@x12i/docify-docs 1.0.0 → 1.1.0

package/files/agent-manifest.json

@@ -0,0 +1,342 @@
+{
+  "version": 1,
+  "product": "docify",
+  "site": "https://docs.docify.x12i.com",
+  "knowledgePackage": "@x12i/docify",
+  "roles": [
+    "developers",
+    "builders"
+  ],
+  "books": [
+    {
+      "id": "00-platform-overview",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "md": {
+        "developers": "downloads/books/00-platform-overview/developers.md",
+        "builders": "downloads/books/00-platform-overview/builders.md"
+      },
+      "pdf": {
+        "developers": null,
+        "builders": null
+      },
+      "chapters": {
+        "developers": "downloads/books/00-platform-overview/developers.chapters.json",
+        "builders": "downloads/books/00-platform-overview/builders.chapters.json"
+      }
+    },
+    {
+      "id": "01-packages",
+      "audiences": [
+        "developers"
+      ],
+      "md": {
+        "developers": "downloads/books/01-packages/developers.md"
+      },
+      "pdf": {
+        "developers": null
+      },
+      "chapters": {
+        "developers": "downloads/books/01-packages/developers.chapters.json"
+      }
+    },
+    {
+      "id": "02-authoring",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "md": {
+        "developers": "downloads/books/02-authoring/developers.md",
+        "builders": "downloads/books/02-authoring/builders.md"
+      },
+      "pdf": {
+        "developers": null,
+        "builders": null
+      },
+      "chapters": {
+        "developers": "downloads/books/02-authoring/developers.chapters.json",
+        "builders": "downloads/books/02-authoring/builders.chapters.json"
+      }
+    },
+    {
+      "id": "03-for-humans",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "md": {
+        "developers": "downloads/books/03-for-humans/developers.md",
+        "builders": "downloads/books/03-for-humans/builders.md"
+      },
+      "pdf": {
+        "developers": null,
+        "builders": null
+      },
+      "chapters": {
+        "developers": "downloads/books/03-for-humans/developers.chapters.json",
+        "builders": "downloads/books/03-for-humans/builders.chapters.json"
+      }
+    },
+    {
+      "id": "04-for-agents",
+      "audiences": [
+        "developers"
+      ],
+      "md": {
+        "developers": "downloads/books/04-for-agents/developers.md"
+      },
+      "pdf": {
+        "developers": null
+      },
+      "chapters": {
+        "developers": "downloads/books/04-for-agents/developers.chapters.json"
+      }
+    },
+    {
+      "id": "05-design",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "md": {
+        "developers": "downloads/books/05-design/developers.md",
+        "builders": "downloads/books/05-design/builders.md"
+      },
+      "pdf": {
+        "developers": null,
+        "builders": null
+      },
+      "chapters": {
+        "developers": "downloads/books/05-design/developers.chapters.json",
+        "builders": "downloads/books/05-design/builders.chapters.json"
+      }
+    },
+    {
+      "id": "06-getting-started-and-tutorials",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "md": {
+        "developers": "downloads/books/06-getting-started-and-tutorials/developers.md",
+        "builders": "downloads/books/06-getting-started-and-tutorials/builders.md"
+      },
+      "pdf": {
+        "developers": null,
+        "builders": null
+      },
+      "chapters": {
+        "developers": "downloads/books/06-getting-started-and-tutorials/developers.chapters.json",
+        "builders": "downloads/books/06-getting-started-and-tutorials/builders.chapters.json"
+      }
+    }
+  ],
+  "useCases": [
+    {
+      "id": "orient-docify",
+      "title": "Orient on x12i-docify",
+      "md": "downloads/use-cases/orient-docify.md",
+      "path": [
+        {
+          "bookId": "00-platform-overview",
+          "audience": "developers",
+          "chapters": [
+            "the-central-idea",
+            "1-what-x12i-docify-is",
+            "2-layers",
+            "4-where-to-go-next"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "map-packages",
+      "title": "Map the @x12i/docify-* packages",
+      "md": "downloads/use-cases/map-packages.md",
+      "path": [
+        {
+          "bookId": "01-packages",
+          "audience": "developers",
+          "chapters": [
+            "1-package-table",
+            "2-dependency-shape",
+            "3-publish-and-install"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "wire-product-library",
+      "title": "Wire a product docs library",
+      "md": "downloads/use-cases/wire-product-library.md",
+      "path": [
+        {
+          "bookId": "02-authoring",
+          "audience": "developers",
+          "chapters": [
+            "1-recipe",
+            "2-content-layout",
+            "3-data-contracts",
+            "4-build-pipeline"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "ship-human-site",
+      "title": "Ship the human web app",
+      "md": "downloads/use-cases/ship-human-site.md",
+      "path": [
+        {
+          "bookId": "03-for-humans",
+          "audience": "developers",
+          "chapters": [
+            "1-best-form-for-humans",
+            "2-typical-flow",
+            "3-what-the-bundle-emits"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "ship-agent-packs",
+      "title": "Ship agent markdown and knowledge SDK",
+      "md": "downloads/use-cases/ship-agent-packs.md",
+      "path": [
+        {
+          "bookId": "04-for-agents",
+          "audience": "developers",
+          "chapters": [
+            "1-best-form-for-agents",
+            "2-discovery",
+            "3-knowledge-sdk",
+            "4-install-contract"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "keep-one-design",
+      "title": "Keep one design system",
+      "md": "downloads/use-cases/keep-one-design.md",
+      "path": [
+        {
+          "bookId": "05-design",
+          "audience": "builders",
+          "chapters": [
+            "1-principle",
+            "2-identity",
+            "3-surfaces",
+            "4-do-not"
+          ]
+        }
+      ]
+    }
+  ],
+  "indexes": {
+    "indexMd": "INDEX.md",
+    "searchJson": "SEARCH.json"
+  },
+  "concepts": [
+    {
+      "id": "explicit-authoring",
+      "title": "Explicit authoring",
+      "md": "concepts/explicit-authoring.md"
+    },
+    {
+      "id": "open-markdown",
+      "title": "Open Markdown baseline",
+      "md": "concepts/open-markdown.md"
+    },
+    {
+      "id": "guide-vs-scenario",
+      "title": "Guides vs scenarios vs journeys",
+      "md": "concepts/guide-vs-scenario.md"
+    }
+  ],
+  "guides": [
+    {
+      "id": "scaffold-concept",
+      "title": "Scaffold a concept page",
+      "md": "guides/scaffold-concept.md"
+    }
+  ],
+  "scenarios": [
+    {
+      "id": "choose-content-type",
+      "title": "Choose the right Docify content type",
+      "md": "scenarios/choose-content-type.md"
+    }
+  ],
+  "decisions": [],
+  "glossary": [
+    {
+      "id": "docify",
+      "term": "Docify",
+      "md": "glossary/docify.md"
+    },
+    {
+      "id": "search-json",
+      "term": "SEARCH.json",
+      "md": "glossary/search-json.md"
+    }
+  ],
+  "visuals": [],
+  "diagrams": [
+    {
+      "id": "docify-dual-audience",
+      "title": "One library, two consumption surfaces",
+      "md": "diagrams/docify-dual-audience.md",
+      "source": "diagrams/sources/docify-dual-audience.mmd"
+    }
+  ],
+  "relationships": [
+    {
+      "id": "explicit-to-open-md",
+      "type": "prerequisiteOf",
+      "from": "explicit-authoring",
+      "to": "open-markdown"
+    },
+    {
+      "id": "types-related",
+      "type": "relatedTo",
+      "from": "guide-vs-scenario",
+      "to": "explicit-authoring"
+    }
+  ],
+  "tutorials": [],
+  "examples": [],
+  "sampleData": [],
+  "uiClients": [],
+  "apis": [],
+  "packs": [
+    {
+      "id": "concept/explicit-authoring",
+      "type": "concept",
+      "path": "packs/concept/explicit-authoring"
+    },
+    {
+      "id": "concept/open-markdown",
+      "type": "concept",
+      "path": "packs/concept/open-markdown"
+    },
+    {
+      "id": "concept/guide-vs-scenario",
+      "type": "concept",
+      "path": "packs/concept/guide-vs-scenario"
+    },
+    {
+      "id": "guide/scaffold-concept",
+      "type": "guide",
+      "path": "packs/guide/scaffold-concept"
+    },
+    {
+      "id": "scenario/choose-content-type",
+      "type": "scenario",
+      "path": "packs/scenario/choose-content-type"
+    }
+  ]
+}

package/files/concepts/explicit-authoring.md

@@ -0,0 +1,27 @@
+---
+id: "explicit-authoring"
+type: "concept"
+title: "Explicit authoring"
+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"]
+related: ["open-markdown", "knowledge-relationships"]
+next: ["open-markdown"]
+---
+# Explicit authoring
+
+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.
+
+## Mental model
+
+Authors understand; Docify packages and presents.

package/files/concepts/guide-vs-scenario.md

@@ -0,0 +1,26 @@
+---
+id: "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."
+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"]
+related: ["explicit-authoring"]
+---
+# Guides vs scenarios vs journeys
+
+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.
+
+## Mental model
+
+Scenario chooses a guide; journey sequences several guides and decisions.

package/files/concepts/open-markdown.md

@@ -0,0 +1,27 @@
+---
+id: "open-markdown"
+type: "concept"
+title: "Open Markdown baseline"
+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"]
+related: ["explicit-authoring"]
+next: ["guide-vs-scenario"]
+---
+# Open Markdown baseline
+
+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.
+
+## Mental model
+
+INDEX.md and SEARCH.json are the door; Markdown files are the rooms.

package/files/diagrams/docify-dual-audience.md

@@ -0,0 +1,54 @@
+---
+id: "docify-dual-audience"
+type: "diagram"
+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."
+diagramType: "flow"
+audiences: ["developers", "builders"]
+related: ["explicit-authoring", "open-markdown"]
+---
+# One library, two consumption surfaces
+
+Explicitly authored content becomes a human website and an agent knowledge package.
+
+## Why
+
+Humans and agents share one source model without forked facts.
+
+## How to read
+
+Follow arrows from authored sources to human and agent outputs.
+
+## Text alternative
+
+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.
+
+## Nodes
+
+- **Authors** (`authors`): Humans or agents write explicit knowledge
+- **Validate** (`validate`): Schemas, links, a11y metadata
+- **Website** (`web`): Human consumption
+- **Agent package** (`agent`): INDEX, SEARCH, Markdown, SDK
+
+## Edges
+
+- authors → validate (declare)
+- validate → web (render)
+- validate → agent (pack)
+
+## Key takeaways
+
+- Authors own product truth
+- Docify never scans the product repository
+- Open Markdown is the agent baseline
+
+## Mermaid source
+
+```mermaid
+flowchart LR
+  authors[Authors] --> validate[Validate]
+  validate --> web[Website]
+  validate --> agent[Agent package]
+
+```

package/files/diagrams/sources/docify-dual-audience.mmd

@@ -0,0 +1,4 @@
+flowchart LR
+  authors[Authors] --> validate[Validate]
+  validate --> web[Website]
+  validate --> agent[Agent package]

package/files/glossary/docify.md

@@ -0,0 +1,10 @@
+---
+id: "docify"
+type: "glossary-term"
+title: "Docify"
+summary: "x12i framework that turns explicitly authored product knowledge into a website and agent package."
+aliases: ["x12i-docify"]
+---
+# Docify
+
+x12i framework that turns explicitly authored product knowledge into a website and agent package.

package/files/glossary/search-json.md

@@ -0,0 +1,10 @@
+---
+id: "search-json"
+type: "glossary-term"
+title: "SEARCH.json"
+summary: "Deterministic local search index over all addressable knowledge items."
+aliases: ["search index"]
+---
+# SEARCH.json
+
+Deterministic local search index over all addressable knowledge items.

package/files/guides/scaffold-concept.md

@@ -0,0 +1,40 @@
+---
+id: "scaffold-concept"
+type: "guide"
+title: "Scaffold a concept page"
+summary: "Create a validated concept with problem, why, and mental model."
+why: "Concepts without why become unusable glossary stubs."
+audiences: ["developers", "builders"]
+related: ["explicit-authoring"]
+invariants: ["Docify does not invent the concept from source code"]
+confirmationRequired: false
+---
+# Scaffold a concept page
+
+Create a validated concept with problem, why, and mental model.
+
+## Why this path
+
+Concepts without why become unusable glossary stubs.
+
+## Use this when
+
+- Documenting a product idea that needs explanation first
+
+## Do not use this when
+
+- Writing a step-by-step production procedure (use a guide)
+
+## Invariants
+
+- Docify does not invent the concept from source code
+
+## Steps
+
+1. **Run docify scaffold concept <id>** — Markdown file under concepts/
+2. **Fill summary, problem, why, mental model** — Human-understanding fields present
+3. **Run docify validate** — Validation passes
+
+## Verification
+
+- Concept appears in INDEX.md after build

package/files/indexes/books.json

@@ -0,0 +1,47 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "00-platform-overview",
+      "title": "Platform Overview",
+      "summary": "What x12i-docify is, who it serves, and how product libraries plug in without forking UI.",
+      "path": "books/00-platform-overview/"
+    },
+    {
+      "id": "01-packages",
+      "title": "Packages",
+      "summary": "Core, theme, render, export, SDK, web, and screenshots — what each package owns.",
+      "path": "books/01-packages/"
+    },
+    {
+      "id": "02-authoring",
+      "title": "Authoring a Library",
+      "summary": "Recipe to ship a product docs library: BOOK.md layout, data/*.json, site-pages, and the build pipeline.",
+      "path": "books/02-authoring/"
+    },
+    {
+      "id": "03-for-humans",
+      "title": "For Humans",
+      "summary": "How people use @x12i/docify-web — roles, use cases, catalog, chapter reader, downloads.",
+      "path": "books/03-for-humans/"
+    },
+    {
+      "id": "04-for-agents",
+      "title": "For Agents",
+      "summary": "MD packs, chapter indexes, agent-manifest.json, and createEbooksSdk — install knowledge as a devDependency.",
+      "path": "books/04-for-agents/"
+    },
+    {
+      "id": "05-design",
+      "title": "Design System",
+      "summary": "Shared theme tokens and surfaces — products change naming and content only.",
+      "path": "books/05-design/"
+    },
+    {
+      "id": "06-getting-started-and-tutorials",
+      "title": "Getting Started & Tutorials",
+      "summary": "Start here — why agents install @x12i/docify as a devDependency, the authoring order, and hands-on tutorials.",
+      "path": "books/06-getting-started-and-tutorials/"
+    }
+  ]
+}

package/files/indexes/books.md

@@ -0,0 +1,9 @@
+# books
+
+- `00-platform-overview` — Platform Overview — What x12i-docify is, who it serves, and how product libraries plug in without forking UI.
+- `01-packages` — Packages — Core, theme, render, export, SDK, web, and screenshots — what each package owns.
+- `02-authoring` — Authoring a Library — Recipe to ship a product docs library: BOOK.md layout, data/*.json, site-pages, and the build pipeline.
+- `03-for-humans` — For Humans — How people use @x12i/docify-web — roles, use cases, catalog, chapter reader, downloads.
+- `04-for-agents` — For Agents — MD packs, chapter indexes, agent-manifest.json, and createEbooksSdk — install knowledge as a devDependency.
+- `05-design` — Design System — Shared theme tokens and surfaces — products change naming and content only.
+- `06-getting-started-and-tutorials` — Getting Started & Tutorials — Start here — why agents install @x12i/docify as a devDependency, the authoring order, and hands-on tutorials.

package/files/indexes/concepts.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "explicit-authoring",
+      "title": "Explicit authoring",
+      "summary": "Docify only builds knowledge that authors declare — it never discovers product truth from source.",
+      "path": "concepts/explicit-authoring.md"
+    },
+    {
+      "id": "open-markdown",
+      "title": "Open Markdown baseline",
+      "summary": "Every knowledge item ships as readable Markdown plus indexes — the SDK is optional.",
+      "path": "concepts/open-markdown.md"
+    },
+    {
+      "id": "guide-vs-scenario",
+      "title": "Guides vs scenarios vs journeys",
+      "summary": "Guides are bounded procedures; scenarios branch on state; journeys compose an end-to-end outcome.",
+      "path": "concepts/guide-vs-scenario.md"
+    }
+  ]
+}

package/files/indexes/concepts.md

@@ -0,0 +1,5 @@
+# concepts
+
+- `explicit-authoring` — Explicit authoring — Docify only builds knowledge that authors declare — it never discovers product truth from source.
+- `open-markdown` — Open Markdown baseline — Every knowledge item ships as readable Markdown plus indexes — the SDK is optional.
+- `guide-vs-scenario` — Guides vs scenarios vs journeys — Guides are bounded procedures; scenarios branch on state; journeys compose an end-to-end outcome.

package/files/indexes/diagrams.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "docify-dual-audience",
+      "title": "One library, two consumption surfaces",
+      "summary": "Explicitly authored content becomes a human website and an agent knowledge package.",
+      "path": "diagrams/docify-dual-audience.md"
+    }
+  ]
+}

package/files/indexes/diagrams.md

@@ -0,0 +1,3 @@
+# diagrams
+
+- `docify-dual-audience` — One library, two consumption surfaces — Explicitly authored content becomes a human website and an agent knowledge package.

package/files/indexes/guides.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "scaffold-concept",
+      "title": "Scaffold a concept page",
+      "summary": "Create a validated concept with problem, why, and mental model.",
+      "path": "guides/scaffold-concept.md"
+    }
+  ]
+}

package/files/indexes/guides.md

@@ -0,0 +1,3 @@
+# guides
+
+- `scaffold-concept` — Scaffold a concept page — Create a validated concept with problem, why, and mental model.