List cash scope by account type
well_list_cash_scopeList the account types a reader can count as cash, each with what it holds. This is what the cash-scope card offers; it measures nothing well_list_account_balances did not already read.
Each entry in groups is one account type: account_type, account_count, and subtotals — one native amount per currency, never converted and never blended. Sorted with the largest holdings first, so the biggest decision reads first. A type with no accounts is NOT listed: counting it would change nothing, so it is not a choice.
Only proven accounts the workspace owns are folded here. Ownership is settled by a fact about the account, not by a preference, so it is never offered as a choice on this card. excluded_not_owned counts accounts another company owns. estimated_accounts counts self-candidate accounts: they are estimates, stay out of every group, and are never part of proven cash. unsettled_ownership counts accounts whose owner is unanswered; those are NOT in any group, and a non-zero count means the reader has a repair to do before any total is trustworthy. Say when either count is non-zero rather than presenting the groups as the whole picture.
unreadable_balances counts owned accounts whose stored balance could not be read at all; unreadable_currency counts those carrying an amount with no currency code anywhere. Both are in no subtotal, so state them beside any figure rather than presenting one that silently skipped them — and keep them apart, because they are different repairs: a balance that did not arrive against a row that arrived incomplete.
folded_duplicates counts rows left out because they are a second copy of an account already listed, synced once per connector. They are in no group and no count, since the account they copy is counted once. unlinked_accounts counts rows left out by judgment rather than by duplicate collapse. A proven cross-source mirror or a bound alias of an account whose balance is already counted is left out for the same reason. An account whose source connection was removed, with no other live connector link, is left out for a different reason: no live connection keeps it in cash, and no other row counts its balance.
partial: true means the underlying read was cut short before it returned anything, so groups is empty and nothing is known about what the workspace holds. Say the read was cut short and offer to try again, rather than presenting an empty list as a decision.
own_set_truncated: true means the read reached the own-company row cap. The groups and subtotals are still usable; continue to a cash figure and label it partial because an unseen company may add accounts. Pass own_set_truncated: true to well_render_cash_position. This differs from partial: true, which means the read was cut short and must stop.
offered_account_types lists every type this card offers now. stored_choice is an answer a board block stored for this card: pass the block's binding.scope when it carries both counted_account_types and offered_account_types, and omit it otherwise. reuse_stored_choice: true means no type is new since that answer: apply the stored counted_account_types as they stand, and wait for nothing, because the card asks nothing. reuse_stored_choice: false beside a stored choice means new_options names a type the reader never judged: the card shows the stored answer ticked and gives each new type the card's own default, and the answer is awaited as on a first run.
The workspace can keep its own answer to this card: the preference cash_scope. The read compares the types listed now with that saved answer first, and with the stored_choice you pass only when the workspace keeps none: an answer a block or a conversation holds can be older than the saved one, and an older answer must not beat a newer one. stored_choice_source says which stored answer the read compared with: workspace_preference, stored_choice_input (the one you passed), or null with none. stored_counted_account_types holds the types that answer counts, so with reuse_stored_choice: true they are the answer as they stand. choice_savable is true when the caller is an owner or admin of the workspace, the only people who can save an answer for it with well_upsert_preference (key cash_scope). choice_workspace_id is the workspace this read ran in: an answer to its card belongs to that workspace and is saved there, never in another one.
The card records the reader's answer in this session, so wait for it unless the stored choice was reused: call well_wait_for_selection({ kind: "cash_scope" }) in the SAME turn, and read selection.counted_account_types. An EMPTY array there is the answer "nothing is cash" — a resolution that ends the run, never a zero total. Do not settle the scope yourself: on a workspace holding more than one type that is the figure decided on the reader's behalf. A card listing no type at all asks nothing and carries no wait. only_default_types: true means the read completed, no stored answer applies, and every type the card lists is a deposit type, which is cash by any reading and which the card counts by default: the card holds no decision, so it asks nothing and carries no wait. Count the listed types as they stand. Once the answer is in, YOU apply it when you total the balances, then call well_render_cash_position with the types you counted in scope.account_types.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| stored_choice | No | The answer a board block stored for this card: the block's `binding.scope`. Omit it outside a board run. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| groups | Yes | ||
| partial | Yes | ||
| success | Yes | ||
| next_step | No | What to do with the card this result renders. Added by the dispatcher when the card asks for a click. | |
| pre_ticked | Yes | The options the card starts with ticked. | |
| new_options | Yes | Options listed now that the stored choice did not offer. Empty when no stored choice was passed. Name each one when the card is shown for it. | |
| choice_savable | Yes | True when the caller is an owner or admin of the workspace and so can save an answer for it. | |
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| folded_duplicates | Yes | ||
| own_set_truncated | Yes | ||
| unlinked_accounts | Yes | ||
| estimated_accounts | Yes | Self-candidate accounts excluded from proven cash and every account-type group. | |
| excluded_not_owned | Yes | ||
| only_default_types | Yes | True when the read completed, no stored answer applies, and every type listed is the deposit type the card counts by default. The card then asks nothing and no wait is owed on it. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| choice_workspace_id | Yes | The workspace this read ran in, where an answer to its card is saved, or null when none resolved. | |
| reuse_stored_choice | Yes | True when a stored choice was passed, the read completed, and no option is new. Apply the stored choice as it stands: the card asks nothing and no wait is owed on it. | |
| unreadable_balances | Yes | ||
| unreadable_currency | Yes | ||
| unsettled_ownership | Yes | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| stored_choice_source | Yes | The stored answer the read compared with: the workspace's saved answer, the stored_choice passed in when the workspace keeps none, or null with none. | |
| offered_account_types | Yes | Every account type this card offers now, in the order it lists them. The card records it beside the reader's answer, so a board block can store the two together. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. | |
| stored_counted_account_types | Yes | The account types the stored answer counts as cash, or null with no stored answer. |