create-win-project 1.3.0 → 2.0.0

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.
@@ -55,4 +55,4 @@ Manifests compose capabilities; `lib/scaffold.js` owns their executable minimum.
 - `playbooks/`: only selected reusable guidance.
 - `docs/`: setup, API, architecture, auth, and deployment for the generated product.
 
-See `docs/CONTENT_MODEL.md` for authoring and deduplication rules and `docs/ARCHITECTURE.md` for the generation pipeline.
+See `docs/maintainers/content-model.md` for authoring and deduplication rules and `docs/maintainers/architecture.md` for the generation pipeline.

package/library/compatibility-impact.json

@@ -0,0 +1,14 @@
+{
+  "stacks": {
+    "nextjs": ["src/stacks/frontends/nextjs/", "library/stacks/nextjs/", "templates/agents/nextjs.", "templates/ci/nextjs."],
+    "react": ["src/stacks/frontends/react-vite/", "library/stacks/react-vite/", "templates/agents/react-vite.", "templates/ci/vite."],
+    "react-native": ["src/stacks/frontends/react-native/", "library/stacks/expo/", "templates/agents/react-native.", "templates/ci/expo."],
+    "springboot": ["src/stacks/backends/springboot/", "library/stacks/springboot/", "library/features/flyway/", "templates/ci/springboot."],
+    "fastapi": ["src/stacks/backends/fastapi/", "library/stacks/fastapi/", "library/features/sqlalchemy-alembic.md", "templates/ci/fastapi."],
+    "laravel": ["src/stacks/backends/laravel/", "library/stacks/laravel/", "library/features/laravel", "templates/ci/laravel."],
+    "supabase": ["src/stacks/backends/supabase/", "library/features/supabase/"],
+    "postgres": ["src/stacks/backends/postgres/", "library/features/postgresql/", "library/features/prisma/"],
+    "none": ["src/stacks/backends/none/"]
+  },
+  "shared": ["library/tested-versions.json", "lib/", "src/engine/", "src/stacks/shared/", "templates/docker/", "templates/gitignore/", "templates/makefile/", "checks/check-compatibility.js", "checks/check-generated-project.js"]
+}

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/library/development-tools/devops/makefile/commands.md

@@ -0,0 +1,11 @@
+# Make commands
+
+## Core Rules
+
+- Targets wrap documented project commands; they do not hide different behavior.
+- Declare non-file targets with `.PHONY`.
+- Use tabs for recipes and `$(VARIABLE)` for configurable values.
+- Keep the default target safe and read-only; `help` or `check` is preferred.
+- Fail on command errors and preserve the underlying exit status.
+
+Use small targets such as `install`, `dev`, `lint`, `test`, `build`, and `check`. Compose them instead of duplicating recipes.

package/library/development-tools/devops/makefile/definition.json

@@ -0,0 +1,11 @@
+{
+  "id": "makefile",
+  "kind": "devops",
+  "label": "Makefile",
+  "playbooks": ["capabilities/devops/makefile/commands.md", "capabilities/devops/makefile/docker.md", "capabilities/devops/makefile/validation.md"],
+  "required": false,
+  "folders": [],
+  "concerns": [
+    { "id": "makefile", "required": true, "playbook": "capabilities/devops/makefile/commands.md", "sections": ["Core Rules"] }
+  ]
+}

package/library/development-tools/devops/makefile/docker.md

@@ -0,0 +1,9 @@
+# Make and Docker
+
+## Docker Targets
+
+- Keep image building separate from container startup.
+- `build` may run `docker compose build`; `run` must not rebuild implicitly.
+- Use the generated Compose file as the source of service names and profiles.
+- Never interpolate secrets into command output.
+- Destructive volume or database targets require explicit names and confirmation.

package/library/development-tools/devops/makefile/validation.md

@@ -0,0 +1,5 @@
+# Make validation
+
+## Validation Targets
+
+`check` should compose the same lint, typecheck, test, and build commands used by CI. Keep focused targets independently runnable, and avoid suppressing failures with leading `-`, `|| true`, or unconditional success messages.

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/library/features/sqlalchemy-alembic.md

@@ -0,0 +1,17 @@
+# SQLAlchemy and Alembic
+
+## Session Ownership
+
+Use SQLAlchemy 2 async sessions with `asyncpg`. Services own session and transaction
+boundaries spanning multiple writes or read-modify-write behavior. Routers never manage
+sessions directly; they receive a session dependency from shared core infrastructure.
+
+Database unique/check/foreign-key constraints are the final concurrency boundary; map
+expected constraint conflicts to stable application errors.
+
+## Migrations
+
+Alembic owns all schema changes. Generate revisions explicitly and apply them with
+`alembic upgrade head` from the backend directory. Application startup must not
+automatically migrate production databases. Verify migration configuration and upgrade
+checks in CI before container builds.

package/library/optional-features/concerns/zod/errors.md

@@ -0,0 +1,5 @@
+# Zod validation errors
+
+## Safe Validation Errors
+
+Convert issues to stable field/code structures at the boundary. Do not expose internal paths, secrets, provider payloads, or raw exception text. Log diagnostic context server-side with request correlation and privacy filtering.

package/library/optional-features/concerns/zod/testing.md

@@ -0,0 +1,5 @@
+# Testing Zod schemas
+
+## Schema Tests
+
+Test valid boundaries, missing required values, wrong types, limits, unknown keys, and security-sensitive malformed input. Prefer small representative fixtures and assert stable error codes rather than complete library messages.

package/library/optional-features/concerns/zod/validation.md

@@ -0,0 +1,21 @@
+# Runtime validation with Zod
+
+## Agent Quick Reference
+
+Parse untrusted values once at their owning boundary, use the inferred type internally, and return safe structured errors.
+
+## Schema First, Always
+
+Define the runtime contract before consuming external data. Use strict schemas for requests, environment variables, persisted data, and provider responses. Apply coercion only when the transport contract explicitly permits it.
+
+## Zod Schema Placement
+
+Place a schema at the boundary that owns the contract. Feature schemas stay with the feature; shared protocol schemas live in a dependency-neutral contract module. Export inferred types rather than duplicating shapes.
+
+## Web Form (React Hook Form)
+
+Use the schema resolver at submission boundaries, show field errors accessibly, and validate again on the server. Client validation improves feedback but never establishes trust.
+
+## React Native Form (React Hook Form + Controller)
+
+Wrap controlled native inputs with `Controller`, preserve accessible labels and errors, and validate the same transport contract again at the trusted server boundary.

package/library/optional-features/styling/css-modules/definition.json

@@ -0,0 +1,12 @@
+{
+  "id": "css-modules",
+  "kind": "styling",
+  "label": "CSS Modules",
+  "playbooks": ["styling/css-modules/theme.md", "styling/css-modules/responsive.md"],
+  "required": false,
+  "folders": [],
+  "concerns": [
+    { "id": "styling-theme", "required": true, "playbook": "styling/css-modules/theme.md", "sections": ["Dark Mode with CSS Variables"] },
+    { "id": "styling-responsive", "required": true, "playbook": "styling/css-modules/responsive.md", "sections": ["Responsive in Module File"] }
+  ]
+}

package/library/optional-features/styling/css-modules/responsive.md

@@ -0,0 +1,5 @@
+# CSS Modules responsive layout
+
+## Responsive in Module File
+
+Keep component breakpoints beside the component styles. Start with the narrow layout, add only measured breakpoints, and prefer container-aware layout when the component is reusable. Avoid global selectors and viewport assumptions inside modules.

package/library/optional-features/styling/css-modules/theme.md

@@ -0,0 +1,7 @@
+# CSS Modules theming
+
+## Dark Mode with CSS Variables
+
+Define semantic color and spacing variables at the application theme boundary. Switch variable values through the selected theme mechanism; components consume semantic tokens and must not duplicate light/dark selectors.
+
+Respect system preference by default, preserve explicit user choice, and maintain accessible contrast in every supported theme.

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": [],

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

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