Drive Pen or Prompt from your own code

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

{"task": "tool-sort", "headline": "...", "items": [{"item": 1, "verdict": "builtin", "why": "...", "first_move": "..."}, ...], "build": {"item": 2, "must": ["...", "...", "..."], "leave_out": "...", "first_prompt": "..."}, "closing": "..."}

{
 "task": "tool-sort",
 "kit": "a phone, a pen and a corkboard",
 "items": "item 1 | annoyance: forgetting to water the fern on the landing | how often: every week (52 times a year) | minutes lost each time: 2 | a fix would need: a nudge at the right time | minutes a year: 104 (about 1.7 hours) | page verdict: builtin\nitem 2 | annoyance: packing the gym bag and leaving something behind | how often: every week (52 times a year) | minutes lost each time: 5 | a fix would need: a fixed list or steps to follow | minutes a year: 260 (about 4.3 hours) | page verdict: paper\nitem 3 | annoyance: not knowing what is left in the chest freezer | how often: every week (52 times a year) | minutes lost each time: 5 | a fix would need: a running record of what happened | minutes a year: 260 (about 4.3 hours) | page verdict: sheet\nitem 4 | annoyance: hunting for the spare bike lock key | how often: a few times a year (4 times a year) | minutes lost each time: 10 | a fix would need: a fixed list or steps to follow | minutes a year: 40 (about 0.7 hours) | page verdict: skip",
 "facts": "build first: none\ntotal minutes a year: 664 (about 11 hours)\nsorted: skip 1, builtin 1, paper 1, sheet 1, vibe 0\nno tiny app needed: 4 of 4 items"
}

{
 "task": "tool-sort",
 "headline": "4 of 4 items need no tiny app - nothing here calls for a build.",
 "items": [
  {
   "item": 1,
   "verdict": "builtin",
   "why": "Watering the fern on the landing happens every week and costs 104 minutes a year, and a nudge at the right time is exactly what a reminder provides.",
   "first_move": "Set a phone reminder to repeat every week with words like 'water the fern on the landing.'"
  },
  {
   "item": 2,
   "verdict": "paper",
   "why": "Packing the gym bag and leaving something behind comes round every week, racking up 260 minutes a year, and a list of steps is what covers it.",
   "first_move": "Write a list of everything that goes in the gym bag and keep it with the bag so nothing gets left behind."
  },
  {
   "item": 3,
   "verdict": "sheet",
   "why": "Not knowing what is left in the chest freezer comes round every week, adding up to 260 minutes a year, and a running record fits a simple sheet best.",
   "first_move": "Column headings for the chest freezer sheet: item, date added, date used."
  },
  {
   "item": 4,
   "verdict": "skip",
   "why": "Hunting for the spare bike lock key happens only a few times a year and costs 40 minutes a year - a small enough loss to leave alone.",
   "first_move": "Let the spare bike lock key hunt go for now - 40 minutes a year is too little to fix with anything."
  }
 ],
 "build": null,
 "closing": "4 light fixes, no tiny app needed - pick a first move and give it a go, whenever suits you."
}

{
 "task": "tool-sort",
 "kit": "a laptop and a phone",
 "items": "item 1 | annoyance: writing down my run times and finding my best on each route | how often: every day (365 times a year) | minutes lost each time: 5 | a fix would need: a running record of what happened | minutes a year: 1825 (about 30 hours) | page verdict: vibe\nitem 2 | annoyance: comparing the electricity meter reading with last month | how often: every month (12 times a year) | minutes lost each time: 10 | a fix would need: adding up or comparing numbers | minutes a year: 120 (about 2 hours) | page verdict: sheet\nitem 3 | annoyance: remembering to stretch after sitting | how often: every day (365 times a year) | minutes lost each time: 1 | a fix would need: a nudge at the right time | minutes a year: 365 (about 6.1 hours) | page verdict: builtin\nitem 4 | annoyance: the TV remote slipping down the sofa | how often: a few times a year (4 times a year) | minutes lost each time: 5 | a fix would need: a fixed list or steps to follow | minutes a year: 20 (about 0.3 hours) | page verdict: skip",
 "facts": "build first: item 1 (1825 minutes a year)\ntotal minutes a year: 2330 (about 39 hours)\nsorted: skip 1, builtin 1, paper 0, sheet 1, vibe 1\nno tiny app needed: 3 of 4 items"
}

{
 "task": "tool-sort",
 "headline": "3 of 4 items need no tiny app; a tiny app suits what's left.",
 "items": [
  {
   "item": 1,
   "verdict": "vibe",
   "why": "You write down run times and best on each route every day (365 times a year), for 1825 minutes a year - too much for a sheet, needing a tiny app.",
   "first_move": "This fits a tiny app - look at the build card below for the first concrete step to set it up."
  },
  {
   "item": 2,
   "verdict": "sheet",
   "why": "Comparing your electricity meter reading with last month happens every month, 12 times a year, 120 minutes a year - adding and comparing numbers that a simple sheet handles well.",
   "first_move": "Try a few columns: month, electricity meter reading, difference from last month."
  },
  {
   "item": 3,
   "verdict": "builtin",
   "why": "Remembering to stretch after sitting comes round every day, 365 times a year, costing 365 minutes a year - just a nudge at the right time, which a built-in reminder gives.",
   "first_move": "Set a daily reminder on your phone or laptop, repeating every day, with the words 'stretch after sitting'."
  },
  {
   "item": 4,
   "verdict": "skip",
   "why": "The TV remote slipping down the sofa happens a few times a year, just 20 minutes a year - small enough to let it be.",
   "first_move": "Let the TV remote slipping down the sofa be - it costs so little it's fine to let it be, no tool needed."
  }
 ],
 "build": {
  "item": 1,
  "must": [
   "Log each run's time and route.",
   "Keep a running record of past run times and routes.",
   "Show the best time found so far for each route."
  ],
  "leave_out": "Leave out sharing your times with other people for the first version.",
  "first_prompt": "Build a small app that logs each run's time and route, keeps a running record of past run times and routes, and shows the best time found so far for each route, all on a single screen, with data kept only on this device, no sign-in, no payments and no other people's personal details."
 },
 "closing": "Whenever you're ready, picking any fix here is a good place to start - no rush."
}

{
 "task": "tool-sort",
 "kit": "none",
 "items": "item 1 | annoyance: keeping track of library books, due dates and which shelf they go back to | how often: every week (52 times a year) | minutes lost each time: 10 | a fix would need: several of these at once | minutes a year: 520 (about 8.7 hours) | page verdict: vibe\nitem 2 | annoyance: tracking how many pages I read and my monthly total | how often: every day (365 times a year) | minutes lost each time: 2 | a fix would need: adding up or comparing numbers | minutes a year: 730 (about 12 hours) | page verdict: vibe\nitem 3 | annoyance: the bread recipe steps I keep mixing up | how often: every week (52 times a year) | minutes lost each time: 5 | a fix would need: a fixed list or steps to follow | minutes a year: 260 (about 4.3 hours) | page verdict: paper",
 "facts": "build first: item 2 (730 minutes a year)\ntotal minutes a year: 1510 (about 25 hours)\nsorted: skip 0, builtin 0, paper 1, sheet 0, vibe 2\nno tiny app needed: 1 of 3 items"
}

{
 "task": "tool-sort",
 "headline": "1 of 3 items needs no tiny app; the rest point toward building a tiny app.",
 "items": [
  {
   "item": 1,
   "verdict": "vibe",
   "why": "Library books, due dates and which shelf they go back to need several things at once - more than a list or a sheet - every week for 520 minutes a year.",
   "first_move": "This waits until the other tiny app is finished and working, then you could set up something similar for this annoyance."
  },
  {
   "item": 2,
   "verdict": "vibe",
   "why": "Tracking how many pages you read and your monthly total happens every day, 730 minutes a year - enough numbers to outgrow a sheet and be worth a tiny app.",
   "first_move": "This is the annoyance picked to turn into a tiny app now - look below for what it must do and a request ready to paste into an AI app builder."
  },
  {
   "item": 3,
   "verdict": "paper",
   "why": "The bread recipe steps you keep mixing up just need a fixed list to follow, not tracking - this happens every week and costs 260 minutes a year.",
   "first_move": "Write out the bread recipe steps in order on paper and keep it right where you use them."
  }
 ],
 "build": {
  "item": 2,
  "must": [
   "Log how many pages you read each day",
   "Add up your daily pages into a monthly total",
   "Let you compare your monthly totals"
  ],
  "leave_out": "Skip charts, streaks or goals when starting out.",
  "first_prompt": "Build a small app that logs how many pages you read each day, adds them up into a monthly total, and lets you compare your monthly totals, on a single screen, with data kept only on this device, and no sign-in, payments or other people's personal details."
 },
 "closing": "Whenever you're ready, picking up a pen or starting that new tiny app could feel surprisingly easy."
}

const K = PenKit;
const built = K.buildInput(K.form({ kit: "a phone",
  items: [{ what: "forgetting to water the fern", often: "weekly", minutes: 2, needs: "nudge" },
          { what: "logging my run times per route", often: "daily", minutes: 5, needs: "log" }] }));
built.input.facts;                      // the page's lines: build first, totals, the sort counts
const wire = K.toWire(built.input);     // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output));
// built.facts.items[0].verdict         // the sort the page's rule gives
// K.check(reply, built).notes          // the page's re-check of the reply
// K.md(built, reply, "my list")        // the list as Markdown

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://pen-or-prompt.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":"pen-or-prompt"}' | jq -r '.data.token')

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

# input.json: the run input object - {"task": "tool-sort", "kit": "a laptop and a phone", "items": "item 1 | annoyance: ...", "facts": "build first: item 1 ..."}
# - see the field table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}' 

KEY="pen-or-prompt:tool-sort:$(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: pen-or-prompt:tool-sort:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json