From 036f03208596bebfc259049b6cc3b28e348ae4bd Mon Sep 17 00:00:00 2001 From: Michael Lebowitz Date: Sat, 9 May 2026 17:01:25 -0400 Subject: [PATCH] Add desktop first-run quickstart docs --- README.md | 17 +++++++++++++++++ docs/public-readiness-plan.md | 10 +++++++++- packages/app/README.md | 18 ++++++++++++++++++ 3 files changed, 44 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4e2bfbc..dbf6aa1 100644 --- a/README.md +++ b/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 --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: diff --git a/docs/public-readiness-plan.md b/docs/public-readiness-plan.md index 5da41d2..f853015 100644 --- a/docs/public-readiness-plan.md +++ b/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 diff --git a/packages/app/README.md b/packages/app/README.md index 50fbe44..1c5cc55 100644 --- a/packages/app/README.md +++ b/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 --json` from the CLI. + ## Develop ```bash