living-documentation 7.46.0 → 7.48.0

package/dist/starting-doc/AI/flavors/project-instructions-backend-api.md

@@ -0,0 +1,41 @@
+# Project AI Instructions - Backend API
+
+Use this flavor for HTTP APIs, workers, services, and server-side applications.
+
+## Startup Routine
+
+1. Read this file.
+2. Read `memory/MEMORY.md`.
+3. Read every rule in `DOCS_FOLDER/AI/rules/*.md`.
+4. Inspect ADR frontmatter before opening full ADRs.
+
+Replace `DOCS_FOLDER` with the real docs folder path.
+
+## Backend Rules
+
+- Identify request validation, authorization, persistence, and error handling before editing routes.
+- Preserve API compatibility unless the user explicitly requests a breaking change.
+- Prefer structured parsing and validation over ad hoc string handling.
+- Keep filesystem and database path boundaries explicit.
+- Add focused tests around changed behavior and failure paths.
+
+## Continuous Documentation
+
+At the end of every coherent feature or meaningful refactor:
+
+- create or update an ADR when the change affects an architecture boundary, public contract, storage format, protocol, workflow, or durable convention;
+- skip ADRs for trivial fixes and implementation details that are obvious from code;
+- when you create or update an ADR or durable documentation page, attach Living Documentation metadata to the source files that prove or implement it;
+- if MCP tools are available, prefer `add_metadata` and `refresh_metadata`;
+- if metadata cannot be updated from the current environment, state which source files should be attached.
+
+## Verification
+
+Use the project's actual commands, for example:
+
+```bash
+npm run build
+npm run test
+```
+
+For API changes, include at least one test that exercises the route or public contract.

package/dist/starting-doc/AI/flavors/project-instructions-frontend-app.md

@@ -0,0 +1,42 @@
+# Project AI Instructions - Frontend Application
+
+Use this flavor for React, Vue, Svelte, Angular, or static frontend applications.
+
+## Startup Routine
+
+1. Read this file.
+2. Read `memory/MEMORY.md`.
+3. Read every rule in `DOCS_FOLDER/AI/rules/*.md`.
+4. Inspect ADR frontmatter before opening full ADRs.
+
+Replace `DOCS_FOLDER` with the real docs folder path.
+
+## Frontend Rules
+
+- Keep user-visible strings in the project's i18n system when one exists.
+- Preserve existing design system conventions before adding new UI patterns.
+- Verify responsive layouts at small and desktop widths.
+- Avoid layout shifts caused by dynamic text, icons, and loading states.
+- Prefer existing shared components and utilities over new abstractions.
+
+## Continuous Documentation
+
+At the end of every coherent feature or meaningful refactor:
+
+- create or update an ADR when the change affects an architecture boundary, public contract, storage format, protocol, workflow, or durable convention;
+- skip ADRs for trivial fixes and implementation details that are obvious from code;
+- when you create or update an ADR or durable documentation page, attach Living Documentation metadata to the source files that prove or implement it;
+- if MCP tools are available, prefer `add_metadata` and `refresh_metadata`;
+- if metadata cannot be updated from the current environment, state which source files should be attached.
+
+## Verification
+
+Use the project's actual commands, for example:
+
+```bash
+npm run build
+npm run lint
+npm run test
+```
+
+For visual changes, add a browser or screenshot verification when practical.

package/dist/starting-doc/AI/flavors/project-instructions-library-cli.md

@@ -0,0 +1,41 @@
+# Project AI Instructions - Library Or CLI
+
+Use this flavor for packages, SDKs, CLIs, and developer tools.
+
+## Startup Routine
+
+1. Read this file.
+2. Read `memory/MEMORY.md`.
+3. Read every rule in `DOCS_FOLDER/AI/rules/*.md`.
+4. Inspect ADR frontmatter before opening full ADRs.
+
+Replace `DOCS_FOLDER` with the real docs folder path.
+
+## Library And CLI Rules
+
+- Treat public APIs, command flags, output formats, and config files as compatibility surfaces.
+- Keep error messages actionable and stable when tests or users may depend on them.
+- Prefer small focused helpers over broad abstractions.
+- Update docs or examples when behavior changes.
+- Test both success paths and invalid input paths.
+
+## Continuous Documentation
+
+At the end of every coherent feature or meaningful refactor:
+
+- create or update an ADR when the change affects an architecture boundary, public contract, storage format, protocol, workflow, or durable convention;
+- skip ADRs for trivial fixes and implementation details that are obvious from code;
+- when you create or update an ADR or durable documentation page, attach Living Documentation metadata to the source files that prove or implement it;
+- if MCP tools are available, prefer `add_metadata` and `refresh_metadata`;
+- if metadata cannot be updated from the current environment, state which source files should be attached.
+
+## Verification
+
+Use the project's actual commands, for example:
+
+```bash
+npm run build
+npm run test
+```
+
+For CLI changes, verify the command with realistic arguments.

package/dist/starting-doc/AI/flavors/project-instructions-monorepo.md

@@ -0,0 +1,41 @@
+# Project AI Instructions - Monorepo
+
+Use this flavor for repositories with multiple apps, packages, or services.
+
+## Startup Routine
+
+1. Read this file.
+2. Read `memory/MEMORY.md`.
+3. Read every rule in `DOCS_FOLDER/AI/rules/*.md`.
+4. Inspect ADR frontmatter before opening full ADRs.
+
+Replace `DOCS_FOLDER` with the real docs folder path.
+
+## Monorepo Rules
+
+- Identify the package or app owning the files before editing.
+- Use the nearest package scripts and config where possible.
+- Avoid cross-package refactors unless required by the task.
+- Check workspace dependency boundaries before importing across packages.
+- Prefer focused tests for the affected package first, then broader tests if shared contracts changed.
+
+## Continuous Documentation
+
+At the end of every coherent feature or meaningful refactor:
+
+- create or update an ADR when the change affects an architecture boundary, public contract, storage format, protocol, workflow, or durable convention;
+- skip ADRs for trivial fixes and implementation details that are obvious from code;
+- when you create or update an ADR or durable documentation page, attach Living Documentation metadata to the source files that prove or implement it;
+- if MCP tools are available, prefer `add_metadata` and `refresh_metadata`;
+- if metadata cannot be updated from the current environment, state which source files should be attached.
+
+## Verification
+
+Use the project's actual commands, for example:
+
+```bash
+npm run build --workspace <package>
+npm run test --workspace <package>
+```
+
+Adapt commands to the package manager used by the repository.

package/dist/starting-doc/AI/project-instructions.md

@@ -0,0 +1,78 @@
+# Project AI Instructions
+
+This file is the shared operating guide for AI assistants working on this project.
+
+Keep this file short, concrete, and project-specific. `AGENTS.md` and `CLAUDE.md` should point here instead of duplicating the same instructions.
+
+## Startup Routine
+
+Before making changes:
+
+1. Read this file.
+2. Read `memory/MEMORY.md` and load the relevant memory files listed there.
+3. Read every rule in `DOCS_FOLDER/AI/rules/*.md`.
+4. To understand existing decisions, inspect ADR frontmatter first: read only `description` and `tags`, then open the full ADR only when relevant.
+
+Replace `DOCS_FOLDER` with the real documentation folder path used by this project, for example `documentation` or `docs`.
+
+## AI Rules
+
+Rules live in `DOCS_FOLDER/AI/rules/*.md`.
+
+Each rule uses frontmatter:
+
+- `id` - stable rule identifier
+- `title` - short human-readable name
+- `severity` - `guideline`, `warning`, or `required`
+- `description` - concise summary
+- `tags` - themes used for discovery
+- `appliesTo` - file globs describing where the rule applies
+
+Apply every rule whose `appliesTo` patterns match files you touch. If a rule conflicts with the user request or another project instruction, state the conflict explicitly before proceeding.
+
+## ADRs
+
+ADRs are the durable record of important decisions.
+
+When you need to understand why something exists:
+
+1. List ADR files.
+2. Read only frontmatter `description` and `tags`.
+3. Open the full ADR only when it is relevant to the current task.
+4. If you make or change an important decision, create or update an ADR.
+
+## Continuous Documentation
+
+At the end of every coherent feature or meaningful refactor, update the durable documentation autonomously when the change created knowledge that future work must preserve.
+
+Do create or update an ADR when the feature:
+
+- changes an architecture boundary, public contract, storage format, protocol, or workflow;
+- introduces a convention that future changes must follow;
+- resolves a trade-off that would be hard to infer from code alone;
+- supersedes or invalidates a previous decision.
+
+Do not create ADRs for trivial fixes, mechanical renames, formatting-only changes, or implementation details that are obvious from the changed code.
+
+When you create or update an ADR or another durable documentation page, attach source-file metadata so Living Documentation can show reliability drift:
+
+1. Link the document to the source files that prove or implement what it describes.
+2. After the document is correct, refresh/re-baseline its metadata hashes.
+3. If MCP tools are available, prefer `add_metadata` and `refresh_metadata`.
+4. If metadata cannot be updated from the current environment, state that explicitly and list the source files that should be attached.
+
+## Memory
+
+Memory files live in the project under `memory/`.
+
+Do not store project memory in a tool-specific global folder if the user expects project-local memory. Update `memory/MEMORY.md` whenever you add or remove memory files.
+
+## Verification
+
+Before finishing a task, run the smallest useful verification:
+
+- build command if build files or typed code changed
+- focused tests when behavior changed
+- lint or formatting command if this project has one
+
+If a verification command cannot be run, say why.

package/dist/starting-doc/AI/rules/no-magic-numbers.md

@@ -0,0 +1,18 @@
+---
+id: no-magic-numbers
+title: Avoid magic numbers
+severity: warning
+description: Numeric values with domain meaning must be named constants instead of repeated raw literals.
+tags: ["code-quality", "maintainability"]
+appliesTo: ["src/**/*.ts", "src/frontend/**/*.js"]
+---
+
+Numeric values with domain meaning should be named where they are introduced.
+
+Prefer a constant whose name explains the intent:
+
+```ts
+const DEFAULT_CUSTOM_SHAPE_SIZE = 65;
+```
+
+Avoid repeating raw values in code when the value carries product, rendering, sizing, timing, or protocol meaning.

package/dist/starting-doc-fr/.living-doc.json

@@ -0,0 +1,52 @@
+{
+  "filenamePattern": "YYYY_MM_DD_HH_mm_[Category]_title",
+  "title": "Living Documentation",
+  "theme": "system",
+  "language": "fr",
+  "port": 4321,
+  "extraFiles": [],
+  "showDiagramDebug": false,
+  "diagramNodePalette": [
+    "#ffffff",
+    "#f5f5f4",
+    "#f1f5f9",
+    "#dbeafe",
+    "#e0f2fe",
+    "#cffafe",
+    "#ccfbf1",
+    "#dcfce7",
+    "#ecfccb",
+    "#fef9c3",
+    "#ffedd5",
+    "#fee2e2",
+    "#ffe4e6",
+    "#fce7f3",
+    "#ede9fe"
+  ],
+  "diagramEdgePalette": [
+    "#ffffff",
+    "#a8a29e",
+    "#374151",
+    "#3b82f6",
+    "#14b8a6",
+    "#22c55e",
+    "#f97316",
+    "#ef4444",
+    "#a855f7"
+  ],
+  "sourceRoot": "..",
+  "blockedFileExtensions": [
+    "exe",
+    "sh",
+    "bat",
+    "cmd",
+    "com",
+    "scr",
+    "ps1",
+    "msi"
+  ],
+  "exclusiveFolderExpansion": true,
+  "exclusiveCategoryExpansion": true,
+  "codeBlockMaxHeight": 400,
+  "markdownSoftBreaks": true
+}

package/dist/starting-doc-fr/ADRS/2026_01_01_[ADR]_example_architecture_decision.md

@@ -0,0 +1,58 @@
+---
+**date:** 2026-01-01
+**status:** Exemple
+**description:** Template d'ADR montrant comment enregistrer une décision projet avec assez de contexte, conséquences et tags pour qu'un assistant IA puisse la retrouver et la réutiliser plus tard.
+**tags:** adr, template, decision-architecture, contexte-ia, documentation
+---
+
+# Exemple de décision d'architecture
+
+## Contexte
+
+Remplacez cette section par la situation qui a mené à la décision.
+
+Expliquez le problème en termes concrets :
+
+- ce qui était difficile à comprendre, maintenir, faire évoluer, tester ou opérer ;
+- les contraintes existantes importantes ;
+- les alternatives considérées ;
+- le workflow utilisateur ou développeur impacté.
+
+Un ADR doit capturer la raison du changement, pas seulement la forme finale du code. C'est ce qui le rend utile plus tard pour les humains et pour les assistants IA qui doivent comprendre pourquoi le projet fonctionne ainsi.
+
+## Décision
+
+Remplacez cette section par la décision prise.
+
+Soyez assez spécifique pour qu'un autre développeur ou assistant IA puisse appliquer la même règle plus tard. Mentionnez les fichiers, modules, contrats de données, commandes ou conventions qui portent la décision lorsqu'ils sont pertinents.
+
+Exemple :
+
+- stocker les instructions IA projet dans `AI/project-instructions.md` ;
+- exposer les points d'entrée propres aux outils via `AGENTS.md` et `CLAUDE.md` ;
+- garder les règles IA réutilisables dans `AI/rules/*.md` ;
+- utiliser des liens symboliques quand un document doit apparaître dans Living Documentation sans dupliquer la source de vérité.
+
+## Conséquences
+
+### PROS
+
+- La décision est découvrable depuis la documentation, pas seulement depuis le code.
+- Les assistants IA peuvent lire le frontmatter des ADR d'abord, puis charger l'ADR complet seulement s'il correspond à la tâche.
+- Les futurs changements peuvent préserver l'intention originale au lieu de la redécouvrir depuis les détails d'implémentation.
+
+### CONS
+
+- L'ADR doit être maintenu quand la décision change.
+- Un ADR vague est pire que pas d'ADR, car il donne une fausse confiance aux futurs lecteurs.
+- Si la même règle est répétée à trop d'endroits, le projet peut dériver. Préférer une seule source de vérité et créer des liens vers elle.
+
+## Suite
+
+Quand cet exemple devient un vrai ADR :
+
+- renommer le fichier avec la vraie date, catégorie et titre de décision ;
+- définir `status` selon la convention du projet : `Proposed`, `Accepted`, `Superseded`, etc. ;
+- remplacer `description` par une phrase utile pour la découverte ;
+- remplacer `tags` par des thèmes recherchables ;
+- supprimer cette section si elle n'est plus utile.