@launchsecure/launch-kit 0.0.27 → 0.0.28

package/scaffolds/ls-marketplace/plugins/ls/commands/activate-beacon.md

@@ -0,0 +1,216 @@
+---
+description: Wire @launchsecure/launch-kit/beacon into this app — mounts the <launch-kit-beacon> Web Component in the root layout and scaffolds /api/feedback forwarding to LaunchSecure. Detects the framework, asks scope/endpoint/trigger decisions, then writes a real PR-shaped change.
+---
+
+# Activate launch-kit-beacon
+
+Integrate the in-app feedback widget into the current project. Beacon is a vanilla Web Component shipped via the `@launchsecure/launch-kit/beacon` subpath export. It captures a written description, severity (bug/idea/UX/a11y), a viewport screenshot with auto-numbered element pins, and runtime errors (`window.error` + `unhandledrejection`). Reports POST to a feedback endpoint that forwards into LaunchSecure as feedback comments in the Comm Hub.
+
+This command does the integration as a normal dev cycle — read the layout, propose the diff, install deps, verify in the browser. It is NOT a one-shot script.
+
+## Preflight
+
+1. Confirm `.launch-secure.cred.config` exists at the repo root. If missing, stop and tell the user to run `npx launch-kit init` first — without the cred file the scaffolded `/api/feedback` route has no upstream credentials.
+2. Read `package.json` to detect framework:
+   - **Next.js App Router** — `next` in deps AND `app/` or `src/app/` directory present.
+   - **Next.js Pages Router** — `next` in deps AND `pages/` directory (no `app/`).
+   - **Vite + React** — `vite` + `react` in deps; no server route available (Vite is client-only — feedback POSTs will need a user-supplied endpoint).
+   - **Other** — Astro, SvelteKit, Nuxt, plain HTML, Express, etc. Print the integration snippet and stop; the user wires it themselves.
+3. Grep the source for `launch-kit-beacon` to check if beacon is already mounted. If found, ask the user whether to update the existing mount or abort.
+4. Use the `launch-chart` MCP (`detect_project_stack`, `read_graph` with `type: "page"`) to confirm the root layout file path before editing.
+
+## Decisions
+
+Ask the user three questions before touching files:
+
+1. **Mount scope**
+   - (a) Whole app — mount in the root layout, shown on every route
+   - (b) Auth-gated only — mount in an authenticated layout group (e.g. `(authenticated)/layout.tsx`)
+   - (c) Specific route group — user picks the layout file
+
+2. **Feedback endpoint**
+   - (a) Scaffold `/api/feedback` forwarding to LaunchSecure (recommended). Reads `.launch-secure.cred.config` server-side, POSTs to `<serverUrl>/api/feedback` with the PAT in the `Authorization` header. Secrets stay server-side.
+   - (b) Skip — user will wire their own endpoint and set `endpoint=` attribute manually.
+
+3. **Trigger**
+   - (a) Default floating button, position `bottom-right`
+   - (b) User provides a custom trigger via `slot="trigger"`; widget renders no default button
+
+Echo the chosen answers back before writing.
+
+## Implementation — Next.js App Router (v1 target)
+
+### 1. Add dependency
+
+Check if `@launchsecure/launch-kit` is already in `dependencies` in `package.json`. If not, add it (pinned to a caret range of the current major). Then run install with the detected package manager (`pnpm install` / `npm install` / `yarn install` / `bun install`). Detect the PM from `packageManager` field first, then lockfile presence (pnpm-lock.yaml > yarn.lock > bun.lock > package-lock.json).
+
+### 2. Mount the widget
+
+Web Components cannot SSR. The beacon module calls `customElements.define` at import time, which throws in a Node SSR environment. Mount via a small Client Component, not directly in the Server Component layout.
+
+Create `src/app/_components/BeaconMount.tsx` (or `app/_components/BeaconMount.tsx` if the project uses `app/` at the repo root):
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+
+export function BeaconMount() {
+  useEffect(() => {
+    void import('@launchsecure/launch-kit/beacon');
+  }, []);
+  return (
+    <launch-kit-beacon
+      endpoint="/api/feedback"
+      position="bottom-right"
+    />
+  );
+}
+```
+
+Then read the target layout file (root layout for scope (a), authenticated layout for (b), or user-specified layout for (c)) and add the mount near the end of `<body>`:
+
+```tsx
+import { BeaconMount } from '@/app/_components/BeaconMount';
+// ... inside the layout's return, just before </body>:
+<BeaconMount />
+```
+
+If the user picked trigger option (b) (custom trigger via slot), set `position="hidden"` on the element and pass children through:
+
+```tsx
+<launch-kit-beacon endpoint="/api/feedback" position="hidden">
+  <button slot="trigger">Send feedback</button>
+</launch-kit-beacon>
+```
+
+### 3. Add TypeScript declaration
+
+Create `src/types/launch-kit-beacon.d.ts` (or `types/launch-kit-beacon.d.ts` at repo root if the project has no `src/`):
+
+```ts
+import type { DetailedHTMLProps, HTMLAttributes } from 'react';
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'launch-kit-beacon': DetailedHTMLProps<
+        HTMLAttributes<HTMLElement> & {
+          endpoint?: string;
+          position?: 'bottom-right' | 'bottom-left' | 'hidden';
+          theme?: 'auto' | 'light' | 'dark';
+          severities?: string;
+        },
+        HTMLElement
+      >;
+    }
+  }
+}
+
+export {};
+```
+
+Confirm `tsconfig.json` includes the types directory (most Next.js setups already cover `src/**/*.d.ts` via the default `"include": ["**/*.ts", "**/*.tsx"]`). If not, add the file's path to `include`.
+
+### 4. Scaffold /api/feedback (if user chose endpoint option (a))
+
+Create `src/app/api/feedback/route.ts` (or `app/api/feedback/route.ts`):
+
+```ts
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { NextRequest } from 'next/server';
+
+interface Profile {
+  pat: string;
+  orgSlug: string;
+  projectSlug: string;
+  serverUrl: string;
+}
+
+interface CredConfig extends Partial<Profile> {
+  active?: string;
+  profiles?: Record<string, Profile>;
+}
+
+function readCred(): Profile {
+  // Resolved relative to the working directory of the Next.js server, which
+  // is the repo root in both `next dev` and `next start`. For production
+  // deploys (Vercel, Docker, etc.) where the cred file is not present,
+  // switch to env vars: LS_PAT, LS_ORG_SLUG, LS_PROJECT_SLUG, LS_SERVER_URL.
+  //
+  // Handles both shapes: nested multi-profile (written by `launch-course`)
+  // and legacy flat (written by older `launch-kit init` runs).
+  const p = join(process.cwd(), '.launch-secure.cred.config');
+  const raw = JSON.parse(readFileSync(p, 'utf-8')) as CredConfig;
+  const block = raw.profiles && raw.active ? raw.profiles[raw.active] : raw;
+  if (!block?.pat || !block.orgSlug || !block.projectSlug || !block.serverUrl) {
+    throw new Error('.launch-secure.cred.config is missing required fields');
+  }
+  return { pat: block.pat, orgSlug: block.orgSlug, projectSlug: block.projectSlug, serverUrl: block.serverUrl };
+}
+
+export async function POST(req: NextRequest) {
+  const cred = readCred();
+  const body = await req.text();
+  const upstream = await fetch(`${cred.serverUrl}/api/feedback`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${cred.pat}`,
+      'X-Org-Slug': cred.orgSlug,
+      'X-Project-Slug': cred.projectSlug,
+    },
+    body,
+  });
+  return new Response(upstream.body, {
+    status: upstream.status,
+    headers: { 'Content-Type': upstream.headers.get('Content-Type') ?? 'application/json' },
+  });
+}
+```
+
+Tell the user explicitly: this works for local dev. For production, replace `readCred()` with `process.env.LS_PAT` / `LS_ORG_SLUG` / `LS_PROJECT_SLUG` / `LS_SERVER_URL` and set those env vars in their deployment platform.
+
+### 5. Verify
+
+After all edits:
+1. Run install with the detected PM.
+2. Run `pnpm dev` (or detected dev command from `package.json` scripts).
+3. Open the app in the browser. Confirm the floating beacon button is visible bottom-right (or that the custom slot trigger renders, for option (b)).
+4. Click it, fill in a description, pick severity, capture a screenshot, submit.
+5. Confirm via the `launch-secure` MCP: call `communication_read` and look for a new feedback comment landing in the project's Comm Hub.
+6. Report the verification result to the user (which steps passed, anything that didn't).
+
+## Implementation — Next.js Pages Router
+
+Same as App Router but adjust paths:
+- Mount in `pages/_app.tsx` instead of `app/layout.tsx`. `_app.tsx` is already a Client Component, so the dynamic `import` workaround in step 2 is unnecessary — import `@launchsecure/launch-kit/beacon` at the top of the file directly.
+- Feedback endpoint becomes `pages/api/feedback.ts` with a default-exported handler matching the Pages API signature (`req: NextApiRequest, res: NextApiResponse`).
+- TypeScript declaration is identical.
+
+## Implementation — Vite + React
+
+- Mount: add `import '@launchsecure/launch-kit/beacon';` to `src/main.tsx` (or whatever entry the Vite config points at), and add `<launch-kit-beacon endpoint="...">` inside the root `<App>` render. No SSR concerns — Vite is client-only.
+- No server route — Vite does not provide one. Print the beacon snippet and tell the user they need either (a) to stand up their own backend with a forwarding handler matching the Next.js scaffold, or (b) to wait until LS exposes a public per-project ingest URL.
+- TypeScript declaration is identical.
+
+## Implementation — other frameworks
+
+For Astro, SvelteKit, Nuxt, Express, plain HTML, etc.: do NOT attempt to edit application source automatically. Print the integration snippet and the API forwarding handler skeleton (translated to Node `http`/Express), and tell the user the two changes they need to make in their stack. Frameworks vary too much to mechanize this correctly.
+
+## Idempotency
+
+Re-running `/ls:activate-beacon`:
+- If `BeaconMount.tsx` exists, leave it alone unless the user explicitly asks to regenerate.
+- If `<launch-kit-beacon>` is already mounted in the layout, do NOT add a duplicate. Offer to update attributes (endpoint, position) or migrate trigger mode.
+- If `app/api/feedback/route.ts` exists, do NOT overwrite. Diff against the scaffold template and ask whether to merge.
+- If `@launchsecure/launch-kit` is already a dependency, skip the install step (but still run install if other files changed).
+
+## Notes for the assistant
+
+- Use the `launch-chart` MCP for file discovery instead of grep/glob (per project CLAUDE.md). `read_graph` with `type: "page"` finds layout files; `grep_nodes` with a `launch-kit-beacon` pattern finds existing mounts.
+- Use the `launch-secure` MCP `communication_read` to verify a test feedback landed in the Comm Hub after the user submits.
+- Show the diff before applying edits. The user reviews and approves like any PR.
+- This is the user's application code. Default to the smallest possible edit — do not "improve" surrounding code, restyle the layout, or refactor unrelated files.

package/scaffolds/ls-marketplace/plugins/ls/commands/beacon-array.md

@@ -0,0 +1,92 @@
+---
+description: Show the array of launch-beacon monitor sessions in `.launchsecure/` — 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.
+---
+
+# /ls:beacon-array
+
+Liveness + inventory across every `launch-beacon monitor` session this repo has recorded — one row per beacon in the array.
+
+`$ARGUMENTS` may be `full` for an expanded report. Empty → terse one-line-per-session summary.
+
+## Preflight
+
+List the NDJSON files. If none, say so plainly:
+
+```bash
+ls -t .launchsecure/beacon-*.ndjson 2>/dev/null || { echo "No beacon sessions found in .launchsecure/. Start one with: npx launch-beacon monitor"; exit 0; }
+```
+
+If the listing is empty (the command above succeeded but produced no output because `2>/dev/null` swallowed the error and no files matched), check explicitly:
+
+```bash
+SESSIONS=$(ls -t .launchsecure/beacon-*.ndjson 2>/dev/null)
+test -n "$SESSIONS" || { echo "No beacon sessions found in .launchsecure/. Start one with: npx launch-beacon monitor"; exit 0; }
+```
+
+## Per-session facts to collect
+
+For each session file (newest first), gather:
+- **token** — slice between `beacon-` and `.ndjson` in the filename
+- **events** — `wc -l < <file>`
+- **last_ts** — parse the last JSON line's `.ts` field (epoch ms). Use a one-liner like:
+  ```bash
+  tail -n 1 "$F" | sed -n 's/.*"ts":\([0-9]*\).*/\1/p'
+  ```
+- **last_kind** — same trick on `.kind` from the last line
+- **mtime** — `stat -f "%m" "$F"` on macOS or `stat -c "%Y" "$F"` on Linux. Use whichever your shell supports; fall back to `ls -lt` parse if neither.
+- **size** — file size in bytes (`stat` again; or `wc -c < "$F"`)
+
+Use the mtime to compute **age** ("just now", "2m ago", "1h ago"). Do the arithmetic yourself (current epoch minus mtime); don't shell out for time formatting.
+
+## Liveness heuristic
+
+Mark a session as **active** if its mtime is within the last 5 seconds — that's the maximum interval the receiver flushes batches. Otherwise **idle**. Sessions older than 30 minutes are **stale** (the receiver enforces a 30-min cap, so anything older is from a previous monitor run).
+
+## 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) — last event "kind (age)" — status word.
+- Summary line: total count + how many active.
+- Plain text, monospace alignment.
+
+## Full output (`/ls:beacon-array full`)
+
+Same per-session block as default, but expand each into a block with extra fields:
+
+```
+● 8f3c2a91 — ACTIVE
+   file:        .launchsecure/beacon-8f3c2a91.ndjson
+   size:        42.1 KB
+   events:      247
+   started:     2026-05-21T07:12:33Z (8m ago)
+   last event:  2026-05-21T07:20:51Z (just now)
+   last kind:   click
+   kinds:       click 142, fetch 71, route 12, error 3, dialog 9, probe 10
+
+  a1b2c3d4 — idle
+   file:        .launchsecure/beacon-a1b2c3d4.ndjson
+   ...
+```
+
+`kinds:` is a histogram from `grep -oE '"kind":"[a-z]+"' <file> | sort | uniq -c | sort -rn`. Format as `kind1 N1, kind2 N2, …` newest-first by count.
+
+`started:` = first line's `.ts`; `last event:` = last line's `.ts`.
+
+End with the same summary line as default.
+
+## Constraints
+
+- **Read-only.** No deletion, no rotation, no auto-cleanup.
+- **Fast.** Default view should be sub-second even with many session files. Don't full-parse JSON — line counts + first/last line sed is enough.
+- **Plain text.** No markdown tables, no fenced blocks in the actual output.
+- **Don't suggest cleanup.** That's `/ls:beacon-clear`'s job. Stale sessions are informational, not an error.

package/scaffolds/ls-marketplace/plugins/ls/commands/beacon-clear.md

@@ -0,0 +1,68 @@
+---
+description: Wipe launch-beacon monitor session NDJSON files. Default clears only the latest session (so you can start a clean repro); pass `all` to remove every `.launchsecure/beacon-*.ndjson`. Always shows what will be deleted and asks for confirmation. Destructive.
+---
+
+# /ls: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`:
+- empty → clear the most recent session file only
+- `all` → clear every `.launchsecure/beacon-*.ndjson`
+- a specific token or filename → clear that one file (must match a real path)
+
+## Preflight
+
+List candidate files. If none, say so and stop:
+
+```bash
+SESSIONS=$(ls -t .launchsecure/beacon-*.ndjson 2>/dev/null)
+test -n "$SESSIONS" || { echo "No beacon sessions found in .launchsecure/. Nothing to clear."; exit 0; }
+```
+
+Decide the **target set** based on `$ARGUMENTS`:
+- empty → first line of `$SESSIONS` (the newest)
+- `all`  → all lines of `$SESSIONS`
+- otherwise → resolve to a single path (try `.launchsecure/beacon-<arg>.ndjson` first, then the literal arg). If it doesn't exist or isn't inside `.launchsecure/`, refuse with a clear message.
+
+## Refusal rule
+
+Refuse with a clear message if:
+- the target set is empty
+- any target path resolves outside `.launchsecure/` (defence against `..` injection from `$ARGUMENTS`)
+- the active monitor session is being written *right now* (mtime within the last 5 seconds) — print a one-line warning and ask the user to stop the monitor first, e.g.:
+  ```
+  ⚠ .launchsecure/beacon-8f3c2a91.ndjson was written 2s ago — looks active.
+    Stop the receiver (Ctrl+C in the launch-beacon monitor terminal) and re-run /ls:beacon-clear.
+  ```
+  The user can still force by passing the token explicitly as the argument — but never silently nuke an actively-written file.
+
+## Confirmation
+
+Print what's about to be deleted and ask before doing it.
+
+```
+About to delete 1 file:
+  .launchsecure/beacon-a1b2c3d4.ndjson   89 events, 12m ago
+
+Confirm? (y/N)
+```
+
+For `all`, list every file with its size + age. Don't truncate the list — the user should see all of it.
+
+Wait for explicit `y`/`yes`. Anything else → abort with `Cancelled. No files were deleted.`
+
+## Delete
+
+`rm` each target. After deletion, print a one-line summary:
+
+```
+✓ deleted 1 file (89 events freed).
+```
+
+## Constraints
+
+- **Destructive — always confirm.** Even if `$ARGUMENTS` is `all`, ask first.
+- **Scope-locked to `.launchsecure/`.** Reject anything outside that directory, even if the user passes an absolute path. We never delete files we didn't write.
+- **No undo.** NDJSON is local-only; we don't ship recall integration for it (recall is for source files). Be explicit in the confirmation message.
+- **Don't stop the monitor server.** This command only clears 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/ls/commands/beacon-pulse.md

@@ -0,0 +1,80 @@
+---
+description: Show the most recent error 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.
+---
+
+# /ls:beacon-pulse
+
+The "what happened just before this error" 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.
+
+Parse `$ARGUMENTS` as one optional integer — the count of preceding events to include. Default 10. Cap at 100.
+
+## Preflight
+
+Same as `/ls:beacon-scan` — find the latest NDJSON; if none, stop:
+
+```bash
+LATEST=$(ls -t .launchsecure/beacon-*.ndjson 2>/dev/null | head -1)
+test -n "$LATEST" || { echo "No beacon sessions found. Start one with: npx launch-beacon monitor"; exit 0; }
+```
+
+## Locate the most recent error
+
+Errors are events with `"kind":"error"` or `"kind":"unhandledrejection"`. Find the line number of the LAST such line in the file:
+
+```bash
+ERR_LINE=$(grep -nE '"kind":"(error|unhandledrejection)"' "$LATEST" | tail -1 | cut -d: -f1)
+test -n "$ERR_LINE" || { echo "No errors in the current session. Use /ls:beacon-scan to browse all events."; exit 0; }
+```
+
+## Pull the window
+
+`N` is the user-supplied count (default 10). Read the file lines from `max(1, ERR_LINE-N)` through `ERR_LINE`:
+
+```bash
+N="${1:-10}"
+START=$(( ERR_LINE - N ))
+[ "$START" -lt 1 ] && START=1
+sed -n "${START},${ERR_LINE}p" "$LATEST"
+```
+
+That's your input. The error itself is the last line; everything before is context.
+
+## Output
+
+Render a **timeline** with the error visually separated at the bottom:
+
+```
+session: .launchsecure/beacon-<token>.ndjson
+window:  10 events before error at line 247
+
+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)
+...
+
+╴╴╴╴ ERROR ╴╴╴╴
+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 `/ls:beacon-scan`.
+- The error block at the end gets the message + (truncated) stack frames if present.
+- Separator above the error 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"
+
+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 `/ls:beacon-scan <kind>` to drill into).
+
+## Constraints
+
+- **Read-only.**
+- **Most recent error only.** If the user wants an earlier one, they can clear the session (`/ls:beacon-clear`) and reproduce, or grep manually.
+- **Plain text.** Same monospace conventions as `/ls:beacon-scan`.

package/scaffolds/ls-marketplace/plugins/ls/commands/beacon-scan.md

@@ -0,0 +1,62 @@
+---
+description: Scan recent events from the active launch-beacon monitor session. 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. Reads `.launchsecure/beacon-*.ndjson` — the file written by `launch-beacon monitor`. Read-only.
+---
+
+# /ls: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 up to two tokens (space-separated):
+- A **kind filter**: one of `error`, `unhandledrejection`, `fetch`, `xhr`, `click`, `mousedown`, `route`, `dialog`, `probe`. Anything else is treated as a limit.
+- A **limit**: integer. Default 50.
+
+Examples:
+- `/ls:beacon-scan` → last 50 events of any kind
+- `/ls:beacon-scan error` → last 50 errors only
+- `/ls:beacon-scan click 20` → last 20 click events
+- `/ls:beacon-scan 100` → last 100 events of any kind
+
+## Preflight
+
+Find the most recent NDJSON file via Bash. If none exist, say so plainly and stop — there's nothing to scan.
+
+```bash
+LATEST=$(ls -t .launchsecure/beacon-*.ndjson 2>/dev/null | head -1)
+test -n "$LATEST" || { echo "No beacon sessions found in .launchsecure/. Start one with: npx launch-beacon monitor"; exit 0; }
+echo "session: $LATEST"
+```
+
+## Scan
+
+If no kind filter, `tail -n <limit> "$LATEST"`.
+
+If a kind filter is set, `grep '"kind":"<kind>"' "$LATEST" | tail -n <limit>`. The events are NDJSON, one per line — `grep` over the literal `"kind":"X"` substring is safe because the `kind` field is always the first or near-first key serialised by the beacon client.
+
+Capture the raw JSON lines as the input to your analysis.
+
+## Output
+
+Group events visually by **time** (most recent last — chronological order matches the user's 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]`)
+- **probe** → `<label>: <truncated JSON>`
+
+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
+
+- **Read-only.** Never delete, modify, or write to the NDJSON file. Wiping is `/ls:beacon-clear`.
+- **Always use the latest session by default.** If the user wants a specific session, they'll pass it as a third token — accept any of `<token>`, `<filename>`, or absolute path, and resolve to a valid `.launchsecure/beacon-*.ndjson` path before scanning. Reject with a clear error if it doesn't exist.
+- **Plain text output.** Monospace alignment beats markdown tables here. The user is reading this fast during a debug loop.
+- **Don't speculate on root cause.** Surface anomalies; let the user direct the next query (often: `/ls:beacon-pulse` for context around the latest error).

package/scaffolds/ls-marketplace/plugins/ls/commands/show-mcp-status.md

@@ -0,0 +1,109 @@
+---
+description: Show the health of launch-kit's daemon-style MCPs (today just launch-recall). Default output is a terse one-line summary per daemon; pass `full` for expanded details — PID, pidfile, last snapshot, debounce, shadow repo size, recent activity. Read-only; never mutates state.
+---
+
+# /ls:show-mcp-status
+
+Reports the liveness and recent activity of launch-kit's long-running MCP daemons. The recall watcher is the only daemon today; this command is structured so additional daemons can be added without changing its interface.
+
+Read $ARGUMENTS to decide output verbosity:
+- empty (`/ls:show-mcp-status`) → terse one-liner per daemon. Goal: fits in one or two visual lines.
+- `full` (`/ls:show-mcp-status full`) → expanded report per daemon. Goal: enough detail to diagnose health problems.
+
+## Preflight
+
+1. Verify the launch-recall MCP is wired by checking whether `mcp__launch-recall__recall_status` (or `mcp__local-launch-recall__recall_status` for dev repos) is callable. If neither is available, say so plainly: "launch-recall MCP not wired in this project — nothing to report" and stop.
+2. Pick whichever recall MCP is available. Prefer the project-level published one (`mcp__launch-recall__*`) unless only the local dev one is wired.
+
+## Daemons
+
+Today: **launch-recall** (the shadow-git file watcher).
+
+Structure your output so adding more daemons later is a copy-paste — one section per daemon, same shape.
+
+## Default output (no arguments)
+
+Call `mcp__launch-recall__recall_status`. Format as ONE LINE per daemon, then a single summary line. Example:
+
+```
+recall    ✓ alive  pid 12456  last snap 2m ago
+
+All daemons healthy.
+```
+
+Or if dead:
+
+```
+recall    ✗ dead   pidfile missing/stale
+
+1 daemon down. Run /ls:show-mcp-status full for details, or restart the watcher (kill any stale pid, then either start a new Claude Code session — the SessionStart hook respawns it — or run `node packages/cli/dist/server/recall-entry.js watch` from this repo).
+```
+
+Rules for the default view:
+- One line per daemon — name, glyph, status word, key metric.
+- `✓` (green) for alive, `✗` (red) for dead.
+- "X ago" for timestamps — relative time, easier to scan than ISO.
+- Summary line on a fresh line at the end. If anything is wrong, include a one-sentence recovery hint.
+- No JSON, no PID files paths, no debug info — that's for `full`.
+
+## Full output (`/ls:show-mcp-status full`)
+
+For each daemon, call BOTH `recall_status` AND `recall_report`. Combine into a per-daemon block:
+
+```
+recall — launch-recall watcher (shadow-git backup)
+
+  Status:        ✓ alive
+  PID:           12456
+  Watch tree:    /Users/prajyot/Documents/Work/AutomateWithUs/launchsecure-v2
+  Shadow repo:   /Users/prajyot/Documents/Work/AutomateWithUs/launchsecure-v2/.recall/repo.git
+
+  Last snapshot: 2026-05-21T12:05:45+05:30 (2m ago)
+  Total snaps:   1,247
+  Shadow size:   1.4 MB
+  Debounce:      3000ms
+  Retention:     keepLast 5000, maxAgeDays 30
+
+  Recent activity (last 5 snaps):
+    a1b2c3d  2m ago     snap 2026-05-21T06:35:45Z
+    9f8e7d6  14m ago    snap 2026-05-21T06:21:42Z
+    2557799  53m ago    snap 2026-05-21T05:52:35Z
+    8349edb  17h ago    snap 2026-05-20T13:36:39Z
+    e5a05cf  17h ago    snap 2026-05-20T13:32:05Z
+
+All daemons healthy.
+```
+
+If a daemon is dead, the block should still appear but with status `✗ dead` and as many fields as can be derived from the on-disk shadow repo + pidfile. Include a concrete recovery command at the end of the block (the same SessionStart restart path from the default view, plus the manual command for impatient users).
+
+Rules for the full view:
+- Two-column field labels — visually aligned, easier to skim.
+- Times: ISO timestamp + relative ("2m ago") in parens.
+- Sizes: human-readable (KB/MB), not bytes.
+- Last 5 snapshots only — newer first.
+- One blank line between daemon blocks (for when there are more than one).
+- Summary line at the end, same as the default view.
+
+## Health classification
+
+Use these rules to decide alive vs dead vs degraded:
+
+- **alive**: `recall_status.running === true` AND `lastSnapshotAt` is within the last 6 hours (heuristic — for an active repo, snaps happen every few minutes; 6h of silence suggests the watcher is wedged or no files have changed, both worth surfacing).
+- **dead**: `recall_status.running === false` OR `recall_status` errors out.
+- **degraded** (still print as alive but note it): `running === true` BUT `lastSnapshotAt` is older than 6h. Add a single inline note `(no activity in 6h — possibly idle or wedged)`.
+
+Don't over-warn — if a repo has genuinely been idle (e.g. you opened it for the first time today after a week), a 6h+ gap is normal. The note is informational, not an error.
+
+## Constraints
+
+- **Read-only.** This command never mutates state, never restarts watchers, never modifies config. Recovery is a recommendation in the output, not an automatic action.
+- **Fast.** Default view should be sub-second. The MCP tools are cheap; don't add scrubbing or heavy formatting.
+- **Plain text.** No markdown headers, no fenced blocks in the actual output — Claude Code renders them but the human eye scans monospace plain text fastest.
+- **Output what the user asked for.** If they ran the default, don't dump the full report "just in case." If they ran `full`, don't abbreviate.
+
+## Notes for the assistant
+
+- Use the wired `launch-recall` MCP tools — do not shell out to `node packages/cli/dist/server/recall-entry.js status` even though it works. Going through MCP makes this command portable across projects that have launch-kit init'd via npx vs dev-build.
+- When listing recent snaps, use the `recentSnapshots` array from `recall_report`. It's already sorted newest-first; just truncate.
+- For "X ago" formatting, do the math yourself. Don't fetch any time service.
+- If you find yourself wanting to add features beyond status display (restart the watcher, prune snaps, etc.) — stop. Those belong in separate `/ls:*` commands. This one is a status pane.