The README shipped with the first @netscript/mcp publish (v0.0.1-beta.10) is accurate but fails its actual job: it reads internal (implementation-first prose, layering talk), buries the flagship story, and doesn't serve as a public introduction that hooks an evaluating engineer and hands deep-dives off to the docs site.
Lane rule (owner-ratified 2026-07-17): package-README authoring is a Claude · Fable 5 lane — high for flagship/new packages like this one. Accuracy gates still apply (every command verified against the shipped public binary; doc-audit pipeline applies — the Sol audit is opposite-family to a Fable generator, so the pipeline composes correctly).
Rewrite requirements
- Catchy, professional introduction — what an agent can DO with a running NetScript app in the first three sentences; positioning in one paragraph (why an app-semantic MCP beats generic log-scraping; complements Aspire's MCP).
- Flagship features first: benefit-first bullets (13 token-bounded tools; framework-semantic trace intelligence; default-deny CLI gate; one-command install via
netscript agent init; version-locked CLI×SKILL×MCP surface).
- Mermaid architecture diagram: agent host ↔ stdio ↔
netscript agent mcp ↔ (telemetry port / docs corpus / CLI gate) ↔ running app. Verify rendering on GitHub; degrade gracefully on jsr.io if unsupported.
- Major API surface: compact tool-catalog table (name → one-line purpose), the two exports (
., ./cli), nothing more — depth belongs to the site.
- 1–2 real examples: the
agent init flow and one "ask the agent" transcript-style example; every command executed against the shipped binary before landing.
- Deep-dive delegation: a Docs section linking the docs-site MCP reference (13 tools), agent-tooling page, and the jsr.io API docs — links verified live and current.
- Keep the JSR tagline ≤250 bytes; keep
@<version>-placeholder pinning conventions from the current README; zero internal vocabulary (no archetype/layering/process talk).
Docs-coverage audit (same issue)
Verify the docs site fully covers the shipped MCP surface and fix gaps: all 13 tools with input/output contracts and truncation semantics; agent init per-host behavior; agent mcp flags; the command-policy allowlist model (what's denied and why); docs-corpus default + --docs-root; troubleshooting (doctor interpretation). Anything undocumented is a gap to close in the same PR (docs lane).
Acceptance: README passes the production-standard check + doc-audit pipeline (Sol audit, executed evidence, Gate log) + Fable-medium polish; coverage gaps enumerated and closed; no regression in tagline/pinning gates.
Part of the beta.11 docs quality track (see the all-packages README rework issue).
The README shipped with the first
@netscript/mcppublish (v0.0.1-beta.10) is accurate but fails its actual job: it reads internal (implementation-first prose, layering talk), buries the flagship story, and doesn't serve as a public introduction that hooks an evaluating engineer and hands deep-dives off to the docs site.Lane rule (owner-ratified 2026-07-17): package-README authoring is a Claude · Fable 5 lane —
highfor flagship/new packages like this one. Accuracy gates still apply (every command verified against the shipped public binary; doc-audit pipeline applies — the Sol audit is opposite-family to a Fable generator, so the pipeline composes correctly).Rewrite requirements
netscript agent init; version-locked CLI×SKILL×MCP surface).netscript agent mcp↔ (telemetry port / docs corpus / CLI gate) ↔ running app. Verify rendering on GitHub; degrade gracefully on jsr.io if unsupported..,./cli), nothing more — depth belongs to the site.agent initflow and one "ask the agent" transcript-style example; every command executed against the shipped binary before landing.@<version>-placeholder pinning conventions from the current README; zero internal vocabulary (no archetype/layering/process talk).Docs-coverage audit (same issue)
Verify the docs site fully covers the shipped MCP surface and fix gaps: all 13 tools with input/output contracts and truncation semantics;
agent initper-host behavior;agent mcpflags; the command-policy allowlist model (what's denied and why); docs-corpus default +--docs-root; troubleshooting (doctor interpretation). Anything undocumented is a gap to close in the same PR (docs lane).Acceptance: README passes the production-standard check + doc-audit pipeline (Sol audit, executed evidence, Gate log) + Fable-medium polish; coverage gaps enumerated and closed; no regression in tagline/pinning gates.
Part of the beta.11 docs quality track (see the all-packages README rework issue).