fix(cli/agent-init): root AGENTS.md is the only guaranteed-read file and teaches diagnostics but not how to build — and never links the app-level guide

[rickylabs]

Summary

The root AGENTS.md written by agent init is the one file every coding agent loads by default.
It currently teaches diagnostics only — skills, find_guidance, doctor, telemetry, drift
receipts — and says nothing about how to build with NetScript. The file that does teach the
architecture, apps/<app>/AGENTS.md, is never referenced from it.

The result is that an agent starts with a complete picture of how to investigate NetScript and no
picture of how to use it, and the guidance that would fix that sits in a nested file it is never
told about.

Evidence

Fresh 0.0.6 scaffold + agent init --host all --with-docs, and a Wave 7 build run on it
(Claude Opus 5, max effort, ~1.5h, 7 commits).

Root AGENTS.md — 1,655 bytes, loaded by default. Mentions of build surfaces:

Symbol	Occurrences
definePage, withResource, staleTime, withForm	0
defineRouteContract, query factories, dehydration, optimistic	0
contract → service → SDK → page flow	0
pointer to apps/<app>/AGENTS.md	0

It is entirely find_guidance / search_docs / doctor / aspire otel / drift-receipt guidance.
That content is good — it is simply only half the job.

App-level apps/<app>/AGENTS.md — 2,073 bytes, not referenced from root. This file is genuinely
strong: it names the canonical local examples to inspect, gives the MCP path
(list_api_services → list_service_operations → get_operation_schema) before hand-writing a request,
and lays out a five-step default architecture — contract → client and query factories in the
resource-local (_lib), withResource + definePage layers, QueryIsland + useMutation with
canonical query keys, live stream where needed, withForm for route-bound mutations — plus the three
ui:add verbs and an explicit copy-versus-delete rule.

What the run actually did, having loaded the root file and not followed the app file:

• (_lib) used in 0 files (the app guide says query factories live there)
• ui:add invoked 0 times (the app guide lists three verbs)
• NetScript MCP calls: 0 (both files point at find_guidance)
• Deleted routes/(_components)/dashboard-view.tsx — the first file the app guide says to inspect
• Ended with 0 route contracts, 0 dehydration/prefetch, ~0 optimistic UI, and one dead partial

CLI adoption was otherwise strong (25 db, 11 contract, 6 plugin install), so this is not an
agent that ignored tooling in general — it followed what it was given and never saw the rest.

Why this is high leverage

AGENTS.md is the only file with a guaranteed read. Everything else — offline docs, MCP, /design,
the app guide, the scaffold examples — depends on the agent choosing to go there. Six consecutive
measured runs across waves 4–7 have shown near-zero discovery of exactly those optional surfaces.
Fixing the guaranteed file is strictly cheaper than trying to make six optional ones more attractive.

Target contract

Root AGENTS.md should, in addition to today's diagnostics content:

• state the architectural spine in a few lines — database-derived schemas → contract → service →
  typed SDK and query factories → definePage composition → islands — so an agent knows the intended
  shape before it invents one;
• link apps/<app>/AGENTS.md explicitly as the build guide for app work, and say that it exists;
• name the ui:add verbs as the way to create routes, islands and tables;
• keep it short. This is a pointer surface, not a tutorial — the depth belongs in the MCP and the
  offline docs, both of which already have it.

Acceptance

• A fresh scaffold's root AGENTS.md names the contract → service → SDK → page spine
• It links apps/<app>/AGENTS.md and states what that file is for
• It names at least the ui:add route/island verbs
• A measured unfamiliar-agent smoke shows non-zero ui:add or non-zero MCP find_guidance
  usage, or an explicit recorded rejection — silence is a harness failure, not an agent failure
• No duplication of MCP/offline-doc content; root stays a pointer surface

Boundaries

Complements #1672 (generated guidance must teach the Deno toolchain) — same file, different gap: that
issue is about the runtime's tooling, this one is about NetScript's own architecture and the
unreferenced app-level guide. Does not change the MCP corpus (#1201) or the scaffold's example routes
(#1333); both are fine and both are already correct.

Provenance

Wave 7 run 3 (ceiling probe, 0.0.6), evidence in
agent-posts/wave-7/runs/PROCESS-LEDGER.md. Filed 2026-08-17.

[rickylabs]

Scope refinement (owner, 2026-08-17): one root file, rewritten from scratch

Two corrections to the original framing, both verified on a fresh 0.0.6 scaffold.

1. There should be exactly ONE AGENTS.md, at the root

agent init currently writes two:

AGENTS.md                      1,655 B   ← loaded by default
apps/<app>/AGENTS.md           2,073 B   ← the actual build guide

Nested AGENTS.md files are not how the convention works — agents load the root file, and a
subfolder file is not reliably read. So the better guidance is sitting in a location that is
structurally unreachable by default, and the original proposal in this issue (make root link to it)
is the wrong fix.

Correct fix: consolidate into a single root AGENTS.md, rewritten from scratch, and drop the
nested file. Everything worth saying belongs in the one file with a guaranteed read.

2. It must point at all three surfaces: skills, MCP, and CLI

Today's root file covers MCP well (find_guidance, search_docs, get_doc, doctor,
get_app_status, analyze_*) and names the installed skills in a single sentence. It covers the
CLI only for diagnostics (netscript plugin doctor), and the architecture not at all.

The rewritten file should carry, briefly:

• How to build — the spine: database-derived schemas → contract → service → typed SDK and query
  factories → definePage composition → islands. A few lines, not a tutorial.
• Skills — that they exist, what each is for, and when to invoke them. Naming them in a
  sentence has not been enough (see the measurement below).
• MCP — as today, with find_guidance first. This part already works.
• CLI — the build verbs, not just the diagnostic ones: contract, service, db, generate,
  and the ui:add route/island/data-table verbs.

Measurement supporting this

Wave 7 run 3, Claude Opus 5 at max effort, ~1.5 h, 9 commits, on this exact scaffold:

Surface	Named in root AGENTS.md?	Used
MCP find_guidance	yes	0
Skills (5 installed, named in one sentence)	yes, in passing	1 call
ui:add verbs	no	0
Architecture (definePage, contracts, query factories)	no	0 route contracts, 0 dehydration
netscript db / contract / plugin install	yes	25 / 11 / 6

The pattern is consistent: what the root file names, the agent uses; what it omits, the agent never
finds. Being named in passing (skills) sits in between and produced one call in ninety minutes.