@agent-native/core 0.68.3 → 0.70.0

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.

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