@josfox/jos 4.0.8 → 5.0.0

package/examples/04-use-template/use.jos

@@ -0,0 +1,64 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "flow"
+  },
+  "id": "tour.use-template",
+  "meta": {
+    "name": "tour.use-template",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Greet two people with one template, pinned by its digest",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "Leo"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "orchestration": {
+    "definitions": {
+      "ana": {
+        "use": "tour.greeting@^1.0.0",
+        "with": {
+          "name": "Ana"
+        }
+      },
+      "leo": {
+        "use": "tour.greeting@^1.0.0",
+        "with": {
+          "name": "Leo"
+        }
+      }
+    },
+    "flows": {
+      "main": {
+        "steps": [
+          "ana",
+          "leo"
+        ]
+      }
+    }
+  },
+  "requires": [
+    {
+      "kind": "artifact",
+      "name": "tour.greeting",
+      "version": "^1.0.0",
+      "digest": "art_7ed518676186fe910bc5441ba4ae0126b6ebdeaedec7ef14b7a96422da764210"
+    }
+  ]
+}

package/examples/05-sealed/.jos/manifest.jos

@@ -0,0 +1,53 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "directory"
+  },
+  "id": "tour.sealed",
+  "meta": {
+    "name": "tour.sealed",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Run only while this folder is exactly as it was sealed",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "sealed folder ran"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "orchestration": {
+    "definitions": {
+      "say": {
+        "engine": "shell",
+        "run": [
+          "echo",
+          "the sealed folder ran"
+        ]
+      }
+    },
+    "flows": {
+      "main": {
+        "steps": [
+          "say"
+        ]
+      }
+    }
+  },
+  "integrity": {
+    "hash": "sha256:621c560a601e2274e1e3009f226e8b3cd3934eff0adb32f62e6b95018ad945eb"
+  }
+}

package/examples/05-sealed/README.md

@@ -0,0 +1,25 @@
+# 05 · a sealed folder
+
+A folder with a `.jos/manifest.jos` is itself a `.jos` document (kind `directory`). This one is sealed: its
+`integrity.hash` is the hash jos-core computes over everything in `.jos/` (the manifest with `integrity.hash`
+blanked, and every other file; `replays/`, `logs/` and `dev/` are not counted). `jos run` recomputes it before
+anything starts.
+
+| Command | Result |
+|---|---|
+| `jos run 05-sealed` | the hash matches: prints `the sealed folder ran`; exit 0. The ledger of the run goes to `05-sealed/.jos/replays/` (not counted in the hash) |
+| `jos ids 05-sealed` | `directory: sha256:… (sealed, matches)` |
+
+To see the seal refuse a change, edit the text `the sealed folder ran` in `.jos/manifest.jos` (or add any file
+under `.jos/`) and run it again:
+
+```
+$ jos run 05-sealed
+…
+✖ Intention NOT met (code 3: blocked) (run_…)
+  integrity: declared hash does not match the directory hash (SPEC-2.0 §9.3)
+```
+
+Exit 3, and nothing ran. `jos ids 05-sealed` now says `sealed, does NOT match`. Undo the edit and it runs again.
+
+What the seal covers is `.jos/` only: this README, next to `.jos/`, is not part of the hash.

package/examples/06-requires.jos

@@ -0,0 +1,42 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.requires",
+  "meta": {
+    "name": "tour.requires",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Charge a card through the payments service",
+    "success_criteria": [
+      {
+        "exit": 0
+      }
+    ]
+  },
+  "guardrails": {
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "echo",
+      "charged"
+    ],
+    "env": [
+      "PATH"
+    ]
+  },
+  "requires": [
+    {
+      "kind": "service",
+      "name": "payments"
+    }
+  ]
+}

package/examples/07-sandbox.jos

@@ -0,0 +1,39 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.sandbox",
+  "meta": {
+    "name": "tour.sandbox",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Run a step that must not reach the network or files outside its folder",
+    "success_criteria": [
+      {
+        "exit": 0
+      }
+    ]
+  },
+  "guardrails": {
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "echo",
+      "confined"
+    ],
+    "env": [
+      "PATH"
+    ]
+  },
+  "security": {
+    "tier": "sandbox"
+  }
+}

package/examples/08-ids-ledger-meter.md

@@ -0,0 +1,26 @@
+# 08 · identities, the ledger and the meter
+
+Every `jos run` (not `--dry-run`) leaves a hash-chained ledger. These commands read what jos-core recorded; none of
+them runs a document or writes anything.
+
+```
+jos ids 01-hello.jos 05-sealed        # art_ (content), ent_ (name), and the directory hash of a folder
+jos run 01-hello.jos                  # note the run id it prints: run_…
+jos runs                              # the runs in ~/.jos/runs, newest first: id, start, code, document, art_
+jos ledger verify run_…               # every entry's hash recomputed, chain continuous, run ended
+jos meter run_…                       # steps, attempts, time; tokens and cost when an engine reported them
+```
+
+What to expect:
+
+| Command | Result |
+|---|---|
+| `jos ids 01-hello.jos` | `artifact: art_40762df5…`: the same value on every machine and in both reference kernels; `entity: ent_…` from `atom:tour.hello` |
+| `jos runs` | `✓ run_…  <start>  code 0 (done)` and, below it, `tour.hello  art_…`; a ledger that does not verify is listed with `⚠` and the reason |
+| `jos ledger verify run_…` | `✓ LEDGER VERIFIED`, with the number of entries and the head hash; exit 0. Change one byte of the run's `ledger.jsonl` and it is `✖ LEDGER DOES NOT VERIFY`, `Reason: hash_mismatch`, exit 1 |
+| `jos meter run_…` | `Code: 0`, `Steps: tour.hello`, `Engines: shell`, `Time: … ms`, `Tokens in: not reported`, `Cost: not reported` (the shell engine reports neither; never shown as 0) |
+
+`jos ledger verify` and `jos meter` also take the path of a `ledger.jsonl` or of a run folder. A run id is looked up
+in `.jos/replays/` of the folders above the current directory (that is where `05-sealed` keeps its runs: run the
+command from inside `05-sealed/`, or pass the path), then in `~/.jos/runs/`. Add `--json` to any of them for the
+machine-readable form.

package/examples/10-ollama.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.ollama",
+  "meta": {
+    "name": "tour.ollama",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "In one sentence: what is a declared intention?",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_matches": "\\S"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 300,
+      "output_bytes": 1048576,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "/bin/sh",
+      "-c",
+      "url=http://localhost:11434\nif ! command -v curl >/dev/null 2>&1; then echo \"curl is not installed: cannot check $url\" >&2; exit 3; fi\nif ! curl -sf --max-time 3 -o /dev/null \"$url/api/tags\"; then\n  echo \"Ollama is not answering on $url: nothing was sent.\" >&2\n  echo \"Start it (ollama serve, or the Ollama app), then run this again.\" >&2\n  exit 3\nfi\ncommand -v ollama >/dev/null 2>&1 || { echo \"Ollama answers on $url but the ollama command is not on PATH\" >&2; exit 4; }\nexec ollama run \"${OLLAMA_MODEL:-llama3.2}\" \"$1\"",
+      "10-ollama",
+      "In one sentence: what is a declared intention?"
+    ],
+    "env": [
+      "PATH",
+      "HOME",
+      "OLLAMA_MODEL"
+    ]
+  }
+}

package/examples/11-openai.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.openai",
+  "meta": {
+    "name": "tour.openai",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "In one sentence: what is a declared intention?",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_matches": "\\S"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 180,
+      "output_bytes": 1048576,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "/bin/sh",
+      "-c",
+      "if [ -z \"$OPENAI_API_KEY\" ]; then\n  echo \"OPENAI_API_KEY is not set: no request was sent.\" >&2\n  echo \"Store the key once:  jos secrets set OPENAI_API_KEY --stdin\" >&2\n  echo \"Then run:            jos secrets exec --only OPENAI_API_KEY -- jos run 11-openai.jos\" >&2\n  exit 3\nfi\ncommand -v curl >/dev/null 2>&1 || { echo \"curl is not installed\" >&2; exit 4; }\nmodel=\"${OPENAI_MODEL:-gpt-5-mini}\"\nbody=$(node -e 'process.stdout.write(JSON.stringify({ model: process.argv[1], input: process.argv[2] }))' \"$model\" \"$1\") || exit 4\nresp=$(printf \"Authorization: Bearer %s\\n\" \"$OPENAI_API_KEY\" | curl -sS --max-time 150 -H @- -H \"Content-Type: application/json\" -d \"$body\" https://api.openai.com/v1/responses) || { echo \"the request failed (curl exit $?)\" >&2; exit 5; }\nprintf %s \"$resp\" | node -e 'let s = \"\";\nprocess.stdin.on(\"data\", (d) => { s += d; }).on(\"end\", () => {\n  const key = process.env[process.argv[1]] || \"\";\n  const clean = (t) => { let x = String(t); if (key) x = x.split(key).join(\"[key]\"); return x.replace(/(sk-|AIza)[A-Za-z0-9_*-]{6,}/g, \"[key]\"); };\n  let j;\n  try { j = JSON.parse(s); } catch (e) { console.error(\"the API did not answer JSON: \" + clean(s.slice(0, 300))); process.exit(6); }\n  if (j.error) { console.error(\"API error: \" + clean(j.error.message || JSON.stringify(j.error))); process.exit(6); }\n  const text = (j.output || []).flatMap((o) => o.content || []).filter((c) => c.type === \"output_text\").map((c) => c.text).join(\"\");\n  if (!text) { console.error(\"no text in the answer: \" + clean(JSON.stringify(j).slice(0, 300))); process.exit(6); }\n  console.log(text);\n});' OPENAI_API_KEY",
+      "11-openai",
+      "In one sentence: what is a declared intention?"
+    ],
+    "env": [
+      "PATH",
+      "OPENAI_API_KEY",
+      "OPENAI_MODEL"
+    ]
+  }
+}

package/examples/12-gemini.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.gemini",
+  "meta": {
+    "name": "tour.gemini",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "In one sentence: what is a declared intention?",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_matches": "\\S"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 180,
+      "output_bytes": 1048576,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "/bin/sh",
+      "-c",
+      "if [ -z \"$GEMINI_API_KEY\" ]; then\n  echo \"GEMINI_API_KEY is not set: no request was sent.\" >&2\n  echo \"Store the key once:  jos secrets set GEMINI_API_KEY --stdin\" >&2\n  echo \"Then run:            jos secrets exec --only GEMINI_API_KEY -- jos run 12-gemini.jos\" >&2\n  exit 3\nfi\ncommand -v curl >/dev/null 2>&1 || { echo \"curl is not installed\" >&2; exit 4; }\nmodel=\"${GEMINI_MODEL:-gemini-2.5-flash}\"\nbody=$(node -e 'process.stdout.write(JSON.stringify({ contents: [{ parts: [{ text: process.argv[2] }] }] }))' \"$model\" \"$1\") || exit 4\nresp=$(printf \"x-goog-api-key: %s\\n\" \"$GEMINI_API_KEY\" | curl -sS --max-time 150 -H @- -H \"Content-Type: application/json\" -d \"$body\" \"https://generativelanguage.googleapis.com/v1beta/models/$model:generateContent\") || { echo \"the request failed (curl exit $?)\" >&2; exit 5; }\nprintf %s \"$resp\" | node -e 'let s = \"\";\nprocess.stdin.on(\"data\", (d) => { s += d; }).on(\"end\", () => {\n  const key = process.env[process.argv[1]] || \"\";\n  const clean = (t) => { let x = String(t); if (key) x = x.split(key).join(\"[key]\"); return x.replace(/(sk-|AIza)[A-Za-z0-9_*-]{6,}/g, \"[key]\"); };\n  let j;\n  try { j = JSON.parse(s); } catch (e) { console.error(\"the API did not answer JSON: \" + clean(s.slice(0, 300))); process.exit(6); }\n  if (j.error) { console.error(\"API error: \" + clean(j.error.message || JSON.stringify(j.error))); process.exit(6); }\n  const text = ((j.candidates || [])[0] || { content: { parts: [] } }).content.parts.map((p) => p.text || \"\").join(\"\");\n  if (!text) { console.error(\"no text in the answer: \" + clean(JSON.stringify(j).slice(0, 300))); process.exit(6); }\n  console.log(text);\n});' GEMINI_API_KEY",
+      "12-gemini",
+      "In one sentence: what is a declared intention?"
+    ],
+    "env": [
+      "PATH",
+      "GEMINI_API_KEY",
+      "GEMINI_MODEL"
+    ]
+  }
+}

package/examples/13-anthropic.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.anthropic",
+  "meta": {
+    "name": "tour.anthropic",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "In one sentence: what is a declared intention?",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_matches": "\\S"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 180,
+      "output_bytes": 1048576,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "/bin/sh",
+      "-c",
+      "if [ -z \"$ANTHROPIC_API_KEY\" ]; then\n  echo \"ANTHROPIC_API_KEY is not set: no request was sent.\" >&2\n  echo \"Store the key once:  jos secrets set ANTHROPIC_API_KEY --stdin\" >&2\n  echo \"Then run:            jos secrets exec --only ANTHROPIC_API_KEY -- jos run 13-anthropic.jos\" >&2\n  exit 3\nfi\ncommand -v curl >/dev/null 2>&1 || { echo \"curl is not installed\" >&2; exit 4; }\nmodel=\"${ANTHROPIC_MODEL:-claude-opus-5-5}\"\nbody=$(node -e 'process.stdout.write(JSON.stringify({ model: process.argv[1], max_tokens: 1024, messages: [{ role: \"user\", content: process.argv[2] }] }))' \"$model\" \"$1\") || exit 4\nresp=$(printf \"x-api-key: %s\\n\" \"$ANTHROPIC_API_KEY\" | curl -sS --max-time 150 -H @- -H \"anthropic-version: 2023-06-01\" -H \"Content-Type: application/json\" -d \"$body\" https://api.anthropic.com/v1/messages) || { echo \"the request failed (curl exit $?)\" >&2; exit 5; }\nprintf %s \"$resp\" | node -e 'let s = \"\";\nprocess.stdin.on(\"data\", (d) => { s += d; }).on(\"end\", () => {\n  const key = process.env[process.argv[1]] || \"\";\n  const clean = (t) => { let x = String(t); if (key) x = x.split(key).join(\"[key]\"); return x.replace(/(sk-|AIza)[A-Za-z0-9_*-]{6,}/g, \"[key]\"); };\n  let j;\n  try { j = JSON.parse(s); } catch (e) { console.error(\"the API did not answer JSON: \" + clean(s.slice(0, 300))); process.exit(6); }\n  if (j.error) { console.error(\"API error: \" + clean(j.error.message || JSON.stringify(j.error))); process.exit(6); }\n  const text = (j.content || []).filter((c) => c.type === \"text\").map((c) => c.text).join(\"\");\n  if (!text) { console.error(\"no text in the answer: \" + clean(JSON.stringify(j).slice(0, 300))); process.exit(6); }\n  console.log(text);\n});' ANTHROPIC_API_KEY",
+      "13-anthropic",
+      "In one sentence: what is a declared intention?"
+    ],
+    "env": [
+      "PATH",
+      "ANTHROPIC_API_KEY",
+      "ANTHROPIC_MODEL"
+    ]
+  }
+}

package/examples/14-serve.jos

@@ -0,0 +1,88 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "flow"
+  },
+  "id": "tour.serve",
+  "meta": {
+    "name": "tour.serve",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Serve a read-only HTML index of ~/.jos/runs on http://127.0.0.1:8765/ for 60 s, from a temporary folder (never ~/.jos itself)",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "stopped and removed"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf",
+      "curl",
+      "wget"
+    ],
+    "limit": {
+      "seconds": 900,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "orchestration": {
+    "definitions": {
+      "index": {
+        "engine": "shell",
+        "run": [
+          "/bin/sh",
+          "-c",
+          "dir=$(mktemp -d \"${TMPDIR:-/tmp}/jos-runs-index.XXXXXX\") || exit 1\nnode -e 'const fs = require(\"fs\"), path = require(\"path\");\nconst [runs, out] = process.argv.slice(1);\nconst esc = (s) => String(s).replace(/[&<>\"]/g, (c) => ({ \"&\": \"&amp;\", \"<\": \"&lt;\", \">\": \"&gt;\", \"\\\"\": \"&quot;\" })[c]);\nlet ids = [];\ntry { ids = fs.readdirSync(runs).filter((n) => /^run_[0-9A-Za-z]+$/.test(n)).sort().reverse(); } catch (e) { ids = []; }\nconst rows = ids.map((id) => {\n  let es = [];\n  try { es = fs.readFileSync(path.join(runs, id, \"ledger.jsonl\"), \"utf8\").split(\"\\n\").filter(Boolean).map((l) => JSON.parse(l)); } catch (e) { es = []; }\n  const b = (e) => (e && e.body) || {};\n  const end = b(es.find((e) => e.kind === \"end\"));\n  const top = b(es.filter((e) => e.kind === \"receipt\").pop());\n  const cells = [id, top.step || \"\", end.code === undefined ? \"\" : end.code, es.length ? es[0].ts : \"\"];\n  return \"<tr>\" + cells.map((c) => \"<td>\" + esc(c) + \"</td>\").join(\"\") + \"</tr>\";\n});\nfs.writeFileSync(out, \"<!doctype html>\\n<meta charset=\\\"utf-8\\\">\\n<title>jos runs</title>\\n<h1>Runs in ~/.jos/runs</h1>\\n<p>A read-only snapshot. Check a run with <code>jos ledger verify &lt;run_id&gt;</code>.</p>\\n<table>\\n<tr><th>run</th><th>document</th><th>code</th><th>started</th></tr>\\n\" + rows.join(\"\\n\") + \"\\n</table>\\n\");\nconsole.error(ids.length + \" runs indexed\");' \"$HOME/.jos/runs\" \"$dir/index.html\" || { rmdir \"$dir\"; exit 1; }\nprintf %s \"$dir\"",
+          "index"
+        ],
+        "execution": {
+          "env": [
+            "PATH",
+            "HOME",
+            "TMPDIR"
+          ]
+        },
+        "as": "site",
+        "description": "Write index.html for ~/.jos/runs into a new temporary folder"
+      },
+      "serve": {
+        "engine": "shell",
+        "run": [
+          "/bin/sh",
+          "-c",
+          "dir=$(node -e 'let s = \"\"; process.stdin.on(\"data\", (d) => { s += d; }).on(\"end\", () => { process.stdout.write(String(JSON.parse(s).input.dir)); });') || exit 2\ncase \"$dir\" in \"\"|\"$HOME/.jos\"|\"$HOME/.jos/\"*) echo \"refusing to serve $dir\" >&2; exit 2;; esac\n[ -f \"$dir/index.html\" ] || { echo \"no index in $dir\" >&2; exit 2; }\ncommand -v python3 >/dev/null 2>&1 || { echo \"python3 is not installed\" >&2; rm -f \"$dir/index.html\"; rmdir \"$dir\"; exit 3; }\nport=\"${JOS_SERVE_PORT:-8765}\"\nsecs=\"${JOS_SERVE_SECONDS:-60}\"\nlog=\"$dir.log\"\npython3 -u -m http.server \"$port\" --bind 127.0.0.1 --directory \"$dir\" >\"$log\" 2>/dev/null &\npid=$!\nn=0\nuntil grep -q '^Serving HTTP on' \"$log\" 2>/dev/null; do\n  if ! kill -0 \"$pid\" 2>/dev/null; then echo \"python3 could not serve on 127.0.0.1:$port (is the port in use?)\" >&2; rm -f \"$dir/index.html\" \"$log\"; rmdir \"$dir\"; exit 1; fi\n  if [ \"$n\" -ge 600 ]; then echo \"python3 did not start serving on 127.0.0.1:$port within 60 s\" >&2; kill \"$pid\" 2>/dev/null; wait \"$pid\" 2>/dev/null; rm -f \"$dir/index.html\" \"$log\"; rmdir \"$dir\"; exit 1; fi\n  n=$((n + 1))\n  sleep 0.1\ndone\nsleep \"$secs\"\nkill \"$pid\" 2>/dev/null\nwait \"$pid\" 2>/dev/null\nrm -f \"$dir/index.html\" \"$log\"\nrmdir \"$dir\"\necho \"served a read-only index of ~/.jos/runs from $dir on http://127.0.0.1:$port/ for $secs s; stopped and removed it\"",
+          "serve"
+        ],
+        "execution": {
+          "env": [
+            "PATH",
+            "HOME",
+            "JOS_SERVE_PORT",
+            "JOS_SERVE_SECONDS"
+          ]
+        },
+        "needs": [
+          "index"
+        ],
+        "with": {
+          "dir": "{{ site }}"
+        },
+        "description": "python3 -m http.server --bind 127.0.0.1 on that folder, counted from the moment it says it is serving, then remove it"
+      }
+    },
+    "flows": {
+      "main": {
+        "steps": [
+          "index",
+          "serve"
+        ]
+      }
+    }
+  }
+}

package/examples/README.md

@@ -0,0 +1,105 @@
+# The tour
+
+Each example is one capability of `jos`, and each one runs. Copy the folder first, so the runs do not write into
+the installed package (a run of `05-sealed` keeps its ledger in `05-sealed/.jos/replays/`; the others in
+`~/.jos/runs/`):
+
+```
+cp -R "$(npm root -g)/@josfox/jos/examples" jos-tour && cd jos-tour
+```
+
+Every `jos run` prints the document's intention before it runs (`Intention`, `Done when`, `Avoid`, `Limit`), then
+the verdict of each criterion as jos-core evaluated it, then `Intention met` or `Intention NOT met (code N: …)`.
+`--json` prints jos-core's result object instead, unchanged.
+
+| Example | Command | Result |
+|---|---|---|
+| `01-hello.jos` | `jos run 01-hello.jos` | prints `hello, .jos`; `✓ Intention met`; exit 0 |
+| `02-criteria.jos` | `jos run 02-criteria.jos` | one verdict line per criterion: `exit`, `stdout_contains`, `stdout_matches`, `stderr_empty`, `not`, and a descriptive one (recorded, never evaluated); exit 0. Change the `echo` text and it is exit 1 |
+| `03-flow-gate.jos` | `jos run 03-flow-gate.jos` | `build` runs, the human gate stops the flow: `Intention NOT met (code 1: not done)` and the command to approve; exit 1 |
+| | `jos run 03-flow-gate.jos --approve build` | `build`, then `publish`; prints `published`; exit 0 |
+| | `jos run 03-flow-gate.jos --flow build-only` | runs the other flow of the document (`build` only); exit 0 |
+| `04-use-template/` | `jos run 04-use-template/use.jos --library 04-use-template/lib` | one template, used twice with `with`, pinned by its digest; prints `hello, Leo`; exit 0. See [its README](04-use-template/README.md) |
+| | `jos run 04-use-template/lib/greeting.jos --with '{"name":"Ana"}'` | the template run directly; prints `hello, Ana`; exit 0 |
+| `05-sealed/` | `jos run 05-sealed` | the folder runs while its hash matches `integrity.hash`; exit 0. Edit it and it is exit 3. See [its README](05-sealed/README.md) |
+| `06-requires.jos` | `jos run 06-requires.jos` | needs a `payments` service this runtime does not provide: refused before anything starts, `/requires/0: not satisfied`; exit 5 |
+| `07-sandbox.jos` | `jos run 07-sandbox.jos` | `security.tier: sandbox`, and this kernel cannot confine a process: refused, `sandbox not available`; exit 5 |
+| `08-ids-ledger-meter.md` | the commands in it | `jos ids`, `jos runs`, `jos ledger verify`, `jos meter` over the runs above |
+| `10-ollama.jos` | `jos run 10-ollama.jos` | checks `http://localhost:11434`; without Ollama it says so and sends nothing (exit 1); with Ollama the objective goes to `ollama run ${OLLAMA_MODEL:-llama3.2}` and the answer is printed (exit 0) |
+| `11-openai.jos` | `jos secrets exec --only OPENAI_API_KEY -- jos run 11-openai.jos` | the objective to the OpenAI Responses API (`${OPENAI_MODEL:-gpt-5-mini}`); prints the answer; exit 0. Without the key: `OPENAI_API_KEY is not set: no request was sent.`, exit 1 |
+| `12-gemini.jos` | `jos secrets exec --only GEMINI_API_KEY -- jos run 12-gemini.jos` | the same with the Gemini API (`${GEMINI_MODEL:-gemini-2.5-flash}`) |
+| `13-anthropic.jos` | `jos secrets exec --only ANTHROPIC_API_KEY -- jos run 13-anthropic.jos` | the same with the Anthropic Messages API (`${ANTHROPIC_MODEL:-claude-opus-5-5}`) |
+| `14-serve.jos` | `jos run 14-serve.jos` | writes a read-only HTML index of `~/.jos/runs` into a new temporary folder and serves only that folder with `python3 -m http.server --bind 127.0.0.1` on port `${JOS_SERVE_PORT:-8765}` for `${JOS_SERVE_SECONDS:-60}` seconds, counted from the moment python3 says it is serving (it may take a few seconds to listen; at most 60 s), then removes it; exit 0 |
+
+`hello.jos` is the document `jos verify` runs.
+
+## The provider examples and your keys
+
+`11`, `12` and `13` are shell steps that call the provider's REST API with `curl`. They are paid calls on your
+account. Store a key once, then give it only to the run that needs it:
+
+```
+jos secrets set OPENAI_API_KEY --stdin          # type or paste the key; it is not echoed
+jos secrets exec --only OPENAI_API_KEY -- jos run 11-openai.jos
+```
+
+What happens to the key: `jos secrets exec` puts it only in the environment of that `jos run`; the document's
+`execution.env` lets it reach the step; the step hands it to `curl` on stdin (`-H @-`), so it is never on a command
+line; the examples never print it, and an error message from the API is printed with the key replaced by `[key]`.
+The key is not in the receipts or the ledger: a receipt records the step's code, its criteria verdicts and hashes
+of its input and output, never the environment (the test suite checks the ledger, the result and the output for
+the key). The answer itself is printed
+to your terminal and not stored. The model's tokens and cost are not recorded either: the `shell` engine does not
+report them, so `jos meter` shows them as "not reported".
+
+## What `jos run` prints (NO_COLOR)
+
+```
+$ jos run 03-flow-gate.jos
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JOS RUN // jos-core 2.0.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  File: 03-flow-gate.jos
+
+Intention: Build, wait for a person to approve the build, then publish
+Done when:
+  • exit 0
+Avoid: "rm -rf"
+Limit: 10 s, 65536 output bytes per stream, 0 retries
+
+  ID: art_572a58662e9e76761b6844bfd091ed08636023e39ce10cd13dc1cdf463741d96
+  Input version: 2.0.0
+  Capability: cap_01M5DX8R8WT15PS3SQV70CV2PM (local-trusted)
+  Ledger: ~/.jos/runs/run_01M5DX8R8TCEQ2D7DESRZQH8JG/ledger.jsonl
+
+built
+
+Verdict:
+  [1] build ✓ code 0
+    ✓ stdout_contains: found
+  [1] tour.flow-gate (flow main) ✖ code 1
+    ✓ exit: exit 0 (want 0)
+
+✖ Intention NOT met (code 1: not done) (run_01M5DX8R8TCEQ2D7DESRZQH8JG)
+  gate human: waiting for an approval of "build"
+  To approve it: jos run 03-flow-gate.jos --approve build
+
+$ jos run 03-flow-gate.jos --approve build
+…
+published
+
+Verdict:
+  [1] build ✓ code 0
+    ✓ stdout_contains: found
+  [1] publish ✓ code 0
+    ✓ stdout_contains: found
+  [1] tour.flow-gate (flow main) ✓ code 0
+    ✓ exit: exit 0 (want 0)
+
+✓ Intention met (code 0, run_01M5DX8R9YSZT1S7GKJJJNS9MM)
+```
+
+The `run_` and `cap_` ids and the ledger path are yours; the `art_` is the same on every machine and in both
+reference kernels, because it is the hash of the document's content.