@x12i/docify-docs 1.0.0 → 1.1.0

package/files/indexes/scenarios.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "choose-content-type",
+      "title": "Choose the right Docify content type",
+      "summary": "Pick concept, guide, scenario, journey, tutorial, or reference from the reader goal.",
+      "path": "scenarios/choose-content-type.md"
+    }
+  ]
+}

package/files/indexes/scenarios.md

@@ -0,0 +1,3 @@
+# scenarios
+
+- `choose-content-type` — Choose the right Docify content type — Pick concept, guide, scenario, journey, tutorial, or reference from the reader goal.

package/files/indexes/tutorials.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "items": []
+}

package/files/indexes/tutorials.md

@@ -0,0 +1,3 @@
+# tutorials
+
+

package/files/indexes/use-cases.json

@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "orient-docify",
+      "title": "Orient on x12i-docify",
+      "summary": "Understand the dual-audience platform and where product libraries fit.",
+      "path": "use-cases/orient-docify.md"
+    },
+    {
+      "id": "map-packages",
+      "title": "Map the @x12i/docify-* packages",
+      "summary": "Know which package owns schemas, theme, render, export, SDK, web, and screenshots.",
+      "path": "use-cases/map-packages.md"
+    },
+    {
+      "id": "wire-product-library",
+      "title": "Wire a product docs library",
+      "summary": "Add books, data/*.json, site-pages, and build scripts in another monorepo without forking theme or web.",
+      "path": "use-cases/wire-product-library.md"
+    },
+    {
+      "id": "ship-human-site",
+      "title": "Ship the human web app",
+      "summary": "Build and serve dist/web with roles, use cases, catalog, and chapter reader.",
+      "path": "use-cases/ship-human-site.md"
+    },
+    {
+      "id": "ship-agent-packs",
+      "title": "Ship agent markdown and knowledge SDK",
+      "summary": "Export MD packs, agent-manifest.json, and a product @…-docs package for npm i -D.",
+      "path": "use-cases/ship-agent-packs.md"
+    },
+    {
+      "id": "keep-one-design",
+      "title": "Keep one design system",
+      "summary": "Change product naming and content only — never fork theme or invent a competing palette.",
+      "path": "use-cases/keep-one-design.md"
+    }
+  ]
+}

package/files/indexes/use-cases.md

@@ -0,0 +1,8 @@
+# use-cases
+
+- `orient-docify` — Orient on x12i-docify — Understand the dual-audience platform and where product libraries fit.
+- `map-packages` — Map the @x12i/docify-* packages — Know which package owns schemas, theme, render, export, SDK, web, and screenshots.
+- `wire-product-library` — Wire a product docs library — Add books, data/*.json, site-pages, and build scripts in another monorepo without forking theme or web.
+- `ship-human-site` — Ship the human web app — Build and serve dist/web with roles, use cases, catalog, and chapter reader.
+- `ship-agent-packs` — Ship agent markdown and knowledge SDK — Export MD packs, agent-manifest.json, and a product @…-docs package for npm i -D.
+- `keep-one-design` — Keep one design system — Change product naming and content only — never fork theme or invent a competing palette.

package/files/knowledge.json

@@ -0,0 +1,361 @@
+{
+  "concepts": [
+    {
+      "summary": "Docify only builds knowledge that authors declare — it never discovers product truth from source.",
+      "problem": "Auto-scanning repositories invents incomplete or wrong documentation.",
+      "why": "Accessibility requires intentional explanations, relationships, and confirmation boundaries.",
+      "mentalModel": "Authors understand; Docify packages and presents.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [
+        "Starting a docs library",
+        "Asking an agent to document a product"
+      ],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "open-markdown",
+        "knowledge-relationships"
+      ],
+      "next": [
+        "open-markdown"
+      ],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "authoring",
+        "boundary"
+      ],
+      "id": "explicit-authoring",
+      "type": "concept",
+      "title": "Explicit authoring",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Every knowledge item ships as readable Markdown plus indexes — the SDK is optional.",
+      "problem": "Knowledge trapped in generated JS or HTML blocks offline and agent workflows.",
+      "why": "Agents and humans must grep, read, and pack the same facts without executing code.",
+      "mentalModel": "INDEX.md and SEARCH.json are the door; Markdown files are the rooms.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "explicit-authoring"
+      ],
+      "next": [
+        "guide-vs-scenario"
+      ],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "agents",
+        "packaging"
+      ],
+      "id": "open-markdown",
+      "type": "concept",
+      "title": "Open Markdown baseline",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Guides are bounded procedures; scenarios branch on state; journeys compose an end-to-end outcome.",
+      "problem": "Mixing learning, diagnosis, and production procedures confuses agents and operators.",
+      "why": "Clear types keep invariants and confirmation boundaries enforceable.",
+      "mentalModel": "Scenario chooses a guide; journey sequences several guides and decisions.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "explicit-authoring"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "authoring"
+      ],
+      "id": "guide-vs-scenario",
+      "type": "concept",
+      "title": "Guides vs scenarios vs journeys",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    }
+  ],
+  "guides": [
+    {
+      "summary": "Create a validated concept with problem, why, and mental model.",
+      "why": "Concepts without why become unusable glossary stubs.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "explicit-authoring"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Docify does not invent the concept from source code"
+      ],
+      "alternatives": [],
+      "confirmationRequired": false,
+      "tags": [
+        "authoring"
+      ],
+      "id": "scaffold-concept",
+      "type": "guide",
+      "title": "Scaffold a concept page",
+      "useWhen": [
+        "Documenting a product idea that needs explanation first"
+      ],
+      "doNotUseWhen": [
+        "Writing a step-by-step production procedure (use a guide)"
+      ],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "scaffold",
+          "title": "Run docify scaffold concept <id>",
+          "expectedResult": "Markdown file under concepts/",
+          "optional": false
+        },
+        {
+          "id": "fill",
+          "title": "Fill summary, problem, why, mental model",
+          "expectedResult": "Human-understanding fields present",
+          "optional": false
+        },
+        {
+          "id": "validate",
+          "title": "Run docify validate",
+          "expectedResult": "Validation passes",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Concept appears in INDEX.md after build"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    }
+  ],
+  "scenarios": [
+    {
+      "summary": "Pick concept, guide, scenario, journey, tutorial, or reference from the reader goal.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Do not invent unsupported actions from a broad why statement"
+      ],
+      "alternatives": [],
+      "tags": [],
+      "id": "choose-content-type",
+      "type": "scenario",
+      "title": "Choose the right Docify content type",
+      "situation": "An agent is asked to document a product behavior and is unsure which file to create.",
+      "preconditions": [
+        "Product material is explicitly supplied"
+      ],
+      "signals": [
+        "Need a definition and why",
+        "Need a bounded production procedure",
+        "Need branching on observed state",
+        "Need safe rehearsal with sample data"
+      ],
+      "decisionQuestion": "Which Docify content type fits this goal?",
+      "paths": [
+        {
+          "id": "concept",
+          "label": "Author a concept",
+          "when": "The reader needs what it is and why it exists",
+          "rationale": "Concepts carry mental models before procedures.",
+          "guideIds": [
+            "scaffold-concept"
+          ]
+        },
+        {
+          "id": "guide",
+          "label": "Author a guide",
+          "when": "The reader needs a bounded task with verification",
+          "rationale": "Guides are normative procedures with confirmation boundaries.",
+          "guideIds": [
+            "scaffold-concept"
+          ]
+        },
+        {
+          "id": "tutorial",
+          "label": "Author a tutorial",
+          "when": "The goal is learning with sample data and reset",
+          "rationale": "Tutorials teach; production guides remain usable without them.",
+          "guideIds": []
+        }
+      ],
+      "verification": [
+        "Selected type matches the FR selection table"
+      ],
+      "recovery": [],
+      "escalation": "If product truth is unclear, stop and ask the product owners — do not infer from source."
+    }
+  ],
+  "decisions": [],
+  "glossary": [
+    {
+      "id": "docify",
+      "term": "Docify",
+      "meaning": "x12i framework that turns explicitly authored product knowledge into a website and agent package.",
+      "technicalName": "@x12i/docify",
+      "aliases": [
+        "x12i-docify"
+      ],
+      "relatedConceptIds": [
+        "explicit-authoring"
+      ],
+      "firstPageId": "explicit-authoring"
+    },
+    {
+      "id": "search-json",
+      "term": "SEARCH.json",
+      "meaning": "Deterministic local search index over all addressable knowledge items.",
+      "aliases": [
+        "search index"
+      ],
+      "relatedConceptIds": [
+        "open-markdown"
+      ]
+    }
+  ],
+  "visuals": [],
+  "diagrams": [
+    {
+      "id": "docify-dual-audience",
+      "type": "flow",
+      "title": "One library, two consumption surfaces",
+      "summary": "Explicitly authored content becomes a human website and an agent knowledge package.",
+      "why": "Humans and agents share one source model without forked facts.",
+      "direction": "left-to-right",
+      "nodes": [
+        {
+          "id": "authors",
+          "label": "Authors",
+          "description": "Humans or agents write explicit knowledge",
+          "conceptId": "explicit-authoring"
+        },
+        {
+          "id": "validate",
+          "label": "Validate",
+          "description": "Schemas, links, a11y metadata"
+        },
+        {
+          "id": "web",
+          "label": "Website",
+          "description": "Human consumption"
+        },
+        {
+          "id": "agent",
+          "label": "Agent package",
+          "description": "INDEX, SEARCH, Markdown, SDK",
+          "conceptId": "open-markdown"
+        }
+      ],
+      "edges": [
+        {
+          "from": "authors",
+          "to": "validate",
+          "label": "declare",
+          "description": "Only declared inputs are processed"
+        },
+        {
+          "from": "validate",
+          "to": "web",
+          "label": "render"
+        },
+        {
+          "from": "validate",
+          "to": "agent",
+          "label": "pack"
+        }
+      ],
+      "howToRead": "Follow arrows from authored sources to human and agent outputs.",
+      "keyTakeaways": [
+        "Authors own product truth",
+        "Docify never scans the product repository",
+        "Open Markdown is the agent baseline"
+      ],
+      "textAlternative": "Authors write books, concepts, guides, diagrams, and data files. Docify validates and builds a website for humans and Markdown indexes, packs, and an SDK for agents.",
+      "mermaid": "flowchart LR\n  authors[Authors] --> validate[Validate]\n  validate --> web[Website]\n  validate --> agent[Agent package]\n",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "related": [
+        "explicit-authoring",
+        "open-markdown"
+      ],
+      "tags": [
+        "platform"
+      ]
+    }
+  ],
+  "relationships": [
+    {
+      "id": "explicit-to-open-md",
+      "type": "prerequisiteOf",
+      "from": "explicit-authoring",
+      "to": "open-markdown",
+      "label": "enables",
+      "description": "Explicit authorship feeds open Markdown packaging"
+    },
+    {
+      "id": "types-related",
+      "type": "relatedTo",
+      "from": "guide-vs-scenario",
+      "to": "explicit-authoring",
+      "description": "Type selection is part of the authoring method"
+    }
+  ],
+  "tutorials": [],
+  "examples": [],
+  "sampleData": [],
+  "uiClients": [],
+  "apis": []
+}

package/files/packs/concept/explicit-authoring/PACK.md

@@ -0,0 +1,11 @@
+---
+id: "concept/explicit-authoring"
+type: "pack"
+title: "Explicit authoring"
+summary: "Docify only builds knowledge that authors declare — it never discovers product truth from source."
+---
+# Pack: Explicit authoring
+
+Docify only builds knowledge that authors declare — it never discovers product truth from source.
+
+Primary markdown: `concepts/explicit-authoring.md`

package/files/packs/concept/explicit-authoring/pack.json

@@ -0,0 +1,14 @@
+{
+  "id": "concept/explicit-authoring",
+  "type": "concept",
+  "title": "Explicit authoring",
+  "summary": "Docify only builds knowledge that authors declare — it never discovers product truth from source.",
+  "markdownPath": "concepts/explicit-authoring.md",
+  "files": [
+    "concepts/explicit-authoring.md"
+  ],
+  "related": [
+    "open-markdown",
+    "knowledge-relationships"
+  ]
+}

package/files/packs/concept/guide-vs-scenario/PACK.md

@@ -0,0 +1,11 @@
+---
+id: "concept/guide-vs-scenario"
+type: "pack"
+title: "Guides vs scenarios vs journeys"
+summary: "Guides are bounded procedures; scenarios branch on state; journeys compose an end-to-end outcome."
+---
+# Pack: Guides vs scenarios vs journeys
+
+Guides are bounded procedures; scenarios branch on state; journeys compose an end-to-end outcome.
+
+Primary markdown: `concepts/guide-vs-scenario.md`

package/files/packs/concept/guide-vs-scenario/pack.json

@@ -0,0 +1,13 @@
+{
+  "id": "concept/guide-vs-scenario",
+  "type": "concept",
+  "title": "Guides vs scenarios vs journeys",
+  "summary": "Guides are bounded procedures; scenarios branch on state; journeys compose an end-to-end outcome.",
+  "markdownPath": "concepts/guide-vs-scenario.md",
+  "files": [
+    "concepts/guide-vs-scenario.md"
+  ],
+  "related": [
+    "explicit-authoring"
+  ]
+}

package/files/packs/concept/open-markdown/PACK.md

@@ -0,0 +1,11 @@
+---
+id: "concept/open-markdown"
+type: "pack"
+title: "Open Markdown baseline"
+summary: "Every knowledge item ships as readable Markdown plus indexes — the SDK is optional."
+---
+# Pack: Open Markdown baseline
+
+Every knowledge item ships as readable Markdown plus indexes — the SDK is optional.
+
+Primary markdown: `concepts/open-markdown.md`

package/files/packs/concept/open-markdown/pack.json

@@ -0,0 +1,13 @@
+{
+  "id": "concept/open-markdown",
+  "type": "concept",
+  "title": "Open Markdown baseline",
+  "summary": "Every knowledge item ships as readable Markdown plus indexes — the SDK is optional.",
+  "markdownPath": "concepts/open-markdown.md",
+  "files": [
+    "concepts/open-markdown.md"
+  ],
+  "related": [
+    "explicit-authoring"
+  ]
+}

package/files/packs/guide/scaffold-concept/PACK.md

@@ -0,0 +1,11 @@
+---
+id: "guide/scaffold-concept"
+type: "pack"
+title: "Scaffold a concept page"
+summary: "Create a validated concept with problem, why, and mental model."
+---
+# Pack: Scaffold a concept page
+
+Create a validated concept with problem, why, and mental model.
+
+Primary markdown: `guides/scaffold-concept.md`

package/files/packs/guide/scaffold-concept/pack.json

@@ -0,0 +1,13 @@
+{
+  "id": "guide/scaffold-concept",
+  "type": "guide",
+  "title": "Scaffold a concept page",
+  "summary": "Create a validated concept with problem, why, and mental model.",
+  "markdownPath": "guides/scaffold-concept.md",
+  "files": [
+    "guides/scaffold-concept.md"
+  ],
+  "related": [
+    "explicit-authoring"
+  ]
+}

package/files/packs/scenario/choose-content-type/PACK.md

@@ -0,0 +1,11 @@
+---
+id: "scenario/choose-content-type"
+type: "pack"
+title: "Choose the right Docify content type"
+summary: "Pick concept, guide, scenario, journey, tutorial, or reference from the reader goal."
+---
+# Pack: Choose the right Docify content type
+
+Pick concept, guide, scenario, journey, tutorial, or reference from the reader goal.
+
+Primary markdown: `scenarios/choose-content-type.md`

package/files/packs/scenario/choose-content-type/pack.json

@@ -0,0 +1,11 @@
+{
+  "id": "scenario/choose-content-type",
+  "type": "scenario",
+  "title": "Choose the right Docify content type",
+  "summary": "Pick concept, guide, scenario, journey, tutorial, or reference from the reader goal.",
+  "markdownPath": "scenarios/choose-content-type.md",
+  "files": [
+    "scenarios/choose-content-type.md"
+  ],
+  "related": []
+}

package/files/scenarios/choose-content-type.md

@@ -0,0 +1,54 @@
+---
+id: "choose-content-type"
+type: "scenario"
+title: "Choose the right Docify content type"
+summary: "Pick concept, guide, scenario, journey, tutorial, or reference from the reader goal."
+audiences: ["developers", "builders"]
+invariants: ["Do not invent unsupported actions from a broad why statement"]
+---
+# Choose the right Docify content type
+
+## Situation
+
+An agent is asked to document a product behavior and is unsure which file to create.
+
+## Decision
+
+Which Docify content type fits this goal?
+
+## Signals
+
+- Need a definition and why
+- Need a bounded production procedure
+- Need branching on observed state
+- Need safe rehearsal with sample data
+
+## Paths
+
+### Author a concept
+
+**When:** The reader needs what it is and why it exists
+
+Concepts carry mental models before procedures.
+
+Guides: `scaffold-concept`
+
+### Author a guide
+
+**When:** The reader needs a bounded task with verification
+
+Guides are normative procedures with confirmation boundaries.
+
+Guides: `scaffold-concept`
+
+### Author a tutorial
+
+**When:** The goal is learning with sample data and reset
+
+Tutorials teach; production guides remain usable without them.
+
+Guides: _none_
+
+## Escalation
+
+If product truth is unclear, stop and ask the product owners — do not infer from source.

package/files/use-cases/keep-one-design.md

@@ -0,0 +1,46 @@
+# Keep one design system
+
+> **Use case id:** `keep-one-design`
+> **Goal:** Change product naming and content only — never fork theme or invent a competing palette.
+> **Audiences:** developers, builders
+> **Tags:** design, theme
+
+## Reading path
+
+1. **Design System** (builders) → chapters: `1-principle`, `2-identity`, `3-surfaces`, `4-do-not`
+
+## From: Design System — 1. Principle
+
+**One design system.** You change **words, books, and brand strings** — not layout, cards chrome, or a new palette.
+
+---
+
+## From: Design System — 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.
+
+---
+
+## From: Design System — 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` |
+
+---
+
+## From: Design System — 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
+
+## Also see
+
+- **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._