@agent-native/core 0.69.0 → 0.70.1

package/src/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/src/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/corpus/templates/analytics/app/pages/About.tsx

@@ -1,108 +0,0 @@
-import {
-  IconChartBar,
-  IconMessage,
-  IconLayoutDashboard,
-  IconDatabase,
-} from "@tabler/icons-react";
-import { dataSources, categoryLabels, categoryOrder } from "@/lib/data-sources";
-
-const capabilities = [
-  {
-    icon: IconDatabase,
-    title: "Connect Data Sources",
-    description:
-      "Connect any of 20+ data sources — from Google Analytics and BigQuery to Stripe, HubSpot, and PostgreSQL. Each source includes a step-by-step setup guide.",
-  },
-  {
-    icon: IconLayoutDashboard,
-    title: "Create Custom Dashboards",
-    description:
-      "Describe the dashboard you want and the agent builds it — charts, tables, metrics, and all. A Google Analytics example is included to show what's possible.",
-  },
-  {
-    icon: IconChartBar,
-    title: "Query Explorer",
-    description:
-      "Use the Explorer tool to write arbitrary SQL against BigQuery and visualize results as charts or tables instantly.",
-  },
-  {
-    icon: IconMessage,
-    title: "Ask Questions in Chat",
-    description:
-      "Ask natural-language questions about any connected data source. Get answers, charts, and insights without writing SQL.",
-  },
-];
-
-export default function About() {
-  return (
-    <div className="mx-auto max-w-4xl space-y-10 p-6 md:p-10">
-      <header>
-        <h1 className="text-3xl font-bold tracking-tight">About This App</h1>
-        <p className="mt-2 text-muted-foreground text-lg">
-          Analytics gives you a single place to connect data sources, build
-          custom dashboards, and ask questions across all of your key metrics.
-        </p>
-      </header>
-
-      {/* Capabilities */}
-      <section>
-        <h2 className="text-xl font-semibold mb-4">What You Can Do</h2>
-        <div className="grid gap-4 sm:grid-cols-2">
-          {capabilities.map((cap) => (
-            <div
-              key={cap.title}
-              className="rounded-lg border border-border bg-card p-5 space-y-2"
-            >
-              <div className="flex items-center gap-3">
-                <div className="flex h-9 w-9 items-center justify-center rounded-md bg-primary/10 text-primary">
-                  <cap.icon className="h-5 w-5" />
-                </div>
-                <h3 className="font-medium">{cap.title}</h3>
-              </div>
-              <p className="text-sm text-muted-foreground leading-relaxed">
-                {cap.description}
-              </p>
-            </div>
-          ))}
-        </div>
-      </section>
-
-      {/* Available Data Sources */}
-      <section>
-        <h2 className="text-xl font-semibold mb-4">Available Data Sources</h2>
-        {categoryOrder.map((category) => {
-          const sources = dataSources.filter((s) => s.category === category);
-          if (sources.length === 0) return null;
-          return (
-            <div key={category} className="mb-4">
-              <h3 className="text-xs font-semibold text-muted-foreground uppercase tracking-wider mb-2">
-                {categoryLabels[category]}
-              </h3>
-              <div className="grid gap-2 sm:grid-cols-3">
-                {sources.map((source) => {
-                  const Icon = source.icon;
-                  return (
-                    <div
-                      key={source.id}
-                      className="flex items-center gap-2.5 rounded-lg border border-border bg-card px-3 py-2.5"
-                    >
-                      <div className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-primary/10 text-primary">
-                        <Icon className="h-4 w-4" />
-                      </div>
-                      <span className="text-sm font-medium">{source.name}</span>
-                    </div>
-                  );
-                })}
-              </div>
-            </div>
-          );
-        })}
-      </section>
-
-      <footer className="text-xs text-muted-foreground pt-4 border-t border-border">
-        All data is queried live from the connected sources. BigQuery queries
-        are capped at 750 GB per query for cost safety.
-      </footer>
-    </div>
-  );
-}

package/corpus/templates/analytics/app/routes/about.tsx

@@ -1,9 +0,0 @@
-import About from "@/pages/About";
-
-export function meta() {
-  return [{ title: "About — Analytics" }];
-}
-
-export default function AboutRoute() {
-  return <About />;
-}