---
cuppy_hub: cuppy
cuppy_path: guides/hub-generation-blueprint.md
cuppy_section: docs
cuppy_doc: 3DMF-6TS1
cuppy_doc_uuid: 95f16478-a7f6-4ed9-9aa6-b26842d08b14
cuppy_permalink: https://cuppy.io/cuppy/d/3DMF-6TS1
cuppy_version: 1
cuppy_updated: 2026-10-17T06:32:45.511Z
cuppy_canonical: https://cuppy.io/cuppy/docs/guides/hub-generation-blueprint
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: 9db67c363aba9c752163b1306b1ec6fceeec315847d52f43b4328ecb9c32bb0c
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---

# 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

1. **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.
2. **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.
3. **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.
4. **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.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 18 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/cuppy/
<!-- /cuppy -->