@coopcli/specsketch 5.3.0 → 5.5.0

package/README.md

@@ -32,18 +32,33 @@ contains artifacts — scaffolded by `openspec new change` or hand-written — t
 baseline: generation makes the **smallest revision** that fulfills the drawing, leaving
 unimplicated files byte-identical.
 
-### File references: `@<path | filename>`
+## Use cases
+
+- **Spec-first feature kickoff.** Sketch the shape of a change, generate the OpenSpec
+  proposal/design/tasks/capability specs, review, and hand the change directory to an
+  implementing agent. `npx openspec validate` works on the output.
+- **Revising an existing change.** Point specsketch at a change directory that already has
+  artifacts; update the drawing and regenerate — only what the diagram implicates changes.
+- **Design review, captured.** Chat about the generated spec (answers are grounded in the
+  artifacts on disk), then **Regenerate** — your corrections in the conversation become
+  requirements for the next pass, so review decisions land in the spec instead of a
+  meeting doc.
+- **Whiteboarding with the team.** `--share` hosts the canvas live; teammates draw with you
+  from a plain browser link, no account or install, and everything lands in the change
+  directory on your machine.
+- **Grounded in real code.** `@` references pull actual files into the model's context, so
+  the spec describes your system rather than a guess at it.
+
+## File references: `@<path | filename>`
 
 Anywhere you type — the architecture title, text on the canvas (labels and loose notes),
-or the review chat — an `@` reference pulls a real file into the model's context, so the
-generated OpenSpec is grounded in your actual code instead of guesses:
+or the review chat — an `@` reference pulls a real file into the model's context:
 
 - `@server/app.ts` — a path relative to the directory you launched `specsketch` from.
 - `@schema.ts` — a bare filename; the tree is searched (skipping `.git`, `node_modules`,
   `dist`) and the shallowest match wins. Multiple matches are noted in the context.
 - `@src/ui` or `@src/ui/` — a **directory**; its files (recursively, up to 50 files and
-  the size budgets) are all pulled into context, each reported individually. Oversized
-  directories include what fits and note what was omitted.
+  the size budgets) are all pulled into context, each reported individually.
 
 Typing `@` in the chat composer or the system prompt editor opens an **inline search**
 over that same scope — files and directories, filtered as you type; arrows + Enter/Tab
@@ -57,27 +72,25 @@ unresolvable reference never fails generation or chat — it degrades to a "coul
 resolved" note in the context, and the chat pane lists which files resolved and which
 didn't under each answer.
 
-### The spec review pane: Spec / System Prompt / Chat
+## The spec review pane: Spec / System Prompt / Chat
 
 The right-hand panel has a menu with three options:
 
-- **Spec** — the generated artifacts (summary, proposal, design, tasks, capability specs),
-  exactly what the panel showed before.
+- **Spec** — the generated artifacts (summary, proposal, design, tasks, capability specs).
 - **System Prompt** — view *and edit* the prompt that drives generation. Saved edits apply
   to every subsequent generation and persist with the change directory (`specsketch.json`);
   **Reset** restores the built-in default. `@` references inside the prompt resolve like
   any other input, so you can pin conventions with `@docs/style.md`.
-- **Chat** — available once a spec exists. Ask questions about the generated OpenSpec
-  (answers are grounded in the artifacts on disk), pull files in with `@` references, and
-  iterate:
+- **Chat** — available once a spec exists. Ask questions about the generated OpenSpec,
+  pull files in with `@` references, and iterate:
   - **Regenerate** (header, next to Generate Spec) re-runs generation with the conversation
-    as extra context — your corrections in chat become requirements for the next pass.
+    as extra context.
   - **Clear** (in the pane) discards the conversation and starts over.
   - Every generation resets the chat and seeds it with an AI-written summary of the prior
-    conversation and what changed on disk in that generation — context stays bounded, the
-    thread of decisions survives. The chat persists in `specsketch.json` across restarts.
+    conversation and what changed on disk — context stays bounded, the thread of decisions
+    survives. The chat persists in `specsketch.json` across restarts.
 
-### Requirements & auth
+## Requirements & auth
 
 - **Node ≥ 22** (the CLI checks at startup).
 - **Anthropic credentials** — only needed for Generate Spec; drawing works without them, and
@@ -89,10 +102,11 @@ The right-hand panel has a menu with three options:
   brew install anthropics/tap/ant && ant auth login
   ```
 
-### CLI reference
+## CLI reference
 
 ```
 specsketch <path-to-openspec-change-dir> [--port <n>] [--share]
+specsketch login [--profile <name>] [--web-url <url>]
 ```
 
 - The directory is created if it doesn't exist; its basename becomes the change name.
@@ -106,7 +120,7 @@ specsketch <path-to-openspec-change-dir> [--port <n>] [--share]
   server-side refusal fallbacks to Opus and requires your org to allow 30-day data
   retention.
 
-### Shared sessions (`--share`)
+## Shared sessions (`--share`)
 
 ```bash
 specsketch login                                                 # once per machine
@@ -119,164 +133,36 @@ browser — **no account, no install** — see the live canvas, and can draw on
 edits stream back and land in `diagram.excalidraw` like your own. The top bar shows a
 live pill with the participant count and a copy-link button.
 
-How it hangs together:
+Worth knowing:
 
 - The host needs a CoopCLI account (`specsketch login` — opens a browser, saves
-  credentials to `~/.coopcli/config.json`, the same file `coop login` writes); guests never do. The link
-  itself is the capability: anyone holding it can view **and edit** until the session
-  ends. The server stores only a hash of the link token.
+  credentials to `~/.coopcli/config.json`, the same file `coop login` writes); guests
+  never do. The link itself is the capability: anyone holding it can view **and edit**
+  until the session ends. The server stores only a hash of the link token.
 - The local server still binds to 127.0.0.1 only — sharing runs over a single outbound
-  connection from the CLI to `api.coopcli.com` (a per-session Durable Object). Your
-  CoopCLI API key never reaches any browser.
-- Concurrent edits resolve per element, last-write-wins — the same scheme Excalidraw's
-  own collab server uses. The change directory on the host remains the durable copy.
+  connection from the CLI. Your CoopCLI API key never reaches any browser.
+- Concurrent edits resolve per element, last-write-wins. The change directory on the
+  host remains the durable copy.
 - Connections heal themselves (heartbeat + reconnect with backoff); a brief
-  "reconnecting…" pill is normal during deploys.
+  "reconnecting…" pill is normal.
 - **Ctrl-C ends the session and invalidates the link.** Idle sessions expire server-side
   after 24 h.
 
-### Troubleshooting
+## Troubleshooting
 
 | Symptom | Fix |
 |---|---|
-| `sh: specsketch: command not found` from `npx` **inside this repo** | This repo *is* `@coopcli/specsketch`, so npx resolves to the local checkout (which has no bin link) instead of the registry. Use `npm run cli -- ./openspec/changes/<name>`, or run npx from any other directory |
 | `npm error 404 @coopcli/specsketch not found` right after a release | Registry propagation lag — retry in a minute or two |
 | Startup warning "No Anthropic credentials detected" | Set `ANTHROPIC_API_KEY` or run `ant auth login`, then restart |
 | Generate fails with a 401 / "anthropic-auth" | Same as above — the server found no credentials, or the login profile expired (`ant auth status`) |
 | "Node NN detected — specsketch needs Node >= 22" | Upgrade Node (https://nodejs.org) |
 | Port already in use | Handled automatically — the server moves to the next free port and prints it; `--port <n>` sets the preferred starting port |
 | Regeneration changed a file you hand-edited | Expected when the drawing implicates it — the diagram is the source of truth; use `git diff`/`git checkout` to recover, and keep change dirs in version control |
-
-More: [getting started page](https://coopcli.com/products/specsketch) ·
-[TESTING.md](TESTING.md) for the QA checklist.
-
----
-
-# The SpecSketch project
-
-Diagram a system with your team in real time, talk it through, and turn the result into an
-**OpenSpec** change proposal. Boxes and arrows + conversation in → a reviewable, spec-shaped
-proposal out.
-
-This repo is **spec-first**: `openspec/` is the source of truth for what SpecSketch does. The
-code in `src/` is the Phase 1 reference implementation of those specs.
-
-## Product shape (phased)
-
-- **Phase 1 — diagram → spec (built).** A single browser session: draw an architecture on an
-  Excalidraw canvas, press **Generate Spec**, and an agentic workflow (Flue) returns an OpenSpec
-  change proposal (proposal / design / tasks / capability specs).
-- **Phase 2 — real-time collaboration.** Multiple engineers on one server-authoritative canvas
-  (Durable Object over WebSocket), with presence and shareable session links.
-- **Phase 3 — voice & specs-from-conversation.** Live audio/video over Cloudflare Realtime
-  (WebRTC), transcription, and feeding the transcript into spec generation.
-
-## Architecture (Phase 1)
-
-```
-Browser (Workers Assets)                Cloudflare Worker
-┌───────────────────────────┐           ┌──────────────────────────────┐
-│  React + @excalidraw       │  POST     │  src/app.ts (Hono @ /api)    │
-│  architecture canvas       │ ───────►  │   /api/workflows/spec-builder│
-│  [Generate Spec]           │  graph    │        │                     │
-│                            │  (JSON)   │        ▼                     │
-│  ◄── OpenSpec artifacts ────┼──────────┤   Flue workflow (Durable     │
-└───────────────────────────┘  bundle   │   Object) → Anthropic Claude │
-                                         │        │ structured output    │
-                                         │        ▼  (SpecBundle)        │
-                                         └──────────────────────────────┘
-```
-
-The client distills the raw Excalidraw scene into a compact `{nodes, edges, notes}` graph
-(`src/ui/scene.ts`); the `spec-builder` workflow (`src/workflows/spec-builder.ts`) turns it into
-a validated `SpecBundle` (`src/lib/schema.ts`), rendered as browsable artifacts.
-
-## Stack
-
-- **Cloudflare Workers + Workers Assets** — one Worker serves the SPA and the API.
-- **Flue** (`@flue/runtime`, `@flue/cli`) — AI agent orchestration; each workflow is a Durable
-  Object. Provider: Anthropic (Claude); the Workers `AI` binding is also available.
-- **Excalidraw** (`@excalidraw/excalidraw`) — the drawing surface.
-- **valibot** — shared request/response schemas (UI + workflow).
-- **Cloudflare Realtime** (Phase 3) — WebRTC SFU for audio/video.
-
-## Getting started (local MVP)
-
-Contributor flow for this repo (the published CLI above is built from the same code —
-`npm run cli -- <change-dir>` builds and runs it from source; don't use
-`npx @coopcli/specsketch` inside this repo, since npx resolves the name to the local
-checkout instead of the registry).
-
-```bash
-npm install
-npm run dev        # web (Vite, http://localhost:5173) + api (Hono/Node, :8787)
-```
-
-Open <http://localhost:5173> — a unique canvas URL is minted automatically. Draw labeled boxes
-and arrows, click **Generate Spec**, then use the top-bar **Canvas | Spec** toggle to read the
-generated OpenSpec proposal.
-
-**Auth:** the backend calls Anthropic via `new Anthropic()` with no key configured — the SDK
-resolves the local authed session (`ANTHROPIC_API_KEY` → `ANTHROPIC_AUTH_TOKEN` → the active
-`ant auth login` / Claude Code profile). As a dev convenience the local server also reads
-`ANTHROPIC_API_KEY` from `.dev.vars` (the same file the Cloudflare dev flow uses) when the
-environment has no credentials. If a generate call 401s, run `ant auth status`; never paste a
-key into the code.
-
-Other scripts:
-
-```bash
-npm run check      # tsc --noEmit
-npm test           # vitest — unit + integration tests, no credentials needed
-npm run server     # api only (tsx watch server/index.ts)
-npm run web        # web only (vite)
-npm run smoke      # live end-to-end check against a running server (needs auth)
-```
-
-See [TESTING.md](TESTING.md) for the manual QA checklist mapped to the OpenSpec scenarios.
-
-### Cloudflare/Flue production path
-
-The Cloudflare deployment (single Worker + Flue Durable Objects) is kept intact under the
-`*:cf` scripts and is not used by the local MVP:
-
-```bash
-cp .dev.vars.example .dev.vars   # add your ANTHROPIC_API_KEY
-npm run dev:cf     # build the UI, then flue dev --target cloudflare (http://localhost:3583)
-npm run build:cf   # vite build → flue build --target cloudflare → patch asset binding
-npx wrangler secret put ANTHROPIC_API_KEY
-npm run deploy:cf  # build, then wrangler deploy the generated config
-```
-
-## OpenSpec roadmap
-
-All outcomes are defined as validated OpenSpec change proposals under `openspec/changes/`.
-Each change is a thin, independently implementable/testable slice; its spec scenarios are the QA
-acceptance criteria. Run `npx openspec list` / `npx openspec validate --all`.
-
-| Phase | Change | Capability(ies) | Status |
-|-------|--------|-----------------|--------|
-| 1 | `phase-1-diagram-to-spec` | architecture-canvas, diagram-interpretation, spec-generation, openspec-artifacts, worker-platform | scaffold built |
-| 2 | `canvas-room-durable-object` | canvas-room | proposed |
-| 2 | `realtime-canvas-sync` | realtime-canvas-sync | proposed |
-| 2 | `collaboration-presence` | collaboration-presence | proposed |
-| 2 | `shareable-session-links` | shareable-session-links | proposed |
-| 3 | `realtime-voice-signaling` | realtime-voice-session | proposed |
-| 3 | `voice-audio` | voice-audio | proposed |
-| 3 | `participant-video` | participant-video | proposed |
-| 3 | `conversation-transcription` | conversation-transcription | proposed |
-| 3 | `transcript-informed-specs` | transcript-informed-specs | proposed |
-| — | `spec-persistence-and-export` | spec-persistence-and-export | proposed |
-| — | `coopcli-specsketch-distribution` | npm-distribution, local-persistence, product-microsite | shipped (v0.1.0 on npm; microsite live) |
-
-Suggested implementation order follows the table (each Phase 2/3 change builds on the one above
-it). The `spec-builder` workflow already dogfoods this format — its output is exactly these
-artifacts.
-
-## Notes
-
-- **Model**: pinned to a verified Flue specifier in one constant in `src/workflows/spec-builder.ts`;
-  bump it there as newer Claude specifiers are confirmed in Flue's provider mapping.
-- **Flue beta asset binding**: `flue build` (beta) regenerates the Cloudflare config and currently
-  drops the user `assets` block, so `scripts/patch-assets.mjs` re-injects it after the build. Once
-  Flue propagates user asset config, delete that script and its `build` step.
+| `--share` says it needs login | Run `specsketch login` once on the hosting machine; `--profile` selects a non-default CoopCLI config profile |
+| Share link says it no longer works | The host ended the session (Ctrl-C) or it idled out — ask for a fresh link |
+
+More: [product page](https://coopcli.com/products/specsketch) ·
+[docs](https://coopcli.com/products/specsketch/docs/). Sibling product:
+[specplan](https://coopcli.com/products/specplan/) — plan the roadmap those changes live
+on. Source, contributor setup, and the QA checklist live in the
+[coopcli repo](https://github.com/jtaylorcpp/coopcli) (`packages/specsketch`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@coopcli/specsketch",
-	"version": "5.3.0",
+	"version": "5.5.0",
 	"description": "coopcli specsketch \u2014 draw an architecture diagram, generate an OpenSpec change proposal into your openspec/ change directory. Local-only.",
 	"type": "module",
 	"bin": {