@launchsecure/launch-kit 0.0.29 → 0.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchsecure/launch-kit",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "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).",
   "license": "MIT",
   "author": "LaunchSecure - AutomateWithUs",
@@ -66,8 +66,9 @@
     "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 --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 && 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 --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\"",
@@ -84,6 +85,7 @@
     "html-to-image": "^1.11.13",
     "node-pty": "^1.2.0-beta.12",
     "pg": "^8.13.0",
+    "pgsql-parser": "^17.9.15",
     "tree-sitter": "^0.21.1",
     "tree-sitter-typescript": "^0.23.2",
     "typescript": "^5.5.0",

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

@@ -0,0 +1,180 @@
+---
+description: Source-code analysis using launch-chart as the default tool. Routes structural / internal-state / content queries to the chart MCP first; falls back to grep/Read only when the chart cannot answer (non-TS files, missing layer, parser gap). Files a one-line LS feedback comment whenever the fallback is the chart's fault, so gaps get fixed.
+when_to_use: |
+  Auto-fire whenever the user wants to understand, explore, audit, or trace source code or codebase structure — INSTEAD of defaulting to grep / glob / Read. Trigger phrases: "analyse" / "analyze" / "analysis", "explain how X works", "how does X work", "where is X", "what depends on / calls / renders / imports X", "trace / walk through Y", "explore the codebase", "understand this module", "audit X", "show me all / list every X" (pages, endpoints, tables, hooks, components), "what state does X track", "what conditions exist in X", "which endpoints check Y", "what tables relate to X", "what permissions does role X grant", "is migration X destructive", "what seed roles / tags / providers exist", "find FIXME / TODO". Also auto-fire on open-ended structural questions ("how is auth set up", "where does the work-item flow happen") even without explicit "analyse" wording. Do NOT auto-fire for: bug investigation framed as symptom ("X is broken", "why doesn't Y work" — use /kit:debug), refactor blast assessment ("what breaks if I change Z" — use /kit:blast-radius), or render-as-diagram requests (use /kit:diagram).
+allowed-tools:
+  - mcp__launch-chart__read_graph
+  - mcp__launch-chart__inspect_node
+  - mcp__launch-chart__grep_nodes
+  - mcp__launch-chart__detect_project_stack
+  - mcp__launch-chart__blast_points
+  - mcp__launch-chart__effects_index
+  - mcp__launch-chart__list_notes
+  - mcp__launch-chart__who_uses
+  - mcp__launch-chart__trace_path
+  - mcp__launch-chart__migration_audit
+  - mcp__launch-chart__drift_report
+  - mcp__launch-chart__auth_coverage_report
+  - mcp__launch-secure__kit_feedback_submit
+---
+
+# /kit:analyse
+
+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.
+
+## 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.
+2. **On illegitimate chart gap, file ONE LS feedback report** via `mcp__launch-secure__kit_feedback_submit` (the kit-self feedback channel — NOT `communication_write`, which would land in the user's own project Comm Hub instead of the launch-kit project). One report per invocation, not per query.
+3. **Fall back to grep / Read** only per the rules below.
+4. **Surface the fallback verbatim** in your final output — silent fallbacks hide gaps and let the chart rot.
+
+## Routing table — chart tool per question shape
+
+Specialized tools (use these first when the question matches):
+
+| Question shape | Chart tool | Notes |
+|---|---|---|
+| "Where is X referenced from other layers / who uses permission P / who calls endpoint E / who references table T" | `who_uses(target: X)` | scans all layers' cross_refs (calls_api, references_static, reads_via, mutates_via, reads, mutates, references_api). Paginated. |
+| "Trace path between A and B / how does page X end up reading table T" | `trace_path(from: A, to: B)` | BFS via cross_refs including via[] middleware chains. Bounded by max_hops/max_paths. Paginated. |
+| "Are migrations safe / which destructive migrations lack guards" | `migration_audit` | codifies CLAUDE.md's three-layer discipline. Lists destructives missing orphan_check / sidecar_backup / pre_flight_notice. Paginated. |
+| "Show drift / SQL vs ORM mismatches / unresolved routes / FK drift" | `drift_report(layer?, kind?, confidence?)` | aggregates contradictions + flagged_edges across layers. Generalizes db-only include_findings. Paginated. |
+| "Audit auth coverage / which endpoints are public / how many use withAuth" | `auth_coverage_report(module?, strategy?)` | aggregates api endpoints by auth[] wrapper. Surfaces unauthenticated. Grouped by module. |
+| "What endpoints call /api/X / what URLs does UI fetch / who calls this endpoint" | `effects_index(kind: "fetch_calls", key?)` | UI→API call inventory from cross_refs[calls_api] + raw effects.fetches. |
+| "Invert endpoint effects / which endpoints call db.user.findUnique" | `effects_index(kind: "api_effects", key?)` | inverts api endpoint effects.{calls,fetches,persists,…}. Use `key` for full caller list across categories. |
+
+General routes (use these when no specialized tool fits):
+
+| Question shape | Chart tool | Notes |
+|---|---|---|
+| "Where is X defined / what is it" | `read_graph(search: X)` | substring match on id, name, route, JSX text, ui_labels, notes |
+| "What pages / hooks / endpoints / tables / migrations exist" | `read_graph(layer: <L>, type: <T>)` | layer + type filters |
+| "What's in module Y" | `read_graph(module: Y)` | module tags from `.launchchart.json` |
+| "Filter by multiple conditions (e.g. destructive AND missing orphan check)" | `read_graph(tag_predicates: [{field,op,value},...])` | ops: eq/ne/gt/lt/gte/lte/exists/not_exists/in. Matches top-level node attrs OR tag keys. |
+| "Per-node incoming + outgoing cross-layer refs" | `read_graph(node_id: X, include_cross_refs: true, cross_ref_type?)` OR `inspect_node(node_id: X, fields: ["crossRefs"])` | when you want crossRefs inline alongside other data |
+| "Surface flagged_edges by confidence (DYNAMIC routes, FK drift)" | `read_graph(layer: <L>, edge_confidence: ["medium","high"])` | layer-independent flagged_edges filter |
+| "What does X render / what renders X" | `read_graph(node_id: X, hops: 1, include_edges: true)` | renders / imports edges |
+| "Which UI calls API endpoint E" | `read_graph(node_id: E, layer: "api", include_edges: true)` OR `who_uses(target: E)` | cross-layer `calls_api` edges |
+| "What endpoints touch table T" | `read_graph(layer: "api", search: T)` then check `db_models[]` | endpoints already index `db_models` and `db_operations` |
+| "What auth does endpoint E use" | `read_graph(layer: "api", search: E)` then check `auth[]` | auth wrappers extracted per endpoint |
+| "Is endpoint E mutating" | `read_graph(layer: "api", search: E)` then check `mutates` flag | already extracted |
+| "What state does Z hold" | `inspect_node(node_id: Z, fields: ["stateVars"])` | start narrow, always |
+| "What conditions exist in Z" | `inspect_node(node_id: Z, fields: ["conditions"])` | if / else / ternary tests with their test expressions |
+| "Which nodes match pattern P inside conditions/vars/elements" | `inspect_node(layer: <L>, filter: P, fields: ["conditions"])` | regex over deep fields, raises node limit to 50 |
+| "DOM ids / storage keys / window events / fetch urls / timers / singleton risks" | `effects_index(kind: <kind>, key?)` | precomputed cross-cutting inverted indexes |
+| "DOM-id / storage-key collisions" | `effects_index(kind: "collisions")` | impossible without graph |
+| "What tables relate to X" | `read_graph(layer: "db", node_id: X, include_edges: true)` | belongs_to / has_many edges |
+| "Single migration M's safety status" | `read_graph(layer: "db", type: "migration", search: M)` | migration nodes carry `is_destructive`, `has_orphan_check`, `has_sidecar_backup`, `has_pre_flight_notice`, `contains_backfill`, `contains_drop_column` (use `migration_audit` for cross-migration audits) |
+| "What seed roles / permissions / tags / providers / plans exist" | `read_graph(layer: "static", type: "seed_role")` etc. | static layer covers `prisma/seed.ts` |
+| "What permissions does role R grant" | `read_graph(layer: "static", node_id: "seed:role:R", include_edges: true)` | `grants` edges |
+| "Find pattern P in module M's files only" | `grep_nodes(layer: <L>, module: M, pattern: P)` | grep scoped via graph — much narrower than raw grep |
+| "What breaks if I delete / change X" | `blast_points(node_id: X, direction: "reverse")` | reverse-dep walk across all layers in one call |
+| "Find FIXME / TODO / tagged notes" | `read_graph(search: "FIXME")` or `list_notes` | tagged comments indexed |
+| "What's the current stack / which parsers run / which layers are available" | `detect_project_stack` | run before concluding a layer is missing |
+
+## inspect_node strategy — start narrow, widen if needed
+
+1. **Decide first**: structure or variables? Structure (renders/imports/depends) → `read_graph`. Variables/state/conditions → `inspect_node`.
+2. **Always pass `fields` and/or `filter`** to keep the response small and inline. Examples:
+   - State only → `inspect_node(node_id: X, fields: ["stateVars"])`
+   - Pattern across many nodes → `inspect_node(layer: "ui", filter: "isAdmin", fields: ["conditions"])`
+3. **Only broaden if narrow returns nothing.** Remove `filter`, add more `fields`, or omit `fields` entirely as a last resort.
+4. **Never** call `inspect_node` with no `fields` and no `filter` on a large page or component — returns 50-80KB dumps that get persisted to disk and force a second read step.
+
+## parser_warning awareness
+
+Several chart tools (`who_uses`, `trace_path`, `drift_report`, `read_graph` with `include_cross_refs` or `edge_confidence`, `inspect_node` with `crossRefs`, `effects_index` with `fetch_calls`) attach a `parser_warning` field when the underlying source data (cross_refs / flagged_edges / contradictions) is completely empty for the scanned layer(s). This is the chart **telling you the parser may not have run** — not "there's no match."
+
+When you see `parser_warning` in a tool response:
+1. **Don't silently report "no results."** Empty-with-warning is a different signal than empty-without-warning.
+2. **Run `detect_project_stack`** to verify which parsers are detected. If the parser referenced in the warning IS detected, the data should be present — that's a chart-gap worth filing per the protocol below.
+3. **If the parser isn't detected for this stack** (e.g. cross-layer parsers don't apply because the project isn't TS/Next), surface that to the user — the chart doesn't claim coverage here.
+4. **Never strip `parser_warning` from your output.** Include it (or a short paraphrase) in the user-facing summary so they can act.
+
+## Chart breakage triage — BEFORE filing any feedback comment
+
+When a chart query returns empty / errors / fires `parser_warning`, walk this triage. Two upstream causes are common and require NO feedback comment — they're user-action gaps, not chart bugs. File a comment ONLY after both are ruled out.
+
+### Step 1 — does the graph file even exist?
+
+If a chart tool returns an error like `"No <layer> graph found at .launchsecure/graphs/<layer>.json"` or `"Run generate_graph first"`, the user hasn't built the graph yet. **Do NOT file a comment.** Tell the user verbatim and stop:
+- `"No chart graph found in this project. Run mcp__launch-chart__generate_graph (or `npx launch-chart generate`) once, then retry the query."`
+
+### Step 2 — is the graph stale?
+
+Every chart response carries `_meta.state`. If it's anything other than `"fresh"` (e.g. `"stale"`, `"escalated"`), the graph hasn't been regenerated since recent file edits — your query may be looking at an outdated snapshot. **Do NOT file a comment for stale-graph results.** Surface to the user:
+- `"Chart graph is <state> (last full regen: <_meta.lastFullRegenAt>, <N> patches since). Recent edits may not be visible. Run generate_graph to refresh, then retry."`
+- Then either stop OR proceed with the stale results, flagging the staleness in your final output.
+
+### Step 3 — parser produced empty/wrong output (the only chart-gap case)
+
+Only AFTER ruling out steps 1 + 2: if `detect_project_stack` shows the relevant parser is detected, the graph file exists, AND `_meta.state` is fresh — and the query still returns empty / missing expected fields / missing cross-layer edges — that's a real chart gap. File the LS feedback comment per the template below, with parser-specific fields populated (parser name, layer, graph_meta).
+
+## When the fallback is legitimate (NO feedback comment)
+
+These are expected gaps — the chart doesn't claim coverage here:
+
+- **Non-TS source files** — SQL (`prisma/migrations/**/*.sql` and other), JS/CJS/MJS files, JSON, markdown (docs/), env files, CSS / Tailwind config, YAML / TOML
+- **CSS classes, Tailwind utilities, inline styles** — chart doesn't model class names or computed styles
+- **CLI bin / Node script files** — the typescript-project parser is Next.js-shaped and may skip standalone server entrypoints (e.g. `packages/cli/src/server/init-entry.ts` is known to be unindexed)
+- **Untagged comment content** — only notes-tagged comments are indexed; arbitrary inline comments are not
+- **Verifying a file's literal contents for review or editing** — Read is correct for "show me lines 40-80 of foo.ts"
+
+In these cases, jump to grep / Read directly. Tell the user explicitly which non-coverage rule applied — e.g. `"Symptom is in an SQL migration file; chart doesn't model raw SQL — using Read directly."`
+
+## When the fallback is illegitimate (FEEDBACK COMMENT REQUIRED)
+
+The chart should have answered but didn't. File ONE comment before falling back:
+
+- `read_graph(search: "X")` returns 0 candidates AND a quick `grep` confirms "X" exists in indexed TS source
+- A layer listed by `detect_project_stack` returns 0 nodes for any well-formed query (parser misconfig)
+- `inspect_node` returns no `columns` / `elements` / `stateVars` for a known table or component (extractor gap)
+- A cross-layer edge that should exist (e.g. UI page that fetches `/api/foo` should have a `calls_api` edge) is missing
+
+### Feedback report template
+
+Call `mcp__launch-secure__kit_feedback_submit` — routes to the launch-kit project regardless of which repo the user is in:
+
+```
+title: "launch-chart gap: <one-line, e.g. 'fetch-resolver produced 0 calls_api refs on ui layer'>"
+source: "kit:analyse"
+body: |
+  Skill: /kit:analyse
+  Query: <one-line what the user asked>
+  Tool:  <chart_tool>(<args>)
+  Returned: <summary — e.g. "0 nodes" or "missing 'columns' field">
+  Cross-check: grep "<term>" matched <N> files (sample: <path1>, <path2>)
+  Project stack: <one-line from detect_project_stack>
+  Triage:
+    graph_exists: yes
+    graph_state: <_meta.state>           # fresh — ruled out staleness
+    parser_detected: <parser_id>          # from detect_project_stack
+  Parser: <parser_id>                     # e.g. fetch-resolver, typescript-project
+  Layer:  <layer_id>                      # ui / api / db / static
+  Graph meta:
+    state: <_meta.state>
+    last_full_regen_at: <_meta.lastFullRegenAt>
+```
+
+One report per invocation. After filing, surface to the user: `"(Filed chart-gap report to launch-kit project. Falling back to grep / Read for this query.)"` and continue.
+
+## Output shape
+
+For every analysis, return:
+
+1. **One-paragraph answer** to the user's question — direct, no preamble.
+2. **Citations as chart node ids** — each claim links to a node (file path like `app/api/orgs/.../route.ts`, table name like `WorkItem`, route like `/admin/analytics`). The user must be able to verify by clicking through.
+3. **The chart query path you used** — one or two lines naming the tools + arguments. Lets the user re-run or extend the investigation.
+
+If a fallback happened, prefix the output with one of:
+- `(Filed gap report id: <id>. Falling back to grep — chart should have answered.)`
+- `(Symptom is in <non-TS asset class>; chart doesn't model it — using grep / Read directly.)`
+
+## Constraints
+
+- **Chart-first. No exceptions.** Default to MCP queries. grep / glob / Read only per the fallback rules above.
+- **One feedback report per invocation.** Do not spam — bundle multiple chart issues into one report if they fire in the same run.
+- **Cloud LS by default.** Use `mcp__launch-secure__kit_feedback_submit` (cloud). The local variant only if the user explicitly said "local".
+- **No implementation.** This skill explains and traces; it does not edit. If the user wants the fix, hand the diagnosis back and let them invoke an editor flow.
+- **Cite by node id.** Every claim links to a chart node so the user can verify.
+- **Surface the fallback verbatim.** Silent fallbacks hide gaps and let the chart rot.

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

@@ -0,0 +1,107 @@
+---
+description: Show the array of launch-beacon monitor sessions via the launch-beacon MCP — which is most recent, how many events each has, last event time, suspected liveness. Use to confirm a session is being recorded, find an old session to inspect, or audit disk usage. Read-only.
+---
+
+# /kit:beacon-array
+
+Liveness + inventory across every `launch-beacon monitor` session this repo has recorded — one row per beacon in the array.
+
+Parse `$ARGUMENTS` as space-separated tokens, in any order:
+- `full` — expanded report. Empty → terse one-line-per-session summary.
+- `--worktree=<slug>` — orbit worktree slug. Forwarded to MCP as the `worktree` arg.
+- `--project_root=<path>` — explicit project root (absolute, or relative to cwd). Forwarded as `project_root`. Takes precedence over `--worktree`.
+
+Examples:
+- `/kit:beacon-array` → terse one-line-per-session summary
+- `/kit:beacon-array full` → expanded report
+- `/kit:beacon-array --worktree=beacon_rewrite` → enumerate sessions captured in that worktree
+- `/kit:beacon-array full --worktree=beacon_rewrite` → expanded report for that worktree
+
+## Enumerate sessions
+
+Call `mcp__local-launch-beacon__beacon_sessions`, forwarding `worktree` / `project_root` if supplied. Returns an array of per-session summaries: token, event count, kind breakdown, first/last seq, last event timestamp.
+
+If the response is `{sessions: []}` OR `{error: ...}`, **alert the user with the exact MCP error string**, then walk the fallback below — do NOT silently `ls`.
+
+**Fallback when the MCP returns nothing:**
+1. If the user did NOT pass `--worktree` / `--project_root` and `launch-orbit` has worktrees registered for this repo, suggest re-running with `--worktree=<slug>` before falling back to the filesystem.
+2. Look for `.launchsecure/beacon-*.ndjson` in cwd, then in up to 2 parent dirs. Use the `Read` tool — never `ls`, `find`, or globbing as the primary path.
+3. If files are found at an alternative path, tell the user the path mismatch explicitly: `"MCP scans <root>/.launchsecure/ but sessions live at <found-path>. Reading directly."`
+4. If nothing is found anywhere, stop with: `"No beacon sessions found in .launchsecure/. Start one with: npx launch-beacon monitor"`.
+
+## Per-session facts
+
+For each session the MCP returns:
+- **token** — session id
+- **events** — total event count
+- **last_ts** — last event timestamp (epoch ms)
+- **last_kind** — kind of the last event (read from the kind breakdown's most-recent entry, or call `beacon_event(seq: last_seq)` for certainty)
+- **kinds** — kind breakdown map (`{click: 142, fetch: 71, …}`)
+- **first_seq / last_seq** — bounds
+
+Compute **age** from `last_ts` (current epoch minus `last_ts`):
+- < 5s → "just now"
+- < 60s → "Ns ago"
+- < 1h → "Nm ago"
+- < 24h → "Nh ago"
+- else → "Nd ago"
+
+## Liveness heuristic
+
+- **active** — `last_ts` is within the last 5 seconds (matches the receiver's batch-flush interval)
+- **idle** — between 5 seconds and 30 minutes
+- **stale** — older than 30 minutes (the receiver enforces a 30-min cap)
+
+## Default output (no arguments)
+
+```
+.launchsecure/
+  ● 8f3c2a91     247 events    click (just now)        ACTIVE
+    a1b2c3d4      89 events    error (12m ago)         idle
+    2557799f   1,247 events    route (2h ago)          stale
+
+3 sessions, 1 active.
+```
+
+Rules:
+- Glyph: `●` (filled) for active, blank for idle/stale.
+- Columns: token (8 chars) — events (right-aligned, thousands-separated) — last event "kind (age)" — status word.
+- Sort newest-first by `last_ts`.
+- Summary line: total count + how many active.
+- Plain text, monospace alignment.
+
+## Full output (`/kit:beacon-array full`)
+
+Same per-session block as default, then expand each:
+
+```
+● 8f3c2a91 — ACTIVE
+   events:      247
+   last event:  2026-05-26T12:20:51Z (just now)
+   last kind:   click
+   kinds:       click 142, fetch 71, route 12, error 3, dialog 9, probe 10
+   seq range:   1–247
+   started:     2026-05-26T12:12:33Z (8m ago)
+
+  a1b2c3d4 — idle
+   ...
+```
+
+For the `started` timestamp, call `mcp__local-launch-beacon__beacon_event` with `seq: <first_seq>, session: <token>` (and forward the same `worktree` / `project_root` args you used on `beacon_sessions`) and read its `ts`. Only do this for the full view — skip in the default view to keep it sub-second.
+
+`kinds:` formatted as `kind1 N1, kind2 N2, …` sorted by count desc, comma-separated.
+
+End with the same summary line as default.
+
+## File size
+
+The `beacon_sessions` summary does NOT include byte size. Both default and full views omit it — size isn't load-bearing for diagnosis. If the user explicitly asks ("how big is this file?"), fall back to `Read`-then-count or `wc -c` for that single file and tell them so: `"MCP doesn't expose byte size — falling back to wc -c."`.
+
+## Constraints
+
+- **MCP-first.** Use `beacon_sessions` and `beacon_event` — never `ls`, `wc`, `stat`, `tail`, `sed` as the primary path.
+- **Alert on fallback.** If the MCP can't answer, say so verbatim before reading the files directly.
+- **Read-only.** No deletion, no rotation, no auto-cleanup.
+- **Fast.** Default view should be sub-second even with many sessions.
+- **Plain text.** No markdown tables, no fenced blocks in the actual output.
+- **Don't suggest cleanup.** That's `/kit:beacon-clear`'s job. Stale sessions are informational, not an error.

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

@@ -0,0 +1,94 @@
+---
+description: Soft-delete launch-beacon monitor session NDJSON files. Default clears only the latest session (so you can start a clean repro); pass `all` to clear every `.launchsecure/beacon-*.ndjson`. Always shows what will be cleared and asks for confirmation. Recoverable from `.launchsecure/.trash/<ts>/`.
+---
+
+# /kit:beacon-clear
+
+Clean slate before a fresh repro. The receiver appends to the same NDJSON file across reconnects of the same session, so an existing file accumulates noise from earlier attempts — clearing first makes the new stream easier to reason about.
+
+Parse `$ARGUMENTS` as space-separated tokens, in any order:
+- empty → clear the most recent session file only
+- `all` → clear every `.launchsecure/beacon-*.ndjson` in the target dir
+- a specific token or filename → clear that one file (must match a real path)
+- `--worktree=<slug>` — orbit worktree slug. Forwarded to MCP as the `worktree` arg; the soft-delete acts on the worktree's `.launchsecure/`.
+- `--project_root=<path>` — explicit project root (absolute, or relative to cwd). Forwarded as `project_root`. Takes precedence over `--worktree`.
+
+Examples:
+- `/kit:beacon-clear` → clear the most recent session in cwd's `.launchsecure/`
+- `/kit:beacon-clear all` → clear every session in cwd's `.launchsecure/`
+- `/kit:beacon-clear all --worktree=beacon_rewrite` → clear every session in that worktree's `.launchsecure/`
+
+## Enumerate candidates
+
+Call `mcp__local-launch-beacon__beacon_sessions`, forwarding `worktree` / `project_root` if supplied. Use `token`, `last_ts`, `events`, and `path` (absolute) from the response. **The filesystem operations below MUST use `path` from this response — never reconstruct paths from `.launchsecure/beacon-<token>.ndjson` relative to cwd**, because with `--worktree` / `--project_root` the real directory is elsewhere.
+
+If the response is `{sessions: []}` OR `{error: ...}`, **alert the user with the exact MCP error string**, then walk the fallback below — do NOT silently `ls`.
+
+**Fallback when the MCP returns nothing:**
+1. If the user did NOT pass `--worktree` / `--project_root` and `launch-orbit` has worktrees registered for this repo, suggest re-running with `--worktree=<slug>` before falling back to the filesystem.
+2. Look for `.launchsecure/beacon-*.ndjson` in cwd, then in up to 2 parent dirs. Use the `Read` tool — never `ls`, `find`, or globbing as the primary path.
+3. If files are found at an alternative path, tell the user the path mismatch and ASK before proceeding — the user may not want to clear files at an unexpected location.
+4. If nothing is found anywhere, stop with: `"No beacon sessions found in .launchsecure/. Nothing to clear."`.
+
+## Decide target set
+
+- empty → most-recent session (highest `last_ts`)
+- `all`  → every session the MCP returned
+- otherwise → resolve `$ARGUMENTS` to a single token: try the literal arg first as a session id, then strip a `.ndjson` suffix, then try matching against the filename portion of a path containing `beacon-<token>.ndjson`. Refuse with a clear message if none match.
+
+## Refusal rules
+
+Refuse with a clear message if:
+- the target set is empty
+- any target resolves outside `.launchsecure/` (defence against `..` injection from `$ARGUMENTS` — even if the user passes an absolute path)
+- the active session is being written *right now* (`last_ts` within the last 5 seconds) — print a one-line warning and ask the user to stop the monitor first:
+  ```
+  ⚠ .launchsecure/beacon-8f3c2a91.ndjson was last written 2s ago — looks active.
+    Stop the receiver (Ctrl+C in the launch-beacon monitor terminal) and re-run /kit:beacon-clear.
+  ```
+  The user can still force by passing the token explicitly — but never silently nuke an actively-written file.
+
+## Confirmation
+
+Print what's about to be moved and ask before doing it.
+
+```
+About to soft-delete 1 file:
+  .launchsecure/beacon-a1b2c3d4.ndjson   89 events, 12m ago
+
+Recoverable from .launchsecure/.trash/<UTC-timestamp>/ until manually purged.
+
+Confirm? (y/N)
+```
+
+For `all`, list every file with event count + age. Don't truncate.
+
+Wait for explicit `y`/`yes`. Anything else → abort with `Cancelled. No files were moved.`
+
+## Soft-delete (move, don't rm)
+
+Create `<sessionDir>/.trash/<UTC-ISO-timestamp>/` and `mv` each target into it, where `<sessionDir>` is `dirname(path)` from the `beacon_sessions` response — NOT a hard-coded `.launchsecure/`. This matters when `--worktree` or `--project_root` was passed, because the dir is then the worktree's `.launchsecure/`, not cwd's. **Never `rm`.** This is the mitigation for the recall coverage gap — recall doesn't snapshot `.launchsecure/*` today (tracked in LS work item #144). Soft-delete preserves the option to recover within the same machine.
+
+```bash
+SESSION_DIR=$(dirname "<path-from-beacon_sessions>")  # e.g. /repo/.claude/worktrees/foo/.launchsecure
+TRASH="$SESSION_DIR/.trash/$(date -u +%Y%m%dT%H%M%SZ)"
+mkdir -p "$TRASH"
+mv "$SESSION_DIR/beacon-<token>.ndjson" "$TRASH/"
+```
+
+After the move, print:
+
+```
+✓ moved 1 file to .launchsecure/.trash/20260526T142233Z/ (89 events archived).
+  Recover with: mv .launchsecure/.trash/20260526T142233Z/beacon-a1b2c3d4.ndjson .launchsecure/
+```
+
+For `all`, print the count and the trash dir once; don't list every recovery command.
+
+## Constraints
+
+- **MCP-first for enumeration.** Use `beacon_sessions` — never `ls` as the primary path.
+- **Destructive — always confirm.** Even if `$ARGUMENTS` is `all`, ask first.
+- **Scope-locked to the session dir.** The session dir is `dirname(path)` from `beacon_sessions` (typically `.launchsecure/`, but `<worktree>/.launchsecure/` when `--worktree`/`--project_root` is passed). Reject any target outside the dir the MCP told you about, even if the user passes an absolute path. We never touch files we didn't write.
+- **Soft-delete only.** Never `rm` — always `mv` into `.launchsecure/.trash/<ts>/`. The trash dir is not auto-pruned; cleaning it up is a deliberate user action.
+- **Don't stop the monitor server.** This command only moves files. The receiver keeps running and will reopen the same file on its next write — which is fine, the file just starts empty again.

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

@@ -0,0 +1,82 @@
+---
+description: Show the most recent failure from the active launch-beacon monitor session, plus the N events that preceded it (default 10). Answers "what was happening when it broke" without scrolling through the full stream. Read-only.
+---
+
+# /kit:beacon-pulse
+
+The "what happened just before this failure" command — a single pulse, freezing the moment the beacon caught a failure. When a bug fires, the actual story is usually the chain of events leading up to it: the click that triggered a state change, the failed fetch that left auth in a bad state, the route change that mounted the wrong component.
+
+A "failure" here is anything `mcp__local-launch-beacon__beacon_failures` returns — window errors, unhandled rejections, fetch/xhr with status ≥ 400 or thrown, and clicks where overlay interception blocked the intended target. Broader than just `kind=error`; matches what users mean when they say "something broke."
+
+Parse `$ARGUMENTS` as space-separated tokens, in any order:
+- An optional **integer** — the count of preceding events to include. Default 10. Cap at 50 (the `beacon_correlate.before` tool limit).
+- `--worktree=<slug>` — orbit worktree slug. Forwarded to every MCP call as the `worktree` arg.
+- `--project_root=<path>` — explicit project root (absolute, or relative to cwd). Forwarded as `project_root`. Takes precedence over `--worktree`.
+
+Examples:
+- `/kit:beacon-pulse` → 10 events before the latest failure
+- `/kit:beacon-pulse 25` → 25 events before
+- `/kit:beacon-pulse --worktree=beacon_rewrite` → query a worktree's session
+
+## Locate the most recent failure
+
+Call `mcp__local-launch-beacon__beacon_failures` with `limit: 1` (and `worktree` / `project_root` if the user supplied them). The tool implicitly targets the most recent session.
+
+If the response is `{error: "no session found"}` OR an empty failures array, **alert the user with the exact MCP error string**, then walk the fallback below — do NOT silently grep. The MCP can come up empty for two non-bug reasons: (a) no session has been started, (b) the session NDJSON lives outside the MCP's watch root (e.g. inside an orbit worktree the user didn't name).
+
+**Fallback when the MCP returns nothing:**
+1. If the user did NOT pass `--worktree` / `--project_root` and `launch-orbit` has worktrees registered for this repo, suggest re-running with `--worktree=<slug>` before falling back to the filesystem.
+2. Look for `.launchsecure/beacon-*.ndjson` in cwd, then in up to 2 parent dirs. Use the `Read` tool to inspect the most-recently-modified matching file — do NOT use `grep`, `find`, or `ls` as the primary path.
+3. If files are found at an alternative path, tell the user the path mismatch explicitly: `"MCP scans <root>/.launchsecure/ but the session lives at <found-path>. Reading directly."`
+4. If nothing is found anywhere, stop with: `"No beacon sessions found. Start one with: npx launch-beacon monitor"`.
+
+Capture the failure's `seq`, `kind`, `ts`, and message.
+
+## Pull the context window
+
+Call `mcp__local-launch-beacon__beacon_correlate` with `seq: <failure.seq>`, `before: N`, `after: 0`, plus the same `worktree` / `project_root` args you used on `beacon_failures`. The tool returns event summaries directly — no JSON parsing required.
+
+If a context event's summary is missing detail you need for analysis (truncated stack, missing response body, selector chain), call `mcp__local-launch-beacon__beacon_event` with that event's specific `seq` for the full JSON — and forward the same root args. Only do this when the summary is insufficient — not unconditional.
+
+## Output
+
+Render a **timeline** with the failure visually separated at the bottom:
+
+```
+session: <token>
+window:  N events before failure at seq <seq>
+
+12:34:51  click       button.submit-btn
+12:34:51  fetch       POST 401 /api/sessions (120ms)  FAILED
+12:34:51  fetch       GET 401 /api/me (45ms)  FAILED
+12:34:52  route       /login → /dashboard (pushState)
+...
+
+╴╴╴╴ FAILURE ╴╴╴╴
+12:34:53  error       Cannot read properties of undefined (reading 'orgSlug')
+              at apps/Console.tsx:42:18
+              stack: Console.render
+                     React.renderWithHooks
+                     React.beginWork
+```
+
+Format rules:
+- One line per event, same SUMMARY format as `/kit:beacon-scan`.
+- The failure block at the end gets the message + (truncated) stack frames if present. For fetch/xhr failures, include method + status + url + response body summary.
+- Separator above the failure is the visual cue.
+
+After the timeline, write **one short paragraph** of analysis: what does the chain *look* like? Common patterns:
+- 401s → error referencing user/org → "auth expired or org context missing"
+- click → no observable effect → click again → error → "first click handler crashed silently; second click landed on something else"
+- route change → error → "component on the new route blew up during initial render"
+- repeated 400s on the same endpoint → "request shape mismatch — check the server's Zod schema against the client payload"
+
+Don't dive into a fix — name the suspected proximate cause, suggest one concrete next step (which file to read, which probe to add, which `/kit:beacon-scan <kind>` to drill into).
+
+## Constraints
+
+- **MCP-first.** Use `beacon_failures`, `beacon_correlate`, `beacon_event` — never `grep`, `find`, `ls`, `sed`, `cut`, or `tail` as the primary path.
+- **Alert on fallback.** If the MCP can't answer, say so verbatim before reading the file directly.
+- **Read-only.**
+- **Most recent failure only.** For an earlier one, clear the session (`/kit:beacon-clear`) and reproduce, or use `/kit:beacon-scan error` / `/kit:beacon-scan fetch` to browse.
+- **Plain text.** Same monospace conventions as `/kit:beacon-scan`.

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

@@ -0,0 +1,66 @@
+---
+description: Scan recent events from the active launch-beacon monitor session via the launch-beacon MCP. Defaults to last 50 events across all kinds; pass a kind (`error`, `click`, `fetch`, `route`, `dialog`, `probe`, etc.) to filter, and/or a numeric limit. Read-only.
+---
+
+# /kit:beacon-scan
+
+Recent runtime events captured by a `launch-beacon monitor` session. Use this as the first step when investigating something that just happened in the browser — clicks, failed network calls, errors, route changes, probe() calls, dialog mount/unmount.
+
+Parse `$ARGUMENTS` as space-separated tokens, in any order:
+- A **kind filter**: one of `error`, `unhandledrejection`, `fetch`, `xhr`, `click`, `mousedown`, `route`, `dialog`, `submit`, `probe`. Anything else that doesn't parse as an integer or a known `--flag` is treated as an explicit session token.
+- A **limit**: integer. Default 50. Hard cap 500 (the `beacon_recent.limit` tool ceiling).
+- An explicit **session token** (8-char hex like `8f3c2a91`) — passed straight through as the `session` MCP arg.
+- `--worktree=<slug>` — orbit worktree slug (from `launch-orbit create`). Forwarded to the MCP as the `worktree` arg so a Claude session pinned to the main repo can read sessions captured inside a worktree.
+- `--project_root=<path>` — explicit project root (absolute, or relative to cwd). Forwarded to the MCP as `project_root`. Takes precedence over `--worktree`.
+
+Examples:
+- `/kit:beacon-scan` → last 50 events of any kind from the latest session
+- `/kit:beacon-scan error` → last 50 errors only
+- `/kit:beacon-scan click 20` → last 20 click events
+- `/kit:beacon-scan 100` → last 100 events of any kind
+- `/kit:beacon-scan fetch 50 8f3c2a91` → last 50 fetches from a specific session
+- `/kit:beacon-scan fetch --worktree=beacon_rewrite` → last 50 fetches captured in that worktree
+
+## Scan
+
+Call `mcp__local-launch-beacon__beacon_recent` with `kind: <kind?>`, `limit: <limit>`, `session: <session?>`, plus `worktree: <slug?>` and `project_root: <path?>` if the user supplied them. The tool defaults to the most-recent session and returns one compact summary line per event.
+
+If the response is `{error: "no session found"}` OR an empty events array, **alert the user with the exact MCP error string**, then walk the fallback below — do NOT silently grep.
+
+**Fallback when the MCP returns nothing:**
+1. If the user did NOT pass `--worktree` / `--project_root` and the cwd is the main repo of a project that has worktrees registered with `launch-orbit`, suggest re-running with `--worktree=<slug>` before falling back to the filesystem — that's usually the actual fix and avoids a wrong-directory scan.
+2. Look for `.launchsecure/beacon-*.ndjson` in cwd, then in up to 2 parent dirs. Use the `Read` tool to inspect the most-recently-modified matching file — do NOT use `grep`, `find`, or `ls` as the primary path.
+3. If files are found at an alternative path, tell the user the path mismatch explicitly: `"MCP scans <root>/.launchsecure/ but the session lives at <found-path>. Reading directly."`
+4. If nothing is found anywhere, stop with: `"No beacon sessions found. Start one with: npx launch-beacon monitor"`.
+
+## Output
+
+Group events by **time** (most recent last — chronological matches user intuition for "what happened"). For each event, render one line:
+
+```
+HH:MM:SS  KIND     SUMMARY
+```
+
+Where SUMMARY is a one-liner pulled from the event body:
+- **error / unhandledrejection** → `message` (truncate ≤ 80 chars)
+- **fetch / xhr** → `METHOD status url (durationMs)` — flag `FAILED` if `failed:true`
+- **click / mousedown** → `target.selector` and, when `hitMatchesTarget === false`, also append `(occluded by <hitTarget.selector>)` — that's exactly the diagnostic the user is here for
+- **route** → `from → to (via)`
+- **dialog** → `<action> <selector>` (e.g. `mount dialog#xyz` or `unmount section[role=dialog]`)
+- **submit** → `<form selector> (preventDefault?)`
+- **probe** → `<label>: <truncated JSON>`
+
+If a summary line is missing detail you need (truncated response body, full selector chain, stack frames), call `mcp__local-launch-beacon__beacon_event` with that event's `seq` for the full JSON — and forward the same `worktree` / `project_root` args you used on `beacon_recent`. Only on demand — not unconditional.
+
+After the timeline, if anything looks suspicious (clusters of failed network calls, a click followed by no observable effect, a `hitMatchesTarget:false` event, an unhandled rejection), call it out in **one short paragraph** at the end. Don't analyze every event — only surface the standouts.
+
+If the buffer is empty after filtering, say so: `No events match that filter in <session>.`
+
+## Constraints
+
+- **MCP-first.** Use `beacon_recent` / `beacon_event` — never `grep`, `find`, `ls`, `tail`, `head` as the primary path.
+- **Alert on fallback.** If the MCP can't answer, say so verbatim before reading the file directly.
+- **Read-only.** Never delete, modify, or write to the NDJSON file. Wiping is `/kit:beacon-clear`.
+- **Always use the latest session by default.** Pass an explicit token as the third arg only when the user wants a specific older session.
+- **Plain text output.** Monospace alignment beats markdown tables here.
+- **Don't speculate on root cause.** Surface anomalies; let the user direct the next query (often: `/kit:beacon-pulse` for context around the latest failure).