superwiki 0.1.4 → 0.1.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sw",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "license": "MIT",
   "keywords": [
     "wiki",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sw",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
   "license": "MIT",
   "skills": "./skills/",

package/README.md

@@ -23,13 +23,13 @@ It is built to be cheap for the agent:
 
 - **Little to read.** One small index, one file per task, and a script that answers "what is ready?", "what blocks this?" or "is anything broken?" without the agent reading the vault.
 - **Work in clean contexts.** Planning, implementing and reviewing run in subagents, each on the model you choose for it. The main session only keeps the task's status true, so it stays small.
-- **Cost you can see.** `sw-stats` shows what a session used, per agent.
+- **Cost you can see.** `sw-stats` shows what a session used, per agent; `sw-doctor` shows what every session carries before it starts, and what can go.
 
 Measured on a real project with 165 tasks, converted from a single markdown index:
 
 | | Before | After |
 | --- | --- | --- |
-| Read at the start of every session | 197 KB index | 94-byte catalog + 1.7 KB of rules |
+| Read at the start of every session | 197 KB index | 7.7 KB index (the 97 open tasks, a line each) + 2.7 KB of rules |
 | Read to start one task | the index, then the task's section | one file, 2 KB at the median |
 | Marking a task done | a status cell, plus a ✅ at every reference to it (median 12 places) | one frontmatter line |
 
@@ -39,7 +39,7 @@ Measured on a real project with 165 tasks, converted from a single markdown inde
 
 ```text
 docs/
-  index.md       catalog of the wiki, one line per page
+  index.md       the open tasks, then the catalog of the wiki, one line per page
   log.md         append-only history
   raw/           your sources, never modified
   wiki/          pages the agent writes
@@ -50,6 +50,31 @@ docs/
 
 `AGENTS.md` gets a short block of rules so the agent maintains the vault in every session, with or without a command.
 
+You can follow the work without the viewer: `index.md` opens with the task list, written from the task files. Each open task is a line that links to its file; finished ones are listed by id.
+
+```markdown
+## Tasks
+
+ready 9 · in progress 1 · blocked 18 · done 20
+
+**In progress**
+
+- [[B-20]] Portfolio sync · M5
+
+**Ready**
+
+- [[F-01]] Frontend skeleton and guards · M0
+- [[B-18]] Valuation · M4
+
+**Blocked**
+
+- [[B-21]] Journal and thesis gates · M5 · waits on B-20
+
+**Done (20)** [[B-01]] [[B-02]] [[B-03]] ...
+```
+
+A task's status still lives only in its own file. The list is a view: the agent rewrites it with `sw.mjs board` whenever a task changes, and `lint` says when it has fallen behind.
+
 ## Install
 
 Requires Node 18 or newer.
@@ -139,7 +164,7 @@ Agents that load `SKILL.md` folders from `~/.agents/skills` pick the skills up f
 
 - the skills name Claude Code, Codex and Copilot tools when they dispatch subagents; elsewhere they fall back to doing the work in the main session, and say so;
 - `sw-config` writes agent files only for `claude`, `codex` and `copilot`, so a per-role model cannot be set;
-- `sw-stats` reads the session records of those three tools only.
+- `sw-stats` and `sw-doctor` read the session records of those three tools only.
 
 Everything else (the vault, the CLI, the viewer, ingest, lint, explain, triage) depends only on Node and on the agent following the skill text.
 
@@ -157,7 +182,7 @@ npx superwiki@latest install claude      # update: same command, newest release
 npx superwiki uninstall all
 ```
 
-After an update, run `sw-init` again in each project: it replaces `docs/.sw/sw.mjs`, the templates and `docs/viewer.html` with the new version and keeps your content.
+After an update, run `sw-init` again in each project: it replaces `docs/.sw/sw.mjs`, the templates and `docs/viewer.html` with the new version and keeps your content. Until then the project keeps the script it was set up with, and a skill that needs a newer command says so.
 
 A project's `docs/` folder is plain markdown and keeps working as an Obsidian vault without Superwiki.
 
@@ -175,6 +200,7 @@ A project's `docs/` folder is plain markdown and keeps working as an Obsidian va
 | `sw-lint` | structural checks by script, semantic review on request |
 | `sw-visualize` | open the viewer |
 | `sw-stats` | what the current session has cost: tokens, context, steps and tool calls, per agent |
+| `sw-doctor` | what a session carries before any work, and what to remove to make every step cheaper |
 | `sw-config` | the model each tool uses for planning, implementing and reviewing; task areas |
 
 ### Examples
@@ -203,6 +229,7 @@ Shown as typed in Claude Code. In Codex, write `$sw-plan` instead of `/sw-plan`.
 /sw-lint                          check links, frontmatter and task dependencies
 /sw-visualize                     open the task board and the wiki in the browser
 /sw-stats                         what this session has cost so far, per agent
+/sw-doctor                        what fills the context before any work, and what can go
 ```
 
 You do not have to type a command. The rules `sw-init` adds to `AGENTS.md` tell the agent which skill fits, so a plain request should reach the same skill:
@@ -232,6 +259,24 @@ total                                149      -     -  20.9M     95%     43k
 
 `first` and `peak` are the tokens sent with one request. `sent` is that, summed over every step: each step sends the whole context again, which is why a long session in one context is expensive. In Copilot CLI the token columns fill in once the session has closed.
 
+### What a session starts with
+
+Every agent above began at 59k to 79k tokens before it had read anything, and paid for that on each of its steps. `sw-doctor` shows what that start is made of, from the same session record, and proposes what to switch off for this project. The same session:
+
+```text
+context at session start  claude  fe4cbd6c-8abf-4db6-9755-469dc7321dc7
+first request: 79k tokens
+part                             size  holds
+rule and memory files           30 KB  memory/MEMORY.md 18 KB, my-app/AGENTS.md 11 KB, ...
+skill list                      29 KB  213: marketing-skills 41, (none) 37, claude-seo 25, claude-ads 23, +11 more
+tool names (loaded on demand)   17 KB  381: claude_ai_higgsfield 116, claude_ai_meta_ads 98, +9 more
+agent list                      14 KB  46: claude-seo 18, (none) 12, claude-ads 10, +4 more
+MCP server instructions        8.3 KB  claude.ai higgsfield 2.0 KB, notebooklm 2.0 KB, ...
+session-start hooks            3.3 KB
+```
+
+Here most of the skills, agents and tools came from advertising and SEO plugins that this project never uses. The skill proposes changes and asks before making any; it touches project-local settings only, and never uninstalls a plugin or deletes a memory. Sizes are characters of text: a skill cannot run your agent's own context command (`/context` in Claude Code and Copilot CLI, `/status` in Codex), which shows the same in tokens.
+
 ### The CLI
 
 The skills call a small script that answers questions without the agent reading the vault. You can run it yourself, from the project root:
@@ -243,8 +288,10 @@ node docs/.sw/sw.mjs check P-15             # can it start or finish, what is op
 node docs/.sw/sw.mjs explain P-15           # dependencies, what it unblocks, plan, area guide
 node docs/.sw/sw.mjs search sync timeout    # where something is mentioned
 node docs/.sw/sw.mjs next-id P              # next free id in an area
-node docs/.sw/sw.mjs lint                   # broken links, bad frontmatter, dependency errors
+node docs/.sw/sw.mjs board                  # rewrite the task list in index.md from the task files
+node docs/.sw/sw.mjs lint                   # broken links, bad frontmatter, dependency errors, a stale task list
 node docs/.sw/sw.mjs stats                  # tokens, context and steps of the agent session here
+node docs/.sw/sw.mjs doctor                 # what that session carried before it read anything
 node docs/.sw/sw.mjs serve --open           # the viewer, reading files live
 node docs/.sw/sw.mjs snapshot               # or: freeze the vault into docs/viewer.html, no server
 ```
@@ -260,7 +307,10 @@ Edit sources in `src/`:
 | File | What it is |
 | --- | --- |
 | `src/core.js` | the vault model, derived task state, lint and search; shared by the CLI and the viewer |
-| `src/stats.js` | reads the agents' session records |
+| `src/board.js` | the task list in `index.md` |
+| `src/sessions.js` | finds the record an agent keeps of a session |
+| `src/stats.js` | reduces a session record to cost per agent |
+| `src/doctor.js` | reduces a session record to what the session started with |
 | `src/cli.js` | the commands |
 | `src/viewer.html` | the viewer |
 

package/commands/doctor.md

@@ -0,0 +1,5 @@
+---
+description: Show what fills the context before any work (rules, memory, skills, plugins, tools) and propose what to remove
+---
+
+Use the sw-doctor skill. User arguments: $ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superwiki",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Agent skills that turn docs/ into an LLM-maintained wiki and task tracker. Obsidian-friendly. Works with Claude Code, Codex and Copilot CLI.",
   "keywords": [
     "claude-code",

package/skills/sw-doctor/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: sw-doctor
+description: Use when the user wants to make agent sessions lighter or cheaper to start, asks what fills the context window before any work (rules, memory, skills, plugins, MCP tools), why a session starts with so many tokens, or invokes sw-doctor or sw:doctor.
+---
+
+# sw-doctor
+
+Shows what a session carries before it has read anything, and proposes what to remove. Rule and memory files, the lists of skills, agents and tools, and what plugins and hooks add are sent again with every step of every agent, subagents included, so a smaller start makes every step cheaper.
+
+You cannot run the tool's own context command: it is typed by the user. A script reads the same blocks from the record the tool keeps of this session. You read nothing yourself and write no report.
+
+Run from the project root:
+
+```bash
+node docs/.sw/sw.mjs doctor
+```
+
+It reports the session it runs in. `--session <id or its first characters>` picks another session of this project, `--tool claude|codex|copilot` looks only at one tool's sessions.
+
+## Steps
+
+1. **Show the table as printed**, in a code block. Sizes are characters of text, not tokens.
+2. **Propose changes**, largest saving first, at most five. For each: the part and its size from the table, what to change, and where. Use the table under "What to propose". Propose only what the output supports, and say plainly when a part cannot be made smaller.
+3. **Ask before changing anything**, one proposal at a time. Which plugin or server a project needs is the user's call: say what a group appears to be for and let them decide.
+4. **Apply what the user approved**, within the limits under "Limits".
+5. **Have it measured.** A change takes effect in a new session. Ask the user to open one and run the tool's own command there: `/context` in Claude Code and Copilot CLI, `/status` in Codex. Compare its figures with the ones from before; a setting that changed nothing is reported as such and taken out again.
+
+If the user pastes the output of that command, use its token figures in place of the character sizes; the parts are the same.
+
+## What to propose
+
+| In the table | Propose | What it saves |
+| --- | --- | --- |
+| `rule and memory files`: one file is most of the part | name the file. A rules file (`AGENTS.md`, `CLAUDE.md`): move sections that are needed only for some work into a document the agent opens on demand, and leave a one-line pointer. A memory index: one line per entry holding one lesson; dates, counts and status belong in the entry's own file | its full size |
+| `agent list`: groups that have nothing to do with this project | switch those plugins off for this project (how: "Limits"). The group label is the plugin's name; `(none)` is the user's own and built-in entries | the lines of those agents |
+| `skill list`: groups that have nothing to do with this project | the same switch. Say what to expect: the tool gives the list a fixed budget and shortens descriptions to fit, so fewer skills usually means fuller descriptions for the rest, not a smaller list. Worth doing so the agent picks skills better; not a token saving | little or nothing |
+| `tool names (loaded on demand)`: servers the project does not use | the user disables those MCP servers for this project. Only names are loaded, so the saving is the size shown, not the size of the tool definitions | the names of those tools |
+| `MCP server instructions` | goes away with the server; no separate change | with the server |
+| `session-start hooks` | name the hook and the plugin it belongs to, if the user can say; it goes away with that plugin | its full size |
+| Codex: `skills instructions` is large | skills are listed from `~/.agents/skills` and from plugins; remove or move the ones this user does not use | not measured |
+| Copilot CLI: `custom instruction` is large | the project's instruction files; same advice as for a rules file | its full size |
+| `first request` is far above what the parts add up to | the rest is the tool's own system prompt and built-in tool definitions. Say so; it cannot be changed from here | nothing |
+
+Give a saving as the size in the table. Do not turn it into a token or money figure unless the user pasted token numbers.
+
+## Limits
+
+- **Project-local settings only.** Never edit the user's global settings, and never uninstall a plugin or remove a server: switching it off for this project is enough and is undone by deleting a line.
+- **Claude Code**:
+  - a plugin off: in `.claude/settings.local.json` (personal, normally git-ignored; keep what is already there), `"enabledPlugins": { "<plugin>@<marketplace>": false }`. The full key is in `~/.claude/settings.json` under `enabledPlugins`; read only that key.
+  - an MCP server or a claude.ai connector off: the user does it with `/mcp` in the session. Do not edit `~/.claude.json`, and do not set environment variables for it in the project's settings: that was tried and changed nothing.
+  - plugins synced from the user's claude.ai account are not in that settings file; they are removed in the account's settings.
+- **Codex and Copilot CLI**: propose, and let the user change their configuration; this skill does not edit it.
+- **Memory and rule files are the user's.** Shorten an index or move a section only when asked, keep a copy of the previous version next to the file, and never delete an entry.
+- If the project's own rules forbid a change, they win.
+
+## If it fails
+
+| Output | Do |
+| --- | --- |
+| `unknown command doctor` | the project's `docs/.sw/sw.mjs` is older than this skill; offer to run sw-init, which updates it |
+| `no agent session record found` | say so and ask the user to run the tool's context command and paste the output; work from that |
+| a note that the session has not made a request yet | another session of this project is newer than yours; run again with `--session` and the id of the one you mean |
+| a note that Copilot has not counted its tool definitions | pass it on; the other parts are valid |

package/skills/sw-implement/SKILL.md

@@ -25,7 +25,10 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    | `plan: none` | fine for a small task: one area, three "Done when" items or fewer, nothing open in its notes, a few files. For anything larger, recommend sw-plan first and let the user choose |
    | `review: required (...)` | remember it for step 7 |
 
-3. **Mark it started** before any work: in the frontmatter of `docs/tasks/<ID>.md` set `status: in-progress` and `started:` today. Append `## [date] task | <ID> started` to `docs/log.md`, in the layout its last entries use.
+3. **Mark it started** before any work:
+   - in the frontmatter of `docs/tasks/<ID>.md`, `status: in-progress` and `started:` today;
+   - in `docs/log.md`, a new entry `## [date] task | <ID> started`, in the layout its last entries use;
+   - `node docs/.sw/sw.mjs board`, so the task list in `index.md` shows it.
 4. **Checks that need the environment.** If the task has a plan, look for `needs:` in it: `grep -n 'needs:' docs/plans/<ID>-plan.md`. Each hit is a check that starts services or changes data. Ask the user which of them may run; without a yes, none.
 5. **Dispatch the implementer** (how: "Dispatching" below). Its prompt is the task id, the project root if it is not your working directory, and which `needs:` checks it may run. Do not paste the plan into the prompt; it reads the files.
 6. **Judge the report.** Its `Requirements:` list must name every "Done when" item and every scope, state or constraint item of the task; compare it with the task file.
@@ -36,7 +39,7 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    - `Verdict: pass`: go on. Pass `important` and `minor` findings to the user in your report; they do not block.
    - `Verdict: changes needed`: dispatch the implementer again with the blocking findings, word for word, then the reviewer again with the files changed since. After two rounds that still end in `changes needed`, stop and put the findings to the user.
    - Do not review the change yourself in place of the reviewer, and do not argue a blocking finding away. If you think a finding is wrong, say so to the user and let them decide.
-8. **Record the outcome.**
+8. **Record the outcome**, then run `node docs/.sw/sw.mjs board`.
 
    | Outcome | Task file | Log entry |
    | --- | --- | --- |
@@ -50,7 +53,7 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
 10. **File what else was learned.** These are separate offers: act on each only when the user says yes to that one.
     - A report held a decision or constraint the wiki should keep: offer a wiki page (`type: decision` or `concept`), added to `index.md`.
     - The task fixed a problem whose cause is now known, or the review caught a defect worth remembering: offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later.
-    - A report named follow-up work: offer to create the tasks.
+    - A report named follow-up work, or the review left `important` findings open: offer to create the tasks. A finding that lives only in the log is forgotten.
 11. **Report** to the user, in this order. Commit only if the user asks.
     - the outcome;
     - each requirement with its evidence, and anything that differs from the task;
@@ -77,6 +80,7 @@ The same table serves both roles: `sw-implementer` with `implementer.md`, `sw-re
 - Accepting a `differs` item on the user's behalf. A sensible alternative is still not what the task asked for.
 - Skipping the review on a task that requires it, or doing it yourself in the same context that judged the implementation.
 - Starting work before the task file says `in-progress`. If the session dies, nobody knows the task was touched.
-- Letting a subagent edit the task file or the log. One writer for status: you.
+- Letting a subagent edit the task file, the log or the task list. One writer for status: you.
+- Editing the task list in `index.md` by hand. It is written from the task files; change the task file and run `board`.
 - Reading the plan or the code "to follow along". The subagents already paid for that.
 - Running the next task in the same session out of momentum.

package/skills/sw-init/assets/agents-block.md

@@ -3,7 +3,12 @@
 
 `docs/` is a wiki you write and keep current, and an Obsidian vault the user reads.
 
+{{#tasks}}
+- `docs/index.md`: the open tasks, then the catalog, one line per wiki page. Read it first, then open only the pages you need.
+{{/tasks}}
+{{^tasks}}
 - `docs/index.md`: catalog, one line per wiki page. Read it first, then open only the pages you need.
+{{/tasks}}
 - `docs/log.md`: append-only. Add `## [YYYY-MM-DD] <kind> | <title>` at the end; read it with `tail`, never whole.
 - `docs/raw/`: sources. Read, never modify.
 - `docs/wiki/`: flat, one page per topic, frontmatter `type:` and one-line `summary:`.
@@ -27,6 +32,7 @@ Wiki:
 Tasks:
 
 - A task's status lives only in its frontmatter. Before you start: `status: in-progress` and `started:`. When its "Done when" list is met: `status: done` and `finished:`. Each change of status gets a `task` entry in `log.md`.
+- The task list in `index.md` is written from the task files. After you add a task or change a task's status, title, milestone or dependencies, run `node docs/.sw/sw.mjs board`. Never edit that list by hand.
 - Do not start a task while any of its `deps` is not done.
 - If `explain <ID>` names an area guide (`docs/wiki/guide-<area>.md`), read it before you change code for the task: where things are, patterns, how to verify. Afterwards add the facts it was missing, one line each.
 - Work that belongs to no task (a quick fix, a small request) needs no task file. Append one `change` entry to `log.md` instead: what changed and why, in a line.

package/skills/sw-init/assets/sw.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Generated by scripts/build.mjs from src/core.js, src/stats.js, src/cli.js. Do not edit.
+// Generated by scripts/build.mjs from src/core.js, src/board.js, src/sessions.js, src/stats.js, src/doctor.js, src/cli.js. Do not edit.
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve as resolvePath, sep } from 'node:path';
@@ -322,21 +322,87 @@ export function guideFor(vault, area) {
   return vault.pages.find(p => p.folder === 'wiki' && p.data.type === 'guide' && key(p.data.area ?? '') === key(area)) || null;
 }
 
-// Session statistics: what the agent session working in this project has cost so far.
-// Claude Code, Codex and Copilot CLI each keep a record of every session on disk. This finds the
-// record of the project's session and reduces it to one row per agent: the main session and each
-// subagent it started.
+// The task board: the open tasks as a section of index.md, so a person can follow the work in the
+// vault itself, without the viewer. It is a view, written from the task files by `sw.mjs board`
+// and never edited by hand; a task's status still lives only in its own frontmatter.
+// Open tasks get a line each. Finished ones are listed by id only, so the section stays small as
+// a project grows: index.md is the one file every session reads.
 
-export const STATS_TOOLS = ['claude', 'codex', 'copilot'];
+const BOARD_START = '<!-- sw:board:start (written by `sw.mjs board`; do not edit) -->';
+const BOARD_END = '<!-- sw:board:end -->';
+const BOARD_BLOCK = /<!-- sw:board:start[^\n]*-->\n[\s\S]*?<!-- sw:board:end -->/;
+const REFRESH = 'run `node docs/.sw/sw.mjs board`';
+
+// Sections in reading order: what is being worked on, what can start, what waits.
+const OPEN_STATES = [['progress', 'In progress'], ['ready', 'Ready'], ['blocked', 'Blocked']];
+
+function openLine(vault, task) {
+  // A dependency that does not exist is lint's finding, not something a task waits on.
+  const waiting = task.openDeps.filter(id => taskOf(vault, id));
+  return [
+    `- [[${task.id}]] ${task.title}`,
+    ...(task.milestone ? [task.milestone] : []),
+    ...(task.state === 'blocked' && waiting.length ? [`waits on ${waiting.join(', ')}`] : []),
+  ].join(' · ');
+}
+
+// The board for this vault, markers included.
+export function taskBoard(vault) {
+  const { total } = summary(vault);
+  const counts = [
+    `ready ${total.ready}`, `in progress ${total.progress}`, `blocked ${total.blocked}`, `done ${total.done}`,
+    ...(total.cancelled ? [`cancelled ${total.cancelled}`] : []),
+  ];
+  const sections = OPEN_STATES
+    .map(([state, heading]) => [heading, tasksIn(vault, state)])
+    .filter(([, tasks]) => tasks.length)
+    .map(([heading, tasks]) => `**${heading}**\n\n${tasks.map(task => openLine(vault, task)).join('\n')}`);
+  // Finished tasks are looked up, not worked through: by id, not in running order.
+  const done = tasksIn(vault, 'done').map(task => task.id).sort((a, b) => a.localeCompare(b, 'en', { numeric: true })).map(id => `[[${id}]]`);
+  const paragraphs = [
+    '## Tasks',
+    total.total ? counts.join(' · ') : 'No tasks yet.',
+    ...sections,
+    ...(done.length ? [`**Done (${done.length})** ${done.join(' ')}`] : []),
+  ];
+  return `${BOARD_START}\n${paragraphs.join('\n\n')}\n${BOARD_END}`;
+}
+
+export const boardIn = indexText => (String(indexText).match(BOARD_BLOCK) || [null])[0];
+
+// index.md with this board in it: in place of the one it has, otherwise right under the title.
+export function indexWithBoard(indexText, board) {
+  const text = String(indexText);
+  if (BOARD_BLOCK.test(text)) return text.replace(BOARD_BLOCK, () => board);
+  const title = text.match(/^# .*\n?/);
+  if (!title) return `${board}\n\n${text}`;
+  const rest = text.slice(title[0].length).replace(/^\n+/, '');
+  return `${title[0].trimEnd()}\n\n${board}\n${rest ? `\n${rest}` : ''}`;
+}
+
+// A lint finding when index.md does not show the tasks as they are now, else null.
+export function boardFinding(vault) {
+  if (!vault.index) return null; // a missing index is reported on its own
+  const current = boardIn(vault.index.body);
+  if (!current && !vault.tasks.size) return null; // a vault without tasks needs no board
+  if (current === taskBoard(vault)) return null;
+  return current
+    ? { level: 'warn', code: 'stale-board', path: 'index.md', message: `the task list is out of date; ${REFRESH}` }
+    : { level: 'warn', code: 'missing-board', path: 'index.md', message: `the tasks are not listed; ${REFRESH}` };
+}
+
+// Finds the record an agent tool keeps of the session working in a project.
+// Claude Code, Codex and Copilot CLI each write every session to disk in their own layout; this
+// lists a project's sessions as { tool, id, modified, current, source } and picks one. What a
+// record means is left to the readers in stats.js and doctor.js.
+
+export const SESSION_TOOLS = ['claude', 'codex', 'copilot'];
 
-const MAIN = 'main';
 // Codex keeps every project's sessions in one tree; only the most recent files are opened.
 const CODEX_FILES_SCANNED = 100;
 
-// ---------- Reading records ----------
-
 // A record still being written can end in half a line; lines that do not parse are skipped.
-function jsonLines(path) {
+export function jsonLines(path) {
   const records = [];
   for (const line of readFileSync(path, 'utf8').split('\n')) {
     if (!line) continue;
@@ -347,7 +413,7 @@ function jsonLines(path) {
   return records;
 }
 
-function jsonFile(path) {
+export function jsonFile(path) {
   try {
     return JSON.parse(readFileSync(path, 'utf8'));
   } catch {
@@ -368,9 +434,111 @@ function rootForms(root) {
 
 const isWithin = (roots, dir) => Boolean(dir) && roots.some(root => dir === root || dir.startsWith(root + sep));
 
+// ---------- Claude Code ----------
+// ~/.claude/projects/<working directory, non-alphanumerics as dashes>/<session>.jsonl, and next to
+// it <session>/subagents/agent-<id>.jsonl with a .meta.json naming the agent type.
+// source: { path, subagentDir }
+
+const claudeHome = () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+
+function claudeSessions(root) {
+  const sessions = [];
+  for (const form of rootForms(root)) {
+    const dir = join(claudeHome(), 'projects', form.replace(/[^A-Za-z0-9]/g, '-'));
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.jsonl')) continue;
+      const id = name.slice(0, -'.jsonl'.length);
+      const path = join(dir, name);
+      sessions.push({
+        tool: 'claude',
+        id,
+        modified: modifiedAt(path),
+        current: id === process.env.CLAUDE_CODE_SESSION_ID,
+        source: { path, subagentDir: join(dir, id, 'subagents') },
+      });
+    }
+  }
+  return sessions;
+}
+
+// ---------- Codex ----------
+// ~/.codex/sessions/<year>/<month>/<day>/rollout-*.jsonl. The first line is the session's meta:
+// its working directory and, for a subagent, the session that spawned it and its role.
+// source: { files: [{ meta, records }] }, one file per agent
+
+const codexHome = () => process.env.CODEX_HOME || join(homedir(), '.codex');
+
+function rolloutFiles(dir, found = []) {
+  if (!existsSync(dir)) return found;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) rolloutFiles(path, found);
+    else if (entry.name.endsWith('.jsonl')) found.push({ path, modified: modifiedAt(path) });
+  }
+  return found;
+}
+
+function codexSessions(root) {
+  const roots = rootForms(root);
+  const recent = rolloutFiles(join(codexHome(), 'sessions')).sort((a, b) => b.modified - a.modified).slice(0, CODEX_FILES_SCANNED);
+  const byId = new Map();
+  for (const { path, modified } of recent) {
+    const records = jsonLines(path);
+    const meta = records[0]?.type === 'session_meta' ? records[0].payload : null;
+    if (!meta || !isWithin(roots, meta.cwd)) continue;
+    const id = meta.session_id || meta.id;
+    if (!byId.has(id)) byId.set(id, { modified: 0, files: [] });
+    const group = byId.get(id);
+    group.modified = Math.max(group.modified, modified);
+    group.files.push({ meta, records });
+  }
+  return [...byId].map(([id, { modified, files }]) => ({ tool: 'codex', id, modified, current: false, source: { files } }));
+}
+
+// ---------- Copilot CLI ----------
+// ~/.copilot/session-state/<session>/events.jsonl, with the working directory in workspace.yaml.
+// source: { path }
+
+const copilotHome = () => join(homedir(), '.copilot');
+
+function copilotSessions(root) {
+  const roots = rootForms(root);
+  const base = join(copilotHome(), 'session-state');
+  if (!existsSync(base)) return [];
+  const sessions = [];
+  for (const id of readdirSync(base)) {
+    const path = join(base, id, 'events.jsonl');
+    const workspace = join(base, id, 'workspace.yaml');
+    if (!existsSync(path) || !existsSync(workspace)) continue;
+    const cwd = (readFileSync(workspace, 'utf8').match(/^cwd: (.*)$/m) || [])[1];
+    if (!isWithin(roots, cwd)) continue;
+    sessions.push({ tool: 'copilot', id, modified: modifiedAt(path), current: false, source: { path } });
+  }
+  return sessions;
+}
+
+// ---------- Choosing ----------
+
+const LISTERS = { claude: claudeSessions, codex: codexSessions, copilot: copilotSessions };
+
+// The session to report: the one named by `id` (a prefix is enough), else the session this command
+// runs in when the tool says which one that is, else the most recently written one.
+export function findSession(root, { tool, id } = {}) {
+  let sessions = (tool ? [tool] : SESSION_TOOLS).flatMap(name => LISTERS[name](root));
+  if (id) sessions = sessions.filter(session => session.id.startsWith(id));
+  sessions.sort((a, b) => b.modified - a.modified);
+  return (!id && sessions.find(session => session.current)) || sessions[0] || null;
+}
+
+// Session statistics: what an agent session has cost so far, as one row per agent: the main
+// session and each subagent it started. Reads the session record found by sessions.js.
+
+const MAIN = 'main';
+
 // ---------- The summary being built ----------
 
-const newSession = (tool, id) => ({ tool, id, agents: [], tools: {}, note: '' });
+const newStats = session => ({ tool: session.tool, id: session.id, agents: [], tools: {}, note: '' });
 
 // Token fields stay null when the record does not hold them, so "unknown" never prints as 0.
 const newAgent = name => ({
@@ -389,9 +557,9 @@ function addStep(agent, { context, cached, output }) {
   agent.output = plus(agent.output, output);
 }
 
-function addToolCall(session, agent, name) {
+function addToolCall(stats, agent, name) {
   agent.toolCalls++;
-  session.tools[name] = (session.tools[name] || 0) + 1;
+  stats.tools[name] = (stats.tools[name] || 0) + 1;
 }
 
 // Widens the agent's working period to include this record.
@@ -406,33 +574,8 @@ function touch(agent, timestamp) {
 const byStart = (a, b) => (a.start ?? 0) - (b.start ?? 0);
 
 // ---------- Claude Code ----------
-// ~/.claude/projects/<working directory, non-alphanumerics as dashes>/<session>.jsonl, and next to
-// it <session>/subagents/agent-<id>.jsonl with a .meta.json naming the agent type.
-
-const claudeHome = () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
-
-function claudeSessions(root) {
-  const sessions = [];
-  for (const form of rootForms(root)) {
-    const dir = join(claudeHome(), 'projects', form.replace(/[^A-Za-z0-9]/g, '-'));
-    if (!existsSync(dir)) continue;
-    for (const name of readdirSync(dir)) {
-      if (!name.endsWith('.jsonl')) continue;
-      const id = name.slice(0, -'.jsonl'.length);
-      const path = join(dir, name);
-      sessions.push({
-        tool: 'claude',
-        id,
-        modified: modifiedAt(path),
-        current: id === process.env.CLAUDE_CODE_SESSION_ID,
-        read: () => readClaude(id, path, join(dir, id, 'subagents')),
-      });
-    }
-  }
-  return sessions;
-}
 
-function readClaudeAgent(session, name, path) {
+function claudeAgent(stats, name, path) {
   const agent = newAgent(name);
   // A reply is written as one line per content block. Each line repeats the reply's usage, and
   // only the last one has the final output count, so the last line of a reply is the one kept.
@@ -442,7 +585,7 @@ function readClaudeAgent(session, name, path) {
     const message = record.type === 'assistant' && record.message;
     if (!message) continue;
     for (const block of message.content || []) {
-      if (block.type === 'tool_use') addToolCall(session, agent, block.name);
+      if (block.type === 'tool_use') addToolCall(stats, agent, block.name);
     }
     if (message.usage) replies.set(message.id, message);
   }
@@ -458,61 +601,31 @@ function readClaudeAgent(session, name, path) {
   return agent;
 }
 
-function readClaude(id, path, subagentDir) {
-  const session = newSession('claude', id);
-  session.agents.push(readClaudeAgent(session, MAIN, path));
-  if (!existsSync(subagentDir)) return session;
+function claudeStats(session) {
+  const { path, subagentDir } = session.source;
+  const stats = newStats(session);
+  stats.agents.push(claudeAgent(stats, MAIN, path));
+  if (!existsSync(subagentDir)) return stats;
   const subagents = readdirSync(subagentDir)
     .filter(name => name.endsWith('.jsonl'))
     .map(name => {
       const meta = jsonFile(join(subagentDir, name.replace(/\.jsonl$/, '.meta.json')));
-      return readClaudeAgent(session, meta.agentType || 'subagent', join(subagentDir, name));
+      return claudeAgent(stats, meta.agentType || 'subagent', join(subagentDir, name));
     });
-  session.agents.push(...subagents.sort(byStart));
-  return session;
+  stats.agents.push(...subagents.sort(byStart));
+  return stats;
 }
 
 // ---------- Codex ----------
-// ~/.codex/sessions/<year>/<month>/<day>/rollout-*.jsonl. The first line is the session's meta:
-// its working directory and, for a subagent, the session that spawned it and its role.
 
-const codexHome = () => process.env.CODEX_HOME || join(homedir(), '.codex');
-
-function rolloutFiles(dir, found = []) {
-  if (!existsSync(dir)) return found;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const path = join(dir, entry.name);
-    if (entry.isDirectory()) rolloutFiles(path, found);
-    else if (entry.name.endsWith('.jsonl')) found.push({ path, modified: modifiedAt(path) });
-  }
-  return found;
-}
-
-function codexSessions(root) {
-  const roots = rootForms(root);
-  const recent = rolloutFiles(join(codexHome(), 'sessions')).sort((a, b) => b.modified - a.modified).slice(0, CODEX_FILES_SCANNED);
-  const byId = new Map();
-  for (const { path, modified } of recent) {
-    const records = jsonLines(path);
-    const meta = records[0]?.type === 'session_meta' ? records[0].payload : null;
-    if (!meta || !isWithin(roots, meta.cwd)) continue;
-    const id = meta.session_id || meta.id;
-    if (!byId.has(id)) byId.set(id, { modified: 0, files: [] });
-    const group = byId.get(id);
-    group.modified = Math.max(group.modified, modified);
-    group.files.push({ meta, records });
-  }
-  return [...byId].map(([id, { modified, files }]) => ({ tool: 'codex', id, modified, current: false, read: () => readCodex(id, files) }));
-}
-
-function readCodexAgent(session, name, records) {
+function codexAgent(stats, name, records) {
   const agent = newAgent(name);
   let lastTotal = null;
   for (const record of records) {
     touch(agent, record.timestamp);
     const payload = record.payload || {};
     if (record.type === 'turn_context') agent.model = payload.model || agent.model;
-    if (record.type === 'response_item' && /_call$/.test(payload.type || '')) addToolCall(session, agent, payload.name || payload.type);
+    if (record.type === 'response_item' && /_call$/.test(payload.type || '')) addToolCall(stats, agent, payload.name || payload.type);
     if (record.type !== 'event_msg' || payload.type !== 'token_count' || !payload.info) continue;
     // The count is also repeated when only the rate limits change; a new request moves the total.
     const total = payload.info.total_token_usage?.total_tokens;
@@ -524,41 +637,22 @@ function readCodexAgent(session, name, records) {
   return agent;
 }
 
-function readCodex(id, files) {
-  const session = newSession('codex', id);
+function codexStats(session) {
+  const stats = newStats(session);
   const subagents = [];
-  for (const { meta, records } of files) {
-    if (meta.thread_source === 'subagent') subagents.push(readCodexAgent(session, meta.agent_role || meta.agent_nickname || 'subagent', records));
-    else session.agents.push(readCodexAgent(session, MAIN, records));
+  for (const { meta, records } of session.source.files) {
+    if (meta.thread_source === 'subagent') subagents.push(codexAgent(stats, meta.agent_role || meta.agent_nickname || 'subagent', records));
+    else stats.agents.push(codexAgent(stats, MAIN, records));
   }
-  session.agents.push(...subagents.sort(byStart));
-  return session;
+  stats.agents.push(...subagents.sort(byStart));
+  return stats;
 }
 
 // ---------- Copilot CLI ----------
-// ~/.copilot/session-state/<session>/events.jsonl, with the working directory in workspace.yaml.
 // Events of a subagent carry its agentId. Token counts are written only when the session closes.
 
-const copilotHome = () => join(homedir(), '.copilot');
-
-function copilotSessions(root) {
-  const roots = rootForms(root);
-  const base = join(copilotHome(), 'session-state');
-  if (!existsSync(base)) return [];
-  const sessions = [];
-  for (const id of readdirSync(base)) {
-    const events = join(base, id, 'events.jsonl');
-    const workspace = join(base, id, 'workspace.yaml');
-    if (!existsSync(events) || !existsSync(workspace)) continue;
-    const cwd = (readFileSync(workspace, 'utf8').match(/^cwd: (.*)$/m) || [])[1];
-    if (!isWithin(roots, cwd)) continue;
-    sessions.push({ tool: 'copilot', id, modified: modifiedAt(events), current: false, read: () => readCopilot(id, events) });
-  }
-  return sessions;
-}
-
-function readCopilot(id, path) {
-  const session = newSession('copilot', id);
+function copilotStats(session) {
+  const stats = newStats(session);
   const agents = new Map();
   const agentOf = key => {
     if (!agents.has(key)) agents.set(key, newAgent(key));
@@ -566,7 +660,7 @@ function readCopilot(id, path) {
   };
   agentOf(MAIN);
   let closed = false;
-  for (const event of jsonLines(path)) {
+  for (const event of jsonLines(session.source.path)) {
     const data = event.data || {};
     const agent = agentOf(event.agentId || MAIN);
     touch(agent, event.timestamp);
@@ -576,7 +670,7 @@ function readCopilot(id, path) {
       agent.steps++;
       agent.model = data.model || agent.model;
     } else if (event.type === 'tool.execution_start') {
-      addToolCall(session, agent, data.toolName);
+      addToolCall(stats, agent, data.toolName);
     } else if (event.type === 'session.shutdown' && data.agentMetrics) {
       // A resumed session closes more than once; each close reports the run that ended with it.
       closed = true;
@@ -590,24 +684,14 @@ function readCopilot(id, path) {
       }
     }
   }
-  session.agents = [...agents.values()];
-  if (!closed) session.note = 'Copilot writes token counts when the session closes; until then /usage shows them.';
-  return session;
+  stats.agents = [...agents.values()];
+  if (!closed) stats.note = 'Copilot writes token counts when the session closes; until then /usage shows them.';
+  return stats;
 }
 
-// ---------- Choosing the session ----------
-
-const LISTERS = { claude: claudeSessions, codex: codexSessions, copilot: copilotSessions };
+const STATS_READERS = { claude: claudeStats, codex: codexStats, copilot: copilotStats };
 
-// The session to report: the one named by `id` (a prefix is enough), else the session this command
-// runs in when the tool says which one that is, else the most recently written one.
-export function sessionStats(root, { tool, id } = {}) {
-  let sessions = (tool ? [tool] : STATS_TOOLS).flatMap(name => LISTERS[name](root));
-  if (id) sessions = sessions.filter(session => session.id.startsWith(id));
-  sessions.sort((a, b) => b.modified - a.modified);
-  const chosen = (!id && sessions.find(session => session.current)) || sessions[0];
-  return chosen ? chosen.read() : null;
-}
+export const sessionStats = session => STATS_READERS[session.tool](session);
 
 // ---------- Printing ----------
 
@@ -615,7 +699,7 @@ const COLUMNS = ['agent', 'model', 'steps', 'first', 'peak', 'sent', 'cached', '
 const TEXT_COLUMNS = 2; // agent and model align left; the numbers after them align right
 const LEGEND = 'first, peak: tokens sent with one request. sent: that, summed over every step. cached: the share of sent read from the cache.';
 
-function tokens(n) {
+export function tokenCount(n) {
   if (n == null) return '-';
   if (n < 1000) return String(n);
   if (n < 1e6) return `${Math.round(n / 1000)}k`;
@@ -658,33 +742,238 @@ function totalOf(agents) {
 }
 
 const cells = agent => [
-  agent.name, agent.model, String(agent.steps), tokens(agent.first), tokens(agent.peak), tokens(agent.sent), cachedShare(agent),
-  tokens(agent.output), String(agent.toolCalls), agent.start == null ? '' : String(minutes(agent.start, agent.end)),
+  agent.name, agent.model, String(agent.steps), tokenCount(agent.first), tokenCount(agent.peak), tokenCount(agent.sent), cachedShare(agent),
+  tokenCount(agent.output), String(agent.toolCalls), agent.start == null ? '' : String(minutes(agent.start, agent.end)),
 ];
 
-function table(rows) {
-  const widths = COLUMNS.map((_, column) => Math.max(...rows.map(row => row[column].length)));
-  const pad = (cell, column) => (column < TEXT_COLUMNS ? cell.padEnd(widths[column]) : cell.padStart(widths[column]));
+// Rows of text cells as aligned lines: the first `textColumns` align left, the rest right.
+export function alignedRows(rows, textColumns) {
+  const widths = rows[0].map((_, column) => Math.max(...rows.map(row => row[column].length)));
+  const pad = (cell, column) => (column < textColumns ? cell.padEnd(widths[column]) : cell.padStart(widths[column]));
   return rows.map(row => row.map(pad).join('  ').trimEnd());
 }
 
-export function formatStats(session) {
-  const { agents } = session;
+export function formatStats(stats) {
+  const { agents } = stats;
   const rows = [COLUMNS, ...agents.map(cells)];
   if (agents.length > 1) rows.push(cells(totalOf(agents)));
-  const calls = Object.entries(session.tools).sort((a, b) => b[1] - a[1]).map(([name, count]) => `${name} ${count}`);
+  const calls = Object.entries(stats.tools).sort((a, b) => b[1] - a[1]).map(([name, count]) => `${name} ${count}`);
   return [
-    ['session', session.tool, session.id, sessionPeriod(agents)].filter(Boolean).join('  '),
-    ...table(rows),
+    ['session', stats.tool, stats.id, sessionPeriod(agents)].filter(Boolean).join('  '),
+    ...alignedRows(rows, TEXT_COLUMNS),
     `tool calls  ${calls.join('  ') || 'none'}`,
     LEGEND,
-    ...(session.note ? [session.note] : []),
+    ...(stats.note ? [stats.note] : []),
+  ].join('\n');
+}
+
+// Start context: what an agent session carries before it has read anything. Rule and memory
+// files, the lists of skills, agents and tools, and what plugins and hooks add are sent again with
+// every step of every agent, so this is the cheapest place to make a session lighter.
+// Reads the session record found by sessions.js and reduces it to parts with a size and a source.
+
+// The command that shows the same context in tokens, in each tool.
+const CONTEXT_COMMANDS = { claude: '/context', codex: '/status', copilot: '/context' };
+const SMALL_PART_CHARS = 512; // smaller parts are summed into "other"
+const SOURCES_SHOWN = 6;
+const UNGROUPED = '(none)';
+const NOT_STARTED = 'This session has not made a request yet; its context is recorded with the first one.';
+
+// ---------- The report being built ----------
+
+const newReport = session => ({ tool: session.tool, id: session.id, firstRequest: null, parts: [], note: '' });
+
+// A part's sources are either texts with a size or groups with a count: { label, amount }.
+// `chars` is null for a part the record counts in tokens instead.
+const newPart = (name, measure) => ({ name, chars: 0, tokens: null, count: null, measure, sources: [] });
+
+// A part made of texts, each from a named source.
+function sized(name, texts) {
+  const part = newPart(name, 'size');
+  for (const [label, text] of texts) {
+    part.chars += text.length;
+    part.sources.push({ label, amount: text.length });
+  }
+  return part;
+}
+
+// A part that is one list of names, grouped by where each name comes from.
+function listed(name, names, text, groupOf) {
+  const part = newPart(name, 'count');
+  part.chars = text.length;
+  part.count = names.length;
+  const groups = new Map();
+  for (const item of names) groups.set(groupOf(item), (groups.get(groupOf(item)) || 0) + 1);
+  part.sources = [...groups].map(([label, amount]) => ({ label, amount }));
+  return part;
+}
+
+// "plugin:skill" and "plugin:agent" belong to the plugin; "mcp__server__tool" to the server.
+const pluginOf = name => (name.includes(':') ? name.slice(0, name.indexOf(':')) : UNGROUPED);
+const serverOf = name => (name.match(/^mcp__(.+?)__/) || [])[1] || UNGROUPED;
+
+// "memory/MEMORY.md": the last folder says which of several same-named files this is.
+const shortPath = path => `${basename(dirname(path))}/${basename(path)}`;
+
+// ---------- Claude Code ----------
+// Before the first reply the record holds one "attachment" per block of context the session was
+// given: the instruction files, the skill, agent and tool lists, server instructions, hook output.
+
+function claudePart(attachment) {
+  switch (attachment.type) {
+    case 'instructions':
+      return sized('rule and memory files', (attachment.files || []).map(file => [shortPath(file.path), file.content || '']));
+    case 'skill_listing':
+      return listed('skill list', attachment.names || [], attachment.content || '', pluginOf);
+    case 'agent_listing_delta':
+      return listed('agent list', attachment.addedTypes || [], (attachment.addedLines || []).join('\n'), pluginOf);
+    case 'deferred_tools_delta':
+      return listed('tool names (loaded on demand)', attachment.addedNames || [], (attachment.addedLines || []).join('\n'), serverOf);
+    case 'mcp_instructions_delta':
+      return sized('MCP server instructions', (attachment.addedNames || []).map((name, i) => [name, attachment.addedBlocks?.[i] || '']));
+    case 'hook_additional_context':
+      return sized('session-start hooks', [[attachment.hookName || 'hook', [attachment.content].flat().join('\n')]]);
+    default:
+      return null;
+  }
+}
+
+function claudeStart(session) {
+  const report = newReport(session);
+  for (const record of jsonLines(session.source.path)) {
+    if (record.type === 'attachment') {
+      const part = claudePart(record.attachment || {});
+      if (part) report.parts.push(part);
+    }
+    const usage = record.type === 'assistant' && record.message?.usage;
+    if (!usage) continue;
+    report.firstRequest = (usage.input_tokens || 0) + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0);
+    break;
+  }
+  if (report.firstRequest == null) report.note = NOT_STARTED;
+  return report;
+}
+
+// ---------- Codex ----------
+// The session meta holds the base instructions. The messages before the first request hold the
+// rest, one tagged block each: <skills_instructions>, <plugins_instructions>, the AGENTS.md text.
+
+function codexBlockName(text) {
+  if (text.startsWith('# AGENTS.md')) return 'AGENTS.md';
+  const tag = (text.match(/^<([a-z_ ]+)>/) || [])[1];
+  return tag ? tag.replace(/_/g, ' ') : null; // untagged text is the user's own request
+}
+
+function codexStart(session) {
+  const report = newReport(session);
+  const main = session.source.files.find(file => file.meta.thread_source !== 'subagent') || session.source.files[0];
+  report.parts.push(sized('base instructions', [['codex', main.meta.base_instructions?.text || '']]));
+  for (const record of main.records) {
+    const payload = record.payload || {};
+    if (record.type === 'response_item' && payload.type === 'message') {
+      for (const block of payload.content || []) {
+        const name = codexBlockName(block.text || '');
+        if (name) report.parts.push(sized(name, [[payload.role, block.text]]));
+      }
+    }
+    if (record.type !== 'event_msg' || payload.type !== 'token_count' || !payload.info) continue;
+    report.firstRequest = payload.info.last_token_usage?.input_tokens ?? null;
+    break;
+  }
+  if (report.firstRequest == null) report.note = NOT_STARTED;
+  return report;
+}
+
+// ---------- Copilot CLI ----------
+// The first system message holds the context as tagged blocks (<tools>, <custom_instruction>).
+// A usage checkpoint, written later in the session, counts the tool definitions in tokens.
+
+function copilotStart(session) {
+  const report = newReport(session);
+  const events = jsonLines(session.source.path);
+  const system = events.find(event => event.type === 'system.message')?.data?.content || '';
+  for (const [, tag, body] of system.matchAll(/<([a-z_]+)>(.*?)<\/\1>/gs)) report.parts.push(sized(tag.replace(/_/g, ' '), [['system', body]]));
+  const checkpoint = events.find(event => event.type === 'session.usage_checkpoint')?.data?.promptCacheBreakState?.[0]?.models;
+  const usage = checkpoint && Object.values(checkpoint)[0];
+  if (usage?.tool_tokens == null) {
+    report.note = 'Copilot counts its tool definitions at the first usage checkpoint; this session has not reached one.';
+    return report;
+  }
+  report.parts.push({ ...newPart('tool definitions', 'count'), chars: null, tokens: usage.tool_tokens, count: usage.tool_count ?? null });
+  return report;
+}
+
+const START_READERS = { claude: claudeStart, codex: codexStart, copilot: copilotStart };
+
+// ---------- Tidying ----------
+
+// Blocks with the same name become one part.
+function mergedByName(parts) {
+  const byName = new Map();
+  for (const part of parts) {
+    const known = byName.get(part.name);
+    if (!known) {
+      byName.set(part.name, part);
+      continue;
+    }
+    known.chars += part.chars;
+    known.sources.push(...part.sources);
+  }
+  return [...byName.values()];
+}
+
+// Largest first; parts too small to matter are summed into "other", which comes last.
+function ranked(parts) {
+  const other = newPart('other', 'size');
+  const kept = [];
+  for (const part of parts) {
+    if (part.chars == null || part.chars >= SMALL_PART_CHARS) kept.push(part);
+    else other.chars += part.chars;
+  }
+  kept.sort((a, b) => (b.chars ?? 0) - (a.chars ?? 0));
+  return other.chars ? [...kept, other] : kept;
+}
+
+export function startContext(session) {
+  const report = START_READERS[session.tool](session);
+  report.parts = ranked(mergedByName(report.parts));
+  for (const part of report.parts) part.sources.sort((a, b) => b.amount - a.amount);
+  return report;
+}
+
+// ---------- Printing ----------
+
+const kilobytes = chars => `${(chars / 1024).toFixed(chars < 10 * 1024 ? 1 : 0)} KB`;
+const sizeOf = part => (part.chars == null ? `${tokenCount(part.tokens)} tokens` : kilobytes(part.chars));
+
+// "213: marketing-skills 41, claude-seo 25, +9 more" for a list, "MEMORY.md 18 KB, AGENTS.md 11 KB"
+// for texts. A part that is a single text says nothing its name and size have not said.
+function sourcesOf(part) {
+  if (part.measure === 'size' && part.sources.length < 2) return '';
+  const amount = source => (part.measure === 'size' ? kilobytes(source.amount) : String(source.amount));
+  const shown = part.sources.slice(0, SOURCES_SHOWN).map(source => `${source.label} ${amount(source)}`);
+  const hidden = part.sources.length - shown.length;
+  const list = shown.join(', ') + (hidden > 0 ? `, +${hidden} more` : '');
+  return part.count == null ? list : [String(part.count), list].filter(Boolean).join(': ');
+}
+
+export function formatStartContext(report) {
+  const rows = [['part', 'size', 'holds'], ...report.parts.map(part => [part.name, sizeOf(part), sourcesOf(part)])];
+  const [nameWidth, sizeWidth] = [0, 1].map(column => Math.max(...rows.map(row => row[column].length)));
+  return [
+    `context at session start  ${report.tool}  ${report.id}`,
+    ...(report.firstRequest == null ? [] : [`first request: ${tokenCount(report.firstRequest)} tokens`]),
+    ...rows.map(([name, size, holds]) => `${name.padEnd(nameWidth)}  ${size.padStart(sizeWidth)}  ${holds}`.trimEnd()),
+    `sizes are characters of text; ${CONTEXT_COMMANDS[report.tool]} shows this session's context in tokens`,
+    ...(report.note ? [report.note] : []),
   ].join('\n');
 }
 
 // Superwiki CLI. Lives in a project at docs/.sw/sw.mjs and prints short answers,
 // so agents do not have to read the vault to get them.
 
+const SESSION_FLAGS = `[--session <id>] [--tool ${SESSION_TOOLS.join('|')}]`;
+
 const HELP = `sw <command> [--docs <dir>] [--json]
 
   status          task counts per area and wiki page count
@@ -693,9 +982,11 @@ const HELP = `sw <command> [--docs <dir>] [--json]
   explain <ID>    a task's dependencies, what it blocks and unblocks, its plan and linked pages
   search <words>  pages and log entries that mention the words, best match first
   next-id <AREA>  next free task id for an area (numbers are never reused)
+  board           rewrite the task list in docs/index.md from the task files
   lint            structural checks; exit code 1 on errors
   stats           what the agent session here has cost so far: steps, context and tokens per agent
-                  [--session <id>] another session of this project  [--tool ${STATS_TOOLS.join('|')}]
+  doctor          what that session carried before it read anything: rule files, skill and tool lists
+                  both take ${SESSION_FLAGS} to look at another session of this project
   serve [--open]  start (or reuse) a local viewer at http://127.0.0.1:<port>/ that reads the files live
   snapshot        write docs/.sw/data.js so docs/viewer.html opens as a file, frozen at this moment`;
 
@@ -756,7 +1047,7 @@ export function vaultData(docs) {
 // "<" is escaped so page text can never close the script element the viewer loads this with.
 export const dataScript = data => `window.SW_DATA = ${JSON.stringify(data).replace(/</g, '\\u003c')};\n`;
 
-// ---------- Commands ----------
+// ---------- Vault commands ----------
 // Each command gets { docs, vault, args, flags } and returns { data, text, code? } or
 // { error, code? }. `data` is what --json prints; `text` is the default output.
 
@@ -907,8 +1198,25 @@ function nextIdCommand({ vault, args }) {
   return { data: { id }, text: id };
 }
 
+// The task list in index.md is a view of the task files; this writes it again from them.
+function boardCommand({ docs, vault }) {
+  if (!existsSync(join(docs, 'tasks'))) return { error: 'this vault has no task module (docs/tasks); sw-init --tasks adds it', code: 1 };
+  const path = join(docs, 'index.md');
+  if (!existsSync(path)) return { error: 'docs/index.md is missing; run sw-init', code: 1 };
+  const before = readFileSync(path, 'utf8');
+  const after = indexWithBoard(before, taskBoard(vault));
+  const changed = after !== before;
+  if (changed) writeFileSync(path, after);
+  const { total } = summary(vault);
+  return {
+    data: { changed, ready: total.ready, inProgress: total.progress, blocked: total.blocked, done: total.done },
+    text: `board: docs/index.md ${changed ? 'updated' : 'unchanged'}  ready ${total.ready}  in-progress ${total.progress}  blocked ${total.blocked}  done ${total.done}`,
+  };
+}
+
 function lintCommand({ vault }) {
-  const findings = lint(vault);
+  const board = boardFinding(vault);
+  const findings = [...lint(vault), ...(board ? [board] : [])];
   const errors = findings.filter(f => f.level === 'error').length;
   return {
     data: findings,
@@ -920,17 +1228,6 @@ function lintCommand({ vault }) {
   };
 }
 
-// Agent sessions are recorded by the folder they ran in: the project root, which holds docs/.
-function stats({ docs, flags }) {
-  if (flags.tool && !STATS_TOOLS.includes(flags.tool)) {
-    return { error: `usage: sw stats [--session <id>] [--tool ${STATS_TOOLS.join('|')}]` };
-  }
-  const root = dirname(docs);
-  const session = sessionStats(root, { tool: flags.tool, id: flags.session });
-  if (!session) return { error: `no ${flags.tool || 'agent'} session record found for ${root}`, code: 1 };
-  return { data: session, text: formatStats(session) };
-}
-
 function snapshot({ docs }) {
   const data = vaultData(docs);
   mkdirSync(join(docs, '.sw'), { recursive: true });
@@ -939,6 +1236,31 @@ function snapshot({ docs }) {
   return { data: { files: data.files.length }, text };
 }
 
+// ---------- Session commands ----------
+// These read the record an agent tool keeps of a session, not the vault. Tools file a session
+// under the folder it ran in: the project root, which holds docs/.
+
+function sessionArg(command, { docs, flags }) {
+  if (flags.tool && !SESSION_TOOLS.includes(flags.tool)) return { error: `usage: sw ${command} ${SESSION_FLAGS}` };
+  const root = dirname(docs);
+  const session = findSession(root, { tool: flags.tool, id: flags.session });
+  return session || { error: `no ${flags.tool || 'agent'} session record found for ${root}`, code: 1 };
+}
+
+function statsCommand(ctx) {
+  const session = sessionArg('stats', ctx);
+  if (session.error) return session;
+  const stats = sessionStats(session);
+  return { data: stats, text: formatStats(stats) };
+}
+
+function doctorCommand(ctx) {
+  const session = sessionArg('doctor', ctx);
+  if (session.error) return session;
+  const report = startContext(session);
+  return { data: report, text: formatStartContext(report) };
+}
+
 // ---------- Viewer server ----------
 // A file:// page cannot read local files unless the user picks a folder. Served from localhost it
 // can: every Refresh asks this process, which reads the files as they are now.
@@ -1037,8 +1359,10 @@ const COMMANDS = {
   explain: { run: explain, needsVault: true },
   search: { run: searchCommand, needsVault: true },
   'next-id': { run: nextIdCommand, needsVault: true },
+  board: { run: boardCommand, needsVault: true },
   lint: { run: lintCommand, needsVault: true },
-  stats: { run: stats, needsVault: false },
+  stats: { run: statsCommand, needsVault: false },
+  doctor: { run: doctorCommand, needsVault: false },
   snapshot: { run: snapshot, needsVault: false },
   serve: { run: serve, needsVault: false },
 };

package/skills/sw-init/scripts/init.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Scaffolds docs/ as a Superwiki vault. Safe to re-run: user content is kept, tool files are
 // replaced with this version, and the report says which was which.
+import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +12,7 @@ const MANAGED_BLOCK = /<!-- sw:start[\s\S]*?<!-- sw:end -->/;
 // What a vault consists of at the top of docs/. Anything else there belongs to someone else.
 const VAULT_ENTRIES = ['index.md', 'log.md', 'raw', 'wiki', 'tasks', 'plans', 'viewer.html'];
 const ROLES = ['plan', 'implement', 'review'];
+const NEW_INDEX = '# Index\n\n## Wiki\n\nCatalog of the wiki: one line per page, `- [[file-name]]: summary`, grouped by type.\n';
 
 const HELP = `init.mjs [--root <dir>] [--tasks | --no-tasks] [--areas "M=Mobile,B=Backend"]
 
@@ -116,7 +118,7 @@ function writeVault(docs, tasks, report) {
   }
 
   const today = new Date().toISOString().slice(0, 10);
-  report.keep(join(docs, 'index.md'), '# Index\n\nCatalog of the wiki: one line per page, `- [[file-name]]: summary`, grouped by type.\n');
+  report.keep(join(docs, 'index.md'), NEW_INDEX);
   report.keep(join(docs, 'log.md'), `# Log\n\nAppend-only. Entry format: \`## [YYYY-MM-DD] kind | title\`.\n\n## [${today}] init | Superwiki vault created\n`);
 
   // The viewer snapshot and the local server's address are per-machine and regenerated on demand.
@@ -128,6 +130,18 @@ function writeVault(docs, tasks, report) {
   }
 }
 
+// The task list in index.md is the one part of that file the tool owns. The vault's own CLI
+// writes it, so an upgraded vault gets the list in the format of the version just installed.
+function writeTaskBoard(docs, report) {
+  const index = join(docs, 'index.md');
+  const cli = join(docs, '.sw', 'sw.mjs');
+  if (!existsSync(cli)) return; // already reported as missing
+  const before = readFileSync(index, 'utf8');
+  const run = spawnSync(process.execPath, [cli, 'board', '--docs', docs], { encoding: 'utf8' });
+  if (run.status !== 0) return report.line('note', `the task list in docs/index.md was not written: ${run.stderr.trim()}`);
+  report.line(readFileSync(index, 'utf8') === before ? 'unchanged' : 'updated', 'docs/index.md (task list)');
+}
+
 function writeAgentRules(root, tasks, report) {
   const block = schemaBlock(tasks);
   const agentsPath = join(root, 'AGENTS.md');
@@ -174,6 +188,7 @@ function main(argv) {
   const hadTaskFiles = !previous && existsSync(join(docs, 'tasks'));
   const report = createReport(root);
   writeVault(docs, tasks, report);
+  if (tasks) writeTaskBoard(docs, report);
   const config = buildConfig(previous, { root, tasks, areas: options.areas });
   report.write(configPath, JSON.stringify(config, null, 2) + '\n');
   writeAgentRules(root, tasks, report);

package/skills/sw-lint/SKILL.md

@@ -17,6 +17,7 @@ Two passes. The first is a script and costs almost nothing. The second reads pag
 
    | Finding | Fix |
    |---|---|
+   | `stale-board`, `missing-board` | `node docs/.sw/sw.mjs board`: it rewrites the task list in `index.md` from the task files. Never edit that list by hand |
    | `not-in-index` | add `- [[page]]: summary` to `index.md`, using the page's `summary:` |
    | `missing-field` `summary` | copy it from the page's line in `index.md`; if there is none, read the page and write it |
    | `missing-field` `type` | read that page, write the field |

package/skills/sw-plan/SKILL.md

@@ -14,7 +14,10 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
 1. **Pick the task.**
    - Id given: `node docs/.sw/sw.mjs check <ID>`, then read `docs/tasks/<ID>.md`. Status `done` or `cancelled`: stop and ask what the user wants. A plan already exists: this run revises it; say so. Open deps do not prevent planning.
    - No id, existing work: `node docs/.sw/sw.mjs ready`, and let the user choose.
-   - New work: agree on title, area and dependencies with the user, get the id from `node docs/.sw/sw.mjs next-id <AREA>`, and write `docs/tasks/<ID>.md` from `docs/.sw/templates/task.md` with `status: todo`, a "Goal" and a "Done when" list. Append `## [date] task | <ID> created` to `docs/log.md`.
+   - New work: agree on title, area and dependencies with the user, and get the id from `node docs/.sw/sw.mjs next-id <AREA>`. Then:
+     - write `docs/tasks/<ID>.md` from `docs/.sw/templates/task.md` with `status: todo`, a "Goal" and a "Done when" list;
+     - append `## [date] task | <ID> created` to `docs/log.md`;
+     - run `node docs/.sw/sw.mjs board`, so the task list in `index.md` shows it.
 2. **Does it need a plan?** Judge from the task file alone. A task is small when all of these hold: one area, three "Done when" items or fewer, nothing left open in its notes, and the change it describes is confined to a few files. A small task needs no plan: say so and offer `sw-implement <ID>` directly. Go on with planning only if the user wants a plan anyway, or the task is not small.
 3. **Clarify.** Ask the user only what the task file leaves open about scope or intent, one question at a time, each with your recommendation. Add the answers to the task's "Notes" now. Do not read code to find questions; the planner surfaces the technical ones. Skip this when nothing is open.
 4. **Dispatch the planner.** Its prompt is: the task id, today's date, the project root if it is not your working directory, and any feedback from an earlier round. It writes the plan file as a draft and returns a short message.
@@ -36,7 +39,7 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
    - in the area guide, if `node docs/.sw/sw.mjs explain <ID>` names one, the planner's `Guide:` lines, one line per fact;
    - in `docs/log.md`, a new entry `## [date] plan | <ID>`, in the layout the log's last entries use.
 
-   Then run `node docs/.sw/sw.mjs lint`.
+   Then run `node docs/.sw/sw.mjs lint`. If it reports `stale-board`, a task's title, milestone or dependencies changed along the way: run `node docs/.sw/sw.mjs board`.
 7. **Stop.** Do not start implementing. Tell the user the plan is approved and that sw-implement `<ID>` runs it.
 
 ## Common mistakes
@@ -46,3 +49,4 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
 - Editing the plan yourself. If something in it is wrong, send it back to the planner.
 - Setting the task to `in-progress`. Planning does not change status.
 - Planning several tasks in one plan file. One task, one plan; shared design goes to a `type: decision` wiki page that the plans link.
+- Adding the new task to the list in `index.md` by hand. `board` writes that list from the task files.

package/skills/sw-stats/SKILL.md

@@ -24,7 +24,7 @@ It reports the session it runs in. For another session of this project, add `--s
    | --- | --- |
    | one agent's `sent` is most of the total | which agent, and its share. That is where the session's cost is |
    | an agent's `peak` is several times its `first` | its context grew during the work; `steps` times a large context is what makes `sent` large |
-   | `first` is large for `main` | the session starts heavy before it reads anything: rules files, plugins and tool definitions. The tool's own context command shows what fills it |
+   | `first` is large, for `main` or for the subagents | every agent starts heavy before it reads anything: rules, memory, and the lists of skills and tools. sw-doctor shows what fills it and what can go |
    | `cached` is well below the others for one agent | much of what it sent was not served from the cache, which costs more per token. Long pauses do that |
    | `main` has many `steps` or a `peak` far above its `first` | work is running in the main session that a subagent could do in a clean context |
 
@@ -36,7 +36,7 @@ So that you can answer a question about them:
 
 - `steps`: model requests. `tools`: tool calls. `min`: minutes between the agent's first and last record.
 - `first`, `peak`: tokens sent with the first request and with the largest one.
-- `sent`: tokens sent, summed over every step. A step re-sends the whole context, so this is far larger than `peak`.
+- `sent`: tokens sent, summed over every step. A step sends the whole context again, so this is far larger than `peak`.
 - `cached`: the share of `sent` that was read from the cache.
 - `output`: tokens the model wrote.
 - `-`: the tool's record does not hold that number.