A blueprint for generating a hub

guides/approach-an-unknown-system.md is the protocol an agent follows inside a phase: collect, classify, reduce, write front matter, write the head by hand, dry run to a fixpoint, measure with a client agent, loop. guides/test-loop.md is the measurement — the fifteen steps, the label, the pass, the server-side match.

This guide is neither. It is the project shell around them: phases, the record each one leaves, the gate out of it, who does the work, what it costs, and what makes it stop. It exists because this hub was built in the wrong order once and the loop measured the cost of that, so the order is now a plan rather than an instinct.

Nothing in this guide is restated from the two guides above. Read this to plan a generation; read those to carry one out.

0. The one lesson the whole plan is built around

Six good documents were written before the one document a newcomer is told to read first was correct. The loop's reading: _boot/START.md instructed five calls of which one worked, and its "start here for the surface itself" pointer led to an eighteen-tool design blueprint rather than a description of the six served tools (tracking/backlog/hub.md items 52 and 53).

Fixing the door, and nothing else, produced the first measured improvement in a newcomer's path rather than only a larger corpus: instructed calls 1 of 5 → 6 of 6, the blueprint the largest single read of the run → never read, its replacement answering the same question at 37 percent of the cost, and the client's own would_boot_unaided false → true (docs/commander/LOOP-LOG.md, the N1 and N2 rows).

So: the entry document comes before the corpus, and the generated half of it comes from a generator, not from prose.

1. The nine phases, 0 to 8

#	phase	the record it leaves	the gate out of it
0	Charter and bounds — the system, the audience, the bounds, and the content licence	a revision note in `tracking/roadmap/`, committed before any code, in the shape of the Semarchy migration note: the inventory, the arithmetic, the bounds, and what it deliberately does not decide	Spec first. The note is committed before the collector runs. `rights.hub_content_license` defaults to `null` and public visibility is refused until an owner declares a value from `rights.hub_license_allowed` — D27's one precondition
1	Collect — mirror the sources into a non-indexed holding area; record every origin as you go	a file census with counts and bytes per lane	The bounds arithmetic. The census lands inside `import.max_files` (2,000) and `import.max_bytes` (50 MiB), or the note says how it will
2	Classify onto the spine — map every surviving document onto the Part N skeleton and assign facets	the manifest, plus a per-document justification table in the hub's README with a companion table of what is deliberately left out	No unjustified document. Every file the runner stages has a row; every row's spine path exists
3	Write — head first — the hand-written head before any body, then the authored documents	a document set with the full front-matter contract and a `provenance` block per file naming the source commit, the spec revision and the records	Head under cap, every instructed call served. Head tokens below `boot.handwritten_max_tokens`, and the instructed-call count matching the served list
4	Generate — everything a client could read from the wire comes from a generator with a `--check` drift mode	the generator's source, its test holding that no figure is typed, and its `--check` cell in the suite	`--check` green on the committed tree
5	Import to a fixpoint — dry run on a private cluster, fix refusals, real run, re-run	the runner's own output in the delivery record: `staged N (M mapped, A authored)`, the per-entry verdicts, the derived fields, both runs' counters	The fixpoint: `0 created, 0 changed, N unchanged` with the same `START.md` digest, compared real-run to real-run (a dry run's digest can never be the real run's)
6	Measure with a client agent — one labelled run of the committed prompt, by an agent with the prompt and nothing else	a run record, a usage report, and one row in the loop log naming the change since the previous run	The row is complete and the match holds: audit rows matched equals the labelled call count
7	Change the content, not the build — close MEDIUM and above in the round, file the rest with a reproducer	backlog items with dispositions, and the next loop row reading the change against its effect	A measured improvement in a newcomer's path, not only a larger corpus
8	Promote — declare the licence, run the standup pass, then make the hub public	the delivery note, and the build document's coverage rows updated	Operator-hand. Visibility, licence and DNS are the owner's acts

2. The roles

role	owns	the discipline that applies
Collector	phase 1: the mirror, the census, the origins	records only, no write to the hub; never signals a process it did not start
Classifier	phase 2: the spine mapping, the facets, the manifest, the justification table	deduplicate by content hash before classifying — reduction is a classifier's output, not an importer's
Writer	phase 3: the head first, then the authored documents	docs only, so no review under lean mode; proposals marked in place where not derived
Generator author	phase 4	it is code, so it is reviewed; no typed figures, held by a test over the generator's own source; owns the re-import
Client-agent tester	phase 6: one labelled run, reporting in a fixed shape	no repository access — it must learn the surface from the surface, or the measurement is about the agent and not the hub
Orchestrator	the phase boundaries, the gates, the ledger rows, the loop log	never approves its own work; a fresh session per phase from a written handoff; may build a fix of five files or fewer itself

Two lanes at most, and only across disjoint surfaces. A collector and a writer on the same hub are not disjoint.

3. The budget, in the units the delivery tuning report measures

unit	value	status
a writer or assessor document set (no review)	0.23M to 0.30M subagent tokens, 14 to 29M cache-read, 20 to 30 minutes	measured, three observations
one client-agent loop run (fifteen steps, the match, the usage report)	about 0.25M subagent tokens, 10 to 14M cache-read, 25 minutes	measured, four observations within about 4 percent
a reviewed generator slice	about 0.7M to 0.86M end to end	measured as a service slice, borrowed — not measured for a generator
a collection phase	0.2M to 0.3M	proposal
a classification phase	0.2M to 0.3M	proposal
a whole first generation, phases 0 to 8 with one loop run	1.6M to 2.4M subagent tokens	proposal, derived by adding the units and never measured end to end

The grain is tracking/metrics/ledger.jsonl (one row per closed item) and the authored text is tracking/metrics/report/tuning-curated.json. Subagent tokens are input + output

cache-write of the agent's own turns; cache-read is what moves the usage meter.

4. Acceptance — the loop log's own columns

A generation is accepted when a single loop-log row can be filled with no empty cell and:

MUST — all of them.
MUST-NOT fired — zero.
SHOULD — all, or a named row that mismatches with its mechanism explained.
audit rows matched — equals the labelled call count.
documents served — every row is this hub's; the store column has one distinct value.
findings — no MEDIUM open against the hub's own content.
change since — names the content or build change, and the row is read against the

previous row.

Plus the client's own would_boot_unaided reading true, which is the most compressed statement of whether a hub works.

5. The four controls that keep generations consistent

The standard. reference/standard/hub-standard.md, reference/standard/open-standard.md,

guides/skill-packs.md, guides/sdk-and-transport.md, guides/test-loop.md and guides/approach-an-unknown-system.md. A new hub cites them; it does not restate them. Their provenance blocks name the spec revision, so a generation can say which revision it was built against.

The generator. Anything derivable from the wire or the tree is generated, with a

--check drift mode in the suite. This is what stops a hand-typed count from drifting into every future hub.

The re-import rule. A slice that changes a generator owns the re-import, or a gate

checks that the hub's generated documents match the tree's generator. Without it a release note claims closures a client cannot see: measured once, on three of five.

The loop log. One row per labelled run, with a change since column. It is the only

artifact that forces a content change to be read against its effect rather than its intent.

6. What is operator-hand in every generation

The licence declaration and public visibility; DNS and certificates; the control plane's test pass, which no agent can award today; and the deployment switch itself.

7. What in this guide is a proposal

The collector and classifier phase budgets, and the whole-generation figure: all

derived or anchored on a single observation of a different shape, never measured.

Phases 0, 1, 2 and 8 as written. They are the shell proposed around

guides/approach-an-unknown-system.md's steps, and that guide already marks its generic protocol as unproven. Nothing here changes that.

That this plan generalises past the one hub it was derived from. It has produced exactly

one hub, and the loop has measured four runs against it.

Next reads

guides/approach-an-unknown-system.md — the protocol inside the phases.
guides/test-loop.md — the measurement, step by step.
reference/standard/hub-standard.md — the spine, the front-matter contract per shape,

the boot document and its tiers, and the order an agent reads in.

guides/bootstrap-a-hub.md — the workflow this hub's own bundle was imported with.
reference/cuppy/build.md — what this deployment serves, and the distance from what is

specified.