@thinkingai/ae-cli 6.1.10 → 6.1.12

package/skills/ae-experiment-design/references/metric-readiness.md

@@ -0,0 +1,143 @@
+# Metric Readiness
+
+Use this checklist to decide whether a candidate metric can support an experiment decision.
+
+## Contents
+
+- Supported experiment metric contract
+- Preregistered planning policy
+- Evidence levels
+- Feasibility gates
+- Role selection
+- Common blockers
+- Required output
+
+## Supported experiment metric contract
+
+Use event metrics only. A platform enum or API field is not evidence that
+another metric kind is implemented in the report calculation path.
+
+Use only these event calculation codes:
+
+| Code | Calculation | User-level value | Planning type |
+| --- | --- | --- | --- |
+| `A101` | Triggered users | Whether each user triggered the event; compare group trigger rates | `proportion` |
+| `A100` | Total times | Each user's total event count; compare group user-level means | `continuous` |
+| `A201` | Days | Each user's distinct active-event days; compare group user-level means | `continuous` |
+| `A103` | Sum | Each user's sum of a numeric event property; compare group user-level means | `continuous` |
+| `A104` | Average | Each user's average numeric event-property value; compare group user-level means | `continuous` |
+| `A106` | Maximum | Each user's maximum numeric event-property value; compare group user-level means | `continuous` |
+| `A108` | Distinct count | Each user's distinct count of one event property; compare group user-level means | `continuous` |
+
+Require a numeric event property for `A103`, `A104`, and `A106`, and an exact
+event property for `A108`.
+
+The current report calculation uses a two-sided Z test for both planning
+types, returns p-value, lift, and a 95% confidence interval, and uses
+`p < 0.05` plus confidence-interval direction and goal direction to label a
+positive or negative significant result.
+
+## Preregistered planning policy
+
+Fix the family-wise significance level at `alpha=0.05`, the confidence level
+at `0.95`, and the test direction at two-sided to match current reporting.
+Use `power=0.80` as the explicit planning-policy default when the user does not
+provide power, and label its source as `policy_default`.
+
+Require the MDE before definitive planning. Record whether it is `relative` or
+`absolute` and whether the desired effect is an `increase` or `decrease`; never
+silently substitute a 5% lift. Require observed user-level standard deviation
+for continuous metrics; never substitute an assumed coefficient of variation.
+
+For one control and multiple treatments, treat each treatment-versus-control
+comparison as one member of the same family. Use Bonferroni planning:
+`alpha_per_comparison = 0.05 / number_of_treatments`. Return the family alpha,
+adjusted alpha, method, and comparison count. The current native report still
+labels significance with unadjusted `p < 0.05` and a 95% confidence interval,
+so use raw p-values against the preregistered adjusted threshold for the final
+decision and disclose that native-label mismatch.
+
+Use a minimum runtime of seven days and align recommendations to full weeks by
+default; permit explicit overrides when the decision context justifies them.
+When traffic is not fixed, evaluate absolute experiment-traffic candidates no
+greater than the verified layer capacity and choose the smallest candidate
+that reaches the sample target within the maximum runtime. If none is feasible,
+return the true duration at maximum available traffic and mark it infeasible;
+never truncate the duration to the maximum.
+
+Do not add ad hoc missing-value imputation, winsorization, truncation, or
+post-treatment exclusions. Use the exact platform metric definition and
+preregister any supported filtering or data-quality rule before the run.
+
+Call `calculate_experiment_plan.py` with `metric_type`, `baseline`, `mde`,
+`mde_type`, `effect_direction`, `allocations`, and `daily_eligible_units`.
+Pass `standard_deviation` for a continuous metric. Pass `experiment_traffic`
+when traffic is confirmed; otherwise pass `max_available_traffic` and
+optionally `traffic_candidates` to request a recommendation. `power`,
+`min_runtime_days`, `max_runtime_days`, and `align_to_full_weeks` may override
+their policy defaults. Do not pass `confidence_level` other than `0.95`.
+
+Do not create or recommend a metric outside this contract. If the requested
+business outcome cannot be expressed by one supported event calculation,
+state that it is unavailable and propose the closest valid event metric
+without representing it as equivalent.
+
+## Evidence levels
+
+Label every statement:
+
+- `verified`: supported by current `ae-cli` platform output;
+- `provided`: supplied by the user but not verified on the platform;
+- `assumed`: introduced for design or sensitivity analysis;
+- `missing`: required evidence is unavailable.
+
+Only `verified` or explicitly accepted `provided` evidence can support a final readiness decision.
+
+## Feasibility gates
+
+A metric is feasible only when all applicable gates pass:
+
+1. **Contract**: event, supported calculation code, required property, goal
+   direction, filters, and attribution window are explicit.
+2. **Source**: required events and properties exist or are supplied as a concrete schema.
+3. **Identity**: assignment, exposure, and outcome share a stable join path.
+4. **Ordering**: outcome is attributed after exposure or treatment activation.
+5. **Population**: pre-treatment eligibility and exclusions are reproducible.
+6. **Planning evidence**: baseline, MDE and its type and direction, eligible
+   daily units, verified layer capacity when recommending traffic, and—except
+   for `A101`—user-level standard deviation are available before a definitive
+   sample or duration calculation.
+7. **Stability**: collection and definition are not expected to change during the experiment.
+8. **Sensitivity**: the metric can plausibly respond to the treatment.
+
+Block or mark unverified when any required gate lacks evidence.
+
+## Role selection
+
+### Primary
+
+Choose one supported event metric closest to the hypothesis and decision.
+Confirm its calculation code and direction, then establish its baseline and
+minimum business-relevant effect. Do not calculate a definitive duration
+before the metric contract is confirmed.
+
+## Common blockers
+
+- missing exposure event or treatment-activation marker;
+- assignment uses `user_id` while outcomes only have `device_id`;
+- anonymous-to-login identity cannot be reconciled;
+- cross-device identity is unstable;
+- outcome precedes exposure;
+- denominator is filtered by post-treatment behavior;
+- event volume is too low;
+- metric definition or instrumentation changed during the run;
+- cross-platform events use incompatible identities or semantics.
+
+## Required output
+
+For each candidate, return:
+
+| Metric | Status | Event | Calculation | Property | Direction | Join identity | Window | Evidence | Reason or remediation |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+When blocked, give the smallest concrete instrumentation or identity change that would make the metric measurable.

package/skills/ae-experiment-design/references/platform-operations.md

@@ -0,0 +1,105 @@
+# Platform Operations
+
+Read this reference before any AE/TE platform interaction.
+
+## Hard boundary
+
+All platform operations must use `ae-cli`. Do not call raw APIs, use browser automation, query a database, invoke te-mcp, or fabricate a platform result.
+
+Use curated commands when their contract is known. Use the Capability Gateway for experiment capabilities that do not yet have a curated command:
+
+```bash
+ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]
+ae-cli capability inspect <capability-id> --project-id <id>
+ae-cli capability validate <capability-id> --input '<json-object>'
+ae-cli capability dry-run <capability-id> --input '<json-object>'
+ae-cli capability run <capability-id> --input '<json-object>'
+```
+
+Search and inspect before constructing input. Never guess capability IDs, fields, enums, resource IDs, or project IDs. Search with the narrowest useful terms, then inspect every plausible candidate.
+
+Use at most one normal pre-check:
+
+- use `validate` while correcting a complex nested payload;
+- use `dry-run` for the final request when execution impact or deletion risk must be reviewed;
+- do not routinely stack `validate`, `dry-run`, and `run`.
+
+## Host compatibility
+
+After every `ae-cli` invocation, inspect stderr and `_notice.host_compat`. If a notice exists, start the user-facing result with a version warning and reproduce its update command lines verbatim. A successful envelope does not cancel the notice.
+
+## Project gate
+
+When the user supplies a project ID, resolve it directly:
+
+```bash
+ae-cli project info get --project-id <id>
+```
+
+When the user supplies only a project name, search and disambiguate:
+
+```bash
+ae-cli project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
+```
+
+Reuse a project only when its ID and host were verified in the same continuous conversation. If multiple projects match, stop and ask the user to choose.
+
+## Metadata and metric evidence
+
+Use these curated reads when applicable:
+
+```bash
+ae-cli analysis-meta event list --project-id <id> --query "<event>" --fields '["event_name","event_desc","authentication_status"]' --limit 20 --offset 0
+ae-cli analysis-meta property list --project-id <id> --scope event --event-name "<event>" --limit 50 --offset 0
+ae-cli analysis-meta property list --project-id <id> --scope user --limit 50 --offset 0
+ae-cli analysis-meta metric list --project-id <id> --query "<metric>" --fields '["metric_id","metric_name","metric_desc","authentication_status"]' --limit 20 --offset 0
+```
+
+Use `ae-cli analysis-meta metric get` after list/search when the exact metric definition is required. Use `ae-cli analysis adhoc run|export` for historical baseline and eligible-traffic evidence, following the installed `ae-analysis` command reference. Do not infer a baseline from a metric definition.
+
+For metric creation, use the curated `ae-cli analysis-meta metric create`
+command only after the supported event-metric definition and calculation code
+are exact. Use `--validate` while fixing complex metric input. Do not create a
+metric from a prose-only definition.
+
+## Experiment capability discovery
+
+Discover, inspect, and select capabilities for the semantic operation. Typical search concepts include:
+
+- experiment list, get, draft save, readiness, conflict, submit, start, pause, end, delete;
+- Feature list, get, create, update;
+- layer or bucket list and available traffic;
+- experiment metric report, summary, trend, sample, group, or exposure.
+
+Catalog wording and capability IDs may differ by deployment. The inspected `input_schema`, `risk`, auth requirements, output contract, and supported dry-run behavior are authoritative.
+
+If search returns no supported capability, report `capability gap` and continue with an offline design. Do not convert an intended platform write into raw HTTP.
+
+## Experiment detail link
+
+After a successful experiment save or verified exact-match reuse:
+
+1. Read the actual `expId` from the successful `ae-cli` result; do not use a proposed input ID unless the inspected output contract confirms that the save preserved it.
+2. Prefer a canonical detail link returned by the inspected capability output contract.
+3. When the result contains the actual `expId` but no link, use the verified relative frontend route:
+
+```text
+/#/atlas/experiment/detail?expId=<actual-expId>&currentProjectId=<actual-projectId>
+```
+
+The user-facing response must render this as a Markdown link with a localized label. Do not put it in a code block, output it as bare text, add a `{domain}` placeholder, or construct it when either verified ID is missing.
+
+## Risk and lifecycle policy
+
+- `read`: execute after project and target resolution.
+- `write`: execute when it is directly requested and inputs are exact.
+- `high-risk-write`: dry-run the final input, summarize target and impact, wait for a later explicit confirmation, then execute unchanged input with `--yes`.
+
+Regardless of catalog risk, require a separate explicit confirmation before submitting, starting, changing live traffic, pausing, ending, or deleting an experiment. A request to design or create a draft is not authorization to launch.
+
+## Envelope handling
+
+- `ok: true` with empty data is a successful empty result.
+- `ok: true` with `meta.partial: true` is partial success; preserve `meta.failures`.
+- `ok: false` is failure; preserve error code, message, request ID, invocation ID, stage, and failures.
+- Do not retry an unchanged failed request.

package/skills/ae-experiment-design/references/sdk-index.md

@@ -0,0 +1,76 @@
+# Experiment SDK Documentation Index
+
+Read this reference before giving exact experiment-SDK versions, dependencies, packages, imports, or API calls.
+
+## Source policy
+
+- Bundled references contain a concise extract for common questions.
+- The local official Wiki is preferred for exact version-specific APIs when it contains the relevant main page.
+- If the Wiki mirror is missing an experiment page, use the verified official source below and label the local mirror gap.
+- Recheck document version and update date before generating production code.
+- Do not use a page merely because a link label says it is an SDK page; verify its title and content.
+
+## Experiment SDK matrix
+
+Verified from the official Feishu pages on 2026-07-26:
+
+| Platform | Experiment SDK | Analytics dependency | Remote Config dependency | Main source |
+|---|---:|---:|---:|---|
+| Android | `TDExperiment` 1.0.1 | `TDAnalytics` >= 3.3.6 | `TDRemoteConfig` >= 1.3.0 | `CQ83wzJjui88V1keGtNcKLxgnXb` |
+| iOS | `TDExperiment` 1.0.2 | `ThinkingSDK` >= 3.1.6 | `TDRemoteConfig` >= 1.3.1 | `RlYIwkcvXizJeFkhp2acbWGwnFf` |
+| JavaScript | experiment package 1.0.0 | `TDAnalytics` >= 2.6.0 | `TDRemoteconfig` >= 1.3.0 | `GlR8w2bFbiJKqUka03pcJEdnndf` |
+
+Official source pages:
+
+- Client SDK overview: `https://thinkingdata.feishu.cn/wiki/MCy3w6eKjihQsmkZWSQcNlrQnie`
+- Android experiment SDK: `https://thinkingdata.feishu.cn/wiki/CQ83wzJjui88V1keGtNcKLxgnXb`
+- iOS experiment SDK: `https://thinkingdata.feishu.cn/wiki/RlYIwkcvXizJeFkhp2acbWGwnFf`
+- JavaScript experiment SDK: `https://thinkingdata.feishu.cn/wiki/GlR8w2bFbiJKqUka03pcJEdnndf`
+
+## Remote Config dependency matrix
+
+| Platform | Remote Config version | Minimum OS | Main source |
+|---|---:|---:|---|
+| Android | 1.3.0 | Android 4.0 / API 14 | `Lsdmwhhigi9Z3AkKs2fc9tw3nEd` |
+| iOS | 1.3.1 | iOS 9.0 | `K85DwZetDidpMPkGHWhccKQGnUf` |
+| JavaScript | 1.3.0 | Not stated in the verified page | `Yg3uw8RDii2WEskhz2Qc4zOanwg` |
+
+Official source pages:
+
+- Android Remote Config: `https://thinkingdata.feishu.cn/wiki/Lsdmwhhigi9Z3AkKs2fc9tw3nEd`
+- iOS Remote Config: `https://thinkingdata.feishu.cn/wiki/K85DwZetDidpMPkGHWhccKQGnUf`
+- JavaScript Remote Config: `https://thinkingdata.feishu.cn/wiki/Yg3uw8RDii2WEskhz2Qc4zOanwg`
+
+## Local Wiki discovery
+
+The runtime mirror is expected under:
+
+```text
+~/.ae-cli/wiki/te-docs/
+├── index.md
+├── synthesis/
+└── raw/
+```
+
+Before reading a local experiment page:
+
+1. Check whether `index.md` exists.
+2. Search the index and `raw/` for `experiment`, `TDExperiment`, `remote config`, `配置中心`, and `实验`.
+3. Choose the latest main page, not a historical/versioned copy.
+4. Read synthesis for orientation and raw for exact API details.
+
+At the verification date, the local mirror used to build this reference did not contain experiment or Remote Config pages. Do not assume this remains true after a Wiki refresh.
+
+## Known source conflict
+
+The client SDK overview page labels `AvX7wAp0zix522kSy9BcBziMnJd` as the JavaScript Remote Config document, but that token currently resolves to a Data Platform Release Note. The JavaScript experiment page links to `Yg3uw8RDii2WEskhz2Qc4zOanwg`, which resolves to the verified JavaScript Remote Config 1.3.0 document.
+
+Use `Yg3uw8RDii2WEskhz2Qc4zOanwg` until the overview page is corrected. If either page changes, verify the title, SDK version, and API content again.
+
+## JavaScript spelling warning
+
+The verified JavaScript experiment page spells the global object `TDExpriment`. This may be an SDK export name or a documentation typo. Copy it only after checking the downloaded package or a newer verified main document. Do not silently “correct” it to `TDExperiment`, and do not ship the documented spelling without verification.
+
+## Unsupported exact-code cases
+
+The supplied official pages do not establish an exact server-side experiment SDK or server evaluation API. For server or hybrid implementation, follow the architecture references and use pseudocode until `ae-cli` or verified server documentation resolves a concrete API.

package/skills/ae-experiment-design/references/sdk-integration.md

@@ -0,0 +1,114 @@
+# Experiment SDK Knowledge and Execution Router
+
+Read this reference only when the user explicitly asks about an A/B experiment SDK, client experiment SDK integration, experiment SDK code, or SDK troubleshooting.
+
+Do not read or apply this reference for a normal experiment-design, Feature-design, sample-size, readiness, or draft-creation request. An experiment requiring a product change does not by itself authorize or trigger SDK work.
+
+Examples that activate this reference:
+
+- “How do I integrate the Android experiment SDK?”
+- “Generate the client SDK code for this experiment.”
+- “Why does the experiment SDK always return the default?”
+
+Examples that do not activate it:
+
+- “Create an experiment for a blue versus green button.”
+- “Design the groups and traffic for this Feature.”
+- “Create an experiment draft.”
+
+## Four-layer architecture
+
+Use the following layers for different jobs:
+
+1. **Skill workflow** — `SKILL.md` enforces the explicit SDK activation gate; this reference classifies the request as knowledge, client integration, project-bound generation, or generic data integration.
+2. **Bundled references** — concise experiment contracts, platform notes, and troubleshooting answers. Read only the files required by the request.
+3. **Local official Wiki** — use the synced official documentation for exact packages, imports, signatures, and version-specific behavior that is not covered by references.
+4. **Dedicated generation capability** — use an inspected `ae-cli` capability to combine a real project, Feature, experiment, and SDK type into project-bound code.
+
+References supply knowledge. A generation capability supplies project context and execution. Do not substitute one for the other.
+
+## Request decision
+
+| User intent | Route |
+|---|---|
+| “How does automatic exposure work?” | `experiment-sdk-contract.md` + `exposure-contract.md` |
+| “How do I initialize Android/iOS/JS experiment SDK?” | `sdk-index.md` + `client-experiment-sdk.md`; consult the local Wiki main page when exact code is required |
+| “Should assignment happen on client or server?” | `experiment-sdk-contract.md` + the matching client/server/hybrid reference |
+| “Why do I always get the default?” | `sdk-troubleshooting.md`, then the verified platform main document |
+| “Generate code for this project/experiment” | `platform-operations.md` + this reference; resolve real assets and use a dedicated inspected capability |
+| “How do I call track/user_set or configure LogBus?” | Route to `ae-data-integration-helper` |
+
+## Documentation source order
+
+For SDK knowledge, search in this order:
+
+1. Read the matching bundled reference.
+2. If `~/.ae-cli/wiki/te-docs/index.md` exists, inspect it and the most relevant document under `synthesis/`.
+3. Read the latest main document under `~/.ae-cli/wiki/te-docs/raw/`; ignore historical or versioned pages unless the user explicitly targets that version.
+4. If the local mirror is absent or incomplete, use the verified official online document listed in `sdk-index.md`.
+
+You may also use:
+
+```bash
+ae-cli tracking wiki search "experiment SDK"
+ae-cli tracking wiki search "remote config"
+```
+
+Treat an empty search as a documentation gap, not proof that the product has no capability.
+
+Do not hardcode a guessed Wiki path. Verify that an indexed local path exists before reading it. If the local page and bundled reference disagree, prefer the newer verified main document and disclose the conflict.
+
+## Exact-code gate
+
+Emit exact imports, packages, classes, methods, configuration keys, defaults, and version requirements only when all of the following are known:
+
+- SDK platform and language;
+- exact or compatible SDK version;
+- verified main documentation;
+- client, server, or hybrid ownership;
+- assignment identity and Feature value type.
+
+Otherwise provide architecture-level pseudocode and a verification checklist.
+
+Application SDKs consume published configuration and report exposure or outcome events. They must not read or mutate AE platform configuration.
+
+## Project-bound generation
+
+For a request tied to a real project:
+
+1. Resolve the project through `ae-cli`.
+2. Resolve the exact experiment and Feature; do not accept a name-only guess.
+3. Confirm target platforms and versions.
+4. Search the Capability Gateway for experiment SDK sample generation.
+5. Inspect every plausible capability and its input schema.
+6. Validate or dry-run once when needed, then run the selected capability.
+7. Return only artifacts and metadata present in the successful response.
+
+Do not assume a proposed name such as `generate_experiment_sdk_sample` exists. If no dedicated capability is available, say so and provide a project-independent template with placeholders; do not call it generated project code.
+
+## Required integration contract
+
+Every SDK deliverable must define:
+
+- architecture: client, server, or hybrid;
+- initialization and dependency order;
+- assignment identity and identity transitions;
+- Feature key, value type, and typed default;
+- fetch, cache, timeout, stale-value, and retry behavior;
+- point where the assigned behavior becomes effective;
+- automatic or manual exposure ownership;
+- outcome event and identity join;
+- debug/test procedure;
+- acceptance checks.
+
+Configuration retrieval is not exposure. Do not record exposure when the assigned behavior was never applied.
+
+## Generic integration boundary
+
+Do not duplicate generic SDK ingestion material here. When `ae-data-integration-helper` is bound, use it for:
+
+- analytics SDK initialization unrelated to experiment ordering;
+- `track`, user properties, identity APIs, and data validation;
+- upload failures, LogBus, REST, and collection logs.
+
+If it is not bound, answer the experiment-specific portion and state that the generic integration dependency is unavailable.

package/skills/ae-experiment-design/references/sdk-troubleshooting.md

@@ -0,0 +1,139 @@
+# Experiment SDK Troubleshooting
+
+Read this reference for retrieval, default, assignment, exposure, cache, or debug problems. Resolve the exact project and Feature through `ae-cli` when the diagnosis depends on platform state.
+
+## Collect first
+
+Ask only for missing facts:
+
+- platform and SDK versions;
+- app ID and environment, without requesting secrets;
+- Feature key and expected type;
+- assignment identity before and after login;
+- automatic or manual exposure mode;
+- fetch callback or full error;
+- whether the value was fetched, applied, and exposed;
+- whether the issue affects all users, one test user, or one group.
+
+## Symptom routing
+
+### Always receives the default
+
+Check in order:
+
+1. analytics initialized before experiment SDK;
+2. experiment, analytics, and Remote Config versions meet `sdk-index.md`;
+3. app ID and server environment match the target experiment;
+4. startup or explicit fetch succeeded;
+5. Feature key and getter type match the platform Feature;
+6. assignment identity is established before evaluation;
+7. targeting and experiment traffic include the test identity;
+8. custom bucket and custom fetch parameters match the verified contract;
+9. cached or local default is not masking a remote miss.
+
+Do not treat a successful SDK initialization as proof that a Feature value was fetched.
+
+### Value changes unexpectedly
+
+Check:
+
+- identity transition after login;
+- account or role switching;
+- mid-session fetch;
+- cache isolation by identity and environment;
+- platform configuration changes;
+- client and server evaluating independently;
+- stale value replacement policy.
+
+Freeze the value at the intended decision boundary when mid-session changes are not part of the product design.
+
+### No exposure
+
+Check:
+
+- `automaticExposureTracking` is enabled when automatic mode is intended;
+- the typed getter was actually called;
+- the assigned behavior was applied;
+- manual mode calls the platform’s verified exposure operation at activation;
+- analytics upload and identity are healthy through `ae-data-integration-helper`;
+- the exposure/report window has completed.
+
+### Duplicate exposure
+
+Check:
+
+- automatic and manual modes are not both active;
+- render loops or repeated getters;
+- retries without an application deduplication scope;
+- client and server both reporting;
+- route changes or component remounts;
+- account switching.
+
+### Wrong group or cross-platform mismatch
+
+Check:
+
+- custom bucket ID values on every platform;
+- pre-login and post-login identifiers;
+- string normalization and missing values;
+- project and environment;
+- client/server cache keys;
+- experiment traffic and targeting;
+- whether one side falls back to control while the other evaluates treatment.
+
+## Fetch and callback checks
+
+Verified client pages provide:
+
+- startup fetch success/failure callbacks;
+- explicit `fetch`;
+- custom fetch parameters;
+- experiment logging.
+
+Capture the exact callback code and message. Do not retry an unchanged invalid request. Separate transport failure, configuration absence, targeting exclusion, type mismatch, and control assignment.
+
+## Defaults and Remote Config
+
+Verified Remote Config pages define:
+
+1. remote value;
+2. local default;
+3. empty when neither exists.
+
+For experiment behavior, also keep an application-owned typed control default. Confirm which layer produced the observed value.
+
+## Debug and test mode
+
+The verified Remote Config pages state that client debug mode pulls test strategies every five seconds and requires a selected or added test device. This is a test-mode Remote Config behavior, not a production experiment polling guarantee.
+
+Platform notes:
+
+- Android Remote Config uses debug mode in `TDSettings`.
+- iOS Remote Config uses `TDSDKModeDebug` and can enable logs.
+- JavaScript Remote Config uses `mode: "debug"` and `enableLog`.
+- Experiment SDK pages expose experiment logging separately.
+
+Disable or production-harden debug behavior before release.
+
+## Generic SDK problems
+
+Route these to `ae-data-integration-helper` when available:
+
+- analytics event upload failure;
+- user identity API usage;
+- `track` or user-property syntax;
+- data delay and ingestion validation;
+- LogBus, REST, or collection logs.
+
+Keep the experiment diagnosis focused on assignment, Feature retrieval, defaults, activation, and exposure.
+
+## Diagnostic output
+
+Return:
+
+- observed evidence;
+- likely stage of failure;
+- competing explanation;
+- exact next `ae-cli` or product check;
+- remediation if confirmed;
+- unresolved documentation or capability gap.

package/skills/ae-experiment-design/references/server-experiment-sdk.md

@@ -0,0 +1,78 @@
+# Server Experiment Architecture
+
+Read this reference when assignment, Feature evaluation, or behavior execution belongs on a backend service.
+
+## Evidence boundary
+
+The verified client documentation does not establish an exact AE server experiment SDK, package, endpoint, or method. Do not invent one.
+
+Before exact implementation:
+
+1. Resolve the real project, experiment, Feature, and assignment unit with `ae-cli`.
+2. Search and inspect the Capability Gateway for server experiment evaluation or SDK generation.
+3. Read verified server documentation if returned by the platform or provided by the user.
+4. Use architecture-level pseudocode until the API contract is verified.
+
+## Recommended server contract
+
+```text
+evaluateExperiment(
+  project,
+  featureKey,
+  stableAssignmentId,
+  context
+) -> {
+  value,
+  valueType,
+  assignmentOrGroupId,
+  configVersion,
+  source,
+  evaluatedAt
+}
+```
+
+The field names above describe an application contract, not a verified AE API schema.
+
+## Server responsibilities
+
+- derive a stable assignment ID before evaluation;
+- evaluate once per request, session, or product-defined decision boundary;
+- apply a typed control default on timeout or unavailable configuration;
+- preserve assignment consistency across replicas and regions;
+- prevent cache keys from mixing projects, environments, Features, or identities;
+- expose enough internal metadata to diagnose assignment without leaking it to end users;
+- emit or authorize exposure only when treatment becomes effective;
+- report outcomes with a joinable identity.
+
+## Cache policy
+
+Define separately:
+
+- configuration cache;
+- per-identity assignment cache;
+- response or page cache.
+
+Do not cache a personalized treatment under a shared response key. Include environment, project, Feature key, and assignment identity in any evaluation cache key unless the verified SDK guarantees safe internal caching.
+
+## Failure policy
+
+- timeout or transport failure: use typed control default;
+- invalid value type: reject the value and use control;
+- unknown Feature: fail closed to control and alert;
+- stale configuration: use only within the approved stale window;
+- identity missing: either use a documented anonymous assignment or control; never generate a new unstable ID per request.
+
+## Exposure ownership
+
+If the server fully executes the behavior, server exposure may be appropriate. If the server only sends a variant and the client decides whether it is rendered, client exposure is usually the truthful point.
+
+Choose one owner and read `exposure-contract.md`.
+
+## Verification checklist
+
+- Same identity returns a stable value across replicas.
+- Control fallback is safe and typed.
+- Cache isolation prevents cross-user treatment leakage.
+- Exposure reflects effective behavior, not evaluation alone.
+- Client and server do not both report the same exposure.
+- Outcome identity joins to assignment and exposure.