docs: complete launcher guide and acceptance coverage

Author: TrentBrown

README.md

@@ -62,13 +62,20 @@ The desktop **Stacks** tab can create or edit the same checked-in definition thr
 structured fields. Saving applies the definition but never prepares ports or launches
 project services automatically.
 
+Add a checked-in `portreeve.launcher.json` beside the stack definition when PortReeve
+should inject the stack's current endpoint values into project-owned Start, Stop,
+Restart, and Status commands. Desktop and CLI share the same exact-revision trust and
+lifecycle engine. Begin with command-only integration, then adopt verified activation
+when the project launcher is ready to prove ownership and cleanup.
+
 ## Documentation
 
 - [Installation and releases](docs/installation.md)
 - [JavaScript client](docs/client.md)
 - [Socket protocol](docs/protocol.md)
 - [CLI automation contract](docs/cli-contract.md)
 - [Stack definitions](docs/stacks.md)
+- [Project launchers](docs/launchers.md)
 - [Desktop application](docs/desktop.md)
 - [Mixed process and Docker example](examples/mixed-stack/README.md)
 - [Migration from project-local remapping](docs/migration.md)

docs/cli-contract.md

@@ -61,6 +61,10 @@ output.
 | `stacks prune`                                     | `{ "version": 1, "result": { "candidates": [ ... ], "blocked": [ ... ] } }` |
 | `stacks resolve`                                   | `{ "version": 1, "resolution": { ... } }`                                   |
 | `stacks snapshot`                                  | `{ "version": 1, "result": { "filename": "...", "snapshot": { ... } } }`    |
+| `launcher init`                                    | `{ "version": 1, "result": { "created": true, "trusted": true, ... } }`     |
+| `launcher validate`                                | `{ "version": 1, "launcher": { "valid": true, ... } }`                        |
+| `launcher trust`                                   | `{ "version": 1, "result": { "trusted": true, ... } }`                        |
+| `launcher start` / `stop` / `restart` / `status`   | `{ "version": 1, "result": { ... } }`                                            |
 | `config get`                                       | `{ "version": 1, "settings": { ... } }` or `{ "version": 1, "value": ... }` |
 | `config set`                                       | `{ "version": 1, "settings": { ... } }`                                     |
 | `history`                                          | `{ "version": 1, "events": [ ... ] }`                                       |
@@ -129,6 +133,30 @@ with mode `0600`. The gateway is supplied by the trusted launcher—for example,
 on Linux. PortReeve does not infer or verify sandbox topology. Mount the resulting
 document read-only and never mount the PortReeve control socket into the sandbox.
 
+## Project launchers
+
+`launcher init`, `validate`, `trust`, `start`, `stop`, `restart`, and `status` share
+the same definition, exact-revision trust, environment resolution, lifecycle policy,
+and structured results used by Desktop. They discover the nearest enclosing applied
+stack by default; `--stack-root <path>` selects an explicit canonical root.
+
+`init` is interactive: it refuses an existing file, previews manifest-derived
+suggestions and the exact JSON, creates `portreeve.launcher.json` exclusively, and
+trusts only after confirmation. `validate` may inspect an unapplied definition and does
+not change trust. `trust` is always interactive and reviews the resolved shell, working
+directory, commands, and exact revision. There is no noninteractive trust bypass.
+
+Lifecycle execution refuses invalid, unapplied, or untrusted launchers. `start
+--run-start-anyway` is the explicit repair path for partial nonconflicting evidence.
+`stop --allow-degraded` is the explicit daemon-outage path and uses only an exact-root,
+exact-launcher-revision cached nonsecret environment. Start and Restart never proceed
+without the daemon. Status output remains advisory beside fresh or clearly local stale
+evidence. Attached Start blocks in the invoking CLI process and forwards cancellation
+only to the exact process group that invocation created.
+
+See [Project launchers](launchers.md) for the checked-in schema and complete behavioral
+contract.
+
 ## Prune consent
 
 `claims prune --dry-run` reports eligible missing-workspace claims without mutation.

docs/desktop.md

@@ -92,13 +92,45 @@ Valid output uses two-space indentation, a final newline, editor order, and omit
 defaults such as TCP transport, required or published `true`, automatic allocation, and
 the dependency endpoint when it is `default`.
 
-PortReeve Desktop never starts or stops a project process or container, invokes Docker
+The Stacks tab never starts or stops a project process or container, invokes Docker
 Compose, owns application startup order, maps project environment variables, or asserts
-application health. Those remain responsibilities of the project launcher. Stale stack
+application health. Those remain responsibilities of a project launcher. Stale stack
 evidence remains visible for diagnosis but withholds stack mutation controls until
 current evidence returns; the server revalidates every requested action as final
 authority.
 
+## Launcher
+
+Launcher is the fourth primary tab, after Stacks. It is the low-friction bridge from an
+applied stack's current PortReeve allocation to project-owned lifecycle commands. The
+stack-linked browser shows configuration, exact-revision trust, integration maturity,
+fresh evidence, action availability, bounded current-session output, and the latest
+twenty safe operation records.
+
+An applied stack without `portreeve.launcher.json` offers setup. The dedicated editor
+provides Execution, Commands, Endpoint environment, Advanced, and Review sections. It
+may prefill editable suggestions from supported manifests in the exact selected working
+directory and always displays basename provenance. Discovery never runs project code or
+recursively searches child repositories. The exact canonical JSON is visible before
+**Save and Trust**.
+
+The renderer holds only opaque stack, document, and session identifiers. Electron main
+owns command discovery, exact-byte file replacement, trust, execution, output saving,
+and attached-process termination. External changes offer Review, explicit Overwrite, or
+Cancel; changing verified activation to command-only requires a separate downgrade
+warning. Opening Launcher never executes a command.
+
+Start, Stop, Restart, and Status availability follows the shared engine's current trust
+and evidence policy. Partial Start and degraded Stop require explicit confirmation;
+conflicts block Start. Attached Start has no timeout and blocks normal application exit
+until the stack is stopped, the exact app-owned process group is explicitly terminated,
+or exit is cancelled. Output is retained only in the current application session unless
+the user explicitly selects **Save output**.
+
+See [Project launchers](launchers.md) for the file schema, environment contract,
+command-only and verified semantics, CLI workflow, degraded recovery, concurrency,
+retention, and platform boundaries.
+
 ## Trust and data boundary
 
 Electron runs a sandboxed renderer with context isolation, Node integration disabled,

docs/issues/tb-portreeve-launcher/issues.md

@@ -98,7 +98,7 @@ and existing lifecycle failure details.
 
 ## I-8 - Deliver the Desktop Launcher tab
 
-- **Status:** in-review
+- **Status:** closed
 - **Estimate:** 3d
 - **Plan steps:** P8
 - **Rubric criteria:** R1, R2, R3, R4, R5, R7, R8
@@ -111,7 +111,7 @@ flow, degraded states, Stacks cross-links, and packaged accessibility coverage.
 
 ## I-9 - Document and verify the assembled feature
 
-- **Status:** open
+- **Status:** in-progress
 - **Estimate:** 2d
 - **Plan steps:** P9
 - **Rubric criteria:** R1, R2, R3, R4, R5, R6, R7, R8

docs/issues/tb-portreeve-launcher/tracker.md

@@ -128,7 +128,7 @@ Append PR boundary entries here.
 ### PR #32 - Desktop Launcher tab
 
 - **PR:** [#32](https://github.com/TrentBrown/portreeve/pull/32)
-- **Status:** in review
+- **Status:** merged 2026-08-08
 - **Scope:** P8 / I-8: fourth primary Launcher tab, stack-linked master-detail browser,
   guided editor and provenance, exact JSON review, Save and Trust, evidence and maturity
   presentation, lifecycle controls, confirmations, progress, cancellation, bounded