---
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)
4. Generate i18n FR file (source language only)
5. Update docs-manifest.json
6. Update App.tsx routing and parent indexes
```

**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`)
</execution_rules>

---

<success_criteria>
- Documentation page renders correctly in React app
- i18n files created for all 4 languages (FR, EN, IT, DE)
- Route registered in App.tsx
- docs-manifest.json updated
- Module appears in UserIndexPage (if type = user)
</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.

---

## 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`
- **Manifest Schema:** `_resources/docs-manifest-schema.md`
- **Complete Command:** `.claude/commands/documentation-module.md`
