From a93061237668ceab76fdf36f2c5425f0df6aea7e Mon Sep 17 00:00:00 2001
From: gaboesquivel <contact@gaboesquivel.com>
Date: Fri, 4 Sep 2026 17:23:56 -0600
Subject: [PATCH 1/2] docs(docu): add product feature map and honesty edits

---
 README.md                                     | 16 +++---
 _first/basilic/DOCUMENTATION.md               |  2 +-
 _first/basilic/PRODUCT.md                     | 48 ++++++++--------
 apps/docu/README.md                           |  3 +-
 .../docs/architecture/authentication.mdx      |  2 +-
 apps/docu/content/docs/development/index.mdx  |  4 +-
 apps/docu/content/docs/index.mdx              | 16 +++++-
 apps/docu/content/docs/meta.json              |  2 +-
 apps/docu/content/docs/product/features.mdx   | 55 +++++++++++++++++++
 apps/docu/content/docs/product/index.mdx      | 45 +++++++++++++++
 apps/docu/content/docs/product/meta.json      |  4 ++
 11 files changed, 161 insertions(+), 36 deletions(-)
 create mode 100644 apps/docu/content/docs/product/features.mdx
 create mode 100644 apps/docu/content/docs/product/index.mdx
 create mode 100644 apps/docu/content/docs/product/meta.json

diff --git a/README.md b/README.md
index 1c59fe4d..96ce06e7 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,6 @@
 # Basilic: API-First TypeScript FullStack Starter
 
-Build production-ready APIs and apps with typed SDKs, out-of-the-box authentication, a portable architecture, AI tooling, and crypto integrations.
-Fastify • OpenAPI • Next.js • Expo — one stack, multiple platforms.
+Fork-and-run developer starter: typed SDKs, self-hosted auth, a portable architecture, Cursor-first workflow, and a thin web demo. Fastify • OpenAPI • Next.js • Expo scaffold — one stack, multiple clients.
 
 > 🚧 **Active development** — Explore, fork, and contribute. 🏗️
 
@@ -10,21 +9,21 @@ Fastify • OpenAPI • Next.js • Expo — one stack, multiple platforms.
 - 🤖 **AI-first dev workflow** — Agent rules, skills, MCP integrations, and automated CodeRabbit reviews
 - 🔌 **REST API & JWT** — OpenAPI spec, Swagger UI, JWT and API key auth for all clients
 - 📦 **SDK generation** — Type-safe clients from OpenAPI via HeyAPI
-- 🧩 **Web3 & AI starters** — Ready-to-use templates for Next.js, React, Expo, and Fastify
+- 🧩 **Web + API starters** — Next.js demo, React hooks, Expo UI scaffold, Fastify API (not a wallet or OpenAI template)
 - 🔓 **Zero vendor lock-in** — Run on VPS, AWS, Vercel, or local
 - 🎨 **Turbo monorepo + design system** — ShadcnUI components with shared utilities
 - ⚙️ **Preconfigured dev tools** — Biome, Git workflows, hooks, and security checks
 - 🛡️ **Security & quality** — Automated checks in CI (Gitleaks, OSV, DeepSec)
-- ⛓️ **Multichain** — EVM, Solana; shared validation and chain-specific tooling
+- ⛓️ **Multichain (API)** — EVM and Solana SIWE/SIWS on Fastify; shared `@repo/utils/web3` helpers — not a web wallet demo
 - 📐 **Conventions** — Cursor rules per domain, @repo/error, Pino logging, shared TS and style
 - 🧑‍💻 **TypeScript-first** — End-to-end types from database to frontend
 
 ## Technology stack
 
-- **AI:** AI SDK, OpenAI, Claude, Grok
+- **AI (in-app):** AI SDK — Anthropic, OpenRouter, Ollama (no first-class OpenAI SDK)
 - **Frontend:** Next.js 16, React 19, Tailwind, ShadcnUI
 - **Backend:** Fastify, PostgreSQL, Supabase
-- **Web3:** Viem, Wagmi, Solana wallet tooling in shared packages
+- **Web3:** Fastify SIWE/SIWS + `@repo/utils/web3` helpers. **No Wagmi and no wallet UI in `apps/web`**
 - **DevOps:** Node.js 24.x (LTS Krypton), pnpm, TurboRepo, TypeScript, Biome, ESLint
 
 ## Apps
@@ -32,7 +31,7 @@ Fastify • OpenAPI • Next.js • Expo — one stack, multiple platforms.
 - **[API](apps/api/README.md)** — Type-safe REST API built with Fastify & OpenAPI
 - **[Web App](apps/web/README.md)** — Next.js app with monorepo integration
 - **[Mobile App](apps/mobile/README.md)** — Expo UI scaffold (shared `@repo/ui`; not an API client yet)
-- **[Documentation](apps/docu/README.md)** — Fumadocs-based docs site for architecture, ADRs, and development workflows
+- **[Documentation](apps/docu/README.md)** — Fumadocs site ([Product](https://basilic-docs.vercel.app/docs/product), architecture, ADRs, development)
 
 ## Packages
 
@@ -96,5 +95,8 @@ Run with `pnpm <script>`.
 
 Full docs: [basilic-docs.vercel.app](https://basilic-docs.vercel.app/docs)
 
+- [Product](https://basilic-docs.vercel.app/docs/product) — what Basilic is, feature map, non-goals
+- [Getting Started](https://basilic-docs.vercel.app/docs/development) — clone, `pnpm setup`, `db:start`, `pnpm reset`
 - [Dev Environments](https://basilic-docs.vercel.app/docs/development/dev-environments) — Local vs remote (ports 3000, 3001, 8081; `start:localhost`, `start:tunnel`)
+- FIRST factory (stations, overlays): [`_first/`](_first/README.md) — load `_first/AGENTS.md` then `_first/ABOUT.md` then `_first/FIRST.md`. See [AI Workflow](https://basilic-docs.vercel.app/docs/development/ai-workflow)
 
diff --git a/_first/basilic/DOCUMENTATION.md b/_first/basilic/DOCUMENTATION.md
index ae0732c5..876daff5 100644
--- a/_first/basilic/DOCUMENTATION.md
+++ b/_first/basilic/DOCUMENTATION.md
@@ -14,7 +14,7 @@ Consequential decisions, conventions, setup steps, and domain context live in di
 
 ## Artifacts
 
-- **Fact:** Canonical: [`../../apps/docu/content/docs/`](../../apps/docu/content/docs/) — architecture, ADRs, development, testing, deployment
+- **Fact:** Canonical: [`../../apps/docu/content/docs/`](../../apps/docu/content/docs/) — product, architecture, ADRs, development, testing, deployment
 - **Fact:** How to run: [`../../README.md`](../../README.md) and app/package READMEs — link to docs, no duplication ([docs.mdc](../../.cursor/rules/base/docs.mdc))
 - **Fact:** Agents: [`../../AGENTS.md`](../../AGENTS.md); constraints `.cursor/rules/`; skills `.agents/skills/`
 - **Fact:** Workflow index: [ai-workflow.mdx](../../apps/docu/content/docs/development/ai-workflow.mdx)
diff --git a/_first/basilic/PRODUCT.md b/_first/basilic/PRODUCT.md
index 93d6cfd9..8ba7bc06 100644
--- a/_first/basilic/PRODUCT.md
+++ b/_first/basilic/PRODUCT.md
@@ -14,29 +14,32 @@ The project has an inspectable answer to what, why, and how we will know. Non-go
 
 ## Artifacts
 
-- **Fact:** [`../../README.md`](../../README.md) — API-first TypeScript fullstack starter (Fastify, OpenAPI, Next, Expo)
-- **Fact:** [`../../apps/docu/content/docs/index.mdx`](../../apps/docu/content/docs/index.mdx) — toolkit intro
+- **Fact:** Canonical product brief: [product/index.mdx](../../apps/docu/content/docs/product/index.mdx) and [product/features.mdx](../../apps/docu/content/docs/product/features.mdx)
+- **Fact:** [`../../README.md`](../../README.md) — fork-and-run TypeScript fullstack starter (Fastify, OpenAPI, Next, Expo scaffold). No Wagmi, no first-class OpenAI SDK, no web wallet UI
+- **Fact:** [`../../apps/docu/content/docs/index.mdx`](../../apps/docu/content/docs/index.mdx) — toolkit intro; Product is in the docs nav
 - **Fact:** Two audiences: **adopters** (developers using the starter) and **demo users** (web news `/`, markets, settings, in-shell assistant; auth is the shipped job)
+- **Fact:** GTM: clone + [Getting Started](../../apps/docu/content/docs/development/index.mdx) + first local login. Finance **N/A** (toolkit)
+- **Fact:** Owner: Gabo Esquivel (named on product index)
 - **Fact:** New-device sign-in alerts are transactional email via Fastify `emailProvider` + `@repo/email`, not a notification product
-- **Fact:** Not a billed SaaS in files. No `PRODUCT.md` / PRD. Do not invent one to fill TAM.
-- **Fact:** Observed non-goals in code/docs: mobile not an API client; no web wallet UI; Cache Components off; `@repo/react` hooks handwritten
-- **Fact:** PostHog **chosen, not installed**. No SDK, env keys, or sink. Product events are **specified** in types + [analytics.mdx](../../apps/docu/content/docs/architecture/analytics.mdx) and **instrumented** at the web boundary via `apps/web/lib/analytics.ts` `capture()`. They are **not collected** and therefore **not measured**. No `@vercel/analytics`.
-- **Fact:** Two demo questions are specified: (1) auth — did sign-in complete or did a visible attempt fail (`auth_succeeded` / `auth_failed` by `method`); (2) assistant — did this turn render `__render: 'user-info'` (`assistant_turn` with `accountRender`). Factory GTM, GenUI act, demo surfaces, session revoke, cost-per-job: **unmeasured** (not instrumented).
-- **Unresolved:** GTM (channel, first successful use); PostHog install / consent / retention; success metrics that can fail (not `pnpm qa`); TAM/LTV (toolkit — say so); named decision owners for the product bet
-- **Unresolved:** keep / iterate / kill board; whether adopters copy `lib/analytics` (qualitative — no event can evaluate that)
+- **Fact:** Not a billed SaaS in files. Do not invent TAM/LTV
+- **Fact:** Non-goals: mobile not an API client; no web wallet UI; Cache Components off; `@repo/react` hooks handwritten; PostHog not installed; Sentry inactive
+- **Fact:** PostHog **chosen, not installed**. Product events are **specified** in types + [analytics.mdx](../../apps/docu/content/docs/architecture/analytics.mdx) and **instrumented** via `apps/web/lib/analytics.ts` `capture()`. They are **not collected** and therefore **not measured**
+- **Fact:** Two demo questions are specified: (1) auth — `auth_succeeded` / `auth_failed` by `method`; (2) assistant — `__render: 'user-info'` (`assistant_turn` with `accountRender`). Unmeasured
+- **Fact:** PD (Markets + GenAI artifacts) is named on the feature map as **intended**, not shipped
+- **Unresolved:** PostHog install / consent / retention; keep / iterate / kill board; whether adopters copy `lib/analytics`
 
 `pnpm qa` going green is Quality/Pipelines, not product success.
 
 ## Minimum Useful Artifact
 
 - problem: bootstrap a typed API + web/mobile/docs without inventing the stack
-- users: adopting developers (inferred); demo end users on web auth and dashboard
-- goal: portable starter with self-hosted Web2/Web3 auth and Cursor-first workflow
-- non-goals: listed above as observed, not a ratified PRD
-- audience/channel/first use: **unresolved** beyond “fork and run”
-- metrics: auth and assistant jobs **instrumented, not collected** (cannot be queried yet)
+- users: adopting developers; demo end users on web auth and dashboard
+- goal: portable starter with self-hosted Web2 auth and Cursor-first workflow (Web3 on API only)
+- non-goals: [product/index.mdx](../../apps/docu/content/docs/product/index.mdx) R0 list
+- audience/channel/first use: clone + Getting Started + first local login
+- metrics: auth and assistant jobs **instrumented, not collected**
 - events: `auth_succeeded`, `auth_failed`, `assistant_turn` — specified + instrumented, no sink
-- owners: **unresolved**
+- owners: Gabo Esquivel
 
 ## Recipe
 
@@ -51,11 +54,10 @@ The project has an inspectable answer to what, why, and how we will know. Non-go
 
 ## Validation
 
-- A new contributor can answer what we are building from README + this file: a starter/toolkit with a demo web app. Who/why/how-we-will-know beyond that is unresolved.
-- Success metrics can fail. They are not CI green. Currently unmeasured.
-- Named metrics have events, or are marked unmeasured. Auth/assistant are instrumented without a sink (not measured).
-- GTM is named at the level the product needs, or marked unresolved.
-- No silent product decisions in code without a note or open question.
+- A new contributor can answer what we are building from `apps/docu` Product pages + README without `__dev/`
+- Success metrics can fail. They are not CI green. Auth/assistant remain unmeasured (no sink)
+- GTM is clone + Getting Started. Finance N/A
+- No silent product decisions in code without a note or open question
 
 ## Definition of Done
 
@@ -65,11 +67,11 @@ Product intent is documented or explicitly deferred with named owners. Implement
 
 Apply Product First to Basilic.
 
-Read root README, `apps/docu/content/docs/index.mdx`, analytics MDX and ADR 011, and what the web, mobile, and API actually do. Do not assume documentation is complete. PostHog is not installed. `capture()` is a no-op — do not claim events are collected or measured.
+Read root README, `apps/docu/content/docs/product/`, analytics MDX and ADR 011, and what the web, mobile, and API actually do. PostHog is not installed. `capture()` is a no-op — do not claim events are collected or measured. PD is named on the feature map, not shipped.
 
-Preserve intentional existing product choices. Do not silently decide scope, priorities, pricing, TAM, LTV, event names, or GTM. This is a toolkit, not a billed product in files — say so rather than filling finance blanks.
+Preserve intentional existing product choices. Do not silently decide scope, priorities, pricing, TAM, LTV, or event names. This is a toolkit — say so rather than filling finance blanks.
 
-Separate `pnpm qa` from post-launch success. If a metric is named but not instrumented, implement the event or mark it unmeasured. Do not file that as operations work. Propose the smallest useful update to README or `apps/docu`. Update this instance when paths or unresolved items change.
+Separate `pnpm qa` from post-launch success. Propose the smallest useful update to Product MDX or README. Update this instance when paths or unresolved items change.
 
 ## Notes
 
@@ -81,4 +83,4 @@ Separate `pnpm qa` from post-launch success. If a metric is named but not instru
 
 **Product vs Data:** Product names events and outcomes to measure. Data owns canonical domain meaning, authority, lifecycle, and evolution.
 
-**Navigation:** [Generic spec](../principles/PRODUCT.md) · [Human essay](https://github.com/blockmatic/first/blob/main/_first/articles/PRODUCT.md) · [Factory map](../ABOUT.md) · [Introduction](../../apps/docu/content/docs/index.mdx) · [ADR 011](../../apps/docu/content/docs/adrs/011-product-analytics.mdx)
+**Navigation:** [Generic spec](../principles/PRODUCT.md) · [Human essay](https://github.com/blockmatic/first/blob/main/_first/articles/PRODUCT.md) · [Factory map](../ABOUT.md) · [Product](../../apps/docu/content/docs/product/index.mdx) · [Feature map](../../apps/docu/content/docs/product/features.mdx) · [ADR 011](../../apps/docu/content/docs/adrs/011-product-analytics.mdx)
diff --git a/apps/docu/README.md b/apps/docu/README.md
index 7d78ddb3..af1cd810 100644
--- a/apps/docu/README.md
+++ b/apps/docu/README.md
@@ -8,10 +8,11 @@ pnpm --filter @repo/docu dev
 
 http://localhost:3002. Live: [https://basilic-docs.vercel.app/docs](https://basilic-docs.vercel.app/docs).
 
-Content is `content/docs/` (`architecture`, `development`, `testing`, `deployment`, `adrs`). Sidebar order is each folder’s `meta.json`.
+Content is `content/docs/` (`product`, `architecture`, `development`, `testing`, `deployment`, `adrs`). Sidebar order is each folder’s `meta.json`.
 
 **Crawl / LLM:** [`/robots.txt`](https://basilic-docs.vercel.app/robots.txt), [`/sitemap.xml`](https://basilic-docs.vercel.app/sitemap.xml), [`/llms.txt`](https://basilic-docs.vercel.app/llms.txt), [`/llms-full.txt`](https://basilic-docs.vercel.app/llms-full.txt). Policy: [Docs host crawl](content/docs/deployment/vercel.mdx#docs-host-crawl).
 
+- [Product](content/docs/product/index.mdx)
 - [Getting Started](content/docs/development/index.mdx)
 - [AI Workflow](content/docs/development/ai-workflow.mdx)
 - [Architecture](content/docs/architecture/index.mdx)
diff --git a/apps/docu/content/docs/architecture/authentication.mdx b/apps/docu/content/docs/architecture/authentication.mdx
index 91d075d0..2337795e 100644
--- a/apps/docu/content/docs/architecture/authentication.mdx
+++ b/apps/docu/content/docs/architecture/authentication.mdx
@@ -67,7 +67,7 @@ Passkey **verify** consumes the auth challenge before WebAuthn verification (one
 
 ## Web (Next.js)
 
-Callback routes under `/auth/callback/*` exchange with Fastify, set cookies, redirect to `/`. `/auth/logout` revokes the session and clears cookies. `/auth/session/revoke` consumes the email token (works logged out) and clears `api.session` when the current JWT session was the one revoked. Client-side token persistence goes through `POST /api/auth/update-tokens`, which accepts same-origin requests only and calls Fastify `POST /auth/session/validate-tokens` before writing `api.session`. After login, home includes link-wallet and link-email.
+Callback routes under `/auth/callback/*` exchange with Fastify, set cookies, redirect to `/`. `/auth/logout` revokes the session and clears cookies. `/auth/session/revoke` consumes the email token (works logged out) and clears `api.session` when the current JWT session was the one revoked. Client-side token persistence goes through `POST /api/auth/update-tokens`, which accepts same-origin requests only and calls Fastify `POST /auth/session/validate-tokens` before writing `api.session`. After login, home is the news dashboard. Settings covers profile, sessions, and API keys. Change-email lives in Settings. Link-email and Web3 link exist on the API and in `@repo/react` — **web has no link-wallet or link-email UI**. See [Frontend](/docs/architecture/frontend).
 
 ### Web auth gate
 
diff --git a/apps/docu/content/docs/development/index.mdx b/apps/docu/content/docs/development/index.mdx
index 39021858..0e79b0ef 100644
--- a/apps/docu/content/docs/development/index.mdx
+++ b/apps/docu/content/docs/development/index.mdx
@@ -42,8 +42,10 @@ Local Postgres via Supabase: `pnpm --filter @repo/api db:start`, then **`pnpm re
 
 ## Next
 
+- [Product](/docs/product) — starter vs demo, feature map
 - [Dev Environments](/docs/development/dev-environments) — ports, remote, Expo
-- [AI Workflow](/docs/development/ai-workflow) — Cursor-first (Claude Code supported)
+- [AI Workflow](/docs/development/ai-workflow) — Cursor-first; FIRST / `_first/` load order
+- FIRST adopter pack: repo `_first/README.md` (stations and overlays; not a second docs site)
 - [Cursor Setup](/docs/development/cursor-setup) — indexed docs and MCP
 - [Cursor Skills](/docs/development/cursor-skills) — versioned tech skills and slash workflows
 - [Architecture](/docs/architecture)
diff --git a/apps/docu/content/docs/index.mdx b/apps/docu/content/docs/index.mdx
index 4ab42d89..bfec3a83 100644
--- a/apps/docu/content/docs/index.mdx
+++ b/apps/docu/content/docs/index.mdx
@@ -3,13 +3,27 @@ title: "Introduction"
 description: "App development toolkit: starters, conventions, and tooling for web, API, and mobile."
 ---
 
-Portable architecture, a Fastify REST API with OpenAPI-generated clients, self-hosted Web2/Web3 auth, and a Cursor-first AI workflow. Shared packages keep web, mobile, and docs consistent.
+Developer starter: a Fastify REST API with OpenAPI-generated clients, self-hosted Web2 auth (Web3 on the API, no web wallet UI), and a Cursor-first workflow. Shared packages keep web, mobile, and docs consistent. Product intent: [Product](/docs/product).
 
 LLM-friendly index: [`/llms.txt`](/llms.txt) (table of contents) and [`/llms-full.txt`](/llms-full.txt) (full text dump).
 
 ## Explore the docs
 
 <div className="grid grid-cols-1 gap-4 md:grid-cols-2 my-8">
+  <div className="rounded-lg border border-border bg-card p-6">
+    <div className="mb-2 flex items-center gap-2">
+      <h3 className="text-lg font-semibold">Product</h3>
+    </div>
+    <p className="text-sm text-muted-foreground">
+      Starter vs demo, feature map, goals and non-goals.
+    </p>
+    <div className="mt-4">
+      <a href="/docs/product" className="text-sm font-medium text-primary hover:underline">
+        Learn more →
+      </a>
+    </div>
+  </div>
+
   <div className="rounded-lg border border-border bg-card p-6">
     <div className="mb-2 flex items-center gap-2">
       <h3 className="text-lg font-semibold">Architecture</h3>
diff --git a/apps/docu/content/docs/meta.json b/apps/docu/content/docs/meta.json
index 21fdd003..267ed095 100644
--- a/apps/docu/content/docs/meta.json
+++ b/apps/docu/content/docs/meta.json
@@ -1,3 +1,3 @@
 {
-  "pages": ["index", "architecture", "development", "testing", "deployment", "adrs"]
+  "pages": ["index", "product", "architecture", "development", "testing", "deployment", "adrs"]
 }
diff --git a/apps/docu/content/docs/product/features.mdx b/apps/docu/content/docs/product/features.mdx
new file mode 100644
index 00000000..519a2280
--- /dev/null
+++ b/apps/docu/content/docs/product/features.mdx
@@ -0,0 +1,55 @@
+---
+title: Feature map
+description: Shipped spine, demo chrome, packages without web UX, inactive scaffolds, R0 non-goals, and the PD demo bet.
+---
+
+Status is what the tree does today, not a wish list. Roadmap horizons live in a later Product page.
+
+## Spine (fork-and-run)
+
+Must work after clone → `pnpm setup` → `db:start` → `pnpm reset` → `pnpm dev`.
+
+- Fastify TypeBox API → generated OpenAPI → `@repo/core` / handwritten `@repo/react`
+- Auth: magic link (Resend **or** `ALLOW_TEST` + `test@test.ai`) → cookies → `/`
+- Optional OAuth (unconfigured = disabled / 503)
+- Passkeys, sessions, API keys `bask_`, Settings profile and security
+- Next 16 web app gated by `apps/web/proxy.ts`
+- Docs site (`apps/docu`), Cursor rules, basilic-skills playbooks
+- `@repo/ui` tokens in `packages/ui/src/styles/tokens.css`
+- `@repo/email` for auth mail; CLI with API key only
+- Pino `reqId`; `GET /health` `{ ok, dbReady }`
+
+## Demo chrome (thin on purpose)
+
+- News home (`/`) — NewsAPI or explicit empty state when the key is unset
+- Markets (`/markets`) — public CoinGecko table, not on-chain
+- In-shell assistant — `getAccountInfo` / `__render: 'user-info'` (needs an AI provider key; Ollama is the free local path)
+
+## Shipped in API or packages, not in web UX
+
+- Web3 SIWE/SIWS + Next `/auth/callback/web3` — **no wallet connect UI, no Wagmi**
+- `@repo/utils/web3` chain metadata and RPC helpers
+- Link-email API and `@repo/react` hooks — **no web UI** (change-email exists in Settings)
+
+## Scaffold or inactive
+
+- Expo UI scaffold — not an API client
+- `capture()` analytics — specified and instrumented, not collected (PostHog not installed)
+- Sentry packages — installed, inactive
+- Ollama provider — real, not the default when Anthropic or OpenRouter is set
+
+## R0 non-goals
+
+Wallet UI / Wagmi / Solana adapter in web · mobile as API client · PostHog install · Sentry on · Cache Components on · billed SaaS · first-class OpenAI SDK · GCP/AWS as first-class deploy · FIRST CLI / `first.json` / FIRST as a Cursor skill.
+
+## PD (intended — not shipped)
+
+Reshape the signed-in demo around **Markets + GenAI artifacts**: CoinGecko or a checked-in mock (no CoinGecko key required), one new chat tool and one json-render catalog, keep `getAccountInfo`. No wallet UI. No Fastify markets CRUD. No extra CI workflow. News stays thin or becomes supporting copy.
+
+Until PD ships, do not describe Basilic as a markets product or a wallet demo.
+
+## Related
+
+- [Product](/docs/product)
+- [AI](/docs/architecture/ai)
+- [Frontend](/docs/architecture/frontend)
diff --git a/apps/docu/content/docs/product/index.mdx b/apps/docu/content/docs/product/index.mdx
new file mode 100644
index 00000000..3d764aa0
--- /dev/null
+++ b/apps/docu/content/docs/product/index.mdx
@@ -0,0 +1,45 @@
+---
+title: Product
+description: What Basilic is, who it is for, what we are not building, and how we will know.
+---
+
+Basilic is a **developer starter** (fork-and-run toolkit): Fastify + OpenAPI, Next.js, Expo scaffold, Cursor workflow, and a thin web demo that proves auth and the API. It is not a billed SaaS. Do not invent TAM or LTV.
+
+Owner until this page says otherwise: **Gabo Esquivel**.
+
+## Two audiences
+
+**Adopters** clone the repo, run the stack locally, and copy patterns. First successful use is clone → [Getting Started](/docs/development) → magic-link (or `ALLOW_TEST` + `test@test.ai`) to `/`.
+
+**Demo users** sign in to the web app. The shipped job is auth (sessions, API keys, settings). News, Markets, and the in-shell assistant are demo chrome. The intended reshape of that chrome is named on [Features](/docs/product/features) (PD) — not shipped yet.
+
+## Goal
+
+A portable typed API plus web, mobile scaffold, and docs so an adopting developer does not invent the stack. Self-hosted Web2 auth is the spine. Web3 auth exists on Fastify; the web app has **no wallet UI**.
+
+## Non-goals (R0)
+
+- Wallet connect UI, Wagmi, or a Solana adapter in `apps/web`
+- Mobile as an `@repo/core` API client
+- Installing PostHog or turning Sentry on
+- Next.js Cache Components on
+- First-class OpenAI SDK (chat uses Anthropic → OpenRouter → Ollama)
+- GCP/AWS as the shipped deploy path (Vercel + Supabase is documented)
+- FIRST CLI, `first.json`, or FIRST as a Cursor skill
+- Billed SaaS metrics
+
+## How we will know
+
+`pnpm qa` going green is Quality and Pipelines, not product success.
+
+Auth (`auth_succeeded` / `auth_failed`) and assistant (`assistant_turn` with `accountRender`) are **instrumented** via `capture()` and **not collected** — PostHog is chosen, not installed. Those jobs are therefore **unmeasured**. Factory GTM, demo surface quality, and cost-per-job are unmeasured.
+
+Finance: **N/A** (toolkit).
+
+## Related
+
+- [Feature map](/docs/product/features)
+- [Authentication](/docs/architecture/authentication)
+- [Frontend](/docs/architecture/frontend) — no wallet UI
+- [Product analytics](/docs/architecture/analytics)
+- [ADR 011](/docs/adrs/011-product-analytics)
diff --git a/apps/docu/content/docs/product/meta.json b/apps/docu/content/docs/product/meta.json
new file mode 100644
index 00000000..75c4fb85
--- /dev/null
+++ b/apps/docu/content/docs/product/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Product",
+  "pages": ["index", "features"]
+}

From 07a34dc3f17367fdf7d65c7b40af3dbb837a10c5 Mon Sep 17 00:00:00 2001
From: Gabo Esquivel <contact@gaboesquivel.com>
Date: Fri, 4 Sep 2026 18:51:29 -0600
Subject: [PATCH 2/2] docs(docu): name Product Ready fork-and-run bar (#182)

* docs(docu): name Product Ready fork-and-run bar

Document db:start and pnpm reset before pnpm dev. Quality is that checklist, not CI green. Vendor the onboard playbook.

* docs(docu): add product roadmap and issue backlog (#187)

Place R0, R-demo, and later bets in Fumadocs. GitHub Issues are the backlog; __dev is scratch. R0 needs no release.
---
 .../workflow/onboard-new-developer/SKILL.md   | 18 +++++----
 README.md                                     |  5 ++-
 _first/basilic/DOCUMENTATION.md               |  1 +
 _first/basilic/JOURNEYS.md                    |  1 +
 _first/basilic/PIPELINES.md                   |  1 +
 _first/basilic/PRODUCT.md                     | 10 ++---
 _first/basilic/QUALITY.md                     |  7 ++--
 _first/basilic/WORKFLOW.md                    |  8 ++--
 apps/api/README.md                            |  2 +-
 apps/docu/README.md                           |  1 +
 apps/docu/content/docs/development/index.mdx  |  7 +++-
 apps/docu/content/docs/index.mdx              |  4 +-
 apps/docu/content/docs/product/features.mdx   |  2 +-
 apps/docu/content/docs/product/index.mdx      |  5 ++-
 apps/docu/content/docs/product/meta.json      |  2 +-
 apps/docu/content/docs/product/roadmap.mdx    | 39 +++++++++++++++++++
 apps/docu/content/docs/testing/index.mdx      |  1 +
 apps/docu/content/docs/testing/meta.json      |  2 +-
 .../content/docs/testing/product-ready.mdx    | 36 +++++++++++++++++
 apps/web/README.md                            |  2 +-
 20 files changed, 121 insertions(+), 33 deletions(-)
 create mode 100644 apps/docu/content/docs/product/roadmap.mdx
 create mode 100644 apps/docu/content/docs/testing/product-ready.mdx

diff --git a/.agents/skills/workflow/onboard-new-developer/SKILL.md b/.agents/skills/workflow/onboard-new-developer/SKILL.md
index 89846e2c..7531ccd8 100644
--- a/.agents/skills/workflow/onboard-new-developer/SKILL.md
+++ b/.agents/skills/workflow/onboard-new-developer/SKILL.md
@@ -4,13 +4,15 @@ description: Comprehensive onboarding process to get new developer up and runnin
 disable-model-invocation: true
 ---
 
-Comprehensive onboarding process to get new developer up and running quickly.
+Comprehensive onboarding process to get a new developer up and running quickly. Product Ready is this fork-and-run path, not CI green. Canonical checklist: `apps/docu/content/docs/testing/product-ready.mdx`.
 
-1. **Environment setup**: Install required tools, set up development environment, configure IDE/extensions, set up git/SSH keys
-2. **Clone and setup**: Run `pnpm setup` at repo root
+1. **Environment setup**: Install required tools, set up development environment, configure IDE/extensions, set up git/SSH keys (Node 24, pnpm from `packageManager`)
+2. **Clone and setup**: Run `pnpm setup` at repo root (install, hooks, env templates, Docker/Supabase CLI, Playwright)
 3. **Decide context**: Local only, or remote VPC? (Remote VPC = dev machine in cloud; trade-offs: networking, access, cost, latency. See `apps/docu/content/docs/development/dev-environments.mdx`.)
-4. **Run web/API**: `pnpm dev` (API + Next.js)
-5. **Run mobile (optional)**: `pnpm --filter @repo/mobile start` (or `start:localhost` / `start:tunnel` for remote). See `apps/docu/content/docs/development/dev-environments.mdx`
-6. **Verify**: Simulator/device can load the app and reach the API
-7. **Project familiarization**: Review project structure, understand architecture, read key documentation, set up local database, verify all tests passing, submit first PR
-
+4. **Start local Postgres**: `pnpm --filter @repo/api db:start` (`setup` does not start Supabase)
+5. **Reset and seed**: `pnpm reset` from repo root (Supabase reset + Drizzle migrate + seed). See `apps/api/README.md` and ADR 008
+6. **Run web/API**: `pnpm dev` (API + Next.js)
+7. **First login**: Magic link, or `ALLOW_TEST=true` + `test@test.ai`. Signed-in home is `/`
+8. **Run mobile (optional)**: `pnpm --filter @repo/mobile start` (or `start:localhost` / `start:tunnel` for remote). See `apps/docu/content/docs/development/dev-environments.mdx`
+9. **Verify**: Web loads, API `GET /health` succeeds, simulator/device can reach the API if running mobile
+10. **Project familiarization**: Review `_first/`, Product docs, architecture MDX; run tests when changing code; submit first PR
diff --git a/README.md b/README.md
index 96ce06e7..561cca04 100644
--- a/README.md
+++ b/README.md
@@ -95,8 +95,9 @@ Run with `pnpm <script>`.
 
 Full docs: [basilic-docs.vercel.app](https://basilic-docs.vercel.app/docs)
 
-- [Product](https://basilic-docs.vercel.app/docs/product) — what Basilic is, feature map, non-goals
-- [Getting Started](https://basilic-docs.vercel.app/docs/development) — clone, `pnpm setup`, `db:start`, `pnpm reset`
+- [Product](https://basilic-docs.vercel.app/docs/product) — what Basilic is, feature map, roadmap
+- [Getting Started](https://basilic-docs.vercel.app/docs/development) — clone, `pnpm setup`, `db:start`, `pnpm reset`, `pnpm dev`
+- [Product Ready](https://basilic-docs.vercel.app/docs/testing/product-ready) — fork-and-run bar (not CI green)
 - [Dev Environments](https://basilic-docs.vercel.app/docs/development/dev-environments) — Local vs remote (ports 3000, 3001, 8081; `start:localhost`, `start:tunnel`)
 - FIRST factory (stations, overlays): [`_first/`](_first/README.md) — load `_first/AGENTS.md` then `_first/ABOUT.md` then `_first/FIRST.md`. See [AI Workflow](https://basilic-docs.vercel.app/docs/development/ai-workflow)
 
diff --git a/_first/basilic/DOCUMENTATION.md b/_first/basilic/DOCUMENTATION.md
index 876daff5..46bbf539 100644
--- a/_first/basilic/DOCUMENTATION.md
+++ b/_first/basilic/DOCUMENTATION.md
@@ -21,6 +21,7 @@ Consequential decisions, conventions, setup steps, and domain context live in di
 - **Fact:** Public LLM indexes: `/llms.txt`, `/llms-full.txt` on the docs site
 - **Fact:** Portable factory: vendored `../AGENTS.md`, `../ABOUT.md`, `../principles/`. This folder is the Basilic adoption pack, not a second docs site. Essays live in [`blockmatic/first`](https://github.com/blockmatic/first/tree/main/_first/articles).
 - **Fact:** Same-change rule: update matching MDX when behavior, commands, or conventions change
+- **Fact:** `__dev/` is gitignored scratch. Do not treat it as Fact or as the backlog. Remembered decisions go in `apps/docu` or ADRs.
 - **Drift:** named in sibling instances (PostHog, “API as source of truth”, portability vs Vercel). Fix MDX in the same work when you change the fact; do not leave load-bearing drift only in chat.
 
 ## Minimum Useful Artifact
diff --git a/_first/basilic/JOURNEYS.md b/_first/basilic/JOURNEYS.md
index 61f1c1c8..f4dc84d7 100644
--- a/_first/basilic/JOURNEYS.md
+++ b/_first/basilic/JOURNEYS.md
@@ -16,6 +16,7 @@ Actors, entry points, happy paths, alternates, error paths, permission gates, an
 
 - **Fact:** [authentication.mdx](../../apps/docu/content/docs/architecture/authentication.mdx), [account-linking.mdx](../../apps/docu/content/docs/architecture/account-linking.mdx)
 - **Fact:** Web gate: [`../../apps/web/proxy.ts`](../../apps/web/proxy.ts). Public: `/auth/login`, `/auth/callback/*`, `/auth/logout`, `/auth/session/revoke`, `/terms`, `/privacy`, `/images/auth-login-hero.webp`. Unauthenticated → login. Authenticated on login → `/`. Token refresh on navigation.
+- **Fact:** Adopter first-success: [product-ready.mdx](../../apps/docu/content/docs/testing/product-ready.mdx) (`db:start` + `pnpm reset` + `pnpm dev` + first login). Not CI green.
 - **Fact:** Actors: web end user; adopting developer; CLI/agent with API key; CI/CodeRabbit/DeepSec; mobile user (**deferred**)
 - **Fact:** Login methods: magic link (`token`+`verificationId` or `token`+`email`); OAuth GitHub/Google/Facebook/Twitter; passkey; Web3 EIP-155/Solana on the API. TOTP is 2FA only.
 - **Fact:** E2E magic link: `test@test.ai` when `ALLOW_TEST=true`
diff --git a/_first/basilic/PIPELINES.md b/_first/basilic/PIPELINES.md
index 696340b9..5e3d84f8 100644
--- a/_first/basilic/PIPELINES.md
+++ b/_first/basilic/PIPELINES.md
@@ -22,6 +22,7 @@ Changes flow through an automated path: format → lint → typecheck → test 
 - **Fact:** Local: `pnpm qa` via [`../../scripts/run-qa.mjs`](../../scripts/run-qa.mjs) — checktypes → lint → generate + drift → build → unit → e2e (`SKIP_BUILD=1`)
 - **Fact:** Vercel git deploys web/api/docu ([vercel.mdx](../../apps/docu/content/docs/deployment/vercel.mdx)). CI does **not** deploy. Preview migrate gated unless `RUN_PG_MIGRATE=true`.
 - **Fact:** `web-e2e` needs `ANTHROPIC_API_KEY`
+- **Fact:** R0 is documentation alignment. It does not require a GitHub Release or a version bump. Preview deploys still run from git as usual.
 - **Unresolved:** commit-stage artifact identity and promote-without-rebuild (hosts rebuild from git)
 
 ## Minimum Useful Artifact
diff --git a/_first/basilic/PRODUCT.md b/_first/basilic/PRODUCT.md
index 8ba7bc06..65a7d563 100644
--- a/_first/basilic/PRODUCT.md
+++ b/_first/basilic/PRODUCT.md
@@ -14,11 +14,11 @@ The project has an inspectable answer to what, why, and how we will know. Non-go
 
 ## Artifacts
 
-- **Fact:** Canonical product brief: [product/index.mdx](../../apps/docu/content/docs/product/index.mdx) and [product/features.mdx](../../apps/docu/content/docs/product/features.mdx)
+- **Fact:** Canonical product brief: [product/index.mdx](../../apps/docu/content/docs/product/index.mdx), [product/features.mdx](../../apps/docu/content/docs/product/features.mdx), [product/roadmap.mdx](../../apps/docu/content/docs/product/roadmap.mdx)
 - **Fact:** [`../../README.md`](../../README.md) — fork-and-run TypeScript fullstack starter (Fastify, OpenAPI, Next, Expo scaffold). No Wagmi, no first-class OpenAI SDK, no web wallet UI
 - **Fact:** [`../../apps/docu/content/docs/index.mdx`](../../apps/docu/content/docs/index.mdx) — toolkit intro; Product is in the docs nav
 - **Fact:** Two audiences: **adopters** (developers using the starter) and **demo users** (web news `/`, markets, settings, in-shell assistant; auth is the shipped job)
-- **Fact:** GTM: clone + [Getting Started](../../apps/docu/content/docs/development/index.mdx) + first local login. Finance **N/A** (toolkit)
+- **Fact:** GTM: clone + [Getting Started](../../apps/docu/content/docs/development/index.mdx) (`db:start`, `pnpm reset`) + first local login. Bar: [Product Ready](../../apps/docu/content/docs/testing/product-ready.mdx). Finance **N/A** (toolkit)
 - **Fact:** Owner: Gabo Esquivel (named on product index)
 - **Fact:** New-device sign-in alerts are transactional email via Fastify `emailProvider` + `@repo/email`, not a notification product
 - **Fact:** Not a billed SaaS in files. Do not invent TAM/LTV
@@ -28,7 +28,7 @@ The project has an inspectable answer to what, why, and how we will know. Non-go
 - **Fact:** PD (Markets + GenAI artifacts) is named on the feature map as **intended**, not shipped
 - **Unresolved:** PostHog install / consent / retention; keep / iterate / kill board; whether adopters copy `lib/analytics`
 
-`pnpm qa` going green is Quality/Pipelines, not product success.
+`pnpm qa` going green is Pipelines, not product success. Quality for R0 is [Product Ready](../../apps/docu/content/docs/testing/product-ready.mdx).
 
 ## Minimum Useful Artifact
 
@@ -36,7 +36,7 @@ The project has an inspectable answer to what, why, and how we will know. Non-go
 - users: adopting developers; demo end users on web auth and dashboard
 - goal: portable starter with self-hosted Web2 auth and Cursor-first workflow (Web3 on API only)
 - non-goals: [product/index.mdx](../../apps/docu/content/docs/product/index.mdx) R0 list
-- audience/channel/first use: clone + Getting Started + first local login
+- audience/channel/first use: clone + Getting Started (`db:start`, `pnpm reset`) + first local login ([Product Ready](../../apps/docu/content/docs/testing/product-ready.mdx))
 - metrics: auth and assistant jobs **instrumented, not collected**
 - events: `auth_succeeded`, `auth_failed`, `assistant_turn` — specified + instrumented, no sink
 - owners: Gabo Esquivel
@@ -56,7 +56,7 @@ The project has an inspectable answer to what, why, and how we will know. Non-go
 
 - A new contributor can answer what we are building from `apps/docu` Product pages + README without `__dev/`
 - Success metrics can fail. They are not CI green. Auth/assistant remain unmeasured (no sink)
-- GTM is clone + Getting Started. Finance N/A
+- GTM is clone + Getting Started. Product Ready is that path, not CI green. Finance N/A
 - No silent product decisions in code without a note or open question
 
 ## Definition of Done
diff --git a/_first/basilic/QUALITY.md b/_first/basilic/QUALITY.md
index b869c039..08e48bfb 100644
--- a/_first/basilic/QUALITY.md
+++ b/_first/basilic/QUALITY.md
@@ -14,7 +14,7 @@ Acceptance criteria exist for features that matter. Tests protect critical paths
 
 ## Artifacts
 
-- **Fact:** [testing/index.mdx](../../apps/docu/content/docs/testing/index.mdx), [e2e-testing.mdx](../../apps/docu/content/docs/testing/e2e-testing.mdx)
+- **Fact:** [testing/index.mdx](../../apps/docu/content/docs/testing/index.mdx), [product-ready.mdx](../../apps/docu/content/docs/testing/product-ready.mdx), [e2e-testing.mdx](../../apps/docu/content/docs/testing/e2e-testing.mdx)
 - **Fact:** API: Vitest + `fastify.inject()`, group `*.spec.ts` imports `*.test.ts`, PGLite, serial workers, orphan import check
 - **Fact:** Packages: Vitest for `core`, `react`, `error`
 - **Fact:** Web: Playwright only (no frontend unit suite). Maestro deferred in CI.
@@ -22,12 +22,13 @@ Acceptance criteria exist for features that matter. Tests protect critical paths
 - **Fact:** AI: contract tests hard; remote may `ctx.skip()` when key missing or 402 — never return early without skip (soft-pass forbidden). With real key, 502/503/504 fail.
 - **Fact:** Coverage: `pnpm --filter @repo/api test:cov` uploaded; **no floors** in CI
 - **Fact:** Playbooks: `write-api-test`, `write-unit-tests`, `use-tdd`, `run-all-tests-and-fix`
-- **Unresolved:** named release bar beyond “CI green”; eval datasets for `/ai/chat` and `/ai/generate`; performance budgets; visual regression
+- **Fact:** Product Ready (R0 bar) is the fork-and-run checklist on [product-ready.mdx](../../apps/docu/content/docs/testing/product-ready.mdx), not CI green. Pipelines run CI.
+- **Unresolved:** eval datasets for `/ai/chat` and `/ai/generate`; performance budgets; visual regression
 
 ## Minimum Useful Artifact
 
 - risk: auth, health, catalog errors, OpenAPI drift
-- criterion: API test or Playwright spec asserting behavior
+- criterion: API test or Playwright spec asserting behavior; adopter bar is [product-ready.mdx](../../apps/docu/content/docs/testing/product-ready.mdx)
 - eval/budget: **unresolved** for probabilistic AI and perf
 - command: `pnpm --filter @repo/api test:unit`, `pnpm test:e2e`
 - on fail: fix or escalate; do not skip remote AI without `ctx.skip()`
diff --git a/_first/basilic/WORKFLOW.md b/_first/basilic/WORKFLOW.md
index f0552556..a6676bbf 100644
--- a/_first/basilic/WORKFLOW.md
+++ b/_first/basilic/WORKFLOW.md
@@ -14,10 +14,10 @@ Work flows through a recognizable path: idea → plan → implement → review 
 
 ## Artifacts
 
-- **Fact:** Path: plan (`/plan-feature`) → review → implement (`/exec-push`) → `/git-commit` → PR → CI + CodeRabbit → `/retro`
+- **Fact:** Work state: GitHub Issues and pull requests. There is no `BACKLOG.md`. `__dev/` is gitignored scratch, not the backlog.
+- **Fact:** Path: plan (`/plan-feature`) → review → implement → `/git-commit` → `/git-create-pr` → CI + CodeRabbit → `/retro`. Prefer `/git-create-pr` (description + labels) over `/exec-push`.
 - **Fact:** Index: [ai-workflow.mdx](../../apps/docu/content/docs/development/ai-workflow.mdx)
 - **Fact:** Playbooks: `.agents/skills/workflow/` — `plan-feature`, `exec-push`, `git-commit`, `code-review`, `deslop`, `retro`, `git-create-pr`
-- **Fact:** Work state: GitHub issues and pull requests
 - **Fact:** Consequential decisions: ADRs and `apps/docu`
 - **Fact:** Git: default global user; Conventional Commits; never `--no-verify`; never Co-authored-by trailers ([git.mdc](../../.cursor/rules/base/git.mdc))
 - **Fact:** Human gates: product scope, secrets/trust boundaries, destructive ops ([`../AGENTS.md`](../AGENTS.md))
@@ -29,7 +29,7 @@ Work flows through a recognizable path: idea → plan → implement → review 
 - plan and acceptance criteria: `/plan-feature` for non-trivial work
 - actors: human, agent, CI, CodeRabbit
 - gates: product, security, destructive — ask a human
-- validation: CI; learning: `/retro` and durable files when decisions changed
+- validation: Product Ready for adopter bar; CI for Pipelines; learning: `/retro` and durable files when decisions changed
 
 ## Recipe
 
@@ -59,7 +59,7 @@ Apply Workflow First to Basilic.
 
 Read current issues/PRs, ai-workflow MDX, and `.agents/skills/workflow/` before acting. Do not rely on chat as the system of record.
 
-Propose before implementing on non-trivial work. Implement in reviewable chunks. Use `/exec-push` and `/git-commit`. Never `--no-verify`. Use the default global git user.
+Propose before implementing on non-trivial work. Implement in reviewable chunks. Use `/git-commit` and `/git-create-pr`. Never `--no-verify`. Use the default global git user.
 
 Stop and ask a human for product scope, security-sensitive changes, and destructive operations. Update issues, PRs, and documentation as work progresses. Preserve intentional existing process.
 
diff --git a/apps/api/README.md b/apps/api/README.md
index 1053b492..70b0aba5 100644
--- a/apps/api/README.md
+++ b/apps/api/README.md
@@ -4,7 +4,7 @@ Type-safe REST API built with Fastify & OpenAPI. Routes in `src/routes/` are the
 
 ## Development
 
-Copy [`.env.defaults.example`](.env.defaults.example) to `.env` and set values (gitignored). Start database first (`pnpm db:start`), then `pnpm dev`. Uses Supabase CLI for PostgreSQL, or `PGLITE=true` for in-memory. Dev server at [http://localhost:3001](http://localhost:3001).
+Copy [`.env.defaults.example`](.env.defaults.example) to `.env` and set values (gitignored). Start database first (`pnpm db:start`), then **`pnpm reset`** from the repo root (or `pnpm reset` here) before `pnpm dev`. Uses Supabase CLI for PostgreSQL, or `PGLITE=true` for in-memory. Dev server at [http://localhost:3001](http://localhost:3001). Adopter bar: [Product Ready](../docu/content/docs/testing/product-ready.mdx).
 
 **Switching project_id:** If you change `project_id` in `supabase/config.toml` (e.g. after a rebrand), run `pnpm db:stop` before `pnpm db:start`—only one Supabase instance runs per host.
 
diff --git a/apps/docu/README.md b/apps/docu/README.md
index af1cd810..572af28d 100644
--- a/apps/docu/README.md
+++ b/apps/docu/README.md
@@ -14,6 +14,7 @@ Content is `content/docs/` (`product`, `architecture`, `development`, `testing`,
 
 - [Product](content/docs/product/index.mdx)
 - [Getting Started](content/docs/development/index.mdx)
+- [Product Ready](content/docs/testing/product-ready.mdx)
 - [AI Workflow](content/docs/development/ai-workflow.mdx)
 - [Architecture](content/docs/architecture/index.mdx)
 - [Security](content/docs/architecture/security.mdx)
diff --git a/apps/docu/content/docs/development/index.mdx b/apps/docu/content/docs/development/index.mdx
index 0e79b0ef..26fd5841 100644
--- a/apps/docu/content/docs/development/index.mdx
+++ b/apps/docu/content/docs/development/index.mdx
@@ -23,9 +23,11 @@ cd <project-name>
 pnpm run setup
 ```
 
-`setup` installs dependencies, git hooks, security tools, and the database. It also copies `.env.<qualifier>.example` templates to gitignored dest files when those dest files are missing. Edit the copied files to set secrets.
+`setup` installs dependencies, git hooks, security tools, and database **tooling**. It also copies `.env.<qualifier>.example` templates to gitignored dest files when those dest files are missing. Edit the copied files to set secrets. `setup` does **not** start Postgres.
 
 ```bash
+pnpm --filter @repo/api db:start
+pnpm reset
 pnpm dev
 ```
 
@@ -38,11 +40,12 @@ pnpm dev
 
 **Packages:** `core`, `react`, `ui`, `utils`, `error`, `email`, `cli`. Catalog: [Packages](/docs/development/packages).
 
-Local Postgres via Supabase: `pnpm --filter @repo/api db:start`, then **`pnpm reset`** from the repo root. See [ADR 008](/docs/adrs/008-database).
+Local Postgres is Supabase CLI. `db:start` then **`pnpm reset`** (repo root) before `pnpm dev`. See [ADR 008](/docs/adrs/008-database) and [Product Ready](/docs/testing/product-ready).
 
 ## Next
 
 - [Product](/docs/product) — starter vs demo, feature map
+- [Product Ready](/docs/testing/product-ready) — fork-and-run bar (not CI green)
 - [Dev Environments](/docs/development/dev-environments) — ports, remote, Expo
 - [AI Workflow](/docs/development/ai-workflow) — Cursor-first; FIRST / `_first/` load order
 - FIRST adopter pack: repo `_first/README.md` (stations and overlays; not a second docs site)
diff --git a/apps/docu/content/docs/index.mdx b/apps/docu/content/docs/index.mdx
index bfec3a83..84d657f3 100644
--- a/apps/docu/content/docs/index.mdx
+++ b/apps/docu/content/docs/index.mdx
@@ -15,7 +15,7 @@ LLM-friendly index: [`/llms.txt`](/llms.txt) (table of contents) and [`/llms-ful
       <h3 className="text-lg font-semibold">Product</h3>
     </div>
     <p className="text-sm text-muted-foreground">
-      Starter vs demo, feature map, goals and non-goals.
+      Starter vs demo, feature map, goals, and roadmap.
     </p>
     <div className="mt-4">
       <a href="/docs/product" className="text-sm font-medium text-primary hover:underline">
@@ -57,7 +57,7 @@ LLM-friendly index: [`/llms.txt`](/llms.txt) (table of contents) and [`/llms-ful
       <h3 className="text-lg font-semibold">Testing</h3>
     </div>
     <p className="text-sm text-muted-foreground">
-      Vitest for the API and packages; Playwright E2E for web.
+      Vitest, Playwright, and the Product Ready fork-and-run bar.
     </p>
     <div className="mt-4">
       <a href="/docs/testing" className="text-sm font-medium text-primary hover:underline">
diff --git a/apps/docu/content/docs/product/features.mdx b/apps/docu/content/docs/product/features.mdx
index 519a2280..cd841d62 100644
--- a/apps/docu/content/docs/product/features.mdx
+++ b/apps/docu/content/docs/product/features.mdx
@@ -3,7 +3,7 @@ title: Feature map
 description: Shipped spine, demo chrome, packages without web UX, inactive scaffolds, R0 non-goals, and the PD demo bet.
 ---
 
-Status is what the tree does today, not a wish list. Roadmap horizons live in a later Product page.
+Status is what the tree does today, not a wish list. Horizons: [Roadmap](/docs/product/roadmap).
 
 ## Spine (fork-and-run)
 
diff --git a/apps/docu/content/docs/product/index.mdx b/apps/docu/content/docs/product/index.mdx
index 3d764aa0..5d861eae 100644
--- a/apps/docu/content/docs/product/index.mdx
+++ b/apps/docu/content/docs/product/index.mdx
@@ -9,7 +9,7 @@ Owner until this page says otherwise: **Gabo Esquivel**.
 
 ## Two audiences
 
-**Adopters** clone the repo, run the stack locally, and copy patterns. First successful use is clone → [Getting Started](/docs/development) → magic-link (or `ALLOW_TEST` + `test@test.ai`) to `/`.
+**Adopters** clone the repo, run the stack locally, and copy patterns. First successful use is [Product Ready](/docs/testing/product-ready): clone → [Getting Started](/docs/development) (`db:start`, `pnpm reset`, `pnpm dev`) → magic-link (or `ALLOW_TEST` + `test@test.ai`) to `/`.
 
 **Demo users** sign in to the web app. The shipped job is auth (sessions, API keys, settings). News, Markets, and the in-shell assistant are demo chrome. The intended reshape of that chrome is named on [Features](/docs/product/features) (PD) — not shipped yet.
 
@@ -30,7 +30,7 @@ A portable typed API plus web, mobile scaffold, and docs so an adopting develope
 
 ## How we will know
 
-`pnpm qa` going green is Quality and Pipelines, not product success.
+`pnpm qa` going green is **Pipelines**, not product success. The R0 Quality bar is [Product Ready](/docs/testing/product-ready). Horizons: [Roadmap](/docs/product/roadmap).
 
 Auth (`auth_succeeded` / `auth_failed`) and assistant (`assistant_turn` with `accountRender`) are **instrumented** via `capture()` and **not collected** — PostHog is chosen, not installed. Those jobs are therefore **unmeasured**. Factory GTM, demo surface quality, and cost-per-job are unmeasured.
 
@@ -39,6 +39,7 @@ Finance: **N/A** (toolkit).
 ## Related
 
 - [Feature map](/docs/product/features)
+- [Roadmap](/docs/product/roadmap)
 - [Authentication](/docs/architecture/authentication)
 - [Frontend](/docs/architecture/frontend) — no wallet UI
 - [Product analytics](/docs/architecture/analytics)
diff --git a/apps/docu/content/docs/product/meta.json b/apps/docu/content/docs/product/meta.json
index 75c4fb85..c5a1d28a 100644
--- a/apps/docu/content/docs/product/meta.json
+++ b/apps/docu/content/docs/product/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "Product",
-  "pages": ["index", "features"]
+  "pages": ["index", "features", "roadmap"]
 }
diff --git a/apps/docu/content/docs/product/roadmap.mdx b/apps/docu/content/docs/product/roadmap.mdx
new file mode 100644
index 00000000..db1d2d33
--- /dev/null
+++ b/apps/docu/content/docs/product/roadmap.mdx
@@ -0,0 +1,39 @@
+---
+title: Roadmap
+description: R0, R-demo, later bets, and not-now. Backlog is GitHub Issues, not a markdown file.
+---
+
+Horizons, not a sprint board. Work items live in [GitHub Issues](https://github.com/blockmatic/basilic/issues). `__dev/` is gitignored scratch — not Fact, not the backlog.
+
+R0 is **documentation alignment**. It does not need a semver bump or a GitHub Release. Pipelines still run on PRs; Quality is [Product Ready](/docs/testing/product-ready).
+
+## R0 — docs, honesty, onboarding
+
+- Product pages: what Basilic is, [feature map](/docs/product/features), this roadmap
+- Honesty in README and auth docs (starter, not wallet/OpenAI template)
+- [Product Ready](/docs/testing/product-ready): `db:start` + `pnpm reset` before `pnpm dev`
+
+## R-demo — Markets + GenAI artifacts
+
+Named even if the implementation PR is still in flight: CoinGecko or checked-in mock, `getMarketSnapshot` + market-card catalog, Markets as signed-in home. No wallet UI. No Fastify markets CRUD. No extra CI workflow. See [Features](/docs/product/features).
+
+## Later (ask before R0)
+
+Tracked as issues. Do not treat them as committed R1.
+
+- PostHog install — [#183](https://github.com/blockmatic/basilic/issues/183)
+- Turn Sentry on — [#184](https://github.com/blockmatic/basilic/issues/184)
+- Wallet connect UI — [#185](https://github.com/blockmatic/basilic/issues/185)
+- Mobile `@repo/core` client — [#186](https://github.com/blockmatic/basilic/issues/186)
+
+R1 is still a choice among wallet UI, mobile client, and observability — not all three.
+
+## Not now
+
+FIRST CLI, `first.json`, FIRST as a Cursor skill, billed SaaS / TAM-LTV, first-class OpenAI SDK, GCP/AWS as the shipped deploy path, Cache Components on, 13th FIRST station, root `PRODUCT.md` / `ROADMAP.md`.
+
+## Related
+
+- [Product](/docs/product)
+- [Feature map](/docs/product/features)
+- [Product Ready](/docs/testing/product-ready)
diff --git a/apps/docu/content/docs/testing/index.mdx b/apps/docu/content/docs/testing/index.mdx
index 6a3f7b8a..7b0f4908 100644
--- a/apps/docu/content/docs/testing/index.mdx
+++ b/apps/docu/content/docs/testing/index.mdx
@@ -6,6 +6,7 @@ description: "Vitest for the API and packages; Playwright E2E for web. No fronte
 - **API** — Vitest + `fastify.inject()`, blackbox HTTP, in-memory PGlite. Group entry files are `*.spec.ts`; route tests are imported `*.test.ts` (see Fastify testing rules).
 - **Packages** — Vitest unit tests for packages with a `test` script (`core`, `react`, `error`). CI: `packages-test.yml` when `packages/` or `tools/` change.
 - **Web** — Playwright E2E only. Commands, fixtures, and specs: [E2E Testing](/docs/testing/e2e-testing).
+- **Product Ready** — Fork-and-run checklist for adopters ([Product Ready](/docs/testing/product-ready)). That page is the release bar for R0. CI green is Pipelines, not Quality.
 
 PGLite does not support concurrent writers. API Vitest runs with `fileParallelism: false`, `maxWorkers: 1`, and `sequence.concurrent: false`. Between group entry files, `cleanupGroupDatabase()` truncates all 15 schema tables and clears the JWT session pool.
 
diff --git a/apps/docu/content/docs/testing/meta.json b/apps/docu/content/docs/testing/meta.json
index fccd023b..d3fee75c 100644
--- a/apps/docu/content/docs/testing/meta.json
+++ b/apps/docu/content/docs/testing/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "Testing",
-  "pages": ["index", "e2e-testing"]
+  "pages": ["index", "product-ready", "e2e-testing"]
 }
diff --git a/apps/docu/content/docs/testing/product-ready.mdx b/apps/docu/content/docs/testing/product-ready.mdx
new file mode 100644
index 00000000..229a9522
--- /dev/null
+++ b/apps/docu/content/docs/testing/product-ready.mdx
@@ -0,0 +1,36 @@
+---
+title: Product Ready
+description: Fork-and-run bar for Basilic. CI green is Pipelines, not this bar.
+---
+
+**Product Ready** is a local fork that a new developer can clone, start, and sign into without tribal knowledge. It is **not** “CI is green.” Pipelines prove the repo on GitHub Actions. This page is the adopter bar.
+
+Canonical commands: [Getting Started](/docs/development). Playbook: `/onboard-new-developer`.
+
+## Checklist
+
+Do these in order. `pnpm setup` installs tools and copies env templates. It does **not** start Postgres.
+
+1. **Node 24 + pnpm** — `.nvmrc` / `packageManager` (`11.24.0`). `corepack enable` then `corepack prepare pnpm@11.24.0 --activate`.
+2. **Clone** the repo.
+3. **`pnpm setup`** at the repo root (install, hooks, scanners, env templates, Docker/Supabase CLI, Playwright Chromium).
+4. **`pnpm --filter @repo/api db:start`** — local Supabase Postgres. One instance per host; `pnpm db:stop` before changing `project_id`.
+5. **`pnpm reset`** at the repo root — Supabase reset + Drizzle migrate + seed. See [ADR 008](/docs/adrs/008-database) and `apps/api/README.md`.
+6. **`pnpm dev`** — API at http://localhost:3001 (`GET /health`, `/reference`), web at http://localhost:3000.
+7. **First login** — magic link, or `ALLOW_TEST=true` and `test@test.ai`. Land on `/`.
+8. **Optional mobile** — `pnpm --filter @repo/mobile start`. Not required for Product Ready.
+
+Stop if any step fails. Do not skip `db:start` or `pnpm reset` and treat a hanging API as a product bug.
+
+## What this bar is not
+
+- A GitHub Actions green check
+- Production deploy, Sentry, or PostHog
+- Wallet UI or a mobile `@repo/core` client
+- Coverage floors
+
+Those are Pipelines, later bets, or non-goals. See [Product](/docs/product).
+
+## After first login
+
+Auth, sessions, API keys, and settings are the shipped job. Demo chrome (news, markets, assistant) is extra. The feature map names what is intended vs shipped: [Features](/docs/product/features).
diff --git a/apps/web/README.md b/apps/web/README.md
index 8378019f..4c4cbc66 100644
--- a/apps/web/README.md
+++ b/apps/web/README.md
@@ -1,6 +1,6 @@
 # Web App
 
-Next.js 16 dashboard for the Basilic stack: news, markets, settings, and AI assistant chrome. Uses `@repo/core` and `@repo/react` against the Fastify API.
+Next.js 16 dashboard for the Basilic stack: settings, auth chrome, and demo surfaces (news, markets, assistant). Uses `@repo/core` and `@repo/react` against the Fastify API. From the monorepo root, start Postgres (`pnpm --filter @repo/api db:start`), seed (`pnpm reset`), then `pnpm dev`. See [Product Ready](../docu/content/docs/testing/product-ready.mdx).
 
 ## Tech Stack