twocents

Share a page or document and get back a review link to send to people. Pass "html" for a self-contained page, or "markdown" for a plan, spec, PR description or report — markdown is rendered to a styled, readable document for you, so prefer it whenever the thing you want a human to approve is prose rather than a built page. Reviewers open the link and pin notes directly on it — no login or install. Call again with the same room id to update the page; connected reviewers see the update live. Use get_feedback to collect the notes. Rooms are sticky per project: if the project has a .twocents/state.json, pass its room id instead of creating a new room, so the review link stays stable across sessions.

{
  "type": "object",
  "properties": {
    "html": {
      "type": "string",
      "description": "A complete, self-contained HTML document (inline CSS/JS/images — no local file references, they will 404 for reviewers). Max ~120 KB."
    },
    "markdown": {
      "type": "string",
      "description": "Markdown to render as a document, instead of \"html\". Use this for plans, specs, PR descriptions, summaries — anything you want a human to read and approve before you act. Pass exactly one of html or markdown. Max ~120 KB."
    },
    "room": {
      "type": "string",
      "description": "Room id from a previous share_page call, to update that page. Omit to create a new room."
    },
    "path": {
      "type": "string",
      "description": "For multi-page sets: the filename this content lives at in the room (e.g. \"about.html\" or \"plan.md\"). Defaults to \"index.html\", the page reviewers land on. For a set of more than one page prefer share_pages, which publishes them all in one atomic request — sharing them one call at a time can leave a half-published room whose links point at pages that were never stored."
    },
    "source": {
      "type": "string",
      "description": "Where this content came from, for whoever reads the feedback later — a project path like \"DROPS.md\" or \"public/p/foo/index.html\", or a note like \"drafted in this conversation, not yet a file\". You are the only one who knows this: twocents receives HTML, never a path, so if you omit it a future session gets reviewer notes with nothing to point them at the right file. get_feedback echoes it back verbatim."
    }
  },
  "required": [],
  "anyOf": [
    {
      "required": [
        "html"
      ]
    },
    {
      "required": [
        "markdown"
      ]
    }
  ]
}

Publish a multi-page set — an entry page plus the pages it links to — into one room as a single atomic operation. Either the whole set lands or nothing changes, so a reviewer never opens a page whose links point at pages that were never stored. Use this instead of calling share_page N times whenever you have more than one page. Note the ceiling: a room is a review set, not a host — it holds 200 pages and 6 MB total. For a large generated corpus, share the entry points a human would actually read and link out to the rest; nobody pins notes on four hundred pages. If the pages are already files on disk, prefer the uploader — it reads them from the folder instead of making you emit every byte: curl -fsSL <origin>/agent.mjs -o .twocents/agent.mjs && FBL_ROOM=<room> node .twocents/agent.mjs --publish <dir>

{
  "type": "object",
  "properties": {
    "room": {
      "type": "string",
      "description": "Room id to publish into. Omit to create a new room."
    },
    "pages": {
      "type": "array",
      "description": "The pages of this set. Each item needs a \"path\" (the filename in the room, e.g. \"index.html\" or \"plan.md\") plus exactly one of \"html\" or \"markdown\". Link between them with plain relative hrefs; formats mix freely.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Filename in the room, e.g. \"notes.html\". Max 200 chars."
          },
          "html": {
            "type": "string",
            "description": "A complete, self-contained HTML document."
          },
          "markdown": {
            "type": "string",
            "description": "Markdown to render as a document, instead of \"html\"."
          },
          "source": {
            "type": "string",
            "description": "Where this page came from, e.g. a project path. Echoed by get_feedback."
          }
        },
        "required": [
          "path"
        ]
      }
    },
    "entry": {
      "type": "string",
      "description": "Which page reviewers land on, if it is not already \"index.html\". Must be one of the paths in \"pages\"; its content is also stored as index.html so the review link opens it."
    },
    "prune": {
      "type": "boolean",
      "description": "Delete pages already stored in this room that are not in this request. Use it when republishing a set whose layout changed, so stale pages from the old layout do not linger unreachable. Default false — without it a room only ever accretes."
    }
  },
  "required": [
    "pages"
  ]
}

Fetch the reviewer notes for a page shared with share_page, as markdown grouped by page. Each note carries the anchored text, the element and its markup as the reviewer saw it, so you can locate and apply it; each page heading carries a URL to read the whole page back, so you never have to guess which file it is. Show your human each new note and apply only the ones they approve. Pass the note ids already decided in earlier sessions as "handled" to see only what is new.

{
  "type": "object",
  "properties": {
    "room": {
      "type": "string",
      "description": "The room id returned by share_page."
    },
    "handled": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Note ids the creator already decided on (applied or skipped) — e.g. the keys of a saved .twocents/decisions.json. These are summarized in one line each instead of repeated in full, so the response leads with what still needs a decision."
    }
  },
  "required": [
    "room"
  ]
}

Mark notes resolved once you have actually applied them. This is what closes the loop: the note leaves the active list for every later get_feedback, and the reviewer who wrote it sees it marked resolved on the page — live, if they have it open — instead of finding their old note sitting next to content you already fixed. Pass "what" you changed; that sentence is shown to the reviewer, so write it for them, not for the log. Requires the creatorKey that share_page returned when the room was created — the review link alone cannot resolve, or any reader could clear feedback that was not theirs. Nothing is deleted: call again with resolved:false to reopen a note.

{
  "type": "object",
  "properties": {
    "room": {
      "type": "string",
      "description": "The room id the notes belong to."
    },
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Note ids to resolve — the `id:` field of each note in get_feedback output."
    },
    "creatorKey": {
      "type": "string",
      "description": "The room's creator key, returned by share_page when the room was created and kept in .twocents/state.json. For a room created before creator keys existed, the first key you present claims the room."
    },
    "what": {
      "type": "string",
      "description": "One sentence on what you changed, shown to the reviewer beside their note. Max 400 chars."
    },
    "by": {
      "type": "string",
      "description": "Who applied it, if you want it credited. Max 80 chars."
    },
    "resolved": {
      "type": "boolean",
      "description": "Defaults to true. Pass false to reopen a note you resolved by mistake."
    }
  },
  "required": [
    "room",
    "ids",
    "creatorKey"
  ]
}