docs: rewrite the MAIN repository README — the NetScript entry point, absolute quality bar (multi-lane pipeline: agy research → Opus swarm materials → Fable 5 high redaction → Sol xhigh adversarial)

[rickylabs]

Lands AFTER #814 and #815 (it links into the reworked package READMEs and must not contradict them).

The root README.md is the single most-read document in the project — the first thing every evaluating engineer, contributor, and agent sees. It must meet an absolute bar: the strongest READMEs shipped by major frameworks, not just "good for a beta".

Owner-ratified pipeline (2026-07-17) — four lanes, in order

1. Deep research — Antigravity agy CLI (Gemini 3.5 Flash, extended thinking), the research_extraction lane: sweep the best-built READMEs of major libraries/frameworks (candidates: Deno/Fresh, Astro, Bun, Vite, Remix/React Router, Tauri, Supabase, tRPC, Nest, Laravel, Rails — final list from the criteria) and extract what makes them work: structure, hook density, diagram usage, quickstart friction, ecosystem presentation, social proof placement. The research criteria are authored first by a Fable 5 · high agent (what to look for, how to score, what NetScript specifically needs from an entry point) — the researcher executes against those criteria, never freestyles.
2. Materials swarm — Claude Opus 4.8 · high sub-agents: deep-dive NetScript internals + docs site to surface everything the writer needs, each agent owning a domain (runtime/services model; plugins ecosystem; CLI surface incl. the full-coverage story; agentic combo MCP×skills×CLI — the flagship differentiator; Aspire orchestration + telemetry; deploy targets; docs/tutorial map; honest current-state: what's beta, what's stable). Output: fact sheets with source citations (file/deno doc/docs-page), verified claims only.
3. Redaction — Fable 5 · high writes the README from the research findings + fact sheets. Requirements: a hero section that says what NetScript IS in one breath and why it exists in the next; the agentic story surfaced as the flagship; a real <5-minute quickstart (every command executed before landing); one clean architecture mermaid; an ecosystem map (packages/plugins table linking the docs: rework every package README to the public-introduction standard (Fable 5 lane — high for flagships, low for refreshes) #815 READMEs); docs/tutorials entry points; project status stated honestly (pre-release line, what changes at 0.0.1); zero internal vocabulary; tagline conventions respected.
4. Adversarial pass — Codex Sol · xhigh: hostile read for hallucinated claims/verbs/flags (execute everything), overpromising vs the shipped truth, broken/missing links, inconsistency with docs(mcp): rewrite the @netscript/mcp README as a true public-facing introduction (Fable 5 high) + verify full docs-site coverage of the MCP surface #814/docs: rework every package README to the public-introduction standard (Fable 5 lane — high for flagships, low for refreshes) #815 READMEs and the docs site, and "does the quickstart actually work on a clean machine" (run it).

Fix cycles per the doc-audit pipeline (same generator session resumed); final Fable polish is the redactor itself. Gate log + evidence per lane in the run dir.

Acceptance

• Research criteria doc + comparative findings artifact committed to the run dir (not the repo README).
• Every claim in the README traceable to a fact-sheet citation; every command executed on a clean checkout.
• Quickstart proven end-to-end (fresh clone → running app) within the stated time envelope.
• Consistency check against docs(mcp): rewrite the @netscript/mcp README as a true public-facing introduction (Fable 5 high) + verify full docs-site coverage of the MCP surface #814/docs: rework every package README to the public-introduction standard (Fable 5 lane — high for flagships, low for refreshes) #815 outputs and the docs site — zero contradictions.
• Sol xhigh adversarial PASS; docs:links + readme/tagline gates green; no internal wording.

Blocked by #814, #815.

[rickylabs]

Acceptance boxes checked with executed evidence (PR #862, head after CI reset):

• Research criteria + comparative findings committed to the run dir — criteria.md (14-candidate corpus, D1–D10 rubric) + findings.md (57KB agy sweep) in slices/g14-816-main-readme/, never in the repo README.
• Every claim fact-sheet-traceable; every command executed — claim→citation map in the slice worklog; all commands executed on fresh scaffolds across 4 adversarial cycles (final PASS at 67c1d0d, re-verified through 86939bf).
• Quickstart proven end-to-end — full clean-machine run recorded; timing promise removed after the adversary's honest finding (product flake filed as scaffold: netscript db init can block indefinitely on an Unhealthy-but-Running Postgres resource (clean-machine quickstart flake) #863); readiness step printed.
• Consistency vs docs(mcp): rewrite the @netscript/mcp README as a true public-facing introduction (Fable 5 high) + verify full docs-site coverage of the MCP surface #814/docs: rework every package README to the public-introduction standard (Fable 5 lane — high for flagships, low for refreshes) #815 + docs site — verified across the audited 36-page README set and the rebuilt homepage (531-file site build green).
• Sol xhigh adversarial PASS; gates green; no internal wording — Lane-5 trail in adversarial.md (2 escalations resolved, final PASS); docs:links/tagline/mermaid/wording all green; owner de-internalization + repositioning applied; Kimi K3 final pass zero-edit.

— beta-11 supervisor (owner-approved merge in flight)