Movi | Review-first file organization docs

Movi Detailed Operator Guide

This file is the detailed operator guide. Detailed operator guide for runtime commands, API usage, and operator-facing execution notes. This guide is for people who want the full operator route, not just the fast first-look flow from README.md.

If you only need the public overview, go back to README.md. If you need release or platform-boundary rules, continue with docs/open_source_runbook.md.

This repository is a limited-maintenance open-source project. The product promise stays intentionally small: review-first, AI-assisted, dry-run before execute, rollback-ready, local-first.

What This Guide Is For

Use this document when you need one of these:

Copyable Config Example

If you want an explicit config file path in your command, use:

--config ./contracts/runtime/config.example.toml

That flag is useful when you want a command that can be copied into an issue, a docs example, or a repeatable local script without depending on hidden shell state.

Core Flow

Think of the workflow as three separate steps:

analyze may call Gemini. apply and rollback do not call Gemini.

When you use the browser surface, the practical route is a little more guided:

Naming Baseline

Fast Operator Route

This route is longer than the README quickstart because it is meant for people who want explicit paths and repeatable local outputs.

bash tooling/runtime/bootstrap_env.sh
mkdir -p .runtime-cache/operator-demo
MOVI_ALLOW_HOST_EXECUTION=1 bash tooling/runtime/run_analyze.sh \
  --offline \
  --config ./contracts/runtime/config.example.toml \
  --input ./tests/fixtures/golden_input \
  --manifest ./.runtime-cache/operator-demo/manifest.jsonl \
  --report ./.runtime-cache/operator-demo/analyze-report.json
cp ./.runtime-cache/operator-demo/manifest.jsonl ./.runtime-cache/operator-demo/manifest.apply.jsonl
MOVI_ALLOW_HOST_EXECUTION=1 bash tooling/runtime/run_apply.sh \
  --config ./contracts/runtime/config.example.toml \
  --manifest ./.runtime-cache/operator-demo/manifest.apply.jsonl \
  --input-root ./tests/fixtures/golden_input \
  --output ./.runtime-cache/operator-demo/output \
  --dry-run \
  --verify-sha1 \
  --report ./.runtime-cache/operator-demo/apply-report.json

Start real execution only after a dry run and review-queue pass.

Browser Surface Route

If you want the app shell instead of the CLI:

npm run dev:stack

This starts the Web API and WebUI so you can walk through setup, analyze, Movi Review, Movi Rules, apply, report, rollback, and Movi Inbox from the browser. Inside the review workbench, saved rules can be reloaded into Rule Studio and learned suggestions can be promoted into an editable draft before you apply them to the overlay. The current Wave 2 surface also adds a visible Movi Copilot v1 panel for review-only guidance, batch triage that writes to the overlay rather than disk, explainable learned suggestions that can be accepted or dismissed, and a rule from examples helper that seeds Rule Studio with transparent heuristics instead of auto-executing changes. The current Wave 3 surface makes the front door more continuous: Inbox can explicitly launch Analyze with batch context, Strategy Packs are explained as analyze templates instead of hidden settings, Collection Intelligence v2 explains why a slice belongs together, and Report can loop you back into Review with clear focus filters such as conflicts or learning suggestions. Wave 4 adds Movi MCP v1 as the agent/developer-facing extension surface. It stays stdio-first and local-first, and it only exposes review-safe tools plus read-only resources rather than a hidden execute shortcut.

Important promise boundary:

Movi MCP v1

Movi MCP v1 is the agent-safe extension surface for this repository.

In plain language: it gives an LLM or automation client a supervised service window into the same workflow you already use in the app. It can inspect queues, read reports, patch overlays, preview rules, and queue dry-run apply jobs, but it does not get a secret door that bypasses review.

Use it when you want:

Do not use it as if it were:

Start with docs/mcp.md for the capability map and docs/developer_guide.md for the surface-selection guide.

Operator Notes

Space Governance

Think of Movi’s runtime footprint as four primary rails, plus one infrastructure-only surface:

Use the cleanup entrypoint that matches the bucket you actually want to trim:

# repo-local residue only
bash tooling/cleanup/prune_repo_runtime.sh

# safest machine-cache cleanup: Python bytecode only
bash tooling/cleanup/prune_machine_cache.sh --safe

# broader rebuildable machine caches: pycache + pip + npm + playwright + pytest-runtime
bash tooling/cleanup/prune_machine_cache.sh --rebuildable

# aggressive host fallback reclaim: rebuildable caches + governed host venv
bash tooling/cleanup/prune_machine_cache.sh --aggressive-host

# container-first docker runtime audit
bash tooling/cleanup/prune_docker_runtime.sh --dry-run

# repo-related docker build cache only
bash tooling/cleanup/prune_docker_runtime.sh --rebuildable

# explicit high-risk docker reclaim path (still opt-in for image/volumes)
bash tooling/cleanup/prune_docker_runtime.sh --aggressive

# workspace retention cleanup (runs/artifacts only; manifests stay intact)
bash tooling/cleanup/prune_workspace_runtime.sh --dry-run

Important boundary:

Where To Read What

Auto-generated: the current source package version comes from pyproject.toml. current-head release boundaries depend on local/CI runtime evidence, and a clean checkout does not carry a repo-local release evidence summary by default.

Runtime Topology

Auto-generated: runtime services, default ports, runtime paths, and entrypoint facts live in generated runtime topology.

Web API Summary

Auto-generated: current Web API facts come from contracts/api/web_api.openapi.yaml; the full method/path list lives in generated reference.

Governance And Completion

Auto-generated: delivery-complete truth, governance scorecard truth, hosted CI facts, and platform-alignment facts live in generated governance reference, required checks matrix, and runner contract.

Delivery-complete truth for the current snapshot still comes only from a fresh pass of bash tooling/gates/quality_gate.sh. Repo-side governance scorecard, not delivery completion: bash tooling/gates/verify_repo_final.sh.

CI Summary

Auto-generated: CI truth-chain, failure-domain policy, navigation entrypoints, and executable gate facts come from required checks matrix, runner contract, and ci.yml.

This site is open source. Improve this page.