claude-code-session-manager 0.27.0 → 0.28.0

package/dist/index.html

@@ -7,7 +7,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;0,6..72,700;1,6..72,400&family=Geist:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="./assets/index-DU1pkhIQ.js"></script>
+    <script type="module" crossorigin src="./assets/index-DtQ4LzuV.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/monaco-editor-BW5C4Iv1.js">
     <link rel="stylesheet" crossorigin href="./assets/monaco-editor-BTnBOi8r.css">
     <link rel="stylesheet" crossorigin href="./assets/index-Dwb94Uxm.css">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Local cockpit for the Claude Code CLI — multi-tab terminal, full config surface, scheduler, voice dictation, and live observability.",
   "type": "module",
   "main": "src/main/index.cjs",
@@ -9,6 +9,8 @@
   },
   "files": [
     "bin/",
+    ".claude-plugin/",
+    "plugins/",
     "src/main/",
     "src/preload/",
     "dist/index.html",

package/plugins/session-manager-dev/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "session-manager-dev",
+  "description": "The default end-to-end development skillset for the Claude Code Session Manager: decompose work into scheduler PRDs (/develop, /prd), triage cross-project feedback (/process-feedback, /my-feedback), roll up operational status and optimize the North-Star KPI (/project-status, /optimize-kpi, /local-project-health), gate with review (/requesting-code-review, /security-review), and document how the project works (/explain-to-me). Together with the session-manager scheduler these form a closed develop → queue → track → review → status → improve loop.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Stanislav Georgiev",
+    "url": "https://github.com/StanislavBG"
+  },
+  "homepage": "https://github.com/StanislavBG/claude-code-session-manager",
+  "keywords": [
+    "development",
+    "scheduler",
+    "prd",
+    "feedback",
+    "code-review",
+    "kpi",
+    "session-manager"
+  ]
+}

package/plugins/session-manager-dev/skills/develop/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: develop
+description: >-
+  Lead a software-development task by decomposing a feature/refactor/bugfix prompt into a
+  series of self-contained PRDs queued for the session-manager scheduler, each carrying the
+  engineering standards inline so the headless executor honors them — then track those PRDs
+  to completion, verify them against their acceptance criteria, and report back. Use whenever
+  the user says "/develop", "develop X", "build me X", "implement X", "let's code X", or
+  otherwise starts dev work that should run as scheduled PRDs rather than inline now. This
+  skill is the home for the developer-only guidance (performance, debugging, API-reuse, TDD)
+  that was removed from the always-on global CLAUDE.md. Keywords: develop, build, implement,
+  code, feature, refactor, bugfix, queue dev work, PRDs.
+---
+
+# /develop — prompt → scheduled PRDs → tracked to done
+
+**Role:** `/develop` owns the *pipeline*: it turns a development request into one or more
+self-contained PRDs, queues them, and tracks them to completion. It is the convergence point
+for both entry paths — an interactive human prompt comes straight here; an agent feedback file
+arrives via `/process-feedback`, which evaluates it and then calls this skill. Everything from
+here on is identical regardless of who asked.
+
+**Never** hand-implement the work inline in chat, and never restate rules that live elsewhere:
+single-PRD structure/sizing belongs to `/prd`, the engineering rules belong to `standards.md`.
+Reference them; don't fork them.
+
+## Standards (single source of truth)
+
+The engineering standards (Performance, Debugging, API reuse / single source of truth, TDD,
+and the executor-facing Execution discipline) live in **`standards.md`** beside this file:
+`~/.claude/skills/develop/standards.md`. Read it, hold it while planning, and inline it
+verbatim into every PRD you emit (Phase 1 step 4). Never restate or fork its content — one
+concept, one implementation.
+
+For interactive dev work, also apply the `test-driven-development` and `systematic-debugging`
+skills; the headless PRDs get the distilled core from `standards.md` instead, since they
+can't load skills.
+
+## Phase 1 — Author + queue the PRDs
+
+1. **Clarify scope first.** If the prompt has genuine ambiguity (acceptance criteria, target
+   repo, framework, edge cases), ask 2–4 focused questions as plain text and wait. Don't use
+   the AskUserQuestion tool. Don't guess on decisions that would cost real rework. (When the
+   caller is `/process-feedback`, scope is already established by its evaluation — don't
+   re-ask; build from the brief it hands you.)
+
+2. **Explore the target repo.** Identify the absolute `cwd`, existing patterns/utilities to
+   reuse (per the API-reuse standard — search before writing new code), the test command, and
+   any constraints. Capture exact file paths and signatures; they go straight into the PRDs.
+
+3. **Decompose into a series of SMALL, bounded PRDs.** This is the part `/develop` owns that
+   `/prd` doesn't: split a large ask into multiple PRDs and sequence them. For each PRD's
+   *size, command-bounding, `NN` parallel group, and structure*, follow `~/.claude/skills/prd/SKILL.md`
+   — it is the canonical authority; do not restate its rules here. To pick `NN`, **compute the
+   highest in-use number deterministically — never eyeball or narrow-grep the `ls`** (a
+   narrowed pattern like `'^10[0-9]'` silently misses `110+` and collides):
+   ```bash
+   ls ~/.claude/session-manager/scheduled-plans/prds/ | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
+   ```
+   The last line is the current max. Then: same `NN` as a logically independent sibling that
+   can run in parallel; **next free `NN` = max+1** when this PRD hard-depends on prior work or
+   is unrelated to every existing group. Record each cross-PRD dependency in the dependent
+   PRD's notes.
+
+4. **Emit each PRD** to the canonical path per `/prd`'s structure, then **append `## Engineering
+   standards` and paste the full contents of `standards.md` verbatim.** This is the
+   load-bearing step — it's the only way the standards (incl. Execution discipline) reach the
+   headless run. Honor the `PRD_AUTHORING.md` §10 pre-queue checklist.
+
+5. **Confirm to the user**, per emitted PRD: filename, chosen `NN` + rationale
+   (parallel-with-X / serial-after-Y), `cwd`, and an ETA + token-cost ballpark. Note they can
+   "Run now" in the SchedulePanel or wait for `when-available` polling.
+
+## Phase 2 — Track to completion (reusable tail)
+
+The queued PRDs run headlessly and can take a while. Don't fire-and-forget, and don't block —
+hand off to a recurring check. `/process-feedback` delegates to this exact phase, so it is the
+single definition of "tracked to done" for both entry paths.
+
+6. **Watch the scheduler every ~30 min.** Start a 30-minute monitoring loop (`/loop 30m` over
+   this watch step, or a `ScheduleWakeup` at 1800s if self-pacing) scoped to the PRD ids you
+   emitted. On each tick, read the scheduler's job status (queue + run history under
+   `~/.claude/session-manager/scheduled-plans/`, or the SchedulePanel) and branch:
+   - **Still queued / running, within its window** — leave it; re-check next tick.
+   - **Failed / errored / `needs_review` / timed out / killed by the watchdog or supervisor /
+     overran its estimate badly** — STOP waiting and surface it now: which PRD, the failure
+     signal, the relevant log tail, and the likely cause (a stuck poll-loop or post-AC overrun
+     per `PRD_AUTHORING.md`). Don't silently retry forever. A `rateLimited` exit-1 is the
+     scheduler's benign auto-pause (auto-resumes next window) — keep waiting, don't escalate.
+   - **All PRDs completed successfully** — go to step 7.
+
+7. **Gate: definition of done** (same for both entry paths). Once the code has landed:
+   - **Verify live against each PRD's acceptance criteria** — run the health check, hit the
+     endpoint, show before/after. The headless run asserted its own test command; this is the
+     interactive confirmation it actually does what was asked.
+   - For a **major feature or risky change**, dispatch a review via the
+     `requesting-code-review` skill before calling it done; fix Critical/Important findings.
+   - **Report back**: what landed, PRD/commit refs, verification result, anything left open.
+
+## References (reuse, don't duplicate)
+
+- `~/.claude/skills/prd/SKILL.md` — canonical single-PRD structure, location, filename rules, scope sizing.
+- `~/.claude/session-manager/scheduled-plans/PRD_AUTHORING.md` — the §1–§10 safety rules.
+- `~/.claude/skills/develop/standards.md` — the engineering + execution-discipline rules inlined into every PRD.
+- `test-driven-development`, `systematic-debugging` — interactive dev sessions.
+- `requesting-code-review` — the Phase-2 review gate.
+
+## Notes
+
+- Write PRD files directly, then confirm — don't draft them inline in chat for review first.
+- Don't combine unrelated features into one PRD. One focused, completable unit each.
+- Don't add a `parallelGroup` frontmatter key — the filename `NN-` prefix drives grouping.

package/plugins/session-manager-dev/skills/develop/standards.md

@@ -0,0 +1,67 @@
+# Engineering standards
+
+> Single source of truth for the developer guidance that used to live in the global
+> `~/.claude/CLAUDE.md`. Consumers: the `/develop` skill reads it while planning and
+> inlines it **verbatim** into every PRD it emits (under an `## Engineering standards`
+> heading); the `/prd` command points here for the execution-discipline rules so a
+> directly-authored PRD carries the same block. The headless `claude -p` executor sees no
+> skills and no conversation — inlining this is the only way these rules reach it. Edit
+> here once; every call site updates.
+>
+> The **Execution discipline** section below is the executor-facing core — it is the part
+> that MUST appear in every PRD body. The rest (Performance, Debugging, API reuse, TDD)
+> guides authoring and interactive work.
+
+## Performance
+
+- State the time and space complexity of any non-trivial algorithm in a comment.
+- Flag any nested loop over user-scaled data as a complexity hazard.
+- Prefer O(n) solutions over O(n log n) only when n is provably small or constant.
+- Lay out hot data contiguously and traverse it in memory order.
+- Prefer arrays of structs or structs of arrays based on actual access patterns.
+- Avoid pointer-chasing in inner loops on large datasets.
+
+## Debugging approach
+
+- State an explicit hypothesis before each debugging action.
+- Describe what observation would confirm or refute the hypothesis.
+- If three hypotheses fail, stop and re-examine your assumptions from scratch.
+- When a bug was recently introduced, bisect commits to find the offender.
+- When a bug is in a long pipeline, halve the input or code path until it localizes.
+- Record each bisection step so the path to the root cause is reproducible.
+- Never attempt a fix until you can reproduce the bug on demand.
+- Capture the reproduction as a failing test before changing production code.
+- If the bug cannot be reproduced, instrument the system until it can.
+
+## API reuse and single source of truth
+
+- One concept = one implementation. Before writing code that computes, fetches, formats, or displays a value, search the codebase for an existing implementation and reuse it. Do not write a second or third copy of the same logic.
+- N display sites, ONE source. When the same datum appears in multiple places (a metric shown in several tabs, a value returned by several endpoints), it must flow from a single shared accessor / store / hook / endpoint. Displaying something in 3 places must not mean 3 implementations — it means 1 implementation with 3 call sites.
+- Extend, don't fork. If an existing function/module/API is close but not sufficient, generalize it (add a param, widen the contract) rather than cloning a divergent variant. Prefer composition over duplication.
+- Treat duplication as a latent bug. Copy-pasted logic drifts; divergence between copies is how silent inconsistencies ship (e.g. one site reads a 0–100 percentage as a 0–1 fraction). When you see the same logic in two places, consolidate it on sight and route both through the shared unit.
+- Design for extensibility: stable shared contracts, single ownership, callers depend on the contract — not on a private copy. New surfaces consume the canonical API; they never reimplement it.
+- When reviewing or implementing, explicitly check: "is this value/behaviour already produced elsewhere, and am I reusing that path?" If not, fix the reuse before adding the feature.
+
+## Test-driven development
+
+- Write the failing test first, then the implementation that makes it pass — for every feature and every bugfix.
+- A bugfix starts with a test that reproduces the bug (red), then the fix (green).
+- Do not write production code without a test asserting the behavior it adds.
+- (Interactive sessions: the `test-driven-development` skill has the full red-green-refactor
+  workflow. Headless PRD runs can't load it — the three rules above are the load-bearing core.)
+
+## Execution discipline (headless runs)
+
+Data-driven from 400+ scheduler runs: long hangs (not bad code) are the dominant real failure, and "exited clean but left a red test" is the top verifier downgrade. These rules run at execution time — they are inlined into every PRD because the headless executor reads nothing else.
+
+- **Bound every command.** Wrap every test/build/dev-server/deploy/poll command in a hard timeout: `timeout 300 <typecheck|unit>`, `timeout 120 <one e2e spec>`, `curl --max-time 15`. Never run a bare `playwright test`/`vite`/`pnpm dev`, a full e2e suite, or an endpoint-polling publish — those are the SIGTERM/4h-watchdog tail.
+- **Verify before done.** Run the acceptance test command once before declaring success. If it's red, fix it or `exit 1` with the failure — never end the run on a failing test (that trips the verifier's `transcript_errors` downgrade).
+- **Fail loud, fail fast.** On any step failure, print one diagnostic line and `exit 1`; don't swallow with `|| true` or spin in a silent retry. A `rateLimited` exit-1 is the scheduler's benign auto-pause (auto-resumes next window) — not a failure to engineer around.
+- **Stay in the AC.** Do not add work past the acceptance checklist ("while we're here" generators/fixtures are the post-AC-overrun incident). Body must be clean UTF-8 — no NUL/control bytes.
+- **Negative-assertion checks must exit 0 when clean.** A check that verifies the *absence* of something (a `grep` that should find nothing, "no leftover X", `diff` expecting no change) must return exit 0 on the clean case. A bare `grep` exits **1 on no-match** — so the *success* path surfaces as `is_error=true` and the verifier downgrades a perfect run to `needs_review`. Always invert: `if <detector>; then echo "HALT: <what was found>"; exit 1; fi; echo clean`. Never let the no-match/empty path carry the non-zero exit.
+- **Recover or annotate every error — don't strand a Traceback in the transcript.** The verifier downgrades an otherwise-perfect run to `needs_review` when a `Traceback`/`Error` appears with *no visible recovery within ~10 lines* (the `transcript_errors` heuristic — the single most common false-positive on green deliverables). Two executor habits cause it: (1) **throwaway probes that error** — an inline `python -c` with a quoting/f-string slip, a wrong kwarg, a bad path. When a probe errors, immediately re-run the corrected version *or* print one line `# expected/handled: <why>` right after, so recovery is adjacent. Don't move on leaving a bare error as the last thing in that step. Prefer a small temp `.py` file over a fragile multi-quote `python -c` one-liner (inline f-string errors are the top source of stranded tracebacks). (2) See the timeout rule below.
+- **An *expected* bounded-timeout (exit 124) must be annotated, not bare.** `timeout`-capping a genuinely long task you expect to hit the cap (a full-universe ingest, a long scan) is correct — but a bare `Exit code 124` reads as a failure to the verifier. Wrap it so the cap is a success-with-note: `timeout 120 <cmd> || { rc=$?; [ $rc -eq 124 ] && echo "hit time cap — idempotent/partial, rows persist incrementally; OK" || { echo "HALT: <cmd> failed rc=$rc"; exit 1; }; }`. (Distinguish 124 = expected cap from a real non-zero.) For work that legitimately needs longer than a safe cap, run it in the background and poll a bounded number of times rather than capping the foreground command.
+- **Finish so the verifier auto-clears you.** The scheduler appends a finish protocol that requires you to COMMIT your work and emit `SCHEDULER_VERDICT: PASS` (or `FAIL <reason>` + `exit 1`) as the literal last line. Honor it exactly: a *truthful* PASS plus a commit that landed during the run is what lets the verifier override incidental transcript noise (a grep hit containing "Error", a TDD red-phase run, a debug Traceback) instead of parking the job in `needs_review` for a human. A job that exits 0 with **uncommitted** changes, or with no PASS sentinel, is the #1 cause of needless `needs_review`. Never print PASS on a red gate — a lying PASS turns the verifier into a silent-failure shipper.
+- **Don't leak expected-error text into tool output.** The verifier pattern-matches transcript content for `Traceback`/`FAIL`/`Error:`. When a step is *expected* to error (a TDD red-phase test, an availability/existence probe, a "should raise" assertion), don't let the raw exception land verbatim — capture it and surface a clean token instead: `if python -c '…' 2>/dev/null; then echo PROBE_OK; else echo PROBE_ABSENT; fi`, or pipe the noisy run through a matcher that prints only `RED (expected)` / `GREEN`. When you retry a transient failure, re-run the **same command with the same description** — the verifier's self-recovery detector pairs a failed call with a later identical-description call that succeeds and clears it.
+- **End green: run the acceptance/test gate LAST, and let nothing error after it.** The post-run verifier scans the transcript and downgrades to `needs_review` on error markers — and weighs the *final* portion of the run most heavily (a tool error in the last ~20% trips it even if everything actually passed). So order the run so the last command is the green AC gate: do any intentionally-failing step (e.g. a TDD red test, an expected-nonzero probe) **early**, never after the gate. If you must demonstrate a failure late, capture it so it doesn't surface as a raw `is_error`/`Traceback` (`… 2>&1 | tail` inside a conditional, or assert on the captured text) rather than letting it hit the transcript bare.
+- **The verdict sentinel is your authoritative "I passed" signal — emit it truthfully.** The scheduler appends a FINISH PROTOCOL that ends by printing `SCHEDULER_VERDICT: PASS` once the AC gate is green and the commit has landed (or `SCHEDULER_VERDICT: FAIL <reason>` + `exit 1` otherwise). The verifier treats `PASS` + a commit that landed during the run as **authoritative** and overrides incidental transcript markers — so a *deliberately reproduced* red test (systematic-debugging) or a grep result containing the word "Error" will **not** false-trip `needs_review`, as long as the run genuinely ends green and committed. Never print `PASS` when the gate is red — that's the one thing that turns a safety net into a silent-failure machine.

package/plugins/session-manager-dev/skills/explain-to-me/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: explain-to-me
+description: >-
+  Build and maintain HUMAN_LEARN/ — a human-readable, visually-rich HTML
+  knowledge base at the repo root that explains how this project actually works.
+  Deep-probes the codebase for a given topic/component (real file:line refs,
+  real constants, real on-disk state — never invented), then writes or updates a
+  clean, self-contained HTML — one combined component page (HUMAN_LEARN/index.html)
+  plus a separate skill-chain map (HUMAN_LEARN/SKILL_MAP.html) for the local-dev
+  workflow — with advanced CSS, flow diagrams, sticky nav, collapsible tables. Use
+  whenever the user says "/explain-to-me X", "explain X to me", "explain how X
+  works", "document X for me", "add X to HUMAN_LEARN", "make me a human-readable
+  page for X", or "update the skill map". Keywords: explain, explain-to-me,
+  human-learn, HUMAN_LEARN, skill map, document, one-pager, how does X work, visual
+  explainer, knowledge base.
+model: opus
+---
+
+# explain-to-me
+
+Turn a question about this codebase ("explain how the scheduler works") into a
+**clean, visually-rich HTML one-pager** in `HUMAN_LEARN/` at the repo root, and
+keep that folder's index coherent as it grows. The output is for a *human*
+catching up on the project — not for the model. It is the human-facing complement
+to the Memory tab (which is Claude's own terse recall store).
+
+The bar: **clean, explanatory, visually rich, self-contained** (opens directly in
+a browser — no build, no external network deps). Every claim grounded in the
+actual code.
+
+**Document the CURRENT state, present-tense — never the journey.** A reader wants
+to know *what the project is and how it works right now*, not how it got there.
+This is a snapshot of the system as it stands today, not a changelog. So:
+
+- **No PRD numbers, ticket ids, or commit refs** ("added in PRD 66", "schema
+  bumped to v3"). State the field/behavior as it simply *is* — `panels.ticker_metrics`
+  *carries* an `as_of` freshness field; don't say when or why it was added.
+- **No evolution or "was X → now Y"** ("grew from 2 to 5 tools", "migrated off the
+  local cache", "reborn processed"). Describe the 5 tools that exist; the prior
+  count is irrelevant to someone reading today.
+- **No incident/history narrative** ("the 06-10 churn incident", "the outage that
+  shaped this", "the bug we fixed"). If a guard exists, describe *what it guards*
+  in the present, not the failure that motivated it.
+- **No migration tiers / in-flight roadmap / "gated" future work.** Document what
+  is true now; a thing that's being retired is just "internal, not on the public
+  surface" today.
+
+Present-tense **design rationale is fine and useful** — *why the system is shaped
+this way as it stands* (a tradeoff, a complexity bound, a boundary rule). That is
+not history. The line is: explain the *standing* reason, never the *chronology*.
+If you can't state it in the present tense without a date or a PRD, cut it.
+
+## Where things live
+
+- Repo root: `git rev-parse --show-toplevel` (fall back to cwd if not a git repo).
+- Knowledge base: `<root>/HUMAN_LEARN/`. Create it if missing.
+- **One combined page** — `HUMAN_LEARN/index.html`. Every component explainer is a
+  `<section>` in this single file, under a sticky section-nav, ordered so the page
+  reads top-to-bottom as one narrative. A new topic becomes a **new `<section>`**,
+  never a new file. One navigable page that logically follows itself beats a folder
+  of thin pages; do not re-introduce per-topic `.html` files.
+- **The Skill Map** — `HUMAN_LEARN/SKILL_MAP.html`, a **separate, dedicated** page
+  (NOT a section of index.html) that visualizes the *local-development skill chain*:
+  the two intakes (interactive human prompt; agent feedback via `/process-feedback`)
+  converging on `/develop`, which reads `/prd` + `standards.md`, queues onto the
+  scheduler, and gates with review/verify — plus `/my-feedback` outbound. It is the
+  "how I build on this project" companion to index.html's "how this project works."
+  index.html links to it from the nav; it links back.
+
+## Workflow
+
+1. **Locate & survey.** Find the repo root + `HUMAN_LEARN/`. If `index.html`
+   exists, read it to see what's already documented — you are *maintaining* a
+   knowledge base, not starting fresh. If the topic already has a page/section,
+   you are updating it, not duplicating it.
+2. **Deep-probe the topic.** Read the real code. Gather exact `file:line`
+   references, real constant names + values, and real on-disk state where it
+   matters (run `ls`/`cat`/`jq` to ground claims in what actually exists). For a
+   broad topic, fan out parallel `Explore` subagents over the relevant
+   subsystems and collect the conclusions. **Never invent** a path, constant, or
+   behavior — if you can't verify it, don't write it.
+3. **Decide placement.** A component/subsystem topic → a new (or edited) `<section>`
+   in `index.html`, slotted into the narrative order. The dev skill chain → it's in
+   `SKILL_MAP.html`. Re-explaining an existing topic → edit that section in place,
+   refresh the "generated" date. Never spin up a new per-topic `.html`.
+4. **Write the HTML.** Use the design system below — both pages share the same tokens
+   and components so they read as one product. A page must be self-contained (inline
+   `<style>`, no external fonts/scripts/CDNs). Lead with what the thing *is* and *when
+   it runs*, then the step-by-step flow with `file:line` tags, then the knobs (a
+   collapsible constants table), then the present-tense design rationale ("why
+   it's shaped this way" as it *stands* — a standing tradeoff/bound, never a dated
+   history or a PRD).
+5. **Wire the navigation.** Add/refresh the topic's pill in `index.html`'s sticky
+   section-nav (and the footer's source-file list). Keep the nav and `SKILL_MAP.html`
+   cross-links intact: index.html's nav has a "⛓ Skill Map ↗" link, SKILL_MAP.html's
+   nav links back to "📖 HUMAN_LEARN".
+6. **Maintain the Skill Map.** When the local-dev skills/commands change — a new skill
+   in `~/.claude/skills/`, a changed Role/Never contract, a re-routed step in the
+   chain — refresh `SKILL_MAP.html` (its chain diagram + the role-contract table +
+   the two walkthroughs) so it stays a faithful map of the actual files on disk.
+7. **Tell the user the path** to open (`HUMAN_LEARN/index.html` or
+   `HUMAN_LEARN/SKILL_MAP.html`, optionally with a `#anchor`). Do not commit unless asked.
+
+## Grounding rules (non-negotiable)
+
+- Every behavioral claim cites a real `file:line`. Spot-check by reading the
+  cited line before writing it.
+- Constants show their real values from the source, not approximations.
+- "On disk" claims are verified with a real command first.
+- If two sources disagree (e.g. a stale CLAUDE.md vs the code), trust the code
+  and note the discrepancy.
+
+## Maintenance
+
+- Idempotent: re-running for the same topic updates that `<section>` (and its nav
+  pill) in place — it never appends a duplicate or spawns a new file.
+- Never clobber unrelated sections. Edit the one section the topic owns.
+- Refresh the footer "generated <date>" and the source-file list on each update.
+- HUMAN_LEARN holds exactly two pages: `index.html` (components, one combined page)
+  and `SKILL_MAP.html` (the dev skill chain). They cross-link via their navs. Don't
+  add a third page.
+
+## Design system
+
+Reuse these tokens and patterns verbatim so every page looks like one product.
+A complete, copy-ready exemplar lives at `assets/style-reference.html` next to
+this file — **read it and mirror its structure/CSS** for any new page. The
+essentials:
+
+**Palette + base** (inline `<style>`, dark theme):
+
+```css
+:root{
+  --bg:#0d1117; --panel:#161b22; --panel2:#1c2330; --line:#2d333b;
+  --fg:#e6edf3; --dim:#9da7b3; --faint:#6e7681;
+  --blue:#60a5fa; --green:#34d399; --amber:#fbbf24; --violet:#a78bfa;
+  --pink:#f472b6; --red:#f87171; --cyan:#22d3ee;
+  --mono:ui-monospace,'SF Mono',Menlo,Consolas,monospace;
+}
+*{box-sizing:border-box;margin:0;padding:0}
+html{scroll-behavior:smooth}
+body{background:var(--bg);color:var(--fg);
+  font:15px/1.6 ui-sans-serif,system-ui,sans-serif;padding:0 20px 80px}
+.wrap{max-width:980px;margin:0 auto}
+code{font-family:var(--mono);font-size:12.5px;background:var(--panel2);
+  border:1px solid var(--line);border-radius:4px;padding:1px 5px}
+pre{font-family:var(--mono);font-size:12px;background:var(--panel);
+  border:1px solid var(--line);border-radius:8px;padding:14px 16px;overflow-x:auto}
+```
+
+**Component patterns** (use the ones the topic needs — don't force all of them):
+
+- **`.loc` chip** — a cyan monospace pill for every `file:line` reference. This is
+  the signature element: claims are traceable.
+  `font:11px var(--mono);color:var(--cyan);background:rgba(34,211,238,.08);
+  border:1px solid rgba(34,211,238,.25);border-radius:99px;padding:1px 9px`
+- **`.proc` badge** — colored uppercase pill marking *where* a step runs
+  (e.g. shell hook / main process / subprocess / renderer / disk / network). One
+  color per layer; show a legend once near the top.
+- **Sticky section nav** — for multi-section pages: a `position:sticky;top:0`
+  bar with `backdrop-filter:blur(6px)` and pill links to each `#section`.
+- **Flow diagram** — a horizontal row of `.box` cards joined by `→` arrows for a
+  pipeline, OR a numbered vertical "stage" stack for a deeper step-by-step. Each
+  box: a title, a one-line what, and a `.where` `file:line`. Color the top border
+  by the layer it runs in.
+- **Stat strip** — a row of big-number cards for the load-bearing figures
+  (counts, caps, sizes) pulled from real state.
+- **Callout** — left-border tinted block for "the key insight" / "the caveat"
+  (`.ok` green, `.bad` red, default amber).
+- **Collapsible constants table** — `<details><summary>` wrapping a table of
+  `constant · value · file:line · what it bounds`. Keeps the page scannable.
+- **Two-column rationale** — a `grid-template-columns:1fr 1fr` "why it's shaped
+  this way" section, collapsing to one column under `@media(max-width:760px)`.
+- **Footer** — muted, lists the exact source files the page was distilled from +
+  "generated <date>".
+
+**Advanced techniques to deploy** (tasteful, not gratuitous): CSS grid layouts,
+`position:sticky` nav, `scroll-behavior:smooth` + anchor links, `backdrop-filter`,
+`<details>`/`<summary>` for progressive disclosure, responsive `@media`
+breakpoints, CSS-only flow diagrams (borders + flex, no images), subtle
+`transition`/`:hover` affordances on cards. **No** external fonts, scripts, CDNs,
+or build step — every page is one self-contained `.html` file.
+
+## What good looks like
+
+Lead with the outcome (what the thing *is*, when it runs). Make the flow the
+centerpiece. Tag everything with `file:line`. Surface the real numbers. Give the
+present-tense design rationale where it helps (the *standing* tradeoff or
+constraint that makes the shape make sense) — but **no chronology**: no PRD
+numbers, no "was X → now Y", no incident/migration history, no roadmap. A reader
+should learn what the project *is* today, not how it got here. Keep prose tight
+and in complete sentences — visually rich, not noisy.

package/plugins/session-manager-dev/skills/explain-to-me/assets/style-reference.html

@@ -0,0 +1,163 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>explain-to-me · style reference (copy this)</title>
+<!--
+  STYLE REFERENCE for the /explain-to-me skill.
+  This is a complete, self-contained exemplar page. When writing a HUMAN_LEARN
+  page, mirror this structure and CSS. Replace the placeholder "Widget Pipeline"
+  content with the real, file:line-grounded explanation of the user's topic.
+  Every component below is optional — use the ones the topic needs.
+-->
+<style>
+  :root{
+    --bg:#0d1117; --panel:#161b22; --panel2:#1c2330; --line:#2d333b;
+    --fg:#e6edf3; --dim:#9da7b3; --faint:#6e7681;
+    --blue:#60a5fa; --green:#34d399; --amber:#fbbf24; --violet:#a78bfa;
+    --pink:#f472b6; --red:#f87171; --cyan:#22d3ee;
+    --mono:ui-monospace,'SF Mono',Menlo,Consolas,monospace;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  html{scroll-behavior:smooth}
+  body{background:var(--bg);color:var(--fg);font:15px/1.6 ui-sans-serif,system-ui,sans-serif;padding:0 20px 80px}
+  .wrap{max-width:980px;margin:0 auto}
+  a{color:var(--blue);text-decoration:none} a:hover{text-decoration:underline}
+  .crumb{font-size:12px;color:var(--faint);margin:24px 0 14px}
+  h1{font-size:28px;letter-spacing:-.5px;margin-top:26px}
+  .sub{color:var(--dim);margin:8px 0 6px;max-width:780px}
+  h2{font-size:22px;margin:44px 0 12px;padding-top:18px;border-top:1px solid var(--line)}
+  h3{font-size:16px;margin:24px 0 8px}
+  p{margin:8px 0;color:var(--dim)} p strong,li strong{color:var(--fg)}
+  ul.tight{margin:6px 0 6px 20px;color:var(--dim);font-size:13.5px} ul.tight li{margin:4px 0}
+  code{font-family:var(--mono);font-size:12.5px;background:var(--panel2);border:1px solid var(--line);border-radius:4px;padding:1px 5px;color:var(--fg);white-space:nowrap}
+  pre{font-family:var(--mono);font-size:12px;background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:14px 16px;overflow-x:auto;margin:10px 0;line-height:1.55}
+  pre code{background:none;border:none;padding:0;white-space:pre}
+
+  /* signature element: every file:line reference is a traceable chip */
+  .loc{font-family:var(--mono);font-size:11px;color:var(--cyan);background:rgba(34,211,238,.08);border:1px solid rgba(34,211,238,.25);border-radius:99px;padding:1px 9px;white-space:nowrap}
+
+  /* layer badges — one color per place a step runs */
+  .proc{font-size:11px;text-transform:uppercase;letter-spacing:.08em;padding:1px 8px;border-radius:99px;border:1px solid}
+  .proc.hook{color:var(--amber);border-color:rgba(251,191,36,.4);background:rgba(251,191,36,.07)}
+  .proc.main{color:var(--green);border-color:rgba(52,211,153,.4);background:rgba(52,211,153,.07)}
+  .proc.sub{color:var(--violet);border-color:rgba(167,139,250,.4);background:rgba(167,139,250,.07)}
+  .proc.rend{color:var(--pink);border-color:rgba(244,114,182,.4);background:rgba(244,114,182,.07)}
+  .proc.disk{color:var(--cyan);border-color:rgba(34,211,238,.4);background:rgba(34,211,238,.07)}
+  .legend{display:flex;flex-wrap:wrap;gap:14px;margin:10px 0;font-size:12px;color:var(--dim)}
+
+  /* sticky in-page nav */
+  nav.toc{position:sticky;top:0;z-index:10;background:rgba(13,17,23,.92);backdrop-filter:blur(6px);border-bottom:1px solid var(--line);margin:0 -20px;padding:10px 20px}
+  nav.toc .row{max-width:980px;margin:0 auto;display:flex;gap:8px;flex-wrap:wrap}
+  nav.toc a{font-size:13px;padding:4px 14px;border-radius:99px;border:1px solid var(--line);color:var(--dim)}
+  nav.toc a:hover{color:var(--fg);border-color:var(--faint);text-decoration:none}
+
+  /* stat strip */
+  .statline{display:flex;gap:18px;flex-wrap:wrap;margin:16px 0}
+  .stat{background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:10px 18px}
+  .stat .v{font-size:22px;font-weight:700} .stat .k{font-size:11px;text-transform:uppercase;letter-spacing:.07em;color:var(--faint)}
+
+  /* horizontal flow diagram */
+  .flow{display:flex;flex-wrap:wrap;gap:8px;align-items:stretch;margin:16px 0}
+  .flow .box{flex:1 1 150px;min-width:150px;background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:10px 12px}
+  .flow .box .bt{font-weight:700;font-size:13px;margin-bottom:2px}
+  .flow .box .bd{font-size:12px;color:var(--dim)}
+  .flow .box .where{font-family:var(--mono);font-size:10px;color:var(--cyan);margin-top:6px}
+  .flow .arrow{align-self:center;color:var(--faint);font-size:18px;flex:0 0 auto}
+  .box.b-amber{border-top:3px solid var(--amber)} .box.b-green{border-top:3px solid var(--green)}
+  .box.b-violet{border-top:3px solid var(--violet)} .box.b-cyan{border-top:3px solid var(--cyan)}
+  .box.b-pink{border-top:3px solid var(--pink)}
+
+  /* callouts */
+  .callout{border-left:3px solid var(--amber);background:rgba(251,191,36,.06);border-radius:0 8px 8px 0;padding:12px 16px;margin:14px 0;font-size:14px;color:var(--dim)}
+  .callout.ok{border-color:var(--green);background:rgba(52,211,153,.06)}
+  .callout.bad{border-color:var(--red);background:rgba(248,113,113,.06)}
+  .callout strong{color:var(--fg)}
+
+  /* tables + collapsible knobs */
+  table{border-collapse:collapse;width:100%;margin:12px 0;font-size:13px}
+  th,td{text-align:left;padding:6px 11px;border:1px solid var(--line)}
+  th{background:var(--panel2);font-size:11.5px;text-transform:uppercase;letter-spacing:.05em;color:var(--dim)}
+  td{background:var(--panel);color:var(--dim)} td code{white-space:nowrap}
+  details.consts summary{cursor:pointer;font-size:13px;color:var(--blue);margin:10px 0}
+
+  /* two-column rationale */
+  .twocol{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+  @media(max-width:760px){.twocol{grid-template-columns:1fr}.flow .box{flex-basis:100%}}
+
+  footer{margin-top:60px;padding-top:16px;border-top:1px solid var(--line);font-size:12px;color:var(--faint)}
+</style>
+</head>
+<body>
+
+<nav class="toc"><div class="row">
+  <a href="index.html">📖 HOME</a>
+  <a href="#flow">Flow</a>
+  <a href="#knobs">Knobs</a>
+  <a href="#why">Why</a>
+</div></nav>
+
+<div class="wrap">
+  <div class="crumb"><a href="index.html">HUMAN_LEARN</a> / Widget Pipeline</div>
+  <h1>⚙️ Widget Pipeline — how a request becomes a widget</h1>
+  <p class="sub">
+    One-sentence lead: what this is and when it runs. (Replace this whole page with the
+    real, <code>file:line</code>-grounded explanation of the user's topic — this file is only the
+    visual template.)
+  </p>
+  <div class="legend">
+    <span><span class="proc hook">trigger</span> what kicks it off</span>
+    <span><span class="proc main">core</span> main logic</span>
+    <span><span class="proc sub">worker</span> spawned work</span>
+    <span><span class="proc disk">store</span> persistence</span>
+  </div>
+
+  <div class="statline">
+    <div class="stat"><div class="v">5</div><div class="k">stages</div></div>
+    <div class="stat"><div class="v">20</div><div class="k">batch cap</div></div>
+    <div class="stat"><div class="v">8&nbsp;MB</div><div class="k">read window</div></div>
+  </div>
+
+  <h2 id="flow">The flow, step by step</h2>
+  <div class="flow">
+    <div class="box b-amber"><div class="bt">1 · Trigger</div><div class="bd">what starts it</div><div class="where">file.ext:NN</div></div>
+    <div class="arrow">→</div>
+    <div class="box b-green"><div class="bt">2 · Read</div><div class="bd">bounded input read</div><div class="where">file.ext:NN</div></div>
+    <div class="arrow">→</div>
+    <div class="box b-green"><div class="bt">3 · Transform</div><div class="bd">the core step</div><div class="where">file.ext:NN</div></div>
+    <div class="arrow">→</div>
+    <div class="box b-sub b-violet"><div class="bt">4 · Work</div><div class="bd">spawned subprocess</div><div class="where">file.ext:NN</div></div>
+    <div class="arrow">→</div>
+    <div class="box b-cyan"><div class="bt">5 · Persist</div><div class="bd">atomic write</div><div class="where">file.ext:NN</div></div>
+  </div>
+
+  <h3>3 · Transform <span class="proc main">core</span> <span class="loc">file.ext:120-148</span></h3>
+  <p>Prose explaining the step, with inline <code>constants</code> and a <span class="loc">file.ext:NN</span> for
+  each claim. Show a real snippet when it clarifies:</p>
+  <pre><code>doThing(input, { cap: 20, windowBytes: 8 * 1024 * 1024 })</code></pre>
+
+  <div class="callout ok"><strong>Key insight.</strong> The one thing a reader must take away —
+  e.g. why the design is correct, or the invariant it preserves.</div>
+
+  <h2 id="knobs">The knobs</h2>
+  <details class="consts" open><summary>All constants (real names + values)</summary>
+  <table>
+    <tr><th>Constant</th><th>Value</th><th>Where</th><th>Bounds</th></tr>
+    <tr><td><code>BATCH</code></td><td>20</td><td><span class="loc">file.ext:50</span></td><td>items per unit of work</td></tr>
+    <tr><td><code>MAX_BYTES</code></td><td>8 MB</td><td><span class="loc">file.ext:52</span></td><td>read window per run</td></tr>
+  </table>
+  </details>
+
+  <h2 id="why">Why it's shaped this way</h2>
+  <div class="twocol">
+    <div><h3>Constraint A</h3><p>The real reason — an incident, a platform limit, a cost guard.</p></div>
+    <div><h3>Constraint B</h3><p>Another forcing function that explains a non-obvious choice.</p></div>
+  </div>
+
+  <footer>
+    HUMAN_LEARN · &lt;project&gt; · generated &lt;date&gt; from <code>file.ext</code> + live on-disk state.
+  </footer>
+</div>
+</body>
+</html>