docs(app-bundle): make the packaged-app smoke two-part (RIG-3201)

[rigel-mintaka]

Impl task T-5 part (a) of the frozen embedded-revival design
(docs/designs/ui/compass-native-embedded-revival/design.md, T-5 at :640-659). Linear RIG-3201.

Part (b) of that task, the embedded-launch e2e leg, is not in this PR. It hit a real blocker and
is parked for a ruling — see Open Questions.

Why

app-bundle/SMOKE.md was the client-only runbook, and it asserted the bundle "spawns, supervises,
and tears down no stack". T-4 falsified that: the bundle now stages compass-stack,
compass-server and compass-runner beside the shell (app-bundle/build.sh:88-97). So the mode
that the revival exists to ship had no acceptance procedure, and the file actively denied the
behavior.

What this does

Part (a), embedded, is new. It follows the record's sequence: unpack, launch with no app.toml,
the app runs preflight and brings the stack up itself, one agent session runs, then quit-and-stop.

Part (b), client, is the existing procedure kept — same steps, same citations, same loopback-TLS
rationale and OQ-3 cross-machine gap, same keychain/bearer detail. It is renested under a part-(b)
heading and its checklist items are preserved.

The facts are read off the code, not restated

Each claim part (a) makes is cited to the production line that makes it true, so a drift shows up as
a wrong runbook rather than a silently stale one:

• the launch order is preflight, compass-stack up, WhoAmI (go/cmd/compass-app/embedded.go:111-114);
• the documented argv is exactly what stackUpArgs builds, including the four flags it deliberately
  omits (embedded.go:134-150);
• an absent app.toml is what selects embedded mode (go/internal/appconfig/appconfig.go:170-208);
• compass-stack resolves as a sibling of the running shell before PATH (embedded.go:297-323,
  :325-355), so the runbook does not ask the human to install it on PATH;
• the fatal host checks are Linux/macOS, rootless podman, and the podman 4.3 floor
  (go/internal/preflight/preflight.go:96-101, :156-174).

Two details worth calling out, because getting either wrong would make the runbook lie:

• The image check is advisory, not fatal. compass-stack up is what pulls the agent image, so on
  a fresh state dir the image check necessarily fails before up has run; gating on it would break
  the zero-config cold start (embedded.go:407-423).
• Quit-and-stop quits anyway if teardown fails (OQ-6, lifecycle.go:57-60). So podman ps -a
  alone is not a verdict for that step: a lingering stack is a real failure that still exits cleanly,
  and the runbook says to read the app log too.

What it deliberately does not claim

The doc does not say CI covers an embedded-launch e2e leg. It does not, and this file renders
publicly, so claiming it would be a false statement in a public doc.

Verification

• rumdl check app-bundle/SMOKE.md → Success: No issues found in 1 file.
• Every path:line citation in the file was resolved against the tree: all 21 in-range, and the
  load-bearing ones (stackUpArgs, the absent-file default, the sidecar staging loop, the quit
  controller, the podman floor) were read and confirmed to say what the doc claims. The 4.3 floor
  matches the production copy string asserted in preflight_test.go:190-203.
• One file changed.

Open Questions

The e2e leg cannot be built where the record puts it. The record says to add it to the dogfood
e2e job; that job cannot reach embedded mode:

• go/cmd/compass-app/embedded.go is package main under //go:build (linux && gtk4) || darwin, so
  the pipeline is neither importable from package e2e nor built without the gtk4 tag;
• the e2e job runs go test -tags podman and never sets gtk4;
• the gtk4-e2e job has the tag but no podman at all — and embedded's first fatal check is a
  rootless-podman probe.

No existing job has both halves. This is the same constraint go/e2e/client_mode_test.go already
documents for client mode.

Four options (extract the pipeline into an importable package; give the gtk4 lane podman; drive the
seams without importing, per the client_mode_test.go precedent; or descope the leg) are written up
with tradeoffs on RIG-3201. My recommendation is the extraction, since it is the only one that
asserts the real launch path — but it moves code the design just froze, so it is a ruling, not my
call. Part (a) stands on its own regardless.

Also noted there: the record's line cites for that job have drifted (ci.yml:1614 → :1945).
Positional only; the job's shape is as described.

Refs RIG-1662, RIG-3139.

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[linear-code]

RIG-1662

RIG-3201

RIG-3139

[github-actions]

Compass engineering docs preview: https://compass-native-rig-3201-smok.compass-eng-docs.pages.dev

Deployed from compass-native/rig-3201-smoke-two-part at 1789007.

Changed pages:

• app-bundle/SMOKE.md