docs: sharpen front door proof routes

xiaojiou176 · xiaojiou176 · commit 44e103a054a5 · 2026-04-07T00:42:34.000-07:00
diff --git a/README.md b/README.md
@@ -2,15 +2,15 @@
 
 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) · [Browser Surface](#browser-surface) · [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) · [Docs](docs/index.md) · [Releases](https://github.com/xiaojiou176-open/movi-organizer/releases) · [Discussions](https://github.com/xiaojiou176-open/movi-organizer/discussions) · [Security](SECURITY.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) · [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)
 
 Movi is a **review-first local AI file organizer**. It turns a chaotic intake folder into a review queue, then into a reviewed manifest, and only then into safer file moves you can dry-run, audit, and roll back. The current shipped surface stays intentionally narrow: `Movi Review`, `Movi Rules`, `Movi Inbox`, `Movi Copilot v1`, and `Movi MCP v1` all describe real current surfaces, but they still stay inside one safety story instead of pretending Movi is an autonomous organizer.
 
 Public maintenance posture: limited-maintenance open source.
 
-Current proof posture: reproducible smoke-tier evidence with upgrade packs for recorded manual baselines and human rubric review. It is not public-grade headline proof yet.
+Current proof posture: reproducible smoke-tier evidence with a live release trail, Pages front door, and repo-side safety gates. It is not public-grade headline proof yet, and the current proof routes are kept explicit in [Public Proof](docs/public_proof.md) instead of being buried in operator-only docs.
 
 ## Why Movi Exists
 
@@ -33,6 +33,17 @@ Think of it like moving house: AI makes the packing list, but the moving crew st
 - **Local-first runtime**: your folders, manifests, and reports stay under your chosen workspace root.
 - **Operator-grade guardrails**: quality gates, structured logs, and release runbooks exist for people who need deeper operational truth.
 
+## Public Proof At A Glance
+
+If you are asking, "is this a real product surface or just a careful README," the shortest honest answer is:
+
+- **Public source repo + GitHub Releases**: the release trail is public on [GitHub Releases](https://github.com/xiaojiou176-open/movi-organizer/releases).
+- **Live Pages front door**: the current public landing route is [xiaojiou176-open.github.io/movi-organizer](https://xiaojiou176-open.github.io/movi-organizer/).
+- **Review-first proof, not autonomy theater**: the repo ships a fixture-backed safe first look, dry-run apply, rollback boundaries, and a real MCP surface that still stays behind review-safe semantics.
+- **Honest boundary language**: Movi does not claim hosted SaaS, zero-review file mutation, or public benchmark-grade proof that the repo has not actually earned yet.
+
+If you want the full outsider-facing proof map, open [Public Proof](docs/public_proof.md). If you want the shortest hands-on route, stay on this page and run [Safe First Look](#safe-first-look).
+
 ## Product Surface Baseline
 
 - **Movi**: the main product brand.
@@ -155,7 +166,7 @@ If you want the public release storyline instead of the repo history, start with
 - **The manifest is the source of truth**: review happens before file mutation.
 - **`apply` and `rollback` stay deterministic**: AI helps plan, not execute arbitrary moves.
 - **Safety language is explicit**: `dry-run`, `allowed-root`, and manifest validation are first-class, not buried extras.
-- **Governance truth is documented**: deeper runtime, release, and platform boundaries are kept in operator docs instead of being silently implied.
+- **Proof routes are explicit**: live release, Pages, and deeper operator truth routes are linked directly instead of being hidden in internal-only notes.
 
 ## Brand And Landing Notes
 
@@ -221,25 +232,16 @@ Container-first default:
 
 If review-first cleanup is the workflow you keep wishing existed, star the repo so you can find Movi again when the next messy folder lands.
 
-## Operator And Governance References
+## Proof And Truth Routes
 
+- Public-facing proof map: [docs/public_proof.md](docs/public_proof.md)
 - Detailed operator route: [docs/usage.md](docs/usage.md)
 - Architecture and execution boundaries: [docs/architecture.md](docs/architecture.md)
 - Public release and platform boundary: [docs/open_source_runbook.md](docs/open_source_runbook.md)
 - Third-party notices: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)
 
-## Deeper Operator Truth Surfaces
-
 Delivery-complete truth for the current snapshot still depends on fresh gate evidence, not on static prose.
-Treat `bash tooling/gates/quality_gate.sh` as the delivery-complete receipt for the current snapshot.
-Treat repository docs as guidance, not as live platform state.
-
-## Minimal Truth Routes
-
-- Overview and fastest first look: [README.md](README.md)
-- Detailed operator guide: [docs/usage.md](docs/usage.md)
-- Architecture and execution boundaries: [docs/architecture.md](docs/architecture.md)
-- Public release and platform boundary: [docs/open_source_runbook.md](docs/open_source_runbook.md)
+Treat `bash tooling/gates/quality_gate.sh` as the delivery-complete receipt for the current snapshot, and treat repository docs as guidance rather than a live platform dashboard.
 
 Public readiness gates:
 
diff --git a/docs/index.md b/docs/index.md
@@ -11,16 +11,16 @@ Movi is a review-first local file organizer and workbench for messy photos, scre
 
 - New here: read the public overview in [README.md](../README.md)
 - Want the fastest safe first look: follow [Quickstart](./quickstart.md)
+- Want the shortest outsider-facing trust map: open [Public Proof](./public_proof.md)
 - Need the full operator route: open [Operator Guide](./usage.md)
-- Want the agent/developer extension surface: open [Movi MCP v1](./mcp.md) and [Developer Guide](./developer_guide.md)
-- Want a client-specific MCP route: open [Movi MCP For Codex](./codex_mcp.md) or [Movi MCP For Claude Code](./claude_code_mcp.md)
-- Need the shortest builder route for MCP vs Web API vs generated client: open [Developer Guide](./developer_guide.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 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)
 - Need a use-case landing page first: open [Photo Organizer](./photo_organizer.md), [Screenshot Organizer](./screenshot_organizer.md), or [Receipt Organizer](./receipt_organizer.md)
+- Want the agent/developer extension surface after you understand the product story: open [Movi MCP v1](./mcp.md) and [Developer Guide](./developer_guide.md)
+- Want a client-specific MCP route: open [Movi MCP For Codex](./codex_mcp.md) or [Movi MCP For Claude Code](./claude_code_mcp.md)
 
 ## What Makes Movi Different
 
@@ -56,6 +56,7 @@ This Navigation map is intentionally search-before-write friendly: pick the shor
 ## Next Doors
 
 - [Quickstart / safe first look](./quickstart.md)
+- [Public Proof](./public_proof.md)
 - [FAQ](./faq.md)
 - [Movi MCP v1](./mcp.md)
 - [Movi MCP For Codex](./codex_mcp.md)
diff --git a/docs/public_proof.md b/docs/public_proof.md
@@ -0,0 +1,64 @@
+# Movi Public Proof
+
+This page is the outsider-facing proof map for Movi.
+
+In plain language: it tells a first-time visitor what Movi already proves in public, where to click for live evidence, and what Movi still does **not** claim yet.
+
+## What Movi Publicly Proves Today
+
+- **The core story is real**: Movi ships a review-first local file organizer and workbench, not just a future concept.
+- **The safe path is real**: the repo contains a fixture-backed first-look route that goes `analyze -> manifest -> dry-run apply` without touching real folders by default.
+- **The public release surface is real**: Movi publishes a live source repo and release trail on GitHub.
+- **The browser surface is real**: the GitHub Pages front door is already live.
+- **The agent surface is real, but secondary**: `Movi MCP v1` exists as a local-first stdio extension surface, but it is not the main product claim.
+
+## Live Proof Routes
+
+Use these routes when you want current public evidence instead of marketing prose:
+
+| What you want to verify | Live route |
+| :-- | :-- |
+| Public source repo | [GitHub repository](https://github.com/xiaojiou176-open/movi-organizer) |
+| Public release trail | [GitHub Releases](https://github.com/xiaojiou176-open/movi-organizer/releases) |
+| Public front door | [GitHub Pages site](https://xiaojiou176-open.github.io/movi-organizer/) |
+| Current docs landing page | [docs/index.md](./index.md) |
+| Safe first-look workflow | [Quickstart](./quickstart.md) |
+| Review-first operator contract | [README.md](../README.md) and [Operator Guide](./usage.md) |
+| Agent/developer extension surface | [Movi MCP v1](./mcp.md) |
+
+## What Movi Does Not Claim Yet
+
+Movi is intentionally explicit about the boundaries it has **not** crossed yet:
+
+- not a hosted SaaS
+- not a zero-review automatic organizer
+- not a broad agent platform whose first identity is MCP
+- not public-grade headline proof with large public benchmark packs or broad external validation
+
+Think of it like a well-run workshop that already has a real front door, a real service desk, and real receipts, but has not yet turned itself into a shopping mall with billboards claiming world domination.
+
+## How To Read The Current Proof Posture
+
+The current proof posture is best understood in three layers:
+
+| Layer | What it proves | What it does not prove |
+| :-- | :-- | :-- |
+| Repo-side proof | the shipped workflow, docs, gates, and local-first runtime surfaces are real | that every live GitHub/platform detail is currently aligned |
+| Public platform proof | the repo, Pages, releases, and public-facing GitHub surfaces are live | that every deeper manual or admin-only platform toggle is already perfect |
+| Manual / human proof | recorded human baselines, rubric reviews, and broader user trust signals | anything the repo has not explicitly published yet |
+
+## Why This Page Exists
+
+Movi already had a lot of serious engineering proof, but too much of it was hidden in operator docs and workflow files.
+
+This page exists so the front door can answer three normal outsider questions faster:
+
+1. Is this thing real?
+2. Where do I see the proof?
+3. What is still intentionally not claimed yet?
+
+## Best Next Click
+
+- If you want the shortest honest demo path: open [Quickstart](./quickstart.md)
+- If you want the full product overview first: go back to [README.md](../README.md)
+- If you want the deeper operator truth routes: open [Operator Guide](./usage.md) and [Open Source Runbook](./open_source_runbook.md)
