@agent-native/core 0.46.0 → 0.48.1

package/docs/content/observability.md

@@ -1,13 +1,15 @@
 ---
 title: "Observability"
-description: "Agent traces, evals, feedback, A/B experiments, and the admin dashboard — all built-in with zero configuration."
+description: "Agent traces, evals, feedback, A/B experiments, and the built-in dashboard — all with zero configuration."
 ---
 
 # Agent Observability
 
 Every agent-native app gets observability out of the box. Traces, automated evals, user feedback, and A/B experiments work with zero configuration — all data lives in the app's own SQL database.
 
-## What's Captured Automatically
+This page covers _agent quality_ metrics: traces, cost, evals, and feedback stored in your database. For _product_ analytics (your app's events flowing to PostHog/Mixpanel/Amplitude), see [Tracking](/docs/tracking).
+
+## What's captured automatically {#captured}
 
 When a user sends a message, the framework automatically records:
 
@@ -19,7 +21,7 @@ When a user sends a message, the framework automatically records:
 
 No code changes needed. The instrumentation hooks into `production-agent.ts` transparently.
 
-## The Dashboard
+## The dashboard {#dashboard}
 
 Add the dashboard to any template with a single route:
 
@@ -36,6 +38,8 @@ export default function ObservabilityPage() {
 }
 ```
 
+All data is scoped to the signed-in user; there is no cross-user admin view today.
+
 The dashboard has 5 tabs:
 
 | Tab               | What it shows                                                                   |
@@ -46,13 +50,13 @@ The dashboard has 5 tabs:
 | **Experiments**   | A/B test list with status badges, variant results with confidence intervals     |
 | **Feedback**      | Thumbs up/down stream, category breakdown, frustration scores                   |
 
-## User Feedback
+## User feedback {#feedback}
 
-### Explicit Feedback
+### Explicit feedback
 
 Thumbs up/down buttons render inline on every agent message in the chat UI. Thumbs down opens a category popover (Inaccurate, Not helpful, Wrong tool, Too slow). This is wired into `AssistantChat.tsx` automatically.
 
-### Implicit Feedback (Frustration Index)
+### Implicit feedback (frustration index)
 
 The framework computes a Frustration Index (0-100) from conversation signals:
 
@@ -66,7 +70,7 @@ The framework computes a Frustration Index (0-100) from conversation signals:
 
 Score interpretation: 0-20 = healthy, 20-40 = friction, 40-60 = dissatisfied, 60+ = broken session.
 
-## Automated Evals
+## Automated evals {#evals}
 
 Five deterministic scorers run after every agent run:
 
@@ -78,7 +82,7 @@ Five deterministic scorers run after every agent run:
 | `cost_efficiency`   | Normalized against cost baseline                       | 0-1         |
 | `error_recovery`    | Did the agent recover from tool errors?                | 0 or 1      |
 
-### LLM-as-Judge (Optional)
+### LLM-as-judge (optional)
 
 Enable sampled LLM-based evaluation by setting `evalSampleRate`:
 
@@ -101,7 +105,7 @@ const criteria = {
 };
 ```
 
-## A/B Experiments
+## A/B experiments {#experiments}
 
 Test different models, temperatures, or agent configurations:
 
@@ -124,7 +128,7 @@ PUT /_agent-native/observability/experiments/:id
 
 The agent loop automatically resolves the user's variant and applies the config override. Assignment uses consistent hashing — same user always gets the same variant.
 
-## Configuration
+## Configuration {#config}
 
 All settings are stored in the `observability-config` key:
 
@@ -141,7 +145,7 @@ All settings are stored in the `observability-config` key:
 
 Content is **redacted by default** — only token counts, costs, and timing are stored. Opt in to content capture when needed for debugging.
 
-## API Endpoints
+## API endpoints {#api}
 
 All auto-mounted at `/_agent-native/observability/`:
 
@@ -158,13 +162,14 @@ All auto-mounted at `/_agent-native/observability/`:
 | GET    | `/evals/stats`             | Eval statistics                |
 | POST   | `/experiments`             | Create experiment              |
 | GET    | `/experiments`             | List experiments               |
+| GET    | `/experiments/:id`         | Get experiment detail          |
 | PUT    | `/experiments/:id`         | Update experiment              |
 | POST   | `/experiments/:id/results` | Compute results                |
 | GET    | `/experiments/:id/results` | Get results                    |
 
 All endpoints support `?since=N` (ms timestamp) and `?limit=N` query params.
 
-## Export to External Platforms
+## Export to external platforms {#export}
 
 Send traces to Langfuse, Datadog, Grafana, or any OTel-compatible backend:
 
@@ -183,7 +188,7 @@ await putSetting("observability-config", {
 
 The framework emits `gen_ai.*` semantic convention spans compatible with the OpenTelemetry GenAI spec.
 
-## Error Reporting (Sentry)
+## Error reporting (Sentry) {#sentry}
 
 Server-side errors that escape Nitro route handlers are reported to Sentry when a DSN is configured. Without it the SDK silently no-ops, so it's safe to leave the env vars unset in dev. Browser and server events can go to the same Sentry project; split them into separate projects only when you want operational separation for ownership, volume, quotas, or alert routing.
 
@@ -193,7 +198,7 @@ Server-side errors that escape Nitro route handlers are reported to Sentry when
 | Nitro server       | `@sentry/node`    | `SENTRY_SERVER_DSN` or `SENTRY_DSN`                            | Captures 5xx responses and Nitro lifecycle errors. Per-request user.  |
 | `agent-native` CLI | `@sentry/node`    | _hardcoded_                                                    | Crash reports from the published CLI binary; not user-configurable.   |
 
-### Server-side configuration
+### Server-side configuration {#sentry-config}
 
 Set `SENTRY_SERVER_DSN` or the shared `SENTRY_DSN` in the deploy environment (Netlify dashboard, Cloudflare secrets, etc.). The framework auto-mounts a Nitro plugin that:
 
@@ -218,7 +223,7 @@ export default createSentryPlugin();
 
 The CLI's hardcoded DSN is intentional — the published binary needs to phone home crashes regardless of which environment runs it. The server module never hardcodes a DSN because it runs inside customer environments where operators decide whether errors should reach Sentry at all.
 
-### Privacy & PII
+### Privacy & PII {#privacy}
 
 Both server and CLI initialize with `sendDefaultPii: false` and a `beforeSend` hook that strips:
 
@@ -229,3 +234,9 @@ Both server and CLI initialize with `sendDefaultPii: false` and a `beforeSend` h
 - Any event whose top-level exception type is `ValidationError` (treated as expected user-input rejection, not a bug).
 
 Identity fields explicitly set via `setUser({ id, email, username })` are preserved.
+
+## What's next
+
+- [**Tracking**](/docs/tracking) — product analytics (PostHog, Mixpanel, Amplitude) for your app's own events
+- [**Actions**](/docs/actions) — the operations that appear as tool calls in traces
+- [**Security**](/docs/security) — data scoping and credential handling

package/docs/content/onboarding.md

@@ -99,6 +99,7 @@ All routes live under `/_agent-native/onboarding/`:
 // server/plugins/my-onboarding.ts
 import { defineNitroPlugin } from "@agent-native/core/server";
 import { registerOnboardingStep } from "@agent-native/core/onboarding";
+import { listOAuthAccounts } from "@agent-native/core/oauth-tokens";
 
 export default defineNitroPlugin(() => {
   registerOnboardingStep({
@@ -127,7 +128,12 @@ export default defineNitroPlugin(() => {
         },
       },
     ],
-    isComplete: () => !!process.env.GMAIL_REFRESH_TOKEN,
+    // OAuth tokens live in the oauth_tokens store (saveOAuthTokens), not env vars.
+    // Check the store — not process.env.GMAIL_REFRESH_TOKEN.
+    isComplete: async () => {
+      const accounts = await listOAuthAccounts("google");
+      return accounts.length > 0;
+    },
   });
 });
 ```

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

@@ -5,7 +5,7 @@ description: "A GitHub Action that runs your repo's visual-recap skill on every
 
 # PR Visual Recap
 
-PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs your repo's [`visual-recap`](/docs/template-plan) skill against the PR diff, publishes a structured recap plan to the hosted Plans app, shows an informational `Visual Recap` check while it runs, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
+PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs the latest bundled [`visual-recap`](/docs/template-plan) skill (or your repo's committed copy when `VISUAL_RECAP_SKILL_SOURCE=repo`) against the PR diff, publishes a structured recap plan to the hosted Plans app, shows an informational `Visual Recap` check while it runs, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
 
 This is not a deterministic diff renderer. The action invokes a real coding agent (Claude Code CLI by default, or OpenAI Codex CLI) that reads the change, decides what matters, and authors the recap by calling the Plans MCP tool `create-visual-recap` — the same tool the `/visual-recap` slash command uses. You get a high-altitude, schema/API/before-after view of the change instead of a wall of raw diff.
 
@@ -16,8 +16,8 @@ The recap is **informational and non-blocking**. It creates a check row so revie
 On each PR push, the workflow:
 
 1. Collects a bounded diff between the PR base and head.
-2. Creates an informational `Visual Recap` GitHub check with `Review in progress`.
-3. Runs the configured coding agent against that diff. The agent reads your repo's `visual-recap` skill and authors a recap, publishing it with `create-visual-recap`.
+2. Creates an informational `Visual Recap` GitHub check with `Visual recap in progress`.
+3. Runs the configured coding agent against that diff. The agent reads the bundled `visual-recap` skill guidance (or your repo-pinned copy) and authors a recap, publishing it with `create-visual-recap`.
 4. Reads the published plan URL the agent wrote to `recap-url.txt`.
 5. Opens that URL in headless Chrome and screenshots the rendered plan.
 6. Uploads the PNG to a signed public image route on the Plans app.
@@ -36,7 +36,7 @@ explicitly at any time:
 agent-native 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** — `agent-native recap scan|build-prompt|shot|comment` — so nothing is copied into your repo as helper scripts.
+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** — `agent-native recap gate|collect-diff|mcp-config|scan|build-prompt|shot|comment|check|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:
 
@@ -84,14 +84,31 @@ Set these in your repository's **Settings → Secrets and variables → Actions*
 
 ### Secrets (only two required)
 
-| Secret              | Purpose                                                                                                                     |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `PLAN_RECAP_TOKEN`  | Per-user, revocable token minted by `agent-native connect`. Authorizes publishing the recap plan and the screenshot upload. |
-| `ANTHROPIC_API_KEY` | The LLM key for the default Claude Code backend.                                                                            |
+| Secret              | Purpose                                                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `PLAN_RECAP_TOKEN`  | Revocable token minted by `agent-native connect`. Authorizes publishing the recap plan and the screenshot upload. |
+| `ANTHROPIC_API_KEY` | The LLM key for the default Claude Code backend.                                                                  |
 
-Mint `PLAN_RECAP_TOKEN` with `agent-native connect` against your Plans app. For
-the hosted app, this also writes a local publish-token file that
-`agent-native recap setup` can read:
+**Teams: use an org service token.** A personal token is bound to the person
+who minted it — if they leave the org or revoke their tokens, every repo using
+that secret starts failing with 401s, and CI-created plans are owned by that
+individual instead of the team. An org service token is owned by your
+**organization**: it acts as a service principal (`svc-<name>@service.<orgId>`),
+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
+agent-native connect https://plan.agent-native.com --service-token pr-recap
+```
+
+The command authenticates you in the browser, then prints the service token
+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.
+
+**Solo: a personal token still works.** Mint it with `agent-native connect`
+against your Plans app. For the hosted app, this also writes a local
+publish-token file that `agent-native recap setup` can read:
 
 ```bash
 agent-native connect https://plan.agent-native.com --client codex
@@ -104,13 +121,14 @@ 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_AGENT`     | `claude`                        | Variable. Selects the coding-agent backend (`claude` or `codex`).                                                |
-| `VISUAL_RECAP_MODEL`     | each CLI's default              | Variable. Pins the model — e.g. `gpt-5.5` for Codex, or a Claude model id. Unset uses the 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. |
-| `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_AGENT`     | `claude`                        | Variable. Selects the coding-agent backend (`claude` or `codex`).                                                                               |
+| `VISUAL_RECAP_MODEL`     | each CLI's default              | Variable. Pins the model — e.g. `gpt-5.5` for Codex, or a Claude model id. Unset uses the 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/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.                                                                             |
 
 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.
 
@@ -118,15 +136,57 @@ The workflow auto-detects how to invoke its helper CLI (local source inside this
 
 After the agent publishes the recap, the workflow screenshots the rendered plan in headless Chrome and uploads the PNG to a signed public image route on the Plans app. The sticky PR comment then embeds that screenshot **inline** — GitHub re-serves it through its camo proxy, so reviewers see a preview of the recap directly in the comment without opening anything. The link to the full interactive plan sits right next to it for when they want to explore, comment, or annotate.
 
-## Fork-PR safety
+## Fork PRs
+
+### Default behavior (no action required)
+
+The main `pr-visual-recap.yml` workflow fires on the plain `pull_request` trigger, **not** `pull_request_target`. Fork PRs therefore run with **no access to repository secrets**, so the workflow finds no `PLAN_RECAP_TOKEN` and cleanly no-ops — no failed publish, no error comment, no credentials exposed. Recaps only run for PRs from branches in the same repository, where the secrets are available.
+
+This also means you can merge the workflow file **before** the secrets exist: with no token configured, every run is a quiet no-op until you set the secrets. The `gate` step also skips draft PRs and bot-authored PRs automatically, so neither trigger recap runs by default.
+
+### Opt-in with the label-gated fork workflow
+
+If you want to generate recaps for fork PRs, a second workflow file is available: `.github/workflows/pr-visual-recap-fork.yml`. It uses `pull_request_target` (which runs with base-repo secrets) but requires an explicit **per-PR maintainer opt-in** via a `recap` label before the recap agent runs.
+
+To install it, copy the file from [BuilderIO/agent-native](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/pr-visual-recap-fork.yml) into your repo's `.github/workflows/` directory alongside the existing `pr-visual-recap.yml`. The same secrets (`PLAN_RECAP_TOKEN`, `ANTHROPIC_API_KEY`) apply.
+
+### How the label gate works
+
+1. A fork contributor opens a PR. No recap runs automatically.
+2. A maintainer reviews the diff (especially for any prompt-injection-shaped content — see below), then applies the `recap` label to the PR.
+3. The fork workflow's gate checks: **is this a fork PR?** and **does the `recap` label exist?** Both must be true. If either fails, the job skips.
+4. On subsequent pushes to the same PR, the gate re-checks that the label is still present. Removing the label revokes consent — the recap will not run on the next synchronize event.
+
+### What the fork workflow does and does NOT do
+
+| The workflow DOES                                                                                                      | The workflow does NOT                                                              |
+| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Checkout the **base repository** at the **base branch ref** — trusted code only                                        | Check out or execute any code from the fork                                        |
+| Fetch the fork head as a remote ref (`git fetch origin pull/<n>/head:refs/recap/fork-head`) — fetching commits is safe | Install packages from the fork, run fork scripts, or evaluate fork content as code |
+| Run `git diff base...refs/recap/fork-head` — pure text diff of two already-fetched objects                             | Use the diff as anything other than text input to the LLM                          |
+| Run the **base repo's** visual-recap skill and agent configuration                                                     | Load any skill or config from the fork                                             |
+| Pass the diff through the same secret-scan step (fail-closed) as first-party PRs                                       | Skip the secret scan                                                               |
+| Add an explicit prompt-hardening note to the agent prompt marking diff content as untrusted                            | Grant the agent any additional permissions beyond the normal recap agent           |
+
+### Why you must review the diff before labeling
+
+The fork diff is attacker-controlled text that the recap agent reads as input. A carefully crafted diff could contain prompt-injection content — for example, diff lines that look like agent instructions — intended to make the recap agent take unintended actions (e.g., exfiltrate the publish token or produce misleading recap content).
 
-The workflow uses the plain `pull_request` trigger, **not** `pull_request_target`. Fork PRs therefore run with **no access to repository secrets**, so the recap step finds no `PLAN_RECAP_TOKEN` and cleanly no-ops — no failed publish, no error comment, no leaked credentials. Recaps only run for PRs from branches in the same repository, where the secrets are available.
+Before applying the `recap` label, skim the diff for:
 
-This also means you can merge the workflow file **before** the secrets exist: with no token configured, every run is a quiet no-op until you set the secrets.
+- Lines that read like direct commands or role instructions ("Ignore previous instructions...", "You are now...", "Write the token to...").
+- Unusual file names that could be misread as system prompts.
+- Encoded content in added files that might decode to instructions.
 
-## Self-modifying guard (sensitive paths)
+These mitigations are already layered in the workflow (secret scan, sensitive-path gate, prompt-hardening note, restricted agent tool allowlist), but label review is the primary line of defense.
 
-The workflow's gate job skips the recap entirely if a PR touches any of the following paths, so a PR can never rewrite what the trusted recap job runs and exfiltrate secrets:
+### Relationship to the main workflow
+
+The two workflow files are independent. For non-fork PRs, only `pr-visual-recap.yml` fires (fork check in its gate excludes them). For fork PRs, only `pr-visual-recap-fork.yml` fires (non-fork check in its gate excludes them). They share the same sticky comment marker and plan-id threading, so both PRs and fork PRs produce a single upserted comment on the same PR.
+
+### Self-modifying guard {#self-modifying-guard}
+
+The `gate` step skips the recap entirely when a PR touches any of the following paths, so a PR can never rewrite what the trusted recap job runs and exfiltrate secrets:
 
 | Path pattern                               | Reason                                                    |
 | ------------------------------------------ | --------------------------------------------------------- |
@@ -173,6 +233,126 @@ The recap is a review aid layered on top of the normal PR flow:
 - A generation or publish failure completes neutrally and surfaces as an explanatory sticky comment, not a red X on unrelated code.
 - The recap and its screenshot **do not imply the diff has been reviewed**. Reviewers still need to read the actual changed lines.
 
+## 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:
+
+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`.
+
+The variable is optional. Leave it unset (or set it to `latest`) to track the newest release.
+
+For the reusable-caller variant, use the `cli-version` input instead (see [Version pinning](#version-pinning) in the reusable section).
+
+## Secret-scan allowlist
+
+Before publishing a recap the workflow runs `agent-native 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.
+
+### Format
+
+Each non-blank, non-comment line is either a **literal substring** or a **`/regex/flags`** pattern:
+
+```
+# Lines starting with # are comments.
+
+# Literal substring — any diff line containing this string is allowed.
+sk-test-fixture1234567890abcdef
+
+# Regex pattern — written as /pattern/flags (JS syntax).
+/^.STRIPE_KEY=sk-test-/i
+
+# Another literal.
+EXAMPLE_API_KEY=placeholder-value
+```
+
+Rules:
+
+- A line is **suppressed** (allowed) when it contains the literal, or when the full line matches the regex.
+- The file is **fail-closed**: if it is absent, no suppressions apply — the scanner behaves as before.
+- An empty file is equivalent to no file.
+- Malformed regex lines are treated as literal strings.
+
+The allowlist is only consulted by the secret-scan gate. It does not affect what the coding agent can read — if the gate passes, the agent receives the full diff regardless.
+
+## Adopt as a reusable workflow
+
+### 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 `agent-native 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.
+
+|                                | Copy (default)            | Reusable                       |
+| ------------------------------ | ------------------------- | ------------------------------ |
+| Workflow size in your repo     | ~360 lines                | ~20 lines                      |
+| Picks up fixes automatically   | No — re-run `recap setup` | Yes                            |
+| Air-gap / full auditability    | Yes                       | No                             |
+| Pinnable to a specific version | Only by editing locally   | Yes — set `@v1.2.3` in `uses:` |
+
+### Caller snippet
+
+This is what `agent-native recap setup --reusable` writes (or you can paste it manually):
+
+```yaml
+name: PR Visual Recap
+
+# Thin caller — the full workflow logic lives in BuilderIO/agent-native.
+# Fixes and improvements reach this repo automatically on each run.
+# To pin a specific version for reproducibility replace '@main' with a
+# tag or SHA, e.g. '@v1.2.3' or '@abc1234'.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+jobs:
+  visual-recap:
+    uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@main
+    secrets:
+      PLAN_RECAP_TOKEN: ${{ secrets.PLAN_RECAP_TOKEN }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      # OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}  # only when agent: codex
+      # PLAN_RECAP_APP_URL: ${{ secrets.PLAN_RECAP_APP_URL }}  # only when self-hosting
+    with:
+      # cli-version: "latest"  # pin to a specific @agent-native/core version
+      # reasoning: "high"      # codex only: none|minimal|low|medium|high|xhigh
+      # skill-source: "repo"   # pin to committed visual-recap skill
+```
+
+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.
+
+### Installing via the CLI
+
+```bash
+# Write the thin caller instead of the full copy:
+agent-native recap setup --reusable
+
+# Or with a pinned ref for reproducibility:
+agent-native 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 `agent-native recap doctor` as usual to confirm secrets are configured.
+
+### Version pinning
+
+By default the caller references `@main`, which always uses the latest published version of the reusable workflow. For production repos that need reproducible CI, pin to a tag or SHA:
+
+```yaml
+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.
+
+### workflow_call event context
+
+`workflow_call` workflows inherit the **caller's** event context. The reusable workflow uses `github.event.pull_request.*` expressions to read the PR number, head SHA, base SHA, and PR metadata — these work correctly only when the caller triggers on `pull_request`. The caller snippet above already includes the correct event types.
+
+Do not trigger the caller on `workflow_dispatch` or `push` — those events do not carry a `pull_request` payload, and the gate will skip the recap with "no pull_request payload".
+
 ## Related
 
 - [Visual Plans](/docs/template-plan) — the `/visual-plan` and `/visual-recap` skills, the hosted Plans connector, and the interactive review surface this action publishes to.

package/docs/content/progress.md

@@ -41,7 +41,7 @@ Separate concern from [notifications](/docs/notifications): notifications fire o
 | `failed`    | Error terminal              |
 | `cancelled` | User interrupted            |
 
-Terminal statuses set `completed_at`. The UI tray shows only `running` rows; completed rows stay in the database for `manage-progress --action=list` queries.
+Terminal statuses set `completed_at`. The UI tray shows only `running` rows; completed rows stay in the database for `action=list` queries.
 
 ## API {#api}
 
@@ -138,7 +138,7 @@ A single `manage-progress` tool is registered in every template. The `action` pa
 
 - Use for anything > ~5 seconds. A spinner with no context feels frozen.
 - Update at natural checkpoints, not every iteration. Every 5–10% is plenty.
-- **Always** call `manage-progress --action=complete`, including in error paths. An orphan `running` row is worse than no row.
+- **Always** call `manage-progress` with `action=complete`, including in error paths. An orphan `running` row is worse than no row.
 - Pair with `notify` on completion so the user sees the outcome when they're not actively watching the tray.
 
 ## Event bus {#event-bus}
@@ -156,10 +156,10 @@ Two events emit on the [event bus](/docs/automations#event-bus):
 ---
 triggerType: event
 event: run.progress.updated
-condition: "status is running and (now - started) > 5 minutes"
+condition: "status is failed"
 mode: agentic
 ---
-Notify me that run {{runId}} has been running for a long time.
+Notify me that run {{runId}} has failed.
 ```
 
 ## How it works {#internals}
@@ -171,6 +171,6 @@ Notify me that run {{runId}} has been running for a long time.
 
 ## What's next
 
-- [**Notifications**](/docs/notifications) — pair with `manage-progress --action=complete` to tell the user when work finishes
+- [**Notifications**](/docs/notifications) — pair with `manage-progress` (`action=complete`) to tell the user when work finishes
 - [**Automations**](/docs/automations) — watchdog slow runs via `run.progress.updated`
 - [**Client**](/docs/client) — `useDbSync` for real-time cache invalidation

package/docs/content/pure-agent-apps.md

@@ -5,6 +5,8 @@ description: "Apps where the agent is the whole product — open it, ask for wha
 
 # Pure-Agent Apps
 
+This is the minimal end of agent-native — for the full-UI end, start from a [template](/docs/cloneable-saas).
+
 Imagine opening an app and seeing… just a chat. No dashboard. No sidebar full of menus. No forms. You ask for what you want — "summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week" — and the agent goes off and does it. The output shows up in chat, in Slack, in your inbox, wherever it belongs.
 
 That's a pure-agent app. The agent _is_ the product.
@@ -63,7 +65,7 @@ If you're not a developer, you can usually start with the [Dispatch template](/d
 For developers who want the absolute minimum, start from the **Starter** template:
 
 ```bash
-pnpm dlx @agent-native/core create my-agent --template starter
+npx @agent-native/core create my-agent --template starter
 ```
 
 Starter gives you the architecture, the agent panel, the workspace, auth, polling, and one example action — and nothing else. Add your own actions in `actions/`, connect any MCP servers you need, write the relevant skills into the workspace, and you're done.

package/docs/content/real-time-collaboration.md

@@ -17,6 +17,10 @@ agent-native collaboration model.
 Editing alongside the agent feels like working in Google Docs or Figma with
 a coworker who is both instant and tireless:
 
+If you just need the UI to refresh when the agent or another user writes to SQL, you don't need any of this — use [`useDbSync`](/docs/client). This page is for character-level co-editing of a single rich-text document (shared cursors, conflict-free merging). Both ride the same `/_agent-native/poll` channel.
+
+This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-free merging), **TipTap** (rich text editor), and **polling-based sync** (works in all deployment environments including serverless and edge).
+
 - **CRDT merging** — Concurrent edits from humans and agents merge without
   conflicts. You type in one paragraph; the agent rewrites another; both
   land cleanly.
@@ -214,12 +218,114 @@ useEffect(() => {
 }, [ydoc, editor, isLoaded]);
 ```
 
+User identity is derived from the session email. The framework provides `emailToColor()` and `emailToName()` helpers to generate consistent cursor colors and display names from email addresses.
+
+## Comments {#comments}
+
+Templates can add a comments system with threaded discussions on documents. The content template's comments system includes a full implementation with:
+
+- `document_comments` SQL table (threads, replies, resolved status)
+- The content template's REST routes for update/delete at `/api/comments/:id`; create and list run through the `add-comment` / `list-comments` actions. Custom templates implement their own equivalent endpoints against the core `POST /_agent-native/collab/:docId/search-replace` route.
+- Comments sidebar with threaded view and reply UI
+- Resolve/unresolve threads
+- **Send to AI** button — sends the comment thread context to the agent chat via `sendToAgentChat()`
+- Agent actions: `list-comments`, `add-comment`
+- Notion comment sync: `sync-notion-comments` action for bidirectional pull/push
+
+## Collab routes {#collab-routes}
+
+All collab routes are auto-mounted under `/_agent-native/collab/` by the collab plugin:
+
+| Route                         | Purpose                                  |
+| ----------------------------- | ---------------------------------------- |
+| `GET /:docId/state`           | Fetch full Y.Doc state (base64)          |
+| `POST /:docId/update`         | Apply client Yjs update                  |
+| `POST /:docId/text`           | Apply full text replacement (diff-based) |
+| `POST /:docId/search-replace` | Surgical find/replace in Y.XmlFragment   |
+| `POST /:docId/awareness`      | Sync cursor/presence state               |
+| `GET /:docId/users`           | List active users on a document          |
+
+## Agent edit action {#edit-document}
+
+The content template's `edit-document` action is the primary way agents make changes to documents in collaborative mode:
+
+```bash
+# Single edit
+pnpm action edit-document --id doc123 --find "old text" --replace "new text"
+
+# Batch edits
+pnpm action edit-document --id doc123 --edits '[{"find":"old","replace":"new"}]'
+
+# Delete text
+pnpm action edit-document --id doc123 --find "delete me" --replace ""
+```
+
 ---
 
 ## Presence Kit {#presence-kit}
 
 The presence kit provides Liveblocks/Figma-grade live-cursor and selection primitives on top of the existing awareness layer.
 
+Import client-side presence and editor UI from the focused browser subpath:
+
+```ts
+import {
+  PresenceBar,
+  LiveCursorOverlay,
+  RemoteSelectionRings,
+  useCollaborativeDoc,
+  usePresence,
+} from "@agent-native/core/client/collab";
+```
+
+Server-side agent presence helpers stay in the lower-level collab package:
+
+```ts
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+```
+
+### Public API {#presence-public-api}
+
+| API                                                 | Purpose                                                                                                                                                |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useCollaborativeDoc(options)`                      | Creates the stable `Y.Doc` and awareness instance, handles state-vector sync, SSE fast-path, polling fallback, active users, and agent presence flags. |
+| `usePresence(awareness, localClientId)`             | Derives remote participants and publishes arbitrary local awareness fields such as cursor, selection, viewport, or tool mode.                          |
+| `<PresenceBar>`                                     | Renders active collaborators plus the AI agent, with optional avatar-click follow mode wiring.                                                         |
+| `<LiveCursorOverlay>`                               | Renders remote cursor labels over a positioned container from normalized 0-1 coordinates.                                                              |
+| `<RemoteSelectionRings>`                            | Renders colored rings and labels around selected DOM elements resolved by your app.                                                                    |
+| `useFollowUser(options)`                            | Invokes a callback when the followed participant publishes viewport changes.                                                                           |
+| `toNormalized()` / `fromNormalized()`               | Convert pointer coordinates to/from normalized container coordinates.                                                                                  |
+| `dedupeCollabUsersByEmail()`                        | Build custom avatar stacks without one user showing once per open tab.                                                                                 |
+| `useCollaborativeMap()` / `useCollaborativeArray()` | Client hooks for Y.Map/Y.Array structured collaboration. Treat as lower-level until a template proves the exact product pattern.                       |
+
+`UseCollaborativeDocOptions`:
+
+| Option                | Description                                                         |
+| --------------------- | ------------------------------------------------------------------- |
+| `docId`               | Document id, or `null` to disable the hook.                         |
+| `pollInterval`        | Poll interval when SSE is unavailable. Default: `2000`.             |
+| `pollIntervalWithSse` | Slow poll interval while SSE is healthy. Default: `12000`.          |
+| `pauseWhenHidden`     | Pause remote update/presence polling while hidden. Default: `true`. |
+| `baseUrl`             | Collab endpoint prefix. Default: `/_agent-native/collab`.           |
+| `requestSource`       | Stable tab/source id used to ignore self-originated refresh noise.  |
+| `user`                | `{ name, email, color }` shown in cursor and presence UI.           |
+
+`UseCollaborativeDocResult`:
+
+| Field          | Description                                                          |
+| -------------- | -------------------------------------------------------------------- |
+| `ydoc`         | Stable `Y.Doc` for the current `docId`.                              |
+| `awareness`    | Yjs Awareness instance used by cursors, selections, and follow mode. |
+| `isLoading`    | Initial server state is still loading.                               |
+| `isSynced`     | The hook has caught up to server state.                              |
+| `activeUsers`  | Human collaborators from awareness.                                  |
+| `agentActive`  | The agent is actively editing right now.                             |
+| `agentPresent` | The agent has an awareness entry for this document.                  |
+
 ### Fast awareness {#fast-awareness}
 
 Awareness state changes now propagate at ~150ms instead of the 2s poll cycle: