Drive Bones to Reef from your own code

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

{"verdict": "reef-ready", "headline": "...", "items": [{"n": 1, "leftover": "two toolboxes", "stage": 1, "taker": "Marta", "move": "...", "why": "..."}, ...], "signpost": "...", "last_word": "..."}

{
 "task": "sort-the-fall",
 "thing": "the zine I photocopy for the laundrette noticeboard",
 "ends": "undated",
 "leftover_count": "5",
 "leftovers": "1. a box of 60 back issues [page stage: 1]\n2. the long-arm stapler [page stage: none]\n3. a contacts list of 14 contributors [page stage: 2]\n4. my layout template [page stage: 3]\n5. the habit of writing every month [page stage: 4]",
 "takers": "Rosa: runs the community centre library shelf\nDev: wants to start a comic"
}

{
 "verdict": "set-a-date",
 "headline": "Winding down the zine for the laundrette noticeboard leaves 5 leftovers, 1 unclaimed, mostly at stage 1, scavengers.",
 "items": [
  {
   "n": 1,
   "leftover": "a box of 60 back issues",
   "stage": 1,
   "taker": "Rosa",
   "move": "Ask Rosa if the community centre library shelf can take the back issues.",
   "why": "A box of 60 back issues is something someone can take and use right away."
  },
  {
   "n": 2,
   "leftover": "the long-arm stapler",
   "stage": 1,
   "taker": "Dev",
   "move": "Ask Dev if the comic could use the long-arm stapler.",
   "why": "A long-arm stapler is something someone can carry off and use right away."
  },
  {
   "n": 3,
   "leftover": "a contacts list of 14 contributors",
   "stage": 2,
   "taker": "unclaimed",
   "move": "Pin a note on the laundrette noticeboard asking who would like the contacts list.",
   "why": "A contacts list of contributors is something others could keep using, not use up."
  },
  {
   "n": 4,
   "leftover": "my layout template",
   "stage": 3,
   "taker": "Dev",
   "move": "Ask Dev if the new comic could use the layout template.",
   "why": "A layout template is something that can keep helping with future issues slowly."
  },
  {
   "n": 5,
   "leftover": "the habit of writing every month",
   "stage": 4,
   "taker": "you",
   "move": "Keep writing every month, with or without the zine.",
   "why": "A habit of writing every month can keep going for years by itself."
  }
 ],
 "signpost": "This zine for the noticeboard is winding down, with no date yet. The back issues may go to Rosa's community centre library shelf, and the long-arm stapler and layout template might suit Dev's comic. Ask here if you're interested in the contacts list of contributors.",
 "last_word": "Pick an end date for the zine."
}

{
 "task": "sort-the-fall",
 "thing": "my weekly language-exchange meetup at the cafe",
 "ends": "soon",
 "leftover_count": "5",
 "leftovers": "1. laminated conversation cards [page stage: 1]\n2. the cafe's back-room booking on Wednesdays [page stage: 2]\n3. a group chat of 38 members [page stage: 2]\n4. a tin with £22 in it [page stage: 1]\n5. the friendships with Tomas and Ewa [page stage: 4]",
 "takers": "(none)"
}

{
 "verdict": "needs-takers",
 "headline": "This weekly language-exchange meetup's ending leaves 5 leftovers, 4 of them unclaimed, mostly at stage 1, Scavengers.",
 "items": [
  {
   "n": 1,
   "leftover": "laminated conversation cards",
   "stage": 1,
   "taker": "unclaimed",
   "move": "Ask in the group chat whether anyone wants the conversation cards.",
   "why": "The cards are something to take and start using straight away."
  },
  {
   "n": 2,
   "leftover": "the cafe's back-room booking on Wednesdays",
   "stage": 2,
   "taker": "unclaimed",
   "move": "Ask the cafe whether someone else can keep the Wednesday booking.",
   "why": "The back-room booking is a slot that could keep being used on Wednesdays."
  },
  {
   "n": 3,
   "leftover": "a group chat of 38 members",
   "stage": 2,
   "taker": "unclaimed",
   "move": "Ask the group chat's members if someone wants to keep running it.",
   "why": "The chat's 38 members are an audience that could keep talking on their own."
  },
  {
   "n": 4,
   "leftover": "a tin with £22 in it",
   "stage": 1,
   "taker": "unclaimed",
   "move": "Ask the group chat's members openly how the £22 should be used.",
   "why": "The tin's £22 can be spent or shared right away."
  },
  {
   "n": 5,
   "leftover": "the friendships with Tomas and Ewa",
   "stage": 4,
   "taker": "you",
   "move": "Message Tomas and Ewa to keep in touch beyond the meetup.",
   "why": "Friendships with Tomas and Ewa are what will keep lasting for years."
  }
 ],
 "signpost": "This weekly language-exchange meetup at the cafe is ending soon. The conversation cards, the Wednesday back-room booking, the group chat, and the tin with £22 still need a taker - if interested, please ask.",
 "last_word": "Go find takers for the cards, the booking, the chat, and the tin."
}

{
 "task": "sort-the-fall",
 "thing": "the repair table I run at the church hall",
 "ends": "months",
 "leftover_count": "5",
 "leftovers": "1. two toolboxes [page stage: 1]\n2. a soldering iron [page stage: 1]\n3. the mailing list of 120 people [page stage: 2]\n4. a binder of repair notes [page stage: 3]\n5. the knack for fixing lamps [page stage: 4]",
 "takers": "Marta: wants to run a repair night at the youth club\nthe church hall committee"
}

{
 "verdict": "reef-ready",
 "headline": "5 leftovers remain from the repair table, 1 unclaimed, with stage 1, Scavengers, holding the most — ready for someone to use straight away.",
 "items": [
  {
   "n": 1,
   "leftover": "two toolboxes",
   "stage": 1,
   "taker": "Marta",
   "move": "Ask Marta whether the toolboxes suit the youth club repair night before handing them over.",
   "why": "Toolboxes are physical kit that gets used once someone takes them."
  },
  {
   "n": 2,
   "leftover": "a soldering iron",
   "stage": 1,
   "taker": "Marta",
   "move": "Ask Marta whether the soldering iron suits the youth club repair night.",
   "why": "A soldering iron is kit someone takes and uses straight away."
  },
  {
   "n": 3,
   "leftover": "the mailing list of 120 people",
   "stage": 2,
   "taker": "unclaimed",
   "move": "Ask around the church hall for someone willing to keep the list going.",
   "why": "A mailing list of 120 people is an audience a group could keep using."
  },
  {
   "n": 4,
   "leftover": "a binder of repair notes",
   "stage": 3,
   "taker": "Marta",
   "move": "Ask Marta whether the binder of repair notes would help the youth club nights.",
   "why": "A binder of repair notes is know-how that can keep helping for a long time."
  },
  {
   "n": 5,
   "leftover": "the knack for fixing lamps",
   "stage": 4,
   "taker": "you",
   "move": "Keep fixing lamps for people who ask, so the knack stays alive.",
   "why": "The knack for fixing lamps is a skill that stays with you."
  }
 ],
 "signpost": "The repair table that used to run here is ending. The two toolboxes, a soldering iron and a binder of repair notes may go to Marta for a youth club repair night. If you'd like to help keep the mailing list going, ask here.",
 "last_word": "What's ending still leaves something lasting behind — the knack for fixing lamps stays with you."
}

{
 "task": "sort-the-fall",
 "thing": "my vintage postcard stall at the Saturday market",
 "ends": "soon",
 "leftover_count": "4",
 "leftovers": "1. about 900 postcards in shoeboxes [page stage: 1]\n2. the gazebo [page stage: 1]\n3. the card reader [page stage: 1]\n4. my pitch at the market [page stage: 2]",
 "takers": "Joe: sells old maps on the next pitch, asked about my gazebo and card reader\nLena: collects seaside postcards\nthe market manager: hands out the pitches"
}

{
 "verdict": "picked-clean",
 "headline": "Your postcard stall's ending leaves 4 leftovers, 0 unclaimed, with stage 1 Scavengers holding the most.",
 "items": [
  {
   "n": 1,
   "leftover": "about 900 postcards in shoeboxes",
   "stage": 1,
   "taker": "Lena",
   "move": "Ask Lena whether they want the postcards before you box them up.",
   "why": "About 900 postcards in shoeboxes are things someone can take and use right away."
  },
  {
   "n": 2,
   "leftover": "the gazebo",
   "stage": 1,
   "taker": "Joe",
   "move": "Ask Joe whether they want the gazebo before you take it down.",
   "why": "The gazebo is a structure you can hand over all at once."
  },
  {
   "n": 3,
   "leftover": "the card reader",
   "stage": 1,
   "taker": "Joe",
   "move": "Ask Joe whether they want the card reader before you pass it on.",
   "why": "The card reader is equipment someone can take and start using right away."
  },
  {
   "n": 4,
   "leftover": "my pitch at the market",
   "stage": 2,
   "taker": "the market manager",
   "move": "Ask the market manager about handing on your pitch at the market.",
   "why": "Your pitch at the market is a spot someone else could step into and keep running."
  }
 ],
 "signpost": "This vintage postcard stall is ending soon. Lena may take the postcards, Joe may take the gazebo and card reader, and the market manager may take on the pitch. Ask before anything moves.",
 "last_word": "Everything from your stall has somewhere to go; now it's just asking each one."
}

const K = ReefKit;
const built = K.buildInput(K.form({ thing: "the book swap shelf at work", ends: "soon", leftovers: "a crate of paperbacks\nthe sign-up sheet", takers: "Ali: runs the staff room" }));
built.facts.items                       // each leftover with the page's stage (0 = still sinking)
const wire = K.toWire(built.input);     // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output));
// K.check(reply, built).notes          // the page's re-check of the reply
// K.md(built, reply, "the book swap")  // the sorting as Markdown

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://bones-to-reef.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"bones-to-reef"}' | jq -r '.data.token')

api GET /me | jq '.data | {subject_type, credits}' 

# input.json: the run input object - {"task": "sort-the-fall", "thing": "the repair table I run at the church hall", "ends": "months", "leftover_count": "5", "leftovers": "1. two toolboxes [page stage: 1]\n2. ...", "takers": "Marta: wants to run a repair night at the youth club\n..."}
# - see the field table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}' 

KEY="bones-to-reef:sort-the-fall:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}' 

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: bones-to-reef:sort-the-fall:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json