@agent-native/core 0.121.2 → 0.122.0

package/corpus/templates/analytics/.agents/skills/dashboard-management/references/template-catalog-and-demo.md

@@ -0,0 +1,62 @@
+# Template Catalog And Demo Dashboards
+
+## Listing And Installing Templates
+
+- `list-dashboard-templates` lists source-controlled dashboard templates with
+  `id`, category, data sources, panel count, and installed dashboard IDs.
+- `install-dashboard-template` installs a catalog template into normal
+  SQL-backed dashboards. Required: `templateId`. Optional: `dashboardId`,
+  `name`, `overwrite`, `forceNew`, and `mergePanels` (see "Reliable Bulk
+  Edits" in the main skill for the `mergePanels` append behavior).
+
+## Canonical Agent Native Dashboard
+
+Keep the canonical Agent Native dashboard (`agent-native-templates-first-party`)
+focused: it includes one explicit feedback-sentiment-by-model chart and one
+optional inferred-message-sentiment chart, not the broader LLM cost, token,
+latency, or error suite.
+
+- Explicit feedback uses content-free `$ai_feedback` events with `sentiment`
+  (`positive` or `negative`) and model in `$ai_model` or `model`.
+- Inferred sentiment uses `$ai_sentiment` events with `method = 'llm'` and
+  `sentiment` (`positive`, `neutral`, or `negative`).
+
+Keep these panels in the canonical dashboard and do not recreate a separately
+installable observability template.
+
+## Node Exporter Templates
+
+Node Exporter ships as `node-exporter-macos` (Darwin/Homebrew `node_exporter`
+scrapes) and `node-exporter-full` (the Linux-focused Grafana 1860 revision 45
+dashboard converted into native Analytics panels, plus Prometheus
+Observability Demo app metrics — `demo_http_*`, `demo_chaos_mode`, synthetic
+CPU/disk/memory workload metrics). See the `prometheus` skill for the full
+panel/field breakdown and local Homebrew setup.
+
+Keep the first-open `App / Overview` tab light: it should show the Request
+Latency highlight plus current app state, while Traffic, Latency, and
+Workload details stay split across their own `App / *` tabs.
+
+## Demo Dashboard
+
+- `ensure-demo-dashboards` installs one private per-user demo on first app
+  open: `demo-node-exporter`. The Analytics root route calls this before
+  honoring local last-opened state; when the action creates the demo, the
+  user should land directly on the Node Exporter demo's `App / Overview` tab
+  without visiting the template catalog or data-source setup.
+- The demo dashboard is generated from the same `node-exporter-full` seed as
+  the catalog template. Its Prometheus panels keep the same PromQL
+  descriptors and use `source: "demo"` so queries route to the demo
+  Prometheus endpoint instead of the user's `PROMETHEUS_*` credential slot.
+- The demo Prometheus endpoint defaults to the public read-only
+  `https://prometheus.agent-native.foo`, so cloud and local MPX installs work
+  without user setup. Deployments can override it with
+  `ANALYTICS_DEMO_PROMETHEUS_URL` and optional
+  `ANALYTICS_DEMO_PROMETHEUS_USERNAME`, `ANALYTICS_DEMO_PROMETHEUS_PASSWORD`,
+  or `ANALYTICS_DEMO_PROMETHEUS_BEARER_TOKEN`. Do not put credential values
+  in source, docs, fixtures, tests, prompts, or dashboard seeds.
+- Demo dashboards are ordinary SQL dashboard rows, so rename, share, archive,
+  and delete flows apply. Deleted demo IDs are tombstoned in SQL settings and
+  are not recreated unless the user explicitly asks to reset demos.
+- Use `ensure-demo-dashboards --reset=true` only when the user asks to
+  restore a deleted or changed demo dashboard.

package/corpus/templates/analytics/.agents/skills/dashboard-ops/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: dashboard-ops
+description: >-
+  Deployment and runtime internals for dashboard email reports and analytics
+  alert rules: Playwright/Chromium capture, serverless timing budgets, cron
+  wiring, and notification delivery env vars. Use when configuring, deploying,
+  or debugging report/alert delivery infrastructure — not when just creating a
+  report subscription or alert rule via the action surface.
+scope: dev
+---
+
+# Dashboard Reports & Alerts Ops
+
+Dashboard email reports (`dashboard-report-subscriptions` actions) and
+analytics alert rules (`analytics-alert-rules` actions) are SQL-backed action
+surfaces. This skill covers the deployment/runtime machinery behind them —
+the agent chatting with an end user does not need this; it only needs the
+action names and the user-facing constraints already in `AGENTS.md`.
+
+## Dashboard Email Report Capture
+
+- Report PNGs are Playwright captures of the real dashboard route in
+  `reportScreenshot=1` mode, authenticated by a short-lived embed-session
+  token, and embedded inline in the email as ordered CID images.
+- Complete dashboards are captured sequentially in four-panel windows matching
+  the browser's four-query concurrency limit. Every window must match the
+  panel ids snapshotted at the start; a failed or mismatched window
+  invalidates the entire image set so the scheduler retries instead of
+  sending a partial report.
+- Capture is capped at 10 windows and 14 MiB of raw PNG data. Subscriptions
+  are capped at five distinct recipients — recommend a mailing-list address
+  for larger audiences.
+- The serverless capture deadline reserves 90 seconds of the 300-second
+  worker budget for cleanup and delivery.
+- The ten-minute retry delay is an eligibility floor, not a guarantee; the
+  `*/15` sweep runs the retry on its first tick after that floor.
+- PNG rendering uses local Chrome in development and `playwright-core` plus
+  `@sparticuz/chromium-min` in serverless runtimes. Set
+  `DASHBOARD_REPORT_CHROMIUM_PACK_URL` only when overriding the default
+  Chromium pack location.
+
+## Cron Wiring
+
+- Netlify builds emit a scheduled trigger plus a background worker from
+  `scripts/emit-netlify-dashboard-report-cron.ts`, using a per-deploy internal
+  token and disabling the in-process interval scheduler on Netlify to avoid
+  duplicate sends.
+- External cron callers can sweep due reports by POSTing
+  `/api/dashboard-reports/run` with
+  `Authorization: Bearer $DASHBOARD_REPORTS_CRON_SECRET`.
+- The same `scripts/emit-netlify-dashboard-report-cron.ts` script also emits
+  the alert-rule cron trigger plus background worker, running every five
+  minutes on Netlify. Long-lived runtimes use the in-process scheduler unless
+  `ANALYTICS_ALERT_JOBS=0` is set.
+- External cron callers can run due alerts by POSTing
+  `/api/analytics-alerts/run` with
+  `Authorization: Bearer $ANALYTICS_ALERTS_CRON_SECRET`.
+
+## Alert Notification Delivery
+
+Alert notifications use the shared notification channel registry
+(`channels` can include `inbox`, `email`, `slack`, `webhook`, or any custom
+registered channel):
+
+- Slack/webhook delivery prefers per-rule `metadata.delivery.slackWebhookUrl`
+  / `metadata.delivery.webhookUrl` (uptime monitors store these on the
+  monitor row), then falls back to `NOTIFICATIONS_SLACK_WEBHOOK_URL` /
+  `NOTIFICATIONS_WEBHOOK_URL`. Optional `NOTIFICATIONS_SLACK_WEBHOOK_AUTH`
+  configures Slack auth.
+- Email delivery needs `RESEND_API_KEY` or `SENDGRID_API_KEY` plus
+  `EMAIL_FROM`. Per-rule `emailRecipients` fall back to
+  `NOTIFICATIONS_EMAIL_RECIPIENTS`. Saving explicit `emailRecipients` also
+  remembers them as the current user's defaults for the next alert rule
+  created in Settings.
+
+Users can also view and manage report subscriptions and alert rules in
+Settings; that UI uses the same action surface as the agent, so no separate
+implementation is needed there.
+
+## Related Skills
+
+- **dashboard-management** — the dashboard artifact model these features
+  attach to.
+- **integration-webhooks** (root) — the general queue-and-processor pattern
+  for outbound webhook delivery.

package/corpus/templates/analytics/.agents/skills/data-querying/SKILL.md

@@ -34,12 +34,37 @@ Convert the user's requested local date/timezone to UTC before querying. For
 example, May 1, 2026 in America/New_York is `2026-05-01T04:00:00Z`
 through `2026-05-02T04:00:00Z`.
 
-## Showing Charts In Chat
+## Inline Charts In Chat
 
-For an in-chat answer, **emit a live `/chart` embed** — never `generate-chart`. The embed mounts a live `SqlChart` that re-queries when its source changes, and it doesn't choke on rigid JSON params the way the PNG action does. Full shape in `AGENTS.md` ("Inline Charts in Chat" section). Reach for `generate-chart` only when you're building a dashboard artifact that needs a persisted report image.
+For an in-chat answer, **emit a live `/chart` embed** — never `generate-chart`. The embed mounts a live `SqlChart` that re-queries when its source changes, and it doesn't choke on rigid JSON params the way the PNG action does. Reach for `generate-chart` only when you're building a dashboard artifact that needs a persisted report image.
 
 If `generate-chart` returns an error in any chat-answering flow, the recovery is to switch to the live embed, not to retry with reformatted params.
 
+**How it renders.** The core chat markdown renderer turns any fenced block tagged `embed` into a sandboxed, same-origin iframe. Emit:
+
+````markdown
+```embed
+src: /chart?panel=<base64url-encoded panel JSON>
+title: Daily pageviews
+height: 320
+```
+````
+
+Fence keys: `src` (required, same-origin path), `title`, and either `height` (px) or `aspect` (`16/9`, `4/3`, `1/1`, `21/9`, `3/2`, `2/1`; default `16/9`). A cross-origin `src` renders an "Embed blocked" notice instead of a chart.
+
+**Panel JSON.** The `/chart` route decodes `panel` into a `SqlPanel` (`app/pages/adhoc/sql-dashboard/types.ts`):
+
+- `sql` — required, non-empty.
+- `source` — required, one of `bigquery`, `ga4`, `amplitude`, `first-party`, `demo`, `prometheus`. `program` is deliberately **not** embeddable.
+- `chartType` — required, one of `line`, `area`, `bar`, `metric`, `table`, `pie`. Dashboard-layout types (`section`, `heatmap`, `callout`, `extension`) are rejected.
+- `id` (defaults `"embed"`), `title` (rendered above the chart), `width` (dashboard-only, ignored here), `config` (passed through unvalidated — `xKey`/`yKeys`, `colors`, `yFormatter`, `columns`, `stacked`, `legend`, …).
+
+An unknown `source`/`chartType` or blank `sql` renders an error card, not a chart.
+
+**Encoding.** JSON-stringify the panel, base64-encode it, then make it URL-safe: `+` → `-`, `/` → `_`, strip `=` padding. No further URL-encoding is needed. Keep the SQL short — it rides in a query string; if it's long, save it as a dashboard panel and link to the dashboard instead.
+
+Full details (per-field validation, `config` keys, a verified round-trip example, and how this differs from `generate-chart`) are in `references/inline-chart-embeds.md` — read it with `docs-search --slug "skill-data-querying--references-inline-chart-embeds"`.
+
 ## Script Patterns
 
 ### Reusing Existing Actions

package/corpus/templates/analytics/.agents/skills/data-querying/references/inline-chart-embeds.md

@@ -0,0 +1,139 @@
+# Inline Chart Embeds (the live `/chart` embed)
+
+For an in-chat answer, emit a fenced ` ```embed ` block whose `src` points at
+the app's own `/chart` route with a base64url-encoded panel in the `panel`
+query param. The chat renderer mounts that route in a sandboxed same-origin
+iframe, which renders a live `SqlChart` that re-queries when its source
+changes. This is a different mechanism from `generate-chart` (a static
+PNG/SVG render) — see "How This Differs From `generate-chart`" below.
+
+## The Two Layers
+
+1. **The chat markdown embed fence** — this lives in core, not in the
+   template. Analytics chat renders through `AgentChatSurface` →
+   `MarkdownText` (`packages/core/src/client/chat/markdown-renderer.tsx`),
+   whose `markdownComponents.pre` handler intercepts any code block tagged
+   `language-embed` and renders `IframeEmbed`
+   (`packages/core/src/client/IframeEmbed.tsx`) instead of a `<pre>`.
+   `parseEmbedBody` there reads `key: value` lines:
+   - `src` (required) — the iframe URL.
+   - `title` (optional) — shown in the embed's "Preview" header bar and used
+     as the iframe `title`. Defaults to "Embedded content".
+   - `aspect` (optional) — one of `16/9`, `4/3`, `1/1`, `21/9`, `3/2`, `2/1`;
+     anything else falls back to `16/9`. Ignored when `height` is set.
+   - `height` (optional) — pixels; overrides `aspect`.
+
+   `isSameOriginSrc` only allows same-origin URLs: a path starting with `/`
+   (but not `//`), `./`, or `../`, or an absolute URL whose origin matches the
+   app's. Anything cross-origin renders an "Embed blocked" notice instead of
+   an iframe. The iframe itself is sandboxed
+   (`allow-scripts allow-same-origin allow-forms allow-popups`),
+   `referrerPolicy="same-origin"`, and lazy-loaded. An embedded page can call
+   `postNavigate()` from `@agent-native/core/client/embed` to pop the user out
+   into the parent window at the same path.
+
+   The template also ships its own `embed`-fence implementation in
+   `templates/analytics/app/components/Markdown.tsx`, but that one renders
+   **saved analysis bodies** (`app/pages/analyses/AnalysisDetail.tsx`), not
+   chat. It is stricter: relative `src` only (no absolute same-origin URL) and
+   `height` clamped to 2000. Keep embeds relative and they work in both.
+
+2. **The `/chart` route** — `templates/analytics/app/routes/chart.tsx`. It
+   reads the `panel` search param and decodes it with `decodePanel`
+   (`chart.tsx:31-73`), then renders `<SqlChart panel={result} />`
+   (`chart.tsx:115`), the same live chart component dashboards use
+   (`templates/analytics/app/components/dashboard/SqlChart.tsx:1111`).
+
+So the full pattern the agent must emit is:
+
+```embed
+src: /chart?panel=<base64url-encoded-panel-json>
+title: Daily pageviews
+height: 320
+```
+
+## The Panel JSON Shape (validated by `decodePanel`, `chart.tsx:31-73`)
+
+| Field       | Required | Type / allowed values                                                                     | Notes                                                                                                                                                                                                             |
+| ----------- | -------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sql`       | yes      | non-empty string                                                                          | The query to run.                                                                                                                                                                                                 |
+| `source`    | yes      | `"bigquery"` \| `"ga4"` \| `"amplitude"` \| `"first-party"` \| `"demo"` \| `"prometheus"` | `chart.tsx:22-29`. This is every `DataSourceType` (`app/pages/adhoc/sql-dashboard/types.ts:1-8`) **except `"program"`** — data-program-backed sources cannot be embedded this way.                                |
+| `chartType` | yes      | `"line"` \| `"area"` \| `"bar"` \| `"metric"` \| `"table"` \| `"pie"`                     | `chart.tsx:12-19`. This is every `ChartType` (`types.ts:10-20`) **except `"section"`, `"heatmap"`, `"callout"`, `"extension"`** — those are dashboard-layout-only types and are not valid for a standalone embed. |
+| `id`        | no       | string                                                                                    | Defaults to `"embed"`.                                                                                                                                                                                            |
+| `title`     | no       | string                                                                                    | Defaults to `""`. Shown above the chart in `ChartRoute` (`chart.tsx:109-113`) — separate from the outer `embed` fence's own `title:` line, which only sets the iframe's `title` attribute.                        |
+| `width`     | no       | number ≥ 1, floored                                                                       | Defaults to `1`. Legacy dashboard row-layout field; has no effect on the standalone `/chart` page.                                                                                                                |
+| `config`    | no       | `SqlPanelConfig` object (`types.ts`)                                                      | Passed through as-is — `decodePanel` only checks `typeof === "object"`, it does not validate individual keys.                                                                                                     |
+
+Any other `source`/`chartType` value, or a missing/blank `sql`, makes
+`decodePanel` return an error and the route renders `ChartError`
+(`chart.tsx:75-92`) instead of a chart.
+
+### Useful `config` keys (from `SqlPanelConfig`, `types.ts`)
+
+- `xKey`, `yKey` / `yKeys` — column names for the x-axis and series. If
+  omitted, `SqlChart`'s `detectKeys` (`SqlChart.tsx:1013-1060`) auto-picks a
+  date/string-like column for `xKey` and all remaining numeric columns for
+  `yKeys`, so these are usually only needed to override the guess. Prefer
+  writing SQL that already returns unambiguous column names over relying on
+  auto-detection.
+- `colors` / `color` — series colors.
+- `yFormatter` — `"number"` | `"currency"` | `"percent"`.
+- `columns` — `table` chartType only: `{ key, label?, format?, linkKey?, hidden? }[]`.
+- `stacked`, `legend`, `pivot`, `limit`, `valueLabels`, `description` — see
+  `SqlPanelConfig` in `types.ts` for the full list.
+
+## Encoding The `panel` Param
+
+`decodePanel` un-does a URL-safe, unpadded base64 encoding
+(`chart.tsx:33-35`): it replaces `-` back to `+` and `_` back to `/`, then
+pads with `=` before `atob`-decoding and `JSON.parse`-ing. To encode, do the
+reverse — base64-encode the JSON, then replace `+` with `-`, `/` with `_`,
+and strip any trailing `=` padding.
+
+Worked example (verified round-trip):
+
+Panel JSON:
+
+```json
+{
+  "title": "Daily pageviews",
+  "sql": "SELECT date_trunc('day', timestamp) AS day, COUNT(*) AS pageviews FROM analytics_events WHERE event_name = 'pageview' GROUP BY 1 ORDER BY 1",
+  "source": "first-party",
+  "chartType": "line"
+}
+```
+
+Resulting embed:
+
+```embed
+src: /chart?panel=eyJ0aXRsZSI6IkRhaWx5IHBhZ2V2aWV3cyIsInNxbCI6IlNFTEVDVCBkYXRlX3RydW5jKCdkYXknLCB0aW1lc3RhbXApIEFTIGRheSwgQ09VTlQoKikgQVMgcGFnZXZpZXdzIEZST00gYW5hbHl0aWNzX2V2ZW50cyBXSEVSRSBldmVudF9uYW1lID0gJ3BhZ2V2aWV3JyBHUk9VUCBCWSAxIE9SREVSIEJZIDEiLCJzb3VyY2UiOiJmaXJzdC1wYXJ0eSIsImNoYXJ0VHlwZSI6ImxpbmUifQ
+title: Daily pageviews
+height: 320
+```
+
+Since it's a plain query-string param, keep the SQL reasonably short — it
+rides in a URL that also has to survive markdown fencing and the iframe's
+`src` attribute. It does not need extra URL-encoding beyond the base64url
+step above (base64url output contains only `A-Za-z0-9-_`, which is
+URL-safe).
+
+## How This Differs From `generate-chart`
+
+`generate-chart` (`templates/analytics/actions/generate-chart.ts`) renders a
+**static** PNG (or SVG fallback) file to the media directory:
+
+- Params are separate top-level fields (`title`, `labels`, `data`, `type`,
+  `subtitle`, `width`, `height`, `theme`, `color`), where `labels` and `data`
+  are **pre-stringified JSON arrays** the caller must have already computed —
+  there is no `sql`/`source` and no live query.
+- Only three chart types: `bar`, `line`, `area` (no `pie`, `metric`, `table`).
+- The output is a saved image file, not a live component — it never
+  re-queries if the underlying data changes.
+- It exists for `save-analysis` artifacts and other places that need a
+  persisted image (exports, archived reports), not for in-chat answers.
+
+The `/chart` embed instead re-runs `sql` against `source` live through
+`SqlChart`/`useSqlQuery`, so it always reflects current data and supports the
+full `pie`/`metric`/`table` chart types dashboards use. Prefer it for every
+in-chat data answer; reach for `generate-chart` only when building a
+save-analysis artifact that needs a static image.

package/corpus/templates/analytics/.agents/skills/monitoring/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: monitoring
+description: >-
+  Implementation map for the Monitoring tab (uptime checks, public status
+  pages, error triage): component/server file locations, schema, jobs, and
+  scheduler wiring. Use when building or debugging Monitoring UI, uptime
+  checks, status pages, or error capture/grouping — not when just calling the
+  monitoring actions from chat.
+scope: dev
+---
+
+# Monitoring Implementation Map
+
+`/monitoring` is a thin shell (`app/routes/monitoring._index.tsx` →
+`app/pages/monitoring/MonitoringPage.tsx`) hosting two independently-owned
+panels selected by `?view=uptime|errors` (defaults to uptime). `navigation`
+mirrors it as `view="monitoring"` with `monitoringView` (plus
+`monitorId`/`errorIssueId` when a row is open); each panel also writes richer
+selection to the `monitoring` application-state key.
+
+## Uptime
+
+- UI: `app/pages/monitoring/UptimePanel.tsx`, `app/pages/monitoring/uptime/**`.
+- Server: `server/lib/uptime-monitors.ts` (checks/alerting), sweep job
+  `server/jobs/uptime-monitors.ts`, scheduler
+  `server/plugins/uptime-monitor-jobs.ts`, schema
+  `server/db/schema-monitoring.ts`.
+- Actions: `list-monitors`, `get-monitor`, `save-monitor`, `run-monitor-check`,
+  `delete-monitor`.
+- Production serverless/Netlify-style runtimes skip the in-process interval
+  scheduler and rely on the generated scheduled/background worker or external
+  cron instead.
+- Deep links: list `?view=uptime`, detail `?view=uptime&monitor=<id>`, create
+  `?view=uptime&monitor=new`, edit `?view=uptime&monitor=<id>&edit=1`.
+- See `docs/uptime-monitoring.md`.
+
+## Status Pages
+
+- UI: `app/pages/monitoring/uptime/status-pages/**`, a config sub-view under
+  Uptime that bundles chosen monitors under a public `/status/<slug>` page.
+- Server: owner-scoped CRUD and the sanitized public projection live in
+  `server/lib/status-pages.ts` over `server/db/schema-monitoring.ts`.
+- Actions: `list-status-pages`, `get-status-page`, `save-status-page`,
+  `delete-status-page`, `add-status-page-monitor`,
+  `remove-status-page-monitor`, `reorder-status-page-monitors`, plus the
+  unauthenticated `get-public-status-page`.
+- Deep links: index `?view=uptime&statuspage=list`, create
+  `?view=uptime&statuspage=new`, edit `?view=uptime&statuspage=<id>`.
+
+## Errors
+
+- UI: `app/pages/monitoring/ErrorsPanel.tsx`, `app/pages/monitoring/errors/**`
+  — Sentry-style exception triage grouped into issues by fingerprint.
+- Server: ingest/grouping in `server/lib/error-capture.ts` over
+  `server/db/schema-errors.ts`.
+- Actions: `list-error-issues`, `get-error-issue`, `resolve-error-issue`,
+  `capture-test-error`, `match-error-issues`.
+- Browser capture uses the SDK from `@agent-native/core/client`
+  (`captureException` / `captureMessage` / `addErrorBreadcrumb`),
+  auto-enabled by `configureTracking` and transported through the first-party
+  analytics ingest as a `$exception` event.
+- Deep link: `?view=errors&issue=<id>`. Issue detail includes recent
+  frequency, parsed/raw stack traces, source code snippets when available,
+  breadcrumbs, tags, occurrence history, and session replay links.
+- See `docs/error-capture.md`.
+
+## Session Replay ↔ Errors
+
+A recording's devtools Console error lines link to the grouped issue at
+`/monitoring?view=errors&issue=<id>`, resolved by `match-error-issues` (exact
+fingerprint match, no heuristics); issues link back to the originating
+recording at `/sessions/<recordingId>`.
+
+## Related Skills
+
+- **session-replay** — replay storage, capture, and the Dev Tools panel this
+  feature links to.

package/corpus/templates/analytics/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run