docs(docs): add experience.js migration workflow

[Charles Hudson (phobetron)]

Summary

Adds the documentation workflow and guide set for migrating from experience.js to the Optimization SDK Suite.

This PR introduces:

• New migration-specific agent roles for legacy experience.js knowledge capture and migration guide architecture.
• A migration-aware source-verification path for existing guide verifier agents.
• An internal experience.js migration knowledge file.
• A migration guide recipe and migration blueprints for the supported migration paths.
• Eight public migration guides, routed from the guide index in a dedicated migration section.
• SDK knowledge updates for migration-relevant target behavior.
• guides:check coverage for migration blueprints.

What changed

Agent roles

Added new local agent adapters for both Codex and Claude:

• experience-js-migration-knowledge-author
• migration-guide-architect

Updated guide-source-verifier so migration guides can verify:

• legacy experience.js claims against migration knowledge and adjacent source for interface checks;
• Optimization SDK claims against existing SDK knowledge and local package types.

Migration knowledge

Added internal migration knowledge for experience.js, sourced from the adjacent experience.js checkout.

The knowledge captures migration-relevant legacy behavior including:

• package mapping from @ninetailed/* packages to Optimization SDK targets;
• React, Web, Next.js, Node, SSR, and ESR runtime surfaces;
• Contentful mapper and nt_* content-model assumptions;
• legacy Experience API client behavior;
• persistence keys and cookie identifiers;
• plugin, preview, privacy, analytics, and insights behavior;
• manual migration boundaries and unsupported one-to-one mappings.

Authoring workflow

Added a migration guide recipe and dedicated migration blueprints for:

• Contentful model migration
• Web SDK migration
• React Web migration
• Next.js migration path choice
• Next.js App Router migration
• Next.js Pages Router migration
• Node, SSR, and ESR migration
• Plugins and preview migration

The migration recipe and blueprints now encode reusable review learnings, including:

• content-model prerequisites before runtime rendering;
• first-verification expectations;
• config, consent, cookie, event, analytics, preview, and cache ownership;
• accepted and blocked event observability;
• runtime-specific consent routing;
• manual Node/Web cookie boundaries.

Public guides

Added public migration guides for the same eight paths and updated documentation/guides/README.md with a dedicated experience.js migration guides section.

The migration guide index now helps readers choose by:

• guide;
• legacy integration type;
• target path.

SDK knowledge

Extended SDK knowledge with target behavior needed by the migration guides:

• stateful flag-view tracking and manual trackFlagView();
• accepted eventStream payloads;
• blockedEventStream and onEventBlocked behavior;
• preview audience, variant, and inline-variable overrides;
• Web, React Web, and Next.js references for these migration-facing behaviors.

Validation

Extended scripts/validate-guide-authoring.ts so pnpm guides:check now validates migration blueprints as well as integration blueprints.

Migration blueprint validation now checks:

• required frontmatter;
• template heading conformance;
• Migration route and Section plan table shape;
• non-empty table cells;
• fact-source links;
• source and guide target resolution;
• local links and anchors;
• rendered migration guide section spine.

Review process

The guide set went through the intended staged workflow:

1. Legacy migration knowledge authoring.
2. Optimization SDK knowledge gap resolution.
3. Migration guide architecture.
4. Guide drafting.
5. Newcomer review.
6. Source verification.
7. Guide fix pass.

Review findings were resolved before final validation.

Validation

Ran:

pnpm exec eslint scripts/validate-guide-authoring.ts
pnpm guides:check
pnpm knowledge:check
pnpm lint
pnpm exec prettier --check <changed docs and agent files>

All passed.

[NT-3738]