chore: sharpen API SaaS positioning

Lead with the API SaaS recipe as the traction wedge and align the site, docs, README, registry metadata, and AI discovery copy around modules as editable source.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jesseoue

AGENTS.md

@@ -1,6 +1,6 @@
 # Agent Context
 
-StackFoundry is a public source registry for production SaaS modules.
+StackFoundry is a public source registry for production SaaS modules. The sharp public wedge is API SaaS: API keys, usage tracking, rate limits, credits, Stripe billing, docs, and webhooks as editable source.
 
 ## Product Rules
 
@@ -34,6 +34,8 @@ Before moving to a new phase:
 
 Use this product positioning:
 
-> Install production SaaS modules as editable source code.
+> shadcn for production SaaS systems.
+>
+> Install API keys, usage tracking, billing, webhooks, and production SaaS modules as editable source code.
 
-Avoid overclaiming unsupported providers. Keep launch scope narrow and credible. AI-related modules are optional module categories, not the core project identity.
+Avoid overclaiming unsupported providers. Keep launch scope narrow and credible. Lead with the API SaaS recipe before broad catalog coverage. AI-related modules are optional module categories, not the core project identity.

CHANGELOG.md

@@ -14,6 +14,7 @@
 
 ### Changed
 
+- Sharpened public positioning around the API SaaS wedge: API keys, usage tracking, rate limits, credits, Stripe billing, docs, and webhooks as editable source.
 - Pointed module maintenance skills to installed shared provider, framework, database, SDK, and platform skills.
 - Standardized provider adapter registry language and replaced legacy provider wording/paths.
 - Renamed public command examples to `stackfoundry`.

README.md

@@ -1,6 +1,6 @@
 # StackFoundry
 
-Install production SaaS modules as editable source code.
+shadcn for production SaaS systems.
 
 [![CI](https://github.com/jesseoue/stackfoundry/actions/workflows/ci.yml/badge.svg)](https://github.com/jesseoue/stackfoundry/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/jesseoue/stackfoundry/actions/workflows/codeql.yml/badge.svg)](https://github.com/jesseoue/stackfoundry/actions/workflows/codeql.yml)
@@ -14,25 +14,40 @@ Install production SaaS modules as editable source code.
 ![Presets](https://img.shields.io/badge/presets-13-teal)
 ![Inspired by shadcn](https://img.shields.io/badge/inspired%20by-shadcn-111111)
 
-StackFoundry is a public source registry for the product plumbing most SaaS teams rebuild: billing, auth, API keys, webhooks, docs, analytics, notifications, operations, provider adapters, and launch readiness.
+StackFoundry is a public source registry for the production systems SaaS teams rebuild: API keys, usage tracking, rate limits, Stripe billing, credits, webhooks, auth, docs, analytics, and operations.
 
 Modules install as source files in your app. You review the code, own the code, and keep the maintenance context that ships with it.
 
-> [!NOTE]
-> The registry is the product. Presets are only curated bundles of modules.
+> [!IMPORTANT]
+> The registry is the product. Modules are the unit of value. Recipes are the guided path. Presets are convenience bundles.
 
-StackFoundry is inspired by the shadcn registry/source-block model and applies that idea to production SaaS systems: modules ship as editable source, not opaque dependencies.
+Start with the sharp wedge: launch an API SaaS with billing, credits, API keys, usage tracking, docs, and webhooks as editable source.
 
 ## Why Use It
 
 | Problem | StackFoundry gives you |
 | --- | --- |
-| Rebuilding the same SaaS systems | Installable source modules for common production capabilities |
+| Shipping an API product | API keys, usage, quotas, credits, billing, docs, and webhooks as source |
 | Black-box starter lock-in | Normal files, routes, schemas, docs, checklists, and maintenance skills |
 | Provider sprawl | Optional adapters around shared product concepts |
 | Unsafe copy/paste snippets | Manifests, env metadata, dependency metadata, and registry validation |
 | Hard-to-review upgrades | Dry runs, diff commands, tracked install metadata, and generated examples |
 
+## Best First Use Case
+
+```bash
+pnpm stackfoundry add recipe api-saas-starter --target ./my-app --dry-run
+pnpm stackfoundry add recipe api-saas-starter --target ./my-app
+```
+
+The API SaaS recipe installs the path most developer tools, AI APIs, data APIs, and B2B platforms need first:
+
+- API key lifecycle and verification
+- usage metering, quotas, and rate limits
+- credit wallet and Stripe billing foundations
+- webhook inbox and outbound delivery
+- API docs, request visibility, auditability, and operating checks
+
 ## Quick Start
 
 ```bash
@@ -43,8 +58,8 @@ pnpm registry:doctor
 pnpm registry:categories
 pnpm registry:list
 
-pnpm stackfoundry add api-keys --target ./my-app --dry-run
-pnpm stackfoundry add preset next-saas --target ./my-app --dry-run
+pnpm stackfoundry recipe api-saas-starter
+pnpm stackfoundry add recipe api-saas-starter --target ./my-app --dry-run
 ```
 
 Install from the public registry URL when you want to consume generated registry items:
@@ -98,10 +113,31 @@ Current source registry coverage:
 
 </details>
 
+## Modules, Recipes, Presets
+
+The public hierarchy is intentionally simple:
+
+- Modules are the product.
+- Recipes explain the install path and order.
+- Presets are bundles for convenience.
+
+## Recipes
+
+Recipes are opinionated install paths that explain what to install together and in what order.
+
+```bash
+pnpm stackfoundry recipes
+pnpm stackfoundry recipe api-saas-starter
+pnpm stackfoundry add recipe api-saas-starter --target ./my-app --dry-run
+```
+
+High-priority recipes include `api-saas-starter`, `saas-starter-minimal`, `enterprise-saas`, `ai-saas-starter`, `cloudflare-saas`, `support-ops`, `security-center`, `integration-marketplace`, and `customer-intelligence`.
+
 ## Presets
 
 | Preset | Intended path |
 | --- | --- |
+| `api-saas-starter` | API-first SaaS workflow with keys, usage, rate limits, credits, billing, webhooks, docs, and observability |
 | `next-saas` | Broad app foundation with database, billing, account surfaces, docs, ops, security, and growth modules |
 | `b2b-saas` | Team workspaces, tenant controls, RBAC, auditability, SSO, and SCIM |
 | `developer-platform` | API keys, public APIs, webhooks, docs, SDK snippets, and developer portal modules |
@@ -111,7 +147,6 @@ 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 Vercel AI SDK chat, AI Elements, usage metering, quotas, and billing |
 
@@ -120,18 +155,6 @@ pnpm registry:presets
 pnpm stackfoundry add preset next-saas --target ./my-app --dry-run
 ```
 
-## Recipes
-
-Recipes are opinionated install paths that explain what to install together and in what order.
-
-```bash
-pnpm stackfoundry recipes
-pnpm stackfoundry recipe api-saas-starter
-pnpm stackfoundry add recipe api-saas-starter --target ./my-app --dry-run
-```
-
-High-priority recipes include `saas-starter-minimal`, `api-saas-starter`, `enterprise-saas`, `ai-saas-starter`, `cloudflare-saas`, `support-ops`, `security-center`, `integration-marketplace`, and `customer-intelligence`.
-
 ## StackFoundry Command
 
 The `stackfoundry` command intentionally stays on Node + pnpm. It is a small registry/install engine, not an interactive component wizard.

apps/cli/README.md

@@ -1,14 +1,14 @@
 # StackFoundry Command
 
-The `stackfoundry` command is the local install engine for StackFoundry registry modules.
+The `stackfoundry` command is the local install engine for StackFoundry registry modules. The clean first path is the API SaaS recipe: keys, usage, quotas, credits, billing, docs, and webhooks as editable source.
 
 ## Responsibilities
 
-- List modules and presets.
+- List modules, recipes, and presets.
 - Browse canonical categories and search modules.
 - Validate registry source.
 - Build registry-compatible output.
-- Install modules or presets into a target app.
+- Install modules, recipes, or presets into a target app.
 - Install generated registry block JSON from local files or StackFoundry registry URLs.
 - Refuse to overwrite modified target files unless `--force` is explicit.
 - Write install metadata for future diff/update workflows.
@@ -33,8 +33,8 @@ pnpm stackfoundry recipes
 pnpm stackfoundry recipe api-saas-starter
 pnpm stackfoundry doctor
 pnpm stackfoundry build
-pnpm stackfoundry add api-keys --target /tmp/app --dry-run
 pnpm stackfoundry add recipe api-saas-starter --target /tmp/app --dry-run
+pnpm stackfoundry add api-keys --target /tmp/app --dry-run
 pnpm stackfoundry add preset provider-adapters --target /tmp/app --dry-run
 pnpm stackfoundry add https://stackfoundry.dev/r/api-keys.json --target /tmp/app --dry-run
 pnpm stackfoundry diff api-keys --target /tmp/app

apps/web/app/ai-seo.ts

@@ -11,8 +11,8 @@ export const aiSeoPages: AiSeoPage[] = [
   {
     title: "Home",
     path: "/",
-    description: "StackFoundry positioning, install flow, module previews, and product overview.",
-    audience: "founders, builders, platform teams, and AI systems evaluating SaaS module coverage",
+    description: "API SaaS positioning, install flow, module previews, and product overview.",
+    audience: "founders, devtools builders, agencies, platform teams, and AI API teams",
   },
   {
     title: "Docs",
@@ -23,8 +23,8 @@ export const aiSeoPages: AiSeoPage[] = [
   {
     title: "Registry",
     path: "/registry",
-    description: "Catalog of modules, presets, provider adapters, and registry families.",
-    audience: "teams choosing SaaS capabilities, provider adapters, and install paths",
+    description: "Catalog of modules, recipes, provider adapters, and registry families.",
+    audience: "teams choosing API SaaS capabilities, provider adapters, and install paths",
   },
   {
     title: "Registry Index",
@@ -43,7 +43,7 @@ export function renderLlmsTxt() {
     .map((page) => `- [${page.title}](${absoluteUrl(page.path)}): ${page.description}`)
     .join("\n");
 
-  return `# StackFoundry\n\n> Install production SaaS modules as editable source code. StackFoundry is a public source registry for billing, auth, docs, API products, operations, analytics, provider adapters, and optional AI modules.\n\n## Primary Pages\n\n${links}\n\n## Machine-Readable Surfaces\n\n- [Registry JSON](${absoluteUrl("/r/registry.json")}): Public registry index.\n- [AI Sitemap](${absoluteUrl("/ai-sitemap.json")}): JSON summary of AI-discoverable pages.\n- [Full AI Context](${absoluteUrl("/llms-full.txt")}): Expanded context for systems that prefer one fetch.\n\n## Notes For Automation\n\n- The registry is the product; presets are only bundles of modules.\n- Modules install source files, docs, env notes, checklists, and maintenance skills.\n- Provider modules are adapters, not base dependencies.\n`;
+  return `# StackFoundry\n\n> shadcn for production SaaS systems. Start with API keys, usage tracking, billing, webhooks, docs, and SaaS modules as editable source code.\n\n## Primary Pages\n\n${links}\n\n## Machine-Readable Surfaces\n\n- [Registry JSON](${absoluteUrl("/r/registry.json")}): Public registry index.\n- [AI Sitemap](${absoluteUrl("/ai-sitemap.json")}): JSON summary of AI-discoverable pages.\n- [Full AI Context](${absoluteUrl("/llms-full.txt")}): Expanded context for systems that prefer one fetch.\n\n## Notes For Automation\n\n- The registry is the product; modules are the unit of value.\n- Recipes explain install paths; presets are only bundles of modules.\n- The first traction path is api-saas-starter.\n- Provider modules are adapters, not base dependencies.\n`;
 }
 
 export function renderLlmsFullTxt() {
@@ -54,13 +54,13 @@ export function renderLlmsFullTxt() {
     )
     .join("\n\n");
 
-  return `# StackFoundry Full AI Context\n\nStackFoundry helps teams install production SaaS modules as editable source code. Modules include source files, documentation, environment notes, verification checklists, and maintainer skills so teams can safely review what lands in an app.\n\n${pages}\n\n## Coverage\n\nStackFoundry covers foundation, database, auth and tenancy, billing, API products, operations, observability, analytics and growth, docs, SEO, support, security, storage, deployment, provider adapters, and optional AI modules.\n\n## Positioning\n\nUse StackFoundry when a team wants production SaaS capabilities without adopting a black-box starter. The installed code belongs to the target repository and can be edited, reviewed, diffed, migrated, and removed like normal source.\n`;
+  return `# StackFoundry Full AI Context\n\nStackFoundry helps teams install production SaaS systems as editable source code. The sharp wedge is API SaaS: API keys, usage tracking, quotas, credits, Stripe billing, docs, webhooks, and request visibility.\n\n${pages}\n\n## Coverage\n\nStackFoundry covers foundation, database, auth and tenancy, billing, API products, operations, observability, analytics and growth, docs, SEO, support, security, storage, deployment, provider adapters, and optional AI modules.\n\n## Positioning\n\nUse StackFoundry when a team wants production SaaS capabilities without adopting a black-box starter. The installed code belongs to the target repository and can be edited, reviewed, diffed, migrated, and removed like normal source.\n`;
 }
 
 export function getAiSitemap() {
   return {
     name: "StackFoundry",
-    description: "Install production SaaS modules as editable source code.",
+    description: "Install API SaaS systems and production SaaS modules as editable source code.",
     generatedAt: new Date().toISOString(),
     pages: aiSeoPages.map((page) => ({ ...page, url: absoluteUrl(page.path) })),
     feeds: {