@agent-native/core 0.203.2-nightly-20261007213109 → 0.204.0

package/dist/templates/factory/.agents/skills/review-latest-feedback/SKILL.md

@@ -21,8 +21,10 @@ Four phases, in order. Phase 0 comes before any investigation, not after.
 2. **Fix** what the evidence actually proves, at the owning boundary.
 3. **Reply**, under a hard question budget, then recap.
 
-Output is fixes; reply only when informative. Two fixes and three messages
-beats thirty replies.
+Output is fixes. Reply in-thread for every workflow reaction added this run;
+continuing work gets a concrete progress reply, and resolved work gets a final
+reply after verification. Follow
+[`slack-reaction-replies.md`](references/slack-reaction-replies.md).
 
 ## Slack channels
 
@@ -46,9 +48,10 @@ work, post one status reply with task link and remaining scope.
 
 ## Phase 0: claim what you are taking
 
-For an eligible item you intend to take, add `👀` before investigation and
-never remove it. Do not resume items excluded by the Slack ownership gate. Post
-**In progress** only when work continues beyond this run.
+Resolve known duplicate clusters before claiming. For an eligible item, add
+`👀` before investigation and never remove it. Do not resume items excluded by
+the Slack ownership gate. Post **In progress** only when work continues beyond
+this run.
 
 **Defects are in scope: fix them or ask for the one detail needed to fix them.**
 Investigate first; ask what they saw or did in plain language. Gather request
@@ -62,13 +65,16 @@ doesn't close a separate defect. Tie each reaction to the scope it marks.
 
 ### Reaction gate
 
-`👀` is claim history; `✅` requires **Fixed** after all Phase 2 bars. `🎫`
-marks accepted work another owner must do; use it only with an existing ticket
-naming that owner and exact action, linked in the ledger and reply. No `🎫` for
-fixed scope, routine rollout, optional live checks, subjective/out-of-scope, or
-unapproved work. Pair `✅` + `🎫` only for distinct scopes; name the fixed
-behavior and ticket action. **Shipped**/**Live verified** alone don't earn
-`✅`. Never remove reactions.
+`👀` is claim history; `✅` requires **Fixed** after Phase 2 bars. Check each
+reported symptom separately. For partial fixes, pair `✅` for verified scope
+with `🎫` for any distinct unfinished scope that needs a human to take
+ownership or act, whether or not a ticket exists. Link a verified ticket and
+name its owner/action; without one, keep the handoff explicit in the reply and
+ledger and say that an owner or ticket still needs to be assigned. Do not
+create or promise a ticket without authorization. No `🎫` for fixed scope,
+routine rollout, optional checks, subjective/out-of-scope, or unapproved work.
+**Shipped**/**Live verified** alone don't earn `✅`. Never remove reactions.
+Follow the reply reference before marking an item replied.
 
 For every concrete objective defect, attempt to reproduce it before recording
 an evidence limit or asking the reporter for more information. A screenshot,
@@ -89,7 +95,8 @@ means you found neither a fix nor a useful question; state why in the thread.
 For eligible items, use one disposition per row; record it in the recap and, if
 unstated, in the thread or linked work. Do not inspect gated items for status.
 For clusters, post one owner status with each source permalink and
-**Clustered**; reply in a non-owner only for a distinct question or update.
+**Clustered**; do not mark duplicate non-owners separately. Give a distinct
+question or update its own reaction and reply.
 
 - **Terminal (keep this workflow's eye):** **Fixed**, **Shipped**, **Live
   verified**, **Open - no question**, **Resolved elsewhere**, **Skipped**,
@@ -455,16 +462,8 @@ Share only new or useful information.
 
 ### After a PR merges
 
-After a Slack-fix PR merges, reply only in threads claimed this run.
-
-For beta app fixes, check the merge-triggered publisher run before giving the
-normal few-hours ETA. This checks release-job status, not beta behavior. If it
-succeeds, say what changed and that it'll be on beta in the next few hours.
-Keep test environment, verification, publisher results, and rollout details out
-of the reply; record evidence in the recap or PR. If the run is missing or
-failed, omit the ETA and state what's done, the exact remaining action and owner,
-and an existing ticket when available. Apply the Reaction gate before `🎫`.
-For packages, state availability without verification details.
+Follow [`slack-reaction-replies.md`](references/slack-reaction-replies.md) for
+post-merge beta ETAs and package replies.
 
 For a fixed behavior with a ticketed handoff, state the done behavior and
 remaining action/owner/ticket separately; don't imply the fixed scope is open.
@@ -561,9 +560,9 @@ Questions asked: N/3 · Dropped at 4 days: N
 Repeats of a prior Fixed claim: N (each with its earlier thread and failed fix)
 Upvoted items in scope: N (built: N)
 
-| Tracker/source or workflow run | Reporter/owner | Status | Repro or failed step | Pre/post/recovery | Run/SHA/target/version/artifact/runtime proof | Locales | Handoff (action/owner/ticket) | Replied | Reactions |
+| Tracker/source or workflow run | Reporter/owner | Status | Repro or failed step | Pre/post/recovery | Run/SHA/target/version/artifact/runtime proof | Locales | Handoff (action/owner/ticket) | Reply proof | Reactions |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| 18 / [thread](...) or [workflow run](...) | ... | <disposition> | steps; expected/actual or failed job/step | before/after/recovery run | source/tests/build/run/SHA/target/version/URL | updated/N/A/pending | none or action/owner/[ticket](...) | yes/no | 👀 claim; ✅ Fixed; 🎫 ticketed only |
+| 18 / [thread](...) or [workflow run](...) | ... | <disposition> | steps; expected/actual or failed job/step | before/after/recovery run | source/tests/build/run/SHA/target/version/URL | updated/N/A/pending | none or action/owner/[ticket](...) | [reply](...) or blocker | 👀 claim; ✅ Fixed; 🎫 human handoff needed |
 
 Sibling sweep: <fingerprint> - N hits, M fixed, K triaged
 Tracker: <sheet/export and bounded range> - N rows enumerated, N ledgers complete

package/dist/templates/factory/.agents/skills/review-latest-feedback/references/slack-reaction-replies.md

@@ -0,0 +1,33 @@
+# Slack Reaction Replies
+
+For every Slack item this run independently marks with a workflow reaction,
+send one concise reply under the same parent with its disposition. A same-run
+fix gets its final reply after verification; continuing work gets a concrete
+progress reply. An earlier generic “taking a look” does not satisfy this
+update.
+
+Preserve cluster handling: identify known duplicates before claiming them;
+represent duplicate non-owner threads by permalink and **Clustered** in one
+owner-thread status. Do not react or reply in a non-owner thread unless a
+distinct question or update needs its own disposition; if it does, react and
+reply there as a separate item. If a duplicate is discovered only after this
+run added `👀`, keep it and post a concise **Clustered** reply with the owner
+permalink; never remove the reaction.
+
+Compare each reported symptom with the evidence. State what is fixed and what
+is not. Use `✅` only for verified fixed scope. Use `🎫` for each distinct
+unfinished scope that needs a human to take ownership or act, whether or not a
+ticket exists. Link a verified ticket and name its owner/action; if no ticket
+or owner is assigned, state the exact handoff and that gap in the reply and
+ledger. Do not create or promise a ticket without authorization. Never imply a
+partial fix resolved the whole report.
+
+For beta app fixes, check the matching merge-triggered publisher. While it is
+queued or running, say what changed and that it should be on beta within about
+24 hours. If it succeeds, report beta publication as complete; that does not
+prove independent runtime behavior. If the run is missing or fails, omit the
+ETA and state the next action and owner. Keep verification and rollout details
+in the recap. For packages, state availability without verification details.
+
+Read back the reaction and reply as the invoking identity before recording the
+item as replied.

package/dist/templates/headless/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/dist/templates/workspace-core/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/dist/triggers/actions/manage-automation.d.ts

@@ -13,6 +13,8 @@ declare const _default: import("../../action.js").ActionDefinition<{
     executionEngine?: string;
     executionCwd?: string;
 }, {
+    deleted?: undefined;
+    enabled?: undefined;
     created: boolean;
     name: string;
     scope: "organization" | "personal";
@@ -23,33 +25,31 @@ declare const _default: import("../../action.js").ActionDefinition<{
     reasoningEffort: "auto" | "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh";
     webhookPath: string;
     nextRun: string;
-    deleted?: undefined;
-    enabled?: undefined;
     executionHostId?: undefined;
     executionEngine?: undefined;
     executionCwd?: undefined;
 } | {
-    scope?: undefined;
+    enabled?: undefined;
+    nextRun?: undefined;
     created?: undefined;
+    scope?: undefined;
     triggerType?: undefined;
     event?: undefined;
     deleted: boolean;
     name: string;
-    enabled?: undefined;
     schedule?: undefined;
     timezone?: undefined;
     reasoningEffort?: undefined;
     executionHostId?: undefined;
     executionEngine?: undefined;
     executionCwd?: undefined;
-    nextRun?: undefined;
     webhookPath?: undefined;
 } | {
-    scope?: undefined;
+    deleted?: undefined;
     created?: undefined;
+    scope?: undefined;
     triggerType?: undefined;
     event?: undefined;
-    deleted?: undefined;
     name: string;
     enabled: boolean;
     schedule: string;

package/dist/vite/client.js

@@ -1159,6 +1159,7 @@ function getAgentKitOptimizeDeps(cwd) {
                     "@agent-native/toolkit/app/agentkit/react/components",
                     "@agent-native/toolkit/app/agentkit/react/context",
                     "@agent-native/toolkit/app/agentkit/react/root",
+                    "@agent-native/toolkit/app/chat",
                     "@agent-native/toolkit/app/chat/agentkit-chat/index",
                 ]
                 : []),

package/docs/content/audit-log.mdx

@@ -169,6 +169,21 @@ const { data } = useActionQuery("list-audit-events", {
 
 The agent can call the same action — ask it "what did you change on this recording?" and it answers from the trail.
 
+## Export to a SIEM (OCSF) {#ocsf}
+
+**`export-audit-ocsf`** returns the organization's trail as [OCSF](https://schema.ocsf.io) 1.9.0 API Activity events (`class_uid` 6003), oldest first, for a SIEM to pull on a schedule. Owners and admins only, and it reads the same `org` and `admins` events as the organization audit log, never anyone's private rows.
+
+| Input    | Meaning                                                      |
+| -------- | ------------------------------------------------------------ |
+| `since`  | Only events at or after this ISO 8601 timestamp or epoch ms. |
+| `until`  | Only events before this ISO 8601 timestamp or epoch ms.      |
+| `cursor` | The `nextCursor` from the previous page.                     |
+| `limit`  | Events per page, up to 500 (default 100).                    |
+
+It returns `{ events, hasMore, nextCursor }`. Store every returned `nextCursor` and send it back on the next pull, including when `events` is empty; empty pages advance the ready watermark. The cursor replays a five-minute overlap to catch late commits, so deduplicate across pulls by `metadata.uid`. The newest five seconds are held back so a late-written row is never skipped.
+
+Each event maps `status` to `status_id` (`success` is Success; `error` and `denied` are Failure, with `denied` also `action_id` Denied and a higher `severity_id`), the actor to `actor.user` (a service principal is type Service), the action to `api.operation`, and the target to `resources`. Run, task, parent-task, thread, turn, and app ids have no OCSF field, so they sit under `unmapped`. Call arguments are never exported.
+
 ## Privacy & retention {#privacy}
 
 - **Redaction** — before any inputs are stored, credential-shaped keys and values (tokens, secrets, passwords, bearer strings) are stripped and oversized payloads truncated. The audit log never becomes a secondary store of secrets. Keep `summary` text free of sensitive data too.

package/docs/content/external-agents-catalog.mdx

@@ -236,6 +236,25 @@ from the request origin, so deployments should not hard-code a production
 
 Once an agent is connected, it sees the [compact catalog](#catalog-tiers) by default: template-declared app actions plus the builtin cross-app verbs (`list_apps`, `open_app`, `ask_app`, and the app-only embed helper). Use `ask_app` to route a natural-language task through an app agent (the same cross-app entry point [A2A](/docs/a2a-protocol) uses).
 
+### Tool annotations {#tool-annotations}
+
+Every catalog advertises an action's declared `mcpAnnotations`, including the
+optional `idempotentHint`. Declare them wherever the derived hints would
+misstate the effect: moving an item to recoverable Trash still removes it from
+view, so it is `destructiveHint: true`, and a call guarded by an idempotency
+key is `idempotentHint: true`. Without a declaration, `/mcp` derives
+`readOnlyHint` from `readOnly` and `destructiveHint` from `needsApproval` or
+`publicAgent.isConsequential`.
+
+```ts
+mcpAnnotations: {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: true,
+  openWorldHint: false,
+},
+```
+
 ### MCP Apps compatibility {#mcp-apps-compatibility}
 
 Agent-Native apps also speak the official MCP Apps extension. When any action

package/docs/content/http-api.mdx

@@ -60,7 +60,7 @@ The command still authenticates you in the browser first — minting requires or
 | Who can mint                 | Any signed-in user          | Org owner/admin only             |
 | Best for                     | Your own scripts, local dev | CI, bots, scheduled integrations |
 
-Both default to a 365-day lifetime and accept `--ttl-days` between 1 and 365. If a machine cannot open a browser, the app's connect page at `https://<app>/mcp/connect` is the fallback: sign in there, copy the token, and pass it with `connect <url> --token <token>` or paste it directly into your secret store.
+Personal tokens default to 365 days in the CLI device flow; to choose a lifetime from 1 to 365 days, use the app's Connect page at `https://<app>/mcp/connect`. Org service tokens also default to 365 days and accept `--ttl-days` values between 1 and 3650. If a machine cannot open a browser, the app's Connect page is the fallback: sign in there, copy the token, and pass it with `connect <url> --token <token>` or paste it directly into your secret store.
 
 For a self-hosted, single-tenant app where per-person identity does not matter, the static `ACCESS_TOKEN` / `ACCESS_TOKENS` environment variables are the simplest option — see [Authentication — Static MCP Bearer Tokens](/docs/authentication#access-tokens).
 
@@ -223,7 +223,7 @@ The action ran exactly as it would have from chat or the UI — same validation,
 
 Tokens are JWTs signed by the app and bound to that app's audience. A token minted for one app cannot call another.
 
-- **Lifetime** — 365 days by default, `--ttl-days` between 1 and 365. Shorter is better for anything that runs unattended.
+- **Lifetime** — 365 days by default, `--ttl-days` between 1 and 3650. Shorter is better for anything that runs unattended.
 - **Rotation** — mint the new token, deploy it to the caller, confirm traffic is flowing, then revoke the old one. There is no in-place rotation; the two tokens are independent and can overlap.
 - **Revocation** — every token carries a `jti`, and revocation is a `jti` check on every request, so a revoked token stops working immediately. Use the `list-org-service-tokens` action to see names, who minted them, and last-used timestamps, then `revoke-org-service-token` with the id. Both are owner/admin-gated for writes; any org member can list.
 - **Recovery** — the token value is never stored, only its `jti`. If you lose it, mint a new one and revoke the old.
@@ -242,6 +242,25 @@ Because `list-org-service-tokens` reports `lastUsedAt`, it doubles as a cleanup
 
 </Callout>
 
+## Service principals {#service-principals}
+
+Each org service token is a **service principal**, and a governance record says who answers for it and what it may do. Owners and admins set it when minting (`create-org-service-token` takes optional `ownerEmail`, `team`, `riskTier`, `purpose`, and `allowedActions`) and change it later with `set-service-principal-policy`. `list-org-service-tokens` returns each principal's record in `principals`.
+
+| Field             | Meaning                                                                                                                                         |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ownerEmail`      | The accountable human. Defaults to the admin who minted the token.                                                                              |
+| `team`, `purpose` | Who to page and what the principal is for.                                                                                                      |
+| `riskTier`        | `low`, `medium`, or `high`.                                                                                                                     |
+| `lifecycle`       | `active`, `suspended`, or `retired`.                                                                                                            |
+| `allowedActions`  | `null` is unrestricted. A list is a deny-by-default grant of exact action names or a trailing `*` prefix pattern; an empty list grants nothing. |
+
+- **Grant** — `tools/list` shows only the granted actions, and any call outside the grant is refused, whether it arrives over MCP, an HTTP action route, or an agent run the principal started with `ask-agent` or `ask_app`. Agent built-ins such as `tool-search` and `view-screen` are covered too, so name them in the grant if the principal needs them. The grant narrows what the `member` role already allows; it never adds access.
+- **Suspend and resume** — `set-service-principal-lifecycle` with `suspended` refuses the principal on every request, refuses new agent runs for it, and aborts its in-flight runs. `active` resumes it. The MCP connect page (`/mcp/connect`) has the same suspend and resume controls. `retired` also revokes its tokens and cannot be undone.
+- **Ungoverned** — a service token minted before governance has no record. It stays active and unrestricted until an admin sets a policy.
+- **Fails closed** — if the policy cannot be read, the request is refused with a `503`, never admitted.
+
+These actions are owner/admin-only and are not callable by the agent, so neither an agent nor a service token can loosen its own grant.
+
 ## When it 403s {#troubleshooting}
 
 A `401` means the token was not accepted at all. A `403` means the token _was_ accepted and the request then failed an access check — a different problem with a different fix.

package/docs/content/pr-visual-recap.mdx

@@ -249,7 +249,7 @@ survives any individual leaving, the recaps it publishes are org-visible, and
 any org owner or admin can list or revoke it. Mint one (org owner/admin only):
 
 ```bash
-npx @agent-native/core@latest connect https://plan.agent-native.com --service-token pr-recap
+npx @agent-native/core@latest connect https://plan.agent-native.com --service-token pr-recap --ttl-days 3650
 ```
 
 The command authenticates you in the browser, then prints the service token
@@ -257,6 +257,8 @@ exactly once — store it as the `PLAN_RECAP_TOKEN` secret. Manage it later with
 the `list-org-service-tokens` and `revoke-org-service-token` actions on the
 Plans app.
 
+That gives CI a 10-year lifetime while keeping the token revocable at any time.
+
 **Solo: a personal token still works.** Mint it with `npx @agent-native/core@latest connect`
 against your Plans app. For the hosted app, this also writes a local
 publish-token file that `npx @agent-native/recap-cli@latest recap setup` can read:

package/docs/content/template-clips-embed.mdx

@@ -43,7 +43,7 @@ npx @agent-native/core@latest connect https://clips.agent-native.com \
 
 Copy the printed token directly into your product's server-side secret manager. The token is organization-owned, so it continues working if the person who minted it leaves the organization or revokes their personal tokens. It is never written to a local client configuration. Use a different service name for each integration so one caller can be revoked without breaking another.
 
-`--ttl-days` accepts 1 to 365 days and defaults to 365. The token acts as an organization member. It cannot create or revoke other service tokens or change organization settings.
+`--ttl-days` accepts 1 to 3650 days and defaults to 365. The token acts as an organization member. It cannot create or revoke other service tokens or change organization settings.
 
 ## Request an intake URL
 

package/docs/content/turn-into-app.mdx

@@ -0,0 +1,118 @@
+---
+title: "Turn Into App"
+description: "The /turn-into-app skill turns a thread, skill, spreadsheet, or Claude or ChatGPT project into a runnable Agent-Native app that opens on a populated, domain-shaped surface."
+---
+
+# Turn Into App
+
+`/turn-into-app` is a skill that turns a workflow you have already proven into an Agent-Native app. The source can be a thread, a skill, a spreadsheet, or a Claude or ChatGPT project. The app opens on your world, populated with sample data shaped like the source, with the in-app agent working behind controls on the objects it acts on. A form under a step bar is the result the skill is built to avoid.
+
+## Install {#install}
+
+```bash
+npx @agent-native/skills@latest add --skill turn-into-app
+```
+
+The same skill ships with the core CLI:
+
+```bash
+npx @agent-native/core@latest skills add turn-into-app
+```
+
+Inside a project that already has the Agent-Native CLI, `agent-native skills add turn-into-app` does the same thing. See the [Skills Guide](/docs/skills-guide) for how skills are installed and loaded.
+
+## Invoke it {#invoke}
+
+| Command                            | Source                                                      |
+| ---------------------------------- | ----------------------------------------------------------- |
+| `/turn-into-app`                   | The visible project context, otherwise the current thread   |
+| `/turn-into-app /some-skill`       | The named skill, packaged immediately, even at thread start |
+| `/turn-into-app ./forecast.xlsx`   | A spreadsheet, turned into a workbench                      |
+| `/turn-into-app ./project-export/` | A Claude or ChatGPT project export                          |
+
+Without an argument the skill builds the latest successful, repeatable job and names it. A worked example, such as one account or one deal, is evidence for the job, not its schema. If no job can be identified, it says what is missing instead of asking a generic "what app do you want?" question.
+
+## Where it runs {#hosts}
+
+| Host                                                  | What happens                                                                                                    |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Claude Code, Codex, Cursor, other local coding agents | Builds, runs, and reviews the app in your checkout.                                                             |
+| Claude or ChatGPT on the web                          | Writes a bounded brief and hands it to Builder through the Dispatch connector. It does not run anything itself. |
+
+A host counts as local when it has a real working directory, a terminal, and a workspace. Having a Builder or Dispatch connector does not make a host a browser host.
+
+On a browser host the skill requires the Agent-Native Dispatch MCP connector (`https://dispatch.agent-native.com/mcp`, OAuth) and calls its `start-workspace-app-creation` action. The host cannot run or inspect the app, so the report stays pending or unverified until the branch Dispatch returns is built. The skill reports what Dispatch actually returned and never invents a branch URL. For a ChatGPT Project, or any host that only exposes MCP, put the skill instructions in the Project instructions or knowledge files.
+
+## Sources {#sources}
+
+- **Threads.** The last concrete, repeatable job is the product.
+- **Skills.** The skill's steps, human decision points, and read-only rules become the app. If the skill keeps plan files, those files stay the source of truth through Local File Mode and the app is local-only.
+- **Spreadsheets.** Every worksheet is inventoried first. Structure decides which cells are inputs and outputs; color is only a weak hint. The workbook is never copied into a prompt, SQL, or application state. A Google Sheets link is only a source when it is readable through an authenticated Sheets or Drive connection; otherwise the skill asks for an export.
+- **Claude and ChatGPT projects.** Visible instructions, knowledge files, and supplied past runs are the source. The connector does not read hidden project chats, private URLs, or credentials, and there is no shared-link importer. Attach an export when the context is not visible.
+
+## What you get {#what-you-get}
+
+- **A shape chosen from the source.** The skill picks one of 13 archetypes, such as a triage queue, pipeline board, live workbench, schedule grid, review diff, or monitor. The archetype is the object the user looks at, not the procedure they follow, so source steps become states on objects (Draft, Checked, Approved) rather than a stepper or wizard.
+- **A named visual direction.** One of six directions (`ledger`, `control-room`, `paper-desk`, `studio-canvas`, `tidepool`, `signal-board`) with light and dark tokens, picked from the archetype and the source's domain. An existing brand or your explicit direction wins.
+- **A populated first screen.** `/` lands on a named domain route with synthetic sample data, labeled as sample, shaped like the source. An empty state, a hero, the procedure's first step, or a form is a defect unless the source itself is form-shaped.
+- **Agent moments on the objects.** Each AI-labeled control hands a bounded prompt to the agent sidebar. The object shows a working state right away, and the result lands back on it with Accept, Edit, and Retry. Follow-ups stay in the same thread.
+- **A real Agent-Native app.** Deterministic work is `defineAction` files that both the UI and the agent call. The app uses the standard Use Builder.io or Custom keys setup, writes the current view and selection to application state, and has `AGENTS.md` teaching the in-app agent about the new app.
+
+The skill saves its source brief as `docs/brief.md` and appends the surface design to `DESIGN.md`.
+
+## How a run works {#how-it-works}
+
+1. **Brief.** It reads the whole source and writes a short brief: the job, at most three agent moments, invariants, data hazards, source of truth, and assumptions.
+2. **Design.** It decides the archetype, direction, shell, first viewport and sample data, and agent moments, and posts the brief once as a checkpoint. It continues without waiting.
+3. **Scaffold.** It creates the real app with the chat template and never overwrites an existing app.
+
+   ```bash
+   npx --yes @agent-native/core@latest create <slug> --standalone --template chat
+   ```
+
+   Inside an existing Agent-Native workspace it runs `pnpm exec agent-native add-app <slug> --template chat` from the workspace root instead.
+
+4. **Build.** Actions, the domain surface, sample data, agent moments, and agent instructions are built together.
+5. **Review.** It runs the app and reviews screenshots. See below.
+6. **Verify.** It runs `pnpm typecheck`, `pnpm agent-native:doctor`, and `pnpm build`, then writes the final report.
+
+The skill aims for about 45 minutes. If 35 minutes have passed when the review starts, it runs one pass and lists the open criteria.
+
+## The screenshot review loop {#review-loop}
+
+Before handoff the skill starts the dev server and screenshots `/` at desktop and phone sizes in light and dark, plus the main agent control after a click. It scores the shots against a 12-row rubric covering first-viewport impact, domain fit, hierarchy, chrome discipline, sample data, typography, color, polish, agent and UI together, 390px layout, dark mode, and accessibility.
+
+Some findings fail the review whatever the average score: a stepper or wizard shell, `/` not opening on the domain route, an empty or form-only first viewport, scaffold default tokens, clipped text, raw markdown, sideways scroll at 390px, or a console error. It fixes every finding in one batch, resets whatever the click changed, and shoots again. The default is two passes, with a third only if the second still misses the bar and time allows. The bar is a mean of 4.0 or higher with no criterion below 3 and no automatic fail.
+
+Screenshots are saved in the app's `.tmp/ui-review/out/`, and the final report lists their paths and scores. A result landing in the UI can only be exercised with a connected AI provider; without one, the report says the result was not exercised.
+
+## Run and deploy {#run-deploy}
+
+For local review the skill sets `AUTH_DISABLED=1` in the app's ignored `.env`, because a fresh screenshot browser is not signed in. This is for loopback development only. It is removed before the final `pnpm build`, and it must never be committed or deployed. Without it, opening the app shows a "Continue as local dev" card.
+
+To run the app yourself:
+
+```bash
+pnpm dev
+```
+
+To use your own model provider locally, put a key such as `ANTHROPIC_API_KEY` in the same `.env`. Otherwise the agent sidebar shows the shared Use Builder.io or Custom keys setup.
+
+The skill deploys only when you ask or the provider is already configured. A healthy local build still prints a "production configuration errors" block with exit code 0. That is the deploy checklist: a stable `BETTER_AUTH_SECRET` and a persistent `DATABASE_URL`, plus `A2A_SECRET` for an app inside a workspace. The skill reports these as the pending step and does not create placeholder values. See [Deploy an app](/docs/deploy-an-app) and [Deploy a workspace](/docs/workspace-deployment).
+
+The final report labels evidence separately: locally running, locally verified, build-ready, deployed, and live-verified are different states, and the report never lets one stand in for another.
+
+## Known limits {#limits}
+
+- **Editing `.env` while the dev server runs.** An in-place reload after an `.env` change loops on the local database lock and serves 500s. Stop the server, edit `.env`, and start it again.
+- **Ambiguous spreadsheets.** If the candidate workflows or the input and output mapping stay materially ambiguous after a bounded review, the skill asks one compact question with its recommended interpretation. In a headless run it prints the question, records the assumption in the brief, and keeps building.
+- **Spreadsheets on a browser host.** A workbook cannot be attached; the host passes a bounded CSV rendering as text, or a URL that is intentionally public, and the handoff says what was left out. A link to a private sheet is not a source; the skill asks for an authenticated Sheets or Drive connection or an export, and never uses a public export URL to get around access controls.
+- **Cell colors.** A text preview cannot prove colors, so on a local host the skill reads both formulas and cached values, and treats color as a weak hint.
+- **Local File Mode apps.** An app whose source of truth is the host's files is local-only and is not deployed.
+- **Browser-host handoffs.** The result is unverified until Dispatch returns a built branch. The skill cannot run or screenshot the app there.
+
+## What's next {#whats-next}
+
+- [Skills Guide](/docs/skills-guide) for how skills are installed and loaded
+- [Dispatch](/docs/dispatch) for the connector used from Claude and ChatGPT on the web
+- [Deploy an app](/docs/deploy-an-app) for taking the generated app to production

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.203.2-nightly-20261007213109",
+  "version": "0.204.0",
   "description": "The agentic application framework for building autonomous agents with intuitive UIs",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -682,8 +682,8 @@
     "yaml": "^2.9.0",
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
-    "@agent-native/agentkit": "^0.203.2-nightly-20261007213109",
-    "@agent-native/recap-cli": "^0.5.65"
+    "@agent-native/agentkit": "^0.204.0",
+    "@agent-native/recap-cli": "^0.5.66"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",
@@ -753,7 +753,7 @@
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {
-    "@agent-native/core-corpus": "0.203.2-nightly-20261007213109",
+    "@agent-native/core-corpus": ">=0.196.0",
     "@ai-sdk/anthropic": ">=3",
     "@ai-sdk/cohere": ">=3",
     "@ai-sdk/google": ">=3",

package/src/templates/chat/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/src/templates/default/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/src/templates/factory/.agents/skills/review-latest-feedback/SKILL.md

@@ -21,8 +21,10 @@ Four phases, in order. Phase 0 comes before any investigation, not after.
 2. **Fix** what the evidence actually proves, at the owning boundary.
 3. **Reply**, under a hard question budget, then recap.
 
-Output is fixes; reply only when informative. Two fixes and three messages
-beats thirty replies.
+Output is fixes. Reply in-thread for every workflow reaction added this run;
+continuing work gets a concrete progress reply, and resolved work gets a final
+reply after verification. Follow
+[`slack-reaction-replies.md`](references/slack-reaction-replies.md).
 
 ## Slack channels
 
@@ -46,9 +48,10 @@ work, post one status reply with task link and remaining scope.
 
 ## Phase 0: claim what you are taking
 
-For an eligible item you intend to take, add `👀` before investigation and
-never remove it. Do not resume items excluded by the Slack ownership gate. Post
-**In progress** only when work continues beyond this run.
+Resolve known duplicate clusters before claiming. For an eligible item, add
+`👀` before investigation and never remove it. Do not resume items excluded by
+the Slack ownership gate. Post **In progress** only when work continues beyond
+this run.
 
 **Defects are in scope: fix them or ask for the one detail needed to fix them.**
 Investigate first; ask what they saw or did in plain language. Gather request
@@ -62,13 +65,16 @@ doesn't close a separate defect. Tie each reaction to the scope it marks.
 
 ### Reaction gate
 
-`👀` is claim history; `✅` requires **Fixed** after all Phase 2 bars. `🎫`
-marks accepted work another owner must do; use it only with an existing ticket
-naming that owner and exact action, linked in the ledger and reply. No `🎫` for
-fixed scope, routine rollout, optional live checks, subjective/out-of-scope, or
-unapproved work. Pair `✅` + `🎫` only for distinct scopes; name the fixed
-behavior and ticket action. **Shipped**/**Live verified** alone don't earn
-`✅`. Never remove reactions.
+`👀` is claim history; `✅` requires **Fixed** after Phase 2 bars. Check each
+reported symptom separately. For partial fixes, pair `✅` for verified scope
+with `🎫` for any distinct unfinished scope that needs a human to take
+ownership or act, whether or not a ticket exists. Link a verified ticket and
+name its owner/action; without one, keep the handoff explicit in the reply and
+ledger and say that an owner or ticket still needs to be assigned. Do not
+create or promise a ticket without authorization. No `🎫` for fixed scope,
+routine rollout, optional checks, subjective/out-of-scope, or unapproved work.
+**Shipped**/**Live verified** alone don't earn `✅`. Never remove reactions.
+Follow the reply reference before marking an item replied.
 
 For every concrete objective defect, attempt to reproduce it before recording
 an evidence limit or asking the reporter for more information. A screenshot,
@@ -89,7 +95,8 @@ means you found neither a fix nor a useful question; state why in the thread.
 For eligible items, use one disposition per row; record it in the recap and, if
 unstated, in the thread or linked work. Do not inspect gated items for status.
 For clusters, post one owner status with each source permalink and
-**Clustered**; reply in a non-owner only for a distinct question or update.
+**Clustered**; do not mark duplicate non-owners separately. Give a distinct
+question or update its own reaction and reply.
 
 - **Terminal (keep this workflow's eye):** **Fixed**, **Shipped**, **Live
   verified**, **Open - no question**, **Resolved elsewhere**, **Skipped**,
@@ -455,16 +462,8 @@ Share only new or useful information.
 
 ### After a PR merges
 
-After a Slack-fix PR merges, reply only in threads claimed this run.
-
-For beta app fixes, check the merge-triggered publisher run before giving the
-normal few-hours ETA. This checks release-job status, not beta behavior. If it
-succeeds, say what changed and that it'll be on beta in the next few hours.
-Keep test environment, verification, publisher results, and rollout details out
-of the reply; record evidence in the recap or PR. If the run is missing or
-failed, omit the ETA and state what's done, the exact remaining action and owner,
-and an existing ticket when available. Apply the Reaction gate before `🎫`.
-For packages, state availability without verification details.
+Follow [`slack-reaction-replies.md`](references/slack-reaction-replies.md) for
+post-merge beta ETAs and package replies.
 
 For a fixed behavior with a ticketed handoff, state the done behavior and
 remaining action/owner/ticket separately; don't imply the fixed scope is open.
@@ -561,9 +560,9 @@ Questions asked: N/3 · Dropped at 4 days: N
 Repeats of a prior Fixed claim: N (each with its earlier thread and failed fix)
 Upvoted items in scope: N (built: N)
 
-| Tracker/source or workflow run | Reporter/owner | Status | Repro or failed step | Pre/post/recovery | Run/SHA/target/version/artifact/runtime proof | Locales | Handoff (action/owner/ticket) | Replied | Reactions |
+| Tracker/source or workflow run | Reporter/owner | Status | Repro or failed step | Pre/post/recovery | Run/SHA/target/version/artifact/runtime proof | Locales | Handoff (action/owner/ticket) | Reply proof | Reactions |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| 18 / [thread](...) or [workflow run](...) | ... | <disposition> | steps; expected/actual or failed job/step | before/after/recovery run | source/tests/build/run/SHA/target/version/URL | updated/N/A/pending | none or action/owner/[ticket](...) | yes/no | 👀 claim; ✅ Fixed; 🎫 ticketed only |
+| 18 / [thread](...) or [workflow run](...) | ... | <disposition> | steps; expected/actual or failed job/step | before/after/recovery run | source/tests/build/run/SHA/target/version/URL | updated/N/A/pending | none or action/owner/[ticket](...) | [reply](...) or blocker | 👀 claim; ✅ Fixed; 🎫 human handoff needed |
 
 Sibling sweep: <fingerprint> - N hits, M fixed, K triaged
 Tracker: <sheet/export and bounded range> - N rows enumerated, N ledgers complete