Skip to main content
How every page in this training site is written, so the whole tree stays consistent and drops into a docs generator (Astro Starlight / Mintlify / etc.) later without a rewrite. Read this before adding or editing a page.

​
Structure

docs/training/
├── index.md                 ← home + learning paths
├── part-1-theory/           ← the Synscribe Way (why)
├── part-2-platform/         ← platform how-tos (how)
├── part-3-sops/             ← SOPs for running accounts at scale (AM-only)
├── _sources/                ← mined raw material (NOT published pages)
├── gap-register.md          ← every ❓ needing Raymond, aggregated
├── video-shot-list.md       ← videos still to record
├── JOURNAL.md               ← build log (per milestone)
├── PLAN.md · GOAL.md · CONVENTIONS.md  ← meta (not published pages)
Page files are kebab-case.md, prefixed with their map number for ordering, e.g. part-2-platform/2-2-1-keyword-exploration.md.

​
Front-matter (every published page)

---
title: <human title>            # shown in nav + as H1 source
description: <one line>          # for search + page subtitle
part: 1 | 2 | 3
audience: all | am | self-serve # who this page is primarily for (default: all)
video: <url or "">              # primary embedded video, if any
status: draft | review | done   # editorial state
---

​
Audience tagging

Self-serve subscribers can do everything AMs can — the difference is discipline and standardization at scale, not gated features. So:
  • Default a page to audience: all and write it for everyone.
  • Where the guidance genuinely diverges, use an inline callout rather than forking the page:
    For AMs — the rigorous, standardized version: <checklist / cadence / quality gate>.
    For self-serve — the quick version: <the lighter path>.
  • Part 3 (SOPs) is audience: am throughout.

​
Video embed slot

Videos aren’t in the repo. Use a consistent placeholder so a generator can render it and a missing video is obvious: 
> 🎥 **Video:** [<what it shows>](<url>)
If no video exists yet, leave a shot-list marker and add the page to video-shot-list.md: 
> 🎬 **Video planned:** <the one task it shows>. See the shot-list.

​
Real prompts

When the “how” is a prompt you send Pi, show the real (mined, anonymized) prompt in a fenced block, then say what Pi does with it. Placeholders in [brackets]. Example: 
```text
based on the latest transcript and review, draft up a strategy.
suggest [N] keywords for this cycle and tag them '[cycle tag]'.
```
Pi drafts the strategy, proposes keywords, and tags them — then asks you to confirm before
executing.

​
Markers

  • ❓ [needs Raymond: <question>] — an unverified claim; also add it to gap-register.md.
  • Never state an unverified platform behavior as fact. Ground claims in code/prod/SOP/video.
  • Never mention credits / credit units. Describe throughput in posts/pages/weeks.

​
Cross-linking

Use relative links between pages (../part-2-platform/2-2-1-keyword-exploration.md). Every Part 1 concept should link to the Part 2 page(s) that operationalize it, and every Part 3 SOP should link to the Part 2 how-tos it depends on. Extra rules for the how-to library:
  • Every how-to links up to its Part 1 concept (“why”), across to the next/previous task in the flow, and sideways to its sibling how-tos in the same feature cluster (e.g. all the refiner + evaluator pages link to each other).
  • Difference-explainer pages (“X vs Y”) link to both things they compare.
  • No orphans: every how-to must appear in the How-to index. A page not in the index is a bug.

​
How-to library conventions (GEO)

Part 2 pages are a library of short how-tos — each answers one “How do I do X with my software / my AI?” question, and each is written to be found and cited (by humans and by AI agents). Applies to Part 2 pages (intent: how-to); Part 1 stays conceptual, Part 3 stays procedural.

​
Question-shaped titles

A how-to page’s title and H1 are the literal search query, phrased as the task:
  • Good: “How to set up blog refiners in Synscribe”, “How to check if you can rank for a keyword”.
  • Not: “Refiners”, “Keyword evaluation”.
Keep the numeric filename (2-1-7-…) for ordering; the title carries the query. (Part 1 concept pages keep conceptual titles and answer “why”.)

​
The Answer box (first thing on every how-to page)

Right under the H1, before any section, put a 2–4 sentence direct answer — self-contained, no “read the next section first”. State what to do, name the surface (e.g. /app/refiners) and the Pi skill, and link onward. Steps and nuance follow below. Format: 
# How to set up blog refiners in Synscribe

Set up refiners on the Content Refiners page (`/app/refiners`), or ask Pi with the
`refiner-management` skill. A refiner is a reusable rule that rewrites a draft (brand
positioning, CTA, FAQ, TLDR); you configure them once per client and apply them in one pass.
This is different from the evaluator, which gates content rather than editing it — see
[Refiner vs evaluator](./2-7-4-refiner-vs-evaluator.md).

> 🎥 **Video:** …

## Steps
…
The Answer box is what a retrieval system extracts and an answer engine cites, so it must stand alone and be accurate.

​
Extended front-matter (how-to pages)

In addition to the base fields, how-to pages carry facet tags so the How-to index can group them and so the library is machine-navigable: 
task: setup | keywords | landing-pages | blog | publish | analytics | compliance | diagnose
feature: refiners | lp-refiners | evaluator | keyword-eval | serp-cliff | pillars | product-bible | gsc | posthog | image-generator | press-release | link-building | seo-debug | fanout
persona: all | am | self-serve
intent: how-to | concept | reference | sop
keywords: ["how to set up refiners", "blog post automation rules"]   # target queries

​
The How-to index

part-2-platform/index.md is the How-to index (surfaced as its own nav tab). It lists every how-to three ways — by task, by feature, by persona — each row linking to the canonical page. It is a router, not a second copy: one source of truth per topic. Regenerate/curate it whenever a how-to is added.

​
GEO checklist (per how-to page)

  • Question-shaped title/H1 = the target query; Answer box first; keywords + intent set.
  • Every factual claim links to the product surface or the concept that backs it.
  • No credit language; straight quotes; MDX-safe.
The .md mirror + /llms.txt that make these pages agent-citable are generated by Mintlify’s hosted deploy, not mint dev (local returns 404). Realizing that GEO win needs the cloud deploy — tracked as a [DECIDE].