docguard-cli 0.28.0 → 0.30.0

package/cli/writers/doc-generators.mjs

@@ -0,0 +1,853 @@
+/**
+ * Document Generators — the seven doc emitters behind `docguard generate`:
+ * ARCHITECTURE, API-REFERENCE, DATA-MODEL, ENVIRONMENT, TEST-SPEC, SECURITY,
+ * plus the root files (AGENTS.md, CHANGELOG.md, DRIFT-LOG.md).
+ *
+ * v0.29 split: extracted verbatim from cli/commands/generate.mjs — pure code
+ * motion, zero behavior change.
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve, basename, extname } from 'node:path';
+import { c } from '../shared.mjs';
+import { generateERDiagram } from '../scanners/schemas.mjs';
+import { safeWrite, appendStandardsCitation } from './generate-io.mjs';
+
+// ── Document Generators ────────────────────────────────────────────────────
+
+export function generateArchitecture(dir, config, stack, scan, flags, docTools) {
+  const path = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
+  if (existsSync(path) && !flags.force) {
+    console.log(`  ${c.dim}⏭️  ARCHITECTURE.md (exists)${c.reset}`);
+    return false;
+  }
+
+  const techRows = Object.entries(stack)
+    .filter(([, v]) => v)
+    .map(([k, v]) => `| ${k.charAt(0).toUpperCase() + k.slice(1)} | ${v} | | |`)
+    .join('\n');
+
+  const componentRows = [];
+  if (scan.routes.length > 0) componentRows.push(`| API Routes | HTTP request handling | ${scan.routes.length > 3 ? scan.routes.slice(0, 3).join(', ') + '...' : scan.routes.join(', ')} | |`);
+  if (scan.services.length > 0) componentRows.push(`| Services | Business logic | ${scan.services.length > 3 ? scan.services.slice(0, 3).join(', ') + '...' : scan.services.join(', ')} | |`);
+  if (scan.models.length > 0) componentRows.push(`| Models | Data entities | ${scan.models.length > 3 ? scan.models.slice(0, 3).join(', ') + '...' : scan.models.join(', ')} | |`);
+  if (scan.components.length > 0) componentRows.push(`| UI Components | Frontend components | ${scan.components.length} files | |`);
+  if (scan.middlewares.length > 0) componentRows.push(`| Middleware | Request processing | ${scan.middlewares.join(', ')} | |`);
+
+  // Storybook integration
+  if (docTools?.storybook?.found) {
+    componentRows.push(`| Storybook | UI component docs | .storybook/ (${docTools.storybook.storyCount || '?'} stories) | |`);
+  }
+
+  // Doc tools section — always include DocGuard since it generated these docs
+  const docToolRows = ['| DocGuard | `.docguard.json` | Active |'];
+  if (docTools?._detected?.length > 0) {
+    for (const tool of docTools._detected) {
+      const info = docTools[tool];
+      docToolRows.push(`| ${tool} | ${info.config || info.path || info.middleware || 'detected'} | Active |`);
+    }
+  }
+
+  const content = `# Architecture
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed ${new Date().toISOString().split('T')[0]} -->
+<!-- docguard:generated true -->
+<!-- docguard:standards arc42, C4 -->
+
+> **Auto-generated by DocGuard.** Review and refine this document.
+> Follows [arc42](https://arc42.org) structure and [C4 Model](https://c4model.com) diagrams.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+| **Version** | \`0.1.0\` |
+| **Last Updated** | ${new Date().toISOString().split('T')[0]} |
+| **Project Size** | ${scan.totalFiles} files, ~${Math.round(scan.totalLines / 1000)}K lines |
+
+---
+
+## 1. Introduction & Goals
+<!-- arc42: §1 — Introduction and Goals -->
+
+<!-- TBD: Describe what this system does, who it's for, and key quality goals -->
+${config.projectName} is a ${stack.framework || stack.language || 'software'} application.
+
+### Quality Goals
+
+| Priority | Quality Goal | Scenario |
+|----------|-------------|----------|
+| 1 | <!-- e.g. Performance --> | <!-- e.g. Response time < 200ms --> |
+| 2 | <!-- e.g. Security --> | <!-- e.g. All endpoints authenticated --> |
+| 3 | <!-- e.g. Maintainability --> | <!-- e.g. New feature in < 1 day --> |
+
+## 2. Constraints
+<!-- arc42: §2 — Constraints -->
+
+| Type | Constraint | Background |
+|------|-----------|------------|
+| Technical | ${stack.language || 'TBD'} | Primary language |
+| Technical | ${stack.framework || 'TBD'} | Framework |
+| Infrastructure | ${stack.hosting || 'TBD'} | Hosting provider |
+
+## 3. Context & Scope
+<!-- arc42: §3 — Context and Scope (C4 Level 1: System Context) -->
+
+\\\`\\\`\\\`mermaid
+graph TD
+    U[Users/Clients] --> S[${config.projectName}]
+    S --> DB[(${stack.database || 'Database'})]
+    S --> EXT[External Services]
+\\\`\\\`\\\`
+
+## 4. Solution Strategy
+<!-- arc42: §4 — Solution Strategy -->
+
+See \\\`docs-canonical/ADR.md\\\` for architecture decision records.
+
+## 5. Building Block View
+<!-- arc42: §5 — Building Block View (C4 Level 2: Container) -->
+
+| Component | Responsibility | Location | Tests |
+|-----------|---------------|----------|-------|
+${componentRows.join('\\n') || '| <!-- Add components --> | | | |'}
+
+\\\`\\\`\\\`mermaid
+graph TD
+    A[Client] --> B[${stack.framework || 'API'}]
+    B --> C[Services]
+    C --> D[${stack.database || 'Database'}]
+    ${scan.middlewares.length > 0 ? 'A --> M[Middleware] --> B' : ''}
+    ${scan.components.length > 0 ? 'A --> UI[UI Components]' : ''}
+\\\`\\\`\\\`
+
+## 6. Runtime View
+<!-- arc42: §6 — Runtime View -->
+
+\\\`\\\`\\\`mermaid
+sequenceDiagram
+    participant C as Client
+    participant A as ${stack.framework || 'API'}
+    participant S as Service
+    participant D as ${stack.database || 'DB'}
+    C->>A: Request
+    A->>S: Process
+    S->>D: Query
+    D-->>S: Result
+    S-->>A: Response
+    A-->>C: JSON
+\\\`\\\`\\\`
+
+## 7. Deployment View
+<!-- arc42: §7 — Deployment View -->
+
+See \\\`docs-canonical/DEPLOYMENT.md\\\` for details.
+
+| Environment | Infrastructure | URL |
+|-------------|---------------|-----|
+| Development | localhost | http://localhost:3000 |
+| Staging | ${stack.hosting || 'TBD'} | <!-- TBD --> |
+| Production | ${stack.hosting || 'TBD'} | <!-- TBD --> |
+
+## 8. Crosscutting Concepts
+<!-- arc42: §8 — Crosscutting Concepts -->
+
+### Tech Stack
+
+| Category | Technology | Version | License |
+|----------|-----------|---------|---------|
+${techRows || '| <!-- Add technologies --> | | | |'}
+${docToolRows.length > 0 ? `
+### Documentation Tools
+
+| Tool | Config | Status |
+|------|--------|--------|
+${docToolRows.join('\\n')}
+` : ''}
+
+### Layer Boundaries
+
+| Layer | Can Import From | Cannot Import From |
+|-------|----------------|-------------------|
+${scan.routes.length > 0 ? '| Routes/Handlers | Services, Middleware | Models (direct) |' : ''}
+${scan.services.length > 0 ? '| Services | Repositories, Utils | Routes |' : ''}
+${scan.models.length > 0 ? '| Models/Repositories | Utils | Services, Routes |' : ''}
+
+## 9. Architecture Decisions
+<!-- arc42: §9 — Architecture Decisions -->
+
+See \\\`docs-canonical/ADR.md\\\` for the full decision log.
+
+## 10. Quality Requirements
+<!-- arc42: §10 — Quality Requirements -->
+
+See \\\`docs-canonical/TEST-SPEC.md\\\` for test requirements and coverage targets.
+
+## 11. Risks & Technical Debt
+<!-- arc42: §11 — Risk Assessment and Technical Debt -->
+
+See \\\`DRIFT-LOG.md\\\` for documented deviations from canonical specs.
+See \\\`docs-canonical/KNOWN-GOTCHAS.md\\\` for known issues.
+
+## 12. Glossary
+<!-- arc42: §12 — Glossary -->
+
+| Term | Definition |
+|------|-----------|
+| CDD | Canonical-Driven Development — documentation as the source of truth |
+| Canonical Doc | A specification document that defines system behavior |
+| Drift | Conscious deviation from canonical documentation |
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (arc42 + C4 aligned) |
+`;
+
+  safeWrite(path, appendStandardsCitation(content, 'ARCHITECTURE.md'), 'utf-8');
+  console.log(`  ${c.green}✅ ARCHITECTURE.md${c.reset} (arc42 §1-§12, ${componentRows.length} components, ${Object.values(stack).filter(Boolean).length} tech)`);
+  return true;
+}
+
+// ── API Reference Generator (NEW — from deep route scanning) ───────────────
+
+export function generateApiReference(dir, config, stack, deepRoutes, flags) {
+  const path = resolve(dir, 'docs-canonical/API-REFERENCE.md');
+  if (existsSync(path) && !flags.force) {
+    console.log(`  ${c.dim}⏭️  API-REFERENCE.md (exists)${c.reset}`);
+    return false;
+  }
+
+  // Group routes by resource (first path segment after /api/)
+  const groups = {};
+  for (const route of deepRoutes) {
+    const parts = route.path.split('/').filter(Boolean);
+    const resource = parts[1] || parts[0] || 'root';
+    if (!groups[resource]) groups[resource] = [];
+    groups[resource].push(route);
+  }
+
+  // Build endpoint table
+  const endpointRows = deepRoutes
+    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+    .map(r => `| \`${r.method}\` | \`${r.path}\` | ${r.handler || '—'} | ${r.auth ? '🔒' : '🔓'} | ${r.description || '—'} |`)
+    .join('\n');
+
+  // Build per-resource sections
+  const resourceSections = Object.entries(groups)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([resource, routes]) => {
+      const routeDetails = routes.map(r => `#### ${r.method} \`${r.path}\`
+
+> Source: \`${r.file}\`${r.source ? ` (${r.source})` : ''}
+
+- **Auth:** ${r.auth ? 'Required' : 'None'}
+- **Handler:** ${r.handler || '—'}
+${r.description ? `- **Description:** ${r.description}` : ''}
+
+| Parameter | In | Type | Required | Description |
+|-----------|-----|------|:--------:|-------------|
+| <!-- TBD --> | | | | |
+
+| Status | Response |
+|--------|----------|
+| 200 | Success |
+| 400 | Bad Request |
+| 401 | Unauthorized |
+`).join('\n');
+
+      return `### ${resource.charAt(0).toUpperCase() + resource.slice(1)}
+
+${routeDetails}`;
+    }).join('\n---\n\n');
+
+  const content = `# API Reference
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed ${new Date().toISOString().split('T')[0]} -->
+<!-- docguard:generated true -->
+
+> **Auto-generated by DocGuard.** Review and refine this document.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+| **Base URL** | \`http://localhost:3000\` |
+| **Auth** | <!-- TBD: Describe auth mechanism --> |
+| **Total Endpoints** | ${deepRoutes.length} |
+| **Source** | ${deepRoutes[0]?.source || 'code scan'} |
+
+---
+
+## Endpoints Summary
+
+| Method | Path | Handler | Auth | Description |
+|--------|------|---------|:----:|-------------|
+${endpointRows}
+
+---
+
+## Endpoint Details
+
+${resourceSections}
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${deepRoutes.length} endpoints from ${deepRoutes[0]?.source || 'code'}) |
+`;
+
+  safeWrite(path, appendStandardsCitation(content, 'API-REFERENCE.md'), 'utf-8');
+  console.log(`  ${c.green}✅ API-REFERENCE.md${c.reset} (${deepRoutes.length} endpoints, ${Object.keys(groups).length} resources)`);
+  return true;
+}
+
+// ── Enhanced Data Model Generator ──────────────────────────────────────────
+
+export function generateDataModel(dir, config, stack, scan, flags, deepSchemas) {
+  const path = resolve(dir, 'docs-canonical/DATA-MODEL.md');
+  if (existsSync(path) && !flags.force) {
+    console.log(`  ${c.dim}⏭️  DATA-MODEL.md (exists)${c.reset}`);
+    return false;
+  }
+
+  // Use deep schemas if available, fallback to basic scan
+  let entities = [];
+  let relationships = [];
+  let schemaSource = 'file scan';
+
+  if (deepSchemas && deepSchemas.entities.length > 0) {
+    entities = deepSchemas.entities;
+    relationships = deepSchemas.relationships;
+    schemaSource = deepSchemas.source;
+  } else {
+    // Fallback: basic entity detection from file names
+    for (const modelFile of scan.models) {
+      const name = basename(modelFile, extname(modelFile));
+      if (name !== 'index' && name !== 'schema') {
+        entities.push({
+          name: name.charAt(0).toUpperCase() + name.slice(1),
+          fields: [],
+          file: modelFile,
+          source: 'file',
+        });
+      }
+    }
+  }
+
+  // Build entity summary table
+  const entityRows = entities
+    .filter(e => e.source !== 'prisma-enum')
+    .map(e => {
+      const pk = e.fields?.find(f => f.primaryKey);
+      return `| ${e.name} | ${stack.database || 'TBD'} | ${pk ? pk.name : e.name.toLowerCase() + 'Id'} | ${e.file || '—'} | ${e.fields?.length || 0} fields |`;
+    }).join('\n');
+
+  // Build detailed entity sections
+  const entitySections = entities
+    .filter(e => e.source !== 'prisma-enum')
+    .map(e => {
+      if (!e.fields || e.fields.length === 0) {
+        return `### ${e.name}
+
+> Source: \`${e.file || 'unknown'}\`
+
+| Field | Type | Required | Default | Constraints | Description |
+|-------|------|----------|---------|-------------|-------------|
+| <!-- TBD: Fill in fields --> | | | | | |
+`;
+      }
+      const fieldRows = e.fields.map(f =>
+        `| ${f.name} | ${f.type} | ${f.required ? '✓' : '✗'} | ${f.default || '—'} | ${f.primaryKey ? 'PK' : ''}${f.unique ? ' UK' : ''} | ${f.description || ''} |`
+      ).join('\n');
+
+      return `### ${e.name}
+
+> Source: \`${e.file || 'unknown'}\` (${e.source || 'detected'})
+
+| Field | Type | Required | Default | Constraints | Description |
+|-------|------|:--------:|---------|-------------|-------------|
+${fieldRows}
+`;
+    }).join('\n');
+
+  // Build enum sections (if Prisma enums found)
+  const enums = entities.filter(e => e.source === 'prisma-enum');
+  const enumSection = enums.length > 0 ? `## Enums
+
+${enums.map(e => `### ${e.name}
+
+| Value |
+|-------|
+${e.fields.map(f => `| ${f.name} |`).join('\n')}
+`).join('\n')}` : '';
+
+  // Build relationship table
+  const relRows = relationships.length > 0
+    ? relationships.map(r => `| ${r.from} | ${r.to} | ${r.type} | ${r.field} | — |`).join('\n')
+    : '| <!-- No relationships detected --> | | | | |';
+
+  // Generate mermaid ER diagram
+  const erDiagram = generateERDiagram(entities, relationships);
+
+  const content = `# Data Model
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed ${new Date().toISOString().split('T')[0]} -->
+<!-- docguard:generated true -->
+
+> **Auto-generated by DocGuard.** Review and refine this document.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+| **Version** | \`0.1.0\` |
+| **Database** | ${stack.database || 'TBD'} |
+| **ORM** | ${stack.orm || 'None detected'} |
+| **Schema Source** | ${schemaSource} |
+| **Entities** | ${entities.filter(e => e.source !== 'prisma-enum').length} |
+| **Relationships** | ${relationships.length} |
+
+---
+
+## Entity Summary
+
+| Entity | Storage | Primary Key | Source | Fields |
+|--------|---------|-------------|--------|--------|
+${entityRows || '| <!-- No models detected --> | | | | |'}
+
+---
+
+## Entity Details
+
+${entitySections}
+${enumSection}
+
+## Relationships
+
+| From | To | Type | FK/Reference | Cascade |
+|------|-----|------|-------------|---------|
+${relRows}
+${erDiagram ? `
+## Entity-Relationship Diagram
+
+\`\`\`mermaid
+${erDiagram}
+\`\`\`
+` : ''}
+
+## Indexes
+
+| Table | Index Name | Fields | Type | Purpose |
+|-------|-----------|--------|------|---------|
+| <!-- TBD: Document indexes --> | | | | |
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${entities.length} entities, ${relationships.length} relationships from ${schemaSource}) |
+`;
+
+  safeWrite(path, appendStandardsCitation(content, 'DATA-MODEL.md'), 'utf-8');
+  console.log(`  ${c.green}✅ DATA-MODEL.md${c.reset} (${entities.length} entities, ${relationships.length} relationships from ${schemaSource})`);
+  return true;
+}
+
+export function generateEnvironment(dir, config, stack, scan, flags) {
+  const path = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
+  if (existsSync(path) && !flags.force) {
+    console.log(`  ${c.dim}⏭️  ENVIRONMENT.md (exists)${c.reset}`);
+    return false;
+  }
+
+  const envVarRows = scan.envVars.map(v =>
+    `| \`${v.name}\` | ${categorizeEnvVar(v.name)} | Yes | \`${v.example}\` | |`
+  ).join('\n');
+
+  const content = `# Environment
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed ${new Date().toISOString().split('T')[0]} -->
+<!-- docguard:generated true -->
+
+> **Auto-generated by DocGuard.** Review and refine this document.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+| **Version** | \`0.1.0\` |
+
+---
+
+## Prerequisites
+
+| Tool | Version | Installation |
+|------|---------|-------------|
+${stack.language ? `| ${stack.language.split(' ')[0]} | ${stack.language.split(' ')[1] || 'latest'} | |` : ''}
+${stack.framework ? `| ${stack.framework.split(' ')[0]} | ${stack.framework.split(' ')[1] || 'latest'} | |` : ''}
+${stack.database ? `| ${stack.database} | latest | |` : ''}
+
+## Environment Variables
+
+| Variable | Category | Required | Example | Description |
+|----------|----------|:--------:|---------|-------------|
+${envVarRows || '| <!-- No .env.example found --> | | | | |'}
+
+## Setup Steps
+
+1. Clone the repository
+2. Install dependencies: \`${existsSync(resolve(dir, 'pnpm-lock.yaml')) ? 'pnpm install' : 'npm install'}\`
+3. Copy environment file: \`cp .env.example .env.local\`
+4. Fill in environment variables
+5. Start development server: \`${existsSync(resolve(dir, 'pnpm-lock.yaml')) ? 'pnpm' : 'npm'} run dev\`
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${scan.envVars.length} env vars found) |
+`;
+
+  safeWrite(path, appendStandardsCitation(content, 'ENVIRONMENT.md'), 'utf-8');
+  console.log(`  ${c.green}✅ ENVIRONMENT.md${c.reset} (${scan.envVars.length} env vars detected)`);
+  return true;
+}
+
+export function generateTestSpec(dir, config, stack, scan, flags) {
+  const path = resolve(dir, 'docs-canonical/TEST-SPEC.md');
+  if (existsSync(path) && !flags.force) {
+    console.log(`  ${c.dim}⏭️  TEST-SPEC.md (exists)${c.reset}`);
+    return false;
+  }
+
+  // Build service-to-test map
+  const serviceMap = [];
+  for (const svc of scan.services) {
+    const svcName = basename(svc, extname(svc));
+    const matchingTest = scan.tests.find(t =>
+      t.includes(svcName) || t.includes(svcName.replace('.', '.test.'))
+    );
+    serviceMap.push({
+      source: svc,
+      test: matchingTest || '—',
+      status: matchingTest ? '✅' : '❌',
+    });
+  }
+
+  const serviceRows = serviceMap.map(s =>
+    `| \`${s.source}\` | \`${s.test}\` | — | ${s.status} |`
+  ).join('\n');
+
+  const content = `# Test Specification
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed ${new Date().toISOString().split('T')[0]} -->
+<!-- docguard:generated true -->
+
+> **Auto-generated by DocGuard.** Review and refine this document.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+| **Test Framework** | ${stack.testing || 'Not detected'} |
+| **Test Files Found** | ${scan.tests.length} |
+
+---
+
+## Test Categories
+
+| Category | Framework | Location | Run Command |
+|----------|-----------|----------|-------------|
+| Unit | ${stack.testing || 'TBD'} | tests/unit/ | \`npm test\` |
+| Integration | ${stack.testing || 'TBD'} | tests/integration/ | \`npm run test:integration\` |
+| E2E | Playwright | tests/e2e/ | \`npm run test:e2e\` |
+
+## Coverage Rules
+
+| Metric | Target | Current |
+|--------|:------:|:-------:|
+| Line Coverage | 80% | <!-- TBD --> |
+| Branch Coverage | 70% | <!-- TBD --> |
+| Function Coverage | 80% | <!-- TBD --> |
+
+## Service-to-Test Map
+
+| Source File | Unit Test | Integration Test | Status |
+|------------|-----------|-----------------|:------:|
+${serviceRows || '| <!-- No services found --> | | | |'}
+
+## Critical User Journeys
+
+| # | Journey | Test File | Status |
+|---|---------|-----------|:------:|
+| 1 | <!-- e.g. User Registration --> | <!-- test file --> | ❌ |
+| 2 | <!-- e.g. Login Flow --> | | ❌ |
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated (${scan.tests.length} test files, ${serviceMap.filter(s => s.status === '✅').length}/${serviceMap.length} mapped) |
+`;
+
+  safeWrite(path, appendStandardsCitation(content, 'TEST-SPEC.md'), 'utf-8');
+  console.log(`  ${c.green}✅ TEST-SPEC.md${c.reset} (${scan.tests.length} tests, ${serviceMap.filter(s => s.status === '✅').length}/${serviceMap.length} services mapped)`);
+  return true;
+}
+
+export function generateSecurity(dir, config, stack, scan, flags) {
+  const path = resolve(dir, 'docs-canonical/SECURITY.md');
+  if (existsSync(path) && !flags.force) {
+    console.log(`  ${c.dim}⏭️  SECURITY.md (exists)${c.reset}`);
+    return false;
+  }
+
+  const content = `# Security
+
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed ${new Date().toISOString().split('T')[0]} -->
+<!-- docguard:generated true -->
+
+> **Auto-generated by DocGuard.** Review and refine this document.
+
+| Metadata | Value |
+|----------|-------|
+| **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
+
+---
+
+## Authentication
+
+| Method | Provider | Token Type | Expiry |
+|--------|---------|-----------|--------|
+| ${stack.auth || '<!-- TBD -->'} | | | |
+
+## Authorization
+
+| Role | Permissions | Notes |
+|------|-----------|-------|
+| <!-- e.g. admin --> | <!-- All --> | |
+| <!-- e.g. user --> | <!-- Read/Write --> | |
+
+## Secrets Management
+
+| Secret | Storage | Rotation | Access |
+|--------|---------|----------|--------|
+${scan.envVars.filter(v => isSecretVar(v.name)).map(v =>
+  `| \`${v.name}\` | Environment Variable | <!-- TBD --> | Application |`
+).join('\n') || '| <!-- TBD --> | | | |'}
+
+## Security Rules
+
+- [ ] All secrets stored in environment variables (never in code)
+- [ ] \`.env\` is in \`.gitignore\`
+- [ ] API endpoints require authentication
+- [ ] Input validation on all user inputs
+- [ ] HTTPS enforced in production
+- [ ] CORS configured appropriately
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1.0 | ${new Date().toISOString().split('T')[0]} | DocGuard Generate | Auto-generated |
+`;
+
+  safeWrite(path, appendStandardsCitation(content, 'SECURITY.md'), 'utf-8');
+  console.log(`  ${c.green}✅ SECURITY.md${c.reset} (auth: ${stack.auth || 'not detected'})`);
+  return true;
+}
+
+export function generateRootFiles(dir, config, stack, scan, flags, docTools) {
+  let created = 0;
+  let skipped = 0;
+
+  // AGENTS.md (AGENTS.md Standard compliant)
+  const agentsPath = resolve(dir, 'AGENTS.md');
+  if (!existsSync(agentsPath) || flags.force) {
+    const content = `# AI Agent Instructions — ${config.projectName}
+
+<!-- Standard: https://agents.md -->
+<!-- Generated by DocGuard — AGENTS.md standard compliant -->
+
+> This project follows **Canonical-Driven Development (CDD)**.
+> Documentation is the source of truth. Read before coding.
+
+## Workflow
+
+1. **Read** \`docs-canonical/\` before suggesting changes
+2. **Check** existing patterns in the codebase
+3. **Run** \`npx docguard-cli diagnose\` to see what needs fixing
+4. **Confirm** your approach before writing code
+5. **Implement** matching existing code style
+6. **Log** any deviations in \`DRIFT-LOG.md\` with \`// DRIFT: reason\`
+7. **Verify** with \`npx docguard-cli guard\` — all checks must pass
+
+## Project Stack
+
+${Object.entries(stack).filter(([, v]) => v).map(([k, v]) => `- **${k}**: ${v}`).join('\n')}
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| \`docs-canonical/ARCHITECTURE.md\` | System design (arc42 aligned) |
+| \`docs-canonical/API-REFERENCE.md\` | API endpoint documentation |
+| \`docs-canonical/DATA-MODEL.md\` | Database schemas & entities |
+| \`docs-canonical/SECURITY.md\` | Auth & secrets |
+| \`docs-canonical/TEST-SPEC.md\` | Test requirements |
+| \`docs-canonical/ENVIRONMENT.md\` | Environment setup |
+| \`AGENTS.md\` | AI agent instructions (this file) |
+| \`CHANGELOG.md\` | Change tracking |
+| \`DRIFT-LOG.md\` | Documented deviations |
+
+## Permissions & Guardrails
+
+> **IMPORTANT:** These limits apply to all AI agents working on this project.
+
+### Allowed
+
+- Read any file in the repository
+- Modify files within \`src/\`, \`tests/\`, and \`docs-canonical/\`
+- Run test commands (\`npm test\`, \`npx docguard-cli guard\`)
+- Create new files in appropriate directories
+
+### Not Allowed
+
+- Modify \`.env\` files or secrets
+- Push commits or create releases without explicit approval
+- Delete or rename canonical documentation files
+- Bypass DocGuard checks (\`docguard guard\` must pass)
+- Install new dependencies without approval
+
+### Safety Rules
+
+- Never hardcode secrets, tokens, or API keys
+- Always validate inputs before processing
+- Never expose internal paths or stack traces to users
+- Run \`npx docguard-cli guard\` before every commit
+
+## Monorepo Support
+
+<!-- If this is a monorepo, nested AGENTS.md files in subdirectories
+     override these instructions for their scope. -->
+
+| Scope | AGENTS.md Location |
+|-------|-------------------|
+| Root (default) | \`./AGENTS.md\` |
+| <!-- e.g. packages/api --> | <!-- packages/api/AGENTS.md --> |
+
+## DocGuard Commands
+
+\`\`\`bash
+npx docguard-cli guard          # Validate compliance
+npx docguard-cli diagnose       # Identify issues + AI fix prompts
+npx docguard-cli fix --doc ARCH # Fix specific document
+npx docguard-cli score          # CDD maturity score (0-100)
+npx docguard-cli generate       # Generate docs from code
+\`\`\`
+
+### AI Agent Workflow (IMPORTANT)
+
+1. **Before work**: Run \`npx docguard-cli guard\` — understand compliance state
+2. **After changes**: Run \`npx docguard-cli diagnose\` — get fix instructions
+3. **Fix issues**: Each issue has an \`ai_instruction\` — follow it exactly
+4. **Verify**: Run \`npx docguard-cli guard\` again — must pass before commit
+5. **Update CHANGELOG**: All changes need a changelog entry
+
+## Rules
+
+- Never commit without updating CHANGELOG.md
+- If code deviates from docs, add \`// DRIFT: reason\`
+- Security rules in SECURITY.md are mandatory
+- Test requirements in TEST-SPEC.md must be met
+- Documentation changes must pass \`docguard guard\`
+`;
+    safeWrite(agentsPath, content);
+    console.log(`  ${c.green}✅ AGENTS.md${c.reset} (AGENTS.md standard compliant)`);
+    created++;
+  } else {
+    console.log(`  ${c.dim}⏭️  AGENTS.md (exists)${c.reset}`);
+    skipped++;
+  }
+
+  // CHANGELOG.md
+  const changelogPath = resolve(dir, 'CHANGELOG.md');
+  if (!existsSync(changelogPath) || flags.force) {
+    const content = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+- CDD documentation via DocGuard generate
+`;
+    safeWrite(changelogPath, content);
+    console.log(`  ${c.green}✅ CHANGELOG.md${c.reset}`);
+    created++;
+  } else {
+    console.log(`  ${c.dim}⏭️  CHANGELOG.md (exists)${c.reset}`);
+    skipped++;
+  }
+
+  // DRIFT-LOG.md
+  const driftPath = resolve(dir, 'DRIFT-LOG.md');
+  if (!existsSync(driftPath) || flags.force) {
+    const content = `# Drift Log
+
+> Documents conscious deviations from canonical specifications.
+> Every \`// DRIFT: reason\` in code must have a corresponding entry here.
+
+| Date | File | Canonical Doc | Drift Description | Severity | Resolution |
+|------|------|---------------|-------------------|----------|------------|
+| | | | | | |
+`;
+    safeWrite(driftPath, content);
+    console.log(`  ${c.green}✅ DRIFT-LOG.md${c.reset}`);
+    created++;
+  } else {
+    console.log(`  ${c.dim}⏭️  DRIFT-LOG.md (exists)${c.reset}`);
+    skipped++;
+  }
+
+  return { created, skipped };
+}
+
+// ── Utility Functions ──────────────────────────────────────────────────────
+
+function categorizeEnvVar(name) {
+  if (name.includes('SECRET') || name.includes('KEY') || name.includes('TOKEN') || name.includes('PASSWORD')) return '🔐 Secret';
+  if (name.includes('DATABASE') || name.includes('DB_') || name.includes('REDIS')) return '🗃️ Database';
+  if (name.includes('AUTH') || name.includes('JWT') || name.includes('SESSION')) return '🔒 Auth';
+  if (name.includes('AWS') || name.includes('CLOUD') || name.includes('S3')) return '☁️ Cloud';
+  if (name.includes('URL') || name.includes('HOST') || name.includes('PORT')) return '🌐 Network';
+  return '⚙️ Config';
+}
+
+function isSecretVar(name) {
+  return name.includes('SECRET') || name.includes('KEY') || name.includes('TOKEN') || name.includes('PASSWORD');
+}