How-to library plan

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.

• Our own Agentic Discovery Playbook (the 12 plays; the find→research→shortlist→act stages) and 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

​

1.2 SEO/GEO-shaped page titles (“How to …”)

• 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”

​

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

​

1.4 Tagging: task / feature / persona / intent

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

​

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

• 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)

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

​

2. The how-to library catalogue

​

Setup & orientation

​

Keywords & planning

​

Landing pages

​

Blog content

​

Publish & distribute

​

Analytics & review

​

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

​

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)

​

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)

• 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)

​

3.3 How to set up the evaluator

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)

• 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)

• 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)

• 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)

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.

​

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

• 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

• 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).

• 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

​

6. Phased execution plan

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

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

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

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

• 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}/.