> ## 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.

# How-to library plan

> Turn the training docs into a navigable, SEO/GEO-shaped library of short how-to entries — grounded in the agentic-discovery playbook and the real codebase.

**What this is:** the plan to evolve `docs/training/` from a linear three-part curriculum into a
**navigable, jump-between library of short, SEO/GEO-friendly how-to entries** — each answering one
"How do I do X with my software / my AI?" question, concise, cross-linked, and (where useful) paired
with a short how-to video.

**What this is not:** a rewrite. Parts 1–3 are strong and stay. We add a **how-to layer on top of
them** and re-shape titles/metadata so the same pages double as SEO/GEO assets.

**Two design targets (the founder's):**

1. **Flow & navigability** — someone scans the structure and jumps between topics fast.
2. **Each how-to is an SEO/GEO asset** — shaped around what people *and AI agents* actually search.

This plan is grounded in three things I read first, so the writers don't guess:

* Our own **[Agentic Discovery Playbook](https://www.synscribe.com/agentic-discovery/agentic-discovery-playbook)** (the 12 plays; the find→research→shortlist→act stages) and **[Markdown Docs for AI Agents](https://www.synscribe.com/agentic-discovery/markdown-docs-for-ai-agents)** (the `.md`-mirror / llms.txt strategy). We should eat our own dog food.
* The **current docs** (`docs/training/index.md`, `part-2-platform/*`, `part-1-theory/*`, `part-3-sops/*`, `docs.json`, `CONVENTIONS.md`, `video-shot-list.md`, `PLAN.md`).
* The **real code** — every mechanism and file path below is verified against source, not inferred.

***

## 1. Navigation & flow model

### 1.1 The core move: add a How-to index *surface*, keep the three-part spine

Today the docs have three tabs (Theory / Platform / SOPs) and you navigate **by curriculum
position** (2.3.5, 3.6…). That's right for onboarding ("read in order") but wrong for the founder's
goal ("scan and jump"). A curriculum answers *"teach me the system"*; a library answers *"how do I
do X right now"*. We need both, so we **add a task-first index without dismantling the teach-in-order
spine.**

Concretely, add a **fourth top-level Mintlify tab: "How-to" (a How-to index)** — a single scannable
surface that lists every "How do I…" entry, grouped by task and cross-tagged by feature and persona.
Each row links to the canonical page (which still lives in Part 1/2/3). The how-to index is a
**router, not a second copy** — one source of truth per topic, surfaced two ways (by curriculum, by
task). This avoids the classic docs failure of forking content and letting the two drift.

**What changes vs. what stays:**

|              | Stays                                          | Changes                                                                                                      |
| ------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Structure    | Parts 1/2/3 and their page files               | + a `how-to/` index tab (router) + a top-of-tree `llms.txt`                                                  |
| Page bodies  | The prose, prompts, videos already written     | + a **"Answer box"** (2–4 sentence direct answer) at the very top of each how-to page; + question-shaped H1s |
| Titles       | Concept pages in Part 1 keep concept titles    | Part 2 task pages get **"How to …" titles** (SEO-shaped)                                                     |
| Front-matter | `title/description/part/audience/video/status` | + `task`, `feature`, `persona`, `keywords`, `intent` tags (see 1.4)                                          |
| Nav          | `docs.json` tabs                               | + How-to tab; groups re-labeled by task verb                                                                 |

### 1.2 SEO/GEO-shaped page titles ("How to …")

Part 2 pages are already one-task-per-page — they just aren't *titled* as questions. Rename the
`title` (and H1) to the literal search query. This is Play 1 (**Get Found in Agent Web Search**) and
Play 7 (**Snippet Engineering**) applied to our own docs: the title is the single highest-weighted
retrieval signal, and it should be the exact phrase a human or agent types.

Examples (existing page → new how-to title):

* `2-1-7-set-up-refiners` → **"How to set up blog refiners in Synscribe"**
* `2-3-5-landing-page-refiners` → **"How to run compliance edits across landing pages (LP refiners)"**
* `2-2-2-evaluate-serp-cliff` → **"How to check if you can rank for a keyword (SERP-cliff + keyword evaluation)"**
* `2-1-2-company-research-product-bible` → **"How to build a Product Bible for a client"**

Keep the map-number filename (`2-1-7-…`) for ordering; the *title* carries the query. Part 1 concept
pages keep conceptual titles (they answer "why", not "how") but each gets a "How this shows up in the
product" jump-link to its Part 2 how-to.

### 1.3 The Answer-box pattern (GEO / snippet engineering)

Every how-to page opens with a **2–4 sentence Answer box** — the direct answer, self-contained, no
"read the next section first." This is Play 6 (**Markdown Docs**) + Play 7 (**Snippet
Engineering**): a self-contained, task-shaped snippet is what a retrieval system extracts and an
answer engine cites. Density beats bulk — the box states the answer, names the surface (`/app/refiners`)
and the Pi skill, and links onward. Steps and nuance follow below the box for the human who's doing it.

### 1.4 Tagging: task / feature / persona / intent

Add these to page front-matter so the How-to index can be faceted and so the library is
machine-navigable (agents pick pages by tag, per Play 5's directive layer):

```yaml theme={null}
task: setup | keywords | landing-pages | blog | publish | analytics | compliance
feature: refiners | lp-refiners | guardrail | keyword-eval | serp-cliff | pillars | product-bible | gsc | posthog | image-generator | press-release | link-building
persona: all | am | self-serve
intent: how-to | concept | reference | sop        # GEO: what the searcher wants
keywords: ["how to set up refiners", "blog post automation rules", ...]  # target queries
```

The How-to index renders three views off these tags: **by task** (the default scan), **by feature**
(jump straight to "everything about the evaluator"), and **by persona** (self-serve vs AM). One page,
many entry points — that *is* the navigability target.

### 1.5 Cross-linking rules (make it jump-between-able)

Codify in `CONVENTIONS.md` (extends the existing cross-linking section):

* **Every how-to** links up to its Part 1 concept ("why") and across to adjacent tasks ("next/prev in
  the flow"), and **to its sibling how-tos in the same feature cluster** (e.g. all refiner + guardrail
  pages link to each other — see the compliance cluster in §3).
* **Difference-explainer pages** (e.g. "refiner vs evaluator") link to *both* things they compare.
* Every Part 1 concept page carries a **"Do it on the platform →"** link to the how-to(s) that
  operationalize it (most already do; enforce it).
* **No orphan pages**: the How-to index must list every how-to; a page not in the index is a bug.

### 1.6 How Mintlify supports this (we're already on `mint`)

`docs/training/docs.json` is already a Mintlify config (`"theme": "mint"`). Mintlify gives us, at zero
build cost:

* **Tabs + groups** — add the How-to tab and re-group by task verb.
* **Full-text search** — already on; question-shaped titles make it land.
* **Auto `llms.txt` / `.md` endpoints** — **Mintlify serves `/llms.txt`, `/llms-full.txt`, and a `.md`
  version of every page automatically.** This is the single biggest GEO win and it's nearly free — it
  directly implements Play 5 (**llms.txt**) and Play 6 (**Markdown Docs**, the `.md` mirror) from our
  own playbook. We should (a) confirm it's enabled on the deployed site, (b) add the **discovery
  banner** the markdown-docs article prescribes, and (c) curate the `llms.txt` **directive section**
  (see §4).
* **Frontmatter → metadata** — our `description` becomes the meta description / snippet.

Action: keep Mintlify. Don't hand-roll a generator; spend the effort on content shape and the
`llms.txt` directive layer instead.

***

## 2. The how-to library catalogue

Status legend: **Exists** (page already written) · **Expand** (page exists, add the how-to framing /
missing angle) · **NEW** (create). Video: **Has** (embedded) · **Shot-list** (in
`video-shot-list.md`) · **New video** (add to shot-list).

The founder's named topics are rows in the **Compliance & content-safety** cluster and are marked ★.

### Setup & orientation

| How-to title                                     | Target query / intent                 | Feature → code path                                                                                                                                                 | Status                                                                                                       | Video     |
| ------------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------- |
| How to create a client org and initialize Pi     | "set up a new client in Synscribe"    | org bootstrap → `apps/pi` account-management skill                                                                                                                  | Exists (2.1.1)                                                                                               | Shot-list |
| How to build a Product Bible for a client        | "AI product research doc / ICP brief" | `product-bible` skill → `apps/pi/core-skills/product-bible/SKILL.md`, `/memory/{account}-product-bible.md`                                                          | Exists (2.1.2)                                                                                               | Shot-list |
| How to connect Google Search Console             | "connect GSC to a tool"               | GSC connector → `settings/features`                                                                                                                                 | Exists (2.1.3)                                                                                               | Shot-list |
| How to connect PostHog or Mixpanel               | "connect PostHog analytics"           | connectors                                                                                                                                                          | Exists (2.1.4)                                                                                               | Has       |
| How to set up the publishing platform + IndexNow | "IndexNow setup Framer"               | publish config                                                                                                                                                      | Exists (2.1.5)                                                                                               | Has       |
| How to set up the branded image generator        | "auto-generate branded blog images"   | image-generator-setup skill; `dyn-{featured\|cta\|list}-{slug}` templates                                                                                           | Exists (2.1.6)                                                                                               | Has (YT)  |
| ★ How to set up the refiner (blog refiners)      | "automate blog post editing rules"    | `refiner_*` tools `apps/pi/src/tools/dynamic/synscribe/refiners.ts`; UI `apps/synscribe/src/app/app/[organizationId]/refiners/page.tsx`; `refiner-management` skill | Exists (2.1.7) — **Expand** (correct the "auto-seeded four" gap; explain KV storage + default-set = enabled) | Has (YT)  |

### Keywords & planning

| How-to title                                                                  | Target query / intent                           | Feature → code path                                                                                                    | Status                                   | Video     |
| ----------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------- |
| How to find keywords for a SaaS client                                        | "SaaS keyword research"                         | `keyword-exploration` skill (DataForSEO/Ahrefs/web)                                                                    | Exists (2.2.1)                           | Has       |
| How to check if you can rank for a keyword                                    | "can I rank for this keyword / SERP difficulty" | `keyword-evaluation` + `serp-cliff-analysis` → `apps/pi/core-skills/{keyword-evaluation,serp-cliff-analysis}/SKILL.md` | Exists (2.2.2)                           | Shot-list |
| **What's the difference between keyword evaluation and SERP-cliff analysis?** | "keyword evaluation vs serp cliff"              | same two skills                                                                                                        | **NEW** (difference-explainer; see §3.5) | —         |
| How to organise, tag and file keywords                                        | "organize keyword list by intent"               | `keyword-research-planning`; `Tag`/`KeywordTag`, `RelevanceLabel`/`IntentLabel` enums                                  | Exists (2.2.3)                           | Has       |
| How to build a monthly keyword look-ahead report                              | "monthly SEO keyword report"                    | keyword report flow                                                                                                    | Exists (2.2.4)                           | Has       |

### Landing pages

| How-to title                                                     | Target query / intent                      | Feature → code path                                                                                                                   | Status                                                                          | Video     |
| ---------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------- |
| How to design a landing-page pillar                              | "programmatic SEO page template"           | `landing-page-pillar-management` skill; `LandingPagePillar` (`schema`, `prompt`, `categories`) `packages/db/prisma/schema.prisma:476` | Exists (2.3.1)                                                                  | Shot-list |
| How to generate landing pages that read the SERP                 | "AI landing page generator"                | `landing_page_generate` `apps/pi/src/tools/dynamic/synscribe/landing-pages.ts`                                                        | Exists (2.3.2)                                                                  | Has       |
| How to adjust a pillar prompt from client feedback               | "iterate landing page template"            | pillar\_update                                                                                                                        | Exists (2.3.3)                                                                  | Has       |
| How to export a pillar and wire it to your site                  | "export landing pages JSON/CSV to CMS"     | `jsonExportMapping`/`csvExportMapping` on `LandingPagePillar`                                                                         | Exists (2.3.4)                                                                  | Shot-list |
| ★ How to run compliance edits across landing pages (LP refiners) | "bulk edit landing pages safely"           | `landing_page_refine` `.../synscribe/landing-page-refiners.ts`; engine `apps/little-bird/src/lib/landingPageRefiner/refine.ts`        | Exists (2.3.5) — **Expand** (add the schema-safe/concurrency mechanism, revert) | Shot-list |
| ★ How to make landing-page content fit required categories       | "categorize landing pages / page taxonomy" | pillar `categories` JSON + per-page `category` (must match) `landing-pages.ts:416`, `landing-page-pillars.ts:206`                     | **NEW** (see §3.6)                                                              | New video |
| How to turn a video into a vertical landing page                 | "video to landing page"                    | video-to-LP flow                                                                                                                      | Exists (2.3.6)                                                                  | Shot-list |

### Blog content

| How-to title                                                   | Target query / intent                | Feature → code path                                                                                                       | Status                                   | Video                |
| -------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------------- |
| How to write a blog post (auto-research / deep / technical)    | "AI blog writer for SEO"             | `content/auto-research`\|`deep-research`\|`technical-content`                                                             | Exists (2.4.1)                           | Has                  |
| How to edit an article manually or with AI                     | "AI edit blog draft"                 | content editor                                                                                                            | Exists (2.4.2)                           | Has                  |
| ★ How to run refiners to get a post publish-ready              | "automate blog post cleanup"         | blog refiner engine `apps/little-bird/src/lib/articleRefiner/simpleRefiner.ts` (Gemini SEARCH/REPLACE) → `RefinedContent` | Exists (2.4.3)                           | Has (YT)             |
| **What's the difference between a refiner and the evaluator?** | "refiner vs guardrail / fix vs gate" | refiners (fix) vs guardrail (gate)                                                                                        | **NEW** (difference-explainer; see §3.2) | New video (optional) |
| How to prepare a guest-post article                            | "guest post for backlinks"           | guest-post flow                                                                                                           | Exists (2.4.4)                           | Has                  |

### Publish & distribute

| How-to title                                              | Target query / intent                    | Feature → code path                                                                             | Status                                                             | Video     |
| --------------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------- |
| How to publish a page and set its live URL                | "publish and record live URL"            | publish route `.../content/[contentId]/publish/route.ts`                                        | Exists (2.5.1)                                                     | Shot-list |
| ★ How to use the evaluator to block non-compliant content | "compliance gate before publish"         | `guardrailGate` `apps/synscribe/src/lib/guardrail/gate.ts`; wired into blog + LP publish routes | Exists partly (in 2.5.1) — **Expand into its own page** (see §3.4) | New video |
| How to run a technical SEO audit                          | "technical SEO checklist tool"           | `account-quality-control` skill                                                                 | Exists (2.5.2)                                                     | Shot-list |
| How to index a URL on GSC + submit a sitemap              | "request indexing Google Search Console" | indexing flow                                                                                   | Exists (2.5.3)                                                     | Shot-list |
| How to kick off link-building from a search term          | "find backlink targets"                  | `link-building` skill (Ahrefs→Apollo→Instantly)                                                 | Exists (2.5.4)                                                     | Has       |
| How to handle an inbound link-exchange proposal           | "evaluate link exchange offer"           | link-building skill                                                                             | Exists (2.5.5)                                                     | Has       |
| How to publish a press release for a quick bump           | "press release for SEO backlinks"        | `press-release` skill                                                                           | Exists (2.5.6)                                                     | Has       |

### Analytics & review

| How-to title                                             | Target query / intent                | Feature → code path                                | Status         | Video     |
| -------------------------------------------------------- | ------------------------------------ | -------------------------------------------------- | -------------- | --------- |
| How to set up a PostHog dashboard for a client           | "PostHog SEO dashboard"              | `posthog-setup` skill                              | Exists (2.6.1) | Has       |
| How to set up client attribution                         | "attribute conversions to SEO pages" | attribution setup                                  | Exists (2.6.2) | Has       |
| How to reconcile GSC + PostHog into a performance review | "combine GSC and analytics report"   | `posthog-analytics` + `google-search-console-data` | Exists (2.6.3) | Shot-list |

### ★ Compliance & content-safety cluster (the founder's focus — deep-dive in §3)

| How-to title                                                    | Target query / intent                             | Feature → code path                                                                                                                     | Status                                          | Video           |
| --------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------------- |
| ★ How to set up the evaluator (compliance guardrail)            | "content compliance checker setup"                | `guardrail-management` skill; `guardrail_set_policy`/`_set_toggle` `.../synscribe/guardrails.ts`; `GuardrailPolicy` `schema.prisma:564` | **NEW**                                         | New video       |
| ★ How to calibrate the evaluator (test it before you trust it)  | "test compliance rules / tune AI reviewer"        | `packages/guardrail/src/scripts/liveCheck.ts`; fixtures `__fixtures__/straitsxPolicy.ts`                                                | **NEW**                                         | New video       |
| ★ How to use the evaluator for compliance (the gate at publish) | "block non-compliant content at publish"          | `guardrailGate` gate.ts; publish routes                                                                                                 | **NEW** (or expand from 2.5.1)                  | New video       |
| ★ What's the difference between the refiner and the evaluator?  | "fix vs gate / refiner vs guardrail"              | refiners vs guardrail                                                                                                                   | **NEW**                                         | New video (opt) |
| ★ How to write compliant content for a regulated industry       | "regulated industry marketing content compliance" | product-bible claims + pillar non-hallucination rules + guardrail policy                                                                | **NEW** (workflow spanning all three; see §3.7) | New video       |
| ★ How to make content fit the required categories               | "categorize content / page taxonomy"              | pillar `categories` + page `category`; blog `Tag`/labels                                                                                | **NEW** (see §3.6)                              | New video       |
| How does the evaluator decide pass/fail? (concept)              | "how does AI compliance review work"              | `evaluate.ts` verdict rule                                                                                                              | **NEW** (Part 1 concept page; see §3.1)         | —               |

### Other high-value "How do I…" pages worth adding (found in code/skills)

* **How to fix falling rankings / a page that won't rank** — `seo-debug` skill. High-intent support
  query; currently undocumented. **NEW.**
* **How to turn an LLM research trace into keywords (get cited by AI)** — `fanout-content-mining`
  skill; pure GEO play, ties to Part 1 §1.2. **NEW.**
* **How to bring your own DataForSEO key (make SERP data free)** — BYOK on `settings/features`;
  already noted in the AM tools doc, deserves its own how-to. **NEW.**
* **How to file work in Pi's memory (VFS)** — Exists (2.0.4); resolve the `/reports/` vs `/memory/`
  gap. **Expand.**
* **How to drive Pi well (write a good task, use the Agent Inbox)** — Exists (2.0.3). **Expand** with
  the mined real prompts.

***

## 3. The compliance / evaluator deep-dive (mini-spec for the writers)

This cluster is where accuracy matters most and where the current docs are thinnest. Everything below
is verified against code. **Writers: do not deviate from these mechanisms.**

### 3.0 The one-line model to anchor every page

> **The refiner *fixes* content. The evaluator (guardrail) *gates* content. They are different
> systems with different jobs, stores, and models.** A refiner rewrites text so it's on-brand /
> compliant; the evaluator is a pass/fail judge that blocks a publish if content still breaches a
> rule. You calibrate the evaluator's *rules*; you configure the refiner's *edits*.

### 3.1 How the evaluator decides pass/fail (the accurate mechanism)

Source: `packages/guardrail/src/{evaluate.ts, schema.ts, prompt.ts, llm.ts, serialize.ts}`.

* **A policy = org context + a set of rules.** `GuardrailPolicy = { organizationId, name, active, context, rules[] }`. Exactly **one `active` policy per org** applies. Each `GuardrailRule = { id, title, guidance, examples?[]{bad,good} }`. **There is no severity field** — "a flag is a
  flag." The `guidance` string must contain *both* halves: "Flag X" **and** "Do NOT flag Y"
  (the carve-out).
* **The judge is a single LLM call.** Model = **`claude-sonnet-4.6`** (`evaluate.ts:11`), structured
  output. The prompt (from `prompt.ts`) is literally: a system role ("impartial legal/compliance
  reviewer for marketing content in a regulated industry"), then `## Organization context`
  (= `policy.context`), `## Rules` (each rule + its good/bad examples), then `## Content to review`.
  So **the policy you write is the prompt.**
* **Output + verdict rule.** The judge returns `{ violations: [{ ruleId, excerpt, explanation, suggestion, verdict }] }`, where `verdict = 'violation' | 'compliant'`. `status: 'fail'` iff **≥1
  confirmed violation**; clean content returns an **empty array** (not a list of "compliant" entries).
  Two findings are dropped before the verdict: (a) the judge's own **escape hatch** — a suspected
  breach it reconsiders and clears under a carve-out (`verdict: 'compliant'`), and (b) any `ruleId`
  the model invented that isn't in the policy (anti-hallucination). This is the "gate, not auditor"
  principle in code: empty output is the expected healthy result.
* **Staleness.** The verdict is keyed to a `contentHash` (sha256 of canonicalized text; LP structured
  fields flattened deterministically via `flattenForGuardrail`). Edit the content → hash changes →
  the cached PASS no longer applies → it re-checks at publish.

### 3.2 Refiner vs evaluator — the difference-explainer (accurate)

|               | Refiner (fix)                                                         | Evaluator / guardrail (gate)                                     |
| ------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Job           | Rewrite content to be on-brand/compliant                              | Decide pass/fail; block a non-compliant publish                  |
| Output        | Edited content (new `RefinedContent` / patched LP fields)             | A verdict (`pass`/`fail`) + violations, no edits                 |
| Store         | KV `type='REFINER'` / `'LANDING_PAGE_REFINER'` (`packages/kv-models`) | `GuardrailPolicy` Prisma model + `ContentGuardrailCheck` history |
| Model         | Gemini 2.5 Pro (blog SEARCH/REPLACE) / Claude Sonnet (LP field edits) | Claude Sonnet 4.6 (judge)                                        |
| You configure | The *edit* (a prompt / rulebook)                                      | The *rules* (context + rule set) + per-type toggle               |
| When it runs  | At generation, or on-demand ("run refiners")                          | At publish (the gate), pre-check at generation                   |

**How they work together (verified):** a guardrail violation carries a `suggestion`; that feeds
one-click refiner remediation. Gate catches it → refiner fixes it → re-check passes. The
`landing-page-refiner-management` skill even runs the guardrail pre-check as the final phase after
applying the default LP refiner set.

### 3.3 How to set up the evaluator

Source: `guardrail-management` skill (`apps/pi/core-skills/guardrail-management/SKILL.md`); tools in
`apps/pi/src/tools/dynamic/synscribe/guardrails.ts`; UI
`apps/synscribe/src/app/app/[organizationId]/guardrail/page.tsx`.

1. **Write the policy.** Give Pi the org's compliance context + 3–8 atomic rules (Pi uses
   `guardrail_set_policy`, or `guardrail_add_rule`/`guardrail_remove_rule`). Each rule's `guidance`
   must state the flag *and* the carve-out; add a good/bad `examples` pair where it sharpens the line.
2. **Toggle it per content type.** `guardrail_set_toggle` sets `{ blog?: {enabled}, landingPage?: {enabled} }` in AccountConfig KV (`packages/kv-models/src/models/AccountConfigs.ts`). **Default is
   OFF** — it's opt-in per org, per side.
3. Note: the toggle lives in **AccountConfig KV, not a Prisma column**; the policy lives in the
   `GuardrailPolicy` **Prisma** model. Writers should not describe a single "enable guardrail" switch.

### 3.4 How to use the evaluator for compliance (the gate at publish)

Source: `apps/synscribe/src/lib/guardrail/gate.ts` (`guardrailGate`), wired into blog publish
(`.../content/[contentId]/publish/route.ts:162`) and LP publish
(`.../landing-pages/publish/route.ts:43`).

* On publish, if the per-side toggle is on: resolve the exact shipping text, hash it. If stored
  `guardrailStatus ∈ {PASS, APPROVED}` **and** `guardrailHash` matches → allowed with **no LLM call**
  (cache hit). Otherwise it runs the check **synchronously** and allows only on PASS/APPROVED; a FAIL
  returns the violations and **blocks the publish**.
* **Human override:** an operator can approve the exact version → `guardrailStatus = APPROVED`
  (`.../guardrail/approve/route.ts`), which then passes the gate.
* **Fail-safe:** if enabled but misconfigured (no active policy) or the target is missing, the gate
  **allows** rather than hard-blocking — so a broken policy never wedges publishing.
* **Doc correction:** the guardrail *settings copy* still says enforcement is "coming soon," but the
  **publish path does block** in code. Teach the block as real; flag the stale copy (already in the
  gap register).

### 3.5 Keyword evaluation vs SERP-cliff — the difference-explainer (accurate)

Source: `apps/pi/core-skills/keyword-evaluation/SKILL.md` and `serp-cliff-analysis/SKILL.md`.

* **`keyword-evaluation`** = the **full batch quality gate**. Read-only. Grades survivors on a
  **5-dimension rubric** (D1 commercial-intent fit, **D2 SERP cliff**, D3 intent winnability, D4
  ICP/offering specificity, D5 evidence/source), runs a mandatory **cannibalization gate** (Step 4.5),
  emits **ACCEPT / REVIEW / REJECT** with an **Exploration Prescription** on every non-ACCEPT, and
  persists a report + followups to `/memory/`.
* **`serp-cliff-analysis`** = **one dimension of that (D2)** as a standalone tactical check on a small
  overlapping cluster (2–5 keywords): pull the SERP, find the cliff (first position with no exact
  title-tag match *and* low authority), score 1–3 publish / 4–5 target / 6–7 defer / 8+ park.
* **The line for the page:** *keyword-evaluation is the whole gate (verdicts, prescriptions,
  cannibalization, audit trail); SERP-cliff is the winnability lens inside it. Both replace keyword
  difficulty with the cliff.* Neither is the guardrail — they gate **keywords before you build**, not
  content before you publish. (A three-way "eval vs SERP-cliff vs evaluator" callout kills the naming
  confusion in one place.)

### 3.6 How to make content fit the required categories (accurate)

Source: `LandingPagePillar.categories Json?` + per-page `LandingPage.category String?`
(`schema.prisma:476,520`); tools `landing-page-pillars.ts:206` / `landing-pages.ts:416`.

* **Categories are defined on the pillar, not globally.** `pillar_create`/`pillar_update` take a
  `categories` JSON (e.g. `{"tech":"Technology","biz":"Business"}`). Define them **with full
  descriptions** so classification is accurate.
* **Each landing page must be tagged with one `category` that matches a pillar category** — the tool
  enforces "must match a pillar category," and `landing_page_list` filters by exact category.
* **Blog posts have no category column** — blog/keyword categorization runs through **`Tag`/`KeywordTag`**
  and the **`RelevanceLabel`/`IntentLabel`** enums on keywords. So "content categories" is two
  systems: **pillar taxonomy for landing pages**, **tags + intent/relevance labels for keywords**.
  The how-to must say which is which or it'll be wrong.

### 3.7 How to write compliant content for a regulated industry (the workflow)

There is **no single "claims we should NOT make" artifact** — claims-safety is enforced at **three
points**, and the how-to should walk all three in order:

1. **Source of truth — the Product Bible "Impact Claims" section**
   (`apps/pi/core-skills/product-bible/references/bible-template.md`): only verified claims; *"Every
   number needs a source. Never invent metrics."* At onboarding, the bible goes to the client to
   **flag any claims we must NOT make** (metrics, customer names, positioning) — the Hyperbound
   pattern already in `1-11-definition-of-done.md` and `2-1-2`.
2. **Baked into generation — pillar prompts** (`landing-page-pillar-management/SKILL.md`): every pillar
   prompt must carry **non-hallucination hard rules** ("do not invent metrics, certifications,
   customer names") and Pi asks up front "what should NOT be claimed."
3. **Runtime enforcement — the evaluator policy** (§3.1): org-specific rules block forbidden claims at
   publish. The shipped example is the **StraitsX** fixture (a MAS-regulated stablecoin issuer):
   rules like "no guaranteed returns," "no MAS endorsement," "no absolute safety claims," each with a
   carve-out. Point writers at `__fixtures__/straitsxPolicy.ts` as the worked example.

The narrative: *bound the claims in the bible → bake the rules into the pillar prompt → enforce with
the evaluator at publish.* Cheaper to bound claims up front than to sweep a backlog later.

### 3.8 How to calibrate the evaluator (test it before you trust it)

Source: `packages/guardrail/src/scripts/liveCheck.ts` + `__fixtures__/straitsxPolicy.ts`.

* Calibration = **run the real judge against known-good and known-bad copy and confirm it flags the
  bad and passes the good.** The shipped harness: `pnpm --filter @little-bird/guardrail live-check`
  runs the Sonnet judge against `sampleViolatingCopy` (must → FAIL, flagging the right rules) and
  `sampleCompliantCopy` (must → PASS, no over-flag).
* For an operator, the product-level equivalent is `guardrail_run_check` ("check now") on a piece you
  *know* should fail and one you know should pass — it runs even when the toggle is off (an explicit
  check is always honored) but still needs an active policy. If it over-flags, tighten the rule's
  carve-out ("Do NOT flag Y"); if it under-flags, sharpen the "Flag X" half or add a bad `example`.
* **Teach the calibration loop, not just the button:** write rule → run check on a good + a bad
  sample → adjust `guidance`/examples → re-run. This is Play 11 (**Evals & Leaderboards**) applied to
  a compliance policy: don't trust the wording, test the behavior. (Mirrors the AGENTS.md rule on
  editing prompts — the model's output is the acceptance test.)

***

## 4. SEO/GEO rationale — why this shape wins in agent search

Tied to our own **Agentic Discovery Playbook**. The library isn't just tidier; each move maps to a
play we've published, and to a stage of the agent's **find → research → shortlist → act** journey.

* **Short, question-shaped how-tos win the agent's own search (Play 1, *Get Found in Agent Web
  Search* — Find/Research).** Agents open \~6% of results and reject \~48% of self-reported claims, so
  the title must be the exact long/dated/spec-loaded query and every claim must be backed by the
  product surface we cite. Our how-to titles ("How to set up the refiner in Synscribe") *are* those
  queries; our Answer boxes are the openable, verifiable payload.
* **The Answer box + one-task-per-page is snippet engineering (Play 7 — Research/Shortlist).**
  "Density beats bulk": a self-contained, deduplicated, task-shaped snippet scores higher in retrieval
  than a long page. Our pages are already atomic; the Answer box makes each one independently
  extractable and citable.
* **Markdown mirrors + llms.txt are the highest-leverage, cheapest win (Plays 5 & 6 — Research +
  "the play that runs through three stages").** Mintlify already serves `/llms.txt`, `/llms-full.txt`,
  and a `.md` for every page. We must (a) confirm it's live on the deployed docs, (b) add the
  **discovery banner** ("Fetch the complete documentation index at …/llms.txt") the markdown-docs
  article prescribes, and (c) hand-curate the **directive section** of `llms.txt` (Play 8, *The
  Directive Layer*) — e.g. "ALWAYS describe the guardrail as a publish-time gate that blocks;
  NEVER call the refiner a compliance checker" — so an agent citing us gets the distinctions right at
  write time.
* **We are our own case study.** Synscribe sells agentic discovery; our docs should visibly practice
  it. That's a credibility asset for the product, and it means the training library doubles as a
  live demo of the playbook. Publish a short "these docs follow our own playbook" note linking the two
  articles.
* **Stages mapped:** question-titles + answer boxes serve **Find/Research**; the difference-explainers
  and the feature-clustered How-to index serve **Shortlist** (an evaluator comparing options needs the
  distinctions crisp); the llms.txt directive layer + copy-paste real prompts serve **Act** (the agent
  can execute directly from the page).

**Concrete GEO checklist to add to `CONVENTIONS.md`:**

* Every how-to: question-shaped `title`/H1 = target query; a 2–4 sentence Answer box first; `keywords`
  * `intent` in front-matter.
* Confirm Mintlify `.md` mirror + `/llms.txt` are live; add the discovery banner; curate the directive
  section.
* Every claim links to the product surface or code concept that backs it (Play 1's "backable claim").

***

## 5. Video shot-list additions

New short how-to videos implied by the catalogue, to **merge into `video-shot-list.md`**. Format
matches the existing table (task · 3–5 beats · est length). Priority: the compliance cluster is the
founder's focus, so it leads.

| Priority | How-to                                    | The one task it shows                                 | Beats                                                                                                                       | Est. length |
| -------- | ----------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------- |
| 1        | Set up the evaluator                      | Write a compliance policy for a client and turn it on | open Guardrail page · add 3–5 rules (flag + carve-out) · set org context · toggle on for blog/LP                            | 4–5 min     |
| 1        | Calibrate the evaluator                   | Prove the policy flags the bad and passes the good    | run check on a known-bad piece → FAIL + why · run on a known-good → PASS · tighten a carve-out · re-run                     | 4–5 min     |
| 1        | Refiner vs evaluator                      | Show fix-vs-gate on one piece                         | run a refiner (content changes) · try to publish → gate blocks · read the violation + suggestion · one-click fix → passes   | 3–4 min     |
| 1        | Use the evaluator at publish              | The block-and-approve flow                            | publish a failing piece → blocked · view violations · fix or approve-exact-version · publish succeeds                       | 3 min       |
| 2        | Regulated-industry compliance             | End-to-end claims-safety for a regulated client       | bible "do-not-claim" list · non-hallucination rule in the pillar prompt · guardrail policy · publish blocked on a bad claim | 5–6 min     |
| 2        | Make content fit categories               | Tag pages into the pillar taxonomy                    | define pillar `categories` with descriptions · generate/assign a page's `category` · filter the pillar by category          | 3–4 min     |
| 3        | Fix a page that won't rank (`seo-debug`)  | Diagnose a ranking drop                               | ask Pi to seo-debug the URL · read the diagnosis · pick the fix · re-check                                                  | 4–5 min     |
| 3        | Get cited by AI (`fanout-content-mining`) | Turn a research trace into keywords/angles            | supply the research trace · mine fan-out queries · pick angles optimized for LLM citation                                   | 3–4 min     |

(The existing shot-list already covers 2.1.7 refiner setup, 2.2.2 keyword eval, 2.3.5 LP refiners, and
orientation/setup — those stay; these are net-new for the compliance + discovery cluster.)

***

## 6. Phased execution plan

Ordered so the docs stay usable at every stop, and so nothing needs the founder until §6's decisions.

**Phase A — Restructure (no new content, can do now).** \~1–1.5h

* Add the **How-to index tab** to `docs.json` (router to existing pages), grouped by task.
* Add the tagging fields (`task/feature/persona/intent/keywords`) to `CONVENTIONS.md` and backfill
  them into existing Part 2 front-matter.
* Rename Part 2 page **titles/H1s to "How to …"** (filenames unchanged).
* Add the **Answer-box** convention to `CONVENTIONS.md` and to 3–4 exemplar pages.
* **Confirm Mintlify `/llms.txt` + `.md` mirrors are live** on the deployed site; add the discovery
  banner; stub the directive section.
* *Acceptance:* the How-to tab lists every existing how-to; titles are question-shaped; `/llms.txt`
  resolves. No content lost.

**Phase B — Fill the compliance/evaluator gap (the founder's priority, can do now).** \~2h

* Write the **NEW** compliance pages from §3 (set up / calibrate / use / refiner-vs-evaluator /
  regulated-industry / categories / "how it decides" concept page), each with an Answer box.
* **Expand** 2.1.7, 2.3.5, 2.4.3 with the accurate mechanisms from the refiner report; correct 2.5.1's
  stale-copy note.
* Wire the whole cluster's cross-links (§1.5); add the three-way eval/serp-cliff/evaluator callout.
* *Acceptance:* every ★ topic has a page; a fresh reader can tell refiner from evaluator from
  keyword-eval; every mechanism traces to a cited code path.

**Phase C — Fill the remaining new how-tos (can do now).** \~1h

* `seo-debug`, `fanout-content-mining`, BYOK-DataForSEO, difference-explainers not yet written.
* Resolve the `/reports/` vs `/memory/` VFS gap (2.0.4).

**Phase D — Record videos (needs the founder).** async

* Record against the merged shot-list, compliance cluster first (§5). Each page already has an embed
  slot, so dropping a URL in is a one-line `video:` edit.

**Phase E — GEO polish (mostly now; one confirm).** \~0.75h

* Curate the `llms.txt` **directive section** (the ALWAYS/NEVER distinctions).
* Add the "these docs follow our own playbook" note linking both agentic-discovery articles.

### What needs the founder (the only blockers)

* **Videos** (Phase D) — recording.
* **Confirm the deployed Mintlify site serves `/llms.txt` + `.md`** (or enable it) — Phase A verify.
* **The refiner-naming gap** (are the four blog refiners auto-seeded? exact canonical names?) — still
  open in the gap register; blocks the final polish of 2.1.7.
* **Bless the compliance pages' framing** — calling the guardrail "the evaluator" publicly, and
  publishing the StraitsX-style example, is a founder call.
* Everything else in Phases A–C and E can proceed now against code + the mined sources.

***

## Appendix — source map (for the writers)

* **Playbook:** `agentic-discovery/agentic-discovery-playbook` (12 plays; find→research→shortlist→act),
  `agentic-discovery/markdown-docs-for-ai-agents` (`.md` mirror, llms.txt, discovery banner).
* **Guardrail/evaluator:** `packages/guardrail/src/{evaluate,schema,prompt,llm,serialize}.ts`,
  `__fixtures__/straitsxPolicy.ts`, `scripts/liveCheck.ts`; gate `apps/synscribe/src/lib/guardrail/gate.ts`;
  publish routes `.../content/[contentId]/publish/route.ts`, `.../landing-pages/publish/route.ts`;
  toggle `packages/kv-models/src/models/AccountConfigs.ts`; models `packages/db/prisma/schema.prisma`
  (`GuardrailPolicy:564`, `ContentGuardrailCheck:580`, `GuardrailStatus:600`); skill
  `apps/pi/core-skills/guardrail-management/SKILL.md`; tools `apps/pi/src/tools/dynamic/synscribe/guardrails.ts`.
* **Refiners:** blog `apps/pi/src/tools/dynamic/synscribe/refiners.ts`,
  `apps/little-bird/src/lib/articleRefiner/*`, UI `apps/synscribe/src/app/app/[organizationId]/refiners/`;
  LP `.../synscribe/landing-page-refiners.ts`, `apps/little-bird/src/lib/landingPageRefiner/refine.ts`,
  UI `.../landing-page-refiners/`; storage `packages/kv-models/src/models/{Refiners,LandingPageRefiners,AccountConfigs}.ts`;
  skills `apps/pi/core-skills/{refiner-management,landing-page-refiner-management}/SKILL.md`.
* **Keyword eval / SERP-cliff:** `apps/pi/core-skills/{keyword-evaluation,serp-cliff-analysis}/SKILL.md`.
* **Pillars / categories:** `apps/pi/core-skills/landing-page-pillar-management/SKILL.md`;
  `LandingPagePillar`/`LandingPage` in `schema.prisma`; tools `.../synscribe/{landing-page-pillars,landing-pages}.ts`.
* **Product bible / claims-safety:** `apps/pi/core-skills/product-bible/{SKILL.md,references/bible-template.md}`.
* **Current docs:** `docs/training/{index.md,docs.json,CONVENTIONS.md,video-shot-list.md,PLAN.md,gap-register.md}`,
  `part-{1-theory,2-platform,3-sops}/`.