[codex] close pure-mcp descriptor ambiguity with signed replay (#26)

* docs: close pure-mcp descriptor ambiguity

(cherry picked from commit 260d845)

* fix: remove duplicate server.json key

(cherry picked from commit 8ef67d7)

Author: xiaojiou176

DISTRIBUTION.md

@@ -23,6 +23,7 @@ shipped yet.
 | :-- | :-- | :-- |
 | Source install from this repository | Ready | The repository ships Python package metadata and console entrypoints such as `movi-organizer`, `movi-web-api`, and `movi-mcp`. |
 | Movi MCP v1 stdio server | Ready | The MCP surface is a local-first stdio integration that can be launched from this repository or an installed environment. |
+| Pure-MCP registry descriptor | Submission-ready-unlisted | Root [`server.json`](./server.json) names the canonical MCP surface without claiming a live registry publication. |
 | Codex / Claude Code setup docs | Ready | The repository ships setup pages for Codex and Claude Code, but those docs describe local wiring, not a separate public distribution channel. |
 | Skills / agent bundle shelf | Submission-ready-unlisted | The repository now ships repo-owned skill bundle examples and install/proof notes without claiming a live skills registry listing. |
 | OpenClaw / ClawHub bundle | Submission-ready-unlisted | The repository now ships an OpenClaw-facing bundle and proof note without claiming a live catalog entry. |
@@ -46,7 +47,8 @@ Use the surfaces above in this order:
 2. GitHub Releases for release history
 3. GitHub Pages for the current public landing route
 4. `manifest.yaml` for the repo-owned submission summary
-5. `examples/skills/README.md` and `examples/openclaw/README.md` for unlisted bundle surfaces
+5. `server.json` for the canonical pure-MCP descriptor
+6. `examples/skills/README.md` and `examples/openclaw/README.md` for unlisted bundle surfaces
 
 If you need to answer a stricter question such as "is the current head verified
 as a published release," do not infer that from a tag alone. Use the release

README.md

@@ -2,7 +2,7 @@
 
 Movi is a review-first local file organizer and workbench for messy photos, screenshots, documents, and audio. It lets AI assist with the manifest first, then lets you inspect, label, and approve the plan before deterministic `apply` or `rollback` touches your files.
 
-[Safe First Look](#safe-first-look) · [10-Second Tour](#10-second-tour) · [Good Fit / Not A Fit](#good-fit--not-a-fit) · [Public Proof](docs/public_proof.md) · [Docs](docs/index.md) · [Distribution](DISTRIBUTION.md) · [Integrations](INTEGRATIONS.md) · [Submission Manifest](manifest.yaml) · [Skills Bundle](examples/skills/README.md) · [OpenClaw Bundle](examples/openclaw/README.md) · [Browser Surface](#browser-surface) · [Releases](https://github.com/xiaojiou176-open/movi-organizer/releases) · [Discussions](https://github.com/xiaojiou176-open/movi-organizer/discussions) · [Security](SECURITY.md) · [Movi MCP v1](docs/mcp.md) · [Codex Integration](docs/codex_mcp.md) · [Claude Code Integration](docs/claude_code_mcp.md) · [Developer Guide](docs/developer_guide.md)
+[Safe First Look](#safe-first-look) · [10-Second Tour](#10-second-tour) · [Good Fit / Not A Fit](#good-fit--not-a-fit) · [Public Proof](docs/public_proof.md) · [Docs](docs/index.md) · [Distribution](DISTRIBUTION.md) · [Integrations](INTEGRATIONS.md) · [Submission Manifest](manifest.yaml) · [MCP Descriptor](server.json) · [Review-First Skill Packet](examples/skills/README.md) · [OpenClaw Bundle](examples/openclaw/README.md) · [Browser Surface](#browser-surface) · [Releases](https://github.com/xiaojiou176-open/movi-organizer/releases) · [Discussions](https://github.com/xiaojiou176-open/movi-organizer/discussions) · [Security](SECURITY.md) · [Movi MCP v1](docs/mcp.md) · [Codex Integration](docs/codex_mcp.md) · [Claude Code Integration](docs/claude_code_mcp.md) · [Developer Guide](docs/developer_guide.md)
 
 ![Movi overview showing mixed files flowing into manifest review and organized output](docs/assets/storefront/hero-movi-overview.svg)
 
@@ -12,6 +12,17 @@ Public maintenance posture: limited-maintenance open source.
 
 Current proof posture: reproducible smoke-tier evidence with a live release trail, Pages front door, and repo-side safety gates. It is not broad benchmark-grade proof yet, but the current front door already clears a truthful public-entry bar, and the proof routes stay explicit in [Public Proof](docs/public_proof.md) instead of being buried in operator-only docs.
 
+## Canonical Public Roots
+
+Read Movi like a workshop with one front desk and several labeled shelves:
+
+- **Canonical public root:** this root [`README.md`](./README.md) plus the root [`manifest.yaml`](./manifest.yaml)
+- **Canonical pure-MCP registry descriptor:** [`server.json`](./server.json)
+- **Current pure-skills packet:** [`examples/skills/`](./examples/skills/)
+- **Host-specific supporting bundle:** [`examples/openclaw/`](./examples/openclaw/)
+- **Pure-MCP support surface:** [`docs/mcp.md`](./docs/mcp.md)
+- **Pure-MCP runtime implementation guide:** [`apps/mcp/README.md`](./apps/mcp/README.md)
+
 ## Why Movi Exists
 
 Cleaning up a mixed folder usually fails for one of two reasons: either the tool is too manual, or the AI is allowed to move files before you can inspect the plan.

apps/mcp/README.md

@@ -0,0 +1,37 @@
+# apps/mcp
+
+`apps/mcp` is the runtime implementation path for Movi MCP v1.
+
+The canonical public root for the product still lives at the repo root
+(`README.md` + `manifest.yaml`), and the canonical machine-readable descriptor
+for the pure-MCP lane now lives at `../../server.json`.
+
+Use the surfaces in this order when you need truthful MCP context:
+
+1. `../../README.md`
+   - canonical public storefront and overall product truth
+2. `../../server.json`
+   - canonical machine-readable MCP descriptor for the repo
+3. `../../docs/mcp.md`
+   - public MCP support surface, install path, and safety boundary
+4. `apps/mcp/*`
+   - implementation files for the local stdio facade
+
+In plain language: this directory is the machine room, not the store window.
+It explains where the MCP runtime is implemented, but it must not pretend to be
+the repo storefront or a live registry listing.
+
+## What lives here
+
+- `server.py`
+  - FastMCP entrypoint and tool/resource registration
+- `service.py`
+  - thin facade over the review-first Movi workflow
+- `__main__.py`
+  - package entrypoint for local execution
+
+## Truth boundary
+
+- this directory does not claim a live registry listing
+- this directory does not replace `docs/mcp.md` as the public MCP support note
+- this directory does not bypass the review-first -> dry-run -> execute contract

contracts/governance/public_readiness_policy.yaml

@@ -11,6 +11,7 @@ required_repo_surface_files:
   - DISTRIBUTION.md
   - INTEGRATIONS.md
   - manifest.yaml
+  - server.json
   - SUPPORT.md
   - CODE_OF_CONDUCT.md
   - .github/CODEOWNERS
@@ -27,6 +28,7 @@ required_repo_surface_files:
   - docs/mcp.md
   - docs/developer_guide.md
   - docs/review_first_ai_file_organizer.md
+  - apps/mcp/README.md
   - examples/skills/README.md
   - examples/skills/SKILL.md
   - examples/openclaw/README.md

contracts/governance/public_surface.yaml

@@ -2,6 +2,7 @@ version: 1
 public_docs:
   - README.md
   - manifest.yaml
+  - server.json
   - AGENTS.md
   - CLAUDE.md
   - LICENSE
@@ -15,6 +16,7 @@ public_docs:
   - CODE_OF_CONDUCT.md
   - docs/usage.md
   - docs/architecture.md
+  - apps/mcp/README.md
   - examples/skills/README.md
   - examples/openclaw/README.md
 public_doc_globs:

contracts/governance/root_allowlist.yaml

@@ -18,6 +18,7 @@ canonical_tracked_entries:
   - NOTICE
   - README.md
   - SECURITY.md
+  - server.json
   - SUPPORT.md
   - THIRD_PARTY_NOTICES.md
   - apps
@@ -70,6 +71,7 @@ entry_purposes:
   NOTICE: public repository notice summary
   README.md: public repo entry document
   SECURITY.md: public security reporting policy
+  server.json: canonical machine-readable MCP descriptor for the public pure-MCP lane
   SUPPORT.md: public support boundary
   THIRD_PARTY_NOTICES.md: third-party dependency and asset notices
   apps: repo entry applications

contracts/governance/root_change_control.yaml

@@ -96,6 +96,10 @@ entries:
     owner: repo
     change_class: security
     approval_rule: architecture-review
+  server.json:
+    owner: repo
+    change_class: public-doc
+    approval_rule: architecture-review
   SUPPORT.md:
     owner: repo
     change_class: public-doc

docs/_generated/render_state.json

@@ -58,14 +58,14 @@
       "block_id": null,
       "source_hashes": {
         "contracts/governance/done_signal_policy.yaml": "16e2fc2add45a68406d6a6077ed7b912fe2406905bf1ff68e967bceeda4bd83c",
-        "contracts/governance/public_readiness_policy.yaml": "eacf27c9d50b2c4295abddecddc23c83f9302140cf82bbd26cd0070cf18ce835",
+        "contracts/governance/public_readiness_policy.yaml": "fc5821ecc62249926ee5e282d114b63eb844d39e4ec408f8673a7bc162d5ad39",
         "contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
         ".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
         ".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
       },
-      "output_hash": "b87dbaba30da2a7478fb1870192748b312367579f91832025a2be12458f9ccba"
+      "output_hash": "fa8b6fe93898b373d52e412d172e93daf7ff7ed50e4b3f29c0c89bb65b6de0c4"
     },
     {
       "id": "root-web-api-routes",
@@ -76,7 +76,7 @@
       "source_hashes": {
         "contracts/api/web_api.openapi.yaml": "c97830844b65fd8f76cd23688187ca8648835d787d1819045882dea01e1d7b64"
       },
-      "output_hash": "c0edfeff801744050b9f8e0b7661f30a4ab0f6667c5d987e24ac7eb1ad56f869"
+      "output_hash": "52a2f027fcd3223d465bdebc88a4dbe70231040cf05ade1c9d53a0f45caedfde"
     },
     {
       "id": "root-runtime-topology",
@@ -91,7 +91,7 @@
         "package.json": "4b9bfb8aac66c5c9101b56af866932d5a27a2b1b912b01439905155a09cd6827",
         ".env.example": "32a60792624cd36eb5992b34d9c67c6e6e2a0971a45f3a48370f3b0b720b0aa8"
       },
-      "output_hash": "c0edfeff801744050b9f8e0b7661f30a4ab0f6667c5d987e24ac7eb1ad56f869"
+      "output_hash": "52a2f027fcd3223d465bdebc88a4dbe70231040cf05ade1c9d53a0f45caedfde"
     },
     {
       "id": "root-ci-governance-summary",
@@ -106,7 +106,7 @@
         "contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
         "package.json": "4b9bfb8aac66c5c9101b56af866932d5a27a2b1b912b01439905155a09cd6827"
       },
-      "output_hash": "c0edfeff801744050b9f8e0b7661f30a4ab0f6667c5d987e24ac7eb1ad56f869"
+      "output_hash": "52a2f027fcd3223d465bdebc88a4dbe70231040cf05ade1c9d53a0f45caedfde"
     },
     {
       "id": "root-release-identity",
@@ -117,7 +117,7 @@
       "source_hashes": {
         "pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495"
       },
-      "output_hash": "c0edfeff801744050b9f8e0b7661f30a4ab0f6667c5d987e24ac7eb1ad56f869"
+      "output_hash": "52a2f027fcd3223d465bdebc88a4dbe70231040cf05ade1c9d53a0f45caedfde"
     },
     {
       "id": "script-readme-web-api-routes",
@@ -179,7 +179,7 @@
       "block_id": "script-readme-governance-truth",
       "source_hashes": {
         "contracts/governance/done_signal_policy.yaml": "16e2fc2add45a68406d6a6077ed7b912fe2406905bf1ff68e967bceeda4bd83c",
-        "contracts/governance/public_readiness_policy.yaml": "eacf27c9d50b2c4295abddecddc23c83f9302140cf82bbd26cd0070cf18ce835",
+        "contracts/governance/public_readiness_policy.yaml": "fc5821ecc62249926ee5e282d114b63eb844d39e4ec408f8673a7bc162d5ad39",
         "contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
@@ -222,7 +222,7 @@
       "block_id": "architecture-governance-truth",
       "source_hashes": {
         "contracts/governance/done_signal_policy.yaml": "16e2fc2add45a68406d6a6077ed7b912fe2406905bf1ff68e967bceeda4bd83c",
-        "contracts/governance/public_readiness_policy.yaml": "eacf27c9d50b2c4295abddecddc23c83f9302140cf82bbd26cd0070cf18ce835",
+        "contracts/governance/public_readiness_policy.yaml": "fc5821ecc62249926ee5e282d114b63eb844d39e4ec408f8673a7bc162d5ad39",
         "contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
@@ -239,7 +239,7 @@
       "block_id": "open-source-platform-truth",
       "source_hashes": {
         "contracts/governance/done_signal_policy.yaml": "16e2fc2add45a68406d6a6077ed7b912fe2406905bf1ff68e967bceeda4bd83c",
-        "contracts/governance/public_readiness_policy.yaml": "eacf27c9d50b2c4295abddecddc23c83f9302140cf82bbd26cd0070cf18ce835",
+        "contracts/governance/public_readiness_policy.yaml": "fc5821ecc62249926ee5e282d114b63eb844d39e4ec408f8673a7bc162d5ad39",
         "contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",

docs/mcp.md

@@ -7,6 +7,12 @@ description: Local-first stdio MCP surface for Movi with review-safe tools, read
 
 `Movi MCP v1` is the local-first stdio extension surface for Movi.
 
+The canonical public root still lives at the repo root (`README.md` +
+`manifest.yaml`), the canonical machine-readable descriptor now lives at
+`../server.json`, and `../apps/mcp/README.md` explains the runtime
+implementation path. This page explains the pure-MCP support surface; it does
+not mean the repo already ships a live registry listing.
+
 In plain language: it gives an agent or automation client a supervised control window into the same workflow humans use in the app. It can inspect jobs, read reports, patch overlays, preview reusable rules, and queue dry-run-safe follow-up work, but it does not get a secret “move files now” shortcut.
 
 ## What V1 Is

docs/reference/governance_truth.generated.md

@@ -29,7 +29,7 @@
 - **Repo public readiness gate**: `bash tooling/gates/public_readiness_gate.sh repo`
 - **Release public readiness gate**: `bash tooling/gates/public_readiness_gate.sh release`
 - **Platform alignment gate**: `bash tooling/gates/platform_alignment_gate.sh`
-- **Required repo surface files**: `28`
+- **Required repo surface files**: `30`
 - **Required package scripts**: `5`
 - **Release-mode requires tracked public files**: `yes`
 - **Release-mode requires public repo**: `yes`