Docs: alpha.11 CLI surface + multi-backend cache + polyglot database realignment

[rickylabs]

Docs: alpha.11 CLI surface + multi-backend cache realignment

Aligns the docs site to the built alpha.11 CLI surface, with a site-wide realignment presenting the scaffold cache as a multi-backend capability.

Cache: multi-backend (this commit)

• redis is the default cache backend everywhere; garnet and deno-kv are first-class alternatives selectable via --cache-backend.
• Garnet is kept only where shown as an explicit alternative backend choice.
• Real symbols preserved verbatim: createGarnetListTransport(), Cache.<backend> config keys, GARNET_URI / REDIS_URI, CACHE_PROVIDER values.
• 45 docs files realigned: concepts, cli-reference, glossary, explanation/*, capabilities/*, how-to/*, tutorials/*, plus index / why / quickstart.
• aspire-resource-graph diagram: adds the default Redis cache resource node + wiring; SVG regenerated (byte-clean — single-diagram delta, renderer verified deterministic vs the other 14).
• quickstart bare netscript init now passes --db postgres to match the tutorial stack.

Ground truth

Cache surface verified against the merged CLI: CacheBackendChoice = 'redis' | 'garnet' | 'deno-kv', defaults CACHE_BACKEND: 'redis' / CACHE_ENABLED: true, flags --cache [enabled] (default on) + --cache-backend <backend> (default redis), disable via --cache=false. redis/garnet emit an Aspire container resource; deno-kv is app-level (no container).

Gates

• Lume build: green (306 files, all diagram refs resolve).
• Final Garnet sweep: every remaining mention is an intentional alternative-backend reference or a real exported symbol.

Validation note: per harness doctrine the authoring lane does not self-certify — per-domain doc validation runs separately in OpenHands.

🤖 Generated with Claude Code

[rickylabs]

Follow-up: database presented as polyglot (commit 28539811)

Mirrors the cache multi-backend realignment, now for the database. NetScript scaffolds a Prisma-backed database for four engines, chosen at scaffold time with --db: postgres | mysql | mssql | sqlite. Postgres is the recommended default (every tutorial keeps --db postgres); mysql / mssql / sqlite are first-class alternatives. postgres/mysql/mssql provision an Aspire container resource; sqlite is file-backed with no container.

This pass is enrichment, not replacement (unlike cache, where redis replaced garnet as the default):

• 27 docs files realigned: capabilities/*, cli-reference, glossary, explanation/*, how-to/*, tutorials/*, plus concepts / index / why / quickstart.
• Anchor pages (capabilities/database, cli-reference, glossary, how-to/use-a-second-database, how-to/database-migration) get a richer backend/--db passage incl. the sqlite no-container caveat.
• Tutorials keep every --db postgres command verbatim and gain one swap-engine note near the first scaffold step.

Rule-C — left untouched by design (not the app-DB-engine choice)

• Postgres-as-subsystem backends: queue provider (FOR UPDATE SKIP LOCKED, advisory locks), saga / durable stores.
• Connection-string mechanics (DATABASE_URL, POSTGRES_URI), Prisma provider literals, engine-specific paths.
• The runtime second-datasource adapter barrel ships postgres/mssql/mysql only — no sqlite runtime adapter was fabricated. (Scaffold-time --db = 4 engines; runtime adapter barrel = 3. The docs keep these distinct.)

Gates

• Lume build: green (306 files). No diagram sources changed.

Validation note: per harness doctrine the authoring lane does not self-certify — per-domain doc validation runs separately in OpenHands.

🤖 Generated with Claude Code

[rickylabs]

Folded in: Prisma-backed subsystems are not Postgres-only (commit 474a47ca)

Follow-up to the polyglot DB pass. A file-grounded subsystem audit found that the saga prisma store and the better-auth backend persist through the project's Prisma client — so they follow whichever engine you scaffolded with --db, not Postgres specifically. The docs framed them as "Postgres" stores. Corrected at the definitional points:

• capabilities/durable-sagas.md — prisma backend bullet + trait-matrix row (type Postgres / Prisma → Relational / Prisma).
• explanation/durability-model.md — prisma store row + "choosing kv vs prisma".
• capabilities/auth.md — better-auth tables provisioning note.
• how-to/add-authentication.md — auth.prisma aggregation line + table caption.

Deliberately left engine-specific (same audit confirmed real coupling):

• The queue PostgreSQL provider — hard-tied to Postgres (FOR UPDATE SKIP LOCKED, JSONB, TIMESTAMPTZ, raw $N SQL). A polyglot queue is genuine engineering (SQLite infeasible) → backlog (QUEUE-ENGINE-POSTGRES-LOCK), not a doc change.
• The durable-streams service's Postgres/Redis dependency line (service infra, accurate by default).

Lume build: green (306 files).

🤖 Generated with Claude Code

[rickylabs]

@openhands-agent model=openrouter/qwen/qwen3.7-max provider=openrouter output=pr-comment iterations=600

use harness

You are the IMPL-EVAL evaluator (separate session from the generator) for PR #162 — docs realignment. This is a documentation accuracy validation against framework ground truth. You are the evaluator only: you do NOT edit docs or "fix" anything. You read the changed docs, verify each claim against the actual code, run the docs build, and emit a per-domain verdict.

SKILL

Activate and follow these repo skills before any work:

• netscript-harness — IMPL-EVAL protocol, verdict definitions (PASS / FAIL_FIX / FAIL_RESCOPE / FAIL_DEBT), evaluator-separation rule.
• netscript-doctrine — package/plugin public-surface truth for the capabilities being documented.
• netscript-deno-toolchain — use deno doc <module> / deno doc --filter <symbol> to confirm a documented symbol/type actually exists and is exported; deno why <pkg> for coupling questions. deno doc is the cheapest ground-truth check — prefer it over guessing.
• netscript-cli — the init scaffold surface, --db / --cache flags, db-engine domain.
• netscript-tools — scoped check/lint/fmt wrappers and gate-evidence rules; raw root noise is not a verdict.

Scope of this PR (three docs passes, one branch)

The PR branch docs/alpha11-cli-surface carries three commits. Validate each as its own domain:

1. Cache → multi-backend (commit b847c6a8). Claim: redis is the default cache backend; garnet and deno-kv are first-class alternatives selected via --cache-backend; cache is enabled by default and disabled with --cache=false (NOT --no-cache).
2. Database → polyglot (commit 28539811). Claim: scaffold-time --db accepts four engines postgres | mysql | mssql | sqlite; Postgres is the recommended default (tutorials keep --db postgres); postgres/mysql/mssql provision an Aspire container; sqlite is file-backed, no container.
3. Prisma-backed subsystems follow the scaffolded engine (commit 474a47ca). Claim: the sagas prisma store and the better-auth backend persist through the project's Prisma client and therefore run on whichever engine was scaffolded (NOT Postgres-only).

Ground-truth anchors you MUST verify against code (do not trust the prose)

• DB engine domain: packages/cli/src/kernel/domain/db-engine.ts — confirm DbEngine = 'postgres'|'mysql'|'mssql'|'sqlite', that the DbEngineProvider for sqlite has supportsContainerMode: false (file-backed, no container) and the other three have container mode, and that Prisma providers map postgres→postgresql, mysql→mysql, mssql→sqlserver, sqlite→sqlite.
• CLI default: the literal init default DB is none (no DB) — confirm the docs frame Postgres as the recommended default, never claim the CLI's literal default is Postgres.
• --cache surface: confirm --cache (default on) + --cache-backend exist and disable is --cache=false; the docs must not invent --no-cache.
• CRITICAL — runtime adapter vs scaffold --db: the runtime second-datasource adapter barrel (see capabilities/database.md and the generate-engine code) ships three engines (postgres / mssql / mysql) — there is no sqlite runtime adapter. Scaffold-time --db = 4 engines; runtime adapter barrel = 3. Verify the docs keep these DISTINCT and did NOT fabricate a sqlite runtime adapter.
• Queue coupling (subsystem pass): the queue PostgreSQL provider is genuinely Postgres-specific (packages/queue/adapters/postgres.adapter.ts uses FOR UPDATE SKIP LOCKED, JSONB, TIMESTAMPTZ, raw $N SQL). Verify the docs did NOT relabel the queue as polyglot. Conversely verify the sagas prisma store (plugins/sagas/src/runtime/prisma-saga-store.ts) and better-auth (packages/auth-better-auth) are genuinely Prisma-delegating (engine-agnostic), so the new "follows your scaffolded engine" framing is correct.

Gate

• Build the docs site from docs/site: deno task build (Lume). It must succeed (expect ~306 files). Report the file count and any Vento/Lume error. Do NOT treat root composite deno task build lint/arch failures as a docs verdict — those are package gates out of scope here.
• Spot-check that no internal xref/link introduced by these commits is broken.

Output

output=pr-comment. Emit a per-domain verdict table — one row each for (1) cache, (2) database polyglot, (3) subsystem framing — each PASS or FAIL_FIX with the specific file:line and the code anchor that proves or refutes the claim. If anything is a real but deferrable inaccuracy, mark FAIL_DEBT and name it. End with an overall verdict and the Lume build result. Keep it concise and evidence-first; cite file:line and the verifying symbol. Do not edit any file.

[rickylabs]

OpenHands Agent — Completed

Model: openrouter/qwen/qwen3.7-max
Provider: OPENROUTER
Job status: success
Trace: .llm/tmp/run/openhands/pr-162/run-28300391133-1 (committed to the PR branch)
Artifact: openhands-agent-28300391133-1

PR #162 Documentation Realignment Evaluation Summary

Summary

Evaluating three commits on branch docs/alpha11-cli-surface against framework ground truth:

1. b847c6a8 - Multi-backend cache (redis default, garnet/deno-kv alternatives)
2. 28539811 - Polyglot database (4 engines at scaffold-time, Postgres recommended)
3. 474a47ca - Prisma-backed subsystems follow scaffolded engine (not Postgres-only)

Verification Results

Domain 1: Multi-backend cache (commit b847c6a) - PASS

Claim: redis is default cache backend; garnet/deno-kv are alternatives via --cache-backend; cache enabled by default, disabled with --cache=false (NOT --no-cache)

Code anchors verified:

• packages/cli/src/kernel/adapters/cache/cache-backend.ts:15-17: CacheBackendChoice = 'redis' | 'garnet' | 'deno-kv'
• packages/cli/src/kernel/domain/scaffold/scaffold-defaults.ts:8: CACHE_BACKEND: 'redis' (default)
• packages/cli/src/cli.ts (grep confirms --cache bool flag + --cache-backend string flag)
• No --no-cache found in entire docs/site tree (grep returned 0 results)

Docs verified (docs/site/cli-reference.md:100):

"netscript init my-app --cache-backend garnet" - The shared cache is on by default 
with the redis backend. Pick another with --cache-backend: redis (default) or garnet 
are provisioned as Aspire container resources; deno-kv is app-level and needs no 
container. Pass --cache=false to scaffold without a cache.

Verdict: PASS - All claims align with code surface. Correctly frames redis as default, uses --cache=false for disable, never invents --no-cache.

---

Domain 2: Polyglot database (commit 2853981) - PASS

Claim: scaffold-time --db accepts 4 engines (postgres|mysql|mssql|sqlite); Postgres is recommended (not literal CLI default); postgres/mysql/mssql provision Aspire container; sqlite is file-backed with no container; runtime adapter barrel = 3 engines (no sqlite runtime adapter)

Code anchors verified:

• packages/cli/src/kernel/domain/db-engine.ts:8: DbEngine = 'postgres' | 'mysql' | 'mssql' | 'sqlite'
• packages/cli/src/kernel/adapters/database/providers/postgres.provider.ts: prismaProvider: 'postgresql', supportsContainerMode: true
• packages/cli/src/kernel/adapters/database/providers/mysql.provider.ts: prismaProvider: 'mysql', supportsContainerMode: true
• packages/cli/src/kernel/adapters/database/providers/mssql.provider.ts: prismaProvider: 'sqlserver', supportsContainerMode: true
• packages/cli/src/kernel/adapters/database/providers/sqlite.provider.ts: prismaProvider: 'sqlite', supportsContainerMode: false
• packages/cli/src/kernel/domain/scaffold/scaffold-defaults.ts:7: DB_ENGINE: 'none' (literal CLI default is none, not postgres)

Docs verified (docs/site/capabilities/database.md:54-55):

The scaffold engine is chosen with the --db flag — 
netscript init my-app --db postgres|mysql|mssql|sqlite. Postgres is the recommended
default (and what every tutorial uses); mysql, mssql, and sqlite are first-class
alternatives. postgres / mysql / mssql provision an Aspire container; sqlite is
file-backed with no Aspire container resource.

Runtime adapter separation verified (docs/site/capabilities/database.md:119-138):

• Runtime adapter barrel exports only 3 engines: postgres, mssql, mysql
• No sqlite runtime adapter exists (correct - scaffold-only)
• Docs correctly distinguish scaffold-time choice vs runtime adapter availability

Verdict: PASS - All claims align. Correctly frames Postgres as "recommended" (not literal default), correctly identifies sqlite container-less, correctly separates scaffold from runtime adapter surface.

---

Domain 3: Prisma-backed subsystems follow scaffolded engine (commit 474a47c) - PASS

Claim: sagas prisma store and better-auth backend are engine-agnostic (persist through Prisma client, follow whatever engine was scaffolded); queue PostgreSQL provider is genuinely Postgres-specific (not relabeled as polyglot)

Code anchors verified:

• plugins/sagas/src/runtime/prisma-saga-store.ts: Uses Prisma client queries (no raw SQL), delegates all persistence to Prisma ORM - engine-agnostic
• packages/auth-better-auth/src/better-auth.ts:166-171: Uses prismaAdapter(prisma, { provider, ... }) - delegates to Prisma, provider is parameter
• packages/queue/adapters/postgres.adapter.ts:180-190: Raw SQL with FOR UPDATE SKIP LOCKED, JSONB, TIMESTAMPTZ, $N parameter binding - genuinely Postgres-specific

Docs verified (commit 474a47ca diff):

• docs/site/capabilities/durable-sagas.md:289-294: Correctly frames prisma store as following scaffolded engine via Prisma client
• docs/site/explanation/durability-model.md:143-147: Same framing - "follows your Prisma client, it is not Postgres-specific"
• docs/site/capabilities/auth.md:313-316: Correctly notes better-auth persists through Prisma
• docs/site/how-to/add-authentication.md:119-122: Correctly notes auth.prisma aggregation follows engine
• docs/site/capabilities/kv-queues-cron.md:177-193: Correctly keeps queue PostgreSQL provider marked as PostgreSQL-specific (not polyglot)

Verdict: PASS - All claims align. Correctly distinguishes engine-agnostic (sagas prisma store, better-auth) from engine-specific (queue postgres adapter). No relabeling of queue as polyglot.

---

Gate: Documentation build - PASS

Lume build result: 306 files generated in 6.46 seconds, 0 errors

Command: deno task build (executed from docs/site/)

Xrefs verified: All comp.xref() calls in changed docs resolve to valid keys (cap:database, ref:sagas, explain:observability, etc.)

---

Overall Verdict

PR #162: PASS (3/3 domains PASS, Lume build green)

All documentation claims verified against:

1. Type definitions in packages/cli/src/kernel/domain/
2. Provider metadata in packages/cli/src/kernel/adapters/database/providers/
3. Runtime adapter implementations in plugins/sagas/, packages/auth-better-auth/, packages/queue/
4. CLI flag surface in packages/cli/src/cli.ts

No broken xrefs. No invented flags (--no-cache). No runtime adapter fabrication (sqlite runtime adapter does not exist, docs correctly reflect this). No relabeling of engine-specific code as polyglot (queue adapter remains correctly marked as PostgreSQL-specific).

Changes

Documentation-only changes across three commits:

• Multi-backend cache framing
• Polyglot database framing
• Prisma-backed subsystem engine-agnostic framing

No source code changes. No test changes.

Validation

• Code anchor inspection: 7 provider files, 3 runtime adapter implementations
• Docs grep: 15+ files checked for claim alignment
• Lume build: 306 files, 0 errors
• Xref resolution: all internal links valid

Remaining risks

None identified. All factual claims in documentation align with implementation ground truth.

Run: https://github.com/rickylabs/netscript/actions/runs/28300391133