# docify — complete library (all audiences)

_Generated whole-library download. See `agent-manifest.json` → `library` for discovery._

## Table of contents

- **Platform Overview** (`00-platform-overview`, developers)
- **Platform Overview** (`00-platform-overview`, builders)
- **Packages** (`01-packages`, developers)
- **Authoring a Library** (`02-authoring`, developers)
- **Authoring a Library** (`02-authoring`, builders)
- **For Humans** (`03-for-humans`, developers)
- **For Humans** (`03-for-humans`, builders)
- **For Agents** (`04-for-agents`, developers)
- **Design System** (`05-design`, developers)
- **Design System** (`05-design`, builders)
- **Getting Started & Tutorials** (`06-getting-started-and-tutorials`, developers)
- **Getting Started & Tutorials** (`06-getting-started-and-tutorials`, builders)

---

# Platform Overview — developers

# x12i-docify Platform Overview — Developers

**Audience:** Engineers wiring `@x12i/docify-*` into a monorepo or publishing a product knowledge SDK.  
**Twin:** [Builders version](../builders/BOOK.md)  
**Site:** this library’s web app · platform README at `x12i-docify/README.md`

---

## Install (start here)

```bash
npm i -D @x12i/docify         # this platform’s docs knowledge SDK
npm i -D @x12i/memorix-docs   # product example (Memorix)
npm i @x12i/docify-core @x12i/docify-theme @x12i/docify-render \
      @x12i/docify-export @x12i/docify-sdk @x12i/docify-web
```

Knowledge packages (`@x12i/docify`, `@x12i/<product>-docs`) are **devDependencies** only.

---

## How to read this guide

1. Start with **install** above, then the **central idea** — one content library, two consumption surfaces.
2. Use **layers** when deciding platform vs product library responsibilities.
3. Jump to Packages, Authoring, For Humans, or For Agents for depth.

---

## The central idea

**x12i-docify** is the reusable **product site + docs + knowledge packs** platform for x12i monorepos.

> One content library (`BOOK.md` + use cases). Two consumption surfaces. Same design system everywhere — products change naming and content only.

| Audience | Best form | What we ship |
|---|---|---|
| **Humans** | Web app | Product home, docs hub, roles, use cases, catalog, book landings, chapter reader, MD/PDF downloads — `@x12i/docify-web` |
| **AI agents** | Markdown + packages | Per-book MD, use-case packs, chapter indexes, `agent-manifest.json`, `@x12i/docify-sdk` / product `@…-docs` |

Knowledge SDKs are **devDependencies** — documentation for tools and agents, not a production runtime.

---

## 1. What x12i-docify is

### The problem it solves

Every product monorepo needs:

- a branded docs **site** humans can browse,
- **ebooks** with stable chapter structure,
- **task-first use cases** that deep-link into chapters,
- **agent-friendly** Markdown packs and a discoverable manifest,
- one **visual system** so products do not invent competing UIs.

Docify answers that with shared packages. Product folders supply content and brand strings only.

### Who uses what

| You are… | Primary surface | Install |
|---|---|---|
| Reader (human) | Product `dist/web` | Nothing — open the site |
| Content author | `BOOK.md` + `site-pages` + `data/*.json` | Platform packages in the monorepo |
| Integrator / platform engineer | `@x12i/docify-*` | Platform packages; optional product `@…-docs` as `devDependency` |
| AI agent / tooling | MD downloads + knowledge SDK | `npm i -D @your-scope/<product>-docs` |

---

## 2. Layers

```mermaid
flowchart TB
  Platform[x12i-docify platform packages]
  Product["&lt;product&gt;-docs content library"]
  Web[dist/web for humans]
  SDK["@…-docs knowledge package"]
  Product --> Platform
  Product --> Web
  Product --> SDK
```

| Layer | What it is |
|---|---|
| `x12i-docify` | Shared platform (theme, render, web, export, SDK, screenshots) |
| `<product>-docs/` | Product content: books, site-pages, catalog, use cases |
| `@x12i/<product>-docs` | Knowledge SDK + MD packs for agents (`npm i -D`) |

Memorix is the large reference implementation: `memorix-docs/` → `@x12i/memorix-docs`.  
**This library** is the platform documenting itself (dogfood).

---

## 3. Hard rules

1. **Do not fork** `@x12i/docify-theme` or `@x12i/docify-web` per product.
2. Knowledge packages are **devDependencies**, never production UI runtime.
3. Markdown (`BOOK.md`) is the **source of truth**; HTML/PDF are derived.
4. Use-case paths must reference **real chapter slugs** (H2 headings).
5. Site pages use **YAML front-matter**; the platform renders HTML.

---

## 4. Where to go next

| Goal | Book |
|---|---|
| Package map | [Packages](../../01-packages/developers/BOOK.md) |
| Wire a new library | [Authoring a Library](../../02-authoring/developers/BOOK.md) |
| Human site behavior | [For Humans](../../03-for-humans/developers/BOOK.md) |
| Agent / SDK path | [For Agents](../../04-for-agents/developers/BOOK.md) |
| Theme contract | [Design System](../../05-design/developers/BOOK.md) |

---

# Platform Overview — builders

# x12i-docify Platform Overview — Builders

**Audience:** Content authors writing books and site pages for a product docs library.  
**Twin:** [Developers version](../developers/BOOK.md)

---

## How to read this guide

Focus on **what you author** and **what readers see**. Leave package wiring details to the developers twin unless you also own the build scripts.

---

## The central idea

You write **one library of Markdown**. Docify turns it into:

- a **website** people browse (roles → use cases → chapters),
- **downloadable books** (MD, and PDF when built),
- **use-case packs** agents can load without scraping HTML.

You do **not** design a new theme or web app. You fill content contracts.

---

## 1. What you own

| Artifact | Your job |
|---|---|
| `NN-slug/{audience}/BOOK.md` | Chapter bodies (H2 = chapter) |
| `NN-slug/site-pages/landing.md` | Book landing copy |
| `site-pages/*.md` | Product home, docs hub, getting started, … |
| `data/catalog.json` | Roles, families, book metadata |
| `data/use-cases.json` | Task → book + chapter slugs |
| `data/site.json` | Brand strings, nav, knowledge package name |

---

## 2. Layers

Product content lives in a **docs library** folder (for Memorix: `memorix-docs/`; for this platform: this tree under `x12i-docify/`). The platform packages under `packages/docify-*` stay shared.

---

## 3. Hard rules (author edition)

1. Prefer **task-first use cases** over dumping entire books into one path.
2. Chapter slugs come from **H2 titles** — rename headings carefully; update use cases.
3. Keep **developers** and **builders** twins in sync on shared facts; diverge only on depth and tone.
4. Never invent a second visual brand that fights the shared design system.

---

## 4. Where to go next

| Goal | Book |
|---|---|
| Authoring recipe | [Authoring a Library](../../02-authoring/builders/BOOK.md) |
| Human navigation | [For Humans](../../03-for-humans/builders/BOOK.md) |
| Design do / don’t | [Design System](../../05-design/builders/BOOK.md) |

---

# Packages — developers

# Packages — Developers

**Audience:** Engineers choosing and wiring `@x12i/docify-*` packages.  
**Related:** [Platform Overview](../../00-platform-overview/developers/BOOK.md) · [Authoring](../../02-authoring/developers/BOOK.md)

---

## 1. Package table

| Folder | npm | Role |
|---|---|---|
| `docify-core` | `@x12i/docify-core` | Catalog / use-case / site-page / manifest schemas + loaders |
| `docify-theme` | `@x12i/docify-theme` | Shared site + reader CSS (tokens, site, book, extras) |
| `docify-render` | `@x12i/docify-render` | `BOOK.md` + site-pages → HTML; chapter extract / splice |
| `docify-export` | `@x12i/docify-export` | Content bundle builder (downloads, landings, agent-manifest) |
| `docify-sdk` | `@x12i/docify-sdk` | `createEbooksSdk(bundle)` knowledge SDK factory |
| `docify-web` | `@x12i/docify-web` | Shareable static web app + `docify-web serve` |
| `docify-screenshots` | `@x12i/docify-screenshots` | Shot lists, placeholders, capture helpers |
| `docify` | `@x12i/docify` | Platform docs knowledge SDK (dogfood — docs of docify itself) |

---

## 2. Dependency shape

```mermaid
flowchart LR
  Core[docify-core]
  Theme[docify-theme]
  Render[docify-render]
  Export[docify-export]
  Sdk[docify-sdk]
  Web[docify-web]
  Shots[docify-screenshots]
  Dogfood["@x12i/docify"]
  Render --> Core
  Export --> Core
  Export --> Render
  Sdk --> Core
  Web --> Theme
  ProductDocs[product-docs build] --> Export
  ProductDocs --> Web
  ProductSdk["@…-docs"] --> Sdk
  Dogfood --> Sdk
```

- **Humans** consume `docify-web` + theme assets from the assembled `dist/web`.
- **Agents** consume MD packs from the bundle and/or a published product knowledge SDK built on `docify-sdk`.
- **`@x12i/docify`** is this platform’s own knowledge SDK (docs of docify).

---

## 3. Publish and install

From the monorepo (uses root `.npmrc`):

```bash
bash scripts/publish-docify.sh
```

Typical product install:

```bash
npm i @x12i/docify-core @x12i/docify-theme @x12i/docify-render \
      @x12i/docify-export @x12i/docify-sdk @x12i/docify-web
npm i -D @x12i/docify         # this platform’s docs knowledge SDK
npm i -D @x12i/memorix-docs   # example product knowledge SDK
```

In this monorepo, product builds usually **import from source** under `x12i-docify/packages/*/dist` rather than resolving published tarballs during local `npm run docs`.

---

## 4. Migration names

| Old | New |
|---|---|
| `@x12i/ebooks-*` | `@x12i/docify-*` |
| `x12i-ebooks/` | `x12i-docify/` |
| `ebooks-web` CLI | `docify-web` |
| `@x12i/memorix-ebooks` | `@x12i/memorix-docs` |

---

# Authoring a Library — developers

# Authoring a Library — Developers

**Audience:** Engineers scaffolding a product docs library on docify.  
**Twin:** [Builders version](../builders/BOOK.md)  
**Reference:** `memorix-docs/` in this monorepo · this dogfood tree under `x12i-docify/`

---

## 1. Recipe

1. Depend on `@x12i/docify-{core,theme,render,export,sdk,web}` — do **not** fork theme or web app.
2. Author books as `NN-slug/{audience}/BOOK.md`.
3. Add product data:
   - `data/site.json` — `product`, `brand`, `brandAccent`, `siteUrl`, `knowledgePackage`
   - `data/catalog.json` — roles, families, books (kickers / colors / titles)
   - `data/use-cases.json` — task → book + chapter slugs
4. Add `site-pages/*.md` with YAML front-matter (`product-home`, `docs-home`, …).
5. Wire build scripts to import platform packages (see `memorix-docs/scripts/` or `x12i-docify/scripts/`).
6. Publish `@your-scope/<product>-docs` as a **devDependency** knowledge SDK.
7. Deploy `dist/web` for humans; ship MD + `agent-manifest.json` for agents.

---

## 2. Content layout

```
<product>-docs/
  README.md                 # TWO LINES ONLY — see below
  data/{site,catalog,use-cases}.json
  site-pages/*.md
  NN-slug/
    developers/BOOK.md
    builders/BOOK.md          # optional twin
    site-pages/landing.md
    diagrams/ … screenshots/
  packages/<product>-docs/    # published knowledge SDK
    README.md                 # TWO LINES ONLY — see below
  scripts/build-bundle.mjs
  scripts/build-knowledge.mjs
  scripts/docs.mjs
```

### READMEs (two lines only)

Product docs libraries **must not** turn `README.md` into a Docify manual. Use the templates from `@x12i/docify-core` (`libraryRootReadme`, `knowledgePackageReadme`) — `docify init` writes them:

1. Title line (`# …`)
2. One pointer: humans (`npm run docs`) / agents (`npm i -D <pkg>`) / built with Docify — how-to lives in Docify, not here

`docify validate` warns when root or knowledge-package READMEs grow past that shape (sections, code fences, missing Docify mention).

---

## 3. Data contracts

| File | Owns |
|---|---|
| `site.json` | Brand chrome, accent CSS colors, nav, knowledge package name |
| `catalog.json` | Roles (`developers` \| `builders`), families, book metadata |
| `use-cases.json` | Stable use-case ids + reading paths (bookId, audience, chapter slugs) |

Chapter slugs are produced by slugifying `##` headings in `BOOK.md`. Broken use-case paths **fail the bundle build**.

---

## 4. Build pipeline

Typical scripts:

| Script | Job |
|---|---|
| `build-bundle.mjs` | `buildContentBundle` → `dist/bundle` + assemble `dist/web` |
| `build-knowledge.mjs` | Embed downloads + JSON into `packages/<sdk>/src/generated/bundle.ts` |
| `docs.mjs` | Build if needed, `docify-web serve dist/web`, open browser |

Env: set `EBOOKS_PDF=0` or `DOCIFY_PDF=0` to skip PDF when `wkhtmltopdf` is unavailable.

---

## 5. Humans vs agents after build

| Output | Audience |
|---|---|
| `dist/web` static app | Humans |
| `downloads/*.md`, chapter JSON, `agent-manifest.json` | Agents |
| Published `@…-docs` package | Agents / tooling (`npm i -D`) |

---

# Authoring a Library — builders

# Authoring a Library — Builders

**Audience:** Content authors filling a product docs library.  
**Twin:** [Developers version](../developers/BOOK.md)

---

## 1. Recipe (content side)

1. Create `NN-slug/{developers|builders}/BOOK.md` with clear `##` chapter titles.
2. Add a book landing at `NN-slug/site-pages/landing.md`.
3. Register the book in `data/catalog.json` (id, audiences, kicker, title, blurb, color, dir).
4. Add or extend use cases in `data/use-cases.json` with real chapter slugs.
5. Update site pages when the library story changes (home, getting started, catalog lead).

---

## 2. Content layout

You mostly live in:

- book folders (`BOOK.md`, diagrams, screenshots, landings),
- top-level `site-pages/`,
- `data/catalog.json` and `data/use-cases.json`.

Leave package install and `dist/` assembly to developers unless you run `npm run docs` locally to preview.

**READMEs:** library root and `packages/<product>-docs` stay at two lines (Docify pointer only). Do not expand them into Docify how-to — that lives in Docify / authored books.

---

## 3. Data contracts (what you edit)

**Catalog book entry** — title, subtitle, blurb, tags, color, audiences, status.  
**Use case** — id, title, goal, tags, and a `path` of `{ bookId, audience, chapters[] }`.

Tip: after renaming an H2, search use-cases for the old slug before merging.

---

## 4. Build pipeline (preview)

```bash
npm run docs          # build if needed, serve, open browser
npm run docs:rebuild  # force rebuild
```

Confirm landings, chapter sidebar, and use-case deep links before calling content done.

---

## 5. Writing tips

- One job per chapter; keep H2 titles stable once published.
- Cross-link twins (`developers` ↔ `builders`) at the top of each book.
- Prefer use cases that assemble **a few** chapters for a task over entire books.

---

# For Humans — developers

# For Humans — Developers

**Audience:** Engineers shipping `dist/web` for human readers.  
**Twin:** [Builders version](../builders/BOOK.md)

---

## 1. Best form for humans

The **web app** (`@x12i/docify-web`) is the human surface: case-file UI, role chooser, use-case routing, chapter reader, and download buttons.

Humans should not be asked to scrape Markdown repos as their primary path. Deploy the static tree.

---

## 2. Typical flow

1. **Role** — pick developers / builders (or product-defined roles)
2. **Use cases** — task-first entry; opens the right book + chapter
3. **Catalog** — browse books by family
4. **Reader** — chapter HTML in the shared book theme
5. **Downloads** — MD (and PDF when built) for offline reading

Product home (`/`) and docs hub (`/docs`) are authored as site-pages with YAML front-matter.

---

## 3. What the bundle emits

| Path | Role |
|---|---|
| `index.html`, `docs.html`, … | Marketing / docs chrome from site-pages |
| `books/<id>.html` | Book landings |
| `read.html` + chapter HTML | Reader shell |
| `catalog.json`, `use-cases.json`, `site.json` | Client data |
| `downloads/` | MD / PDF / chapter indexes |
| `agent-manifest.json` | Also useful for humans’ tooling links |

Assemble with `buildContentBundle`, then overlay `docify-web/public` runtime assets (`app.js`, `read.html`, `agents.html`).

---

## 4. Product libraries

Each monorepo ships its own library (e.g. Memorix at `memorix-docs/`) with brand strings and books. The platform does not fork a separate UI per product.

---

# For Humans — builders

# For Humans — Builders

**Audience:** Authors shaping how people navigate the library.  
**Twin:** [Developers version](../developers/BOOK.md)

---

## 1. Best form for humans

Readers land on the **web app**: choose a role, pick a use case or browse the catalog, then read chapters. Your job is clear titles, short blurbs, and use cases that match real tasks.

---

## 2. Typical flow

Think about the path a first-time reader takes:

1. Product home → audience chooser  
2. Getting started tracks (developers vs builders)  
3. A featured use case or book  
4. Chapter reading with a sensible next chapter  

If that path feels broken, fix catalog blurbs and use-case paths before adding more books.

---

## 3. What the bundle emits

You preview via `npm run docs`. Confirm:

- home and docs heroes read correctly,
- catalog cards show your kickers and colors,
- use cases deep-link into the intended chapters,
- downloads appear on book landings.

---

## 4. Writing for the site

- One headline job per site-page section.
- Keep CTAs to role / getting started / use cases / catalog.
- Book landings: short lead + related books — catalog stays authoritative for metadata.

---

# For Agents — developers

# For Agents — Developers

**Audience:** Engineers shipping agent-consumable knowledge.  
**Related:** [Packages](../../01-packages/developers/BOOK.md) · [Authoring](../../02-authoring/developers/BOOK.md)

---

## 1. Best form for agents

Agents should use **structured Markdown** and **packages**, not the HTML reader:

| Artifact | Role |
|---|---|
| Per-book `.md` | Full `BOOK.md` export |
| Use-case packs | Assembled MD for a task |
| `.chapters.json` | Chapter slug → title index |
| `agent-manifest.json` | Discovery map of all downloads |
| Knowledge SDK | `listUseCases`, `getUseCaseMarkdown`, `getBookMarkdown` |

---

## 2. Discovery

Without the SDK:

1. Open `/agent-manifest.json` on the deployed web app
2. Follow `downloads/` paths for MD packs
3. Prefer chapter indexes when slicing context

With the SDK: install the product knowledge package and call the typed helpers.

---

## 3. Knowledge SDK

Platform factory: `@x12i/docify-sdk` → `createEbooksSdk(bundle)`.

Product packages pre-wire a bundle (catalog, use cases, site, manifest, embedded files). Example:

```ts
import { memorixDocs } from "@x12i/memorix-docs";

const pack = memorixDocs.getUseCaseMarkdown("client-first-read-write");
const book = memorixDocs.getBookMarkdown("02-runtime-data-client", "developers");
const hits = memorixDocs.listUseCases({ audience: "developers", tag: "http" });
```

This platform’s own package is `@x12i/docify` (`docify`) — the docs of docify itself.

---

## 4. Install contract

Knowledge packages document the product for tools and agents. They are **not** a production runtime dependency.

```bash
npm i -D @x12i/docify         # this platform’s docs
npm i -D @x12i/memorix-docs   # Memorix product example
```

Export pipeline (`@x12i/docify-export`) emits MD + manifest alongside the web bundle. Stable use-case IDs keep agent prompts reproducible.

Start-here version with the full why/when: [Getting Started & Tutorials — Installation for agents](../../06-getting-started-and-tutorials/developers/BOOK.md).

---

# Design System — developers

# Design System — Developers

**Audience:** Engineers integrating theme assets into a product build.  
**Twin:** [Builders version](../builders/BOOK.md)

---

## 1. Principle

**One design system.** Product libraries change **naming and content only** — not layout, palette, or component chrome.

Wire CSS from `@x12i/docify-theme` (or the monorepo `packages/docify-theme` path) into the content bundle. Do not copy-fork stylesheets into the product folder.

---

## 2. Identity

- IBM Plex Sans / Mono
- Neutral near-white surface, single blue accent + warm builders accent (`--accent`, `--accent-alt`)
- Site chrome for product home, docs hub, catalog, use cases
- Book bodies for chapter reading (screen-tuned; print stays PDF-safe)

Product `data/site.json` may set `accent` / `accentAlt` CSS colors within the shared system — not a second brand language.

---

## 3. Surfaces

| Surface | Stylesheet | Notes |
|---|---|---|
| Web app shell | `site.css`, `extras.css` | Product/docs chrome |
| Chapter reader | `book.css` | Screen column + print rules |
| Tokens | `tokens.css` | Shared variables |

---

## 4. Do not

- Fork a second theme per product
- Invent a new brand palette that fights the shared system
- Treat the knowledge SDK as a production UI dependency
- Hand-author HTML for marketing routes — use site-page Markdown + front-matter

---

# Design System — builders

# Design System — Builders

**Audience:** Authors staying inside the shared visual system.  
**Twin:** [Developers version](../developers/BOOK.md)

---

## 1. Principle

**One design system.** You change **words, books, and brand strings** — not layout, cards chrome, or a new palette.

---

## 2. Identity

The site already carries IBM Plex, neutral surfaces, and a primary + builders accent. Catalog **book colors** are case-file accents inside that system, not a free-for-all.

---

## 3. Surfaces

| Surface | What you influence |
|---|---|
| Product / docs chrome | Site-page copy, CTAs, featured book ids |
| Chapter reader | Markdown structure and diagrams inside books |
| Catalog cards | Title, blurb, kicker, color field in `catalog.json` |

---

## 4. Do not

- Ask engineering to fork theme CSS “just for this product”
- Overload the first viewport with secondary marketing blocks (follow product-home patterns)
- Treat screenshots as decoration without a shot-list purpose

---

# Getting Started & Tutorials — developers

# Getting Started & Tutorials — Developers

**Audience:** Engineers adopting docify in a monorepo — from first install to a published knowledge package.
**Twin:** [Builders version](../builders/BOOK.md)
**Related:** [Platform Overview](../../00-platform-overview/developers/BOOK.md) · [Authoring](../../02-authoring/developers/BOOK.md) · [For Agents](../../04-for-agents/developers/BOOK.md)

---

## 1. Installation for agents

The single most useful thing you can do for AI tooling in your monorepo is install the docs **knowledge package** as a devDependency:

```bash
npm i -D @x12i/docify              # docs of the docify platform itself
npm i -D @x12i/<product>-docs      # docs of your product (e.g. @x12i/memorix-docs)
```

### Why install it

- **Versioned product truth for agents.** Cursor / Codex / CI agents get a pinned, updatable knowledge surface instead of stale prompts or scraped HTML.
- **Structured Markdown, not web pages.** The package ships per-book MD, chapter indexes (`.chapters.json`), use-case packs, and `agent-manifest.json`.
- **Typed discovery.** `listUseCases`, `getBookMarkdown`, `getUseCaseMarkdown` answer “which book / chapter?” without hallucinated paths.
- **Knowledge stays out of prompts.** Product truth lives in a package you upgrade like any dependency.

### Who needs what

| You are… | Install |
|---|---|
| Human reading docs | Nothing — use the website |
| AI agent / tooling / CI | `npm i -D @…-docs` (knowledge package) |
| Engineer wiring a docs library | `npm i @x12i/docify-{core,theme,render,export,sdk,web}` |

### The devDependency rule

Knowledge packages are **documentation for tools** — never a production runtime.

- Do: `devDependencies`, pinned or caret versions, wired into agent rules/skills.
- Do not: put `@…-docs` in `dependencies`, import it from shipped product code, or fork its content.

Point your agent at the package after install — e.g. a repo rule like “consult `@x12i/<product>-docs` (`node_modules/@x12i/<product>-docs`) before answering product questions.”

---

## 2. Getting started

The fastest working loop on this dogfood library:

```bash
cd x12i-docify
npm run docs            # build if needed, serve, open browser (port 4174)
npm run docs:rebuild    # force rebuild
npm test                # platform package tests
```

What you are looking at:

| Path | Role |
|---|---|
| `packages/docify-*` | Platform (schemas, theme, render, export, SDK, web) |
| `NN-slug/{audience}/BOOK.md` | Ebooks (H2 = chapter) |
| `site-pages/*.md` | YAML front-matter site pages |
| `data/{catalog,use-cases,sequences,site}.json` | Catalog, tasks, journey, chrome |
| `dist/web` | The built human site |

For a product library (e.g. `memorix-docs/`), the same layout applies — it depends on the platform packages and never forks theme or web UI.

---

## 3. Best practice — authoring order

Build a docs library in this order. Each step feeds the next; skipping ahead produces broken links and orphan pages.

1. **Site identity** — `data/site.json`: product, brand, `knowledgePackage`, accents.
2. **Catalog skeleton** — `data/catalog.json`: roles, family, book ids + dirs (books may start `coming-soon`).
3. **Books** — `NN-slug/{developers,builders}/BOOK.md` with clear `##` chapter titles (slugs come from them).
4. **Landings** — `NN-slug/site-pages/landing.md` per book.
5. **Use cases** — `data/use-cases.json`: task → book + real chapter slugs.
6. **Journey** — `data/sequences.json`: the ordered start-to-finish path, required vs optional steps.
7. **Site pages** — home, getting started, journey, catalog, use cases.
8. **Build + validate** — `npm run docs:rebuild`; the bundle fails on unknown books or chapter slugs.
9. **Publish** — web tree for humans, `@…-docs` for agents.

The rule of thumb mirrors the platform’s own pipeline story: declare **nouns** (books, chapters) before **paths** (use cases, journey) before **surfaces** (site pages).

---

## 4. Tutorial — run the docs site

Goal: see the dogfood site served locally.

1. `cd x12i-docify && npm run build` — compile platform packages.
2. `npm run docs` — builds the content bundle into `dist/bundle`, assembles `dist/web`, serves on port 4174.
3. Open `/docs`, `/getting-started`, `/journey`, `/catalog` and one book landing.
4. Check `/agent-manifest.json` and `/sequences.json` — those are the agent-facing artifacts.

If a page 404s, the bundle didn’t emit it — rerun `npm run docs:rebuild` and read the build error; it names the missing book/chapter.

---

## 5. Tutorial — author a book

Goal: add one book and see it everywhere.

1. Create `NN-slug/developers/BOOK.md` (and `builders/` if dual-audience). Every `##` becomes a chapter slug.
2. Add `NN-slug/site-pages/landing.md` (`page: book-landing`, `bookId`).
3. Register the book in `data/catalog.json` (id, audiences, kicker, title, blurb, color, dir).
4. Reference it from `data/use-cases.json` and, if it belongs on the path, `data/sequences.json` — use exact chapter slugs.
5. `npm run docs:rebuild` — validation fails loudly on wrong ids or slugs.
6. Verify: catalog row, landing page, reader chapters, MD download.

---

## 6. Tutorial — publish the knowledge package

Goal: ship `@…-docs` so agents can install it.

1. `npm run build:docs` — regenerates the content bundle and the generated `src/generated/bundle.ts` of the knowledge package.
2. `npm test` — the knowledge package tests assert books/use cases resolve.
3. Publish from the monorepo (see `scripts/publish-docify.sh` at repo root).
4. Consumers install with `npm i -D @…-docs` and wire it into their agents (chapter 1).

---

## 7. Where to go next

| Need | Book |
|---|---|
| Platform map | [Platform Overview](../../00-platform-overview/developers/BOOK.md) |
| Package responsibilities | [Packages](../../01-packages/developers/BOOK.md) |
| Full authoring contract | [Authoring a Library](../../02-authoring/developers/BOOK.md) |
| Agent artifacts in depth | [For Agents](../../04-for-agents/developers/BOOK.md) |
| Visual rules | [Design System](../../05-design/developers/BOOK.md) |

Or take the interactive path: open **/journey** on the docs site.

---

# Getting Started & Tutorials — builders

# Getting Started & Tutorials — Builders

**Audience:** Content authors starting a docs library — what to write, in what order, and how readers and agents consume it.
**Twin:** [Developers version](../developers/BOOK.md)
**Related:** [Platform Overview](../../00-platform-overview/builders/BOOK.md) · [Authoring](../../02-authoring/builders/BOOK.md) · [For Humans](../../03-for-humans/builders/BOOK.md)

---

## 1. Installation for agents

You write one library; two audiences consume it:

| Audience | Form | Their “install” |
|---|---|---|
| **Humans** | The website (`dist/web`) | None — they browse |
| **AI agents & tooling** | The knowledge package | `npm i -D @…-docs` |

Why the package matters to you as an author:

- Everything you write in `BOOK.md` ships **verbatim** to agents as Markdown — clear chapter titles and stable structure directly improve agent answers.
- Use-case packs are assembled from **your chapter slugs** — renaming an H2 silently changes a slug, so treat headings as contracts.
- The package is a **devDependency only**: documentation for tools, never product runtime. If someone asks to “import the docs in production,” the answer is no.

You do not publish the package yourself — engineering does — but your content is what’s inside.

---

## 2. Getting started

Preview loop while writing:

```bash
cd x12i-docify
npm run docs        # serve the built site locally (port 4174)
```

You mostly live in:

- book folders — `NN-slug/{developers,builders}/BOOK.md`, landings, diagrams, screenshots,
- top-level `site-pages/*.md`,
- `data/catalog.json`, `data/use-cases.json`, `data/sequences.json`.

Leave package wiring and `dist/` assembly to developers unless you like running builds.

---

## 3. Best practice — authoring order

Write in this order — it prevents dead links and rework:

1. **Name the books** in `data/catalog.json` first (even as `coming-soon`).
2. **Write chapters** with clear, stable `##` titles — every H2 becomes an anchor others link to.
3. **Landing per book** — one lead sentence, prerequisites, related books.
4. **Use cases after chapters exist** — each path step needs real chapter slugs.
5. **Journey last** — the ordered path across books only works when the chapters it points at are written.
6. **Site pages** — update home / getting started copy when the story changes.
7. **Preview** — `npm run docs`; the build refuses unknown books and chapter slugs, which protects you.

One idea per chapter. If a chapter needs three headlines, it is three chapters.

---

## 4. Tutorial — run the docs site

1. Ask a developer (or run yourself): `cd x12i-docify && npm run docs`.
2. Walk the reader path: docs home → getting started → journey → a book landing → chapters.
3. Confirm your latest text is there; if not, `npm run docs:rebuild`.
4. Check your chapter titles read well in the sidebar — that list is generated from your H2s.

---

## 5. Tutorial — author a book

1. Draft `NN-slug/builders/BOOK.md` (and coordinate the developers twin so H2 titles match — shared slugs keep journey links working for both).
2. Add the landing (`site-pages/landing.md`) with a one-sentence lead.
3. Register in `data/catalog.json` — kicker, title, blurb, color.
4. Add at least one use case that deep-links into your chapters.
5. Preview and click every link you created.

---

## 6. Tutorial — publish the knowledge package

Your part of the publish story:

1. Confirm chapter titles are final — slugs freeze into agent packs and prompts.
2. Confirm use cases and the journey point at the right chapters.
3. Hand off to engineering (`npm run build:docs` + publish script).
4. After publish, agents installing `npm i -D @…-docs` read exactly what you wrote.

---

## 7. Where to go next

| Need | Book |
|---|---|
| Platform mental model | [Platform Overview](../../00-platform-overview/builders/BOOK.md) |
| Authoring contract in depth | [Authoring a Library](../../02-authoring/builders/BOOK.md) |
| Reader navigation | [For Humans](../../03-for-humans/builders/BOOK.md) |
| Visual rules | [Design System](../../05-design/builders/BOOK.md) |

Or take the interactive path: open **/journey** on the docs site.