docs: clarify saas registry positioning

jesseoue · jesseoue · commit bc0f3072e75a · 2026-05-13T19:10:08.000-04:00
diff --git a/.gitignore b/.gitignore
@@ -20,8 +20,8 @@ coverage/
 # Logs
 *.log
 
-# Local planning / assistant artifacts
-.cursor/
+# Local planning / scratch artifacts
+.local/
 .agents/
 agent-transcripts/
 plans/
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,11 +1,11 @@
 # Agent Context
 
-StackFoundry is a public source registry for production SaaS and AI modules.
+StackFoundry is a public source registry for production SaaS modules.
 
 ## Product Rules
 
 1. The registry is the product. Presets are only bundles of modules.
-2. Every module must include source files, docs, env notes, tests/checklist, and agent operating instructions.
+2. Every module must include source files, docs, env notes, tests/checklist, and maintenance instructions.
 3. Base scaffolds must stay small. Optional providers are adapters, not hard dependencies.
 4. Do not introduce public-facing references to how the project was authored.
 5. Never commit secrets, `.env.local`, provider credentials, private customer data, local caches, or generated machine metadata.
@@ -30,6 +30,6 @@ Before moving to a new phase:
 
 Use this product positioning:
 
-> Install production SaaS and AI features as editable source code.
+> Install production SaaS modules as editable source code.
 
-Avoid overclaiming unsupported providers. Keep launch scope narrow and credible.
+Avoid overclaiming unsupported providers. Keep launch scope narrow and credible. AI-related modules are optional module categories, not the core project identity.
diff --git a/README.md b/README.md
@@ -1,16 +1,24 @@
 # StackFoundry
 
-Install production SaaS and AI features as editable source code.
+Install production SaaS modules as editable source code.
 
-StackFoundry is a source registry for full-stack app modules: auth, billing, API keys, webhooks, AI chat, agents, analytics, docs, Drizzle schemas, tests, and deployment workflows.
+StackFoundry is a source registry for full-stack app modules: auth, billing, API keys, webhooks, analytics, docs, Drizzle schemas, tests, and deployment workflows.
 
-Every module ships with the code and the agent operating instructions needed to maintain it.
+Every module ships with the code and the operating instructions needed to maintain it.
 
 No black boxes. No locked framework. Copy the code. Own the code.
 
 ## Status
 
-This repository is the public seed for StackFoundry. The product direction is the registry and module installer.
+This repository is the public seed for StackFoundry. The product is the registry and module installer. Presets are only bundles of modules.
+
+StackFoundry sits between three familiar ideas:
+
+- source registries: copy code into your app so you own it
+- stack builders: choose only the systems you need
+- production SaaS kits: ship real auth, billing, database, analytics, docs, and operations surfaces
+
+The difference is that StackFoundry modules include the implementation, the setup notes, the test checklist, and the maintenance guidance together.
 
 ## First Demo
 
@@ -20,6 +28,7 @@ Target workflow:
 pnpm create stackfoundry my-app
 cd my-app
 
+pnpm dlx stackfoundry add drizzle-postgres
 pnpm dlx stackfoundry add api-keys
 pnpm dlx stackfoundry add stripe-billing
 ```
@@ -32,8 +41,8 @@ The demo should show each module adding:
 - environment variables
 - docs
 - tests or verification checklist
-- `.agents/skills/<module>/SKILL.md`
-- `AGENTS.md` guidance
+- maintenance guidance
+- install metadata for future diff/update safety
 
 ## V1 Golden Path
 
@@ -52,6 +61,20 @@ The demo should show each module adding:
 - `sentry-monitoring`
 - `resend-email`
 
+## Module Categories
+
+StackFoundry is designed around production SaaS systems:
+
+- foundation: Next.js App Router, shadcn-compatible source files, Sidebar shell, Geist theme, T3 env
+- data: Drizzle, Postgres, migrations, audit log, soft delete, seed data
+- auth and tenancy: Clerk, organizations, RBAC, invitations, workspace settings
+- billing: Stripe, billing core, webhooks, entitlements, usage metering
+- developer platform: API keys, scopes, public API, webhook delivery, developer portal
+- growth: PostHog, PLG metrics, AARRR dashboards, onboarding, lifecycle email
+- operations: admin console, support console, system health, Sentry, incident tools
+- providers: Vercel, Neon, Supabase, Upstash, Cloudflare, Resend, PostHog, Sentry
+- optional AI modules: AI chat, artifacts, model routing, prompt library
+
 ## Principles
 
 - Registry is the product.
@@ -61,7 +84,7 @@ The demo should show each module adding:
 - Provider modules are adapters around shared domain interfaces.
 - Never overwrite modified user files silently.
 - Track installed file hashes for diff/update safety.
-- Each module teaches maintainers and coding agents how to safely change it.
+- Each module teaches maintainers how to safely change it.
 
 ## Repository Layout
 
@@ -83,7 +106,7 @@ docs/
 
 ## Development
 
-The next milestone is to build `stackfoundry add` for the first production modules.
+The current milestone is to make the first modules installable and safe to diff.
 
 Current local prototype:
 
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -9,21 +9,30 @@
 - [x] `stackfoundry add <module>` prototype
 - [x] file hash manifest
 - [x] `stackfoundry diff <module>` prototype
+- [ ] overwrite conflict UI
+- [ ] generated install report
+- [ ] public demo app
 
 ## Wave 2
 
 - [ ] `clerk-auth`
 - [ ] `orgs-rbac`
 - [ ] `unkey-api-keys`
 - [ ] `unkey-rate-limits`
-- [ ] `ai-chat`
-- [ ] `ai-artifacts`
 - [ ] `usage-metering`
 - [ ] `public-api-orpc`
 - [ ] `vercel-blob`
 - [ ] `vercel-edge-config`
 - [ ] `upstash-redis`
 - [ ] `feature-flags`
+- [ ] `posthog-analytics`
+- [ ] `sentry-monitoring`
+- [ ] `resend-email`
+- [ ] `webhook-inbox`
+- [ ] `audit-log`
+- [ ] `plg-metrics`
+- [ ] `aarrr-dashboard`
+- [ ] `activation-onboarding`
 
 ## Wave 3
 
@@ -34,6 +43,21 @@
 - [ ] `convex-backend`
 - [ ] `paddle-billing`
 - [ ] Cloudflare provider modules
+- [ ] optional AI modules
+- [ ] docs/help center modules
+- [ ] search provider modules
+
+## Module System
+
+- [ ] module manifest schema package
+- [ ] registry loader package
+- [ ] generator package
+- [ ] file hash diff/update engine
+- [ ] module dependency resolver
+- [ ] `.env.example` patcher
+- [ ] AGENTS/maintenance-guidance patcher
+- [ ] registry build command
+- [ ] hosted registry docs site
 
 ## Launch Readiness
 
diff --git a/docs/agents.md b/docs/agents.md
@@ -1,12 +1,12 @@
-# Agent Operating Instructions
+# Maintenance Instructions
 
-Every module can include agent operating instructions in:
+Every module can include maintenance instructions in:
 
 ```text
 registry/modules/<module>/skill/SKILL.md
 ```
 
-These files teach maintainers and coding agents:
+These files teach maintainers:
 
 - which files own the module
 - which environment variables matter
diff --git a/docs/modules.md b/docs/modules.md
@@ -9,3 +9,93 @@ The first production modules are:
 - `stripe-billing`
 
 Each module should be installable into an existing app as editable source code. Presets are only bundles of modules.
+
+## What a Module Includes
+
+- `module.json`
+- source files
+- dependency metadata
+- environment variable metadata
+- docs
+- verification checklist
+- maintenance guidance
+- install metadata for diff/update safety
+
+## Planned Module Families
+
+### Foundation
+
+- `next-saas`
+- `t3-env`
+- `shadcn-sidebar-shell`
+- `geist-theme`
+- `quality-tooling`
+- `playwright-e2e`
+
+### Data
+
+- `drizzle-postgres`
+- `drizzle-multitenancy`
+- `drizzle-relations`
+- `drizzle-audit-log`
+- `drizzle-soft-delete`
+- `neon-postgres`
+- `supabase-postgres`
+
+### Auth and Tenancy
+
+- `clerk-auth`
+- `orgs-rbac`
+- `invites`
+- `workspace-settings`
+- `account-settings`
+- `session-management`
+
+### Billing
+
+- `billing-core`
+- `stripe-billing`
+- `paddle-billing`
+- `autumn-entitlements`
+- `usage-metering`
+- `trial-management`
+- `plan-gating`
+
+### Developer Platform
+
+- `api-keys`
+- `unkey-api-keys`
+- `unkey-rate-limits`
+- `public-api-orpc`
+- `webhook-inbox`
+- `webhook-delivery`
+- `developer-portal`
+
+### Growth and Analytics
+
+- `posthog-analytics`
+- `plg-metrics`
+- `aarrr-dashboard`
+- `activation-onboarding`
+- `lifecycle-email`
+- `cohort-retention`
+- `experiments`
+
+### Operations
+
+- `sentry-monitoring`
+- `audit-log`
+- `admin-console`
+- `support-console`
+- `system-health`
+- `incident-management`
+- `data-import-export`
+
+### Optional AI
+
+- `ai-chat`
+- `ai-artifacts`
+- `ai-tools`
+- `model-router`
+- `prompt-library`
+- `evals`
diff --git a/docs/providers.md b/docs/providers.md
@@ -16,3 +16,36 @@ Provider modules adapt external services into StackFoundry systems.
 ## Adapter Rule
 
 Providers map into shared domain systems. They should not become one-off code islands.
+
+## Provider Families
+
+### Deploy and Hosting
+
+- Vercel first for Next.js applications
+- Cloudflare as an optional edge/workers platform
+- Railway, Fly, and Render as future adapters
+
+### Database and Storage
+
+- Postgres + Drizzle as the default data model
+- Neon and Supabase as managed Postgres providers
+- Vercel Blob and S3/R2 for object storage
+- Upstash Redis for cache, queues, and rate-limit support
+
+### Billing and Entitlements
+
+- Stripe as the default payment provider
+- Paddle for Merchant of Record workflows
+- Autumn for pricing, entitlements, credits, and usage control
+
+### Product and Operations
+
+- PostHog for product analytics and feature flags
+- Sentry for error monitoring
+- Resend for transactional email
+- Unkey for managed API keys and rate limits
+
+### Optional AI
+
+- Vercel AI SDK and AI Gateway for AI modules
+- Provider-specific model routing belongs behind module adapters
diff --git a/docs/registry.md b/docs/registry.md
@@ -21,9 +21,17 @@ Each module has:
 - `env`: required environment variables
 - `files`: files installed into the target app
 - `drizzle`: schema/migration metadata
-- `agents`: agent operating instructions metadata
+- `agents`: maintenance instruction metadata
 - `status`: planned, experimental, stable
 
+## Registry Principles
+
+- Modules install source code, not opaque package wrappers.
+- Presets only compose modules.
+- Provider modules adapt services into shared domain systems.
+- Installers must produce enough metadata for safe diff/update workflows.
+- Public modules should avoid private assumptions about a single company or app.
+
 ## Safety
 
 Installers must not overwrite modified user files silently. The installer should track file hashes and support diff/update flows.
diff --git a/registry.json b/registry.json
@@ -19,7 +19,7 @@
       "name": "api-keys",
       "type": "registry:item",
       "title": "API Keys",
-      "description": "API key lifecycle, scopes, hashed storage, usage metadata, and agent operating instructions.",
+      "description": "API key lifecycle, scopes, hashed storage, usage metadata, and maintenance instructions.",
       "files": [
         {
           "path": "registry/modules/api-keys/module.json",

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@`
`19`	`19`	`"name": "api-keys",`
`20`	`20`	`"type": "registry:item",`
`21`	`21`	`"title": "API Keys",`
`22`		`- "description": "API key lifecycle, scopes, hashed storage, usage metadata, and agent operating instructions.",`
	`22`	`+ "description": "API key lifecycle, scopes, hashed storage, usage metadata, and maintenance instructions.",`
`23`	`23`	`"files": [`
`24`	`24`	`{`
`25`	`25`	`"path": "registry/modules/api-keys/module.json",`