@ai-coders/context 0.3.0 → 0.4.0

package/dist/generators/documentation/templates/apiReferenceTemplate.js

@@ -0,0 +1,490 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderApiReference = renderApiReference;
+function renderApiReference() {
+    return `<!-- agent-update:start:api-reference -->
+# API Reference
+
+**Purpose:** Enable AI agents to programmatically interact with all API endpoints.
+
+**Agent Usage Instructions:**
+- Use documented curl commands as templates for requests
+- Verify expected response codes match actual responses
+- Handle authentication token expiration automatically
+- Parse error responses to determine retry strategy
+- Log all API interactions for debugging
+
+## Base URLs
+
+**Agent Configuration:**
+\`\`\`bash
+# Set as environment variables for easier switching
+export API_BASE_DEV="http://localhost:3000/api"
+export API_BASE_STAGING="https://staging-api.example.com"  # TODO: Update
+export API_BASE_PROD="https://api.example.com"              # TODO: Update
+
+# Agent uses based on context
+API_BASE=$API_BASE_STAGING  # Change as needed
+\`\`\`
+
+## Authentication
+
+**Agent Authentication Flow:**
+
+### Step 1: Obtain Token
+\`\`\`bash
+# Agent executes login
+TOKEN_RESPONSE=$(curl -s -X POST "\${API_BASE}/auth/login" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "email": "agent@example.com",
+    "password": "'\${AGENT_PASSWORD}'"
+  }')
+
+# Agent extracts token
+TOKEN=$(echo \$TOKEN_RESPONSE | jq -r '.token')
+EXPIRES_IN=$(echo \$TOKEN_RESPONSE | jq -r '.expiresIn')
+
+# Agent stores token with expiration
+echo "\$TOKEN" > .api-token
+echo \$((\$(date +%s) + \$EXPIRES_IN)) > .api-token-expires
+
+# Expected response structure
+# {
+#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+#   "expiresIn": 3600,
+#   "refreshToken": "refresh_token_here",
+#   "user": {"id": "123", "email": "agent@example.com"}
+# }
+\`\`\`
+
+### Step 2: Use Token in Requests
+\`\`\`bash
+# Agent includes token in all authenticated requests
+curl -X GET "\${API_BASE}/resources" \\
+  -H "Authorization: Bearer \$TOKEN" \\
+  -H "Content-Type: application/json"
+\`\`\`
+
+### Step 3: Handle Token Expiration
+\`\`\`bash
+# Agent checks token expiration before each request
+function check_token() {
+  if [ ! -f .api-token ] || [ ! -f .api-token-expires ]; then
+    return 1  # Token missing, need to authenticate
+  fi
+
+  EXPIRES=$(cat .api-token-expires)
+  NOW=$(date +%s)
+
+  if [ $NOW -ge $EXPIRES ]; then
+    return 1  # Token expired
+  fi
+
+  return 0  # Token valid
+}
+
+# Agent refresh flow (if 401 received)
+if ! check_token; then
+  echo "Token expired or missing, re-authenticating..."
+  # Re-run Step 1
+fi
+\`\`\`
+
+**Agent Error Handling:**
+- 401 response → Token invalid/expired, re-authenticate
+- 403 response → Permission denied, check agent has required role
+- 429 response → Rate limited, wait and retry (see Rate Limiting section)
+
+### Authorization & Permissions
+- Document role-based access control (RBAC) if applicable
+- List permission levels and their capabilities
+- Explain scope-based authorization for OAuth
+
+## API Versioning
+- **Current Version:** v1
+- **Versioning Strategy:** TODO: URL path (/v1/), header, or query parameter
+- **Deprecation Policy:** TODO: Document how versions are deprecated
+
+## Rate Limiting
+
+**Agent Must Implement:** Check rate limit headers and back off when necessary.
+
+\`\`\`bash
+# Agent rate limit handler
+function make_api_request() {
+  local url=$1
+  local method=$2
+  local data=$3
+
+  RESPONSE=$(curl -i -X "$method" "$url" \\
+    -H "Authorization: Bearer $TOKEN" \\
+    -H "Content-Type: application/json" \\
+    -d "$data" 2>&1)
+
+  # Agent extracts rate limit headers
+  LIMIT=$(echo "$RESPONSE" | grep -i "x-ratelimit-limit" | cut -d: -f2 | tr -d ' \\r')
+  REMAINING=$(echo "$RESPONSE" | grep -i "x-ratelimit-remaining" | cut -d: -f2 | tr -d ' \\r')
+  RESET=$(echo "$RESPONSE" | grep -i "x-ratelimit-reset" | cut -d: -f2 | tr -d ' \\r')
+
+  # Agent checks if approaching limit
+  if [ "\$REMAINING" -lt "10" ]; then
+    NOW=$(date +%s)
+    WAIT=\$((RESET - NOW))
+    echo "Rate limit low (\$REMAINING remaining), waiting \${WAIT}s until reset..."
+    sleep \$WAIT
+  fi
+
+  # Agent handles 429 (rate limited)
+  HTTP_CODE=$(echo "\$RESPONSE" | grep "HTTP/" | awk '{print \$2}')
+  if [ "\$HTTP_CODE" == "429" ]; then
+    RETRY_AFTER=$(echo "\$RESPONSE" | grep -i "retry-after" | cut -d: -f2 | tr -d ' \\r')
+    echo "Rate limited, retrying after \${RETRY_AFTER}s..."
+    sleep "\$RETRY_AFTER"
+    make_api_request "\$url" "\$method" "\$data"  # Retry
+  fi
+
+  echo "$RESPONSE"
+}
+\`\`\`
+
+**Rate Limit:** TODO: e.g., 1000 requests per hour
+**Headers Agent Should Monitor:**
+- \`X-RateLimit-Limit\`: Maximum allowed
+- \`X-RateLimit-Remaining\`: Remaining in window
+- \`X-RateLimit-Reset\`: Reset time (Unix timestamp)
+- \`Retry-After\`: Seconds to wait (when 429 received)
+
+## Common Headers
+### Request Headers
+- \`Content-Type: application/json\` - Required for POST/PUT/PATCH
+- \`Authorization: Bearer <token>\` - Authentication token
+- \`X-Request-ID: <uuid>\` - Optional request tracking ID
+
+### Response Headers
+- \`Content-Type: application/json\`
+- \`X-Request-ID: <uuid>\` - Echo of request ID for tracking
+- \`X-Response-Time: <ms>\` - Server processing time
+
+## Endpoints
+
+### Authentication Endpoints
+
+#### POST /auth/register
+Register a new user account.
+
+**Request:**
+\`\`\`json
+{
+  "email": "user@example.com",
+  "password": "securePassword123",
+  "name": "John Doe"
+}
+\`\`\`
+
+**Response (201 Created):**
+\`\`\`json
+{
+  "id": "user_123",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+\`\`\`
+
+**Errors:**
+- \`400\`: Validation error (invalid email, weak password)
+- \`409\`: Email already registered
+
+---
+
+#### POST /auth/login
+Authenticate user and receive access token.
+
+**Request:**
+\`\`\`json
+{
+  "email": "user@example.com",
+  "password": "securePassword123"
+}
+\`\`\`
+
+**Response (200 OK):**
+\`\`\`json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "refresh_token_here",
+  "expiresIn": 3600,
+  "user": {
+    "id": "user_123",
+    "email": "user@example.com",
+    "name": "John Doe"
+  }
+}
+\`\`\`
+
+**Errors:**
+- \`401\`: Invalid credentials
+- \`429\`: Too many failed attempts
+
+---
+
+### Resource Endpoints
+
+#### GET /api/resources
+List all resources with pagination.
+
+**Query Parameters:**
+- \`page\` (integer, default: 1): Page number
+- \`limit\` (integer, default: 20, max: 100): Items per page
+- \`sort\` (string): Sort field (e.g., "createdAt", "-name" for desc)
+- \`filter\` (string): Filter criteria (implementation-specific)
+
+**Response (200 OK):**
+\`\`\`json
+{
+  "data": [
+    {
+      "id": "res_123",
+      "name": "Resource Name",
+      "status": "active",
+      "createdAt": "2024-01-15T10:30:00Z",
+      "updatedAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "pages": 5
+  }
+}
+\`\`\`
+
+**Errors:**
+- \`401\`: Unauthorized (missing or invalid token)
+- \`403\`: Forbidden (insufficient permissions)
+
+---
+
+#### GET /api/resources/:id
+Get a specific resource by ID.
+
+**Path Parameters:**
+- \`id\` (string, required): Resource identifier
+
+**Response (200 OK):**
+\`\`\`json
+{
+  "id": "res_123",
+  "name": "Resource Name",
+  "description": "Detailed description",
+  "status": "active",
+  "metadata": {
+    "key": "value"
+  },
+  "createdAt": "2024-01-15T10:30:00Z",
+  "updatedAt": "2024-01-15T10:30:00Z"
+}
+\`\`\`
+
+**Errors:**
+- \`401\`: Unauthorized
+- \`404\`: Resource not found
+
+---
+
+#### POST /api/resources
+Create a new resource.
+
+**Request:**
+\`\`\`json
+{
+  "name": "New Resource",
+  "description": "Resource description",
+  "status": "active",
+  "metadata": {
+    "key": "value"
+  }
+}
+\`\`\`
+
+**Response (201 Created):**
+\`\`\`json
+{
+  "id": "res_124",
+  "name": "New Resource",
+  "description": "Resource description",
+  "status": "active",
+  "metadata": {
+    "key": "value"
+  },
+  "createdAt": "2024-01-15T11:00:00Z",
+  "updatedAt": "2024-01-15T11:00:00Z"
+}
+\`\`\`
+
+**Errors:**
+- \`400\`: Validation error
+- \`401\`: Unauthorized
+- \`403\`: Forbidden
+
+---
+
+#### PUT /api/resources/:id
+Update an existing resource (full replacement).
+
+**Path Parameters:**
+- \`id\` (string, required): Resource identifier
+
+**Request:**
+\`\`\`json
+{
+  "name": "Updated Resource",
+  "description": "Updated description",
+  "status": "inactive",
+  "metadata": {
+    "key": "newValue"
+  }
+}
+\`\`\`
+
+**Response (200 OK):**
+Returns updated resource object.
+
+**Errors:**
+- \`400\`: Validation error
+- \`401\`: Unauthorized
+- \`404\`: Resource not found
+
+---
+
+#### PATCH /api/resources/:id
+Partially update a resource.
+
+**Path Parameters:**
+- \`id\` (string, required): Resource identifier
+
+**Request:**
+\`\`\`json
+{
+  "status": "inactive"
+}
+\`\`\`
+
+**Response (200 OK):**
+Returns updated resource object.
+
+---
+
+#### DELETE /api/resources/:id
+Delete a resource.
+
+**Path Parameters:**
+- \`id\` (string, required): Resource identifier
+
+**Response (204 No Content)**
+
+**Errors:**
+- \`401\`: Unauthorized
+- \`404\`: Resource not found
+- \`409\`: Conflict (resource has dependencies)
+
+---
+
+## Webhooks
+### Registering Webhooks
+Document webhook registration process if applicable.
+
+### Webhook Events
+- \`resource.created\` - Fired when a new resource is created
+- \`resource.updated\` - Fired when a resource is updated
+- \`resource.deleted\` - Fired when a resource is deleted
+
+### Webhook Payload Example
+\`\`\`json
+{
+  "event": "resource.created",
+  "timestamp": "2024-01-15T11:00:00Z",
+  "data": {
+    "id": "res_124",
+    "name": "New Resource"
+  }
+}
+\`\`\`
+
+### Webhook Security
+- Document signature verification mechanism
+- Explain retry logic for failed deliveries
+
+## Error Responses
+### Standard Error Format
+\`\`\`json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input data",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ],
+    "requestId": "req_abc123"
+  }
+}
+\`\`\`
+
+### HTTP Status Codes
+- \`200 OK\`: Successful request
+- \`201 Created\`: Resource created successfully
+- \`204 No Content\`: Successful deletion
+- \`400 Bad Request\`: Invalid input or validation error
+- \`401 Unauthorized\`: Missing or invalid authentication
+- \`403 Forbidden\`: Insufficient permissions
+- \`404 Not Found\`: Resource not found
+- \`409 Conflict\`: Resource conflict (duplicate, dependencies)
+- \`422 Unprocessable Entity\`: Valid syntax but semantic errors
+- \`429 Too Many Requests\`: Rate limit exceeded
+- \`500 Internal Server Error\`: Server error
+- \`503 Service Unavailable\`: Service temporarily unavailable
+
+### Common Error Codes
+- \`VALIDATION_ERROR\`: Input validation failed
+- \`AUTHENTICATION_REQUIRED\`: No authentication provided
+- \`AUTHENTICATION_FAILED\`: Invalid credentials
+- \`PERMISSION_DENIED\`: Insufficient permissions
+- \`RESOURCE_NOT_FOUND\`: Requested resource doesn't exist
+- \`RATE_LIMIT_EXCEEDED\`: Too many requests
+- \`INTERNAL_ERROR\`: Server-side error
+
+## SDK & Client Libraries
+- Document available SDKs (JavaScript, Python, Ruby, etc.)
+- Link to SDK documentation and examples
+
+## Postman/OpenAPI Collection
+- Link to Postman collection for easy testing
+- Link to OpenAPI/Swagger specification if available
+
+<!-- agent-readonly:guidance -->
+## AI Update Checklist
+1. Review route definitions and controller implementations for new or changed endpoints
+2. Verify authentication flows match current implementation
+3. Update rate limiting policies if thresholds changed
+4. Document new error codes and response formats
+5. Ensure all examples use realistic data and current API structure
+6. Validate that webhook event types are current
+7. Update SDK links and availability
+
+<!-- agent-readonly:sources -->
+## Acceptable Sources
+- API route files and controller implementations
+- Authentication middleware and JWT/OAuth configurations
+- OpenAPI/Swagger specifications
+- Integration tests that demonstrate API usage
+- Postman collections or API testing suites
+
+<!-- agent-update:end -->
+`;
+}
+//# sourceMappingURL=apiReferenceTemplate.js.map

package/dist/generators/documentation/templates/apiReferenceTemplate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiReferenceTemplate.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/apiReferenceTemplate.ts"],"names":[],"mappings":";;AAAA,gDAqeC;AAreD,SAAgB,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmeR,CAAC;AACF,CAAC"}

package/dist/generators/documentation/templates/architectureTemplate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"architectureTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/architectureTemplate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAGvD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA8DrF"}
+{"version":3,"file":"architectureTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/architectureTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAGvD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA6DrF"}

package/dist/generators/documentation/templates/architectureTemplate.js

@@ -1,39 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderArchitectureNotes = renderArchitectureNotes;
-const frontMatter_1 = require("./frontMatter");
 const common_1 = require("./common");
 function renderArchitectureNotes(context) {
-    const frontMatter = (0, frontMatter_1.createFrontMatter)({
-        id: 'architecture-notes',
-        goal: 'Describe how the system is assembled, key trade-offs, and active constraints.',
-        requiredInputs: [
-            'Recent architectural decisions or ADRs',
-            'Observed service/module boundaries in the codebase',
-            'Dependency graphs or build tooling insights'
-        ],
-        successCriteria: [
-            'Decision list covers the most influential trade-offs',
-            'Risks capture active constraints or technical debt',
-            'Links to diagrams or monitors are up to date'
-        ],
-        relatedAgents: ['architect-specialist', 'backend-specialist']
-    });
-    const defaultSections = [
-        'System boundaries and integration points',
-        'Primary modules and their responsibilities',
-        'Data flow between major components',
-        'Dependencies worth highlighting'
-    ];
     const directorySnapshot = (0, common_1.formatDirectoryStats)(context.directoryStats);
-    return `${frontMatter}
-<!-- ai-task:architecture-notes -->
+    const coreComponentsSection = directorySnapshot || '- *Add notes for each core component or module.*';
+    return `<!-- agent-update:start:architecture-notes -->
 # Architecture Notes
 
 > TODO: Describe how the system is assembled and why the current design exists.
 
-## Decisions To Record
-${defaultSections.map(item => `- ${item}`).join('\n')}
+## System Architecture Overview
+- Summarize the top-level topology (monolith, modular service, microservices) and deployment model.
+- Highlight how requests traverse the system and where control pivots between layers.
+
+## Core System Components
+${coreComponentsSection}
+
+## Internal System Boundaries
+- Document seams between domains, bounded contexts, or service ownership.
+- Note data ownership, synchronization strategies, and shared contract enforcement.
+
+## System Integration Points
+- Map inbound interfaces (APIs, events, webhooks) and the modules that own them.
+- Capture orchestration touchpoints where this system calls or coordinates other internal services.
+
+## External Service Dependencies
+- List SaaS platforms, third-party APIs, or infrastructure services the system relies on.
+- Describe authentication methods, rate limits, and failure considerations for each dependency.
+
+## Key Decisions & Trade-offs
+- Summarize architectural decisions, experiments, or ADR outcomes that shape the current design.
+- Reference supporting documents and explain why selected approaches won over alternatives.
 
 ## Diagrams
 - Link architectural diagrams or add mermaid definitions here.
@@ -44,6 +42,7 @@ ${defaultSections.map(item => `- ${item}`).join('\n')}
 ## Top Directories Snapshot
 ${directorySnapshot}
 
+<!-- agent-readonly:guidance -->
 ## AI Update Checklist
 1. Review ADRs, design docs, or major PRs for architectural changes.
 2. Verify that each documented decision still holds; mark superseded choices clearly.
@@ -51,6 +50,7 @@ ${directorySnapshot}
 4. Update Risks & Constraints with active incident learnings or TODO debt.
 5. Link any new diagrams or dashboards referenced in recent work.
 
+<!-- agent-readonly:sources -->
 ## Acceptable Sources
 - ADR folders, \`/docs/architecture\` notes, or RFC threads.
 - Dependency visualisations from build tooling or scripts.
@@ -60,7 +60,7 @@ ${directorySnapshot}
 - [Project Overview](./project-overview.md)
 - Update [agents/README.md](../agents/README.md) when architecture changes.
 
-<!-- /ai-task -->
+<!-- agent-update:end -->
 `;
 }
 //# sourceMappingURL=architectureTemplate.js.map

package/dist/generators/documentation/templates/architectureTemplate.js.map

@@ -1 +1 @@
-{"version":3,"file":"architectureTemplate.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/architectureTemplate.ts"],"names":[],"mappings":";;AAIA,0DA8DC;AAlED,+CAAkD;AAElD,qCAAgD;AAEhD,SAAgB,uBAAuB,CAAC,OAAqC;IAC3E,MAAM,WAAW,GAAG,IAAA,+BAAiB,EAAC;QACpC,EAAE,EAAE,oBAAoB;QACxB,IAAI,EAAE,+EAA+E;QACrF,cAAc,EAAE;YACd,wCAAwC;YACxC,oDAAoD;YACpD,6CAA6C;SAC9C;QACD,eAAe,EAAE;YACf,sDAAsD;YACtD,oDAAoD;YACpD,8CAA8C;SAC/C;QACD,aAAa,EAAE,CAAC,sBAAsB,EAAE,oBAAoB,CAAC;KAC9D,CAAC,CAAC;IAEH,MAAM,eAAe,GAAG;QACtB,0CAA0C;QAC1C,4CAA4C;QAC5C,oCAAoC;QACpC,iCAAiC;KAClC,CAAC;IAEF,MAAM,iBAAiB,GAAG,IAAA,6BAAoB,EAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAEvE,OAAO,GAAG,WAAW;;;;;;;EAOrB,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;EASnD,iBAAiB;;;;;;;;;;;;;;;;;;;CAmBlB,CAAC;AACF,CAAC"}
+{"version":3,"file":"architectureTemplate.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/architectureTemplate.ts"],"names":[],"mappings":";;AAGA,0DA6DC;AA/DD,qCAAgD;AAEhD,SAAgB,uBAAuB,CAAC,OAAqC;IAC3E,MAAM,iBAAiB,GAAG,IAAA,6BAAoB,EAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE,MAAM,qBAAqB,GAAG,iBAAiB,IAAI,kDAAkD,CAAC;IAEtG,OAAO;;;;;;;;;;EAUP,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;EAyBrB,iBAAiB;;;;;;;;;;;;;;;;;;;;;CAqBlB,CAAC;AACF,CAAC"}

package/dist/generators/documentation/templates/common.js

@@ -27,13 +27,13 @@ function formatDirectoryList(context, includePlaceholders) {
             return `- \`${dir}/\``;
         }
         const slotId = slugify(dir);
-        return `- <!-- ai-slot:directory-${slotId} -->\`${dir}/\` — TODO: Describe the purpose of this directory.<!-- /ai-slot -->`;
+        return `- <!-- agent-fill:directory-${slotId} -->\`${dir}/\` — TODO: Describe the purpose of this directory.<!-- /agent-fill -->`;
     })
         .join('\n');
 }
 function buildDocumentMapTable(guides) {
     const rows = guides.map(meta => `| ${meta.title} | \`${meta.file}\` | ${meta.marker} | ${meta.primaryInputs} |`);
-    return ['| Guide | File | Task Marker | Primary Inputs |', '| --- | --- | --- | --- |', ...rows].join('\n');
+    return ['| Guide | File | AI Marker | Primary Inputs |', '| --- | --- | --- | --- |', ...rows].join('\n');
 }
 function formatDirectoryStats(stats) {
     if (!stats.length) {

package/dist/generators/documentation/templates/common.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/common.ts"],"names":[],"mappings":";;AAWA,kDAuBC;AAED,sDAGC;AAED,oDAQC;AAED,8DAMC;AAED,0BAKC;AA9DD,MAAM,kBAAkB,GAA2B;IACjD,GAAG,EAAE,8CAA8C;IACnD,IAAI,EAAE,yDAAyD;IAC/D,IAAI,EAAE,6CAA6C;IACnD,MAAM,EAAE,iCAAiC;IACzC,KAAK,EAAE,+BAA+B;IACtC,QAAQ,EAAE,gCAAgC;CAC3C,CAAC;AAEF,SAAgB,mBAAmB,CACjC,OAAqC,EACrC,mBAA4B;IAE5B,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,OAAO,CAAC,mBAAmB;SAC/B,GAAG,CAAC,GAAG,CAAC,EAAE;QACT,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,OAAO,GAAG,SAAS,WAAW,EAAE,CAAC;QAC1C,CAAC;QAED,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACzB,OAAO,OAAO,GAAG,KAAK,CAAC;QACzB,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,4BAA4B,MAAM,SAAS,GAAG,sEAAsE,CAAC;IAC9H,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAgB,qBAAqB,CAAC,MAA8C;IAClF,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;IACjH,OAAO,CAAC,iDAAiD,EAAE,2BAA2B,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC9G,CAAC;AAED,SAAgB,oBAAoB,CAAC,KAAsB;IACzD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,4BAA4B,CAAC;IACtC,CAAC;IAED,OAAO,KAAK;SACT,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,CAAC,IAAI,uBAAuB,IAAI,CAAC,SAAS,QAAQ,CAAC;SAC1E,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAgB,yBAAyB,CAAC,WAAqB;IAC7D,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,SAAgB,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/common.ts"],"names":[],"mappings":";;AAWA,kDAuBC;AAED,sDAGC;AAED,oDAQC;AAED,8DAMC;AAED,0BAKC;AA9DD,MAAM,kBAAkB,GAA2B;IACjD,GAAG,EAAE,8CAA8C;IACnD,IAAI,EAAE,yDAAyD;IAC/D,IAAI,EAAE,6CAA6C;IACnD,MAAM,EAAE,iCAAiC;IACzC,KAAK,EAAE,+BAA+B;IACtC,QAAQ,EAAE,gCAAgC;CAC3C,CAAC;AAEF,SAAgB,mBAAmB,CACjC,OAAqC,EACrC,mBAA4B;IAE5B,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,OAAO,CAAC,mBAAmB;SAC/B,GAAG,CAAC,GAAG,CAAC,EAAE;QACT,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,OAAO,GAAG,SAAS,WAAW,EAAE,CAAC;QAC1C,CAAC;QAED,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACzB,OAAO,OAAO,GAAG,KAAK,CAAC;QACzB,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,+BAA+B,MAAM,SAAS,GAAG,yEAAyE,CAAC;IACpI,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAgB,qBAAqB,CAAC,MAA8C;IAClF,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;IACjH,OAAO,CAAC,+CAA+C,EAAE,2BAA2B,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5G,CAAC;AAED,SAAgB,oBAAoB,CAAC,KAAsB;IACzD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,4BAA4B,CAAC;IACtC,CAAC;IAED,OAAO,KAAK;SACT,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,CAAC,IAAI,uBAAuB,IAAI,CAAC,SAAS,QAAQ,CAAC;SAC1E,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAgB,yBAAyB,CAAC,WAAqB;IAC7D,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,SAAgB,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC"}

package/dist/generators/documentation/templates/dataFlowTemplate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataFlowTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/dataFlowTemplate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAGvD,wBAAgB,cAAc,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAiD5E"}
+{"version":3,"file":"dataFlowTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/dataFlowTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAGvD,wBAAgB,cAAc,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAkC5E"}

package/dist/generators/documentation/templates/dataFlowTemplate.js

@@ -1,26 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderDataFlow = renderDataFlow;
-const frontMatter_1 = require("./frontMatter");
 const common_1 = require("./common");
 function renderDataFlow(context) {
-    const frontMatter = (0, frontMatter_1.createFrontMatter)({
-        id: 'data-flow',
-        goal: 'Describe how information moves through the system and where it integrates with external services.',
-        requiredInputs: [
-            'Architecture diagrams or sequence flows',
-            'Integration specs (APIs, queues, webhooks, third-party services)',
-            'Notes on batch jobs, schedulers, or ETL processes'
-        ],
-        successCriteria: [
-            'Highlights inbound, internal, and outbound flows',
-            'Documents transformation points and trust boundaries',
-            'Identifies failure modes and retry/backoff behaviour'
-        ],
-        relatedAgents: ['architect-specialist', 'backend-specialist']
-    });
-    return `${frontMatter}
-<!-- ai-task:data-flow -->
+    return `<!-- agent-update:start:data-flow -->
 # Data Flow & Integrations
 
 Explain how data enters, moves through, and exits the system, including interactions with external services.
@@ -32,24 +15,26 @@ Explain how data enters, moves through, and exits the system, including interact
 - Describe how modules within ${(0, common_1.formatInlineDirectoryList)(context.topLevelDirectories)} collaborate (queues, events, RPC calls, shared databases).
 
 ## External Integrations
-- <!-- ai-slot:integration -->**Integration** — Purpose, authentication, payload shapes, retry strategy.<!-- /ai-slot -->
+- <!-- agent-fill:integration -->**Integration** — Purpose, authentication, payload shapes, retry strategy.<!-- /agent-fill -->
 
 ## Observability & Failure Modes
 - Metrics, traces, or logs that monitor the flow.
 - Backoff, dead-letter, or compensating actions when downstream systems fail.
 
+<!-- agent-readonly:guidance -->
 ## AI Update Checklist
 1. Validate flows against the latest integration contracts or diagrams.
 2. Update authentication, scopes, or rate limits when they change.
 3. Capture recent incidents or lessons learned that influenced reliability.
 4. Link to runbooks or dashboards used during triage.
 
+<!-- agent-readonly:sources -->
 ## Acceptable Sources
 - Architecture diagrams, ADRs, integration playbooks.
 - API specs, queue/topic definitions, infrastructure code.
 - Postmortems or incident reviews impacting data movement.
 
-<!-- /ai-task -->
+<!-- agent-update:end -->
 `;
 }
 //# sourceMappingURL=dataFlowTemplate.js.map

package/dist/generators/documentation/templates/dataFlowTemplate.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataFlowTemplate.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/dataFlowTemplate.ts"],"names":[],"mappings":";;AAIA,wCAiDC;AArDD,+CAAkD;AAElD,qCAAqD;AAErD,SAAgB,cAAc,CAAC,OAAqC;IAClE,MAAM,WAAW,GAAG,IAAA,+BAAiB,EAAC;QACpC,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,mGAAmG;QACzG,cAAc,EAAE;YACd,yCAAyC;YACzC,kEAAkE;YAClE,mDAAmD;SACpD;QACD,eAAe,EAAE;YACf,kDAAkD;YAClD,sDAAsD;YACtD,sDAAsD;SACvD;QACD,aAAa,EAAE,CAAC,sBAAsB,EAAE,oBAAoB,CAAC;KAC9D,CAAC,CAAC;IAEH,OAAO,GAAG,WAAW;;;;;;;;;;gCAUS,IAAA,kCAAyB,EAAC,OAAO,CAAC,mBAAmB,CAAC;;;;;;;;;;;;;;;;;;;;;CAqBrF,CAAC;AACF,CAAC"}
+{"version":3,"file":"dataFlowTemplate.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/dataFlowTemplate.ts"],"names":[],"mappings":";;AAGA,wCAkCC;AApCD,qCAAqD;AAErD,SAAgB,cAAc,CAAC,OAAqC;IAClE,OAAO;;;;;;;;;gCASuB,IAAA,kCAAyB,EAAC,OAAO,CAAC,mBAAmB,CAAC;;;;;;;;;;;;;;;;;;;;;;;CAuBrF,CAAC;AACF,CAAC"}