The ordered path from a task description to a connected node

[makseq]

Why

Everything an agent needs to build somebody's node is already here — the contract, the recipe, a correct reference, a black-box harness, the operational steps. What was missing is the order. The orchestrator's "Create external node" button hands the user's own coding agent a prompt that says: clone this repository, read its docs, build the node, come back with an image digest. An agent arriving that way had to infer the sequence from five documents that each assume you already know why you are reading them.

What this adds

One section, "Building your own node from this template", in CLAUDE.md — the file Claude Code reads without being asked — plus a one-line pointer from README.md. Six numbered steps: read the documents, edit node.py, prove it with the harness, take the digest, write the README the human gets, hand it back.

Link, not copy. Every step points at the document that owns the detail and restates none of it. A rule written down twice goes stale in one of the two places, and the stale copy is the one somebody is reading. The only new normative claim about the platform is one BEHAVIOUR in step 6, about where a digest is pasted and what the reply prints.

Step 3 is the one that matters, because after step 2 the harness is building and judging the author's container, not ours. It states the bar honestly rather than pleasantly:

• --red-for-real can only differ from the plain run while some test carries expected_red_until_fixed, and none does today;
• only the conforms_today group has node.py as its subject, and most of it rests on basis_reference_quality or basis_our_policy — bases the contract permits a node to fail;
• several of those tests assert this node copies its inputs to its outputs, so a node that transforms them goes red honestly. A red test there is a question, not an instruction.
• CONFORMANCE-BASELINE.md is named for what it is: a measurement of the reference node, not a prediction about anybody else's.

Also, in passing

docs/OPERATIONS.md told the reader that a denied pull of the agent image meant the package had not been made public yet, and to ask an admin to publish it. The package is public now — an anonymous token against ghcr.io returns the manifest with a 200 — so no docker login is needed and the paragraph said the opposite of the truth. Corrected.

Known-stale and deliberately NOT fixed here

.github/workflows/conformance.yml's header still explains why CI is green by saying "Twenty tests are known to fail against node.py as it stands" and "Six of the twenty are contract violations". Both were true before node.py was repaired and are false now — that commit updated every document except this one. The token pushing this branch has no workflow scope, so the fix has to come from a push that is allowed to touch .github/workflows/.

Verification

• python -m pytest → 128 passed, 1 skipped in 138s, on a real Docker daemon (28.4). The skip is the verbatim-citation check, which needs a checkout of the orchestrator.
• python -m pytest --collect-only -q --print-labels → exit 0, 129 collected, so every test still declares exactly one group and one basis. Split today: 41 conforms_today, 67 subject_is_platform, 21 harness_self_test; 82 basis_contract, 24 basis_reference_quality, 23 basis_our_policy.
• Every relative link and heading anchor added by this change resolves, checked mechanically.
• The public-image claim was verified against ghcr.io directly, with no credentials.

🤖 Generated with Claude Code