@x12i/docify-docs 1.0.0 → 1.1.0

package/files/use-cases/map-packages.md

@@ -0,0 +1,83 @@
+# Map the @x12i/docify-* packages
+
+> **Use case id:** `map-packages`
+> **Goal:** Know which package owns schemas, theme, render, export, SDK, web, and screenshots.
+> **Audiences:** developers
+> **Tags:** packages, npm
+
+## Reading path
+
+1. **Packages** (developers) → chapters: `1-package-table`, `2-dependency-shape`, `3-publish-and-install`
+
+## From: Packages — 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) |
+
+---
+
+## From: Packages — 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).
+
+---
+
+## From: Packages — 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`.
+
+---
+
+## Also see
+
+- **Packages** (`01-packages`) — Core, theme, render, export, SDK, web, and screenshots — what each package owns.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/orient-docify.md

@@ -0,0 +1,92 @@
+# Orient on x12i-docify
+
+> **Use case id:** `orient-docify`
+> **Goal:** Understand the dual-audience platform and where product libraries fit.
+> **Audiences:** developers, builders
+> **Tags:** platform, start-here
+
+## Reading path
+
+1. **Platform Overview** (developers) → chapters: `the-central-idea`, `1-what-x12i-docify-is`, `2-layers`, `4-where-to-go-next`
+
+## From: Platform Overview — 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.
+
+---
+
+## From: Platform Overview — 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` |
+
+---
+
+## From: Platform Overview — 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).
+
+---
+
+## From: Platform Overview — 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) |
+
+## Also see
+
+- **Platform Overview** (`00-platform-overview`) — What x12i-docify is, who it serves, and how product libraries plug in without forking UI.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/ship-agent-packs.md

@@ -0,0 +1,75 @@
+# Ship agent markdown and knowledge SDK
+
+> **Use case id:** `ship-agent-packs`
+> **Goal:** Export MD packs, agent-manifest.json, and a product @…-docs package for npm i -D.
+> **Audiences:** developers
+> **Tags:** agents, sdk
+
+## Reading path
+
+1. **For Agents** (developers) → chapters: `1-best-form-for-agents`, `2-discovery`, `3-knowledge-sdk`, `4-install-contract`
+
+## From: For Agents — 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` |
+
+---
+
+## From: For Agents — 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.
+
+---
+
+## From: For Agents — 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.
+
+---
+
+## From: For Agents — 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).
+
+## Also see
+
+- **For Agents** (`04-for-agents`) — MD packs, chapter indexes, agent-manifest.json, and createEbooksSdk — install knowledge as a devDependency.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/ship-human-site.md

@@ -0,0 +1,53 @@
+# Ship the human web app
+
+> **Use case id:** `ship-human-site`
+> **Goal:** Build and serve dist/web with roles, use cases, catalog, and chapter reader.
+> **Audiences:** developers, builders
+> **Tags:** humans, web
+
+## Reading path
+
+1. **For Humans** (developers) → chapters: `1-best-form-for-humans`, `2-typical-flow`, `3-what-the-bundle-emits`
+
+## From: For Humans — 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.
+
+---
+
+## From: For Humans — 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.
+
+---
+
+## From: For Humans — 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`).
+
+---
+
+## Also see
+
+- **For Humans** (`03-for-humans`) — How people use @x12i/docify-web — roles, use cases, catalog, chapter reader, downloads.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/wire-product-library.md

@@ -0,0 +1,79 @@
+# Wire a product docs library
+
+> **Use case id:** `wire-product-library`
+> **Goal:** Add books, data/*.json, site-pages, and build scripts in another monorepo without forking theme or web.
+> **Audiences:** developers, builders
+> **Tags:** authoring, getting-started
+
+## Reading path
+
+1. **Authoring a Library** (developers) → chapters: `1-recipe`, `2-content-layout`, `3-data-contracts`, `4-build-pipeline`
+
+## From: Authoring a Library — 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.
+
+---
+
+## From: Authoring a Library — 2. Content layout
+
+```
+<product>-docs/
+  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
+  scripts/build-bundle.mjs
+  scripts/build-knowledge.mjs
+  scripts/docs.mjs
+```
+
+---
+
+## From: Authoring a Library — 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**.
+
+---
+
+## From: Authoring a Library — 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.
+
+---
+
+## Also see
+
+- **Authoring a Library** (`02-authoring`) — Recipe to ship a product docs library: BOOK.md layout, data/*.json, site-pages, and the build pipeline.
+- **Design System** (`05-design`) — Shared theme tokens and surfaces — products change naming and content only.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/package.json

@@ -1,13 +1,10 @@
 {
   "name": "@x12i/docify-docs",
-  "version": "1.0.0",
-  "description": "x12i-docify platform docs knowledge SDK — install as a devDependency only. Catalog, use cases, and markdown packs for humans and agents.",
+  "version": "1.1.0",
+  "description": "Docify platform dogfood knowledge package — open Markdown, indexes, and SDK. Install as a devDependency only.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "docify-docs": "bin/docify-docs.js"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -16,42 +13,27 @@
   },
   "files": [
     "dist",
-    "bin",
+    "files",
     "README.md"
   ],
   "scripts": {
     "prebuild": "rm -rf dist",
-    "build": "tsc -p tsconfig.build.json && node -e \"import('node:fs').then(fs=>fs.chmodSync('dist/cli.js',0o755))\"",
-    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@x12i/docify-core": "^1.0.1",
-    "@x12i/docify-sdk": "^1.0.1"
+    "@x12i/docify": "^1.1.0",
+    "@x12i/docify-sdk": "^1.1.0"
   },
   "devDependencies": {
-    "@types/node": "^20.14.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
+    "typescript": "^5.6.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+ssh://git@github.com/x12i/memorix-mono-repo.git",
-    "directory": "x12i-docify/packages/docify-docs"
-  },
-  "keywords": [
-    "x12i",
-    "docify",
-    "docs",
-    "knowledge",
-    "devDependency"
-  ],
   "license": "exellix-license"
 }

package/bin/docify-docs.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import('../dist/cli.js');

package/dist/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -1,56 +0,0 @@
-#!/usr/bin/env node
-import { docifyDocs } from "./index.js";
-const [cmd, id, audience] = process.argv.slice(2);
-function usage() {
-    console.error(`Usage:
-  docify-docs use-case <id>          Print assembled use-case markdown
-  docify-docs book <id> <audience>   Print book markdown
-  docify-docs list-use-cases         List use case ids
-  docify-docs list-books             List book ids
-`);
-}
-if (!cmd || cmd === "help" || cmd === "--help") {
-    usage();
-    process.exit(cmd ? 0 : 1);
-}
-if (cmd === "list-use-cases") {
-    for (const uc of docifyDocs.listUseCases()) {
-        console.log(`${uc.id}\t${uc.title}`);
-    }
-    process.exit(0);
-}
-if (cmd === "list-books") {
-    for (const b of docifyDocs.listBooks()) {
-        console.log(`${b.id}\t${b.title}\t${b.audiences.join(",")}`);
-    }
-    process.exit(0);
-}
-if (cmd === "use-case") {
-    if (!id) {
-        usage();
-        process.exit(1);
-    }
-    const md = docifyDocs.getUseCaseMarkdown(id);
-    if (!md) {
-        console.error(`Unknown use case: ${id}`);
-        process.exit(1);
-    }
-    process.stdout.write(md);
-    process.exit(0);
-}
-if (cmd === "book") {
-    if (!id || !audience) {
-        usage();
-        process.exit(1);
-    }
-    const md = docifyDocs.getBookMarkdown(id, audience);
-    if (!md) {
-        console.error(`Unknown book/audience: ${id} ${audience}`);
-        process.exit(1);
-    }
-    process.stdout.write(md);
-    process.exit(0);
-}
-usage();
-process.exit(1);
-//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,CAAC,GAAG,EAAE,EAAE,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAElD,SAAS,KAAK;IACZ,OAAO,CAAC,KAAK,CAAC;;;;;CAKf,CAAC,CAAC;AACH,CAAC;AAED,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;IAC/C,KAAK,EAAE,CAAC;IACR,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED,IAAI,GAAG,KAAK,gBAAgB,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAE,IAAI,UAAU,CAAC,YAAY,EAAE,EAAE,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,KAAK,EAAE,CAAC;QACR,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,EAAE,GAAG,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;QACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACrB,KAAK,EAAE,CAAC;QACR,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,EAAE,GAAG,UAAU,CAAC,eAAe,CAAC,EAAE,EAAE,QAAqC,CAAC,CAAC;IACjF,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,IAAI,QAAQ,EAAE,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,KAAK,EAAE,CAAC;AACR,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}