@launchsecure/launch-kit 0.0.33 → 0.0.34

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.34",
+  "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,33 @@
   },
   "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"
+  },
+  "scripts": {
+    "build": "pnpm build:client && pnpm build:chart-client && pnpm build:deck-client && pnpm build:council-client && pnpm build:beacon && pnpm build:server",
+    "build:beacon": "vite build --config vite.beacon.config.ts && tsc -p tsconfig.beacon.json --emitDeclarationOnly --outDir dist/beacon/types",
+    "test:beacon": "vitest run --config vite.beacon.config.ts",
+    "test:radar": "vitest run --config vite.radar.config.ts",
+    "test:chart": "vitest run --config vite.chart.test.config.ts",
+    "build:deck-client": "vite build --config vite.deck.config.ts",
+    "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 src/server/launch-radar-entry.ts src/server/rover-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",
+    "dev:server": "pnpm build:server && node dist/server/cli.js",
+    "dev": "pnpm build:server && concurrently -k -n client,server -c cyan,magenta \"vite\" \"node dist/server/cli.js\"",
+    "prepublishOnly": "pnpm build"
   },
   "files": [
     "dist",
@@ -76,6 +96,8 @@
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@launchsecure/claude-code-web": "workspace:*",
+    "@launchsecure/ui": "workspace:*",
     "@types/node": "^20.0.0",
     "@types/pg": "^8.11.10",
     "@types/react": "^18.3.12",
@@ -99,25 +121,6 @@
     "react-router-dom": "^6.28.0",
     "tailwindcss": "^3.4.19",
     "vite": "^5.4.11",
-    "vitest": "^1.6.0",
-    "@launchsecure/claude-code-web": "0.0.1",
-    "@launchsecure/ui": "0.0.1"
-  },
-  "scripts": {
-    "build": "pnpm build:client && pnpm build:chart-client && pnpm build:deck-client && pnpm build:council-client && pnpm build:beacon && pnpm build:server",
-    "build:beacon": "vite build --config vite.beacon.config.ts && tsc -p tsconfig.beacon.json --emitDeclarationOnly --outDir dist/beacon/types",
-    "test:beacon": "vitest run --config vite.beacon.config.ts",
-    "test:radar": "vitest run --config vite.radar.config.ts",
-    "test:chart": "vitest run --config vite.chart.test.config.ts",
-    "build:deck-client": "vite build --config vite.deck.config.ts",
-    "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",
-    "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",
-    "dev:server": "pnpm build:server && node dist/server/cli.js",
-    "dev": "pnpm build:server && concurrently -k -n client,server -c cyan,magenta \"vite\" \"node dist/server/cli.js\""
+    "vitest": "^1.6.0"
   }
-}
+}

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,48 @@
 ---
-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 idea document committed as a markdown file under doc/ideas/. NOT a Comm Hub / CapCom comment. Use to capture an idea in the repo before promoting it to an Epic.
 ---
 
 # /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 repo-backed idea document: a long-form description of a problem/opportunity written as a **markdown file committed to the repo** under `doc/ideas/<slug>.md`. It is the structured alternative to a free-form thought 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 FILE, not a comment.** Do NOT post Briefs to the LaunchSecure Comm Hub / CapCom via `communication_write`. Briefs live in the repo and travel through git like any other source artefact. (An earlier version of this skill posted Briefs as Comm Hub comments — that was wrong; Briefs are file commits.)
 
 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), `--from=discussion:<id>` to seed body from an existing discussion thread, `--dir=<path>` to override the default `doc/ideas/` location.
+- For **update**: `<slug-or-path>` and either a body description (re-generates body) or `--append=<text>` to add a section.
+- For **list**: `[--dir=<path>]` — defaults to listing `doc/ideas/`.
+- For **show**: `<slug-or-path>`.
 
 Examples:
-- `/kit:brief new "Channels for Comm Hub" --module=communication`
+- `/kit:brief new "Channels for Comm Hub"`
 - `/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."`
-
-## Preflight
+- `/kit:brief list`
+- `/kit:brief show launch-watch`
+- `/kit:brief update launch-watch --append="Resolved: use the Slack metaphor not Teams."`
 
-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
+- **Default directory**: `doc/ideas/` at the repo root.
+- **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 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. For **new**, check `doc/ideas/<slug>.md` does not already exist. If it does, surface it and ask whether to `update` instead — do NOT overwrite silently.
+3. No MCP, no network, no Comm Hub calls. This skill only touches the filesystem + git.
 
-### 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 +67,38 @@ 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. 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 to a file, never posted back).
+2. Use launch-chart (`read_graph`, `grep_nodes`) to populate the References section with real code paths — don't invent them.
+3. **Write the file** to `doc/ideas/<slug>.md` with the Write tool.
+4. Print the path written. 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>` to a file under `doc/ideas/` (or the `--dir` override). If nothing matches, list candidates and stop.
+2. If `--append=<text>`, Read the 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`.
+List `doc/ideas/*.md` (or `--dir`). Render one line per brief: `slug  status  title` — read each file's `# Title` and `**Status**:` line to fill those columns.
 
 ### show
 
-Fetch via `communication_read` and print the body as-is, no transformation.
+Read the file and print its contents as-is, no transformation.
 
 ## 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".
+- **A Brief is a file, never a Comm Hub comment.** Do NOT call `communication_write` / `communication_update` to create or store a Brief. Reading a `--from` discussion seed is the only allowed Comm Hub touch, and it's read-only.
+- **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 the brief the user asked for, but 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/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.