docs(api+laws): align verbs with OpenAI public API + fix env-layer ordering

INDEX.md sec 2 (API surface):
- /v1/mcp Method was 'filesystem' (not an HTTP verb). Corrected to GET
  and re-marked as a MiOS extension (the public OpenAI surface invokes
  MCP via POST /v1/responses with tools=[{type:'mcp', server_url:...}];
  /v1/mcp is a MiOS-internal manifest endpoint that populates that
  tools array).
- Enumerate the canonical OpenAI endpoints LocalAI serves
  (chat/completions, responses, embeddings, models, audio/*) with
  per-row spec links to platform.openai.com/docs/api-reference. The
  prior table omitted everything except chat/completions + models.
- 'x-mios:' prefix marks rows that are MiOS extensions, so strict
  OpenAI clients can ignore them by name.

INDEX.md sec 3 Law 5:
- Replace 'MIOS_AI_KEY, MIOS_AI_MODEL, MIOS_AI_ENDPOINT -> URL' (which
  implied all three vars equal the URL) with role-explicit wording:
  ENDPOINT is the OpenAI-SDK base_url slot, MODEL is the default model
  id, KEY is the api_key (empty for the local proxy).
- Add /etc/profile.d/mios-env.sh and /usr/bin/mios-env to the
  enforcement column -- they are the canonical resolver + CLI now.

INDEX.md sec 4 + etc/profile.d/mios-env.sh + /usr/bin/mios-env:
- Reorder the environment-layer overlay so legacy ~/.env.mios sits
  between vendor defaults and admin/host layers (was at the bottom in
  INDEX.md, just-below-current in the resolver -- both wrong).
  Correct precedence (lowest -> highest):
    1. /usr/share/mios/env.defaults
    2. ~/.env.mios (legacy)
    3. /etc/mios/env.d/*.env
    4. /etc/mios/install.env
    5. ~/.config/mios/env
  This guarantees a stale legacy file cannot override a fresher
  install.env or env.d entry, while still honoring legacy values when
  no fresher source supplies them.
- Reorder the LAYERS array in /usr/bin/mios-env to match.
- Fix INDEX.md prose: list now reads lowest -> highest with that
  direction stated explicitly, since the previous '1 = highest' framing
  was the source of the inconsistency.

Author: Kabuki94

INDEX.md

@@ -13,15 +13,27 @@ OCI image. Source: `README.md`, `Containerfile`. Image:
 ## 2. API surface (OpenAI-compatible)
 
 All system agents target the local proxy at `http://localhost:8080/v1`,
-served by the LocalAI Quadlet at `etc/containers/systemd/mios-ai.container`.
-
-| Path | Method | Manifest |
-|---|---|---|
-| `/v1/chat/completions` | POST | LocalAI runtime |
-| `/v1/models` | GET | `usr/share/mios/ai/v1/models.json` |
-| `/v1/mcp` | filesystem | `usr/share/mios/ai/v1/mcp.json` |
-
-Spec: <https://platform.openai.com/docs/api-reference>.
+served by the `mios-ai.container` Quadlet (LocalAI runtime). The
+endpoints below follow the OpenAI public API spec
+(<https://platform.openai.com/docs/api-reference>) verb-for-verb;
+`x-mios.*` rows are MiOS extensions, clearly namespaced so strict
+OpenAI clients can ignore them.
+
+| Path | Method | Served by | Spec |
+|---|---|---|---|
+| `/v1/chat/completions` | POST | LocalAI runtime | <https://platform.openai.com/docs/api-reference/chat> |
+| `/v1/responses` | POST | LocalAI runtime | <https://platform.openai.com/docs/api-reference/responses> |
+| `/v1/embeddings` | POST | LocalAI runtime | <https://platform.openai.com/docs/api-reference/embeddings> |
+| `/v1/models` | GET | `usr/share/mios/ai/v1/models.json` | <https://platform.openai.com/docs/api-reference/models/list> |
+| `/v1/audio/{transcriptions,speech}` | POST | LocalAI runtime (when configured) | <https://platform.openai.com/docs/api-reference/audio> |
+| `x-mios:/v1/mcp` | GET | `usr/share/mios/ai/v1/mcp.json` | <https://modelcontextprotocol.io/specification> |
+
+`/v1/mcp` is a MiOS extension (not part of the OpenAI public API). The
+canonical OpenAI route to invoke an MCP server is
+`POST /v1/responses` with `tools=[{"type": "mcp", "server_url": ...}]`;
+the manifest at `/v1/mcp` is what MiOS agents read to populate that
+`tools` array. The `x-mios:` prefix is a documentation marker only --
+the served URL is `/v1/mcp`.
 
 ## 3. Architectural laws (enforced; non-negotiable)
 
@@ -31,7 +43,7 @@ Spec: <https://platform.openai.com/docs/api-reference>.
 | 2 | **NO-MKDIR-IN-VAR** -- every `/var/` path declared via `usr/lib/tmpfiles.d/*.conf`. | `usr/lib/tmpfiles.d/mios*.conf` |
 | 3 | **BOUND-IMAGES** -- every Quadlet image symlinked into `/usr/lib/bootc/bound-images.d/`. Binder loop: `automation/08-system-files-overlay.sh:74-86`. | `usr/lib/bootc/bound-images.d/` |
 | 4 | **BOOTC-CONTAINER-LINT** -- final RUN of `Containerfile`. | `Containerfile` (last `RUN`) |
-| 5 | **UNIFIED-AI-REDIRECTS** -- `MIOS_AI_KEY`, `MIOS_AI_MODEL`, `MIOS_AI_ENDPOINT` → `http://localhost:8080/v1`. No vendor URLs. | `usr/bin/mios`, `etc/mios/ai/` |
+| 5 | **UNIFIED-AI-REDIRECTS** -- every OpenAI-API-shaped client resolves through one canonical surface: `MIOS_AI_ENDPOINT` (default `http://localhost:8080/v1`, the OpenAI-SDK `base_url` slot), `MIOS_AI_MODEL` (default model id), `MIOS_AI_KEY` (api key, empty for the local proxy). No vendor-hardcoded URLs. | `/etc/profile.d/mios-env.sh`, `usr/bin/mios`, `usr/bin/mios-env`, `etc/mios/ai/` |
 | 6 | **UNPRIVILEGED-QUADLETS** -- every Quadlet declares `User=`, `Group=`, `Delegate=yes`. Documented exceptions: `mios-ceph` and `mios-k3s` declare `User=root`/`Group=root` because Ceph/K3s require uid 0 (see file headers). | `etc/containers/systemd/`, `usr/share/containers/systemd/` |
 
 ## 4. Profile + environment resolution
@@ -48,13 +60,19 @@ and at runtime by `mios` CLI clients):
 3. `/usr/share/mios/profile.toml` -- vendor defaults (shipped by `mios.git`,
    immutable, USR-OVER-ETC)
 
-**Environment layers** (resolved by `/etc/profile.d/mios-env.sh` at login):
+**Environment layers** (resolved by `/etc/profile.d/mios-env.sh` at
+login; later sources override earlier values, so this list runs from
+**lowest** precedence to **highest**):
+
+1. `/usr/share/mios/env.defaults` -- vendor defaults (lowest)
+2. `~/.env.mios` -- legacy per-user (deprecated; honored only when no
+   admin/host/current source supplies the same key)
+3. `/etc/mios/env.d/*.env` -- admin/distro drop-ins (alphabetical)
+4. `/etc/mios/install.env` -- host identity, written by bootstrap
+5. `~/.config/mios/env` -- canonical per-user override (highest)
 
-1. `~/.config/mios/env`
-2. `/etc/mios/install.env` (written by bootstrap install.sh)
-3. `/etc/mios/env.d/*.env` (admin/distro drop-ins)
-4. `/usr/share/mios/env.defaults` (vendor defaults)
-5. `~/.env.mios` (legacy, deprecated; kept for backwards compatibility)
+The CLI `/usr/bin/mios-env` prints the resolved surface (`--explain`
+shows which layer supplied each key).
 
 **Build-time variables** read by `Justfile`:
 

etc/profile.d/mios-env.sh

@@ -5,12 +5,17 @@
 # MIOS_* variables so every agent and CLI sees the same values regardless
 # of which shell or terminal launched them.
 #
-# Resolution order (later layers override earlier values):
+# Resolution order (later layers override earlier values, so this list
+# runs from LOWEST precedence to HIGHEST):
 #   1. /usr/share/mios/env.defaults    vendor defaults (lowest)
-#   2. /etc/mios/env.d/*.env           admin/distro drop-ins (alphabetical)
-#   3. /etc/mios/install.env           host bootstrap-written identity
-#   4. ~/.env.mios                     legacy per-user (deprecated)
-#   5. ~/.config/mios/env              per-user override (highest)
+#   2. ~/.env.mios                     legacy per-user (deprecated;
+#                                      sourced before admin/host so a
+#                                      stale legacy value cannot
+#                                      override a fresher install.env
+#                                      or env.d/*.env entry)
+#   3. /etc/mios/env.d/*.env           admin/distro drop-ins (alphabetical)
+#   4. /etc/mios/install.env           host bootstrap-written identity
+#   5. ~/.config/mios/env              canonical per-user override (highest)
 #
 # Architectural Law 5 (UNIFIED-AI-REDIRECTS): MIOS_AI_ENDPOINT,
 # MIOS_AI_MODEL, and MIOS_AI_KEY are exported here so every OpenAI-API
@@ -41,24 +46,25 @@ _mios_source_if_readable() {
     . "$1"
 }
 
-# Layer 1: vendor defaults (always present on a 'MiOS' system).
+# Layer 1 (lowest): vendor defaults (always present on a 'MiOS' system).
 _mios_source_if_readable /usr/share/mios/env.defaults
 
-# Layer 2: admin / distro drop-ins (alphabetical, env-style).
+# Layer 2: legacy per-user env file (deprecated; sourced before
+# admin/host so a stale ~/.env.mios cannot override fresher data).
+_mios_source_if_readable "${HOME}/.env.mios"
+
+# Layer 3: admin / distro drop-ins (alphabetical, env-style).
 if [ -d /etc/mios/env.d ]; then
     for _f in /etc/mios/env.d/*.env; do
         _mios_source_if_readable "$_f"
     done
     unset _f
 fi
 
-# Layer 3: host install.env -- bootstrap writes identity here.
+# Layer 4: host install.env -- bootstrap writes identity here.
 _mios_source_if_readable /etc/mios/install.env
 
-# Layer 4: legacy per-user env file (deprecated; kept for migration).
-_mios_source_if_readable "${HOME}/.env.mios"
-
-# Layer 5: canonical per-user env override.
+# Layer 5 (highest): canonical per-user env override.
 _mios_source_if_readable "${HOME}/.config/mios/env"
 
 # Export the OpenAI-API surface required by every Law-5-compliant agent.

usr/bin/mios-env

@@ -24,6 +24,7 @@ set -euo pipefail
 # Canonical layer paths (mirrors mios-env.sh).
 LAYERS=(
     "/usr/share/mios/env.defaults"
+    "${HOME}/.env.mios"
 )
 # /etc/mios/env.d/*.env (alphabetical)
 if [[ -d /etc/mios/env.d ]]; then
@@ -33,7 +34,6 @@ if [[ -d /etc/mios/env.d ]]; then
 fi
 LAYERS+=(
     "/etc/mios/install.env"
-    "${HOME}/.env.mios"
     "${HOME}/.config/mios/env"
 )