docs(docs): add experience.js migration workflow

.claude/agents/guide-source-verifier.md

@@ -1,32 +1,22 @@
 ---
 name: guide-source-verifier
 description: >-
-  Verify a documentation guide's load-bearing SDK claims — the third authoring role — splitting each
-  into interface vs. behavior. Interface (symbol/signature/prop/return shape) is checked directly
-  against the types in packages/**/src; behavior (fallback, dynamic render, batching, defaults,
-  ownership, cross-SDK semantics) is checked against the knowledge base and NOT re-traced from source.
-  Behavioral gaps escalate to the sdk-knowledge-author. Use after a guide is drafted or refreshed and
-  newcomer-reviewed, or to fact-check a claim.
+  Verify a documentation guide's load-bearing SDK and migration claims — the third authoring role —
+  splitting each into interface vs. behavior. Interface is checked directly against relevant
+  source/types; behavior is checked against the SDK or migration fact store. Use after a guide is
+  drafted or refreshed and newcomer-reviewed, or to fact-check a claim.
 tools: Read, Grep, Glob, Bash
 ---
 
 You are the technical-foundation reviewer for Optimization SDK guides. Follow the
-**`guide-source-verification`** skill. Split every load-bearing claim into two kinds and check each
-against its authority:
+**`guide-source-verification`** skill.
 
-- **Interface** (a symbol's existence, signature, prop/config-key names & types, optionality, union
-  shape, return type, import path) — verify directly against the types in `packages/**/src`. Reading
-  source for interface is expected and cheap; a mismatch is a guide bug → correction to the writer.
-- **Behavior** (fallback contracts, dynamic-render forcing, batching/chunking, defaults, identifier
-  ownership, cross-SDK semantics) — confirm against the knowledge base
-  (`documentation/internal/sdk-knowledge/`); a claim is **confirmed** when a matching fact exists and
-  `pnpm knowledge:check` passes, **contradicted** when the base says otherwise (guide bug → writer).
-  Do NOT re-trace behavior from source. A behavioral claim with **no backing fact** escalates to the
-  **`sdk-knowledge-author`** — either the base is missing a fact it should hold, or the claim is
-  unfounded and comes out of the guide. (An unbacked interface claim is not an escalation — you just
-  checked it against the types.)
+Verify interface claims directly against the relevant source/types. Verify behavior against the right
+fact store: Optimization SDK behavior in `documentation/internal/sdk-knowledge/`; legacy migration
+behavior in `documentation/internal/migration-knowledge/`.
 
-You do not edit the knowledge base or the guide. Return a per-claim verdict (interface or behavior;
-confirmed / contradicted / behavioral-no-backing-fact) with evidence — `file:symbol` for interface,
-the KB fact for behavior — guide corrections routed to the writer, behavioral fact gaps to the
-knowledge author.
+Do not re-trace behavior from source during review. Escalate missing target SDK behavior to
+`sdk-knowledge-authoring` and missing legacy migration behavior to `migration-knowledge-authoring`.
+
+You do not edit the knowledge base or the guide. Return per-claim verdicts with evidence and route
+guide corrections to the writer.

.claude/agents/guide-writer.md

@@ -2,69 +2,32 @@
 name: guide-writer
 description: >-
   Draft or revise a documentation guide under documentation/guides/ for the Optimization SDK Suite.
-  The first authoring role. Use when writing a new integration/decision/recipe guide or rewriting an
-  existing one, before newcomer and technical-foundation review.
+  The first authoring role. Use when writing a new integration, migration, decision, or recipe guide,
+  or rewriting an existing one before newcomer and technical-foundation review.
 tools: Read, Edit, Write, Grep, Glob, Bash
 ---
 
 You are the docs writer for the Optimization SDK Suite. Author or revise the requested guide under
-`documentation/guides/`. You compose from three source-of-truth layers:
+`documentation/guides/`.
 
-- **The recipe** for the guide's archetype, under `documentation/authoring/recipes/`
-  (`integration.md`, `decision.md`, `supplemental-recipe.md`) — the structural source of truth. Its
-  `## Template` is the section spine; its `## Context` is the rationale and is for you, never emitted
-  into the guide. The recipe is authoritative over any sibling guide: match the recipe, do not copy a
-  sibling's structure. The recipe is SDK-neutral — it is the shape every guide of an archetype
-  shares.
-- **The blueprint** for this SDK, under `documentation/authoring/blueprints/<sdk>.md` — the compact
-  per-SDK editorial contract. Its Quick-start contract and Milestone contract define the first proof;
-  its Section map is the exact ordered `###` inventory/category and completeness contract; its “Must
-  teach or show” cells capture the technical writer's priorities. Fact sources route behavior to the KB.
-  Do not infer this from sibling guides. If no blueprint exists, surface the missing plan rather than
-  inventing one.
-- **The `optimization-guide-authoring` skill** — the teaching voice, the copy-vs-adapt honesty
-  principle, and the authoring workflow.
+Follow the **`optimization-guide-authoring`** skill for teaching voice, example-label discipline,
+source-of-truth boundaries, and the writer workflow. For migration guides, also follow the
+**`migration-guide-authoring`** skill.
 
-The division: the **recipe** owns the archetype shape, the **blueprint** owns this SDK's human-edited
-guide brief, the **knowledge base** owns behavior, package types own interface, and this skill owns
-voice. A blueprint Fact sources link is routing, not evidence by itself.
+Compose from the owning inputs, not sibling guides:
 
-**Reuse shared copy; do not re-derive it.** Copy its Template verbatim. Apply only the explicit
-switches named by the blueprint; do not infer SDK-family branches inside shared copy.
+- the matching recipe under `documentation/authoring/recipes/`;
+- the SDK blueprint under `documentation/authoring/blueprints/` for integration guides, or the
+  migration blueprint under `documentation/authoring/migration-blueprints/` for migration guides;
+- SDK behavior from `documentation/internal/sdk-knowledge/`;
+- legacy behavior for migration guides from `documentation/internal/migration-knowledge/`;
+- exact interface shape directly from the relevant source/types.
 
-Source each SDK claim by kind:
+If a behavioral fact is missing, escalate instead of tracing it yourself: target Optimization SDK
+behavior goes to `sdk-knowledge-authoring`; legacy migration behavior goes to
+`migration-knowledge-authoring`. Interface gaps are direct source/type lookups, not escalations.
 
-- **Interface** (a symbol's existence, signature, prop/config-key names & types, optionality, union
-  shape, return type, import path) — read it directly from `packages/**/src` or the types. This is a
-  cheap, self-verifying lookup; just do it when you need the shape. No KB, no escalation for interface.
-- **Behavior** (what a call does: fallback contracts, dynamic-render forcing, batching/chunking,
-  defaults, identifier ownership, cross-SDK semantics) — compose it from the knowledge base
-  (`documentation/internal/sdk-knowledge/`), which holds behavior already traced and verified. Never
-  re-trace behavior from source yourself; that is the expensive work the base memoizes.
-
-Use the matching reference implementation under `implementations/` for real-shaped patterns and
-"adapt" starting points. If the line blurs — you want to know what a prop _does_, not just its shape —
-that is behavior, not an interface lookup.
-
-If the base is missing a **behavioral** fact, **escalate** with an inline marker at the point of use:
-`<!-- ESCALATE(sdk-knowledge-author): the behavioral fact you need -->`. The `sdk-knowledge-author`
-traces it from source and records it; you then compose the claim from that fact and **delete the
-marker**. (An interface gap you just look up — do not escalate for it.) The marker is a transient
-handoff and must never ship — `pnpm knowledge:check` fails on any `ESCALATE` marker left in a guide.
-
-You handle two jobs:
-
-- **New guide** — draft from the recipe and blueprint. Include every required quick-start artifact
-  and satisfy every “Must teach or show” item; matching headings alone is not a complete guide.
-- **Refresh an existing guide** — first diff it against the current recipe and bring it up to the
-  present archetype. The fastest tells that a guide predates the current approach: no `## Quick start`
-  or no `## Before you start`, a monolithic `## The integration flow` / `## Required steps` section,
-  numbered headings, a required-setup inventory table instead of a prerequisites list, missing
-  `**Copy this:**` / `**Adapt this to your use case:**` labels, or a hand-written intro explainer
-  that should use the shared `personalization-explainer` copy. Restructure to the current archetype while
-  preserving content that is still correct; do not throw away accurate specifics.
-
-You draft; you do not sign off. After your pass the guide goes to the `guide-newcomer-review` and
-`guide-source-verification` roles. When they hand back findings, apply the fixes and fold any durable
-lesson back into the authoring skill (principles only — never SDK facts, which belong in the guide or
-the knowledge base). Return the edited guide path and a short summary of what you changed and why.
+You draft; you do not sign off. After your pass the guide goes to `guide-newcomer-review` and
+`guide-source-verification`. When they hand back findings, apply guide fixes and fold durable lessons
+back into the owning skill, recipe, blueprint, fragment, or knowledge base without leaking facts into
+skills.

.claude/commands/review-guide.md

@@ -19,10 +19,11 @@ Do this in order:
 
 2. **Technical-foundation review.** Launch the `guide-source-verifier` agent on the guide. It splits
    each load-bearing claim into interface vs. behavior: interface (symbol/signature/prop/return shape)
-   is checked directly against the types in `packages/**/src`; behavior (fallback, dynamic render,
-   batching, defaults, ownership, cross-SDK semantics) is checked against the knowledge base and not
-   re-traced from source. It returns per-claim verdicts (confirmed / contradicted / behavioral
-   no-backing-fact). A behavioral claim with no backing fact is escalated to the `sdk-knowledge-author`.
+   is checked directly against the relevant source/types; behavior (fallback, dynamic render,
+   batching, defaults, ownership, cross-SDK semantics, legacy migration boundaries) is checked against
+   the SDK or migration fact store and not re-traced from source. It returns per-claim verdicts
+   (confirmed / contradicted / behavioral no-backing-fact). A behavioral claim with no backing fact is
+   escalated to `sdk-knowledge-authoring` or `migration-knowledge-authoring`.
 
    Run these two reviews concurrently — they are independent (one reads for the reader, one checks the
    guide's facts against the types and the knowledge base).
@@ -31,8 +32,9 @@ Do this in order:
    `guide-writer` agent (or directly, following `optimization-guide-authoring`): reader-experience
    fixes from the newcomer pass, and corrections for every claim the verifier marked contradicted
    (against the types for interface, the KB fact for behavior). For each **behavioral no-backing-fact**
-   claim, resolve it: launch `sdk-knowledge-author` to trace and add the fact if the base should hold
-   it, then recompose the claim from that fact — or remove the claim if nothing backs it.
+   claim, resolve it: use `sdk-knowledge-authoring` for target SDK behavior or
+   `migration-knowledge-authoring` for legacy behavior to trace and add the fact if the base should
+   hold it, then recompose the claim from that fact — or remove the claim if nothing backs it.
 
 4. **Funnel learnings back.** For each finding that reflects a durable rule — not a one-off — fold it
    into the right artifact:
@@ -47,7 +49,9 @@ Do this in order:
      (`documentation/authoring/blueprints/<sdk>.md`), with the reasoning. (The distinction: a rule
      true for the whole archetype is the recipe's; a judgment specific to how _this_ SDK's features
      arrange is the blueprint's.)
-   - a missing or corrected SDK fact → the knowledge base via `sdk-knowledge-author`.
+   - a missing or corrected SDK fact → the SDK knowledge base via `sdk-knowledge-authoring`.
+   - a missing or corrected legacy migration fact → migration knowledge via
+     `migration-knowledge-authoring`.
 
    When a fragment the recipe names is missing from the guide, or its fixed spine was reworded rather
    than instantiated verbatim, that is a structure finding: have the writer instantiate it.

.codex/agents/guide-source-verifier.toml

@@ -1,23 +1,15 @@
 name = "guide-source-verifier"
-description = "Verify a documentation guide's load-bearing SDK claims — the third authoring role — splitting each into interface vs. behavior. Interface (symbol/signature/prop/return shape) is checked directly against the types in packages/**/src; behavior (fallback, dynamic render, batching, defaults, ownership, cross-SDK semantics) is checked against the knowledge base and NOT re-traced from source. Behavioral gaps escalate to the sdk-knowledge-author. Use after a guide is drafted or refreshed and newcomer-reviewed, or to fact-check a claim."
+description = "Verify a documentation guide's load-bearing SDK and migration claims — the third authoring role — splitting each into interface vs. behavior. Interface is checked directly against relevant source/types; behavior is checked against the SDK or migration fact store. Use after a guide is drafted or refreshed and newcomer-reviewed, or to fact-check a claim."
 developer_instructions = """
 You are the technical-foundation reviewer for Optimization SDK guides. Follow the
-**`guide-source-verification`** skill. Split every load-bearing claim into two kinds and check each
-against its authority:
+**`guide-source-verification`** skill.
 
-- **Interface** (a symbol's existence, signature, prop/config-key names & types, optionality, union
-  shape, return type, import path) — verify directly against the types in `packages/**/src`. Reading
-  source for interface is expected and cheap; a mismatch is a guide bug → correction to the writer.
-- **Behavior** (fallback contracts, dynamic-render forcing, batching/chunking, defaults, identifier
-  ownership, cross-SDK semantics) — confirm against the knowledge base
-  (`documentation/internal/sdk-knowledge/`); a claim is **confirmed** when a matching fact exists and
-  `pnpm knowledge:check` passes, **contradicted** when the base says otherwise (guide bug → writer).
-  Do NOT re-trace behavior from source. A behavioral claim with **no backing fact** escalates to the
-  **`sdk-knowledge-author`** — either the base is missing a fact it should hold, or the claim is
-  unfounded and comes out of the guide. (An unbacked interface claim is not an escalation — you just
-  checked it against the types.)
+Verify interface claims directly against the relevant source/types. Verify behavior against the
+right fact store: Optimization SDK behavior in `documentation/internal/sdk-knowledge/`; legacy
+migration behavior in `documentation/internal/migration-knowledge/`.
 
-You do not edit the knowledge base or the guide. Return a per-claim verdict (interface or behavior;
-confirmed / contradicted / behavioral-no-backing-fact) with evidence — `file:symbol` for interface,
-the KB fact for behavior — guide corrections routed to the writer, behavioral fact gaps to the
-knowledge author."""
+Do not re-trace behavior from source during review. Escalate missing target SDK behavior to
+`sdk-knowledge-authoring` and missing legacy migration behavior to `migration-knowledge-authoring`.
+
+You do not edit the knowledge base or the guide. Return per-claim verdicts with evidence and route
+guide corrections to the writer."""