create-forgeon 0.3.1 → 0.3.2

package/package.json

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

package/src/integrations/flow.mjs

@@ -125,7 +125,7 @@ export function printOptionalIntegrationsWarning(integrations) {
   for (const integration of integrations) {
     console.log(`\n${colorize('yellow', 'Warning: optional integration available')}`);
     console.log(`- ${integration.title}`);
-    console.log('Modules:');
+    console.log('Modules / capabilities:');
     for (const moduleId of integration.modules ?? []) {
       console.log(`- ${colorize('cyan', moduleId)}`);
     }

package/src/modules/dependencies.test.mjs

@@ -44,8 +44,8 @@ const TEST_PRESETS = [
       {
         id: 'auth-persistence',
         title: 'Auth Persistence Integration',
-        modules: ['jwt-auth', 'db-prisma'],
-        requires: [{ type: 'module', id: 'db-prisma' }],
+        modules: ['jwt-auth', 'db-adapter'],
+        requires: [{ type: 'capability', id: 'db-adapter' }],
         description: ['Persist refresh-token state'],
         followUpCommands: [
           'npx create-forgeon@latest add db-prisma',
@@ -130,7 +130,7 @@ describe('module dependency helpers', () => {
 
       assert.equal(pending.length, 1);
       assert.equal(pending[0].id, 'auth-persistence');
-      assert.equal(pending[0].missing[0].id, 'db-prisma');
+      assert.equal(pending[0].missing[0].id, 'db-adapter');
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }

package/src/modules/executor.test.mjs

@@ -79,6 +79,8 @@ function assertRateLimitWiring(projectRoot) {
 
   const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
   assert.match(readme, /## Rate Limit Module/);
+  assert.match(readme, /installs independently/i);
+  assert.match(readme, /no optional integration sync is required/i);
 }
 
 function assertRbacWiring(projectRoot) {
@@ -110,6 +112,8 @@ function assertRbacWiring(projectRoot) {
 
   const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
   assert.match(readme, /## RBAC \/ Permissions Module/);
+  assert.match(readme, /installs independently/i);
+  assert.match(readme, /jwt-auth.*optional/i);
 }
 
 function assertJwtAuthWiring(projectRoot, withPrismaStore) {
@@ -476,6 +480,13 @@ describe('addModule', () => {
       assert.match(rootPackage, /"i18n:types"/);
       assert.match(rootPackage, /"i18n:add"/);
 
+      const rootReadme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
+      assert.match(rootReadme, /## I18n Module/);
+      assert.match(rootReadme, /installs independently/i);
+      assert.match(rootReadme, /multi-package split/i);
+      assert.match(rootReadme, /pnpm i18n:sync/);
+      assert.match(rootReadme, /pnpm i18n:add <locale>/);
+
       const i18nAddScriptPath = path.join(projectRoot, 'scripts', 'i18n-add.mjs');
       assert.equal(fs.existsSync(i18nAddScriptPath), true);
       const syncScriptPath = path.join(projectRoot, 'scripts', 'forgeon-sync-integrations.mjs');
@@ -505,6 +516,11 @@ describe('addModule', () => {
       assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/core build/);
       assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/db-prisma build/);
       assert.match(apiDockerfile, /COPY packages\/db-prisma\/package\.json packages\/db-prisma\/package\.json/);
+
+      const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
+      assert.match(moduleDoc, /I18n/);
+      assert.match(moduleDoc, /installs independently/i);
+      assert.match(moduleDoc, /helper commands are part of the module surface/i);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
@@ -577,6 +593,15 @@ describe('addModule', () => {
       assert.match(apiEnv, /LOGGER_HTTP_ENABLED=true/);
       assert.match(apiEnv, /LOGGER_REQUEST_ID_HEADER=x-request-id/);
 
+      const healthController = fs.readFileSync(
+        path.join(projectRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'),
+        'utf8',
+      );
+      assert.doesNotMatch(healthController, /logger/i);
+
+      const appTsx = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'src', 'App.tsx'), 'utf8');
+      assert.doesNotMatch(appTsx, /Check logger/i);
+
       const dockerEnv = fs.readFileSync(
         path.join(projectRoot, 'infra', 'docker', '.env.example'),
         'utf8',
@@ -592,12 +617,16 @@ describe('addModule', () => {
 
       const rootReadme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
       assert.match(rootReadme, /## Logger Module/);
+      assert.match(rootReadme, /installs independently/i);
+      assert.match(rootReadme, /does not add a dedicated API\/web probe/i);
       assert.match(rootReadme, /LOGGER_LEVEL=log/);
+      assert.match(rootReadme, /stdout\/stderr/i);
       assert.match(rootReadme, /docker compose logs api/);
 
       const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
       assert.match(moduleDoc, /Logger/);
       assert.match(moduleDoc, /Status: implemented/);
+      assert.match(moduleDoc, /no dedicated probe is added by design/i);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
@@ -633,6 +662,8 @@ describe('addModule', () => {
       const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
       assert.match(moduleDoc, /## Idea \/ Why/);
       assert.match(moduleDoc, /## Configuration/);
+      assert.match(moduleDoc, /installs independently/i);
+      assert.match(moduleDoc, /No follow-up integration sync is required/i);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
@@ -756,12 +787,15 @@ describe('addModule', () => {
 
       const rootReadme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
       assert.match(rootReadme, /## Swagger \/ OpenAPI Module/);
+      assert.match(rootReadme, /installs independently/i);
+      assert.match(rootReadme, /decorators.*manual/i);
       assert.match(rootReadme, /SWAGGER_ENABLED=false/);
       assert.match(rootReadme, /localhost:3000\/api\/docs/);
 
       const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
       assert.match(moduleDoc, /Swagger \/ OpenAPI/);
       assert.match(moduleDoc, /Status: implemented/);
+      assert.match(moduleDoc, /feature-specific Swagger decorators remain manual/i);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
@@ -1098,10 +1132,13 @@ describe('addModule', () => {
 
       const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
       assert.match(readme, /refresh token persistence: enabled/);
+      assert.match(readme, /db-adapter/);
+      assert.match(readme, /current provider: `db-prisma`/);
       assert.match(readme, /0002_auth_refresh_token_hash/);
 
       const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
       assert.match(moduleDoc, /Status: implemented/);
+      assert.match(moduleDoc, /db-adapter/);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
@@ -1142,6 +1179,7 @@ describe('addModule', () => {
 
       const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
       assert.match(readme, /refresh token persistence: disabled/);
+      assert.match(readme, /db-adapter/);
       assert.match(readme, /create-forgeon add db-prisma/);
 
     } finally {

package/src/modules/i18n.mjs

@@ -405,6 +405,50 @@ function patchRootPackage(targetRoot) {
   writeJson(packagePath, packageJson);
 }
 
+function patchReadme(targetRoot) {
+  const readmePath = path.join(targetRoot, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    return;
+  }
+
+  const marker = '## I18n Module';
+  let content = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+  if (content.includes(marker)) {
+    return;
+  }
+
+  const section = `## I18n Module
+
+The i18n add-module provides a full backend + frontend localization baseline.
+
+It installs independently and uses a multi-package split:
+- \`@forgeon/i18n\` for Nest runtime wiring
+- \`@forgeon/i18n-contracts\` for generated locale/namespace contracts and maintenance scripts
+- \`@forgeon/i18n-web\` for React-side locale helpers
+
+Shared dictionaries:
+- stored under \`resources/i18n/<locale>/*.json\`
+- current default locale set: \`en\`
+
+Helper commands:
+- \`pnpm i18n:sync\`
+- \`pnpm i18n:check\`
+- \`pnpm i18n:types\`
+- \`pnpm i18n:add <locale>\`
+
+Module env:
+- \`I18N_DEFAULT_LANG=en\`
+- \`I18N_FALLBACK_LANG=en\``;
+
+  if (content.includes('## Prisma In Docker Start')) {
+    content = content.replace('## Prisma In Docker Start', `${section}\n\n## Prisma In Docker Start`);
+  } else {
+    content = `${content.trimEnd()}\n\n${section}\n`;
+  }
+
+  fs.writeFileSync(readmePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
 function restoreKnownWebProbes(targetRoot, previousAppContent) {
   if (!previousAppContent) {
     return;
@@ -533,6 +577,7 @@ export function applyI18nModule({ packageRoot, targetRoot }) {
   patchApiPackage(targetRoot);
   patchWebPackage(targetRoot);
   patchRootPackage(targetRoot);
+  patchReadme(targetRoot);
   patchAppModule(targetRoot);
   patchHealthController(targetRoot);
   patchApiDockerfile(targetRoot);

package/src/modules/jwt-auth.mjs

@@ -309,10 +309,10 @@ function patchReadme(targetRoot) {
   }
 
   const persistenceSummary =
-    '- refresh token persistence: disabled by default (stateless mode)';
+    '- refresh token persistence: disabled by default (stateless mode; enable it later through a `db-adapter` provider + integration sync)';
   const dbFollowUp = `- to enable persistence later:
-  1. install a DB module first (for now: \`create-forgeon add db-prisma --project .\`);
-  2. run \`pnpm forgeon:sync-integrations\` to auto-wire pair integrations.`;
+  1. install a DB adapter provider first (current provider: \`create-forgeon add db-prisma --project .\`);
+  2. run \`pnpm forgeon:sync-integrations\` to wire auth persistence to the active DB adapter implementation.`;
 
   const section = `## JWT Auth Module
 

package/src/modules/logger.mjs

@@ -181,6 +181,9 @@ The logger add-module provides:
 - HTTP access logs with method/path/status/duration/ip/requestId
 - Nest logger integration via \`app.useLogger(...)\`
 
+It installs independently and intentionally does not add a dedicated API/web probe.
+Its verification path is operational: inspect API stdout/stderr in dev or container logs in Docker.
+
 Configuration (env):
 - \`LOGGER_LEVEL=log\` (\`error|warn|log|debug|verbose\`)
 - \`LOGGER_HTTP_ENABLED=true\`

package/src/modules/rate-limit.mjs

@@ -289,7 +289,7 @@ function patchReadme(targetRoot) {
 
   const section = `## Rate Limit Module
 
-The rate-limit add-module provides a simple first-line safeguard against burst traffic, accidental request loops, and brute-force style abuse.
+The rate-limit add-module installs independently and provides a simple first-line safeguard against burst traffic, accidental request loops, and brute-force style abuse.
 
 What it adds:
 - global request throttling for the API
@@ -310,7 +310,8 @@ Configuration (env):
 
 Operational notes:
 - \`THROTTLE_TRUST_PROXY=true\` is recommended behind reverse proxies
-- this is an in-memory throttle preset, not a distributed limiter`;
+- this is an in-memory throttle preset, not a distributed limiter
+- no optional integration sync is required for this module in the current scaffold`;
 
   if (content.includes('## Prisma In Docker Start')) {
     content = content.replace('## Prisma In Docker Start', `${section}\n\n## Prisma In Docker Start`);

package/src/modules/rbac.mjs

@@ -282,6 +282,8 @@ function patchReadme(targetRoot) {
 
 The rbac add-module provides a minimal authorization layer for role and permission checks.
 
+It installs independently. \`jwt-auth\` is optional and only extends demo JWT claims through integration sync.
+
 What it adds:
 - \`@Roles(...)\` and \`@Permissions(...)\` decorators
 - \`ForgeonRbacGuard\`
@@ -299,6 +301,10 @@ How to verify:
 - the generated frontend button sends \`x-forgeon-permissions: health.rbac\` and should return \`200\`
 - the same route without that header should return \`403\`
 
+Optional integration:
+- if \`jwt-auth\` is installed too, run \`pnpm forgeon:sync-integrations\`
+- that enables demo JWT permissions for the same RBAC probe flow
+
 Current scope:
 - no policy engine
 - no database-backed role store

package/src/modules/registry.mjs

@@ -16,7 +16,8 @@ const MODULE_PRESETS = {
     label: 'I18n',
     category: 'localization',
     implemented: true,
-    description: 'Backend/frontend i18n wiring with locale contracts and translation resources.',
+    description:
+      'Independent backend/frontend i18n wiring with contracts, web helpers, shared translation resources, and locale maintenance scripts.',
     detectionPaths: ['packages/i18n/package.json'],
     provides: ['i18n-runtime'],
     requires: [],
@@ -28,7 +29,8 @@ const MODULE_PRESETS = {
     label: 'Logger',
     category: 'observability',
     implemented: true,
-    description: 'Structured API logger with request id middleware and HTTP logging interceptor.',
+    description:
+      'Independent structured API logger with request id middleware and HTTP logging interceptor; intentionally no dedicated runtime probe.',
     detectionPaths: ['packages/logger/package.json'],
     provides: ['logger-runtime'],
     requires: [],
@@ -40,7 +42,8 @@ const MODULE_PRESETS = {
     label: 'Swagger / OpenAPI',
     category: 'api-documentation',
     implemented: true,
-    description: 'OpenAPI docs setup with env-based toggle and route path.',
+    description:
+      'Independent OpenAPI docs setup with env-based toggle and route path; feature-level Swagger decorators remain manual.',
     detectionPaths: ['packages/swagger/package.json'],
     provides: ['openapi-runtime'],
     requires: [],
@@ -52,7 +55,8 @@ const MODULE_PRESETS = {
     label: 'JWT Auth',
     category: 'auth-security',
     implemented: true,
-    description: 'JWT auth preset with contracts/api module split, guard+strategy, and DB-aware refresh token storage wiring.',
+    description:
+      'JWT auth preset with contracts/api module split, guard+strategy, and optional db-adapter-backed refresh token persistence via integration sync.',
     detectionPaths: ['packages/auth-api/package.json'],
     provides: ['auth-runtime'],
     requires: [],
@@ -60,10 +64,11 @@ const MODULE_PRESETS = {
       {
         id: 'auth-persistence',
         title: 'Auth Persistence Integration',
-        modules: ['jwt-auth', 'db-prisma'],
-        requires: [{ type: 'module', id: 'db-prisma' }],
+        modules: ['jwt-auth', 'db-adapter'],
+        requires: [{ type: 'capability', id: 'db-adapter' }],
         description: [
-          'Persist refresh-token state through the current DB integration',
+          'Persist refresh-token state through the db-adapter capability boundary',
+          'Use the current DB adapter implementation (today: db-prisma) for refresh-token storage',
           'Enable stronger refresh-token invalidation flows after logout and rotation',
         ],
         followUpCommands: [
@@ -93,7 +98,8 @@ const MODULE_PRESETS = {
     label: 'Rate Limit',
     category: 'auth-security',
     implemented: true,
-    description: 'Request throttling preset with env-based limits, proxy-aware trust, and a runtime probe endpoint.',
+    description:
+      'Independent request throttling preset with env-based limits, proxy-aware trust, and a runtime probe endpoint.',
     detectionPaths: ['packages/rate-limit/package.json'],
     provides: ['rate-limit-runtime'],
     requires: [],
@@ -115,7 +121,8 @@ const MODULE_PRESETS = {
     label: 'RBAC / Permissions',
     category: 'auth-security',
     implemented: true,
-    description: 'Role and permission decorators with a Nest guard and a protected probe endpoint.',
+    description:
+      'Role and permission decorators with a Nest guard and a protected probe endpoint; installs independently and optionally integrates with jwt-auth.',
     detectionPaths: ['packages/rbac/package.json'],
     provides: ['rbac-runtime'],
     requires: [],

package/src/modules/swagger.mjs

@@ -181,6 +181,9 @@ function patchReadme(targetRoot) {
 
 The swagger add-module provides generated OpenAPI docs for the API.
 
+It installs independently and only wires the OpenAPI runtime.
+Feature-specific Swagger decorators (for example \`@ApiOperation\`, \`@ApiBody\`, \`@ApiResponse\`) remain manual and are not auto-patched into other modules.
+
 Configuration (env):
 - \`SWAGGER_ENABLED=false\`
 - \`SWAGGER_PATH=docs\`

package/src/modules/sync-integrations.mjs

@@ -97,10 +97,10 @@ const INTEGRATION_GROUPS = [
     title: 'Auth Persistence Integration',
     modules: ['jwt-auth', 'db-prisma'],
     description: [
-      'Patch AppModule to wire AUTH_REFRESH_TOKEN_STORE with PrismaAuthRefreshTokenStore',
+      'Patch AppModule to wire AUTH_REFRESH_TOKEN_STORE to the current db-adapter implementation (today: PrismaAuthRefreshTokenStore)',
       'Add apps/api/src/auth/prisma-auth-refresh-token.store.ts',
       'Extend Prisma User model with refreshTokenHash and add migration 0002_auth_refresh_token_hash',
-      'Update JWT auth README note about refresh-token persistence',
+      'Update JWT auth README note to reflect db-adapter-backed refresh-token persistence',
     ],
     isAvailable: (detected) => detected.jwtAuth && detected.dbPrisma,
     isPending: (rootDir) => isAuthPersistencePending(rootDir),
@@ -236,11 +236,11 @@ function syncJwtDbPrisma({ rootDir, packageRoot, changedFiles }) {
     let readme = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
     const originalReadme = readme;
     readme = readme.replace(
-      '- refresh token persistence: disabled by default (stateless mode)',
-      '- refresh token persistence: enabled (`db-prisma` adapter)',
+      '- refresh token persistence: disabled by default (stateless mode; enable it later through a `db-adapter` provider + integration sync)',
+      '- refresh token persistence: enabled through the `db-adapter` capability (current provider: `db-prisma`)',
     );
     readme = readme.replace(
-      /- to enable persistence later:[\s\S]*?2\. run `pnpm forgeon:sync-integrations` to auto-wire pair integrations\./m,
+      /- to enable persistence later:[\s\S]*?2\. run `pnpm forgeon:sync-integrations` to wire auth persistence to the active DB adapter implementation\./m,
       '- migration: `apps/api/prisma/migrations/0002_auth_refresh_token_hash`',
     );
     if (readme !== originalReadme) {

package/templates/base/README.md

@@ -38,7 +38,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.
+- `jwt-auth + db-adapter` (current provider: `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/docs/AI/ARCHITECTURE.md

@@ -57,7 +57,7 @@ Reference: `docs/AI/MODULE_SPEC.md`.
   - each add-module patches only itself;
   - cross-module changes are allowed only in integration sync rules.
 - Current integration:
-  - `jwt-auth + db-prisma` (persistent refresh-token store wiring + schema/migration sync).
+  - `jwt-auth + db-adapter` (current provider: `db-prisma`; persistent refresh-token store wiring + schema/migration sync).
 - Pair sync is explicit (opt-in), not automatic after `add`.
 - Run `pnpm forgeon:sync-integrations` when you want to apply module-pair integrations.
 - Swagger auth decorators are intentionally not auto-patched.

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

@@ -162,11 +162,11 @@ function syncJwtDbPrisma({ rootDir, changedFiles }) {
     let readme = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
     const originalReadme = readme;
     readme = readme.replace(
-      '- refresh token persistence: disabled by default (stateless mode)',
-      '- refresh token persistence: enabled (`db-prisma` adapter)',
+      '- refresh token persistence: disabled by default (stateless mode; enable it later through a `db-adapter` provider + integration sync)',
+      '- refresh token persistence: enabled through the `db-adapter` capability (current provider: `db-prisma`)',
     );
     readme = readme.replace(
-      /- to enable persistence later:[\s\S]*?2\. run `pnpm forgeon:sync-integrations` to auto-wire pair integrations\./m,
+      /- to enable persistence later:[\s\S]*?2\. run `pnpm forgeon:sync-integrations` to wire auth persistence to the active DB adapter implementation\./m,
       '- migration: `apps/api/prisma/migrations/0002_auth_refresh_token_hash`',
     );
     if (readme !== originalReadme) {
@@ -293,12 +293,12 @@ function run() {
 
   if (detected.jwtAuth && detected.dbPrisma) {
     summary.push({
-      feature: 'jwt-auth + db-prisma',
+      feature: 'jwt-auth + db-adapter (current provider: db-prisma)',
       result: syncJwtDbPrisma({ rootDir, changedFiles }),
     });
   } else {
     summary.push({
-      feature: 'jwt-auth + db-prisma',
+      feature: 'jwt-auth + db-adapter (current provider: db-prisma)',
       result: { applied: false, reason: 'required modules are not both installed' },
     });
   }

package/templates/module-fragments/i18n/10_overview.md

@@ -10,6 +10,11 @@ Included parts:
 - shared dictionaries in `resources/i18n/*` (`en` by default) used by both API and web
 - default namespaces: `common`, `errors`, `validation`, `ui`, `notifications`, `meta`
 
+Important boundary:
+- this module installs independently
+- it is intentionally split across runtime, contracts, and web helper packages
+- translation maintenance flows are part of the module contract, not ad-hoc project scripts
+
 Utility commands:
 - `pnpm i18n:sync` - regenerate `I18N_LOCALES` and `I18N_NAMESPACES` from `resources/i18n`.
 - `pnpm i18n:check` - verify generated contracts, JSON validity, and missing/extra keys vs fallback locale.

package/templates/module-fragments/i18n/20_scope.md

@@ -10,3 +10,9 @@
 - `i18n:sync` for locale/namespace contracts sync from `resources/i18n`
 - `i18n:check` for contract/json/key consistency checks
 - `i18n:types` for translation key type generation
+- `i18n:add` for adding a new locale from the command line
+
+Operational notes:
+
+- this module owns the i18n helper commands
+- it does not use integration sync groups today because its work is self-contained within the localization stack

package/templates/module-fragments/i18n/90_status_implemented.md

@@ -1,3 +1,8 @@
 ## Status
 
 Implemented and applied by `create-forgeon add i18n`.
+
+Notes:
+- install is independent
+- helper commands are part of the module surface
+- the module is intentionally multi-package (`runtime + contracts + web`)

package/templates/module-fragments/jwt-auth/20_scope.md

@@ -10,8 +10,10 @@ Implemented scope:
    - `JwtStrategy` + `JwtAuthGuard`
    - `authConfig` + `authEnvSchema` wiring through root `ConfigModule` validator chain
 3. DB behavior:
-   - if supported DB adapter is present (`db-prisma`), refresh token hash persistence is auto-wired
-   - if DB is missing/unsupported, module installs in stateless mode and prints red warning
+   - module install stays stateless by default
+   - refresh token hash persistence is enabled later through the `db-adapter` capability via `pnpm forgeon:sync-integrations`
+   - current DB adapter implementation for this integration is `db-prisma`
+   - if no DB adapter is installed, the module stays stateless and prints an optional integration warning with follow-up commands
 4. Module checks:
    - API probe endpoint: `GET /api/health/auth`
    - default web probe button + result block

package/templates/module-fragments/jwt-auth/90_status_implemented.md

@@ -3,5 +3,6 @@
 Status: implemented.
 
 Notes:
-- DB adapter auto-detection is currently implemented for `db-prisma`.
-- Unknown/missing DB adapter falls back to stateless refresh flow with explicit warning.
+- The persistence boundary is `db-adapter`, not a hard dependency on one concrete DB module.
+- The current DB adapter implementation for auth persistence is `db-prisma`.
+- If no DB adapter is installed, jwt-auth stays in stateless refresh mode and surfaces an optional integration warning.

package/templates/module-fragments/logger/10_overview.md

@@ -8,3 +8,7 @@ Included parts:
 - HTTP logging interceptor for request/response timing
 - env-driven logger config (`LOGGER_LEVEL`, `LOGGER_HTTP_ENABLED`, `LOGGER_REQUEST_ID_HEADER`)
 
+Important boundary:
+- this module installs independently
+- it intentionally does not add a dedicated runtime probe
+- verification is done through API process logs

package/templates/module-fragments/logger/20_scope.md

@@ -9,3 +9,8 @@
 - Adds logger env keys to `apps/api/.env.example` and `infra/docker/.env.example`
 - Passes logger env keys through `infra/docker/compose.yml`
 
+Intentional exception:
+
+- no API `/api/health/*` probe is added
+- no web diagnostics button is added
+- this module is verified by observing structured logs

package/templates/module-fragments/logger/90_status_implemented.md

@@ -2,3 +2,6 @@
 
 Implemented and applied by `create-forgeon add logger`.
 
+Notes:
+- install is independent
+- no dedicated probe is added by design

package/templates/module-fragments/rate-limit/20_idea.md

@@ -1,6 +1,7 @@
 ## Idea / Why
 
 This module adds a simple first-line request throttle to the API.
+It installs independently and does not require another add-module to provide immediate value.
 
 It exists to reduce three common classes of problems:
 

package/templates/module-fragments/rate-limit/30_what_it_adds.md

@@ -7,4 +7,6 @@
 - `GET /api/health/rate-limit` probe endpoint
 - frontend probe button on the generated home page
 
+This module installs independently. In the current scaffold it does not depend on, or require sync with, any other add-module.
+
 This module is API-first. It does not add shared contracts or a web package in v1 because the runtime value is in backend request throttling, not in reusable client-side types.

package/templates/module-fragments/rate-limit/50_how_to_use.md

@@ -7,6 +7,8 @@ npx create-forgeon@latest add rate-limit
 pnpm install
 ```
 
+This module installs independently. No follow-up integration sync is required.
+
 Verify:
 
 1. start the project

package/templates/module-fragments/rbac/30_what_it_adds.md

@@ -9,3 +9,8 @@
 - a frontend probe button that sends a valid permission header
 
 This module is backend-first. It does not include frontend route guards. If frontend access-control helpers are needed later, they should live in a separate module.
+
+Optional integration:
+
+- `jwt-auth` can extend demo JWT claims with RBAC permissions through `pnpm forgeon:sync-integrations`
+- this module does not require `jwt-auth` to install or work for header-based/manual probe checks

package/templates/module-fragments/rbac/40_how_it_works.md

@@ -18,3 +18,8 @@ Failure path:
 
 - denied access throws `403`
 - the existing Forgeon error envelope wraps it as `FORBIDDEN`
+
+Integration note:
+
+- if `jwt-auth` is also installed, the optional `auth-rbac-claims` integration can expose demo permissions inside JWT payloads
+- that integration is explicit and is applied through `pnpm forgeon:sync-integrations`

package/templates/module-fragments/rbac/50_how_to_use.md

@@ -17,3 +17,8 @@ Manual forbidden-path check:
 
 1. call `GET /api/health/rbac` without the `x-forgeon-permissions` header
 2. the request should return `403`
+
+Optional follow-up:
+
+1. install `jwt-auth` if you want RBAC claims in demo JWT payloads
+2. run `pnpm forgeon:sync-integrations`

package/templates/module-fragments/swagger/10_overview.md

@@ -8,3 +8,7 @@ Included parts:
 - configurable docs path/title/version
 - `setupSwagger(...)` bootstrap helper
 
+Important boundary:
+- this module installs independently
+- it wires only the OpenAPI runtime and bootstrap setup
+- feature-specific Swagger decorators remain manual

package/templates/module-fragments/swagger/20_scope.md

@@ -11,3 +11,7 @@
   - `infra/docker/.env.example`
   - `infra/docker/compose.yml` (api service env passthrough)
 
+Not included:
+
+- no auto-patching of Swagger decorators into feature modules
+- no implicit integration with `jwt-auth` or other add-modules

package/templates/module-fragments/swagger/90_status_implemented.md

@@ -2,3 +2,6 @@
 
 Implemented and applied by `create-forgeon add swagger`.
 
+Notes:
+- install is independent
+- feature-level decorators stay manual by design