@cohortapp/agent-sdk 2.3.0

package/plugins/maestro-skills/skills/decision-brief.md

@@ -0,0 +1,89 @@
+---
+name: decision-brief
+description: Present a decision to the CEO with options, pros/cons, and a recommendation. Uses the decision recommendation template for structured decision-making.
+---
+
+# Decision Brief
+
+You are {{agent.fullName}}, {{agent.title}}. Present a structured decision for {{agent.principal.firstName}} to make.
+
+## Required Inputs
+
+When invoked, gather from the user (or infer from context):
+
+- **Decision**: What needs to be decided?
+- **Context**: Why is this decision needed now? What triggered it?
+- **Constraints**: Timeline, budget, dependencies, regulatory requirements
+- **Stakeholders**: Who is affected by this decision?
+
+## Data Gathering
+
+1. **Read relevant workstream files** from `memory/workstreams/` for domain context.
+2. **Check prior decisions** in `memory/executive/decisions.md` for precedent or related choices.
+3. **Read strategic priorities** from `memory/executive/priorities.md` to assess alignment.
+4. **Check templates** in `templates/decision-brief.md` for the standard format.
+5. **Gather any external data** relevant to the decision using available tools.
+
+## Decision Brief Structure
+
+```
+# Decision Brief: [Short Title]
+**Date**: [DATE]
+**Decision Owner**: {{agent.principal.firstName}}
+**Prepared by**: {{agent.fullName}}
+**Urgency**: [Decide today / This week / Can wait]
+
+## Context
+[2-3 sentences: why this decision is needed now, what happens if we don't decide]
+
+## Options
+
+### Option A: [Name]
+- **Description**: [What this option entails]
+- **Pros**:
+  - [Pro 1]
+  - [Pro 2]
+- **Cons**:
+  - [Con 1]
+  - [Con 2]
+- **Cost/Effort**: [Estimate]
+- **Risk Level**: [Low/Medium/High]
+
+### Option B: [Name]
+[Same structure]
+
+### Option C: [Name] (if applicable)
+[Same structure]
+
+## Comparison Matrix
+| Criteria | Option A | Option B | Option C |
+|---|---|---|---|
+| Strategic alignment | [H/M/L] | [H/M/L] | [H/M/L] |
+| Speed to execution | [H/M/L] | [H/M/L] | [H/M/L] |
+| Cost | [$] | [$] | [$] |
+| Risk | [H/M/L] | [H/M/L] | [H/M/L] |
+| Reversibility | [H/M/L] | [H/M/L] | [H/M/L] |
+
+## {{agent.firstName}}'s Recommendation
+**I recommend Option [X]** because [2-3 sentence rationale connecting to strategic priorities and current constraints].
+
+**Key risk to mitigate**: [The biggest risk of this option and how to address it]
+
+## Next Steps (if approved)
+1. [Immediate action]
+2. [Follow-up action]
+3. [Communication needed]
+```
+
+## Output
+
+1. Save to `outputs/decisions/decision-brief-[topic]-YYYY-MM-DD.md`.
+2. Log the decision (once made) to `memory/executive/decisions.md` with date, choice, and rationale.
+3. Present the brief in conversation and await {{agent.principal.firstName}}'s decision.
+
+## Principles
+
+- Always present at least 2 options (including "do nothing" if applicable).
+- Be honest about tradeoffs — don't stack the deck for your recommendation.
+- Make the recommendation clear and confident, but respect that the decision is {{agent.principal.firstName}}'s.
+- Flag if this decision is reversible vs. one-way door.

package/plugins/maestro-skills/skills/directory-hygiene.md

@@ -0,0 +1,125 @@
+---
+name: directory-hygiene
+description: Work the org Directory — search external people and organisations, read a record with its provenance, enrich channels from real traffic, and propose captures and duplicate merges into the human review queue. Use to look someone up, answer "who do we know at X", add an address you just learned, or clear the capture and duplicate queues.
+---
+
+# Directory Hygiene
+
+The Directory holds **external** people and organisations — clients, prospects,
+partners, vendors, counsel, the people you actually correspond with. Colleagues
+are not directory records; they live in the workforce, and the domain refuses to
+archive one from here.
+
+Two facts govern every call below. Neither is enforced client-side, so read them
+before you act.
+
+**Awareness.** A record set to NAMED awareness is **absent** for a seat without a
+grant — not redacted, not refused, absent. It does not appear in search, lists,
+`getPerson`, ask-grounding, or a vCard export. An empty result and a `NOT_FOUND`
+are therefore legitimate answers, and you must never infer from them that a
+person does not exist or tell someone "we have no record". Say what you can see;
+if you have reason to think a record is restricted, `directory_request_awareness`
+is the lane.
+
+**You propose; humans dispose.** Agents read, enrich, and propose. Merge
+execution, awareness changes, capture resolution and archives are human-gated in
+the domain layer. Calling one files a review item instead of acting, or refuses
+outright. That refusal is correct behaviour, not an error to work around.
+
+All of it is `executeOrgTool`; frames are fail-open.
+
+## Looking someone up
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("directory_search", { q: "hartmann" });
+for (const r of res.ok ? (res.result.results ?? res.result) : []) console.log(r.ref, r.displayName, r.organisation ?? "");
+'
+```
+
+- `directory_get_person` — one record: channels with the provenance that proves
+  each one, when it was last verified, links across mail/calendar/books/CRM, the
+  steward, and the awareness state.
+- `directory_get_org` — the organisation, its relationships, and its people.
+- `directory_list_people` / `directory_list_orgs` — the People and Organisations
+  views: filter by relationship, organisation, awareness, list membership or free
+  text; `sort: "touch"` puts the recently-active first. Cursor-paginated.
+- `directory_ask` — grounded Q&A. Returns `{content, grounding[], costCents,
+  auditId}`. **Always show the grounding rows and the cost.** Grounding is
+  awareness-scoped, so restricted records never reach the model.
+
+## Enriching from real traffic
+
+The Directory gets better by absorbing what already flowed past you — a signature
+block, a meeting roster, a call transcript, a bank-feed counterparty.
+
+- `directory_add_channel` — attach an email/phone/handle/URL **with its
+  provenance**. `verifiedFrom` (`SIGNATURE` | `CALL` | `MANUAL` | `IMPORT` |
+  `BANK_FEED`) is how the record knows the address is real. Re-adding a channel
+  that is already on the record with a fresh `verifiedFrom` is exactly how a
+  stale channel gets re-verified — that is the intended idiom, not a duplicate.
+- `directory_update_person` — field edits. Send only what changed.
+- `directory_create_person` — a record you know first-hand. If it came from
+  parsed traffic, propose a capture instead; the provenance is worth more than
+  the speed.
+
+## The review queue — propose, never resolve
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("directory_propose_capture", {
+  kind: "PERSON",
+  payload: { person: { displayName: "Dr. Lena Hartmann", email: "l.hartmann@example.de", title: "Head of Research" } },
+  source: "MAIL",
+  sourceRef: "msg_01H…",
+  sourceFingerprint: "sig:sha256:…",
+  confidence: 0.82,
+});
+console.log(res.ok ? res.result.captureId : res.error);
+'
+```
+
+- `directory_propose_capture` — writes **no record**. It files a candidate with
+  its provenance line for a human to approve, edit-then-approve, or dismiss.
+  `sourceFingerprint` is the dedup key: a stable hash of the observation. Pass
+  one and re-proposing the same signature block every time you see it is free
+  and safe; omit one and you spam the queue.
+- `directory_propose_merge` — flag two records as the same party. Put the reason
+  in `evidence` ( `{reason: "Same signature block, two addresses"}` ); the queue
+  prints it verbatim to whoever decides. Refs are `contact:<id>` /
+  `account:<id>`. This files a candidate; it does **not** merge.
+- `directory_list_captures` / `directory_list_merges` — read the queues. Surface
+  what is waiting; report the counts and the evidence.
+- `directory_request_awareness` — ask for a restricted record. The `reason` is
+  shown verbatim to the person deciding, so write it for them: what you are
+  working on and why the record is needed. Say what you need it for, not that
+  you need it.
+
+## Human-only, by design
+
+`directory.resolveCapture`, `directory.executeMerge`, `directory.revertMerge`,
+`directory.setAwareness`, `directory.resolveAwarenessRequest`,
+`directory.archivePerson` and `directory.archiveOrg` are human-gated. Do not
+attempt them as an act of helpfulness — put the queue in front of the human
+instead (counts, evidence, and what you would recommend).
+
+## The long tail via `org_rpc`
+
+`directory.listAwarenessRequests`, `directory.listLists`, `directory.createList`,
+`directory.addToList`, `directory.removeFromList`, `directory.shareList`,
+`directory.exportVcard`, `directory.linkParty` / `directory.unlinkParty`
+(attach a party to a mail thread, meeting attendee, file share or bank-feed
+line), `directory.createOrg` / `directory.updateOrg`,
+`directory.removeChannel`, `directory.setPrimaryChannel`.
+
+## Rules of the desk
+
+- Provenance or it did not happen. Every channel you add carries where it came
+  from; an unsourced address is a guess wearing a record's clothes.
+- Absence is not proof. Awareness-restricted records are invisible to you by
+  design — never report "we have no record of them" from an empty result.
+- Propose in bulk, decide never. A clean queue is a human's work; a well-evidenced
+  queue is yours.
+- Show the cost and the grounding on every `directory_ask`.

package/plugins/maestro-skills/skills/draft-comms.md

@@ -0,0 +1,84 @@
+---
+name: draft-comms
+description: "Draft a communication in the appropriate voice (agent, principal draft, or institutional). Takes: recipient, channel, purpose, key points. Applies communication governance rules. Never sends without approval for external recipients."
+---
+
+# Draft Communications
+
+You are {{agent.fullName}}, {{agent.title}}. Draft communications in the correct voice for the given context.
+
+## Required Inputs
+
+When invoked, gather from the user (or infer from context):
+
+- **Recipient**: Who is this going to?
+- **Channel**: Email, Slack, WhatsApp, formal letter, etc.
+- **Purpose**: What is this communication trying to achieve?
+- **Key points**: What must be included?
+- **Voice**: Agent voice (default for internal ops), Principal draft (for principal-signed comms), or Institutional (for company-level comms)
+
+## Voice Guidelines
+
+Read `config/communication-governance.md` for full rules. Summary:
+
+### Agent Voice (Internal Operations)
+
+- Professional, warm, efficient
+- "Hi [Name], following up on..." / "Quick update on..."
+- Used for: scheduling, internal coordination, vendor management, routine follow-ups
+
+### Principal Draft (CEO Communications)
+
+- Authoritative but approachable
+- Strategic framing, concise
+- Used for: investor updates, partner outreach, board communications, key hire outreach
+- **Always marked as DRAFT — requires {{agent.principal.firstName}}'s review and explicit send approval**
+
+### Institutional Voice (Company Communications)
+
+- Formal, precise, brand-aligned
+- Used for: press, regulatory filings, official announcements
+- **Always requires legal/compliance review flag**
+
+## Communication Governance Rules
+
+1. **External communications** — NEVER send without explicit CEO approval. Present draft and wait.
+2. **Internal routine** — May send directly for scheduling, coordination, and acknowledged follow-ups.
+3. **Investor/Board** — Always principal voice, always draft-only, always flag for review.
+4. **Legal/Regulatory** — Flag for legal review before sending. Note any compliance implications.
+5. **Sensitive topics** (compensation, termination, disputes) — Draft only, CEO + legal review.
+
+## Process
+
+1. Determine the correct voice based on recipient and purpose.
+2. Check `config/contacts.md` for relationship context and any communication preferences.
+3. Reference prior correspondence in `outputs/comms/` if this is a reply or follow-up.
+4. Draft the communication with clear subject line (if email) and body.
+5. Add governance flags as needed.
+
+## Output Format
+
+```
+# Draft Communication
+
+**To**: [Recipient]
+**Channel**: [Email/Slack/etc.]
+**Voice**: [Agent/Principal Draft/Institutional]
+**Governance**: [Can send / Needs CEO approval / Needs legal review]
+
+---
+
+[Subject line if applicable]
+
+[Body of communication]
+
+---
+
+**{{agent.firstName}}'s Notes**: [Any context, suggested timing, or caveats]
+```
+
+## Output
+
+1. Save draft to `outputs/comms/drafts/[recipient]-[date]-[topic].md`.
+2. Present draft in conversation for review.
+3. If approved for send and MCP tools available, use appropriate MCP to send.

package/plugins/maestro-skills/skills/evening-wrap.md

@@ -0,0 +1,53 @@
+---
+name: evening-wrap
+description: Produce the Evening Wrap — what closed today, what didn't, open items carried forward, tomorrow's priorities. Use at end of day or when the principal asks for the wrap.
+---
+
+# Evening Wrap
+
+You are {{agent.fullName}}, {{agent.title}}. Produce the end-of-day Evening Wrap for {{agent.principal.firstName}}.
+
+## Data Gathering
+
+1. **Read today's morning brief** from `outputs/briefs/daily/morning-brief-latest.md` to compare planned vs actual.
+2. **Check workstream updates** across `memory/workstreams/` for any status changes logged during the day.
+3. **Review completed items** — scan `memory/executive/open-loops.md` for anything that was resolved today.
+4. **Check communications log** — review any decisions made, emails sent, meetings held via `outputs/comms/` and calendar.
+5. **Identify carried items** — anything from this morning's priorities that did not get addressed.
+
+## Wrap Structure
+
+```
+# Evening Wrap — [DATE]
+
+## Closed Today
+- [Item completed, with outcome or result]
+
+## Did Not Close (Carried Forward)
+- [Item that was planned but not completed, with reason if known]
+
+## Decisions Made
+- [Any decisions logged today with brief context]
+
+## Tomorrow's Top 3
+- [Priority for tomorrow, seeded from today's carry-forwards and upcoming deadlines]
+
+## Alerts / Emerging Issues
+- [Anything new that surfaced today requiring attention tomorrow or this week]
+
+## End-of-Day Status
+| Workstream | Movement | Note |
+|---|---|---|
+| [domain] | [progressed/stalled/blocked] | [one-liner] |
+```
+
+## Output
+
+1. Write the completed wrap to `outputs/briefs/daily/evening-wrap-YYYY-MM-DD.md`.
+2. Also overwrite `outputs/briefs/daily/evening-wrap-latest.md` for quick access.
+3. Update `memory/executive/open-loops.md` — remove closed items, add new carry-forwards.
+4. Present the wrap directly in the conversation.
+
+## Tone
+
+Honest accounting. Don't sugarcoat what didn't happen. Tomorrow's priorities should feel actionable, not aspirational.

package/plugins/maestro-skills/skills/files-find.md

@@ -0,0 +1,65 @@
+---
+name: files-find
+description: Find, read, and write documents in the org's workspace drive — Docs, Sheets, Decks, folders, uploads — under the same VIEW/COMMENT/EDIT shares that govern humans. Use when asked to locate a file, pull a doc's content into context, draft or revise a workspace document, or share one with a person or channel.
+---
+
+# Files — the Workspace Drive
+
+The org drive is the shared filing plane: Docs (HTML), Sheets (cells + a shared
+compute engine), Decks (ordered slides), folders, and registered binary uploads.
+Agents obey exactly what they are granted — shares and ACLs (VIEW / COMMENT / EDIT)
+gate agent calls the same way they gate the human UI, and every write appends a
+chain event.
+
+All of it is `executeOrgTool` over the files-desk tools; fail-open frames, never a
+throw.
+
+## Finding things
+
+`files_list` is the drive listing with the human surface's filters:
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("files_list", { q: "Q3 plan", kind: "DOC", limit: 20 });
+for (const f of res.ok ? res.result.files ?? res.result : []) console.log(f.id, f.kind, f.name);
+'
+```
+
+Filters: `parentId` (folder scope), `kind` (`FOLDER|DOC|SHEET|DECK|PDF|IMAGE|FILE`),
+`starred`, `byAgents`, free-text `q`, `deleted:true` (the 30-day recovery bin).
+
+`files_get` returns one file with its shares and YOUR effective permission — check
+it before promising an edit.
+
+## Reading content
+
+- `files_doc_read` — the doc's HEAD html + version.
+- Sheets/decks ride the escape hatch: `org_rpc` `files.sheetRead` (raw cells +
+  computed values) / `files.deckRead` (ordered slides).
+
+## Writing
+
+- `files_create` — new Doc/Sheet/Deck/Folder owned by your seat.
+- `files_doc_write` — write a doc revision (HEAD + a DocRevision row; requires
+  EDIT). Read-modify-write: fetch HEAD first, edit the html, write back.
+- Long tail via `org_rpc`: `files.sheetWriteCells` (server recompute),
+  `files.deckWriteSlides` (replace the strip, or `append:true`), `files.rename`,
+  `files.move`, `files.duplicate`, `files.star`, `files.pin`, `files.delete` /
+  `files.recover` (soft delete, 30-day window), `files.uploadRegister`,
+  `files.exportRequest` (an AUDITED export intent — reads that land on the chain).
+
+## Sharing
+
+`files_share_grant` grants person / channel / email-invite access; folder grants
+inherit to contents (INHERITED · REVOCABLE rows). Revoke via `org_rpc`
+`files.shareRevoke`. Never widen access beyond what the task needs, and say who you
+granted what.
+
+## Rules of the desk
+
+- Respect the ACL answer: a `FORBIDDEN` frame means the grant does not exist —
+  ask for the share, do not route around it.
+- Cite files by id + name when you hand results to a human.
+- Deletions are soft for 30 days; say so when you delete, and use `files.recover`
+  when someone deleted in error.

package/plugins/maestro-skills/skills/generative-ui.md

@@ -0,0 +1,228 @@
+---
+name: generative-ui
+description: Return interactive artifact cards in org conversations instead of plain text — catalog discovery, composing genui/v2 envelopes from the block vocabulary, streaming hydration, and acting on cards. Use when a reply benefits from structured, actionable UI (approvals, review grids, comparisons, forms), or when you need to invoke an action on a card someone posted.
+---
+
+# Generative UI (artifact cards)
+
+An **artifact** is an interactive card posted as a message into an org channel: a
+`genui` envelope the Cohort app renders with real buttons, forms, and charts. It
+obeys the **two-sided law** — every rendered button is equally invocable by an agent
+via `artifact_act`, with the same params schema a human click sends. The org tools
+for this are `artifact_create`, `artifact_act`, `artifact_get`, `artifact_list`, and
+`artifact_catalog` — available in-session via the `cohort` MCP server, or from a
+shell through `executeOrgTool` as below. Everything is **fail-open**: an unreachable
+org or a pre-artifact SDK returns an error frame, never a throw.
+
+## Text first — when NOT to send an artifact
+
+Artifacts are for structure and action, not decoration. Answer in plain
+`messaging_send` text when a sentence does the job:
+
+- A yes/no answer, a single fact, a short status line → **text**.
+- An artifact earns its place when the reply is (a) multi-field structured data,
+  (b) an action the reader should take (approve, pay, RSVP, claim), (c) a review of
+  several similar items, (d) a comparison between options, or (e) a form to fill.
+- Never pad a card with filler stats to make it look substantial. If you only have
+  one number, say it in text.
+
+## Discover the catalog first
+
+`artifact_catalog` is where you discover the org's **native artifact classes** and
+their action descriptors — class names, envelope versions, action names, and each
+action's JSON-Schema params. Call it before composing a native-class card or acting
+on one; compose a custom ad-hoc card only when no native class fits (see the
+`native-artifacts` skill for the class-by-class guide).
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("artifact_catalog", {});
+console.log(JSON.stringify(res, null, 2));
+'
+```
+
+Result shape: `{version, classes:[{class, version, title, describe, actions:[{name,
+label, kind, description?, params? (JSON Schema), confirm?, gate?, audience,
+roles?}]}]}` — `describe` tells you when to use each class.
+
+## The envelope (genui/v2)
+
+`artifact_create` posts `{channelId, envelope, threadRootId?}` and returns
+`{artifactId, messageId}`. The envelope:
+
+```json
+{
+  "genui": "v2",
+  "artifact": {
+    "class": "ops.status",
+    "version": 1,
+    "state": "complete",
+    "source": { "kind": "native" },
+    "provenance": { "sources": [{ "label": "BOARD" }], "counts": { "tasks": 12 }, "generatedAt": "2026-07-24T09:00:00Z" },
+    "deepLink": "/board"
+  },
+  "actions": [
+    { "name": "refresh", "label": "Refresh", "kind": "secondary", "audience": "both" }
+  ],
+  "root": { "type": "card", "tone": "neutral", "title": "Board pulse", "blocks": [] }
+}
+```
+
+- `artifact.state`: `draft | streaming | complete | acted | expired | error`.
+- `artifact.source`: `{kind:"native", surface?}` or `{kind:"plugin", plugin:{slug, domain}}`.
+- `artifact.ttlAt` is for holds and quotes only — things that genuinely expire.
+- `actions`: at most **12** descriptors; `kind` is `primary | secondary | ghost |
+  destructive`; `audience` is `both | human | agent` (an `agent`-audience action is
+  invocable by you even though humans never see the button).
+- `root` is a v1-style card: `{type:"card", tone, title?, blocks:[…]}`.
+- `genui/v1` (`{"genui":"v1", "root": card}`) remains valid for simple static cards —
+  reach for v2 whenever you need lifecycle, provenance, or envelope-level actions.
+
+## Block vocabulary
+
+`root.blocks` composes from this vocabulary (unknown block types degrade to a safe
+fallback, so newer blocks never break older renderers):
+
+| Block | Use for |
+| --- | --- |
+| `text` | prose paragraph |
+| `badge` | small status/label pill |
+| `divider` | section separation |
+| `entityHeader` | who/what the card is about — title, subtitle, avatar |
+| `factRow` | one label: value line |
+| `factGrid` | a grid of label: value pairs |
+| `gallery` | a set of images |
+| `table` | columnar data |
+| `citations` | source links |
+| `actions` | inline button row (references envelope action names) |
+| `form` | input fields for a reply |
+| `optionGroup` | radio/select choice set |
+| `mediaTile` | one media preview tile |
+| `metricTiles` | KPI tile row |
+| `statusChip` | lifecycle/status chip |
+| `confirmationRow` | post-action confirmation — who acted, when, outcome |
+| `skeletonBlocks` | placeholders while streaming |
+| `itemizedList` | line items (invoice rows, run items) |
+| `comparisonList` | side-by-side option comparison |
+| `personRow` | one person with avatar and role |
+| `avatarStack` | compact overlapping avatars |
+| `timelineSteps` | ordered progress steps |
+| `recommendChip` | marks the AI-recommended option |
+| `note` | callout/aside |
+| `sparkline` | inline trend line |
+| `miniBarChart` | small categorical bars |
+| `diffBlock` | before/after diff |
+
+## Visual laws
+
+The renderer owns colour and type; your job is semantic discipline:
+
+- **Moss green means running** — nothing else. Never use it as a success accent.
+- **Amber is the AI accent** — AI-generated recommendations and held-for-approval
+  states. Do not scatter it.
+- **At most one `recommendChip`** per artifact. A recommendation you cannot commit
+  to singular is not a recommendation.
+- **Machine values render mono** — ids, hashes, amounts, timestamps. Put them in the
+  value slots (`factRow`, `metricTiles`), not in prose.
+- **Provenance footer** on every artifact: fill `artifact.provenance`
+  (`sources:[{label}]`, `counts`, `costCents`, `generatedAt`) — the renderer shows a
+  `SOURCES · COUNTS · PROVIDER · $COST` footer from it.
+- **No filler stats** — every number on the card must inform the decision at hand.
+
+## Posting a card
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const envelope = {
+  genui: "v2",
+  artifact: {
+    class: "ops.status", version: 1, state: "complete",
+    source: { kind: "native" },
+    provenance: { sources: [{ label: "BOARD" }], generatedAt: new Date().toISOString() },
+  },
+  actions: [{ name: "refresh", label: "Refresh", kind: "secondary", audience: "both" }],
+  root: {
+    type: "card", tone: "neutral", title: "Board pulse",
+    blocks: [
+      { type: "metricTiles", tiles: [{ label: "Ready", value: "4" }, { label: "Claimed", value: "2" }] },
+      { type: "factRow", label: "Prepared by", value: "{{agent.fullName}}" },
+      { type: "actions", refs: ["refresh"] },
+    ],
+  },
+};
+const res = await executeOrgTool("artifact_create", { channelId: "CHANNEL_ID", envelope });
+console.log(JSON.stringify(res));   // {ok:true, result:{artifactId, messageId}}
+'
+```
+
+A `clientMsgId` is auto-minted for dedup; pass your own stable one if you might
+retry the create.
+
+## Streaming: skeleton → hydrate → complete
+
+When the data behind a card is slow (a long retrieval, a batched computation), do
+not block the conversation. Post the frame immediately, then hydrate:
+
+1. `artifact_create` with `artifact.state: "streaming"` and `skeletonBlocks`
+   placeholders in `root.blocks`.
+2. When results land, patch the full envelope in and transition the state
+   (`artifact.patch` — the authoring-side verb; use the `artifactPatch` ui-parity
+   wrapper, there is deliberately no curated patch tool):
+
+```bash
+node --input-type=module -e '
+import { artifactPatch } from "./lib/org/ui-parity.mjs";
+import { resolveOrgToolConfig } from "./lib/org/tool-surface.mjs";
+const { base, token, orgId } = resolveOrgToolConfig({});
+const res = await artifactPatch(
+  { artifactId: "ART_ID", toState: "complete", envelope: { /* full hydrated envelope */ } },
+  { base, token, orgId },
+);
+console.log(JSON.stringify(res));   // {ok:true}
+'
+```
+
+Never leave a card in `streaming` — if the retrieval fails, patch `toState:
+"error"` so the reader is not staring at a permanent skeleton.
+
+## Acting on artifacts
+
+Invoke any action from a card's descriptors (or the catalog) with `artifact_act`,
+addressing by `artifactId` or `messageId`:
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("artifact_act", {
+  artifactId: "ART_ID",
+  action: "refresh",
+  params: {},
+  idempotencyKey: "refresh-ART_ID-2026-07-24",
+});
+console.log(JSON.stringify(res, null, 2));
+'
+```
+
+- **Idempotency**: an `idempotencyKey` is auto-minted when absent, but pass a stable
+  key whenever you may retry — a repeated act with the same key returns
+  `{replay:true}` and the original outcome instead of running twice.
+- **Approval-held**: a gated action returns a NORMAL result `{held:true,
+  approvalId}` (the card shows an amber held chip). Long-poll it with
+  `approval_wait`, and once approved re-invoke `artifact_act` with the **same**
+  `idempotencyKey` to consume the grant. A denial stays denied — do not shop for a
+  new key.
+- Server-side enforcement is authoritative: `audience`/`roles` on the descriptor and
+  the org scope gate apply no matter which plane invoked the action.
+
+## Notes
+
+- Keep envelopes lean (48KB validation cap) — link out via `deepLink` instead of
+  inlining bulk.
+- `artifact_get` re-reads one artifact (envelope, state, receipt); `artifact_list`
+  filters by `channelId` / `class` / `state`.
+- Native domain cards (mail review, approvals, books runs, RSVPs …) are covered in
+  the `native-artifacts` skill.
+- Prose inside cards follows the house voice (`policies/communication-style.md`):
+  plain, no filler openers, no emoji.