YNU-864: Compat layer correctness + cookbooks

[ihsraham]

Summary

This PR updates the TypeScript compat SDK docs for apps migrating from @erc7824/nitrolite@0.5.3 to the v1 runtime through @yellow-org/sdk-compat. It also adds a Build examples page with deployed apps, screenshots, source links, and stack/SDK notes.

Intent

• Make the compat migration path accurate against the public @yellow-org/sdk-compat and native @yellow-org/sdk surfaces.
• Replace stale codemod instructions with the current public layer-3/yellow-sdk-codemod source workflow.
• Keep MCP-assisted migration marked as coming soon until @yellow-org/sdk-mcp is published.
• Give builders a quick examples index for deployed Nitrolite apps they can inspect and compare.

Files Touched

• docs/nitrolite/build/sdk/typescript-compat/overview.mdx: compat package purpose, installation, quick start, amount units, supported surface, and limits.
• docs/nitrolite/build/sdk/typescript-compat/migration-overview.mdx: codemod flow, MCP coming-soon note, client construction, migration matrix, and manual migration review areas.
• docs/nitrolite/build/sdk/typescript-compat/migration-onchain.mdx: deposits, withdrawals, channel operations, native fallback guidance, and amount handling.
• docs/nitrolite/build/sdk/typescript-compat/migration-offchain.mdx: auth helpers, app sessions, transfers, ledger queries, EventPoller, and typed error handling.
• docs/nitrolite/build/sdk/typescript-compat/event-poller.mdx: polling bridge for migrated server-push event handlers.
• docs/nitrolite/build/sdk/typescript-compat/errors.mdx: typed compat errors and recovery recipes.
• docs/nitrolite/build/examples.mdx: new Build examples index for Co-Sign Checkout, Nitrolite Store, and Nexus P2P Transfer.
• static/img/nitrolite/examples/*.png: captured front-page screenshots for the examples cards.
• src/css/custom.css: horizontal examples-card layout and centered screenshot media frames.

What Changed

• Documented the codemod as git clone, npm install, npm run build, and node dist/cli.js because the npm package is not published yet.
• Added a compact MCP-assisted migration preview without tool-specific commands that would not run before publication.
• Clarified compat amount rules: deposits and withdrawals use raw token-unit bigint, transfers use raw asset-unit strings, app-session allocations use human-readable decimal strings, and direct native SDK calls use Decimal.
• Reworked the migration overview, on-chain guide, and off-chain guide around the actual compat API behavior.
• Made the compat limits explicit, including unsupported server-push events and fail-fast checkpointChannel(...).
• Added EventPoller and errors/recovery cookbooks for the parts migrated apps still need to handle manually.
• Added a top-level Build examples page with live demo links, source repos, functionality summaries, stack notes, SDK packages, and visible screenshots.

Validation

• git diff --check
• npm run build
• Local browser check for /nitrolite/build/examples in dark mode.
• Live example URLs returned HTTP 200 for Co-Sign Checkout, Nitrolite Store, and Nexus P2P Transfer.
• npm view @yellow-org/sdk-mcp version currently returns 404, so the MCP flow remains labeled coming soon.
• Checked that the docs do not use the unpublished npm codemod command, fake sandbox hostnames, or human-readable transfer amounts where raw asset units are required.
• GitHub verifies the latest commit signature as valid.

The docs build still reports existing warnings from versioned 0.5.x and Clearnet contract docs. This PR does not add compat-page broken links or anchors.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f3a655fc-8762-45ff-8719-74de5ef46bfe

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ynu-864-compat-correctness-cookbooks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nksazonov]

Good job! The migration content is clear and the amount-unit clarifications are a meaningful correctness improvement. A few code snippets in errors.mdx reference methods that aren't in the documented compat surface (getTokenBalance, getOpenChannels) and have a missing import — these will cause copy-paste failures and should be fixed before landing.

[nksazonov]

Every comment addressed — clean turnaround. The compat docs are in great shape now: accurate API surface, correct amount units, real import paths, typed enum for channel status, and a solid examples index. Ship it! 🚀