geneseed 2.0.0

package/src/skills/release.md

@@ -0,0 +1,43 @@
+# {{SKILL}}: release
+
+> {{DESC_RELEASE}}
+
+**Trigger:** cutting a release — a version bump, a changelog entry, and a tag.
+
+## Procedure
+1. Decide the version from the changes since the last tag, following the project's
+   scheme (semver: breaking → major, feature → minor, fix → patch). Verify the
+   current version and the last tag rather than guessing (universal {{LAW}} III).
+   **Never ship a breaking change under a non-major bump** — honest versions are a
+   promise to downstream consumers, and a quiet break is a broken one.
+2. Update the version wherever it is declared (manifest, package metadata, a VERSION
+   constant) — find *every* occurrence so they cannot drift (universal {{LAW}} XII).
+3. Update the changelog: a dated section for the new version summarising the
+   user-visible changes, grouped (added / changed / fixed), derived from the commits
+   since the last tag.
+4. Commit the version bump and changelog as one focused commit, through the
+   [commit {{SKILL}}](commit.md) — summary and exact message presented for
+   acceptance (universal {{LAW}} II, {{LAW}} XX).
+5. Tag the release (annotated, matching the version). Tagging and publishing are
+   **outward-facing** (universal {{LAW}} IV), and the push itself needs explicit
+   per-push acceptance — a release lands on a shared branch, where {{LAW}} XX
+   applies with extra care and grants no standing consent.
+6. With that acceptance, push the commit and the tag together; trigger or verify
+   the publish/release pipeline.
+
+## Done when
+- Version, changelog, and tag all name the same number, and the release is pushed
+  (or staged for the pipeline) with no unrelated changes bundled in.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/repo-map.md

@@ -0,0 +1,36 @@
+# {{SKILL}}: repo-map
+
+> {{DESC_REPO_MAP}}
+
+**Trigger:** onboarding to a repo that has no map, or after a structural change.
+
+## Procedure
+1. If `ARCHITECTURE.md` exists, read it first — it is the cheapest orientation
+   (universal {{LAW}} XV).
+2. Locate the project's own documentation — a `docs/`, `doc/`, `documentation/`,
+   or `wiki/` folder at the root, or the top-level README. Note where it lives and
+   what it covers, and record that in the map. Read the pages relevant to the work
+   at hand before changing the code they describe (universal {{LAW}} XVII) — the
+   relevant pages, not the whole tree ({{LAW}} XV).
+3. If `ARCHITECTURE.md` is absent or stale, build or refresh it: entry points, the
+   key directories and what each holds, how to build / test / run, external
+   services, and the one or two non-obvious conventions a newcomer must know.
+4. Keep it short — a map, not documentation. Link out for detail.
+5. Update it in the same change whenever structure shifts (universal {{LAW}} XI).
+
+## Done when
+- `ARCHITECTURE.md` reflects the current structure, and a fresh agent could orient
+  from it in a single read.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/research.md

@@ -0,0 +1,42 @@
+# {{SKILL}}: research
+
+> {{DESC_RESEARCH}}
+
+**Trigger:** a question needs current, external, or wide-ranging information that is
+not in this repository or your own knowledge — facts to gather and verify from the
+open web.
+
+**Requires:** a host web-search or web-fetch capability ({{LAW}} XIX) — without one,
+stop and report it ({{LAW}} VII); never substitute recall for verified research.
+
+## Procedure
+1. State the question and what a complete answer must contain. Break a broad question
+   into specific sub-questions.
+2. Search the web — use the host's web-search tool or a connected search provider
+   ({{LAW}} XIX). Query from several angles; one search is not research. If the host
+   exposes no web capability at all, stop and report that ({{LAW}} VII) — never
+   substitute your own knowledge for verified research.
+3. Open the most promising sources and extract only the relevant slice, not the whole
+   page ({{LAW}} XV). Prefer primary and recent sources.
+4. Cross-check every material claim against at least two independent sources. Treat a
+   single-source or unsourced claim as unverified, and say so ({{LAW}} III).
+5. Note recency — flag anything that may be out of date, and prefer the most current
+   authority.
+6. Synthesise a concise answer with each claim attributed to its source (title or URL).
+
+## Done when
+- The question is answered, every material claim is traceable to a cited,
+  cross-checked source, and remaining uncertainties are flagged explicitly.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/review-response.md

@@ -0,0 +1,36 @@
+# {{SKILL}}: review-response
+
+> {{DESC_REVIEW_RESPONSE}}
+
+**Trigger:** you have received review feedback — from a human or another agent — and
+are about to act on it.
+
+## Procedure
+1. Read every comment in full before changing anything. Group related comments.
+2. Classify each comment: correct, partially correct, wrong, or unclear.
+3. For anything you judge wrong or unclear, verify it against the code or a test before
+   responding — do not comply blindly and do not dismiss blindly ({{LAW}} III,
+   {{LAW}} VIII).
+4. Respond to each comment: the change you will make and why, or a reasoned decline
+   with evidence.
+5. Apply the accepted changes — one intent per commit ({{LAW}} II), each through the
+   [commit {{SKILL}}](commit.md) so {{LAW}} XX's per-commit consent holds — then
+   re-run the checks ({{LAW}} III).
+6. Surface anything the review missed that you noticed while addressing it.
+
+## Done when
+- Every comment has a reasoned response and either an applied change or a justified
+  decline, and the resulting changes are verified.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/roast-me.md

@@ -0,0 +1,28 @@
+# {{SKILL}}: roast-me
+
+> {{DESC_ROAST_ME}}
+
+**Trigger:** the user asks to "roast", "tear apart", "find the fatal flaws", or "be brutally honest" about an artifact — code, design, plan, pitch, or writing. This is the *open-ended quality critique*: for reviewing a diff use [geneseed-code-review](geneseed-code-review.md); for a zero-context does-it-meet-the-spec verdict use [fresh-eyes](fresh-eyes.md).
+
+## Procedure
+1. Identify the artifact and the critique axis that matters (correctness, architecture, viability, clarity, security…); if unclear, ask once, then proceed.
+2. Steelman it: state the strongest case FOR the artifact in a sentence, so the attack hits the real thing, not a strawman.
+3. In the voice of {{ROAST_PERSONA}}, write each flaw as one line — `location/claim — what's wrong — what to do instead`. No praise, no hedging, no filler; drop any finding you can't pair with a fix.
+4. Rank findings by severity: fatal → significant → minor.
+5. Close with the single change that would help most.
+
+## Done when
+- Findings are severity-ranked, every one carries a fix, and the highest-impact change is named.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/rule.md

@@ -0,0 +1,100 @@
+# {{SKILL}}: rule
+
+> {{DESC_RULE}}
+
+**Trigger:** anything the user wants to outlive this session — a standing rule of
+their own ("always…", "never…", "from now on…", "make that a rule") or a durable
+fact ("remember that…", "note that…", "keep in mind…"). Also fires when a
+`feedback` {{MEMORY}} lesson keeps recurring and deserves promotion, or when
+`user-rules.md` needs review — a trial rule past its date, a stale rule, a bloated
+set. Nothing reaches `user-rules.md` or {{MEMORY}} except through here ({{LAW}} VI).
+
+## Procedure
+
+### 0 — The fork
+Ask first, always: **a standing rule, or a fact to remember?** Never infer it. The
+two stores bind differently and the choice belongs to the user. If they hesitate,
+draw the line in one sentence: a rule changes how you *act* and binds every future
+session; a memory records something *true* that would otherwise be lost or
+re-derived. Then take exactly one branch.
+
+### Branch A — a fact to remember
+1. Search {{MEMORY}} for a file that already covers it. If one exists, update that
+   file — never mint a twin.
+2. Ask which **binding force** the fact carries, in plain words, not jargon:
+   *imposed by you, not mine to relax* (`constraint`) · *a choice taken among real
+   alternatives* (`choice`) · *a stance I hold until evidence overturns it*
+   (`conviction`) · *a constraint you deliberately relaxed* (`tempered`).
+3. Infer the `type` (`user` | `feedback` | `project` | `reference`), draft the file
+   per the {{MEMORY}} convention, and **show the exact content, frontmatter
+   included** — so a wrong inference is visible before it is written, not after.
+4. On the user's word, write the file and add its one-line entry to `MEMORY.md`.
+
+### Branch B — a standing rule
+1. **Triage.** A rule earns its place only if it is all three of: *standing
+   behaviour* (how to act — a fact belongs in Branch A, a pointer to documentation
+   in `context.json`), *recurring* (it will bind many future tasks, not just this
+   one), and *not already covered* (not a {{LAW}}, not an existing rule — extend
+   the existing rule rather than minting a twin). A failed triage goes back to the
+   fork, named and explained; a lean rule set is the feature, not a failure.
+2. **Reformulation.** Have the user state the rule as they would to a colleague on
+   their first day. Interrupt the moment they (a) use a term they cannot themselves
+   unpack, (b) skip a step — it says what to do but not when it bites, or the
+   reverse — or (c) simplify so far that the rule becomes false. Name which of the
+   three it was, each time. Then ask only about the axes still open — scope,
+   trigger, action, conflict, cost — one question at a time.
+3. **The counter-example.** Always, even for a rule that came out clean: build the
+   case where this rule would do harm, put it to the user, and make them choose —
+   accept it ("yes, even there") or narrow the rule. A rule that cannot survive its
+   own worst case was never generic, only never contradicted.
+4. **Legality.** A user rule may *tighten* a {{LAW}}, never repeal or weaken one.
+   If the rule conflicts — "push without asking", "skip the tests" — refuse, cite
+   the {{LAW}} it would repeal, and offer the nearest compliant version. Never write
+   rules into the {{LAWS}} file itself: it is regenerated on every update and the
+   edit would be silently lost.
+5. **Destination.** Scope decides the file: a rule that holds across all the user's
+   work goes to the *global* install's `user-rules.md`, a rule bound to this
+   codebase to the project's. Read the target first ({{LAW}} III — the real current
+   rules, not a remembered copy). The build seeds it once and never overwrites it;
+   if it is genuinely absent, create it with a `# User rules` header and note that a
+   rebuild would have seeded it.
+6. **Draft in the file's own format**: the next free `## R<n> — Title` heading, an
+   optional `(scope: user|project | source: …)` metadata line, then the rule in one
+   short paragraph, plain and testable. For a promotion from {{MEMORY}}, set
+   `source:` to the memory's name and add `trial until:` about a month out — a
+   promoted rule starts on probation.
+7. Show the exact text to the user and wait for explicit consent ({{LAW}} IV) before
+   appending it. For a promotion, after the rule lands, delete or archive the source
+   memory (with the same consent) so the lesson is not loaded twice.
+8. **Keep the set lean.** After writing, if the file holds more than ~15 rules or
+   any rule no longer changes behaviour, say so and propose merges or prunes — every
+   rule is loaded every session, and a bloated set dilutes the rules that matter.
+
+The asymmetry is deliberate: Branch A costs one question, Branch B costs several.
+The price is the safeguard — make remembering cheap and legislating expensive, or
+the user picks "rule" out of impatience and the set inflates.
+
+**Review flow** (on request, or when a `trial until:` date has passed): for each rule
+due, ask whether it actually fired since adoption — graduate it (drop the trial
+marker), demote it back to a {{MEMORY}} fact, or delete it. Same consent gate as
+adoption.
+
+## Done when
+- The fork was put to the user, and then either a {{MEMORY}} file exists carrying its
+  `force`, its `type` and its `MEMORY.md` line — or a rule stands in the right
+  `user-rules.md`, having survived reformulation, its own counter-example and the
+  {{LAWS}}, consented to explicitly, with any promoted source memory archived. The
+  {{LAWS}} file is untouched either way.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/ship.md

@@ -0,0 +1,49 @@
+# {{SKILL}}: ship
+
+> {{DESC_SHIP}}
+
+**Trigger:** the change is committed and verified, and it is time to open a pull
+request or merge the branch.
+
+## Procedure
+1. Confirm the work is actually done before shipping. Find the project's Definition
+   of Done — its test, lint, and build commands (often pointed at from
+   `context.json`); if it is undefined, ask rather than assume. Run those checks and
+   read the actual output (universal {{LAW}} III); state what you ran and its result.
+   Never ship on an unproven claim.
+2. Confirm the branch carries only this change's commits and is rebased/updated on
+   the base branch; resolve any divergence before opening.
+3. Push the branch only with the user's explicit, per-push acceptance — on every
+   branch, feature branches included ({{LAW}} XX); present the change summary + commit
+   message and wait, and never treat an earlier approval as consent for this push.
+   Opening a PR or merging is **outward-facing** — get explicit confirmation first too,
+   unless already authorized (universal {{LAW}} IV).
+4. Open the PR with a structured body: *what* changed and *why*, *how it was
+   tested*, and any risk or follow-up. Link the issue it closes; keep the title an
+   imperative one-line summary.
+5. If the project merges locally instead, merge into the base branch only after
+   review/approval, then delete the merged branch.
+   If shipping triggers a production deploy, confirm a tested rollback or
+   fix-forward path and a retained previous artifact *before* deploying — there must
+   be a way back (universal {{LAW}} IV); dispatch the
+   [operator {{AGENT}}](../{{DIR_AGENTS}}/operator.md) when the runtime surface is
+   non-trivial.
+6. Make sure documentation shipped with the code (universal {{LAW}} XI) — a change
+   that alters behaviour without its docs is incomplete, not ready to ship.
+
+## Done when
+- The PR is open (or the branch is merged) with a body stating what / why / how it
+  was tested, and nothing unrelated rides along.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/tdd.md

@@ -0,0 +1,31 @@
+# {{SKILL}}: tdd
+
+> {{DESC_TDD}}
+
+**Trigger:** implementing a feature or fixing a bug whose behaviour can be expressed as a test — before writing implementation code.
+
+## Procedure
+1. Agree the seams first: name the public interfaces the tests will target and
+   confirm them with the user — no test is written at an unconfirmed seam.
+   Testing effort belongs on critical paths and complex logic, not every edge.
+2. Write one failing test that pins the next small slice of behaviour; be specific about the expected output. For a bug, the test reproduces it.
+3. Run it and watch it fail for the RIGHT reason — a test that passes immediately proves nothing.
+4. Write the minimum code to make it pass; add nothing the test doesn't demand ({{LAW}} XXV).
+5. With the suite green, tidy up via the [refactor {{SKILL}}](refactor.md) — the tests are your safety net.
+6. Repeat one slice at a time, committing each green cycle with the [commit {{SKILL}}](commit.md).
+
+## Done when
+- The behaviour is covered by tests written before the code, the suite is green, and each cycle was committed.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/tickets.md

@@ -0,0 +1,44 @@
+# {{SKILL}}: tickets
+
+> {{DESC_TICKETS}}
+
+**Trigger:** a spec or plan is too big for one session and must be split into
+tracker issues that fresh sessions can pick up independently.
+
+## Procedure
+1. Work from the spec or plan already in context; explore the code enough that
+   ticket titles and bodies use the project's domain vocabulary (read
+   `CONTEXT.md` if it exists).
+2. Cut **tracer-bullet vertical slices**: each ticket cuts a narrow but
+   complete path through every layer it touches (schema, API, UI, tests), is
+   demoable or verifiable on its own, and fits one fresh context window. Any
+   prefactoring gets its own ticket first — make the change easy, then make
+   the easy change.
+3. Give every ticket its **blocking edges** — the tickets that must land
+   before it can start. A ticket with no blockers can start immediately.
+4. Exception — a **wide refactor** (one mechanical change whose blast radius
+   spans the codebase: a rename, a shared retype) cannot land as a green
+   vertical slice. Sequence it as **expand–contract**: expand (add the new
+   form beside the old, nothing breaks), migrate call sites in batches sized
+   by blast radius (each batch its own ticket, blocked by the expand),
+   contract (delete the old form, blocked by every batch).
+5. Publish to the repo's tracker (GitHub Issues by default; markdown files
+   under `docs/` when the repo has none). Each implementing session then takes
+   one unblocked ticket in a fresh context.
+
+## Done when
+- Every slice of the spec is a published ticket with explicit blockers, each
+  sized for one session, and at least one unblocked ticket exists to start on.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/token-report/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: token-report
+description: "Generate a token usage report for the current session — a markdown table breakdown of context window usage: the session-start baseline (harness, system prompt, tools, skills), everything processed since (user messages, replies, thinking, tool calls and results per tool), exact recorded totals, and the heaviest single items. Use this whenever the user asks about token usage, context usage, context window size, session cost in tokens, 'how full is the context', 'what is eating my context', a usage breakdown or usage report — even if they don't say the word 'token'."
+---
+
+# Token usage report
+
+> Generate the session's token usage breakdown — exact recorded totals, context
+> window occupancy, and an estimated attribution of what filled it — as markdown
+> tables, on any supported host.
+
+Produce a token usage report for the current session by running the bundled
+script, then present its markdown output to the user.
+
+## How to run
+
+Run the script that sits next to this SKILL.md:
+
+```bash
+node <this-skill-directory>/scripts/token_report.mjs
+```
+
+It auto-detects the host you are running on by locating session data and
+picking the most recently active source:
+
+| Host | Session data | Fidelity |
+|---|---|---|
+| Claude Code | `~/.claude/projects/<slug>/*.jsonl` | exact usage per request |
+| IBM Bob | `~/.bob/projects/<slug>/*.jsonl` (Claude-shaped, `$BOB_CONFIG_DIR` honoured) | exact usage per request |
+| OpenCode | `~/.local/share/opencode/opencode.db` (SQLite, v1.2+; pre-1.2 falls back to `storage/` JSON files) | exact `tokens` per request; child sessions attributed as subagents |
+| GitHub Copilot | `~/.copilot/history-session-state/` | best effort — undocumented schema; token-like fields harvested, else estimates only |
+
+Useful flags: `--host claude|bob|opencode|copilot` to force a host,
+`--transcript <path>` / `--session <id>` for a specific session,
+`--limit <tokens>` for the context-window limit used in the % columns
+(default 200000), `--top <n>` for the heaviest-items list.
+
+## What the report contains, and where the numbers come from
+
+Two kinds of numbers — keep the distinction explicit when presenting:
+
+1. **Exact numbers** come from the usage the host records with every request:
+   session totals (output tokens, fresh input, cache reads/writes), the
+   session-start baseline, and the current/peak context size. These are ground
+   truth — never contradict them.
+2. **Estimated attribution** (~4 characters per token) explains *what* fills
+   the context: user messages, assistant replies, thinking, tool calls, and
+   tool results grouped per tool. These are labeled estimates; keep them
+   labeled that way.
+
+The session-start baseline is the input-side token count of the very first
+request — that is the harness (system prompt, tool schemas, skill/agent
+listings, memory files) plus the user's first message. At the start of a
+fresh session that is the whole story; later, the delta between current and
+start context is the work processed since.
+
+## Presenting the result
+
+Relay the script's markdown tables directly — they are the deliverable.
+After the tables, add a short interpretation in your own words: what is
+consuming the most context, and one concrete suggestion if something stands
+out (e.g. a single huge file read dominating, or heavy tool results that a
+subagent could have absorbed instead). Do not pad the report with generic
+advice when nothing stands out.
+
+If the script errors or reports degraded fidelity (a host that stores its
+sessions elsewhere, or records no usage), say so plainly and fall back to
+reporting what you know: rough context size from any usage information
+available to you, and a qualitative breakdown of what has happened this
+session. Do not invent exact numbers.
+
+## Self-improvement
+
+If the script failed to find this host's session data, or a host changed its
+storage schema, note the observed layout and fix `scripts/token_report.mjs`
+(or record the finding in memory for the next run) before closing out.

package/src/skills/token-report/VENDOR.md

@@ -0,0 +1,23 @@
+# Folder skill — token-report
+
+Unlike its siblings in `VENDORED_SKILL_DIRS`, this folder is **Geneseed-authored**,
+not third-party. It rides the vendored-folder mechanism because it bundles an
+executable (`scripts/token_report.mjs`) and Geneseed's flat-skill pipeline renders
+single `.md` files only. Listing it in the generator's `VENDORED_SKILL_DIRS`
+makes the whole folder ride along verbatim into every host emit — Claude Code,
+IBM Bob, OpenCode, GitHub Copilot — which is exactly what a multi-file skill needs.
+
+- **Upstream:** this repository (first-party)
+- **License:** same as Geneseed (see repository LICENSE)
+
+Consequences of riding this mechanism (deliberate):
+
+- exempt from the flat-skill authoring gates (theme DESC tokens, dead-link,
+  hermeticity, skill counts) — the SKILL.md here carries its own frontmatter
+  `description` and blockquote purpose line instead;
+- listed in AGENT.md's folder-skills section, not the main skills table.
+
+The script supports all four emitted hosts (exact usage on Claude Code, Bob and
+OpenCode; best-effort on Copilot, whose session-state schema is undocumented).
+If a host changes its session storage layout, fix the corresponding finder or
+parser in `scripts/token_report.mjs`.