Move the levers.
Watch what lands.

Four levers on the left; the window on the right shows exactly what arrived, from which layer, and what exists but cannot be reached. Every line has a WHERE FROM button naming the file it came from.

Where the numbers come from

Some fences cut
one at a time.
Some cut everything.

A helper's file is the only layer that takes things away — but it doesn't fence every kind of thing the same way. That difference is the one you need to design around.

A fenced helper walks into the strategy seat folder — what it gets, item by item

Where a helper
comes from — and what it arrives with

A helper is a file: a name, a description, a tools line, a model, its instructions. That file is its identity. Where the file sits decides who can see it. Where it is launched decides what it knows. Those are three different things, and every confusion about helpers is two of them being read as one.

The four places a helper's file can come from — every row tested

~/Projects/strategy-seat $ claude --agents '{"probe-json": {"description": "A probe helper defined inline, for one run.", "prompt": "You are a probe. Your marker is PROBE-JSON-5150.", "tools": ["Read"]}}' --agent probe-json
  (1) marker: PROBE-JSON-5150        ← the identity came from the JSON
  (2) tools: Read only                  ← its fence held
  (3) sees the strategy seat rulebook: yes   ← the equipment came from the FOLDER
  (4) sees the strategy seat memory:   yes

Two verbs, one rule

Universal identity is not universal knowledge

A skill is a file.
The magic is the listing.

Every skill has two required pieces: a name and a one-line description. Everything under that is ordinary written instructions. What the system adds is the listing at boot and a tidy way to load it — nothing else.

---
name: corpus
description: "Use whenever you need information from the operator's knowledge home
  (~/Projects/knowledge-base) — business frameworks, venture facts, the operator profile…"
---

# Corpus — using the knowledge home
1. **Route** — read ~/Projects/knowledge-base/index.md …
2. **Pull** — read wiki/<slug>.md …
3. **Needle** — grep across wiki/ AND raw/ …

Two front-matter lines, then ordinary instructions. The description is the only part a window sees before it decides to load the skill — which makes it the entire routing mechanism.

The four homes — and what each holds on this machine, today

The journey from your folder to a window — and the three places it breaks

Turn the breaks on and off. The first is on because it is true on this machine right now.

The costs, measured

A folder you
switch on as one unit

Think of it as an app. It has a name and a version so the system can refer to it, and room for five kinds of thing — skills are only one of them.

What the files look like — the prototype's, verbatim

{
  "name": "real-estate",
  "version": "0.1.0",
  "description": "A brokerage's listing and transaction craft…",
  "author": { "name": "Harborline Realty (illustrative example)" }
}

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Read|Write|Edit",
        "hooks": [ { "type": "command",
                     "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/stamp.py\"",
                     "timeout": 10 } ] }
    ]
  }
}

The folder layout is the whole format: .claude-plugin/plugin.json · skills/<name>/SKILL.md · agents/<name>.md · hooks/hooks.json · .mcp.json. Seven files made the prototype.

A second real plugin, installed today — and the scoping rule shown on it

Scope — who pays, and the surprise

The switch and the files — click through the four measured positions

A plugin is two things that are easy to conflate: where its files live and where its switch is. Pick one of each and watch what a window opened in the case folder actually loads — and what goes stale when you edit the source. Every position below was measured with the sample plugin on 30 Aug.

Rules that run,
not rules that are read

A hook is a small program that fires by itself at a fixed moment. It doesn't ask. That makes it the strongest rule you have — and it still obeys the reach rules of wherever it lives.

The moments — and which can say no

The useful subset, not the inventory — the registry holds 31 moments. And a hook isn't only a script: command, prompt and agent kinds exist; the last two let a rule think before deciding.

Where a hook lives decides who it governs — try it

Pick a home. fires never sees it untested

---
name: gm
model: opus
tools: Read, Write, Edit, Bash, Agent(gap-checker, general-purpose), ListAgents, SendMessage, Skill
hooks:
  Stop:
    - hooks:
        - type: command
          command: "~/.claude/hooks/stop-hook.sh"
        - type: command
          command: "~/.claude/hooks/capture-hook.sh"
---

Two things in one frontmatter: the tools line that fences (note Agent(gap-checker, general-purpose) — a roster of exactly two) and the hooks block that travels with the helper into any folder. 27 of your 34 helper files carry a Stop block like this.

Wired on this machine, today

A cabinet on the floor,
one drawer per folder

The right words: each fact is a memory file, they sit in a memory directory, and MEMORY.md is the index. Only the index loads at start; a memory file is opened when its line looks relevant. Cabinet and catalog.

- [strategy seat CLI port](strategy-seat-cli-port.md) — what the strategy seat is; phase-1 (Notion dead, knowledge read-only)
- [System roadmap](system-roadmap.md) — LIVING roadmap at reference/roadmap.md; read on strategy/sequencing
- [Title X vs Title Co](title-x-vs-title-co-distinction.md) — "Title X" (#146) = friend PM favor; NEVER his own Title Co
…  127 lines · 24,864 bytes · one line per memory file · the ONLY part loaded at start

The cabinet and the catalog — the strategy seat store, measured

The wall the index stands against

What memory costs — try it

161 slim files and 161 heavy files cost exactly the same at boot, because only the index loads. Weight is paid per open, by the session that opens it.

Who writes it, and the rules

One window,
one drawer

The rulebook stacks — global, category and project all load. Memory never stacks: a window is handed exactly one memory directory. "User scope" is not a second layer on top of a project drawer; it is the same single slot, filled from a different settings file.

What decides the drawer — highest wins, nothing adds

Read top-down. The first level that names a drawer wins; every level below it is ignored for that window. Only when no level names one does the default apply.

Try the setups — three of your projects, one slot each

Each switch is one real mechanism. Watch which drawer each project is handed, and who decided it. The paths under the switches are example values.

The five channels — the only ways memory crosses a project line

The rulebook,
split into files

A rule is not a new kind of thing. It is a page of the rulebook kept as its own file — .claude/rules/<topic>.md, one topic per file — and loaded exactly like .claude/CLAUDE.md. None existed on this Mac when this page was first written. ⭐ That changed 2026-09-01: ~/Projects/study-project/.claude/rules/claude-code.md is a live always-on rule file. And it carries a measured finding of its own — an HTML comment inside a rule file does not reach the session it governs (19 lines on disk, 16 injected; the missing 3 were a comment block).

Four things that look alike — told apart

What one would look like — an example, not on disk

---
paths:
  - "reference/records/**"
---
# Records
- Every record carries its date in the filename and a `class:` line at the top.
- A count stated in a record is produced by a command, never recalled.
- A record that names a live artifact's version is updated in the same act as the artifact.

Because of the paths: line this would cost the window nothing at launch and arrive only when a record is opened. The same three lines without paths: would load every time, like a page of CLAUDE.md.

A path-scoped rule — where it takes effect, step by step

The rule does not follow the file around. It belongs to a launch folder, watches for a pattern, and lands in the window that reads a matching file — from that moment, for that session.

Sharp edges the vendor documents (added 8/28)

How it could be used on your floor — five candidates, not decisions

Each row is a real folder on this Mac and a rule the floor already carries somewhere always-on. Behind a paths: line it would cost nothing until that kind of file is touched.

Where does a rule go — the decision, in order

Three verbs that get mixed up — and the instrument for each

Every part,
every place

Rows are kinds of moving part. Columns are places. Click any cell for its evidence. Solid green was verified on this machine this week; outlined green is a standard mechanism not exercised here; amber is untested or inconclusive. Five cells that were amber yesterday were tested today.

The scaffolding — click any file to see what it is and what's in it

The real folders on this Mac, with the real contents of the files that matter (structure only where a file holds secrets). Each node names which layer it belongs to.

The matrix — every part, every place

The direction rules — same tree, different answers

Flip one thing.
See what it moves.

Four control panels, one per layer, in layer order — floor, folder, helper, launch. The window below them is reassembled every time you click. The strip under its title says exactly what your last click added and removed. Locked controls tell you which layer actually holds that lever.

Every mechanism,
by purpose

The pages before this one mapped what a window knows and can do. This page adds the layer you named as missing — evaluation, guardrails, verification, observation — and puts every mechanism in one table by the job it does, where it lives, what it costs, and whether it is a request or an enforcement. Sources: the vendor's own pages, read today, plus this manual's measurements.

The nine jobs — vendor names first, one card each, click to see a real example

Everything that shapes a window does one of nine jobs. Each card says what the job is in the vendor's words, where it lives, when it fires, and whether this floor uses it today. The one-word nicknames are ours — memory aids, marked as such.

| Category              | Tokens | Percentage |
| System prompt         | 4.4k   | 0.4%  |
| System tools          | 1.7k   | 0.2%  |
| MCP tools (deferred)  | 115.5k | 11.6% |   ← names only; schemas load on search
| System tools (deferred) | 13.3k | 1.3% |
| Custom agents         | 16k    | 1.6%  |
| Memory files          | 44k    | 4.4%  |   ← CLAUDE.md stack + MEMORY.md
| Skills                | 8k     | 0.8%  |
| Messages              | 4.9k   | 0.5%  |
Tokens: 79k / 1m (8%)

claude_ai_Notion    37 tools   42.4k
claude_ai_Gmail     29 tools   21.0k
github              45 tools   19.2k
brave-search         8 tools   13.1k
workspace-mcp       22 tools   13.0k
playwright          24 tools    6.5k
TOTAL              165 tools  115.3k  — all deferred; loaded only when searched

---
name: home-lead
model: sonnet
tools: Read, Write          ← no Skill (no listing), no Agent (no roster), no MCP tool
hooks:
  Stop: [ stop-hook.sh ]   ← travels with it
---

PreToolUse hook   knowledge-home-guard.py  → DENIES any write into ~/Projects/knowledge-base  (exercised at every boot)
permissions.deny  one rule in ~/.claude/settings.json
sandbox.enabled   false   (the strongest wall, unused)

/goal all tests in test/auth pass and the lint step is clean — or stop after 20 turns

"Stop": [ { "hooks": [ { "type": "prompt",
   "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains\"}." } ] } ]

"Stop": [ { "hooks": [ { "type": "command", "command": "~/.claude/hooks/stop-hook.sh" } ] } ]   ← yours today

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console      # or otlp / prometheus
export OTEL_LOGS_EXPORTER=console
claude
# → claude_code.token.usage{type=input|output|cacheRead…}  claude_code.cost.usage  claude_code.tool_decision{decision=accept|reject}

dispatch    Agent(subagent_type: gap-checker, prompt: "grade this artifact…")     ← fresh context, returns a file
fork        /subtask "verify the three numbers above"                            ← copies the conversation
workflow    parallel(findings.map(f => agent("verify " + f.title)))             ← many children, fixed pattern
schedule    /loop 20m /check-deploy   ·   /schedule "every weekday 6am, run the brief"

~/Projects/strategy-seat/tools/lab/example-marketplace/          ← a marketplace (address book)
  .claude-plugin/marketplace.json                     name: re-lab · plugins: [ real-estate ]
  real-estate/                                        ← the plugin
    .claude-plugin/plugin.json   skills/ (2)   agents/ (2)   hooks/hooks.json   .mcp.json (comps-db)

$ claude plugin marketplace add ~/Projects/strategy-seat/tools/lab/example-marketplace
$ claude plugin install real-estate@re-lab --scope local     → .claude/settings.local.json: enabledPlugins

All nine, as a reference table — knowledge split into its four homes

The vendor's own build order — quoted, not invented

What this research corrected on the pages before it

A driving test
for a tool

An eval grades the tool, never a piece of work — that is a different machine, and you already own it. This page is the whole eval side: what exists, what it costs, and what happened when a session stopped believing the question was closed. Measured 31 Aug – 1 Sep 2026, CLI 2.1.251.

Start here — two questions, one word

That gap is what evals fill. Keeping the two apart is most of the topic.

The three machines — the whole inventory, there is no fourth

Why a delta, not a score

⛔ The defect — the open machine under-reports, and it looks like a bad description

What was run: the same rigged-to-pass control twice in one fresh folder, changing only how many test runs go at once.

t+2s  command files present: 4
  net-sheet-skill-259a47e4.md
  net-sheet-skill-b95fcf52.md
  net-sheet-skill-c3666a31.md
  net-sheet-skill-d748d95b.md
  ↑ same description · four names · each worker counts only its own
  illustrative names. the SCHEME is read from the script's source; these four
  strings are not a captured poll. real, and a genuine hazard — but NOT what
  caused the zeros.

$ bash reference/claude-code/repro-eval-worker-defect.sh
  Both queries name the skill outright. Every run SHOULD trigger.
  WARNING: this contrast has been observed to INVERT (serial fail / parallel pass) on an
  instrumented copy, 2026-09-01. Treat a single result as provisional. The published cause is
  THREE compounding bugs -- see section 8 of evals-measured-2026-08-31.md.

  --- serialized (--num-workers 1) ---   Results: 2/2 passed
  --- parallel   (--num-workers 4) ---   Results: 0/2 passed

Running a real one — and what it costs

The tool writes your first case for you and refuses to do it outside a plugin folder — a guardrail, not an obstacle. Cases live beside the plugin at evals/<case>/prompt.md with graders/*.md; results and an HTML report land under evals/results/<timestamp>/. The no-plugin arm runs by default whenever a plugin resolves — --ablation none turns it off. Six grader kinds ship: regex (match the text) · tool_used · file_exists · tool_order · llm (a model's verdict) · baseline. One case was run both ways, three times each:

The four settings a working suite needs — and what each one silently does when it is missing

Everything above this line was measured on a suite that had a bug in it. A later session built a suite from nothing — a skill, a case that should fire, a case that should not — and found that three graders out of three were faulty, each in a different way. None of them announced it. Each one reported a number. The four settings below are the difference between a suite that measures something and a suite that reports confidently on nothing.

How much the number wobbles — measured on purpose, and it is worse than it looks

The page above retires +0.17 because of this measurement. Here is the measurement itself: three identical batches — same case, same graders, same settings, nothing changed between them — scored +0.67 / +1.00 / +1.00. A spread of 0.33, a third of the whole scale, and the entire spread traces to two grader outcomes out of thirty-six.

How the finding was reached — two of these steps were being wrong

Order matters: each step only makes sense after the one before it. The wrongness is the instructive part.

What is yours to decide — nothing here needs an answer today

$ CLAUDE_CODE_WALNUT_SPIRE=1 claude plugin eval --help

Sourcing — and one correction about method

⭐ Where the vendor's own words are — and the retrieval trap on this exact subject

Lookup

What stops an act —
as opposed to what asks

Instructions ask. Three mechanisms stop: a hook, a permission rule, and the sandbox. They sit in that order, each stronger than the last, and a fenced tools line sits in front of all three. here: sign on the door · doorman · locked door · wall

"permissions": {
  "allow": [ "Bash(git status *)", "Read(**)" ],
  "ask":   [ "Bash(git push *)" ],
  "deny":  [ "Edit(~/Projects/knowledge-base/**)", "mcp__workspace-mcp__send_gmail_message" ],
  "defaultMode": "acceptEdits"
}

Try it — pick an act, set the walls, watch which one catches it

The order is real: the agent's tools line first (if the tool is not held, nothing else is consulted), then any PreToolUse hook, then the permission rules and mode, then the sandbox under every command.

Five moments.
Launch · turn · dispatch · compaction · stop

The third question. Everything on the earlier pages enters a window at one of five moments — and some things leave at one of them. Click a moment.

Why the moment matters more than the place

The window squeezes itself.
What survives is decided by files.

A window's context fills — every message, every file read, every tool result. When it nears the limit, Claude Code compacts: it folds the conversation into a summary and continues from that. Auto-compact is on by default and needs nobody present. The whole question is what comes back after the cut, and the answer is: whatever a file re-supplies.

Try it — fill a window, watch it cut

The levers — vendor names, this Mac's values (30 Aug)

Three things measured on 27 Aug that the docs only imply

A chat is a file.
The window is what you do to it.

Everything the earlier pages assemble lands in one running session. This page is the part that happens inside it — what a session is, where it is stored, how to find it again, the commands you type at the prompt, and how to get out of a screen you did not mean to open. Folded from Part I (the chats manual) plus the vendor's interactive-mode and commands pages, 30 Aug.

What a session is — four facts

The launch and resume commands — click one to see what it does

Find an old chat in three steps: cd into the folder it happened in, then claude --resume · don't know the folder? ls -lt ~/.claude/projects/*/ lists every session across every folder, newest first · once you have the id, claude --resume <id> works from anywhere. Name a session as you start it (claude -n "fridge inventory") or later (/rename) and resume it by name.

Getting out — the keys that close things

The /memory trap of 28 Aug: you opened a CLAUDE.md in the viewer, pressed Ctrl-C, and stayed stuck. The vendor's interactive-mode page settles it:

The commands you will actually type — the vendor's table, curated

Headless, and the flags that change a launch

Accounts — the reason this page has a new address

The folder holds the knowledge.
The plugin does the work.

Your own picture, in the vendor's words: a project (CLAUDE.md, rules, auto memory, the case files) with a plugin switched on for it (subagents, skills, hooks, MCP servers), the plugin sourced from one versioned folder you can switch on in any other project. This page is your architecture-in-progress — the distinction, the avenues, and what the machine measured about each. These measurements change the weight of three of the objections; the choice is still yours — no recommendation is drawn.

The picture, with the four measured facts drawn onto it

What the machine said about your hypothesis — measured 30 Aug

The four avenues — named, with the honest case for and against each

Still open — yours to answer, in the order the briefing put them

Our pictures,
the vendor's words

Every nickname this manual uses, mapped to the term you will meet in the documentation and everywhere else. When you read outside, translate left-to-right; when you read here, the nickname is only a picture.

Used and unused on this Mac — the takeaway

Trust — how each page was settled