YNU-864: API Reference rebuild from api.yaml

[ihsraham]

Summary

This PR replaces the old 0.5.x-style API Reference with a v1 RPC reference sourced from docs/api.yaml in the Nitrolite repository.

Intent

• Make the docs API Reference reflect the canonical v1 RPC groups and method names.
• Give builders one page per RPC group, plus shared types and aggregated errors.
• Preserve a visible session_keys.v1 page as a reserved stub because the group exists in api.yaml but has no methods yet.
• Point 0.5.3 helper users toward the TypeScript compat SDK instead of leaving stale helper docs in the API Reference.
• Make the API Reference landing page explicitly distinguish the conceptual Protocol tab from the concrete wire-method catalogue, and steer app builders to official SDKs by default.

Files Touched

• docs/nitrolite/api-reference/index.md: new v1 RPC landing page, Protocol-vs-API orientation, SDK-first guidance, wire-envelope note, group index, compat redirect, and MCP lookup hint.
• docs/nitrolite/api-reference/types.md: shared schema field tables from docs/api.yaml.
• docs/nitrolite/api-reference/channels-v1.md: channels.v1 methods and home_channel_created event note.
• docs/nitrolite/api-reference/app-sessions-v1.md: app_sessions.v1 methods, including the app-registration prerequisite for create_app_session.
• docs/nitrolite/api-reference/apps-v1.md: app registry lookup and submit_app_version registration.
• docs/nitrolite/api-reference/user-v1.md: user balances, transactions, and allowances.
• docs/nitrolite/api-reference/node-v1.md: connectivity, config, and assets.
• docs/nitrolite/api-reference/errors.md: aggregated RPC errors and suggested user-facing handling.
• docs/nitrolite/api-reference/session-keys-v1.md: reserved stub for the empty session_keys.v1 group.
• docs/nitrolite/api-reference/app-sessions.md: removed old app-session helper reference, replaced by app-sessions-v1.md.

What Changed

• Removed old helper-oriented content such as legacy app-session message builders and VirtualApp framing.
• Added landing-page guidance explaining that Protocol covers the semantic model, while API Reference catalogs the concrete wire methods from docs/api.yaml.
• Promoted SDK-first guidance for @yellow-org/sdk, @yellow-org/sdk-compat, and github.com/layer-3/nitrolite/sdk/go, including why they are safer than hand-rolled RPC for most apps.
• Added H2 sections for every method currently defined in docs/api.yaml across channels.v1, app_sessions.v1, apps.v1, user.v1, and node.v1.
• Added request fields, response fields, declared errors, SDK wrapper notes, and example v1 RPC envelopes for each method.
• Linked application_not_registered recovery directly to apps.v1.submit_app_version.
• Documented the home_channel_created event while noting that async event notifications are reserved for a future protocol revision in the Interaction Model.

Validation

• git diff --check
• npm run build
• Verified all docs/api.yaml methods have an H2 section in docs/nitrolite/api-reference/.
• Verified legacy helper strings and 0.5.x framing are removed from the API Reference tree.
• Verified session_keys.v1 renders as a reserved stub.
• Local rendered check confirmed the API Reference sidebar ordering, app_sessions.v1#create_app_session, channels.v1#submit_state, and the SDK-first landing-page orientation load correctly.

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

Post-merge follow-up: add a CI drift check that fails if docs/api.yaml diverges from the rendered API Reference pages.

[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: 317b66b7-cd36-451f-b9cf-e244e3b6a0db

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-api-reference-rebuild

---

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 structural approach to the rebuild, but several fields are wrong or missing against api.yaml and need to be fixed before this lands.

[nksazonov]

Every comment addressed cleanly and completely. The field-name fix, missing pagination/metadata fields, optional-field notes, expanded examples, and the constraint documentation all landed exactly right. Great turnaround — ship it!