chore: clean registry install surfaces

Resolve the Next SaaS preset/module ambiguity, improve planned module install warnings, document Stripe env requirements, and acknowledge the shadcn registry/source-block inspiration.

Author: jesseoue

README.md

@@ -13,6 +13,8 @@ Modules install as source files in your app. You review the code, own the code,
 > [!NOTE]
 > The registry is the product. Presets are only curated bundles of modules.
 
+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.
+
 ## Why Use It
 
 | Problem | StackFoundry gives you |
@@ -64,7 +66,7 @@ Current source registry coverage:
 
 | Area | Examples |
 | --- | --- |
-| Foundation | `next-saas`, `sidebar-shell`, `t3-env`, `quality-tooling`, `theme-system` |
+| Foundation | `next-saas-shell`, `sidebar-shell`, `t3-env`, `quality-tooling`, `theme-system` |
 | Database | `drizzle-postgres`, `drizzle-relations`, `neon-postgres`, `supabase-postgres`, `cloudflare-d1` |
 | Auth and tenancy | `clerk-auth`, `orgs-rbac`, `account-modes`, `invites`, `enterprise-sso`, `scim-provisioning` |
 | Billing | `stripe-billing`, `billing-core`, `entitlements`, `credit-wallet`, `one-time-purchases`, `tax-vat` |

apps/cli/src/cli.mjs

@@ -587,13 +587,13 @@ async function saveInstallManifest(target, manifest) {
   await writeFile(path.join(dir, "installed.json"), `${JSON.stringify(manifest, null, 2)}\n`);
 }
 
-async function addModule(name, flags, visited = new Set()) {
+async function addModule(name, flags, visited = new Set(), context = {}) {
   if (visited.has(name)) return;
   visited.add(name);
 
   const { dir, manifest } = await getModule(name);
   for (const dependency of manifest.registryDependencies) {
-    await addModule(dependency, flags, visited);
+    await addModule(dependency, flags, visited, context);
   }
 
   const filesDir = path.join(dir, "files");
@@ -602,6 +602,12 @@ async function addModule(name, flags, visited = new Set()) {
   const installed = await loadInstallManifest(flags.target);
   const installedFiles = {};
 
+  if (sourceFiles.length === 0 && !context.presetName) {
+    console.log(
+      `warning: ${manifest.name} is ${manifest.status} and currently installs maintenance metadata only`,
+    );
+  }
+
   for (const source of sourceFiles) {
     const relative = path.relative(filesDir, source);
     const normalized = toPosixPath(relative);
@@ -660,7 +666,7 @@ async function addPreset(name, flags) {
   const visited = new Set();
   console.log(`${flags.dryRun ? "would install" : "installing"} preset ${preset.name}`);
   for (const moduleName of preset.modules) {
-    await addModule(moduleName, flags, visited);
+    await addModule(moduleName, flags, visited, { presetName: preset.name });
   }
 }
 
@@ -683,6 +689,12 @@ async function addRegistryItem(specifier, flags, visited = new Set()) {
   const installedFiles = {};
   console.log(`${flags.dryRun ? "would install" : "installing"} registry item ${item.name}`);
 
+  if ((item.files?.length ?? 0) === 0 && item.meta?.category !== "preset") {
+    console.log(
+      `warning: ${item.name} is ${item.meta?.status ?? "planned"} and currently installs maintenance metadata only`,
+    );
+  }
+
   for (const file of item.files ?? []) {
     if (!file.content) throw new Error(`${item.name}: ${file.path} is missing embedded content`);
 

apps/web/app/docs/page.tsx

@@ -87,7 +87,7 @@ const moduleGroups = [
     category: "Foundation",
     summary: "Small base scaffolds and product shell pieces.",
     modules: [
-      "next-saas",
+      "next-saas-shell",
       "sidebar-shell",
       "t3-env",
       "theme-system",
@@ -226,7 +226,7 @@ const moduleGroups = [
 ];
 
 const moduleMeta: Record<string, { tone: string; domain?: string }> = {
-  "next-saas": { tone: "foundation", domain: "nextjs.org" },
+  "next-saas-shell": { tone: "foundation", domain: "nextjs.org" },
   "drizzle-postgres": { tone: "database", domain: "drizzle.team" },
   "drizzle-relations": { tone: "database", domain: "drizzle.team" },
   "drizzle-soft-delete": { tone: "database", domain: "drizzle.team" },

apps/web/app/registry/page.tsx

@@ -293,7 +293,7 @@ const providerOptions = [
     domain: "nextjs.org",
     logo: "nextjs",
     role: "App framework",
-    modules: ["next-saas", "docs-fumadocs"],
+    modules: ["next-saas-shell", "docs-fumadocs"],
   },
   {
     name: "React",

docs/modules.md

@@ -27,7 +27,7 @@ Module-specific skills stay focused on ownership, installed files, environment v
 
 ### Foundation
 
-- `next-saas`
+- `next-saas-shell`
 - `t3-env`
 - `sidebar-shell`
 - `geist-nova-theme`

docs/providers.md

@@ -21,7 +21,7 @@ Providers map into shared domain systems. They should not become one-off code is
 
 - Vercel first for Next.js applications
 - Cloudflare as an optional edge/workers platform
-- Railway, Fly, and Render as future adapters
+- Railway, Fly, and Render as optional deploy adapters
 
 ### Database and Storage
 
@@ -46,4 +46,4 @@ Providers map into shared domain systems. They should not become one-off code is
 ### Optional AI
 
 - Vercel AI SDK and AI Gateway for AI modules
-- Provider-specific model routing belongs behind module adapters
+- Provider model routing belongs behind module adapters

docs/registry.md

@@ -28,6 +28,8 @@ Each module has:
 
 StackFoundry follows a source registry pattern: source blocks are described by JSON, files are copied into the consumer app, and the consumer owns the result.
 
+The model is inspired by the shadcn registry/source-block approach, then extended for production SaaS modules with routes, server helpers, schema files, env notes, docs, verification checklists, and maintenance skills.
+
 StackFoundry adapts that model for production SaaS systems instead of UI-only components. A block may include routes, server helpers, schema files, env examples, docs, tests/checklists, and maintainer skill guidance.
 
 ## Registry Principles

package.json

@@ -26,7 +26,7 @@
     "test": "pnpm test:registry",
     "test:brand": "node scripts/smoke-brand.mjs",
     "test:registry": "pnpm test:registry:dry && pnpm test:registry:install",
-    "test:registry:dry": "rm -rf /tmp/stackfoundry-test && mkdir -p /tmp/stackfoundry-test && pnpm cli list >/dev/null && pnpm cli presets >/dev/null && pnpm cli add next-saas --target /tmp/stackfoundry-test/next-saas-module >/dev/null && test -f /tmp/stackfoundry-test/next-saas-module/apps/web/src/components/stackfoundry/app-shell.tsx && pnpm cli add auth-core --target /tmp/stackfoundry-test/auth-core >/dev/null && test -f /tmp/stackfoundry-test/auth-core/docs/auth-architecture.md && pnpm cli add cloudflare-pages --target /tmp/stackfoundry-test/cloudflare-pages >/dev/null && test -f /tmp/stackfoundry-test/cloudflare-pages/apps/web/src/lib/stackfoundry/providers/cloudflare-pages.ts && pnpm cli add railway-deploy --target /tmp/stackfoundry-test/railway-deploy >/dev/null && test -f /tmp/stackfoundry-test/railway-deploy/apps/web/src/lib/stackfoundry/providers/railway-deploy.ts && pnpm cli add api-keys --target /tmp/stackfoundry-test >/dev/null && pnpm cli diff api-keys --target /tmp/stackfoundry-test >/dev/null && pnpm cli add preset next-saas --target /tmp/stackfoundry-test --dry-run >/dev/null && pnpm cli add preset provider-adapters --target /tmp/stackfoundry-test --dry-run >/dev/null && pnpm cli add preset saas-coverage --target /tmp/stackfoundry-test --dry-run >/dev/null && pnpm cli add public/r/api-keys.json --target /tmp/stackfoundry-test --dry-run >/dev/null && pnpm cli add public/r/provider-adapters.json --target /tmp/stackfoundry-test --dry-run >/dev/null",
+    "test:registry:dry": "rm -rf /tmp/stackfoundry-test && mkdir -p /tmp/stackfoundry-test && pnpm cli list >/dev/null && pnpm cli presets >/dev/null && pnpm cli add next-saas-shell --target /tmp/stackfoundry-test/next-saas-module >/dev/null && test -f /tmp/stackfoundry-test/next-saas-module/apps/web/src/components/stackfoundry/app-shell.tsx && pnpm cli add auth-core --target /tmp/stackfoundry-test/auth-core >/dev/null && test -f /tmp/stackfoundry-test/auth-core/docs/auth-architecture.md && pnpm cli add cloudflare-pages --target /tmp/stackfoundry-test/cloudflare-pages >/dev/null && test -f /tmp/stackfoundry-test/cloudflare-pages/apps/web/src/lib/stackfoundry/providers/cloudflare-pages.ts && pnpm cli add railway-deploy --target /tmp/stackfoundry-test/railway-deploy >/dev/null && test -f /tmp/stackfoundry-test/railway-deploy/apps/web/src/lib/stackfoundry/providers/railway-deploy.ts && pnpm cli add api-keys --target /tmp/stackfoundry-test >/dev/null && pnpm cli diff api-keys --target /tmp/stackfoundry-test >/dev/null && pnpm cli add preset next-saas --target /tmp/stackfoundry-test --dry-run >/dev/null && pnpm cli add preset provider-adapters --target /tmp/stackfoundry-test --dry-run >/dev/null && pnpm cli add preset saas-coverage --target /tmp/stackfoundry-test --dry-run >/dev/null && pnpm cli add public/r/api-keys.json --target /tmp/stackfoundry-test --dry-run >/dev/null && pnpm cli add public/r/provider-adapters.json --target /tmp/stackfoundry-test --dry-run >/dev/null",
     "test:registry:install": "rm -rf /tmp/stackfoundry-install && mkdir -p /tmp/stackfoundry-install/next-saas /tmp/stackfoundry-install/provider-adapters /tmp/stackfoundry-install/cloudflare-native /tmp/stackfoundry-install/vercel-native /tmp/stackfoundry-install/saas-coverage /tmp/stackfoundry-install/registry-api-keys /tmp/stackfoundry-install/registry-adapters /tmp/stackfoundry-install/url-api-keys /tmp/stackfoundry-install/url-adapters && pnpm cli add preset next-saas --target /tmp/stackfoundry-install/next-saas >/dev/null && pnpm cli add preset provider-adapters --target /tmp/stackfoundry-install/provider-adapters >/dev/null && pnpm cli add preset cloudflare-native --target /tmp/stackfoundry-install/cloudflare-native >/dev/null && pnpm cli add preset vercel-native --target /tmp/stackfoundry-install/vercel-native >/dev/null && pnpm cli add preset saas-coverage --target /tmp/stackfoundry-install/saas-coverage >/dev/null && pnpm cli add public/r/api-keys.json --target /tmp/stackfoundry-install/registry-api-keys >/dev/null && pnpm cli add public/r/provider-adapters.json --target /tmp/stackfoundry-install/registry-adapters >/dev/null && pnpm cli add https://stackfoundry.dev/r/api-keys.json --target /tmp/stackfoundry-install/url-api-keys >/dev/null && pnpm cli add https://stackfoundry.dev/r/provider-adapters.json --target /tmp/stackfoundry-install/url-adapters >/dev/null",
     "cli": "node apps/cli/src/cli.mjs",
     "registry:list": "pnpm cli list",

public/r/github-integration.json

@@ -16,7 +16,7 @@
       "path": "apps/web/src/lib/github/app.ts",
       "type": "registry:file",
       "target": "apps/web/src/lib/github/app.ts",
-      "content": "import \"server-only\";\n\nimport { App } from \"octokit\";\n\nfunction requireEnv(key: string) {\n  const value = process.env[key];\n  if (!value) throw new Error(`${key} is required.`);\n  return value;\n}\n\nexport function createGitHubApp() {\n  return new App({\n    appId: requireEnv(\"GITHUB_APP_ID\"),\n    privateKey: requireEnv(\"GITHUB_PRIVATE_KEY\").replace(/\\n/g, \"\n\"),\n  });\n}\n"
+      "content": "import \"server-only\";\n\nimport { App } from \"octokit\";\n\nfunction requireEnv(key: string) {\n  const value = process.env[key];\n  if (!value) throw new Error(`${key} is required.`);\n  return value;\n}\n\nexport function createGitHubApp() {\n  return new App({\n    appId: requireEnv(\"GITHUB_APP_ID\"),\n    privateKey: requireEnv(\"GITHUB_PRIVATE_KEY\").replace(/\\\\n/g, \"\\n\"),\n  });\n}\n"
     },
     {
       "path": "apps/web/src/app/api/webhooks/github/route.ts",