code-to-docs-sync.mdc

---
description: Always sync extended-docs (×6), glossary, legacy docs, OpenAPI, i18n, CHANGELOG when code or features change
alwaysApply: true
---

# Code → documentation sync (mandatory)

**Always apply** at the end of every product task — before marking work done. Works with [`cross-cutting-changes.mdc`](cross-cutting-changes.mdc) and [`extended-docs-cve.mdc`](extended-docs-cve.mdc).

**Skills:** [`arvan-extended-docs`](../skills/arvan-extended-docs/SKILL.md) · [`arvan-persian-orthography`](../skills/arvan-persian-orthography/SKILL.md) · [`prd-extended-delivery`](../skills/prd-extended-delivery/SKILL.md)

## Agent workflow (automatic — every change)

1. **Detect** — after editing code, match every touched path against the mapping table (§Path mapping) and markdown inventory (§Markdown inventory).
2. **Plan** — list doc files + locales to update (default: **all six** when an extended-docs chapter applies).
3. **Write** — update **English first** (`extended-docs/docs/content/en/`), then mirror structure to `fa`, `ar`, `ru`, `zh`, `fr` (same `##` headings, tables, env names in `code`/backticks).
4. **Glossary** — new terms → `extended-docs/docs/glossary.md` only (multilingual table row + anchor section).
5. **Legacy `docs/`** — update ADRs, `self-hosted/`, `ALERTS.md`, etc. when the mapping row or inventory says so.
6. **Verify** — run checks in §Verification; fix locale drift with `scripts/check-extended-docs-locale-sync.sh`.
7. **Changelog** — bullet under `CHANGELOG.md` `[Unreleased]` ([`pr-ready-ci-changelog.mdc`](pr-ready-ci-changelog.mdc)).
8. **Cursor sync** — after editing `agent/rules/**`, run `npm run agent:install`.

Do **not** ship code-only PRs when any mapping row or inventory entry applies.

## Markdown inventory

Update these when behaviour, ops, or developer workflow changes:

| Tree / file | Role | When to edit |
|-------------|------|--------------|
| **`extended-docs/docs/content/{en,fa,ar,ru,zh,fr}/`** | Canonical product docs (11 chapters) | Any user-visible feature, config, API, architecture |
| **`extended-docs/docs/glossary.md`** | Glossary tab (single file) | New domain terms, acronyms, env groups |
| **`extended-docs/docs/index.md`** | Extended-docs home | Release version, major highlights |
| **`extended-docs/docs/prototype/`** | UI + API explorer tabs | API shape, mock flows, wireframes |
| **`docs/README.md`** | Legacy docs index | Pointers, maintainer workflow |
| **`docs/ALERTS.md`**, **`docs/WATCH.md`**, **`docs/TRANSLATION.md`** | Focused legacy guides | Alerting, watch, translation behaviour |
| **`docs/self-hosted/*.md`** | Ops runbooks | RBAC, tenants, metrics, airgap, K8s, secrets |
| **`docs/DOCKER.md`**, **`docs/GITHUB_PAGES.md`**, **`docs/RELEASE.md`**, **`docs/OPENAPI.md`** | Deploy & release | Docker, Pages, semver, OpenAPI sync |
| **`docs/adr/*.md`** | Architecture decisions | Persistence, feeds, OpenAPI policy |
| **`README.md`**, **`README.{fa,ar,ru,zh,fr}.md`** | Repo entry (6 languages) | Features, roadmap, quick start — see [`readme-locale-sync.mdc`](readme-locale-sync.mdc) |
| **`ARCHITECTURE.md`**, **`README.md`**, **`README.*.md`** | Repo entry points | Layout, features, test tree |
| **`AGENTS.md`**, **`CONTRIBUTING.md`**, **`CHANGELOG.md`** | Agent + contributor | Rules, checklist, unreleased notes |
| **`tests/README.md`** | Test layout | New suites, fixtures, E2E status |

Frozen (do **not** extend): legacy short MkDocs under `docs/en/`, `docs/fa/`, … — use `extended-docs/` instead.

## Path → documentation mapping

| Code / config change | Update (same PR) |
|----------------------|------------------|
| `server/services/notifications/**`, `server/services/alerts.ts`, watch alerting | `extended-docs/docs/content/*/09-alerts.md`, `*/07-configuration.md`, `*/11-self-hosted.md`; `docs/ALERTS.md`; `docs/self-hosted/NOTIFICATIONS.md`, `SECRETS.md`; glossary `#notification-service` |
| `server/db/schema.ts`, `server/db/drizzle.ts`, `server/db/*.ts` queries | `extended-docs/docs/content/*/08-architecture.md`, `*/11-self-hosted.md` (PostgreSQL); glossary `#drizzle-orm` |
| `server/routes/**`, `server/handlers/**`, request/response shape | `extended-docs/docs/content/*/06-api.md`; `server/openapi/spec.json` → `extended-docs/docs/assets/cve-openapi.json`; `extended-docs/docs/prototype/api-explorer.md`; `tests/server/` |
| `shared/api/**` | Same as API row + both OpenAPI copies |
| New/changed `process.env.*` | `.env.example`; matching extended-docs config/self-hosted chapters (×6); `docs/self-hosted/*.md` when ops-related |
| `src/**` UI flow, export, wizard, tabs | `extended-docs/docs/content/*/03-user-interface.md`; **all six** `src/i18n/messages/*.ts`; screenshots only if layout changed (`npm run docs:screenshots`) |
| `src/constants/presets.ts` (`STORAGE_KEYS`) | `extended-docs/docs/content/*/07-configuration.md` (×6); glossary `#scan-cache`; `docs/adr/002-scan-persistence-localstorage.md` if semantics change |
| `tests/**` (new suites, coverage targets, E2E) | `extended-docs/docs/content/*/10-operations.md` (×6); `tests/README.md`; `CONTRIBUTING.md`; `AGENTS.md`; glossary `#playwright-e2e` if E2E changes |
| `server/middleware/**`, `server/lib/**` (cache, RBAC, tenant, SSE) | Relevant architecture/config chapters (×6); `tests/README.md` when new test files |
| `tsconfig*.json`, build tooling | `CONTRIBUTING.md` if developer workflow changes |
| `.github/workflows/**` | `.github/workflows/README.md`, `.github/CI-CD.md`; `extended-docs/docs/content/*/10-operations.md` if user-facing |
| `Dockerfile`, `docker-compose*.yml` | `docs/DOCKER.md`; `extended-docs/docs/content/*/02-installation.md` if install steps change |
| `agent/rules/**`, `agent/skills/**` | `npm run agent:install`; `AGENTS.md`; `CONTRIBUTING.md` if new rule |

## Six-locale parity rules

Canonical tree: `extended-docs/docs/content/{en,fa,ar,ru,zh,fr}/` — files `01-overview.md` … `11-self-hosted.md`.

| Rule | Requirement |
|------|-------------|
| Structure | Same chapter filenames and **`##` heading count/order** in all six locales |
| RTL | Wrap `fa` and `ar` body in `<div class="doc-locale doc-locale--rtl" markdown="1" dir="rtl">` … `</div>` |
| LTR | Wrap `en`, `ru`, `zh`, `fr` in `<div class="doc-locale doc-locale--ltr" markdown="1">` when sibling RTL chapters use wrappers |
| Identifiers | Env vars, API paths, file paths, JSON keys — **identical** across locales (Latin) |
| Prose | Translate narrative; follow [`arvan-persian-orthography`](arvancloud_orthography.mdc) for `fa` |
| Terms | Link `[term](../../glossary.md#anchor)` — do not redefine long glossary text in chapters |
| Diagrams | Mermaid blocks identical across locales; walkthrough prose translated |

## Verification

```bash
scripts/check-extended-docs-locale-sync.sh   # heading parity across 6 locales
scripts/check-readme-locale-sync.sh        # README.md × 5 locale READMEs
make extended-docs-check                      # MkDocs strict + Mermaid + locale sync
npm run check:openapi                         # if API/OpenAPI touched
make check                                    # if app code touched
npm run agent:install                         # if agent/rules or agent/skills changed
```

Fix all locale-sync errors before handoff.

## Examples

**Bad:** Add `NOTIFICATION_DISCORD_WEBHOOK_URL` in `.env.example` only.  
**Good:** `.env.example` + `07-configuration.md` (×6) + `09-alerts.md` (×6) + `11-self-hosted.md` (×6) + `docs/ALERTS.md` + glossary + CHANGELOG.

**Bad:** Add 20 server tests without updating `10-operations.md` or `tests/README.md`.  
**Good:** Chapter 10 (×6) coverage baseline + `tests/README.md` suite table + CHANGELOG.

**Bad:** English-only extended-docs update.  
**Good:** Same sections added to `fa`, `ar`, `ru`, `zh`, `fr` in the same PR.