{"id":48111570,"url":"https://github.com/xiaojiou176-open/prooftrail","last_synced_at":"2026-04-04T16:08:02.658Z","repository":{"id":346739288,"uuid":"1169264672","full_name":"xiaojiou176-open/prooftrail","owner":"xiaojiou176-open","description":"Auditable browser automation platform for repeatable runs, inspectable evidence, and recovery-ready workflows.","archived":false,"fork":false,"pushed_at":"2026-03-25T23:06:10.000Z","size":8363,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T11:51:15.349Z","etag":null,"topics":["browser-automation","developer-tools","e2e-testing","fastapi","mcp","playwright","reproducibility","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xiaojiou176-open.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-28T12:24:53.000Z","updated_at":"2026-03-25T23:06:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xiaojiou176-open/prooftrail","commit_stats":null,"previous_names":["xiaojiou176-open/prooftrail"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/xiaojiou176-open/prooftrail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaojiou176-open%2Fprooftrail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaojiou176-open%2Fprooftrail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaojiou176-open%2Fprooftrail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaojiou176-open%2Fprooftrail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xiaojiou176-open","download_url":"https://codeload.github.com/xiaojiou176-open/prooftrail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaojiou176-open%2Fprooftrail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405502,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser-automation","developer-tools","e2e-testing","fastapi","mcp","playwright","reproducibility","workflow-automation"],"created_at":"2026-04-04T16:08:02.585Z","updated_at":"2026-04-04T16:08:02.648Z","avatar_url":"https://github.com/xiaojiou176-open.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ProofTrail\n\nEvidence-first browser automation with recovery and MCP.\n\nFor AI agents and human operators who need inspectable runs, retained\nevidence, and guided recovery.\n\nIt also fits teams using Codex, Claude Code, OpenHands, OpenCode, OpenClaw, or\nother agent shells that need a browser-evidence layer through API and governed\nMCP, not a generic browser bot.\n\n[Docs](docs/index.md) | [Quickstart](docs/getting-started/human-first-10-min.md) | [Minimal Success Case](docs/showcase/minimal-success-case.md) | [API Builder Quickstart](docs/how-to/api-builder-quickstart.md) | [ProofTrail for AI Agents](docs/how-to/prooftrail-for-ai-agents.md) | [ProofTrail for Coding Agents and Agent Ecosystems](docs/how-to/prooftrail-for-coding-agents.md) | [MCP for Browser Automation](docs/how-to/mcp-quickstart-1pager.md) | [AI Reconstruction](docs/how-to/ai-reconstruction-side-road.md) | [Evidence, Recovery, and Review Workspace](docs/how-to/evidence-recovery-review-workspace.md) | [Alternatives](docs/compare/prooftrail-vs-generic-browser-agents.md) | [Release Guide](docs/release/README.md)\n\n\u003cimg src=\"assets/storefront/prooftrail-readme-hero.svg\" alt=\"ProofTrail canonical proof loop showing one public command, one retained evidence bundle, and one exact recovery path.\" /\u003e\n\n![ProofTrail command center showing the canonical run path, evidence-focused navigation, and operator parameter rail](assets/storefront/prooftrail-hero.png)\n\n\u003e ProofTrail is for AI agents and human operators who need browser automation\n\u003e to stay inspectable, replayable, and recoverable after the first run.\n\n## Category Fit\n\nProofTrail is not a generic browser bot and it is not a hosted AI agent\nplatform.\n\nIt is an evidence-first browser automation product:\n\n- run one canonical workflow\n- inspect one retained evidence bundle\n- recover with structured guidance\n- expose the same trusted surfaces to MCP clients and optional AI helpers\n\n## Why ProofTrail\n\n- **One canonical path**: start with `just run`, then inspect one retained\n  evidence bundle instead of juggling ad-hoc scripts and shell fragments.\n- **Recovery before guesswork**: move from explanation to recovery to compare\n  before you fall back to raw logs or helper-path debugging.\n- **AI and MCP in the right place**: use AI reconstruction and MCP as governed\n  side roads after the first proof run, not as replacements for the\n  deterministic mainline.\n- **Strong AI-builder fit without fake heat**: ProofTrail is a truthful browser\n  evidence layer for Codex, Claude Code, OpenHands, OpenCode, OpenClaw, and\n  other AI-agent workflows that need retained proof, recovery, and governed\n  integration instead of prompt-only browser improvisation.\n\n## Builder Entry\n\nIf you are integrating ProofTrail into another toolchain, use this order:\n\n1. [API Builder Quickstart](docs/how-to/api-builder-quickstart.md)\n2. [Universal API Reference](docs/reference/universal-api.md)\n3. `node --import tsx contracts/scripts/generate-client.ts --verify`\n4. [ProofTrail MCP Server README](apps/mcp-server/README.md)\n\nThat sequence helps you separate:\n\n- the **API contract layer**\n- the **generated-client freshness path**\n- the **governed MCP tool surface**\n\nThe checked-in client under `apps/web/src/api-gen/` is a **repo-local\ngenerated helper**, not a published SDK package.\n\nIf you are evaluating this repo for **Codex**, **Claude Code**,\n**OpenHands**, **OpenCode**, **OpenClaw**, or similar coding-agent workflows,\nkeep the fit narrow and honest:\n\n- ProofTrail does **not** replace a coding agent\n- it fits as the browser execution, retained evidence, recovery, and governed\n  MCP/API layer that a coding agent can call\n- the best public entry is still\n  [ProofTrail for AI Agents](docs/how-to/prooftrail-for-ai-agents.md), then the\n  builder/API and MCP pages\n\n## For Coding-Agent And Agent-Stack Workflows\n\nIf you found ProofTrail while searching for:\n\n- browser automation for Codex\n- browser automation for Claude Code\n- browser automation for OpenHands\n- browser automation for OpenCode\n- browser automation for OpenClaw\n- MCP browser automation for AI agents\n- API-first browser evidence for tool-using agents\n\nread this repo in one very specific way:\n\n\u003e ProofTrail is a browser-execution and evidence layer for agent shells such as\n\u003e Codex, Claude Code, OpenHands, OpenCode, OpenClaw, and other tool-using AI\n\u003e workflows. It is **not** claiming to be an official vendor-specific\n\u003e integration, plugin, or generic AI assistant shell.\n\nThe most truthful ecosystem fit today looks like this:\n\n| Ecosystem | Best public angle | Best first road |\n| --- | --- | --- |\n| Claude Code | governed browser-evidence side road for a tool-using coding shell | [ProofTrail for Coding Agents and Agent Ecosystems](docs/how-to/prooftrail-for-coding-agents.md) -\u003e [MCP for Browser Automation](docs/how-to/mcp-quickstart-1pager.md) |\n| Codex | browser-evidence substrate with API-first control and optional MCP | [ProofTrail for Coding Agents and Agent Ecosystems](docs/how-to/prooftrail-for-coding-agents.md) -\u003e [API Builder Quickstart](docs/how-to/api-builder-quickstart.md) |\n| OpenHands | browser-evidence subsystem behind a larger orchestration runtime | [ProofTrail for AI Agents](docs/how-to/prooftrail-for-ai-agents.md) -\u003e [API Builder Quickstart](docs/how-to/api-builder-quickstart.md) |\n| OpenCode | governed MCP browser surface behind the coding-agent shell | [ProofTrail for Coding Agents and Agent Ecosystems](docs/how-to/prooftrail-for-coding-agents.md) -\u003e [MCP for Browser Automation](docs/how-to/mcp-quickstart-1pager.md) |\n| OpenClaw | browser workflow backend behind a multi-channel gateway or tool router | [ProofTrail for Coding Agents and Agent Ecosystems](docs/how-to/prooftrail-for-coding-agents.md) -\u003e [API Builder Quickstart](docs/how-to/api-builder-quickstart.md) |\n\nThe truthful bridge is:\n\n1. [ProofTrail for AI Agents](docs/how-to/prooftrail-for-ai-agents.md)\n2. [ProofTrail for Coding Agents and Agent Ecosystems](docs/how-to/prooftrail-for-coding-agents.md)\n3. [MCP for Browser Automation](docs/how-to/mcp-quickstart-1pager.md)\n4. [API Builder Quickstart](docs/how-to/api-builder-quickstart.md)\n\nThis discovery layer is **not claiming** official vendor integrations, plugins,\nor a generic AI assistant shell.\n\nThat order keeps search intent and product truth aligned:\n\n- audience fit first\n- coding-agent fit second\n- governed MCP tool use third\n- direct API control after that\n\n## Ecosystem Fit At A Glance\n\nIf you only have ten seconds, use the map below like an airport departures\nboard:\n\n- **Claude Code** and **OpenCode** are the clearest MCP-first fits today\n- **Codex**, **OpenHands**, and **OpenClaw** usually start API-first or hybrid\n- **ProofTrail** stays the browser-evidence and recovery layer in all cases\n\n\u003cimg src=\"assets/storefront/prooftrail-agent-ecosystem-map.svg\" alt=\"ProofTrail ecosystem fit map showing Codex, Claude Code, OpenHands, OpenCode, and OpenClaw with API-first and MCP-first entry roads.\" /\u003e\n\n## Explore the Product Surface\n\nIf you want the shortest truthful way to understand where ProofTrail fits, use\nthese six pages as the current public matrix:\n\n1. [ProofTrail for AI Agents](docs/how-to/prooftrail-for-ai-agents.md)\n2. [ProofTrail for Coding Agents and Agent Ecosystems](docs/how-to/prooftrail-for-coding-agents.md)\n3. [MCP for Browser Automation](docs/how-to/mcp-quickstart-1pager.md)\n4. [AI Reconstruction Side Road](docs/how-to/ai-reconstruction-side-road.md)\n5. [ProofTrail vs Generic Browser Agents](docs/compare/prooftrail-vs-generic-browser-agents.md)\n6. [Evidence, Recovery, and Review Workspace](docs/how-to/evidence-recovery-review-workspace.md)\n\nIf your search intent sounds more like:\n\n- `browser automation for Codex`\n- `browser automation for Claude Code`\n- `browser automation for OpenHands`\n- `browser automation for OpenCode`\n- `browser automation for OpenClaw`\n- `MCP browser automation for AI agents`\n- `browser evidence layer for coding agents`\n\nstart with [ProofTrail for AI Agents](docs/how-to/prooftrail-for-ai-agents.md)\nbefore dropping into the lower-level builder pages.\n\nThat sequence keeps the outward story honest:\n\n- audience fit first\n- coding-agent fit second\n- governed MCP and AI side roads next\n- alternatives framing after that\n- evidence/recovery/review loop as the deepest current product proof\n\nUse the builder entry separately.\n\nThe outward matrix explains category fit and product shape.\nThe builder entry explains contract-level integration once that product shape\nalready makes sense.\n\nIf you are coming from the builder side instead of the operator side, pair that\nmatrix with the [API Builder Quickstart](docs/how-to/api-builder-quickstart.md)\nso the public story and the integration story stay connected.\n\n## First Practical Win\n\nChoose the shortest path that matches what you want to confirm first:\n\n| I want to... | Run this first | What I get |\n| --- | --- | --- |\n| produce one canonical run | `just setup \u0026\u0026 just run` | a new run directory under `.runtime-cache/artifacts/runs/\u003crunId\u003e/` with manifest and proof reports |\n| know what good evidence should look like | [docs/reference/run-evidence-example.md](docs/reference/run-evidence-example.md) | the concrete report shape you should expect from a healthy run |\n| follow the guided operator path | [docs/getting-started/human-first-10-min.md](docs/getting-started/human-first-10-min.md) | the shortest human-readable route from fresh checkout to inspectable proof |\n\n## 15-Minute Evaluation Path\n\nIf you are seeing ProofTrail for the first time, keep the first pass simple:\n\n1. run `just setup`\n2. run `just run`\n3. inspect the resulting bundle under `.runtime-cache/artifacts/runs/\u003crunId\u003e/`\n4. use the command center for the deeper follow-up:\n   - `Quick Launch` to repeat the canonical path\n   - `Task Center` to confirm the result and inspect retained evidence\n   - `Recovery Center` inside `Task Center` before raw logs or replay\n   - `Flow Workshop` only after you already have one clear result\n\nTreat helper and workshop commands like the advanced bench. Keep them available,\nbut do not use them as the default first step.\n\nThe evaluator path for a first pass is intentionally short:\n\n1. run the canonical flow\n2. confirm the visible result in Task Center\n3. inspect the retained evidence bundle\n4. use Recovery Center before raw logs or shell fallbacks\n5. only then open sharing, compare, or deeper workshop tools\n\nIf you are evaluating through the local command center instead of only the CLI,\nuse the same story in product form:\n\n1. **Quick Launch**: start the canonical run first\n2. **Task Center**: confirm the result and inspect the evidence state first\n3. **Recovery Center**: use the recovery layer inside Task Center before raw logs\n   or workshop replay\n4. **Flow Workshop**: refine drafts or replay steps only after the first result\n   already exists\n\n## What This Repo Actually Does\n\nHow do we make browser automation reproducible, inspectable, and recoverable?\n\nProofTrail gives you one public mainline for running a workflow, one evidence\nbundle for understanding what happened, and one shared repo for the backend,\nweb command center, automation runner, and MCP adapter that support that flow.\n\nThink of the product in two layers:\n\n- **Primary layer**: canonical run, evidence, recovery\n- **Secondary layer**: template reuse, compare, studio tuning, AI\n  reconstruction, MCP integration\n\nThe canonical public mainline is:\n\n1. run `just setup`\n2. run `just run`\n3. inspect `.runtime-cache/artifacts/runs/\u003crunId\u003e/`\n\n`just run` is the canonical public mainline wrapper for `pnpm uiq run --profile pr --target web.local`.\n\n`just run-legacy` remains available for lower-level workshop troubleshooting,\nbut it is not the canonical public mainline.\n\n## Why Teams Use It\n\n- **Fewer mystery failures**: every canonical run writes a manifest-anchored\n  evidence bundle with summary, index, and proof reports instead of leaving\n  you with scattered logs and screenshots.\n- **Easier recovery**: the web command center, run records, and flow workshop\n  are built to help you inspect, replay, and repair workflows after something\n  breaks.\n- **One repo, one story**: backend orchestration, operator UI, automation\n  runner, and release proof surfaces live together, so docs and runtime truth\n  can stay aligned.\n\n## Quickstart\n\nRequirements:\n\n- Python 3.11+\n- Node.js 20+\n- `pnpm`\n- `uv`\n- `just`\n\n1. Install dependencies and local tooling.\n\n```bash\njust setup\n```\n\n2. Run the canonical workflow.\n\n```bash\njust run\n```\n\n3. Inspect the resulting evidence bundle.\n\n```bash\nls .runtime-cache/artifacts/runs\n```\n\nWhat good looks like:\n\n- a new run directory appears under `.runtime-cache/artifacts/runs/\u003crunId\u003e/`\n- the run contains `manifest.json`, `reports/summary.json`,\n  `reports/diagnostics.index.json`, `reports/log-index.json`,\n  `reports/proof.coverage.json`, `reports/proof.stability.json`,\n  `reports/proof.gaps.json`, and `reports/proof.repro.json`\n- `manifest.json` points back to those proof artifacts through both\n  `manifest.proof` and `manifest.reports`\n- the same orchestrator-first chain is reachable through `pnpm uiq run --profile pr --target web.local`\n- even when the PR gate fails, `reports/summary.json` still tells you why\n  instead of leaving you with a silent shell failure\n\nIf `just run` fails, start with the\n[human-first 10 minute guide](docs/getting-started/human-first-10-min.md) and\nthe [run evidence example](docs/reference/run-evidence-example.md) before\ndropping to legacy helper paths.\n\nIf `just run` succeeds, the next stop is Task Center: confirm the result, read\nthe evidence summary, and only then move into explain/share/recovery paths.\n\nIf you are already in the Web command center, keep the same order:\n\n1. start from **Quick Launch**\n2. move to **Task Center** to confirm the result and inspect evidence\n3. use **Recovery Center** before diving into raw logs\n4. open **Flow Workshop** only when you intentionally need the advanced draft\n   or replay surfaces\n\n## After The First Successful Run\n\nOnce one canonical or operator-supported result already exists, the next value\nlayer is no longer \"how do I start?\" It becomes \"how do I reuse, compare,\noperate, and hand this off without losing trust?\"\n\nUse the product surfaces in this order:\n\n1. **Template reuse / readiness** in **Flow Workshop**\n   - Ask: \"Is this flow stable enough to reuse, or should it stay in workshop mode?\"\n   - Treat readiness as a reuse verdict, not as a vanity score.\n2. **Compare** in **Task Center**\n   - Ask: \"How does this retained run differ from a baseline run?\"\n   - Use compare to judge change, not to replace the canonical evidence bundle.\n3. **Profile / Target Studio**\n   - Ask: \"Which knobs are safe to tune, and what validation runs when I save?\"\n   - Studio is a guarded operator surface, not a raw YAML editor.\n4. **AI reconstruction**\n   - Ask: \"Do I need help rebuilding a flow from artifacts?\"\n   - Use it only after artifacts already exist; it is an optional advanced helper.\n5. **MCP**\n   - Ask: \"Do I need an external AI client to inspect runs or operate this repo safely?\"\n   - Treat it as an integration side road, not as a replacement for `just run`.\n6. **Review Workspace**\n   - Ask: \"Do I need one review-ready packet before I hand this run to another maintainer?\"\n   - Treat it as a local-first review packet, not as a hosted collaboration product.\n7. **Template Exchange**\n   - Ask: \"Do I need to move a reusable template contract into another checkout?\"\n   - Use import/export/share for that handoff, not a marketplace mental model.\n\nWave 5 also makes the recovery boundary more explicit:\n\n- `inspect_task`-style actions are safe to suggest immediately\n- replay actions stay human-confirmed\n- OTP, provider-step, and manual-input actions stay manual-only\n\n## Outward Product Story\n\nUse this mental model when you explain ProofTrail to a new evaluator:\n\n- **What it is**: evidence-first browser automation with recovery and MCP\n- **Who it helps**: AI agents and human operators who need trustworthy browser workflows\n- **Why it feels different**: the product does not stop at “the automation ran”; it keeps the evidence, recovery path, and handoff surfaces attached to the run\n- **Where AI fits**: AI reconstruction helps after artifacts already exist\n- **Where MCP fits**: MCP exposes the same governed surfaces to external AI clients\n\n## Suitable / Not Suitable\n\nSuitable for:\n\n- teams standardizing browser automation runs across operators and environments\n- maintainers who need inspectable evidence instead of ad-hoc shell output\n- workflows where replay, diagnostics, and recovery matter as much as first-run success\n\nNot suitable for:\n\n- tiny one-off browser scripts where no shared evidence or recovery path is needed\n- teams unwilling to maintain a Python + Node workspace\n- people looking for a hosted SaaS with zero local setup\n\n## Validation and Governance\n\nProofTrail keeps the public story honest by separating runtime proof from\ngovernance checks.\n\n- [Minimal success case](docs/showcase/minimal-success-case.md)\n- [Run evidence example](docs/reference/run-evidence-example.md)\n- [Quality gates](docs/quality-gates.md)\n- [Changelog](CHANGELOG.md)\n- [Release guide](docs/release/README.md)\n- [Release supply-chain policy](docs/reference/release-supply-chain-policy.md)\n- Maintainer GitHub closure evidence: `just github-closure-report`\n\nPublic collaboration contract:\n\n- external pull requests stay on GitHub-hosted, low-risk governance and build lanes\n- live, external, and owner-secret workflows are manual-only and require the protected `owner-approved-sensitive` environment\n- macOS-only smoke and regression lanes use GitHub-hosted `macos-latest`; `self-hosted` / `shared-pool` are not part of the public collaboration contract\n\n## Maintainer Space Hygiene\n\nProofTrail treats disk cleanup as a governed maintenance path, not an ad-hoc\n\"delete the biggest folder\" exercise.\n\n- `just space-report` emits a repo-exclusive JSON report for runtime buckets,\n  `safe-clean` residue, explicit `reclaim` candidates, protected totals, and the\n  dedicated external pnpm layer\n- `just space-clean-safe` runs a default **dry-run** for the low-risk cleanup\n  wave; use `./scripts/space-clean-safe.py --apply` only when you want to\n  execute the same safe-clean list\n- `just space-clean-reclaim` runs a default **dry-run** for large\n  repo-exclusive reclaim targets such as the root `.venv`, isolated\n  `node_modules`, and the repo-scoped pnpm store; use explicit `--scope ...`\n  plus `--apply` only after the matching validation gate passes\n- `just runtime-gc -- --dry-run` previews retention-based cleanup for the\n  review-class runtime buckets before you let the same policy delete old files\n- canonical run evidence under `.runtime-cache/artifacts/runs/`, runtime\n  backups under `.runtime-cache/backups/`, and managed toolchains under\n  `.runtime-cache/toolchains/` are intentionally outside the first cleanup wave\n- empty run stub directories under `.runtime-cache/artifacts/runs/` are the\n  one explicit exception: they may enter the first safe-clean wave only when\n  they are still empty and have no evidence files yet\n- the canonical Python runtime target is `.runtime-cache/toolchains/python/.venv`;\n  the root `.venv` is a retired legacy surface and may only be reclaimed\n  through `space-clean-reclaim --scope root-venv` after single-track validation\n\n## FAQ\n\n### Do I need the legacy helper path?\n\nNo. `just run` is the public default road. `just run-legacy` is only for\nlower-level workshop troubleshooting when you need to inspect helper-path\nbehavior directly.\n\n### Where should I look after a run finishes?\n\nStart with `.runtime-cache/artifacts/runs/\u003crunId\u003e/manifest.json`, then open\n`reports/summary.json`, the four `reports/proof.*.json` files, and the index\nfiles described in\n[docs/reference/run-evidence-example.md](docs/reference/run-evidence-example.md).\n\nIf you are using the local command center, the matching product path is:\n\n1. open **Task Center**\n2. inspect the evidence state first: `retained`, `partial`, `missing`, or `empty`\n3. use **Failure Explainer** to understand the current run\n4. use **Share Pack** when you want a handoff-friendly summary\n5. use **Compare** when you need a baseline-versus-candidate judgment\n6. treat **Promotion Candidate** as a later release/showcase decision, not as the\n   first diagnostic step\n\n### Is this repository already a full docs site?\n\nNot yet. Today the GitHub README is the conversion page, and the docs surface is\nthe supporting second layer. See [docs/index.md](docs/index.md) for the current\npublic docs map.\n\n## Repository Map\n\n- `apps/api/` - backend API and orchestration services\n- `apps/web/` - operator-facing web command center\n- `apps/automation-runner/` - record, replay, and reconstruction pipeline\n- `apps/mcp-server/` - MCP adapter\n- `packages/` - shared orchestration and runtime packages\n- `configs/` - environment, schema, and governance configuration\n- `contracts/` - API contracts\n- `scripts/` - repo entrypoints and CI helpers\n- `docs/` - storefront-supporting public docs surface\n\n## Documentation\n\n- Docs map: [docs/index.md](docs/index.md)\n- Public docs overview: [docs/README.md](docs/README.md)\n- Architecture contract: [docs/architecture.md](docs/architecture.md)\n- CLI guide: [docs/cli.md](docs/cli.md)\n- [docs/localized/zh-CN/README.md](docs/localized/zh-CN/README.md)\n\n## Security and Contribution\n\n- [SECURITY.md](SECURITY.md)\n- [SUPPORT.md](SUPPORT.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n\n## License\n\nThis repository is released under the [MIT License](LICENSE).\n\nIf ProofTrail saves you time during evaluation or implementation, star the repo\nso you can find the updates, release notes, and new evidence examples later.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaojiou176-open%2Fprooftrail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiaojiou176-open%2Fprooftrail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaojiou176-open%2Fprooftrail/lists"}