fruxon 1.0.0__tar.gz → 2.0.1__tar.gz

{fruxon-1.0.0 → fruxon-2.0.1}/HISTORY.md

@@ -1,5 +1,122 @@
 # History
 
+## Unreleased — `o` in `fruxon dash` opens the same page in the web app
+
+- `o` opens the web app on the exact tab or record behind what the console
+  shows: Home → the Application's Overview over the same window, an agent → its
+  page, a run → that execution (`?tab=executions&id=`), an automation → its
+  Overview, Settings or Work tab, an item → that item (`?tab=work&item=`), the
+  Items filter → `&status=`. On Configuration it opens where the selected
+  finding is put right (the agent editor, an integration's configs, an LLM
+  provider, the automation's settings or edit page, its work filtered to a
+  stage). The selected row wins; `O` opens the screen's own page.
+- Every link carries `?workspace=<slug>`, so the browser switches to the
+  console's workspace before it opens the page.
+- The automation link was broken (`/applications/{id}/…`); it is
+  `/app/{slug}/automations/triggers/{id}` now.
+- The URL stays up as a notification after it opens — over SSH, that is the
+  link. `--demo` shows the URL it would open and opens nothing.
+- `CheckResult.fix` names where a finding is put right (`editor`,
+  `integration:<id>`, `llm-provider:<id>`, `trigger-settings`,
+  `work:<status>:<stage>`, …); `to_dict()` and `-o json` are unchanged. The
+  link map is one pure function, `fruxon.tui.links.web_link`.
+
+## Unreleased — an agent reads as one agent, not a flow
+
+An agent runs as one definition. These surfaces still drew it as steps.
+
+- **`fruxon dash`**: an agent's Configuration tab shows an **Agent · rev N**
+  panel: one box with the agent's model, its tools, and each tool behind a
+  human-approval gate (`⧗ issue_refund · approval by …`). A gate with no
+  approver is named in red. It was a **Flow** panel drawing boxes joined by
+  arrows. The `--demo` agents no longer appear as a five-step pipeline. The
+  `consults this agent` line under the panel is gone; the Consult roster row
+  covers consults.
+- **`fruxon agents executions trace`**: the text tree's first line for an
+  agent run reads `1  Agent` instead of `1  FLOW_STEP · Agent`. Paths and
+  `-o json` are unchanged: the JSON is still the server's payload.
+- **`fruxon agents draft run`**: the NDJSON stream no longer relays the
+  server's `step_trace` for the `FLOW_STEP` frame around a run. The steps
+  inside it still come through.
+- **`fruxon agents approvals get` / `list`** no longer print a `step` for an
+  agent's gate. It was always `agent`, because the gate sits on a tool the
+  agent called. A workflow's tool step (`TOOL_FLOW_STEP`) still names its
+  step. `-o json` keeps `stepIdentifier` either way.
+- **`fruxon agents check`** and the dash's check rows say `consult is off
+  (network.enabled)`, `consult is on (network.enabled) but the roster is
+  empty`, and `no tool needs human approval`. They used to say "no step
+  enables consult", list step names, or say "on any step".
+- **Help text, guides and docs** talk about an agent and its definition,
+  not a flow or a step. This covers `draft validate` (its list of checks now
+  matches what it checks), `draft evaluate` (and its confirmation prompt),
+  `secrets`, `assets`, `metrics`, `participants`, `llm-providers configs`,
+  `storage`, `agents approvals`, and the Python client's docstrings. The
+  README and `docs/python-client.md` "Test a draft" examples now use the real
+  `put_draft` → `test(agent, base_revision, request)` calls; the old ones
+  posted a `flow` body to a signature that doesn't exist.
+
+## Unreleased — a form stage's own wording, checked before saving
+
+Follows the backend's operator-worded form messages (BE #1415) and a form
+batch's drafted rows (BE #1335).
+
+- **`fruxon triggers preview-shape`** shows a FORM stage's `join notice` under
+  its question: the line sent when more items join an open form, with its
+  counts filled in. A stage whose `formJoinNotice` is blank says a join sends
+  nothing. `-o json` carries it as `formJoinNotice`
+  (`WorkShapeStagePreview.form_join_notice`), null on every other stage.
+- **`fruxon triggers set-stages --help`** documents `formClosing` (the line
+  under the header in the form message) and `formJoinNotice`, the
+  `{{item_count}}` / `{{added_count}}` they fill in, unset vs blank, and that
+  the server refuses both on a stage that is not a form.
+- **`fruxon triggers ledger batches`** prints `N waiting, M drafted` for an open
+  FORM batch: rows saved on the page and not yet submitted, which no item
+  shows. `-o json` carries `draftCount` (`LedgerBatch.draft_count`).
+
+## Unreleased — `fruxon triggers check`, and an automation's Configuration tab in `fruxon dash`
+
+- **`fruxon triggers check <trigger> [-o json]`** audits a work-shape
+  automation part by part: the automation, its source (by its last pass),
+  every stage (a PROCESS stage's agent runs and reaches what it calls; an ASK
+  stage has someone to ask and is not close to expiring questions), the
+  outcome note's contact, the weekly budget and the dead items. Same
+  `{…, overall, checks[]}` contract and exit codes as `agents check`.
+  The audit is `fruxon.checks.ledger.check_ledger`.
+- `fruxon dash`: an automation's `2` Configuration tab shows those rows with
+  the selected one explained in place, `t` tests the source (admits nothing),
+  `p` previews what a stage sends its agent (saves nothing), and lists the
+  shape.
+
+## Unreleased — `fruxon dash` opens on the Fruxon wordmark
+
+While Home makes its first reads, `fruxon dash` shows "FRUXON" spelled out
+one letter at a time in outlined letters (the F in the brand's red) with a
+spinner and what is being read. It leaves once Home has its numbers, after
+at least 1.6 s; a failed read ends it at once, and enter, space or esc skip
+it.
+
+## Unreleased — `fruxon dash`, a read-only console for an Application
+
+Everything else in the CLI prints and exits. `fruxon dash` stays open and
+shows one Application the way the web app's overview does, in the terminal.
+
+- **`fruxon dash [--app A] [--demo] [--ground black|ink]`**. Home: runs,
+  spend, items finished and who is waiting in big digits; every agent and
+  automation; what needs a person. An agent: overview, the `agents check`
+  rows plus credential, model-config and budget health, runs and traces. An
+  automation: its stages and counts, items per day, what failed, its items.
+  Live parts every 5 s, totals every minute. Read-only.
+- Needs the new `tui` extra: `pip install "fruxon[tui]"` (Textual). Nothing
+  imports it until the command runs, so the CLI starts as fast as before.
+- `--demo` is a made-up workspace with a pinned clock and seeded live runs,
+  for recordings; `docs/tui/demo.tape` records it with VHS.
+- The audit behind `agents check` moved to `fruxon.checks.agent` and returns
+  `CheckResult` rows; the command's output and exit codes are unchanged.
+- New client reads: `get_application_spend`, `get_application_activity_counts`,
+  `get_application_support_kpis`, `get_agent_conversation_timeseries`,
+  `get_agent_judge_activity`, `get_agent_cost_forecast`,
+  `get_agent_llm_config_health`, `get_agent_credential_health`.
+
 ## Unreleased — edit and publish an integration config from the CLI
 
 `integrations configs` could only `list` and `get`, so changing a config

{fruxon-1.0.0 → fruxon-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fruxon
-Version: 1.0.0
+Version: 2.0.1
 Summary: The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.
 Project-URL: bugs, https://github.com/fruxon-ai/fruxon-sdk/issues
 Project-URL: changelog, https://github.com/fruxon-ai/fruxon-sdk/blob/main/HISTORY.md
@@ -29,6 +29,8 @@ Requires-Dist: pre-commit; extra == 'test'
 Requires-Dist: pytest; extra == 'test'
 Requires-Dist: ruff; extra == 'test'
 Requires-Dist: ty; extra == 'test'
+Provides-Extra: tui
+Requires-Dist: textual>=8.2; extra == 'tui'
 Description-Content-Type: text/markdown
 
 # fruxon
@@ -80,7 +82,7 @@ Auth:
 
 | Command | What it does |
 | --- | --- |
-| `fruxon login` | Browser-based sign-in. token goes to your OS keychain (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows). `--token $KEY` for headless. `--preset observer\|operator\|developer\|maintainer\|admin` declares the access level the key is minted with (default: developer); the approval page shows it for the user to approve or deny. |
+| `fruxon login` | Browser-based sign-in. token goes to your OS keychain (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows). `--token $KEY` for headless. `--preset observer\|operator\|developer\|maintainer\|admin` declares the access level the key is minted with (default: developer); the approval page shows it for the user to approve or deny. Adds a workspace without moving the default (the first sign-in sets it); `--set-default` moves it. |
 | `fruxon whoami` | Show the active key/workspace and where each value came from (flag, env, keychain, file). |
 | `fruxon logout` | Forget stored credentials. `--workspace <id>` signs out of one and leaves the rest; `--all` clears every one. |
 | `fruxon workspaces list` | Which workspaces this machine is signed in to, each with its host and cell, and which one is the default. Offline, no auth. |
@@ -96,7 +98,7 @@ Execution:
 | `fruxon agents executions get <agent> <record-id>` | Record summary for one execution — status, duration, cost, tokens. |
 | `fruxon agents executions trace <agent> <record-id>` | Step-by-step trace of one execution — LLM/tool calls, durations, and for a tool that records it, where the call's time went (service stages vs. unaccounted). Flags a result the model got offloaded or projected. Prints a quality check's verdict (score, criteria, rationale) under its `JUDGE` step, and marks a reply the check refused. `--show-io` also prints each tool step's parameters and result (the payload lives at `steps[].result`, a sibling of `toolTrace` — whose `resultDelivery` carries sizes only). `--show-system` labels each LLM step's system prompt block by block — your prompt vs. the platform's `<tag>` blocks, sizes, and the cache breakpoint. |
 | `fruxon agents executions result <agent> <record-id>` | The final output one execution produced. |
-| `fruxon agents approvals list/get/respond/cancel <agent>` | Operate a step's human-in-the-loop gate — see what a run is blocked on and answer it. `respond`/`cancel` confirm first and refuse without `--yes` in agent mode (an LLM must not silently auto-approve). |
+| `fruxon agents approvals list/get/respond/cancel <agent>` | Operate human-in-the-loop approval gates — see what a run is blocked on and answer it. `respond`/`cancel` confirm first and refuse without `--yes` in agent mode (an LLM must not silently auto-approve). |
 | `fruxon agents memory list/subjects/get/forget-subject <agent>` | Inspect and prune what an agent remembers. `list` filters server-side by `--subject`/`--query`/`--scope`; `forget-subject` is a GDPR-style delete (confirms; refuses without `--yes` in agent mode). |
 | `fruxon agents topics list/search/get/messages/sessions <agent>` + `fruxon agents inbox <agent>` | Read the conversation spine — the agent's topics (threads), one topic's transcript, its episodes, and its inbox (what it's focused on). `list`/`search` filter server-side by `--state`/`--participant`/`--query`. Read-only. Each message carries `author` — a human colleague's turn is stored as `ASSISTANT` on purpose, so `role` alone cannot tell their reply from the agent's; `HUMAN_OPERATOR` can. A message the runtime *withheld* is in no transcript at all — see `fruxon messages list`. `sessions` explains a fresh, blind session: a topic outlives its sessions, and `endCause` on the previous one (`CONSOLE_ALREADY_RESOLVED` — a human closed it in the provider's console) is why the next started with no history. |
 | `fruxon escalations list/history/unhandled/policy/ack` | What happened when an agent handed a conversation to a person. `list` is the queue (live takeovers + degraded escalations nobody was reachable for); `unhandled` is the append-only ledger under it. **`history` is the record of closed console-routed takeovers** — those leave the queue, so `list --status ALL` answers `[]` about a conversation a human worked for half an hour. Read `humanObservedAt` before believing a `RESOLVED`: null means nobody was ever seen picking it up. `policy <agent>` resolves who the *next* escalation would reach — an empty ladder under `NATIVE_HANDOFF` is correct, the console supplies the human. |
@@ -146,8 +148,8 @@ Integrations + tools:
 | `fruxon tools list/get/create/update/delete/run` | Manage the tools inside an integration. Integration-scoped. `get` and `run` select the tool with `--tool`; `run` executes it outside any agent — real credentials, real result — with `-p key=value`, and `-c` naming the config that supplies credentials. The tenant list API hides internal `knowledge_base` / `assets` tools; `tools list` recovers them by ID and lists them like any other (`--no-include-internal` for the raw server answer). |
 | `fruxon keys list/mint/revoke/delete/history/scopes` | Audit and revoke scoped tokens. Minting opens the dashboard so the secret never enters the CLI process. |
 | `fruxon llm-providers list/get/models` | Browse LLM providers and models supported at the tenant level. |
-| `fruxon llm-providers configs list/get/test/publish` | The workspace's saved LLM credentials — the `provider.tenantConfigId` a step pins. `get` shows the draft (secrets masked), the published revision and last known health. `test` probes the draft on every provider surface that shares the credential (or just one, given that surface's provider id), one line per failing surface, exit 12 on failure (`llm_providers:test`). `publish` ships the draft as a new revision that every agent on the config switches to — it confirms, needs `--yes` in agent mode, and does not wait on a passing test (`llm_providers:write`). |
-| `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets a step can query — upload local files, wait for async ingestion, inspect operations, and use the ids for `assetConfig.assetIds`. `delete` confirms + refuses without `--yes` in agent mode. |
+| `fruxon llm-providers configs list/get/test/publish` | The workspace's saved LLM credentials — the `provider.tenantConfigId` an agent pins. `get` shows the draft (secrets masked), the published revision and last known health. `test` probes the draft on every provider surface that shares the credential (or just one, given that surface's provider id), one line per failing surface, exit 12 on failure (`llm_providers:test`). `publish` ships the draft as a new revision that every agent on the config switches to — it confirms, needs `--yes` in agent mode, and does not wait on a passing test (`llm_providers:write`). |
+| `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets an agent can query — upload local files, wait for async ingestion, inspect operations, and use the ids for `assetConfig.assetIds`. `delete` confirms + refuses without `--yes` in agent mode. |
 | `fruxon knowledge-bases list/get/create/update/publish/archive/delete` | The authored, reviewable corpus behind a `manual_knowledge` asset — **not** the asset itself, which is what gets searched (`get` prints the asset id as `backingAssetId`). **`publish` is the step that makes any of it findable**: only `PUBLISHED` documents travel in a snapshot, and only publishing the *base* moves one, so a base full of finished articles answers nothing until it runs. It returns on *acceptance*, not searchability — RAG ingests afterwards, so a pending publish state is normal. `list` hides archived bases, which keep answering for agents already attached to them; `delete` is refused while an agent revision still attaches one, and `archive` is the reversible path. |
 | `fruxon knowledge-bases usage <kb>` | Whether agents actually use the base: searches per hour, day or week (`--interval`), the passage tokens each search handed the agent, how many found nothing (split from searches that **could not fully search** it — index missing or still building, a phrasing failed), and which agents searched (up to 20 you can open, the rest counted together). `--origin test` counts test runs instead of production. Retrieved tokens are counted by the search index, so what the model read can be less when a large result is trimmed or offloaded. Searches are recorded from 15 October 2026 and kept 90 days at most, so a window reaching further back says where counting began rather than showing empty days. A 404 is a wrong id or a backend that predates the read. |
 | `fruxon knowledge-bases notices/notice/post-notice/edit-notice/extend-notice/withdraw-notice` | Time-boxed notices on a base — an outage being fixed, a known bug, a closure. **Not documents**: never indexed or published, so every agent attaching the base is given each active notice whole from its next turn. `post-notice --valid-for 4h` (or `--until`) — every notice ends, at most 30 days after it was posted, and a base holds ten active ones (409 `notice_limit` / `notice_too_long`, each with its remedy). The body is Markdown, at most 1,200 characters, best as four headings: *What is happening*, *Applies when*, *Tell the customer*, *Do not*. A time without an offset is read in the notice's zone (`--time-zone`, else this machine's), which is also the zone agents tell customers the end in. `withdraw-notice` tells each conversation that was given it, on its next turn, that it ended; it confirms, and needs `--yes` in agent mode. An ended notice is not extended: `post-notice --from <id>` posts it again as a new one. |
@@ -156,13 +158,14 @@ Integrations + tools:
 | `fruxon knowledge-bases consolidate` → `apply` / `calibrate` | Two steps on purpose. `consolidate` queues a **report** of near-duplicate clusters and writes nothing — a standalone pass can no longer merge as it goes, and the old `--apply` is refused. `apply <kb> <run> --cluster <id>` (or `--all`) merges the clusters you accepted: the report's version rides along as a compare-and-set read off the run itself, and each member is revalidated against the content hash the report recorded, so a cluster whose documents moved comes back STALE and is left **entirely** alone rather than partly merged. It re-runs the base's consolidator agent per cluster, so a base without a deployed one is refused. `calibrate` records what a person reviewed a report under — it applies and publishes nothing, and is what reopens automatic source approval. |
 | `fruxon knowledge-bases source list/get/add/update/plan-update/preview/activity/passes/sync/pause/resume/archive/unarchive/fork/delete` | The pipelines that read a customer's history and write articles. `managementMode` decides **who owns the implementation**, which is what the verbs key on: a LINKED source's resources are yours and survive a `delete`, a MANAGED one's agents, automation and ledger go with it — and `fork` flips managed to linked, keeping the history, one-way. **Stopped is the default**: a built source lands paused and `unarchive` returns one paused, so `resume` and `sync` confirm (they start reading someone's history, and dispatched items cost a run each) while `pause` and `archive` do not. `preview` admits nothing and is deliberately not narrowed by the watermark — a caught-up source would otherwise look broken — and reports **floors, not totals**, once a ceiling stopped the scan. `activity` speaks the ledger's vocabulary, so `ready` is backlog rather than motion, and a missing work ledger is reduced health rather than an error. |
 | `fruxon assets search/documents/chunks` | Reproduce and inspect a retrieval. `search` runs the same query an agent's `search_assets` does (`--mode HYBRID/VECTOR/FULL_TEXT`, `--top-k`, fusion weights) — note `score` is on a different scale per mode, and in hybrid the top hit is always 1.0. `documents` lists what the index contains (a `chunkCount` of 0 means that file yielded no indexable text); `chunks` reads one document's chunks in order. The `documentId` these print is the **index's** id, which is what `chunks` takes — on a knowledge base's backing asset it is not the editable document's id, and it changes whenever a document's body is re-indexed. The `fileName` (`<knowledge document id>.md`) is the document a `knowledge_base` tool would edit. |
-| `fruxon metrics list` | Browse the evaluation-metric catalog — the ids a step's LLM-judge config (`judge.metrics[]`) binds, with a default weight each. |
+| `fruxon metrics list` | Browse the evaluation-metric catalog — the ids an agent's quality check (`judge.metrics[]`) binds, with a default weight each. |
 | `fruxon triggers list/get/create/update/delete/fire/bind/unbind` | Manage triggers — the schedule/event sources that fire agents. `create`/`update` take `--file` (+`--schema`); `create` also takes `--application`, the Application that will own the trigger and must own everything it fires. `bind`/`unbind` wire which agents fire; `fire` runs it now (`--close-gathering` also runs every group a batch stage is gathering). `fire`/`delete`/`unbind` confirm + refuse without `--yes` in agent mode. The control plane for autonomy. `get` returns the full stored `workShape` and every `scheduleTimes` slot, so `get -o json | jq .workShape` produces a body `update --file` can post straight back — a PATCH replaces the whole shape, so edit what you read. Each binding carries its `outputDestination` (where a fired run's reply is delivered, e.g. a Telegram group) verbatim, and text output names it as `delivers to telegram -5129894975 (Daria Group)`; a `bindings` list posted back without it unpins the delivery. |
 | `fruxon triggers doors` | The pre-configured source doors a work shape can be built on — the **first** question of authoring an automation, and the one `--schema` cannot answer: it tells you a `workShape.door` carries a `doorId`, not which ids exist. Each row is the integration a chosen `integrationConfigId` must belong to, plus the one query field that is genuinely yours (label + example), and `supportsStartFrom` — whether that door's source accepts a lower bound, and so whether a `door.startFrom` horizon does anything there. `door.skipWhen` is the other field that is yours rather than the integration's: a `{match, conditions[]}` filter, same shape as a trigger's event filter, whose matching records are **never admitted** — no item, no stage, no model call. It has to live on the `door` because saving re-expands `source` from it, so the same filter written onto `source` is discarded by the next save. `door.projection` is the third: a list of dotted record paths naming the fields an admitted item **keeps**, with the door's own `defaultProjection` as the suggestion to seed it from — without one an item carries the whole record, into the Work grid and into every stage's prompt on every pass. Read that against the door's `labelPaths` (or, for the sheet and table doors, `labelFieldName` naming the field whose answer picks the label column): those are where an item's title comes from, and a projection that drops one is refused at save time rather than quietly repaired. Read-only and static: a door is a claim that one combination of list tool, identity path and watermark actually works, made in platform code by someone who verified it. An integration with no door is still fully usable — configure `workShape.source` by hand. |
-| `fruxon triggers preview-shape/test-source` | Dry-run a work shape before saving or activating it; both write nothing. `preview-shape` renders, per stage, the resolved instruction, the whole `user_query` the agent is handed (item payload included), and the JSON schema the stage's declared `produces` keys become — against a real backlog item when you name a trigger. `--file` takes a draft shape, or just the stages — the same file `set-stages` takes — which it merges into the named trigger's saved shape the way `set-stages` would, so the preview is of what that save would write. `test-source` runs the door's list tool once and says, per record, whether admission would take it, plus the exact arguments the tool was called with (for Gmail, your query with the day-granular `after:` folded in). Records a `door.skipWhen` filter would drop read `FILTERED`, with a footer count — which is where to see what a rule costs before it goes onto a live automation. `--count` pages the whole door instead and answers how much is waiting: the total, how many the filter drops, how many the ledger already holds, how many clear the watermark, and which server ceiling stopped the scan — so `total − filtered − already held` is the work that would actually arrive. Each record prints **as the item will carry it** — narrowed to the shape's `door.projection`, with an `item keeps` line naming the paths that survived, so a field your projection drops and a field the source never sent are not the same silence. `--file` tests a shape being edited — and a draft whose `door.startFrom` (Unix ms) sets a first-run horizon gets a `first run sends` line with the `after:` term that horizon produces, which is the only place to see it: `startFrom` seeds the ledger cursor once, when the ledger is created. |
+| `fruxon triggers preview-shape/test-source` | Dry-run a work shape before saving or activating it; both write nothing. `preview-shape` renders, per stage, the resolved instruction, the whole `user_query` the agent is handed (item payload included), and the JSON schema the stage's declared `produces` keys become — against a real backlog item when you name a trigger. A FORM stage shows its form message and, under it, the `join notice` sent when more items join the open form, both in the stage's own `formClosing` / `formJoinNotice` wording. `--file` takes a draft shape, or just the stages — the same file `set-stages` takes — which it merges into the named trigger's saved shape the way `set-stages` would, so the preview is of what that save would write. `test-source` runs the door's list tool once and says, per record, whether admission would take it, plus the exact arguments the tool was called with (for Gmail, your query with the day-granular `after:` folded in). Records a `door.skipWhen` filter would drop read `FILTERED`, with a footer count — which is where to see what a rule costs before it goes onto a live automation. `--count` pages the whole door instead and answers how much is waiting: the total, how many the filter drops, how many the ledger already holds, how many clear the watermark, and which server ceiling stopped the scan — so `total − filtered − already held` is the work that would actually arrive. Each record prints **as the item will carry it** — narrowed to the shape's `door.projection`, with an `item keeps` line naming the paths that survived, so a field your projection drops and a field the source never sent are not the same silence. `--file` tests a shape being edited — and a draft whose `door.startFrom` (Unix ms) sets a first-run horizon gets a `first run sends` line with the `after:` term that horizon produces, which is the only place to see it: `startFrom` seeds the ledger cursor once, when the ledger is created. |
 | `fruxon triggers ledger funnel/items/cursor/transitions/effects/batches` | The work items a schedule trigger's work shape admitted. `funnel` counts per stage and status (every item is in exactly one cell). `items` is the grid — `--stage`, `--status`, `--ignore-reason`, `--item-key` (client-side; the endpoint has no such filter), each item's `label` (what the Work grid calls the row, as against the provider's opaque `itemKey`), and its accumulated `data`, which is where a stage's declared `produces` keys land. A listing is **one page of 20** that reports how many matched in total — a ledger's healthy state is thousands of rows served ten per request, so an unbounded walk is rate-limited long before the end; `-n` sizes the page and `--all` walks the lot. `--ignore-reason` narrows to the items one exclusion reason set aside — the same filter `redrive-many` selects by, matched whole and case-sensitively, so it is how you read a batch before putting it back. `--where field=value` (or `!=`, repeatable, dotted for a nested field) selects by what a stage wrote into `data` — `--where destination=SKIP` — matched whole and case-sensitively, as text and as the number, boolean or null it spells; the server filters and the CLI re-applies it, so an older server is slower, never wrong. `cursor` is the watermark and its freshness. `transitions` is one item's attempt history; `effects` is what it did to the outside world — an `UNKNOWN` row parks the item until someone settles it. `batches` is what an ASK stage is waiting on a human for — read its `delivery` first, because `UNDELIVERABLE` / `FAILED` mean nobody was asked and nobody will answer while the batch, the count and the stage all look healthy (`QUEUE_ONLY` is not a fault); a WAITING item's `batchId` is the join to it, and the pairing is total, so one `--open-only` listing resolves every waiting row. `batches --answers <batch>` is one question's answers item by item — what the person gave (`given`), what was handed back (`answer`), what the item holds now (`current`), with `mismatch` where the first two differ (a prose reply is every item's `given` at once, `givenIsReply`, and is never compared); a `given` the server did not record is read from the resolving run's sheet read (`givenFrom: "trace"`, `--no-trace` to skip). `batches --transcript <batch>` prints the conversation it was asked in, read under the agent that owns it — the stage's asking agent, not the desk that talks to the person. `funnel` and `items` also carry `cost` (all-in USD) and `runs` — so the funnel says *which stage* the money goes to, not merely how much. An item's `runs` spans every stage it passed through and so is not `stageAttempts`, which resets per stage; a `Cost` of `—` means nothing there has ever been claimed, as against `$0.0000`, which means it ran and was free. Cost is not sortable: the endpoint's `--order-by` allow-list does not carry it. |
 | `fruxon triggers ledger passes` | Every time the automation fired, newest first — `admitted` (what the door took), `dispatched` (what the pass claimed and sent to work, questions parked on a human included), `completed` (how many of *this pass's* dispatches reached the terminal stage), `runs`, and the pass's all-in USD. `runs` sits **below** `dispatched` while runs are in flight or when a dispatch went to a person rather than a model — that gap is normal, not a lost item. And a pass's `cost` **rises after** it fired, as those runs finish, so a pass read seconds later reports a floor rather than its bill. An `outcome` other than `FIRED` means no sweep happened: `FILTERED` / `COALESCED` are healthy (nothing to do, or folded into a pass already running), `FAILED` / `FILTER_ERROR` are not. `-n/--limit` bounds the walk. |
 | `fruxon triggers ledger spend/spend-series/item-series` | What the automation spent and what happened to its items, over time. `spend` is the **current UTC calendar** day, week (from Monday) or month (`--period`), so a weekly read on a Monday is hours of spend, not seven days — the figure the automation's spend chip shows: item runs, the conversations its questions are held in, and its report, one row per agent and part (`ITEM_RUNS` / `CONVERSATIONS` / `REPORTS` / `OTHER`). It is **not** the funnel's `cost`, which files item runs under the cell each item sits in *now*; the two overlap, so never add them. `spend-series` is the same figure per `day` or `week` over `--since`/`--until` (default the last 30 days), `--by-stage` adding a column per agent and part; it reads live run records, so a window older than the workspace's run history is counted from `countedFromMs` and the CLI says so. `--interval hour` is refused (tokens are priced per day), and a `week` bucket starts on a Thursday, so it does not line up with `spend --period weekly`. `item-series` counts admitted, finished, set aside and dead per `hour`, `day` or `week` — **events, not items**: a re-driven item that finishes again counts twice and an operator's ignore counts as set aside. Both series omit empty buckets; the footer says how many had anything. A server that predates the series reads 404s (exit 11). |
+| `fruxon triggers check <trigger>` | Audit whether a work-shape automation can move its items, part by part in the order an item meets them: on and taking items in, the last pass read its source, each PROCESS stage's agent exists with a deployed revision and working credentials and models (a rejected credential's row says how many items failed there since), each ASK stage's contact is declared and bound on the asking agent and its oldest question has not waited past a fifth of its answer window, the outcome note's contact reaches a person, this week's spend against the weekly limit, and how many items died in the last 7 days. `{trigger, overall, checks[]}` like `agents check`; exits 12 only on a hard fail, warnings stay 0. Read-only. |
 | `fruxon triggers budget list/get/set/delete` | Spend limits on an automation **as a whole** (`--period DAILY/WEEKLY/MONTHLY`, UTC calendar windows), counting every production run it caused whichever agent made it. Once one is enforced they govern its runs, which then meet only these limits and not the agents' own; with none enforced, each stage stops at its agent's own limit. None by default and every one removable. An enforced limit refuses new work at the limit (stage runs, passes, a question's opening, the report) and holds the stages until the window resets, while turns of conversations it already opened still run (up to 110%); `--no-enforce` only alerts the Application's admins. Needs Editor. |
 | `fruxon triggers ledger redrive/ignore/settle/cancel-batch` | The operator verbs; all confirm and refuse without `--yes` in agent mode. `redrive` returns a DEAD or FAILED item to the queue with its attempts reset — settle any `UNKNOWN` effect first or the next attempt hits the same refusal. `ignore` excludes an item for a **required** reason, which is the only thing separating IGNORED from DEAD later. `settle` answers an effect the platform could not confirm (`--landed` / `--did-not-land` + `--reason`); wrong in the second direction duplicates the write. `cancel-batch` calls off a question — the items go back to READY and a later pass re-batches them. |
 | `fruxon triggers ledger set-data` | Correct a parked (DEAD / FAILED / IGNORED) item's `data` before re-driving it — the value a stage recorded wrong, such as an ASK answer written as `SKIP`, which a plain re-drive would route on again. `--set path=value` (or `path:=<json>`, repeatable) on a top-level key the item carries or a path the shape declares (`produces`, `answeredWhenPath`); a misspelled key is refused with the settable list rather than added. `--reason` is required and lands on the item's history beside every old → new value. `--redrive` re-drives in the same transaction; `redrive` and `redrive-many` take `--set` too. |
@@ -174,9 +177,9 @@ Integrations + tools:
 | `fruxon triggers ledger walk/walk-steps` | `walk --item <id> --yes` chains stage tests: the item's stage (or `--from`), then each stage it advances into, on the data it advanced with, until a real pass would stop too. Each ASK stage it reaches takes `--reply <stage>=<text>` or `--answer <stage>=<value>`; `--agent-revision <agent>=<N>` runs every stage of that agent on an undeployed revision. `stopped.code` is `COMPLETED`, `REACHED_UNTIL` (`--until`), `NOT_ADVANCED` (a `WAIT`, too, and an ADVANCE a pass would undo: a duplicate, or fields the next stage requires), `REPLY_NEEDED` (an ASK stage nobody answered), `STAGE_NOT_TESTABLE`, `MAX_STEPS` (default 10), `TIMEOUT` or `CANCELLED`. Every step is a paid run, so it confirms first and needs `--yes` in agent mode; it exits 0 whenever it ran. `walk-steps <trigger> <walk>` reads a walk back in step order. |
 | `fruxon triggers ledger reset-cursor/purge` | `reset-cursor` moves where the next scan starts, as a compare-and-swap on the version it just read (`--value` omitted = the door's own horizon); it never re-runs admitted work. It is the *after* to `workShape.door.startFrom`'s *before* — a horizon set at creation seeds the cursor before anything sweeps, and is ignored once a pass has read the source. `purge` starts the ledger over — cancels open questions, deletes items and effects, bumps the cursor version — and confirms the exact item count first. The items' transitions stay, as the ledger's history. Destructive; the effects' external targets are not touched. |
 | `fruxon triggers questions list/answer` | The human half of an ASK stage, tenant-wide. `ledger batches <trigger>` answers *what is this automation waiting on*; this answers *what is waiting on anyone* — soonest deadline first, which is how an undelivered question gets found at all. Read **`delivery`** first: `UNDELIVERABLE` (nobody reachable in the slot) and `FAILED` (a target resolved, the send did not land) both mean nobody was asked and nobody will answer unless you do — `QUEUE_ONLY` is healthy. `--undelivered-only` narrows to that pair; `--trigger` filters client-side (the endpoint has no such filter). `answer` settles one on the assignee's behalf and is `--yes`-gated: the reply interpreter **fails closed**, so an answer it cannot place advances nothing and the question stays open, and each item advances only once the stage's `answeredWhenPath` is filled — answering two of three advances two. |
-| `fruxon triggers set-stages <id> --file` | Replace an automation's stages without rewriting the rest of its work shape (a PATCH replaces the whole shape, so this reads it, splices, and posts). Takes a bare stages array or any document carrying one. Pre-flights the two refusals the server only reports after the write: live items at a stage your list drops, and a `door` that will re-expand `source` on save. `--dry-run` prints the merged shape and the warnings; `preview-shape <id> --file` takes the same file and renders what each stage would hand its agent. |
+| `fruxon triggers set-stages <id> --file` | Replace an automation's stages without rewriting the rest of its work shape (a PATCH replaces the whole shape, so this reads it, splices, and posts). Takes a bare stages array or any document carrying one. Pre-flights the two refusals the server only reports after the write: live items at a stage your list drops, and a `door` that will re-expand `source` on save. `--dry-run` prints the merged shape and the warnings; `preview-shape <id> --file` takes the same file and renders what each stage would hand its agent. `--help` documents every stage field the server reads but the CLI passes through untouched — `routes`, `ignoreReasons`, a FORM stage's `answerField`, `formClosing` and `formJoinNotice`. |
 | `fruxon triggers revisions list/get/restore` | A trigger's audit history — every mutation writes a snapshot, and `changeReason` separates a config edit from a binding reconcile. `get -o json | jq .workShape` is the shape as it stood, which is how you undo an edit by hand. `restore` replays one and is **not** a universal undo: it runs the same validation a save does, so a snapshot that drops a stage still holding live items is refused. |
-| `fruxon secrets list/get/grants` | Discover tenant secrets a step can reference — the ids for `allowedSecretIds` and the `{{secret.KEY}}` names, with publish-state and per-agent grants. Metadata only; values are never returned. |
+| `fruxon secrets list/get/grants` | Discover tenant secrets an agent can reference — the ids for `allowedSecretIds` and the `{{secret.KEY}}` names, with publish-state and per-agent grants. Metadata only; values are never returned. |
 | `fruxon participants list/get/create/update/delete/enable/disable` | Manage agent-network participants (people / groups / agents the network routes to). `list` takes `--query` (matches names **and channel addresses and account ids**, so a phone number or handle resolves to an id, and searches both directory tiers by default), `--kind`, `--tier`, `--agent`, `--environment-id`, and pages up to `--limit` / `--all`. `create`/`update` take `--file` (+`--schema`); `enable`/`disable` toggle routing; `delete` confirms + refuses without `--yes` in agent mode. |
 | `fruxon applications roles <id>` | The Application's roster roles — who holds each, who defers to it, and how many holders are `consultable`. The answer to what a `--role` contact binding leaves open: the server takes any role string, so a role with references and no holders refuses at delivery time. `--unheld-only` lists just those. Trust the consultable count — every role path, delivery and consult alike, resolves through the consult-allowed member edges, so a holder without one is tagged but unreachable. |
 | `fruxon applications list/get` | Inspect Applications — the container that owns agents, workflows and people. Every agent belongs to exactly one, and `agents create` needs its id, so this is where you find it. Creating and re-homing an Application itself stays in the dashboard. |
@@ -190,6 +193,30 @@ Integrations + tools:
 | `fruxon agents channels list` / `fruxon agents endpoints` | Inspect a networked agent's channel bindings and resolved provider endpoints (with bot identity). Superseded by `applications entry-points list`, which names the Application answering on each address; these read endpoints outside the published API. |
 | `fruxon skills list/show/create/update/delete` | Browse the tenant's product-skill catalog and author its own skills (resources that attach to agents at runtime). |
 
+### `fruxon dash` — the console
+
+![fruxon dash --demo](https://raw.githubusercontent.com/fruxon-ai/fruxon-sdk/develop/docs/tui/demo.gif)
+
+A read-only, full-screen console for one Application. Home has the week's runs,
+spend and finished items, every agent with its share of the spend, every
+automation with what it holds, and what needs a person; Enter opens an agent
+(overview, the `agents check` rows plus credential, model and budget health,
+runs and their traces) or an automation (its stages, items per day, what
+failed, the `triggers check` rows, a source test and a stage preview). Live
+parts refresh every 5 seconds, totals every minute. It changes nothing.
+
+```bash
+pip install "fruxon[tui]"     # the console runs on Textual, an optional extra
+fruxon dash                   # the Application with the most agents
+fruxon dash --app "Support & Ops"
+fruxon dash --demo            # a made-up workspace, for a first look or a recording
+```
+
+Keys: `↑↓` move, `enter` open, `tab` next panel, `esc` back, `1 2 3` tabs,
+`7 3 1` (or `w` on a tabbed screen) the time window, `a` another Application,
+`r` refresh, `?` every key, `q` quit. It needs a terminal, so agent mode and
+piped output are refused (exit 16).
+
 ### `fruxon agents draft run` — examples
 
 ```bash
@@ -272,9 +299,11 @@ schema = client.get_agent_parameter_metadata("support-agent", revision=1)
 for p in schema["metadata"]:
     print(p["name"], p["type"], "required" if p.get("required") else "optional")
 
-# Test a draft flow without publishing it (same result shape as execute)
-result = client.test("support-agent", {"flow": {...}, "baseRevision": 3, "parameters": {...}})
-for event in client.stream_test("support-agent", {"flow": {...}}):
+# Test a draft without publishing it (same result shape as execute):
+# save the draft on top of revision 3, then run it
+client.put_draft("support-agent", 3, {"definition": {...}, "parametersMetadata": [...]})
+result = client.test("support-agent", 3, {"parameters": {"question": "Hi"}})
+for event in client.stream_test("support-agent", 3, {"parameters": {"question": "Hi"}}):
     ...
 
 # Integrations & tools — the connections + capabilities agents are built from

{fruxon-1.0.0 → fruxon-2.0.1}/README.md

@@ -47,7 +47,7 @@ Auth:
 
 | Command | What it does |
 | --- | --- |
-| `fruxon login` | Browser-based sign-in. token goes to your OS keychain (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows). `--token $KEY` for headless. `--preset observer\|operator\|developer\|maintainer\|admin` declares the access level the key is minted with (default: developer); the approval page shows it for the user to approve or deny. |
+| `fruxon login` | Browser-based sign-in. token goes to your OS keychain (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows). `--token $KEY` for headless. `--preset observer\|operator\|developer\|maintainer\|admin` declares the access level the key is minted with (default: developer); the approval page shows it for the user to approve or deny. Adds a workspace without moving the default (the first sign-in sets it); `--set-default` moves it. |
 | `fruxon whoami` | Show the active key/workspace and where each value came from (flag, env, keychain, file). |
 | `fruxon logout` | Forget stored credentials. `--workspace <id>` signs out of one and leaves the rest; `--all` clears every one. |
 | `fruxon workspaces list` | Which workspaces this machine is signed in to, each with its host and cell, and which one is the default. Offline, no auth. |
@@ -63,7 +63,7 @@ Execution:
 | `fruxon agents executions get <agent> <record-id>` | Record summary for one execution — status, duration, cost, tokens. |
 | `fruxon agents executions trace <agent> <record-id>` | Step-by-step trace of one execution — LLM/tool calls, durations, and for a tool that records it, where the call's time went (service stages vs. unaccounted). Flags a result the model got offloaded or projected. Prints a quality check's verdict (score, criteria, rationale) under its `JUDGE` step, and marks a reply the check refused. `--show-io` also prints each tool step's parameters and result (the payload lives at `steps[].result`, a sibling of `toolTrace` — whose `resultDelivery` carries sizes only). `--show-system` labels each LLM step's system prompt block by block — your prompt vs. the platform's `<tag>` blocks, sizes, and the cache breakpoint. |
 | `fruxon agents executions result <agent> <record-id>` | The final output one execution produced. |
-| `fruxon agents approvals list/get/respond/cancel <agent>` | Operate a step's human-in-the-loop gate — see what a run is blocked on and answer it. `respond`/`cancel` confirm first and refuse without `--yes` in agent mode (an LLM must not silently auto-approve). |
+| `fruxon agents approvals list/get/respond/cancel <agent>` | Operate human-in-the-loop approval gates — see what a run is blocked on and answer it. `respond`/`cancel` confirm first and refuse without `--yes` in agent mode (an LLM must not silently auto-approve). |
 | `fruxon agents memory list/subjects/get/forget-subject <agent>` | Inspect and prune what an agent remembers. `list` filters server-side by `--subject`/`--query`/`--scope`; `forget-subject` is a GDPR-style delete (confirms; refuses without `--yes` in agent mode). |
 | `fruxon agents topics list/search/get/messages/sessions <agent>` + `fruxon agents inbox <agent>` | Read the conversation spine — the agent's topics (threads), one topic's transcript, its episodes, and its inbox (what it's focused on). `list`/`search` filter server-side by `--state`/`--participant`/`--query`. Read-only. Each message carries `author` — a human colleague's turn is stored as `ASSISTANT` on purpose, so `role` alone cannot tell their reply from the agent's; `HUMAN_OPERATOR` can. A message the runtime *withheld* is in no transcript at all — see `fruxon messages list`. `sessions` explains a fresh, blind session: a topic outlives its sessions, and `endCause` on the previous one (`CONSOLE_ALREADY_RESOLVED` — a human closed it in the provider's console) is why the next started with no history. |
 | `fruxon escalations list/history/unhandled/policy/ack` | What happened when an agent handed a conversation to a person. `list` is the queue (live takeovers + degraded escalations nobody was reachable for); `unhandled` is the append-only ledger under it. **`history` is the record of closed console-routed takeovers** — those leave the queue, so `list --status ALL` answers `[]` about a conversation a human worked for half an hour. Read `humanObservedAt` before believing a `RESOLVED`: null means nobody was ever seen picking it up. `policy <agent>` resolves who the *next* escalation would reach — an empty ladder under `NATIVE_HANDOFF` is correct, the console supplies the human. |
@@ -113,8 +113,8 @@ Integrations + tools:
 | `fruxon tools list/get/create/update/delete/run` | Manage the tools inside an integration. Integration-scoped. `get` and `run` select the tool with `--tool`; `run` executes it outside any agent — real credentials, real result — with `-p key=value`, and `-c` naming the config that supplies credentials. The tenant list API hides internal `knowledge_base` / `assets` tools; `tools list` recovers them by ID and lists them like any other (`--no-include-internal` for the raw server answer). |
 | `fruxon keys list/mint/revoke/delete/history/scopes` | Audit and revoke scoped tokens. Minting opens the dashboard so the secret never enters the CLI process. |
 | `fruxon llm-providers list/get/models` | Browse LLM providers and models supported at the tenant level. |
-| `fruxon llm-providers configs list/get/test/publish` | The workspace's saved LLM credentials — the `provider.tenantConfigId` a step pins. `get` shows the draft (secrets masked), the published revision and last known health. `test` probes the draft on every provider surface that shares the credential (or just one, given that surface's provider id), one line per failing surface, exit 12 on failure (`llm_providers:test`). `publish` ships the draft as a new revision that every agent on the config switches to — it confirms, needs `--yes` in agent mode, and does not wait on a passing test (`llm_providers:write`). |
-| `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets a step can query — upload local files, wait for async ingestion, inspect operations, and use the ids for `assetConfig.assetIds`. `delete` confirms + refuses without `--yes` in agent mode. |
+| `fruxon llm-providers configs list/get/test/publish` | The workspace's saved LLM credentials — the `provider.tenantConfigId` an agent pins. `get` shows the draft (secrets masked), the published revision and last known health. `test` probes the draft on every provider surface that shares the credential (or just one, given that surface's provider id), one line per failing surface, exit 12 on failure (`llm_providers:test`). `publish` ships the draft as a new revision that every agent on the config switches to — it confirms, needs `--yes` in agent mode, and does not wait on a passing test (`llm_providers:write`). |
+| `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets an agent can query — upload local files, wait for async ingestion, inspect operations, and use the ids for `assetConfig.assetIds`. `delete` confirms + refuses without `--yes` in agent mode. |
 | `fruxon knowledge-bases list/get/create/update/publish/archive/delete` | The authored, reviewable corpus behind a `manual_knowledge` asset — **not** the asset itself, which is what gets searched (`get` prints the asset id as `backingAssetId`). **`publish` is the step that makes any of it findable**: only `PUBLISHED` documents travel in a snapshot, and only publishing the *base* moves one, so a base full of finished articles answers nothing until it runs. It returns on *acceptance*, not searchability — RAG ingests afterwards, so a pending publish state is normal. `list` hides archived bases, which keep answering for agents already attached to them; `delete` is refused while an agent revision still attaches one, and `archive` is the reversible path. |
 | `fruxon knowledge-bases usage <kb>` | Whether agents actually use the base: searches per hour, day or week (`--interval`), the passage tokens each search handed the agent, how many found nothing (split from searches that **could not fully search** it — index missing or still building, a phrasing failed), and which agents searched (up to 20 you can open, the rest counted together). `--origin test` counts test runs instead of production. Retrieved tokens are counted by the search index, so what the model read can be less when a large result is trimmed or offloaded. Searches are recorded from 15 October 2026 and kept 90 days at most, so a window reaching further back says where counting began rather than showing empty days. A 404 is a wrong id or a backend that predates the read. |
 | `fruxon knowledge-bases notices/notice/post-notice/edit-notice/extend-notice/withdraw-notice` | Time-boxed notices on a base — an outage being fixed, a known bug, a closure. **Not documents**: never indexed or published, so every agent attaching the base is given each active notice whole from its next turn. `post-notice --valid-for 4h` (or `--until`) — every notice ends, at most 30 days after it was posted, and a base holds ten active ones (409 `notice_limit` / `notice_too_long`, each with its remedy). The body is Markdown, at most 1,200 characters, best as four headings: *What is happening*, *Applies when*, *Tell the customer*, *Do not*. A time without an offset is read in the notice's zone (`--time-zone`, else this machine's), which is also the zone agents tell customers the end in. `withdraw-notice` tells each conversation that was given it, on its next turn, that it ended; it confirms, and needs `--yes` in agent mode. An ended notice is not extended: `post-notice --from <id>` posts it again as a new one. |
@@ -123,13 +123,14 @@ Integrations + tools:
 | `fruxon knowledge-bases consolidate` → `apply` / `calibrate` | Two steps on purpose. `consolidate` queues a **report** of near-duplicate clusters and writes nothing — a standalone pass can no longer merge as it goes, and the old `--apply` is refused. `apply <kb> <run> --cluster <id>` (or `--all`) merges the clusters you accepted: the report's version rides along as a compare-and-set read off the run itself, and each member is revalidated against the content hash the report recorded, so a cluster whose documents moved comes back STALE and is left **entirely** alone rather than partly merged. It re-runs the base's consolidator agent per cluster, so a base without a deployed one is refused. `calibrate` records what a person reviewed a report under — it applies and publishes nothing, and is what reopens automatic source approval. |
 | `fruxon knowledge-bases source list/get/add/update/plan-update/preview/activity/passes/sync/pause/resume/archive/unarchive/fork/delete` | The pipelines that read a customer's history and write articles. `managementMode` decides **who owns the implementation**, which is what the verbs key on: a LINKED source's resources are yours and survive a `delete`, a MANAGED one's agents, automation and ledger go with it — and `fork` flips managed to linked, keeping the history, one-way. **Stopped is the default**: a built source lands paused and `unarchive` returns one paused, so `resume` and `sync` confirm (they start reading someone's history, and dispatched items cost a run each) while `pause` and `archive` do not. `preview` admits nothing and is deliberately not narrowed by the watermark — a caught-up source would otherwise look broken — and reports **floors, not totals**, once a ceiling stopped the scan. `activity` speaks the ledger's vocabulary, so `ready` is backlog rather than motion, and a missing work ledger is reduced health rather than an error. |
 | `fruxon assets search/documents/chunks` | Reproduce and inspect a retrieval. `search` runs the same query an agent's `search_assets` does (`--mode HYBRID/VECTOR/FULL_TEXT`, `--top-k`, fusion weights) — note `score` is on a different scale per mode, and in hybrid the top hit is always 1.0. `documents` lists what the index contains (a `chunkCount` of 0 means that file yielded no indexable text); `chunks` reads one document's chunks in order. The `documentId` these print is the **index's** id, which is what `chunks` takes — on a knowledge base's backing asset it is not the editable document's id, and it changes whenever a document's body is re-indexed. The `fileName` (`<knowledge document id>.md`) is the document a `knowledge_base` tool would edit. |
-| `fruxon metrics list` | Browse the evaluation-metric catalog — the ids a step's LLM-judge config (`judge.metrics[]`) binds, with a default weight each. |
+| `fruxon metrics list` | Browse the evaluation-metric catalog — the ids an agent's quality check (`judge.metrics[]`) binds, with a default weight each. |
 | `fruxon triggers list/get/create/update/delete/fire/bind/unbind` | Manage triggers — the schedule/event sources that fire agents. `create`/`update` take `--file` (+`--schema`); `create` also takes `--application`, the Application that will own the trigger and must own everything it fires. `bind`/`unbind` wire which agents fire; `fire` runs it now (`--close-gathering` also runs every group a batch stage is gathering). `fire`/`delete`/`unbind` confirm + refuse without `--yes` in agent mode. The control plane for autonomy. `get` returns the full stored `workShape` and every `scheduleTimes` slot, so `get -o json | jq .workShape` produces a body `update --file` can post straight back — a PATCH replaces the whole shape, so edit what you read. Each binding carries its `outputDestination` (where a fired run's reply is delivered, e.g. a Telegram group) verbatim, and text output names it as `delivers to telegram -5129894975 (Daria Group)`; a `bindings` list posted back without it unpins the delivery. |
 | `fruxon triggers doors` | The pre-configured source doors a work shape can be built on — the **first** question of authoring an automation, and the one `--schema` cannot answer: it tells you a `workShape.door` carries a `doorId`, not which ids exist. Each row is the integration a chosen `integrationConfigId` must belong to, plus the one query field that is genuinely yours (label + example), and `supportsStartFrom` — whether that door's source accepts a lower bound, and so whether a `door.startFrom` horizon does anything there. `door.skipWhen` is the other field that is yours rather than the integration's: a `{match, conditions[]}` filter, same shape as a trigger's event filter, whose matching records are **never admitted** — no item, no stage, no model call. It has to live on the `door` because saving re-expands `source` from it, so the same filter written onto `source` is discarded by the next save. `door.projection` is the third: a list of dotted record paths naming the fields an admitted item **keeps**, with the door's own `defaultProjection` as the suggestion to seed it from — without one an item carries the whole record, into the Work grid and into every stage's prompt on every pass. Read that against the door's `labelPaths` (or, for the sheet and table doors, `labelFieldName` naming the field whose answer picks the label column): those are where an item's title comes from, and a projection that drops one is refused at save time rather than quietly repaired. Read-only and static: a door is a claim that one combination of list tool, identity path and watermark actually works, made in platform code by someone who verified it. An integration with no door is still fully usable — configure `workShape.source` by hand. |
-| `fruxon triggers preview-shape/test-source` | Dry-run a work shape before saving or activating it; both write nothing. `preview-shape` renders, per stage, the resolved instruction, the whole `user_query` the agent is handed (item payload included), and the JSON schema the stage's declared `produces` keys become — against a real backlog item when you name a trigger. `--file` takes a draft shape, or just the stages — the same file `set-stages` takes — which it merges into the named trigger's saved shape the way `set-stages` would, so the preview is of what that save would write. `test-source` runs the door's list tool once and says, per record, whether admission would take it, plus the exact arguments the tool was called with (for Gmail, your query with the day-granular `after:` folded in). Records a `door.skipWhen` filter would drop read `FILTERED`, with a footer count — which is where to see what a rule costs before it goes onto a live automation. `--count` pages the whole door instead and answers how much is waiting: the total, how many the filter drops, how many the ledger already holds, how many clear the watermark, and which server ceiling stopped the scan — so `total − filtered − already held` is the work that would actually arrive. Each record prints **as the item will carry it** — narrowed to the shape's `door.projection`, with an `item keeps` line naming the paths that survived, so a field your projection drops and a field the source never sent are not the same silence. `--file` tests a shape being edited — and a draft whose `door.startFrom` (Unix ms) sets a first-run horizon gets a `first run sends` line with the `after:` term that horizon produces, which is the only place to see it: `startFrom` seeds the ledger cursor once, when the ledger is created. |
+| `fruxon triggers preview-shape/test-source` | Dry-run a work shape before saving or activating it; both write nothing. `preview-shape` renders, per stage, the resolved instruction, the whole `user_query` the agent is handed (item payload included), and the JSON schema the stage's declared `produces` keys become — against a real backlog item when you name a trigger. A FORM stage shows its form message and, under it, the `join notice` sent when more items join the open form, both in the stage's own `formClosing` / `formJoinNotice` wording. `--file` takes a draft shape, or just the stages — the same file `set-stages` takes — which it merges into the named trigger's saved shape the way `set-stages` would, so the preview is of what that save would write. `test-source` runs the door's list tool once and says, per record, whether admission would take it, plus the exact arguments the tool was called with (for Gmail, your query with the day-granular `after:` folded in). Records a `door.skipWhen` filter would drop read `FILTERED`, with a footer count — which is where to see what a rule costs before it goes onto a live automation. `--count` pages the whole door instead and answers how much is waiting: the total, how many the filter drops, how many the ledger already holds, how many clear the watermark, and which server ceiling stopped the scan — so `total − filtered − already held` is the work that would actually arrive. Each record prints **as the item will carry it** — narrowed to the shape's `door.projection`, with an `item keeps` line naming the paths that survived, so a field your projection drops and a field the source never sent are not the same silence. `--file` tests a shape being edited — and a draft whose `door.startFrom` (Unix ms) sets a first-run horizon gets a `first run sends` line with the `after:` term that horizon produces, which is the only place to see it: `startFrom` seeds the ledger cursor once, when the ledger is created. |
 | `fruxon triggers ledger funnel/items/cursor/transitions/effects/batches` | The work items a schedule trigger's work shape admitted. `funnel` counts per stage and status (every item is in exactly one cell). `items` is the grid — `--stage`, `--status`, `--ignore-reason`, `--item-key` (client-side; the endpoint has no such filter), each item's `label` (what the Work grid calls the row, as against the provider's opaque `itemKey`), and its accumulated `data`, which is where a stage's declared `produces` keys land. A listing is **one page of 20** that reports how many matched in total — a ledger's healthy state is thousands of rows served ten per request, so an unbounded walk is rate-limited long before the end; `-n` sizes the page and `--all` walks the lot. `--ignore-reason` narrows to the items one exclusion reason set aside — the same filter `redrive-many` selects by, matched whole and case-sensitively, so it is how you read a batch before putting it back. `--where field=value` (or `!=`, repeatable, dotted for a nested field) selects by what a stage wrote into `data` — `--where destination=SKIP` — matched whole and case-sensitively, as text and as the number, boolean or null it spells; the server filters and the CLI re-applies it, so an older server is slower, never wrong. `cursor` is the watermark and its freshness. `transitions` is one item's attempt history; `effects` is what it did to the outside world — an `UNKNOWN` row parks the item until someone settles it. `batches` is what an ASK stage is waiting on a human for — read its `delivery` first, because `UNDELIVERABLE` / `FAILED` mean nobody was asked and nobody will answer while the batch, the count and the stage all look healthy (`QUEUE_ONLY` is not a fault); a WAITING item's `batchId` is the join to it, and the pairing is total, so one `--open-only` listing resolves every waiting row. `batches --answers <batch>` is one question's answers item by item — what the person gave (`given`), what was handed back (`answer`), what the item holds now (`current`), with `mismatch` where the first two differ (a prose reply is every item's `given` at once, `givenIsReply`, and is never compared); a `given` the server did not record is read from the resolving run's sheet read (`givenFrom: "trace"`, `--no-trace` to skip). `batches --transcript <batch>` prints the conversation it was asked in, read under the agent that owns it — the stage's asking agent, not the desk that talks to the person. `funnel` and `items` also carry `cost` (all-in USD) and `runs` — so the funnel says *which stage* the money goes to, not merely how much. An item's `runs` spans every stage it passed through and so is not `stageAttempts`, which resets per stage; a `Cost` of `—` means nothing there has ever been claimed, as against `$0.0000`, which means it ran and was free. Cost is not sortable: the endpoint's `--order-by` allow-list does not carry it. |
 | `fruxon triggers ledger passes` | Every time the automation fired, newest first — `admitted` (what the door took), `dispatched` (what the pass claimed and sent to work, questions parked on a human included), `completed` (how many of *this pass's* dispatches reached the terminal stage), `runs`, and the pass's all-in USD. `runs` sits **below** `dispatched` while runs are in flight or when a dispatch went to a person rather than a model — that gap is normal, not a lost item. And a pass's `cost` **rises after** it fired, as those runs finish, so a pass read seconds later reports a floor rather than its bill. An `outcome` other than `FIRED` means no sweep happened: `FILTERED` / `COALESCED` are healthy (nothing to do, or folded into a pass already running), `FAILED` / `FILTER_ERROR` are not. `-n/--limit` bounds the walk. |
 | `fruxon triggers ledger spend/spend-series/item-series` | What the automation spent and what happened to its items, over time. `spend` is the **current UTC calendar** day, week (from Monday) or month (`--period`), so a weekly read on a Monday is hours of spend, not seven days — the figure the automation's spend chip shows: item runs, the conversations its questions are held in, and its report, one row per agent and part (`ITEM_RUNS` / `CONVERSATIONS` / `REPORTS` / `OTHER`). It is **not** the funnel's `cost`, which files item runs under the cell each item sits in *now*; the two overlap, so never add them. `spend-series` is the same figure per `day` or `week` over `--since`/`--until` (default the last 30 days), `--by-stage` adding a column per agent and part; it reads live run records, so a window older than the workspace's run history is counted from `countedFromMs` and the CLI says so. `--interval hour` is refused (tokens are priced per day), and a `week` bucket starts on a Thursday, so it does not line up with `spend --period weekly`. `item-series` counts admitted, finished, set aside and dead per `hour`, `day` or `week` — **events, not items**: a re-driven item that finishes again counts twice and an operator's ignore counts as set aside. Both series omit empty buckets; the footer says how many had anything. A server that predates the series reads 404s (exit 11). |
+| `fruxon triggers check <trigger>` | Audit whether a work-shape automation can move its items, part by part in the order an item meets them: on and taking items in, the last pass read its source, each PROCESS stage's agent exists with a deployed revision and working credentials and models (a rejected credential's row says how many items failed there since), each ASK stage's contact is declared and bound on the asking agent and its oldest question has not waited past a fifth of its answer window, the outcome note's contact reaches a person, this week's spend against the weekly limit, and how many items died in the last 7 days. `{trigger, overall, checks[]}` like `agents check`; exits 12 only on a hard fail, warnings stay 0. Read-only. |
 | `fruxon triggers budget list/get/set/delete` | Spend limits on an automation **as a whole** (`--period DAILY/WEEKLY/MONTHLY`, UTC calendar windows), counting every production run it caused whichever agent made it. Once one is enforced they govern its runs, which then meet only these limits and not the agents' own; with none enforced, each stage stops at its agent's own limit. None by default and every one removable. An enforced limit refuses new work at the limit (stage runs, passes, a question's opening, the report) and holds the stages until the window resets, while turns of conversations it already opened still run (up to 110%); `--no-enforce` only alerts the Application's admins. Needs Editor. |
 | `fruxon triggers ledger redrive/ignore/settle/cancel-batch` | The operator verbs; all confirm and refuse without `--yes` in agent mode. `redrive` returns a DEAD or FAILED item to the queue with its attempts reset — settle any `UNKNOWN` effect first or the next attempt hits the same refusal. `ignore` excludes an item for a **required** reason, which is the only thing separating IGNORED from DEAD later. `settle` answers an effect the platform could not confirm (`--landed` / `--did-not-land` + `--reason`); wrong in the second direction duplicates the write. `cancel-batch` calls off a question — the items go back to READY and a later pass re-batches them. |
 | `fruxon triggers ledger set-data` | Correct a parked (DEAD / FAILED / IGNORED) item's `data` before re-driving it — the value a stage recorded wrong, such as an ASK answer written as `SKIP`, which a plain re-drive would route on again. `--set path=value` (or `path:=<json>`, repeatable) on a top-level key the item carries or a path the shape declares (`produces`, `answeredWhenPath`); a misspelled key is refused with the settable list rather than added. `--reason` is required and lands on the item's history beside every old → new value. `--redrive` re-drives in the same transaction; `redrive` and `redrive-many` take `--set` too. |
@@ -141,9 +142,9 @@ Integrations + tools:
 | `fruxon triggers ledger walk/walk-steps` | `walk --item <id> --yes` chains stage tests: the item's stage (or `--from`), then each stage it advances into, on the data it advanced with, until a real pass would stop too. Each ASK stage it reaches takes `--reply <stage>=<text>` or `--answer <stage>=<value>`; `--agent-revision <agent>=<N>` runs every stage of that agent on an undeployed revision. `stopped.code` is `COMPLETED`, `REACHED_UNTIL` (`--until`), `NOT_ADVANCED` (a `WAIT`, too, and an ADVANCE a pass would undo: a duplicate, or fields the next stage requires), `REPLY_NEEDED` (an ASK stage nobody answered), `STAGE_NOT_TESTABLE`, `MAX_STEPS` (default 10), `TIMEOUT` or `CANCELLED`. Every step is a paid run, so it confirms first and needs `--yes` in agent mode; it exits 0 whenever it ran. `walk-steps <trigger> <walk>` reads a walk back in step order. |
 | `fruxon triggers ledger reset-cursor/purge` | `reset-cursor` moves where the next scan starts, as a compare-and-swap on the version it just read (`--value` omitted = the door's own horizon); it never re-runs admitted work. It is the *after* to `workShape.door.startFrom`'s *before* — a horizon set at creation seeds the cursor before anything sweeps, and is ignored once a pass has read the source. `purge` starts the ledger over — cancels open questions, deletes items and effects, bumps the cursor version — and confirms the exact item count first. The items' transitions stay, as the ledger's history. Destructive; the effects' external targets are not touched. |
 | `fruxon triggers questions list/answer` | The human half of an ASK stage, tenant-wide. `ledger batches <trigger>` answers *what is this automation waiting on*; this answers *what is waiting on anyone* — soonest deadline first, which is how an undelivered question gets found at all. Read **`delivery`** first: `UNDELIVERABLE` (nobody reachable in the slot) and `FAILED` (a target resolved, the send did not land) both mean nobody was asked and nobody will answer unless you do — `QUEUE_ONLY` is healthy. `--undelivered-only` narrows to that pair; `--trigger` filters client-side (the endpoint has no such filter). `answer` settles one on the assignee's behalf and is `--yes`-gated: the reply interpreter **fails closed**, so an answer it cannot place advances nothing and the question stays open, and each item advances only once the stage's `answeredWhenPath` is filled — answering two of three advances two. |
-| `fruxon triggers set-stages <id> --file` | Replace an automation's stages without rewriting the rest of its work shape (a PATCH replaces the whole shape, so this reads it, splices, and posts). Takes a bare stages array or any document carrying one. Pre-flights the two refusals the server only reports after the write: live items at a stage your list drops, and a `door` that will re-expand `source` on save. `--dry-run` prints the merged shape and the warnings; `preview-shape <id> --file` takes the same file and renders what each stage would hand its agent. |
+| `fruxon triggers set-stages <id> --file` | Replace an automation's stages without rewriting the rest of its work shape (a PATCH replaces the whole shape, so this reads it, splices, and posts). Takes a bare stages array or any document carrying one. Pre-flights the two refusals the server only reports after the write: live items at a stage your list drops, and a `door` that will re-expand `source` on save. `--dry-run` prints the merged shape and the warnings; `preview-shape <id> --file` takes the same file and renders what each stage would hand its agent. `--help` documents every stage field the server reads but the CLI passes through untouched — `routes`, `ignoreReasons`, a FORM stage's `answerField`, `formClosing` and `formJoinNotice`. |
 | `fruxon triggers revisions list/get/restore` | A trigger's audit history — every mutation writes a snapshot, and `changeReason` separates a config edit from a binding reconcile. `get -o json | jq .workShape` is the shape as it stood, which is how you undo an edit by hand. `restore` replays one and is **not** a universal undo: it runs the same validation a save does, so a snapshot that drops a stage still holding live items is refused. |
-| `fruxon secrets list/get/grants` | Discover tenant secrets a step can reference — the ids for `allowedSecretIds` and the `{{secret.KEY}}` names, with publish-state and per-agent grants. Metadata only; values are never returned. |
+| `fruxon secrets list/get/grants` | Discover tenant secrets an agent can reference — the ids for `allowedSecretIds` and the `{{secret.KEY}}` names, with publish-state and per-agent grants. Metadata only; values are never returned. |
 | `fruxon participants list/get/create/update/delete/enable/disable` | Manage agent-network participants (people / groups / agents the network routes to). `list` takes `--query` (matches names **and channel addresses and account ids**, so a phone number or handle resolves to an id, and searches both directory tiers by default), `--kind`, `--tier`, `--agent`, `--environment-id`, and pages up to `--limit` / `--all`. `create`/`update` take `--file` (+`--schema`); `enable`/`disable` toggle routing; `delete` confirms + refuses without `--yes` in agent mode. |
 | `fruxon applications roles <id>` | The Application's roster roles — who holds each, who defers to it, and how many holders are `consultable`. The answer to what a `--role` contact binding leaves open: the server takes any role string, so a role with references and no holders refuses at delivery time. `--unheld-only` lists just those. Trust the consultable count — every role path, delivery and consult alike, resolves through the consult-allowed member edges, so a holder without one is tagged but unreachable. |
 | `fruxon applications list/get` | Inspect Applications — the container that owns agents, workflows and people. Every agent belongs to exactly one, and `agents create` needs its id, so this is where you find it. Creating and re-homing an Application itself stays in the dashboard. |
@@ -157,6 +158,30 @@ Integrations + tools:
 | `fruxon agents channels list` / `fruxon agents endpoints` | Inspect a networked agent's channel bindings and resolved provider endpoints (with bot identity). Superseded by `applications entry-points list`, which names the Application answering on each address; these read endpoints outside the published API. |
 | `fruxon skills list/show/create/update/delete` | Browse the tenant's product-skill catalog and author its own skills (resources that attach to agents at runtime). |
 
+### `fruxon dash` — the console
+
+![fruxon dash --demo](https://raw.githubusercontent.com/fruxon-ai/fruxon-sdk/develop/docs/tui/demo.gif)
+
+A read-only, full-screen console for one Application. Home has the week's runs,
+spend and finished items, every agent with its share of the spend, every
+automation with what it holds, and what needs a person; Enter opens an agent
+(overview, the `agents check` rows plus credential, model and budget health,
+runs and their traces) or an automation (its stages, items per day, what
+failed, the `triggers check` rows, a source test and a stage preview). Live
+parts refresh every 5 seconds, totals every minute. It changes nothing.
+
+```bash
+pip install "fruxon[tui]"     # the console runs on Textual, an optional extra
+fruxon dash                   # the Application with the most agents
+fruxon dash --app "Support & Ops"
+fruxon dash --demo            # a made-up workspace, for a first look or a recording
+```
+
+Keys: `↑↓` move, `enter` open, `tab` next panel, `esc` back, `1 2 3` tabs,
+`7 3 1` (or `w` on a tabbed screen) the time window, `a` another Application,
+`r` refresh, `?` every key, `q` quit. It needs a terminal, so agent mode and
+piped output are refused (exit 16).
+
 ### `fruxon agents draft run` — examples
 
 ```bash
@@ -239,9 +264,11 @@ schema = client.get_agent_parameter_metadata("support-agent", revision=1)
 for p in schema["metadata"]:
     print(p["name"], p["type"], "required" if p.get("required") else "optional")
 
-# Test a draft flow without publishing it (same result shape as execute)
-result = client.test("support-agent", {"flow": {...}, "baseRevision": 3, "parameters": {...}})
-for event in client.stream_test("support-agent", {"flow": {...}}):
+# Test a draft without publishing it (same result shape as execute):
+# save the draft on top of revision 3, then run it
+client.put_draft("support-agent", 3, {"definition": {...}, "parametersMetadata": [...]})
+result = client.test("support-agent", 3, {"parameters": {"question": "Hi"}})
+for event in client.stream_test("support-agent", 3, {"parameters": {"question": "Hi"}}):
     ...
 
 # Integrations & tools — the connections + capabilities agents are built from

{fruxon-1.0.0 → fruxon-2.0.1}/pyproject.toml

@@ -92,6 +92,12 @@ dependencies = [
 requires-python = ">= 3.10"
 
 [project.optional-dependencies]
+# ``fruxon dash`` — the read-only, full-screen console. Kept out of the base
+# install so ``pip install fruxon`` stays as small as it was and the CLI's
+# start-up never pays for it: the console imports Textual only when it runs.
+tui = [
+    "textual>=8.2",
+]
 test = [
     "coverage",  # testing
     "pytest",  # testing

{fruxon-1.0.0 → fruxon-2.0.1}/src/fruxon/_ssl.py

@@ -52,6 +52,7 @@ def context_for(base_url: str) -> ssl.SSLContext | None:
     """
     host = urllib.parse.urlparse(base_url).hostname or ""
     if host in _LOOPBACK_HOSTS:
+        # nosemgrep: unverified-ssl-context — loopback hosts only; the request never leaves this machine
         return ssl._create_unverified_context()  # noqa: S323 — loopback only
 
     bundle = os.environ.get("FRUXON_CA_BUNDLE", "").strip()
@@ -62,6 +63,7 @@ def context_for(base_url: str) -> ssl.SSLContext | None:
 
     if _insecure_enabled():
         _warn_insecure_once(host)
+        # nosemgrep: unverified-ssl-context — explicit FRUXON_INSECURE=1 opt-in, warned about on stderr
         return ssl._create_unverified_context()  # noqa: S323 — opt-in
 
     return _default_or_certifi_context()

{fruxon-1.0.0 → fruxon-2.0.1}/src/fruxon/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.0'
-__version_tuple__ = version_tuple = (1, 0, 0)
+__version__ = version = '2.0.1'
+__version_tuple__ = version_tuple = (2, 0, 1)
 
 __commit_id__ = commit_id = None

fruxon-2.0.1/src/fruxon/checks/__init__.py

@@ -0,0 +1,101 @@
+"""Read-only audits shared by the CLI and the ``fruxon dash`` console.
+
+A check reads a resource and the surfaces around it and says, row by row,
+whether it is wired to run. The rows are plain data: :class:`CheckResult`
+carries no markup and decides nothing about how it is shown, so
+``fruxon agents check`` prints them as text or JSON and the console lays
+them out in a panel, and both say the same thing because they ran the same
+code.
+
+Nothing here writes. Nothing here imports :mod:`fruxon.cli`, either — the
+console is built without the CLI, and a check that reached into it would
+drag the whole command tree in with it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# The four outcomes a row can have. ``skip`` is "nothing to check here" (no
+# consult step, so no roster to audit), which is a pass, not a warning.
+STATUSES = ("ok", "warn", "fail", "skip")
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """One audited surface: what was checked, how it came out, and what to do.
+
+    ``detail`` is what was found, in a sentence. ``hint`` is the next step —
+    usually a CLI command — or ``None`` when there is nothing to do.
+    ``explain`` says what the row checks and why it matters, for a reader who
+    has never seen it before; the CLI does not print it, the console shows it
+    beside the selected row.
+
+    ``fix`` says where the finding is put right, as a short reference rather
+    than a URL — ``editor`` (the agent's definition), ``channels``,
+    ``integration:<id>``, ``llm-provider:<id>``, ``work:<status>:<stage>``
+    and so on — so the console can link to the page without the checks
+    knowing the web app's routes.
+    """
+
+    title: str
+    status: str
+    detail: str
+    hint: str | None = None
+    explain: str = ""
+    fix: str = ""
+
+    def to_dict(self) -> dict:
+        """The row as ``agents check -o json`` has always printed it."""
+        return {"title": self.title, "status": self.status, "detail": self.detail, "hint": self.hint}
+
+
+@dataclass(frozen=True)
+class CheckReport:
+    """Every row of one audit, plus what the console needs to draw around it.
+
+    ``revision`` is the revision the audit read (``None`` when there is
+    none). ``revision_body`` is that revision as fetched, kept so a caller
+    that wants to draw the agent does not have to fetch it again.
+    """
+
+    subject: str
+    checks: tuple[CheckResult, ...] = ()
+    revision: int | None = None
+    revision_body: dict | None = field(default=None, compare=False)
+
+    @property
+    def overall(self) -> str:
+        """``fail`` if any row failed, else ``warn`` if any warned, else ``ok``."""
+        return overall_status(self.checks)
+
+    def counts(self) -> dict[str, int]:
+        """How many rows passed (``ok`` and ``skip``), warned and failed."""
+        return {
+            "passed": sum(1 for c in self.checks if c.status in ("ok", "skip")),
+            "warnings": sum(1 for c in self.checks if c.status == "warn"),
+            "failing": sum(1 for c in self.checks if c.status == "fail"),
+        }
+
+
+def overall_status(checks) -> str:
+    """The worst status among ``checks``: ``fail`` › ``warn`` › ``ok``."""
+    statuses = {c.status for c in checks}
+    if "fail" in statuses:
+        return "fail"
+    if "warn" in statuses:
+        return "warn"
+    return "ok"
+
+
+def shape_get(node: dict, name: str) -> object:
+    """Read a work-shape key by camelCase name, tolerating PascalCase.
+
+    The API speaks camelCase, but the stored JSONB is PascalCase — so a
+    shape pasted out of the database (or a stage file hand-written against
+    it) reads the other way. Only the display path is tolerant; what gets
+    posted back is whatever the caller supplied, untouched.
+    """
+    if name in node:
+        return node[name]
+    return node.get(name[:1].upper() + name[1:])