docs(structure): updated the docs to use new sub-folder format

.gitignore

@@ -664,5 +664,5 @@ sketch
 
 # Purview addition, not in the SDK's template: the skills CLI's universal install location. An
 # install is reproducible from skills-lock.json, and it must not appear as an untracked change in
-# somebody's working tree. See docs/wiki/Agent-Enablement.md.
+# somebody's working tree. See docs/wiki/agents/Agent-Enablement.md.
 .agents/

AGENTS.md

@@ -56,7 +56,8 @@ demonstrate it.
 
 ## Documentation conventions
 
-- **One page per concern**, in `docs/wiki/<Page-Name>.md`. Title case, hyphens between words.
+- **One page per concern**, in `docs/wiki/<Section>/<Page-Name>.md`. The section is the topic folder,
+  the file name is title case with hyphens between words, and the folder name is lower-case.
 - **Four sections, in order:** the rule, why, how it is enforced, at your scale. A rule a build cannot check
   is labelled a review obligation — never described as enforced. `Home.md` and `index.md` are navigation,
   and `Engineering-Principles.md` is an index that links to the page stating each rule in full.
@@ -76,7 +77,7 @@ Authored skills live in `skills/<name>/SKILL.md` at the repository root. `.agent
 CLI's install location for skills from **other** repositories and is gitignored; this repository's own
 skills are never installed into it, because two copies drift apart. A skill states when it applies in its
 `description`, keeps the workflow in `SKILL.md`, and pushes detail into `references/`. See
-[Agent Skills Distribution](docs/wiki/Agent-Skills-Distribution.md).
+[Agent Skills Distribution](docs/wiki/agents/Agent-Skills-Distribution.md).
 
 Nothing packs a skill into a NuGet package - `Purview.BuildSdk` 1.0.6 removed skill packaging and the
 build-time `.agents/` mirror outright. The skills CLI clones the git repository, and that is the only route.
@@ -130,13 +131,13 @@ These apply only when the repository persists data; a stateless CLI or a pure li
 
 - **A value known before storage is derived, not generated.** Use UUIDv5 over an installation-scoped
   namespace and key it `ValueGeneratedNever()`, so a sequential convention never overwrites it. See
-  [Well-Known Identifiers](docs/wiki/Well-Known-Identifiers.md).
+  [Well-Known Identifiers](docs/wiki/data/Well-Known-Identifiers.md).
 - **Every other GUID key uses one strategy per store.** SQL Server and PostgreSQL order GUIDs
   differently, so the strategy is carried as context-options data and applied by a model-finalising
-  convention. See [GUID Key Strategy](docs/wiki/Guid-Key-Strategy.md).
+  convention. See [GUID Key Strategy](docs/wiki/data/Guid-Key-Strategy.md).
 - **EF Core is the boundary.** Use `DbContext` directly rather than a repository added for testability;
   map value objects once; keep design-time and runtime options in step; apply migrations deliberately.
-  See [EF Core Integration](docs/wiki/EF-Core-Integration.md).
+  See [EF Core Integration](docs/wiki/data/EF-Core-Integration.md).
 - **The runnable evidence is the sample.** `samples/Acme.Persistence` is outside `src/` and outside the
   canonical solution; `just samples` builds, runs and self-checks it. Run it when you change the sample
   or an identifier convention.
@@ -167,7 +168,7 @@ Before handing work back:
   `continue-on-error` or `|| true` on a check, no force-push over a protected ref. If a hook is wrong or
   too slow, change the hook in its own reviewed change. "CI will run the same thing anyway" is a claim
   about a different run, made by the party being checked — and a bypass leaves no trace, which is why it
-  is never a judgement call. See [Verification Model](docs/wiki/Verification-Model.md).
+  is never a judgement call. See [Verification Model](docs/wiki/foundations/Verification-Model.md).
 - Confirm the requested behaviour and scope are satisfied, and that only intended files changed.
 - If a rule was added or changed: the page states the failure it prevents, says whether it is enforced or a
   review obligation, has an "at your scale" section, is in `_Sidebar.md` and the `Home.md` table, and is

README.md

@@ -14,31 +14,31 @@ coding agents are enabled to work in a codebase without hand-holding.
 | -- | -- |
 | [Getting started](docs/wiki/Getting-Started.md) | What is the smallest repository that satisfies every rule, in the order you build it? |
 | [Engineering principles](docs/wiki/Engineering-Principles.md) | What are the non-negotiable rules, and where is each one stated in full? |
-| [Repository shape](docs/wiki/Repository-Shape.md) | Where does a file go, and what is it called? |
-| [Project responsibilities](docs/wiki/Project-Responsibilities.md) | What is each project for, how is it named, and what may it depend on? |
-| [Architecture as tests](docs/wiki/Architecture-As-Tests.md) | How does the build refuse a dependency that points the wrong way? |
-| [Verification model](docs/wiki/Verification-Model.md) | Which checks run, in which tier, for which change? |
-| [Contracts and data exchange](docs/wiki/Contracts-And-Data-Exchange.md) | How do value objects, schemas and results cross a boundary? |
-| [Well-known identifiers](docs/wiki/Well-Known-Identifiers.md) | How is an identity derived so every process and restart agrees? |
-| [GUID key strategy](docs/wiki/Guid-Key-Strategy.md) | How is a sequential GUID key chosen and applied per store? |
-| [EF Core integration](docs/wiki/EF-Core-Integration.md) | How do the context, providers, value objects, models and migrations fit together? |
-| [Testing and test data](docs/wiki/Testing-And-Test-Data.md) | How are tests written, and where does their data come from? |
-| [Agent enablement](docs/wiki/Agent-Enablement.md) | How is a repository made legible to a coding agent? |
-| [Agent skills distribution](docs/wiki/Agent-Skills-Distribution.md) | How is a skill published once and reach an agent? |
-| [Agent guidance skills](docs/wiki/Agent-Guidance-Skills.md) | Which shared guidance ships as a skill, and what context comes first? |
-| [Documentation convention](docs/wiki/Documentation-Convention.md) | How is the wiki written, structured and published? |
-| [Worked examples](docs/wiki/Worked-Examples.md) | What does the reference implementation under `src/` actually demonstrate? |
-| [Adopting this at your scale](docs/wiki/Adopting-This-At-Your-Scale.md) | Which parts apply to a small, medium or large repository? |
-| [Contributing](docs/wiki/Contributing.md) | How do I change the playbook itself? |
-| [Release flow](docs/wiki/Release-Flow.md) | How does a change become a version, and what does a release mean here? |
+| [Repository shape](docs/wiki/foundations/Repository-Shape.md) | Where does a file go, and what is it called? |
+| [Project responsibilities](docs/wiki/foundations/Project-Responsibilities.md) | What is each project for, how is it named, and what may it depend on? |
+| [Architecture as tests](docs/wiki/foundations/Architecture-As-Tests.md) | How does the build refuse a dependency that points the wrong way? |
+| [Verification model](docs/wiki/foundations/Verification-Model.md) | Which checks run, in which tier, for which change? |
+| [Contracts and data exchange](docs/wiki/data/Contracts-And-Data-Exchange.md) | How do value objects, schemas and results cross a boundary? |
+| [Well-known identifiers](docs/wiki/data/Well-Known-Identifiers.md) | How is an identity derived so every process and restart agrees? |
+| [GUID key strategy](docs/wiki/data/Guid-Key-Strategy.md) | How is a sequential GUID key chosen and applied per store? |
+| [EF Core integration](docs/wiki/data/EF-Core-Integration.md) | How do the context, providers, value objects, models and migrations fit together? |
+| [Testing and test data](docs/wiki/testing/Testing-And-Test-Data.md) | How are tests written, and where does their data come from? |
+| [Agent enablement](docs/wiki/agents/Agent-Enablement.md) | How is a repository made legible to a coding agent? |
+| [Agent skills distribution](docs/wiki/agents/Agent-Skills-Distribution.md) | How is a skill published once and reach an agent? |
+| [Agent guidance skills](docs/wiki/agents/Agent-Guidance-Skills.md) | Which shared guidance ships as a skill, and what context comes first? |
+| [Documentation convention](docs/wiki/foundations/Documentation-Convention.md) | How is the wiki written, structured and published? |
+| [Worked examples](docs/wiki/examples/Worked-Examples.md) | What does the reference implementation under `src/` actually demonstrate? |
+| [Adopting this at your scale](docs/wiki/governance/Adopting-This-At-Your-Scale.md) | Which parts apply to a small, medium or large repository? |
+| [Contributing](docs/wiki/governance/Contributing.md) | How do I change the playbook itself? |
+| [Release flow](docs/wiki/governance/Release-Flow.md) | How does a change become a version, and what does a release mean here? |
 
 ## Start here
 
 - **New to the playbook?** [Getting started](docs/wiki/Getting-Started.md) walks the smallest
   repository that satisfies every rule.
-- **Adopting it?** [Adopting this at your scale](docs/wiki/Adopting-This-At-Your-Scale.md) picks the
+- **Adopting it?** [Adopting this at your scale](docs/wiki/governance/Adopting-This-At-Your-Scale.md) picks the
   subset that fits, and [`templates/`](templates) is the copy-paste starting point.
-- **Want to see it run?** [Worked examples](docs/wiki/Worked-Examples.md) walks the reference
+- **Want to see it run?** [Worked examples](docs/wiki/examples/Worked-Examples.md) walks the reference
   implementation under [`src/`](src), which this repository's own pipeline builds and tests.
 
 ## Repository layout

docs/wiki/Engineering-Principles.md

@@ -13,16 +13,16 @@ A rule that claims enforcement it does not have is worse than no rule, because p
 
 | # | Principle | In one line | Detail |
 | -- | -- | -- | -- |
-| 1 | Convention over configuration | A repository declares as little as possible; one MSBuild SDK supplies the defaults, so a project file is short. | [Repository Shape](Repository-Shape.md) |
-| 2 | Identity is derived, never repeated | A name appears once, in the folder and file name; `RootNamespace` and `AssemblyName` are computed from it. | [Repository Shape](Repository-Shape.md) |
-| 3 | Architecture is a test, not a diagram | The dependencies a layer may have are asserted by tests, so a wrong `ProjectReference` fails the build. | [Architecture as Tests](Architecture-As-Tests.md), [Project Responsibilities](Project-Responsibilities.md) |
-| 4 | The build is the only authority | A convention a build can check is checked by the build; the rest is labelled a review obligation, never described as enforced. | [Documentation Convention](Documentation-Convention.md) |
-| 5 | Warnings are not acceptable output | A clean build has no warnings: fix one, suppress it where it occurs with a justification, or turn the rule off deliberately. | [Testing and Test Data](Testing-And-Test-Data.md) |
-| 6 | Every claim about a consumer is proved by a consumer | A package that documents how it must be used ships something that builds that documented consumer and asserts the documented outcome. | [Contracts and Data Exchange](Contracts-And-Data-Exchange.md) |
-| 7 | Documentation is a build artefact of the repository | The wiki lives in the repository it describes, and the repository owns its `mkdocs.yml`, navigation and `edit_uri`. | [Documentation Convention](Documentation-Convention.md) |
-| 8 | Everything a test needs is built by one builder | Domain content in a test comes from `TestBuilder`; a test overrides only the value it is proving. | [Testing and Test Data](Testing-And-Test-Data.md) |
-| 9 | An agent is a reader with no memory | A repository states its purpose, layout and conventions in `AGENTS.md`; nothing important is discoverable only from the code. | [Agent Enablement](Agent-Enablement.md) |
-| 10 | A change is verified in proportion to its risk | Checks are tiered; a pull request runs the fast tier, and the slow tier is run deliberately. | [Verification Model](Verification-Model.md) |
+| 1 | Convention over configuration | A repository declares as little as possible; one MSBuild SDK supplies the defaults, so a project file is short. | [Repository Shape](foundations/Repository-Shape.md) |
+| 2 | Identity is derived, never repeated | A name appears once, in the folder and file name; `RootNamespace` and `AssemblyName` are computed from it. | [Repository Shape](foundations/Repository-Shape.md) |
+| 3 | Architecture is a test, not a diagram | The dependencies a layer may have are asserted by tests, so a wrong `ProjectReference` fails the build. | [Architecture as Tests](foundations/Architecture-As-Tests.md), [Project Responsibilities](foundations/Project-Responsibilities.md) |
+| 4 | The build is the only authority | A convention a build can check is checked by the build; the rest is labelled a review obligation, never described as enforced. | [Documentation Convention](foundations/Documentation-Convention.md) |
+| 5 | Warnings are not acceptable output | A clean build has no warnings: fix one, suppress it where it occurs with a justification, or turn the rule off deliberately. | [Testing and Test Data](testing/Testing-And-Test-Data.md) |
+| 6 | Every claim about a consumer is proved by a consumer | A package that documents how it must be used ships something that builds that documented consumer and asserts the documented outcome. | [Contracts and Data Exchange](data/Contracts-And-Data-Exchange.md) |
+| 7 | Documentation is a build artefact of the repository | The wiki lives in the repository it describes, and the repository owns its `mkdocs.yml`, navigation and `edit_uri`. | [Documentation Convention](foundations/Documentation-Convention.md) |
+| 8 | Everything a test needs is built by one builder | Domain content in a test comes from `TestBuilder`; a test overrides only the value it is proving. | [Testing and Test Data](testing/Testing-And-Test-Data.md) |
+| 9 | An agent is a reader with no memory | A repository states its purpose, layout and conventions in `AGENTS.md`; nothing important is discoverable only from the code. | [Agent Enablement](agents/Agent-Enablement.md) |
+| 10 | A change is verified in proportion to its risk | Checks are tiered; a pull request runs the fast tier, and the slow tier is run deliberately. | [Verification Model](foundations/Verification-Model.md) |
 
 ### Conditional persistence rules
 
@@ -32,9 +32,9 @@ silent there. Each is stated in full on its own page.
 
 | Rule | In one line | Detail | Page |
 | -- | -- | -- | -- |
-| P1 | A value known before storage is derived, not generated | UUIDv5 over an installation-scoped namespace, keyed `ValueGeneratedNever()` so no generator overwrites it. | [Well-Known Identifiers](Well-Known-Identifiers.md) |
-| P2 | A GUID key strategy is chosen once per store | One provider-specific strategy, carried as context-options data and applied to every key by convention. | [GUID Key Strategy](Guid-Key-Strategy.md) |
-| P3 | EF Core is the persistence boundary | `DbContext` used directly, value objects mapped once, design-time and runtime options in step, migrations applied deliberately. | [EF Core Integration](EF-Core-Integration.md) |
+| P1 | A value known before storage is derived, not generated | UUIDv5 over an installation-scoped namespace, keyed `ValueGeneratedNever()` so no generator overwrites it. | [Well-Known Identifiers](data/Well-Known-Identifiers.md) |
+| P2 | A GUID key strategy is chosen once per store | One provider-specific strategy, carried as context-options data and applied to every key by convention. | [GUID Key Strategy](data/Guid-Key-Strategy.md) |
+| P3 | EF Core is the persistence boundary | `DbContext` used directly, value objects mapped once, design-time and runtime options in step, migrations applied deliberately. | [EF Core Integration](data/EF-Core-Integration.md) |
 
 Enforcement is stated per rule on the linked page. Three of the ten are enforced by the build in a way
 worth knowing at a glance: identity (rule 2) by `PurviewProjectFileNameMismatch` and the SDK's
@@ -45,7 +45,7 @@ says which.
 ## At your scale
 
 Every rule has a smaller version, and taking one before the problem it prevents exists is pure cost.
-[Adopting This at Your Scale](Adopting-This-At-Your-Scale.md) decides which rules apply to a small,
+[Adopting This at Your Scale](governance/Adopting-This-At-Your-Scale.md) decides which rules apply to a small,
 medium or large repository, and in what order to adopt them.
 
 The conditional persistence rules are the clearest example: a repository that stores nothing takes none
@@ -54,11 +54,11 @@ of them, and a repository with low write volume takes only P3. The smaller versi
 
 ## See also
 
-- [Repository Shape](Repository-Shape.md)
-- [Architecture as Tests](Architecture-As-Tests.md)
-- [Verification Model](Verification-Model.md)
-- [Testing and Test Data](Testing-And-Test-Data.md)
-- [Well-Known Identifiers](Well-Known-Identifiers.md)
-- [GUID Key Strategy](Guid-Key-Strategy.md)
-- [EF Core Integration](EF-Core-Integration.md)
-- [Adopting This at Your Scale](Adopting-This-At-Your-Scale.md)
+- [Repository Shape](foundations/Repository-Shape.md)
+- [Architecture as Tests](foundations/Architecture-As-Tests.md)
+- [Verification Model](foundations/Verification-Model.md)
+- [Testing and Test Data](testing/Testing-And-Test-Data.md)
+- [Well-Known Identifiers](data/Well-Known-Identifiers.md)
+- [GUID Key Strategy](data/Guid-Key-Strategy.md)
+- [EF Core Integration](data/EF-Core-Integration.md)
+- [Adopting This at Your Scale](governance/Adopting-This-At-Your-Scale.md)