claude-code-session-manager 0.111.0 → 0.113.0

package/plugins/session-manager-dev/skills/blog-for-project-feature/7-review/SKILL.md

@@ -1,54 +0,0 @@
----
-name: blog-for-project-feature:review
-description: Step 7 of blog-for-project-feature — check the composed HTML against feature.config.yaml's gate list before reporting it ready. Loops back to :compose for content issues, :capture for screenshot gaps, or :illustrate for a mislabeled companion image; never ships on a failed gate.
----
-
-# blog-for-project-feature:review
-
-## Input
-Path to the composed HTML (or html+folder) + output mode + size, from `:compose`.
-
-## Steps
-
-Check every item in `feature.config.yaml`'s `gates` list against the actual file:
-
-1. Open it (or inspect its markup directly) and confirm every image reference resolves — for
-   base64-embedded images this means the data URI is present and non-empty; for the folder mode,
-   confirm each referenced file actually exists on disk.
-2. Confirm zero placeholder/mockup images slipped through — cross-check every `kind: screenshot`
-   image against `:capture`'s reported real captures; anything not in that list is a violation.
-   If a companion illustration is present, confirm it's placed only in the Feature Description
-   header (never inside the Click-Through Demo) and is visually distinguishable from a real
-   screenshot (no fake window chrome/UI text) — if it could pass as a captured screen, that's a
-   violation too.
-3. Confirm all three required sections are present and non-empty (or explicitly gap-noted per
-   `:compose` step 5, which is an acceptable non-empty state). The companion illustration is
-   optional — its absence is never a gate failure.
-4. Confirm the section order matches `feature.config.yaml`'s `content.sections_required` —
-   Click-Through Demo leads the page (above the fold, before the prose sections), each visible
-   step showing its real image on top and the caption directly below it.
-5. Confirm the demo is genuinely click-through — the next/prev or tab controls exist and their
-   JS actually switches the visible step (not just a cosmetic active-class flip with all steps
-   rendered stacked underneath).
-6. Confirm no external network calls (grep for `http://`/`https://` in `<script src>`,
-   `<link href>`, `fetch(`, `@import` — should be none).
-7. Confirm the size ceiling was respected for the mode chosen.
-8. Spot-check 2-3 sentences in the Mission/Feature sections against `:research`'s notes for
-   traceability — flag anything that reads like invented marketing language.
-
-## On failure
-
-- **Content/structure issue** (sections, theme, controls, external calls, size) → loop back to
-  `:compose` with the specific gate that failed.
-- **Screenshot issue** (missing/broken image, a step that needs re-capturing) → loop back to
-  `:capture` for that step specifically, then re-run `:compose` for just the affected step.
-- **Illustration issue** (looks like a mockup/screenshot, placed in the wrong section) → loop
-  back to `:illustrate` for one more attempt, or drop it entirely and re-run `:compose` without it.
-- Never mark the page ready with a known-failing gate "to save time" — a shorter honest page
-  beats a complete one that fails its own checklist.
-
-## Output
-
-On all-pass: report the final path, output mode, size, and step count to the user. State clearly
-that publishing/uploading/deploying happens **only if explicitly asked next** — this step's job
-ends at "ready," not "shipped."

package/plugins/session-manager-dev/skills/blog-for-project-feature/SKILL.md

@@ -1,144 +0,0 @@
----
-name: blog-for-project-feature
-description: Produce a self-contained, interactive HTML "feature showcase" for one project + one feature — Project Mission & Description, Feature Description (with an optional generated companion illustration), and a Click-Through Demo built from REAL screenshots (never mockups) — one aspect revealed at a time. Output is a single portable HTML file uploadable anywhere (no server, no build step). Distinct from blog-from-git (which drafts narrative bilko.run changelog posts from git history) — this is an evergreen, per-feature product page, not a dated post. Orchestrates 8 nested sub-skills (blog-for-project-feature:select, :research, :storyboard, :capture, :draft-copy, :illustrate, :compose, :review) so each step is independently invokable and inspectable. Use for "make a feature page for X", "showcase this feature", "/blog-for-project-feature", "interactive demo of X", or turning a shipped feature in Session Manager / Social Signal Builder (or any project) into something you can hand someone a link to.
----
-
-# blog-for-project-feature (orchestrator)
-
-Project-agnostic. Runs against whatever project the current working directory (or a named
-project path) points to — built first for **Session Manager** and **Social Signal Builder**,
-but nothing here is hardcoded to either.
-
-**Not `blog-from-git`.** That skill drafts a dated, narrative bilko.run post from git activity
-("here's what shipped this week"). This skill produces an **evergreen, single-feature product
-page** — no date, no changelog framing, not tied to a publishing cadence. One project, one
-feature, three things: what the project is for, what this feature does, and a real click-through
-demo of it working. The two skills never share output or ledger state.
-
-**`feature.config.yaml` in this folder is the grounding authority** for output conventions
-(where the HTML lands, image size/compression limits, single-file-vs-folder default, theme
-tokens). Read it first, before any sub-skill file. If prose here ever disagrees with the config,
-the config wins.
-
-## Pipeline DAG
-
-```
-project (+ optional feature name)
-              │
-              ▼
-┌───────────────────────────────┐
-│ 0. blog-for-project-feature:select │──▶ one confirmed project + one confirmed feature
-└───────────────────────────────┘
-              │
-              ▼
-┌───────────────────────────────┐
-│ 1. :research                       │──▶ mission, feature description, key files/entry points
-└───────────────────────────────┘
-              │
-              ▼
-┌───────────────────────────────┐
-│ 2. :storyboard                     │──▶ ordered demo steps (action, expected screen, caption)
-└───────────────────────────────┘
-              │
-              ▼
-┌───────────────────────────────┐
-│ 3. :capture                        │──▶ real screenshots per step (+ storyboard corrections)
-└───────────────────────────────┘        │ no real screenshot obtainable for a step
-              │ all steps captured        ▼
-              ▼                    STOP — report which step blocked, don't fabricate
-┌───────────────────────────────┐
-│ 4. :draft-copy                     │──▶ FINAL mission/feature text + one-sentence "essence" line
-└───────────────────────────────┘
-              │
-              ▼
-┌───────────────────────────────┐
-│ 5. :illustrate                     │──▶ one companion illustration from the essence line
-└───────────────────────────────┘        (or a clean "omitted" note — never blocks the pipeline)
-              │
-              ▼
-┌───────────────────────────────┐
-│ 6. :compose                        │──▶ one self-contained interactive HTML file
-└───────────────────────────────┘
-              │
-              ▼
-┌───────────────────────────────┐
-│ 7. :review                         │──── fails a check ────┐
-└───────────────────────────────┘                            │
-              │ passes                                        │
-              ▼                                                │
-     report path, wait for explicit                            │
-     "publish/upload" instruction          loop back to :compose / :capture / :illustrate
-```
-
-| Step | Input | Output | On failure |
-|---|---|---|---|
-| 0. `:select` | project (cwd or named) + optional feature hint | one confirmed project + one confirmed feature name + why it's demo-worthy | **STOP** — report if no clear feature can be confirmed (don't guess) |
-| 1. `:research` | confirmed project + feature | mission/description (project-level), feature description, key files, how it actually works | n/a — always produces notes, flags gaps explicitly rather than inventing claims |
-| 2. `:storyboard` | mission + feature notes | ordered list of `{step, action, expected_screen, capture_scope, caption}`, 5-10 steps, a deliberate mix of full-page and component-scoped shots | n/a — storyboard is a draft, `:capture` is allowed to correct it |
-| 3. `:capture` | storyboard | one real screenshot file per step + any corrected captions | **STOP** on that step — report what's missing; never substitute a placeholder/mockup image |
-| 4. `:draft-copy` | research notes + captured captions | final Mission & Feature Description prose + one-sentence essence line | n/a — always produces final text, gaps stay explicit |
-| 5. `:illustrate` | the essence line (text must exist first) | one companion illustration, tagged distinct from screenshots — or an explicit omission note | never blocks — skips cleanly if no image generator is configured, or after one off-brief retry |
-| 6. `:compose` | final copy + captured steps + optional illustration | one self-contained HTML file (or html+images folder per config) | loop back to `:capture` if a required image is missing, else fix and retry |
-| 7. `:review` | the composed HTML | pass/fail against the gate below | loop back to `:compose` (content), `:capture` (screenshot), or `:illustrate` (mislabeled companion image) — never ship on a failed gate |
-
-## Golden rule: screenshots are real or the step doesn't exist
-
-This skill exists specifically because "feature demo" content is worthless if the images are
-invented, stale, or from the wrong build. `:capture` uses `mcp__playwright__*` (or the project's
-own screenshot tooling if `run`/a project skill already drives it — check for one first) against
-a running instance of the actual project. If a step can't be captured for real (app won't start,
-feature is behind auth you don't have, flow requires data that doesn't exist locally), **that
-step is dropped and reported, not faked.** A shorter, honest demo beats a complete, fabricated one.
-
-## Output
-
-Default: one self-contained `.html` file (inline CSS/JS, base64-embedded images) written to
-`docs/feature-showcase/<project-slug>-<feature-slug>.html` inside **`~/Projects/Bilko`** —
-never inside the showcased project's own repo, even when the feature being showcased belongs
-to a different project entirely. Bilko is the author/publisher of every showcase (same as
-`blog-from-git`'s posts), is guaranteed to be locally writable across sessions, and these pages
-are destined to eventually post to bilko.run — so output collects in one place from the start.
-See `feature.config.yaml` for the exact path convention, size ceiling, and the single-file vs.
-folder fallback (used when embedded images would blow past the size ceiling). This is what
-"uploadable anywhere" means: no server, no relative asset paths, no build step — open the file
-or drop it on any static host and it works.
-
-**Only push, deploy, or upload when explicitly asked.** Report the local path and a one-line
-description of what the page shows, and wait — same convention as `blog-from-git`'s seed gate
-and `issue-address`'s "only push when asked" rule.
-
-## Why nested skills instead of one inline pass
-
-Same reasoning as `issue-address` and `pr-review-sweep`: each phase is a real, independently
-invokable `SKILL.md` so progress is visible step by step ("storyboard produced 5 steps, capture
-got 4 real screenshots, 1 dropped") instead of one opaque generation pass, and a single phase
-(e.g. swapping the screenshot tool, changing the HTML theme) can be edited without touching the
-others. If a step is still doing too much once this ships, decompose it further the same way
-`issue-address:select` was (nested sub-DAG) — continuously, wherever one file covers too much to
-inspect as one unit.
-
-## Folder map
-
-```
-blog-for-project-feature/
-  feature.config.yaml ← output path convention, size ceiling, theme tokens — read first
-  SKILL.md             ← this file: pipeline, DAG, output contract
-  0-select/SKILL.md
-  1-research/SKILL.md
-  2-storyboard/SKILL.md
-  3-capture/SKILL.md
-  4-draft-copy/SKILL.md
-  5-illustrate/SKILL.md
-  6-compose/SKILL.md
-  7-review/SKILL.md
-```
-
-## What this skill is not
-
-- Not `blog-from-git` — no dated post, no rotation ledger, no git-diff scan. This is
-  feature-scoped and evergreen; that skill is time-scoped and narrative.
-- Not a marketing copy generator — every claim in `:research`'s output must trace to real code,
-  docs, or a live screenshot, same evidentiary bar as `blog-from-git`'s `ground.md`.
-- Not a full site generator — one feature, one page, per run. A project with N features worth
-  showcasing gets N runs (and, if wanted later, a separate index/landing skill — not built yet,
-  don't invent one inline).

package/plugins/session-manager-dev/skills/blog-for-project-feature/feature.config.yaml

@@ -1,90 +0,0 @@
-# Grounding authority for blog-for-project-feature. Read this before any sub-skill file.
-# If prose in a SKILL.md ever disagrees with this file, this file wins.
-
-output:
-  # Path is relative to ~/Projects/Bilko (the Bilko repo) — ALWAYS, regardless of which
-  # project the showcased feature lives in. Bilko is the author/publisher of every showcase
-  # (same reason blog-from-git's posts live in Bilko, not in the project they're about) and
-  # these pages are destined to eventually be posted on bilko.run — Bilko is the one repo
-  # guaranteed to be locally writable across every session this skill runs in, and keeping
-  # output there means all showcases accumulate in one place instead of scattering across
-  # sibling repos. Never write the HTML into the target project's own repo.
-  base_repo: "~/Projects/Bilko"
-  path_template: "docs/feature-showcase/{project-slug}-{feature-slug}.html"
-  project_slug_rule: "kebab-case, the showcased project's own repo/registry slug (e.g. session-manager, signal-builder) — always prefixed so multi-project output never collides"
-  feature_slug_rule: "kebab-case, derived from the confirmed feature name in :select"
-  # Prefer one self-contained file. Only fall back to a folder when the size ceiling
-  # below would be exceeded by inlining images.
-  default_mode: single_file          # single_file | folder
-  folder_fallback_layout:
-    html: "docs/feature-showcase/{project-slug}-{feature-slug}/index.html"
-    images: "docs/feature-showcase/{project-slug}-{feature-slug}/screenshots/"
-  single_file_size_ceiling_mb: 8       # switch to folder_fallback_layout above this
-  never_upload_or_deploy_without_explicit_ask: true
-
-images:
-  format: png
-  max_width_px: 1600                  # downscale before embedding; demo clarity, not pixel-perfect
-  compression: "reasonable lossy ok for PNG->WebP if it keeps text legible; never so lossy captions become unreadable"
-  source_of_truth: "mcp__playwright__browser_take_screenshot against a real running instance"
-  placeholder_or_mockup_images: forbidden   # a dropped step beats a fabricated one
-  capture_scope: "full_page | component, chosen per step in :storyboard and executed in :capture.
-    Full-page screenshots are not always the clearest way to show a feature — a control or state
-    change is often clearer cropped to just that component. Default to component-scoped shots for
-    mechanism/detail steps; reserve full_page for orientation (where the feature lives) and
-    outcome (the result landing back in the real product) steps. See :storyboard's composition
-    recipe for the authoritative mix."
-
-illustration:
-  # The ONE companion image, generated by :illustrate — a distinct image class from the
-  # click-through screenshots above. Optional: omitted cleanly if no generator is configured.
-  runs_after: draft-copy               # never generate from anything but finalized copy
-  generator: "project-local generator if the target project has one, else Gemini
-    (gemini-2.5-flash-image via google-genai — same provider/pattern as Burrow's
-    app/shared/image_gen.py) using GEMINI_API_KEY / GOOGLE_API_KEY from the environment"
-  count: 1
-  placement: "Feature Description section header only — never inside the Click-Through Demo"
-  format: png
-  max_width_px: 1200
-  style: "conceptual/editorial illustration — mood/palette should follow the project's own
-    theme tokens above if it has brand colors, otherwise a clean flat/geometric style"
-  must_not_resemble: "a UI mockup, screenshot, or contain invented interface text/window chrome
-    — must be visually distinguishable from a real captured screen at a glance"
-  max_regeneration_attempts: 1
-  on_no_generator_available: "skip silently, no page-visible note, report to the operator only"
-
-content:
-  sections_required:
-    # Order matters: this IS the on-page order, top to bottom.
-    - "Click-Through Demo"              # LEADS the page — the storyboard steps, one aspect
-                                         # revealed at a time; screenshot on top, caption below
-    - "Project Mission & Description"   # 2-4 sentences, from :research, project-level not feature-level
-    - "Feature Description"             # what it does, why it matters, 1-2 short paragraphs
-  demo_interaction: "one-step-at-a-time reveal (next/prev controls or numbered tabs) — never a single long scroll dump of every screenshot at once. Each step: real image on top, caption directly below it."
-  demo_step_count: "5-10 steps (a mix of full_page and component-scoped captures — see :storyboard's composition recipe), not a flat full-page-per-step dump"
-  tone: "same plain, non-salesy, show-don't-tell bar as blog-from-git/voice.md bot-tell blocklist — no 'excited to share', no grand-implication filler"
-  caption_rule: "every screenshot has a one-sentence caption naming what changed on screen, not what the code does internally"
-
-theme:
-  # Minimal neutral tokens so every showcase looks consistent without importing a design system.
-  # Swap these per-project only if the project has its own documented brand tokens.
-  font_stack: "system-ui, -apple-system, 'Segoe UI', sans-serif"
-  bg: "#0b0d10"
-  surface: "#15181d"
-  text: "#e8eaed"
-  text_muted: "#9aa0a6"
-  accent: "#5b9dff"
-  radius_px: 10
-  max_width_px: 900
-
-gates:
-  # Checked in step 7 (:review). All must pass before reporting the page ready.
-  - "every image referenced actually loads (no broken src, no 404 in a local file:// open)"
-  - "zero placeholder/mockup images — every screenshot traces to a real :capture run"
-  - "if present, the companion illustration sits only in the Feature Description header and is
-    visually distinguishable from a real screenshot (no UI chrome/invented interface text)"
-  - "all three required sections present and non-empty (illustration is optional, never gates)"
-  - "demo is click-through (has working next/prev or tab controls), not a flat scroll"
-  - "file opens correctly via file:// with no console errors (network calls, external CDN fonts/JS forbidden — must be fully offline-capable)"
-  - "single_file_size_ceiling_mb respected, or folder fallback used instead"
-  - "no invented claims — every sentence in Mission/Feature sections traces to :research notes"

package/plugins/session-manager-dev/skills/discover-features/SKILL.md

@@ -1,95 +0,0 @@
----
-name: discover-features
-description: >-
-  Propose and prototype NEW features for the current project. Reads the project's issues, PRs,
-  `main`, and md/docs to learn its objectives, then runs THREE independent discovery sessions
-  (each may also web-search for ideas) that every one proposes 5 high-level feature ideas best
-  fitting the project's goals — 15 total. Synthesises and ranks them, picks the top 3, and runs a
-  high-quality `/develop` build for each. Delivers a deployed URL per feature plus a validation
-  checklist so the human can try them — and NEVER opens a PR or a GitHub issue from a proposed
-  feature (the human validates first, then decides). Use when the user says "/discover-features",
-  "propose features", "discover feature opportunities", "what should we build next", "prototype
-  some new features for me to try". Keywords: discover, propose, feature, opportunity, ideation,
-  prototype, what's next, roadmap.
----
-
-# /discover-features — propose → prototype → hand over URLs (no PRs)
-
-**Role:** the *generative* counterpart to `/find-opportunity`. `/find-opportunity` triages the
-*existing* backlog to pick the next issue to resolve; `/discover-features` *invents* net-new
-features the backlog doesn't contain yet, prototypes the best ones, and hands the human running
-URLs to validate. It is for "what should we build next?", not "which open issue next?".
-
-**Hard rules (do not violate):**
-- **Never open a PR or a GitHub issue** from a proposed feature. The deliverable is a *running,
-  validatable prototype on a branch* + a URL + a validation checklist — the human decides what
-  (if anything) becomes a PR. (See the `solve-dont-open-issues` principle.)
-- **No fabricated data.** Prototypes run on the project's real data layer / real queries. If a
-  feature needs data that doesn't exist, it shows an honest empty state — never seeded fakes.
-- **Don't touch `main`.** Build on a fresh branch (or worktrees) off the latest `main`.
-- **Respect the conflict-skip sense** (from `/find-opportunity`): don't prototype something an
-  open PR is already building.
-
-## Phase 0 — Ground in the project's objectives
-
-Before ideating, learn what the project is *for* (so ideas fit, not just dazzle):
-```bash
-gh issue list --state open --limit 100 --json number,title,labels
-gh pr list   --state all  --limit 60  --json number,title,headRefName,state
-ls docs/ README.md AGENTS.md CLAUDE.md 2>/dev/null
-```
-Read the design docs / README / AGENTS for the mission, the north-star, the explicit
-non-goals/constraints, and the data model. Extract a short **objectives + constraints** brief —
-this is the anchor every discovery session and the ranking use.
-
-## Phase 1 — THREE independent discovery sessions (fan-out)
-
-Spawn **3 independent agents in parallel**. Each gets the objectives brief and is told to think
-differently from the others (assign distinct stances, e.g. *user-value first* / *data-leverage
-first* / *differentiation-&-novelty first*). Each agent:
-- Re-reads the issues / PRs / `main` / docs itself (independent grounding, not just your brief).
-- **May web-search** for ideas — comparable products, domain best-practice, what peer
-  civic/▢-tech projects ship — and bring back what genuinely fits.
-- Returns **exactly 5 high-level feature ideas**, each with: one-line pitch; which project
-  objective it advances; the data/infra it leans on (must already exist or be honestly stubbable);
-  rough surface (new route/page is preferred so it's independently deployable + validatable); a
-  novelty/effort/impact read. Be creative — no artificial limits.
-
-15 ideas total. Keep each agent blind to the others (diversity > consensus).
-
-## Phase 2 — Synthesise & rank → top 3
-
-Merge the 15. De-dupe near-identicals (keep the sharpest framing). Drop anything that: an open PR
-already builds, needs data the project doesn't have, or is a multi-week epic that can't reach a
-*validatable* prototype in one build. Rank the survivors by **objective-fit × user-value ×
-prototype-feasibility**. Pick the **top 3**. State *why* each won and what you dropped (no silent
-cuts). Prefer 3 that are independently deployable (separate routes) so the human can validate each
-in isolation.
-
-## Phase 3 — High-quality build of each top-3 feature
-
-For each of the 3, run a `/develop` `quality: high`-style build (deep-check → plan → implement →
-tests → self-validate). Build all three on **one branch** (or worktrees) so a single running app
-serves all three. Wire each as its own route/page where possible. Real data via real queries;
-honest empty states. Typecheck + the project's tests must pass before you call a feature done.
-
-## Phase 4 — Deploy locally & hand over (NO PR)
-
-Launch the project's dev server (or preview) so the features are reachable. Deliver, per feature:
-- **The URL** it's live at (e.g. `http://localhost:<port>/<route>`).
-- **What it does** in two lines + which objective it serves.
-- **A validation checklist** — concrete things for the human to click/observe to judge it
-  ("filter to sector X, confirm the sparkline matches the table total", "open on mobile width",
-  "try an entity with no data → honest empty state").
-- Note any assumptions or stubs.
-
-End with: the branch name (un-pushed), the 3 URLs, and "say which to keep → I'll turn those into
-PRs." **Do not push or PR anything yourself.**
-
-## Notes
-- This skill is token-intensive by design (3 discovery sessions + 3 builds). Run it when the user
-  has explicitly asked for a feature-ideation+prototype round, typically as an overnight batch.
-- If the dev server can only serve one branch at a time, that's fine — all three features share
-  the one branch and one server; give three routes/URLs on it.
-- Keep ideas anchored to the project's actual objectives — a brilliant idea that fights the
-  mission is noise. Creativity in service of the goal, not despite it.

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

@@ -1,205 +0,0 @@
----
-name: explain-to-me
-description: >-
-  Build and maintain session-manager-operations/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 (session-manager-operations/HUMAN_LEARN/index.html) plus a separate
-  skill-chain map (session-manager-operations/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 `session-manager-operations/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). All session-manager per-project operations live under
-`session-manager-operations/`.
-
-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>/session-manager-operations/HUMAN_LEARN/`. Create it
-  (and `session-manager-operations/` if needed) if missing.
-- **One combined page** — `session-manager-operations/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** — `session-manager-operations/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;
-  human-opened Epics in the app) converging on `/develop`, which owns
-  PRD authoring + reads `standards.md`, queues onto the scheduler, and gates with
-  review/verify. 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
-
-0. **Self-migrate a legacy root-level folder first.** If `HUMAN_LEARN/` exists
-   at the repo root **and** `session-manager-operations/HUMAN_LEARN/` does not,
-   relocate it now — `mkdir -p session-manager-operations` (if needed), then
-   `git mv HUMAN_LEARN session-manager-operations/HUMAN_LEARN` when the repo is
-   git-tracked, else a plain `mv`. This converges any project this skill runs
-   in to the new layout even if its bulk-relocation PRD hasn't landed yet.
-1. **Locate & survey.** Find the repo root + `session-manager-operations/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 (`session-manager-operations/HUMAN_LEARN/index.html`
-   or `session-manager-operations/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.