> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> Structures SDK and API guides around when developers use hooks, classes, functions, and methods. Use when writing or editing integration guides, hook guides, client reference pages, or when the user asks for use-case-first docs, "when to use," prerequisites, or Usage/Returns sections like the Web SDK hooks page.

# SKILL

# Guide writing: use-case-first structure

When authoring or refactoring **guides** and **developer-focused reference intros** (not replacing full API autogen), organize content so readers see **when** to use something before **how** it is spelled in code.

## When to use this skill

* New or rewritten pages for **hooks**, **providers**, **classes**, **client methods**, or **functions** in Suki docs (`web-sdk/`, `headless-web-sdk/`, `mobile-sdk/`, etc.).
* User asks for guides "like **hooks**," "**when to use**," "**common use cases**," "**Usage** / **Returns**," or developer-journey copy.
* Turning a dry API list into a **task-oriented** page without dropping `ResponseField` blocks, types, warnings, or examples.

## Do not assume

* **Use cases must match the repo:** Link to Quickstart, migration guides, or types pages that already describe the behavior. Do not invent product flows, required fields, or event names that are not documented on this site or in the same file.

## Recommended page shape

Use this order (adapt headings to sentence case per [STYLE\_GUIDE.md](../../../STYLE_GUIDE.md) and [documentation-style](../documentation-style/SKILL.md)):

1. **`## Overview`** (or keep existing title if the page is hook-specific)\
   One or two short paragraphs: what the hook/class/function **lets the developer do** in product terms (React-friendly vs JS client, session vs auth, etc.).

2. **`### Prerequisites`** (or merge into Overview if very short)\
   What must already be true: provider tree (`SukiProvider`, `PlatformClientProvider`), credentials, prior step in a workflow (e.g. session id from another hook), feature flags if documented.

3. **`### Common use cases`**\
   Bullets with **bold labels** mapping **developer tasks** to **specific members** (`init`, `setPartnerToken`, `on`, etc.). Each bullet should point to a **guide or type** page when the detail lives elsewhere.

4. **Optional `<Tip>`**\
   Only for facts already in the repo (migrations, defaults, gotchas). No speculative tips.

5. **`##` + symbol name** (e.g. `## useSuki hook`, `## useAuth hook`)
   * **`### Usage`:** Short instruction plus minimal code sample (how to call it).
   * **`### Returns`:** One paragraph: what object or tuple is returned and **where** the full shape is documented below (link to `##` section anchor for ResponseFields / "What you get").
   * **Diagrams / flow:** Keep existing mermaid or steps; prefer a **`###`** subheading (e.g. "How authentication resolves") so Usage stays scannable.

6. **Detailed reference below**\
   Preserve **`ResponseField`**, type blocks, `<Warning>`, `<Note>`, code examples, and **Next steps**. Do not delete reference blocks to "simplify"; only reorder or add intros.

## Reference examples in this repo

* Web SDK hooks reference pattern: [web-sdk/api-reference/hooks.mdx](../../../web-sdk/api-reference/hooks.mdx)
* Headless hooks (same idea, three guides): [auth-hook.mdx](../../../headless-web-sdk/guides/hooks/auth-hook.mdx), [ambient-hook.mdx](../../../headless-web-sdk/guides/hooks/ambient-hook.mdx), [ambient-session-hook.mdx](../../../headless-web-sdk/guides/hooks/ambient-session-hook.mdx)

## Checklist before finishing

* [ ] Overview answers **what it lets you do** without repeating the entire reference.
* [ ] **Common use cases** tie tasks to **named** API members, with links to existing docs.
* [ ] **Usage** + **Returns** are short; deep detail remains in later sections.
* [ ] No new product claims; cross-links or same-page fields are the source of truth.
* [ ] Style: sentence case headings, no em dashes, Oxford comma, per documentation-style skill.