@agent-native/core 0.101.14 → 0.102.1

package/corpus/templates/tasks/.agents/skills/read-the-damn-docs/README.md

@@ -0,0 +1,54 @@
+# /read-the-damn-docs
+
+Make agents web-search for the docs before they guess.
+
+`/read-the-damn-docs` is a docs-first discipline skill for implementation,
+debugging, and technical answers that depend on versioned or external behavior.
+It tells the agent when docs are mandatory, why web search is usually the right
+way to find them, which sources count as authoritative, and how to report the
+evidence it used.
+
+## What It Does
+
+- Forces a docs pass for third-party APIs, libraries, frameworks, CLIs, cloud
+  services, model SDKs, and provider integrations.
+- Directs the agent to web-search for current official docs unless the relevant
+  docs are already local or supplied by the user.
+- Requires current version checks before adding packages or writing install,
+  import, config, or CLI commands.
+- Prioritizes local repo docs, specs, schemas, generated types, and tests for
+  internal contracts.
+- Treats auth, security, billing, data, migrations, deploys, quotas, caching,
+  and compliance as docs-required surfaces.
+- Makes the agent name the docs or files it relied on when that evidence affects
+  the implementation.
+
+## When To Use It
+
+Use it when an agent might otherwise rely on stale model memory. Most of the
+time, that means it should search the web for official docs first: latest/current
+behavior, package setup, SDK usage, platform limits, provider APIs, upgrade
+guides, framework config, OAuth, payments, webhooks, migrations, CI/CD, browser
+APIs, and repo-specific contracts.
+
+Skip it for trivial typo fixes, formatting, self-contained local code, or cases
+where nearby tests and types fully answer the question.
+
+## Examples
+
+These should trigger docs before code:
+
+- Adding Tailwind, Next.js, React, Vite, Nitro, Drizzle, Prisma, or an AI SDK.
+- Streaming model responses with OpenAI, Anthropic, Google, or a provider SDK.
+- Wiring Stripe webhooks, OAuth, GitHub Actions, Slack apps, or Notion APIs.
+- Debugging deprecations, unknown config fields, missing exports, or changed
+  framework defaults.
+- Choosing a model, package, cloud API, storage strategy, or migration path.
+- Implementing a repo-specific system where local docs, schemas, or generated
+  clients define the contract.
+
+## Install
+
+```sh
+npx @agent-native/skills@latest add --skill read-the-damn-docs
+```

package/corpus/templates/tasks/.agents/skills/read-the-damn-docs/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: read-the-damn-docs
+description: >-
+  Use when implementing, integrating, upgrading, debugging, or answering
+  anything involving third-party APIs, libraries, frameworks, CLIs, cloud
+  services, model/provider SDKs, fast-moving product behavior, user requests for
+  latest/current/official behavior, unfamiliar repo docs/specs, errors that may
+  indicate API drift, or high-stakes auth, security, billing, data, migration,
+  deployment, compliance, or privacy behavior. Forces Codex to web-search for
+  current official docs and read primary docs before assuming from memory.
+---
+
+# Read The Damn Docs
+
+Do not guess where authoritative docs can answer the question. The most common
+right move is to web-search for the current official docs, open the relevant
+pages, and read them before coding. For APIs, versions, provider behavior,
+config, limits, lifecycle hooks, or security-sensitive flows, ground the answer
+in what the docs actually say.
+
+## Docs-First Triggers
+
+Read docs before proceeding when any of these are true:
+
+- The user asks for "latest", "current", "official", "supported", "best
+  practice", "recommended", "today", "now", or "look it up".
+- The needed docs are not already in the repo or supplied by the user. Search
+  the web for the official docs rather than hoping model memory is current.
+- The task adds, upgrades, configures, or imports a package, SDK, framework,
+  plugin, CLI, model, cloud resource, or provider integration.
+- The API is fast-moving or version-sensitive: AI SDKs, OpenAI/Anthropic/Google
+  APIs, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub,
+  Slack, Notion, browser APIs, deployment platforms, auth libraries, and similar.
+- The implementation depends on auth, OAuth scopes, permissions, secrets,
+  webhooks, billing, payments, PII, encryption, data retention, migrations,
+  retries, rate limits, quotas, caching, deploys, or compliance.
+- An error mentions deprecation, unknown options, missing exports, invalid
+  config, unsupported fields, changed defaults, or version mismatch.
+- A repo has local docs, ADRs, generated schemas, OpenAPI specs, route/action
+  registries, design-system docs, or package-level READMEs that could define the
+  contract.
+- The choice is expensive to reverse: public wire formats, database schema,
+  migration strategy, persistent IDs, event names, customer-visible behavior, or
+  external automation contracts.
+- You catch yourself about to write "usually", "probably", "I think", "from
+  memory", or code copied from model memory for an external API.
+
+## What Counts As Docs
+
+Use the most authoritative source available:
+
+- Local repo docs, specs, ADRs, schemas, generated types, package READMEs, and
+  tests for project-specific behavior.
+- Official product docs, API references, migration guides, changelogs, release
+  notes, and SDK source/types for third-party behavior. Find these with web
+  search when you do not already have the exact URL.
+- Package registry metadata for versions. Before adding a dependency, run
+  `npm view <pkg> version`, `pnpm view <pkg> version`, or the ecosystem
+  equivalent, then read the docs for that major version.
+- Source code or type definitions when official docs are incomplete. Treat this
+  as evidence, not folklore.
+
+Avoid Stack Overflow, old blog posts, random snippets, and memory as the primary
+source when official docs exist. Use community sources only to debug symptoms
+after the authoritative contract is known.
+
+## Required Workflow
+
+1. Identify the exact surface: package name, installed version, target version,
+   provider endpoint, CLI command, config file, local helper, schema, or product
+   feature.
+2. Search the web for the current official docs unless the relevant docs are
+   already local or the user supplied a URL. Use targeted searches such as
+   `<product> <feature> official docs`, `<package> migration guide`, or
+   `<provider> API reference`.
+3. Open and read the docs closest to that surface. Prefer local docs first for
+   internal code, then official upstream docs. For new packages, verify the
+   latest version before writing imports, config, or install commands.
+4. Extract the few facts needed for the task: option names, imports, lifecycle
+   rules, default behavior, breaking changes, limits, permissions, and examples
+   for the current major version.
+5. Implement or answer using those facts. If the docs conflict with existing
+   code, inspect the local code path and call out the discrepancy.
+6. Verify with the smallest useful check: typecheck, tests, build, CLI dry run,
+   API schema validation, or a local reproduction.
+7. In the final answer, name the docs or local files consulted when that
+   evidence affects the recommendation or implementation.
+
+## Examples That Must Trigger Docs
+
+- "Add Tailwind to this app." Check the current Tailwind major and its install
+  docs from the web before creating config files or assuming old PostCSS setup.
+- "Use the AI SDK to stream responses." Verify the current AI SDK major,
+  imports, provider package names, streaming helpers, and server/runtime
+  examples from official docs.
+- "Wire up Stripe webhooks." Read Stripe's current signature verification,
+  event retry, endpoint secret, and framework body-parsing docs before coding.
+- "Fix this Next.js caching bug." Read the docs for the installed Next.js major
+  and router mode before assuming cache invalidation semantics.
+- "Add Drizzle migrations." Read the current Drizzle kit docs and existing repo
+  migration conventions before generating files.
+- "Create a GitHub Action." Read official Actions syntax and permissions docs,
+  especially for `pull_request`, `workflow_run`, OIDC, tokens, and artifacts.
+- "Why does this OAuth flow fail?" Read the provider's scopes, redirect URI,
+  PKCE, token refresh, and app verification docs before changing code.
+- "Use this repo's plan/comment/action system." Read local docs, route/action
+  registries, schemas, and tests before inventing endpoints or props.
+- "Upgrade Vite/Nitro/React." Read the migration guide for the exact target
+  major before editing config or imports.
+- "What model should we use?" Read current provider model docs, pricing/limits
+  pages, and SDK examples before recommending.
+
+## When A Quick Local Read Is Enough
+
+Do not browse the web for every tiny edit. A docs pass can be local and brief
+when the answer is already in the repo: existing helper usage, nearby tests,
+typed interfaces, generated clients, ADRs, or package READMEs. But if the task
+depends on an external tool, package, provider, or current product behavior, web
+search is usually the right first step. For trivial language syntax, typo fixes,
+formatting, or self-contained code with no external contract, proceed normally.
+
+## If Docs Are Unavailable
+
+If network access, auth, or missing local files prevents reading the docs, say
+that plainly before relying on memory. Narrow the uncertainty, inspect source or
+types if available, and avoid presenting the result as confirmed-current.

package/corpus/templates/tasks/.agents/skills/read-the-damn-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Read The Damn Docs"
+  short_description: "Make agents web-search docs before guessing."
+  default_prompt: "Use $read-the-damn-docs to web-search for official docs before implementation."

package/corpus/templates/tasks/.agents/skills/real-time-sync/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: real-time-sync
+description: >-
+  How to keep the UI in sync with agent changes via SSE plus polling fallback.
+  Use when wiring query invalidation for new data models, debugging UI not
+  updating, or understanding jitter prevention.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Real-Time Sync
+
+## Rule
+
+The UI stays in sync with agent/script changes through `useDbSync()`. In-process writes stream over `/_agent-native/events` first; `/_agent-native/poll` remains the cross-process/serverless fallback. When the agent writes to the database, the UI detects the change and updates automatically — no manual refresh needed.
+
+## Why
+
+The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same-process writes immediately; polling bridges anything SSE cannot see, such as another serverless invocation, cron job, or external script. Every visible write increments a version counter, `useDbSync()` receives the change, and React Query invalidates the relevant caches. This is what makes database writes feel real-time without relying on aggressive polling.
+
+## How It Works
+
+1. **Server** increments a version counter on every database write. In-process events stream through the authenticated `/_agent-native/events` endpoint.
+
+2. **Client** listens for sync events and updates per-source change counters:
+
+   ```ts
+   import { useDbSync } from "@agent-native/core/client";
+   useDbSync({ queryClient });
+   ```
+
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
+
+3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
+
+   ```ts
+   import { useChangeVersion } from "@agent-native/core/client";
+   import { useQuery } from "@tanstack/react-query";
+
+   const v = useChangeVersion("dashboards");
+   const dashboard = useQuery({
+     queryKey: ["dashboard", id, v],
+     queryFn: () => fetchDashboard(id),
+     placeholderData: (prev) => prev, // no flicker on refetch
+   });
+   ```
+
+   When the agent writes (`update-dashboard` action → server emits `source: "dashboards"`), the counter advances, the queryKey changes, and React Query refetches that one query. The old data stays on screen during the refetch thanks to `placeholderData`.
+
+   For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
+
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
+
+5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
+
+## Don't
+
+- Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
+- Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
+
+## Which sources to depend on
+
+Common sources you'll fold into query keys:
+
+| Source            | Bumped by                                                                   |
+| ----------------- | --------------------------------------------------------------------------- |
+| `action`          | The agent runner after every successful mutating action tool call           |
+| `app-state`       | Writes to `application_state` (navigation, selections, ephemeral UI state)  |
+| `settings`        | Writes to the `settings` table                                              |
+| `dashboards`      | Dashboard CRUD via `upsertDashboard` / `archiveDashboard` etc.              |
+| `analyses`        | Analysis CRUD                                                               |
+| `extensions`      | Extension CRUD                                                              |
+| `collab`          | Yjs collaborative-doc updates                                               |
+| `screen-refresh`  | Explicit `refresh-screen` agent tool call                                   |
+
+If a query reads data the agent can mutate via more than one path, depend on multiple sources with `useChangeVersions`:
+
+```ts
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({ queryKey: ["dashboard", id, v], ... });
+```
+
+`useChangeVersions` returns a single integer that advances whenever any of the listed sources advance.
+
+## Tuning refetch behavior
+
+To prevent cache thrashing during rapid agent writes, set `staleTime` on your queries:
+
+```ts
+useQuery({
+  queryKey: ["items"],
+  queryFn: fetchItems,
+  staleTime: 2000, // don't refetch within 2 seconds
+});
+```
+
+## Troubleshooting
+
+| Symptom                            | Check                                                                                                          |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
+| Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
+| SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`, `deleteAppState`), the write is automatically tagged with `requestSource: "agent"`. This prevents the UI from overwriting active user edits when it receives the change event.
+
+### How it works
+
+1. **Agent writes** are tagged: the script helpers in `@agent-native/core/application-state` pass `{ requestSource: "agent" }` to the store.
+2. **UI writes** are tagged: templates send a per-tab ID via the `X-Request-Source` header on PUT/DELETE requests to application-state endpoints.
+3. **Sync filters**: `useDbSync()` accepts an `ignoreSource` option. The UI passes its own tab ID so it ignores events from its own writes — but still picks up events from agents, other tabs, and scripts.
+
+### Template setup
+
+```ts
+// app/lib/tab-id.ts
+export const TAB_ID = `tab-${Math.random().toString(36).slice(2, 8)}`;
+
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID,
+});
+```
+
+The `use-navigation-state.ts` hook sends the same `TAB_ID` in the `X-Request-Source` header when writing navigation state, so the tab that wrote the state does not refetch it.
+
+### Why this matters
+
+Without jitter prevention, a cycle occurs: the UI writes state, sync detects the change, the UI refetches and re-renders, potentially overwriting what the user is actively editing. With `ignoreSource`, the UI only reacts to changes from other sources (agent scripts, other browser tabs, other users).
+
+## Action Routes and Live Sync
+
+Actions work with the same sync system. When a mutating action writes to the database, the version counter increments and `useDbSync` picks up the change. Frontend mutations via `useActionMutation` automatically invalidate `["action"]` query keys on success, triggering refetches of `useActionQuery` hooks. Client components should call actions through those hooks, not with raw action-route fetches.
+
+For custom apps, the best out-of-the-box path is:
+
+1. Put read actions in `actions/` with `defineAction({ http: { method: "GET" } })`.
+2. Put write actions in `actions/` with the default POST/PUT/DELETE behavior.
+3. Call reads from React with `useActionQuery` and writes with `useActionMutation`.
+
+This avoids duplicate `/api/*` JSON CRUD routes and makes agent-created records show up automatically. Raw `useQuery` can still work, but it should include `useChangeVersions(["action", "<domain-source>"])` in the query key for targeted refreshes.
+
+### Auto-emit on mutating actions
+
+The framework emits a change event with `source: "action"` whenever any non-read-only action runs to completion — whether called via HTTP (`/_agent-native/actions/:name`) or as an agent tool call. Read-only actions (`http: { method: "GET" }` or explicit `readOnly: true`) are skipped.
+
+This means UIs don't need the agent to remember to call `refresh-screen` after every mutation. A listener like this (used in the `macros` template) will refresh after any mutating agent call:
+
+```ts
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID,
+  onEvent: (data) => {
+    if (data.requestSource === TAB_ID) return;
+    // Invalidate all useActionQuery caches so list-*, get-*, etc. refetch
+    queryClient.invalidateQueries({ queryKey: ["action"] });
+  },
+});
+```
+
+`refresh-screen` remains available for unusual cases — e.g. the agent mutated data via a path the framework can't see (external system the app mirrors), or the agent wants to pass a `scope` hint for narrower invalidation.
+
+## Keeping Stateful Components In Sync
+
+The `useChangeVersion` / `useActionQuery` pattern above keeps the **query layer** fresh. But components that copy a server value into local React state still go stale on agent edits — refetching the query updates the prop, yet the local copy never re-adopts it. This is a recurring bug.
+
+**Never do this** for a value the agent can mutate:
+
+```ts
+// BUG: `title` is captured once and never re-reads the prop.
+const [title, setTitle] = useState(props.title);
+```
+
+When the agent renames the record, the query refetches, `props.title` updates, but the input still shows the stale value until the component remounts.
+
+**Derived-state surfaces (form fields, inline editors, popovers): use `useReconciledState`.** It re-adopts the authoritative external value when it changes, except while the user is actively editing that field — so agent mutations show up live without clobbering in-progress typing:
+
+```ts
+import { useReconciledState } from "@agent-native/core/client";
+
+// `active` = true while the user is editing this field (focused / dirty).
+const [title, setTitle] = useReconciledState(props.title, { active: isEditing });
+```
+
+**Collaborative rich-text editors are different** — they don't copy a value into `useState`. They reconcile authoritative SQL content into a shared Y.Doc under an `updatedAt` gate with lead-client election. See `real-time-collab` → "Agent edits as a real-time peer editor". Don't reach for `useReconciledState` for a Yjs-backed editor.
+
+| Surface | Keep it fresh with |
+| ------- | ------------------ |
+| React Query reads | `useChangeVersion` / `useActionQuery` (above) |
+| Local edit state copied from a server value (inputs, popovers, inline editors) | `useReconciledState(externalValue, { active })` |
+| Collaborative rich-text editor (Yjs) | `updatedAt`-gated reconcile + `isReconcileLeadClient` — see `real-time-collab` |
+
+## Granular server-side merge for non-body fields
+
+For structured documents (slide decks, form builders, design files) where the
+Yjs body collab would cause LWW conflicts at the container level, pair the
+change-sync `updatedAt` bump with a **granular server-side merge action** that
+accepts targeted per-item operations (add/patch/delete/reorder). Concurrent
+edits to different items both survive at the action level; the `collab` source
+version bump then propagates the merged state to all open clients. See
+`real-time-collab` for the pattern and examples.
+
+## Related Skills
+
+- **storing-data** — Application-state and settings are data stores that sync through change events
+- **context-awareness** — Navigation state writes use jitter prevention to avoid overwriting active edits
+- **actions** — Mutating actions trigger change events
+- **client-methods** — Route details belong in helpers/hooks, not components
+- **self-modifying-code** — Agent code edits trigger change events; rapid edits can cause event storms
+- **real-time-collab** — Collaborative editors reconcile agent edits into a shared Y.Doc, driven by the same change-sync `updatedAt` bump; also the granular server-side merge pattern for structured data