stageflow 0.36.0 → 0.40.0

package/dist/ui/chat.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en" data-redesign="on" data-theme="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <meta name="robots" content="noindex, nofollow" />
+    <meta name="color-scheme" content="dark light" />
+    <script>
+      try {
+        var light = window.matchMedia && window.matchMedia("(prefers-color-scheme: light)").matches;
+        document.documentElement.setAttribute("data-theme", light ? "light" : "dark");
+      } catch (e) {}
+    </script>
+    <link rel="icon" type="image/svg+xml" href="/stageflow-icon.svg" />
+    <title>Chat</title>
+    <script type="module" crossorigin src="/assets/chat-BbLukq9W.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-iVoFAvQ_.js">
+    <link rel="modulepreload" crossorigin href="/assets/ReadonlyStore-BfXqHykm.js">
+    <link rel="modulepreload" crossorigin href="/assets/AssistantRuntimeProvider-CsiPFhCT.js">
+    <link rel="stylesheet" crossorigin href="/assets/chat-zIZU_bP1.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/ui/index.html

@@ -13,8 +13,12 @@
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap" />
     <link rel="icon" type="image/svg+xml" href="/stageflow-icon.svg" />
     <title>Stageflow</title>
-    <script type="module" crossorigin src="/assets/index-BOhqnPNg.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Clv4sJpU.css">
+    <script type="module" crossorigin src="/assets/main-CijYMeM0.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-iVoFAvQ_.js">
+    <link rel="modulepreload" crossorigin href="/assets/ReadonlyStore-BfXqHykm.js">
+    <link rel="modulepreload" crossorigin href="/assets/AssistantRuntimeProvider-CsiPFhCT.js">
+    <link rel="modulepreload" crossorigin href="/assets/Tooltip-DrpoRRNi.js">
+    <link rel="stylesheet" crossorigin href="/assets/main-BFo79krC.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/workshop/modelSettings.d.ts

@@ -1,11 +1,11 @@
-export declare const DEFAULT_WORKSHOP_MODEL = "cursor/auto";
 export type ResolveWorkshopModelInput = {
     sessionOverride?: string | null;
     settingsDefault?: string | null;
     profileDefault?: string | null;
 };
 /**
- * Effective Workshop chat model: session override → Settings default → profile fallback.
+ * Effective Workshop chat model: session override → Settings default → profile fallback → the
+ * model catalog's default.
  * Credentials stay on the shared Stageflow provider auth stack; this only picks a model id.
  */
 export declare function resolveWorkshopModel(input?: ResolveWorkshopModelInput): string;

package/dist/workshop/modelSettings.js

@@ -1,9 +1,7 @@
-import { globalModelFromManifest } from "../config/resolveModel.js";
-import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
-import { readFactorySettings } from "../runtime/settingsFile.js";
-export const DEFAULT_WORKSHOP_MODEL = "cursor/auto";
+import { getModelCatalog, peekDefaultModel } from "../models/catalog.js";
 /**
- * Effective Workshop chat model: session override → Settings default → profile fallback.
+ * Effective Workshop chat model: session override → Settings default → profile fallback → the
+ * model catalog's default.
  * Credentials stay on the shared Stageflow provider auth stack; this only picks a model id.
  */
 export function resolveWorkshopModel(input = {}) {
@@ -16,7 +14,7 @@ export function resolveWorkshopModel(input = {}) {
     const profile = normalizeModelId(input.profileDefault);
     if (profile)
         return profile;
-    return DEFAULT_WORKSHOP_MODEL;
+    return peekDefaultModel();
 }
 export function parseWorkshopModel(value) {
     if (typeof value !== "string")
@@ -30,11 +28,7 @@ export function parseWorkshopModel(value) {
  * when the manifest has none.
  */
 export async function readWorkshopOpenModel(cwd) {
-    const ctx = await resolveStageflowContext(cwd);
-    return resolveWorkshopModel({
-        settingsDefault: globalModelFromManifest(ctx.manifest) ??
-            readFactorySettings(cwd).workshopModel,
-    });
+    return getModelCatalog(cwd).defaultModel();
 }
 function normalizeModelId(value) {
     if (typeof value !== "string")

package/examples/README.md

@@ -44,6 +44,7 @@ More CI-focused examples will follow this pattern (prepare context → run pipel
 | [verify-tour](verify-tour/) | Verify check types: artifact, command, checklist, payload_schema, gate, checkout_changes | `sf ui`, then pick `verify-tour` |
 | [retry-tour](retry-tour/) | Retry surfaces: emit soft-reject, automatic repair, manual recover, ordinary Retry | `sf ui`, then pick `retry-tour` |
 | [mcp-hitl-tour](mcp-hitl-tour/) | MCP HITL tour: free_text gate, ungated fan-out + Clone Chain join, wait_for_human loop, artifacts | `sf ui` / MCP `start_run`, then [README](mcp-hitl-tour/README.md) |
+| [memory](memory/) | Two pipelines share one data-directory page: one writes a line, the next run reads it | Create `notebook` first, then [README](memory/README.md) |
 
 Current wiring tours: [`route-wiring-smoke-test`](route-wiring-smoke-test/), [`route-if-tour`](route-if-tour/).
 

package/examples/channels-smoke/README.md

@@ -2,10 +2,21 @@
 
 Two stages, one channel each: `send-email` sends one email (AgentMail) and then `send-text` sends one text (iMessage via Photon), through the connections on the Connections page. A stage can use one channel, so the two are separate stages. Nothing is sent until you start a run.
 
+This example is **excluded** from the repo-root catalog manifest (see `stageflow.yaml`) so host-only Connections do not fail `sf validate --strict` or release CI. It remains loadable by explicit path.
+
 1. Connect AgentMail and iMessage on the Connections page. The stage expects the connection ids `agentmail` and `imessage`; if yours differ, edit `connection:` in the two stage files.
 2. Pin your recipients: in `send-email.yaml` replace `to: [change-me@example.invalid]` with your email, and in `send-text.yaml` replace `to: "+10000000000"` with your phone in E.164 form (for example `+14155550123`). On a Free or Pro Photon project the phone must be a project user, and that person must have texted their assigned Photon line once, or the send is rejected.
 3. Change `model:` to one you have a provider for.
-4. Run `sf validate` on the pipeline, then open `channels-smoke` in the console and start it with `channels-smoke-task`. The run checks both connections live before the stage starts.
+4. From the repo root, validate and run by path (Connections must already exist):
+
+```bash
+sf validate --strict --pipeline examples/channels-smoke/channels-smoke.pipeline.yaml
+sf run \
+  --pipeline examples/channels-smoke/channels-smoke.pipeline.yaml \
+  --task examples/channels-smoke/channels-smoke.task.yaml
+```
+
+Or open the console and start `channels-smoke` with `channels-smoke-task` after loading the pipeline by path. The run checks both connections live before the stage starts.
 
 The Claude agent backend does not provide `send_message`; use a Pi model (the default).
 

package/examples/github-release/README.md

@@ -47,7 +47,7 @@ DRY_RUN=1 bash scripts/run-github-release-local.sh
 Manual equivalent:
 
 ```bash
-sf validate --strict
+sf validate --strict --pipeline examples/github-release/github-release.pipeline.yaml
 export CURSOR_API_KEY=…   # no trailing newline; or use repo-root .env
 export GH_TOKEN=…
 CURRENT="$(node -p "require('./package.json').version")"

package/examples/memory/README.md

@@ -0,0 +1,101 @@
+# memory
+
+Two pipelines share one memory, `notebook`, in the data directory. `remember` adds a line to the cover page. `recall` only reads the cover, so a later run can see what an earlier run wrote. `notebook` is the memory id. It is not a card key.
+
+Create the memory before either pipeline runs. A run does not create it. `missing.pipeline.yaml` names an id that is not there, so validate fails and a run does not start.
+
+## Create the memory
+
+With `sf ui` running:
+
+```bash
+curl -sS -X POST http://127.0.0.1:3847/api/memories \
+  -H 'Origin: http://127.0.0.1:3847' \
+  -H 'Content-Type: application/json' \
+  -d '{"id":"notebook","description":"Lines this pipeline has already recorded."}'
+```
+
+Or use **Memories** in the console. The id is `notebook`. `memory.yaml` stays version 1. The cover is `body.md`. Cards live beside it.
+
+## Run the cover
+
+From the repository root, after the memory exists:
+
+```bash
+sf validate --pipeline examples/memory/remember.pipeline.yaml --strict
+sf run \
+  --pipeline examples/memory/remember.pipeline.yaml \
+  --task examples/memory/remember-ada.task.yaml
+
+sf run \
+  --pipeline examples/memory/remember.pipeline.yaml \
+  --task examples/memory/remember-grace.task.yaml
+
+sf run \
+  --pipeline examples/memory/recall.pipeline.yaml \
+  --task examples/memory/recall.task.yaml
+```
+
+The cover is `$STAGEFLOW_HOME/memories/notebook/body.md`. After the two remember runs it should contain both lines (`Ada was sourced.` and `Grace was shortlisted.`). Recall's envelope `page` should match that file. Replacing the cover does not delete cards.
+
+```bash
+sf validate --pipeline examples/memory/missing.pipeline.yaml --strict
+```
+
+That command fails with `pipeline.memory_unavailable`.
+
+## Cards
+
+`file-card` adds one card. `update-card` replaces that card. `find-card` reads it, searches the current cards, and reads the cover without changing either. All three attach `notebook`. Run them in that order, after the memory exists. The cover runs above are optional. A stage cannot delete a card.
+
+```bash
+sf run \
+  --pipeline examples/memory/file-card.pipeline.yaml \
+  --task examples/memory/file-ticket.task.yaml
+
+sf run \
+  --pipeline examples/memory/find-card.pipeline.yaml \
+  --task examples/memory/find-ticket.task.yaml
+
+sf run \
+  --pipeline examples/memory/update-card.pipeline.yaml \
+  --task examples/memory/update-ticket.task.yaml
+
+sf run \
+  --pipeline examples/memory/find-card.pipeline.yaml \
+  --task examples/memory/find-ticket.task.yaml
+```
+
+The first find should return the filed note for `TICKET-1842` and a search hit for `refund`. The second find should return the updated note. The cover text should be unchanged by these four runs. Add refuses a key that already exists, so a second `file-card` run of the same task fails. Update refuses a key that is missing.
+
+`remember` and `recall` attach the same memory, so they can call the card tools too. Their tasks only use the cover. The prompt lists the memory id and its description, not the cover or any card body. The session never receives a filesystem path.
+
+Search is a case-insensitive word scan of the current keys and bodies, at most 20 hits, snippet only.
+
+## A desk with several cards
+
+`desk` files every card in the task, updates only the focus key, then reads the cover and the other cards back. `desk-revisit` does that update on a later run, after the cards already exist. Both attach `new-notebook`. Create that memory in the console before the first run.
+
+`desk-outage` uses a ticket id, a release path (`releases/2.4.1`), and an email. `desk-refund` uses a different ticket, an order path (`orders/4412/refund`), and a different email, so it can run beside the outage without sharing a key. Run each `desk` task once. A second run fails because add refuses a key that already exists.
+
+```bash
+sf run \
+  --pipeline examples/memory/desk.pipeline.yaml \
+  --task examples/memory/desk-outage.task.yaml
+
+sf run \
+  --pipeline examples/memory/desk-revisit.pipeline.yaml \
+  --task examples/memory/desk-revisit-outage.task.yaml
+```
+
+After `desk-outage`, the release card should be the hold-the-deploy decision. `TICKET-1904` and `ada@example.com` should still be the original notes. The last stage's `cover_same` should be `yes`.
+
+After `desk-revisit-outage`, the release card should be the rollback-finished note, and the previous copy in **Memories** should be the hold-the-deploy decision. The ticket and the email card should still be the original notes. `cover_same` should stay `yes`.
+
+`desk-refund` is the same pipeline with a second set of keys. Run it on its own, not after those keys already exist. Search during that run looks for `reviewer`, which is only in the email card, while the card that gets updated is the order path.
+
+The operator, in **Memories**, can list keys, open the `TICKET-1842` card, correct it, and delete it. Delete removes the current card and the previous copy and cannot be undone. The page shows the previous card copy and the previous cover text when they exist. The operator can edit the cover. The operator does not create cards; a session adds them. There is one previous copy, not a full history, and no restore action.
+
+`sandbox-memory-bash` is the sandbox probe. It attaches `shared-notes` and its `probe` stage runs one bash command, then reports whether that command printed a `body.md` path. The task is `probe-bash`. Create `shared-notes` before running it. Edit the `probe` stage prompt in the pipeline file.
+
+This directory is excluded from the repo-root catalog scan, because those commands fail until `notebook` exists.

package/examples/memory/desk-outage.task.yaml

@@ -0,0 +1,15 @@
+id: desk-outage
+goal: File three notes for one incident, then record the rollback decision on the release card only
+context: The memory new-notebook already exists. None of these card keys exist yet. The cover page is a separate instruction and must stay as it is.
+constraints: Do not delete a card. Do not replace the cover. Update only the focus key.
+input:
+  focus: releases/2.4.1
+  decision: Rollback is the plan. Hold the deploy until payments confirms the migration.
+  query: pager
+  cards:
+    - key: TICKET-1904
+      note: Checkout returns 502 for EU customers since 14:10 UTC.
+    - key: releases/2.4.1
+      note: Rollback is blocked on the payments migration.
+    - key: ada@example.com
+      note: On-call pager owner for the checkout outage.

package/examples/memory/desk-refund.task.yaml

@@ -0,0 +1,15 @@
+id: desk-refund
+goal: File a refund, the order path, and the reviewer, then record the payout on the order path only
+context: The memory new-notebook already exists. None of these card keys exist yet. Run this only if desk-outage has not already used these keys.
+constraints: Do not delete a card. Do not replace the cover. Update only the focus key.
+input:
+  focus: orders/4412/refund
+  decision: Store credit was declined. The refund was paid to the original card.
+  query: reviewer
+  cards:
+    - key: TICKET-2040
+      note: Customer asked for store credit on order 4412.
+    - key: orders/4412/refund
+      note: Refund is waiting on a reviewer.
+    - key: grace@example.com
+      note: Refund reviewer for order 4412.

package/examples/memory/desk-revisit-outage.task.yaml

@@ -0,0 +1,11 @@
+id: desk-revisit-outage
+goal: Change the release card again and leave the ticket and the pager owner alone
+context: desk-outage has already filed TICKET-1904, releases/2.4.1, and ada@example.com. This run only replaces the release card.
+constraints: Do not add a card. Do not replace the cover. Do not update TICKET-1904 or ada@example.com.
+input:
+  focus: releases/2.4.1
+  decision: Rollback finished at 16:40 UTC. Checkout 502s stopped after the payments migration was reverted.
+  query: "502"
+  neighbors:
+    - TICKET-1904
+    - ada@example.com

package/examples/memory/desk-revisit.pipeline.yaml

@@ -0,0 +1,123 @@
+id: desk-revisit
+memories:
+  - new-notebook
+stages:
+  - id: revise-one
+    entry: true
+    route:
+      - to: check-neighbors
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "focus", "decision", "query", and "neighbors". "neighbors" is a list of keys that must not change.
+      Do these steps in order, then stop:
+      1. Call read_memory with memory "new-notebook".
+      2. Call search_memory_cards with memory "new-notebook" and the query.
+      3. Call read_memory_card with memory "new-notebook" and the focus key.
+      4. For each neighbor key, call read_memory_card with memory "new-notebook" and that key.
+      5. Call update_memory_card with memory "new-notebook", the focus key, and content set to the decision. Do not update a neighbor.
+      6. Call read_memory_card again for the focus key.
+      7. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"cover":"<the exact cover>","focus":"<focus>","decision":"<decision>","before":"<the focus body before the update>","after":"<the focus body after the update>","neighbors":"<one line per neighbor, as key then a tab then the body you read before the update>","hits":"<the search result as JSON text>"}.
+      Do not call add_memory_card or replace_memory. Do not write files. If the focus card is missing, emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - focus
+            - decision
+            - query
+            - neighbors
+          properties:
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+            neighbors:
+              type: array
+              minItems: 1
+              items:
+                type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - cover
+            - focus
+            - decision
+            - before
+            - after
+            - neighbors
+            - hits
+          properties:
+            cover:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            before:
+              type: string
+            after:
+              type: string
+            neighbors:
+              type: string
+            hits:
+              type: string
+          additionalProperties: false
+  - id: check-neighbors
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The input has "cover", "focus", "decision", "neighbors", and "after".
+      "neighbors" is lines of "key<tab>body" from before the update.
+      Do these steps in order, then stop:
+      1. Call read_memory with memory "new-notebook".
+      2. Call read_memory_card with memory "new-notebook" and the focus key.
+      3. For each neighbor key, call read_memory_card with memory "new-notebook" and that key.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"focus":"<focus>","after":"<the focus body you just read>","untouched":"<one line per neighbor, as key then a tab then the body you just read>","page":"<the exact cover>","cover_same":"yes or no"}.
+      Set cover_same to yes only when the cover equals the "cover" you were given. The focus body should equal "decision". Each neighbor body should equal the body on its line in "neighbors". Do not call add_memory_card, update_memory_card, or replace_memory. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - cover
+            - focus
+            - decision
+            - neighbors
+            - after
+          properties:
+            cover:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            neighbors:
+              type: string
+            after:
+              type: string
+          additionalProperties: true
+      output:
+        schema:
+          type: object
+          required:
+            - focus
+            - after
+            - untouched
+            - page
+            - cover_same
+          properties:
+            focus:
+              type: string
+            after:
+              type: string
+            untouched:
+              type: string
+            page:
+              type: string
+            cover_same:
+              type: string
+          additionalProperties: false

package/examples/memory/desk.pipeline.yaml

@@ -0,0 +1,192 @@
+id: desk
+memories:
+  - new-notebook
+stages:
+  - id: file-batch
+    entry: true
+    route:
+      - to: decide
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "focus", "decision", "query", and "cards". "cards" is a list of objects with "key" and "note".
+      Do these steps in order, then stop:
+      1. Call read_memory with memory "new-notebook". Keep that text. Do not call replace_memory.
+      2. For each card, in order, call add_memory_card with memory "new-notebook", that key, and content set to that note. A key may contain "/", spaces, or "@". Pass it through unchanged.
+      3. For each card, call read_memory_card with memory "new-notebook" and that key. The body must equal the note you just wrote.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"cover":"<the exact read_memory text>","filed":"<a JSON array of {key, note} for every card, in the same order>","focus":"<focus>","decision":"<decision>","query":"<query>"}.
+      Do not call update_memory_card. Do not call any memory id other than new-notebook. Do not write files. If any add_memory_card fails, stop and emit status failure. Do not keep filing after a failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - focus
+            - decision
+            - query
+            - cards
+          properties:
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+            cards:
+              type: array
+              minItems: 2
+              items:
+                type: object
+                required:
+                  - key
+                  - note
+                properties:
+                  key:
+                    type: string
+                  note:
+                    type: string
+                additionalProperties: false
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - cover
+            - filed
+            - focus
+            - decision
+            - query
+          properties:
+            cover:
+              type: string
+            filed:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+          additionalProperties: false
+  - id: decide
+    route:
+      - to: audit
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The input has "cover", "filed", "focus", "decision", and "query".
+      Do these steps in order, then stop:
+      1. Call search_memory_cards with memory "new-notebook" and the query. Do not treat a short hit list as permission to skip a card. There may be more matches than the tool returns.
+      2. Call read_memory_card with memory "new-notebook" and the focus key.
+      3. Call update_memory_card with memory "new-notebook", the focus key, and content set to the decision. This replaces the whole card. Do not update any other key.
+      4. Call read_memory_card again with memory "new-notebook" and the focus key.
+      5. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"cover":"<the cover you were given, unchanged>","filed":"<the filed text you were given, unchanged>","focus":"<focus>","decision":"<decision>","query":"<query>","before":"<the first read of the focus card>","after":"<the second read of the focus card>","hits":"<the search result as JSON text>"}.
+      Do not call add_memory_card or replace_memory. Do not call any memory id other than new-notebook. Do not write files. If the focus card is missing, emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - cover
+            - filed
+            - focus
+            - decision
+            - query
+          properties:
+            cover:
+              type: string
+            filed:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - cover
+            - filed
+            - focus
+            - decision
+            - query
+            - before
+            - after
+            - hits
+          properties:
+            cover:
+              type: string
+            filed:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+            before:
+              type: string
+            after:
+              type: string
+            hits:
+              type: string
+          additionalProperties: false
+  - id: audit
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The input has "cover", "filed", "focus", "decision", "before", and "after".
+      "filed" is a JSON array of objects with "key" and "note".
+      Do these steps in order, then stop:
+      1. Call read_memory with memory "new-notebook".
+      2. Call read_memory_card with memory "new-notebook" and the focus key.
+      3. For every other key in "filed", call read_memory_card with memory "new-notebook" and that key.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"focus":"<focus>","after":"<the focus card body you just read>","untouched":"<one line per other key, as key then a tab then the body>","page":"<the exact cover you just read>","cover_same":"yes or no"}.
+      Set cover_same to yes only when the cover you just read is exactly the "cover" you were given. Set it to no otherwise.
+      The focus body should equal "decision". Each other body should equal the note in "filed" for that key. Do not call add_memory_card, update_memory_card, or replace_memory. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - cover
+            - filed
+            - focus
+            - decision
+            - before
+            - after
+          properties:
+            cover:
+              type: string
+            filed:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            before:
+              type: string
+            after:
+              type: string
+          additionalProperties: true
+      output:
+        schema:
+          type: object
+          required:
+            - focus
+            - after
+            - untouched
+            - page
+            - cover_same
+          properties:
+            focus:
+              type: string
+            after:
+              type: string
+            untouched:
+              type: string
+            page:
+              type: string
+            cover_same:
+              type: string
+          additionalProperties: false

package/examples/memory/file-card.pipeline.yaml

@@ -0,0 +1,39 @@
+id: file-card
+stages:
+  - id: file
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "note".
+      Do these steps in order, then stop:
+      1. Call add_memory_card with memory "notebook", that key, and content set to the note.
+      2. Call read_memory_card with memory "notebook" and that key.
+      3. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","note":"<the exact text read_memory_card returned>"}.
+      Do not call replace_memory. Do not call update_memory_card. Do not call any memory id other than notebook. Do not write files. If add_memory_card returns MEMORY_CARD_EXISTS, stop and emit status failure with the same payload shape and the error code in the summary.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+memories:
+  - notebook

package/examples/memory/file-ledger.task.yaml

@@ -0,0 +1,22 @@
+id: file-ledger
+goal: File the refund ledger as a card, keeping the table
+context: Memory new-notebook already exists. This key does not.
+constraints: The card body is the note exactly. Do not change the cover.
+input:
+  key: orders/4412/ledger
+  note: |
+    # Refund ledger — order 4412
+
+    Customer asked for store credit. Finance paid the original card instead.
+
+    | When | Who | Action | Amount |
+    | --- | --- | --- | --- |
+    | 2026-10-18 09:12 | grace@example.com | Request opened | 86.40 USD |
+    | 2026-10-18 11:04 | TICKET-2040 | Store credit declined | — |
+    | 2026-10-19 16:22 | payments | Paid to original card | 86.40 USD |
+
+    Still open:
+
+    - [ ] Customer confirmed the payout
+    - [x] Reviewer recorded the decline
+    - [ ] Receipt attached to the ticket