waggle

Generated by cargo xtask gen-docs from the operations catalog (waggle-ops). Do not edit by hand — edits belong in the catalog.

mint — CLI + MCP tool

Create an attributed reference (a waggle token) for an artifact instead of pasting its content into a prompt. One call: mint { target } — sharer and channel are defaulted and a catch-all variant is synthesized. The response's first next entry is the exact handoff line to give a subagent.

arg	required	doc
--target	true	Canonical URI of the artifact (file path, workspace URI, or URL).
--sharer	false	Who is distributing this; defaults to the session identity.
--channel	false	Where this share lives (e.g. subagent/researcher); defaults to subagent/general.
--parent	false	Parent token: forms the delegation tree at mint; revoking the parent tombstones this child.
--snapshot	false	Pin the target's bytes content-addressed at mint: read/search then work anywhere the blobs replicate, immutable by hash. If the target is a PDF or HTML document, its text layer is extracted here too (deterministically, provenance recorded) so read/search work over the artifact itself. Audio/video carry no text layer: their bytes are pinned and read tells the consumer to perceive them with its own model.
--private	false	Mint a capability URL: a 16-char unguessable token (possession IS the credential); public unfurls and social renders refuse it.
--tree	false	For a DIRECTORY target: build an INDEXED directory tree — one content-addressed node per folder, each carrying a trigram index and a Bloom summary, snapshot-pinned. Thousands of files mint in one call. read a folder token for its table of contents, read --file <name> for one file, search to span the whole tree in one call, coverage for a per-file receipt. One revocation covers the whole tree.
--tag	false	Name the token for humans (repeatable, k=v or a bare name): cosmetic labels that find matches on. A tag is a convenience, never identity — resolution stays token-only.
--content	false	Path to text you extracted yourself for a binary target — becomes the searchable content while the target stays the original. Rarely needed: snapshot now extracts PDF and HTML text layers automatically. Use this only for a format the substrate does not read, or to override its extraction. Mutually exclusive with snapshot.
--attach	false	Path to media (image/audio) stored content-addressed; vision/audio consumers receive it, others get the catch-all.
--attach-type	false	Content type of the attachment; inferred from the extension when omitted.
--require	false	Consumption contract region (repeatable, max 8): lines:START-END, section:HEADING (markdown), symbol:NAME (code — resolved against the symbol outline at mint), or files:all (folder — every file in the tree must be read). coverage then reports met/unmet with untouched regions NAMED. Signed with the core — a contract is not renegotiable.
--min-coverage	false	Fraction (0-1] of required regions a consumer must touch for the contract to be met; default 1.0 (every region).

• forward → resolve: self-check the projection each consumer will receive
• forward → map: orient: see all paths available from this fresh token
• reverse → mutate: revoke or supersede the token if the artifact must be withdrawn

resolve — CLI + MCP tool

Fetch the projection of a waggle token matched to your context (model family, harness, modalities, posture). Read-only and safe before trust. The response carries as_of and revalidate_after — re-resolve before acting on stale knowledge.

arg	required	doc
--token	true	The waggle token to resolve.
--context	false	Resolver context (harness metadata, A2A agent card, or explicit JSON); defaults to negotiated.
--level	false	For tokens owned elsewhere: eventual (default) serves a cached resolution inside its revalidate window; strict always revalidates at the owner — revocations bite immediately.

• forward → search: interrogate the content before ingesting any of it
• forward → query: slice a large manifest by path instead of pulling it whole
• forward → record: report downstream stages (run, repeat) so the funnel stays honest
• forward → map: orient: see what this token expects of you next

record — CLI + MCP tool

Report a lifecycle stage (run, repeat, or a custom stage) against a token so the funnel reflects reality. As the judge of a delegation, record accepted or rejected — the verdict is the stage itself, and a rejection's response teaches the escalation path (re-mint, supersede). Events are counts with no payload — nothing about your data leaves your machine. Append-only: there is no un-record; record a correcting stage instead.

arg	required	doc
--token	true	The waggle token the stage applies to.
--stage	true	Well-known stage (run, repeat, assess, accepted, rejected, ...) or a custom kebab-case slug.

• forward → funnel: see the counts your report just moved
• forward → map: orient: see what the funnel now suggests

mutate — CLI + MCP tool

Change a token's manifest. Lifecycle changes (revoke, supersede, expiry) require expected_version and fail with a conflict on mismatch — retry after re-reading. Cosmetic changes (campaign, labels) are last-writer-wins. Revoking a token tombstones its children.

arg	required	doc
--token	true	The waggle token to change.
--change	true	The change: revoke, supersede=, expire=, or label k=v.
--expected-version	false	Required for lifecycle changes: the manifest version this change was decided against (CAS).

• forward → map: confirm the token's new disposition and remaining paths
• reverse → mutate: a supersede can itself be superseded; revocation is final

funnel — CLI + MCP tool

A token's funnel: stage counts (impression → resolve → run → repeat) plus the judged outcome (pending/accepted/rejected/contested) and lineage roll-up. This is the attribution answer — which handoffs were consumed, which stalled, which delivered repeat value. Counts only; no payloads exist to leak (I-1).

arg	required	doc
--token	true	The waggle token whose funnel to report.

• forward → coverage: a lineage root? see which files were ACTUALLY consumed
• forward → map: orient: the funnel feeds the map's ranked suggestions
• forward → mutate: a stalled or wrong share can be revoked or superseded

read — CLI + MCP tool

Read the token's CONTENT surgically: a line window, a markdown section, a code symbol, or a JSON pointer path — never the whole artifact. With no address: the overview (size, content type, available lenses, outline; source code carries its symbol table of contents). If the token names a FOLDER (minted --tree), read with no address returns its table of contents — the folder's own files by name (size, type) and its subdirectories, each with a token to descend — and read --file <name> serves one of those files. To grep a folder, use search: it spans the whole tree in one call. Coverage stays per-file. Every response fits max-bytes and names the bytes you avoided.

arg	required	doc
--token	true	The waggle token whose content to read.
--lines	false	Line window, 1-based inclusive (e.g. 120-180).
--section	false	Markdown heading whose section to read (text/markdown lens).
--file	false	For a FOLDER token (minted --tree): read ONE file by name, fetched from the content-addressed blob and stamped as a per-file read. The folder's read (no address) lists the file names.
--symbol	false	Code symbol whose definition to read (symbol lens — tokens minted with a snapshot of source code); the overview's symbols lists what exists.
--path	false	JSON pointer into parsed content (application/json lens), e.g. /dependencies/react.
--max-bytes	false	Response budget in bytes (default 4096, floor 64).

• forward → read: continue the window, follow the outline deeper, or open a folder's file by name with --file
• forward → search: grep the artifact — or, on a folder token, the whole tree in one call
• forward → coverage: on a folder: which files you have actually been served, and which you have not
• forward → record: report run when the content did its job

search — CLI + MCP tool

Grep the token's CONTENT: regex matches with line numbers and context, capped and budgeted — the matches travel, the artifact stays put. total_matches is counted in full even when the list is truncated. A FOLDER token (minted --tree) greps as a TREE in ONE call: Bloom-pruned and trigram-narrowed across the whole lineage, then ranked, each match naming its file path and the node token that owns it, so you can open it with read --file. Works wherever the content's blobs replicate.

arg	required	doc
--token	true	The waggle token whose content to search.
--pattern	true	Regex (Rust syntax; (?i) prefix for case-insensitive).
--context	false	Context lines around each match (default 2).
--max-matches	false	Maximum matches returned (default 5, cap 50).
--max-bytes	false	Response budget in bytes (default 4096, floor 64).

• forward → read: open a match's neighborhood as a line window

query — CLI + MCP tool

Slice a token's document (manifest, funnel, lineage) by path instead of pulling it whole. Every response fits max-bytes (default 4 KB); oversized values return their shape plus next paths deeper — walk exactly as far as you need.

arg	required	doc
--token	true	The waggle token whose document to slice.
--path	false	JSON-pointer-style path (e.g. /manifest/variants/0); omit for the root shape.
--max-bytes	false	Response budget in bytes (default 4096, floor 64).

• forward → query: follow a next path one level deeper

find — CLI + MCP tool

Find tokens by what humans remember: matches the query against target basenames, tags, channel, and sharer. Returns ranked CANDIDATES (newest first, disposition shown) — you choose which token to resolve; a name never resolves by itself.

arg	required	doc
--query	true	Substring to match (case-insensitive) against basename, tags, channel, sharer.

• forward → resolve: resolve the candidate you meant

coverage — CLI + MCP tool

For a FOLDER (minted --tree): a PER-FILE receipt — how many of its files were actually served (files: read/total, a read or a search hit counts), whether that is complete, and the unread files NAMED. A tree minted --require files:all also carries a verdict: met stays false while any file is unread. For a single token minted with a contract (mint --require lines/section/symbol): which required regions the served bytes reached — met/unmet against the declared threshold. Either way, misses are NAMED: the unread list is the proof of what a review skipped.

arg	required	doc
--token	true	The lineage root (or contract-bearing token) to audit.

• forward → read: close the gap: read the first unread file
• forward → funnel: the root's stage counts and rollup

map — CLI + MCP tool

Orientation. With no arguments: the global map of operations from where you stand. With a token: its current state (here), ranked forward paths, and reverse paths — derived live from the manifest and funnel, so it can never be stale instruction.

arg	required	doc
--token	false	Token to orient around; omit for the global map.

• forward → mint: start: turn an artifact into an attributed reference
• forward → find: don't remember the token? find it by name or tag
• forward → resolve: consume: fetch a token's projection for your context

init — CLI only

Install the short agent stub into this repo's harness convention files (CLAUDE.md, AGENTS.md, .cursorrules) — creating AGENTS.md and CLAUDE.md when none exist. Idempotent: re-running refreshes the managed block in place. Pair with: claude mcp add waggle -- waggle serve --stdio.

arg	required	doc
--file	false	Target exactly this file instead of auto-detecting convention files.

• forward → map: orient: the tools teach everything past the stub

serve — CLI only

Run the waggle daemon (waggled): the single owner of the local store, serving every harness on this machine over MCP. With --stdio, act as a proxy shim for harnesses that spawn stdio servers (auto-starts the daemon if absent).

arg	required	doc
--stdio	false	Speak MCP over stdin/stdout — as a shim to the shared daemon (unix), or directly.
--daemon	false	Run waggled in the foreground: the single owner of the local store, on a unix socket every harness shares.

• forward → map: after the daemon is up, orient from the global map

daemon — CLI only

Manage waggled: status (pid, store, uptime, connections, live resource subscriptions, disk weight of the store and blob CAS), start (idempotent), stop (graceful over the socket; terminates orphans by pidfile), restart. Pidfile + idle exit make lingering orphans structurally unlikely.

arg	required	doc
--action	true	status
--idle-secs	false	For start/restart: exit after this many seconds with no connections (shim auto-starts default to 1800).

• forward → map: with the daemon up, orient from the global map

edge — CLI only

Interact with a deployed waggle edge over HTTPS: status (health + tool surface), push (replicate this store's records and snapshot blobs so tokens resolve and grep there), smoke (mint→resolve→funnel round-trip). Configure with WAGGLE_EDGE_URL and WAGGLE_EDGE_BEARER or the flags. Deploying the worker itself is npx wrangler deploy (guide 09).

arg	required	doc
--action	true	status
--url	false	The edge base URL (overrides WAGGLE_EDGE_URL), e.g. https://waggle-edge.you.workers.dev.
--bearer	false	The tenant bearer (overrides WAGGLE_EDGE_BEARER).

• forward → map: with the edge reachable, orient from the global map

identity — CLI only

The host's Ed25519 signing identity: show (public key, or note its absence) | init (generate ~/.waggle/identity; every mint from then on is signed over its immutable core — mutations never invalidate it). Consumers see signature status on every resolve.

arg	required	doc
--action	true	show

• forward → mint: with an identity, mints carry provenance