Reorganize the API reference and developer tools navigation

AGENTS.md

@@ -18,13 +18,31 @@ Vocs-powered documentation site for Tempo protocol. Use this guidance when creat
 ## Documentation IA and agent exports
 
 - `src/lib/docs-sections.ts` owns the section labels, landing routes, and route ownership; `vocs.config.ts` owns the sidebar within each section.
-- Primary sections: Get Started (`/get-started`), Accounts (`/docs/accounts`), Earn (`/docs/earn`), Routes (`/docs/routes`), Zones (`/docs/zones`), and Machine Payments (`/docs/agents`).
+- Primary sections: Get Started (`/get-started`), Accounts (`/docs/accounts`), Earn (`/docs/earn`), Routes (`/docs/routes`), Zones (`/docs/zones`), and Machine Payments (`/docs/agents`). Get Started also owns the SDK, CLI, wallet CLI, and server handler pages (`/docs/sdk`, `/docs/cli`, `/docs/wallet`, `/docs/server`) as its Tempo CLI and Tempo SDK sections.
 - Tempo EVM (`/docs/development`) covers wallets and signing keys, transactions, fees, TIP-20 Tokens, contracts, exchange, network details, nodes, protocol specifications, and changelog.
-- APIs & SDKs (`/docs/tools`) contains the API reference, SDKs, CLI, and wallet/server libraries. Partners (`/docs/partners`) contains third-party integrations.
+- API reference (`/docs/api`) is its own top-nav link, matching Console's "API Docs" link. Partners (`/docs/partners`) contains third-party integrations. The old APIs & SDKs hub (`/docs/tools`) redirects to `/docs/sdk`.
 - Keep Earn and Routes beta notices and the Zones limited-preview notice on their overview pages. The earlier `/docs/guide/private-zones` sandbox is a separate integration.
 - `SKILL.md` is the docs site's published skill. The installable plugin's skill lives in `tempoxyz/plugins`; update it separately when routing changes.
 - `src/lib/ai-docs.ts` and the Vite build hook generate `llms.txt`, `llms-full.txt`, Markdown section context, and the published skill from source. Never edit `dist` or `.vercel` copies by hand.
 - After changing navigation or exported components, build and run `pnpm check:markdown` to check content and IA coverage. Keep Markdown exports useful without interactive UI.
+- When a top-nav section is added, renamed, or removed, update its routing description in `src/lib/ai-docs.ts`, the routing table in `SKILL.md`, and the tests that name sections (`DocsHeader.test.ts`, `ai-docs.test.ts`, `ai-docs-dev.test.ts`, `markdown-output.test.ts`).
+
+### API reference sidebar
+
+- The sidebar comes from the `openapi` entry in `vocs.config.ts`: `intro` holds the API reference overview pages, and the endpoint sections come from the OpenAPI spec's `x-tagGroups`. Until the API repo's spec carries the grouping, `regroupApiTags` rewrites tags, merges, and groups as the spec loads.
+- Sections: API reference (overview, authentication, conventions, MCP server, all endpoints, FAQ), Accounts, Earn API, Routes API, Zones API, Data API, Console (in Console app order), and MPP last.
+- Put each guide inside the endpoint group it explains (for example, Fee payer › Guide) instead of listing it again at the top. Each page appears once in the sidebar.
+- Keep the API reference to API pages: endpoints, authentication, conventions, and API guides. Client libraries live under Get Started › Tempo SDK; the Tempo API client for TypeScript (`tapimo`) is at `/docs/sdk/typescript/api-client`.
+- A single-tag section renders its operations directly under the section header, so give that tag the section's name as its `x-displayName`.
+- When renaming or merging a tag, set `x-pagePath` to keep the existing URL; the display name otherwise changes the page path.
+- The `introFlat`, `hide`, `groupExtrasByName`, and `sectionExtras` sidebar options are local additions to vocs. Ship them through `patches/vocs@2.8.5.patch`, including their types, or upstream.
+
+### Moving, renaming, or removing pages
+
+- Add the redirect in `vocs.config.ts` and mirror it under `/developers` in `vercel.json`; `docs-routing.test.ts` enforces the mirror. Point older redirects at the final destination instead of chaining.
+- Repoint inbound links instead of relying on redirects: search `src/pages`, `src/lib/docs-link-cards.ts`, `src/lib/docs-setup.ts`, and `SKILL.md`.
+- Keep linked heading anchors working with `<span id="old-anchor" />` above the renamed heading.
+- Every page needs a sidebar home; `sidebar-coverage.test.ts` fails otherwise. Merge redundant pages into the canonical page and redirect, rather than keeping link-only pages.
 
 ## Source of Truth
 
@@ -38,6 +56,8 @@ Use repo-local sources first:
 - `src/snippets/` - shared MDX snippets and reusable reference content
 - `src/components/` - custom React/MDX components and interactive guide surfaces
 
+For the `tempo api` CLI, the source of truth is `tempoxyz/api`: `apps/cli/SKILL.md` and the commands in `src/cli/`. Do not document the internal `admin` commands.
+
 When documenting MPP concepts on Tempo, cross-check the relevant MPP docs or SDK references. Keep MPP protocol facts aligned with MPP, but write the page around the Tempo user journey.
 
 ## Commands
@@ -48,19 +68,39 @@ Use `pnpm`.
 - `pnpm build` - typecheck and build docs plus marketing site
 - `pnpm check` - run Biome format/lint with fixes
 - `pnpm check:types` - run TypeScript check
-- `pnpm test` - run Vitest tests
+- `pnpm test` - run Vitest tests (`vitest run --dir src`; a bare `vitest run` also picks up the Playwright `e2e/` files and fails)
 - `pnpm test:e2e` - run Playwright tests
 - `pnpm preview` - preview the production build
 
+### Dev server
+
+- Start `pnpm dev` once and keep it running. Do not stop or restart it between edits.
+- MDX pages, components, styles, and `src/lib` changes hot-reload. Refresh the page instead of restarting.
+- Vocs reads `vocs.config.ts` (sidebar, redirects, OpenAPI options) only at startup and does not watch it. Batch config edits, then restart once to check them.
+- Vite restarts the server by itself when a file imported by `vite.config.ts` changes, including `src/lib/ai-docs.ts` and `src/lib/docs-sections.ts`. Make all edits to those files in one pass.
+- Adding or deleting a page file also restarts the server, so routes stay current.
+- The first load of an API page parses the OpenAPI spec and can take a minute or two. Wait for it instead of restarting. If responses stay slow (20 seconds or more per page) after many edits, one restart clears it.
+- Check rendered pages with headless Playwright screenshots against the running server. Wait for React hydration before clicking sidebar controls.
+- If the server runs out of memory, start it with `NODE_OPTIONS=--max-old-space-size=16384`. Set `VITE_USE_HTTP=true` to skip the mkcert HTTPS setup, which needs sudo.
+
 Before finishing docs-only changes, run at least `pnpm check:types` when practical. Run `pnpm build` for config, component, routing, sidebar, or MDX structure changes. Run targeted tests for changed interactive components.
 
+## CLI pages
+
+- Title each page with just the command: ``# `tempo request` ``. Wallet subpages use ``# `tempo wallet` recipes``.
+- Order sections Usage → task sections or Examples → Commands → Flags → Related. `/docs/cli` covers Install, the commands table, agent setup, and common flags only; command-specific details stay on the command's page.
+- Show commands in `bash [Terminal]` code blocks with the flags in use. Write placeholders as `<UPPER_SNAKE>`, such as `<SERVICE_ID>`.
+- Tables: `Command | Description` lists each command once, without flag variants. `Flag | Description` details flags, with one `###` subsection per command on multi-command pages. Write flags as `-D, --dump-header <FILE>`, defaults as "Defaults to `X`.", and descriptions as sentences ending with a period.
+- Keep each command's flag table self-contained, even when commands share flags (`tempo download` and `tempo node` both take `--chain` and `--datadir`).
+
 ## Site styling rules
 
 - Import `style`/`variants` from `src/styles/recipes.ts` for layout recipes, `theme.ts` for semantic components, or `scoped.ts` for existing unlayered selectors. Do not import unrestricted helpers from `zyzz` or create component-local configs.
 - Use the shared `vars` exported by `theme.ts`, or configured token names. `contract.ts` owns spacing, typography, radius, border, and stacking scales; `palette.ts` owns colors. Add a token only for a reusable design decision.
 - `inherited.ts` is the reviewed bridge to existing Vocs, blog, terminal, and artwork CSS scopes. Its expressions must resolve on the styled element; do not hoist local CSS variables into root tokens.
 - An intentional one-off uses ` !custom` and a declaration-local `// design-exception: <specific reason>` comment. Native CSS keywords need no explanation. Prefer normalizing incidental values to the scale over adding exceptions.
 - Global styles and keyframes use explicit token references. Use token-based border/background longhands, logical properties, and explicit transition properties. Style interactive state through existing ARIA/data attributes or native `:checked`/`:disabled` selectors. Reserve DOM style writes for scroll locking, theme application, and named CSS-variable bindings for runtime measurements.
+- Linked inline code (for example, a command linked to its page) keeps the code style and shows its link on hover; see the `a[data-v]:has(> code:only-child)` rule in `globals.ts`.
 - `pnpm check` runs Biome plus the architecture policy and Zyzz Oxlint rules. `pnpm check:types` checks token/variant contracts, including negative fixtures. `pnpm build` also enforces the compiler contract. Keep all three passing; do not suppress errors or weaken helper mappings to make a new value fit.
 
 ## Project Structure

SKILL.md

@@ -13,17 +13,17 @@ All links below use the canonical docs mount at `https://tempo.xyz/developers`.
 
 | Section | Start here when the reader wants to… |
 | --- | --- |
-| [Get Started](https://tempo.xyz/developers/get-started.md) | Choose an integration, send a first test payment, get testnet funds, or connect a coding agent. |
+| [Get Started](https://tempo.xyz/developers/get-started.md) | Choose an integration, send a first test payment, get testnet funds, connect a coding agent, or find the SDKs and CLI. |
 | [Accounts](https://tempo.xyz/developers/docs/accounts.md) | Create accounts, connect wallets, read balances, send or receive payments, and reconcile customer deposits. |
 | [Earn](https://tempo.xyz/developers/docs/earn.md) | Choose a vault, deposit stablecoins, read positions, or withdraw. Earn is in beta; check access on the introduction page. |
 | [Routes](https://tempo.xyz/developers/docs/routes.md) | Accept cross-network deposits, quote transfers, or track delivery. Routes is in beta; check access on the introduction page. |
 | [Zones](https://tempo.xyz/developers/docs/zones.md) | Connect to a Zone and work with private balances, deposits, or withdrawals. Zones is in limited preview; check access on the introduction page. |
 | [Machine Payments](https://tempo.xyz/developers/docs/agents.md) | Pay for APIs, accept API payments, discover services, or integrate MPP. |
 | [Tempo EVM](https://tempo.xyz/developers/docs/development.md) | Build wallet support, manage signing keys, use transactions and fees, issue TIP-20 Tokens, deploy contracts, exchange stablecoins, run nodes, or read protocol specifications and changelog. |
-| [APIs & SDKs](https://tempo.xyz/developers/docs/tools.md) | Find the API reference, authentication, SDKs, CLI, and wallet or server libraries. |
+| [API reference](https://tempo.xyz/developers/docs/api.md) | Find Tempo API endpoints by product, authentication, Console management endpoints, JSON-RPC, and the indexer. |
 | [Partners](https://tempo.xyz/developers/docs/partners.md) | Find third-party wallets, bridges, RPC infrastructure, data services, and integrations. |
 
-Accounts covers application payment workflows; Tempo EVM covers the chain capabilities behind them. Routes covers cross-network movement. API reference belongs under APIs & SDKs; it supplements product guides.
+Accounts covers application payment workflows; Tempo EVM covers the chain capabilities behind them. Routes covers cross-network movement. The API reference supplements product guides with exact endpoints and schemas. SDKs and the CLI are under Get Started.
 
 Use current Zones pages before the earlier `/docs/guide/private-zones` sandbox walkthroughs. That sandbox uses a separate integration and does not establish which operations are available in the limited preview.
 

e2e/blog.test.ts

@@ -93,7 +93,7 @@ test('mobile blog articles share developer navigation and return to docs', async
   const menu = page.getByRole('dialog', { name: 'Documentation navigation', exact: true })
   await expect(menu).toBeVisible()
   await expect(menu.getByRole('button', { name: 'Close menu', exact: true })).toBeFocused()
-  await menu.getByRole('link', { name: 'Docs', exact: true }).click()
+  await menu.getByRole('link', { name: 'Tempo documentation', exact: true }).click()
   await expect(page).toHaveURL((url) => url.pathname === '/')
   await expect(page.getByRole('heading', { level: 1 })).toHaveText('Documentation')
   await expect(page.locator('body')).not.toHaveCSS('overflow', 'hidden')