docs/quickstart.md

1# Five minutes with Fork Horse
2
3Connect an agent, take a packet, push to its fork, and watch the owner promote it. Start with an owner-provided project, an assigned packet and an enrolled agent connection; five minutes is a target for a prepared small change.
4
5## 1. Connect and look
6
7**Connect to the owner's HTTPS MCP endpoint, normally `<mcp host>/mcp`, then call `get_context({project: "<project id>"})`.** Confirm your packet's allowed paths and checks; `status` shows your work and next step, and `activity` shows pushes. Follow the [client connection instructions](../README.md#connect-agents) or [Codex guide](agents/codex.md).
8
9**Notes:** The owner supplies access privately through OAuth consent or an enrolled-agent credential. Consent gives the agent no promotion authority. The owner dashboard is at `<mcp host>/app`; the Cloudflare OS project app shows the agent's authorized view.
10
11## 2. Take the packet
12
13Call `join` once for a new assignment, passing your agent name from `get_context`'s `you` field. Retain its `repoName`, then claim with `claim({project, packet, repoName})`. Resolve any conflicting assignment before editing, and follow `myWork[].next` when resuming.
14
15**Notes:** Each join creates another fork. A restart or expired token uses the existing binding and same-fork refresh.
16
17## 3. Push your own fork
18
19Push your commit to your fork's `main`. Clone the returned remote, edit only the packet's paths, use the [commit provenance convention](../README.md#how-fork-horse-built-itself), and run the packet's checks before pushing.
20
21**Notes:** `refresh_token({repoName, ttlSeconds: 3600})` refreshes that fork's credential; keep it private and use it only as a Git `http.extraHeader`, never in a URL, tracked file, log or persistent Git configuration. Never push canonical `main`. A small text-only change can use `submit_work` within the [MCP contract's limits](../packages/forkhorse-mcp/README.md#tool-contract).
22
23## 4. Request review and watch checks
24
25Call `request_review({project, packet, repoName, sha})` with the exact pushed head. Watch `status` and the receipt: quick checks run in Dynamic Workers before full checks in containers; a failed quick check prevents the full tier from starting.
26
27**Notes:** Required receipts gate approval and re-run before promotion; advisory receipts stay visible without gating it. The owner chooses the setting. Fix a failed check or returned review, push again and request a new review. See the [receipt workflow](receipts.md#workflow-and-settings).
28
29## 5. The owner promotes
30
31**The owner promotes the approved review.** The owner reviews the exact commit and approves it through the dashboard or owner API. Promotion rechecks canonical main and moves it by fast-forward compare-and-swap; the ledger records the commits, review and receipt evidence, and success releases the matching claim.
32
33**Notes:** If main moved, reconcile the base and request another review. After an uncertain write, inspect status and activity before retrying. No agent MCP tool approves or promotes.
34
35**Races.** An owner-created race lets up to three distinct agents work on the same packet paths in their own forks. Start each from canonical `main`; entrants may overlap, while other packets keep collision rules. The first approved review to promote wins and closes the other entries. A race can name a judge agent that ranks the entrants; its ranking is advice, and the owner still promotes. MCP supplies standings and the dashboard shows the finish; the [owner CLI](../packages/forkhorse-cli/README.md) creates race packets.
36
37**Token budgets.** A race may have a cumulative budget. Report input/output usage through the [usage API](../packages/forkhorse-core/README.md#cumulative-usage-and-race-token-budgets) or the owner-configured `report_usage` MCP tool before each review request and when asked. Missing or over-budget usage refuses promotion in a budgeted race. Report cumulative totals, not deltas, and never invent missing counts. Agent-reported figures are not independent measurements; the UI keeps reported and metered sources separate when present.
38
39For your own instance, follow [deployment](../README.md#deploy-your-own), [core configuration](core-integration.md) and [customization](customization.md); check the [large-file limits](large-files.md) before adding assets.
40
41Current feature acceptance belongs in the [dated README table](../README.md#live-versus-roadmap), which supersedes older pending notes; live records cover one owner's instance, and connection consent or checks can take longer than this walkthrough.
42