📖 [Docs]: Document architecture and memory boundaries

CONTRIBUTING.md

@@ -78,6 +78,10 @@ index and drill down to the right page. Three conventions make that work.
   `src/zensical.toml`, and fills every index in place. CI runs the same script with `-Check`
   and fails if an index is out of date.
 
+Choose a page's home by subject first, then by the artifact that answers the reader's
+question. The [Documentation Model](https://msxorg.github.io/docs/Ways-of-Working/Documentation-Model/#architecture-and-classification)
+defines those artifact tiers and the deliberate use of minimal OKF-style front matter.
+
 Links are validated the same way: `.github/scripts/Test-DocumentationLink.ps1` checks that
 every relative link and heading anchor across the docs resolves, and
 `.github/scripts/Test-CrossRepositoryLink.ps1` resolves every link into another MSX

src/docs/Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md

@@ -0,0 +1,48 @@
+---
+title: Document architecture and memory boundaries
+description: The topic-and-artifact documentation model, minimal OKF-style metadata, and separate durable memory repository.
+---
+
+# Document architecture and memory boundaries
+
+## Context
+
+MSX documentation is navigable cheaply by humans and agents, agent
+configuration points to canonical knowledge, and durable lessons have a shared
+home. The architecture establishes those boundaries without duplicating
+documentation across classifications or repositories.
+
+## Decision
+
+MSX uses the [Documentation Model](../../../Ways-of-Working/Documentation-Model.md)
+as the documentation architecture:
+
+- Paths are topic- and scope-oriented, and every area is navigated through
+  `index.md`.
+- The spec, design, guide, reference, decision-record, and research artifact
+  tiers classify content by the reader's need.
+- Pages use the minimal OKF-style model: Markdown, YAML `title` and
+  `description` front matter, one primary concept per page, and stable paths.
+- `MSXOrg/docs` remains the reviewed, pull-request-only canonical knowledge
+  base. Durable working knowledge belongs in the separate private
+  `MSXOrg/memory` repository; session notes remain local and ignored.
+
+MSX does not add Diataxis quadrant directories or `diataxis` metadata. The
+artifact tiers already route the same reader needs while keeping related
+subject matter together. MSX also does not adopt strict OKF conformance fields
+or per-area `log.md` files: the only metadata queried by navigation is title
+and description, and Git history is the authoritative changelog.
+
+## Consequences
+
+Contributors file a page by subject and artifact tier, then run the index
+generator. Readers and agents traverse the same indexes without loading an
+unrelated quadrant. Tooling validates the metadata it consumes and validates
+links, while review keeps page boundaries and cross-references coherent.
+
+Agents propose changes to canonical documentation through pull requests.
+Agents commit durable, factual lessons to `MSXOrg/memory` under its
+[memory-writing rules](../design.md#memory-writing-rules); they never use this
+public documentation repository as a low-ceremony dump.
+
+Changes to these boundaries use a new decision record that supersedes this one.

src/docs/Capabilities/agentic-development/decisions/index.md

@@ -0,0 +1,17 @@
+---
+title: Agentic Development decisions
+description: Immutable records of one-way-door choices in the agentic development framework.
+---
+
+# Agentic Development decisions
+
+These records explain choices that constrain the framework. A later decision
+supersedes an earlier one; it does not rewrite it.
+
+<!-- INDEX:START -->
+
+| Page | Description |
+| --- | --- |
+| [Document architecture and memory boundaries](document-architecture-and-memory-boundaries.md) | The topic-and-artifact documentation model, minimal OKF-style metadata, and separate durable memory repository. |
+
+<!-- INDEX:END -->

src/docs/Capabilities/agentic-development/index.md

@@ -22,5 +22,6 @@ A repository adopts the framework by carrying a short router and the client rout
 | [Agent Interaction](agent-interaction.md) | How humans and agents coordinate through issues, labels, and pull requests, and why intent and implementation are kept in separate artifacts. |
 | [Advisory Agents](advisory-agents.md) | The pattern for automation that analyses work and publishes its conclusion as advice, without deciding, relabelling, or committing. |
 | [Conformance](conformance.md) | What a repository must provide to be conformant with the agentic development framework, what it may add, and the duplication checks that keep the router thin. |
+| [Agentic Development decisions](decisions/index.md) | Immutable records of one-way-door choices in the agentic development framework. |
 
 <!-- INDEX:END -->

src/docs/Capabilities/deployment/designs/index.md

@@ -0,0 +1,18 @@
+---
+title: Deployment designs
+description: How the deployment contract is delivered for each service-provider and CI/CD-platform combination.
+---
+
+# Deployment designs
+
+Each page in this section delivers the [Deployment spec](../spec.md) for one
+service-provider and CI/CD-platform combination. Add a design here without
+changing the technology-agnostic contract.
+
+<!-- INDEX:START -->
+
+| Page | Description |
+| --- | --- |
+| [Deploying Azure from GitHub](azure-from-github.md) | How the deployment spec is delivered with Azure as the service provider and GitHub as the CI/CD platform, using Terraform to compute and apply the approved effect. |
+
+<!-- INDEX:END -->

src/docs/Capabilities/deployment/index.md

@@ -29,4 +29,4 @@ combination adds a design; it never changes the spec.
 
 | Design | Service provider | CI/CD platform | Description |
 | --- | --- | --- | --- |
-| [Deploying Azure from GitHub](designs/azure-from-github.md) | Azure | GitHub | GitHub Actions and Terraform deploy Azure and Entra resources with passwordless identity, approving the code change together with its per-environment effect. |
+| [Designs](designs/index.md) | — | — | Deployment designs, one for each service-provider and CI/CD-platform combination. |

src/docs/Ways-of-Working/Documentation-Model.md

@@ -176,6 +176,32 @@ being long.
   describe. Laziness is a design constraint — the less a reader must travel, the
   more they actually read.
 
+## Architecture and classification
+
+The documentation tree is organized **by scope and subject**, then by the
+artifact that answers the reader's question. A reader starts at the root
+`index.md`, chooses the relevant topic, and follows that topic's index inward.
+This keeps related material together without requiring a reader to decide
+whether they need a tutorial, guide, reference, or explanation before they can
+find the subject.
+
+The artifact tiers provide the second classification:
+
+| Reader need | Owning artifact |
+| --- | --- |
+| Understand why a capability exists and what it guarantees | Spec |
+| Understand how the capability is delivered | Design |
+| Perform a task against a capability | Guide |
+| Look up stable facts or values | Reference |
+| Understand a one-way-door choice | Decision record |
+| Revisit point-in-time findings | Research |
+
+This maps the useful reader needs behind Diataxis without imposing a second,
+parallel taxonomy in paths or front matter. A page has one home under its
+subject and links to adjacent artifacts rather than being duplicated across
+quadrants. [Document architecture and memory boundaries](../Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md)
+records that decision and the corresponding OKF and memory boundaries.
+
 ## For humans and agents
 
 The same pages serve both. A contributor reads the index, follows the

src/zensical.toml

@@ -152,7 +152,10 @@ nav = [
     {"Deployment" = [
       "Capabilities/deployment/index.md",
       {"Spec" = "Capabilities/deployment/spec.md"},
-      {"Deploying Azure from GitHub" = "Capabilities/deployment/designs/azure-from-github.md"},
+      {"Designs" = [
+        "Capabilities/deployment/designs/index.md",
+        {"Deploying Azure from GitHub" = "Capabilities/deployment/designs/azure-from-github.md"},
+      ]},
     ]},
     {"VS Code Extension Framework" = [
       "Capabilities/vscode-extension-framework/index.md",
@@ -175,6 +178,10 @@ nav = [
       {"Agent Interaction" = "Capabilities/agentic-development/agent-interaction.md"},
       {"Advisory Agents" = "Capabilities/agentic-development/advisory-agents.md"},
       {"Conformance" = "Capabilities/agentic-development/conformance.md"},
+      {"Decisions" = [
+        "Capabilities/agentic-development/decisions/index.md",
+        {"Document Architecture and Memory Boundaries" = "Capabilities/agentic-development/decisions/document-architecture-and-memory-boundaries.md"},
+      ]},
     ]},
   ]},
   {"Dictionary" = "Dictionary/index.md"},