yaml-flow 5.2.5 → 5.2.8

package/examples/example-board/agent-instructions.md

@@ -38,7 +38,7 @@ vocabulary:
 
   "requires": ["token-a", "token-b"],
 
-  "sources": [
+  "source_defs": [
     { "bindTo": "raw", "outputFile": "my-card-raw.json", /* task-executor fields */ }
   ],
 
@@ -47,7 +47,7 @@ vocabulary:
   ],
 
   "provides": [
-    { "bindTo": "published-token", "src": "computed_values.result" }
+    { "bindTo": "published-token", "ref": "computed_values.result" }
   ],
 
   "view": {
@@ -74,9 +74,10 @@ vocabulary:
   - `outputFile` → where the fetched result is cached
   - `customFields` → interpreted by the registered **task-executor** (examples: `mock`, `copilot`, `http`, `script`)
 - Produces: `fetched_sources.*`
+- **`source_defs` is NOT a valid data namespace** — it is the config array of source definitions. Use `fetched_sources.*` to reference fetched data.
 
 ### Stage 2 — Compute
-- **Runs after sources.** Reads `requires.*`, `fetched_sources.*`, `card_data.*`.
+- **Runs after source_defs.** Reads `requires.*`, `fetched_sources.*`, `card_data.*`.
 - Each entry: `{ "bindTo": "key", "expr": "<JSONata>" }`
 - Produces: `computed_values.*`
 
@@ -84,7 +85,7 @@ vocabulary:
 - **Resolved last.** Can reference all four namespaces:
   `requires.*`, `fetched_sources.*`, `card_data.*`, `computed_values.*`
 - `view.elements[].data.bind` paths are resolved here.
-- `provides[].src` paths are resolved here and published to the graph.
+- `provides[].ref` paths are resolved here and published to the graph.
 
 ---
 
@@ -93,9 +94,9 @@ vocabulary:
 ```json
 // Publishing a token:
 "provides": [
-  { "bindTo": "orders",      "src": "fetched_sources.raw" },
-  { "bindTo": "regionTotals","src": "computed_values.byRegion" },
-  { "bindTo": "my-card",     "src": "card_data" }
+  { "bindTo": "orders",      "ref": "fetched_sources.raw" },
+  { "bindTo": "regionTotals","ref": "computed_values.byRegion" },
+  { "bindTo": "my-card",     "ref": "card_data" }
 ]
 
 // Consuming tokens:
@@ -124,7 +125,7 @@ Every card is a live entity. Any of these events triggers automatic recompute of
 
 ## Task Completion
 
-Task completion is determined by one rule: **a card is complete when all non-optional `sources[]` have been fetched**.
+Task completion is determined by one rule: **a card is complete when all non-optional `source_defs[]` have been fetched**.
 
 If completion requires a judgment call — e.g. "is the data sufficient?", "does this narrative indicate done?" — model it as data using the standard source → compute → provides chain (see LLM source pattern below). The card is complete when that source has been fetched.
 
@@ -272,14 +273,131 @@ Alert/callout display element.
 ### `custom`
 Custom element kind — behaviour defined by the host application.
 
+### `ref`
+Indirection element that resolves its rendered kind at runtime from any namespace variable. The card author declares the data source (`bind`) and where to look up the view definition (`viewBind`). The resolved view definition can come from `card_data` (user-selectable UI), `fetched_sources` (LLM-suggested), `requires` (cross-card), or `computed_values`.
+
+**Resolved value shape:**
+- A **string** — used directly as the element kind: `"table"`, `"chart"`, `"editable-table"`, etc.
+- An **object** — `{ kind, label, data: { columns, chartType, chartOptions, writeTo, ... } }` — merged with the static elemDef (static fields always win, so card authors can fence LLM suggestions).
+- `null`/`undefined` — falls back to `fallbackKind` or shape inference (`array→table`, `string→text`, `object→narrative`).
+
+**Allowed kind values** (whitelist; unknown values fall to `table`):
+`table`, `editable-table`, `chart`, `metric`, `list`, `badge`, `text`, `narrative`, `markdown`, `form`, `filter`, `todo`, `alert`
+
+```json
+{ "kind": "ref",
+  "label": "Trade Data",
+  "data": {
+    "bind": "fetched_sources.rebalance.proposed_trades",
+    "viewBind": "card_data.display_mode",
+    "fallbackKind": "table"
+  }
+}
+```
+
+**Pattern 1 — User-selectable view (selector pattern)**
+
+Pair a `form` element with a `ref` element. The form writes the chosen kind into `card_data`; the `ref` reads it back. The user can switch between table, chart, etc. with no card JSON changes:
+
+```json
+{ "kind": "form",
+  "data": {
+    "writeTo": "card_data.display_mode",
+    "fields": {
+      "type": "object",
+      "properties": {
+        "kind": { "type": "string", "title": "Display as",
+                  "enum": ["table", "chart", "editable-table"] }
+      }
+    }
+  }
+},
+{ "kind": "ref",
+  "data": {
+    "bind": "fetched_sources.rebalance.proposed_trades",
+    "viewBind": "card_data.display_mode",
+    "fallbackKind": "table"
+  }
+}
+```
+
+Note: `card_data.display_mode` can be a plain string (`"chart"`) or an object (`{ "kind": "chart", ... }`). Both are handled.
+
+**Pattern 2 — LLM-suggested view (source carries `_view`)**
+
+The LLM source response includes a `_view` key alongside the data. The `ref` element reads `_view` from the source namespace. The LLM decides chart vs table vs editable-table at runtime based on what the data looks like:
+
+```json
+// LLM returns:
+{ "proposed_trades": [ {"ticker": "AAPL", "trade_value": 1084} ],
+  "_view": { "kind": "chart", "data": { "chartType": "bar", "columns": ["ticker","trade_value"] } }
+}
+
+// Card element:
+{ "kind": "ref",
+  "data": {
+    "bind": "fetched_sources.rebalance.proposed_trades",
+    "viewBind": "fetched_sources.rebalance._view",
+    "fallbackKind": "table"
+  }
+}
+```
+
+Add this to the `copilot` prompt template to instruct the LLM:
+```
+Return JSON with shape:
+{
+  "<data_key>": [ ... ],
+  "_view": {
+    "kind": "editable-table" | "table" | "chart",
+    "data": {
+      // for editable-table: { "writeTo": "card_data.<key>", "columns": ["field1","field2"] }
+      // for chart:          { "chartType": "bar" | "line" | "pie", "columns": ["labelField","valueField"] }
+      // for table:          { "columns": ["field1","field2"] }
+    }
+  }
+}
+Choose kind based on data shape and user intent.
+```
+
+The `_view` key is ignored by any card that reads only `<data_key>` — it is inert to downstream cards.
+
+**Pattern 3 — Cross-card view hint (view definition flows as a token)**
+
+Card A provides both its data and the view hint as separate tokens. Card B requires both and uses `ref` to render whatever Card A’s LLM suggested:
+
+```json
+// Card A provides:
+"provides": [
+  { "bindTo": "trade_data", "ref": "fetched_sources.rebalance.proposed_trades" },
+  { "bindTo": "trade_view", "ref": "fetched_sources.rebalance._view" }
+]
+
+// Card B requires and renders:
+"requires": ["trade_data", "trade_view"],
+"view": {
+  "elements": [
+    { "kind": "ref",
+      "data": {
+        "bind": "requires.trade_data",
+        "viewBind": "requires.trade_view",
+        "fallbackKind": "table"
+      }
+    }
+  ]
+}
+```
+
+Card B’s author does not need to know what kind Card A’s LLM will choose. The view decision propagates through the token graph.
+
 ---
 
 ## Common Card Patterns
 
 ### Root source card
 ```
-sources[mock/http/script] → fetched_sources.raw
-provides: [{ bindTo: "orders", src: "fetched_sources.raw" }]
+source_defs[mock/http/script] → fetched_sources.raw
+provides: [{ bindTo: "orders", ref: "fetched_sources.raw" }]
 view: table showing the raw data
 ```
 
@@ -287,7 +405,7 @@ view: table showing the raw data
 ```
 requires: ["orders"]
 compute: JSONata aggregation → computed_values.result
-provides: [{ bindTo: "regionTotals", src: "computed_values.result" }]
+provides: [{ bindTo: "regionTotals", ref: "computed_values.result" }]
 view: table or metric
 ```
 
@@ -316,14 +434,42 @@ card-child    requires "card-ex-form"
 ### LLM verdict card (completion gating via source)
 ```
 requires: ["some-data"]
-sources: [{ bindTo: "verdict", outputFile: "...", copilot: { prompt_template: "..." } }]
+source_defs: [{ bindTo: "verdict", outputFile: "...", copilot: { prompt_template: "..." } }]
 compute: [{ bindTo: "isReady", expr: "fetched_sources.verdict.isTaskCompleted" }]
-provides: [{ bindTo: "readiness-verdict", src: "fetched_sources.verdict" }]
+provides: [{ bindTo: "readiness-verdict", ref: "fetched_sources.verdict" }]
 view: badge(computed_values.isReady, colorMap) + text(fetched_sources.verdict.reason)
 ```
 The task executor calls the LLM, writes `{ isTaskCompleted: bool, reason: string }` to `--out`.
 The card is complete when the source is fetched. Downstream cards `requires: ["readiness-verdict"]`.
 
+### User-selectable view (selector + ref)
+```
+source_defs: fetch data into fetched_sources.raw
+view:
+  form writeTo:card_data.display_mode  (enum: table, chart, editable-table)
+  ref  bind:fetched_sources.raw  viewBind:card_data.display_mode  fallbackKind:table
+```
+User picks the display kind from a dropdown; the `ref` element re-renders immediately.
+No card JSON changes needed — the form + ref pair handles all switching.
+
+### LLM-suggested view
+```
+source_defs: copilot source returns { data: [...], _view: { kind, data: {...} } }
+view:
+  ref  bind:fetched_sources.raw.data  viewBind:fetched_sources.raw._view  fallbackKind:table
+```
+LLM decides chart vs table vs editable-table at runtime. `_view` is ignored by downstream
+cards that only read `data`. Card author can fence with static `columns` in the ref element data.
+
+### Cross-card view propagation
+```
+Card A provides: trade_data (fetched_sources.rebalance.proposed_trades)
+               + trade_view (fetched_sources.rebalance._view)
+Card B requires: trade_data, trade_view
+       view: ref bind:requires.trade_data  viewBind:requires.trade_view
+```
+Card B author writes no view knowledge — Card A's LLM drives the rendering decision for both cards.
+
 ---
 
 ## Card Design Principles & Layout
@@ -343,21 +489,86 @@ Common customField conventions (demo executor supports `mock` and `copilot`):
 | Field | Meaning |
 |---|---|
 | `"mock": "key"` | Reads from `mock.db` by key — local dev only |
-| `"copilot": { "prompt_template": "...", "args": {} }` | LLM call; `{{key}}` interpolated from `_requires`, `_sourcesData`, `_computed_values`, then explicit `args` |
+| `"copilot": { "prompt_template": "...", "args": {} }` | LLM call; `{{key}}` interpolated from `_projections` (named data projections declared in `projections`), then explicit `args` |
 | `"prompt_template": "..."` | Shorthand top-level LLM call (equivalent to `copilot.prompt_template`) |
 | `"http": { "url": "...", "method": "GET" }` | HTTP/REST — implement in your executor |
 | `"graphapi": { "query": "..." }` | Microsoft Graph API — implement in your executor |
 | `"script": { "path": "...", "args": {} }` | Local script — implement in your executor |
 | `"teams"`, `"mail"`, `"incidentdb"` | Any domain integration — define in your executor |
 
-Sources can reference upstream data in their customFields (e.g. `"url": "https://api.example.com/{{orderId}}"`) — the executor receives `_requires`, `_sourcesData`, `_computed_values` to resolve such references. See [Task Executor Protocol](#task-executor-protocol) for the full `--in` payload shape.
+Sources can access upstream data via the `projections` property — named JSONata projections from `card_data` or `requires` that the engine evaluates before invoking the executor. The executor receives `_projections` containing the resolved values. See [source_defs projections](#source_defs-projections) and [Task Executor Protocol](#task-executor-protocol) for details.
+
+### source_defs projections
+
+The optional `projections` map lets a source definition declare which upstream data it needs. Each key maps to a JSONata expression rooted at `card_data` or `requires`. The engine evaluates these before invoking the executor and attaches the results as `_projections` on the source payload.
+
+```json
+"source_defs": [
+  {
+    "bindTo": "quotes",
+    "outputFile": "quotes.json",
+    "projections": {
+      "holdings": "requires.holdings",
+      "topHoldings": "requires.holdings[weight > 0.05]",
+      "threshold": "card_data.threshold"
+    },
+    "chartApi": {
+      "tickersFrom": "holdings.ticker"
+    }
+  }
+]
+```
+
+**Rules:**
+- Only `card_data` and `requires` are valid namespaces in `projections` expressions
+- `fetched_sources`, `computed_values`, and `source_defs` are **forbidden** in projections
+- Full JSONata syntax is supported (same as `compute[].expr`)
+- Sources without `projections` receive `_projections: {}` — executor must handle empty projections gracefully
+- `tickersFrom: "refKey.fieldName"` reads from `_projections[refKey]` — the `projections` key must exist
 
 ### Optional source field
 - `optionalForCompletionGating: true` — marks this source as optional for default task-completion gating. If set, the card can complete even if this source hasn't been fetched yet.
 
+### Discovering supported source kinds
+
+Rather than guessing which source `customFields` the registered executor supports, query it directly:
+
+```bash
+node board-live-cards-cli.js describe-task-executor-capabilities --rg <boardDir>
+```
+
+This invokes the executor's `describe-capabilities` subcommand and prints its capabilities JSON to stdout. The output includes:
+- **`sourceKinds`** — every source kind the executor handles (e.g. `mock`, `copilot`, `http`, `chartApi`), each with:
+  - `description` — what the kind does
+  - `inputSchema` — the exact `customFields` the executor expects on the source entry
+  - `outputShape` — the shape of the JSON written to `--out`
+  - `example` — sample input/output pair
+- **`extraSchema`** — fields available via `--extra` (board topology context)
+- **`subcommands`** — supported subcommands (typically `run-source-fetch` + `describe-capabilities`)
+
+**Use this before authoring a card** to confirm the executor handles your intended source kind and to discover the correct field names and types. If the kind is missing from the output, the executor needs extending before the card will work.
+
+Example output (excerpt):
+```json
+{
+  "sourceKinds": {
+    "mock": {
+      "description": "Look up a key in a hardcoded MOCK_DB dictionary.",
+      "inputSchema": { "mock": { "type": "string", "required": true } }
+    },
+    "copilot": {
+      "description": "Invoke GitHub Copilot CLI with an interpolated prompt template.",
+      "inputSchema": {
+        "copilot": { "type": "object", "properties": { "prompt_template": { "type": "string" } } }
+      }
+    }
+  }
+}
+```
+
 ## LLM Calls — Use a Source
 
-**All LLM calls belong in sources[], handled by the task executor.** There is one mechanism for external calls — sources.
+**All LLM calls belong in source_defs[], handled by the task executor.** There is one mechanism for external calls — source_defs.
 
 To incorporate LLM reasoning into a card:
 
@@ -367,7 +578,7 @@ To incorporate LLM reasoning into a card:
 4. The card provides those tokens downstream like any other.
 
 ```json
-"sources": [
+"source_defs": [
   {
     "bindTo": "verdict",
     "outputFile": "my-card-verdict.json",
@@ -388,13 +599,13 @@ If the LLM needs computed values (which compute first), chain two cards: Card A
 
 ### CLI (recommended for authoring)
 ```bash
-# Validate all cards in example-board
-npm run validate:cards -- "examples/example-board/cards/*.json"
+# Validate a single card
+node board-live-cards-cli.js validate-card --card cards/my-card.json
 
-# Validate any glob pattern
-npm run validate:cards -- "path/to/cards/*.json"
+# Validate all cards matching a glob
+node board-live-cards-cli.js validate-card --card-glob "cards/*.json"
 ```
-Uses `validateLiveCardDefinition` — structural + schema checks, reports all errors per file.
+Checks JSON Schema structure, JSONata expression syntax in `compute[].expr`, and `provides[].ref` namespace validity. Reports per-file OK/FAIL with detailed errors. Exits with code 1 if any card fails.
 
 ### Programmatic
 ```typescript
@@ -424,24 +635,25 @@ When in doubt about allowed fields, consult:
 - `id` required, non-empty string
 - `card_data` required, must be an object
 - `requires` must be array of strings (if present)
-- `provides` must be array of `{ bindTo: string, src: string }` (if present)
-- `compute[]` each entry must have `bindTo` + `expr` strings
-- `sources[]` each entry must have `bindTo` + `outputFile` strings; both must be unique across the array
+- `provides` must be array of `{ bindTo: string, ref: string }` (if present)
+- `provides[].ref` must start with a valid namespace: `card_data`, `requires`, `fetched_sources`, or `computed_values`
+- `compute[]` each entry must have `bindTo` + `expr` strings; `expr` must be valid JSONata
+- `source_defs[]` each entry must have `bindTo` + `outputFile` strings; both must be unique across the array
 - `view.elements` required, non-empty; each element must have a valid `kind`
 - Top-level unknown keys are flagged as errors
-- Valid element `kind` values: `metric`, `table`, `editable-table`, `chart`, `form`, `filter`, `list`, `notes`, `todo`, `alert`, `narrative`, `badge`, `text`, `markdown`, `custom`
+- Valid element `kind` values: `metric`, `table`, `editable-table`, `chart`, `form`, `filter`, `list`, `notes`, `todo`, `alert`, `narrative`, `badge`, `text`, `markdown`, `ref`, `custom`
 
 ---
 
 ## mock.db
 
-A JSON file at the board root keyed by mock name. Used by `"mock": "key"` sources. Replace with real task-executor integrations in production.
+A JSON file at the board root keyed by mock name. Used by `"mock": "key"` source_defs. Replace with real task-executor integrations in production.
 
 ---
 
 ## Task Executor Protocol
 
-The task executor is a **card-source-driven** component — its behaviour is determined entirely by the `customFields` defined on each card's `sources[]` entries. One executor is registered for the whole board, but it must know how to handle every source kind (`mock`, `copilot`, `http`, `graphapi`, etc.) used by any card on the board. The executor is the only handler where the card's source definition directly drives what the handler needs to do. It is registered once per board:
+The task executor is a **card-source-driven** component — its behaviour is determined entirely by the `customFields` defined on each card's `source_defs[]` entries. One executor is registered for the whole board, but it must know how to handle every source kind (`mock`, `copilot`, `http`, `graphapi`, etc.) used by any card on the board. The executor is the only handler where the card's source definition directly drives what the handler needs to do. It is registered once per board:
 
 ```bash
 node board-live-cards-cli.js init ./my-board --task-executor ./my-executor.js
@@ -454,7 +666,7 @@ node board-live-cards-cli.js init ./my-board --task-executor ./my-executor.js
 node <executor.js> run-source-fetch --in <source.json> --out <result.json> [--err <error.txt>]
 ```
 
-- **`--in`** — path to a JSON file containing a single source object (one entry from `sources[]`), enriched by the runtime with extra context fields:
+- **`--in`** — path to a JSON file containing a single source object (one entry from `source_defs[]`), enriched by the runtime with extra context fields:
 
 ```json
 {
@@ -462,16 +674,12 @@ node <executor.js> run-source-fetch --in <source.json> --out <result.json> [--er
   "outputFile": "my-card-raw.json",
   "cwd": "/absolute/path/to/board",
   "boardDir": "/absolute/path/to/board",
-  "_requires": { "token-a": { ... }, "token-b": { ... } },
-  "_sourcesData": { "previously-fetched-source-key": { ... } },
-  "_computed_values": { "result": "..." },
+  "_projections": { "holdings": [ ... ], "threshold": 0.05 },
   /* ...any other customFields from the card source definition */
 }
 ```
 
-- `_requires` — resolved values for all card `requires` tokens
-- `_sourcesData` — already-fetched sources for this card (earlier in sources[] order)
-- `_computed_values` — current computed_values for the card
+- `_projections` — resolved values for all entries declared in the source's `projections` map (evaluated from `card_data`/`requires` before executor invocation). Empty object `{}` if `projections` was not declared.
 
 - **`--out`** — path to write the fetched value as raw JSON (any shape; stored under `fetched_sources.<bindTo>`)
 - **`--err`** — optional path to write a plain-text error message on failure
@@ -481,7 +689,7 @@ node <executor.js> run-source-fetch --in <source.json> --out <result.json> [--er
 | `customField` | Meaning |
 |---|---|
 | `"mock": "key"` | Lookup `key` in `mock.db` — local dev |
-| `"copilot": { "prompt_template": "..." }` | LLM call; supports `{{key}}` interpolation against `_requires`, `_sourcesData`, `_computed_values` |
+| `"copilot": { "prompt_template": "..." }` | LLM call; supports `{{key}}` interpolation against `_projections` |
 | `"http": { "url": "...", "method": "GET" }` | HTTP/REST fetch |
 | `"graphapi": { "query": "..." }` | Microsoft Graph API query |
 | `"script": { "path": "...", "args": {} }` | Run a local script |
@@ -502,27 +710,45 @@ node board-live-cards-cli.js probe-source \
   --card cards/card-market-prices.json \
   --source-idx 0 \
   --rg <boardRuntimeDir> \
-  --mock-requires '{"holdings":[{"ticker":"AAPL","quantity":10},{"ticker":"MSFT","quantity":5}]}'
+  --mock-projections '{"holdings":[{"ticker":"AAPL","quantity":10},{"ticker":"MSFT","quantity":5}]}'
 ```
 
 | Flag | Required | Description |
 |---|---|---|
 | `--card <card.json>` | yes | Path to the card file to probe |
-| `--source-idx <n>` | no (default 0) | 0-based index into `sources[]` |
+| `--source-idx <n>` | no (default 0) | 0-based index into `source_defs[]` |
 | `--source-bind <name>` | no | Select source by `bindTo` name instead of index |
-| `--mock-requires <json>` | no | JSON string (or `@file.json`) providing the `_requires` token values the source needs. If omitted, `_requires` is `{}`. |
+| `--mock-projections <json>` | no | JSON string (or `@file.json`) providing the `_projections` values the source needs. If omitted, `_projections` is `{}`. |
 | `--rg <boardDir>` | no | Board runtime directory used to locate `.task-executor`. Defaults to the card file's directory. |
 | `--out <result.json>` | no | Write the raw fetch result to this path |
 
 **Output:** the command prints a human-readable report ending with a machine-readable `[probe-source:result]` JSON line. Exit `0` = `PROBE_PASS`, exit `1` = `PROBE_FAIL`.
 
-**`--mock-requires` is the agent's responsibility.** Craft the minimal payload that exercises the source — for example, if the card `requires: ["holdings"]` and the source uses `tickersFrom: "holdings.ticker"`, supply `{"holdings":[{"ticker":"AAPL","quantity":1}]}`.
+**`--mock-projections` is the agent's responsibility.** Craft the minimal payload that exercises the source — for example, if the card declares `"projections": { "holdings": "requires.holdings" }` and the source uses `tickersFrom: "holdings.ticker"`, supply `{"holdings":[{"ticker":"AAPL","quantity":1}]}`.
 
 **Workflow for agents authoring a new card:**
-1. Author the card JSON with `sources[]`.
-2. For each source, run `probe-source` with representative `--mock-requires` data.
-3. If `PROBE_PASS` → proceed with `add-cards` or `upsert-card`.
-4. If `PROBE_FAIL` → inspect the error, fix the source definition or executor, retry.
+1. **Discover available source kinds** — run `describe-task-executor-capabilities` to see exactly which source kinds the registered executor supports, their required `customFields`, and expected output shapes. Only use source kinds present in this output.
+   ```bash
+   node board-live-cards-cli.js describe-task-executor-capabilities --rg <boardDir>
+   ```
+2. **Author the card JSON** with `source_defs[]`, `compute[]`, `provides[]`, and `view` using only the source kinds confirmed in step 1.
+3. **Validate the card structure** — run `validate-card` to catch schema errors, invalid JSONata expressions, and namespace violations before attempting any live fetch.
+   ```bash
+   node board-live-cards-cli.js validate-card --card cards/my-card.json
+   ```
+   Fix any reported errors and re-run until validation passes.
+4. **Probe each source** — run `probe-source` with representative `--mock-projections` data to confirm the executor can successfully fetch each source.
+5. If `PROBE_PASS` → proceed with `upsert-card`.
+6. If `PROBE_FAIL` → inspect the error, fix the source definition or executor, retry from step 3.
+
+**Workflow for agents editing an existing card:**
+1. Make the change to the card JSON.
+2. **Validate immediately** — run `validate-card` after every edit.
+   ```bash
+   node board-live-cards-cli.js validate-card --card cards/my-card.json
+   ```
+3. If validation fails, fix the reported errors and re-run — repeat until the card is clean.
+4. If the change touches a `source_defs[]` entry, also run `probe-source` to confirm the source still fetches correctly before deploying.
 
 ---
 
@@ -532,7 +758,7 @@ node board-live-cards-cli.js probe-source \
 
 ## Chat Handler Protocol
 
-The chat handler is a **universal LLM component** — it does not depend on card sources, card model fields, or board state. Its sole job is: read the conversation, call the LLM, write the response.
+The chat handler is a **universal LLM component** — it does not depend on card source_defs, card model fields, or board state. Its sole job is: read the conversation, call the LLM, write the response.
 
 Enable chat on a card by setting `"chat": true` in the card's `view.features`:
 ```json

package/examples/example-board/cards/card-concentration.json

@@ -6,10 +6,13 @@
     "desc": "AI analysis of portfolio mix and P&L. Publishes structured insights as tokens for downstream risk and action cards."
   },
   "requires": ["positions"],
-  "sources": [
+  "source_defs": [
     {
       "bindTo": "analysis",
       "outputFile": "card-concentration-analysis.json",
+      "projections": {
+        "positions": "requires.positions"
+      },
       "copilot": {
         "prompt_template": "You are a concise equity analyst. Use web search to get today's news and upcoming events for each ticker before answering.\n\nPortfolio positions:\n{{positions}}\n\nFields: ticker, quantity, cost_basis ($), price ($), value ($), gain_$ (unrealised P&L), gain_% (unrealised return), chg_$ (today's position P&L $), chg_pct (today's % move).\n\nIMPORTANT OUTPUT RULES:\n- Return ONLY a valid JSON object. No markdown code fences, no preamble, no trailing text.\n- Start your response with { and end with }.\n- No emojis anywhere.\n- Each value is a Markdown string using - bullet points. No sub-headings inside values.\n- Maximum 40 words per section.\n\n{\n  \"mix\": \"- <dominant holding ticker, % of total, and whether that is a risk>\\n- <sector clustering in one line>\",\n  \"pnl\": \"- Best: <ticker> +X% (+$Y)\\n- Worst: <ticker> +X% (+$Y)\",\n  \"risks\": \"- <TICKER>: <one specific current risk with event name or date>\\n- <TICKER>: ...\\n- (one bullet per position from today's news)\",\n  \"action\": \"- <one sentence: specific action and reason grounded in today's market>\"\n}"
       }
@@ -22,10 +25,10 @@
     { "bindTo": "action", "expr": "fetched_sources.analysis.action" }
   ],
   "provides": [
-    { "bindTo": "portfolio_mix",    "src": "computed_values.mix" },
-    { "bindTo": "portfolio_pnl",    "src": "computed_values.pnl" },
-    { "bindTo": "portfolio_risks",  "src": "computed_values.risks" },
-    { "bindTo": "portfolio_action", "src": "computed_values.action" }
+    { "bindTo": "portfolio_mix",    "ref": "computed_values.mix" },
+    { "bindTo": "portfolio_pnl",    "ref": "computed_values.pnl" },
+    { "bindTo": "portfolio_risks",  "ref": "computed_values.risks" },
+    { "bindTo": "portfolio_action", "ref": "computed_values.action" }
   ],
   "view": {
     "elements": [

package/examples/example-board/cards/card-market-prices.json

@@ -6,28 +6,33 @@
     "desc": "Fetches live prices for portfolio tickers. Publishes enriched quote data for downstream portfolio value calculations."
   },
   "requires": ["holdings"],
-  "sources": [
+  "source_defs": [
     {
       "bindTo": "quotes",
       "outputFile": "market-prices-quotes.json",
-      "chartApi": {
-        "url": "https://query1.finance.yahoo.com/v8/finance/chart/{{ticker}}?interval=1d&range=1d",
+      "projections": {
+        "url_list": "requires.holdings.ticker.('https://query1.finance.yahoo.com/v8/finance/chart/' & $ & '?interval=1d&range=1d')"
+      },
+      "url-list": {
         "headers": {
           "User-Agent": "Mozilla/5.0 (compatible; portfolio-tracker-demo/1.0)"
-        }
-      },
-      "tickersFrom": "holdings.ticker",
-      "mock": "quotes"
+        },
+        "cacheTimeout": 3600
+      }
     }
   ],
   "compute": [
+    {
+      "bindTo": "normalizedQuotes",
+      "expr": "{ \"quoteResponse\": { \"result\": $map(fetched_sources.quotes, function($r) { $r.chart.result[0].meta.{ \"symbol\": symbol, \"shortName\": longName, \"regularMarketPrice\": regularMarketPrice, \"regularMarketChange\": regularMarketChange, \"regularMarketChangePercent\": regularMarketChangePercent } }), \"error\": null } }"
+    },
     {
       "bindTo": "prices",
-      "expr": "$map(fetched_sources.quotes.quoteResponse.result, function($q) { {\"ticker\": $q.symbol, \"name\": $q.shortName, \"price\": $round($q.regularMarketPrice, 2), \"change\": $round($q.regularMarketChange, 2), \"chg_pct\": $round($q.regularMarketChangePercent, 2)} })"
+      "expr": "$map(computed_values.normalizedQuotes.quoteResponse.result, function($q) { {\"ticker\": $q.symbol, \"name\": $q.shortName, \"price\": $round($q.regularMarketPrice, 2), \"change\": $round($q.regularMarketChange, 2), \"chg_pct\": $round($q.regularMarketChangePercent, 2)} })"
     }
   ],
   "provides": [
-    { "bindTo": "quotes", "src": "fetched_sources.quotes" }
+    { "bindTo": "quotes", "ref": "computed_values.normalizedQuotes" }
   ],
   "view": {
     "elements": [

package/examples/example-board/cards/card-my-identity.json

@@ -0,0 +1,28 @@
+{
+  "id": "card-my-identity",
+  "meta": {
+    "title": "My Identity",
+    "tags": ["m365", "workiq"],
+    "desc": "Displays your M365 display name via WorkIQ (Microsoft 365 Copilot)."
+  },
+  "source_defs": [
+    {
+      "bindTo": "identity",
+      "outputFile": "card-my-identity.txt",
+      "workiq": {
+        "query_template": "what is my full display name. No Fluff. No Commentary. No Descriptions. Just Answer the Question"
+      }
+    }
+  ],
+  "view": {
+    "elements": [
+      { "kind": "markdown", "data": { "bind": "fetched_sources.identity" } }
+    ],
+    "layout": {
+      "board": { "col": 4, "order": 10 },
+      "canvas": { "x": 50, "y": 450, "w": 420, "h": 260 }
+    },
+    "features": { "refresh": true }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-portfolio-value.json

@@ -7,7 +7,7 @@
   },
   "requires": ["holdings", "quotes"],
   "provides": [
-    { "bindTo": "positions", "src": "computed_values.positions" }
+    { "bindTo": "positions", "ref": "computed_values.positions" }
   ],
   "compute": [
     {

package/examples/example-board/cards/card-portfolio.json

@@ -6,7 +6,7 @@
     "desc": "Manage your stock holdings — edit tickers and quantities inline, add or delete rows. Changes propagate downstream immediately."
   },
   "provides": [
-    { "bindTo": "holdings", "src": "card_data.holdings" }
+    { "bindTo": "holdings", "ref": "card_data.holdings" }
   ],
   "compute": [],
   "view": {