docs(docu): add product feature map and honesty edits

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,29 +9,29 @@ 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
 
 - **[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)
 

_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)

_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)

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)

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
 

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)

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>

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"]
 }

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)