@team-codeme/crud-forge 0.0.0-stage → 1.0.1

package/src/generator/ai-docs.js

@@ -0,0 +1,691 @@
+const { entityPath } = require('./entity-layout');
+const path = require('path');
+const { formatLocalTimestamp } = require('./embed-config');
+
+/**
+ * GO-DUCK-style agent entrypoint + docs/ai maps for generated Fuse apps.
+ */
+function applyAiDocsPack({ outputDir, config, parsedData, writeOrPreview }) {
+  const pack = config.output?.aiDocs;
+  if (pack && pack.enabled === false) {
+    return { applied: false, reason: 'output.aiDocs.enabled=false' };
+  }
+
+  const generatedAt = new Date();
+  const projectName = config.project?.name || 'CRUDForge App';
+  const entities = parsedData?.entities || [];
+  const enums = parsedData?.enums || [];
+  const relationships = parsedData?.relationships || [];
+  const written = [];
+
+  const files = {
+    'AGENT_README.md': renderAgentReadme({ projectName, config, entities, enums, relationships, generatedAt }),
+    'docs/ai/README.md': renderDocsIndex({ projectName, generatedAt }),
+    'docs/ai/ARCHITECTURE.md': renderArchitecture({ projectName, config, generatedAt }),
+    'docs/ai/ENTITIES.md': renderEntities({ projectName, entities, enums, relationships, generatedAt }),
+    'docs/ai/ROUTES.md': renderRoutes({ projectName, config, entities, generatedAt }),
+    'docs/ai/UI_CONTRACTS.md': renderUiContracts({ projectName, config, generatedAt }),
+    'docs/ai/PRESERVATION.md': renderPreservation({ projectName, config, generatedAt }),
+    '.crudforge/README.md': renderCrudforgeStateReadme({ generatedAt }),
+  };
+
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(outputDir, rel);
+    writeOrPreview(target, content);
+    written.push(target);
+  }
+
+  // Generator state mirror (like .go-duck/config.yaml) — safe, no secrets.
+  const { formatEmbeddableYaml } = require('./embed-config');
+  const stateYaml = formatEmbeddableYaml(config, generatedAt);
+  const statePath = path.join(outputDir, '.crudforge', 'config.yaml');
+  writeOrPreview(statePath, stateYaml);
+  written.push(statePath);
+
+  return { applied: true, files: written };
+}
+
+function header(title, generatedAt) {
+  return [
+    `# ${title}`,
+    '',
+    `> **Generated by \`@crudforge/cli\`** (\`crudforge generate\`) at ${formatLocalTimestamp(generatedAt)} (\`${generatedAt.toISOString()}\`).`,
+    '> Do not treat this file as hand-authored source — regenerate after schema or config changes.',
+    '',
+  ].join('\n');
+}
+
+function fieldNameOf(field) {
+  return field?.fieldName || field?.name || null;
+}
+
+function fieldTypeOf(field) {
+  return field?.fieldType || field?.type || 'unknown';
+}
+
+function fieldRulesOf(field) {
+  return Array.isArray(field?.fieldValidateRules) ? field.fieldValidateRules : [];
+}
+
+function isRequiredField(field) {
+  return fieldRulesOf(field).some((r) => String(r).toLowerCase() === 'required');
+}
+
+function formatFieldRow(field) {
+  const name = fieldNameOf(field);
+  if (!name) {
+    return null;
+  }
+  const type = fieldTypeOf(field);
+  const rules = fieldRulesOf(field).filter(Boolean);
+  const flags = [];
+  if (isRequiredField(field)) flags.push('required');
+  if (field?.fieldTypeIsEnum) flags.push('enum');
+  if (field?.comment) flags.push(String(field.comment).replace(/\s+/g, ' ').trim());
+  const extras = [
+    flags.length ? flags.join(', ') : null,
+    rules.length ? `rules: ${rules.join(', ')}` : null,
+  ]
+    .filter(Boolean)
+    .join(' · ');
+  return `| \`${name}\` | \`${type}\` | ${extras || '—'} |`;
+}
+
+function relationshipsForEntity(entityName, relationships = []) {
+  const name = String(entityName || '');
+  return (relationships || []).filter(
+    (r) => r?.from?.name === name || r?.to?.name === name || r?.otherEntityName === name
+  );
+}
+
+function formatRelationshipRow(rel, entityName) {
+  if (!rel) return null;
+  if (rel.from?.name || rel.to?.name) {
+    const from = rel.from?.name || '?';
+    const to = rel.to?.name || '?';
+    const fromField = rel.from?.fieldName ? `{${rel.from.fieldName}}` : '';
+    const toField = rel.to?.fieldName ? `{${rel.to.fieldName}}` : '';
+    const arrow = from === entityName ? '→' : '←';
+    const other = from === entityName ? `${to}${toField}` : `${from}${fromField}`;
+    const ownField = from === entityName ? fromField : toField;
+    return `| \`${rel.type || 'rel'}\` | ${arrow} \`${other}\` | ${ownField ? `\`${ownField}\`` : '—'} |`;
+  }
+  const other = rel.otherEntityName || rel.target || '?';
+  return `| \`${rel.type || rel.relationshipType || 'rel'}\` | → \`${other}\` | — |`;
+}
+
+function renderDocsIndex({ projectName, generatedAt }) {
+  return `${header(`AI docs index: ${projectName}`, generatedAt)}
+Maps under \`docs/ai/\` are produced by **\`@crudforge/cli\`** on every generate. Start at [AGENT_README.md](../AGENT_README.md), then open the topic file you need.
+
+| Doc | Purpose |
+|---|---|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Shell, API, auth summary |
+| [ENTITIES.md](ENTITIES.md) | Domain fields, validations, relationships |
+| [ROUTES.md](ROUTES.md) | Admin + IAM + auth routes |
+| [UI_CONTRACTS.md](UI_CONTRACTS.md) | formMode / searchMode / theme / ACL |
+| [PRESERVATION.md](PRESERVATION.md) | Overwrite policy & \`cforge-\` merge zones |
+`;
+}
+
+function renderAgentReadme({ projectName, config, entities = [], enums = [], relationships = [], generatedAt }) {
+  const auth = config.auth || {};
+  const iam = config.iam || {};
+  const ui = config.ui || {};
+  const api = config.api || {};
+  const fuse = config.fuse || {};
+  const mock = config.mock || {};
+  const proxy = config.proxy || {};
+  const project = config.project || {};
+  const keycloakOn = auth.provider === 'keycloak';
+  const iamOn = keycloakOn && iam.enabled !== false;
+
+  const entityRows = (entities || [])
+    .map((e) => {
+      const kebab = toKebab(e.name);
+      const fieldCount = (e.fields || []).filter((f) => fieldNameOf(f)).length;
+      const relCount = relationshipsForEntity(e.name, relationships).length;
+      return `| \`${e.name}\` | \`/admin/${kebab}\` | \`src/app/domains/admin/modules/apps/${entityPath(e, config)}/\` | ${fieldCount} fields, ${relCount} rels |`;
+    })
+    .join('\n');
+
+  const enumList = (enums || [])
+    .map((e) => {
+      const values = (e.values || e.vals || [])
+        .map((v) => (typeof v === 'string' ? v : v.name))
+        .filter(Boolean)
+        .join(', ');
+      return `- \`${e.name}\`${values ? `: ${values}` : ''}`;
+    })
+    .join('\n');
+
+  const serviceEntries = normalizeServiceEntries(api.services);
+  const serviceRows = serviceEntries
+    .map((s) => `| \`${s.name}\` | \`${s.proxyPath}\` | \`${s.prodTarget || s.devTarget || ''}\` |`)
+    .join('\n');
+
+  const authBlock = keycloakOn
+    ? `## 7. Auth & IAM (Keycloak overlay)
+
+**Do not** model User or Role as JDL entities. Identity is an overlay.
+
+| Setting | Value |
+|---|---|
+| provider | \`${auth.provider}\` |
+| realm | \`${auth.realm || ''}\` |
+| clientId | \`${auth.clientId || ''}\` |
+| useMockAuth | \`${!!auth.useMockAuth}\` |
+| serverUrl | \`${auth.serverUrl || '(empty — mock or relative proxy)'}\` |
+| forwardedProto | \`${auth.forwardedProto || ''}\` |
+| adminServiceUrl | \`${auth.provision?.adminServiceUrl || ''}\` |
+| IAM enabled | \`${!!iamOn}\` |
+
+### Auth pack — \`src/app/core/auth/\`
+
+See [\`src/app/core/auth/AGENT_README.md\`](src/app/core/auth/AGENT_README.md).
+
+| Folder | Responsibility |
+|---|---|
+| \`services/\` | \`AuthService\`, \`AccessControlService\`, \`KeycloakAdminService\` |
+| \`guards/\` | \`AuthGuard\`, \`NoAuthGuard\`, \`LandingGuard\` |
+| \`interceptors/\` | Bearer + refresh + \`X-Forwarded-Proto\` |
+| \`pipes/\` / \`directives/\` | \`accessCtrl\`, \`hasPermission\` |
+| \`utils/\` | JWT + permission attribute helpers |
+| \`index.ts\` | Public barrel — prefer \`import { … } from '@/app/core/auth'\` |
+
+### User Management — \`src/app/core/user-management/\`
+
+${iamOn
+    ? `See [\`src/app/core/user-management/AGENT_README.md\`](src/app/core/user-management/AGENT_README.md).
+
+| Area | Path | Route |
+|---|---|---|
+| Users | \`users/\` | \`/admin/user-management\` |
+| Roles | \`roles/\` | \`/admin/user-management/roles\` |
+| Matrices | \`matrices/\` | \`/admin/user-management/role-permissions\`, \`…/:id/access\`, \`…/:id/permissions\` |
+
+Components use separate \`.component.ts\` + \`.component.html\` files (\`templateUrl\`).`
+    : '_IAM overlay is off for this generate (`iam.enabled` false or auth not keycloak)._'}
+
+### Auth UI routes
+
+| Screen | Route |
+|---|---|
+| Sign in | \`/auth/sign-in\` |
+| No access | \`/admin/no-access\` |
+`
+    : `## 7. Auth & IAM
+
+\`auth.provider\` is \`${auth.provider || 'none'}\`. No Keycloak pack was generated.
+Turn on with \`auth.provider: keycloak\` (+ optional \`iam.enabled\`) and regenerate.
+`;
+
+  return `${header(`LLM / AI agent instructions: ${projectName}`, generatedAt)}
+This is the **primary orientation document** for agents and developers working in this generated Fuse app.
+Read **top to bottom** once, then use \`docs/ai/*\` and pack-level \`AGENT_README.md\` files for depth.
+
+---
+
+## 1. What this app is
+
+| | |
+|---|---|
+| **Product / project** | ${projectName} |
+| **Description** | ${project.description || '_n/a_'} |
+| **Generator** | CRUDForge (Angular Fuse admin CRUD + optional Keycloak/IAM) |
+| **Repository URL** | ${project.repositoryUrl || '_not set_'} |
+| **Generated at** | ${formatLocalTimestamp(generatedAt)} |
+
+CRUDForge produces a Fuse Angular admin shell, entity CRUD modules from JDL/GDL, shared UI primitives, optional Keycloak auth, and optional User Management (IAM) screens.
+Treat **config + routes + entities + auth/IAM + UI contracts** as one coordinated system.
+
+---
+
+## 2. How to run
+
+\`\`\`bash
+npm install
+npm start                 # ng serve (uses proxy.dev.conf.json in development)
+npm run build             # production build when configured
+\`\`\`
+
+Proxies:
+
+| File | When |
+|---|---|
+| \`proxy.dev.conf.json\` | Dev / mock serve (\`proxy.write\` includes \`dev\`/\`both\`) |
+| \`proxy.conf.json\` | Prod-oriented serve (\`proxy.write\` includes \`prod\`/\`both\`) |
+
+Current \`proxy.write\`: \`${proxy.write || 'both'}\`.
+
+From the **CRUDForge generator repo** (not this app folder):
+
+\`\`\`bash
+./test-run.sh mock        # verify + CRUD e2e + mock IAM
+./test-run.sh live        # Keycloak bootstrap + live Playwright
+\`\`\`
+
+---
+
+## 3. Source of truth (do this before hand-editing)
+
+1. **Domain schema** — original JDL/GDL used at generate time (re-run CRUDForge after changes).
+2. **App preferences** — [\`config/crudforge.config.yml\`](config/crudforge.config.yml) (readable, dated).
+3. **Generator state mirror** — [\`.crudforge/config.yaml\`](.crudforge/config.yaml) (no secrets).
+4. **Browser runtime** — \`src/environments/environment*.ts\` (Keycloak public fields + \`apiUrl\` / \`services\`; **never** provision passwords or \`clientSecret\`).
+5. **Secrets** — local \`.env\` / generator \`.env.qa\` only. \`generate\` must not mutate a remote Keycloak realm; use \`crudforge bootstrap\` for that.
+
+Overwrite policy: \`${config.output?.overwritePolicy || 'overwrite'}\`. Preserve \`// cforge-\` merge zones.
+
+---
+
+## 4. Repository map (top → bottom)
+
+\`\`\`text
+.
+├── AGENT_README.md                 ← you are here (full orientation)
+├── config/crudforge.config.yml     ← canonical preferences
+├── .crudforge/                     ← generator state (+ optional provision-state)
+├── docs/ai/                        ← deep blueprints (architecture, entities, routes, UI, preservation)
+├── proxy.conf.json / proxy.dev.conf.json
+├── src/
+│   ├── environments/               ← browser env (apiUrl, Keycloak public fields, services)
+│   ├── app/
+│   │   ├── app.ts / app.config.ts  ← theming + HTTP interceptors
+│   │   ├── core/
+│   │   │   ├── auth/               ← Keycloak pack (+ AGENT_README.md) when enabled
+│   │   │   ├── user-management/    ← IAM UI (+ AGENT_README.md) when enabled
+│   │   │   ├── theming/ media/ icons/ …
+│   │   └── domains/
+│   │       ├── auth/features/sign-in/
+│   │       └── admin/              ← layout, routes, entity modules, extras
+│   │           └── modules/apps/shared/access-control-tools/  ← RBAC/QA id sync (+ README)
+│   └── …
+└── .cursor/agents/ · .codex/agents/ · .agents/  ← optional keep-team agents
+\`\`\`
+
+---
+
+## 5. Domain entities (this generate)
+
+| Entity | Admin route | Module folder | Size |
+|---|---|---|---|
+${entityRows || '| — | — | — | — |'}
+
+### Enums
+
+${enumList || '_No enums in this generate._'}
+
+Each entity module typically contains: model, service, routes, list/card/detail, filter, actions, form + form-page, settings.
+Shared primitives (confirm dialogs, loading overlay, base list/form/filter, snackbar CSS) live under \`modules/apps/shared/\` when the shared-central pack is used.
+
+Deep field/relationship detail: [docs/ai/ENTITIES.md](docs/ai/ENTITIES.md).
+
+---
+
+## 6. API & backend services
+
+| Setting | Value |
+|---|---|
+| api.baseUrl | \`${api.baseUrl || '/api'}\` |
+| api.microservice | \`${api.microservice || ''}\` |
+| endpointStyle | \`${api.endpointStyle || 'kebab-plural'}\` |
+| dateLibrary | \`${api.dateLibrary || 'dayjs'}\` |
+| mock data | enabled=${!!mock.enabled}, recordsPerEntity=${mock.recordsPerEntity ?? 'n/a'} |
+
+Entity HTTP paths generally look like:
+
+\`/services/{microservice}/api/{kebab-plural-entity}\`
+
+### \`api.services\` → environment + proxy
+
+Browser code should call **relative** \`/services/{name}\` paths. Absolute origins belong only in proxy JSON.
+
+| Service key | Browser path | Target (prod or shared) |
+|---|---|---|
+${serviceRows || '| _(none configured)_ | | |'}
+
+---
+
+${authBlock}
+---
+
+## 8. UI contracts (non-negotiable)
+
+| Contract | Active value | Rule |
+|---|---|---|
+| formMode | \`${ui.formMode || 'sidebar'}\` | **New and edit share the same mode.** Sidebar → drawer (\`mat-drawer\` / \`.cforge-form-drawer\`). Page → \`/new\` and \`/:id/edit\`. Never leave edit on a full page while new uses the drawer. |
+| searchMode | \`${ui.searchMode || 'field'}\` | \`field\` = per-field \`contains\`. \`global\` only if the API accepts \`query\`. |
+| viewMode | \`${ui.viewMode || 'table'}\` | Table/card; breakpoint \`${ui.cardBreakpointPx ?? 640}px\`. |
+| Theme | scheme \`${fuse.theme?.scheme || 'system'}\`, primary \`${fuse.theme?.primary || ''}\` | Change colors only via root \`fuseTheme\` in \`app.ts\` / \`fuse.theme\` — never hardcode entity primary colors. |
+| ACL stamps | \`data-screen-id\` / \`data-component-id\` + \`accessCtrl\` | Hidden UI is not authorization. |
+
+Clean layout: \`${!!fuse.cleanLayout}\`.
+
+More: [docs/ai/UI_CONTRACTS.md](docs/ai/UI_CONTRACTS.md).
+
+---
+
+## 9. Routing & navigation
+
+- Admin shell: \`src/app/domains/admin/routes.ts\` (+ \`AuthGuard\` / \`LandingGuard\` when Keycloak is on).
+- Navigation data: \`src/app/domains/admin/layout/data/navigation.ts\` (filtered by ACL when auth is on).
+- Entity children register under \`// cforge-routes-start\` / \`// cforge-navigation-start\` needles when present.
+
+Full table: [docs/ai/ROUTES.md](docs/ai/ROUTES.md).
+
+---
+
+## 10. Safe evolution workflow
+
+1. Change **JDL/GDL + \`config/crudforge.config.yml\`**, then re-run CRUDForge generate into this app folder.
+2. Hand-edit only inside \`// cforge-\` merge zones, or own files outside generated entity trees.
+3. Never commit secrets into config, environments, screenshots, or fixtures.
+4. After regenerate: \`npm start\` / build, then Playwright (\`test:e2e\`, \`test:e2e:iam\`, or live suite).
+5. Realm mutations: \`crudforge bootstrap --env-file .env\` only — not during \`generate\`.
+
+Preservation details: [docs/ai/PRESERVATION.md](docs/ai/PRESERVATION.md).
+
+---
+
+## 11. Doc index (read before large edits)
+
+| Doc | Purpose |
+|---|---|
+| [AGENT_README.md](AGENT_README.md) | **This file** — full top-to-bottom orientation |
+| [docs/ai/ARCHITECTURE.md](docs/ai/ARCHITECTURE.md) | Shell, API, auth summary, layout |
+| [docs/ai/README.md](docs/ai/README.md) | Index of AI maps |
+| [docs/ai/ENTITIES.md](docs/ai/ENTITIES.md) | Fields, validations & relationships |
+| [docs/ai/ROUTES.md](docs/ai/ROUTES.md) | Admin + IAM + auth routes |
+| [docs/ai/UI_CONTRACTS.md](docs/ai/UI_CONTRACTS.md) | formMode / searchMode / ACL / theme |
+| [docs/ai/PRESERVATION.md](docs/ai/PRESERVATION.md) | Overwrite policy & merge zones |
+| [src/app/core/auth/AGENT_README.md](src/app/core/auth/AGENT_README.md) | Auth pack internals (when Keycloak on) |
+| [src/app/core/user-management/AGENT_README.md](src/app/core/user-management/AGENT_README.md) | IAM UI internals (when IAM on) |
+| [src/app/domains/admin/modules/apps/shared/access-control-tools/AGENT_README.md](src/app/domains/admin/modules/apps/shared/access-control-tools/AGENT_README.md) | RBAC / QA id sync for custom pages |
+| [config/crudforge.config.yml](config/crudforge.config.yml) | Canonical preferences |
+| [.crudforge/README.md](.crudforge/README.md) | Generator state folder |
+
+Optional keep-team IDE agents may also exist under \`.cursor/agents/\`, \`.codex/agents/\`, and Antigravity \`.agents/\`.
+`;
+}
+
+function toKebab(name) {
+  return String(name || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+function normalizeServiceEntries(services) {
+  if (!services || typeof services !== 'object' || Array.isArray(services)) {
+    return [];
+  }
+  return Object.entries(services)
+    .map(([name, value]) => {
+      const key = String(name || '').trim();
+      if (!key) return null;
+      const proxyPath = `/services/${key}`;
+      if (typeof value === 'string') {
+        const target = value.trim().replace(/\/+$/, '');
+        return target ? { name: key, proxyPath, prodTarget: target, devTarget: target } : null;
+      }
+      if (!value || typeof value !== 'object') return null;
+      const prodTarget = String(value.prod || value.target || value.url || '').trim().replace(/\/+$/, '');
+      const devTarget = String(value.dev || value.target || value.url || prodTarget).trim().replace(/\/+$/, '');
+      if (!prodTarget && !devTarget) return null;
+      return { name: key, proxyPath, prodTarget: prodTarget || devTarget, devTarget: devTarget || prodTarget };
+    })
+    .filter(Boolean);
+}
+
+function renderArchitecture({ projectName, config, generatedAt }) {
+  const fuse = config.fuse || {};
+  const api = config.api || {};
+  const auth = config.auth || {};
+  const iam = config.iam || {};
+  return `${header(`Architecture: ${projectName}`, generatedAt)}
+## Shell
+
+- **UI kit**: Fuse Angular (\`fuse.enabled: ${!!fuse.enabled}\`)
+- **Clean layout**: ${!!fuse.cleanLayout}
+- **Theme**: scheme \`${fuse.theme?.scheme || 'system'}\`, primary \`${fuse.theme?.primary || ''}\`, error \`${fuse.theme?.error || ''}\`
+
+## API
+
+- **baseUrl**: \`${api.baseUrl || '/api'}\`
+- **microservice**: \`${api.microservice || ''}\`
+- **endpointStyle**: \`${api.endpointStyle || 'kebab-plural'}\`
+- **dateLibrary**: \`${api.dateLibrary || 'dayjs'}\`
+
+## Auth & IAM
+
+- **provider**: \`${auth.provider || 'none'}\`
+- **useMockAuth**: ${!!auth.useMockAuth}
+- **realm / clientId**: \`${auth.realm || ''}\` / \`${auth.clientId || ''}\`
+- **IAM overlay**: ${!!iam.enabled} (users=${iam.users !== false}, roles=${iam.roles !== false})
+- **IAM code**: \`src/app/core/user-management/\` (see that folder's \`AGENT_README.md\`)
+- **Auth code**: \`src/app/core/auth/\` (services / guards / interceptors — see \`AGENT_README.md\`)
+- **Access-control tools**: \`modules/apps/shared/access-control-tools/\` (\`npm run access-control:sync\`)
+
+## Configuration locations
+
+| Path | Role |
+|---|---|
+| \`config/crudforge.config.yml\` | Canonical app preferences (readable, dated) |
+| \`.crudforge/config.yaml\` | Generator state mirror (incremental regen) |
+| \`src/environments/environment*.ts\` | Browser runtime (no provision secrets) |
+
+## Layout map (Fuse)
+
+\`\`\`text
+src/app/
+  core/auth/          # Keycloak auth pack when enabled
+  domains/admin/      # layout, routes, entity modules, IAM screens
+  domains/auth/       # sign-in
+\`\`\`
+`;
+}
+
+function renderEntities({ projectName, entities, enums, relationships = [], generatedAt }) {
+  const entityBlocks = (entities || [])
+    .map((entity) => {
+      const fieldRows = (entity.fields || []).map(formatFieldRow).filter(Boolean);
+      const entityRels = relationshipsForEntity(entity.name, relationships);
+      const relRows = entityRels.map((r) => formatRelationshipRow(r, entity.name)).filter(Boolean);
+      const annotations = [
+        entity.searchable ? '`@Searchable`' : null,
+        entity.activeStatus ? '`@ActiveStatus`' : null,
+        entity.audited ? '`@Audited` / `@EnableAudit`' : null,
+      ].filter(Boolean);
+
+      const fieldsTable = fieldRows.length
+        ? `| Field | Type | Notes |\n|---|---|---|\n${fieldRows.join('\n')}`
+        : '_No fields._';
+      const relsTable = relRows.length
+        ? `| Kind | Other side | Local field |\n|---|---|---|\n${relRows.join('\n')}`
+        : '_No relationships involving this entity._';
+
+      return [
+        `### \`${entity.name}\``,
+        '',
+        annotations.length ? `Annotations: ${annotations.join(', ')}` : null,
+        annotations.length ? '' : null,
+        '**Fields**',
+        '',
+        fieldsTable,
+        '',
+        '**Relationships**',
+        '',
+        relsTable,
+        '',
+      ]
+        .filter((line) => line !== null)
+        .join('\n');
+    })
+    .join('\n');
+
+  const enumBlocks = (enums || [])
+    .map((e) => {
+      const values = (e.values || e.vals || [])
+        .map((v) => {
+          const name = typeof v === 'string' ? v : v?.name;
+          return name ? `| \`${name}\` |` : null;
+        })
+        .filter(Boolean);
+      const table = values.length ? `| Value |\n|---|\n${values.join('\n')}` : '_No values._';
+      return `### Enum \`${e.name}\`\n\n${table}\n`;
+    })
+    .join('\n');
+
+  const relSummary = (relationships || [])
+    .map((r) => {
+      if (r?.from?.name && r?.to?.name) {
+        const fromField = r.from.fieldName ? `{${r.from.fieldName}}` : '';
+        const toField = r.to.fieldName ? `{${r.to.fieldName}}` : '';
+        return `| \`${r.type || 'rel'}\` | \`${r.from.name}${fromField}\` | \`${r.to.name}${toField}\` |`;
+      }
+      return null;
+    })
+    .filter(Boolean);
+
+  return `${header(`Entities: ${projectName}`, generatedAt)}
+Derived from the JDL/GDL blueprint used at generate time. Field names come from parser \`fieldName\` / \`fieldType\` (not hand-authored). Re-run \`crudforge generate\` after schema changes.
+
+## Summary
+
+| | Count |
+|---|---|
+| Entities | ${(entities || []).length} |
+| Enums | ${(enums || []).length} |
+| Relationships | ${(relationships || []).length} |
+
+## Domain entities
+
+${entityBlocks || '_No entities in this generate run._'}
+
+## Relationship index
+
+${
+  relSummary.length
+    ? `| Kind | From | To |\n|---|---|---|\n${relSummary.join('\n')}`
+    : '_No relationship blocks in this generate run._'
+}
+
+## Enums
+
+${enumBlocks || '_No enums in this generate run._'}
+`;
+}
+
+function renderRoutes({ projectName, config, entities, generatedAt }) {
+  const rows = (entities || [])
+    .map((e) => {
+      const kebab = String(e.name || '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase();
+      return `| ${e.name} | \`/admin/${kebab}\` | \`modules/apps/${entityPath(e, config)}/\` |`;
+    })
+    .join('\n');
+
+  const iam = config.iam?.enabled
+    ? `| User Management | \`/admin/user-management\` | IAM overlay |\n| Roles | \`/admin/user-management/roles\` | IAM overlay |\n| Role permissions | \`/admin/user-management/role-permissions\` | IAM overlay |`
+    : '';
+
+  return `${header(`Routes & navigation: ${projectName}`, generatedAt)}
+Admin shell uses \`AuthGuard\` when Keycloak auth is enabled. Landing uses \`LandingGuard\` (first allowed screen or \`/admin/no-access\`).
+
+## Entity routes
+
+| Entity | Route | Module folder |
+|---|---|---|
+${rows || '| — | — | — |'}
+${iam ? `\n## IAM routes\n\n| Screen | Route | Notes |\n|---|---|---|\n${iam}\n` : ''}
+## Auth routes
+
+| Screen | Route |
+|---|---|
+| Sign in | \`/auth/sign-in\` |
+`;
+}
+
+function renderUiContracts({ projectName, config, generatedAt }) {
+  const ui = config.ui || {};
+  return `${header(`UI contracts: ${projectName}`, generatedAt)}
+## Form mode
+
+- **Active**: \`${ui.formMode || 'sidebar'}\`
+- **Rule**: New and Edit must behave the same. Sidebar → \`mat-drawer\` / \`.cforge-form-drawer\`. Page → \`/new\` and \`/:id/edit\`.
+
+## Search mode
+
+- **Active**: \`${ui.searchMode || 'field'}\`
+- **field**: per-field contains controls (JHipster-style).
+- **global**: single query box only when the backend accepts \`query\`.
+
+## View mode
+
+- **Default**: \`${ui.viewMode || 'table'}\`
+- Card breakpoint: \`${ui.cardBreakpointPx ?? 640}px\`
+
+## Access control stamps
+
+Entity actions should carry \`data-screen-id\` / \`data-component-id\` and \`accessCtrl\` pipes so ACL can hide/disable controls. Hidden UI alone is not authorization.
+
+- **SCREEN** / \`data-screen-id\`: \`{folder}/{entity}\` (nav-aligned), e.g. \`micro-functions/book\`
+- **componentId** (semantic): \`create\`, \`open-filter\`, \`toggle-view\`, \`open-columns\`, \`view\`, \`edit\`, \`delete\`, …
+- Custom pages: run \`npm run access-control:sync\` / \`access-control:apply\` from \`modules/apps/shared/access-control-tools/\` (see that folder's README + AGENT docs)
+
+## Theme
+
+Change colors only via root \`fuseTheme\` / \`fuse.theme\` — never scatter hardcoded primary colors in entity templates.
+`;
+}
+
+function renderPreservation({ projectName, config, generatedAt }) {
+  const policy = config.output?.overwritePolicy || 'overwrite';
+  return `${header(`Preservation & overwrite: ${projectName}`, generatedAt)}
+## Overwrite policy
+
+Current policy: \`${policy}\`.
+
+| Policy | Behavior |
+|---|---|
+| overwrite | Replace generated files |
+| skip | Keep existing file |
+| fail | Abort on conflict |
+| ask | Interactive resolution |
+| merge | Preserve \`// cforge-\` custom zones |
+
+## Merge zones
+
+Custom code belongs inside \`// cforge-*\` / \`// cforge-*-end\` markers. Do not delete those needles. Prefer merge policy when hand-editing generated files.
+
+## Do not hand-edit as source of truth
+
+- Large entity trees under \`modules/apps/**\` — prefer JDL + regenerate
+- Auth pack templates — edit generator \`src/templates/angular/auth\`
+- Embedded config — edit \`config/crudforge.config.yml\` then regenerate if needed
+
+## Generator state
+
+\`.crudforge/config.yaml\` mirrors the last generate preferences (no secrets). Provision tracking files under \`.crudforge/provision-state.json\` are local/CI only and should stay gitignored.
+`;
+}
+
+function renderCrudforgeStateReadme({ generatedAt }) {
+  return `${header('CRUDForge generator state', generatedAt)}
+This folder is the Fuse equivalent of GO-DUCK's \`.go-duck/\` directory.
+
+| File | Purpose |
+|---|---|
+| \`config.yaml\` | Last generate preferences (safe mirror of \`config/crudforge.config.yml\`) |
+| \`provision-state.json\` | Optional bootstrap tracking (gitignored) — only resources CRUDForge created |
+
+Do not put passwords here.
+`;
+}
+
+module.exports = {
+  applyAiDocsPack,
+};