create-win-project 1.3.0 → 1.4.0

package/docs/CONTRIBUTING.md

@@ -0,0 +1,154 @@
+# Contributing
+
+See `docs/ARCHITECTURE.md` for completed source ownership and `docs/DEPENDENCY_MAINTENANCE.md` for profile promotion. This file is the workflow, not the design.
+
+## Quick start
+
+1. Fork and create a feature branch from `dev`.
+2. `npm ci` — Node 22.14+ with npm 11.19+ required (tested on Node 24).
+3. `npm test` must stay green. No global `prettier`/`eslint`/`typescript` needed — they are generated inside your project.
+
+## Adding a stack — plan first, then declare, then build
+
+A stack is **planned content first, then a declaration in `library/`, then executable code in `src/stacks/`**. `library/` never contains business entities — it declares *what* the stack supports; `src/stacks/<id>/create-files.js` implements *how* those files are generated. Do not start with code; start with the content model.
+
+### 0. Plan your stack's content (before touching `library/`)
+
+Answer these 5 questions and write them down (a short RFC or issue is enough). If you can't answer them, you can't write a `definition.json` yet.
+
+**a. Identity & compatibility:** What `id` (`django`, `nuxt`), `kind` (`frontend`|`backend`|`data`), `label` (`Django (Python)`), and which existing stacks can it pair with? Example: `nextjs` pairs with `none,postgres,supabase,springboot,laravel`; `react-native` pairs with `none,supabase,springboot,laravel`; `laravel` pairs with `nextjs,react,react-native,no-frontend,laravel-ui`.
+
+**b. Shapes:** Which **applicationShapes** does it enable? Shapes are the *deployment layout*, not the framework. They determine valid `frontend + backend` combos via `lib/application-shapes.js` → `src/engine/project-shapes.js`:
+
+| Shape | Meaning | Example combos |
+|-------|---------|---------------|
+| `fullstack` | One project owns website + server | `nextjs+none`, `nextjs+postgres`, `laravel-ui+laravel` |
+| `separate` | Two apps via API: frontend + backend API | `nextjs+springboot`, `react+supabase`, `react+laravel` |
+| `api` | Backend API only, no generated website | `no-frontend+springboot`, `no-frontend+laravel` |
+| `mobile` | Expo app + API/managed data | `react-native+supabase`, `react-native+springboot` |
+| `frontend` | Browser-only, no generated server | `react+none` |
+
+You don't invent a new shape — you pick from these 5. If `nextjs+django` should be fullstack, add `django` to `fullstack`'s `VALID_COMBINATIONS`. `inferApplicationShape({frontend,backend})` will then infer it; `validateApplicationShape` rejects invalid pairings.
+
+**c. Architecture & auth:** Which `architectureProfiles` (`small,medium,large` — all 3 required for frontends/backends) and which `authenticationModels` (`public,undecided,supabase,session,oidc,laravel-session,sanctum-spa,laravel-oidc`)? Example: `supabase` → `supabase`, `springboot` website → `session`, `springboot` multi-client → `oidc`.
+
+**d. Playbooks & concerns:** Which 5 facets does the stack need? Every stack needs `architecture.md, structure.md, runtime.md, security.md, testing.md` under `playbooks/stack/<id>/`. Which optional concerns (validation `zod`, state `zustand`, etc.) will it surface? Each concern has one home — don't duplicate prose in `AGENTS.md`.
+
+**e. Dependencies & env:** Which npm/composer package *names* and *scripts* will this stack generate, and which env var *names* (semantic, no prefix)? Example: `deps: ["next","react"]`, `env: ["DATABASE_URL"]`, `clientEnv: ["API_URL"]` — the engine will prefix `API_URL` once (`NEXT_PUBLIC_API_URL`). Never put a version here.
+
+If a new stack needs a runtime (`node`, `java`, `php`), add its version to `library/tested-versions.json` (current profile), not to the definition.
+
+### 1. Declare capability in `library/` (no executable logic yet)
+
+- Add `library/stacks/<id>/definition.json`:
+
+  ```json
+  {
+    "id": "django",
+    "kind": "backend",
+    "label": "Django (Python)",
+    "appliesTo": { "frontend": ["nextjs","react","no-frontend"] },
+    "architectureProfiles": ["small","medium","large"],
+    "playbooks": ["stack/django/architecture.md","stack/django/structure.md","stack/django/runtime.md","stack/django/security.md","stack/django/testing.md"],
+    "deps": ["django"],
+    "env": ["DATABASE_URL"],
+    "clientEnv": [],
+    "concerns": [{ "id": "validation", "required": false, "when": "runtime validation needed", "sections": ["Zod for Runtime Validation"] }]
+  }
+  ```
+
+  - `deps`/`devDeps` are **names only** — never versions or ranges. Exact versions live only in `library/tested-versions.json`.
+  - `env` are semantic names (`DATABASE_URL`); `clientEnv` subset gets the frontend prefix (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`).
+
+- Add `playbooks/stack/<id>/{architecture,structure,runtime,security,testing}.md` — the five facets. Keep each file focused; route concerns via definition `concerns[]`, not duplication. Check `docs/CONTENT_MODEL.md` — every concern section must match a Markdown heading (numbered headings normalized).
+
+- Run: `node checks/check-library.js` — catches duplicate ids, unknown dep names, `clientEnv` not in `env`, missing labels, heading mismatches.
+
+### 2. Create stack directory (one place, owns everything specific to that stack)
+
+```
+src/stacks/<frontends|backends>/<id>/
+  index.js            # defineStackAdapter({ id, kind, label, compatibleWith, capabilities, contributes })
+  create-files.js     # (answers, context) -> FileMap — ALL files this stack generates (pure function)
+  dependencies.js     # optional: { deps: [], devDeps: [], scripts: {} } — names/scripts only
+  environment.js      # optional: ["API_URL","DATABASE_URL"] — semantic env names
+  auth/               # for Laravel-style stacks: session.js, sanctum.js, oidc.js, public.js
+  ui/                 # for Laravel-style stacks: blade.js, livewire.js, inertia-react.js, shared.js
+```
+
+Use `src/stacks/backends/laravel/` as the reference (13 files, 363-line `create-files.js` + `auth/` + `ui/` + `composer.js` + `architecture.js`). `src/stacks/frontends/nextjs/` is the minimal vertical.
+
+`create-files.js` receives a read-only context from `src/stacks/available-stacks.js` + `src/engine/load-library.js` — it returns contributions, it never writes files or installs tools directly.
+
+```js
+// src/stacks/backends/django/index.js
+import { defineStackAdapter } from '../../rules.js'
+export const djangoAdapter = defineStackAdapter({
+  id: 'django', kind: 'backend', label: 'Django (Python)',
+  compatibleWith: { frontend: ['nextjs','react','no-frontend'] },
+  capabilities: { applicationShapes: ['fullstack','api'], architectureProfiles: ['small','medium','large'], authenticationModels: ['public','undecided','session'] },
+  contributes: {
+    environment: () => ['DATABASE_URL'],
+    install: () => [{ cwd: 'backend', command: 'pip', args: ['install','-r','requirements.txt'] }],
+    docker: () => [{ template: 'django', developmentPath: 'Dockerfile.dev' }],
+    ci: () => [{ template: 'django', path: '.github/workflows/ci-backend.yml' }],
+  }
+})
+```
+
+### 3. Register once (explicit, no scanning)
+
+`src/stacks/available-stacks.js` — add one import and one array entry:
+
+```js
+import { djangoAdapter } from './backends/django/index.js'
+export const stackRegistry = createStackRegistry([..., djangoAdapter])
+```
+
+This is the **only** list of available adapters. Adding a file never silently activates a stack.
+
+### 4. Add tests and matrix entries
+
+- `tests/stacks/<id>/` — at least: files exist, env prefix, large-arch boundary, auth metadata.
+- `checks/check-compatibility.js` — add `'<frontend>-<backend>'` to `cases[]` and to `smokeSelections[]`.
+- `templates/` — add `docker/dockerfile/django.dev.dockerfile`, `templates/ci/django.yml` etc. as static templates.
+
+### 5. Verify (focused, not full matrix every time)
+
+```bash
+npm test
+node checks/check-library.js
+node checks/check-compatibility.js --scope=stack --stack=<id> | head
+npm run verify:generated -- --profile=$(jq -r .defaultProfile library/tested-versions.json) --case=<frontend>-<backend> --architecture=medium --authentication=yes
+```
+
+- `verify:generated` compares byte-identical output via `generateProject` vs legacy shim for your new stack.
+- Run `npm run matrix:smoke` (10 smoke projects) before any `feature -> dev` PR.
+- Full matrix `npm run matrix:full` (every profile x stack x arch x auth, with install/build/Maven/Expo/Compose checks) is only required on `dev -> main` promotion per `docs/CI_STRATEGY.md`.
+
+### 6. Docs (only if ownership changed)
+
+Update `docs/ARCHITECTURE.md` only if source ownership or the generation pipeline changed — not for every stack. If you added concerns/playbooks, verify `docs/CONTENT_MODEL.md` checklist (concern has one home, `RULES.md` sections resolve).
+
+## Testing and PRs
+
+- Required checks per `docs/CI_STRATEGY.md`:
+  - `feature -> dev`: `quality` + `compatibility-gate` (repository tests + 10 smoke projects)
+  - `dev -> main`: `quality` + `compatibility-gate` (every profile x stack x arch x applicable auth)
+
+- Contribution history: use merge commits for feature branches so history remains visible. Do not require individual matrix job names; require the stable `compatibility-gate` aggregator.
+
+- `tests/architecture-boundaries.test.js` enforces `src/engine` not importing `cli`/`stacks/frontends|backends` and `src/stacks` not importing `cli`/`engine` (except `shared/scaffold` allowlist). `tests/architecture/no-lib-legacy.test.js` bans `src/** -> lib/**` imports and one-line wrapper regressions (no `lib/` exists).
+
+## Version ownership
+
+Exact versions belong only to `library/tested-versions.json`. Never add a version to a `definition.json` or a `create-files.js`. `packageVersion(profile, name, capability)` and `composerPackageVersion(profile, name)` are the only version sources; they reject ranges and unknown package requests. See `docs/DEPENDENCY_MAINTENANCE.md` for current/previous profile promotion and Renovate flow.
+
+## Docs workflow
+
+- `AGENTS.md` — tiny always-on contract; keep short.
+- `RULES.md` — lazy index `concern -> playbook §`; generated per project, read only what you touch.
+- `playbooks/` — reusable standards; add the five facets per stack (`architecture.md`, `structure.md`, `runtime.md`, `security.md`, `testing.md`).
+- `docs/guides/` inside generated projects — architecture, API, setup, deployment for *this* product.
+
+Do not advertise a capability solely because a playbook mentions it. A generated capability must have executable configuration and contract coverage. For questions, read `docs/ARCHITECTURE.md` first, then this file.

package/docs/DEPENDENCY_MAINTENANCE.md

@@ -1,6 +1,6 @@
 # Dependency maintenance
 
-`compatibility/profiles.json` is the only owner of versions emitted into generated applications. Stack and concern manifests declare package names and capabilities, never ranges or versions. Direct npm dependencies are generated as exact versions, and consumers commit the lockfile created by their first install.
+`library/tested-versions.json` is the only owner of versions emitted into generated applications. Stack and concern definitions declare package names and capabilities, never ranges or versions. Direct npm dependencies are generated as exact versions, and consumers commit the lockfile created by their first install.
 
 ## Profile policy
 

package/index.js

@@ -1,431 +1,4 @@
 #!/usr/bin/env node
-import inquirer from 'inquirer'
-import chalk from 'chalk'
-import ora from 'ora'
-import path from 'path'
-import { fileURLToPath } from 'url'
-import { spawnSync } from 'node:child_process'
-import { generateProject } from './lib/generator.js'
-import { loadCompatibility } from './lib/compatibility.js'
-import { printDoctor } from './lib/doctor.js'
-import { configurationDecisionChoices, promptWithBack } from './lib/interview.js'
-import { projectLocationNotice } from './lib/project-location.js'
-import { w1nBanner } from './lib/banner.js'
-import {
-  loadCatalog, resolveStack,
-  stylingChoicesFor, architectureChoicesFor,
-} from './lib/catalog.js'
-import {
-  APPLICATION_SHAPES,
-  applicationShapeChoices,
-  backendChoicesForShape,
-  frontendChoicesForShape,
-} from './lib/application-shapes.js'
-import { laravelUiPromptContribution, laravelUis } from './lib/stacks/laravel/ui/index.js'
+import { runCli } from './src/cli/main.js'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const cliArgs = process.argv.slice(2)
-const profileArg = cliArgs.find((arg) => arg.startsWith('--profile='))?.split('=')[1]
-const shapeArg = cliArgs.find((arg) => arg.startsWith('--shape='))?.split('=')[1]
-const frontendValue = cliArgs.find((arg) => arg.startsWith('--frontend='))?.split('=')[1]
-const backendArg = cliArgs.find((arg) => arg.startsWith('--backend='))?.split('=')[1]
-const frontendAliases = { vite: 'react', expo: 'react-native', none: 'no-frontend' }
-const frontendArg = frontendAliases[frontendValue] || frontendValue
-const architectureArg = cliArgs.find((arg) => arg.startsWith('--architecture='))?.split('=')[1]
-const authenticationArg = cliArgs.find((arg) => arg.startsWith('--authentication='))?.split('=')[1]
-const authAudienceArg = cliArgs.find((arg) => arg.startsWith('--auth-audience='))?.split('=')[1]
-const laravelUiArg = cliArgs.find((arg) => arg.startsWith('--laravel-ui='))?.split('=')[1]
-if (shapeArg && !APPLICATION_SHAPES[shapeArg]) {
-  throw new Error('--shape must be fullstack, separate, api, mobile, or frontend')
-}
-if (architectureArg && !['small', 'medium', 'large'].includes(architectureArg)) {
-  throw new Error('--architecture must be small, medium, or large')
-}
-if (authenticationArg && !['yes', 'not-yet', 'none'].includes(authenticationArg)) {
-  throw new Error('--authentication must be yes, not-yet, or none')
-}
-if (authAudienceArg && !['website', 'multi-client'].includes(authAudienceArg)) {
-  throw new Error('--auth-audience must be website or multi-client')
-}
-if (laravelUiArg && !laravelUis.some((ui) => ui.id === laravelUiArg)) {
-  throw new Error('--laravel-ui must be blade, livewire, or inertia-react')
-}
-const wantsInstall = cliArgs.includes('--install')
-const skipsInstall = cliArgs.includes('--no-install')
-if (wantsInstall && skipsInstall) throw new Error('Use either --install or --no-install, not both')
-const { profile } = await loadCompatibility(
-  path.join(__dirname, 'compatibility/profiles.json'),
-  profileArg,
-)
-if (cliArgs[0] === 'doctor' || cliArgs.includes('--doctor')) {
-  printDoctor(profile)
-  process.exit(0)
-}
-const catalog = await loadCatalog(path.join(__dirname, 'playbooks'), profile)
-
-// ─── Banner ──────────────────────────────────────────────────────────────────
-
-console.log('')
-console.log(w1nBanner())
-console.log('')
-console.log(chalk.gray('  Production-ready project scaffolding'))
-console.log(chalk.gray(`  Compatibility profile: ${profile.id} (${profile.status})`))
-console.log('')
-
-// ─── Interview ───────────────────────────────────────────────────────────────
-
-const questions = [
-  {
-    type: 'list',
-    name: 'applicationShape',
-    message: 'What kind of application are you building?',
-    choices: applicationShapeChoices(),
-    default: 'fullstack',
-    when: () => !shapeArg,
-  },
-  // ── Always-on ──────────────────────────────────────────────────────────
-  {
-    type: 'input',
-    name: 'projectName',
-    message: 'Project name?',
-    default: 'my-project',
-    validate: (v) => {
-      if (!v.trim()) return 'Project name is required'
-      if (!/^[a-z0-9-]+$/.test(v)) return 'Use lowercase letters, numbers, and hyphens only'
-      return true
-    },
-  },
-  {
-    type: 'input',
-    name: 'projectDescription',
-    message: 'One-line description?',
-    default: 'A new application',
-  },
-
-  // ── Stack selection (catalog-driven) ───────────────────────────────────
-  {
-    type: 'list',
-    name: 'frontend',
-    message: 'Which application framework or frontend?',
-    choices: (a) => frontendChoicesForShape(shapeArg || a.applicationShape, catalog),
-    when: () => !frontendArg,
-  },
-  {
-    type: 'list',
-    name: 'backend',
-    message: 'Which backend or data service?',
-    choices: (a) => backendChoicesForShape(shapeArg || a.applicationShape, a.frontend, catalog),
-    when: () => !backendArg,
-  },
-  ...laravelUiPromptContribution(laravelUiArg).questions,
-
-  // ── Styling: only shown when frontend has >1 option (catalog-driven) ───
-  {
-    type: 'list',
-    name: 'styling',
-    message: 'Styling approach?',
-    choices: (a) => stylingChoicesFor(catalog, a.frontend),
-    when: (a) => stylingChoicesFor(catalog, a.frontend).length > 1,
-  },
-
-  // ── One architecture profile, interpreted natively by every stack ──────
-  {
-    type: 'list',
-    name: 'architecture',
-    message: 'Architecture? (Medium is recommended for most long-term applications)',
-    choices: (a) => {
-      const supported = architectureChoicesFor(catalog, a.frontend, a.backend)
-      return [
-        { name: 'Medium (Recommended) — clear feature, service, and data boundaries', value: 'medium' },
-        { name: 'Small — fewer layers for prototypes and simple applications', value: 'small' },
-        { name: 'Large — enforced boundaries for complex domains and larger teams', value: 'large' },
-      ].filter((choice) => supported.includes(choice.value))
-    },
-    default: 'medium',
-    when: () => !architectureArg,
-  },
-
-  // ── Authentication intent, expressed without protocol jargon ───────────
-  {
-    type: 'list',
-    name: 'authentication',
-    message: 'Does your application need user login?',
-    choices: (a) => {
-      const choices = []
-      if (a.backend === 'supabase' || a.backend === 'springboot' || a.backend === 'laravel') {
-        choices.push({ name: 'Yes — generate authentication appropriate for this stack', value: 'yes' })
-      }
-      choices.push(
-        { name: 'Not yet (Recommended) — add guidance without pretending login exists', value: 'not-yet' },
-        { name: 'No — this application is intentionally public and has no user accounts', value: 'none' },
-      )
-      return choices
-    },
-    default: 'not-yet',
-    when: () => !authenticationArg,
-  },
-  {
-    type: 'list',
-    name: 'authAudience',
-    message: 'Where will users access the application?',
-    choices: [
-      { name: 'Website only — use a secure server-managed browser session', value: 'website' },
-      { name: 'Website and mobile — use a trusted identity provider for every client', value: 'multi-client' },
-    ],
-    default: 'website',
-    when: (a) => ['springboot', 'laravel'].includes(a.backend) && a.frontend !== 'laravel-ui' && (authenticationArg || a.authentication) === 'yes' && !authAudienceArg,
-  },
-
-  // ── Testing ────────────────────────────────────────────────────────────
-  {
-    type: 'list',
-    name: 'testing',
-    message: 'Testing setup?',
-    choices: (a) => {
-      const fe = catalog.byId[a.frontend]
-      if (fe?.platform === 'mobile') {
-        return [
-          { name: 'Basic  (Jest + React Native Testing Library)', value: 'basic' },
-          { name: 'None',                                          value: 'none' },
-        ]
-      }
-      return [
-        { name: 'Full   (Vitest + React Testing Library + Playwright)', value: 'full' },
-        { name: 'Basic  (Vitest + React Testing Library)',               value: 'basic' },
-        { name: 'None',                                                  value: 'none' },
-      ]
-    },
-    default: (a) => {
-      const fe = catalog.byId[a.frontend]
-      return fe?.platform === 'mobile' ? 'basic' : 'full'
-    },
-  },
-
-  // ── DevOps extras ──────────────────────────────────────────────────────
-  {
-    type: 'confirm',
-    name: 'docker',
-    message: 'Include Docker?',
-    default: true,
-    when: (a) => {
-      const fe = catalog.byId[a.frontend]
-      const be = catalog.byId[a.backend]
-      return (be?.needsDocker ?? fe?.needsDocker ?? false)
-    },
-  },
-  {
-    type: 'confirm',
-    name: 'makefile',
-    message: 'Include Makefile?',
-    default: true,
-    when: (a) => {
-      // Makefile is useful for web stacks; less relevant for bare mobile
-      const fe = catalog.byId[a.frontend]
-      return fe?.platform !== 'mobile'
-    },
-  },
-  {
-    type: 'confirm',
-    name: 'githubActions',
-    message: 'Include GitHub Actions CI?',
-    default: true,
-  },
-  {
-    type: 'confirm',
-    name: 'installDependencies',
-    message: 'Install project dependencies and create the lockfile now?',
-    default: true,
-    when: () => !wantsInstall && !skipsInstall,
-  },
-
-  // ── Spring Boot specific ───────────────────────────────────────────────
-  {
-    type: 'input',
-    name: 'packageName',
-    message: 'Java package name? (e.g. com.yourname)',
-    default: 'com.app',
-    when: (a) => a.backend === 'springboot',
-    validate: (v) => {
-      if (!v.trim()) return 'Package name is required'
-      if (!/^[a-z]+(\.[a-z]+)+$/.test(v)) return 'Use format: com.yourname'
-      return true
-    },
-  },
-
-  // ── Optional concerns (filtered to current stack) ──────────────────────
-  {
-    type: 'checkbox',
-    name: 'expectedConcerns',
-    message: 'Expected optional concerns? (advisory only — all stay available)',
-    choices: (a) => {
-      const stack = resolveStack({ ...a, styling: a.styling || catalog.byId[a.frontend]?.stylingOptions?.[0] }, catalog)
-      const opts = new Set()
-      for (const c of stack.concerns) if (!c.required) opts.add(c.id)
-      return [...opts].map((id) => ({ name: id, value: id }))
-    },
-  },
-]
-let answers = {
-  applicationShape: shapeArg,
-  frontend: frontendArg,
-  backend: backendArg,
-}
-let stack
-while (true) {
-answers = await promptWithBack(inquirer, questions, answers)
-answers.compatibilityProfile = profile.id
-answers.applicationShape = shapeArg || answers.applicationShape
-answers.architecture = architectureArg || answers.architecture || 'medium'
-answers.authentication = authenticationArg || answers.authentication || 'not-yet'
-answers.authAudience = authAudienceArg || answers.authAudience || (catalog.byId[answers.frontend]?.platform === 'mobile' ? 'multi-client' : 'website')
-answers.laravelUi = laravelUiArg || answers.laravelUi || (answers.frontend === 'laravel-ui' ? 'blade' : undefined)
-if (wantsInstall) answers.installDependencies = true
-if (skipsInstall) answers.installDependencies = false
-
-// ── Auto-resolve docker for stacks that need it ───────────────────────────────
-if (resolveStack({ ...answers, styling: answers.styling || catalog.byId[answers.frontend]?.stylingOptions?.[0] || 'tailwind' }, catalog).needsDocker) {
-  answers.docker = answers.docker ?? true
-}
-
-stack = resolveStack({ ...answers, styling: answers.styling || catalog.byId[answers.frontend]?.stylingOptions?.[0] || 'tailwind' }, catalog)
-
-// ─── Confirm ─────────────────────────────────────────────────────────────────
-
-console.log('')
-console.log(chalk.bold('  Summary'))
-console.log(chalk.gray('  ───────────────────────────'))
-console.log(`  ${chalk.cyan('Name:')}         ${answers.projectName}`)
-console.log(`  ${chalk.cyan('Stack:')}        ${stack.label}`)
-console.log(`  ${chalk.cyan('Shape:')}        ${APPLICATION_SHAPES[stack.applicationShape].label}`)
-console.log(`  ${chalk.cyan('Platform:')}     ${stack.platform}`)
-if (stack.styleId) {
-  console.log(`  ${chalk.cyan('Styling:')}      ${catalog.byId[stack.styleId]?.label || stack.styleId}`)
-}
-if (answers.laravelUi) console.log(`  ${chalk.cyan('Laravel UI:')}   ${answers.laravelUi}`)
-console.log(`  ${chalk.cyan('Architecture:')} ${stack.architecture[0].toUpperCase()}${stack.architecture.slice(1)}`)
-console.log(`  ${chalk.cyan('Authentication:')} ${stack.authentication}`)
-console.log(`  ${chalk.cyan('Testing:')}      ${answers.testing}`)
-if (stack.platform !== 'mobile') {
-  console.log(`  ${chalk.cyan('Docker:')}       ${answers.docker ? 'yes' : 'no'}`)
-  console.log(`  ${chalk.cyan('Makefile:')}     ${answers.makefile ? 'yes' : 'no'}`)
-}
-console.log(`  ${chalk.cyan('CI/CD:')}        ${answers.githubActions ? 'yes' : 'no'}`)
-console.log(`  ${chalk.cyan('Install deps:')} ${answers.installDependencies ? 'yes' : 'no'}`)
-if (answers.packageName) {
-  console.log(`  ${chalk.cyan('Package:')}      ${answers.packageName}`)
-}
-if (stack.constraints.length) {
-  console.log('')
-  console.log(chalk.gray('  Key constraints:'))
-  for (const rule of stack.constraints.slice(0, 3)) {
-    console.log(chalk.gray(`  • ${rule}`))
-  }
-}
-console.log('')
-
-const { decision } = await inquirer.prompt([{
-  type: 'list', name: 'decision', message: 'Ready?', choices: configurationDecisionChoices(),
-}])
-
-if (decision === 'back') {
-  continue
-}
-if (decision === 'cancel') {
-  console.log(chalk.yellow('\n  Cancelled.\n'))
-  process.exit(0)
-}
-break
-}
-
-// ─── Generate ────────────────────────────────────────────────────────────────
-
-console.log('')
-const spinner = ora('Scaffolding project...').start()
-
-try {
-  await generateProject(answers, __dirname)
-  spinner.succeed(chalk.green('Project created!'))
-  const locationNotice = projectLocationNotice({ cwd: process.cwd(), cliRoot: __dirname, projectName: answers.projectName })
-  if (locationNotice) {
-    console.log('')
-    console.log(chalk.yellow.bold('  Project location note'))
-    console.log(chalk.yellow(`  ${locationNotice.message}`))
-    console.log(chalk.gray(`  Created at: ${locationNotice.generatedPath}`))
-    console.log(chalk.gray(`  Suggested destination: ${locationNotice.suggestedPath}`))
-    console.log(chalk.gray(`  Linux/macOS: mv "${locationNotice.generatedPath}" "${locationNotice.suggestedPath}"`))
-    console.log(chalk.gray(`  Windows: cut the generated folder in File Explorer and paste it into your projects folder.`))
-  }
-  if (answers.installDependencies) {
-    const projectRoot = path.join(process.cwd(), answers.projectName)
-    const steps = []
-    if (stack.backendKey === 'laravel') {
-      const laravelRoot = ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? projectRoot : path.join(projectRoot, 'backend')
-      steps.push({ command: process.platform === 'win32' ? 'composer.bat' : 'composer', args: ['install'], cwd: laravelRoot, retry: `cd ${path.relative(process.cwd(), laravelRoot)} && composer install` })
-    }
-    const needsNpm = stack.frontendKey !== 'no-frontend' && (stack.frontendKey !== 'laravel-ui' || answers.laravelUi === 'inertia-react')
-    if (needsNpm) {
-      const npmRoot = stack.frontendKey === 'react' ? path.join(projectRoot, 'frontend') : projectRoot
-      steps.push({ command: process.platform === 'win32' ? 'npm.cmd' : 'npm', args: ['install'], cwd: npmRoot, retry: `cd ${path.relative(process.cwd(), npmRoot)} && npm install` })
-    }
-    const installSpinner = ora('Installing exact dependencies and creating lockfiles...').start()
-    const failed = steps.find((step) => spawnSync(step.command, step.args, { cwd: step.cwd, stdio: 'inherit', shell: false }).status !== 0)
-    if (failed) {
-      installSpinner.warn(chalk.yellow('Project created, but dependency installation did not finish.'))
-      console.log(chalk.yellow(`  Retry with: ${failed.retry}`))
-    } else {
-      installSpinner.succeed(chalk.green('Dependencies installed and lockfiles created.'))
-    }
-  }
-  console.log('')
-  console.log(chalk.bold(`  Next steps:`))
-  console.log(chalk.gray(`  cd ${answers.projectName}`))
-
-  if (stack.backendKey === 'laravel') {
-    const laravelDir = ['laravel-ui', 'no-frontend'].includes(stack.frontendKey) ? '' : 'backend/'
-    console.log(chalk.gray(`  cp ${laravelDir}.env.example ${laravelDir}.env`))
-    if (answers.makefile) {
-      console.log(chalk.gray(`  make setup  # first run only`))
-      console.log(chalk.gray(`  make run    # later runs; never rebuilds`))
-    } else {
-      console.log(chalk.gray(`  docker compose build`))
-      console.log(chalk.gray(`  docker compose up -d`))
-    }
-  } else if (stack.frontendKey === 'react') {
-    if (stack.backendKey === 'springboot') {
-      console.log(chalk.gray(`  cp .env.example .env  # Docker/backend values`))
-    }
-    console.log(chalk.gray(`  cd frontend`))
-    console.log(chalk.gray(`  cp .env.example .env`))
-    if (!answers.installDependencies) console.log(chalk.gray(`  npm install`))
-  } else {
-    console.log(chalk.gray(`  cp .env.example ${stack.isMobile ? '.env' : '.env.local'}`))
-    if (!answers.installDependencies) console.log(chalk.gray(`  npm install`))
-  }
-
-  if (stack.backendKey === 'laravel') {
-    // Laravel commands were printed above because its root differs by application shape.
-  } else if (stack.isMobile) {
-    console.log(chalk.gray(`  npx expo start`))
-  } else if (answers.makefile) {
-    if (stack.frontendKey === 'react') {
-      console.log(chalk.gray(`  cd ..`))
-    }
-    console.log(chalk.gray(`  make dev`))
-  } else if (stack.backendKey === 'supabase') {
-    console.log(chalk.gray(`  npm run supabase:start`))
-    console.log(chalk.gray(`  npm run dev`))
-  } else if (stack.frontendKey === 'react') {
-    console.log(chalk.gray(`  npm run dev`))
-  } else {
-    console.log(chalk.gray(`  docker compose up -d db`))
-    console.log(chalk.gray(`  npm run dev`))
-  }
-
-  console.log('')
-  console.log(chalk.cyan(`  Read RULES.md before starting — it maps every playbook for this stack.`))
-  console.log('')
-} catch (err) {
-  spinner.fail(chalk.red('Failed to generate project'))
-  console.error(err)
-  process.exit(1)
-}
+await runCli()

package/{playbooks → library}/INDEX.md

@@ -1,6 +1,6 @@
 # Playbook Index
 
-Playbooks are task-routed standards used by generated projects. Their co-located manifests decide when a playbook applies and which headings appear in generated `RULES.md`.
+Guidance files are task-routed standards used by generated projects. Their co-located definitions decide when guidance applies and which headings appear in generated `RULES.md`.
 
 ## Content groups
 
@@ -17,7 +17,7 @@ Playbooks are task-routed standards used by generated projects. Their co-located
 ## Composition
 
 ```text
-required universal + selected platform manifests
+required universal + selected platform definitions
   + selected frontend
   + selected backend/database/migration
   + selected styling
@@ -37,10 +37,10 @@ Expo uses React Native `StyleSheet` by default. Web projects can select Tailwind
 
 ## Manifest contract
 
-A stack manifest must declare all three architecture profiles. Any manifest may declare:
+A stack definition must declare all three architecture profiles. Any definition may declare:
 
 - `id`, `kind`, `label`, and compatibility;
-- dependency names, scripts, templates, and conditional playbooks (versions live only in `compatibility/profiles.json`);
+- dependency names, scripts, templates, and conditional playbooks (versions live only in `library/tested-versions.json`);
 - semantic environment names and client-visible names;
 - stack constraints;
 - required and optional concerns, target playbook, headings, and applicability.

package/{playbooks/capabilities/ci/github-actions.manifest.json → library/development-tools/ci/definition.json}

@@ -2,6 +2,7 @@
   "id": "github-actions",
   "kind": "devops",
   "label": "GitHub Actions CI",
+  "file": "capabilities/ci/github-actions.md",
   "required": false,
   "folders": [".github/workflows"],
   "concerns": [

package/{playbooks/devops/makefile.manifest.json → library/development-tools/devops/makefile/definition.json}

@@ -2,6 +2,7 @@
   "id": "makefile",
   "kind": "devops",
   "label": "Makefile",
+  "file": "devops/makefile.md",
   "required": false,
   "folders": [],
   "concerns": [

package/{playbooks/devops/pr-template.manifest.json → library/development-tools/devops/pr-template/definition.json}

@@ -2,6 +2,7 @@
   "id": "pr-template",
   "kind": "devops",
   "label": "PR Template",
+  "file": "devops/pr-template.md",
   "required": false,
   "folders": [],
   "concerns": [

package/{playbooks/platform/mobile.manifest.json → library/platforms/mobile/definition.json}

@@ -2,6 +2,7 @@
   "id": "mobile-platform",
   "kind": "platform",
   "label": "Mobile Platform",
+  "file": "platform/mobile.md",
   "appliesTo": { "platform": ["mobile"] },
   "deps": [],
   "devDeps": [],