{"slug":"oip-cookbook","title":"The OIP cookbook — the exact curl for everything","body":"## What this article is\n\nEvery common operation on the build as one copy-paste command. No guessing, no asking a model what to type. Commands marked OWNER need the terminal key header. Commands marked TOKEN need a capability link. Everything else is public.\n\n## Step zero — get a token (OWNER, do this once)\n\n```\ncurl -H 'x-terminal-key: <KEY>' 'https://miscsubjects.com/api/dispatch?mint_share=1&scope=act'\n```\n\nThe response contains `share_token`. Everywhere below, `<TOKEN>` means that value. For a safer handout, mint a one-object token instead: `&scope=row&key=NOW&ttl=600&uses=3`.\n\n## Read (public — no credentials)\n\n```\n# what is this whole thing\ncurl 'https://miscsubjects.com/api/dispatch?orient=1&format=markdown'\n# the full capability tree\ncurl 'https://miscsubjects.com/api/dispatch?map=1&format=markdown'\n# one object's contract\ncurl 'https://miscsubjects.com/api/dispatch?key=SEND_BY_CHANNEL&format=markdown'\n# find the right object from plain words\ncurl 'https://miscsubjects.com/api/dispatch?ask=text+cyrus+hello'\n# prove it is a protocol\ncurl 'https://miscsubjects.com/api/dispatch?conformance=1&format=markdown'\n# the design objections, pre-answered\ncurl 'https://miscsubjects.com/api/dispatch?why=1&format=markdown'\n```\n\n## Act (TOKEN)\n\n```\n# no-op heartbeat — proves your token works\ncurl 'https://miscsubjects.com/api/dispatch?ping=1&share=<TOKEN>'\n# text Cyrus\ncurl 'https://miscsubjects.com/api/dispatch?invoke=SEND_BY_CHANNEL&body=blooio|%2B14155480666|Hello&share=<TOKEN>'\n# generate an image\ncurl 'https://miscsubjects.com/api/dispatch?invoke=GROK_IMAGE&body=a+red+fox&share=<TOKEN>'\n# run a shell command on the Mac\ncurl 'https://miscsubjects.com/api/dispatch?invoke=LOCAL_EXEC&body=uptime&share=<TOKEN>'\n```\n\n## Verify (TOKEN)\n\n```\n# full forensic receipt for any invocation\ncurl 'https://miscsubjects.com/api/dispatch?receipt=inv_ID&share=<TOKEN>'\n# public one-line confirmation (no token needed)\ncurl 'https://miscsubjects.com/api/dispatch?confirm=inv_ID'\n```\n\n## Replay and repair (OWNER or act token)\n\n```\n# re-run a recorded invocation\ncurl -X POST https://miscsubjects.com/api/dispatch -H 'x-terminal-key: <KEY>' -d '{\"replay\":\"inv_ID\"}'\n# run a corrected call linked to the failure it fixes\ncurl -X POST https://miscsubjects.com/api/dispatch -H 'x-terminal-key: <KEY>' -d '{\"key\":\"NOW\",\"body\":\"\",\"repairs\":\"inv_FAILED\"}'\n```\n\n## The article system (OWNER)\n\n```\n# list articles\ncurl 'https://miscsubjects.com/api/articles?slim=1&limit=40'\n# read one article's machine bundle\ncurl 'https://miscsubjects.com/api/articles/oip/bundle?format=markdown'\n# seed the clarity-review cycle across all OIP articles\ncurl -X POST https://miscsubjects.com/api/protocol/oip-seed -H 'x-terminal-key: <KEY>' -d '{}'\n# run one loop tick by hand (cron does this every minute)\ncurl -X POST 'https://miscsubjects.com/api/protocol/run?role=oip-review' -H 'x-terminal-key: <KEY>'\n# have a model write a missing article\ncurl -X POST https://miscsubjects.com/api/protocol/oip-write -H 'x-terminal-key: <KEY>' -d '{\"slug\":\"oip-example\",\"title\":\"Example\"}'\n# have a model revise a failing article\ncurl -X POST https://miscsubjects.com/api/protocol/oip-revise -H 'x-terminal-key: <KEY>' -d '{\"slug\":\"oip-example\"}'\n```\n\n## Token management (OWNER)\n\n```\n# explain any token — what it can do, uses left, expiry\ncurl 'https://miscsubjects.com/api/dispatch?explain=1&share=<TOKEN>'\n# revoke a capability instantly\ncurl -H 'x-terminal-key: <KEY>' 'https://miscsubjects.com/api/dispatch?revoke=cap_FINGERPRINT'\n```\n## Latest clarity reviews (live)\n\nFresh models are sent this article's bundle and asked two separate questions: how clear is the machine JSON, and how clear is the English body. Scores are 0 to 10. The full history is in the append-only ledger.\n\n- 2026-07-03 02:18 · model `gemini/gemini-2.5-flash` · NEEDS WORK · JSON 9/10 · English 9/10 · zero-context human 7/10\n- 2026-07-03 02:17 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 7/10\n  - gaps named: MCP comparison; OIP vs MCP; Detailed explanation of Tap & Go\n\nHow the loop self-corrects: a failing review queues a model revision of this article (a new append-only version). A missing concept named by a reviewer queues a brand-new machine-written article, which then enters the same review cycle.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","primer"],"style":{"accent":"#16324f","measure":860},"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"prov":{"model":"system/oip_articles","action":"generate"}}