@agent-native/core 0.100.2 → 0.101.2

package/docs/content/locales/zh-TW/pr-visual-recap.mdx

@@ -102,13 +102,13 @@ PR Visual Recap 是一個 GitHub 操作，它將每個 pull request 轉變為**
 npx @agent-native/core@latest skills add visual-plan --with-github-action
 ```
 
-這將安裝 `visual-plan` 技能（其中包括操作執行的 `visual-recap` 技能）並將 `.github/workflows/pr-visual-recap.yml` 寫入您的儲存庫。工作流程透過 `npx @agent-native/core@latest recap <subcommand>` 呼叫**發布的 CLI 子指令** — 包括 `gate`、`collect-diff`、`block-reference`、`scan`、`build-prompt`、`publish`、`shot`、`comment`、`check` 和`usage` - 因此沒有任何內容作為幫助程式指令碼複製到您的儲存庫中。 `setup`和`doctor`是您本機執行的互動式助手； `gate` 是工作流程在每次回顧之前執行的安全門步驟。
+這將安裝 `visual-plan` 技能（其中包括操作執行的 `visual-recap` 技能）並將 `.github/workflows/pr-visual-recap.yml` 寫入您的儲存庫。工作流程透過 `npx @agent-native/recap-cli@latest recap <subcommand>` 呼叫**發布的 CLI 子指令** — 包括 `gate`、`collect-diff`、`block-reference`、`scan`、`build-prompt`、`publish`、`shot`、`comment`、`check` 和`usage` - 因此沒有任何內容作為幫助程式指令碼複製到您的儲存庫中。 `setup`和`doctor`是您本機執行的互動式助手； `gate` 是工作流程在每次回顧之前執行的安全門步驟。
 
 然後執行引導設定幫助程式：
 
 ```bash
-npx @agent-native/core@latest recap setup
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 `recap setup`重新整理工作流程，使用`gh`設定GitHub Actions
@@ -118,7 +118,7 @@ npx @agent-native/core@latest recap doctor
 產生的工作流程檔案並開啟 PR 以檢視其執行。
 
 預設情況下，工作流程根據最新捆綁的內容建置其代理提示
-`@agent-native/core@latest` 中的 `visual-recap` 指導，包括任何同級
+`@agent-native/recap-cli@latest` 中的 `visual-recap` 指導，包括任何同級
 技能附帶的參考檔案。如果您的儲存庫有意定制並且
 固定其提交的`visual-recap`資料夾，設定儲存庫變數
 `VISUAL_RECAP_SKILL_SOURCE=repo`.
@@ -135,8 +135,8 @@ npx @agent-native/core@latest recap doctor
 JSON 引號不可省略。此值會選取完整 `recap` 工作的執行器。若要在引導設定期間進行設定，請將相同的 JSON 值傳給 `--runs-on`，然後使用 `doctor` 驗證工作流程和執行器可用性：
 
 ```bash
-npx @agent-native/core@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 輕量級閘道會另外使用 `ubuntu-latest`。停用 GitHub 託管執行器的儲存庫可以將 `VISUAL_RECAP_GATE_RUNS_ON` 設為一個不含 JSON 的純文字標籤，或使用 `--gate-runs-on visual-recap-gate`。自訂標籤僅用於同一儲存庫中身分為 `OWNER`、`MEMBER` 或 `COLLABORATOR` 的作者；分支及其他作者會被強制使用 `ubuntu-latest`，在停用 GitHub 託管執行器時可能一直無法排程。請使用專用且最好是暫時性的執行器；標準閘道不會簽出 PR 樹，只評估工作流程邏輯與 PR 中繼資料。
@@ -160,12 +160,30 @@ npx @agent-native/core@latest recap doctor
 
 除了後端之外，兩個儲存庫變數還可以調整代理的執行方式：
 
-- **`VISUAL_RECAP_MODEL`** 固定傳遞給 CLI (`--model`) 的模型 — 例如 `gpt-5.6-sol` 用於 Codex，或 Claude 模型 ID。保留其未設定以使用 CLI 自己的預設模型。
+- **`VISUAL_RECAP_MODEL`** 固定傳遞給 CLI (`--model`) 的模型 — 例如 Codex 使用 `gpt-5.6-luna`、Claude 模型 ID，或 DeepSeek 使用 `deepseek-chat`。對於 `openai-compatible` 是必需的。對於 **Claude** 後端，保留未設定現在預設使用 `claude-sonnet-5`；要使用其他 Claude 模型（例如更便宜的 `claude-haiku-4-5`），請明確設定該變數。對於 **Codex** 後端，保留未設定將使用 Codex CLI 自身的預設模型。
 - **`VISUAL_RECAP_REASONING`** 設定推理深度：`none`、`minimal`、`low`、`medium`、`high` 或 `xhigh`。適用於Codex後端； Claude 的推理是模型驅動的，因此該變數被忽略。
 - **`VISUAL_RECAP_SKILL_SOURCE`** 控制提示新鮮度：`auto`/unset 使用最新的捆綁技能指南，而 `repo` 固定到已提交的儲存庫本機 `visual-recap` 技能資料夾。
 
 例如，要在 Codex 和 GPT-5.6 Sol 上以高推理執行回顧，請設定儲存庫變數 `VISUAL_RECAP_AGENT=codex`、`VISUAL_RECAP_MODEL=gpt-5.6-sol` 和 `VISUAL_RECAP_REASONING=high`。
 
+## 成本
+
+每次回顧執行都是一次完整的代理式編碼代理工作階段，讀取真實的 diff，而不是廉價的範本化摘要，因此其成本取決於模型選擇和執行頻率：
+
+- **每次 PR 推送都會執行完整工作階段。** 預設觸發程序在 `synchronize` 時觸發，因此被推送十次的 PR 會執行代理十次。
+- **每次都是整個 PR**，而不僅僅是自上次執行以來的提交 — 成本隨 PR 總大小而非增量差異大小擴展。
+- **差異輸入上限約為 600KB。** 這限制了每次執行的最壞情況，但大差異的成本仍然明顯高於小差異。
+- **失敗時自動重試一次**，這可能會讓一次暫時性失敗的執行成本大約加倍。
+
+若要降低成本：
+
+- **固定使用較便宜的模型。** 對於 Claude，為簡單或小型儲存庫設定 `VISUAL_RECAP_MODEL=claude-haiku-4-5` — 這是最便宜的 Claude 層級；`claude-sonnet-5`（預設值）是均衡層級。
+- **切換到使用較便宜模型的 Codex。** 設定 `VISUAL_RECAP_AGENT=codex` 並搭配 `VISUAL_RECAP_MODEL=gpt-5.6-luna`（最便宜的 GPT-5.6 層級）或 `gpt-5.6-terra`（中間層級），並設定 `VISUAL_RECAP_REASONING=low` 以進一步減少推理 token 花費。推理深度僅適用於 Codex。
+- **指向較便宜的 OpenAI 相容供應商。** 設定 `VISUAL_RECAP_AGENT=openai-compatible`，並搭配指向 DeepSeek、Kimi 或任何其他 OpenAI 相容端點的 `VISUAL_RECAP_BASE_URL`/`VISUAL_RECAP_MODEL`/`VISUAL_RECAP_API_KEY`。
+- **降低回顧頻率。** 將已安裝工作流程的 `on.pull_request.types` 從 `[opened, synchronize, reopened, ready_for_review, closed]` 編輯為 `[opened, ready_for_review, closed]`，使其僅在 PR 開啟和合併時回顧，而不是每次推送都回顧。
+
+每次執行都會記錄實際花費：工作流程的 `recap usage` 步驟會將 token 和成本使用情況附加到已發布的計畫中，因此你可以查看每次執行的實際花費，而不是靠猜測。
+
 ## 秘密和變數
 
 在儲存庫的 **設定 → 秘密和變數 → Actions** 中設定這些內容。
@@ -196,11 +214,11 @@ npx @agent-native/core@latest connect https://plan.agent-native.com --service-to
 
 **Solo：個人代幣仍然有效。**用 `npx @agent-native/core@latest connect` 鑄造它
 針對您的計畫應用程式。對於託管應用程式，這還會寫入本機
-`npx @agent-native/core@latest recap setup`可以讀取的發布權杖檔案：
+`npx @agent-native/recap-cli@latest recap setup`可以讀取的發布權杖檔案：
 
 ```bash
 npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
-npx @agent-native/core@latest recap setup
+npx @agent-native/recap-cli@latest recap setup
 ```
 
 如果您更喜歡手動設定，請將權杖貼上到 GitHub 金鑰中。使用
@@ -209,16 +227,16 @@ npx @agent-native/core@latest recap setup
 
 ### 可選（僅當您更改預設值時）
 
-| 秘密/變數                | 預設                            | 當你需要的時候                                                                                                               |
-| ------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `OPENAI_API_KEY`         | —                               | 秘密。與 `VISUAL_RECAP_AGENT=codex` 一起設定以使用 Codex 執行回顧。                                                          |
-| `VISUAL_RECAP_AGENT`     | `claude`                        | 變數。選取編碼代理後端（`claude` 或 `codex`）。                                                                              |
-| `VISUAL_RECAP_MODEL`     | 每個 CLI 的預設值               | 變數。固定模型 - 例如`gpt-5.6-sol` 表示 Codex，或 Claude 型號 ID。取消設定使用 CLI 自己的預設值。                            |
-| `VISUAL_RECAP_REASONING` | 每個模型的預設值                | 變數。推理深度：`none`、`minimal`、`low`、`medium`、`high` 或 `xhigh`。適用於Codex後端。                                     |
-| `RECAP_CLI_VERSION`      | `latest`                        | 變數。固定工作流程安裝的 `@agent-native/core` CLI 版本 - 例如`1.5.0`。參見[Version pinning](#version-pinning-copy-variant)。 |
-| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | 秘密。僅當在不同來源自行託管計畫應用時。                                                                                     |
+| 秘密/變數                | 預設                                        | 當你需要的時候                                                                                                                                                                                                       |
+| ------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                                           | 秘密。與 `VISUAL_RECAP_AGENT=codex` 一起設定以使用 Codex 執行回顧。                                                                                                                                                  |
+| `VISUAL_RECAP_AGENT`     | `claude`                                    | 變數。選取編碼代理後端（`claude` 或 `codex`）。                                                                                                                                                                      |
+| `VISUAL_RECAP_MODEL`     | Claude 使用 `claude-sonnet-5`；相容後端必需 | 變數。OpenAI 相容後端的供應商模型 ID（在該後端為必需）。對於 Claude，未設定時現在預設使用 `claude-sonnet-5` — 設定以覆寫，例如使用最便宜層級的 `claude-haiku-4-5`。對於 Codex，未設定時使用 Codex CLI 自身的預設值。 |
+| `VISUAL_RECAP_REASONING` | 每個模型的預設值                            | 變數。推理深度：`none`、`minimal`、`low`、`medium`、`high` 或 `xhigh`。適用於Codex後端。                                                                                                                             |
+| `RECAP_CLI_VERSION`      | `latest`                                    | 變數。固定工作流程安裝的 `@agent-native/recap-cli` CLI 版本 - 例如`1.5.0`。參見[Version pinning](#version-pinning-copy-variant)。                                                                                    |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com`             | 秘密。僅當在不同來源自行託管計畫應用時。                                                                                                                                                                             |
 
-工作流自動偵測如何呼叫其助手 CLI（此 monorepo 內的本機來源，在其他地方發布的 `@agent-native/core`），因此無需設定 `RECAP_CLI` 變數。
+工作流自動偵測如何呼叫其助手 CLI（此 monorepo 內的本機來源，在其他地方發布的 `@agent-native/recap-cli`），因此無需設定 `RECAP_CLI` 變數。
 
 ## 評論內嵌截圖
 
@@ -357,9 +375,9 @@ GitHub 操作專為託管、可共用的 PR 審核而設計。如果你想要一
 相同的幫助程式在本機檔案模式下本機流動：
 
 ```bash
-npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
-npx @agent-native/core@latest recap scan --diff recap.diff
-npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+npx @agent-native/recap-cli@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/recap-cli@latest recap scan --diff recap.diff
+npx @agent-native/recap-cli@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
 ```
 
 將產生的 `recap-prompt.md` 交給您的編碼代理。在本機檔案模式
@@ -389,7 +407,7 @@ npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap -
 
 ## 版本固定（複製變體） {#version-pinning-copy-variant}
 
-預設情況下，複製變體工作流程在執行時安裝 `@agent-native/core@latest`，因此每次回顧執行都會自動選取最新的 CLI。如果您的 CI 需要可重現的工具，請設定 **`RECAP_CLI_VERSION`** 儲存庫變數來固定已安裝的版本：
+預設情況下，複製變體工作流程在執行時安裝 `@agent-native/recap-cli@latest`，因此每次回顧執行都會自動選取最新的 CLI。如果您的 CI 需要可重現的工具，請設定 **`RECAP_CLI_VERSION`** 儲存庫變數來固定已安裝的版本：
 
 1. 轉到您的儲存庫的**設定 → 秘密和變數 → Actions → 變數**。
 2. 建立一個名為 `RECAP_CLI_VERSION` 的變數，其值類似於 `1.5.0`。
@@ -400,7 +418,7 @@ npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap -
 
 ## 秘密掃描允許清單
 
-在發布回顧之前，工作流程執行 `npx @agent-native/core@latest recap scan` 以偵測差異中可能的秘密。任何其 diff 與已知秘密模式匹配的 PR 都會被阻止並帶有解釋性註解 - 不會發布摘要，並且不會將 diff 內容傳送到編碼代理。
+在發布回顧之前，工作流程執行 `npx @agent-native/recap-cli@latest recap scan` 以偵測差異中可能的秘密。任何其 diff 與已知秘密模式匹配的 PR 都會被阻止並帶有解釋性註解 - 不會發布摘要，並且不會將 diff 內容傳送到編碼代理。
 
 在極少數情況下，儲存庫具有故意的測試裝置或表面上類似於秘密模式的非秘密字串（例如，測試檔案中的裝置金鑰）。要抑制誤報，請在儲存庫的根目錄中建立 `.github/recap-scan-allowlist`。
 
@@ -434,7 +452,7 @@ EXAMPLE_API_KEY=placeholder-value
 
 ### 為什麼使用可重用變體？
 
-預設安裝程式將完整的約 360 行工作流程 YAML 複製到您的儲存庫中（**複製**選項）。對於氣隙儲存庫或需要審核每一行執行內容的儲存庫來說，這是正確的選取。缺點是錯誤修復和改進永遠不會到達您的手中 - 您需要在每次發布後手動重新執行 `npx @agent-native/core@latest recap setup`。
+預設安裝程式將完整的約 360 行工作流程 YAML 複製到您的儲存庫中（**複製**選項）。對於氣隙儲存庫或需要審核每一行執行內容的儲存庫來說，這是正確的選取。缺點是錯誤修復和改進永遠不會到達您的手中 - 您需要在每次發布後手動重新執行 `npx @agent-native/recap-cli@latest recap setup`。
 
 **可重用**選項改為編寫一個精簡的約 20 行呼叫程式。它透過`uses:`委托給`BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml`。當工作流程執行時，每個呼叫者都會自動取得最新邏輯，無需本機更新。
 
@@ -447,7 +465,7 @@ EXAMPLE_API_KEY=placeholder-value
 
 ### 呼叫者片段
 
-這是`npx @agent-native/core@latest recap setup --reusable`寫的（或者你可以手動貼上）：
+這是`npx @agent-native/recap-cli@latest recap setup --reusable`寫的（或者你可以手動貼上）：
 
 ```yaml
 name: PR Visual Recap
@@ -482,7 +500,7 @@ jobs:
       skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
       runs-on: ${{ vars.VISUAL_RECAP_RUNS_ON || '"ubuntu-latest"' }}
       gate-runs-on: ${{ vars.VISUAL_RECAP_GATE_RUNS_ON || 'ubuntu-latest' }}
-      # cli-version: "latest"  # pin to a specific @agent-native/core version
+      # cli-version: "latest"  # pin to a specific @agent-native/recap-cli version
 ```
 
 適用 [Secrets and variables](#secrets-and-variables) 中描述的相同秘密和變數。可重複使用的呼叫端會將完整工作的 `VISUAL_RECAP_RUNS_ON` 轉送為 `runs-on`，並將閘道的 `VISUAL_RECAP_GATE_RUNS_ON` 轉送為單一標籤 `gate-runs-on`。省略時兩者都使用 `ubuntu-latest`。
@@ -491,15 +509,15 @@ jobs:
 
 ```bash
 # 編寫瘦呼叫者而不是完整副本：
-npx @agent-native/core@latest recap setup --reusable
+npx @agent-native/recap-cli@latest recap setup --reusable
 
 # 或者使用固定參考來實現可重複性：
-npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
+npx @agent-native/recap-cli@latest recap setup --reusable --ref v1.2.3
 ```
 
 兩種變體都將工作流程寫入 `.github/workflows/pr-visual-recap.yml`。如果現有工作流程已存在且有所不同，則該指令會拒絕並告訴您傳遞 `--force` 進行覆蓋。
 
-寫入後，照常執行 `npx @agent-native/core@latest recap doctor` 以確認機密已設定。
+寫入後，照常執行 `npx @agent-native/recap-cli@latest recap doctor` 以確認機密已設定。
 
 ### 版本固定
 
@@ -509,7 +527,7 @@ npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
 uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
 ```
 
-`cli-version` 輸入控制工作流程中執行的 `@agent-native/core` CLI 版本 - 將其保留在 `"latest"` 以跟蹤最新版本，或將其固定到版本字串（例如 `"1.5.0"`）以實現完全可重複性。
+`cli-version` 輸入控制工作流程中執行的 `@agent-native/recap-cli` CLI 版本 - 將其保留在 `"latest"` 以跟蹤最新版本，或將其固定到版本字串（例如 `"1.5.0"`）以實現完全可重複性。
 
 ### workflow_call事件脈絡
 

package/docs/content/locales/zh-TW/template-plan.mdx

@@ -208,6 +208,13 @@ vscode://builder.agent-native/open?url=<encoded-plan-url>
 **開放式問題**表格位於同一計畫的底部。接聽並傳送
 它向代理啟動針對現有計畫的修訂。
 
+## 成本和模型選擇
+
+產生計畫或回顧會對你的編碼代理的 LLM 執行一次完整的代理式工作階段，而不是輕量級的範本填充，因此成本會隨 diff 或計畫的大小以及你選擇的模型而變化。
+
+- 應用程式自身的預設聊天模型是 Sonnet 5；你可以隨時在 **設定** 中變更它。Haiku 是較便宜的 Claude 選項，Luna 是 GPT-5.6 系列中較便宜的選項。
+- 來自 GitHub Action 的自動化 PR 回顧與互動式應用程式分開執行，擁有自己的模型和成本調整項 — 關於 `VISUAL_RECAP_MODEL`、`VISUAL_RECAP_AGENT` 和 `VISUAL_RECAP_REASONING`，請參見[PR Visual Recap](/docs/pr-visual-recap)。
+
 ## 你可以用它做什麼
 
 - **實施前審查。** React 到圖表、線框圖、選項分頁，

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

@@ -102,13 +102,13 @@ explicitly at any time:
 npx @agent-native/core@latest skills add visual-plan --with-github-action
 ```
 
-This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** through `npx @agent-native/core@latest recap <subcommand>` — including `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check`, and `usage` — so nothing is copied into your repo as helper scripts. `setup` and `doctor` are the interactive helpers you run locally; `gate` is the security-gate step the workflow runs before every recap.
+This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** through `npx @agent-native/recap-cli@latest recap <subcommand>` — including `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check`, and `usage` — so nothing is copied into your repo as helper scripts. `setup` and `doctor` are the interactive helpers you run locally; `gate` is the security-gate step the workflow runs before every recap.
 
 Then run the guided setup helper:
 
 ```bash
-npx @agent-native/core@latest recap setup
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 `recap setup` refreshes the workflow, uses `gh` to set GitHub Actions
@@ -118,7 +118,7 @@ set. Secret values are sent to `gh` through stdin, not command arguments. Commit
 the generated workflow file and open a PR to see it run.
 
 By default, the workflow builds its agent prompt from the latest bundled
-`visual-recap` guidance in `@agent-native/core@latest`, including any sibling
+`visual-recap` guidance in `@agent-native/recap-cli@latest`, including any sibling
 reference files the skill ships with. If your repo intentionally customizes and
 pins its committed `visual-recap` folder, set the repository variable
 `VISUAL_RECAP_SKILL_SOURCE=repo`.
@@ -140,8 +140,8 @@ To configure it during guided setup, pass the same JSON value to `--runs-on`,
 then validate the workflow and runner availability with `doctor`:
 
 ```bash
-npx @agent-native/core@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 The lightweight security gate defaults separately to GitHub-hosted
@@ -186,7 +186,7 @@ If the variable is unset, the action uses `claude`.
 
 Beyond the backend, these repository variables tune how the agent runs:
 
-- **`VISUAL_RECAP_MODEL`** pins the model passed to the CLI (`--model`) — for example `gpt-5.6-sol` for Codex, a Claude model id, or `deepseek-chat` for DeepSeek. It is required for `openai-compatible`; Claude and Codex may leave it unset to use their CLI default.
+- **`VISUAL_RECAP_MODEL`** pins the model passed to the CLI (`--model`) — for example `gpt-5.6-luna` for Codex, a Claude model id, or `deepseek-chat` for DeepSeek. It is required for `openai-compatible`. For the **Claude** backend, leaving it unset now defaults to `claude-sonnet-5`; set the variable explicitly to use a different Claude model, such as the cheaper `claude-haiku-4-5`. For the **Codex** backend, leaving it unset uses the Codex CLI's own default model.
 - **`VISUAL_RECAP_REASONING`** sets the reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. It applies to the Codex backend; Claude's reasoning is model-driven, so this variable is ignored there.
 - **`VISUAL_RECAP_BASE_URL`** selects the HTTP(S) base URL for the `openai-compatible` backend. Use the provider's OpenAI-compatible endpoint, such as DeepSeek or Kimi, without embedding credentials in the URL.
 - **`VISUAL_RECAP_SKILL_SOURCE`** controls prompt freshness: `auto`/unset uses the latest bundled skill guidance, while `repo` pins to the committed repo-local `visual-recap` skill folder.
@@ -195,6 +195,24 @@ For example, to run the recap on Codex with GPT-5.6 Sol at high reasoning, set t
 
 For DeepSeek, set `VISUAL_RECAP_AGENT=openai-compatible`, `VISUAL_RECAP_BASE_URL=https://api.deepseek.com/v1`, `VISUAL_RECAP_MODEL=deepseek-chat`, and the `VISUAL_RECAP_API_KEY` secret. Kimi works the same way with its OpenAI-compatible base URL and model id. Other OpenAI-compatible providers use the same three settings.
 
+## Cost
+
+Each recap run is a full agentic coding-agent session reading a real diff, not a cheap templated summary, so its cost tracks model choice and how often it runs:
+
+- **A full session per PR push.** The default trigger fires on `synchronize`, so a PR that gets pushed to ten times runs the agent ten times.
+- **The whole PR each time**, not just the commits since the last run — cost scales with total PR size, not incremental diff size.
+- **Diff input capped at ~600KB.** This bounds the worst case per run, but large diffs still cost meaningfully more than small ones.
+- **One automatic retry on failure**, which can roughly double the cost of a run that fails transiently.
+
+To reduce cost:
+
+- **Pin a cheaper model.** For Claude, set `VISUAL_RECAP_MODEL=claude-haiku-4-5` for simple or small repos — it's the cheapest Claude tier; `claude-sonnet-5` (the default) is the balanced tier.
+- **Switch to Codex with a cheaper model.** Set `VISUAL_RECAP_AGENT=codex` with `VISUAL_RECAP_MODEL=gpt-5.6-luna` (the cheapest GPT-5.6 tier) or `gpt-5.6-terra` (mid-tier), and set `VISUAL_RECAP_REASONING=low` to cut reasoning-token spend further. Reasoning depth only applies to Codex.
+- **Point at a cheaper OpenAI-compatible provider.** Set `VISUAL_RECAP_AGENT=openai-compatible` with `VISUAL_RECAP_BASE_URL`/`VISUAL_RECAP_MODEL`/`VISUAL_RECAP_API_KEY` targeting DeepSeek, Kimi, or any other OpenAI-compatible endpoint.
+- **Recap less often.** Edit the installed workflow's `on.pull_request.types` from `[opened, synchronize, reopened, ready_for_review, closed]` to `[opened, ready_for_review, closed]` so it recaps only when a PR opens and when it merges, instead of on every push.
+
+Every run records what it actually spent: the workflow's `recap usage` step attaches token and cost usage to the published plan, so you can look at real spend per run instead of guessing.
+
 ## Secrets and variables
 
 Set these in your repository's **Settings → Secrets and variables → Actions**.
@@ -225,11 +243,11 @@ Plans app.
 
 **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/core@latest recap setup` can read:
+publish-token file that `npx @agent-native/recap-cli@latest recap setup` can read:
 
 ```bash
 npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
-npx @agent-native/core@latest recap setup
+npx @agent-native/recap-cli@latest recap setup
 ```
 
 If you prefer manual setup, paste the token into the GitHub secret. Use a
@@ -238,18 +256,18 @@ real token.
 
 ### Optional (only if you change defaults)
 
-| Secret / variable        | Default                         | When you need it                                                                                                                                |
-| ------------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OPENAI_API_KEY`         | —                               | Secret. Set together with `VISUAL_RECAP_AGENT=codex` to run the recap with Codex instead.                                                       |
-| `VISUAL_RECAP_API_KEY`   | —                               | Secret. Set with `VISUAL_RECAP_AGENT=openai-compatible` for DeepSeek, Kimi, or another OpenAI-compatible provider.                              |
-| `VISUAL_RECAP_AGENT`     | `claude`                        | Variable. Selects the coding-agent backend (`claude`, `codex`, or `openai-compatible`).                                                         |
-| `VISUAL_RECAP_BASE_URL`  | required for compatible backend | Variable. HTTP(S) base URL for the OpenAI-compatible backend; credentials are rejected.                                                         |
-| `VISUAL_RECAP_MODEL`     | required for compatible backend | Variable. Provider model id for OpenAI-compatible backends; optional for Claude/Codex, where unset uses the CLI default.                        |
-| `VISUAL_RECAP_REASONING` | each model's default            | Variable. Reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Applies to the Codex backend.                                |
-| `RECAP_CLI_VERSION`      | `latest`                        | Variable. Pins the `@agent-native/core` CLI version the workflow installs — e.g. `1.5.0`. See [Version pinning](#version-pinning-copy-variant). |
-| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | Secret. Only when self-hosting the Plans app at a different origin.                                                                             |
+| Secret / variable        | Default                                                       | When you need it                                                                                                                                                                                                                                         |
+| ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                                                             | Secret. Set together with `VISUAL_RECAP_AGENT=codex` to run the recap with Codex instead.                                                                                                                                                                |
+| `VISUAL_RECAP_API_KEY`   | —                                                             | Secret. Set with `VISUAL_RECAP_AGENT=openai-compatible` for DeepSeek, Kimi, or another OpenAI-compatible provider.                                                                                                                                       |
+| `VISUAL_RECAP_AGENT`     | `claude`                                                      | Variable. Selects the coding-agent backend (`claude`, `codex`, or `openai-compatible`).                                                                                                                                                                  |
+| `VISUAL_RECAP_BASE_URL`  | required for compatible backend                               | Variable. HTTP(S) base URL for the OpenAI-compatible backend; credentials are rejected.                                                                                                                                                                  |
+| `VISUAL_RECAP_MODEL`     | `claude-sonnet-5` for Claude; required for compatible backend | Variable. Provider model id for OpenAI-compatible backends (required there). For Claude, unset now defaults to `claude-sonnet-5` — set it to override, e.g. `claude-haiku-4-5` for the cheapest tier. For Codex, unset uses the Codex CLI's own default. |
+| `VISUAL_RECAP_REASONING` | each model's default                                          | Variable. Reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Applies to the Codex backend.                                                                                                                                         |
+| `RECAP_CLI_VERSION`      | `latest`                                                      | Variable. Pins the `@agent-native/recap-cli` version the workflow installs — e.g. `1.5.0`. See [Version pinning](#version-pinning-copy-variant).                                                                                                         |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com`                               | Secret. Only when self-hosting the Plans app at a different origin.                                                                                                                                                                                      |
 
-The workflow auto-detects how to invoke its helper CLI (local source inside this monorepo, the published `@agent-native/core` elsewhere), so there is no `RECAP_CLI` variable to set.
+The workflow auto-detects how to invoke its helper CLI (local source inside this monorepo, the published `@agent-native/recap-cli` elsewhere), so there is no `RECAP_CLI` variable to set.
 
 ## Inline screenshot in the comment
 
@@ -390,9 +408,9 @@ recap without sending recap content to the Agent-Native Plan database, run the
 same helper flow locally in local-files mode instead:
 
 ```bash
-npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
-npx @agent-native/core@latest recap scan --diff recap.diff
-npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+npx @agent-native/recap-cli@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/recap-cli@latest recap scan --diff recap.diff
+npx @agent-native/recap-cli@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
 ```
 
 Give the generated `recap-prompt.md` to your coding agent. In local-files mode
@@ -422,7 +440,7 @@ The recap is a review aid layered on top of the normal PR flow:
 
 ## Version pinning (copy variant) {#version-pinning-copy-variant}
 
-By default the copy-variant workflow installs `@agent-native/core@latest` at run time so every recap run automatically picks up the newest CLI. If your CI needs reproducible tooling, set the **`RECAP_CLI_VERSION`** repository variable to pin the installed version:
+By default the copy-variant workflow installs `@agent-native/recap-cli@latest` at run time so every recap run automatically picks up the newest CLI. If your CI needs reproducible tooling, set the **`RECAP_CLI_VERSION`** repository variable to pin the installed version:
 
 1. Go to your repo's **Settings → Secrets and variables → Actions → Variables**.
 2. Create a variable named `RECAP_CLI_VERSION` with a value like `1.5.0`.
@@ -433,7 +451,7 @@ For the reusable-caller variant, use the `cli-version` input instead (see [Versi
 
 ## Secret-scan allowlist
 
-Before publishing a recap the workflow runs `npx @agent-native/core@latest recap scan` to detect likely secrets in the diff. Any PR whose diff matches a known-secret pattern is blocked with an explanatory comment — the recap is not published, and no diff content is sent to the coding agent.
+Before publishing a recap the workflow runs `npx @agent-native/recap-cli@latest recap scan` to detect likely secrets in the diff. Any PR whose diff matches a known-secret pattern is blocked with an explanatory comment — the recap is not published, and no diff content is sent to the coding agent.
 
 In rare cases a repo has intentional test fixtures or non-secret strings that superficially resemble secret patterns (e.g., a fixture key in a test file). To suppress a false positive, create `.github/recap-scan-allowlist` in the root of your repository.
 
@@ -467,7 +485,7 @@ The allowlist is only consulted by the secret-scan gate. It does not affect what
 
 ### Why use the reusable variant?
 
-The default installer copies the full ~360-line workflow YAML into your repo (the **copy** option). This is the right choice for air-gapped repos or repos that need to audit every line of what runs. The downside is that bug fixes and improvements never reach you — you need to re-run `npx @agent-native/core@latest recap setup` manually after each release.
+The default installer copies the full ~360-line workflow YAML into your repo (the **copy** option). This is the right choice for air-gapped repos or repos that need to audit every line of what runs. The downside is that bug fixes and improvements never reach you — you need to re-run `npx @agent-native/recap-cli@latest recap setup` manually after each release.
 
 The **reusable** option writes a thin ~20-line caller instead. It delegates to `BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml` via `uses:`. Every caller automatically picks up the latest logic when the workflow runs, with no local update needed.
 
@@ -480,7 +498,7 @@ The **reusable** option writes a thin ~20-line caller instead. It delegates to `
 
 ### Caller snippet
 
-This is what `npx @agent-native/core@latest recap setup --reusable` writes (or you can paste it manually):
+This is what `npx @agent-native/recap-cli@latest recap setup --reusable` writes (or you can paste it manually):
 
 ```yaml
 name: PR Visual Recap
@@ -517,7 +535,7 @@ jobs:
       skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
       runs-on: ${{ vars.VISUAL_RECAP_RUNS_ON || '"ubuntu-latest"' }}
       gate-runs-on: ${{ vars.VISUAL_RECAP_GATE_RUNS_ON || 'ubuntu-latest' }}
-      # cli-version: "latest"  # pin to a specific @agent-native/core version
+      # cli-version: "latest"  # pin to a specific @agent-native/recap-cli version
 ```
 
 The same secrets and variables described in [Secrets and variables](#secrets-and-variables) apply — set them in your repo settings the same way as for the copy variant. The reusable caller forwards `VISUAL_RECAP_RUNS_ON` through its JSON `runs-on` input for the full recap job and `VISUAL_RECAP_GATE_RUNS_ON` through its plain-label `gate-runs-on` input for the metadata-only gate. The latter is used only for trusted same-repository authors; other PRs use GitHub-hosted `ubuntu-latest`. Omitting either input preserves its `ubuntu-latest` default.
@@ -526,15 +544,15 @@ The same secrets and variables described in [Secrets and variables](#secrets-and
 
 ```bash
 # Write the thin caller instead of the full copy:
-npx @agent-native/core@latest recap setup --reusable
+npx @agent-native/recap-cli@latest recap setup --reusable
 
 # Or with a pinned ref for reproducibility:
-npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
+npx @agent-native/recap-cli@latest recap setup --reusable --ref v1.2.3
 ```
 
 Both variants write the workflow to `.github/workflows/pr-visual-recap.yml`. If an existing workflow is already there and differs, the command refuses and tells you to pass `--force` to overwrite.
 
-After writing, run `npx @agent-native/core@latest recap doctor` as usual to confirm secrets are configured.
+After writing, run `npx @agent-native/recap-cli@latest recap doctor` as usual to confirm secrets are configured.
 
 ### Version pinning
 
@@ -544,7 +562,7 @@ By default the caller references `@main`, which always uses the latest published
 uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
 ```
 
-The `cli-version` input controls which `@agent-native/core` CLI version runs inside the workflow — leave it at `"latest"` to track the newest release, or pin it to a version string (e.g. `"1.5.0"`) for full reproducibility.
+The `cli-version` input controls which `@agent-native/recap-cli` version runs inside the workflow — leave it at `"latest"` to track the newest release, or pin it to a version string (e.g. `"1.5.0"`) for full reproducibility.
 
 ### workflow_call event context
 

package/docs/content/template-plan.mdx

@@ -226,6 +226,20 @@ If the first pass still has answerable decisions, the agent can place an
 **Open Questions** form at the bottom of the same plan. Answering it and sending
 it to the agent starts a revision turn against the existing plan.
 
+## Cost and model choice
+
+Generating a plan or recap runs a full agentic session against your coding
+agent's LLM, not a lightweight template fill, so cost scales with the size of
+the diff or plan and the model you choose.
+
+- The app's own default chat model is Sonnet 5; change it any time in
+  **Settings**. Haiku is the cheaper Claude option, and Luna is the cheaper
+  option in the GPT-5.6 family.
+- Automated PR recaps from the GitHub Action run separately from the
+  interactive app and have their own model and cost knobs — see
+  [PR Visual Recap](/docs/pr-visual-recap) for `VISUAL_RECAP_MODEL`,
+  `VISUAL_RECAP_AGENT`, and `VISUAL_RECAP_REASONING`.
+
 ## What you can do with it
 
 - **Review before implementation.** React to diagrams, wireframes, option tabs,

package/docs/content/toolkit-comments-review.mdx

@@ -24,9 +24,9 @@ status such as draft, review, approved, or needs changes.
 | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `registerReviewableResource()` | Register a resource type and optional access resolver for review actions.                                                                                         |
 | Comment actions                | `list-review-comments`, `create-review-comment`, `reply-review-comment`, `resolve-review-thread`, and `delete-review-comment`.                                    |
-| Feedback actions               | `get-review-feedback` and `consume-review-feedback` for agent-readable review queues.                                                                             |
+| Feedback actions               | `get-review-feedback`, `send-review-thread-to-agent`, and `consume-review-feedback` for root-thread agent queues and human handoffs.                              |
 | Review status action           | `set-review-status` for draft, in review, approved, and changes requested states.                                                                                 |
-| `ReviewThreadPanel`            | Drop-in React panel with comment composer, replies, resolve, and delete controls.                                                                                 |
+| `ReviewThreadPanel`            | Drop-in React panel with capability-gated composer, reply, resolve, delete, and custom thread-action controls.                                                    |
 | `ReviewStatusBadge`            | Controlled status badge for app headers, sidebars, and review panels.                                                                                             |
 | Review hooks                   | `useReviewComments()`, `useCreateReviewComment()`, `useReplyReviewComment()`, `useResolveReviewThread()`, `useDeleteReviewComment()`, and `useSetReviewStatus()`. |
 | Mentions helpers               | `extractReviewMentions()` and `normalizeReviewMentions()` for `@[Label](mailto:email@example.com)` tokens.                                                        |
@@ -42,6 +42,13 @@ specialize anchor shapes, but the common model preserves:
 - `parentCommentId` for replies
 - optional `mentions`
 - optional `anchor` or `resolutionTarget`
+- optional `resolutionNote` on a resolved root thread
+
+`list-review-comments` supports anonymous reads for resources whose access
+resolver grants public viewer access. Public viewer responses redact ownership,
+organization, email, and actor metadata while preserving safe display names and
+the caller-specific `canDelete` capability. Its `summary` reports unpaginated
+open-root and agent-queue counts even when the returned comment page is bounded.
 
 ## Register A Resource {#register-resource}
 
@@ -76,6 +83,9 @@ export function DocumentReview({ documentId }: { documentId: string }) {
       resourceType="document"
       resourceId={documentId}
       targetId="intro-section"
+      canReply
+      canResolve={false}
+      canDeleteComment={(comment) => comment.canDelete === true}
     />
   );
 }
@@ -93,6 +103,10 @@ actions and thread UI.
 - Agents can read open review feedback before changing code or content.
 - `consumedAt` and `resolved` are separate. An agent can consume a piece of
   feedback without closing the reviewer-visible thread.
+- The root comment owns routing. A human-targeted root is absent from the agent
+  queue; sending it back to the agent clears its previous consumption marker.
+- Agents can pass `resolutionNote` to `resolve-review-thread` so verification
+  evidence remains attached to the resolved root.
 
 ## What's next
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.100.2",
+  "version": "0.101.2",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -156,6 +156,7 @@
     "./review/actions/consume-review-feedback": "./dist/review/actions/consume-review-feedback.js",
     "./review/actions/get-review-feedback": "./dist/review/actions/get-review-feedback.js",
     "./review/actions/set-review-status": "./dist/review/actions/set-review-status.js",
+    "./review/actions/send-review-thread-to-agent": "./dist/review/actions/send-review-thread-to-agent.js",
     "./comments-review/actions/list-review-comments": "./dist/review/actions/list-review-comments.js",
     "./comments-review/actions/create-review-comment": "./dist/review/actions/create-review-comment.js",
     "./comments-review/actions/reply-review-comment": "./dist/review/actions/reply-review-comment.js",
@@ -164,6 +165,7 @@
     "./comments-review/actions/consume-review-feedback": "./dist/review/actions/consume-review-feedback.js",
     "./comments-review/actions/get-review-feedback": "./dist/review/actions/get-review-feedback.js",
     "./comments-review/actions/set-review-status": "./dist/review/actions/set-review-status.js",
+    "./comments-review/actions/send-review-thread-to-agent": "./dist/review/actions/send-review-thread-to-agent.js",
     "./sharing": "./dist/sharing/index.js",
     "./sharing/actions/share-resource": "./dist/sharing/actions/share-resource.js",
     "./sharing/actions/unshare-resource": "./dist/sharing/actions/unshare-resource.js",
@@ -333,6 +335,7 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
+    "@agent-native/recap-cli": "0.3.0",
     "@agent-native/toolkit": "^0.4.10"
   },
   "devDependencies": {

package/corpus/templates/forms/server/routes/api/forms/og/[slug]/og.png.get.ts

@@ -1,45 +0,0 @@
-import { agentNativeOgImageResponseHeaders } from "@agent-native/core/server";
-import {
-  defineEventHandler,
-  getMethod,
-  getRouterParam,
-  setResponseStatus,
-  type H3Event,
-} from "h3";
-
-import { renderFormOgImagePng } from "../../../../../lib/form-og-image.js";
-import { getPublicFormBySlugOrId } from "../../../../../lib/public-form-ssr.js";
-
-function pngBody(bytes: Uint8Array): ArrayBuffer {
-  const body = new ArrayBuffer(bytes.byteLength);
-  new Uint8Array(body).set(bytes);
-  return body;
-}
-
-export default defineEventHandler(async (event: H3Event) => {
-  const slug = getRouterParam(event, "slug");
-  if (!slug) {
-    setResponseStatus(event, 400);
-    return { error: "slug is required" };
-  }
-
-  const form = await getPublicFormBySlugOrId(slug);
-  if (!form) {
-    setResponseStatus(event, 404);
-    return { error: "Form not found" };
-  }
-
-  if (getMethod(event) === "HEAD") {
-    return new Response(null, {
-      headers: agentNativeOgImageResponseHeaders(0),
-    });
-  }
-
-  const png = await renderFormOgImagePng({
-    title: form.title,
-  });
-
-  return new Response(pngBody(png), {
-    headers: agentNativeOgImageResponseHeaders(png.byteLength),
-  });
-});