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

# RESTRUCTURE

# Docs restructure — learnings + plan

Synthesis of how **Bun, Next.js, and Resend** (all effectively Mintlify-shaped) build their docs, and the
plan to apply it here. This is the working spec for the restructure.

## What the three best-in-class docs do (converged)

1. **Tabs = reader intent, stated to the reader.** The tutorial / guide / reference triad:
   * **Learn in order** (Getting Started / tutorial), **look up a how-to** (Guides), **look up a fact**
     (Reference / Concepts / how-it-works). Next.js literally names them on the landing page.
2. **Drop numeric prefixes.** Order lives in `docs.json`, never in the slug. Slugs are hyphenated,
   keyword-rich topic/question phrases; the URL reads as a breadcrumb. Troubleshooting/FAQ slugs are the
   literal question (Resend: `/knowledge-base/how-do-i-avoid-gmails-spam-folder`).
3. **Answer-first page anatomy.** Front-matter `title` (H1) + a one-line `description` that *is the answer*
   (rendered as the subtitle + meta description; never repeated in the body). Then lead with value —
   an example, `<Steps>`, or a **decision table** — in the first screen. Self-contained, anchor-linkable
   H2s. "See X" / "Next steps" sign-off. No throat-clearing.
4. **Decision/summary table at the top** of any "several ways to do X" page (Next.js redirects page).
5. **"Good to know" callouts** for gotchas; dense cross-linking, no dead ends.
6. **Mintlify components** used purposefully: `<Steps>` (procedures), `<CardGroup>`/`<Card>` (landing
   routers + next-steps), `<Tabs>`/`<CodeGroup>` (variants), `<Accordion>` (FAQ / hide long secondary
   steps), `<Note>`/`<Warning>`/`<Tip>` callouts, `<Frame>` (screenshots), `<ParamField>` (reference).
7. **GEO:** `description` written as the answer; question-shaped titles/slugs; `llms.txt` index linked
   from the landing; each page also served as clean markdown. (We already generate `llms.txt` + `.md`.)

## Our new information architecture

Map our content onto the triad. Tabs in `docs.json`:

| Tab            | Dir (URL)   | What it is                                                                                                                                                                                                                                           |
| -------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Home**       | `index`     | Landing / router — cards + CTAs, not prose.                                                                                                                                                                                                          |
| **Guides**     | `platform/` | The **how-to library** — task-first "How to…" pages. Landing = the How-to index (`how-to`), then task groups (Setup, Keywords, Landing pages, Blog, Publish, Analytics, Compliance, Diagnose). *(Merges the old "How-to" + "Part 2 Platform" tabs.)* |
| **Concepts**   | `theory/`   | The Synscribe way of SEO/GEO — the "why / how it works."                                                                                                                                                                                             |
| **Playbooks**  | `sops/`     | SOPs for running accounts at scale (AM-facing).                                                                                                                                                                                                      |
| **Build docs** | (meta)      | Internal: plan, journal, conventions, gap register, mined sources.                                                                                                                                                                                   |

> Note on dir naming: the founder's example was `part-2-platform → platform`. I read that as "strip the
> `part-N-` prefix" and named the three sections `platform` / `theory` / `sops` (clean, no numbers), with
> intent-named **tabs** (Guides / Concepts / Playbooks). Easy to rename the dirs to `guides/concepts/…`
> if preferred.

## Slug scheme

* Dirs: `part-1-theory → theory`, `part-2-platform → platform`, `part-3-sops → sops`.
* Files: strip the numeric prefix. `2-0-2-working-across-clients → working-across-clients`,
  `1-4-serp-cliff → serp-cliff`, `3-1-onboarding-month-1 → onboarding-month-1`,
  `2-7-1-set-up-evaluator → set-up-evaluator`. `index.md` and `how-to.md` unchanged.
* Order is preserved by `docs.json` (explicit page arrays), not filenames.

## Page-anatomy template (applied to every page in the writing pass)

```
---
title: "How to <task>"          # the search query
description: "<one-line answer>"  # the answer, not a label; Mintlify renders it as the subtitle
part / audience / video / status / task / feature / persona / intent / keywords
---

<Answer paragraph: 1–3 sentences. The direct answer. Names the surface + Pi skill. Links onward.>
<Merge the old Answer box AND the old intro into THIS single lead — no duplication.>

## <first task-shaped H2>
...

**Next / Related:** …
```

* **No body `# H1`** (Mintlify renders the title). *(Already stripped from all pages.)*
* **No stacked intro** — one answer-first lead, not "Answer box" + a second intro paragraph that repeats it.
* Multi-option pages get a **decision table** up top. Gotchas go in `> **Good to know:**` callouts.

## Execution phases

1. **Slugs + IA** (mechanical, scripted, fully tested): rename dirs/files, rewrite all internal links,
   rebuild `docs.json` tabs, rebuild the `how-to` router. Verify: mint parse + internal links + anchors.
2. **Writing pass** (per-cluster subagents): apply the page-anatomy template; **reconcile the
   Answer-box/intro duplication**; add decision tables/callouts where they help; keep facts/prompts/videos.
3. **Audit**: browser-test every page (rendered, no dup title/body), independent judge, full link test
   (files + anchors) on the running site; fix everything found.