[docs] Move-only reorganization

.azure-pipelines/README.md

@@ -55,5 +55,5 @@ setting `dryRun` to `false`.
   request — it mirrors the ADO build stages on native hardware for faster
   developer iteration.
 - The ADO pipeline can also be triggered on PRs via `/azp run`
-  (see [docs/pull-requests.md](../docs/pull-requests.md)) when reviewers want
+  (see [pull request builds](../docs/development/build-and-test/pull-requests.md)) when reviewers want
   to run the official build against a change before merge.

.github/PULL_REQUEST_TEMPLATE.md

@@ -13,8 +13,8 @@
 - [ ] Signed the [Contributor License Agreement](https://cla.opensource.microsoft.com)
 - [ ] Linked to an issue
 - [ ] Updated documentation (if applicable)
-- [ ] Updated [Copilot instructions](.github/copilot-instructions.md) (if build, architecture, or conventions changed)
-- [ ] If this PR changes `Cargo.lock`, the `dependency-feed-check` check passes (see [docs/pull-requests.md](https://github.com/microsoft/mxc/blob/main/docs/pull-requests.md))
+- [ ] Updated [Copilot instructions](copilot-instructions.md) (if build, architecture, or conventions changed)
+- [ ] If this PR changes `Cargo.lock`, the `dependency-feed-check` check passes (see [pull request builds](https://github.com/microsoft/mxc/blob/main/docs/development/build-and-test/pull-requests.md))
 
 ## 📋 Issue Type
 <!-- Select the type that best describes this PR -->
@@ -27,8 +27,8 @@
 GitHub Actions runs the PR validation build automatically. The ADO pipeline
 (`MXC-PR-Build`) is the Azure version of the PR pipeline, kept in parity with the GitHub
 Actions build; it runs on merge to `main`, and Microsoft reviewers with write access can trigger it
-on a PR with `/azp run`. See [docs/pull-requests.md](https://github.com/microsoft/mxc/blob/main/docs/pull-requests.md).
+on a PR with `/azp run`. See [pull request builds](https://github.com/microsoft/mxc/blob/main/docs/development/build-and-test/pull-requests.md).
 
 If the `dependency-feed-check` check fails on a new dependency, the crate must be added to
-the feed before the PR can pass. See [docs/pull-requests.md](https://github.com/microsoft/mxc/blob/main/docs/pull-requests.md)
+the feed before the PR can pass. See [pull request builds](https://github.com/microsoft/mxc/blob/main/docs/development/build-and-test/pull-requests.md)
 for the steps.

.github/copilot-instructions.md

@@ -25,9 +25,9 @@ MXC (Microsoft eXecution Container) is a cross-platform sandboxed code execution
 See:
 
 - [`docs/schema.md`](../docs/schema.md)
-- [`docs/versioning.md`](../docs/versioning.md)
-- [`docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md`](../docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md)
-- [`docs/ci-validation-infrastructure.md`](../docs/ci-validation-infrastructure.md)
+- [`docs/development/architecture/versioning.md`](../docs/development/architecture/versioning.md)
+- [`docs/development/architecture/container-lifecycle.md`](../docs/development/architecture/container-lifecycle.md)
+- [`docs/development/build-and-test/ci-validation-infrastructure.md`](../docs/development/build-and-test/ci-validation-infrastructure.md)
 - The relevant backend guide under `docs/`
 
 ## Build and validation
@@ -71,7 +71,7 @@ npm run test:integration
 dotnet test --solution Microsoft.Mxc.Sdk.slnx
 ```
 
-Prefer the smallest test command covering the change. Host-dependent backend suites live under `tests/scripts/`; use the applicable backend guide and `docs/ci-validation-infrastructure.md` before running or changing them.
+Prefer the smallest test command covering the change. Host-dependent backend suites live under `tests/scripts/`; use the applicable backend guide and `docs/development/build-and-test/ci-validation-infrastructure.md` before running or changing them.
 
 ## Schema and policy rules
 
@@ -94,34 +94,34 @@ Prefer the smallest test command covering the change. Host-dependent backend sui
   serialize/deserialize check to `Microsoft.Mxc.Sdk.AotSmokeTest`; its CI AOT
   publish gate fails on any reflection-dependent path.
 
-See [`docs/schema-codegen.md`](../docs/schema-codegen.md) for regeneration commands.
+See [`docs/development/build-and-test/schema-codegen.md`](../docs/development/build-and-test/schema-codegen.md) for regeneration commands.
 
 ## Error and security behavior
 
 - Surface errors explicitly using repository error types and include actionable context.
 - Preserve panic containment across `mxc_ffi`; no panic may unwind through the C ABI.
 - Preserve exact resource ownership and cleanup contracts, especially for processes, jobs, traces, sessions, and native handles.
 - Do not weaken validation or convert failures into success-shaped fallbacks.
-- Telemetry is Windows-only, requires explicit user consent, and fails closed. Administrative policy may restrict consent but may never grant it. See [`docs/telemetry/`](../docs/telemetry/).
+- Telemetry is Windows-only, requires explicit user consent, and fails closed. Administrative policy may restrict consent but may never grant it. See [`docs/telemetry.md`](../docs/telemetry.md).
 
 ## Documentation
 
 Update documentation in the same change when behavior changes:
 
 - Schema or config fields: `docs/schema.md` and the applicable generated development artifacts.
-- Experimental features: `docs/authoring-a-new-feature.md`.
-- Versioning or promotion: `docs/versioning.md`.
+- Experimental features: `docs/development/guides/authoring-a-new-feature.md`.
+- Versioning or promotion: `docs/development/architecture/versioning.md`.
 - Backend behavior: the corresponding guide under `docs/`.
-- SDK APIs: the affected SDK README and versioned references under `docs/reference/{rust,dotnet,node}/v*/`.
-- Telemetry: `docs/telemetry/`.
-- CI validation: `docs/ci-validation-infrastructure.md`.
+- SDK APIs: the affected SDK README and versioned references under `docs/api-reference/{rust,dotnet,node}/v*/`.
+- Telemetry: `docs/telemetry.md`.
+- CI validation: `docs/development/build-and-test/ci-validation-infrastructure.md`.
 
 Do not duplicate detailed backend behavior here. Keep the canonical explanation in the subsystem documentation.
 
 ## SDK API consistency
 
 - Publish every SDK operation, type, probe, discovery API, telemetry API, and helper only through a supported versioned (V*) namespace/module/entrypoint.
-- Before adding or changing an API or type, compare the corresponding Rust, .NET, and Node references under `docs/reference/`. Align names, field meanings, defaults, optional-field presence, input order, and result/ownership semantics across SDKs.
+- Before adding or changing an API or type, compare the corresponding Rust, .NET, and Node references under `docs/api-reference/`. Align names, field meanings, defaults, optional-field presence, input order, and result/ownership semantics across SDKs.
 - Use language-idiomatic spelling and construction: Rust snake_case and enums, .NET PascalCase and closed SDK-owned classes, and TypeScript camelCase and discriminated unions. Do not force identical syntax or add convenience abstractions merely to imitate another language.
 - Keep authoring requests as typed data. Use consistent policy and backend configuration names; native adapters own wire mapping and the native engine owns semantic validation.
 - Keep API-specific controls in the API-specific options type. Creation takes request then options; existing-container execution takes identity, request, then options; .NET cancellation tokens come last.

.github/workflows/Dependency.Feed.Check.Job.yml

@@ -1,6 +1,6 @@
 # Resolves the locked dependency graph through the public MxcDependencies feed so a crate
 # not yet in the feed fails at PR time. On a 401, seed the crate by running the
-# MXC-Update-Feed-Dependencies pipeline in shine-oss with the PR's number (see docs/pull-requests.md).
+# MXC-Update-Feed-Dependencies pipeline in shine-oss with the PR's number (see docs/development/build-and-test/pull-requests.md).
 
 name: Dependency Feed Check
 
@@ -46,7 +46,7 @@ jobs:
           if grep -qiE '401|failed to get successful HTTP response' fetch.log; then
             echo "::error title=Crate may be missing from the MxcDependencies feed::A locked crate could not be fetched through the feed (HTTP 401 above). If this PR adds a new crates.io dependency, it must be added to the feed before this check can pass."
             echo "To add it: someone with Contributor access to the shine-oss Mxc project runs the MXC-Update-Feed-Dependencies pipeline using the Run pipeline button, with prNumber set to the PR's number."
-            echo "Details: docs/pull-requests.md (Dependency feed check)."
+            echo "Details: docs/development/build-and-test/pull-requests.md (Dependency feed check)."
           else
             echo "::error title=cargo fetch failed::cargo fetch failed for a reason other than a feed 401 (see the log above)."
           fi

CONTRIBUTING.md

@@ -107,16 +107,21 @@ Human-facing Markdown documentation includes one visible audience marker immedia
 
 Do not add these markers to legal text, GitHub templates or workflow prompts, or agent instruction files.
 
+Place developer-only documentation under the appropriate `docs/development/`
+subdirectory. Keep consumer and mixed-audience documentation in the main
+`docs/` tree, and keep implementation-specific READMEs beside the code or tests
+they describe.
+
 ### Experimental features
 
 New, in-development features use their permanent JSON locations in the mutable
 development contract. They may still require the binary's `--experimental`
 runtime authorization until graduation; that gate is independent of JSON
 placement. If you're adding a new feature, follow the step-by-step checklist in
-[`docs/authoring-a-new-feature.md`](./docs/authoring-a-new-feature.md), which
+[`docs/development/guides/authoring-a-new-feature.md`](./docs/development/guides/authoring-a-new-feature.md), which
 walks through the schema, Rust, and test-config changes required. The schema
 versioning model and promotion path from experimental to stable are described
-in [`docs/versioning.md`](./docs/versioning.md).
+in [`docs/development/architecture/versioning.md`](./docs/development/architecture/versioning.md).
 
 ### Help Wanted
 
@@ -269,7 +274,7 @@ PowerShell and shell helper scripts that drive the executor end-to-end live unde
 
 When the change is ready, mark the Draft PR as **Ready for Review**. The PR template asks you to confirm CLA acceptance and to update [`.github/copilot-instructions.md`](./.github/copilot-instructions.md) if your change affects build commands, project architecture, or key conventions.
 
-PR builds don't run automatically — Microsoft ADO policy requires a Microsoft employee to comment `/azp run` to start the `MXC-PR-Build` pipeline. See [`docs/pull-requests.md`](./docs/pull-requests.md) for details.
+PR builds don't run automatically — Microsoft ADO policy requires a Microsoft employee to comment `/azp run` to start the `MXC-PR-Build` pipeline. See [pull request builds](./docs/development/build-and-test/pull-requests.md) for details.
 
 Reviewers will look for:
 

README.md

@@ -38,7 +38,7 @@ backends** (`windows_sandbox`, `microvm`, and `hyperlight`) require
 `{ experimental: true }` in `SandboxSpawnOptions` or the `--experimental` CLI
 flag.
 
-For which filesystem, network, and UI-restriction policy aspects the Windows `processcontainer` backend can enforce on each Windows 11 release (23H2 / 24H2 / 25H2 / 25H2+), see [Windows OS-version policy support](./docs/process-container/os-version-support.md).
+For which filesystem, network, and UI-restriction policy aspects the Windows `processcontainer` backend can enforce on each Windows 11 release (23H2 / 24H2 / 25H2 / 25H2+), see [Windows OS-version policy support](./docs/backends/process-container/os-version-support.md).
 
 
 ### Requirements
@@ -59,7 +59,7 @@ tests/      Test collateral (configs, examples, scripts)
 scripts/    Build and utility scripts
 ```
 
-See [Repository architecture](docs/architecture.md) for the Rust workspace
+See [Repository architecture](docs/development/architecture/repository-architecture.md) for the Rust workspace
 layout, crate responsibilities, dependency direction, and execution surfaces.
 
 ### Full Build
@@ -237,7 +237,7 @@ See the [SDK README](sdk/node/README.md) for full API documentation.
 
 Released, immutable stable schemas live in [`schemas/stable/`](schemas/stable); the in-progress dev schema (experimental backends, state-aware lifecycle) lives in [`schemas/dev/`](schemas/dev). The current stable and dev versions are tracked canonically in [`schemas/schema-version.json`](schemas/schema-version.json).
 
-Pick the latest stable schema for new code on any supported platform. See [docs/versioning.md](docs/versioning.md) for the full versioning design.
+Pick the latest stable schema for new code on any supported platform. See [versioning design](docs/development/architecture/versioning.md) for the full versioning design.
 
 ## Debugging
 
@@ -249,7 +249,7 @@ By default, native binaries run in **silent mode** — stdin/stdout/stderr is co
 wxc-exec.exe --debug config.json
 ```
 
-See [docs/diagnostics.md](docs/diagnostics.md) for full diagnostics reference.
+See [diagnostics](docs/development/guides/diagnostics.md) for the full developer reference.
 
 ### Request-aware ProcessContainer probe
 
@@ -270,7 +270,7 @@ wxc-exec.exe --audit policy.json
 
 Successful non-dry-run audits require capture metadata, actionable denials JSON, its verbose diagnostic sibling, and a retained ETL. The CLI relocates the backend-selected paths to `denials.json`, `denials.verbose.json`, and `trace.etl` in the per-user audit directory, then generates a source-config snapshot and `Adjusted_*.json` from the actionable JSON without decoding the ETL again. Base64-only input keeps both JSON files and the ETL but has no source config to snapshot or adjust. Truncated analysis keeps both JSON files, the ETL, and the source snapshot but skips adjusted-config generation. Use `--audit-verbose` to print learned-policy details.
 
-> **Warning:** `--audit` injects `permissiveLearningMode` — AppContainer restrictions are **not** enforced for the duration of the run. Use only for policy authoring. It cannot be combined with `processContainer.captureDenials`; use `captureDenials.mode: "allow"` for permissive application-driven capture. `learningModeLogging` and `permissiveLearningMode` are reserved internal capability names and are rejected in `processContainer.capabilities`. See [docs/learning-mode/capabilities.md](docs/learning-mode/capabilities.md) for the three learning-mode flows.
+> **Warning:** `--audit` injects `permissiveLearningMode` — AppContainer restrictions are **not** enforced for the duration of the run. Use only for policy authoring. It cannot be combined with `processContainer.captureDenials`; use `captureDenials.mode: "allow"` for permissive application-driven capture. `learningModeLogging` and `permissiveLearningMode` are reserved internal capability names and are rejected in `processContainer.capabilities`. See [logging access denied](docs/logging-access-denied.md) for the three learning-mode flows.
 
 ## Telemetry
 
@@ -322,27 +322,29 @@ Privacy information can be found at https://privacy.microsoft.com and in the Mic
 
 ## Documentation
 
+Repository contributors can browse the [development documentation](docs/development/README.md).
+
 | Document | Description |
 |----------|-------------|
-| [docs/architecture.md](docs/architecture.md) | Repository layout, crate boundaries, and execution surfaces |
+| [Repository architecture](docs/development/architecture/repository-architecture.md) | Repository layout, crate boundaries, and execution surfaces |
 | [docs/schema.md](docs/schema.md) | Full JSON configuration schema reference |
-| [docs/versioning.md](docs/versioning.md) | Schema versioning and experimental feature lifecycle |
+| [Versioning design](docs/development/architecture/versioning.md) | Schema versioning and experimental feature lifecycle |
 | [docs/examples.md](docs/examples.md) | Annotated configuration examples |
-| [docs/ci-validation-infrastructure.md](docs/ci-validation-infrastructure.md) | Scheduled backend validation matrix and CI dispatch |
+| [CI validation infrastructure](docs/development/build-and-test/ci-validation-infrastructure.md) | Scheduled backend validation matrix and CI dispatch |
 | [tests/scripts/README.md](tests/scripts/README.md) | Local and CI backend test suites |
-| [docs/host-prep.md](docs/host-prep.md) | Windows host preparation (`wxc-host-prep.exe`) |
-| [docs/diagnostics.md](docs/diagnostics.md) | Diagnostic logging and ETW |
-| [docs/sandbox-policy/0.7.0/policy.md](docs/sandbox-policy/0.7.0/policy.md) | Sandbox policy 0.7.0 specification |
-| [docs/process-container/guide.md](docs/process-container/guide.md) | Windows AppContainer / BaseContainer guide |
-| [docs/lxc-support/lxc-backend.md](docs/lxc-support/lxc-backend.md) | LXC backend (Linux) |
-| [docs/bwrap-support/bubblewrap-backend.md](docs/bwrap-support/bubblewrap-backend.md) | Bubblewrap backend (Linux) |
-| [docs/seatbelt/seatbelt-backend.md](docs/seatbelt/seatbelt-backend.md) | Seatbelt backend (macOS) |
-| [docs/windows-sandbox/windows-sandbox.md](docs/windows-sandbox/windows-sandbox.md) | Windows Sandbox backend |
-| [docs/hyperlight/hyperlight-backend.md](docs/hyperlight/hyperlight-backend.md) | Hyperlight backend (Linux, Windows) |
-| [docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md](docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md) | State-aware sandbox lifecycle API |
-| [docs/telemetry/telemetry.md](docs/telemetry/telemetry.md) | TraceLogging telemetry architecture |
-| [docs/telemetry/telemetry-consent-design.md](docs/telemetry/telemetry-consent-design.md) | Telemetry consent contract |
-| [docs/telemetry/telemetry-administrative-policy.md](docs/telemetry/telemetry-administrative-policy.md) | Administrative telemetry controls |
+| [Host preparation](docs/backends/process-container/host-prep.md) | Windows host preparation (`wxc-host-prep.exe`) |
+| [Diagnostics](docs/development/guides/diagnostics.md) | Diagnostic logging and ETW |
+| [Containment configuration 0.7.0](docs/containment-configuration/0.7.0/policy.md) | Containment configuration 0.7.0 specification |
+| [Adding ProcessContainer OS features](docs/development/guides/process-container-adding-os-features.md) | Windows AppContainer / BaseContainer developer guide |
+| [docs/backends/lxc/lxc-backend.md](docs/backends/lxc/lxc-backend.md) | LXC backend (Linux) |
+| [docs/backends/bwrap/bubblewrap-backend.md](docs/backends/bwrap/bubblewrap-backend.md) | Bubblewrap backend (Linux) |
+| [docs/backends/seatbelt/seatbelt-backend.md](docs/backends/seatbelt/seatbelt-backend.md) | Seatbelt backend (macOS) |
+| [docs/backends/windows-sandbox/windows-sandbox.md](docs/backends/windows-sandbox/windows-sandbox.md) | Windows Sandbox backend |
+| [docs/backends/hyperlight/hyperlight-backend.md](docs/backends/hyperlight/hyperlight-backend.md) | Hyperlight backend (Linux, Windows) |
+| [Container lifecycle](docs/container-lifecycle.md) | Public container lifecycle API |
+| [Telemetry architecture](docs/development/architecture/telemetry.md) | TraceLogging telemetry architecture |
+| [Telemetry consent design](docs/development/architecture/telemetry-consent-design.md) | Telemetry consent contract |
+| [docs/telemetry.md](docs/telemetry.md) | Administrative telemetry controls |
 
 ## Contributing
 

build-mac.sh

@@ -4,7 +4,7 @@
 # TypeScript SDK. This is the macOS counterpart of build.sh.
 #
 # Codesigning + notarization are NOT performed here — those run later as a
-# release-time step (see docs/seatbelt/seatbelt-backend.md). This script just
+# release-time step (see docs/backends/seatbelt/seatbelt-backend.md). This script just
 # produces an unsigned binary suitable for local development.
 
 set -euo pipefail
@@ -173,4 +173,4 @@ for triple in "${TARGETS[@]}"; do
 done
 echo ""
 echo "Note: this binary is unsigned. Codesigning + notarization happen at"
-echo "release time (see docs/seatbelt/seatbelt-backend.md, codesign-notarize todo)."
+echo "release time (see docs/backends/seatbelt/seatbelt-backend.md, codesign-notarize todo)."