@launchsecure/launch-kit 0.0.33 → 0.0.35

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@launchsecure/launch-kit",
-  "version": "0.0.33",
-  "description": "LaunchSecure toolkit — launch-pod (pipeline), launch-chart (project graph MCP), launch-deck (visual playground MCP), launch-kit-beacon (feedback Web Component), launch-recall (file-watcher backup).",
+  "version": "0.0.35",
+  "description": "LaunchSecure toolkit — launch-sequencer (pipeline runner + terminal bridge), launch-radar (feedback webhook receiver), launch-chart (project graph MCP), launch-deck (visual playground MCP), launch-kit-beacon (feedback Web Component), launch-recall (file-watcher backup). launch-pod is the container image these run inside.",
   "license": "MIT",
   "author": "LaunchSecure - AutomateWithUs",
   "homepage": "https://automatewith.us",
@@ -48,13 +48,16 @@
   },
   "bin": {
     "launch-kit": "./dist/server/init-entry.js",
-    "launch-pod": "./dist/server/cli.js",
+    "launch-sequencer": "./dist/server/cli.js",
+    "launch-radar": "./dist/server/launch-radar-entry.js",
     "launch-chart": "./dist/server/graph-mcp-entry.js",
     "launch-deck": "./dist/server/deck-mcp-entry.js",
     "launch-recall": "./dist/server/recall-entry.js",
     "launch-orbit": "./dist/server/orbit-entry.js",
     "launch-course": "./dist/server/course-entry.js",
-    "launch-beacon": "./dist/server/beacon-monitor-entry.js"
+    "launch-beacon": "./dist/server/beacon-monitor-entry.js",
+    "launch-rover": "./dist/server/rover-entry.js",
+    "launch-bot": "./dist/server/launch-bot-entry.js"
   },
   "files": [
     "dist",
@@ -113,7 +116,7 @@
     "build:council-client": "vite build --config vite.council.config.ts",
     "build:client": "vite build",
     "build:chart-client": "vite build --config vite.chart.config.ts",
-    "build:server": "esbuild src/server/cli.ts src/server/fb-wizard.ts src/server/graph-mcp-entry.ts src/server/chart-serve.ts src/server/deck-mcp-entry.ts src/server/deck-serve.ts src/server/council-entry.ts src/server/council-serve.ts src/server/recall-entry.ts src/server/init-entry.ts src/server/orbit-entry.ts src/server/course-entry.ts src/server/beacon-monitor-entry.ts src/server/parse-worker-entry.ts src/server/radar-teardown-entry.ts src/server/radar-docker-init-entry.ts --bundle --platform=node --target=node18 --outdir=dist/server --external:node-pty --external:ws --external:typescript --external:web-tree-sitter --external:tree-sitter-typescript --external:cloudflared --external:pg --external:pg-native --external:pgsql-parser --external:libpg-query && rm -rf dist/server/public && cp -r ../claude-code-web/src/public dist/server/public && rm -rf dist/server/graph/queries && mkdir -p dist/server/graph && cp -r src/server/graph/queries dist/server/graph/queries",
+    "build:server": "esbuild src/server/cli.ts src/server/fb-wizard.ts src/server/graph-mcp-entry.ts src/server/chart-serve.ts src/server/deck-mcp-entry.ts src/server/deck-serve.ts src/server/council-entry.ts src/server/council-serve.ts src/server/recall-entry.ts src/server/init-entry.ts src/server/orbit-entry.ts src/server/course-entry.ts src/server/beacon-monitor-entry.ts src/server/parse-worker-entry.ts src/server/radar-teardown-entry.ts src/server/radar-docker-init-entry.ts src/server/launch-radar-entry.ts src/server/rover-entry.ts src/server/launch-bot-entry.ts --bundle --platform=node --target=node18 --outdir=dist/server --external:node-pty --external:ws --external:typescript --external:web-tree-sitter --external:tree-sitter-typescript --external:cloudflared --external:pg --external:pg-native --external:pgsql-parser --external:libpg-query && rm -rf dist/server/public && cp -r ../claude-code-web/src/public dist/server/public && rm -rf dist/server/graph/queries && mkdir -p dist/server/graph && cp -r src/server/graph/queries dist/server/graph/queries",
     "dev:client": "vite",
     "dev:deck-serve": "cd ../.. && tsx watch packages/cli/src/server/deck-mcp-entry.ts serve",
     "dev:chart": "pnpm build:server && pnpm build:chart-client && node dist/server/graph-mcp-entry.js serve",

package/scaffolds/ls-marketplace/plugins/kit/commands/standup.md

@@ -63,11 +63,11 @@ Skip this step if no handles were found in commit messages — don't pull the fu
 
 ### 6. Release detection
 
-A commit qualifies the post for the `release` tag if ANY of the following are true:
-- `package.json` `version` field changed in `git diff @{push}..HEAD -- package.json`
-- A migration file under `prisma/migrations/` was added or `prisma/schema.prisma` changed
-- A deploy/publish was mentioned in commit subjects (regex: `\b(publish|release|deploy|bump)\b`)
-- A new bin or export was added to a package's `package.json`
+A commit qualifies the post for the `release` tag if ANY of the following are true. These signals are **stack-detected**, not hardcoded — match against whatever the project actually uses, and a signal that doesn't apply to this stack simply doesn't fire:
+- The project's **version** changed — detect from the stack's version source: `package.json` `version` (Node), `pyproject.toml`/`setup.py`/`__version__` (Python), `Cargo.toml` `version` (Rust), `<Version>` in a `*.csproj` (.NET), a gemspec/`version.rb` (Ruby), `version` in `pubspec.yaml` (Dart), or a new `vX.Y.Z` git tag pushed in this window (language-agnostic). Diff the relevant file over `@{push}..HEAD`.
+- A **migration** was added — any file under the project's migrations directory (detected as in `/kit:ship`: `prisma/migrations/`, `supabase/migrations/`, `db/migrate/`, `alembic/versions/`, `drizzle/`, `src/main/resources/db/migration/`, etc.), or the schema/DDL source changed. Skip this signal when the project has no migrations.
+- A deploy/publish was mentioned in commit subjects (regex: `\b(publish|release|deploy|bump)\b`).
+- A new **public entry point** was added — a bin/CLI command, package export, or exported library symbol (e.g. a new `bin`/`exports` entry in `package.json`, a new console-script in `pyproject.toml`, a new exported package in Go, etc.).
 
 If any are true, set `addReleaseTag = true`. Otherwise `false`.
 
@@ -102,7 +102,7 @@ Pending / in-progress:
 
 ----
 
-<one-line PSA or deploy-safety note. Examples: "TS clean, no schema/migration changes, safe to deploy." or "Includes prisma migration <name> — run migrate-with-backup.sh before deploy.">
+<one-line PSA or deploy-safety note, phrased for the project's stack. Examples: "Typecheck clean, no schema/migration changes, safe to deploy." or "Includes a <migration-tool> migration <name> — take a DB backup before deploy." or "Bumps to vX.Y.Z — publishes on merge.">
 
 Thanks
 ```

package/scaffolds/ls-marketplace/plugins/kit/skills/analyse/SKILL.md

@@ -22,6 +22,12 @@ allowed-tools:
 
 Source-code analysis using launch-chart as the default tool. The chart indexes ~1,200 typed nodes across 4 layers (ui / api / db / static) with cross-layer edges and AST-level deep fields — almost everything grep/glob/Read would surface is queryable here, faster and cheaper in tokens.
 
+## Input
+
+Run the analysis for the user query → **$ARGUMENTS**
+
+This is the target to analyse — a question, a node name (file / table / route / hook), or a module. Route it through the chart tools below. If `$ARGUMENTS` is empty, the user invoked the skill bare; ask them what they want analysed (or infer it from the surrounding conversation) before querying.
+
 ## Discipline (non-negotiable)
 
 1. **Chart-first.** Default to launch-chart MCP for any code-structure or behavior query. Do NOT reach for grep / glob / Read first.

package/scaffolds/ls-marketplace/plugins/kit/skills/brief/SKILL.md

@@ -1,50 +1,65 @@
 ---
-description: Create or update a repo-backed Brief in the LaunchSecure Comm Hub per the LS Briefs framework — Discovery-plane document (docCategory=features) authored as a comment that's also synced to a markdown file in the repo. Use to capture an idea before promoting it to an Epic.
+description: Create or update a repo-backed Brief — a long-form document committed as a markdown file under doc/<category>/. The server syncs it to a Comm Hub comment; you don't post it yourself. Use to capture a feature, architecture decision, requirement, or playbook in the repo.
 ---
 
 # /kit:brief
 
-A **Brief** is an LS Discovery-plane artefact: a long-form description of a problem/opportunity, authored as a comment in the project's Comm Hub AND backed by a markdown file in the repo (`docs/requirements/features/<slug>.md` by convention). It's the structured alternative to a free-form Discussion when the idea has enough shape to write down. Briefs get promoted to Epics on the Roadmap once they're DECIDED.
+A **Brief** is a structured long-form document that lives **both** as a markdown file in the repo at `doc/<category>/<slug>.md` **and** as a comment in the LaunchSecure Comm Hub. You write the file; the LS server's file-backed sync materializes the matching Comm Hub comment (favoring server → file convergence). See `doc/features/briefs.md`, `doc/playbook/runbooks/write-a-brief.md`, and `architecture/systems/briefs-discovery.md`.
+
+**You write the file, the server does the sync.** Do NOT call `communication_write` / `communication_update` yourself — the brief becomes a Comm Hub comment automatically via the `discussion` handler once the file lands on the default branch (stamped with the category's `docCategory`, icon, and color). The only allowed Comm Hub touch from this skill is reading a `--from` discussion seed, and that's read-only.
+
+## Categories
+
+A Brief is **category-scoped** — the category determines its folder, icon, color, and where readers find it. Pick the one matching the question the reader is asking:
+
+| Reader is asking… | Category | Folder |
+|---|---|---|
+| "What are we building / what does LS offer?" | `features` | `doc/features/` |
+| "How does this system work / why built this way?" | `architecture` | `doc/architecture/` |
+| "What rule must I follow?" | `requirement` | `doc/requirement/` |
+| "How do I do X?" | `playbook` | `doc/playbook/` |
+| "Something happened, I want to remember" | `incident` | `doc/incident/` |
+| "Half-formed personal thought" | `ideas` | `doc/ideas/` (personal — see below) |
+
+`features`, `architecture`, `requirement`, `playbook`, `shipping-logs` are framework defaults; `ideas` and `incident` are this project's custom categories (`.launch-secure.config`). Other projects may differ — read `.launch-secure.config` `docCategories[]` if unsure. **Do not default to `ideas`** — that's the personal-scratch category, not a dumping ground for real briefs. Shipping-log briefs are written by `/kit:ship`, not this skill.
 
 Parse `$ARGUMENTS`:
 - **subcommand** (required) — `new` | `update` | `list` | `show`.
-- For **new**: `<title>` (required), `--from=discussion:<id>` to seed body from an existing discussion thread, `--module=<slug>` to tag.
-- For **update**: `<brief-id-or-slug>` and either a body description (re-generates body) or `--append=<text>` to add a section.
-- For **list**: `[--module=<slug>] [--status=open|decided|declined]`.
-- For **show**: `<brief-id-or-slug>`.
+- For **new**: `<title>` (required), `--category=<name>` (the category from the table; if omitted, infer from the title/intent and confirm before writing), `--from=discussion:<id>` to seed body from an existing discussion thread, `--dir=<path>` to override the resolved folder.
+- For **update**: `<slug-or-path>` and either a body description (re-generates body) or `--append=<text>` to add a section.
+- For **list**: `[--category=<name>]` to filter to one category, else lists briefs across all category folders. `[--dir=<path>]` to scan a specific dir.
+- For **show**: `<slug-or-path>`.
 
 Examples:
-- `/kit:brief new "Channels for Comm Hub" --module=communication`
-- `/kit:brief new "Roadmap nav" --from=discussion:cmt_abc123`
-- `/kit:brief list --status=open`
-- `/kit:brief show channels-for-comms`
-- `/kit:brief update channels-for-comms --append="Resolved: use the Slack metaphor not Teams."`
+- `/kit:brief new "Comm Hub channels" --category=features`
+- `/kit:brief new "Roadmap nav" --from=discussion:cmt_abc123 --category=architecture`
+- `/kit:brief list`
+- `/kit:brief list --category=requirement`
+- `/kit:brief show launch-watch`
+- `/kit:brief update comm-hub-channels --append="Resolved: use the Slack metaphor not Teams."`
 
-## Preflight
-
-1. Confirm `mcp__launch-secure__ping` works (the cloud LS MCP must be wired). If only `mcp__local-launch-secure__*` is wired, ask the user whether to post to local or cloud — default per project memory is CLOUD.
-2. For `new`, sanity-check that no existing brief with the same slug already exists — call `mcp__launch-secure__communication_read` filtered by `resourceType=comment` and search the title. If a match is found, ask whether to update instead.
+## Location
 
-## The Brief shape
+- **Folder**: `doc/<category>/` at the repo root, where `<category>` is resolved from `--category` (or inferred + confirmed).
+- **Filename**: `<slug>.md`, where the slug is the kebab-cased title (e.g. "launch-watch — unified monitor" → `launch-watch.md`; keep it short — derive from the leading words, drop the subtitle after an em-dash).
+- Override the folder with `--dir=<path>` only if the user asks.
 
-Per the LS Briefs framework (`docs/requirements/work-items/roadmap-and-hierarchy.md`):
+## Preflight
 
-- **resourceType**: `comment` (Briefs are comments)
-- **docCategory**: `features` (this is what file-backed sync watches)
-- **title**: the human-friendly name; the slug is derived
-- **body**: the long-form markdown — sections below
-- **file_links**: not used here; the FileBackedEntity link is created by LS server-side on first save
-- **tags**: optional module tag, plus a `brief` tag for filtering
+1. Resolve the repo root (the working directory is the repo root in this project).
+2. Resolve the category (from `--category`, or infer from the title and confirm with the user). Map it to `doc/<category>/`.
+3. For **new**, check `doc/<category>/<slug>.md` does not already exist. If it does, surface it and ask whether to `update` instead — do NOT overwrite silently. Also check the slug isn't already used under a *different* category before creating a duplicate.
+4. No `communication_write`. This skill writes the filesystem (+ optionally reads a `--from` seed); the server handles the Comm Hub side.
 
-### Body template
+## Body template
 
-When generating a NEW brief, use this skeleton (markdown body):
+When generating a NEW brief, write this skeleton as the file contents (plain markdown):
 
 ```markdown
 # <Title>
 
-**Status**: PROPOSED  
-**Owner**: <user-mention or "unassigned">  
+**Status**: PROPOSED
+**Owner**: <name or "unassigned">
 **Module**: <module slug or "-">
 
 ## Problem
@@ -69,44 +84,52 @@ When generating a NEW brief, use this skeleton (markdown body):
 
 ## References
 
-- <link to existing code via launch-chart node id (use mcp__launch-chart__read_graph to find the right nodes; cite them as `lib/foo/bar.ts:42`)>
-- <related comments by id>
+- <link to existing code, cited as `lib/foo/bar.ts:42` — use launch-chart (read_graph / grep_nodes) to find the right nodes; don't invent file paths>
 ```
 
-The body is plain markdown — Comm Hub renders it. Use launch-chart to add real code references (don't invent file paths).
-
 ## Write paths
 
 ### new
 
-1. Build the body from the template + the user's description (or the `--from=discussion:<id>` seed — fetch via `communication_read` and weave the relevant points into the Problem/Proposed-direction sections).
-2. Call `mcp__launch-secure__communication_write` with:
-   - `title: <user-supplied>`
-   - `body: <generated-markdown>`
-   - `resource_type: "comment"`
-   - `fields: { docCategory: "features", briefStatus: "PROPOSED" }`
-   - `tag_ids: <module tag id + "brief" tag id>` (call `mcp__launch-secure__tags_list` first to resolve names → ids; if either tag doesn't exist, surface the missing tag(s) and proceed without)
-3. Print the returned comment id + URL.
-4. Tell the user: "LS server-side file-backed sync will materialize `docs/requirements/features/<slug>.md` on the next default-branch push that includes this brief — pull the branch to see it locally."
+1. Resolve the category and folder (see Preflight).
+2. Build the body from the template + the user's description (or the `--from=discussion:<id>` seed — fetch via `mcp__launch-secure__communication_read` and weave the relevant points into Problem / Proposed-direction; reading a seed discussion is fine, but the Brief itself is still written as a file, never posted back).
+3. Use launch-chart (`read_graph`, `grep_nodes`) to populate the References section with real code paths — don't invent them.
+4. **Write the file** to `doc/<category>/<slug>.md` with the Write tool.
+5. Print the path written and remind the user it materializes as a Comm Hub comment on the next default-branch push. Do NOT commit or push unless the user explicitly asks — leave it as a working-tree change for them to review and commit.
 
 ### update
 
-1. Resolve `<brief-id-or-slug>` via `communication_read(resourceType: "comment", search: <slug>)`. If multiple match, list them and stop.
-2. If `--append=<text>`, fetch the current body, append the text under a `## Update <ISO-date>` heading, and call `mcp__launch-secure__communication_update` with the new body.
-3. If a fresh description was passed, regenerate the body from the template + new description, ask the user to confirm (show the diff briefly), then update.
+1. Resolve `<slug-or-path>` with `node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" show <slug>` (it prints the resolved path on its `── <path> ──` header, or exits non-zero with candidates / an ambiguity list). If nothing matches, surface the candidates and stop; if ambiguous, ask which category.
+2. If `--append=<text>`, Read the resolved file, append the text under a `## Update <ISO-date>` heading, and Write it back.
+3. If a fresh description was passed, regenerate the body from the template + new description, show the user the diff briefly, then Write it back on confirmation.
 
 ### list
 
-`mcp__launch-secure__communication_read` filtered by `resourceType=comment`, narrow on `docCategory=features` if the API supports it (otherwise pull a wider set and filter client-side by tag/status). Render one line per brief: `id  status  title  module  updated`.
+Run the bundled scanner — do NOT open and parse the brief files yourself:
+
+```
+node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" list [category]
+```
+
+It walks every `doc/<category>/` folder once and prints an aligned `CATEGORY  SLUG  STATUS  TITLE` table (pass a category to filter). Surface its output as-is; only read individual files if the user then asks to `show` one.
 
 ### show
 
-Fetch via `communication_read` and print the body as-is, no transformation.
+Run the bundled scanner — it resolves the slug across all category folders and prints the file with a `── <path> ──` header:
+
+```
+node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" show <slug-or-path>
+```
+
+Exit 1 = no match (it prints near-matches), exit 2 = ambiguous across categories (it lists them — re-run with the full path). Don't hand-glob `doc/` for the file.
 
 ## Constraints
 
-- **Plain markdown body.** Per project memory `feedback_comms_plain_text.md`, comms posts are plain — no HTML, no emojis unless the user wrote them.
-- **One brief, one comment.** Don't fragment a brief across multiple comments — append via `--append` to keep the document continuous.
-- **Cloud LS by default.** Per memory `feedback_post_to_cloud_ls_default.md`. Local LS only when the user explicitly says "local".
+- **You write a file; the server creates the comment.** Do NOT call `communication_write` / `communication_update`. Reading a `--from` discussion seed is the only allowed Comm Hub touch, and it's read-only.
+- **Pick the right category.** The folder, icon, and color all follow from it. Don't default to `ideas`.
+- **Plain markdown.** No HTML, no emojis unless the user wrote them.
+- **One brief, one file.** Don't fragment a brief across multiple files — append via `--append` to keep the document continuous.
+- **Don't commit or push on your own.** Write the file to the working tree and stop; committing/pushing is the user's call (per project conventions on no unauthorized pushes).
+- **`doc/ideas/` is the user's personal scratch.** Write an `ideas` brief there only when the user explicitly asks for one, and do NOT reorganize, reclassify, or migrate other files in that directory. Promotion out of `doc/ideas/` is user-driven only.
 - **Cite real code.** Use launch-chart node ids in the References section — don't invent file paths.
-- **Don't auto-promote to Epic.** A Brief → Epic is a deliberate human action (project memory: bucket transitions are deliberate, not derived). Surface a hint at the end: "When DECIDED, run `/work-items create epic --from-brief=<id>` to promote."
+- **Don't auto-promote to Epic.** A Brief → Epic is a deliberate human action. Surface a hint at the end: "When DECIDED, promote this to an Epic on the Roadmap."

package/scaffolds/ls-marketplace/plugins/kit/skills/brief/briefs.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// briefs.mjs — list/show repo-backed Briefs without the agent reading every file.
+//
+// A Brief is a markdown file at doc/<category>/<slug>.md (see the /kit:brief
+// SKILL.md). This script scans the doc/ tree once and emits structured output so
+// the skill never has to open + parse N files itself.
+//
+// Usage (run from the repo root — process.cwd() must contain doc/):
+//   node briefs.mjs list [category]          # table: CATEGORY  SLUG  STATUS  TITLE
+//   node briefs.mjs show <slug-or-path>      # print one brief's contents
+//
+// Exit codes: 0 ok · 1 not found · 2 ambiguous · 3 usage error.
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, relative, basename, sep } from 'node:path';
+
+const DOC_ROOT = join(process.cwd(), 'doc');
+
+/** Recursively collect every *.md under doc/, tagged with its top-level category. */
+function collectBriefs(filterCategory) {
+  if (!existsSync(DOC_ROOT)) {
+    return { error: `no doc/ directory at ${DOC_ROOT}` };
+  }
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const rel = relative(DOC_ROOT, full); // e.g. features/foo.md, playbook/runbooks/bar.md
+        const category = rel.split(sep)[0];
+        if (filterCategory && category !== filterCategory) continue;
+        out.push({ category, slug: basename(entry.name, '.md'), rel, full });
+      }
+    }
+  };
+  walk(DOC_ROOT);
+  out.sort((a, b) => a.category.localeCompare(b.category) || a.slug.localeCompare(b.slug));
+  return { briefs: out };
+}
+
+/**
+ * Pull a brief's title + status without loading it into the model. Looks in both
+ * YAML frontmatter (`title:` / `status:`, used by the PUBLISHED briefs) and the
+ * markdown body (`# Title` / `**Status**:`, used by template-generated ones).
+ * Frontmatter wins for the title; the `**Status**:` line wins for status.
+ */
+function parseMeta(file) {
+  let fmTitle = '', fmStatus = '', h1 = '', bodyStatus = '';
+  try {
+    const lines = readFileSync(file, 'utf8').split('\n');
+    let inFm = false, fmDone = false;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (i === 0 && line.trim() === '---') { inFm = true; continue; }
+      if (inFm) {
+        if (line.trim() === '---') { inFm = false; fmDone = true; continue; }
+        const t = line.match(/^title:\s*(.+?)\s*$/i);
+        if (t && !fmTitle) fmTitle = t[1].replace(/^["']|["']$/g, '');
+        const s = line.match(/^status:\s*(.+?)\s*$/i);
+        if (s && !fmStatus) fmStatus = s[1].replace(/^["']|["']$/g, '');
+        continue;
+      }
+      if (!h1) {
+        const m = line.match(/^#\s+(.+?)\s*$/);
+        if (m) { h1 = m[1]; continue; }
+      }
+      if (!bodyStatus) {
+        const m = line.match(/^\*\*Status\*\*:\s*(.+?)\s*$/i);
+        if (m) bodyStatus = m[1];
+      }
+      if ((fmTitle || h1) && (fmStatus || bodyStatus) && fmDone) break;
+    }
+  } catch { /* unreadable → fall through to defaults */ }
+  return {
+    title: fmTitle || h1 || '(untitled)',
+    status: bodyStatus || fmStatus || '-',
+  };
+}
+
+/** First clause of a status, capped — keeps the table aligned when a file writes a sentence. */
+function shortStatus(s) {
+  const first = s.split(/[.(—]/)[0].trim() || s.trim();
+  return first.length > 18 ? first.slice(0, 17) + '…' : first;
+}
+
+function pad(s, n) { return s + ' '.repeat(Math.max(0, n - s.length)); }
+
+function cmdList(category) {
+  const { error, briefs } = collectBriefs(category);
+  if (error) { console.error(error); process.exit(1); }
+  if (briefs.length === 0) {
+    console.log(category ? `(no briefs in doc/${category}/)` : '(no briefs under doc/)');
+    return;
+  }
+  const rows = briefs.map((b) => {
+    const { title, status } = parseMeta(b.full);
+    return { category: b.category, slug: b.slug, status: shortStatus(status), title };
+  });
+  const w = (k) => Math.max(k.length, ...rows.map((r) => r[k].length));
+  const wc = w('category'), ws = w('slug'), wst = w('status');
+  console.log(`${pad('CATEGORY', wc)}  ${pad('SLUG', ws)}  ${pad('STATUS', wst)}  TITLE`);
+  for (const r of rows) {
+    console.log(`${pad(r.category, wc)}  ${pad(r.slug, ws)}  ${pad(r.status, wst)}  ${r.title}`);
+  }
+  console.log(`\n${rows.length} brief${rows.length === 1 ? '' : 's'}.`);
+}
+
+function cmdShow(target) {
+  if (!target) { console.error('show: need a <slug-or-path>'); process.exit(3); }
+  // Direct path hit (relative to cwd or absolute).
+  for (const p of [target, join(process.cwd(), target)]) {
+    if (existsSync(p) && statSync(p).isFile()) {
+      console.log(`── ${relative(process.cwd(), p) || p} ──\n`);
+      console.log(readFileSync(p, 'utf8'));
+      return;
+    }
+  }
+  // Otherwise resolve a slug across categories.
+  const { error, briefs } = collectBriefs();
+  if (error) { console.error(error); process.exit(1); }
+  const slug = basename(target, '.md');
+  const matches = briefs.filter((b) => b.slug === slug);
+  if (matches.length === 0) {
+    console.error(`no brief matching "${slug}".`);
+    const near = briefs.filter((b) => b.slug.includes(slug)).slice(0, 8);
+    if (near.length) {
+      console.error('did you mean:');
+      for (const n of near) console.error(`  ${n.category}/${n.slug}`);
+    }
+    process.exit(1);
+  }
+  if (matches.length > 1) {
+    console.error(`"${slug}" is ambiguous — matches ${matches.length} briefs:`);
+    for (const m of matches) console.error(`  ${m.rel}`);
+    console.error('re-run show with the full path.');
+    process.exit(2);
+  }
+  const hit = matches[0];
+  console.log(`── ${hit.rel} ──\n`);
+  console.log(readFileSync(hit.full, 'utf8'));
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+switch (cmd) {
+  case 'list': cmdList(rest[0]); break;
+  case 'show': cmdShow(rest[0]); break;
+  default:
+    console.error('usage: node briefs.mjs list [category] | show <slug-or-path>');
+    process.exit(3);
+}

package/scaffolds/ls-marketplace/plugins/kit/skills/debug/SKILL.md

@@ -1,54 +1,77 @@
 ---
-description: Investigate a bug, error message, or unexpected behavior using launch-chart first (structural + variable queries), falling back to grep/Read only when the chart can't answer. When the chart gap is the reason for the fallback, files a feedback comment to LaunchSecure so the gap is monitored and fixed.
+description: Investigate a bug, error message, or unexpected behavior. Leads with runtime evidence from the launch-beacon monitor ("what was happening when it broke") when a session exists, then traces the code with launch-chart (structural + variable queries), falling back to grep/Read only when the chart can't answer. Fuses runtime + static signals into a ranked diagnosis. Files a feedback comment when a chart gap forces the fallback. Does NOT edit code.
 ---
 
 # /kit:debug
 
-A guided investigation workflow that defaults to chart-MCP queries and only reaches for grep/Read when the chart can't answer — and when that happens, files a one-line feedback comment in LS so the gap doesn't go unnoticed.
+A guided investigation workflow. It works two evidence sources, in order:
+
+1. **Runtime** — the launch-beacon monitor's captured events (the error itself, plus the clicks / fetches / route changes leading up to it). This is what *actually happened* in the running app. Beacon was built for exactly this.
+2. **Static** — launch-chart structural + variable queries to find *where the code is* and trace the dependency chain toward the cause.
+
+It defaults to beacon-first when there's a live session and the symptom is runtime-shaped, then chart, and only reaches for grep/Read when the chart can't answer — filing a one-line gap report in LS when that happens.
 
 Parse `$ARGUMENTS`:
 - **symptom** (required) — the error message, broken behavior, or question to investigate. Quoted is fine: `/kit:debug "tags don't render on the work-item drawer"`.
-- **--start=<node>** — start the investigation from a specific file/function/table id (skip the search step).
+- **--start=<node>** — start the static investigation from a specific file/function/table id (skip the chart search step). Does not skip beacon.
 - **--layer=<id>** — scope chart queries to one layer (ui / api / db / static).
 - **--no-grep-fallback** — refuse the grep fallback entirely (strict MCP-only).
+- **--no-beacon** — skip the runtime-evidence step; go straight to static chart analysis. Use for pure structural questions, or when no monitor is running and you don't want the check.
+- **--worktree=<slug>** / **--project_root=<path>** — forwarded to every beacon MCP call (orbit worktree slug / explicit project root), same semantics as `/kit:beacon-pulse`.
 
 Examples:
 - `/kit:debug tags don't render on the work-item drawer`
 - `/kit:debug "TypeError: Cannot read property 'status' of undefined" --layer=ui`
 - `/kit:debug --start=src/server/comms/build-feed.ts`
+- `/kit:debug "checkout button does nothing" --worktree=beacon_rewrite`
 
 ## Investigation loop
 
-Run this loop until the user has enough to act, OR until a fallback was filed (then surface the fallback):
+Run Step 0, then the static loop (Steps 1–4), until the user has enough to act, OR a fallback was filed (then surface it).
+
+### Step 0 — runtime evidence (launch-beacon)
+
+Skip this step if `--no-beacon` was passed, or if the symptom is a purely structural question with no runtime component ("where is X defined", "what depends on Y", "how is auth wired"). Otherwise — for any symptom that describes something *happening* (an error message, a broken interaction, a wrong result in the running app) — start here:
+
+1. Call `mcp__local-launch-beacon__beacon_failures` with `limit: 5` (plus `worktree` / `project_root` if supplied). The most recent session is targeted implicitly. A "failure" is broader than `kind=error`: window errors, unhandled rejections, fetch/xhr ≥ 400 or thrown, and clicks where overlay interception blocked the intended target.
+2. **Match the symptom to a failure.** Pick the failure whose message/route best matches the symptom. If several plausibly match, surface the top 2–3 (with `seq`, `kind`, `ts`, message) and ask which — or take the most recent.
+3. **Pull the lead-up.** Call `mcp__local-launch-beacon__beacon_correlate` with `seq: <failure.seq>`, `before: 10`, `after: 0` (forward the same root args). This is the chain of events that produced the failure — the click that set bad state, the fetch that 500'd, the route change that mounted the wrong component. If a context event's summary is too thin (truncated stack, missing response body, selector chain), call `mcp__local-launch-beacon__beacon_event` with that `seq` for the full JSON — only when needed.
+4. **Form a runtime hypothesis** and carry it into the static phase. Example: *"beacon shows `GET /api/work-items/42/tags` returned 500 two events before the render error — so the empty-tags symptom is likely server-side, not the drawer component."* This tells the chart phase **where to start** (the failing endpoint), turning a blind structural search into a targeted one.
+
+**Graceful degradation (beacon is additive, never a hard dependency):**
+- `{error: "no session found"}` or empty failures → say so in one line (`"No beacon monitor session found — proceeding with static analysis only. (Start one with: npx launch-beacon monitor)"`) and go to Step 1. Do NOT treat this as a failure of the debug run.
+- Before giving up: if the user passed no `--worktree`/`--project_root` and `launch-orbit` has worktrees for this repo, suggest re-running with `--worktree=<slug>` (the session NDJSON may live in a worktree outside the MCP's watch root).
+- If the beacon MCP isn't wired at all, note it once and continue static-only.
+- For a deeper runtime drill (more preceding events, a different failure), point the user at `/kit:beacon-pulse` rather than re-deriving it here.
 
-### Step 1 — locate the entry point
+### Step 1 — locate the entry point (static)
 
-If `--start` was given, jump to step 2. Otherwise, use chart to find candidate nodes:
+If `--start` was given, jump to Step 2. If Step 0 produced a concrete node (an endpoint, component, or file from the failing event), use THAT as the entry point — skip the blind search. Otherwise, use chart to find candidates:
 
-1. Extract key terms from the symptom (component name, identifier, error class). Skip noise words.
-2. Call `mcp__launch-chart__read_graph(search: <term>, type: <best-guess-type>, layer: <layer?>)`. If `type` is uncertain, omit it and filter the response by relevance.
-3. If `read_graph` returns 0 candidates, broaden: try without `type`, then without `layer`. Surface the top 3 candidates to the user as ranked options; if the user can pick, jump to step 2 with their pick.
+1. Extract key terms from the symptom (component name, identifier, error class) — and from the beacon failure if Step 0 ran (the failing route/selector is a strong term). Skip noise words.
+2. Call `mcp__launch-chart__read_graph(search: <term>, type: <best-guess-type>, layer: <layer?>)`. If `type` is uncertain, omit it and filter by relevance.
+3. If `read_graph` returns 0 candidates, broaden: drop `type`, then `layer`. Surface the top 3 to the user; if they can pick, jump to Step 2 with their pick.
 
 **Chart-gap detection (entry-point search):**
-- If `read_graph` returns 0 candidates AND a quick `grep` confirms the term exists somewhere in source → file a chart-gap report per the protocol below, then proceed via the grep fallback for this query only.
-- If `detect_project_stack` lists a layer (e.g. `api`) but `read_graph(layer:"api")` returns 0 nodes → file a chart-gap report (parser misconfig).
+- `read_graph` returns 0 AND a quick `grep` confirms the term exists in source → file a chart-gap report (below), then proceed via grep fallback for this query only.
+- `detect_project_stack` lists a layer (e.g. `api`) but `read_graph(layer:"api")` returns 0 nodes → file a chart-gap report (parser misconfig).
 
-### Step 2 — understand the node
+### Step 2 — understand the node (static)
 
 Once the entry point is known, query its structure and behavior:
 
 - **Structural** — `mcp__launch-chart__read_graph(node_id: <id>, hops: 1, include_edges: true)` for what it renders/imports and what depends on it.
-- **Variable / state** — `mcp__launch-chart__inspect_node(node_id: <id>, fields: ["stateVars"])` or `(filter: <key-term>)` for what state it holds, what conditions exist. Per project CLAUDE.md, ALWAYS start with `fields` or `filter` to keep the response small.
+- **Variable / state** — `mcp__launch-chart__inspect_node(node_id: <id>, fields: ["stateVars"])` or `(filter: <key-term>)` for held state and conditions. Per project CLAUDE.md, ALWAYS start with `fields` or `filter` to keep the response small.
 
-Compose a hypothesis from these two reads. Example: "WorkItemDrawer fetches tags via `useWorkItemTags`, which calls `GET /api/work-items/:id/tags` — let's see what that returns."
+Compose a hypothesis. If Step 0 ran, **test the runtime hypothesis against the code** here — e.g. confirm the failing endpoint's handler actually can return the 500 beacon saw.
 
-### Step 3 — follow the trail
+### Step 3 — follow the trail (static)
 
-Walk the dependency edges toward the suspected cause (API endpoint, DB table, util fn, etc.). At each hop, use `read_graph(node_id, hops:1)` to find the next link. When you hit a leaf or run out of edges, narrate the chain back to the user with file:line refs from the node ids.
+Walk dependency edges toward the suspected cause (endpoint, table, util fn). At each hop, `read_graph(node_id, hops:1)` to find the next link. When you hit a leaf, narrate the chain back with file:line refs from the node ids. If Step 0 gave a runtime chain, align the two — the static call path should explain the observed runtime sequence.
 
 ### Step 4 — propose, don't fix
 
-End with a one-paragraph diagnosis + 2-3 candidate causes ranked by likelihood. Do NOT propose an edit unless the user asks for one — debug is investigation, not implementation. Suggest the next move: "Want me to read the route handler and confirm?" or "Want `/kit:diagram sequence`-ing the call chain?"
+End with a one-paragraph diagnosis + 2–3 candidate causes ranked by likelihood. **When both sources contributed, say which evidence is runtime vs static** — e.g. *"Runtime (beacon): the tags fetch 500'd. Static (chart): the handler dereferences `org.id` with no null-guard when the session has no org — the likely cause."* A diagnosis backed by an observed failure + the matching code path is far stronger than either alone. Do NOT propose an edit unless asked — debug is investigation, not implementation. Suggest the next move: "Want me to read the handler and confirm?" or "Want to `/kit:diagram sequence` the call chain?"
 
 ## Grep fallback
 
@@ -78,8 +101,10 @@ Then continue with the grep fallback for THIS query. Don't file again in the sam
 
 ## Constraints
 
-- **Chart-first.** Default to MCP queries; grep only when the chart cannot answer.
+- **Runtime-first, then static.** When a beacon session exists and the symptom is runtime-shaped, lead with beacon — it converts a blind structural search into a targeted one. Beacon is additive evidence: its absence never aborts the run, it just drops you to static-only with a one-line note.
+- **Don't reimplement beacon skills.** Step 0 does a lightweight `beacon_failures` + `beacon_correlate`; for deeper runtime analysis defer to `/kit:beacon-pulse` (failure + N preceding) and `/kit:beacon-scan` (events by kind).
+- **Chart-first for the static phase.** Default to MCP queries; grep only when the chart cannot answer.
 - **One gap report per invocation.** Don't spam comments.
 - **No implementation.** This skill diagnoses; it does not edit. If the user wants the fix, they invoke `/fix:*` or hand the diagnosis back to you in chat.
-- **Cite by node id.** Every claim links to a chart node id (file:line via `inspect_node` lines) so the user can verify.
-- **Surface the fallback verbatim.** When grep is used, the message that grep was used (and why) must appear in the output — silent fallback hides the gap.
+- **Cite your evidence.** Static claims link to a chart node id (file:line via `inspect_node` lines); runtime claims cite the beacon `seq` + event kind. The user can verify either.
+- **Surface fallbacks verbatim.** When grep is used, or when beacon came up empty, the message (and why) must appear in the output — silent fallback hides the gap.