diff --git a/.github/adr-check-prompt.md b/.github/adr-check-prompt.md
index 1b336ae..ce72eed 100644
--- a/.github/adr-check-prompt.md
+++ b/.github/adr-check-prompt.md
@@ -73,7 +73,7 @@ Rules:
 - Base every claim strictly on the provided data. **Invent nothing.** Do not
   guess an ADR number — only cite an ADR that appears in the ADR base.
 - The `report` is **advisory**. It must make clear that nothing here blocks a
-  merge, that a human or an agent drafts the ADR(s) under `maintainers/adr/` with
+  merge, that a human or an agent drafts the ADR(s) under `doc/handwritten/for-maintainers/adr/` with
   `Status: Proposed`, and that the maintainer accepts, supersedes, or deprecates.
   Never claim to have written an ADR or to block anything.
 
@@ -95,6 +95,6 @@ nothing here blocks a merge.
 **Conflicts with**
 - ⚠️ ADR-NNNN (<title>) — <the contradiction>
 
-_Agents: draft the ADR(s) under `maintainers/adr/` as `Status: Proposed` and link
+_Agents: draft the ADR(s) under `doc/handwritten/for-maintainers/adr/` as `Status: Proposed` and link
 them; the maintainer decides. See `AGENTS.md` → "Architecture decisions"._
 ```
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 7bfab97..a032169 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -47,14 +47,14 @@
 
 * [ ] Public API / error documentation updated
 * [ ] README / `doc/` updated
-* [ ] French translation (`doc/README.fr.md`) updated if user-facing behavior changed
+* [ ] French translation (`doc/handwritten/for-users/README.fr.md`) updated if user-facing behavior changed
 * [ ] No documentation change required
 
 ## Architecture decisions
 
-<!-- Every pull request is checked against the ADR base (maintainers/adr/). Most
+<!-- Every pull request is checked against the ADR base (doc/handwritten/for-maintainers/adr/). Most
      embark no architectural decision — tick the first box. Agents draft ADRs as
-     `Proposed`; the maintainer accepts or supersedes. See maintainers/adr/README.md. -->
+     `Proposed`; the maintainer accepts or supersedes. See doc/handwritten/for-maintainers/adr/README.md. -->
 
 * [ ] No architectural decision in this pull request
 * [ ] New decision recorded — ADR drafted as `Proposed`: ADR-____
diff --git a/.github/workflows/adr-check.yml b/.github/workflows/adr-check.yml
index 6e19876..4ea0da4 100644
--- a/.github/workflows/adr-check.yml
+++ b/.github/workflows/adr-check.yml
@@ -10,7 +10,7 @@ name: adr-check
 # recording a decision is a human-reviewed act, exactly like the sibling
 # `changelog` workflow. It NEVER blocks anything and NEVER writes an ADR — every
 # failure mode is a warning, and the verdict is a recommendation a human acts on.
-# See maintainers/workflows/adr-check.en.md.
+# See doc/handwritten/for-maintainers/workflows/adr-check.en.md.
 on:
   workflow_dispatch:
     inputs:
diff --git a/.github/workflows/canary.yml b/.github/workflows/canary.yml
index 4691126..53c6e40 100644
--- a/.github/workflows/canary.yml
+++ b/.github/workflows/canary.yml
@@ -3,7 +3,7 @@ name: canary
 # Early-warning that the documentation tooling still runs on the NEXT, not-yet-released .NET.
 #
 # The shipped tooling targets net8.0 and reaches every newer runtime purely by roll-forward (the worker uses
-# LatestMajor; see maintainers/adr/0002-floor-the-tooling-runtime.md). A runtime breaking change in a future
+# LatestMajor; see doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.md). A runtime breaking change in a future
 # major would surface here first — on a schedule, against the current preview — instead of in a user's CI the
 # day that major ships. It is the upper-end counterpart of the `floor` job in ci.yml, which pins the lower end.
 #
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6d9c7f3..33d986a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -72,7 +72,7 @@ jobs:
 
   # build-test above runs the whole suite on the LATEST .NET (10). This job proves the other end of the
   # supported range: that the fce tool and its worker, which ship targeting net8.0 (the floor — see
-  # maintainers/adr/0002-floor-the-tooling-runtime.md), actually run on the .NET 8 RUNTIME. The net8 TFM
+  # doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.md), actually run on the .NET 8 RUNTIME. The net8 TFM
   # already guards the compile-time API surface on every build; what it cannot show is that the tooling
   # executes on its advertised minimum runtime, which is what this job checks against the real artifacts.
   floor:
diff --git a/AGENTS.md b/AGENTS.md
index 8492e7e..d3289be 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,7 +9,7 @@ Two roles are covered: **writing code** and **reviewing pull requests**.
 - Build: `dotnet build FirstClassErrors.sln`
 - Test: `dotnet test FirstClassErrors.sln` (analyzer tests: `dotnet test FirstClassErrors.Analyzers.UnitTests`).
 - Repository language is **English** (code, comments, commits, PRs, issues, and
-  review comments). French lives only in `doc/README.fr.md` and must stay in sync
+  review comments). French lives only in `doc/handwritten/for-users/README.fr.md` and must stay in sync
   with the English README.
 - `Error` and its hierarchy, `ErrorCode`, `ErrorContextKey`, `Outcome`/`Outcome<T>`
   and any value object are **`class`, never `struct`** — a struct exposes a
@@ -21,7 +21,7 @@ Two roles are covered: **writing code** and **reviewing pull requests**.
 ## Architecture decisions (code changes)
 
 Before finalizing a pull request, check it against the ADR base under
-`maintainers/adr/` (format and conventions: `maintainers/adr/README.md`). An ADR
+`doc/handwritten/for-maintainers/adr/` (format and conventions: `doc/handwritten/for-maintainers/adr/README.md`). An ADR
 records a **significant, lasting decision** — one a future maintainer would ask
 "why did they do it this way?" about — not every change. Apply the README's test:
 *if the implementation changed but the decision stood, the ADR should not need
diff --git a/CLAUDE.md b/CLAUDE.md
index 2f1ff3b..c8560f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,7 +10,7 @@ errors should stay structured, documented, and close to the code.
   source code, code comments, commit messages, branch names,
   PR titles and descriptions, and issues.
 * The English documentation is canonical.
-* The French documentation in `doc/README.fr.md` is an intentional translation
+* The French documentation in `doc/handwritten/for-users/README.fr.md` is an intentional translation
   and must stay in sync with the English documentation when user-facing behavior changes.
 * You may reply to me in French in the chat, but never write repository content in French
   unless you are updating the French documentation.
@@ -34,7 +34,7 @@ errors should stay structured, documented, and close to the code.
 * `FirstClassErrors.Cli`           — command-line tool
 * `FirstClassErrors.RequestBinder` — request binder for the primary-adapter boundary (+ `.UnitTests`)
 * `FirstClassErrors.Usage`         — usage examples
-* `doc/`                           — documentation, including the French translation
+* `doc/`                           — documentation: `handwritten/` (`for-users`, `for-maintainers`) and `generated/` (CI/CD living docs)
 
 ## Change guidelines
 
@@ -62,16 +62,16 @@ errors should stay structured, documented, and close to the code.
 
 * When you add or change an error, update its documentation accordingly.
 * When you change user-facing behavior, keep the English README and the French translation
-  (`doc/README.fr.md`) in sync.
+  (`doc/handwritten/for-users/README.fr.md`) in sync.
 * When you change analyzers, update or add analyzer tests.
 * When you change diagnostics, keep diagnostic IDs, messages, documentation, and tests consistent.
 
 ## Architecture decisions (ADRs)
 
 Before finalizing a pull request, check the change against the ADR base under
-`maintainers/adr/`. This is **advisory**: produce a recommendation, never a
+`doc/handwritten/for-maintainers/adr/`. This is **advisory**: produce a recommendation, never a
 blocker. Full procedure in [`AGENTS.md`](AGENTS.md) ("Architecture decisions");
-format and conventions in [`maintainers/adr/README.md`](maintainers/adr/README.md).
+format and conventions in [`doc/handwritten/for-maintainers/adr/README.md`](doc/handwritten/for-maintainers/adr/README.md).
 The essentials, inlined so they hold even if `AGENTS.md` is not read:
 
 * An ADR records a **significant, lasting decision** — one a future maintainer
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 55e9e6f..f450643 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,7 +1,7 @@
 # Contributing to FirstClassErrors
 
 🌍 **Languages:**  
-🇬🇧 English (this file) | 🇫🇷 [Français](./doc/CONTRIBUTING.fr.md)
+🇬🇧 English (this file) | 🇫🇷 [Français](doc/handwritten/for-users/CONTRIBUTING.fr.md)
 
 FirstClassErrors treats errors as first-class, documented, diagnosable
 concepts. The history of the repository should be as legible as the errors the
@@ -473,7 +473,7 @@ Ordered as the rules are: type, scope, description, body, breaking, issue.
 ### Adoption
 
 This guide is the rule for commits in this repository. Deviating from it
-requires a justification — an ADR under `maintainers/adr/`, or an update to this
+requires a justification — an ADR under `doc/handwritten/for-maintainers/adr/`, or an update to this
 guide.
 
 It applies from its adoption on, to every commit created after. Prior history is
diff --git a/FirstClassErrors.Analyzers/HelpLinks.cs b/FirstClassErrors.Analyzers/HelpLinks.cs
index 651f3a4..0d997f5 100644
--- a/FirstClassErrors.Analyzers/HelpLinks.cs
+++ b/FirstClassErrors.Analyzers/HelpLinks.cs
@@ -2,11 +2,11 @@ namespace FirstClassErrors.Analyzers;
 
 /// <summary>
 ///     Builds the documentation URL surfaced by each diagnostic (the "help link" in the IDE). Per-rule pages are added
-///     under <c>doc/analyzers/</c> in a later phase.
+///     under <c>doc/handwritten/for-users/analyzers/</c> in a later phase.
 /// </summary>
 internal static class HelpLinks {
 
-    private const string Base = "https://github.com/Reefact/first-class-errors/blob/main/doc/analyzers";
+    private const string Base = "https://github.com/Reefact/first-class-errors/blob/main/doc/handwritten/for-users/analyzers";
 
     public static string For(string diagnosticId) {
         return $"{Base}/{diagnosticId}.en.md";
diff --git a/FirstClassErrors.Cli/FirstClassErrors.Cli.csproj b/FirstClassErrors.Cli/FirstClassErrors.Cli.csproj
index 59c93a8..e71513c 100644
--- a/FirstClassErrors.Cli/FirstClassErrors.Cli.csproj
+++ b/FirstClassErrors.Cli/FirstClassErrors.Cli.csproj
@@ -110,7 +110,7 @@
        Do NOT rely on `dotnet build` or `dotnet publish` to validate that the tool ships its worker: neither exercises
        the .nupkg content, so both stay green even if the worker never reaches the package. The real gates are the
        worker-present assertion in tools/packaging/pack.sh and the manual tool-install smoke test documented in
-       maintainers/ReleaseDryRun (install the packed tool, run `fce generate`, expect a non-empty catalog). -->
+       doc/handwritten/for-maintainers/ReleaseDryRun (install the packed tool, run `fce generate`, expect a non-empty catalog). -->
   <Target Name="_CopyDocumentationWorker" AfterTargets="Build">
     <ItemGroup>
       <_DocumentationWorkerFiles Include="$(MSBuildThisFileDirectory)..\FirstClassErrors.GenDoc.Worker\bin\$(Configuration)\$(TargetFramework)\**\*.*" />
diff --git a/FirstClassErrors.RequestBinder/README.nuget.md b/FirstClassErrors.RequestBinder/README.nuget.md
index ed368ba..6fc6178 100644
--- a/FirstClassErrors.RequestBinder/README.nuget.md
+++ b/FirstClassErrors.RequestBinder/README.nuget.md
@@ -17,4 +17,4 @@ Outcome<PlaceBookingCommand> command =
     bind.New(s => new PlaceBookingCommand(s.Get(email), s.Get(stay)));
 ```
 
-See the [request-binder guide](https://github.com/Reefact/first-class-errors/blob/main/doc/RequestBinder.en.md) for the full walkthrough, and the [repository documentation](https://github.com/Reefact/first-class-errors) for the rest of FirstClassErrors.
+See the [request-binder guide](https://github.com/Reefact/first-class-errors/blob/main/doc/handwritten/for-users/RequestBinder.en.md) for the full walkthrough, and the [repository documentation](https://github.com/Reefact/first-class-errors) for the rest of FirstClassErrors.
diff --git a/README.md b/README.md
index fdb933a..e6c1ba7 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # FirstClassErrors
 
 🌍 **Languages:**  
-🇬🇧 English (this file) | 🇫🇷 [Français](./doc/README.fr.md)
+🇬🇧 English (this file) | 🇫🇷 [Français](doc/handwritten/for-users/README.fr.md)
 
 |  |  |
 | :-- | :-- |
@@ -15,7 +15,7 @@
 
 **Turn your errors into structured, living knowledge about your system.**
 
-![FirstClassErrors](./doc/images/first-class-errors.png "FirstClassErrors")
+![FirstClassErrors](doc/handwritten/for-users/images/first-class-errors.png "FirstClassErrors")
 
 ## 🚨 The problem
 
@@ -124,7 +124,7 @@ To generate documentation, install the CLI:
 dotnet tool install --global FirstClassErrors.Cli
 ```
 
-Then follow the [Getting Started guide](doc/GettingStarted.en.md) to create and generate your first documented error.
+Then follow the [Getting Started guide](doc/handwritten/for-users/GettingStarted.en.md) to create and generate your first documented error.
 
 ## 🎯 When it is a good fit
 
@@ -135,11 +135,11 @@ FirstClassErrors is especially useful for long-lived application or domain code
 - support and operations investigate production failures;
 - documentation must remain aligned with behavior.
 
-For prototypes, tiny utilities, or low-level technical code, standard exceptions may be enough. See [When Not to Use FirstClassErrors](doc/WhenNotToUseFirstClassErrors.en.md).
+For prototypes, tiny utilities, or low-level technical code, standard exceptions may be enough. See [When Not to Use FirstClassErrors](doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md).
 
 ## 🔍 Analyzers and supply-chain information
 
-The package includes Roslyn rules with stable `FCExxx` identifiers. They detect duplicate or malformed error codes, invalid documentation wiring, missing examples, and common API misuse. See the [analyzer rules reference](doc/analyzers/README.md).
+The package includes Roslyn rules with stable `FCExxx` identifiers. They detect duplicate or malformed error codes, invalid documentation wiring, missing examples, and common API misuse. See the [analyzer rules reference](doc/handwritten/for-users/analyzers/README.md).
 
 Released packages include signed build provenance and an embedded SPDX SBOM. See the release and verification details in the [supply-chain documentation](SECURITY.md).
 
@@ -153,39 +153,39 @@ For security vulnerabilities, follow the private process in [SECURITY.md](SECURI
 
 ### Discover
 
-- [Getting Started](doc/GettingStarted.en.md)
-- [Design Principles](doc/DesignPrinciples.en.md)
-- [When Not to Use FirstClassErrors](doc/WhenNotToUseFirstClassErrors.en.md)
+- [Getting Started](doc/handwritten/for-users/GettingStarted.en.md)
+- [Design Principles](doc/handwritten/for-users/DesignPrinciples.en.md)
+- [When Not to Use FirstClassErrors](doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md)
 
 ### Understand the model
 
-- [Core Concepts](doc/CoreConcepts.en.md)
-- [Error Taxonomy and Composition](doc/ErrorTaxonomy.en.md)
-- [Error Context Guide](doc/ErrorContext.en.md)
+- [Core Concepts](doc/handwritten/for-users/CoreConcepts.en.md)
+- [Error Taxonomy and Composition](doc/handwritten/for-users/ErrorTaxonomy.en.md)
+- [Error Context Guide](doc/handwritten/for-users/ErrorContext.en.md)
 
 ### Write and use errors
 
-- [Writing Errors Guide](doc/WritingErrorsGuide.en.md)
-- [Usage Patterns](doc/UsagePatterns.en.md)
-- [Binding requests at the boundary (RequestBinder)](doc/RequestBinder.en.md)
-- [Best Practices](doc/BestPractices.en.md)
-- [Testing Guide](doc/Testing.en.md)
-  - [Deterministic Error Tests](doc/DeterministicTesting.en.md)
-  - [Arbitrary Test Values](doc/ArbitraryTestValues.en.md)
+- [Writing Errors Guide](doc/handwritten/for-users/WritingErrorsGuide.en.md)
+- [Usage Patterns](doc/handwritten/for-users/UsagePatterns.en.md)
+- [Binding requests at the boundary (RequestBinder)](doc/handwritten/for-users/RequestBinder.en.md)
+- [Best Practices](doc/handwritten/for-users/BestPractices.en.md)
+- [Testing Guide](doc/handwritten/for-users/Testing.en.md)
+  - [Deterministic Error Tests](doc/handwritten/for-users/DeterministicTesting.en.md)
+  - [Arbitrary Test Values](doc/handwritten/for-users/ArbitraryTestValues.en.md)
 
 ### Generate and operate the catalog
 
-- [CI/CD and Operational Integration](doc/OperationalIntegration.en.md)
+- [CI/CD and Operational Integration](doc/handwritten/for-users/OperationalIntegration.en.md)
 - Catalog versioning
-  - [Overview and workflow](doc/CatalogVersioning.en.md)
-  - [Command reference](doc/CatalogVersioningReference.en.md)
-  - [CI/CD integration](doc/CatalogVersioningCI.en.md)
-- [Architecture of the Documentation Pipeline](doc/ArchitectureOfTheDocumentationPipeline.en.md)
-- [Writing a custom renderer](doc/WritingACustomRenderer.en.md)
-- [Internationalization](doc/Internationalization.en.md)
+  - [Overview and workflow](doc/handwritten/for-users/CatalogVersioning.en.md)
+  - [Command reference](doc/handwritten/for-users/CatalogVersioningReference.en.md)
+  - [CI/CD integration](doc/handwritten/for-users/CatalogVersioningCI.en.md)
+- [Architecture of the Documentation Pipeline](doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md)
+- [Writing a custom renderer](doc/handwritten/for-users/WritingACustomRenderer.en.md)
+- [Internationalization](doc/handwritten/for-users/Internationalization.en.md)
 
 ### Evaluate and troubleshoot
 
-- [Comparison with error-handling libraries](doc/ComparisonWithOtherLibraries.en.md)
-- [Analyzer rules (FCExxx)](doc/analyzers/README.md)
-- [FAQ](doc/FAQ.en.md)
+- [Comparison with error-handling libraries](doc/handwritten/for-users/ComparisonWithOtherLibraries.en.md)
+- [Analyzer rules (FCExxx)](doc/handwritten/for-users/analyzers/README.md)
+- [FAQ](doc/handwritten/for-users/FAQ.en.md)
diff --git a/SECURITY.md b/SECURITY.md
index 5155486..277c934 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,7 +1,7 @@
 # Security Policy
 
 🌍 **Languages:**  
-🇬🇧 English (this file) | 🇫🇷 [Français](./doc/SECURITY.fr.md)
+🇬🇧 English (this file) | 🇫🇷 [Français](doc/handwritten/for-users/SECURITY.fr.md)
 
 ## Supported Versions
 
diff --git a/doc/FirstClassErrors.Documentation.csproj b/doc/FirstClassErrors.Documentation.csproj
index b7c492f..cb666b9 100644
--- a/doc/FirstClassErrors.Documentation.csproj
+++ b/doc/FirstClassErrors.Documentation.csproj
@@ -3,11 +3,15 @@
   <!--
     Documentation-only project.
 
-    This project compiles nothing. Its sole purpose is to surface everything
-    under doc/ in the Visual Studio Solution Explorer, so the documentation is
-    easy to find, read and edit right next to the code: the Markdown pages
-    (English *.en.md and French *.fr.md, including the analyzer pages under
-    analyzers/), the images, and any other asset that may be added later.
+    This project compiles nothing. Its sole purpose is to surface every piece of
+    documentation under doc/ in the Visual Studio Solution Explorer, so it is
+    easy to find, read and edit right next to the code. It covers the whole tree:
+
+      doc/generated/    - living documentation produced by CI/CD (e.g. GenDoc)
+      doc/handwritten/  - documentation written by hand
+        for-users/        the library's user documentation (English *.en.md and
+                          French *.fr.md, including the analyzer pages and images)
+        for-maintainers/  the maintainer documentation (ADRs, workflow notes, ...)
 
     The <None> glob below picks up new files automatically: no need to touch
     this project or the solution when documentation is added or renamed. The
@@ -45,10 +49,11 @@
     <!--
       The repository's main README lives at the solution root, outside doc/, so
       the glob above cannot reach it. Reference it as a link so it is browsable
-      from this project too. Link metadata is required for files located outside
+      from this project too, placed next to its French translation under
+      handwritten/for-users. Link metadata is required for files located outside
       the project directory.
     -->
-    <None Include="..\README.md" Link="README.md" />
+    <None Include="..\README.md" Link="handwritten\for-users\README.md" />
   </ItemGroup>
 
 </Project>
diff --git a/doc/generated/README.md b/doc/generated/README.md
new file mode 100644
index 0000000..3f1f7db
--- /dev/null
+++ b/doc/generated/README.md
@@ -0,0 +1,12 @@
+# Generated documentation
+
+This folder holds **living documentation produced automatically by CI/CD**.
+Do not edit its contents by hand: anything here is regenerated (and overwritten)
+on the next generation run.
+
+- [`gendoc/`](gendoc) — error catalog emitted by the GenDoc toolchain
+  (`FirstClassErrors.GenDoc` / `fce generate`).
+
+Handwritten documentation lives under [`../handwritten`](../handwritten):
+[`for-users`](../handwritten/for-users) and
+[`for-maintainers`](../handwritten/for-maintainers).
diff --git a/doc/generated/gendoc/.gitkeep b/doc/generated/gendoc/.gitkeep
new file mode 100644
index 0000000..6889834
--- /dev/null
+++ b/doc/generated/gendoc/.gitkeep
@@ -0,0 +1,2 @@
+# Placeholder so the CI/CD output directory is tracked before the first
+# generation run. GenDoc writes the rendered error catalog here.
diff --git a/maintainers/AddingAReleaseTrain.en.md b/doc/handwritten/for-maintainers/AddingAReleaseTrain.en.md
similarity index 80%
rename from maintainers/AddingAReleaseTrain.en.md
rename to doc/handwritten/for-maintainers/AddingAReleaseTrain.en.md
index e09382a..d1119ee 100644
--- a/maintainers/AddingAReleaseTrain.en.md
+++ b/doc/handwritten/for-maintainers/AddingAReleaseTrain.en.md
@@ -17,7 +17,7 @@ publishes on its own tag prefix. Today there are two:
 | `cli` | `cli-v*` | `cli`, `gendoc` | FirstClassErrors.Cli (the `fce` tool) | `FirstClassErrors.Cli/CHANGELOG.md` |
 
 The train → (prefix, scopes, package, changelog file) mapping lives in **one place**,
-[`tools/trains.sh`](../tools/trains.sh), which the release-notes generator, the
+[`tools/trains.sh`](../../../tools/trains.sh), which the release-notes generator, the
 changelog collector, and the changelog workflow all *source*. The rest of the edits
 below exist only because GitHub workflow triggers and choice inputs, the commit-lint
 scope allowlist, and the packing logic **cannot** be data-driven from that file —
@@ -30,7 +30,7 @@ they are static by nature.
 
 ## The one data edit
 
-**1. Add a row to [`tools/trains.sh`](../tools/trains.sh).** One line, pipe-separated:
+**1. Add a row to [`tools/trains.sh`](../../../tools/trains.sh).** One line, pipe-separated:
 
 ```
 <id>|<tag-prefix>|<scopes csv>|<changelog file>|<package label>
@@ -44,12 +44,12 @@ The scopes must be a subset of the commit-lint allowlist (next step).
 ## The static edits GitHub and the tooling force
 
 **2. Commit scopes** — if the train introduces new scopes, add them to the closed
-list in [`tools/commit-lint/lint-commit-message.sh`](../tools/commit-lint/lint-commit-message.sh)
+list in [`tools/commit-lint/lint-commit-message.sh`](../../../tools/commit-lint/lint-commit-message.sh)
 (`SCOPES` **and** `SCOPES_HUMAN`) and to the scope table in
-[`CONTRIBUTING.md`](../CONTRIBUTING.md). Without this, commits for the new component
+[`CONTRIBUTING.md`](../../../CONTRIBUTING.md). Without this, commits for the new component
 fail the commit-lint check.
 
-**3. [`.github/workflows/release.yml`](../.github/workflows/release.yml)** — three
+**3. [`.github/workflows/release.yml`](../../../.github/workflows/release.yml)** — three
 spots:
 - the tag trigger list: add `- '<prefix>*.*.*'` (e.g. `- 'docs-v*.*.*'`);
 - the `component` `workflow_dispatch` choice: add `- <id>`;
@@ -57,26 +57,26 @@ spots:
   `<prefix>*) COMPONENT="<id>"; VERSION="${REF_NAME#<prefix>}" ;;`, and add `<id>`
   to the `lib|cli)` allowlist `case` just below it.
 
-**4. [`tools/packaging/pack.sh`](../tools/packaging/pack.sh)** — add a `<id>)` branch
+**4. [`tools/packaging/pack.sh`](../../../tools/packaging/pack.sh)** — add a `<id>)` branch
 selecting which projects that train packs. This is genuinely train-specific packing
 logic (which `.csproj` to pack, whether a symbol package ships), so it is not driven
 from `trains.sh`.
 
-**5. [`.github/workflows/release-dryrun.yml`](../.github/workflows/release-dryrun.yml)** —
+**5. [`.github/workflows/release-dryrun.yml`](../../../.github/workflows/release-dryrun.yml)** —
 both rehearsal steps hardcode the train list: add `tools/packaging/pack.sh "$DRYRUN_VERSION" <id>`
 to the *Pack with SBOM* step and `tools/packaging/release-notes.sh <id> HEAD` to the
 *Rehearse release notes* step. Without this the new train's packaging and notes are
 never exercised before a real release — nothing fails, they are simply never run,
 which defeats the dry-run's whole purpose.
 
-**6. [`.github/workflows/changelog.yml`](../.github/workflows/changelog.yml)** — add
+**6. [`.github/workflows/changelog.yml`](../../../.github/workflows/changelog.yml)** — add
 `- <id>` to the `component` `workflow_dispatch` choice `options`. (The workflow reads
 everything else about the train from `trains.sh`.)
 
 ## What happens on its own
 
-- [`tools/packaging/release-notes.sh`](../tools/packaging/release-notes.sh),
-  [`tools/changelog/collect-prs.sh`](../tools/changelog/collect-prs.sh), and the
+- [`tools/packaging/release-notes.sh`](../../../tools/packaging/release-notes.sh),
+  [`tools/changelog/collect-prs.sh`](../../../tools/changelog/collect-prs.sh), and the
   changelog workflow's "Resolve component" step read the new row directly — no edit.
 - The train's **changelog file is created on the first drafting run**
   (`merge-unreleased.sh` lays down the Keep a Changelog preamble if the file is
@@ -99,8 +99,8 @@ everything else about the train from `trains.sh`.)
 
 ## Related
 
-- [`tools/trains.sh`](../tools/trains.sh) — the single source of truth this runbook
+- [`tools/trains.sh`](../../../tools/trains.sh) — the single source of truth this runbook
   is built around.
 - [`changelog`](workflows/changelog.en.md) and [`release`](workflows/release.en.md)
   workflow pages.
-- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — the Conventional Commit scopes.
+- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — the Conventional Commit scopes.
diff --git a/maintainers/AddingAReleaseTrain.fr.md b/doc/handwritten/for-maintainers/AddingAReleaseTrain.fr.md
similarity index 82%
rename from maintainers/AddingAReleaseTrain.fr.md
rename to doc/handwritten/for-maintainers/AddingAReleaseTrain.fr.md
index 4167c18..5a3df6a 100644
--- a/maintainers/AddingAReleaseTrain.fr.md
+++ b/doc/handwritten/for-maintainers/AddingAReleaseTrain.fr.md
@@ -18,7 +18,7 @@ aujourd'hui :
 | `cli` | `cli-v*` | `cli`, `gendoc` | FirstClassErrors.Cli (l'outil `fce`) | `FirstClassErrors.Cli/CHANGELOG.md` |
 
 Le mapping train → (préfixe, scopes, paquet, fichier changelog) vit à **un seul
-endroit**, [`tools/trains.sh`](../tools/trains.sh), que le générateur de notes de
+endroit**, [`tools/trains.sh`](../../../tools/trains.sh), que le générateur de notes de
 release, le collecteur de changelog et le workflow changelog *sourcent* tous. Les
 autres édits ci-dessous n'existent que parce que les triggers et les entrées de
 choix des workflows GitHub, la liste fermée des scopes du commit-lint, et la logique
@@ -33,7 +33,7 @@ nature.
 
 ## L'unique édit de données
 
-**1. Ajoutez une ligne à [`tools/trains.sh`](../tools/trains.sh).** Une ligne, séparée
+**1. Ajoutez une ligne à [`tools/trains.sh`](../../../tools/trains.sh).** Une ligne, séparée
 par des barres verticales :
 
 ```
@@ -49,12 +49,12 @@ autre changement. Les scopes doivent être un sous-ensemble de la liste du commi
 ## Les édits statiques imposés par GitHub et la tooling
 
 **2. Scopes de commit** — si le train introduit de nouveaux scopes, ajoutez-les à la
-liste fermée de [`tools/commit-lint/lint-commit-message.sh`](../tools/commit-lint/lint-commit-message.sh)
+liste fermée de [`tools/commit-lint/lint-commit-message.sh`](../../../tools/commit-lint/lint-commit-message.sh)
 (`SCOPES` **et** `SCOPES_HUMAN`) et au tableau des scopes de
-[`CONTRIBUTING.md`](../CONTRIBUTING.md). Sans ça, les commits du nouveau composant
+[`CONTRIBUTING.md`](../../../CONTRIBUTING.md). Sans ça, les commits du nouveau composant
 échouent au check commit-lint.
 
-**3. [`.github/workflows/release.yml`](../.github/workflows/release.yml)** — trois
+**3. [`.github/workflows/release.yml`](../../../.github/workflows/release.yml)** — trois
 endroits :
 - la liste des triggers de tag : ajoutez `- '<préfixe>*.*.*'` (p. ex. `- 'docs-v*.*.*'`) ;
 - le choix `component` du `workflow_dispatch` : ajoutez `- <id>` ;
@@ -62,12 +62,12 @@ endroits :
   `<préfixe>*) COMPONENT="<id>"; VERSION="${REF_NAME#<préfixe>}" ;;`, et ajoutez
   `<id>` à la liste blanche `lib|cli)` du `case` juste en dessous.
 
-**4. [`tools/packaging/pack.sh`](../tools/packaging/pack.sh)** — ajoutez une branche
+**4. [`tools/packaging/pack.sh`](../../../tools/packaging/pack.sh)** — ajoutez une branche
 `<id>)` sélectionnant quels projets ce train packe. C'est une logique de packaging
 réellement spécifique au train (quel `.csproj` packer, si un package de symboles est
 livré), donc elle n'est pas pilotée par `trains.sh`.
 
-**5. [`.github/workflows/release-dryrun.yml`](../.github/workflows/release-dryrun.yml)** —
+**5. [`.github/workflows/release-dryrun.yml`](../../../.github/workflows/release-dryrun.yml)** —
 les deux étapes de répétition codent la liste des trains en dur : ajoutez
 `tools/packaging/pack.sh "$DRYRUN_VERSION" <id>` à l'étape *Pack with SBOM* et
 `tools/packaging/release-notes.sh <id> HEAD` à l'étape *Rehearse release notes*.
@@ -75,14 +75,14 @@ Sans cela, le packaging et les notes du nouveau train ne sont jamais exercés av
 une vraie release — rien n'échoue, ils ne sont simplement jamais lancés, ce qui
 annule tout l'intérêt du dry-run.
 
-**6. [`.github/workflows/changelog.yml`](../.github/workflows/changelog.yml)** —
+**6. [`.github/workflows/changelog.yml`](../../../.github/workflows/changelog.yml)** —
 ajoutez `- <id>` aux `options` du choix `component` du `workflow_dispatch`. (Le
 workflow lit tout le reste du train depuis `trains.sh`.)
 
 ## Ce qui se fait tout seul
 
-- [`tools/packaging/release-notes.sh`](../tools/packaging/release-notes.sh),
-  [`tools/changelog/collect-prs.sh`](../tools/changelog/collect-prs.sh) et l'étape
+- [`tools/packaging/release-notes.sh`](../../../tools/packaging/release-notes.sh),
+  [`tools/changelog/collect-prs.sh`](../../../tools/changelog/collect-prs.sh) et l'étape
   « Resolve component » du workflow changelog lisent la nouvelle ligne directement —
   aucun édit.
 - Le **fichier changelog du train est créé au premier run de rédaction**
@@ -107,8 +107,8 @@ workflow lit tout le reste du train depuis `trains.sh`.)
 
 ## En rapport
 
-- [`tools/trains.sh`](../tools/trains.sh) — la source unique de vérité autour de
+- [`tools/trains.sh`](../../../tools/trains.sh) — la source unique de vérité autour de
   laquelle ce runbook est construit.
 - Les pages des workflows [`changelog`](workflows/changelog.fr.md) et
   [`release`](workflows/release.fr.md).
-- [`CONTRIBUTING.fr.md`](../doc/CONTRIBUTING.fr.md) — les scopes Conventional Commit.
+- [`CONTRIBUTING.fr.md`](../for-users/CONTRIBUTING.fr.md) — les scopes Conventional Commit.
diff --git a/maintainers/README.fr.md b/doc/handwritten/for-maintainers/README.fr.md
similarity index 90%
rename from maintainers/README.fr.md
rename to doc/handwritten/for-maintainers/README.fr.md
index d76c336..eec1cec 100644
--- a/maintainers/README.fr.md
+++ b/doc/handwritten/for-maintainers/README.fr.md
@@ -5,7 +5,7 @@
 > Documentation pour les **mainteneurs et opérateurs** de FirstClassErrors —
 > comment le projet est construit, publié et maintenu en bonne santé. Elle ne
 > fait **pas** partie de la documentation utilisateur de la librairie, sous
-> [`doc/`](../doc/). La version anglaise est canonique ; les pages françaises sont
+> [`doc/`](../for-users/). La version anglaise est canonique ; les pages françaises sont
 > tenues à jour en parallèle.
 
 ## Sommaire
@@ -30,7 +30,7 @@ ces workflows structurellement. Aussi en [anglais](ReleaseDryRun.en.md).
 ### [Ajouter un train de release](AddingAReleaseTrain.fr.md)
 
 La checklist pour ajouter un nouveau paquet versionné indépendamment : l'unique
-édit de données dans [`tools/trains.sh`](../tools/trains.sh) et les édits statiques
+édit de données dans [`tools/trains.sh`](../../../tools/trains.sh) et les édits statiques
 imposés par GitHub et la tooling (trigger de tag, options de choix, scopes du
 commit-lint, packaging). Aussi en [anglais](AddingAReleaseTrain.en.md).
 
@@ -51,5 +51,5 @@ copier. *(En anglais uniquement.)*
 
 ## En rapport
 
-- [`CONTRIBUTING.fr.md`](../doc/CONTRIBUTING.fr.md) — conventions de commit et de pull
+- [`CONTRIBUTING.fr.md`](../for-users/CONTRIBUTING.fr.md) — conventions de commit et de pull
   request (imposées par le workflow [`commit-lint`](workflows/commit-lint.fr.md)).
diff --git a/maintainers/README.md b/doc/handwritten/for-maintainers/README.md
similarity index 89%
rename from maintainers/README.md
rename to doc/handwritten/for-maintainers/README.md
index f041feb..0bfa181 100644
--- a/maintainers/README.md
+++ b/doc/handwritten/for-maintainers/README.md
@@ -4,7 +4,7 @@
 
 > Documentation for **maintainers and operators** of FirstClassErrors — how the
 > project is built, released, and kept healthy. It is **not** part of the
-> library's user documentation, which lives under [`doc/`](../doc/). The English
+> library's user documentation, which lives under [`doc/`](../for-users/). The English
 > version is canonical; the French pages are kept in sync.
 
 ## Contents
@@ -28,7 +28,7 @@ workflows structurally. Also in [French](ReleaseDryRun.fr.md).
 ### [Adding a release train](AddingAReleaseTrain.en.md)
 
 The checklist for adding a new independently-versioned package: the single data
-edit in [`tools/trains.sh`](../tools/trains.sh) and the static edits GitHub and the
+edit in [`tools/trains.sh`](../../../tools/trains.sh) and the static edits GitHub and the
 tooling force (tag trigger, choice options, commit-lint scopes, packing). Also in
 [French](AddingAReleaseTrain.fr.md).
 
@@ -48,5 +48,5 @@ follows and provides a copy-ready [template](adr/template.md). *(English only.)*
 
 ## Related
 
-- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — commit and pull-request conventions
+- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — commit and pull-request conventions
   (enforced by the [`commit-lint`](workflows/commit-lint.en.md) workflow).
diff --git a/maintainers/ReleaseDryRun.en.md b/doc/handwritten/for-maintainers/ReleaseDryRun.en.md
similarity index 100%
rename from maintainers/ReleaseDryRun.en.md
rename to doc/handwritten/for-maintainers/ReleaseDryRun.en.md
diff --git a/maintainers/ReleaseDryRun.fr.md b/doc/handwritten/for-maintainers/ReleaseDryRun.fr.md
similarity index 100%
rename from maintainers/ReleaseDryRun.fr.md
rename to doc/handwritten/for-maintainers/ReleaseDryRun.fr.md
diff --git a/maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md b/doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md
similarity index 99%
rename from maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md
rename to doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md
index 220eb98..85dfdbf 100644
--- a/maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md
+++ b/doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.fr.md
@@ -176,7 +176,7 @@ version de référence reste au floor.
      `tools/floor-check/global.json` imbriqué) vers le SDK dont le Roslyn
      correspond au nouveau floor.
   3. Mettre à jour la note d'exigence de compilateur du README /
-     `doc/README.fr.md`.
+     `doc/handwritten/for-users/README.fr.md`.
   4. Remplacer cet ADR (nouveau floor, nouveau SDK/IDE minimum).
 
   L'épinglage, le test unitaire et l'ignore Dependabot ne nécessitent aucun
diff --git a/maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md b/doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md
similarity index 98%
rename from maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md
rename to doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md
index c32dade..a39b2fd 100644
--- a/maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md
+++ b/doc/handwritten/for-maintainers/adr/0001-lock-the-analyzer-roslyn-floor.md
@@ -160,7 +160,7 @@ which can break while every reference version stays at the floor.
   2. Update the floor SDK in `analyzers.yml` (`dotnet-version` and the nested
      `tools/floor-check/global.json`) to the SDK whose Roslyn matches the new
      floor.
-  3. Update the README / `doc/README.fr.md` compiler-requirement note.
+  3. Update the README / `doc/handwritten/for-users/README.fr.md` compiler-requirement note.
   4. Supersede this ADR (new floor, new minimum SDK/IDE).
 
   The pin, the unit test and the Dependabot ignore need no change — they all
diff --git a/maintainers/adr/0002-floor-the-tooling-runtime.fr.md b/doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.fr.md
similarity index 100%
rename from maintainers/adr/0002-floor-the-tooling-runtime.fr.md
rename to doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.fr.md
diff --git a/maintainers/adr/0002-floor-the-tooling-runtime.md b/doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.md
similarity index 100%
rename from maintainers/adr/0002-floor-the-tooling-runtime.md
rename to doc/handwritten/for-maintainers/adr/0002-floor-the-tooling-runtime.md
diff --git a/maintainers/adr/0003-unify-outcome-value-mapping-under-then.fr.md b/doc/handwritten/for-maintainers/adr/0003-unify-outcome-value-mapping-under-then.fr.md
similarity index 100%
rename from maintainers/adr/0003-unify-outcome-value-mapping-under-then.fr.md
rename to doc/handwritten/for-maintainers/adr/0003-unify-outcome-value-mapping-under-then.fr.md
diff --git a/maintainers/adr/0003-unify-outcome-value-mapping-under-then.md b/doc/handwritten/for-maintainers/adr/0003-unify-outcome-value-mapping-under-then.md
similarity index 100%
rename from maintainers/adr/0003-unify-outcome-value-mapping-under-then.md
rename to doc/handwritten/for-maintainers/adr/0003-unify-outcome-value-mapping-under-then.md
diff --git a/maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md b/doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md
similarity index 99%
rename from maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md
rename to doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md
index 6e28456..c834d51 100644
--- a/maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md
+++ b/doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.fr.md
@@ -8,7 +8,7 @@
 
 ## Contexte
 
-Le dépôt consigne les décisions importantes sous forme d'ADR dans `maintainers/adr/`,
+Le dépôt consigne les décisions importantes sous forme d'ADR dans `doc/handwritten/for-maintainers/adr/`,
 mais rien ne confronte un changement à cette base au moment où le changement est
 réalisé. C'est dans une pull request que les nouvelles décisions entrent dans la base
 de code : elle peut embarquer une décision qui n'est jamais consignée, remplacer une
diff --git a/maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md b/doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md
similarity index 98%
rename from maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md
rename to doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md
index f954449..7223222 100644
--- a/maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md
+++ b/doc/handwritten/for-maintainers/adr/0004-check-every-pull-request-against-the-adr-base.md
@@ -8,7 +8,7 @@
 
 ## Context
 
-The repository records significant decisions as ADRs under `maintainers/adr/`, but
+The repository records significant decisions as ADRs under `doc/handwritten/for-maintainers/adr/`, but
 nothing confronts a change with that base at the moment the change is made. A pull
 request is where new decisions enter the codebase: it can embark a decision that is
 never recorded, replace a decision an existing ADR holds without saying so, or
diff --git a/maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md b/doc/handwritten/for-maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md
similarity index 100%
rename from maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md
rename to doc/handwritten/for-maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.fr.md
diff --git a/maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md b/doc/handwritten/for-maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md
similarity index 100%
rename from maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md
rename to doc/handwritten/for-maintainers/adr/0005-reserve-the-plain-factory-name-for-the-outcome-returning-variant.md
diff --git a/maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md b/doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md
similarity index 99%
rename from maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md
rename to doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md
index 415d885..f8adfc7 100644
--- a/maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md
+++ b/doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.fr.md
@@ -180,7 +180,7 @@ principal.
 
 ## Références
 
-* `doc/ArbitraryTestValues.en.md` — le guide où la nouvelle surface est
+* `doc/handwritten/for-users/ArbitraryTestValues.en.md` — le guide où la nouvelle surface est
   documentée.
 * ADR-0005 — décision de nommage antérieure dans le même esprit (un nom devrait
   annoncer ce que fait un appel) ; contexte seulement, pas un précédent pour ce
diff --git a/maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md b/doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md
similarity index 98%
rename from maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md
rename to doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md
index d580568..71e8966 100644
--- a/maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md
+++ b/doc/handwritten/for-maintainers/adr/0006-supply-arbitrary-test-values-from-a-seedable-source.md
@@ -155,6 +155,6 @@ ship test-only surface in the main package.
 
 ## References
 
-* `doc/ArbitraryTestValues.en.md` — the guide where the new surface is documented.
+* `doc/handwritten/for-users/ArbitraryTestValues.en.md` — the guide where the new surface is documented.
 * ADR-0005 — prior naming decision in the same spirit (a name should announce
   what a call does); context only, not a precedent for this choice.
diff --git a/maintainers/adr/0007-name-the-binder-terminals-new-and-create.fr.md b/doc/handwritten/for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.fr.md
similarity index 100%
rename from maintainers/adr/0007-name-the-binder-terminals-new-and-create.fr.md
rename to doc/handwritten/for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.fr.md
diff --git a/maintainers/adr/0007-name-the-binder-terminals-new-and-create.md b/doc/handwritten/for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.md
similarity index 100%
rename from maintainers/adr/0007-name-the-binder-terminals-new-and-create.md
rename to doc/handwritten/for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.md
diff --git a/maintainers/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md b/doc/handwritten/for-maintainers/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md
similarity index 100%
rename from maintainers/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md
rename to doc/handwritten/for-maintainers/adr/0008-bind-nullable-value-type-properties-through-a-struct-constrained-overload.md
diff --git a/maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md b/doc/handwritten/for-maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md
similarity index 100%
rename from maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md
rename to doc/handwritten/for-maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.fr.md
diff --git a/maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.md b/doc/handwritten/for-maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.md
similarity index 100%
rename from maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.md
rename to doc/handwritten/for-maintainers/adr/0009-report-the-toolings-failures-as-first-class-errors.md
diff --git a/maintainers/adr/README.md b/doc/handwritten/for-maintainers/adr/README.md
similarity index 97%
rename from maintainers/adr/README.md
rename to doc/handwritten/for-maintainers/adr/README.md
index ed79960..032fa55 100644
--- a/maintainers/adr/README.md
+++ b/doc/handwritten/for-maintainers/adr/README.md
@@ -15,7 +15,7 @@ the implementation changed but the decision stood, the ADR should not need
 editing.* A new decision is **recorded** here, a decision that replaces another is
 written as a **superseding** ADR, and a change that **conflicts** with an accepted
 ADR is raised for the maintainer. The agent procedure — draft as *Proposed*, never
-flip a status unilaterally — is in [`AGENTS.md`](../../AGENTS.md).
+flip a status unilaterally — is in [`AGENTS.md`](../../../../AGENTS.md).
 
 ## An ADR is a decision record, not a specification
 
@@ -32,7 +32,7 @@ need editing.
 
 ## File conventions
 
-* One file per decision, under `maintainers/adr/`, named
+* One file per decision, under `doc/handwritten/for-maintainers/adr/`, named
   `NNNN-short-title.md` — a four-digit sequence number and a lowercase,
   kebab-case title: `0001-lock-the-analyzer-roslyn-floor.md`.
 * ADRs are written in **English** — the canonical version — with a French
diff --git a/maintainers/adr/template.md b/doc/handwritten/for-maintainers/adr/template.md
similarity index 97%
rename from maintainers/adr/template.md
rename to doc/handwritten/for-maintainers/adr/template.md
index d5593b1..404468e 100644
--- a/maintainers/adr/template.md
+++ b/doc/handwritten/for-maintainers/adr/template.md
@@ -6,7 +6,7 @@
      specification: it lives in the code and the reference docs (e.g. the
      workflow reference), which this ADR links to. Test: if the implementation
      changed but the decision stood, this ADR should not need editing.
-     See maintainers/adr/README.md. -->
+     See doc/handwritten/for-maintainers/adr/README.md. -->
 
 **Status:** Proposed
 **Date:** YYYY-MM-DD
diff --git a/maintainers/workflows/README.fr.md b/doc/handwritten/for-maintainers/workflows/README.fr.md
similarity index 97%
rename from maintainers/workflows/README.fr.md
rename to doc/handwritten/for-maintainers/workflows/README.fr.md
index 9f752cb..b98192e 100644
--- a/maintainers/workflows/README.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/README.fr.md
@@ -10,7 +10,7 @@
 
 ## De quoi il s'agit
 
-Chaque workflow sous [`.github/workflows/`](../../.github/workflows/) porte une
+Chaque workflow sous [`.github/workflows/`](../../../../.github/workflows/) porte une
 intention qu'il est facile de casser en « faisant le ménage » : une permission
 volontairement étroite, un ordre d'étapes qui protège d'une panne précise, une
 version gelée pour une raison produit. Les fichiers de workflow eux-mêmes
@@ -101,5 +101,5 @@ documentées une seule fois ici plutôt que répétées sur chaque page.
 - [ADR 0001 — Verrouiller le floor Roslyn de l'analyzer](../adr/0001-lock-the-analyzer-roslyn-floor.md)
   — pourquoi la version de Roslyn de l'analyzer est gelée, ce que le workflow
   `analyzers` fait respecter. *(Rédigé en anglais.)*
-- [`CONTRIBUTING.fr.md`](../../doc/CONTRIBUTING.fr.md) — les conventions de commit et de PR
+- [`CONTRIBUTING.fr.md`](../../for-users/CONTRIBUTING.fr.md) — les conventions de commit et de PR
   que le workflow `commit-lint` vérifie.
diff --git a/maintainers/workflows/README.md b/doc/handwritten/for-maintainers/workflows/README.md
similarity index 96%
rename from maintainers/workflows/README.md
rename to doc/handwritten/for-maintainers/workflows/README.md
index 13955a7..b6c8c57 100644
--- a/maintainers/workflows/README.md
+++ b/doc/handwritten/for-maintainers/workflows/README.md
@@ -10,7 +10,7 @@
 
 ## What this is
 
-Each workflow under [`.github/workflows/`](../../.github/workflows/) carries a
+Each workflow under [`.github/workflows/`](../../../../.github/workflows/) carries a
 fair amount of intent that is easy to break by "cleaning it up": a permission
 that is narrow on purpose, a step ordering that guards a specific failure, a
 version that is frozen for a product reason. The workflow files themselves hold
@@ -97,5 +97,5 @@ here instead of being repeated on every page.
 - [ADR 0001 — Lock the analyzer Roslyn floor](../adr/0001-lock-the-analyzer-roslyn-floor.md)
   — why the analyzer's Roslyn version is frozen, which the `analyzers` workflow
   enforces.
-- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — the commit and PR conventions the
+- [`CONTRIBUTING.md`](../../../../CONTRIBUTING.md) — the commit and PR conventions the
   `commit-lint` workflow checks.
diff --git a/maintainers/workflows/adr-check.en.md b/doc/handwritten/for-maintainers/workflows/adr-check.en.md
similarity index 90%
rename from maintainers/workflows/adr-check.en.md
rename to doc/handwritten/for-maintainers/workflows/adr-check.en.md
index 78896a4..0d835ba 100644
--- a/maintainers/workflows/adr-check.en.md
+++ b/doc/handwritten/for-maintainers/workflows/adr-check.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/adr-check.yml`](../../.github/workflows/adr-check.yml)
+**Workflow file:** [`.github/workflows/adr-check.yml`](../../../../.github/workflows/adr-check.yml)
 
 ## What it is for
 
@@ -13,7 +13,7 @@
 an architectural decision the project records as an [ADR](../adr/README.md). It is
 the **manual fallback** for a contributor **without Claude Code** — whose coding
 session performs the same check automatically (see
-[`AGENTS.md`](../../AGENTS.md) → "Architecture decisions"). Same three outcomes,
+[`AGENTS.md`](../../../../AGENTS.md) → "Architecture decisions"). Same three outcomes,
 run on demand from the Actions tab instead of inside a session.
 
 It is **advisory**: it **never blocks** anything and **never writes an ADR**. It
@@ -48,11 +48,11 @@ One job, `adr-check`:
 3. Resolve `base` into the branch's **fork point** (`git merge-base`), so the diff
    is exactly what the branch introduces.
 4. **Collect context** with
-   [`tools/adr-check/collect-context.sh`](../../tools/adr-check/collect-context.sh):
+   [`tools/adr-check/collect-context.sh`](../../../../tools/adr-check/collect-context.sh):
    the changed-file list and the unified diff (from `git`, byte-capped) plus the
    current ADR base (index and each ADR, byte-capped), as one delimited bundle.
 5. **Ask the model** under
-   [`.github/adr-check-prompt.md`](../../.github/adr-check-prompt.md), which defines
+   [`.github/adr-check-prompt.md`](../../../../.github/adr-check-prompt.md), which defines
    the three outcomes, biases hard toward silence, and requires a single JSON
    verdict `{ analysis, needs_report, outcomes, report }`.
 6. **Write the verdict to the run summary** (`$GITHUB_STEP_SUMMARY`) — the primary
@@ -61,7 +61,7 @@ One job, `adr-check`:
 7. **Mirror it to the pull request, if one is open** for the branch: when
    `needs_report` is true the report is posted (or refreshed) as the single comment
    found by the hidden `<!-- adr-check -->` marker, via
-   [`tools/adr-check/upsert-comment.sh`](../../tools/adr-check/upsert-comment.sh);
+   [`tools/adr-check/upsert-comment.sh`](../../../../tools/adr-check/upsert-comment.sh);
    when false, any stale comment is removed. With no open pull request, the summary
    is the only output.
 
@@ -104,7 +104,7 @@ is open — it writes nothing to the repository.
 
 ## Related
 
-- [`AGENTS.md`](../../AGENTS.md) — the code-authoring agent's own ADR check, run
+- [`AGENTS.md`](../../../../AGENTS.md) — the code-authoring agent's own ADR check, run
   automatically in a Claude Code session; this workflow is its manual counterpart
   for contributors without Claude Code.
 - [ADR reference](../adr/README.md) — the format, conventions, and "when is an ADR
diff --git a/maintainers/workflows/adr-check.fr.md b/doc/handwritten/for-maintainers/workflows/adr-check.fr.md
similarity index 92%
rename from maintainers/workflows/adr-check.fr.md
rename to doc/handwritten/for-maintainers/workflows/adr-check.fr.md
index 3e0d9f6..b1688f2 100644
--- a/maintainers/workflows/adr-check.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/adr-check.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/adr-check.yml`](../../.github/workflows/adr-check.yml)
+**Fichier du workflow :** [`.github/workflows/adr-check.yml`](../../../../.github/workflows/adr-check.yml)
 
 ## À quoi il sert
 
@@ -13,7 +13,7 @@
 une décision d'architecture que le projet consigne en [ADR](../adr/README.md).
 C'est le **repli manuel** pour un contributeur **sans Claude Code** — dont la
 session de codage effectue le même contrôle automatiquement (voir
-[`AGENTS.md`](../../AGENTS.md) → « Architecture decisions »). Les trois mêmes issues,
+[`AGENTS.md`](../../../../AGENTS.md) → « Architecture decisions »). Les trois mêmes issues,
 lancées à la demande depuis l'onglet Actions au lieu de l'être dans une session.
 
 Il est **consultatif** : il **ne bloque jamais** rien et **n'écrit jamais d'ADR**.
@@ -49,12 +49,12 @@ Un seul job, `adr-check` :
 3. Résout `base` en le **point de divergence** de la branche (`git merge-base`), pour
    que le diff soit exactement ce que la branche introduit.
 4. **Collecte le contexte** avec
-   [`tools/adr-check/collect-context.sh`](../../tools/adr-check/collect-context.sh) :
+   [`tools/adr-check/collect-context.sh`](../../../../tools/adr-check/collect-context.sh) :
    la liste des fichiers modifiés et le diff unifié (via `git`, plafonné en octets)
    plus la base d'ADR courante (index et chaque ADR, plafonnée en octets), en un seul
    paquet délimité.
 5. **Interroge le modèle** sous
-   [`.github/adr-check-prompt.md`](../../.github/adr-check-prompt.md), qui définit les
+   [`.github/adr-check-prompt.md`](../../../../.github/adr-check-prompt.md), qui définit les
    trois issues, pousse fortement vers le silence, et exige un unique verdict JSON
    `{ analysis, needs_report, outcomes, report }`.
 6. **Écrit le verdict dans le résumé de run** (`$GITHUB_STEP_SUMMARY`) — la sortie
@@ -63,7 +63,7 @@ Un seul job, `adr-check` :
 7. **Le reflète sur la pull request, s'il y en a une d'ouverte** pour la branche :
    quand `needs_report` est vrai, le rapport est posté (ou rafraîchi) comme l'unique
    commentaire repéré par le marqueur caché `<!-- adr-check -->`, via
-   [`tools/adr-check/upsert-comment.sh`](../../tools/adr-check/upsert-comment.sh) ;
+   [`tools/adr-check/upsert-comment.sh`](../../../../tools/adr-check/upsert-comment.sh) ;
    quand c'est faux, le commentaire qui traîne est retiré. Sans pull request ouverte,
    le résumé est la seule sortie.
 
@@ -108,7 +108,7 @@ pull request est ouverte — il n'écrit rien dans le dépôt.
 
 ## En rapport
 
-- [`AGENTS.md`](../../AGENTS.md) — le contrôle ADR propre à l'agent qui écrit le code,
+- [`AGENTS.md`](../../../../AGENTS.md) — le contrôle ADR propre à l'agent qui écrit le code,
   lancé automatiquement dans une session Claude Code ; ce workflow en est le pendant
   manuel pour les contributeurs sans Claude Code.
 - [Référence des ADR](../adr/README.md) — le format, les conventions et la note
diff --git a/maintainers/workflows/analyzers.en.md b/doc/handwritten/for-maintainers/workflows/analyzers.en.md
similarity index 98%
rename from maintainers/workflows/analyzers.en.md
rename to doc/handwritten/for-maintainers/workflows/analyzers.en.md
index 7fbfdef..79c5d63 100644
--- a/maintainers/workflows/analyzers.en.md
+++ b/doc/handwritten/for-maintainers/workflows/analyzers.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/analyzers.yml`](../../.github/workflows/analyzers.yml)
+**Workflow file:** [`.github/workflows/analyzers.yml`](../../../../.github/workflows/analyzers.yml)
 
 ## What it is for
 
diff --git a/maintainers/workflows/analyzers.fr.md b/doc/handwritten/for-maintainers/workflows/analyzers.fr.md
similarity index 99%
rename from maintainers/workflows/analyzers.fr.md
rename to doc/handwritten/for-maintainers/workflows/analyzers.fr.md
index e7c1bb6..e31138e 100644
--- a/maintainers/workflows/analyzers.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/analyzers.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/analyzers.yml`](../../.github/workflows/analyzers.yml)
+**Fichier du workflow :** [`.github/workflows/analyzers.yml`](../../../../.github/workflows/analyzers.yml)
 
 ## À quoi il sert
 
diff --git a/maintainers/workflows/changelog.en.md b/doc/handwritten/for-maintainers/workflows/changelog.en.md
similarity index 90%
rename from maintainers/workflows/changelog.en.md
rename to doc/handwritten/for-maintainers/workflows/changelog.en.md
index 7259cde..b9c8999 100644
--- a/maintainers/workflows/changelog.en.md
+++ b/doc/handwritten/for-maintainers/workflows/changelog.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/changelog.yml`](../../.github/workflows/changelog.yml)
+**Workflow file:** [`.github/workflows/changelog.yml`](../../../../.github/workflows/changelog.yml)
 
 ## What it is for
 
@@ -15,7 +15,7 @@ with the result. It never publishes anything and never writes to a released
 section — it produces a **draft for a human to review and merge**.
 
 It fills a gap the [`release`](release.en.md) path leaves open.
-[`tools/packaging/release-notes.sh`](../../tools/packaging/release-notes.sh)
+[`tools/packaging/release-notes.sh`](../../../../tools/packaging/release-notes.sh)
 already generates the GitHub Release body, but those notes are **commit-oriented
 and raw** ("`- feat(core): … (abc1234)`"), scoped to one train. This workflow
 produces the complementary artifact: a **narrative, user-facing changelog** in
@@ -27,8 +27,8 @@ The two trains version independently and keep **separate** changelog files:
 
 | Train | Scopes | Changelog file |
 | --- | --- | --- |
-| `lib` | `core`, `analyzers`, `testing` | [`CHANGELOG.md`](../../CHANGELOG.md) |
-| `cli` | `cli`, `gendoc` | [`FirstClassErrors.Cli/CHANGELOG.md`](../../FirstClassErrors.Cli/CHANGELOG.md) |
+| `lib` | `core`, `analyzers`, `testing` | [`CHANGELOG.md`](../../../../CHANGELOG.md) |
+| `cli` | `cli`, `gendoc` | [`FirstClassErrors.Cli/CHANGELOG.md`](../../../../FirstClassErrors.Cli/CHANGELOG.md) |
 
 ## When it runs
 
@@ -50,7 +50,7 @@ One job, `draft-changelog`:
    with **`fetch-depth: 0`** — the train's previous tag (and its commit
    timestamp, the lower bound of the pull-request range) must resolve.
 2. **Collect** the train's pull requests with
-   [`tools/changelog/collect-prs.sh`](../../tools/changelog/collect-prs.sh):
+   [`tools/changelog/collect-prs.sh`](../../../../tools/changelog/collect-prs.sh):
    `gh pr list` gathers the candidates merged into `main` after the tag's commit
    time, then each candidate is kept only if one of **its commits' Conventional
    Commit scopes** falls in the train's set. This is the **same partition
@@ -59,10 +59,10 @@ One job, `draft-changelog`:
    `chore:` / `docs:`) belong to neither train and are dropped from both.
 3. **Draft** the entry: the merged PRs (number, title, body, labels, author) are
    sent to the Anthropic API under
-   [`.github/changelog-prompt.md`](../../.github/changelog-prompt.md), which
+   [`.github/changelog-prompt.md`](../../../../.github/changelog-prompt.md), which
    instructs the model to group the changes and **invent nothing**.
 4. **Merge** the drafted block into the train's changelog file with
-   [`tools/changelog/merge-unreleased.sh`](../../tools/changelog/merge-unreleased.sh),
+   [`tools/changelog/merge-unreleased.sh`](../../../../tools/changelog/merge-unreleased.sh),
    which **replaces** the `[Unreleased]` section in place.
 5. **Open** (or refresh) a pull request from
    `github-actions/changelog-<component>-draft` via `gh`, for review. The refresh
@@ -86,7 +86,7 @@ to a pull request from a fork — the key is never exposed to fork PRs.
 
 ## Handle with care
 
-- **The train partition lives in one place: [`tools/trains.sh`](../../tools/trains.sh).**
+- **The train partition lives in one place: [`tools/trains.sh`](../../../../tools/trains.sh).**
   `collect-prs.sh`, `release-notes.sh` and this workflow all *source* it, so the
   changelog and the GitHub Release notes can never disagree on which scopes belong
   to which train (`lib` → core/analyzers/testing, `cli` → cli/gendoc). Add a train,
@@ -141,8 +141,8 @@ to a pull request from a fork — the key is never exposed to fork PRs.
 - [`release`](release.en.md) — the tag-driven publish, whose
   `release-notes.sh` produces the raw, commit-oriented GitHub Release body this
   changelog complements.
-- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — the Conventional Commit **scopes**
+- [`CONTRIBUTING.md`](../../../../CONTRIBUTING.md) — the Conventional Commit **scopes**
   the train partition is built on.
-- The two changelog files: [`CHANGELOG.md`](../../CHANGELOG.md) (lib) and
-  [`FirstClassErrors.Cli/CHANGELOG.md`](../../FirstClassErrors.Cli/CHANGELOG.md)
+- The two changelog files: [`CHANGELOG.md`](../../../../CHANGELOG.md) (lib) and
+  [`FirstClassErrors.Cli/CHANGELOG.md`](../../../../FirstClassErrors.Cli/CHANGELOG.md)
   (cli).
diff --git a/maintainers/workflows/changelog.fr.md b/doc/handwritten/for-maintainers/workflows/changelog.fr.md
similarity index 92%
rename from maintainers/workflows/changelog.fr.md
rename to doc/handwritten/for-maintainers/workflows/changelog.fr.md
index 74656c0..589835d 100644
--- a/maintainers/workflows/changelog.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/changelog.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/changelog.yml`](../../.github/workflows/changelog.yml)
+**Fichier du workflow :** [`.github/workflows/changelog.yml`](../../../../.github/workflows/changelog.yml)
 
 ## À quoi il sert
 
@@ -15,7 +15,7 @@ pull request avec le résultat. Il ne publie jamais rien et n'écrit jamais dans
 section déjà publiée — il produit un **brouillon qu'un humain relit et merge**.
 
 Il comble un manque que le chemin [`release`](release.fr.md) laisse ouvert.
-[`tools/packaging/release-notes.sh`](../../tools/packaging/release-notes.sh)
+[`tools/packaging/release-notes.sh`](../../../../tools/packaging/release-notes.sh)
 génère déjà le corps de la GitHub Release, mais ces notes sont **orientées commits
 et brutes** (« `- feat(core): … (abc1234)` »), cantonnées à un train. Ce workflow
 produit l'artefact complémentaire : un **changelog narratif, orienté utilisateur**,
@@ -28,8 +28,8 @@ changelog **distincts** :
 
 | Train | Scopes | Fichier de changelog |
 | --- | --- | --- |
-| `lib` | `core`, `analyzers`, `testing` | [`CHANGELOG.md`](../../CHANGELOG.md) |
-| `cli` | `cli`, `gendoc` | [`FirstClassErrors.Cli/CHANGELOG.md`](../../FirstClassErrors.Cli/CHANGELOG.md) |
+| `lib` | `core`, `analyzers`, `testing` | [`CHANGELOG.md`](../../../../CHANGELOG.md) |
+| `cli` | `cli`, `gendoc` | [`FirstClassErrors.Cli/CHANGELOG.md`](../../../../FirstClassErrors.Cli/CHANGELOG.md) |
 
 ## Quand il s'exécute
 
@@ -54,7 +54,7 @@ Un seul job, `draft-changelog` :
    (et l'horodatage de son commit, la borne basse de la plage de pull requests)
    doit se résoudre.
 2. **Collecter** les pull requests du train avec
-   [`tools/changelog/collect-prs.sh`](../../tools/changelog/collect-prs.sh) :
+   [`tools/changelog/collect-prs.sh`](../../../../tools/changelog/collect-prs.sh) :
    `gh pr list` rassemble les candidates mergées dans `main` après l'heure du
    commit taggé, puis chaque candidate n'est conservée que si l'un des **scopes
    Conventional Commit de ses commits** tombe dans l'ensemble du train. C'est la
@@ -64,10 +64,10 @@ Un seul job, `draft-changelog` :
    écartées des deux.
 3. **Rédiger** l'entrée : les PR mergées (numéro, titre, corps, labels, auteur)
    sont envoyées à l'API Anthropic sous
-   [`.github/changelog-prompt.md`](../../.github/changelog-prompt.md), qui demande
+   [`.github/changelog-prompt.md`](../../../../.github/changelog-prompt.md), qui demande
    au modèle de grouper les changements et de **n'inventer rien**.
 4. **Fusionner** le bloc rédigé dans le fichier de changelog du train avec
-   [`tools/changelog/merge-unreleased.sh`](../../tools/changelog/merge-unreleased.sh),
+   [`tools/changelog/merge-unreleased.sh`](../../../../tools/changelog/merge-unreleased.sh),
    qui **remplace** la section `[Unreleased]` sur place.
 5. **Ouvrir** (ou rafraîchir) une pull request depuis
    `github-actions/changelog-<component>-draft` via `gh`, pour relecture. Le
@@ -93,7 +93,7 @@ exposée aux PR de forks.
 
 ## À manipuler avec précaution
 
-- **La partition par train vit à un seul endroit : [`tools/trains.sh`](../../tools/trains.sh).**
+- **La partition par train vit à un seul endroit : [`tools/trains.sh`](../../../../tools/trains.sh).**
   `collect-prs.sh`, `release-notes.sh` et ce workflow le *sourcent* tous, donc le
   changelog et les notes de release GitHub ne peuvent jamais diverger sur quels
   scopes appartiennent à quel train (`lib` → core/analyzers/testing, `cli` →
@@ -154,8 +154,8 @@ exposée aux PR de forks.
 - [`release`](release.fr.md) — la publication pilotée par tag, dont le
   `release-notes.sh` produit le corps de GitHub Release brut et orienté commits que
   ce changelog complète.
-- [`CONTRIBUTING.fr.md`](../../doc/CONTRIBUTING.fr.md) — les **scopes** Conventional
+- [`CONTRIBUTING.fr.md`](../../for-users/CONTRIBUTING.fr.md) — les **scopes** Conventional
   Commit sur lesquels repose la partition par train.
-- Les deux fichiers de changelog : [`CHANGELOG.md`](../../CHANGELOG.md) (lib) et
-  [`FirstClassErrors.Cli/CHANGELOG.md`](../../FirstClassErrors.Cli/CHANGELOG.md)
+- Les deux fichiers de changelog : [`CHANGELOG.md`](../../../../CHANGELOG.md) (lib) et
+  [`FirstClassErrors.Cli/CHANGELOG.md`](../../../../FirstClassErrors.Cli/CHANGELOG.md)
   (cli).
diff --git a/maintainers/workflows/ci.en.md b/doc/handwritten/for-maintainers/workflows/ci.en.md
similarity index 93%
rename from maintainers/workflows/ci.en.md
rename to doc/handwritten/for-maintainers/workflows/ci.en.md
index 4e0db25..ca3c7bf 100644
--- a/maintainers/workflows/ci.en.md
+++ b/doc/handwritten/for-maintainers/workflows/ci.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml)
+**Workflow file:** [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml)
 
 ## What it is for
 
@@ -40,7 +40,7 @@ On a `[ubuntu-latest, windows-latest]` matrix:
 1. Checkout, then set up the .NET SDK.
 2. `dotnet restore` → `dotnet build -c Release` → `dotnet test -c Release`.
 3. Tests collect OpenCover coverage via `coverlet.collector`, configured by
-   [`coverage.runsettings`](../../coverage.runsettings), into
+   [`coverage.runsettings`](../../../../coverage.runsettings), into
    `artifacts/coverage/<guid>/coverage.opencover.xml`.
 4. The coverage report is uploaded as a per-OS artifact.
 
@@ -76,7 +76,7 @@ secrets and needs no write scope.
   would let a broken coverage setup pass unnoticed. It should fail.
 - **This is the enforcement point for the warning ratchet.** The
   `TreatWarningsAsErrors` / `MSBuildTreatWarningsAsErrors` promotion (see
-  [`Directory.Build.props`](../../Directory.Build.props)) is scoped to CI and is
+  [`Directory.Build.props`](../../../../Directory.Build.props)) is scoped to CI and is
   *enforced here*, on both OS legs. The `sonar` workflow deliberately disables it
   for its own analysis build — so `ci`, not `sonar`, is the gate that must stay
   green on warnings.
@@ -99,7 +99,7 @@ secrets and needs no write scope.
 - [`sonar`](sonar.en.md) reuses the same `coverage.runsettings` so its coverage
   report matches this one.
 - [`analyzers`](analyzers.en.md) covers the analyzer dogfood that `ci` does not.
-- [`canary.yml`](../../.github/workflows/canary.yml) *(no reference page yet)*
+- [`canary.yml`](../../../../.github/workflows/canary.yml) *(no reference page yet)*
   runs the same net8 tooling on the next .NET **preview**, weekly, to catch a
   roll-forward regression onto a not-yet-released major before it ships — the one
   surface the `floor` job cannot cover (see ADR 0002).
diff --git a/maintainers/workflows/ci.fr.md b/doc/handwritten/for-maintainers/workflows/ci.fr.md
similarity index 94%
rename from maintainers/workflows/ci.fr.md
rename to doc/handwritten/for-maintainers/workflows/ci.fr.md
index 42765ef..c9fd159 100644
--- a/maintainers/workflows/ci.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/ci.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml)
+**Fichier du workflow :** [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml)
 
 ## À quoi il sert
 
@@ -42,7 +42,7 @@ Sur une matrice `[ubuntu-latest, windows-latest]` :
 1. Checkout, puis installation du SDK .NET.
 2. `dotnet restore` → `dotnet build -c Release` → `dotnet test -c Release`.
 3. Les tests collectent la couverture OpenCover via `coverlet.collector`,
-   configuré par [`coverage.runsettings`](../../coverage.runsettings), dans
+   configuré par [`coverage.runsettings`](../../../../coverage.runsettings), dans
    `artifacts/coverage/<guid>/coverage.opencover.xml`.
 4. Le rapport de couverture est uploadé en artefact, un par OS.
 
@@ -79,7 +79,7 @@ stocke aucun secret et n'a besoin d'aucun périmètre en écriture.
   Ça doit échouer.
 - **C'est ici que le cliquet de warnings est imposé.** La promotion
   `TreatWarningsAsErrors` / `MSBuildTreatWarningsAsErrors` (voir
-  [`Directory.Build.props`](../../Directory.Build.props)) est cantonnée à la CI et
+  [`Directory.Build.props`](../../../../Directory.Build.props)) est cantonnée à la CI et
   *imposée ici*, sur les deux branches OS. Le workflow `sonar` la désactive
   volontairement pour son propre build d'analyse — c'est donc `ci`, et non
   `sonar`, le barrage qui doit rester vert sur les warnings.
@@ -104,7 +104,7 @@ stocke aucun secret et n'a besoin d'aucun périmètre en écriture.
   rapport de couverture corresponde à celui-ci.
 - [`analyzers`](analyzers.fr.md) couvre le dogfood des analyzers que `ci` ne fait
   pas.
-- [`canary.yml`](../../.github/workflows/canary.yml) *(pas encore de page de
+- [`canary.yml`](../../../../.github/workflows/canary.yml) *(pas encore de page de
   référence)* fait tourner le même outillage net8 sur la **preview** .NET
   suivante, chaque semaine, pour attraper une régression de roll-forward vers un
   major pas encore publié avant qu'il ne sorte — la seule surface que le job
diff --git a/maintainers/workflows/codeql.en.md b/doc/handwritten/for-maintainers/workflows/codeql.en.md
similarity index 96%
rename from maintainers/workflows/codeql.en.md
rename to doc/handwritten/for-maintainers/workflows/codeql.en.md
index cf9ae08..60ca5a1 100644
--- a/maintainers/workflows/codeql.en.md
+++ b/doc/handwritten/for-maintainers/workflows/codeql.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/codeql.yml`](../../.github/workflows/codeql.yml)
+**Workflow file:** [`.github/workflows/codeql.yml`](../../../../.github/workflows/codeql.yml)
 
 ## What it is for
 
diff --git a/maintainers/workflows/codeql.fr.md b/doc/handwritten/for-maintainers/workflows/codeql.fr.md
similarity index 98%
rename from maintainers/workflows/codeql.fr.md
rename to doc/handwritten/for-maintainers/workflows/codeql.fr.md
index 287f17c..125c102 100644
--- a/maintainers/workflows/codeql.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/codeql.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/codeql.yml`](../../.github/workflows/codeql.yml)
+**Fichier du workflow :** [`.github/workflows/codeql.yml`](../../../../.github/workflows/codeql.yml)
 
 ## À quoi il sert
 
diff --git a/maintainers/workflows/commit-lint.en.md b/doc/handwritten/for-maintainers/workflows/commit-lint.en.md
similarity index 87%
rename from maintainers/workflows/commit-lint.en.md
rename to doc/handwritten/for-maintainers/workflows/commit-lint.en.md
index 8c8e42b..5d4194a 100644
--- a/maintainers/workflows/commit-lint.en.md
+++ b/doc/handwritten/for-maintainers/workflows/commit-lint.en.md
@@ -5,18 +5,18 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/commit-lint.yml`](../../.github/workflows/commit-lint.yml)
+**Workflow file:** [`.github/workflows/commit-lint.yml`](../../../../.github/workflows/commit-lint.yml)
 
 ## What it is for
 
 It enforces the repository's commit-message convention (Conventional Commits, as
-specified in [`CONTRIBUTING.md`](../../CONTRIBUTING.md)) on **every non-merge
+specified in [`CONTRIBUTING.md`](../../../../CONTRIBUTING.md)) on **every non-merge
 commit of a pull request**. It is the server-side backstop for the local
 `commit-msg` hook: a contributor who bypasses the hook with
 `git commit --no-verify` is still caught here.
 
 Both the hook and this workflow call the **same script**,
-[`tools/commit-lint/lint-commit-message.sh`](../../tools/commit-lint/lint-commit-message.sh),
+[`tools/commit-lint/lint-commit-message.sh`](../../../../tools/commit-lint/lint-commit-message.sh),
 so there is exactly one definition of "a valid commit message" and CI can never
 drift from the local check.
 
@@ -55,6 +55,6 @@ One job, `Conventional commits`:
 
 ## Related
 
-- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) — the commit and PR conventions this
+- [`CONTRIBUTING.md`](../../../../CONTRIBUTING.md) — the commit and PR conventions this
   workflow enforces. Enable the local hook once per clone with
   `git config core.hooksPath .githooks`.
diff --git a/maintainers/workflows/commit-lint.fr.md b/doc/handwritten/for-maintainers/workflows/commit-lint.fr.md
similarity index 87%
rename from maintainers/workflows/commit-lint.fr.md
rename to doc/handwritten/for-maintainers/workflows/commit-lint.fr.md
index 82c343a..2ed2371 100644
--- a/maintainers/workflows/commit-lint.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/commit-lint.fr.md
@@ -5,18 +5,18 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/commit-lint.yml`](../../.github/workflows/commit-lint.yml)
+**Fichier du workflow :** [`.github/workflows/commit-lint.yml`](../../../../.github/workflows/commit-lint.yml)
 
 ## À quoi il sert
 
 Il impose la convention de message de commit du dépôt (Conventional Commits,
-telle que spécifiée dans [`CONTRIBUTING.fr.md`](../../doc/CONTRIBUTING.fr.md)) sur **chaque
+telle que spécifiée dans [`CONTRIBUTING.fr.md`](../../for-users/CONTRIBUTING.fr.md)) sur **chaque
 commit non-merge d'une pull request**. C'est le filet de sécurité côté serveur du
 hook local `commit-msg` : un contributeur qui contourne le hook avec
 `git commit --no-verify` est quand même rattrapé ici.
 
 Le hook et ce workflow appellent le **même script**,
-[`tools/commit-lint/lint-commit-message.sh`](../../tools/commit-lint/lint-commit-message.sh),
+[`tools/commit-lint/lint-commit-message.sh`](../../../../tools/commit-lint/lint-commit-message.sh),
 donc il existe exactement une définition de « message de commit valide » et la CI
 ne peut jamais diverger du contrôle local.
 
@@ -56,6 +56,6 @@ Un seul job, `Conventional commits` :
 
 ## En rapport
 
-- [`CONTRIBUTING.fr.md`](../../doc/CONTRIBUTING.fr.md) — les conventions de commit et de PR
+- [`CONTRIBUTING.fr.md`](../../for-users/CONTRIBUTING.fr.md) — les conventions de commit et de PR
   que ce workflow impose. Activez le hook local une fois par clone avec
   `git config core.hooksPath .githooks`.
diff --git a/maintainers/workflows/dependabot-automerge.en.md b/doc/handwritten/for-maintainers/workflows/dependabot-automerge.en.md
similarity index 91%
rename from maintainers/workflows/dependabot-automerge.en.md
rename to doc/handwritten/for-maintainers/workflows/dependabot-automerge.en.md
index 05796be..4427248 100644
--- a/maintainers/workflows/dependabot-automerge.en.md
+++ b/doc/handwritten/for-maintainers/workflows/dependabot-automerge.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/dependabot-automerge.yml`](../../.github/workflows/dependabot-automerge.yml)
+**Workflow file:** [`.github/workflows/dependabot-automerge.yml`](../../../../.github/workflows/dependabot-automerge.yml)
 
 ## What it is for
 
@@ -16,7 +16,7 @@ is the low-friction lane of the dependency-update policy: routine bumps do not
 need a human, risky ones do.
 
 The Dependabot configuration itself (which ecosystems, schedule, ignored
-packages) lives in [`.github/dependabot.yml`](../../.github/dependabot.yml), not
+packages) lives in [`.github/dependabot.yml`](../../../../.github/dependabot.yml), not
 here.
 
 ## When it runs
@@ -54,7 +54,7 @@ Workflow default `contents: read`; the job widens to `contents: write` and
 
 ## Related
 
-- [`.github/dependabot.yml`](../../.github/dependabot.yml) — what Dependabot
+- [`.github/dependabot.yml`](../../../../.github/dependabot.yml) — what Dependabot
   updates and what it ignores (e.g. the frozen `Microsoft.CodeAnalysis.*`; see
   [`analyzers`](analyzers.en.md)).
 - [`dependency-review`](dependency-review.en.md) — the PR-time vulnerability gate
diff --git a/maintainers/workflows/dependabot-automerge.fr.md b/doc/handwritten/for-maintainers/workflows/dependabot-automerge.fr.md
similarity index 92%
rename from maintainers/workflows/dependabot-automerge.fr.md
rename to doc/handwritten/for-maintainers/workflows/dependabot-automerge.fr.md
index abdd0d0..15d41d0 100644
--- a/maintainers/workflows/dependabot-automerge.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/dependabot-automerge.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/dependabot-automerge.yml`](../../.github/workflows/dependabot-automerge.yml)
+**Fichier du workflow :** [`.github/workflows/dependabot-automerge.yml`](../../../../.github/workflows/dependabot-automerge.yml)
 
 ## À quoi il sert
 
@@ -17,7 +17,7 @@ voie à faible friction de la politique de mise à jour des dépendances : les
 montées de routine n'ont pas besoin d'un humain, les risquées si.
 
 La configuration de Dependabot elle-même (quels écosystèmes, planning, packages
-ignorés) vit dans [`.github/dependabot.yml`](../../.github/dependabot.yml), pas
+ignorés) vit dans [`.github/dependabot.yml`](../../../../.github/dependabot.yml), pas
 ici.
 
 ## Quand il s'exécute
@@ -58,7 +58,7 @@ la PR.
 
 ## En rapport
 
-- [`.github/dependabot.yml`](../../.github/dependabot.yml) — ce que Dependabot met
+- [`.github/dependabot.yml`](../../../../.github/dependabot.yml) — ce que Dependabot met
   à jour et ce qu'il ignore (p. ex. les `Microsoft.CodeAnalysis.*` gelés ; voir
   [`analyzers`](analyzers.fr.md)).
 - [`dependency-review`](dependency-review.fr.md) — le barrage de vulnérabilité au
diff --git a/maintainers/workflows/dependency-review.en.md b/doc/handwritten/for-maintainers/workflows/dependency-review.en.md
similarity index 94%
rename from maintainers/workflows/dependency-review.en.md
rename to doc/handwritten/for-maintainers/workflows/dependency-review.en.md
index 461b061..969764f 100644
--- a/maintainers/workflows/dependency-review.en.md
+++ b/doc/handwritten/for-maintainers/workflows/dependency-review.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/dependency-review.yml`](../../.github/workflows/dependency-review.yml)
+**Workflow file:** [`.github/workflows/dependency-review.yml`](../../../../.github/workflows/dependency-review.yml)
 
 ## What it is for
 
@@ -42,7 +42,7 @@ check is the signal.
   Advanced Security.)
 - **It only sees changes the PR makes.** A CVE published overnight against an
   *existing* dependency does not fail this check — that stays a warning through
-  the NuGet audit (see [`Directory.Build.props`](../../Directory.Build.props)).
+  the NuGet audit (see [`Directory.Build.props`](../../../../Directory.Build.props)).
   This workflow blocks only at the point of introduction, on purpose.
 - **`fail-on-severity: moderate` is the tuning knob.** Lower it to `low` to be
   stricter, raise it to `high` to be laxer. Because it only inspects the PR's own
diff --git a/maintainers/workflows/dependency-review.fr.md b/doc/handwritten/for-maintainers/workflows/dependency-review.fr.md
similarity index 94%
rename from maintainers/workflows/dependency-review.fr.md
rename to doc/handwritten/for-maintainers/workflows/dependency-review.fr.md
index 03c9225..57a2966 100644
--- a/maintainers/workflows/dependency-review.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/dependency-review.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/dependency-review.yml`](../../.github/workflows/dependency-review.yml)
+**Fichier du workflow :** [`.github/workflows/dependency-review.yml`](../../../../.github/workflows/dependency-review.yml)
 
 ## À quoi il sert
 
@@ -44,7 +44,7 @@ le check en échec est le signal.
 - **Il ne voit que les changements apportés par la PR.** Une CVE publiée pendant
   la nuit contre une dépendance *existante* ne fait pas échouer ce check — cela
   reste un warning via l'audit NuGet (voir
-  [`Directory.Build.props`](../../Directory.Build.props)). Ce workflow ne bloque
+  [`Directory.Build.props`](../../../../Directory.Build.props)). Ce workflow ne bloque
   qu'au point d'introduction, à dessein.
 - **`fail-on-severity: moderate` est le bouton de réglage.** Abaissez-le à `low`
   pour être plus strict, montez-le à `high` pour être plus laxiste. Comme il
diff --git a/maintainers/workflows/release-dryrun.en.md b/doc/handwritten/for-maintainers/workflows/release-dryrun.en.md
similarity index 98%
rename from maintainers/workflows/release-dryrun.en.md
rename to doc/handwritten/for-maintainers/workflows/release-dryrun.en.md
index a7ca3a2..8639e73 100644
--- a/maintainers/workflows/release-dryrun.en.md
+++ b/doc/handwritten/for-maintainers/workflows/release-dryrun.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/release-dryrun.yml`](../../.github/workflows/release-dryrun.yml)
+**Workflow file:** [`.github/workflows/release-dryrun.yml`](../../../../.github/workflows/release-dryrun.yml)
 
 ## What it is for
 
diff --git a/maintainers/workflows/release-dryrun.fr.md b/doc/handwritten/for-maintainers/workflows/release-dryrun.fr.md
similarity index 98%
rename from maintainers/workflows/release-dryrun.fr.md
rename to doc/handwritten/for-maintainers/workflows/release-dryrun.fr.md
index aed1d5c..a5610fe 100644
--- a/maintainers/workflows/release-dryrun.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/release-dryrun.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/release-dryrun.yml`](../../.github/workflows/release-dryrun.yml)
+**Fichier du workflow :** [`.github/workflows/release-dryrun.yml`](../../../../.github/workflows/release-dryrun.yml)
 
 ## À quoi il sert
 
diff --git a/maintainers/workflows/release.en.md b/doc/handwritten/for-maintainers/workflows/release.en.md
similarity index 98%
rename from maintainers/workflows/release.en.md
rename to doc/handwritten/for-maintainers/workflows/release.en.md
index a0d1198..07a1e23 100644
--- a/maintainers/workflows/release.en.md
+++ b/doc/handwritten/for-maintainers/workflows/release.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/release.yml`](../../.github/workflows/release.yml)
+**Workflow file:** [`.github/workflows/release.yml`](../../../../.github/workflows/release.yml)
 
 ## What it is for
 
diff --git a/maintainers/workflows/release.fr.md b/doc/handwritten/for-maintainers/workflows/release.fr.md
similarity index 99%
rename from maintainers/workflows/release.fr.md
rename to doc/handwritten/for-maintainers/workflows/release.fr.md
index 64eac84..68d3ef6 100644
--- a/maintainers/workflows/release.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/release.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/release.yml`](../../.github/workflows/release.yml)
+**Fichier du workflow :** [`.github/workflows/release.yml`](../../../../.github/workflows/release.yml)
 
 ## À quoi il sert
 
diff --git a/maintainers/workflows/scorecard.en.md b/doc/handwritten/for-maintainers/workflows/scorecard.en.md
similarity index 97%
rename from maintainers/workflows/scorecard.en.md
rename to doc/handwritten/for-maintainers/workflows/scorecard.en.md
index bb32f21..aa2ed48 100644
--- a/maintainers/workflows/scorecard.en.md
+++ b/doc/handwritten/for-maintainers/workflows/scorecard.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/scorecard.yml`](../../.github/workflows/scorecard.yml)
+**Workflow file:** [`.github/workflows/scorecard.yml`](../../../../.github/workflows/scorecard.yml)
 
 ## What it is for
 
diff --git a/maintainers/workflows/scorecard.fr.md b/doc/handwritten/for-maintainers/workflows/scorecard.fr.md
similarity index 99%
rename from maintainers/workflows/scorecard.fr.md
rename to doc/handwritten/for-maintainers/workflows/scorecard.fr.md
index 3db7222..aa1bdde 100644
--- a/maintainers/workflows/scorecard.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/scorecard.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/scorecard.yml`](../../.github/workflows/scorecard.yml)
+**Fichier du workflow :** [`.github/workflows/scorecard.yml`](../../../../.github/workflows/scorecard.yml)
 
 ## À quoi il sert
 
diff --git a/maintainers/workflows/sonar.en.md b/doc/handwritten/for-maintainers/workflows/sonar.en.md
similarity index 96%
rename from maintainers/workflows/sonar.en.md
rename to doc/handwritten/for-maintainers/workflows/sonar.en.md
index 9ace285..99c26d3 100644
--- a/maintainers/workflows/sonar.en.md
+++ b/doc/handwritten/for-maintainers/workflows/sonar.en.md
@@ -5,7 +5,7 @@
 > Maintainer documentation — part of the [workflow reference](README.md).
 > Not part of the user documentation under `doc/`.
 
-**Workflow file:** [`.github/workflows/sonar.yml`](../../.github/workflows/sonar.yml)
+**Workflow file:** [`.github/workflows/sonar.yml`](../../../../.github/workflows/sonar.yml)
 
 ## What it is for
 
diff --git a/maintainers/workflows/sonar.fr.md b/doc/handwritten/for-maintainers/workflows/sonar.fr.md
similarity index 98%
rename from maintainers/workflows/sonar.fr.md
rename to doc/handwritten/for-maintainers/workflows/sonar.fr.md
index c7727de..8c59a95 100644
--- a/maintainers/workflows/sonar.fr.md
+++ b/doc/handwritten/for-maintainers/workflows/sonar.fr.md
@@ -5,7 +5,7 @@
 > Documentation mainteneur — fait partie de la [référence des workflows](README.fr.md).
 > Ne fait pas partie de la documentation utilisateur sous `doc/`.
 
-**Fichier du workflow :** [`.github/workflows/sonar.yml`](../../.github/workflows/sonar.yml)
+**Fichier du workflow :** [`.github/workflows/sonar.yml`](../../../../.github/workflows/sonar.yml)
 
 ## À quoi il sert
 
diff --git a/doc/ArbitraryTestValues.en.md b/doc/handwritten/for-users/ArbitraryTestValues.en.md
similarity index 97%
rename from doc/ArbitraryTestValues.en.md
rename to doc/handwritten/for-users/ArbitraryTestValues.en.md
index bd1e201..948539b 100644
--- a/doc/ArbitraryTestValues.en.md
+++ b/doc/handwritten/for-users/ArbitraryTestValues.en.md
@@ -113,7 +113,7 @@ Before reaching for an arbitrary value, verify that:
 ---
 
 <div align="center">
-<a href="DeterministicTesting.en.md">← Deterministic Error Tests</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="OperationalIntegration.en.md">Generating and Publishing the Catalog →</a>
+<a href="DeterministicTesting.en.md">← Deterministic Error Tests</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="OperationalIntegration.en.md">Generating and Publishing the Catalog →</a>
 </div>
 
 ---
diff --git a/doc/ArbitraryTestValues.fr.md b/doc/handwritten/for-users/ArbitraryTestValues.fr.md
similarity index 100%
rename from doc/ArbitraryTestValues.fr.md
rename to doc/handwritten/for-users/ArbitraryTestValues.fr.md
diff --git a/doc/ArchitectureOfTheDocumentationPipeline.en.md b/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md
similarity index 97%
rename from doc/ArchitectureOfTheDocumentationPipeline.en.md
rename to doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md
index 2c589ca..5192454 100644
--- a/doc/ArchitectureOfTheDocumentationPipeline.en.md
+++ b/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.en.md
@@ -184,7 +184,7 @@ The code remains the source of truth; the pipeline makes that knowledge portable
 ---
 
 <div align="center">
-<a href="CatalogVersioning.en.md">← Catalog Versioning</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="DocumentationExtractionReference.en.md">Extraction and Project Discovery Reference →</a>
+<a href="CatalogVersioning.en.md">← Catalog Versioning</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="DocumentationExtractionReference.en.md">Extraction and Project Discovery Reference →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/ArchitectureOfTheDocumentationPipeline.fr.md b/doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.fr.md
similarity index 100%
rename from doc/ArchitectureOfTheDocumentationPipeline.fr.md
rename to doc/handwritten/for-users/ArchitectureOfTheDocumentationPipeline.fr.md
diff --git a/doc/BestPractices.en.md b/doc/handwritten/for-users/BestPractices.en.md
similarity index 97%
rename from doc/BestPractices.en.md
rename to doc/handwritten/for-users/BestPractices.en.md
index 22952eb..fda2672 100644
--- a/doc/BestPractices.en.md
+++ b/doc/handwritten/for-users/BestPractices.en.md
@@ -111,7 +111,7 @@ Before merging an error-related change, verify that:
 ---
 
 <div align="center">
-<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="Testing.en.md">Testing Guide →</a>
+<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="Testing.en.md">Testing Guide →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/BestPractices.fr.md b/doc/handwritten/for-users/BestPractices.fr.md
similarity index 100%
rename from doc/BestPractices.fr.md
rename to doc/handwritten/for-users/BestPractices.fr.md
diff --git a/doc/CONTRIBUTING.fr.md b/doc/handwritten/for-users/CONTRIBUTING.fr.md
similarity index 99%
rename from doc/CONTRIBUTING.fr.md
rename to doc/handwritten/for-users/CONTRIBUTING.fr.md
index 6f83a4d..2d9b3ac 100644
--- a/doc/CONTRIBUTING.fr.md
+++ b/doc/handwritten/for-users/CONTRIBUTING.fr.md
@@ -1,7 +1,7 @@
 # Contribuer à FirstClassErrors
 
 🌍 **Langues:**  
-🇬🇧 [English](../CONTRIBUTING.md) | 🇫🇷 Français (ce fichier)
+🇬🇧 [English](../../../CONTRIBUTING.md) | 🇫🇷 Français (ce fichier)
 
 FirstClassErrors considère les erreurs comme des concepts de premier ordre,
 documentés et diagnostiquables. L’historique du dépôt doit être aussi lisible que
@@ -15,7 +15,7 @@ commits sont écrits ici.
 * Tester : `dotnet test FirstClassErrors.sln`
 * Tests des analyzers, lorsque vous touchez aux analyzers : `dotnet test FirstClassErrors.Analyzers.UnitTests`
 
-Voir [`CLAUDE.md`](../CLAUDE.md) pour l’organisation du projet et les lignes
+Voir [`CLAUDE.md`](../../../CLAUDE.md) pour l’organisation du projet et les lignes
 directrices plus larges concernant les changements.
 
 ## Activer le hook de message de commit
@@ -472,7 +472,7 @@ Classés comme le sont les règles : type, scope, description, corps, breaking,
 ### Adoption
 
 Ce guide est la règle pour les commits de ce dépôt. S’en écarter requiert une justification —
-un ADR sous `maintainers/adr/`, ou une mise à jour de ce guide.
+un ADR sous `doc/handwritten/for-maintainers/adr/`, ou une mise à jour de ce guide.
 
 Il s’applique à partir de son adoption, à chaque commit créé après. L’historique antérieur
 n’est pas réécrit.
diff --git a/doc/CatalogVersioning.en.md b/doc/handwritten/for-users/CatalogVersioning.en.md
similarity index 97%
rename from doc/CatalogVersioning.en.md
rename to doc/handwritten/for-users/CatalogVersioning.en.md
index 26e1ffe..c3e10b3 100644
--- a/doc/CatalogVersioning.en.md
+++ b/doc/handwritten/for-users/CatalogVersioning.en.md
@@ -163,7 +163,7 @@ A rename remains breaking because consumers know the old code. When the title su
 ---
 
 <div align="center">
-<a href="OperationalIntegration.en.md">← CI/CD and Operational Integration</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioningReference.en.md">Command reference →</a>
+<a href="OperationalIntegration.en.md">← CI/CD and Operational Integration</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="CatalogVersioningReference.en.md">Command reference →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/CatalogVersioning.fr.md b/doc/handwritten/for-users/CatalogVersioning.fr.md
similarity index 100%
rename from doc/CatalogVersioning.fr.md
rename to doc/handwritten/for-users/CatalogVersioning.fr.md
diff --git a/doc/CatalogVersioningCI.en.md b/doc/handwritten/for-users/CatalogVersioningCI.en.md
similarity index 97%
rename from doc/CatalogVersioningCI.en.md
rename to doc/handwritten/for-users/CatalogVersioningCI.en.md
index 0440dde..2fc038a 100644
--- a/doc/CatalogVersioningCI.en.md
+++ b/doc/handwritten/for-users/CatalogVersioningCI.en.md
@@ -214,7 +214,7 @@ This form can produce release notes for the error contract or compare the previo
 ---
 
 <div align="center">
-<a href="CatalogVersioningReference.en.md">← Command reference</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="ArchitectureOfTheDocumentationPipeline.en.md">Architecture of the Documentation Pipeline →</a>
+<a href="CatalogVersioningReference.en.md">← Command reference</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="ArchitectureOfTheDocumentationPipeline.en.md">Architecture of the Documentation Pipeline →</a>
 </div>
 
 ---
diff --git a/doc/CatalogVersioningCI.fr.md b/doc/handwritten/for-users/CatalogVersioningCI.fr.md
similarity index 100%
rename from doc/CatalogVersioningCI.fr.md
rename to doc/handwritten/for-users/CatalogVersioningCI.fr.md
diff --git a/doc/CatalogVersioningReference.en.md b/doc/handwritten/for-users/CatalogVersioningReference.en.md
similarity index 97%
rename from doc/CatalogVersioningReference.en.md
rename to doc/handwritten/for-users/CatalogVersioningReference.en.md
index 13fe18c..e10c5b4 100644
--- a/doc/CatalogVersioningReference.en.md
+++ b/doc/handwritten/for-users/CatalogVersioningReference.en.md
@@ -147,7 +147,7 @@ The `catalog update` and `catalog diff` commands accept, among others:
 ---
 
 <div align="center">
-<a href="CatalogVersioning.en.md">← Catalog versioning guide</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioningCI.en.md">CI/CD integration →</a>
+<a href="CatalogVersioning.en.md">← Catalog versioning guide</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="CatalogVersioningCI.en.md">CI/CD integration →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/CatalogVersioningReference.fr.md b/doc/handwritten/for-users/CatalogVersioningReference.fr.md
similarity index 100%
rename from doc/CatalogVersioningReference.fr.md
rename to doc/handwritten/for-users/CatalogVersioningReference.fr.md
diff --git a/doc/ComparisonWithOtherLibraries.en.md b/doc/handwritten/for-users/ComparisonWithOtherLibraries.en.md
similarity index 100%
rename from doc/ComparisonWithOtherLibraries.en.md
rename to doc/handwritten/for-users/ComparisonWithOtherLibraries.en.md
diff --git a/doc/ComparisonWithOtherLibraries.fr.md b/doc/handwritten/for-users/ComparisonWithOtherLibraries.fr.md
similarity index 100%
rename from doc/ComparisonWithOtherLibraries.fr.md
rename to doc/handwritten/for-users/ComparisonWithOtherLibraries.fr.md
diff --git a/doc/CoreConcepts.en.md b/doc/handwritten/for-users/CoreConcepts.en.md
similarity index 96%
rename from doc/CoreConcepts.en.md
rename to doc/handwritten/for-users/CoreConcepts.en.md
index 92b3300..c5d18ea 100644
--- a/doc/CoreConcepts.en.md
+++ b/doc/handwritten/for-users/CoreConcepts.en.md
@@ -151,7 +151,7 @@ Their interaction direction, transience, and composition rules are explained sep
 ---
 
 <div align="center">
-<a href="WhenNotToUseFirstClassErrors.en.md">← When Not to Use FirstClassErrors</a> · <a href="../README.md#-documentation">↑ Table of contents</a> · <a href="ErrorTaxonomy.en.md">Error Taxonomy and Composition →</a>
+<a href="WhenNotToUseFirstClassErrors.en.md">← When Not to Use FirstClassErrors</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="ErrorTaxonomy.en.md">Error Taxonomy and Composition →</a>
 </div>
 
 ---
diff --git a/doc/CoreConcepts.fr.md b/doc/handwritten/for-users/CoreConcepts.fr.md
similarity index 100%
rename from doc/CoreConcepts.fr.md
rename to doc/handwritten/for-users/CoreConcepts.fr.md
diff --git a/doc/DesignPrinciples.en.md b/doc/handwritten/for-users/DesignPrinciples.en.md
similarity index 96%
rename from doc/DesignPrinciples.en.md
rename to doc/handwritten/for-users/DesignPrinciples.en.md
index 31b5ef4..7e20d58 100644
--- a/doc/DesignPrinciples.en.md
+++ b/doc/handwritten/for-users/DesignPrinciples.en.md
@@ -93,7 +93,7 @@ The factory defines one meaningful situation. The `Error` preserves that meaning
 ---
 
 <div align="center">
-<a href="GettingStarted.en.md">← Getting Started</a> · <a href="../README.md#-documentation">↑ Table of contents</a> · <a href="WhenNotToUseFirstClassErrors.en.md">When Not to Use FirstClassErrors →</a>
+<a href="GettingStarted.en.md">← Getting Started</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="WhenNotToUseFirstClassErrors.en.md">When Not to Use FirstClassErrors →</a>
 </div>
 
 ---
diff --git a/doc/DesignPrinciples.fr.md b/doc/handwritten/for-users/DesignPrinciples.fr.md
similarity index 100%
rename from doc/DesignPrinciples.fr.md
rename to doc/handwritten/for-users/DesignPrinciples.fr.md
diff --git a/doc/DeterministicTesting.en.md b/doc/handwritten/for-users/DeterministicTesting.en.md
similarity index 98%
rename from doc/DeterministicTesting.en.md
rename to doc/handwritten/for-users/DeterministicTesting.en.md
index d1af274..e7f68a5 100644
--- a/doc/DeterministicTesting.en.md
+++ b/doc/handwritten/for-users/DeterministicTesting.en.md
@@ -203,7 +203,7 @@ Before approving a deterministic error test, verify that:
 ---
 
 <div align="center">
-<a href="Testing.en.md">← Testing Outcomes and Errors</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="ArbitraryTestValues.en.md">Arbitrary Test Values →</a>
+<a href="Testing.en.md">← Testing Outcomes and Errors</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="ArbitraryTestValues.en.md">Arbitrary Test Values →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/DeterministicTesting.fr.md b/doc/handwritten/for-users/DeterministicTesting.fr.md
similarity index 100%
rename from doc/DeterministicTesting.fr.md
rename to doc/handwritten/for-users/DeterministicTesting.fr.md
diff --git a/doc/DocumentationExtractionReference.en.md b/doc/handwritten/for-users/DocumentationExtractionReference.en.md
similarity index 98%
rename from doc/DocumentationExtractionReference.en.md
rename to doc/handwritten/for-users/DocumentationExtractionReference.en.md
index 5cc1452..b933380 100644
--- a/doc/DocumentationExtractionReference.en.md
+++ b/doc/handwritten/for-users/DocumentationExtractionReference.en.md
@@ -280,7 +280,7 @@ When expected errors are missing, walk the pipeline in order — each step depen
 ---
 
 <div align="center">
-<a href="ArchitectureOfTheDocumentationPipeline.en.md">← Architecture of the Documentation Pipeline</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingACustomRenderer.en.md">Writing a custom renderer →</a>
+<a href="ArchitectureOfTheDocumentationPipeline.en.md">← Architecture of the Documentation Pipeline</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="WritingACustomRenderer.en.md">Writing a custom renderer →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/DocumentationExtractionReference.fr.md b/doc/handwritten/for-users/DocumentationExtractionReference.fr.md
similarity index 100%
rename from doc/DocumentationExtractionReference.fr.md
rename to doc/handwritten/for-users/DocumentationExtractionReference.fr.md
diff --git a/doc/DocumentationMap.en.md b/doc/handwritten/for-users/DocumentationMap.en.md
similarity index 98%
rename from doc/DocumentationMap.en.md
rename to doc/handwritten/for-users/DocumentationMap.en.md
index 1df9e4a..838c8b7 100644
--- a/doc/DocumentationMap.en.md
+++ b/doc/handwritten/for-users/DocumentationMap.en.md
@@ -110,7 +110,7 @@ This keeps local conventions short while allowing the library documentation to e
 ---
 
 <div align="center">
-<a href="../README.md">← Project README</a> · <a href="GettingStarted.en.md">Start with Getting Started →</a>
+<a href="../../../README.md">← Project README</a> · <a href="GettingStarted.en.md">Start with Getting Started →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/DocumentationMap.fr.md b/doc/handwritten/for-users/DocumentationMap.fr.md
similarity index 100%
rename from doc/DocumentationMap.fr.md
rename to doc/handwritten/for-users/DocumentationMap.fr.md
diff --git a/doc/ErrorContext.en.md b/doc/handwritten/for-users/ErrorContext.en.md
similarity index 98%
rename from doc/ErrorContext.en.md
rename to doc/handwritten/for-users/ErrorContext.en.md
index 4ec741e..b13ebdf 100644
--- a/doc/ErrorContext.en.md
+++ b/doc/handwritten/for-users/ErrorContext.en.md
@@ -173,7 +173,7 @@ If the answer is yes to all six, it is a strong context candidate.
 ---
 
 <div align="center">
-<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingErrorsGuide.en.md">Writing Errors Guide →</a>
+<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="WritingErrorsGuide.en.md">Writing Errors Guide →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/ErrorContext.fr.md b/doc/handwritten/for-users/ErrorContext.fr.md
similarity index 100%
rename from doc/ErrorContext.fr.md
rename to doc/handwritten/for-users/ErrorContext.fr.md
diff --git a/doc/ErrorTaxonomy.en.md b/doc/handwritten/for-users/ErrorTaxonomy.en.md
similarity index 98%
rename from doc/ErrorTaxonomy.en.md
rename to doc/handwritten/for-users/ErrorTaxonomy.en.md
index 6cc3a66..8ac451f 100644
--- a/doc/ErrorTaxonomy.en.md
+++ b/doc/handwritten/for-users/ErrorTaxonomy.en.md
@@ -159,7 +159,7 @@ Do not choose a type from the current class or folder. Choose it from the meanin
 ---
 
 <div align="center">
-<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../README.md#-documentation">↑ Table of contents</a> · <a href="ErrorContext.en.md">Error Context Guide →</a>
+<a href="CoreConcepts.en.md">← Core Concepts</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="ErrorContext.en.md">Error Context Guide →</a>
 </div>
 
 ---
diff --git a/doc/ErrorTaxonomy.fr.md b/doc/handwritten/for-users/ErrorTaxonomy.fr.md
similarity index 100%
rename from doc/ErrorTaxonomy.fr.md
rename to doc/handwritten/for-users/ErrorTaxonomy.fr.md
diff --git a/doc/FAQ.en.md b/doc/handwritten/for-users/FAQ.en.md
similarity index 99%
rename from doc/FAQ.en.md
rename to doc/handwritten/for-users/FAQ.en.md
index 7dd76f5..ab2b3bd 100644
--- a/doc/FAQ.en.md
+++ b/doc/handwritten/for-users/FAQ.en.md
@@ -130,7 +130,7 @@ See [Error Taxonomy and Composition](ErrorTaxonomy.en.md).
 ---
 
 <div align="center">
-<a href="Internationalization.en.md">← Internationalization</a> · <a href="../README.md#-next-steps">↑ Table of contents</a>
+<a href="Internationalization.en.md">← Internationalization</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a>
 </div>
 
 ---
diff --git a/doc/FAQ.fr.md b/doc/handwritten/for-users/FAQ.fr.md
similarity index 100%
rename from doc/FAQ.fr.md
rename to doc/handwritten/for-users/FAQ.fr.md
diff --git a/doc/GettingStarted.en.md b/doc/handwritten/for-users/GettingStarted.en.md
similarity index 98%
rename from doc/GettingStarted.en.md
rename to doc/handwritten/for-users/GettingStarted.en.md
index d065def..02c5467 100644
--- a/doc/GettingStarted.en.md
+++ b/doc/handwritten/for-users/GettingStarted.en.md
@@ -178,7 +178,7 @@ Commit or publish this generated catalog according to your delivery workflow. Fo
 ---
 
 <div align="center">
-<a href="../README.md#-documentation">↑ Table of contents</a> · <a href="DesignPrinciples.en.md">Design Principles →</a>
+<a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="DesignPrinciples.en.md">Design Principles →</a>
 </div>
 
 ---
diff --git a/doc/GettingStarted.fr.md b/doc/handwritten/for-users/GettingStarted.fr.md
similarity index 100%
rename from doc/GettingStarted.fr.md
rename to doc/handwritten/for-users/GettingStarted.fr.md
diff --git a/doc/Internationalisation.fr.md b/doc/handwritten/for-users/Internationalisation.fr.md
similarity index 100%
rename from doc/Internationalisation.fr.md
rename to doc/handwritten/for-users/Internationalisation.fr.md
diff --git a/doc/Internationalization.en.md b/doc/handwritten/for-users/Internationalization.en.md
similarity index 98%
rename from doc/Internationalization.en.md
rename to doc/handwritten/for-users/Internationalization.en.md
index 9d07799..21a7edf 100644
--- a/doc/Internationalization.en.md
+++ b/doc/handwritten/for-users/Internationalization.en.md
@@ -250,7 +250,7 @@ Before publishing localized catalogs, verify that:
 ---
 
 <div align="center">
-<a href="WritingACustomRenderer.en.md">← Writing a custom renderer</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="FAQ.en.md">FAQ →</a>
+<a href="WritingACustomRenderer.en.md">← Writing a custom renderer</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="FAQ.en.md">FAQ →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/LoggingIntegration.en.md b/doc/handwritten/for-users/LoggingIntegration.en.md
similarity index 98%
rename from doc/LoggingIntegration.en.md
rename to doc/handwritten/for-users/LoggingIntegration.en.md
index e546a4b..7e2732b 100644
--- a/doc/LoggingIntegration.en.md
+++ b/doc/handwritten/for-users/LoggingIntegration.en.md
@@ -267,7 +267,7 @@ Before approving a logging integration, verify that:
 ---
 
 <div align="center">
-<a href="OperationalIntegration.en.md">← Generating and Publishing the Catalog</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CatalogVersioning.en.md">Catalog Versioning →</a>
+<a href="OperationalIntegration.en.md">← Generating and Publishing the Catalog</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="CatalogVersioning.en.md">Catalog Versioning →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/LoggingIntegration.fr.md b/doc/handwritten/for-users/LoggingIntegration.fr.md
similarity index 100%
rename from doc/LoggingIntegration.fr.md
rename to doc/handwritten/for-users/LoggingIntegration.fr.md
diff --git a/doc/OperationalIntegration.en.md b/doc/handwritten/for-users/OperationalIntegration.en.md
similarity index 98%
rename from doc/OperationalIntegration.en.md
rename to doc/handwritten/for-users/OperationalIntegration.en.md
index d1cd799..fc75625 100644
--- a/doc/OperationalIntegration.en.md
+++ b/doc/handwritten/for-users/OperationalIntegration.en.md
@@ -237,7 +237,7 @@ Before approving a catalog-delivery pipeline, verify that:
 ---
 
 <div align="center">
-<a href="ArbitraryTestValues.en.md">← Arbitrary Test Values</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="LoggingIntegration.en.md">Integrate FirstClassErrors with Structured Logging →</a>
+<a href="ArbitraryTestValues.en.md">← Arbitrary Test Values</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="LoggingIntegration.en.md">Integrate FirstClassErrors with Structured Logging →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/OperationalIntegration.fr.md b/doc/handwritten/for-users/OperationalIntegration.fr.md
similarity index 100%
rename from doc/OperationalIntegration.fr.md
rename to doc/handwritten/for-users/OperationalIntegration.fr.md
diff --git a/doc/OutcomeGuide.en.md b/doc/handwritten/for-users/OutcomeGuide.en.md
similarity index 98%
rename from doc/OutcomeGuide.en.md
rename to doc/handwritten/for-users/OutcomeGuide.en.md
index 881a1d6..eec289a 100644
--- a/doc/OutcomeGuide.en.md
+++ b/doc/handwritten/for-users/OutcomeGuide.en.md
@@ -241,7 +241,7 @@ Before approving an `Outcome` flow, verify that:
 ---
 
 <div align="center">
-<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="BestPractices.en.md">Best Practices →</a>
+<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="BestPractices.en.md">Best Practices →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/OutcomeGuide.fr.md b/doc/handwritten/for-users/OutcomeGuide.fr.md
similarity index 100%
rename from doc/OutcomeGuide.fr.md
rename to doc/handwritten/for-users/OutcomeGuide.fr.md
diff --git a/doc/README.fr.md b/doc/handwritten/for-users/README.fr.md
similarity index 97%
rename from doc/README.fr.md
rename to doc/handwritten/for-users/README.fr.md
index 351e5b4..1f016da 100644
--- a/doc/README.fr.md
+++ b/doc/handwritten/for-users/README.fr.md
@@ -1,7 +1,7 @@
 # FirstClassErrors
 
 🌍 **Langues :**  
-🇬🇧 [English](../README.md) | 🇫🇷 Français (ce fichier)
+🇬🇧 [English](../../../README.md) | 🇫🇷 Français (ce fichier)
 
 |  |  |
 | :-- | :-- |
@@ -9,7 +9,7 @@
 | **Qualité** | [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=reefact_first-class-errors&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=reefact_first-class-errors) [![Couverture](https://sonarcloud.io/api/project_badges/measure?project=reefact_first-class-errors&metric=coverage)](https://sonarcloud.io/summary/new_code?id=reefact_first-class-errors) |
 | **Sécurité** | [![codeql](https://github.com/Reefact/first-class-errors/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/Reefact/first-class-errors/actions/workflows/codeql.yml) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13567/badge)](https://www.bestpractices.dev/projects/13567) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Reefact/first-class-errors/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Reefact/first-class-errors) |
 | **Package** | [![NuGet](https://img.shields.io/nuget/vpre/FirstClassErrors?logo=nuget)](https://www.nuget.org/packages/FirstClassErrors) ![.NET Standard 2.0](https://img.shields.io/badge/.NET%20Standard-2.0-512BD4) |
-| **Projet** | [![License](https://img.shields.io/github/license/Reefact/first-class-errors)](../LICENSE) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fe5196?logo=conventionalcommits&logoColor=white)](https://www.conventionalcommits.org) |
+| **Projet** | [![License](https://img.shields.io/github/license/Reefact/first-class-errors)](../../../LICENSE) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fe5196?logo=conventionalcommits&logoColor=white)](https://www.conventionalcommits.org) |
 
 ---
 
diff --git a/doc/RequestBinder.en.md b/doc/handwritten/for-users/RequestBinder.en.md
similarity index 99%
rename from doc/RequestBinder.en.md
rename to doc/handwritten/for-users/RequestBinder.en.md
index 70a40ef..9323ecd 100644
--- a/doc/RequestBinder.en.md
+++ b/doc/handwritten/for-users/RequestBinder.en.md
@@ -242,7 +242,7 @@ not an argument-binding failure), so it is not re-wrapped in the binder envelope
 A consumer of `Create` therefore sees either the binder's envelope (a field was
 missing or malformed) or the factory's own error (all fields were fine, but the
 combination was rejected). The decision behind these two names is recorded in
-[ADR-0007](../maintainers/adr/0007-name-the-binder-terminals-new-and-create.md).
+[ADR-0007](../for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.md).
 
 ## Collect-all, not fail-fast
 
@@ -489,7 +489,7 @@ Before approving a binding, verify that:
 ---
 
 <div align="center">
-<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../README.md#-documentation">↑ Table of contents</a> · <a href="Testing.en.md">Testing →</a>
+<a href="UsagePatterns.en.md">← Usage Patterns</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="Testing.en.md">Testing →</a>
 </div>
 
 ---
diff --git a/doc/RequestBinder.fr.md b/doc/handwritten/for-users/RequestBinder.fr.md
similarity index 99%
rename from doc/RequestBinder.fr.md
rename to doc/handwritten/for-users/RequestBinder.fr.md
index 346d8bf..2daf292 100644
--- a/doc/RequestBinder.fr.md
+++ b/doc/handwritten/for-users/RequestBinder.fr.md
@@ -249,7 +249,7 @@ ré-emballée dans l’enveloppe du binder. Un consommateur de `Create` voit don
 l’enveloppe du binder (un champ manquant ou malformé), soit l’erreur propre de la
 fabrique (tous les champs allaient bien, mais la combinaison a été rejetée). La
 décision derrière ces deux noms est consignée dans
-[ADR-0007](../maintainers/adr/0007-name-the-binder-terminals-new-and-create.md).
+[ADR-0007](../for-maintainers/adr/0007-name-the-binder-terminals-new-and-create.md).
 
 ## Tout collecter, pas au premier échec
 
diff --git a/doc/SECURITY.fr.md b/doc/handwritten/for-users/SECURITY.fr.md
similarity index 98%
rename from doc/SECURITY.fr.md
rename to doc/handwritten/for-users/SECURITY.fr.md
index b86eae0..6ca3e9b 100644
--- a/doc/SECURITY.fr.md
+++ b/doc/handwritten/for-users/SECURITY.fr.md
@@ -1,7 +1,7 @@
 # Politique de sécurité
 
 🌍 **Langues:**  
-🇬🇧 [English](../SECURITY.md) | 🇫🇷 Français (ce fichier)
+🇬🇧 [English](../../../SECURITY.md) | 🇫🇷 Français (ce fichier)
 
 ## Versions prises en charge
 
diff --git a/doc/Testing.en.md b/doc/handwritten/for-users/Testing.en.md
similarity index 97%
rename from doc/Testing.en.md
rename to doc/handwritten/for-users/Testing.en.md
index f6b4b18..f33d83a 100644
--- a/doc/Testing.en.md
+++ b/doc/handwritten/for-users/Testing.en.md
@@ -166,7 +166,7 @@ Before approving an error test, verify that:
 ---
 
 <div align="center">
-<a href="BestPractices.en.md">← Best Practices</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="DeterministicTesting.en.md">Deterministic Error Tests →</a>
+<a href="BestPractices.en.md">← Best Practices</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="DeterministicTesting.en.md">Deterministic Error Tests →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/Testing.fr.md b/doc/handwritten/for-users/Testing.fr.md
similarity index 100%
rename from doc/Testing.fr.md
rename to doc/handwritten/for-users/Testing.fr.md
diff --git a/doc/TheHtmlRenderer.en.md b/doc/handwritten/for-users/TheHtmlRenderer.en.md
similarity index 100%
rename from doc/TheHtmlRenderer.en.md
rename to doc/handwritten/for-users/TheHtmlRenderer.en.md
diff --git a/doc/TheHtmlRenderer.fr.md b/doc/handwritten/for-users/TheHtmlRenderer.fr.md
similarity index 100%
rename from doc/TheHtmlRenderer.fr.md
rename to doc/handwritten/for-users/TheHtmlRenderer.fr.md
diff --git a/doc/UsagePatterns.en.md b/doc/handwritten/for-users/UsagePatterns.en.md
similarity index 98%
rename from doc/UsagePatterns.en.md
rename to doc/handwritten/for-users/UsagePatterns.en.md
index 097efac..193fa26 100644
--- a/doc/UsagePatterns.en.md
+++ b/doc/handwritten/for-users/UsagePatterns.en.md
@@ -199,7 +199,7 @@ Choose the contract from the first list, the error type from the second, and the
 ---
 
 <div align="center">
-<a href="WritingErrorsGuide.en.md">← Writing Errors Guide</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="OutcomeGuide.en.md">Composing with Outcome →</a>
+<a href="WritingErrorsGuide.en.md">← Writing Errors Guide</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="OutcomeGuide.en.md">Composing with Outcome →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/UsagePatterns.fr.md b/doc/handwritten/for-users/UsagePatterns.fr.md
similarity index 100%
rename from doc/UsagePatterns.fr.md
rename to doc/handwritten/for-users/UsagePatterns.fr.md
diff --git a/doc/WhenNotToUseFirstClassErrors.en.md b/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md
similarity index 94%
rename from doc/WhenNotToUseFirstClassErrors.en.md
rename to doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md
index f63a40c..c9ef858 100644
--- a/doc/WhenNotToUseFirstClassErrors.en.md
+++ b/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.en.md
@@ -73,7 +73,7 @@ The goal of this library is not to make every exception richer. It is to make me
 ---
 
 <div align="center">
-<a href="DesignPrinciples.en.md">← Design Principles</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="CoreConcepts.en.md">Core Concepts →</a>
+<a href="DesignPrinciples.en.md">← Design Principles</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="CoreConcepts.en.md">Core Concepts →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/WhenNotToUseFirstClassErrors.fr.md b/doc/handwritten/for-users/WhenNotToUseFirstClassErrors.fr.md
similarity index 100%
rename from doc/WhenNotToUseFirstClassErrors.fr.md
rename to doc/handwritten/for-users/WhenNotToUseFirstClassErrors.fr.md
diff --git a/doc/WritingACustomRenderer.en.md b/doc/handwritten/for-users/WritingACustomRenderer.en.md
similarity index 98%
rename from doc/WritingACustomRenderer.en.md
rename to doc/handwritten/for-users/WritingACustomRenderer.en.md
index ef2557f..a930983 100644
--- a/doc/WritingACustomRenderer.en.md
+++ b/doc/handwritten/for-users/WritingACustomRenderer.en.md
@@ -307,7 +307,7 @@ Before publishing a renderer, verify that:
 ---
 
 <div align="center">
-<a href="DocumentationExtractionReference.en.md">← Extraction and Project Discovery Reference</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="Internationalization.en.md">Internationalization →</a>
+<a href="DocumentationExtractionReference.en.md">← Extraction and Project Discovery Reference</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="Internationalization.en.md">Internationalization →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/WritingACustomRenderer.fr.md b/doc/handwritten/for-users/WritingACustomRenderer.fr.md
similarity index 100%
rename from doc/WritingACustomRenderer.fr.md
rename to doc/handwritten/for-users/WritingACustomRenderer.fr.md
diff --git a/doc/WritingErrorMessages.en.md b/doc/handwritten/for-users/WritingErrorMessages.en.md
similarity index 98%
rename from doc/WritingErrorMessages.en.md
rename to doc/handwritten/for-users/WritingErrorMessages.en.md
index bafbb68..d416dab 100644
--- a/doc/WritingErrorMessages.en.md
+++ b/doc/handwritten/for-users/WritingErrorMessages.en.md
@@ -212,7 +212,7 @@ For the stable title, description, rule, diagnostics, and examples, return to [W
 ---
 
 <div align="center">
-<a href="WritingErrorsGuide.en.md">← Writing Error Documentation</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="UsagePatterns.en.md">Usage Patterns →</a>
+<a href="WritingErrorsGuide.en.md">← Writing Error Documentation</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="UsagePatterns.en.md">Usage Patterns →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/WritingErrorMessages.fr.md b/doc/handwritten/for-users/WritingErrorMessages.fr.md
similarity index 100%
rename from doc/WritingErrorMessages.fr.md
rename to doc/handwritten/for-users/WritingErrorMessages.fr.md
diff --git a/doc/WritingErrorsGuide.en.md b/doc/handwritten/for-users/WritingErrorsGuide.en.md
similarity index 98%
rename from doc/WritingErrorsGuide.en.md
rename to doc/handwritten/for-users/WritingErrorsGuide.en.md
index 58f2bf9..ef65400 100644
--- a/doc/WritingErrorsGuide.en.md
+++ b/doc/handwritten/for-users/WritingErrorsGuide.en.md
@@ -218,7 +218,7 @@ For choosing public and internal runtime text, continue with [Writing Error Mess
 ---
 
 <div align="center">
-<a href="ErrorContext.en.md">← Error Context Guide</a> · <a href="../README.md#-next-steps">↑ Table of contents</a> · <a href="WritingErrorMessages.en.md">Writing Error Messages →</a>
+<a href="ErrorContext.en.md">← Error Context Guide</a> · <a href="../../../README.md#-documentation">↑ Table of contents</a> · <a href="WritingErrorMessages.en.md">Writing Error Messages →</a>
 </div>
 
 ---
\ No newline at end of file
diff --git a/doc/WritingErrorsGuide.fr.md b/doc/handwritten/for-users/WritingErrorsGuide.fr.md
similarity index 100%
rename from doc/WritingErrorsGuide.fr.md
rename to doc/handwritten/for-users/WritingErrorsGuide.fr.md
diff --git a/doc/analyzers/FCE001.en.md b/doc/handwritten/for-users/analyzers/FCE001.en.md
similarity index 100%
rename from doc/analyzers/FCE001.en.md
rename to doc/handwritten/for-users/analyzers/FCE001.en.md
diff --git a/doc/analyzers/FCE001.fr.md b/doc/handwritten/for-users/analyzers/FCE001.fr.md
similarity index 100%
rename from doc/analyzers/FCE001.fr.md
rename to doc/handwritten/for-users/analyzers/FCE001.fr.md
diff --git a/doc/analyzers/FCE002.en.md b/doc/handwritten/for-users/analyzers/FCE002.en.md
similarity index 100%
rename from doc/analyzers/FCE002.en.md
rename to doc/handwritten/for-users/analyzers/FCE002.en.md
diff --git a/doc/analyzers/FCE002.fr.md b/doc/handwritten/for-users/analyzers/FCE002.fr.md
similarity index 100%
rename from doc/analyzers/FCE002.fr.md
rename to doc/handwritten/for-users/analyzers/FCE002.fr.md
diff --git a/doc/analyzers/FCE003.en.md b/doc/handwritten/for-users/analyzers/FCE003.en.md
similarity index 100%
rename from doc/analyzers/FCE003.en.md
rename to doc/handwritten/for-users/analyzers/FCE003.en.md
diff --git a/doc/analyzers/FCE003.fr.md b/doc/handwritten/for-users/analyzers/FCE003.fr.md
similarity index 100%
rename from doc/analyzers/FCE003.fr.md
rename to doc/handwritten/for-users/analyzers/FCE003.fr.md
diff --git a/doc/analyzers/FCE004.en.md b/doc/handwritten/for-users/analyzers/FCE004.en.md
similarity index 100%
rename from doc/analyzers/FCE004.en.md
rename to doc/handwritten/for-users/analyzers/FCE004.en.md
diff --git a/doc/analyzers/FCE004.fr.md b/doc/handwritten/for-users/analyzers/FCE004.fr.md
similarity index 100%
rename from doc/analyzers/FCE004.fr.md
rename to doc/handwritten/for-users/analyzers/FCE004.fr.md
diff --git a/doc/analyzers/FCE005.en.md b/doc/handwritten/for-users/analyzers/FCE005.en.md
similarity index 100%
rename from doc/analyzers/FCE005.en.md
rename to doc/handwritten/for-users/analyzers/FCE005.en.md
diff --git a/doc/analyzers/FCE005.fr.md b/doc/handwritten/for-users/analyzers/FCE005.fr.md
similarity index 100%
rename from doc/analyzers/FCE005.fr.md
rename to doc/handwritten/for-users/analyzers/FCE005.fr.md
diff --git a/doc/analyzers/FCE006.en.md b/doc/handwritten/for-users/analyzers/FCE006.en.md
similarity index 100%
rename from doc/analyzers/FCE006.en.md
rename to doc/handwritten/for-users/analyzers/FCE006.en.md
diff --git a/doc/analyzers/FCE006.fr.md b/doc/handwritten/for-users/analyzers/FCE006.fr.md
similarity index 100%
rename from doc/analyzers/FCE006.fr.md
rename to doc/handwritten/for-users/analyzers/FCE006.fr.md
diff --git a/doc/analyzers/FCE007.en.md b/doc/handwritten/for-users/analyzers/FCE007.en.md
similarity index 100%
rename from doc/analyzers/FCE007.en.md
rename to doc/handwritten/for-users/analyzers/FCE007.en.md
diff --git a/doc/analyzers/FCE007.fr.md b/doc/handwritten/for-users/analyzers/FCE007.fr.md
similarity index 100%
rename from doc/analyzers/FCE007.fr.md
rename to doc/handwritten/for-users/analyzers/FCE007.fr.md
diff --git a/doc/analyzers/FCE008.en.md b/doc/handwritten/for-users/analyzers/FCE008.en.md
similarity index 100%
rename from doc/analyzers/FCE008.en.md
rename to doc/handwritten/for-users/analyzers/FCE008.en.md
diff --git a/doc/analyzers/FCE008.fr.md b/doc/handwritten/for-users/analyzers/FCE008.fr.md
similarity index 100%
rename from doc/analyzers/FCE008.fr.md
rename to doc/handwritten/for-users/analyzers/FCE008.fr.md
diff --git a/doc/analyzers/FCE009.en.md b/doc/handwritten/for-users/analyzers/FCE009.en.md
similarity index 100%
rename from doc/analyzers/FCE009.en.md
rename to doc/handwritten/for-users/analyzers/FCE009.en.md
diff --git a/doc/analyzers/FCE009.fr.md b/doc/handwritten/for-users/analyzers/FCE009.fr.md
similarity index 100%
rename from doc/analyzers/FCE009.fr.md
rename to doc/handwritten/for-users/analyzers/FCE009.fr.md
diff --git a/doc/analyzers/FCE010.en.md b/doc/handwritten/for-users/analyzers/FCE010.en.md
similarity index 100%
rename from doc/analyzers/FCE010.en.md
rename to doc/handwritten/for-users/analyzers/FCE010.en.md
diff --git a/doc/analyzers/FCE010.fr.md b/doc/handwritten/for-users/analyzers/FCE010.fr.md
similarity index 100%
rename from doc/analyzers/FCE010.fr.md
rename to doc/handwritten/for-users/analyzers/FCE010.fr.md
diff --git a/doc/analyzers/FCE011.en.md b/doc/handwritten/for-users/analyzers/FCE011.en.md
similarity index 100%
rename from doc/analyzers/FCE011.en.md
rename to doc/handwritten/for-users/analyzers/FCE011.en.md
diff --git a/doc/analyzers/FCE011.fr.md b/doc/handwritten/for-users/analyzers/FCE011.fr.md
similarity index 100%
rename from doc/analyzers/FCE011.fr.md
rename to doc/handwritten/for-users/analyzers/FCE011.fr.md
diff --git a/doc/analyzers/FCE012.en.md b/doc/handwritten/for-users/analyzers/FCE012.en.md
similarity index 100%
rename from doc/analyzers/FCE012.en.md
rename to doc/handwritten/for-users/analyzers/FCE012.en.md
diff --git a/doc/analyzers/FCE012.fr.md b/doc/handwritten/for-users/analyzers/FCE012.fr.md
similarity index 100%
rename from doc/analyzers/FCE012.fr.md
rename to doc/handwritten/for-users/analyzers/FCE012.fr.md
diff --git a/doc/analyzers/FCE013.en.md b/doc/handwritten/for-users/analyzers/FCE013.en.md
similarity index 100%
rename from doc/analyzers/FCE013.en.md
rename to doc/handwritten/for-users/analyzers/FCE013.en.md
diff --git a/doc/analyzers/FCE013.fr.md b/doc/handwritten/for-users/analyzers/FCE013.fr.md
similarity index 100%
rename from doc/analyzers/FCE013.fr.md
rename to doc/handwritten/for-users/analyzers/FCE013.fr.md
diff --git a/doc/analyzers/FCE014.en.md b/doc/handwritten/for-users/analyzers/FCE014.en.md
similarity index 100%
rename from doc/analyzers/FCE014.en.md
rename to doc/handwritten/for-users/analyzers/FCE014.en.md
diff --git a/doc/analyzers/FCE014.fr.md b/doc/handwritten/for-users/analyzers/FCE014.fr.md
similarity index 100%
rename from doc/analyzers/FCE014.fr.md
rename to doc/handwritten/for-users/analyzers/FCE014.fr.md
diff --git a/doc/analyzers/FCE015.en.md b/doc/handwritten/for-users/analyzers/FCE015.en.md
similarity index 100%
rename from doc/analyzers/FCE015.en.md
rename to doc/handwritten/for-users/analyzers/FCE015.en.md
diff --git a/doc/analyzers/FCE015.fr.md b/doc/handwritten/for-users/analyzers/FCE015.fr.md
similarity index 100%
rename from doc/analyzers/FCE015.fr.md
rename to doc/handwritten/for-users/analyzers/FCE015.fr.md
diff --git a/doc/analyzers/FCE016.en.md b/doc/handwritten/for-users/analyzers/FCE016.en.md
similarity index 100%
rename from doc/analyzers/FCE016.en.md
rename to doc/handwritten/for-users/analyzers/FCE016.en.md
diff --git a/doc/analyzers/FCE016.fr.md b/doc/handwritten/for-users/analyzers/FCE016.fr.md
similarity index 100%
rename from doc/analyzers/FCE016.fr.md
rename to doc/handwritten/for-users/analyzers/FCE016.fr.md
diff --git a/doc/analyzers/FCE017.en.md b/doc/handwritten/for-users/analyzers/FCE017.en.md
similarity index 100%
rename from doc/analyzers/FCE017.en.md
rename to doc/handwritten/for-users/analyzers/FCE017.en.md
diff --git a/doc/analyzers/FCE017.fr.md b/doc/handwritten/for-users/analyzers/FCE017.fr.md
similarity index 100%
rename from doc/analyzers/FCE017.fr.md
rename to doc/handwritten/for-users/analyzers/FCE017.fr.md
diff --git a/doc/analyzers/FCE018.en.md b/doc/handwritten/for-users/analyzers/FCE018.en.md
similarity index 100%
rename from doc/analyzers/FCE018.en.md
rename to doc/handwritten/for-users/analyzers/FCE018.en.md
diff --git a/doc/analyzers/FCE018.fr.md b/doc/handwritten/for-users/analyzers/FCE018.fr.md
similarity index 100%
rename from doc/analyzers/FCE018.fr.md
rename to doc/handwritten/for-users/analyzers/FCE018.fr.md
diff --git a/doc/analyzers/README.fr.md b/doc/handwritten/for-users/analyzers/README.fr.md
similarity index 100%
rename from doc/analyzers/README.fr.md
rename to doc/handwritten/for-users/analyzers/README.fr.md
diff --git a/doc/analyzers/README.md b/doc/handwritten/for-users/analyzers/README.md
similarity index 100%
rename from doc/analyzers/README.md
rename to doc/handwritten/for-users/analyzers/README.md
diff --git a/doc/images/first-class-errors.png b/doc/handwritten/for-users/images/first-class-errors.png
similarity index 100%
rename from doc/images/first-class-errors.png
rename to doc/handwritten/for-users/images/first-class-errors.png
diff --git a/tools/adr-check/collect-context.sh b/tools/adr-check/collect-context.sh
index 4897cda..2c2dbab 100755
--- a/tools/adr-check/collect-context.sh
+++ b/tools/adr-check/collect-context.sh
@@ -20,7 +20,7 @@ base="${1:?usage: collect-context.sh <base-ref>}"
 
 DIFF_MAX_BYTES="${DIFF_MAX_BYTES:-200000}"
 ADR_MAX_BYTES="${ADR_MAX_BYTES:-120000}"
-adr_dir="maintainers/adr"
+adr_dir="doc/handwritten/for-maintainers/adr"
 
 # --- changed files (a strong, cheap signal on its own) ------------------------
 # The set of touched paths already separates "only tests/docs" from "public API
diff --git a/tools/packaging/pack.sh b/tools/packaging/pack.sh
index ba7dc00..2f0c646 100755
--- a/tools/packaging/pack.sh
+++ b/tools/packaging/pack.sh
@@ -98,7 +98,7 @@ fi
 # content, so dropping the target (or PackAsTool ceasing to pack the publish output) would pass every local
 # check and only surface as "documentation worker could not be located" on a user's first `fce generate`.
 # A pack that stops bundling the worker must fail here, loudly, not in the field. This asserts presence; the
-# closure is completeness-checked out of band by the tool-install smoke test in maintainers/ReleaseDryRun.
+# closure is completeness-checked out of band by the tool-install smoke test in doc/handwritten/for-maintainers/ReleaseDryRun.
 if [ "$scope" = "cli" ]; then
   # The fce tool package carries the CLI's PackageId (FirstClassErrors.Cli), not the ToolCommandName (fce).
   for package in artifacts/FirstClassErrors.Cli.*.nupkg; do
diff --git a/tools/trains.sh b/tools/trains.sh
index 298da11..9902b8a 100644
--- a/tools/trains.sh
+++ b/tools/trains.sh
@@ -14,7 +14,7 @@
 # ── Adding a train ────────────────────────────────────────────────────────────
 # Add one row to trains_rows() below, then make the static edits GitHub forces
 # (tag trigger, choice options, commit-lint scopes, packaging). The full checklist
-# is maintainers/AddingAReleaseTrain.en.md.
+# is doc/handwritten/for-maintainers/AddingAReleaseTrain.en.md.
 #
 # Row format (pipe-separated, no spaces around the pipes except inside the label):
 #   <id>|<tag-prefix>|<scopes csv>|<changelog file>|<package label>