@thinkingai/ae-cli 6.1.20 → 6.1.21

package/skills/ae-migrate-tracking-code/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: ae-migrate-tracking-code
+description: "Migrate existing third-party SDK tracking code (Firebase, Amplitude, Sensors Data, Mixpanel, GA4) to the AE SDK (数数 / ThinkingAI / Agentic Engine / AE SDK) — switch (replace) or add alongside existing tracking (dual-write). Trigger words: 埋点迁移、埋点切换、第三方埋点迁移、第三方埋点切换、迁移埋点到数数、把 xx SDK 切换到数数、把已有埋点用数数实现一遍、用数数替换 xx SDK、集成数数并参考已有 xx SDK 埋点、Firebase 迁移、Amplitude 迁移、Mixpanel 迁移、神策迁移、Sensors Data 迁移、GA4 迁移、gtag 迁移、双写、tracking migration、migrate Firebase/Amplitude/Mixpanel/Sensors Data/GA4 to AE、switch xx SDK to ThinkingAI、replace xx SDK with AE、replace logEvent with track、re-implement existing tracking with ThinkingAI、add AE tracking alongside existing analytics、dual-write. Provider-agnostic core with per-provider adapters; reuses ae-generate-tracking-plan and ae-generate-tracking-code."
+---
+
+# ae-migrate-tracking-code
+
+> **Conversation language**: This skill document is in English, but **all output to the user MUST be in the user's input language**.
+> English input → English reply; Chinese input → Chinese reply; Japanese input → Japanese reply.
+> If uncertain, default to English.
+> This applies to all output: section titles, phase names, prompts, code comments, etc.
+> **⚠️ CRITICAL: Many provider adapter docs contain Chinese glossary notes. When reading them to answer an English/Japanese user, translate headings and comments to the user's language.**
+> Do NOT copy Chinese text verbatim from this document into English/Japanese replies.
+
+## Terminology Glossary
+
+| 中文 | English | Notes |
+|------|---------|-------|
+| 埋点迁移 | Tracking Migration | Convert existing third-party SDK tracking calls to AE SDK |
+| 源 SDK | Source SDK / Provider | The third-party SDK already in the project (Firebase, Amplitude, ...) |
+| 调用点 | Call Site | A source-SDK invocation (`logEvent` / `setUserId` / `setUserProperty` / Identify) |
+| 归一化中间表示 | IR (Intermediate Representation) | Provider-neutral dump of extracted call sites |
+| 映射 | Mapping | Source event/property → AE event/property translation |
+| 切换 | Switch | Replace source calls with AE `track()` and remove source SDK |
+| 双写 / 新增 | Add / Dual-write | Keep source SDK and add AE `track()` alongside |
+| 依赖标识 | Dependency Identifier | Package/module name used to remove the source SDK in switch mode |
+| 自动采集事件 | Auto-track Event | Events the source SDK collects automatically (e.g. `session_start`) |
+| 公共属性 | Super Property | Property attached to every event automatically. ⚠️ The correct Chinese AE term is "公共属性" or "公共事件属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term. |
+| 用户属性 | User Property | Property set on the user profile |
+| 用户体系 | User Identity System | distinct_id / account_id strategy in AE |
+
+## When to Trigger
+
+Trigger when user says: "migrate Firebase tracking to AE / replace Amplitude with ThinkingAI / my project already has Firebase/Amplitude tracking, switch it to AE SDK / add AE tracking alongside existing analytics" etc. — e.g. 把当前工程里的 xx SDK 切换到数数、把已有埋点用数数实现一遍、用数数替换 xx SDK、集成数数并参考已有的 xx SDK 埋点.
+
+The **target AE SDK** may be referred to by any of: 数数 / 数数 SDK / ThinkingAI / ThinkingAI SDK / Agentic Engine / Agentic Engine SDK / AE / AE SDK — they are one SDK. The trigger signal is "an **existing third-party source SDK** + 迁移/切换/替换/实现一遍", or "集成/接入数数 **并参考已有的 xx SDK 埋点**". A bare 接入数数 SDK / 加数数埋点 with no source SDK is greenfield — it belongs to `ae-generate-tracking-code`, not this skill.
+
+**Scope**: this skill is codebase-only — it scans existing third-party tracking calls (Phase 0/1). If there is no source code with third-party tracking (only product docs / descriptions), do NOT use this skill; route to `ae-generate-tracking-plan` + `ae-generate-tracking-code` instead. Historical data import into AE is offline data-migration work, **out of scope** — this skill only switches the live client/server SDK, preserving user IDs and event/property names so new data joins the imported data.
+
+This skill orchestrates the migration end-to-end but **does not duplicate** the two existing skills:
+
+- Plan generation/upload → hand off to `ae-generate-tracking-plan` (codebase path).
+- AE SDK code insertion → hand off to `ae-generate-tracking-code` (insert mode), with insertion sites supplied from the migration mapping instead of grep-discovered business triggers.
+
+## Provider Registry (extensible)
+
+The core is provider-agnostic. Each third-party platform is one adapter file. **To support a new provider, add one adapter under `references/providers/` and one row below — do not modify this SKILL.md.**
+
+| Provider | Adapter | Platforms covered | Detect pattern (summary) |
+|---|---|---|---|
+| Firebase Analytics | `references/providers/firebase.md` | Web v8/v9, Android, iOS, Flutter, React Native, Unity, C++ | `firebase/analytics`, `firebase.analytics()`, `FirebaseAnalytics`, `FIRAnalytics`, `Analytics.logEvent` (iOS Swift), `FirebaseAnalytics.instance` |
+| Amplitude | `references/providers/amplitude.md` | Web legacy (`amplitude-js`), Browser 2.x, Node, Python, Go, Java, Android, iOS, React Native, Flutter, Unity | `amplitude-js`, `@amplitude/analytics-browser`, `@amplitude/analytics-node`, `amplitude.init`, `amplitude.getInstance()`, `amplitude.logEvent`, `amplitude.track`, `Identify`, server imports (`from amplitude import`, `analytics-go`, `com.amplitude:java-sdk`) |
+| Sensors Data (神策) | `references/providers/sensors-data.md` | Web, Android, iOS, Harmony, macOS/tvOS, C++, React Native, Flutter, Unity, Unreal, Cocos2d-x, mini-programs (WeChat/other), QuickApp, APICloud, uni-app, Weex, Egret, LayaAir + server SDKs (Java/Python/Go/Node/PHP/Ruby/C/.NET/Lua) | `sensorsdata.min.js`, `sensors.init`, `sensors.track`, `SensorsDataAPI`, `SensorsAnalyticsSDK`, `profileSet`, `setProfile` (legacy), server `sa-sdk-*` (Python/Go/Node/PHP/Ruby/C/.NET/Lua) |
+| Mixpanel | `references/providers/mixpanel.md` | JavaScript, Node, Python, Go, Java, Ruby, PHP, Android, iOS, Swift, React Native, Flutter, Unity | `mixpanel-browser`, `mixpanel.init`, `mixpanel.track`, `mixpanel.identify`, `mixpanel.people`, `MixpanelAPI`, `mixpanel.NewApiClient` (Go), `Mixpanel::Tracker` (Ruby), `Mixpanel::getInstance` (PHP), `mp.track` / `people_set` (Python) |
+| Google Analytics 4 | `references/providers/ga4.md` | Web (gtag.js / dataLayer), Measurement Protocol (server) | `gtag('event'`, `gtag('config'`, `gtag('set'`, `dataLayer` (GA4 only when `gtag(`/`G-` also present), `G-XXXXXXX`, Measurement Protocol `mp/collect` |
+
+Adapter contract (required fields per adapter) is defined in `references/providers/README.md`.
+
+**Supported scope**: only the providers/platforms listed above (and the per-platform tables in each adapter's Recognition section) are supported. Anything not listed is out of scope and not supported by this skill — do not fabricate a mapping for unlisted platforms.
+
+---
+
+## Phase 0 — Detect source SDK and version
+
+1. Locate the project and its package/dependency manifest (`package.json`, `build.gradle`, `Podfile`, `pubspec.yaml`, `*.csproj`, ...) plus source imports.
+2. Match against the registry above. Read the matching adapter's **Recognition** section to confirm the provider and pin the version variant:
+   - Firebase: v8 namespaced vs v9 modular (web), plus Android/iOS/Flutter native forms.
+   - Amplitude: legacy (`getInstance().logEvent`) vs SDK 2.x (`amplitude.track` / `@amplitude/analytics-browser`).
+3. If multiple providers are present, list them and ask which to migrate first (one provider per run keeps mapping clean). **Exception — GA4 and Firebase Analytics are the same data stream**: GA4 is Firebase's web layer (one measurement ID is both a GA4 property and a Firebase project). If `gtag(...)` and `logEvent(...)` coexist in one project, they are **not two providers** — merge them into a single migration run: one scan, one `draft.json` / `mapping.json`, one dedup pass over the shared event / property / user-id names. Never produce two drafts for one Google data stream.
+4. If no registry match but tracking code exists → show the found calls, ask the user for the provider name, and (per `references/providers/README.md`) collect a minimal adapter from the user-provided docs/snippet before continuing.
+
+## Phase 1 — Extract call sites into IR
+
+Scan the project for four call categories, using the adapter's **Recognition** patterns:
+
+1. **Event** calls: `logEvent(...)` / `track(...)` and their params/properties.
+2. **Identity** calls: `setUserId(...)` / `identify(...)` / `login(...)`.
+3. **User property** calls: `setUserProperty(...)` / `setUserProperties(...)` / `Identify` operations.
+4. **Super property** calls (common event properties): `register(...)` / `registerSuperProperties(...)` (Mixpanel, Sensors Data) / `setDefaultEventParameters(...)` (Firebase). Record them as `kind: super_property` with the full `props` map — do not misread them as user properties (see `mapping-framework.md` §6). Amplitude and GA4 have no such API.
+
+Record each site as `file:line`, call kind, event/param values (literals, or variable names to resolve by reading the surrounding code). Write the normalized dump to `.ae-cli/migration/scan.json` following `references/ir.md`.
+
+**Wrapper-layer resolution (reverse call-graph tracing)** — real projects almost never call the source SDK directly at every business event; they wrap it in an analytics helper (`trackEvent(name, props)` → `mixpanel.track(name, props)`). A naive grep sees only the wrapper's single SDK call (event name = parameter → would be `resolved:false`) and misses every real business event. So when an SDK call's event name is a **function parameter** (a runtime variable flowing from an enclosing function's argument), do **not** immediately record `resolved:false`:
+
+- Identify the enclosing function `F` — it is an **analytics wrapper** only when `F`'s sole role is forwarding that parameter into the SDK call. If the event name comes from local logic/expressions rather than a parameter, it is NOT a wrapper — record the site as `resolved:false` as usual.
+- Grep for every caller of `F`. Resolve each caller with a static event name into a normal call site: `kind` is inferred from the SDK call `F` delegates to (event / identity / user_property), `event_name` from the caller's literal or constant argument, `source_call` = the caller's invocation line, `file` = the caller's file, and `via_wrapper` = `F`'s name.
+- Callers with a dynamic event name stay `resolved:false`. If no callers are found (an exported wrapper used externally, or dynamic dispatch), fall back to recording the wrapper's own SDK call as a single `resolved:false` site.
+- Record `F` itself in scan.json's top-level `wrappers` array (see `references/ir.md`) — it is the pivot for tracing, not a migration target.
+
+**Auto-track note**: source SDK auto-collected events (e.g. Firebase `session_start`, `first_open`, `screen_view`) are not call sites. Handle them per the adapter's **Auto-track decision** table in Phase 2, not here.
+
+## Phase 2 — Map to AE (write draft.json + mapping.json)
+
+1. Read `references/mapping-framework.md` (generic algorithm) + the provider adapter (differences).
+2. For each extracted event call: map to an AE event (snake_case name, or **verbatim** when forward compatibility is required — `mapping-framework.md` §1; `display_name` in the user's language), map each param to an AE property with a type, and apply naming constraints from the adapter (reserved prefixes, special characters, length caps).
+3. Apply dedup + promotion rules: same property on 3+ events → common event property (super property); preset `#` properties never become super properties. Explicit super-property call sites (`register` / `setDefaultEventParameters`) also land in `draft.json`'s `common_event_properties` pool — see `mapping-framework.md` §6.
+4. Map identity → AE `login(accountId)` (account_id_source `user_account`); plus visitor-id continuity (`setDistinctId` / `identify`, init-time) when forward compatibility with imported historical data is in scope — see `mapping-framework.md` §4. User property ops → AE `user_set` / `user_setOnce` / `user_add` / `user_append` / `user_unset` per the adapter's mapping table. Super property calls → AE `setSuperProperties({...})` (static common event property), per `mapping-framework.md` §6.
+5. Decide each event's `platform` (client / server) from where the call site lives (app code → client; backend → server).
+6. Ask the user to confirm the **migration mode** (see Modes below) and whether **historical source-platform data** has been (or will be) imported into AE **offline** — drives forward-compatible naming per `mapping-framework.md` §1 and visitor-id continuity per §4. The import itself is offline data-migration work, out of scope; this skill only switches the live SDK — then:
+   - Write `.ae-cli/migration/mapping.json` (source site → AE event + mode decision, schema in `references/ir.md`).
+   - Write `.ae-cli/draft.json` in the AE plan schema (same schema `ae-generate-tracking-plan` produces) so the plan skill can consume it directly.
+
+Show the mapping summary table and get user `ok` before proceeding.
+
+## Phase 3 — Generate and upload the tracking plan
+
+Hand off to `ae-generate-tracking-plan` using the codebase/draft already produced:
+
+1. `ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx`
+2. `ae-cli tracking plan validate --in .ae-cli/draft.json --fix`
+3. Resolve AE host/login/projectId per the plan skill, then `ae-cli tracking plan upload ...` (ask the user before uploading; append vs replace per that skill's conflict detection).
+
+## Phase 4 — Insert AE SDK code (switch or add)
+
+Hand off to `ae-generate-tracking-code` (insert mode), but **insertion sites come from `.ae-cli/migration/mapping.json`, not from grep business-trigger discovery**:
+
+- Client/server platform + language are already in `draft.json` meta; resolve APP_ID / SERVER_URL as that skill does.
+- For each mapped AE event, the insertion point is the original call site recorded in mapping.json.
+
+**Mode `switch`** (replace) — **high-risk, confirm before deleting**:
+- Before any deletion, explicitly list what will be removed (the source call sites and the source SDK dependency from the adapter's **Dependency identifiers**) and get the user's confirmation to delete.
+- Replace the source `logEvent`/`track` call with the AE `track(...)` call at the same site; remove now-unused source imports.
+- **Inline event names that came from a module constant**: emit the literal snake_case name in the AE `track(...)` call (it must match the `// @tracking <event_name>` marker). **Before deleting the constant definition, grep the whole project for its name** — a module constant is often imported by multiple files, fed to a server-side report, or asserted in tests. Only remove it when the migrated call sites are its sole references (then it is dead code); otherwise keep it. Do not keep a constant that only feeds the migrated call.
+- Remove the source SDK dependency using the adapter's **Dependency identifiers** (e.g. `firebase/analytics`, `@amplitude/analytics-browser`).
+- **Remove dead wrappers**: when every call site resolved through a wrapper is `replace`d, the wrapper function is dead code — delete it (and its now-unused source import). If the wrapper's file holds nothing else, remove the file. (`add` mode keeps the wrapper — it still feeds the source SDK — and adds the AE call at each business call site.)
+- Convert identity/user-property calls to `login(...)` / user-property calls similarly; super-property calls → `setSuperProperties({...})` **in place at the original call site** (never hoisted — the source's `register` position encodes when the values become available, e.g. after login; see `mapping-framework.md` §6).
+
+**Mode `add`** (dual-write):
+- Keep the source call untouched; add the AE `track(...)` call immediately adjacent (before or after, matching surrounding style).
+- **Keep the two SDKs independent — in both directions.** Dual-write means two independent writes, for **every provider / every SDK** (Firebase, Amplitude, Sensors Data, Mixpanel, GA4, …), not a source-guarded AE write:
+  - The AE `track()` / `login()` / user-property / `setSuperProperties()` call must NOT be nested inside the source SDK's availability guard, early-return, or error path — e.g. after `if (!analytics) return`, behind `isSupported()`, or inside the source's `try/catch`. If the source call sits behind such a guard, lift the AE call out so it runs unconditionally.
+  - Give **each SDK its own `try/catch`** around its write: a source-SDK failure (unavailable, `isSupported() === false`, or a thrown error) must never suppress the AE write, and an AE failure must never suppress (or crash) the source write.
+  - The guard must cover the source SDK's **full failure surface, not a single exception type**. A pre-existing narrow catch (e.g. Python `except ValueError` for 400 validation, Java `catch (IllegalArgumentException)`) is **not** the independence guard — other failures (unconfigured API key → `RuntimeError`, network/timeout) still escape and crash before the AE write. Broaden the catch to all exceptions, run the AE write, then re-raise the source exception so the original status/error semantics (400/503) are unchanged.
+  - Give **each SDK's init its own `try/catch`** too, so that one SDK being unloaded or disabled at load time (init throws / module missing) does not take down the other SDK. Both writes must keep working no matter which SDK is unloaded or disabled.
+  - This applies to every `add` / `add_after` / `add_before` entry in mixed runs too.
+- Keep the source SDK dependency; only add the AE SDK dependency.
+
+**Async call sites** — a source call that is `await`ed (React Native / Flutter `await analytics().logEvent(...)`, some `await mixpanel.track(...)`) returns a Promise, but the AE client `track()` / `login()` / user-property / `setSuperProperties()` calls are synchronous:
+- **`switch`**: drop the `await` on the replaced call — awaiting a synchronous AE call is a lint warning and changes nothing. If the source call sat inside a `try/catch` whose `catch` handled the source SDK's **Promise rejection** (network retry, offline fallback, error reporting), that rejection branch dies with the source SDK: remove the now-dead `catch` logic; if the `try` block then holds only the AE call, collapse the `try/catch` into the bare AE call (AE sync failures then follow the code skill's Code Style — loud in `switch`). Never wrap the AE call in a made-up `async`/`await` to keep the shapes matching.
+- **`add`**: keep the source call's `await` and its `try/catch` exactly as-is, and place the AE call **outside** that block, un-`await`ed, in its own `try/catch` per the independence rule above.
+
+Both modes follow the code skill's insert rules: SDK init from the wiki main doc (never guess imports), git-status pre-check, batched Edit with language-style check, `// @tracking <event_name>` comment prefix.
+
+**User-property `append` / `unset`** (`ae_call` = `user_append` / `user_unset`): these two are not in the plan's `update_type` enum (only `user_set` / `user_setOnce` / `user_add` are), so they do not enter `draft.json` — in the draft their `update_type` is written `user_set` (placeholder). At code-insertion time, emit the AE SDK call directly per the mapping's `ae_call` (`user_append` → `userAppend`, `user_unset` → `userUnset`), reading the real method signature from the wiki main doc (never guess).
+
+**⚠️ `add` mode overrides the code skill's "Do NOT add try/catch" Code Style.** That rule is a single-SDK rule (greenfield insert / `switch` after cut-over): with one SDK a loud failure is the point, so init/track failures must surface rather than be swallowed. Dual-write is the opposite — the "each SDK its own `try/catch`" rule above applies to the generated AE code too:
+- The AE init must be guarded the same way (its own `try/catch` / availability check), so an AE-SDK load failure never throws at load time and never takes down the source SDK.
+- Never emit a load-time SDK capture that becomes a permanently-`undefined` reference and throws on every call (e.g. `var ta = window.TA;` in a wrapper) — a missing AE SDK must be a per-call no-op, not a crash of business logic or the source write.
+- `switch` mode does NOT get this override: after cut-over AE is the only SDK, so it follows the code skill's Code Style as-is (failures stay loud).
+
+## Phase 5 — Verify
+
+Reuse the code skill's validation flow:
+
+1. `ae-cli auth status` / confirm active host; debug device add/select.
+2. Trigger the migrated events and query `ae-cli tracking debug-data list`.
+3. In `add` mode, verify AE data alongside the still-running source SDK; in `switch` mode, confirm the source SDK is fully removed and AE data flows.
+
+## Modes
+
+| Mode | Source SDK kept? | AE call placement | Dependency change |
+|---|---|---|---|
+| `switch` | removed | replaces source call | remove source dep, add AE dep |
+| `add` | kept | added alongside | add AE dep only |
+
+Ask the user once in Phase 2 which mode to use. **Default to `add` (dual-write): present `add` as the recommended option in the confirmation prompt.** Treat `switch` as the non-default, destructive choice — offer it only when the user has explicitly expressed wanting a full cut-over, and never mark it recommended.
+
+**Staged / mixed runs**: `mode` is the run-level default, but each mapping entry carries its own `action` (`replace` vs `add_after`/`add_before`), and the per-entry `action` is authoritative. A `switch` run may still keep selected entries as `add_after` for a staged roll-out (e.g. cut over identity + sign-up now, keep `purchase` dual-writing while its data is validated). In that case: replaced files drop the source SDK, dual-write files keep it, and the source SDK dependency is removed **only** on a full cut-over (every entry `replace`). See `references/ir.md` §mapping.json and `mapping-framework.md` §8.
+
+> **⚠️ `switch` is destructive (high-risk)**: it deletes source tracking calls, their imports, and the source SDK dependency. Never delete old code by default. Before deleting anything, explicitly tell the user what will be removed (call sites + dependencies) and get their confirmation; re-confirm again at Phase 4 immediately before deletion, even if `switch` was already chosen in Phase 2.
+
+## Prohibitions
+
+- Guessing AE SDK imports/package names — always read the wiki main doc via `ae-generate-tracking-code` (`references/sdk-index.md`).
+- Modifying event/property names away from the AE plan (`snake_case`, registered names).
+- Migrating source SDK auto-track events as manual `track()` calls — map them to AE auto-track switches or drop them per the adapter.
+- Nesting the AE `track()` / `login()` / user-property calls inside the source SDK's availability guard, early-return, or `try/catch` in `add` mode, or leaving either SDK's init unguarded, or guarding the source write with a narrow exception-type catch that still lets a source failure crash before the AE write — for every provider, dual-write must stay two independent writes (each SDK its own `try/catch`, init included, covering the full failure surface), so one SDK failing or being unloaded never takes down the other.
+- Skipping the mapping summary confirmation in Phase 2.
+- Writing `user_append` / `user_unset` into `draft.json`'s `update_type` (the plan enum is `user_set` / `user_setOnce` / `user_add` only) — append/unset stay in `mapping.json` `ae_call` and are emitted directly at Phase 4.
+- Translating "Super Property" as "超级属性" in any user-facing output.
+- Writing source or AE code before the git-status pre-check (insert mode).
+- Editing the provider adapters to add provider-specific logic into the core — new providers are new adapter files only.
+- Deleting source tracking code or removing the source SDK dependency (`switch` mode) without explicitly warning the user and getting their confirmation immediately before deletion.
+
+## Internal Reference
+
+- `references/ir.md` — normalized IR schema (`scan.json` / `mapping.json`).
+- `references/mapping-framework.md` — provider-agnostic mapping algorithm.
+- `references/ae-preset-properties.md` — authoritative AE `#` preset-property list + system fields (only these `#` names ingest).
+- `references/providers/README.md` — adapter contract + how to add a provider.
+- `references/providers/firebase.md` — Firebase adapter.
+- `references/providers/amplitude.md` — Amplitude adapter.
+- `references/providers/sensors-data.md` — Sensors Data (神策) adapter.
+- `references/providers/mixpanel.md` — Mixpanel adapter.
+- `references/providers/ga4.md` — Google Analytics 4 (gtag.js / Measurement Protocol) adapter.

package/skills/ae-migrate-tracking-code/references/ae-preset-properties.md

@@ -0,0 +1,76 @@
+# AE Preset Properties & System Fields (authoritative)
+
+> **Terminology**: 预置属性 = preset property | 系统字段 = system field | 自动采集 = auto-track
+
+Source of truth: bundled AE wiki `wiki/te-docs/raw/preparations-before-data-ingestion/preset-properties-and-system-fields.md`
+(official doc: `https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=preset_properties`).
+
+> **Scope**: this skill switches the live SDK only; historical data import into AE is offline data-migration work, out of scope. This list is used here for two things: deciding drop-vs-keep on source preset/special properties, and preventing invalid or manual `#` writes.
+
+## Hard rules
+
+1. **Only the `#` names listed below ingest.** Any property whose name starts with `#` but is NOT in the preset-property table is an illegal field and is rejected at ingestion — it cannot be stored. Never invent a `#` name.
+2. **Look up each source preset/special property here to decide drop-vs-keep.** If an AE preset equivalent exists (Sensors `$os` → `#os`, `$ip` → `#ip`, `$url` → `#url`), **drop the source property and rely on AE auto-collect** — never re-add it as a custom property. If there is **no** equivalent in the list (`$is_first_day`, `mp_country_code`, `$current_url`), do NOT fabricate a `#` name — map it to a normal custom property (snake_case per `mapping-framework.md` §1) or drop it, and **surface the choice to the user for confirmation**.
+3. **Preset properties are SDK-provided.** Except `#ip`, do not set them manually — the AE SDK fills them automatically; manual setting is only done under AE staff guidance (multi-terminal consistency).
+4. **System fields are not event/user properties.** `#distinct_id`, `#account_id`, `#user_id`, `#event_name`, `#time` (and the partition fields) are data-structure fields; they cannot be used as event names or property names. Identity migration goes through `login()` / the visitor-id API (`mapping-framework.md` §4), never through a property.
+
+## Preset properties (48)
+
+| # name | Description | Type |
+|---|---|---|
+| `#ip` | Client-side IP (basis for geo parsing) | String |
+| `#country` | Country/region | String |
+| `#country_code` | Country code (ISO 3166-1 alpha-2) | String |
+| `#province` | Province | String |
+| `#city` | City | String |
+| `#os` | OS (Android, iOS, ...) | String |
+| `#os_version` | OS version | String |
+| `#manufacturer` | Device manufacturer | String |
+| `#device_id` | Device ID (iOS IDFV/UUID; Android androidID) | String |
+| `#device_model` | Device model | String |
+| `#device_type` | Device type | String |
+| `#screen_height` | Screen height | Number |
+| `#screen_width` | Screen width | Number |
+| `#app_version` | APP version | String |
+| `#bundle_id` | APP package/process name | String |
+| `#lib` | SDK type | String |
+| `#lib_version` | SDK version | String |
+| `#network_type` | Network type | String |
+| `#carrier` | Operator | String |
+| `#browser` | Browser | String |
+| `#browser_version` | Browser version | String |
+| `#duration` | Event duration (s) | Number |
+| `#url` | Page URL (auto-track) | String |
+| `#url_path` | Page path (`location.pathname`) | String |
+| `#referrer` | Referrer URL | String |
+| `#referrer_host` | Referrer host | String |
+| `#title` | Page title | String |
+| `#screen_name` | Screen name | String |
+| `#element_id` | Element ID (auto-track) | String |
+| `#element_type` | Element type | String |
+| `#element_selector` | Element selector / viewPath | String |
+| `#element_position` | Element position | String |
+| `#element_content` | Element content | String |
+| `#resume_from_background` | Resumed from background (bool) | Number |
+| `#scene` | Scenario value (mini-program launch) | Number |
+| `#mp_platform` | Mini-program platform | String |
+| `#app_crashed_reason` | Crash stack info | String |
+| `#zone_offset` | Timezone offset (hours vs UTC) | Number |
+| `#system_language` | System language (ISO 639-1) | String |
+| `#install_time` | APP install time | Date |
+| `#simulator` | Is simulator (bool) | Number |
+| `#ram` | Memory, e.g. `1.4/2.4` (GB) | String |
+| `#disk` | Storage, e.g. `30/200` (GB) | String |
+| `#fps` | Frames per second | Number |
+| `#background_duration` | Background duration (s) | Number |
+| `#start_reason` | Start reason (non-launcher mode) | String |
+| `#ua` | User-Agent info | String |
+| `#utm` | Ad-source info | String |
+
+## System fields
+
+Not usable as event/property names; listed for reference when reasoning about identity and partition fields.
+
+**Event table**: `$part_event` (partition, from `#event_name`), `$part_date` (partition, from `#event_time`), `#user_id`, `#account_id`, `#distinct_id`, `#event_name`, `#event_time` (= `#time` in the data), `#server_time`.
+
+**User table**: `#user_id`, `#account_id`, `#distinct_id`, `#active_time`, `#reg_time`, `#update_time`, `#server_time`.

package/skills/ae-migrate-tracking-code/references/ir.md

@@ -0,0 +1,167 @@
+# IR Schema (scan.json / mapping.json)
+
+> **Terminology**: 归一化中间表示 = IR (intermediate representation) | 调用点 = call site | 扫描结果 = scan result | 映射结果 = mapping result
+
+Migration artifacts live under `.ae-cli/migration/`. They are JSON, written by the skill at runtime and consumed by the two downstream skills.
+
+## scan.json — extracted call sites (Phase 1 output)
+
+```json
+{
+  "provider": "firebase",
+  "variant": "web-v9",
+  "platforms": ["web"],
+  "call_sites": [
+    {
+      "id": "cs-1",
+      "file": "src/app.js",
+      "line": 42,
+      "kind": "event",
+      "source_call": "logEvent(analytics, 'user_login', { method: 'phone' })",
+      "event_name": "user_login",
+      "params": { "method": "phone" },
+      "resolved": true
+    },
+    {
+      "id": "cs-2",
+      "file": "src/app.js",
+      "line": 18,
+      "kind": "identity",
+      "source_call": "setUserId(analytics, userId)",
+      "resolved": true
+    },
+    {
+      "id": "cs-3",
+      "file": "src/app.js",
+      "line": 25,
+      "kind": "user_property",
+      "source_call": "setUserProperties(analytics, { vip_level: 'gold' })",
+      "op": "set",
+      "prop": "vip_level",
+      "value": "gold"
+    },
+    {
+      "id": "cs-4",
+      "file": "src/app.js",
+      "line": 30,
+      "kind": "super_property",
+      "source_call": "setDefaultEventParameters(analytics, { app_version: '1.2.3', channel: 'web' })",
+      "props": { "app_version": "1.2.3", "channel": "web" }
+    }
+  ]
+}
+```
+
+- `kind` ∈ `event` | `identity` | `user_property` | `super_property`.
+- `via_wrapper` (optional, string): set on a call site resolved through an analytics wrapper function (see **Wrapper-layer resolution** below) — records the wrapper function's name. `kind` stays one of the three values above; a wrapper-resolved site is a normal call site with different provenance.
+- `identity` is a **client global setter** call site (`setUserId` / `identify` / `login`). Server SDKs pass identity **per event** (Amplitude Node `{ user_id }`, GA4 Measurement Protocol `user_id`, Mixpanel server `distinct_id`): record it as a `user_id` (and/or `device_id`) field on the **`event`** call site — `kind` stays `event`, there is no separate `identity` entry (Phase 2 maps it to the AE per-event `#account_id`, see `mapping-framework.md` §4).
+- `variant` is a **fixed SDK-variant token** (not the fixture/project directory name). Map the platform the adapter's Recognition section identified to one of:
+
+  | Provider | Variant tokens |
+  |---|---|
+  | firebase | `web-v8`, `web-v9`, `android`, `ios`, `flutter`, `react-native`, `unity`, `cpp` |
+  | amplitude | `legacy-js`, `browser-2.x`, `node`, `python`, `go`, `java`, `android`, `ios`, `react-native`, `flutter`, `unity` |
+  | sensors-data | `web`, `java`, `android` |
+  | mixpanel | `javascript` (browser JS), `node`, `python`, `go`, `java`, `ruby`, `php`, `android`, `ios` (incl. Swift), `react-native`, `flutter`, `unity` |
+  | ga4 | `gtag-web`, `datalayer`, `mp-server` |
+
+  New providers/platforms add their token to this table alongside their adapter. **Tokens name every documented platform, not only the tested ones** — only a subset has a regression fixture (see `test/ae-migrate-tracking-code/README.md` §Coverage). A token without a fixture is still valid: Phase 1 records it, and the mapping/naming rules apply unchanged.
+
+- `resolved` applies to `event` and `identity` entries:
+  - `event`: `true` whenever the event **name** is a known static value — a string literal, a constant resolved from the scanned source, or an external-SDK constant identifier (see the `event_name` rules below). `false` **only** when the event name itself is a runtime variable/expression that cannot be resolved to a static name (listed for user confirmation in Phase 2). Runtime **param values** (e.g. `{ amount: order.total }`) do **not** set `resolved: false` — they are recorded in `params` as the variable name and surfaced for *type* confirmation in Phase 2, not name confirmation. A name arriving as a **wrapper function's parameter** is resolved via wrapper-layer tracing (below) — business callers with a static name become `resolved: true` sites carrying `via_wrapper`; `false` is reserved for names that stay unresolved *after* tracing (dynamic names, or a wrapper with no findable callers).
+  - `identity`: always `true` — the id is a runtime value, and the mapping target (`login(accountId)`) does not require resolving the id's concrete value.
+- `event_name` records the name **as written in the scanned source**, and only resolves it when the value is visible in that source:
+  - a string literal is recorded verbatim (`"user_login"` → `user_login`; `"userLogin"` → `userLogin` — Phase 2 §1 naming conversion does the snake_case/normalization).
+  - a constant defined **in the scanned source** (e.g. `EVENT_SIGNUP = 'sign_up'`) is resolved to its value, still with `resolved: true` (the name is static).
+  - a constant from an **external SDK** whose value is not visible in the source (e.g. `FirebaseAnalytics.Event.SELECT_CONTENT`) is recorded as the identifier as written (`SELECT_CONTENT`), still with `resolved: true` — it is a static name, not a runtime variable. Do **not** resolve it against SDK documentation; the downstream §1 naming conversion (UPPER_SNAKE → snake_case) yields the correct AE name.
+  - **Expression shapes that are not a single static name** record `resolved: false` and are surfaced in Phase 2 for the user to expand:
+    - **Ternary / conditional** (`track(cond ? 'sign_up' : 'login', ...)`): the branches are static literals but the runtime value is one of several — it is **several distinct events, not one**. Record `event_name` as the expression text as written; in Phase 2 enumerate each static branch and ask the user which (possibly all) become separate AE events.
+    - **Template literal** (`` track(`click_${name}`) ``): the name is unbounded. Record the template as written; in Phase 2 ask the user whether it collapses to a finite set of names or becomes a base event + a `name` property.
+- `user_property` entries carry no `resolved` field. They record `op` (`set` | `setOnce` | `add` | `append` | `unset`, mapping to AE `user_set` / `user_setOnce` / `user_add` / `user_append` / `user_unset`) plus `prop` (the user property name) and `value` (the literal value, or the variable name when not resolvable).
+- `super_property` entries carry no `resolved` field. They record `props` (the full name → value map, like an `event`'s `params`; values may be variable names) — a third-party common-property call sets several properties at once (`register({...})` / `registerSuperProperties({...})` / `setDefaultEventParameters({...})`), so there is no single `prop`/`value` pair. Prop **names** are always static object-literal keys; only the **values** may be runtime variables. `super_property` sites map to AE common event properties (Phase 2 writes them into `draft.json`'s `common_event_properties` pool, Phase 4 emits `setSuperProperties({...})` in place).
+
+**Wrapper-layer resolution** — when an SDK call's event name is a **function parameter** (a runtime variable flowing from an enclosing function's argument), Phase 1 treats that function as an analytics wrapper and traces its callers instead of recording `resolved:false` up front. A discovered wrapper `F` (e.g. `trackEvent(name, props)` → `mixpanel.track(name, props)`) is recorded in the top-level optional `wrappers` array, **not** in `call_sites`:
+
+```json
+{
+  "wrappers": [
+    { "name": "trackEvent", "file": "src/analytics.js", "line": 4, "source_call": "mixpanel.track(name, props)", "delegates_to": "event" }
+  ]
+}
+```
+
+- `delegates_to` ∈ `event` | `identity` | `user_property` | `super_property` — the SDK call kind `F` forwards to; it is the `kind` inherited by `F`'s resolved business call sites.
+- The wrapper is the pivot for tracing, not a migration target: its own SDK call is not a `call_sites` entry. Each business caller becomes a normal call site carrying `via_wrapper`. `source_call` on those sites is the **caller's** invocation line (e.g. `trackEvent('sign_up', { method: user.method })`), which appears literally in the caller's file.
+
+## mapping.json — source site → AE event (Phase 2 output)
+
+```json
+{
+  "provider": "firebase",
+  "variant": "web-v9",
+  "mode": "switch",
+  "entries": [
+    {
+      "site_id": "cs-1",
+      "file": "src/app.js",
+      "line": 42,
+      "source_call": "logEvent(analytics, 'user_login', { method: 'phone' })",
+      "ae_event": "user_login",
+      "display_name": "User Login",
+      "platform": "client",
+      "ae_props": { "method": "string" },
+      "action": "replace"
+    },
+    {
+      "site_id": "cs-2",
+      "file": "src/app.js",
+      "line": 18,
+      "source_call": "setUserId(analytics, userId)",
+      "ae_call": "login(accountId)",
+      "account_id_source": "user_account",
+      "action": "replace"
+    },
+    {
+      "site_id": "cs-3",
+      "file": "src/app.js",
+      "line": 8,
+      "source_call": "getAppInstanceId()",
+      "ae_call": "setDistinctId(appInstanceId)",
+      "account_id_source": "none",
+      "note": "forward compatibility: visitor id set once at init, before any event",
+      "action": "replace"
+    },
+    {
+      "site_id": "cs-4",
+      "file": "src/app.js",
+      "line": 25,
+      "source_call": "setUserProperties(analytics, { vip_level: 'gold' })",
+      "ae_call": "user_set",
+      "ae_props": { "vip_level": "string" },
+      "action": "replace"
+    },
+    {
+      "site_id": "cs-5",
+      "file": "src/app.js",
+      "line": 30,
+      "source_call": "setDefaultEventParameters(analytics, { app_version: '1.2.3', channel: 'web' })",
+      "ae_call": "set_super_properties",
+      "ae_props": { "app_version": "string", "channel": "string" },
+      "action": "replace"
+    }
+  ]
+}
+```
+
+- `mode` ∈ `switch` | `add` — the run-level default, decided once per run in Phase 2.
+- `action` ∈ `replace` | `add_after` | `add_before` — set **per entry** and authoritative. `mode` is only the default an entry inherits; a `switch` run may still carry `add_after` entries (staged roll-out), and an `add` run may carry `replace` entries. The source SDK dependency is removed only on a full cut-over: `mode` = `switch` **and** every entry `action` = `replace`. A mixed run keeps the dependency — surviving `add_*` sites still call it.
+- Identity entries use `ae_call` (no `ae_event`): `login(accountId)` → `#account_id`; `setDistinctId(visitorId)` / `identify(visitorId)` → `#distinct_id` (forward compatibility, init-time, before any event); `logout()` from source `reset()` / `remove()`. `account_id_source` ∈ `user_account` | `none`.
+- Server event entries (identity rides per event) carry `account_id_source` (`user_account` → AE per-event `#account_id`, e.g. from the scan-side `user_id` field) **instead of** an `ae_call` — `login(accountId)` is client-only.
+- User property entries use `ae_call` (no `ae_event`): `ae_call` = the AE user API (`user_set` / `user_setOnce` / `user_add` / `user_append` / `user_unset`, per the adapter's operation table), and `ae_props` = the property-name → type map, exactly like an event entry (the scan-side `op` / `prop` / `value` are not carried over — `op` becomes `ae_call`, `prop` becomes the `ae_props` key, `value` is dropped from mapping and re-emitted as the literal in the migrated code).
+- Super property entries use `ae_call` (no `ae_event`): `ae_call` = `set_super_properties` (emitted as `setSuperProperties({...})` at Phase 4), and `ae_props` = the property-name → type map. The scan-side `props` map is dropped from mapping and re-emitted as the literal object in the migrated `setSuperProperties` call. These properties land in `draft.json`'s `common_event_properties` pool.
+
+## draft.json — AE plan (Phase 2 output, consumed by ae-generate-tracking-plan)
+
+Identical schema to `ae-generate-tracking-plan`'s draft: `meta` (sdk_integration_mode, client/server platform+language, user_identity, host/project_id as filled later) + `events[]` (each with `event_name`, `display_name`, `platform`, `prop_names`, `event_tag`, `source: "codebase"`) + `event_properties[]` / `common_event_properties[]` / `user_properties[]` pools. `source` must be one of the AE plan's `Source` enum values — events/properties extracted from existing tracking code use `"codebase"` (there is no `"migration"` source value).
+
+**`user_append` / `user_unset` are NOT in the plan's `update_type` enum** (that enum is `user_set` / `user_setOnce` / `user_add` only). A user property mapped to `user_append` / `user_unset` keeps that value in `mapping.json` `ae_call` (Phase 4 emits the SDK call directly) but its `draft.json` `update_type` is written as `user_set` (placeholder) — the plan records that the property exists, not the append/unset semantics.

package/skills/ae-migrate-tracking-code/references/mapping-framework.md

@@ -0,0 +1,112 @@
+# Mapping Framework (provider-agnostic)
+
+> **Terminology**: 映射 = mapping | 事件名 = event name | 属性 = property | 类型推断 = type inference | 去重 = dedup | 公共属性提升 = super-property promotion | 用户身份 = user identity | 蛇形命名 = snake_case
+
+This file is the generic algorithm. Provider differences live in `references/providers/<provider>.md`. The algorithm consumes `scan.json` (from Phase 1) and produces `mapping.json` + `.ae-cli/draft.json` (Phase 2).
+
+## 1. Event name → snake_case
+
+> **Naming policy — decide once per run**: ask whether historical source-platform data has been (or will be) imported into AE **offline** and must join with new SDK data. The offline import is outside this skill (data-migration implementation); this skill only switches the live SDK — it preserves names so new events join the imported data.
+>
+> - **Forward compatibility required** → preserve event / property / user-property names **verbatim** (AE matches names case-sensitively, so renaming splits the event stream). Transform a name only if it violates AE hard constraints (starts with a digit, contains characters outside `[A-Za-z0-9_]`, exceeds the length cap); any such transform must match the naming the offline import used (one shared mapping table — this skill produces it and applies it to the SDK code only).
+> - **Greenfield (no historical data)** → apply steps 1–7 below.
+
+**Special characters & reserved prefixes** (apply after the naming policy above):
+
+- **`$` prefix** (Sensors Data preset events/properties; Mixpanel special properties): SDK-provided, not custom. Preset properties → AE `#` preset properties; preset events → AE auto-track or drop (adapter's Auto-track decision table). Never rename `$name` into a custom `_name`. **Only map to `#` names in the authoritative list** (`references/ae-preset-properties.md`); a `$` property with no AE preset equivalent becomes a normal custom property (snake_case) or is dropped — never a made-up `#` name — and is surfaced to the user for confirmation.
+- **Other reserved prefixes** — Mixpanel `mp_`; Amplitude `[Amplitude]` (case-insensitive); Firebase/GA4 `_`, `firebase_`, `ga_`, `google_`, `gtag.`: cannot be custom names. Strip the prefix and flag for user confirmation (adapter §2).
+- **Any other special character** in a custom event / property / user-property name (space, `-`, `.`, brackets, etc.) violates the AE charset. Normalize it (replace with `_`, collapse repeats, strip) and **always surface the rename to the user for confirmation** — a wrong normalization silently changes the metric name.
+
+1. Apply the provider adapter's reserved-prefix/word rules (e.g. Firebase `firebase_`, `google_`, `ga_`; GA4 `_`, `gtag.`; Mixpanel `mp_`; Amplitude `[Amplitude]` — case-insensitive): strip the prefix and flag the rename for user confirmation. Do this **first**, before any other transform, so a prefix containing special characters (`gtag.`, `[Amplitude]`) is removed intact rather than mangled by step 5.
+2. Convert camelCase / PascalCase boundaries to underscores: `userLogin` → `user_login`, `SELECT_CONTENT` → `select_content`, `addPaymentInfo` → `add_payment_info`.
+3. Lowercase.
+4. Replace spaces and hyphens with underscores.
+5. Strip characters outside `[a-z0-9_]`; collapse repeated underscores.
+6. Ensure the result starts with a letter; if it starts with a digit, prefix `e_`.
+7. AE plan rules still apply: `snake_case`, non-empty `display_name` in the user's language, `event_tag` set per the plan skill conventions.
+
+## 2. Property type inference
+
+From the literal value at the call site (or the variable's usage when resolvable):
+
+| Observed value | AE type |
+|---|---|
+| integer / float | `number` |
+| `true` / `false` | `bool` |
+| string | `string` |
+| Date object (`new Date()`, a `Date` variable used directly) | `datetime` — inferred silently, unambiguous |
+| ISO-8601 string (e.g. `"2024-09-01T12:00:00Z"`, `"2024-09-01"`) | `datetime` — **flag for confirmation** (string shapes are ambiguous: `order_no: "20240901123"`, `version: "2024.1"` look identical) |
+| numeric field whose name suggests time (`*_time`, `*_at`, `*_ts`, `timestamp`, `*_date`) | `datetime` — **flag for confirmation** (name heuristic only; the field may be a duration or count) |
+| array of primitives (strings) | `array_string` |
+| plain object `{...}` | `object` |
+| array of objects `[{...}]` | `array_row` |
+| mixed | default `string`, flag as severe (see §3, rule 1) |
+| unresolved variable | infer from the property **name**: numeric-sounding names (`amount`, `price`, `total`, `cost`, `count`, `quantity`, `duration`, or any `*_count` / `*_num` / `*_sum`) → `number`; otherwise `string`. Flag for confirmation in Phase 2. |
+
+`datetime` is the only AE type inferred from a **shape/name heuristic** whose wrong guess silently drops or mangles data at ingestion. Every `datetime` inference except a literal `Date` object must therefore be **flagged for user confirmation in Phase 2**, exactly like `mixed` and `unresolved variable` above. Never silently assign `datetime` to a string or numeric field.
+
+Object spread in a property argument (`track('e', { ...baseProps, amount: 9.99 })`): infer the **visible** keys normally; the spread's keys are not visible at the call site. Record the visible keys, and flag the spread for Phase 2 confirmation — resolve `baseProps` to its definition where visible, otherwise ask the user what keys it contributes (and their types).
+
+Nested objects: `array_row` children use `parent.child` sub-property naming per the AE plan schema.
+
+## 3. Dedup and promotion
+
+1. Same property name across events must share one type; conflicting types → flag as severe (AE discards mismatched data), ask the user.
+2. A property appearing on **3 or more events** → promote to a common event property (super property). Rationale matches `ae-generate-tracking-plan`: business-wide global dimensions belong on every event.
+3. AE preset properties (`#` prefix, e.g. `#device_id`, `#os`) are never created or promoted; they are SDK-provided. Only names in the authoritative list (`references/ae-preset-properties.md`) are valid `#` properties — any other `#` name is rejected at ingestion, so never invent one. System fields (`#distinct_id`, `#account_id`, `#user_id`, `#event_name`, `#time`) are not properties at all.
+
+## 4. Identity mapping
+
+AE uses a three-ID model: `#distinct_id` (visitor ID, anonymous state), `#account_id` (account ID, logged-in state), and `#user_id` (backend-generated; derived from `#account_id` first, else `#distinct_id`). Map the source's two identity layers separately:
+
+| Source identity | AE target | How |
+|---|---|---|
+| Logged-in user id (`setUserId` / `identify` / `login`) | `#account_id` | client: `login(accountId)`; server: per-event `#account_id` param |
+| Anonymous/device id (auto `distinct_id` / `app_instance_id` / `client_id` / `device_id`) | `#distinct_id` | AE visitor-id API (`setDistinctId` / `identify`, name varies by SDK — read the wiki main doc), **only** when forward compatibility must match the imported `#distinct_id`; otherwise leave SDK-managed |
+| No identity call | `account_id_source = "none"` (guest) | leave visitor id SDK-managed |
+
+Rules:
+
+- Client SDKs expose a global setter → `login(accountId)` (account_id_source `user_account`). Server SDKs pass identity per event → per-event `#account_id` + account_id_source, **not** `login()`.
+- **Visitor-id timing**: `setDistinctId` / `identify` must run immediately after SDK init and **before any event is uploaded**; re-setting it after upload causes user-matching failures / duplicate users. It is a one-time startup call, unlike `login()`.
+- `reset()` / `remove()` (source) → AE `logout()` (clears account id, returns to visitor). `logout()` only on explicit sign-out / account deletion, never on app close.
+- `alias` (source anonymous→identified merge) → ignore; AE `login()` already merges visitor → account.
+- Group/role identifiers → `needs decision` (AE has no direct group concept).
+- **Forward compatibility**: the offline-imported `#distinct_id` and the SDK-set visitor id must be byte-identical for old and new data to join into one `#user_id`.
+
+## 5. User property mapping
+
+Use the provider adapter's operation table. Defaults:
+
+- overwrite intent → `user_set`
+- first-time-only intent → `user_setOnce`
+- numeric accumulate intent → `user_add`
+- array append → `user_append`
+- remove → `user_unset`
+- Property-name policy follows §1 (preserve verbatim when forward compatibility is required).
+
+`user_append` / `user_unset` are **code-level only**: the AE plan's `user_properties[].update_type` enum has only `user_set` / `user_setOnce` / `user_add`, so these two never enter `draft.json`. They stay in `mapping.json` `ae_call` and Phase 4 emits them directly as the AE SDK's `userAppend` / `userUnset` call (read the real API signature from the wiki main doc — never guess). In `draft.json` the property's `update_type` is written as `user_set` (placeholder).
+
+## 6. Super property (common event property) mapping
+
+Third-party common-property APIs attach properties to **every event** (they are event properties, never user properties): Mixpanel `register` / `registerSuperProperties`, Sensors Data `register` / `registerSuperProperties`, Firebase `setDefaultEventParameters`. Map them to the AE **static** common event property `setSuperProperties({...})`.
+
+- `register({k:v})` / `registerSuperProperties({k:v})` / `setDefaultEventParameters({k:v})` → `set_super_properties` (`setSuperProperties({...})` at Phase 4), and the properties land in `draft.json`'s `common_event_properties` pool (name / `display_name` / type / `source: "codebase"`), exactly like event properties.
+- **Overwrite semantics**: AE `setSuperProperties` overwrites the whole common-property set each call, while third-party `register` **accumulates**. If the source calls `register` multiple times at different points, merge them into a single `setSuperProperties` (or flag for user confirmation) rather than emitting several overwriting calls that would drop earlier keys.
+- **No 1:1 equivalent** → `needs decision`:
+  - Mixpanel `register_once({k:v})` — AE has no "first-write-wins" common property; `setSuperProperties` overwrites, so either accept the relaxed semantics or mark `needs decision`.
+  - Mixpanel `unregister('k')` — AE has no single-key removal; closest is one `setSuperProperties` with the remaining keys, or exclude the key in a dynamic super property; mark `needs decision`.
+- **AE dynamic common properties** (`setDynamicSuperProperties(fn)`, Android `setDynamicSuperPropertiesTracker`) have **no third-party equivalent** — do not map them from a source call. Offer them only as an optional enhancement when the source computes a common-property value at runtime per event (Phase 4, user decision).
+- Property-name policy follows §1 (preserve verbatim when forward compatibility is required); types follow §2.
+- Amplitude and GA4 have **no** common-property API — their `setUserProperties` / `gtag('set', 'user_properties', ...)` are **user** properties (§5), never super properties.
+
+## 7. Platform assignment (client / server)
+
+- Call site in app/frontend code (client SDK import) → `platform: "client"`.
+- Call site in backend code (server SDK import) → `platform: "server"`.
+- Same event logged from both → `platform: "both"` (timestamps must sync).
+
+## 8. Outputs
+
+- `mapping.json`: one entry per source call site — `{ site, source_call, ae_event | ae_call, ae_props, mode, action }`. Event entries carry `ae_event` + `ae_props` (property-name → type map); identity, user-property, and super-property entries carry `ae_call` instead of `ae_event`, and user-property / super-property entries still carry `ae_props` (the full schema is in `ir.md` §mapping.json). `mode` (`switch` | `add`) is the run-level default; the per-entry `action` (`replace` | `add_after` | `add_before`) is authoritative, so a staged/mixed run can diverge per entry — the source SDK dependency is removed only when `mode` = `switch` and every entry is `replace`.
+- `.ae-cli/draft.json`: the AE plan schema (`events` / `event_properties` / `common_event_properties` / `user_properties` + `meta`), identical to what `ae-generate-tracking-plan` produces, so its `tracking plan draft` / `validate` / `upload` commands consume it unchanged.