Rescoped on 2026-04-29

The original issue is still relevant, but the scope is narrower now because the docs already include an Offline-first Sync tutorial section with a generated tutorial landing page:

• /docs/tutorials/sync/getting-started/
• /docs/tutorials/sync/handling-conflicts/
• /docs/tutorials/sync/offline-first-patterns/

That tutorial work covers much of the missing conceptual Sync API explanation. This issue should now track the remaining navigation and API-category structure work.

Remaining Problem

1. User-related API categories still lack real overview pages

Generated endpoint categories such as Collections, Bookmarks, Notes, Users, Sync, etc. still mostly expand directly to endpoint pages. Developers do not get category-level pages explaining:

• what the category is for
• when to use it
• how its endpoints work together
• which tutorial or conceptual guide to read first

2. User-related API Introduction still does not explain the sync-first architecture

The User-related APIs Introduction currently covers access and pagination, but it does not orient developers around the Sync API, mutation headers, offline-first behavior, or when they should read the sync tutorial before implementing collections/bookmarks/notes workflows.

3. Sync still appears as a normal endpoint category

The standalone tutorial section helps, but the generated User-related API sidebar still leaves Sync inline with the other API categories. Sync should be easier to discover from the User-related API area, either by:

• linking the Sync category to the sync tutorial/overview
• moving Sync near the top of the User-related API categories
• adding an explicit overview page for Sync
• adding sidebar metadata/styling if supported cleanly

Acceptance Criteria

• User-related API Introduction links to the Sync tutorial and briefly explains why Sync matters for mutation-producing user workflows.
• Sync has a category-level overview path from the API sidebar, not only individual endpoint pages.
• Major User-related API categories have at least lightweight overview pages or generated-index descriptions that explain purpose and endpoint relationships.
• The implementation does not rely on stale generated MDX edits that will be overwritten by OpenAPI regeneration.