@coopcli/specsketch 0.1.3 → 5.3.0

package/README.md

@@ -32,6 +32,51 @@ 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>`
+
+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:
+
+- `@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.
+
+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
+(or a click) select, Escape dismisses. Selecting a directory inserts `@dir/` and keeps
+the search open scoped to it: stop there to reference the whole directory, or keep
+typing to drill down to a file.
+
+References are scoped to the launch directory: absolute paths, `..`, and symlinks that
+escape it are refused. Large files truncate at 64KB (256KB across all references). An
+unresolvable reference never fails generation or chat — it degrades to a "could not be
+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 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.
+- **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:
+  - **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.
+  - **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.
+
 ### Requirements & auth
 
 - **Node ≥ 22** (the CLI checks at startup).
@@ -47,7 +92,7 @@ unimplicated files byte-identical.
 ### CLI reference
 
 ```
-specsketch <path-to-openspec-change-dir> [--port <n>]
+specsketch <path-to-openspec-change-dir> [--port <n>] [--share]
 ```
 
 - The directory is created if it doesn't exist; its basename becomes the change name.
@@ -55,15 +100,46 @@ specsketch <path-to-openspec-change-dir> [--port <n>]
   specsketch session is running — the server moves to the next available port and the
   printed URL reflects the one actually bound. Binds to 127.0.0.1 exclusively — there is
   no `--host`.
+- `--share` hosts the canvas as a live multiplayer session (see below).
 - **Model picker** (top bar): `claude-opus-4-8` (default), `claude-sonnet-5`, or
   `claude-fable-5`. The choice is saved with the change directory. Fable runs with
   server-side refusal fallbacks to Opus and requires your org to allow 30-day data
   retention.
 
+### Shared sessions (`--share`)
+
+```bash
+specsketch login                                                 # once per machine
+specsketch ./openspec/changes/new-feature-change --share
+```
+
+`--share` creates a multiplayer session on your CoopCLI account and prints a link like
+`https://coopcli.com/products/specsketch/s/<id>?k=<token>`. Coworkers open it in a plain
+browser — **no account, no install** — see the live canvas, and can draw on it; their
+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:
+
+- 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.
+- 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.
+- Connections heal themselves (heartbeat + reconnect with backoff); a brief
+  "reconnecting…" pill is normal during deploys.
+- **Ctrl-C ends the session and invalidates the link.** Idle sessions expire server-side
+  after 24 h.
+
 ### 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`) |
@@ -127,7 +203,9 @@ a validated `SpecBundle` (`src/lib/schema.ts`), rendered as browsable artifacts.
 ## Getting started (local MVP)
 
 Contributor flow for this repo (the published CLI above is built from the same code —
-`npm run build:cli` then `node dist/cli/index.js <change-dir>` to run it from source).
+`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