chore: polish registry documentation

Refresh the docs to reflect current recipes, readiness states, install order, conventions, and registry scale after the SaaS recipe expansion.

Author: jesseoue

README.md

@@ -82,9 +82,10 @@ Current source registry coverage:
 <details>
 <summary>Current scale</summary>
 
-- 200+ module manifests
+- 294 module manifests
 - 36 canonical categories
-- 9 preset bundles
+- 13 preset bundles
+- 9 architecture recipes
 - provider adapters for Vercel, Cloudflare, Clerk, Supabase, Neon, Upstash, Resend, PostHog, Sentry, Axiom, Unkey, Knock, Tinybird, Trigger.dev, Inngest, GitHub, and more
 
 </details>
@@ -102,6 +103,9 @@ Current source registry coverage:
 | `vercel-native` | Vercel deployment, storage, workflows, edge config, and observability path |
 | `cloudflare-native` | Workers, D1, R2, KV, Queues, Workflows, Turnstile, and Cloudflare-native adapters |
 | `provider-adapters` | Concrete optional provider adapter examples |
+| `api-saas-starter` | API-first SaaS workflow with keys, usage, rate limits, billing, webhooks, docs, and observability |
+| `enterprise-saas` | Enterprise layer with SSO, SCIM, audit, access review, security, SLA, and support workflows |
+| `ai-saas-starter` | AI SaaS workflow with chat, model routing, prompts, evals, RAG, usage metering, and billing |
 
 ```bash
 pnpm registry:presets
@@ -158,6 +162,8 @@ registry/
       tests/checklist.md
   presets/
     <preset>.json
+  recipes/
+    <recipe>.json
   skills/
     <technology>/SKILL.md
 ```
@@ -172,6 +178,8 @@ public/r/
   provider-adapters.json       # installable aggregate preset block
   presets/
     next-saas.json           # StackFoundry preset manifest for tooling/inspection
+  recipes/
+    api-saas-starter.json    # recipe manifest with staged install order
 ```
 
 Generated installable items are `registry:block` payloads with:
@@ -256,16 +264,20 @@ See [`docs/repository.md`](./docs/repository.md) for ownership rules.
 - [Registry](./docs/registry.md)
 - [Modules](./docs/modules.md)
 - [Providers](./docs/providers.md)
+- [Recipes](./docs/recipes.md)
+- [Install order](./docs/install-order.md)
+- [Readiness](./docs/readiness.md)
+- [Conventions](./docs/conventions.md)
 - [Maintenance skills](./docs/maintenance.md)
 - [Repository map](./docs/repository.md)
 - [Registry compatibility](./docs/registry-compat.md)
 
 ## Where This Is Going
 
-- More modules graduating from planned to installable source payloads
+- More stub modules graduating to ready installable source payloads
 - Better diff/update workflows for installed modules
 - More provider adapters without making providers base dependencies
-- More production smoke paths for presets
+- More production smoke paths for presets and recipes
 - Stronger docs around migration, removal, and maintenance ownership
 
 ## Status

docs/index.md

@@ -13,8 +13,9 @@
 
 ## Start Here
 
-1. Read the [Registry](./registry.md) docs.
+1. Read the [Registry](./registry.md), [Readiness](./readiness.md), and [Conventions](./conventions.md) docs.
 2. Inspect the [Recipes](./recipes.md) and [Install order](./install-order.md) docs.
-3. Inspect the first modules in `registry/modules`.
-4. Run `pnpm registry:doctor`.
-5. Try `pnpm stackfoundry add api-keys --target /tmp/app --dry-run`.
+3. Run `pnpm stackfoundry recipes` and `pnpm stackfoundry recipe api-saas-starter`.
+4. Inspect the first modules in `registry/modules`.
+5. Run `pnpm registry:doctor`.
+6. Try `pnpm stackfoundry add api-keys --target /tmp/app --dry-run`.

docs/modules.md

@@ -1,14 +1,14 @@
 # Modules
 
-Modules are the unit of value in StackFoundry.
+Modules are the unit of value in StackFoundry. Recipes are the workflow layer that explains how modules fit together.
 
 The first installable production modules were:
 
 - `drizzle-postgres`
 - `api-keys`
 - `stripe-billing`
 
-The registry now includes core modules, provider adapter examples, and registry-compatible public blocks. Each module should be installable into an existing app as editable source code. Presets are only bundles of modules.
+The registry now includes ready source modules, stub roadmap modules, provider adapter examples, recipes, and registry-compatible public blocks. Each ready module should be installable into an existing app as editable source code. Presets are bundles of modules; recipes are opinionated architecture paths.
 
 Use [Recipes](./recipes.md) and [Install order](./install-order.md) when you want a complete workflow instead of individual blocks.
 
@@ -38,6 +38,19 @@ See [Readiness](./readiness.md) for the meaning of `ready`, `stub`, `planned`, `
 - `quality-tooling`
 - `playwright-e2e`
 
+### Interface Grammar
+
+- `metric-card-grid`
+- `kpi-trend-card`
+- `activity-feed`
+- `timeline`
+- `resource-header`
+- `filter-bar`
+- `saved-views`
+- `bulk-actions-bar`
+- `status-badge-system`
+- `danger-zone-card`
+
 ### Data
 
 - `drizzle-postgres`
@@ -83,6 +96,10 @@ See [Readiness](./readiness.md) for the meaning of `ready`, `stub`, `planned`, `
 - `webhook-inbox`
 - `webhook-delivery`
 - `developer-portal`
+- `api-playground`
+- `request-log-explorer`
+- `usage-event-explorer`
+- `webhook-delivery-detail`
 
 ### Growth and Analytics
 
@@ -110,6 +127,10 @@ See [Readiness](./readiness.md) for the meaning of `ready`, `stub`, `planned`, `
 
 - `background-jobs`
 - `rate-limits`
+- `operator-dashboard`
+- `customer-360`
+- `account-health`
+- `customer-timeline`
 - `sentry-monitoring`
 - `axiom-logging`
 - `audit-log`
@@ -118,6 +139,8 @@ See [Readiness](./readiness.md) for the meaning of `ready`, `stub`, `planned`, `
 - `system-health`
 - `incident-management`
 - `data-import-export`
+- `replay-center`
+- `job-run-detail`
 
 ### Provider Adapter Examples
 
@@ -131,6 +154,30 @@ See [Readiness](./readiness.md) for the meaning of `ready`, `stub`, `planned`, `
 - `posthog-analytics`
 - `arcjet-security`
 
+### Integration Marketplace
+
+- `integration-catalog`
+- `integration-detail-page`
+- `integration-install-flow`
+- `integration-health`
+- `integration-sync-logs`
+
+### Security And Compliance
+
+- `security-center`
+- `security-scorecard`
+- `security-events`
+- `access-review`
+- `api-key-risk-review`
+- `trusted-devices`
+
+### Conventions
+
+- `schema-conventions`
+- `event-taxonomy`
+- `tenant-isolation-policy`
+- `money-and-credits-conventions`
+
 ### Optional AI
 
 - `ai-chat`

docs/recipes.md

@@ -1,6 +1,6 @@
 # Recipes
 
-Recipes are opinionated install paths through the registry. A recipe answers "what should I install together, and in what order?" Presets remain installable bundles; recipes explain the product architecture behind those bundles.
+Recipes are opinionated install paths through the registry. A recipe answers "what should I install together, and in what order?" Presets remain installable bundles; recipes explain the product architecture behind those bundles and can be installed with `stackfoundry add recipe <name>`.
 
 ## Available Recipes
 
@@ -26,6 +26,8 @@ pnpm stackfoundry add recipe api-saas-starter --target ./my-app --dry-run
 
 Recipe definitions live in `registry/recipes/*.json` and are mirrored to `public/r/recipes/*.json` for public inspection.
 
+The most product-ready recipe path today is `api-saas-starter`, which ties together identity, API keys, usage metering, quotas, docs, webhooks, billing, and request visibility. Stub recipes intentionally include stub modules to show the direction of a complete SaaS operating system before every source payload is ready.
+
 ## Recipe Shape
 
 Each recipe includes:

docs/registry.md

@@ -24,7 +24,7 @@ Recipes live in `registry/recipes/*.json` and describe install order across modu
 - `files`: files installed into the target app
 - `drizzle`: schema/migration metadata
 - `maintenance`: maintenance skill and review metadata
-- `status`: planned, experimental, stable
+- `status`: ready, stub, planned, experimental, stable, or deprecated
 
 ## Registry Model
 
@@ -52,10 +52,12 @@ Installers must not overwrite modified user files silently. The installer should
 ```bash
 pnpm registry:list
 pnpm registry:presets
+pnpm stackfoundry recipes
+pnpm stackfoundry recipe api-saas-starter
 pnpm registry:doctor
 pnpm registry:build
 pnpm stackfoundry add drizzle-postgres --target /path/to/app
-pnpm stackfoundry add preset next-saas --target /path/to/app
+pnpm stackfoundry add recipe api-saas-starter --target /path/to/app --dry-run
 pnpm stackfoundry diff drizzle-postgres --target /path/to/app
 ```
 
@@ -82,4 +84,6 @@ Generated public module and aggregate preset items are registry-compatible `regi
 
 Files under `/r/presets/*.json` are StackFoundry preset manifests for tooling and inspection. They are not installable registry item payloads; use `/r/<preset>.json` to install a preset bundle.
 
+Files under `/r/recipes/*.json` are StackFoundry recipe manifests for human-readable architecture, outcomes, and staged install order. Recipes can also be installed through the StackFoundry command with `stackfoundry add recipe <name>`.
+
 The build writes canonical generated output to `public/r` and mirrors it to `apps/web/public/r`. Vercel serves `/r/*.json` directly from the Next app as static JSON; no redirect is required.

docs/repository.md

@@ -9,7 +9,7 @@ StackFoundry is a source registry. Every directory should either own product sou
 - `examples/` contains install targets and walkthroughs used to prove registry modules in realistic app shapes.
 - `packages/` is reserved for extracted library packages when command behavior, registry loading, schema validation, and shared utilities outgrow `apps/cli`.
 - `public/r/` contains generated registry output. Do not edit it by hand.
-- `registry/` contains source modules and presets. This is the product surface.
+- `registry/` contains source modules, presets, recipes, and shared skills. This is the product surface.
 - `scripts/` is reserved for standalone maintenance scripts that should not live inside the StackFoundry command.
 
 ## Applications
@@ -25,14 +25,15 @@ StackFoundry is a source registry. Every directory should either own product sou
 - `registry/modules/<module>/skill/SKILL.md` gives maintainer guidance.
 - `registry/modules/<module>/tests/checklist.md` defines verification expectations.
 - `registry/presets/*.json` composes modules into installable bundles.
+- `registry/recipes/*.json` describes staged install order and workflow outcomes.
 
 ## Generated Output
 
 Run `pnpm registry:build` to regenerate `public/r`.
 
 `public/r/registry.json` is the shadcn-compatible registry index and is not an installable item. Generated module files such as `public/r/api-keys.json` are `registry:block` item JSON files. They include file contents, target paths, package dependencies, registry dependency URLs, environment variables, docs, and metadata.
 
-Generated aggregate preset blocks live at `public/r/<preset>.json`. Raw preset manifests live under `public/r/presets/*.json` for StackFoundry tooling and are not shadcn registry item documents.
+Generated aggregate preset blocks live at `public/r/<preset>.json`. Raw preset manifests live under `public/r/presets/*.json` for StackFoundry tooling and are not shadcn registry item documents. Recipe manifests are mirrored under `public/r/recipes/*.json` for inspection and install-order guidance.
 
 ## Verification