# Documentation Manifest Schema

## Purpose

The `docs-manifest.json` file maps code modules to their documentation artifacts. It is the single source of truth for documentation drift detection.

**Location:** Project root (next to `package.json` or `.sln`)

## Schema

```json
{
  "version": "1.0",
  "lastUpdated": "2026-01-30T10:00:00Z",
  "modules": {
    "business/{app}/{module}": {
      "featureId": "FEAT-NNN",
      "displayName": "Module Display Name",
      "codeFiles": [
        "src/SmartStack.Domain/Entities/Business/{Entity}.cs",
        "src/SmartStack.Application/Features/{Module}/Commands/*.cs",
        "src/SmartStack.Application/Features/{Module}/Queries/*.cs",
        "src/SmartStack.Api/Controllers/Business/{Module}Controller.cs"
      ],
      "docFiles": [
        "web/smartstack-web/src/pages/docs/business/{app}/{module}/doc-data.ts",
        "web/smartstack-web/src/i18n/locales/fr/docs-{app}-{module}.json"
      ],
      "baOutputs": [
        ".business-analyse/business/{app}/modules/{module}/features/FEAT-NNN/"
      ],
      "screenshots": {
        "step1": "/assets/docs/{module}/step-1.png",
        "step2": "/assets/docs/{module}/step-2.png"
      },
      "lastCodeChange": "2026-01-30T10:00:00Z",
      "lastDocUpdate": "2026-01-30T10:00:00Z",
      "gitCommitCode": "abc123",
      "gitCommitDoc": "def456",
      "status": "synced"
    }
  }
}
```

## Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `version` | string | Yes | Schema version (always "1.0") |
| `lastUpdated` | ISO date | Yes | Last time manifest was modified |
| `modules` | object | Yes | Map of module path → module entry |

### Module Entry

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `featureId` | string | Yes | BA feature ID (FEAT-NNN) |
| `displayName` | string | Yes | Human-readable module name |
| `codeFiles` | string[] | Yes | Source code files for this module |
| `docFiles` | string[] | Yes | Documentation files (doc-data.ts, i18n) |
| `baOutputs` | string[] | No | Business Analysis output directory |
| `screenshots` | object | No | Map of stepKey → image path |
| `lastCodeChange` | ISO date | Yes | Last code modification timestamp |
| `lastDocUpdate` | ISO date | Yes | Last documentation update timestamp |
| `gitCommitCode` | string | Yes | Git SHA of last code commit |
| `gitCommitDoc` | string | Yes | Git SHA of last doc commit |
| `status` | enum | Yes | `synced`, `drift`, or `missing` |

## Status Values

| Status | Meaning | Action |
|--------|---------|--------|
| `synced` | Documentation matches code | No action needed |
| `drift` | Code changed after last doc update | Run `/documentation` to update |
| `missing` | Module exists in code but has no documentation | Run `/business-analyse` or `/documentation` to create |

## Usage

### Created by
- BA skill step-06 (doc-html) after generating documentation
- Documentation skill after creating/updating a module page

### Read by
- `docs-context-reader` agent (for context injection)
- `docs-sync-checker` agent (for drift detection)
- BA step-04 (validate) for freshness check
- Drift hook (pre-commit) for commit warnings

### Updated by
- BA step-06 (on doc generation)
- Documentation skill (on doc update)

## Drift Detection Logic

```
IF module.lastCodeChange > module.lastDocUpdate:
    module.status = "drift"
ELSE:
    module.status = "synced"
```

## Example

```json
{
  "version": "1.0",
  "lastUpdated": "2026-01-30T14:30:00Z",
  "modules": {
    "business/support/sla": {
      "featureId": "FEAT-003",
      "displayName": "SLA Management",
      "codeFiles": [
        "src/SmartStack.Domain/Entities/Business/Sla.cs",
        "src/SmartStack.Application/Features/Sla/Commands/CreateSlaCommand.cs",
        "src/SmartStack.Application/Features/Sla/Queries/GetSlaListQuery.cs",
        "src/SmartStack.Api/Controllers/Business/SlaController.cs"
      ],
      "docFiles": [
        "web/smartstack-web/src/pages/docs/business/support/sla/doc-data.ts",
        "web/smartstack-web/src/i18n/locales/fr/docs-support-sla.json"
      ],
      "baOutputs": [
        ".business-analyse/business/Support/modules/Sla/features/FEAT-003/"
      ],
      "screenshots": {
        "step1": "/assets/docs/sla/step-1.png",
        "step2": "/assets/docs/sla/step-2.png",
        "step3": "/assets/docs/sla/step-3.png"
      },
      "lastCodeChange": "2026-01-28T16:00:00Z",
      "lastDocUpdate": "2026-01-30T14:30:00Z",
      "gitCommitCode": "a1b2c3d",
      "gitCommitDoc": "e4f5g6h",
      "status": "synced"
    },
    "business/support/tickets": {
      "featureId": "FEAT-005",
      "displayName": "Ticket Management",
      "codeFiles": [
        "src/SmartStack.Domain/Entities/Business/Ticket.cs",
        "src/SmartStack.Api/Controllers/Business/TicketsController.cs"
      ],
      "docFiles": [],
      "baOutputs": [],
      "screenshots": {},
      "lastCodeChange": "2026-01-29T10:00:00Z",
      "lastDocUpdate": "1970-01-01T00:00:00Z",
      "gitCommitCode": "x7y8z9a",
      "gitCommitDoc": "",
      "status": "missing"
    }
  }
}
```
