docs(root-readme): meta-framework landing README (PR3)

.llm/tmp/run/docs-root-readme/context-pack.md

@@ -0,0 +1,45 @@
+# Context Pack — PR3 root README (docs/root-readme, PR #118)
+
+## Goal
+
+Final docs PR of the "road to JSR publish" topology: author the root `/README.md` as a stunning,
+enterprise-grade, truthful meta-framework landing page. Branch `docs/root-readme` off `main`
+@ `f68fa916` (post PR1 #116 publish-mechanics + PR2 #117 package-README revamp).
+
+## Topology
+
+- PR1 #116 publish mechanics — MERGED (`2e11d655`)
+- PR2 #117 package READMEs + /docs removal — MERGED (`f68fa916`)
+- PR3 #118 root README — THIS (draft)
+- Final: `publish:dry-run` green → release tag push → OIDC `deno publish`
+
+## Branch / upstream landmine
+
+`docs/root-readme` inherited `origin/main` as upstream. NEVER bare `git push` — always
+`git push <auth-url> HEAD:refs/heads/docs/root-readme`.
+
+## Pipeline state
+
+1. **Deep search — DONE.** OpenHands `gemini-3.5-flash`. Output landed:
+   `.llm/tmp/run/docs-root-readme/sota-landing-dossier.md` (347 lines, verified clean — dossier +
+   OpenHands trace only, no lock/source churn). Fast-forwarded to `96063906`.
+2. **Plan → PLAN-EVAL — DISPATCHED (awaiting).** `research.md` + `plan.md` authored + committed
+   (`4bdf9eea`). PLAN-EVAL dispatched to OpenHands `openrouter/minimax/minimax-m3`, 100 iters →
+   PR #118 comment 4793750208 (`plan-eval-dispatch.md`). ON LANDING: read `plan-eval.md`; need PASS
+   before any authoring slice. FAIL_PLAN → fix plan, re-dispatch (2 cycles then escalate).
+3. Author root README (Claude documentation-authoring exception). Not started — GATED on PLAN-EVAL
+   PASS. Locked design in `plan.md`: ASCII hero (A), ASCII arch canvas primary, grouped 6-layer
+   31-pkg map, badges/voice = shipped PR2 convention.
+4. IMPL-EVAL (OpenHands qwen3.7-max, separate session) → merge. Not started.
+
+## Commits
+
+- `fda7f518`: docs(root-readme): PR3 deep-search brief (framework-landing research)
+- `4bdf9eea`: docs(root-readme): PR3 research + plan (locked design, pre-PLAN-EVAL)
+
+## Decisions carried in
+
+- 4 locked publish decisions: align all to `0.0.1-alpha.1` (done); slow types accepted; lock regen
+  allowed (version-driven only); publish via GH Actions OIDC on tag push.
+- Voice doctrine: no "honest/honesty/honestly" or candor/apologetic-alpha framing.
+- Authoritative 31-package map embedded in `deep-search-brief.md`.

.llm/tmp/run/docs-root-readme/deep-search-brief.md

@@ -0,0 +1,137 @@
+use harness
+
+# PR3 Deep-Search Dispatch — NetScript ROOT README (framework-landing) research
+
+You are a **research** agent (OpenHands, `openrouter/google/gemini-3.5-flash`, web-browsing). Your
+job is to produce a single, NetScript-specific dossier that grounds the authoring of the **root
+repository `README.md`** — the front door / landing page for the whole NetScript meta-framework.
+This is PR3 of the "road to JSR publish" program; the bar is **stunning, enterprise-grade, and
+truthful**. You are NOT authoring the README here — produce research, skeletons, and a checklist.
+
+## SKILL
+
+Activate and follow these repo skills before researching (read each `SKILL.md`; mandatory):
+
+- `.agents/skills/netscript-harness` — harness run-artifact contract; where research lands; voice
+  doctrine. You are the Research phase of a harnessed run.
+- `.agents/skills/jsr-audit` — JSR rendering rules: what raw HTML/markdown survives the JSR registry
+  renderer vs. GitHub-only devices (the root README also renders on the repo's JSR scope page).
+- `.agents/skills/netscript-doctrine` — the package/plugin archetypes and the true public surface,
+  so the landing page's architecture story and package map are accurate, not invented.
+- `.agents/skills/netscript-deno-toolchain` — `deno doc` to ground-truth any API/command claim you
+  recommend surfacing on the landing page (e.g. the `@netscript/cli` scaffold command).
+
+## What already exists (read FIRST, then go deeper — do NOT redo it)
+
+A prior dual-track dossier lives at
+`.llm/tmp/run/docs-readme-revamp/sota-readme-dossier.md`. Its **Track 2 — Best-in-Class Monorepo /
+Framework Landing READMEs** already analysed 10 exemplars (Astro, Next.js, Remix, Hono, Bun, NestJS,
+Turborepo, Medusa, Payload, Deno), a canonical framework-landing skeleton, 3 hero options, a
+visual-design + JSR-compat toolkit, and landing anti-patterns. **Treat Track 2 as your seed/baseline.**
+Your mandate is to go BEYOND it in three NetScript-specific directions it did not cover:
+
+1. **NetScript-specific competitor head-to-head.** Track 2 surveyed famous frameworks generically.
+   Now research the *closest-positioned* projects to NetScript — a Deno-native, JSR-published,
+   plugin-architecture meta-framework over Hono + oRPC + Fresh with first-party workers/sagas/
+   triggers/streams/auth plugins and .NET Aspire deployment. Study how these in particular present
+   a *composable, plugin-centric, multi-runtime backend framework* on their landing page:
+   **Encore (encore.dev), Wasp (wasp-lang.dev), RedwoodJS, AdonisJS, Medusa, Nitro/UnJS, Hono,
+   Fresh (deno), Nx, Turborepo, Effect, Modern monorepo "platform" repos.** For each, capture what
+   makes a *plugin/composable-backend* story land: how they show the plugin/module ecosystem, how
+   they draw the architecture, how they sequence "what is it → why → 60-second start → architecture
+   → package map → docs". Cite URLs and quote the specific device.
+
+2. **Architecture-diagram treatment for THIS stack.** NetScript's defining hook is the plugin
+   composition over Hono(router)+oRPC(typed procedures)+Fresh(UI)+Aspire(orchestration), with
+   first-party plugins (auth, workers, sagas, triggers, streams) and `*-core` contract packages.
+   Research how top framework READMEs render an architecture mental-model that renders on BOTH GitHub
+   and JSR (ASCII vs. image vs. mermaid — note mermaid renders on GitHub but is stripped on JSR).
+   Propose 2–3 concrete architecture-diagram options for NetScript specifically, with the
+   GitHub-vs-JSR rendering trade-off stated for each.
+
+3. **Ground-truth package map.** The landing page's monorepo table must use the REAL 31 published
+   packages (below — authoritative, all `0.0.1-alpha.1`). Track 2's table invented names/blurbs; do
+   not reuse it. Recommend how to GROUP these 31 into a scannable table (by layer: foundation /
+   data / runtime plugins / `*-core` contracts / auth backends / app-surface) rather than a flat
+   31-row dump, and design the column set (package · one-line · JSR badge · reference-docs link).
+
+### Authoritative package map (ground truth — use these exact names/descriptions)
+
+```
+@netscript/contracts        — contract primitives, common schemas, CRUD generators, query/transform helpers
+@netscript/config           — typed project config schemas, loaders, env helpers, scaffold constants
+@netscript/logger           — structured logging for services/packages/workers/Hono+oRPC
+@netscript/sdk              — service discovery, oRPC clients, cache-backed query factories
+@netscript/runtime-config   — hot-reloadable runtime override types, loaders, watchers, diagnostics
+@netscript/telemetry        — OpenTelemetry tracing for jobs, queues, RPC, SSE
+@netscript/kv               — reactive key-value abstraction (Redis, Deno KV, in-memory)
+@netscript/database         — DB adapter contracts, Prisma driver helpers, tracing, schema tooling
+@netscript/prisma-adapter-mysql — Prisma driver adapter for MySQL/MariaDB on Deno
+@netscript/queue            — provider-agnostic message queue (Fedify adapters: Deno KV, Redis, RabbitMQ)
+@netscript/cron             — runtime-agnostic cron scheduling abstraction for Deno
+@netscript/watchers         — composable file-watching runtime (strategies, filters, stability, stop)
+@netscript/plugin           — plugin manifest, validation, discovery, host-context contracts
+@netscript/plugin-auth-core — auth plugin contracts, backend ports, stream/config schemas, testing primitives
+@netscript/plugin-workers-core  — job/task/workflow/runtime/config/testing primitives for workers
+@netscript/plugin-sagas-core    — saga DSL, runtime ports, adapters, telemetry, config, testing primitives
+@netscript/plugin-triggers-core — trigger DSL, runtime ports, adapters, telemetry, config, testing primitives
+@netscript/plugin-streams-core  — schema/producer/config/telemetry/testing/diagnostics primitives for streams
+@netscript/plugin-auth      — unified auth API, single-active backend selection, auth DB schema, session streams
+@netscript/plugin-workers   — background job scheduling, task execution, worker API endpoints
+@netscript/plugin-sagas     — durable saga orchestration, workflow APIs, saga runtime metadata
+@netscript/plugin-triggers  — trigger ingress, scheduling, file watching, trigger runtime APIs
+@netscript/plugin-streams   — durable Streams service, CLI, Aspire, E2E, scaffolding
+@netscript/auth-better-auth — better-auth integration helpers
+@netscript/auth-workos      — WorkOS AuthKit authenticators
+@netscript/auth-kv-oauth    — KV-backed OAuth2/OIDC AuthBackendPort backend
+@netscript/aspire           — Aspire TypeScript AppHost config parsing, ports, SDK-agnostic helpers
+@netscript/service          — service bootstrap builders, health probes, Hono/oRPC runtime wiring
+@netscript/fresh            — Fresh runtime extensions, builders, forms, defer primitives, route contracts
+@netscript/fresh-ui         — Fresh UI registry seams and interactive foundations
+@netscript/cli              — public + maintainer command-line tooling for NetScript workspaces
+```
+
+## Context (ground truth you write FOR — do not re-research these facts)
+
+- NetScript is a **Deno-native, JSR-published meta-framework**: plugin architecture over Hono + oRPC
+  + Fresh + .NET Aspire; first-party plugins workers/sagas/triggers/streams/auth; alpha maturity
+  (`0.0.1-alpha.1`); install via `deno add jsr:@netscript/<pkg>`; scaffold via the `@netscript/cli`.
+- Published docs site: **https://rickylabs.github.io/netscript/** with per-package reference pages at
+  `/reference/<pkg>/`, plus capability hubs, tutorials, how-to, explanation. The root README links
+  into that site with **absolute URLs** and must NOT duplicate it.
+- The 31 per-package READMEs were just rewritten (PR2, merged). The root README should feel like the
+  same family — read a few merged package READMEs (e.g. `packages/contracts/README.md`,
+  `packages/cli/README.md`, `plugins/auth/README.md`) so the landing page's voice, badge style, and
+  cross-link convention are consistent with them.
+
+## Output (write to PR3's OWN run folder, then commit + push)
+
+Write the dossier to `.llm/tmp/run/docs-root-readme/sota-landing-dossier.md` on the
+`docs/root-readme` branch. Grow it incrementally; do not defer all writing to the end. It must contain:
+
+1. **Competitor head-to-head** — ≥10 closest-positioned exemplars, each with URL + the specific
+   landing device quoted/described, focused on the plugin/composable-backend story.
+2. **NetScript canonical framework-landing skeleton** — the exact chapter order for `/README.md`,
+   with per-chapter guidance, tuned to this stack (positioning → why → 60-sec quickstart via the CLI
+   → architecture → grouped package map → docs/links → maturity/roadmap → community → license).
+3. **Hero design** — 2–3 concrete hero options for NetScript (markdown/HTML), each with the
+   GitHub-vs-JSR rendering caveat.
+4. **Architecture-diagram options** — 2–3 concrete options for the Hono+oRPC+Fresh+Aspire+plugins
+   model, each with GitHub-vs-JSR rendering trade-off (ASCII / image / mermaid).
+5. **Grouped package-map table design** — column set + the layer grouping for all 31 real packages.
+6. **Visual-design + JSR-compat toolkit** — devices that render on BOTH GitHub and JSR vs.
+   GitHub-only; carried/refined from Track 2 but verified.
+7. **Quality checklist** + **anti-patterns** specific to a framework landing README.
+
+## Constraints
+
+- Cite every exemplar with its URL and quote/describe the specific device — no vague generalities.
+- Distinguish BOTH-GitHub-and-JSR techniques from GitHub-only ones (the root README renders on the
+  JSR scope page too).
+- Use the authoritative package map above; do NOT reuse Track 2's invented package names/blurbs.
+- Honor repo voice doctrine: the words "honest/honesty/honestly" and candor-announcing framing
+  ("to be transparent", "we won't pretend", apologetic alpha disclaimers) are BANNED. Signal
+  alpha maturity as a factual noun-phrase callout with a roadmap link.
+- Do NOT author the NetScript root README here — research + skeleton + checklist only.
+- Lock hygiene: do not touch `deno.lock`, source, or any `packages/`/`plugins/` files. Only write
+  the dossier under `.llm/tmp/run/docs-root-readme/` and commit just that file.

.llm/tmp/run/docs-root-readme/evaluate.md

@@ -0,0 +1,40 @@
+# IMPL-EVAL Verdict — PR3 root README (docs/root-readme)
+
+**Verdict**: `PASS`
+
+**Evaluator session**: OpenHands `openrouter/qwen/qwen3.7-max` (separate from generator)
+**Commit under review**: `b6faf31b` — `docs(root-readme): author meta-framework landing README (PR3)`
+**Scope**: `/README.md` only (236 insertions, 5 deletions; no source, no `deno.json`, no `deno.lock`)
+
+## Per-criterion checklist
+
+| # | Criterion | Status | Evidence |
+|---|-----------|--------|----------|
+| 1 | **Structure (D1)** — 10-chapter order | ✅ PASS | Chapters present in order: Title+hero+3 badges (L1–8) → value prop (L18–20) → 🧭 What is NetScript (L24) → 🚀 60-Second Quick Start (L45) → 🗺️ Architecture (L74) → 📦 Packages (L127) → 📖 Documentation (L176) → 📅 Roadmap & Maturity (L194) → 🤝 Contributing (L207) → 📝 License (L217). All 10 chapters, correct sequence. |
+| 2 | **Hero + badges (D2/D5)** — JSR-safe ASCII hero + exactly 3 badges | ✅ PASS | ASCII monospace banner (L10–16) renders identically on GitHub + JSR; no missing image asset. Three badges: JSR scope `jsr.io/badges/@netscript` (L6), CI `ci.yml/badge.svg` (L7), Docs `rickylabs.github.io-blue` (L8). Badge style matches PR2 package READMEs (sdk, service, auth). |
+| 3 | **Architecture (D3)** — ASCII canvas primary, mermaid optional | ✅ PASS | ASCII four-layer canvas (L79–104) is always-visible: Browser → Application surface → Service runtime → First-party plugins → Platform & data. Mermaid under `<details>` (L112–123) with label "Mermaid view (rendered on GitHub)" — stripped on JSR, not the sole diagram. |
+| 4 | **Package map (D4)** — all 31 packages, exact names, six layers | ✅ PASS | `grep -oP` extracts exactly 31 unique `@netscript/*` names, all matching the authoritative map in `deep-search-brief.md` L60–92. Six layer sections: Foundation core (6), Data messaging & scheduling (6), Plugin contracts `*-core` (6), Runtime plugins (5), Auth backends (3), Application surface (5) = 31. Columns: Package · JSR · Capability · Reference. No drops, no invented rows. |
+| 5 | **Voice (D5)** — zero banned tokens | ✅ PASS | `grep -ioPn 'honest[y]?|to be (honest|transparent|clear)|we won.t pretend|apologeti|to be fair' README.md` returns zero matches. Alpha signalled as factual noun-phrase callout: `> [!NOTE] > **Alpha (`0.0.1-alpha.1`).**` with roadmap link (L38–41). No candor-announcing or apologetic framing. |
+| 6 | **Links** — absolute doc links only | ✅ PASS | Every doc link is `https://rickylabs.github.io/netscript/...` (reference pages, capability hubs, CLI reference) or absolute `github.com` URL (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE, issues, milestones, discussions). External URLs: hono.dev, fresh.deno.dev, learn.microsoft.com, docs.deno.com, better-auth.com. Zero relative doc links. |
+| 7 | **Quick start truthfulness** | ✅ PASS | Install command: `deno install --global --allow-all --name netscript jsr:@netscript/cli/bin/netscript.ts` (L52) — matches shipped `docs/site/cli-reference.md` exactly. No-install form: `deno run -A jsr:@netscript/cli/bin/netscript.ts init my-app` (L65) — matches the ad-hoc pattern. Deferred `deno dx` form correctly absent (recorded follow-up in `.llm/tmp/run/docs-root-readme/followups.md`). |
+| 8 | **fmt** — `deno fmt --check README.md` clean | ✅ PASS | Exit 0, output: "Checked 1 file". |
+| 9 | **Scope** — only README.md changed | ✅ PASS | `git diff --stat 740c3312..b6faf31b`: 1 file changed — `README.md` (236 insertions, 5 deletions). No source, no `deno.json`, no `deno.lock`, no `packages/`/`plugins/` churn. Run artifacts under `.llm/tmp/run/docs-root-readme/` and `.llm/tmp/run/openhands/` are evaluator/trace metadata — not in scope. |
+
+## Consistency with PR2 package READMEs
+
+Badge style, voice, and cross-link convention match merged PR2 package READMEs:
+- `packages/sdk/README.md` L3–5: same 3-badge row pattern (JSR + CI + Docs).
+- `packages/service/README.md` L3–5: identical badge row.
+- `plugins/auth/README.md` L3–5: identical badge row.
+- The root README's 31 package-table JSR badges and reference links use the same `jsr.io/badges/@netscript/<pkg>` and `rickylabs.github.io/netscript/reference/<pkg>/` conventions.
+
+## Recorded follow-ups (non-blocking, OUT of scope for PR3)
+
+Per `deep-search-brief.md` and the plan's "Debt / follow-ups" section:
+- **Brand/banner asset**: ASCII hero shipped; commissioned banner image is a future enhancement.
+- **`@netscript/queue` reference page**: link points at the published site; if the page 404s it degrades gracefully.
+- **`deno dx` CLI form**: deferred sweep — correctly absent from the quick start.
+
+## Recommendation
+
+**Merge PR #118 → main.** The root README is a clean, enterprise-grade landing page that renders on GitHub + JSR, documents the full 31-package surface, and closes the "road to JSR publish" topology. Next steps per the plan's pipeline: `publish:dry-run` green → release tag → OIDC `deno publish`.