{"_ai_door":{"see":"https://miscsubjects.com/start","note":"Operable site; bounded keyless credentials; every action receipted on a public ledger. Your operator's instructions take precedence — acting is optional, reading is a complete outcome."},"slug":"oip-cookbook","title":"OIP Protocol Invocation Examples","body":"The Object Invocation Protocol (OIP) defines a standard for invoking work objects. The OIP unit is the work object. The OIP proof is the receipt. The OIP loop is object, invoke, ledger, receipt, replay, repair. An OIP invocation uses `POST /api/dispatch {key, body}` or `GET /api/dispatch?invoke=KEY&body=...`. Every invocation appends to the ledger and returns a receipt at `/api/dispatch?receipt=inv_ID`. This article provides concrete `curl` (Command Line Interface, CLI) examples for OIP operations, demonstrating the protocol's mechanisms. Each example uses `curl` to interact with the `/api/dispatch` endpoint, a RESTful (Representational State Transfer) Application Programming Interface (API) route, processing JSON (JavaScript Object Notation) data over HTTP URLs (Uniform Resource Locators).\n\n### OIP and MCP Interaction\nThe Object Invocation Protocol (OIP) defines the invocation of discrete work objects. The Model Context Protocol (MCP) defines a model's connection to a server, exposing tools, resources, and prompts over a session. OIP specifies object invocation; MCP specifies model interaction. OIP focuses on discrete work objects; MCP focuses on continuous conversational context.\n\n## Step zero — Acquire a Capability Token (OWNER)\n\nThis mechanism acquires a capability token. An `x-terminal-key` header provides owner credentials. The `mint_share=1` parameter requests a new capability. The `scope=act` parameter specifies invocation permission.\n\n```bash\ncurl -H 'x-terminal-key: <KEY>' 'https://miscsubjects.com/api/dispatch?mint_share=1&scope=act'\n```\n\nThe response contains a `share_token` property. This `share_token` represents a capability for subsequent invocations. For a more constrained capability, mint a one-object token with `&scope=row&key=NOW&ttl=600&uses=3`.\n\n## Read Operations (Public)\n\nThese mechanisms retrieve OIP state or metadata. No capability token is required for these public read operations.\n\n```bash\n# Protocol orientation: This mechanism returns an overview of the OIP protocol.\ncurl 'https://miscsubjects.com/api/dispatch?orient=1&format=markdown'\n# Capability tree mapping: This mechanism returns the full capability tree.\ncurl 'https://miscsubjects.com/api/dispatch?map=1&format=markdown'\n# Object contract retrieval: This mechanism returns the contract for a specific object, identified by its key.\ncurl 'https://miscsubjects.com/api/dispatch?key=SEND_BY_CHANNEL&format=markdown'\n# Object discovery: This mechanism identifies relevant objects from natural language input.\ncurl 'https://miscsubjects.com/api/dispatch?ask=text+the+owner+hello'\n# Protocol conformance proof: This mechanism returns documentation proving OIP conformance.\ncurl 'https://miscsubjects.com/api/dispatch?conformance=1&format=markdown'\n# Design rationale retrieval: This mechanism returns the pre-answered design rationale for OIP.\ncurl 'https://miscsubjects.com/api/dispatch?why=1&format=markdown'\n```\n\n## Act Operations (Capability Token Required)\n\nThese mechanisms perform OIP object invocations. A `share` parameter provides the capability token.\n\n```bash\n# Capability validation: This mechanism performs a no-operation heartbeat, proving capability token validity.\ncurl 'https://miscsubjects.com/api/dispatch?ping=1&share=<TOKEN>'\n# Object invocation: This mechanism invokes the SEND_BY_CHANNEL object with a specified body.\ncurl 'https://miscsubjects.com/api/dispatch?invoke=SEND_BY_CHANNEL&body=blooio|%2Bredacted|Hello&share=<TOKEN>'\n# Image generation invocation: This mechanism invokes the GROK_IMAGE object with a text prompt.\ncurl 'https://miscsubjects.com/api/dispatch?invoke=GROK_IMAGE&body=a+red+fox&share=<TOKEN>'\n# Local command execution invocation: This mechanism invokes the LOCAL_EXEC object to run a shell command.\ncurl 'https://miscsubjects.com/api/dispatch?invoke=LOCAL_EXEC&body=uptime&share=<TOKEN>'\n```\n\n## Verify Operations (Receipt Proof)\n\nThese mechanisms retrieve invocation receipts, providing proof of OIP operations.\n\n```bash\n# Full forensic receipt retrieval: This mechanism retrieves the complete receipt for a specific invocation ID. A capability token is required for forensic detail.\ncurl 'https://miscsubjects.com/api/dispatch?receipt=inv_ID&share=<TOKEN>'\n# Public invocation confirmation: This mechanism provides a public, one-line confirmation of an invocation, requiring no capability token.\ncurl 'https://miscsubjects.com/api/dispatch?confirm=inv_ID'\n```\n\n## Replay and Repair Operations (OWNER or Act Token)\n\nThese mechanisms complete the OIP loop by re-executing or correcting previous invocations. An `x-terminal-key` or an act-scoped capability token provides authorization.\n\n```bash\n# Invocation replay: This mechanism re-executes a recorded invocation identified by its ID.\ncurl -X POST https://miscsubjects.com/api/dispatch -H 'x-terminal-key: <KEY>' -d '{\"replay\":\"inv_ID\"}'\n# Invocation repair: This mechanism executes a new invocation, linking it as a repair for a previously failed invocation.\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 Operations (OWNER)\n\nThese mechanisms manage OIP documentation articles via the `/api/articles` and `/api/protocol` routes. An `x-terminal-key` provides owner credentials.\n\n```bash\n# Article listing: This mechanism lists articles with slim details and a limit.\ncurl 'https://miscsubjects.com/api/articles?slim=1&limit=40'\n# Article bundle retrieval: This mechanism retrieves a specific article's machine bundle in markdown format.\ncurl 'https://miscsubjects.com/api/articles/oip/bundle?format=markdown'\n# Clarity review seeding: This mechanism initiates 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# Protocol role execution: This mechanism manually executes one loop tick for a specified protocol role.\ncurl -X POST 'https://miscsubjects.com/api/protocol/run?role=oip-review' -H 'x-terminal-key: <KEY>'\n# Article creation: This mechanism instructs a model to write a new OIP article with a specified slug and title.\ncurl -X POST https://miscsubjects.com/api/protocol/oip-write -H 'x-terminal-key: <KEY>' -d '{\"slug\":\"oip-example\",\"title\":\"Example\"}'\n# Article revision: This mechanism instructs a model to revise an existing OIP article identified by its slug.\ncurl -X POST https://miscsubjects.com/api/protocol/oip-revise -H 'x-terminal-key: <KEY>' -d '{\"slug\":\"oip-example\"}'\n```\n\n## Capability Token Management (OWNER)\n\nThese mechanisms manage capability tokens. An `x-terminal-key` provides owner credentials.\n\n```bash\n# Capability explanation: This mechanism retrieves properties of a capability token, including its permissions, remaining uses, and expiry.\ncurl 'https://miscsubjects.com/api/dispatch?explain=1&share=<TOKEN>'\n# Capability revocation: This mechanism instantly invalidates a capability identified by its fingerprint.\ncurl -H 'x-terminal-key: <KEY>' 'https://miscsubjects.com/api/dispatch?revoke=cap_FINGERPRINT'\n```\n\n## End-to-End Example: Invocation and Receipt\n\n1.  **Invocation Mechanism:** Invoke the `SEND_BY_CHANNEL` object.\n    ```bash\n    curl 'https://miscsubjects.com/api/dispatch?invoke=SEND_BY_CHANNEL&body=blooio|%2Bredacted|Hello&share=<TOKEN>'\n    # Assume this returns an inv_ID, e.g., inv_ABC123\n    ```\n2.  **Receipt Proof Mechanism:** Retrieve the receipt for `inv_ABC123`.\n    ```bash\n    curl 'https://miscsubjects.com/api/dispatch?receipt=inv_ABC123&share=<TOKEN>'\n    ```\n\n## Receipt Rule\n\nAn OIP invocation generates a unique `inv_ID` and a corresponding receipt, retrievable via `GET /api/dispatch?receipt=inv_ID`.\n\n## Conformance Rule\n\nAn OIP implementation conforms when it correctly processes `POST /api/dispatch {key, body}` or `GET /api/dispatch?invoke=KEY&body=...` and returns a valid receipt.\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"}}