[codex] Add desktop first-run quickstart docs

README.md

@@ -231,6 +231,23 @@ See [`docs/mcp-client-compatibility.md`](docs/mcp-client-compatibility.md) for t
 
 ## How to use it
 
+### Desktop first run
+
+Open the signed macOS app, then register an existing local folder. Setlist asks
+what kind of project or workspace it is, previews shallow local metadata from
+that folder, and keeps non-code workspaces first-class. The preview is local on
+your Mac; it does not upload contents, call an LLM, or index deeply.
+
+From Settings, you can preview installing or removing the managed Setlist MCP
+entry for Claude Desktop or Codex. Setlist shows the config change first,
+preserves unmanaged MCP entries, refuses unmanaged `setlist` conflicts, and
+backs up existing config files before writing. Restore is manual from that
+backup; Setlist does not restart clients or verify the MCP server inside them.
+
+After registration, ask an agent for the Setlist project brief with the MCP
+`get_project_brief` tool, or use `setlist brief <workspace> --json` from the
+CLI.
+
 **Download the desktop app** from [Releases](https://github.com/spaceshipmike/setlist/releases) — `.dmg` for macOS Apple Silicon. Signed, notarized, with in-app auto-update over a stable channel.
 
 **As an MCP server**, point Claude Desktop or Codex at `@setlist/mcp`. The CLI can check supported clients and preview the managed Setlist entry before writing:

docs/public-readiness-plan.md

@@ -21,6 +21,8 @@ Setlist is moving from a personal registry toward a local, agent-readable worksp
 - Done: richer source adapter paths are now being developed in parallel for code and non-code workspaces, adding bounded manifest/dependency/runtime signals and document-category/folder-role signals without persisting inspection-derived fields.
 - Done: Electron first-run onboarding now guides a user through registering one existing local folder and previewing shallow local inspection signals before registration.
 - Done: existing-folder onboarding now lets users choose from live, user-managed project types while keeping broad code/workspace defaults as fallback.
+- Done: packaged-app quickstart docs now describe the desktop first-run path: open the signed app, register an existing folder, choose project/workspace type, preview shallow local metadata, optionally manage the Setlist MCP entry safely for Claude Desktop or Codex, then ask an agent or CLI for the project brief.
+- Done: native folder-picker affordance is no longer a public-readiness TODO for this slice; any future changes should come from observed onboarding friction, not assumed launch-blocking polish.
 
 ## Slice Proof: Alpha MCP Client Controls Tester Packet
 
@@ -45,6 +47,13 @@ What remains:
 - Keep launch surfaces pointed at the README proof and compatibility matrix until broader validation exists.
 - Treat social/direct outreach as a request for feedback on the pattern, not as a maturity announcement.
 
+## Slice Proof: Desktop First-Run Quickstart Docs
+
+- `README.md` now has a short "Desktop first run" subsection under "How to use it" that walks a public user from opening the signed macOS app through registration, shallow local preview, safe optional MCP client config changes, and the agent/CLI project brief.
+- `packages/app/README.md` now documents the same first-run user flow before developer and release material, so app-specific readers see the user journey before build instructions.
+- The docs keep the current scope honest: local-first, no upload, no LLM call during preview, shallow inspection, Claude Desktop and Codex only for MCP client config today, guarded install/remove, backups with manual restore, no client restart, and no in-client MCP validation.
+- The copy keeps non-code workspaces first-class and does not claim broad compatibility, production/team readiness, or real alpha feedback.
+
 ## Slice Proof: Alpha MCP Client Controls Checklist
 
 - `docs/alpha-mcp-client-controls-checklist.md` gives operators a short alpha validation path for Settings > MCP clients without changing core install/remove policy and links to the tester packet for real alpha handoff.
@@ -68,7 +77,6 @@ What remains:
 
 What remains:
 
-- Add richer folder-picker affordances later if manual path entry proves awkward in the packaged app.
 - Watch real onboarding sessions for confusing project-type labels or missing default types before adding more UI.
 
 ## Slice Proof: Workspace Source Inspection

packages/app/README.md

@@ -4,6 +4,24 @@ Desktop control panel for the Setlist project registry. Electron shell,
 React + Tailwind + Radix renderer, `@setlist/core` library in the main
 process via IPC bridge.
 
+## First-run user flow
+
+The signed macOS app starts with a local-first setup path:
+
+1. Open Setlist and register an existing folder.
+2. Choose the project or workspace type. Code projects get richer signals, but
+   non-code workspaces remain first-class.
+3. Review the shallow local metadata preview. Setlist reads cheap folder,
+   document, manifest, and git signals on the Mac; it does not upload contents,
+   call an LLM, or deeply index the folder.
+4. Optionally open Settings > MCP clients to preview installing or removing the
+   managed Setlist MCP entry for Claude Desktop or Codex. Writes are guarded:
+   unmanaged entries are preserved, unmanaged `setlist` conflicts are refused,
+   and existing configs are backed up before changes. Backup restore is manual,
+   and Setlist does not restart clients or validate the MCP server inside them.
+5. Ask an agent for the project brief with `get_project_brief`, or run
+   `setlist brief <workspace> --json` from the CLI.
+
 ## Develop
 
 ```bash