@agent-native/core 0.69.0 → 0.70.1

package/dist/templates/workspace-core/.agents/skills/changelog/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: changelog
+description: >-
+  How to keep each app's user-facing changelog. Use when you ship a change a
+  user would notice (a new feature, a visible improvement, a bug fix), when
+  wiring the in-app "What's new" surface into a template, or when releasing
+  pending changelog entries.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Changelog — user-facing "What's new"
+
+Every template app keeps a `CHANGELOG.md` of **user-facing** changes that
+renders in-app via the command menu (Cmd+K → "What's new") and on the settings
+page. The flow mirrors changesets so it survives many agents working in
+parallel: each change drops a small **pending entry file**, and a later
+**release** rolls all pending files into a dated `CHANGELOG.md` section.
+
+## When to add an entry
+
+Add an entry whenever you ship something a user of that app would notice:
+
+- a new capability or surface,
+- a visible improvement (speed, layout, copy, defaults),
+- a bug fix that affects behavior they'd see.
+
+Do **not** add entries for refactors, internal tooling, tests, dependency
+bumps, or anything invisible to the end user. The changelog is product notes,
+not a commit log — write it the way you'd describe the change to a customer.
+
+## How to add an entry
+
+From the app directory (the template you changed):
+
+```bash
+agent-native changelog add "Recordings can be trimmed before sharing" --type added
+agent-native changelog add "Faster transcript search" --type improved
+agent-native changelog add "Fixed a crash when opening an empty folder" --type fixed
+```
+
+`--type` is one of `added`, `improved`, `fixed`, `changed`, `removed`,
+`security` (aliases like `feature`, `bugfix`, `enhancement` are accepted). This
+writes `changelog/<date>-<slug>.md` — one file per change, so parallel work
+never conflicts. You can also hand-write that file; the frontmatter is just:
+
+```md
+---
+type: added
+date: 2026-06-23
+---
+Recordings can be trimmed before sharing.
+```
+
+## Writing good entries
+
+- One user-facing sentence, present tense, no internal jargon or file names.
+- Lead with the benefit ("Recordings can be trimmed…"), not the mechanism.
+- Markdown is allowed (bold, links) but keep it short — it renders as a bullet.
+
+## Releasing
+
+`release` stamps every pending entry into `CHANGELOG.md` under a dated
+`## <date>` section (grouped by type) and deletes the pending files:
+
+```bash
+agent-native changelog release            # uses today's date
+agent-native changelog list               # preview pending + released
+```
+
+Releasing is usually done at deploy/merge time. The in-app surface reads
+`CHANGELOG.md`, so only released entries are visible to users — pending entries
+stay invisible until rolled up.
+
+## Wiring the in-app surface (once per template)
+
+Templates already get the rendering for free from `@agent-native/core`. To
+expose it in an app:
+
+1. **Command menu** — pass the app's own changelog to `CommandMenu`:
+
+   ```tsx
+   import changelog from "../CHANGELOG.md?raw";
+   // ...
+   <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen} changelog={changelog}>
+     {/* existing groups */}
+   </CommandMenu>
+   ```
+
+   This adds a "What's new" entry with an unseen-release dot and an in-app
+   dialog — no other wiring needed.
+
+2. **Settings** (optional) — drop the card on the settings page:
+
+   ```tsx
+   import { ChangelogSettingsCard } from "@agent-native/core/client";
+   import changelog from "../CHANGELOG.md?raw";
+   // ...
+   <ChangelogSettingsCard markdown={changelog} />
+   ```
+
+`CHANGELOG.md?raw` is inlined by Vite at build time, so this works on every
+host with no server route or runtime file access.
+
+## Checklist
+
+- [ ] Shipped a user-visible change? Run `agent-native changelog add "…"`.
+- [ ] New template UI? Pass `changelog` to its `CommandMenu` and seed a
+      `CHANGELOG.md`.
+- [ ] Releasing/deploying? `agent-native changelog release` rolls pending → dated.

package/dist/templates/workspace-core/.agents/skills/reliable-mutations/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: reliable-mutations
+description: >-
+  How the agent must perform writes so they actually persist under the hosted
+  ~40s run budget. Use whenever you create, update, delete, or batch-write app
+  data — especially "do this for many items" loops, or any task where the user
+  expects N things to end up saved.
+---
+
+# Reliable Mutations
+
+## Rule
+
+Make a change in **one atomic call** when the action supports it, then **verify
+the persisted end state and report concrete proof** (counts/ids). Never drive a
+multi-step change by looping many small writes, and never report success from a
+tool ✓ alone.
+
+## Why
+
+Hosted agent runs have a ~40s soft budget (it exists to hand off cleanly under
+the upstream gateway/function walls — it is correct and is not raisable; see the
+durable-agent-runs design doc). When you loop many sequential writes inside one
+turn, the budget can cut you off mid-loop. The run resumes in a new chunk, but
+the resume often re-does earlier steps instead of advancing, so the loop churns
+and the *saved* result ends up partial — or empty — even though each individual
+tool call appeared to succeed. The user gets told "done" while the data says
+otherwise. One atomic call commits or fails as a unit; verification turns a
+hopeful ✓ into a fact.
+
+## How
+
+1. **Prefer a single atomic call.** If an action accepts the whole set (add
+   many, set all, bulk update), pass the full batch in one call so it commits
+   atomically. Check the action surface for a batch/plural form before reaching
+   for a loop.
+2. **Do not loop many small writes under the run budget.** A sequence of N
+   per-item writes in one turn will race the ~40s cutoff and can leave partial
+   or no state. If no batch action exists, that is a gap in the action layer —
+   add or extend an action that accepts the batch (see the `actions` skill)
+   rather than papering over it with a loop.
+3. **Verify the end state after writing.** Re-read the data (a list/read action,
+   a count query) and confirm the result matches intent — the right number of
+   rows, the expected ids/fields. Do this before you tell the user it worked.
+4. **Report proof-of-done, not vibes.** State concrete evidence: "saved 12 of 12
+   panels (ids …)" or "updated 5 rows". Do not infer success from the presence
+   of a tool ✓ on an individual call.
+5. **On a time-budget cutoff, fail loud.** If the turn is cut before the change
+   is fully committed and verified, say so explicitly and report what *did*
+   persist (M of N) and what remains. Never round a partial or unverified write
+   up to "done".
+
+## Don't
+
+- Don't loop `for each item: write(item)` for a large set in a single hosted
+  turn.
+- Don't claim completion because every tool call returned ✓ — a ✓ on an aborted
+  chunk does not mean the row was committed.
+- Don't silently shrink the scope ("I added a few of them") and present it as the
+  finished task.
+- Don't try to "fix" this by asking for a longer run timeout — the budget is
+  correct; restructure the write instead.
+
+## Related
+
+- `actions` — define or extend a batch/atomic action when only per-item writes
+  exist.
+- `storing-data` — where app data lives and how reads/writes are scoped.
+- `performance` — avoid query waterfalls when verifying end state.
+- Design doc: `packages/core/docs/design/durable-agent-runs.md` — the real
+  ceiling fix (checkpointed and durable runs); this skill is the agent-facing
+  mitigation that reduces how often the ceiling is hit.

package/dist/templates/workspace-core/.agents/skills/tracking/SKILL.md

@@ -31,7 +31,11 @@ Fire an analytics event.
 ```ts
 import { track } from "@agent-native/core/tracking";
 
-track("meal.logged", { mealName: "Salad", calories: 350 }, { userId: "user@example.com" });
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "user@example.com" },
+);
 ```
 
 ### `identify(userId, traits?)`
@@ -73,13 +77,13 @@ Flush all providers (call before process exit).
 
 Set the env var and the provider auto-registers at startup. No SDK dependencies -- all providers use raw HTTP.
 
-| Provider   | Env vars                                                  |
-| ---------- | --------------------------------------------------------- |
-| PostHog    | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`) |
-| Mixpanel   | `MIXPANEL_TOKEN`                                          |
-| Amplitude  | `AMPLITUDE_API_KEY`                                       |
+| Provider               | Env vars                                                                                                                                           |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PostHog                | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`)                                                    |
+| Mixpanel               | `MIXPANEL_TOKEN`                                                                                                                                   |
+| Amplitude              | `AMPLITUDE_API_KEY`                                                                                                                                |
 | Agent Native Analytics | `AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` (server), `AGENT_NATIVE_ANALYTICS_ENDPOINT` (optional, defaults to `https://analytics.agent-native.com/track`) |
-| Webhook    | `TRACKING_WEBHOOK_URL` (required), `TRACKING_WEBHOOK_AUTH` (optional, sent as `Authorization` header) |
+| Webhook                | `TRACKING_WEBHOOK_URL` (required), `TRACKING_WEBHOOK_AUTH` (optional, sent as `Authorization` header)                                              |
 
 Multiple providers can be active simultaneously. All receive every event.
 
@@ -106,10 +110,35 @@ Every browser-side `trackEvent()` POST to the Agent Native Analytics `/track` en
 
 These fields land in the `analytics_events.anonymous_id`, `analytics_events.session_id`, and `analytics_events.user_id` columns in the analytics template. Storage access is wrapped in try/catch — private-browsing / blocked-storage clients silently degrade to NULL rather than crashing the page.
 
+### Referral / viral attribution (first-touch)
+
+`configureTracking()` also captures an anonymous visitor's **first-touch** referral context once, on first page load, and persists it across the signup boundary so the server-side `signup` event records where the user came from. This powers virality metrics for every template (Clips share links, Plans public pages, etc.).
+
+**Share-link params** (set by whatever generates the link; read client-side only):
+
+- `ref` — referral source bucket, e.g. `clip_share`, `plan_share`
+- `via` — the referrer's stable user id (the clip/plan owner)
+- `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`
+
+**Client persistence** (first-write-wins — an existing value is never overwritten):
+
+- `localStorage` key `an_attribution` and first-party cookie `an_ft` (`path=/; max-age=2592000; SameSite=Lax`, not HttpOnly — non-sensitive, written by client JS).
+- Both store the same URL-encoded compact JSON (empty fields omitted, each value capped at 120 chars): `{ ref, via, utm_source, utm_medium, utm_campaign, utm_content, utm_term, landing_path, landing_referrer, landed_at }`. `landing_referrer` is the **host only** of `document.referrer` (scrubbed; same-origin referrers are dropped).
+- `getFirstTouchAttribution()` (from `@agent-native/core/client`) returns the parsed object or `null`.
+
+**Signup event enrichment** (server-side, from the `an_ft` cookie on the signup/OAuth-callback request, derived in `packages/core/src/server/attribution.ts`):
+
+- `referral_source` — `ref` if present, else derived: `/share/…` → `clip_share`; a plan public path (`/p/`, `/plan/`, `/share-plan/`) → `plan_share`; a non-empty external referring host → `external`; otherwise `direct`.
+- `referrer_user` (= `via`), `referral_medium` (= `utm_medium`), `referral_campaign` (= `utm_campaign`)
+- `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` (raw passthrough)
+- `first_touch_path` (= `landing_path`), `landing_referrer`
+
+Attribution parsing is fully defensive and never blocks signup — a missing/malformed cookie falls back to `referral_source: "direct"`.
+
 Other framework-level baseline events:
 
 - `session status` from `useSession()`, with `signed_in`
-- `signup` from Better Auth user creation, with `auth_provider` and `auth_user_id`
+- `signup` from Better Auth user creation, with `auth_provider`, `auth_user_id`, and first-touch referral attribution (`referral_source`, `referrer_user`, `referral_medium`, `referral_campaign`, `utm_*`, `first_touch_path`, `landing_referrer` — see "Referral / viral attribution" above)
 - `builder connect clicked` and `builder connect popup blocked` from browser Connect Builder CTAs
 - `builder connect started`, `builder connect succeeded`, `builder connect failed`, `builder disconnect succeeded`, and `builder disconnect failed` from the Builder connection routes, with LLM connection context when resolvable
 
@@ -121,7 +150,10 @@ For new lifecycle events, call `track()` server-side when the server is the sour
 interface TrackingProvider {
   name: string;
   track(event: TrackingEvent): void | Promise<void>;
-  identify?(userId: string, traits?: Record<string, unknown>): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
   flush?(): void | Promise<void>;
 }
 
@@ -142,11 +174,11 @@ interface TrackingEvent {
 
 ## Key Files
 
-| File                                           | Purpose                                     |
-| ---------------------------------------------- | ------------------------------------------- |
-| `packages/core/src/tracking/registry.ts`       | `track()`, `identify()`, `registerTrackingProvider()`, `flushTracking()` |
-| `packages/core/src/tracking/providers.ts`      | Built-in providers (PostHog, Mixpanel, Amplitude, Agent Native Analytics, Webhook) and `registerBuiltinProviders()` |
-| `packages/core/src/tracking/types.ts`          | `TrackingEvent` and `TrackingProvider` interfaces |
+| File                                      | Purpose                                                                                                             |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `packages/core/src/tracking/registry.ts`  | `track()`, `identify()`, `registerTrackingProvider()`, `flushTracking()`                                            |
+| `packages/core/src/tracking/providers.ts` | Built-in providers (PostHog, Mixpanel, Amplitude, Agent Native Analytics, Webhook) and `registerBuiltinProviders()` |
+| `packages/core/src/tracking/types.ts`     | `TrackingEvent` and `TrackingProvider` interfaces                                                                   |
 
 ## Related Skills
 

package/docs/design/durable-agent-runs.md

@@ -0,0 +1,217 @@
+# Design: Durable / Checkpointed Agent Runs
+
+Status: proposed
+Owner: core / run-manager
+Related code: `packages/core/src/agent/run-manager.ts`,
+`packages/core/src/agent/engine/builder-engine.ts`
+
+## Problem
+
+Hosted agent runs are bounded by a ~40s soft timeout enforced in
+`run-manager.ts` (`DEFAULT_HOSTED_RUN_SOFT_TIMEOUT_MS = 40_000`, also the
+`HOSTED_SOFT_TIMEOUT_CEILING_MS`). That budget is deliberate and correct: it
+sits just under a stack of upstream walls that the framework does not control.
+
+When the soft timeout fires, the run-manager aborts the current chunk, persists
+the partial turn, writes a terminal event, and emits an `auto_continue` event
+(`reason: "run_timeout"`) so the client transparently resumes the turn in a
+fresh chunk. This works well for a single long model call that just needs more
+wall-clock time.
+
+It does **not** work well for long _multi-step_ operations. A turn that performs
+many sequential side effects — for example an agent appending many dashboard
+panels through many separate write calls, or any "do N independent mutations in
+a loop" workflow — fails in a characteristic way:
+
+- **Continuation thrash / re-hydration.** Each `auto_continue` chunk starts the
+  model over from the rebuilt context. If the work isn't expressed as resumable
+  progress, the model frequently re-reasons about and re-issues steps it already
+  attempted in the previous chunk instead of advancing. Successive chunks burn
+  their entire 40s budget re-deciding rather than completing new steps.
+- **Partial or zero net progress.** Because each chunk can be cut mid-step and
+  the next chunk may redo earlier steps, the run can churn for many chunks while
+  the _persisted_ end state barely moves — or, when nothing reaches a committed
+  state before each cutoff, moves not at all.
+- **Silent "looked-done" failure.** A tool call that returned a success marker
+  (✓) in an aborted chunk does not guarantee its effect was committed and
+  survived the cutoff. The model can reasonably believe a step succeeded, report
+  the whole task complete, and leave nothing (or only some rows) actually
+  persisted. The user is told it worked; the data says otherwise.
+
+Net effect: long multi-step runs can spin indefinitely, never finish, and
+terminate with an untruthful "done" state.
+
+## Goals
+
+1. Long multi-step runs **complete reliably** — they make monotonic forward
+   progress across continuation chunks rather than re-doing work.
+2. The user always gets a **truthful terminal state**: either "completed, here
+   is concrete proof (N of N persisted, ids …)", or an honest "did not finish,
+   here is what was committed (M of N) and what remains" — never a false
+   success.
+3. No change to the upstream walls and no raising of the 40s soft timeout (see
+   Guardrail).
+
+## Non-goals
+
+- Raising or removing the soft timeout. It is correct; see Guardrail.
+- Changing the gateway, serverless function limits, or model call timeout.
+- Replacing `auto_continue`. Both approaches below build on it.
+
+## Guardrail: the 40s soft timeout is correct and must not be raised
+
+`DEFAULT_HOSTED_RUN_SOFT_TIMEOUT_MS` / `HOSTED_SOFT_TIMEOUT_CEILING_MS` =
+`40_000` is intentional headroom under the upstream hard walls. Raising it does
+not buy more time — it just converts a graceful hand-off into a hard kill. The
+walls, in order:
+
+1. **Builder model gateway hard cap — ~45s.**
+   `MAX_BUILDER_GATEWAY_TIMEOUT_MS = 45_000` in
+   `packages/core/src/agent/engine/builder-engine.ts`. A single model call is
+   killed at the gateway after 45s. **Not raisable** by the framework.
+2. **Serverless function kill — ~60–65s.** The hosting function is terminated
+   shortly after; the heartbeat then reaps the run row as `stale_run`.
+
+40s leaves ~5s under the gateway wall to abort, persist the partial turn, write
+the terminal event, and emit a clean `auto_continue` so the client resumes. A
+larger value (production saw per-template overrides like `240_000`) pushes the
+cutoff past both walls, so `auto_continue` never fires and the run dies as
+`builder_gateway_timeout` / `stale_run` instead. The ceiling clamp in
+`resolveRunSoftTimeoutMs` exists precisely to defeat that footgun. **Do not
+raise it. Fix durability above the timeout, not by moving the timeout.**
+
+## Approach options
+
+Both options keep the 40s budget and build on the existing `auto_continue`
+mechanism. They differ in _where the long work lives_.
+
+### Option A — Checkpointed / idempotent continuation
+
+Keep the work inside the normal run/`auto_continue` loop, but make each
+continuation chunk **resume from committed progress instead of restarting**.
+
+Mechanism:
+
+- **Persist a progress record** for the operation (a checkpoint): the planned
+  unit of work (the N items / steps), and which units are already committed.
+  This lives in SQL so it survives chunk boundaries and function recycling, the
+  same way run rows do.
+- **Idempotent steps.** Each step keys off a stable identity so re-issuing a
+  completed step is a no-op (upsert by natural key, or "skip if checkpoint says
+  done"). Re-hydration after `auto_continue` then can't double-apply or
+  thrash — a redone step costs a cheap check, not a duplicate write.
+- **Resume, don't replan.** On `auto_continue`, the next chunk reads the
+  checkpoint, skips committed units, and continues with the remainder. Progress
+  is monotonic: every chunk that does anything moves the committed count up.
+- **Truthful terminal state from the checkpoint.** "Done" means the checkpoint
+  shows N of N committed. If the run is cut for good (e.g. it exhausts a
+  continuation budget), the checkpoint still reports M of N committed and the
+  exact remainder — so the terminal message is honest by construction.
+
+Interaction with the walls and the 40s budget:
+
+- Fully respects the 40s soft timeout and the gateway/function walls — it never
+  needs a single chunk to outlast them. It just makes the _sequence_ of chunks
+  productive.
+- Works hand-in-glove with `auto_continue`: today a continuation can redo work;
+  with a checkpoint, a continuation can only advance.
+
+Tradeoffs:
+
+- Pro: smallest change to the runtime model; no new infrastructure; the user
+  keeps watching one live turn; degrades gracefully (even a half-finished run is
+  truthful and re-runnable).
+- Pro: directly kills re-hydration thrash, the actual failure mode.
+- Con: still bounded by however many continuation chunks the client/turn budget
+  allows. A truly enormous job (thousands of steps) can still run out of chunks
+  — but it now ends _truthfully partial and resumable_, not silently empty.
+- Con: requires per-operation work to define the unit of progress and make
+  steps idempotent. Best paid down once at the primitive/action layer (see
+  Tie-in) so individual agents don't have to.
+
+### Option B — Out-of-band durable background execution
+
+Hand a long run to a **queued background job** that executes beyond the
+function/gateway lifetime and reports progress back into the run/event stream.
+
+Mechanism:
+
+- The foreground turn **enqueues** a durable job (the full operation + its
+  inputs) and returns immediately with "started, tracking as job X". The
+  user-facing run does not try to do the work itself within 40s.
+- A durable worker (outside the per-request serverless function lifetime — e.g.
+  the core run-manager / agent-teams background infrastructure the framework
+  already mandates for background agents) runs the job to completion, free of
+  the 45s gateway cap and the ~60s function kill on the _original_ request.
+- The worker **streams progress** (committed counts, ids, errors) back so the
+  UI and the agent can observe and the final state is truthful.
+
+Interaction with the walls and the 40s budget:
+
+- Sidesteps the gateway/function walls for the _long_ work by moving it off the
+  request path. The walls still apply to each individual model call the worker
+  makes, so the worker itself should checkpoint internally (i.e. Option B is
+  strongest when it contains Option A).
+- `auto_continue` becomes a lightweight "is the job still running / what's its
+  progress" poll on the foreground turn rather than the vehicle for the work.
+
+Tradeoffs:
+
+- Pro: removes the hard ceiling on total operation length — genuinely large
+  jobs can finish.
+- Pro: the foreground turn stays responsive and cheap; the user can leave and
+  come back.
+- Con: more infrastructure and lifecycle complexity (job queue, durable worker,
+  progress fan-in, failure/retry semantics, surfacing job state in the UI and
+  to the agent).
+- Con: changes the UX from "one live turn" to "fire-and-track"; needs clear
+  status surfacing so it doesn't become its own kind of silent failure.
+
+## Recommendation
+
+Build **Option A first**, then layer **Option B** for the genuinely unbounded
+cases. Option A delivers the most reliability per unit of effort: it directly
+removes re-hydration thrash and silent looked-done failure for the common case
+(tens of steps), needs no new infrastructure, and makes terminal state truthful
+by construction. Option B is the right ceiling-remover but is a larger build and
+is most valuable _on top of_ a checkpointed core (the durable worker should
+itself checkpoint).
+
+### Phased plan
+
+1. **Phase 0 — Stop hitting the ceiling so often (near-term, cheapest).** Land
+   the mitigations in the Tie-in below (one-call atomic primitives,
+   self-documenting actions, loud termination, proof-of-done verification).
+   These don't fix the ceiling but sharply cut how often multi-step loops are
+   even attempted, and make the failures that remain _loud and truthful_ instead
+   of silent. Capture the agent-facing half as the `reliable-mutations` skill.
+2. **Phase 1 — Checkpointed continuation (Option A).** Add a SQL-backed progress
+   checkpoint for long operations and make their steps idempotent/resumable so
+   each `auto_continue` chunk advances committed progress instead of replanning.
+   Drive terminal state ("N of N", or "M of N + remainder") from the checkpoint.
+   This is the primary reliability win.
+3. **Phase 2 — Durable background execution (Option B).** For operations that
+   can exceed any reasonable number of continuation chunks, enqueue them onto the
+   core background infrastructure, have the durable worker run them to completion
+   (checkpointing internally per Phase 1), and stream truthful progress back to
+   the foreground run and UI.
+
+## Tie-in: cheaper near-term mitigations reduce, but do not replace, the fix
+
+The following reduce _how often_ the 40s ceiling is hit and make the remaining
+failures honest. They are valuable and should ship first (Phase 0), but the
+**actual fix is durable/checkpointed runs** (Phases 1–2):
+
+- **One-call atomic primitives.** Where an action can accept the whole batch
+  (e.g. "set all panels" / "append many in one call"), a single call commits
+  atomically inside one chunk instead of looping N writes that race the budget.
+- **Self-documenting actions.** Action descriptions that steer agents toward the
+  atomic/batch call and away from per-item loops.
+- **Loud termination.** On a time-budget cutoff, fail loud with what was and
+  wasn't committed — never report success on an aborted chunk.
+- **Proof-of-done verification.** After a write, re-read the end state and report
+  concrete proof (counts/ids) rather than trusting a tool ✓.
+
+The agent-facing rules for these live in the `reliable-mutations` skill
+(`.agents/skills/reliable-mutations/SKILL.md`). They lower the blast radius;
+checkpointed and durable runs remove the ceiling itself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.69.0",
+  "version": "0.70.1",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/templates/workspace-core/.agents/skills/changelog/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: changelog
+description: >-
+  How to keep each app's user-facing changelog. Use when you ship a change a
+  user would notice (a new feature, a visible improvement, a bug fix), when
+  wiring the in-app "What's new" surface into a template, or when releasing
+  pending changelog entries.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Changelog — user-facing "What's new"
+
+Every template app keeps a `CHANGELOG.md` of **user-facing** changes that
+renders in-app via the command menu (Cmd+K → "What's new") and on the settings
+page. The flow mirrors changesets so it survives many agents working in
+parallel: each change drops a small **pending entry file**, and a later
+**release** rolls all pending files into a dated `CHANGELOG.md` section.
+
+## When to add an entry
+
+Add an entry whenever you ship something a user of that app would notice:
+
+- a new capability or surface,
+- a visible improvement (speed, layout, copy, defaults),
+- a bug fix that affects behavior they'd see.
+
+Do **not** add entries for refactors, internal tooling, tests, dependency
+bumps, or anything invisible to the end user. The changelog is product notes,
+not a commit log — write it the way you'd describe the change to a customer.
+
+## How to add an entry
+
+From the app directory (the template you changed):
+
+```bash
+agent-native changelog add "Recordings can be trimmed before sharing" --type added
+agent-native changelog add "Faster transcript search" --type improved
+agent-native changelog add "Fixed a crash when opening an empty folder" --type fixed
+```
+
+`--type` is one of `added`, `improved`, `fixed`, `changed`, `removed`,
+`security` (aliases like `feature`, `bugfix`, `enhancement` are accepted). This
+writes `changelog/<date>-<slug>.md` — one file per change, so parallel work
+never conflicts. You can also hand-write that file; the frontmatter is just:
+
+```md
+---
+type: added
+date: 2026-06-23
+---
+Recordings can be trimmed before sharing.
+```
+
+## Writing good entries
+
+- One user-facing sentence, present tense, no internal jargon or file names.
+- Lead with the benefit ("Recordings can be trimmed…"), not the mechanism.
+- Markdown is allowed (bold, links) but keep it short — it renders as a bullet.
+
+## Releasing
+
+`release` stamps every pending entry into `CHANGELOG.md` under a dated
+`## <date>` section (grouped by type) and deletes the pending files:
+
+```bash
+agent-native changelog release            # uses today's date
+agent-native changelog list               # preview pending + released
+```
+
+Releasing is usually done at deploy/merge time. The in-app surface reads
+`CHANGELOG.md`, so only released entries are visible to users — pending entries
+stay invisible until rolled up.
+
+## Wiring the in-app surface (once per template)
+
+Templates already get the rendering for free from `@agent-native/core`. To
+expose it in an app:
+
+1. **Command menu** — pass the app's own changelog to `CommandMenu`:
+
+   ```tsx
+   import changelog from "../CHANGELOG.md?raw";
+   // ...
+   <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen} changelog={changelog}>
+     {/* existing groups */}
+   </CommandMenu>
+   ```
+
+   This adds a "What's new" entry with an unseen-release dot and an in-app
+   dialog — no other wiring needed.
+
+2. **Settings** (optional) — drop the card on the settings page:
+
+   ```tsx
+   import { ChangelogSettingsCard } from "@agent-native/core/client";
+   import changelog from "../CHANGELOG.md?raw";
+   // ...
+   <ChangelogSettingsCard markdown={changelog} />
+   ```
+
+`CHANGELOG.md?raw` is inlined by Vite at build time, so this works on every
+host with no server route or runtime file access.
+
+## Checklist
+
+- [ ] Shipped a user-visible change? Run `agent-native changelog add "…"`.
+- [ ] New template UI? Pass `changelog` to its `CommandMenu` and seed a
+      `CHANGELOG.md`.
+- [ ] Releasing/deploying? `agent-native changelog release` rolls pending → dated.