Maintaining these docs

This site has two layers:

Layer	Location	Source of truth
Guides	docs/guide/core/*, docs/guide/react/*, plus shared pages	Written by hand
API reference	docs/api/ (generated)	TSDoc on public exports + TypeDoc

Dual-track guides

Integrator docs are split by track:

Track	Path	Audience
Core	docs/guide/core/	Vanilla JS/TS via @swapped/connect-sdk
React	docs/guide/react/	Provider + hooks via @swapped/connect-sdk/react

Write track-specific pages (only that track’s code and steps). Keep the API reference shared. Shared guide topics (Formatters, Concepts) still live under both tracks with matching slugs so the Core / React toggle and sidebar stay available - put the canonical copy under docs/guide/core/… and <!--@include: …--> it from docs/guide/react/…. Wallet verification React pages are track-specific (hooks) but keep the same slugs as Core. Cross-track pages that do not toggle (guide/creating-a-session.md, guide/browser-requirements.md, guide/agents.md) stay at the docs/guide/ root. Stub pages at the old mixed paths (guide/getting-started.md, guide/react.md, guide/exchange-pay.md, guide/cash-app.md, guide/coinbase.md, guide/wallets.md, guide/wallet-verification.md) point readers to the new locations.

Top nav uses VitePress activeMatch so Core / React switch sidebars. Track pages also show a Core / React segmented toggle above the sidebar (docs/.vitepress/theme/TrackToggle.vue), which maps the current path after /guide/core|react/ to the other track (e.g. /guide/core/exchange-pay ↔ /guide/react/exchange-pay, /guide/core/wallets ↔ /guide/react/wallets, /guide/core/formatters ↔ /guide/react/formatters, and nested pages like /guide/core/coinbase/cooldown ↔ /guide/react/coinbase/cooldown).

Wallets, Coinbase, Exchange Pay, Cash App, Wallet verification, Formatters, and Client guide pages live under docs/guide/{core,react}/… with matching slugs so the track toggle stays aligned. Keep the same top-level sidebar order in both tracks (guideItems in docs/.vitepress/config.mts): Getting started, then track pages (Client, Session, payment flows, Events, Formatters, Concepts). Wallet verification is a second sidebar group (standalone product, not a Connect session). Then a divider, then shared pages (sharedGuideItems - Browser requirements, Creating a session).

React hook pages for Wallets, Exchange Pay, Cash App, and Coinbase are grouped under a Hooks parent in the React sidebar (…/hooks/). Keep matching docs/guide/core/{section}/hooks/index.md stubs so the Core / React toggle does not 404 - do not list those stubs in the Core sidebar. Do not move individual hook files into a hooks/ folder - slugs must stay shared with Core (wallets/availability, coinbase/connection, …).

Wallet verification examples live under example/ (wallets, coinbase) with matching slugs in both tracks. Coinbase is a first-class flow, not an optional add-on on the wallets walkthrough.

Commands

npm run docs:api     # regenerate docs/api from typedoc-entry/*
npm run docs:dev     # API + local VitePress server
npm run docs:build   # static site → docs/.vitepress/dist
npm run docs:preview # preview the production build

docs/api is gitignored; always run docs:api (or docs:dev / docs:build) before viewing the API section.

What to document

• Document symbols exported from src/index.ts, src/react/index.ts, src/format/index.ts, src/wallet-verification.ts, and src/react/wallet-verification/index.ts.
• Prefer TSDoc (@param, @returns, @example, @remarks) on public APIs.
• Keep internals unmarked or tagged @internal so they stay out of the reference.
• Entry wrappers for TypeDoc live in typedoc-entry/ (core, react, format, locales, wallet-verification, and wallet-verification-react modules).
• Group API reference entries with @group on the barrel re-exports in src/index.ts / src/react/index.ts / src/format/index.ts / src/wallet-verification.ts / src/react/wallet-verification/index.ts (Client, Payment Methods, Wallets, Exchange Pay, Cash App, Coinbase, Wallet Verification, Session, Events, Currency, Token, Numbers, etc.).