living-documentation 7.45.0 → 7.47.0

package/dist/starting-doc/AI/HOW_TO.md

@@ -0,0 +1,338 @@
+# HOW TO - Initialize AI Context
+
+This folder contains a starter setup for AI-assisted development.
+
+The goal is to give AI tools a deterministic entry point:
+
+- `AGENTS.md` for Codex and agent-style tools
+- `CLAUDE.md` for Claude
+- `memory/MEMORY.md` for project-local memory
+- `AI/project-instructions.md` for shared project instructions
+- `AI/rules/*.md` for rules that must be applied while editing
+
+Codex looks for `AGENTS.md`. Claude looks for `CLAUDE.md`. Both files should point to the same project instructions so different tools follow the same rules.
+
+## How It Works
+
+This starter separates AI context into deterministic layers:
+
+```text
+AGENTS.md / CLAUDE.md
+  -> tool-specific entry points at the project root
+
+AI/project-instructions.md
+  -> shared operating instructions for every AI tool
+
+AI/rules/*.md
+  -> small reusable rules that must be applied when matching files are changed
+
+ADRS/*.md
+  -> durable decisions explaining why the project works this way
+
+memory/MEMORY.md
+  -> project-local memory index for frequently reused context
+```
+
+The entry-point files should stay small. Their job is to tell the AI where to look, not to duplicate all project knowledge.
+
+Living Documentation then makes these files visible as regular documents. When the same file must be visible from several places, prefer symbolic links so there is still one source of truth.
+
+The expected AI workflow is:
+
+1. Read `AGENTS.md` or `CLAUDE.md`, depending on the tool.
+2. Follow the link to `AI/project-instructions.md`.
+3. Read `memory/MEMORY.md` and load only relevant memory files.
+4. Read the matching rules from `AI/rules/*.md`.
+5. Inspect ADR frontmatter when the task may touch an existing decision.
+6. Make the change.
+7. At the end of a coherent feature, update durable documentation when needed.
+8. Attach Living Documentation metadata to created or updated documents when source files prove their content.
+
+## 1. Choose Your Project Instructions Flavor
+
+The default file is:
+
+```text
+AI/project-instructions.md
+```
+
+You can keep it, or replace it with one of the examples in:
+
+```text
+AI/flavors/
+```
+
+Available examples:
+
+```text
+AI/flavors/project-instructions-frontend-app.md
+AI/flavors/project-instructions-backend-api.md
+AI/flavors/project-instructions-library-cli.md
+AI/flavors/project-instructions-monorepo.md
+```
+
+To use one flavor, copy it over the default file:
+
+```bash
+cp AI/flavors/project-instructions-frontend-app.md AI/project-instructions.md
+```
+
+If you want to rename the selected example instead of keeping it in `AI/flavors/`, move it to the canonical location:
+
+```bash
+mv AI/flavors/project-instructions-frontend-app.md AI/project-instructions.md
+```
+
+Then edit `AI/project-instructions.md`:
+
+- replace `DOCS_FOLDER` with your real documentation folder name, for example `documentation`, `docs`, or `example`
+- replace example commands with real project commands
+- remove sections that do not apply to your project
+- add project-specific architecture notes
+
+## 2. Install Agent Entry Points
+
+Templates are provided in:
+
+```text
+AI/default/AGENTS.md
+AI/default/CLAUDE.md
+```
+
+Create symbolic links from your project root to those templates.
+
+If your documentation folder is named `documentation`:
+
+```bash
+ln -s documentation/AI/default/AGENTS.md AGENTS.md
+ln -s documentation/AI/default/CLAUDE.md CLAUDE.md
+```
+
+If your documentation folder has another name, adapt the path:
+
+```bash
+ln -s <docs-folder>/AI/default/AGENTS.md AGENTS.md
+ln -s <docs-folder>/AI/default/CLAUDE.md CLAUDE.md
+```
+
+Use both files when the project may be used by different AI tools. Use only one if your team standardizes on one tool.
+
+After creating the links, open `AGENTS.md` and `CLAUDE.md` from the project root and verify that their paths point to the correct documentation folder.
+
+## 3. Install Project Memory
+
+Memory should live in the project, not in a global AI-tool folder.
+
+Create a project-local memory folder:
+
+```bash
+mkdir -p memory
+```
+
+Then create a symbolic link to the starter memory index:
+
+```bash
+ln -s ../<docs-folder>/AI/default/MEMORY.md memory/MEMORY.md
+```
+
+Example when the docs folder is `documentation`:
+
+```bash
+ln -s ../documentation/AI/default/MEMORY.md memory/MEMORY.md
+```
+
+Then edit `memory/MEMORY.md` and add the memory files that matter for your project.
+
+Typical memory files:
+
+```text
+memory/project-overview.md
+memory/architecture.md
+memory/testing.md
+memory/domain-language.md
+```
+
+## 4. Review AI Rules
+
+Rules live in:
+
+```text
+AI/rules/
+```
+
+The starter includes:
+
+```text
+AI/rules/no-magic-numbers.md
+```
+
+Keep it if useful, edit it for your project, or remove it.
+
+Add more rules when you want behavior that every AI tool should apply consistently, for example:
+
+- i18n rules
+- testing strategy
+- public API compatibility
+- security boundaries
+- architecture constraints
+
+## 5. Understand ADRs
+
+ADRs live in:
+
+```text
+ADRS/
+```
+
+The starter includes an example ADR:
+
+```text
+ADRS/2026_01_01_[ADR]_example_architecture_decision.md
+```
+
+Use it as a template when an important decision needs to be recorded.
+
+An ADR is not a task log. It should explain a decision that future humans or AI assistants must understand before changing related code.
+
+Good ADR candidates:
+
+- choosing a framework, storage format, or protocol;
+- defining an architecture boundary;
+- changing a public API contract;
+- adopting a testing, release, or deployment strategy;
+- creating a rule that explains why code must be written a certain way.
+
+Avoid ADRs for small implementation details that are obvious from the code.
+
+Recommended AI workflow:
+
+1. List files in `ADRS/`.
+2. Read only the frontmatter first: `description` and `tags`.
+3. Load the full ADR only when it is relevant to the current task.
+4. At the end of a coherent feature or meaningful refactor, decide whether an ADR must be created or updated.
+5. If the feature changed a durable decision, create or update the ADR autonomously.
+6. After writing the ADR, attach metadata to the source files that prove or implement the decision.
+
+This is intentional: ADR writing should not depend on the user asking for it every time. The AI should keep the decision log current when it finishes a meaningful feature.
+
+Recommended filename format:
+
+```text
+YYYY_MM_DD_[CATEGORY]_short_decision_title.md
+```
+
+Example:
+
+```text
+2026_01_01_[ADR]_example_architecture_decision.md
+```
+
+Keep the frontmatter useful for discovery:
+
+```markdown
+---
+**date:** 2026-01-01
+**status:** Accepted
+**description:** One sentence explaining the decision and why it matters.
+**tags:** architecture, testing, api
+---
+```
+
+Use `status` consistently. Common values are:
+
+- `Proposed`
+- `Accepted`
+- `Superseded`
+- `To be validated`
+
+## 6. Understand Metadata And Reliability
+
+Living Documentation can bind a document to source files. Each binding stores a hash of the source file. The reliability gauge then shows whether the document may have drifted from the code.
+
+For AI-assisted development, this is part of the documentation workflow:
+
+- when an AI creates or updates an ADR, attach the source files that implement or prove the decision;
+- when an AI creates or updates a technical guide, attach the source files that the guide describes;
+- after the document is correct, refresh or re-baseline the metadata hashes;
+- if the AI cannot update metadata directly, it must say so and list the files that should be attached manually.
+
+If the AI has access to the Living Documentation MCP tools, it should prefer:
+
+```text
+add_metadata
+refresh_metadata
+```
+
+If it does not have MCP access, use the document metadata UI in Living Documentation.
+
+## 7. Register Instruction Files In Living Documentation
+
+Start Living Documentation:
+
+```bash
+npx living-documentation <docs-folder>
+```
+
+Open:
+
+```text
+http://localhost:4321/context
+```
+
+Use **Add AI instruction file** to link instruction files such as `AGENTS.md`, `CLAUDE.md`, `memory/MEMORY.md`, or other project-level instruction documents.
+
+Living Documentation creates symbolic links under:
+
+```text
+AI/
+```
+
+This makes instruction files visible in the main documentation without creating duplicate sources of truth.
+
+## 8. Clean Up The Starter
+
+After setup, remove what you do not need.
+
+Usually remove unused flavors:
+
+```bash
+rm -rf AI/flavors
+```
+
+Remove unused entry-point templates if you do not use both tools:
+
+```bash
+rm AI/default/CLAUDE.md
+```
+
+or:
+
+```bash
+rm AI/default/AGENTS.md
+```
+
+Keep `AI/default/MEMORY.md` only if `memory/MEMORY.md` links to it. If you copied the file instead of linking it, remove the unused template.
+
+Keep `AI/HOW_TO.md` only if you want future contributors to see the setup process. Otherwise, remove it after initialization.
+
+Keep the example ADR only if you want an in-project template. Otherwise, copy it when needed and remove the example.
+
+## 9. Final Expected Shape
+
+A minimal initialized project usually ends with:
+
+```text
+AGENTS.md -> <docs-folder>/AI/default/AGENTS.md
+CLAUDE.md -> <docs-folder>/AI/default/CLAUDE.md
+memory/
+  MEMORY.md -> ../<docs-folder>/AI/default/MEMORY.md
+<docs-folder>/
+  AI/
+    project-instructions.md
+    rules/
+      no-magic-numbers.md
+  ADRS/
+    2026_01_01_[ADR]_example_architecture_decision.md
+```
+
+Adapt the shape to your project. The important part is that AI tools have deterministic files to read and that the source of truth is not duplicated.

package/dist/starting-doc/AI/default/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md — Living Documentation
+
+This file is the Codex entry point for this repository.
+
+Before making changes:
+
+1. Read `DOCS_FOLDER/AI/project-instructions.md`.
+2. Read `memory/MEMORY.md` and load the relevant memory files listed there.
+3. Read every rule in `DOCS_FOLDER/AI/rules/*.md` and apply the rules whose `appliesTo` patterns match files you touch.
+4. To understand existing decisions, glob the ADR folder, read only each ADR frontmatter `description` and `tags`, then load the full ADR only when relevant.
+
+Replace `DOCS_FOLDER` with the real documentation folder path for this project.
+
+If an AI rule conflicts with the user request or another project instruction, state the conflict explicitly before proceeding.

package/dist/starting-doc/AI/default/CLAUDE.md

@@ -0,0 +1,14 @@
+# CLAUDE.md — Living Documentation
+
+This file is the Claude entry point for this repository.
+
+Before making changes:
+
+1. Read `DOCS_FOLDER/AI/project-instructions.md`.
+2. Read `memory/MEMORY.md` and load the relevant memory files listed there.
+3. Read every rule in `DOCS_FOLDER/AI/rules/*.md` and apply the rules whose `appliesTo` patterns match files you touch.
+4. To understand existing decisions, glob the ADR folder, read only each ADR frontmatter `description` and `tags`, then load the full ADR only when relevant.
+
+Replace `DOCS_FOLDER` with the real documentation folder path for this project.
+
+If an AI rule conflicts with the user request or another project instruction, state the conflict explicitly before proceeding.

package/dist/starting-doc/AI/default/MEMORY.md

@@ -0,0 +1,7 @@
+# Memory Index
+
+Toujours stocker les fichiers mémoire dans le dossier `memory/` du projet courant, pas dans `~/.claude`.
+
+**Why:** L'utilisateur préfère avoir tout le contexte dans le projet lui-même pour plus de visibilité et de contrôle.
+
+**How to apply:** Écrire les fichiers mémoire dans `<project_root>/memory/` au lieu de `~/.claude/projects/.../memory/`. Mettre à jour `memory/MEMORY.md` en conséquence.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "living-documentation",
-  "version": "7.45.0",
+  "version": "7.47.0",
   "description": "A CLI tool that serves a local Markdown documentation viewer",
   "main": "dist/src/server.js",
   "bin": {

package/dist/starting-doc/.annotations.json

@@ -1 +0,0 @@
-{}