---
name: documentation
description: |
  Automatically generates technical documentation for SmartStack.
  Use this skill when:
  - User asks to create/generate documentation
  - User mentions "document", "documentation", "doc", "ERD", "schema"
  - User wants to document a module, table, tool, or test
  - After implementing a feature to generate its documentation
  Types: user module, developer tools, database ERD, testing tools
argument-hint: "<module-name> [--type user|developer|database|testing|update]"
model: sonnet
---

<objective>
Generate and maintain technical documentation integrated into SmartStack web app.
Works in synergy with the `/documentation:module` command.

**Reference:** [_shared.md](../_shared.md) for architecture, i18n
</objective>

<quick_start>
## WHEN THIS SKILL ACTIVATES

Claude automatically invokes this skill when it detects:

| Trigger | Example |
|---------|---------|
| Explicit request | "Document the SLA module" |
| Documentation mention | "We should create the doc for..." |
| After implementation | "The feature is done, generate the doc" |
| Structure question | "How is the documentation organized?" |
| Keywords | "ERD", "schema", "diagram", "document" |
| **Update request** | "Update the doc", "refresh documentation", "doc is outdated" |
| **Drift detected** | "The SLA documentation is stale" |
</quick_start>

<parameters>
## DOCUMENTATION TYPES

| Type | Description | Output |
|------|-------------|--------|
| `user` | User module (data-driven) | `docs/business/{app}/{module}/doc-data.ts` + `index.tsx` |
| `developer` | Development tool guide | `docs/developer/tools/{Tool}Page.tsx` |
| `database` | Schema with ERD diagram | `docs/developer/database/{Schema}SchemaPage.tsx` |
| `testing` | Testing tool | `docs/developer/testing/{Tool}TestingPage.tsx` |
| `update` | Update existing documentation | Updates `doc-data.ts` + i18n FR |

### Available Developer tools

| Category | Tools |
|----------|-------|
| Local Environment | Docker Compose, MailDev, VS Code, Environment variables |
| API Testing | Postman, REST Client, Swagger/OpenAPI |
| E2E Testing | Microsoft Playwright, Inspector, Trace Viewer |
| Load Testing | NBomber (.NET), k6, Azure Load Testing |
| Security Testing | OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS |
</parameters>

<workflow>
## AUTOMATIC WORKFLOW

### STEP 1: TYPE DETECTION

Analyze the request to identify:

| Clue | → Type |
|------|--------|
| Functional module (SLA, Tickets, Users) | `user` |
| Dev tool (Docker, Postman, VS Code) | `developer` |
| Tables, schema, database | `database` |
| Tests (security, load, E2E) | `testing` |

### STEP 2: TARGET EXTRACTION

Identify the specific name:
- Module: `sla`, `tickets`, `users`, `permissions`
- Tool: `docker`, `postman`, `playwright`, `maildev`
- Schema: `support`, `auth`, `nav`, `usr`
- Test: `security`, `load`, `e2e`

### STEP 3: EXECUTION

**For NEW documentation (type = user|developer|database|testing):**

Follow the data-driven workflow from [templates.md](templates.md):

```
1. Read source data (feature.json, code patterns)
2. Generate doc-data.ts (data file, ~50 lines)
3. Generate index.tsx (page wrapper, ~10 lines) with i18nNamespace prop
4. Generate i18n FR file (source language only)
5. Update docs-manifest.json
6. Update App.tsx routing and parent indexes
7. Update DocPanelContext.tsx mapping (contextual doc panel)
```

**For UPDATE documentation (type = update):**

```
1. Read docs-manifest.json → find target module
2. Invoke docs-context-reader agent → get current doc state
3. Identify code changes since last doc update (git diff)
4. Map changes to documentation sections (see data-schema.md)
5. Update doc-data.ts with new/modified data
6. Update i18n FR file if labels changed
7. Update docs-manifest.json timestamps
```

> **i18n simplifié:** Seul FR (source) est généré. EN/IT/DE sont déférés à un pipeline de traduction séparé.
</workflow>

<execution_rules>
## ABSOLUTE RULES

1. **NEVER** hardcoded text → `useTranslation('docs')`
2. **NEVER** ASCII art → React/HTML components for ERD
3. **ALWAYS** read sources before generating
4. **ALWAYS** confirm before creating
5. **ALWAYS** update App.tsx and parent indexes
6. **ALWAYS** add module in `UserIndexPage.tsx` (IF type == `user`)
7. **ALWAYS** update `DocPanelContext.tsx` mapping (IF type == `user`)
8. **ALWAYS** pass `i18nNamespace` prop to DocRenderer in index.tsx
</execution_rules>

---

<success_criteria>
- Documentation page renders correctly in React app
- i18n FR file created (EN/IT/DE deferred to translation pipeline)
- Route registered in App.tsx
- docs-manifest.json updated
- Module appears in UserIndexPage (if type = user)
- DocPanelContext.tsx mapping updated (if type = user)
- BookOpen edge button opens correct doc for the module's routes
</success_criteria>

---

## UserIndexPage Integration (TYPE: user)

**MANDATORY** for `user` modules: Add the module to the navigation hierarchy.

| File | Modification |
|------|--------------|
| `UserIndexPage.tsx` | Add icon + entry in `modules[]` of parent application |
| `fr/docs.json` | Add `user.modules.{module}.name` and `.description` |
| `en/docs.json` | Add `user.modules.{module}.name` and `.description` |

**Parent applications:**
- `Platform > Administration`: admin modules (users, roles, ai, entra...)
- `Platform > Support`: support modules (tickets, sla, templates...)
- `Personal > MySpace`: personal modules (profile, preferences...)

**Verification:** The module should appear on `/docs/user` under its application.

---

## DocPanelContext Integration (TYPE: user)

**MANDATORY** for `user` modules: Update the contextual documentation panel mapping.

### How it works

When a user clicks the BookOpen icon (edge button) on any application page, the `DocPanelContext` resolves the current route to the matching documentation URL and opens it in an iframe panel.

### File to update

`web/smartstack-web/src/contexts/DocPanelContext.tsx`

### What to add

For each module, add entries in the `docMapping` object for ALL the module's routes:

```typescript
const docMapping: Record<string, string> = {
  // Platform > Administration > {Module}
  '{module}': '/docs/business/platform/administration/{module}',
  '{module}/list': '/docs/business/platform/administration/{module}',
  '{module}/create': '/docs/business/platform/administration/{module}',
  '{module}/dashboard': '/docs/business/platform/administration/{module}',
  // ... add ALL sub-routes that exist for the module
};
```

### Key resolution logic

The `getDocUrlForPath()` function extracts segments from the pathname:
- `/platform/administration/users/list` → tries `users/list`, then `users`
- `/platform/support/tickets/123` → tries `tickets/123`, then `tickets`

**Also update `appDocMapping`** if the module is the "default" for its application:

```typescript
const appDocMapping: Record<string, string> = {
  'administration': '/docs/business/platform/administration/users',  // default for admin
};
```

### index.tsx must pass i18nNamespace

Each doc page wrapper MUST pass the correct i18n namespace to DocRenderer:

```tsx
import { DocRenderer } from '@/components/docs';
import { docData } from './doc-data';

export default function {Module}DocPage() {
  return (
    <DocRenderer
      data={docData}
      backPath="/docs/business/platform"
      backLabel="nav.backToAdministration"
      i18nNamespace="docsAdministration{Module}"
    />
  );
}
```

### i18n namespace naming convention

| Module | Namespace | File |
|--------|-----------|------|
| users | `docsAdministrationUsers` | `docs-administration-users.json` |
| permissions | `docsAdministrationPermissions` | `docs-administration-permissions.json` |
| tenants | `docsAdministrationTenants` | `docs-administration-tenants.json` |

The JSON file root key MUST match the namespace: `{ "docsAdministration{Module}": { ... } }`

### i18n config update

Add the new namespace to `web/smartstack-web/src/i18n/config.ts`:
1. Add to the destructured imports in `loadLanguageResources`
2. Add the dynamic import with `.catch(() => ({ default: {} }))`
3. Add to the return object
4. Add to the `ns` array in `i18n.init()`

---

## DATA SOURCES

| Data | Source |
|------|--------|
| DB schemas | `src/SmartStack.Infrastructure/Persistence/Configurations/` |
| Tables | `ApplicationDbContextModelSnapshot.cs` |
| Existing documentation | `web/smartstack-web/src/pages/docs/` |
| Testing tools | WebSearch (current versions) |

---

## ASSOCIATED FILES

- **React Templates:** [templates.md](templates.md)
- **Data Schema:** [data-schema.md](data-schema.md)
- **DocRenderer:** `web/smartstack-web/src/components/docs/DocRenderer.tsx`
- **Types:** `web/smartstack-web/src/components/docs/types.ts`
- **DocPanelContext:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
- **DocEdgeButton:** `web/smartstack-web/src/components/ui/DocEdgeButton.tsx`
- **DocPanel:** `web/smartstack-web/src/components/ui/DocPanel.tsx`
- **i18n Config:** `web/smartstack-web/src/i18n/config.ts`
- **Manifest Schema:** `_resources/docs-manifest-schema.md`
- **Complete Command:** `.claude/commands/documentation-module.md`
