create-forgeon 0.2.7 → 0.2.9

package/README.md

@@ -37,4 +37,4 @@ pnpm forgeon:sync-integrations
 - `add i18n` is implemented and applies backend/frontend i18n wiring.
 - `add jwt-auth` is implemented and auto-detects DB adapter support for refresh-token persistence.
 - Integration sync is bundled by default and runs after `add` commands (best-effort).
-- Planned modules write docs notes under `docs/AI/MODULES/`.
+- Module notes are written under `modules/<module-id>/README.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Forgeon project generator CLI",
   "license": "MIT",
   "author": "Forgeon",

package/src/core/docs.mjs

@@ -1,10 +1,9 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { getDatabaseLabel } from '../databases/index.mjs';
-import { getFrontendLabel } from '../frameworks/index.mjs';
-import { getProxyConfigPath } from '../infrastructure/proxy.mjs';
-
-function renderTemplate(content, variables) {
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDatabaseLabel } from '../databases/index.mjs';
+import { getFrontendLabel } from '../frameworks/index.mjs';
+
+function renderTemplate(content, variables) {
   return content.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => String(variables[key] ?? ''));
 }
 
@@ -50,7 +49,6 @@ export function generateDocs(targetRoot, options, packageRoot) {
     DB_PRISMA_STATUS: options.dbPrismaEnabled ? 'enabled' : 'disabled',
     DOCKER_STATUS: 'enabled',
     PROXY_LABEL: options.proxy,
-    PROXY_CONFIG_PATH: getProxyConfigPath(options.proxy),
   };
 
   const readmeFragments = ['00_title', '10_stack', '20_quick_start_dev_intro'];
@@ -78,76 +76,13 @@ export function generateDocs(targetRoot, options, packageRoot) {
   }
   readmeFragments.push('41_error_handling');
   readmeFragments.push('90_next_steps');
-
-  const aiProjectFragments = ['00_title', '10_what_is', '20_structure_base'];
-  if (options.dbPrismaEnabled) {
-    aiProjectFragments.push('20b_structure_db_prisma');
-  } else {
-    aiProjectFragments.push('20b_structure_db_none');
-  }
-  if (options.i18nEnabled) {
-    aiProjectFragments.push('21_structure_i18n');
-  }
-  aiProjectFragments.push('22_structure_docker', '23_structure_docs', '30_run_dev', '31_run_docker');
-  if (options.proxy === 'none') {
-    aiProjectFragments.push('32_proxy_notes_none');
-  } else {
-    aiProjectFragments.push('32_proxy_notes');
-  }
-  if (options.i18nEnabled) {
-    aiProjectFragments.push('33_i18n_notes');
-  }
-  aiProjectFragments.push('34_error_handling');
-  aiProjectFragments.push('40_change_boundaries_base');
-  if (options.proxy !== 'none') {
-    aiProjectFragments.push('41_change_boundaries_docker');
-  }
-
-  const aiArchitectureFragments = ['00_title', '10_layout_base', '11_layout_infra'];
-  if (options.i18nEnabled) {
-    aiArchitectureFragments.push('12_layout_i18n_resources');
-  }
-  aiArchitectureFragments.push('20_env_base');
-  if (options.dbPrismaEnabled) {
-    aiArchitectureFragments.push('20b_env_db_prisma');
-  }
-  if (options.i18nEnabled) {
-    aiArchitectureFragments.push('21_env_i18n');
-  }
-  aiArchitectureFragments.push('22_ts_module_policy');
-  aiArchitectureFragments.push('23_error_handling');
-  if (options.dbPrismaEnabled) {
-    aiArchitectureFragments.push('30_default_db');
-  } else {
-    aiArchitectureFragments.push('30_default_db_none');
-  }
-  aiArchitectureFragments.push('31_docker_runtime', '32_scope_freeze');
-  aiArchitectureFragments.push('40_docs_generation', '50_extension_points');
-
-  writeDocFromFragments({
-    targetRoot,
+
+  writeDocFromFragments({
+    targetRoot,
     outputPath: 'README.md',
     fragmentsRoot,
-    docKey: 'README',
-    fragmentNames: readmeFragments,
-    variables,
-  });
-
-  writeDocFromFragments({
-    targetRoot,
-    outputPath: path.join('docs', 'AI', 'PROJECT.md'),
-    fragmentsRoot,
-    docKey: 'AI_PROJECT',
-    fragmentNames: aiProjectFragments,
-    variables,
-  });
-
-  writeDocFromFragments({
-    targetRoot,
-    outputPath: path.join('docs', 'AI', 'ARCHITECTURE.md'),
-    fragmentsRoot,
-    docKey: 'AI_ARCHITECTURE',
-    fragmentNames: aiArchitectureFragments,
-    variables,
-  });
-}
+    docKey: 'README',
+    fragmentNames: readmeFragments,
+    variables,
+  });
+}

package/src/core/docs.test.mjs

@@ -18,7 +18,7 @@ describe('generateDocs', () => {
   const thisDir = path.dirname(fileURLToPath(import.meta.url));
   const packageRoot = path.resolve(thisDir, '..', '..');
 
-  it('generates docs for proxy=none without i18n section', () => {
+  it('generates docs for proxy=none without i18n section', () => {
     const targetRoot = makeTempDir('forgeon-docs-off-');
 
     try {
@@ -34,31 +34,18 @@ describe('generateDocs', () => {
         },
         packageRoot,
       );
-
-      const readme = readFile(path.join(targetRoot, 'README.md'));
-      const projectDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'PROJECT.md'));
-      const architectureDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'ARCHITECTURE.md'));
-
+
+      const readme = readFile(path.join(targetRoot, 'README.md'));
+
       assert.match(readme, /db-prisma`: `disabled`/);
       assert.match(readme, /No DB module is enabled by default/);
       assert.match(readme, /Quick Start \(Docker\)/);
       assert.match(readme, /Proxy Preset: none/);
       assert.match(readme, /Error Handling \(`core-errors`\)/);
+      assert.match(readme, /Module notes index: `modules\/README\.md`/);
       assert.doesNotMatch(readme, /i18n Configuration/);
       assert.doesNotMatch(readme, /Prisma In Container Start/);
-
-      assert.match(projectDoc, /### Docker mode/);
-      assert.match(projectDoc, /Active proxy preset: `none`/);
-      assert.match(projectDoc, /CoreErrorsModule/);
-      assert.doesNotMatch(projectDoc, /packages\/i18n/);
-
-      assert.match(architectureDoc, /generated without `db-prisma`/);
-      assert.doesNotMatch(architectureDoc, /I18N_ENABLED/);
-      assert.match(architectureDoc, /API_PREFIX/);
-      assert.match(architectureDoc, /Config Strategy/);
-      assert.match(architectureDoc, /TypeScript Module Policy/);
-      assert.match(architectureDoc, /tsconfig\.base\.esm\.json/);
-      assert.doesNotMatch(architectureDoc, /DbPrismaModule/);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'docs')), false);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
@@ -80,29 +67,17 @@ describe('generateDocs', () => {
         },
         packageRoot,
       );
-
-      const readme = readFile(path.join(targetRoot, 'README.md'));
-      const projectDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'PROJECT.md'));
-      const architectureDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'ARCHITECTURE.md'));
-
+
+      const readme = readFile(path.join(targetRoot, 'README.md'));
+
       assert.match(readme, /Quick Start \(Docker\)/);
       assert.match(readme, /Proxy Preset: Caddy/);
       assert.match(readme, /i18n Configuration/);
       assert.match(readme, /db-prisma`: `enabled`/);
       assert.match(readme, /Prisma In Container Start/);
       assert.match(readme, /Error Handling \(`core-errors`\)/);
-
-      assert.match(projectDoc, /`infra` - Docker Compose \(always\) \+ proxy preset \(`caddy`\)/);
-      assert.match(projectDoc, /Main proxy config: `infra\/caddy\/Caddyfile`/);
-      assert.match(projectDoc, /CoreExceptionFilter/);
-
-      assert.match(architectureDoc, /infra\/\*/);
-      assert.match(architectureDoc, /I18N_DEFAULT_LANG/);
-      assert.doesNotMatch(architectureDoc, /I18N_ENABLED/);
-      assert.match(architectureDoc, /Active reverse proxy preset: `caddy`/);
-      assert.match(architectureDoc, /TypeScript Module Policy/);
-      assert.match(architectureDoc, /tsconfig\.base\.node\.json/);
-      assert.match(architectureDoc, /DbPrismaModule/);
+      assert.match(readme, /Module-specific notes: `modules\/<module-id>\/README\.md`/);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'docs')), false);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }

package/src/core/scaffold.mjs

@@ -38,7 +38,7 @@ function patchRootPackageJson(targetRoot, projectName) {
   writeJson(rootPackageJsonPath, rootPackageJson);
 }
 
-export function scaffoldProject({
+export function scaffoldProject({
   templateRoot,
   packageRoot,
   targetRoot,
@@ -50,6 +50,10 @@ export function scaffoldProject({
   proxy,
 }) {
   copyRecursive(templateRoot, targetRoot);
+  const generatedDocsPath = path.join(targetRoot, 'docs');
+  if (fs.existsSync(generatedDocsPath)) {
+    fs.rmSync(generatedDocsPath, { recursive: true, force: true });
+  }
   patchRootPackageJson(targetRoot, projectName);
   applyProxyPreset(targetRoot, proxy);
 

package/src/integrations/flow.mjs

@@ -114,5 +114,5 @@ export async function runIntegrationFlow({
 
 export function printModuleAdded(moduleId, docsPath) {
   console.log(colorize('green', `✔ Module added: ${moduleId}`));
-  console.log(`- docs: ${docsPath}`);
+  console.log(`- readme: ${docsPath}`);
 }

package/src/modules/docs.mjs

@@ -20,25 +20,25 @@ function readModuleFragment(packageRoot, moduleId, fragmentName, variables) {
   return renderTemplate(raw, variables).trim();
 }
 
-function ensureModuleIndex(targetRoot) {
-  const indexPath = path.join(targetRoot, 'docs', 'AI', 'MODULES', 'README.md');
-  if (!fs.existsSync(indexPath)) {
-    fs.mkdirSync(path.dirname(indexPath), { recursive: true });
-    fs.writeFileSync(
-      indexPath,
-      '# MODULES\n\nGenerated notes for module presets added via `create-forgeon add`.\n',
-      'utf8',
-    );
-  }
-  return indexPath;
-}
-
-function updateModuleIndex(indexPath, preset) {
-  const relativePath = `${preset.id}.md`;
-  const nextLine = `- \`${preset.id}\` - ${preset.label} (${preset.implemented ? 'implemented' : 'planned'})`;
-  const current = fs.readFileSync(indexPath, 'utf8').replace(/\r\n/g, '\n');
-
-  if (current.includes(`\`${preset.id}\``)) {
+function ensureModuleIndex(targetRoot) {
+  const indexPath = path.join(targetRoot, 'modules', 'README.md');
+  if (!fs.existsSync(indexPath)) {
+    fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+    fs.writeFileSync(
+      indexPath,
+      '# Modules\n\nUser-facing notes for modules added via `create-forgeon add`.\n',
+      'utf8',
+    );
+  }
+  return indexPath;
+}
+
+function updateModuleIndex(indexPath, preset) {
+  const relativePath = `./${preset.id}/README.md`;
+  const nextLine = `- [\`${preset.id}\`](${relativePath}) - ${preset.label} (${preset.implemented ? 'implemented' : 'planned'})`;
+  const current = fs.readFileSync(indexPath, 'utf8').replace(/\r\n/g, '\n');
+
+  if (current.includes(`\`${preset.id}\``)) {
     return;
   }
 
@@ -46,7 +46,7 @@ function updateModuleIndex(indexPath, preset) {
   fs.writeFileSync(indexPath, content, 'utf8');
 }
 
-export function writeModuleDocs({ packageRoot, targetRoot, preset }) {
+export function writeModuleDocs({ packageRoot, targetRoot, preset }) {
   const variables = {
     MODULE_ID: preset.id,
     MODULE_LABEL: preset.label,
@@ -59,9 +59,9 @@ export function writeModuleDocs({ packageRoot, targetRoot, preset }) {
     .map((fragmentName) => readModuleFragment(packageRoot, preset.id, fragmentName, variables))
     .filter(Boolean);
 
-  const outputPath = path.join(targetRoot, 'docs', 'AI', 'MODULES', `${preset.id}.md`);
-  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.writeFileSync(outputPath, `${sections.join('\n\n').trimEnd()}\n`, 'utf8');
+  const outputPath = path.join(targetRoot, 'modules', preset.id, 'README.md');
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${sections.join('\n\n').trimEnd()}\n`, 'utf8');
 
   const indexPath = ensureModuleIndex(targetRoot);
   updateModuleIndex(indexPath, preset);

package/src/modules/executor.mjs

@@ -57,7 +57,7 @@ export function addModule({ moduleId, targetRoot, packageRoot, writeDocs = true
         targetRoot,
         preset,
       })
-    : path.join(targetRoot, 'docs', 'AI', 'MODULES', `${preset.id}.md`);
+    : path.join(targetRoot, 'modules', preset.id, 'README.md');
 
   return {
     preset,

package/src/modules/executor.test.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { addModule } from './executor.mjs';
-import { syncIntegrations } from './sync-integrations.mjs';
+import { scanIntegrations, syncIntegrations } from './sync-integrations.mjs';
 import { scaffoldProject } from '../core/scaffold.mjs';
 
 function mkTmp(prefix) {
@@ -289,11 +289,13 @@ describe('addModule', () => {
         packageRoot,
       });
 
-      assert.equal(result.applied, false);
-      assert.match(result.message, /planned/);
-      assert.equal(fs.existsSync(result.docsPath), true);
-
-      const note = fs.readFileSync(result.docsPath, 'utf8');
+      assert.equal(result.applied, false);
+      assert.match(result.message, /planned/);
+      assert.equal(fs.existsSync(result.docsPath), true);
+      assert.match(result.docsPath, /modules[\\/].+[\\/]README\.md$/);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'modules', 'README.md')), true);
+
+      const note = fs.readFileSync(result.docsPath, 'utf8');
       assert.match(note, /Queue Worker/);
       assert.match(note, /Status: planned/);
     } finally {
@@ -337,6 +339,8 @@ describe('addModule', () => {
         proxy: 'caddy',
       });
 
+      assert.equal(fs.existsSync(path.join(projectRoot, 'docs')), false);
+
       const result = addModule({
         moduleId: 'i18n',
         targetRoot: projectRoot,
@@ -1145,6 +1149,80 @@ describe('addModule', () => {
     }
   });
 
+  it('detects and applies jwt-auth + rbac claims integration explicitly', () => {
+    const targetRoot = mkTmp('forgeon-module-jwt-rbac-');
+    const projectRoot = path.join(targetRoot, 'demo-jwt-rbac');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-jwt-rbac',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      addModule({
+        moduleId: 'rbac',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+      addModule({
+        moduleId: 'jwt-auth',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      const scan = scanIntegrations({
+        targetRoot: projectRoot,
+        relatedModuleId: 'jwt-auth',
+      });
+      assert.equal(scan.groups.some((group) => group.id === 'auth-rbac-claims'), true);
+
+      const syncResult = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-rbac-claims'],
+      });
+      const claimsPair = syncResult.summary.find((item) => item.id === 'auth-rbac-claims');
+      assert.ok(claimsPair);
+      assert.equal(claimsPair.result.applied, true);
+
+      const authContracts = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'auth-contracts', 'src', 'index.ts'),
+        'utf8',
+      );
+      assert.match(authContracts, /permissions\?: string\[\];/);
+
+      const authService = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'auth-api', 'src', 'auth.service.ts'),
+        'utf8',
+      );
+      assert.match(authService, /permissions: \['health\.rbac'\]/);
+      assert.match(authService, /permissions: user\.permissions,/);
+      assert.match(
+        authService,
+        /permissions: Array\.isArray\(payload\.permissions\) \? payload\.permissions : \[\],/,
+      );
+
+      const authController = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'auth-api', 'src', 'auth.controller.ts'),
+        'utf8',
+      );
+      assert.match(
+        authController,
+        /permissions: Array\.isArray\(payload\.permissions\) \? payload\.permissions : \[\],/,
+      );
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
   it('applies logger then jwt-auth on db/i18n-disabled scaffold without breaking health controller syntax', () => {
     const targetRoot = mkTmp('forgeon-module-jwt-nodb-noi18n-');
     const projectRoot = path.join(targetRoot, 'demo-jwt-nodb-noi18n');

package/src/modules/sync-integrations.mjs

@@ -68,6 +68,29 @@ function isAuthPersistencePending(rootDir) {
   return !(hasModuleWiring && hasSchema && hasStoreFile && hasMigration);
 }
 
+function isAuthRbacPending(rootDir) {
+  const authContractsPath = path.join(rootDir, 'packages', 'auth-contracts', 'src', 'index.ts');
+  const authServicePath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.service.ts');
+  const authControllerPath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.controller.ts');
+
+  if (!fs.existsSync(authContractsPath) || !fs.existsSync(authServicePath) || !fs.existsSync(authControllerPath)) {
+    return false;
+  }
+
+  const authContracts = fs.readFileSync(authContractsPath, 'utf8');
+  const authService = fs.readFileSync(authServicePath, 'utf8');
+  const authController = fs.readFileSync(authControllerPath, 'utf8');
+
+  const hasContracts = authContracts.includes('permissions?: string[];');
+  const hasDemoClaims = authService.includes("permissions: ['health.rbac']");
+  const hasPayloadClaims = authService.includes('permissions: user.permissions,');
+  const hasRefreshClaims = authService.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],');
+  const hasControllerClaims =
+    authController.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],');
+
+  return !(hasContracts && hasDemoClaims && hasPayloadClaims && hasRefreshClaims && hasControllerClaims);
+}
+
 const INTEGRATION_GROUPS = [
   {
     id: 'auth-persistence',
@@ -83,6 +106,20 @@ const INTEGRATION_GROUPS = [
     isPending: (rootDir) => isAuthPersistencePending(rootDir),
     apply: syncJwtDbPrisma,
   },
+  {
+    id: 'auth-rbac-claims',
+    title: 'Auth Claims Integration',
+    modules: ['jwt-auth', 'rbac'],
+    description: [
+      'Extend AuthUser with optional permissions in @forgeon/auth-contracts',
+      'Add demo RBAC claims to jwt-auth login and token payloads',
+      'Expose permissions in auth refresh and /me responses',
+      'Update JWT auth README note about RBAC demo claims',
+    ],
+    isAvailable: (detected) => detected.jwtAuth && detected.rbac,
+    isPending: (rootDir) => isAuthRbacPending(rootDir),
+    apply: syncJwtRbacClaims,
+  },
 ];
 
 function detectModules(rootDir) {
@@ -93,6 +130,9 @@ function detectModules(rootDir) {
     jwtAuth:
       fs.existsSync(path.join(rootDir, 'packages', 'auth-api', 'package.json')) ||
       appModuleText.includes("from '@forgeon/auth-api'"),
+    rbac:
+      fs.existsSync(path.join(rootDir, 'packages', 'rbac', 'package.json')) ||
+      appModuleText.includes("from '@forgeon/rbac'"),
     dbPrisma:
       fs.existsSync(path.join(rootDir, 'packages', 'db-prisma', 'package.json')) ||
       appModuleText.includes("from '@forgeon/db-prisma'"),
@@ -216,6 +256,109 @@ function syncJwtDbPrisma({ rootDir, packageRoot, changedFiles }) {
   return { applied: true };
 }
 
+function syncJwtRbacClaims({ rootDir, changedFiles }) {
+  const authContractsPath = path.join(rootDir, 'packages', 'auth-contracts', 'src', 'index.ts');
+  const authServicePath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.service.ts');
+  const authControllerPath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.controller.ts');
+  const readmePath = path.join(rootDir, 'README.md');
+
+  if (!fs.existsSync(authContractsPath) || !fs.existsSync(authServicePath) || !fs.existsSync(authControllerPath)) {
+    return { applied: false, reason: 'auth package files are missing' };
+  }
+
+  let touched = false;
+
+  let authContracts = fs.readFileSync(authContractsPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthContracts = authContracts;
+  if (!authContracts.includes('permissions?: string[];')) {
+    authContracts = authContracts.replace(
+      '  roles: string[];',
+      `  roles: string[];
+  permissions?: string[];`,
+    );
+  }
+  if (authContracts !== originalAuthContracts) {
+    fs.writeFileSync(authContractsPath, `${authContracts.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authContractsPath);
+    touched = true;
+  }
+
+  let authService = fs.readFileSync(authServicePath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthService = authService;
+  authService = authService.replace(
+    /roles: \['user'\],/g,
+    `roles: ['admin'],
+      permissions: ['health.rbac'],`,
+  );
+  if (!authService.includes('permissions: user.permissions,')) {
+    authService = authService.replace(
+      '      roles: user.roles,',
+      `      roles: user.roles,
+      permissions: user.permissions,`,
+    );
+  }
+  if (!authService.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],')) {
+    authService = authService.replace(
+      "      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],",
+      `      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
+      permissions: Array.isArray(payload.permissions) ? payload.permissions : [],`,
+    );
+  }
+  if (!authService.includes('demoPermissions: [')) {
+    authService = authService.replace(
+      "      demoEmail: this.configService.demoEmail,",
+      `      demoEmail: this.configService.demoEmail,
+      demoPermissions: ['health.rbac'],`,
+    );
+  }
+  if (authService !== originalAuthService) {
+    fs.writeFileSync(authServicePath, `${authService.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authServicePath);
+    touched = true;
+  }
+
+  let authController = fs.readFileSync(authControllerPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthController = authController;
+  if (!authController.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],')) {
+    authController = authController.replace(
+      "      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],",
+      `      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
+      permissions: Array.isArray(payload.permissions) ? payload.permissions : [],`,
+    );
+  }
+  if (authController !== originalAuthController) {
+    fs.writeFileSync(authControllerPath, `${authController.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authControllerPath);
+    touched = true;
+  }
+
+  if (fs.existsSync(readmePath)) {
+    let readme = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+    const originalReadme = readme;
+    if (!readme.includes('- RBAC integration: demo auth tokens include `health.rbac` permission')) {
+      const marker = 'Default demo credentials:';
+      if (readme.includes(marker)) {
+        readme = readme.replace(
+          marker,
+          `- RBAC integration: demo auth tokens include \`health.rbac\` permission
+
+Default demo credentials:`,
+        );
+      }
+    }
+    if (readme !== originalReadme) {
+      fs.writeFileSync(readmePath, `${readme.trimEnd()}\n`, 'utf8');
+      changedFiles.add(readmePath);
+      touched = true;
+    }
+  }
+
+  if (!touched) {
+    return { applied: false, reason: 'already synced' };
+  }
+  return { applied: true };
+}
+
 export function syncIntegrations({ targetRoot, packageRoot, groupIds = null }) {
   const rootDir = path.resolve(targetRoot);
   const changedFiles = new Set();

package/src/run-add-module.mjs

@@ -94,7 +94,7 @@ function ensureSyncTooling({ packageRoot, targetRoot }) {
   );
   const targetScript = path.join(targetRoot, 'scripts', 'forgeon-sync-integrations.mjs');
 
-  if (fs.existsSync(sourceScript) && !fs.existsSync(targetScript)) {
+  if (fs.existsSync(sourceScript)) {
     fs.mkdirSync(path.dirname(targetScript), { recursive: true });
     fs.copyFileSync(sourceScript, targetScript);
   }

package/templates/base/README.md

@@ -37,6 +37,7 @@ pnpm forgeon:sync-integrations
 ```
 
 Current sync coverage:
+- `jwt-auth + rbac`: extends demo auth tokens with the `health.rbac` permission.
 - `jwt-auth + db-prisma`: wires persistent refresh-token storage for auth.
 
 `create-forgeon add <module>` scans for relevant integration groups and can apply them immediately.

package/templates/base/scripts/forgeon-sync-integrations.mjs

@@ -53,6 +53,9 @@ function detectModules(rootDir) {
     jwtAuth:
       fs.existsSync(path.join(rootDir, 'packages', 'auth-api', 'package.json')) ||
       appModuleText.includes("from '@forgeon/auth-api'"),
+    rbac:
+      fs.existsSync(path.join(rootDir, 'packages', 'rbac', 'package.json')) ||
+      appModuleText.includes("from '@forgeon/rbac'"),
     dbPrisma:
       fs.existsSync(path.join(rootDir, 'packages', 'db-prisma', 'package.json')) ||
       appModuleText.includes("from '@forgeon/db-prisma'"),
@@ -179,6 +182,109 @@ function syncJwtDbPrisma({ rootDir, changedFiles }) {
   return { applied: true };
 }
 
+function syncJwtRbacClaims({ rootDir, changedFiles }) {
+  const authContractsPath = path.join(rootDir, 'packages', 'auth-contracts', 'src', 'index.ts');
+  const authServicePath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.service.ts');
+  const authControllerPath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.controller.ts');
+  const readmePath = path.join(rootDir, 'README.md');
+
+  if (!fs.existsSync(authContractsPath) || !fs.existsSync(authServicePath) || !fs.existsSync(authControllerPath)) {
+    return { applied: false, reason: 'auth package files are missing' };
+  }
+
+  let touched = false;
+
+  let authContracts = fs.readFileSync(authContractsPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthContracts = authContracts;
+  if (!authContracts.includes('permissions?: string[];')) {
+    authContracts = authContracts.replace(
+      '  roles: string[];',
+      `  roles: string[];
+  permissions?: string[];`,
+    );
+  }
+  if (authContracts !== originalAuthContracts) {
+    fs.writeFileSync(authContractsPath, `${authContracts.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authContractsPath);
+    touched = true;
+  }
+
+  let authService = fs.readFileSync(authServicePath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthService = authService;
+  authService = authService.replace(
+    /roles: \['user'\],/g,
+    `roles: ['admin'],
+      permissions: ['health.rbac'],`,
+  );
+  if (!authService.includes('permissions: user.permissions,')) {
+    authService = authService.replace(
+      '      roles: user.roles,',
+      `      roles: user.roles,
+      permissions: user.permissions,`,
+    );
+  }
+  if (!authService.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],')) {
+    authService = authService.replace(
+      "      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],",
+      `      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
+      permissions: Array.isArray(payload.permissions) ? payload.permissions : [],`,
+    );
+  }
+  if (!authService.includes('demoPermissions: [')) {
+    authService = authService.replace(
+      "      demoEmail: this.configService.demoEmail,",
+      `      demoEmail: this.configService.demoEmail,
+      demoPermissions: ['health.rbac'],`,
+    );
+  }
+  if (authService !== originalAuthService) {
+    fs.writeFileSync(authServicePath, `${authService.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authServicePath);
+    touched = true;
+  }
+
+  let authController = fs.readFileSync(authControllerPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthController = authController;
+  if (!authController.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],')) {
+    authController = authController.replace(
+      "      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],",
+      `      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
+      permissions: Array.isArray(payload.permissions) ? payload.permissions : [],`,
+    );
+  }
+  if (authController !== originalAuthController) {
+    fs.writeFileSync(authControllerPath, `${authController.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authControllerPath);
+    touched = true;
+  }
+
+  if (fs.existsSync(readmePath)) {
+    let readme = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+    const originalReadme = readme;
+    if (!readme.includes('- RBAC integration: demo auth tokens include `health.rbac` permission')) {
+      const marker = 'Default demo credentials:';
+      if (readme.includes(marker)) {
+        readme = readme.replace(
+          marker,
+          `- RBAC integration: demo auth tokens include \`health.rbac\` permission
+
+Default demo credentials:`,
+        );
+      }
+    }
+    if (readme !== originalReadme) {
+      fs.writeFileSync(readmePath, `${readme.trimEnd()}\n`, 'utf8');
+      changedFiles.add(readmePath);
+      touched = true;
+    }
+  }
+
+  if (!touched) {
+    return { applied: false, reason: 'already synced' };
+  }
+  return { applied: true };
+}
+
 function run() {
   const rootDir = process.cwd();
   const changedFiles = new Set();
@@ -197,6 +303,18 @@ function run() {
     });
   }
 
+  if (detected.jwtAuth && detected.rbac) {
+    summary.push({
+      feature: 'jwt-auth + rbac',
+      result: syncJwtRbacClaims({ rootDir, changedFiles }),
+    });
+  } else {
+    summary.push({
+      feature: 'jwt-auth + rbac',
+      result: { applied: false, reason: 'required modules are not both installed' },
+    });
+  }
+
   console.log('[forgeon:sync-integrations] done');
   for (const item of summary) {
     if (item.result.applied) {

package/templates/docs-fragments/AI_ARCHITECTURE/40_docs_generation.md

@@ -1,9 +1,11 @@
-## Docs Generation Pipeline
-
-Project docs are assembled from markdown fragments in:
-
-- `packages/create-forgeon/templates/docs-fragments/README`
-- `packages/create-forgeon/templates/docs-fragments/AI_PROJECT`
-- `packages/create-forgeon/templates/docs-fragments/AI_ARCHITECTURE`
-
-During scaffold generation, the CLI selects fragments based on chosen flags and writes final docs into project root and `docs/AI`.
+## Docs Generation Pipeline
+
+Project docs are assembled from markdown fragments in:
+
+- `packages/create-forgeon/templates/docs-fragments/README`
+- `packages/create-forgeon/templates/docs-fragments/AI_PROJECT`
+- `packages/create-forgeon/templates/docs-fragments/AI_ARCHITECTURE`
+
+During scaffold generation, the CLI currently writes the generated project `README.md` from these fragments.
+
+Internal architecture fragments remain in the Forgeon repository as generator source material and are not emitted into generated projects by default.

package/templates/docs-fragments/README/90_next_steps.md

@@ -1,7 +1,6 @@
-## Next Steps
-
-- Backend entrypoint: `apps/api/src/main.ts`
-- Frontend entrypoint: `apps/web/src/main.tsx`
-- Project docs index: `docs/README.md`
-- AI workflow docs: `docs/AI/*`
-- Module contract spec: `docs/AI/MODULE_SPEC.md`
+## Next Steps
+
+- Backend entrypoint: `apps/api/src/main.ts`
+- Frontend entrypoint: `apps/web/src/main.tsx`
+- Module notes index: `modules/README.md`
+- Module-specific notes: `modules/<module-id>/README.md`