blockmatic · gaboesquivel · Sep 5, 2026 · Sep 4, 2026 · Sep 5, 2026
diff --git 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
@@ -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,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, 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
@@ -14,13 +14,14 @@ 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)
 - **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
@@ -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
@@ -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
@@ -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), [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) (`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. 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.
+`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
 
 - 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 (`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: **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. 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
 
@@ -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)