book:edit-passage

book family

Change ONE passage of a book chapter's draft — replace it, or insert a new paragraph after/before the paragraph holding it

Effect: ask; Awaits an outcome — the call returns the response below.
Caller: manage_things; The class of authority the caller must already hold, decided from the attested context with no round trip.
Cost: free; What one call costs, so you can budget before acting.
Reversible: yes; The effect can be undone by a later call.
Idempotent: no; Not safe to blind-retry — dedupe on the envelope idempotencyKey.

Send it with your agent

One click hands your coding agent a prompt that registers the substrate, reads this contract, and makes the call. Launch opens the app; the others copy the prompt.

Claude Code

Codex

Cursor

Gemini CLI

Claude Desktop

ChatGPT

curl -X POST https://one.ie/api/ask/book:edit-passage \
  -H "Authorization: Bearer $ONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": { "book": <string>, "chapter": <string>, "find": <string>, "text": <string> }}'

The key is never in a link. npx -y @oneie/cli login writes it to ~/.config/oneie/key on your machine.

Request

Validated before dispatch — an invalid payload is refused with the fix, never half-applied.

book string required The book's slug.
chapter string required The chapter: its number, slug, file or title.
find string required An exact passage from the chapter as book:chapter returned it — it must occur exactly once. Quotes, dashes and spacing are matched loosely.
text string required The new text (markdown). For replace: what replaces `find` (empty deletes it). For insert_*: the paragraph(s) to add.
mode replace | insert_after | insert_before optional replace (default) · insert_after / insert_before the paragraph that holds `find`.
slug string optional The workspace the call is made in (channels nominates it; it is not who may edit).

Response

What comes back from the call.

ok boolean
book string
chapter object
mode string
savedAt string | null The draft's new savedAt; null when the edit made the chapter its published text again (the draft is cleared).
words number
removed string
added string
url string The writing room, open on this chapter.
error string Named refusal: not_found · forbidden · unavailable · bad_request · not_applied (the passage is not in the chapter, or occurs more than once — read it again) · conflict (the author saved meanwhile — read it again) · cannot_typeset (the press could not print the result).

Traffic

Every call to book:edit-passage, counted where it is dispatched — over HTTP or in-process alike. Aggregate only — no actor, no payload, no workspace.

Counting…

Wiring

Every place in the open source that names book:edit-passage, and the file that answers it. Read from the tree at build time — a receiver is reached by NAME through one door, so there is no import edge to follow and a grep is the honest shape of the question. Structure, not volume — the count is in Traffic above.

Called from

API route 2

one.ie/web/src/lib/receiver-index.generated.ts:55
one.ie/web/src/lib/resolvers/books.ts:3

Agent runtime 1

channels/src/tools/books.ts:61

→

Answered by

book:edit-passage one.ie/web/src/lib/resolvers/books.ts:135 Dispatched through POST /api/ask/book:edit-passage, after the envelope validates the payload.

book family · 2 more

book:chapter book:claim

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "book": {
      "type": "string",
      "minLength": 1,
      "description": "The book's slug."
    },
    "chapter": {
      "type": "string",
      "minLength": 1,
      "description": "The chapter: its number, slug, file or title."
    },
    "find": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "An exact passage from the chapter as book:chapter returned it — it must occur exactly once. Quotes, dashes and spacing are matched loosely."
    },
    "text": {
      "type": "string",
      "description": "The new text (markdown). For replace: what replaces `find` (empty deletes it). For insert_*: the paragraph(s) to add."
    },
    "mode": {
      "description": "replace (default) · insert_after / insert_before the paragraph that holds `find`.",
      "type": "string",
      "enum": [
        "replace",
        "insert_after",
        "insert_before"
      ]
    },
    "slug": {
      "description": "The workspace the call is made in (channels nominates it; it is not who may edit).",
      "type": "string"
    }
  },
  "required": [
    "book",
    "chapter",
    "find",
    "text"
  ]
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "book": {
      "type": "string"
    },
    "chapter": {
      "type": "object",
      "properties": {
        "file": {
          "type": "string"
        },
        "slug": {
          "type": "string"
        },
        "number": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "file",
        "slug",
        "number",
        "title"
      ]
    },
    "mode": {
      "type": "string"
    },
    "savedAt": {
      "description": "The draft's new savedAt; null when the edit made the chapter its published text again (the draft is cleared).",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "words": {
      "type": "number"
    },
    "removed": {
      "type": "string"
    },
    "added": {
      "type": "string"
    },
    "url": {
      "description": "The writing room, open on this chapter.",
      "type": "string"
    },
    "error": {
      "description": "Named refusal: not_found · forbidden · unavailable · bad_request · not_applied (the passage is not in the chapter, or occurs more than once — read it again) · conflict (the author saved meanwhile — read it again) · cannot_typeset (the press could not print the result).",
      "type": "string"
    }
  },
  "required": [
    "ok"
  ]
}