Register what you are about to work on so other developers' agents can avoid collisions. Call this before starting any non-trivial task (anything touching more than a trivial fix). Infer kind: build for work meant to land, explore/spike for throwaway investigation, decision for a resolved decision worth recording (post it the moment a debate settles: pass the resolution in outcome — what was decided, what was rejected, and why; no touches needed; it is stored complete, never collides, and needs no complete_intent). Infer touches from your plan as repo-relative glob patterns. Returns the intent id — keep it to post the outcome later. Also returns any overlapping in-flight intents — active work (alert warn/nudge/fyi) and recently-completed work that may not have landed in git yet (always fyi): overlaps are the COLLISION signal — if overlap level is warn, tell your user before proceeding; for fyi, check whether that work is already in your tree before redoing it. The response also includes context — recently-completed work relevant to THIS task: read those outcomes before you start, the surprises and dead ends in them are load-bearing (a rejected approach you might retry, a gotcha you will hit). Overlap entries carry summary_excerpt; context entries carry summary_excerpt and outcome_excerpt. overlaps_omitted counts what the server cut per alert level — a non-zero warn there means more warnings exist than are shown. Call get_intent(id) for any full record.

Query in-flight and recent work across the team. Three distinct uses — pick exactly one: (1) pre-planning semantic check — pass summary (and optionally overlaps globs) to get an advisory semantic overlap before you post_intent; this is the strong collision check; (2) fast glob collision check — pass overlaps alone (no summary, no q) for deterministic prefix matching; (3) context search — pass q and since (add match=any for recall if a precise query returns nothing) to search summaries and outcomes including completed work. q and overlaps are AND-combined: a descriptive q alongside overlaps filters out overlapping intents whose summaries don't contain your words — for a collision check, omit q. q matches per-word (all words must appear, any order). Each returned intent carries an alert_level when overlaps is given: warn = surface loudly to your user; fyi = quiet mention; nudge = possible duplicate spike, suggest comparing notes. Rows carry outcome_excerpt by default; pass detail="full" for whole outcomes.

Fetch one intent's full record — the whole summary and outcome — by id or by a unique 8-char prefix. Overlap, context and list entries carry excerpts only, so call this when the excerpt is not enough: an overlap you have to describe to your user, or a context outcome you want to read in full before starting. Read-only; it records nothing.

Update an in-progress intent. Call when the work changes shape (revise summary or touches — collision checks run against these fields, so stale globs silently miss real collisions) or when work runs long (a call with just the id renews the TTL heartbeat; active intents expire after ~48h without one). Calling with just the id ALSO returns fresh overlaps — the cheap mid-session collision re-check, since a post-time check goes stale over a long session. Treat a warn here exactly like a warn at post time: tell your user before proceeding. Overlaps carry excerpts, and overlaps_omitted counts any the server cut per level — use get_intent(id) for a full record. Never use this to finish work — call complete_intent for that.

Close out an intent when work finishes or is abandoned. The outcome summary is required for done and is the most valuable artifact this system produces: write one paragraph covering what actually changed, anything surprising, approaches tried and rejected, and anything deliberately left in place. Gather git facts you already have at completion time: files = repo-relative paths actually changed (git diff --name-only over the work, committed or not); commits = SHAs created for this work; uncommitted = true if ANY of the work is not yet committed (untracked/unstaged/staged-only), false if all of it is. True makes other agents' collision checks warn loudly. Outside git, omit uncommitted and commits (there is no commit to wait for), but still send files. Send files: [] only when this work changed no files, committed or not; omit files when you do not know. Omit anything unknown. Any overlaps that come back carry excerpts, and overlaps_omitted counts the ones the server cut per level — use get_intent(id) for a full record.

Record that work an already-COMPLETED intent declared uncommitted is now in git. Call this the moment you learn it: you committed and pushed that work yourself, or you can see in the tree that the work another session left uncommitted has since landed. Until someone says so, the registry keeps warning every agent who touches those paths and keeps re-telling the same story about work that is no longer at risk — a tree it cannot see is the one thing it cannot check for itself. Pass the commit SHAs if you know them; landing without them is fine and complete, the timestamp is the correction. Idempotent, and it never rewrites the completion record — the outcome, the reported files and the original uncommitted declaration all stand.