Type decisions

ZajLibrary organizes docs by topic first (category, subcategory, topic), then reader intent (shelf), then type (kind/folder). Plain English: put all material about one subject in one neighborhood, then sort that neighborhood into Learn, Build, and Resources.

Topic-first structure

app/src/content/docs/<category>/<subcategory>/<topic>/<shelf>/<kind>/...

Layer	Question it answers	Example
Category	Which broad subject family?	tech-stack, infrastructure, zajlibrary
Subcategory	Which area inside that family?	laravel, hosting, authoring
Topic	Which exact content neighborhood?	codecanyon, shared-hosting, content-system
Shelf	What is the reader trying to do?	learn, build, resources
Kind	What content type is this?	guide, playbook, template, reference

Shelves inside a topic

Shelf	Question it answers	Types
Learn & Understand	What do I need to know?	handbooks, guides, concepts, research, case-studies
Build & Create	What do I design and execute?	playbooks, blueprints, sops, runbooks, checklists
Resources	What can I copy, download, or glance at?	templates, kits, cheatsheets, reference

Type definitions (quick lookup)

Type	Shelf	One-line job
Handbook	Learn	Whole-domain multi-page reference
Guide	Learn	One focused topic — read to understand
Concept	Learn	Theory / explainer / mental model
Research	Learn	Findings and sources
Case study	Learn	Real-work example and lessons
Playbook	Build	Full multi-phase workflow — teach why → how
Blueprint	Build	Design before building — read, don’t execute yet
SOP	Build	The approved standard procedure (policy flavor)
Runbook	Build	Terse commands + checks for one operation
Checklist	Build	Verification list — did every step happen?
Template	Resources	Copy-and-fill starter
Kit	Resources	Bundled reusable assets
Cheat sheet	Resources	Glanceable lookup
Reference	Resources	Site authoring (capabilities, style, components)

---

Learn vs Build — where confusion starts

Learn answers “What do I need to understand?” Build answers “What do I execute?” Guides and playbooks both contain steps, which is why beginners mix them up. The split is intent, not step count:

Shelf	Reader mode	Typical types
Learn	Study once, build mental model	guide, handbook, concept, research, case study
Build	Follow through, ship an outcome	playbook, blueprint, SOP, runbook, checklist

A guide teaches one focused thing on the Learn shelf. A playbook is the full teaching journey for a workflow on the Build shelf — multi-phase, narrative, gates, beginner-friendly. When you are ready to do the whole job, promote to a playbook; don’t park execution docs on Learn just because they have numbered steps.

---

Build shelf — playbook, runbook, SOP (and neighbors)

These three overlap in real projects. They are distinct on purpose — same workflow, different reader moment:

graph TD
  subgraph moment["Reader moment"]
    Q1["I need the full journey — teach me why and how"]
    Q2["I already know the drill — give me exact commands"]
    Q3["What is the official approved way we do this?"]
  end
  Q1 --> PB["Playbook"]
  Q2 --> RB["Runbook"]
  Q3 --> SOP["SOP"]
  PB -->|"one phase gets linkable"| RB
  PB -->|"method frozen as policy"| SOP
  PB --> CL["Checklist"]
  RB --> CL
  SOP --> CL

Playbook

The full teaching journey for a workflow. Multi-phase, narrative, why → how, gates, beginner-friendly. The reader may be new to the outcome; the doc carries judgment calls, context, and “what if” branches.

• Voice: patient teacher — explain before you command.
• Shape: folder of phases (01-…, 02-…), optional progress/stepper, links outward to Learn guides for depth.
• Example: Laravel/CodeCanyon — ZIP → local → staging → production (WF1–WF5 style journeys).
• Not: a single-operation command card (that’s a runbook) or a compliance PDF tone (that’s an SOP).

Runbook

A terse “exact commands + checks” card for one operation when you already know the drill. Think emergency checklist or incident steps — no teaching, minimal prose.

• Voice: operator card — imperative steps, copy-paste commands, pass/fail checks.
• Shape: usually one short page; peeled from a playbook phase when that phase is linkable on its own (rollback, restore, DNS cutover).
• Example: “Production rollback — run these 8 commands and verify these 4 signals.”
• Not: the whole onboarding story (playbook) or the org-wide policy doc (SOP).

SOP

The formal “this is THE approved procedure” flavor — compliance-ish, canonical, org-wide. Less narrative than a playbook; more “we always do it this way” than “let me teach you.”

• Voice: policy-backed standard — roles, prerequisites, required evidence, audit trail.
• Shape: one file or small folder; often pairs with a checklist for sign-off.
• Use sparingly in solo-founder libraries — most execution docs should be playbooks or runbooks. Reserve SOP when repeatability and approval matter (regulated ops, client handoff, team onboarding to a frozen method).

Blueprint and checklist (often paired with the three above)

Type	Job	vs playbook / runbook / SOP
Blueprint	Design before you build — architecture, boundaries, decisions	Read to align; you don’t “run” it like a playbook
Checklist	Verify every step was done — gates, QA, release	Attaches to any Build type; not a substitute for teaching or commands

---

Learn shelf — guide vs handbook (and vs playbook)

Type	Job	vs playbook
Guide	One focused how-to — read top to bottom, learn one topic	Playbook = re-read every time you execute the full outcome; guide = read once to understand
Handbook	Whole-domain hub — many pages, browse by subtopic	Playbook = phased execution path; handbook = reference spine
Concept	Mental model / theory — why something exists	Playbook may link concepts; concepts don’t replace phases
Research	Findings, sources, evidence	Informs blueprints and playbooks; not an execution doc
Case study	What happened in a real instance	Lessons inform playbooks; not a runnable procedure

graph LR
  subgraph learn["Learn — understand"]
    C["Concept"]
    G["Guide"]
    H["Handbook"]
  end
  subgraph build["Build — execute"]
    BP["Blueprint"]
    PB["Playbook"]
    RB["Runbook"]
  end
  C --> G
  G -->|"outcome needs phased execution"| PB
  H -->|"one chapter is runnable"| G
  BP --> PB
  PB -.->|"deep link"| G
  PB -->|"peel one op"| RB

---

Pick your type (decision table)

Use the first row that matches. If two match, prefer the narrower type (runbook over playbook; guide over handbook).

You need…	Type	Shelf
Explain what X means and why it matters	Concept	Learn
One focused how-to — read to learn, not a full project journey	Guide	Learn
Everything about a domain in one browsable hub	Handbook	Learn
Design / architecture before anyone runs commands	Blueprint	Build
Full workflow — phases, why, gates, beginner can follow start to finish	Playbook	Build
One operation — exact commands and checks, no teaching	Runbook	Build
Approved standard — the canonical org method	SOP	Build
Tick-box verification that steps were completed	Checklist	Build
Empty structure to copy	Template	Resources
Glanceable facts or commands	Cheat sheet	Resources

Confusing pairs — one-line rules

Pair	Rule
Playbook vs Guide	Re-read every time you execute the full outcome → Playbook. Read once to learn one topic → Guide.
Playbook vs Runbook	Whole journey with teaching → Playbook. Single operation, commands only → Runbook.
SOP vs Runbook	Approved standard / policy → SOP. Literal commands and checks in the moment → Runbook.
SOP vs Playbook	Playbook teaches and phases; SOP states the frozen approved method with less narrative.
Playbook vs Blueprint	Blueprint = what to build and how it’s structured. Playbook = how to execute building it.
Guide vs Handbook	One topic → Guide. Whole area with many entry points → Handbook.
Checklist vs Runbook	Checklist = verify. Runbook = do (commands). Often used together.

Promotion path (when a doc outgrows its type)

1. Guide → Handbook when one guide sprouts 3+ linkable subtopics worth their own pages.
2. Guide → Playbook when the reader must follow phases with gates every time they ship the outcome (move to Build).
3. Playbook phase → Runbook when one phase is linkable as a standalone command card (rollback, restore, cutover).
4. Playbook → SOP when the method is frozen, approved, and policy-backed (rare for solo workflows).
5. Any Build doc → Checklist when you need a gate list readers tick through at phase boundaries.

Deeper synonym tables and naming rules: Content types (system docs).

Generated browse views

View	Source metadata	Route
Category	category:	/categories/<category>/
Subcategory	subcategory:	/subcategories/<subcategory>/
Topic folder	topic: + physical path	/browse/ topic row
Tag	tags:	/tags/<tag>/

Rules

1. One topic home per subject — add or enrich under the existing <category>/<subcategory>/<topic>/ path when the topic already exists.
2. One type folder per file — never mix playbooks and handbooks in the same directory.
3. Topic is a path segment — use category, subcategory, and topic for the physical home; use tags for cross-cutting filters.
4. Reference is site-only — framework handbooks (Mastra) live under the relevant topic’s learn/handbooks/; authoring docs live under zajlibrary/authoring/content-system/resources/reference/.
5. Promote when dense — a guide with 3+ linkable sections becomes a handbook folder; a long playbook procedure becomes a runbook or SOP.

Metadata pattern

kind: guide
collection: mastra
category: ai-systems
subcategory: agent-frameworks
topic: mastra
tags: [mastra, storage, rag]

collection is optional metadata for legacy grouping and prompt context. Category/subcategory/topic define the path; tags are cross-cutting filters.

URL map (legacy paths — fix links, no redirects)

The topic-first cutover is a hard cutover. Redirect helpers are archived, so after a move, grep and update every internal link to the canonical path:

Old path (do not link)	Canonical path
/build/playbooks/laravel/codecanyon/setup-new/…	/tech-stack/laravel/codecanyon/build/playbooks/setup-new/…
/learn/guides/servers/shared-hosting/…	/infrastructure/hosting/shared-hosting/learn/guides/…
/resources/reference/meta/authoring/writing-style/	/zajlibrary/authoring/content-system/resources/reference/writing-style/
/system_docs/platform-architecture/	/zajlibrary/system/platform/resources/reference/platform-architecture/
/collections/<collection>/	/browse/ or the topic hub, for example /tech-stack/laravel/codecanyon/

Verify: python3 scripts/content-path-audit.py then cd app && npm run build (Starlight link validator).

Inbox & enrich (agent routing)

Processing _INBOX/ or updating a page from research follows AGENTS.md → “Inbox processing” and the content-intake skill — file-by-file classify, corpus check, multi-extract, mandatory ledger row in _INBOX/2-Research/<topic>/COVERAGE.md. First choose or create the topic-first home, then dispatch starlight-content-author + matching type-* skill; CodeCanyon corpus also loads specialized-codecanyon-laravel.