docs: enroll Agent Zero + Archon in living-docs tracking, mark superseded docs

.claude/CLAUDE.md

@@ -38,7 +38,7 @@ Per PR #1378 MOF Architecture: PMOVES is a Metal-Organic Framework for distribut
 - `PMOVES-agents.md/` — AGENTS.md format reference + agent taxonomy/persona docs (Tier-2 *always-relevant*: load when discussing agent class, taxonomy, or AGENTS.md format)
 - `PMOVES-Archon/.claude/CLAUDE.md` — agent service architecture
 - `PMOVES-BoTZ/.claude/CLAUDE.md` — skills marketplace framework (legacy/archived per 2026-04-19)
-- `PMOVES-Agent-Zero/.claude/CLAUDE.md` — orchestration patterns
+- Agent Zero — the submodule has **no** `.claude/CLAUDE.md` (verified 2026-08-06). Use `pmoves/services/agent-zero/README.md` for the service, and `pmoves/docs/operations/AGENT_ZERO_API.md` for the live API surface.
 - `skills/` — skills constellation (5 forks registered in `.gitmodules`: Pmoves-skills, agent-sandbox, fork-repository, awesome-agent-skills, claude-d3js — run `git submodule update --init skills/` to populate); load `skills/README.md` first
 - Load only when working directly on that subsystem.
 
@@ -64,7 +64,7 @@ Detail files live in `.claude/context/`:
 - `testing-strategy.md` — testing workflow + PR requirements
 - `security-patterns.md` — cross-cutting security patterns (auth, secrets, hardening)
 - `observability-patterns.md` — Prometheus, Grafana, Loki, TensorZero metrics
-- `agent-zero-orchestration.md` — MCP API reference, task flow, subordinate model
+- ~~`agent-zero-orchestration.md`~~ — **SUPERSEDED, do not use as an API reference.** It documents `/mcp/health`, `/mcp/agents`, `/mcp/subordinate/create` and an `agent.zero.*` NATS family that were never implemented. Canonical: `pmoves/docs/operations/AGENT_ZERO_API.md` (probed from `/openapi.json`).
 - `tier-architecture.md` — 7-tier env security model, network segmentation
 - `chrome-extension.md` — Chrome Extension integration (8 services, message protocol, auth)
 - `tensorzero.md` — TensorZero detailed documentation
@@ -116,7 +116,7 @@ When conflicts occur: main PMOVES.AI patterns take precedence; document exceptio
 **Solution:**
 - Each agent loads only its direct tier
 - Use MCP APIs for cross-agent communication, not shared context
-- Reference integration docs (e.g., `pmoves/docs/ARCHON_INTEGRATION.md`) instead of duplicating
+- Reference integration docs instead of duplicating (note: `pmoves/docs/integrations/ARCHON_INTEGRATION.md` is **superseded** — it describes the pre-0.6.0 Python/Supabase Archon; current state is `.claude/CATALOG.md` + `pmoves/docs/handoffs/ARCHON_MINT_CONTRACT_REVIEW.md`)
 
 Full audit: `pmoves/docs/CLAUDE_CONTEXT_AUDIT.md`.
 

.claude/context/agent-zero-orchestration.md

@@ -1,3 +1,21 @@
+> [!CAUTION]
+> **SUPERSEDED — DO NOT USE AS AN API REFERENCE (marked 2026-08-06).**
+>
+> This document describes an Agent Zero MCP API that **was never implemented**. Verified
+> against `pmoves/services/agent-zero/main.py`:
+>
+> | Documented here | Reality |
+> |---|---|
+> | `GET /mcp/health` | does not exist — real: `GET /healthz` |
+> | `GET /mcp/agents` | does not exist |
+> | `POST /mcp/subordinate/create` | does not exist |
+> | `POST /mcp/execute` `{task, context, priority}` | real shape is `{cmd, arguments}` |
+> | `agent.zero.*` / `agent.task.*` NATS subjects | real: `agentzero.task.v1`, `agentzero.memory.update` |
+>
+> The `curl` and `nats sub` examples below **cannot work**. Retained for historical intent only.
+>
+> **Canonical:** `pmoves/docs/operations/AGENT_ZERO_API.md` (probed from live `/openapi.json`).
+
 # Agent Zero Orchestration Patterns
 
 Detailed reference for Agent Zero's MCP API, task coordination, and subordinate agent model.

pmoves/configs/living_docs_registry.yaml

@@ -105,6 +105,45 @@ tracked:
     severity: P2
     description: "A2UI Renderer (port 8107) — Remotion animation engine for creator pipeline"
 
+  # ── Agent Zero integration ─────────────────────────────────────────────
+  # Enrolled 2026-08-06. Previously untracked — which is why this integration's
+  # docs drifted from its code unnoticed. Two other docs
+  # (.claude/context/agent-zero-orchestration.md, pmoves/docs/TAC/TAC_AGENT_ZERO.md)
+  # documented an /mcp/* API and an agent.zero.* / agent.task.* NATS family that
+  # were never implemented, including copy-pasteable curl and `nats sub` commands
+  # that cannot work. Those are retired in the companion commit.
+  #
+  # Severity P2 (warn, do not gate) is deliberate: freshness is measured from
+  # last-commit date, and AGENT_ZERO_API.md is already outside budget. Enrolling
+  # at P1 would fail CI the moment this merges. Promote to P1 after a refresh
+  # pass brings them inside budget.
+  - path: pmoves/docs/operations/AGENT_ZERO_API.md
+    freshness_days: 30
+    severity: P2
+    description: "Agent Zero live-state API — probed from /openapi.json; canonical endpoint reference for the outer supervisor (:8080)"
+  - path: pmoves/services/agent-zero/README.md
+    freshness_days: 60
+    severity: P2
+    description: "Agent Zero service README — env vars, build (upstream agent0ai base + PMOVES overlay), make targets"
+
+  # ── Archon integration ─────────────────────────────────────────────────
+  # Enrolled 2026-08-06, same root cause. Archon 0.6.0 (#2217) replaced the
+  # Python service with a TypeScript/Bun app on a single port (3090, /api/health),
+  # but four untracked docs still described the pre-0.6.0 Python/Supabase
+  # split-port architecture and nothing reconciled them against the code.
+  - path: pmoves/docs/handoffs/ARCHON_MINT_CONTRACT_REVIEW.md
+    freshness_days: 60
+    severity: P2
+    description: "Archon mint-contract current state — archon.mint.* implementation + registration gaps; authoritative over the mint-agent command doc"
+
+  # ── Cross-service health-endpoint truth ────────────────────────────────
+  # The doc that would have caught the Archon blackbox probe pointing at a dead
+  # port and path (#2448). Untracked until now.
+  - path: pmoves/docs/operations/SERVICE_HEALTH_ENDPOINTS.md
+    freshness_days: 90
+    severity: P2
+    description: "Per-service health endpoint truth — reference for compose healthchecks and Prometheus blackbox probes"
+
 
 # ============================================================================
 # Renderable entries (Lane 2228, 2026-08-02)

pmoves/docs/TAC/TAC_AGENT_ZERO.md

@@ -1,3 +1,18 @@
+> [!CAUTION]
+> **SUPERSEDED for API/subject detail (marked 2026-08-06).**
+>
+> The endpoint and NATS-subject tables in this TAC repeat the invented API from
+> `.claude/context/agent-zero-orchestration.md` — `/mcp/health`, `/mcp/agents`,
+> `/mcp/subordinate/create`, and the `agent.zero.*` subject family. None exist in
+> `pmoves/services/agent-zero/main.py`.
+>
+> Real endpoints: `/healthz`, `/config/environment`, `/metrics`, `/mcp/commands`,
+> `POST /mcp/execute` `{cmd, arguments}`, `/tasks`, `/jobs/{context_id}`, `/sessions`,
+> `/memory` CRUD, `/events/publish`.
+> Real subjects: `agentzero.task.v1`, `agentzero.memory.update`.
+>
+> **Canonical:** `pmoves/docs/operations/AGENT_ZERO_API.md`. TAC roadmap items below remain valid.
+
 # TAC Tree: Agent Zero
 
 > Technology-Architecture-Context tree for the Agent Zero control-plane orchestrator — the primary L1 coordinator with embedded agent runtime and MCP API.

pmoves/docs/integrations/ARCHON_INTEGRATION.md

@@ -1,3 +1,14 @@
+> [!CAUTION]
+> **SUPERSEDED — describes the pre-0.6.0 Archon (marked 2026-08-06).**
+>
+> Archon 0.6.0 (#2217) replaced the Python service with a **TypeScript/Bun** app serving
+> HTTP + UI on a **single port 3090**, health at **`/api/health`**, backed by a dedicated
+> Postgres. This document's split-port / Supabase-backed / nested-`external/`-submodule
+> model no longer matches anything that runs.
+>
+> **Canonical:** `.claude/CATALOG.md` (ports/health) and
+> `pmoves/docs/handoffs/ARCHON_MINT_CONTRACT_REVIEW.md` (mint pipeline current state).
+
 # Archon External Integration Architecture
 
 > **Part of the [PMOVES.AI Integration Layer](INTEGRATIONS_OVERVIEW.md)** | Category: Integration Architecture

pmoves/docs/services/archon/HEADLESS_RUNBOOK.md

@@ -1,3 +1,15 @@
+> [!CAUTION]
+> **SUPERSEDED — targets endpoints that no longer exist (marked 2026-08-06).**
+>
+> References `/healthz`, `/ready`, `/mcp/describe`, an MCP bridge on `:8051`, and a
+> clone-at-build `ARCHON_VENDOR_ROOT` / `ARCHON_GIT_REF` pattern. None of these exist in
+> Archon 0.6.0, whose Dockerfile builds directly from the submodule source with no such ARG.
+>
+> Current surface: `/api/health`, `/api/workflows*`, `/api/codebases*`, `/api/conversations*`,
+> `/api/providers*`, `/api/auth/*`, `/api/runs/:id/artifacts`, `/webhooks/github`.
+>
+> **Canonical:** `.claude/CATALOG.md`.
+
 Archon Headless Bring‑Up — MCP/API Self‑Connectivity
 
 Targets

pmoves/docs/services/archon/README.md

@@ -1,3 +1,16 @@
+> [!CAUTION]
+> **SUPERSEDED — pre-0.6.0 architecture (marked 2026-08-06).**
+>
+> Claims here that are no longer true: Supabase-backed storage (`SUPABASE_URL` /
+> `SUPABASE_SERVICE_KEY`), `/healthz` on `:8091`, a separate MCP server on `:8051`, a
+> PydanticAI agents service on `:8052`, and a distinct UI service on `:3737`.
+>
+> Archon 0.6.0 is a single unified TypeScript/Bun server on **3090** with **`/api/health`**,
+> Postgres via `DATABASE_URL`, no MCP subserver. Host ports 3737 and 8091 are compat
+> aliases onto container 3090 — they are not separate services.
+>
+> **Canonical:** `.claude/CATALOG.md`.
+
 # Archon Service – Supabase Wiring, Bring-Up, and Smokes
 
 This guide documents how Archon is wired to Supabase in the PMOVES.AI stack, and how to bring it up and validate it alongside the rest of the agents.

pmoves/docs/services/archon/UPDATE_NOTES.md

@@ -1,3 +1,14 @@
+> [!CAUTION]
+> **SUPERSEDED — last synced against the pre-0.6.0 Python Archon (marked 2026-08-06).**
+>
+> The commits listed below belong to the old Python service that Archon 0.6.0 (#2217)
+> replaced. Retained as history; do not read as current state.
+>
+> **Canonical:** `.claude/CATALOG.md` and `pmoves/docs/handoffs/ARCHON_MINT_CONTRACT_REVIEW.md`.
+>
+> Note: `pmoves/scripts/update_service_logs.py` references this file — retained rather than
+> deleted so that tooling does not break.
+
 # archon — Update Notes
 
 _Last synced: 2025-11-07T15:48:32Z_

pmoves/scripts/update_service_logs.py

@@ -220,6 +220,24 @@ def collect_services(filter_names: Optional[List[str]] = None) -> List[Path]:
     return candidates
 
 
+def extract_manual_prefix(path: Path) -> str:
+    """Return any manually-authored content above the generated H1 heading.
+
+    ``render_markdown`` rewrites the whole file, so a hand-written banner above
+    the ``# <name> — Update Notes`` heading (e.g. a SUPERSEDED caution) would be
+    silently wiped on the next rerun. Preserve it verbatim so the helper is safe
+    to re-run against legacy service docs.
+    """
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+    except (OSError, UnicodeDecodeError):
+        return ""
+    for i, line in enumerate(lines):
+        if line.startswith("# ") and "— Update Notes" in line:
+            return "".join(lines[:i])
+    return ""
+
+
 def update_service(service_path: Path, limit: int, dry_run: bool) -> Optional[Path]:
     doc_dir = DOCS_ROOT / service_path.name
     if not doc_dir.exists():
@@ -230,6 +248,11 @@ def update_service(service_path: Path, limit: int, dry_run: bool) -> Optional[Pa
     markdown = render_markdown(service_path.name, commits, versions)
 
     update_path = doc_dir / "UPDATE_NOTES.md"
+    # Preserve a hand-authored prefix (e.g. a SUPERSEDED banner) above the
+    # generated heading so a rerun does not silently discard it.
+    if update_path.exists():
+        markdown = extract_manual_prefix(update_path) + markdown
+
     if not dry_run:
         update_path.write_text(markdown, encoding="utf-8")
     return update_path