docs: FHS-categorize all operator docs; move agent contract to usr/share/mios/ai/

Project invariant per user direction: regular documentation is
categorized and stored according to OpenAI-API-style topical groupings
under usr/share/doc/mios/{concepts,guides,reference,audits}/ (FHS 3.0
canonical doc path). The agent-facing architectural-laws contract and
audit-mode prompt live under usr/share/mios/ai/ alongside system.md.

Moves (git mv preserves history):
- INDEX.md                  -> usr/share/mios/ai/INDEX.md
- CLAUDE.AUDIT.md           -> usr/share/mios/ai/audit-prompt.md
- ARCHITECTURE.md           -> usr/share/doc/mios/concepts/architecture.md
- ENGINEERING.md            -> usr/share/doc/mios/guides/engineering.md
- DEPLOY.md                 -> usr/share/doc/mios/guides/deploy.md
- SELF-BUILD.md             -> usr/share/doc/mios/guides/self-build.md
- SECURITY.md               -> usr/share/doc/mios/guides/security.md
- INSTALL.md                -> usr/share/doc/mios/guides/install.md
- API.md                    -> usr/share/doc/mios/reference/api.md
- SOURCES.md                -> usr/share/doc/mios/reference/sources.md
- CREDITS.md                -> usr/share/doc/mios/reference/credits.md
- LICENSES.md               -> usr/share/doc/mios/reference/licenses.md
- TREE.md                   -> usr/share/doc/mios/reference/tree.md
- MiOS-Engineering-Reference.md -> usr/share/doc/mios/reference/engineering-reference.md
- MiOS-Build-Scripts.md     -> usr/share/doc/mios/reference/build-scripts.md
- AUDIT-FINDINGS-20260505.md -> usr/share/doc/mios/audits/AUDIT-FINDINGS-20260505.md

Removed: 10 obsolete numbered summaries under usr/share/doc/mios/
(00-overview.md through 90-deploy.md) -- they were derivations of the
root-level docs that are now the canonical FHS-located source.

Kept at root (GitHub conventions / tool discovery):
- README.md, LICENSE, CONTRIBUTING.md, SECURITY.md (now a 5-line
  pointer to the canonical guide), AGREEMENTS.md, VERSION
- AGENTS.md, CLAUDE.md, GEMINI.md, system-prompt.md (thin
  redirectors per the OpenAI-API-vendor-neutral discovery convention)
- llms.txt, llms-full.txt, manifest.json, MiOS-SBOM.csv
- .gitignore, .gitattributes, .editorconfig, .cursorrules, .clinerules
- All build orchestration scripts (Containerfile, Justfile, *.ps1, *.sh)

Cross-references updated across 51 files (README, llms.txt, llms-full,
CONTRIBUTING, AGREEMENTS, agent system prompts, Quadlet headers,
automation banners, push-to-github, tools manifests, docs that cite
each other) via a python regex pass that only rewrites bare-filename
citations -- already-correct paths under usr/share/doc/ or
usr/share/mios/ai/ are not touched.

.gitignore whitelist trimmed to only the 16 files that remain at root;
new files under usr/share/doc/mios/ and usr/share/mios/ai/ are
automatically tracked via the existing cascade rules in sections 2b/9.

Author: Kabuki94

.github/ai-instructions.md

@@ -1,6 +1,6 @@
 # 'MiOS' -- GitHub Copilot entry point.
 # Canonical prompt: usr/share/mios/ai/system.md (deployed from mios-bootstrap).
-# Architectural laws and contribution rules: INDEX.md.
+# Architectural laws and contribution rules: usr/share/mios/ai/INDEX.md.
 
 ## Quick actions
 

.gitignore

@@ -32,43 +32,30 @@
 # GHCR-side CI.
 !/.forgejo/
 !/.forgejo/**
+# Repo-root files. After the 2026-05-05 FHS-consolidation pass:
+#   - operator-facing docs (architecture, engineering, deploy, security,
+#     api, sources, credits, licenses, tree, audits, ...) moved to
+#     usr/share/doc/mios/{concepts,guides,reference,audits}/
+#   - the agent-facing INDEX.md and CLAUDE.AUDIT.md moved to
+#     usr/share/mios/ai/{INDEX.md,audit-prompt.md}
+#   - GitHub-convention files (README, LICENSE, CONTRIBUTING, SECURITY,
+#     AGREEMENTS) and agent-tool discovery redirectors stay at root.
 !/AGENTS.md
 !/AGREEMENTS.md
-!/AI.md
-!/API.md
 !/CLAUDE.md
-!/CREDITS.md
-!/GEMINI.md
-!/system-prompt.md
-!/ARCHITECTURE.md
 !/CONTRIBUTING.md
 !/Containerfile
-!/DEPLOY.md
-!/ENGINEERING.md
-!/INDEX.md
+!/GEMINI.md
 !/Justfile
 !/LICENSE
-!/LICENSES.md
+!/MiOS-SBOM.csv
 !/README.md
-!/INSTALL.md
-!/SOURCES.md
-!/manifest.json
 !/SECURITY.md
-!/SELF-BUILD.md
-!/TREE.md
 !/VERSION
 !/llms-full.txt
 !/llms.txt
-!/MiOS-Engineering-Reference.md
-!/MiOS-SBOM.csv
-!/MiOS-Build-Scripts.md
-!/CLAUDE.AUDIT.md
-# Audit findings reports. Recurring class -- one file per audit pass,
-# named AUDIT-FINDINGS-YYYYMMDD.md per the format defined in
-# CLAUDE.AUDIT.md. Always tracked so a fresh clone restores full
-# audit history alongside the rest of the repo (per project
-# invariant: pulling the latest must reconstitute context).
-!/AUDIT-FINDINGS-*.md
+!/manifest.json
+!/system-prompt.md
 !/image-versions.yml
 !/install.sh
 !/install-mios-agents.sh

AGREEMENTS.md

@@ -50,8 +50,8 @@ that is the expected mode of contribution.
 
 Every upstream project, specification, vendor, and community whose
 work 'MiOS' depends on or refers to is listed -- with a link to its
-canonical home -- in [`CREDITS.md`](./CREDITS.md). License terms for
-each component are inventoried in [`LICENSES.md`](./LICENSES.md). The
+canonical home -- in [`usr/share/doc/mios/reference/credits.md`](usr/share/doc/mios/reference/credits.md). License terms for
+each component are inventoried in [`usr/share/doc/mios/reference/licenses.md`](usr/share/doc/mios/reference/licenses.md). The
 'MiOS'-owned source of this repository is licensed under
 [`LICENSE`](./LICENSE) (Apache-2.0).
 
@@ -69,8 +69,8 @@ by, or partnered with OpenAI.
 Invoking any of the following entry points is treated as
 acknowledgment of this document, the Apache-2.0 license at
 [`LICENSE`](./LICENSE), the bundled-component licenses inventoried in
-[`LICENSES.md`](./LICENSES.md), and the attribution registry in
-[`CREDITS.md`](./CREDITS.md). Each entry point displays a banner
+[`usr/share/doc/mios/reference/licenses.md`](usr/share/doc/mios/reference/licenses.md), and the attribution registry in
+[`usr/share/doc/mios/reference/credits.md`](usr/share/doc/mios/reference/credits.md). Each entry point displays a banner
 referencing this file when it starts.
 
 | Entry point | Repo | Purpose |
@@ -88,17 +88,17 @@ referencing this file when it starts.
 | `bootc upgrade`, `bootc switch ghcr.io/mios-dev/mios` | deployed image | OS lifecycle commands operating on a 'MiOS' image |
 
 If you do not agree with the terms inventoried in `LICENSE`,
-`LICENSES.md`, or `CREDITS.md`, do not invoke these entry points.
+`usr/share/doc/mios/reference/licenses.md`, or `usr/share/doc/mios/reference/credits.md`, do not invoke these entry points.
 
 ## 5. Runtime agreements that apply implicitly
 
 By using a deployed 'MiOS' image you also accept any third-party
 agreements that govern bundled vendor components. The notable ones
-are listed verbatim in `LICENSES.md`; non-exhaustive highlights:
+are listed verbatim in `usr/share/doc/mios/reference/licenses.md`; non-exhaustive highlights:
 
 - **NVIDIA** -- proprietary GPU drivers and CUDA libraries are
   governed by the NVIDIA Software License.
-  [`LICENSES.md`](./LICENSES.md) carries the link.
+  [`usr/share/doc/mios/reference/licenses.md`](usr/share/doc/mios/reference/licenses.md) carries the link.
 - **Steam** -- if installed, the Steam Subscriber Agreement applies
   on first launch.
 - **Microsoft Windows VM guests** -- bring-your-own valid licenses
@@ -144,8 +144,8 @@ canonical form is:
 
 ```
 [mios] By invoking this entry point you acknowledge AGREEMENTS.md
-       (Apache-2.0 main + bundled-component licenses in LICENSES.md +
-        attribution in CREDITS.md). MiOS is a research project.
+       (Apache-2.0 main + bundled-component licenses in usr/share/doc/mios/reference/licenses.md +
+        attribution in usr/share/doc/mios/reference/credits.md). MiOS is a research project.
 ```
 
 The banner is informational; there is no interactive y/n prompt by
@@ -190,8 +190,8 @@ re-source `tools/lib/userenv.sh` in your shell).
 ## 9. Pointers
 
 - [`LICENSE`](./LICENSE) -- Apache-2.0 main license
-- [`LICENSES.md`](./LICENSES.md) -- bundled-component license inventory
-- [`CREDITS.md`](./CREDITS.md) -- attribution registry (every
+- [`usr/share/doc/mios/reference/licenses.md`](usr/share/doc/mios/reference/licenses.md) -- bundled-component license inventory
+- [`usr/share/doc/mios/reference/credits.md`](usr/share/doc/mios/reference/credits.md) -- attribution registry (every
   upstream project, dependency, application, repo, file, and pattern)
 - [`SECURITY.md`](./SECURITY.md) -- security posture and hardening
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md) -- contributor conventions

CONTRIBUTING.md

@@ -2,11 +2,11 @@
 
 ## Project rules
 
-- **Single source of truth: `INDEX.md` + `usr/share/mios/PACKAGES.md`.**
+- **Single source of truth: `usr/share/mios/ai/INDEX.md` + `usr/share/mios/PACKAGES.md`.**
   Every package belongs in `PACKAGES.md`, every architectural rule in
-  `INDEX.md`. Other docs cite, never duplicate.
+  `usr/share/mios/ai/INDEX.md`. Other docs cite, never duplicate.
 - **USR-OVER-ETC, NO-MKDIR-IN-VAR, BOUND-IMAGES, BOOTC-CONTAINER-LINT,
-  UNIFIED-AI-REDIRECTS, UNPRIVILEGED-QUADLETS** -- see `INDEX.md` §3.
+  UNIFIED-AI-REDIRECTS, UNPRIVILEGED-QUADLETS** -- see `usr/share/mios/ai/INDEX.md` §3.
   Violating any of the six is a build/audit fail.
 - **Pure build-up.** Only the ~25 GNOME packages required for the desktop
   ship. No `dnf remove` bloat blocks. User-facing apps are Flatpaks; RPMs

README.md

@@ -14,8 +14,8 @@
 > (`just <target>`, `install.sh`, `install.ps1`, `bootstrap.{sh,ps1}`,
 > the deployed `mios` CLIs, `bootc upgrade` against a 'MiOS' image, ...),
 > you acknowledge [`AGREEMENTS.md`](./AGREEMENTS.md) -- Apache-2.0 main
-> license, bundled-component licenses ([`LICENSES.md`](./LICENSES.md)),
-> and attribution ([`CREDITS.md`](./CREDITS.md)). All upstream projects
+> license, bundled-component licenses ([`usr/share/doc/mios/reference/licenses.md`](usr/share/doc/mios/reference/licenses.md)),
+> and attribution ([`usr/share/doc/mios/reference/credits.md`](usr/share/doc/mios/reference/credits.md)). All upstream projects
 > and standards referenced here are the property of their respective
 > owners; 'MiOS' integrates with them but claims no affiliation with
 > them.
@@ -200,31 +200,47 @@ build-time lint and by `automation/99-postcheck.sh`:
    `Delegate=yes`. Documented exceptions: `mios-ceph` and `mios-k3s`
    (rationale in their headers).
 
-If you want the deeper dive: [`INDEX.md`](INDEX.md) is the architectural
-contract, [`ARCHITECTURE.md`](ARCHITECTURE.md) is the layout, and
-[`ENGINEERING.md`](ENGINEERING.md) is the build-pipeline rules.
+If you want the deeper dive: [`usr/share/mios/ai/INDEX.md`](usr/share/mios/ai/INDEX.md)
+is the architectural contract (agent-facing),
+[`usr/share/doc/mios/concepts/architecture.md`](usr/share/doc/mios/concepts/architecture.md)
+is the layout, and
+[`usr/share/doc/mios/guides/engineering.md`](usr/share/doc/mios/guides/engineering.md)
+is the build-pipeline rules.
 
 ---
 
 ## Where things live
 
+Documentation follows the FHS doc layout (`/usr/share/doc/<pkg>/`) with an
+OpenAI-style topical split: `concepts/`, `guides/`, `reference/`, `audits/`.
+The agent-facing contract lives under `/usr/share/mios/ai/`.
+
 | Document | What's in it |
 |---|---|
-| [`INDEX.md`](INDEX.md) | Architectural laws + API surface (the contract). |
-| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Filesystem and hardware layout. |
-| [`ENGINEERING.md`](ENGINEERING.md) | Build pipeline + shell conventions. |
-| [`SECURITY.md`](SECURITY.md) | Hardening kargs and posture. |
-| [`SELF-BUILD.md`](SELF-BUILD.md) | Build modes (CI, Linux, Windows, self-build). |
-| [`DEPLOY.md`](DEPLOY.md) | bootc + Day-2 lifecycle. |
-| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution conventions. |
-| [`API.md`](API.md) | OpenAI-compatible AI surface. |
-| [`SOURCES.md`](SOURCES.md) | Every external reference, every upstream link. |
+| [`usr/share/mios/ai/INDEX.md`](usr/share/mios/ai/INDEX.md) | Architectural laws + OpenAI-compatible API surface (agent contract). |
+| [`usr/share/mios/ai/system.md`](usr/share/mios/ai/system.md) | Canonical agent system prompt. |
+| [`usr/share/mios/ai/audit-prompt.md`](usr/share/mios/ai/audit-prompt.md) | Read-only audit-mode prompt for any OpenAI-API-compatible agent. |
+| [`usr/share/mios/ai/v1/`](usr/share/mios/ai/v1/) | `models.json`, `mcp.json`, etc. -- per-OpenAI-v1-surface manifests. |
+| [`usr/share/doc/mios/concepts/architecture.md`](usr/share/doc/mios/concepts/architecture.md) | Filesystem and hardware layout. |
+| [`usr/share/doc/mios/guides/engineering.md`](usr/share/doc/mios/guides/engineering.md) | Build pipeline + shell conventions. |
+| [`usr/share/doc/mios/guides/security.md`](usr/share/doc/mios/guides/security.md) | Hardening kargs and posture. |
+| [`usr/share/doc/mios/guides/self-build.md`](usr/share/doc/mios/guides/self-build.md) | Build modes (CI, Linux, Windows, self-build). |
+| [`usr/share/doc/mios/guides/deploy.md`](usr/share/doc/mios/guides/deploy.md) | bootc + Day-2 lifecycle. |
+| [`usr/share/doc/mios/guides/install.md`](usr/share/doc/mios/guides/install.md) | KB ingest recipes (OpenAI-shaped). |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution conventions (root by GitHub convention). |
+| [`usr/share/doc/mios/reference/api.md`](usr/share/doc/mios/reference/api.md) | OpenAI-compatible AI surface (full spec). |
+| [`usr/share/doc/mios/reference/sources.md`](usr/share/doc/mios/reference/sources.md) | Every external reference, every upstream link. |
+| [`usr/share/doc/mios/reference/credits.md`](usr/share/doc/mios/reference/credits.md) | Attribution registry. |
+| [`usr/share/doc/mios/reference/licenses.md`](usr/share/doc/mios/reference/licenses.md) | Component licenses. |
+| [`usr/share/doc/mios/reference/tree.md`](usr/share/doc/mios/reference/tree.md) | Annotated FHS tree. |
+| [`usr/share/doc/mios/audits/`](usr/share/doc/mios/audits/) | Audit reports. |
 
 For LLMs and AI agents arriving at the repo:
 [`llms.txt`](llms.txt) and [`llms-full.txt`](llms-full.txt) are the
 machine-readable index. [`AGENTS.md`](AGENTS.md), [`CLAUDE.md`](CLAUDE.md),
-and [`GEMINI.md`](GEMINI.md) are the per-tool entry points. They all
-ultimately defer to `/usr/share/mios/ai/system.md` once the OS is running.
+and [`GEMINI.md`](GEMINI.md) are the per-tool entry-point redirectors at
+repo root for tool discovery -- they all defer to
+`/usr/share/mios/ai/system.md` (canonical) once the OS is running.
 
 ---
 
@@ -244,7 +260,7 @@ Open issues + roadmap live on the GitHub side. PRs welcome -- read
 ## License
 
 Apache-2.0. Component licenses for every shipped piece are catalogued in
-[`LICENSES.md`](LICENSES.md).
+[`usr/share/doc/mios/reference/licenses.md`](usr/share/doc/mios/reference/licenses.md).
 
 The `'MiOS'` name (capitalized) is a project mark; lowercase `mios` (used in
 file paths, package names, env-var prefixes, etc.) is the technical