chore: close out final distribution prep surfaces

Author: xiaojiou176

.github/workflows/mutation-weekly.yml .github/workflows/mutation-manual.yml.github/workflows/mutation-weekly.yml renamed to .github/workflows/mutation-manual.yml

@@ -32,7 +32,7 @@ jobs:
         with:
           inputs: >-
             .github/workflows/nightly-drift-audit.yml
-            .github/workflows/upstream-governance-weekly.yml
+            .github/workflows/upstream-governance-manual.yml
             .github/workflows/zizmor.yml
             .github/workflows/trivy-fs.yml
             .github/workflows/trufflehog.yml

…workflows/upstream-governance-weekly.yml …workflows/upstream-governance-manual.yml.github/workflows/upstream-governance-weekly.yml renamed to .github/workflows/upstream-governance-manual.yml .github/workflows/upstream-governance-weekly.yml renamed to .github/workflows/upstream-governance-manual.yml

@@ -76,6 +76,34 @@ Keep the diff honest and reviewable:
 - Do not add compatibility shims just to hide the real problem
 - Keep documentation, contracts, templates, and gate entrypoints aligned
 
+## Current Truth Surface
+
+This repository no longer uses a repo-local `.agents/Tasks` TaskBoard as an
+active source of truth.
+
+Use the versioned repository surfaces on `main` instead:
+
+- `README.md` and `docs/` for public product and operator guidance
+- contracts, workflows, and generated references for executable truth
+- current repository settings and branch protection for GitHub-side policy
+
+Treat `.agents/` as local operator state, not as a committed planning system.
+
+## Closed Dependabot Pull Requests
+
+Closed-but-unmerged Dependabot pull requests in this repository are kept as
+audit history of automated dependency-update attempts that were later closed
+without merge.
+
+Use the following rule when describing them:
+
+- only call a PR a grouped update when `.github/dependabot.yml` directly
+  supports that grouping
+- only call a PR later superseded when current `main` clearly carries the same
+  or a newer dependency state
+- do not treat a closed PR by itself as proof that the proposed dependency
+  state landed
+
 ## Atomic Commit Guidance
 
 Think of the atomic-commit gate like an airline carry-on sizer: it is there

.github/workflows/zizmor.yml

@@ -0,0 +1,48 @@
+# Distribution
+
+This file answers one narrow question:
+
+What public distribution surfaces does Movi actually have today?
+
+Think of it like a shipping manifest. It tells you which boxes are really on
+the truck, which ones are ready at the warehouse, and which ones have not been
+shipped yet.
+
+## Current Published Surfaces
+
+| Surface | Current status | What we can truthfully claim |
+| :-- | :-- | :-- |
+| GitHub repository | Published | The canonical public source and collaboration surface is `xiaojiou176-open/movi-organizer`. |
+| GitHub Releases | Published | GitHub Releases is the canonical release trail for this repository. |
+| GitHub Pages | Published | GitHub Pages is the current public front door and discovery page. |
+
+## Current Ready But Not Registry-Published
+
+| Surface | Current status | What we can truthfully claim |
+| :-- | :-- | :-- |
+| 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. |
+| 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. |
+
+## Surfaces We Do Not Currently Claim As Published
+
+| Surface | Current status | Truthful boundary |
+| :-- | :-- | :-- |
+| PyPI | Not published | This repository does not currently claim an official PyPI release surface. |
+| npm package | Not published | The root Node surface is a repo control surface, not a published npm package. |
+| MCP registry | Not published | `Movi MCP v1` is documented as a local-first stdio surface, not a registry-published listing. |
+| Skills registry | Not published | No official skills-registry distribution claim is made here. |
+| Plugin marketplace | Not published | Strategy Packs are templates, not a plugin marketplace. |
+| Chrome Web Store | Not published | No official Chrome Web Store distribution claim is made here. |
+
+## Current Reading Rule
+
+Use the surfaces above in this order:
+
+1. GitHub repository for the public source of truth
+2. GitHub Releases for release history
+3. GitHub Pages for the current public landing route
+
+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
+truth and release evidence workflows instead of promotional copy.

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Integrations
+
+This file answers a different question from `DISTRIBUTION.md`:
+
+What integration surfaces does Movi actually fit today?
+
+Think of it like a map of doors into the same workshop. Some doors are first
+class, some are side entrances, and some are only comparison points.
+
+## Core Integration Surfaces
+
+| Surface | Current role | Truthful boundary |
+| :-- | :-- | :-- |
+| CLI | Primary operator surface | Best for full analyze, apply, rollback, and report workflows. |
+| Web API | Local integration substrate | A local HTTP contract exists for app and builder integration. |
+| Generated TypeScript client | Builder substrate | The repository exposes generated client/types for local integrations. |
+| Movi MCP v1 | Primary agent integration surface | The canonical agent-facing surface is local-first stdio MCP. |
+
+## Primary Fit
+
+| Client | Why it is a primary fit | Boundary |
+| :-- | :-- | :-- |
+| Codex | The repository already ships a dedicated Codex MCP setup page and local-first stdio wiring. | This is local MCP wiring, not a hosted service. |
+| Claude Code | The repository already ships a dedicated Claude Code MCP setup page and local-first stdio wiring. | This is local MCP wiring, not a hosted service. |
+
+## Secondary Fit
+
+| Client family | Why it is a secondary fit | Boundary |
+| :-- | :-- | :-- |
+| Cursor and other local MCP-capable clients | The current transport and tool surface already match their local MCP model. | The repository does not currently promote them as the front-door story. |
+
+## Comparison-Only Fit
+
+| Client family | Why it stays comparison-only | Boundary |
+| :-- | :-- | :-- |
+| OpenHands | A real API and MCP substrate exists, but no dedicated first-party setup page or branded workflow is shipped. | Do not present it as a primary or secondary front-door integration. |
+| OpenCode | Same honest boundary as OpenHands. | Do not present it as a primary or secondary front-door integration. |
+
+## Not A Front-Door Fit Today
+
+| Surface | Why it is not front-door fit today |
+| :-- | :-- |
+| OpenClaw | The repository does not currently ship a dedicated integration surface or branded product flow for it. |
+| MCP registry listings | The current story is local-first stdio MCP, not registry publication. |
+| Skills registry or plugin marketplaces | The repository does not currently claim those as shipped integration channels. |
+
+## Safety Boundary
+
+All current integrations share the same safety line:
+
+- review-first
+- overlay-only editing for review state
+- dry-run before execute
+- no hidden `apply.execute` shortcut in `Movi MCP v1`
+
+If a description crosses that line, it is overstating the current integration
+surface.

DISTRIBUTION.md

@@ -66,7 +66,8 @@ Movi belongs to a very specific lane:
 Current honest ecosystem fit:
 
 - **Primary fit**: Codex and Claude Code, because `Movi MCP v1` already ships as a local-first stdio surface with review-safe tools
-- **Secondary ecosystem fit**: OpenHands and OpenCode, because the repo has a real MCP and API substrate they can consume, but no dedicated first-party setup surface yet
+- **Secondary ecosystem fit**: Cursor and other local MCP-capable clients, because the transport and tool surface already match their integration model
+- **Comparison-only fit**: OpenHands and OpenCode, because the repo has a real MCP and API substrate they can consume, but no dedicated first-party setup surface or branded workflow yet
 - **Not a front-door fit today**: OpenClaw, because the repo does not currently ship a tailored integration surface or branded product claim for it
 
 ## 10-Second Tour

INTEGRATIONS.md

@@ -40,7 +40,7 @@ renders:
       - .github/workflows/ci.yml
       - .github/workflows/pre-commit.yml
       - .github/workflows/live-integration.yml
-      - .github/workflows/mutation-weekly.yml
+      - .github/workflows/mutation-manual.yml
     output_path: docs/reference/governance_truth.generated.md
   - id: root-web-api-routes
     kind: fragment
@@ -124,7 +124,7 @@ renders:
       - .github/workflows/ci.yml
       - .github/workflows/pre-commit.yml
       - .github/workflows/live-integration.yml
-      - .github/workflows/mutation-weekly.yml
+      - .github/workflows/mutation-manual.yml
     output_path: docs/usage.md
     block_id: script-readme-governance-truth
   - id: architecture-web-api-summary
@@ -155,7 +155,7 @@ renders:
       - .github/workflows/ci.yml
       - .github/workflows/pre-commit.yml
       - .github/workflows/live-integration.yml
-      - .github/workflows/mutation-weekly.yml
+      - .github/workflows/mutation-manual.yml
     output_path: docs/architecture.md
     block_id: architecture-governance-truth
   - id: open-source-platform-truth
@@ -168,7 +168,7 @@ renders:
       - .github/workflows/ci.yml
       - .github/workflows/pre-commit.yml
       - .github/workflows/live-integration.yml
-      - .github/workflows/mutation-weekly.yml
+      - .github/workflows/mutation-manual.yml
     output_path: docs/open_source_runbook.md
     block_id: open-source-platform-truth
   - id: runner-contract-governance-truth
@@ -179,7 +179,7 @@ renders:
       - .github/workflows/ci.yml
       - .github/workflows/pre-commit.yml
       - .github/workflows/live-integration.yml
-      - .github/workflows/mutation-weekly.yml
+      - .github/workflows/mutation-manual.yml
     output_path: docs/runner_contract.md
     block_id: runner-contract-governance-truth
   - id: webui-api-contract

README.md

@@ -63,7 +63,7 @@
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
         ".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
-        ".github/workflows/mutation-weekly.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
+        ".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
       },
       "output_hash": "1e9db2c2bcd9dc853fd5772bd1edabf7b910d9014dc7bc2cc78f5a835f83e588"
     },
@@ -76,7 +76,7 @@
       "source_hashes": {
         "contracts/api/web_api.openapi.yaml": "c97830844b65fd8f76cd23688187ca8648835d787d1819045882dea01e1d7b64"
       },
-      "output_hash": "cb6345e4f376224c71bddab270ce33f2a043caf985668a63c5b18cdea159c44a"
+      "output_hash": "ac7ae956b9adc83bdebf65c60c15798a27259f5be04ce702d4d8bcd1d2d75843"
     },
     {
       "id": "root-runtime-topology",
@@ -91,7 +91,7 @@
         "package.json": "19ed161b16378601fc42d4baa05b7225fc57a47cfdee28a64131fd57d3cd1efc",
         ".env.example": "32a60792624cd36eb5992b34d9c67c6e6e2a0971a45f3a48370f3b0b720b0aa8"
       },
-      "output_hash": "cb6345e4f376224c71bddab270ce33f2a043caf985668a63c5b18cdea159c44a"
+      "output_hash": "ac7ae956b9adc83bdebf65c60c15798a27259f5be04ce702d4d8bcd1d2d75843"
     },
     {
       "id": "root-ci-governance-summary",
@@ -106,7 +106,7 @@
         "contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
         "package.json": "19ed161b16378601fc42d4baa05b7225fc57a47cfdee28a64131fd57d3cd1efc"
       },
-      "output_hash": "cb6345e4f376224c71bddab270ce33f2a043caf985668a63c5b18cdea159c44a"
+      "output_hash": "ac7ae956b9adc83bdebf65c60c15798a27259f5be04ce702d4d8bcd1d2d75843"
     },
     {
       "id": "root-release-identity",
@@ -117,7 +117,7 @@
       "source_hashes": {
         "pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495"
       },
-      "output_hash": "cb6345e4f376224c71bddab270ce33f2a043caf985668a63c5b18cdea159c44a"
+      "output_hash": "ac7ae956b9adc83bdebf65c60c15798a27259f5be04ce702d4d8bcd1d2d75843"
     },
     {
       "id": "script-readme-web-api-routes",
@@ -184,7 +184,7 @@
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
         ".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
-        ".github/workflows/mutation-weekly.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
+        ".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
       },
       "output_hash": "4203a15a1ce623a972a6ba31f6a28f55eaa4520db960e7529b165e1bb550e2b3"
     },
@@ -227,7 +227,7 @@
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
         ".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
-        ".github/workflows/mutation-weekly.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
+        ".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
       },
       "output_hash": "c0cb776be4feeaa4d6517d934e2d4f541ae1a04d66350c7bd82da6b009f710b4"
     },
@@ -244,7 +244,7 @@
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
         ".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
-        ".github/workflows/mutation-weekly.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
+        ".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
       },
       "output_hash": "590a2ddf45c93e4e0639c4c4a077e725da6fb8c107a7567d7edb484e714a5b2b"
     },
@@ -259,9 +259,9 @@
         ".github/workflows/ci.yml": "145d243beb087cd6a976d45e4455e0747ace3ee3ad9c77160b57fb17f75c63fe",
         ".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
         ".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
-        ".github/workflows/mutation-weekly.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
+        ".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
       },
-      "output_hash": "6f81c9b2b0e6e733c3f9eaebc0a92d2c05d246683a14750e6cb42f7d4a359700"
+      "output_hash": "633b230e1dba7628f622a01d8a4ed273844a38bd15e88124a914ea2e500d2edc"
     },
     {
       "id": "webui-api-contract",

contracts/docs/docs_render_manifest.yaml

@@ -15,6 +15,8 @@ Movi is a review-first local file organizer and workbench for messy photos, scre
 - Need the full operator route: open [Operator Guide](./usage.md)
 - Need system wiring: open [Architecture](./architecture.md)
 - Need release or GitHub-facing boundary rules: open [Open Source Runbook](./open_source_runbook.md)
+- Need the current distribution boundary: open [Distribution](../DISTRIBUTION.md)
+- Need the current client-fit map: open [Integrations](../INTEGRATIONS.md)
 - Need the naming baseline: open [Brand Positioning](./brand_positioning.md)
 - Need the search-intent map: open [SEO Landing Map](./seo_landing_map.md)
 - Want the search-intent landing page first: open [Review-First AI File Organizer](./review_first_ai_file_organizer.md)