@bytesbybrandon/living-docs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon D. Phillips
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# living-docs
+
+[![CI](https://github.com/bytesbybrandon/living-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/bytesbybrandon/living-docs/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Turns a source document into a designed, self-contained HTML doc in one of three styles: an academic paper, dark reading notes, or a telemetry console.
+Ships an AXI CLI and a stdio MCP server over the same core.
+
+---
+
+### Key Features
+
+* **Three themes:** `paper-light` for papers and reports, `paper-dark` for reading notes and essays, `hud` for repo audits and system snapshots.
+* **Generated visuals:** diagrams and charts render as inline SVG from a compact spec, and the console hero uses a seeded graph layout.
+* **Per-source style tokens:** palette, seed color, type pairing, density, and figure treatment adapt a theme without arbitrary CSS. See [Style tokens](docs/guide/style-tokens.md).
+* **One self-contained file:** inline CSS, inline SVG, no network assets, and print rules. See [Guarantees](docs/guide/guarantees.md).
+* **Engine and interfaces:** the same core powers the CLI and the MCP server.
+
+### Tech Stack
+
+* **Language:** JavaScript on Node.js 20 or newer, ECMAScript modules.
+* **Rendering:** no UI framework and no build step; blocks, SVG, and theme CSS are plain JavaScript.
+* **Dependencies:** `@modelcontextprotocol/sdk` for the MCP server and `unpdf` for PDF text extraction.
+* **Tests:** the Node.js built-in test runner.
+
+### Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Usage](#usage)
+3. [Running Tests](#running-tests)
+4. [Project Structure](#project-structure)
+5. [Contributing](#contributing)
+6. [License](#license)
+
+---
+
+### Getting Started
+
+Install the package globally or run it without installing.
+
+#### Prerequisites
+
+* Node.js 20 or newer.
+* npm 10 or newer.
+
+#### Installation
+
+1. **Install from npm:**
+   ```bash
+   npm install -g @bytesbybrandon/living-docs
+   ```
+2. **Or clone the repository:**
+   ```bash
+   git clone https://github.com/bytesbybrandon/living-docs.git
+   cd living-docs
+   ```
+3. **Install dependencies for a checkout:**
+   ```bash
+   npm install
+   ```
+4. **Environment setup:** none. The engine reads files and URLs only.
+
+---
+
+### Usage
+
+#### Running Locally
+
+Render the bundled samples:
+
+```bash
+npm run samples
+```
+
+That writes one HTML file per sample model into `docs/`.
+
+#### Code Example
+
+```bash
+node bin/living-docs-axi.js ingest samples/source/harness-notes.md --draft --theme paper-dark -o docs/note.model.json
+node bin/living-docs-axi.js render docs/note.model.json --theme paper-dark -o docs/note.html
+node bin/living-docs-axi.js preview docs
+```
+
+With the published package, use `npx -y -p @bytesbybrandon/living-docs living-docs-axi` for each command.
+
+Detailed references:
+
+* [Pipeline](docs/guide/pipeline.md)
+* [CLI reference](docs/guide/cli.md)
+* [Document model](docs/guide/document-model.md)
+* [Style tokens](docs/guide/style-tokens.md)
+* [MCP server](docs/guide/mcp.md)
+* [Reactive workflow](docs/guide/reactive-workflow.md)
+* [Guarantees](docs/guide/guarantees.md)
+* [Architecture](ARCHITECTURE.md)
+* [Decisions](docs/decisions/0001-one-model-three-themes.md)
+
+---
+
+### Running Tests
+
+```bash
+npm test
+```
+
+The suite covers rendering determinism and self-containment, escaping and link sanitization, schema validation, ingest of Markdown, HTML, and text, CLI behavior and exit codes, an in-memory MCP client round trip, and style token resolution.
+
+---
+
+### Project Structure
+
+```text
+living-docs/
+  bin/                 CLI and MCP entry points
+  src/
+    axi/               command parsing, compact output, file writes, preview
+    ingest/            Markdown, text, HTML, URL, and PDF intake
+    mcp/               stdio MCP server and tool definitions
+    model/             document model schema, validator, safe inline Markdown
+    render/            block renderers, SVG generators, style resolution, themes
+    server/            local preview server
+  samples/             sample models and one Markdown source
+  scripts/             sample build script
+  tests/               Node test runner suites
+  docs/
+    decisions/         architecture decision records
+    guide/             user and contributor guides
+```
+
+---
+
+### Contributing
+
+Contributions are welcome.
+Read [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the fork, branch, test, and pull request workflow.
+Repository agent rules live in [AGENTS.md](AGENTS.md), and module boundaries live in [ARCHITECTURE.md](ARCHITECTURE.md).
+
+---
+
+### License
+
+Released under the MIT License.
+See [LICENSE](LICENSE).

package/bin/living-docs-axi.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from '../src/axi/cli.js';
+
+const output = await main(process.argv.slice(2));
+if (output) process.stdout.write(output.endsWith('\n') ? output : output + '\n');

package/bin/living-docs-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startStdioServer } from '../src/mcp/server.js';
+
+startStdioServer().catch(error => {
+  process.stderr.write(`living-docs-mcp: ${error.stack || error.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,57 @@
-{
-  "name": "@bytesbybrandon/living-docs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@bytesbybrandon/living-docs",
+  "version": "0.1.0",
+  "description": "Turn a source document into a designed, self-contained living doc: academic paper, dark reading notes, or telemetry console. Ships an AXI CLI and an MCP server.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Brandon D. Phillips",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bytesbybrandon/living-docs.git"
+  },
+  "homepage": "https://github.com/bytesbybrandon/living-docs#readme",
+  "bugs": {
+    "url": "https://github.com/bytesbybrandon/living-docs/issues"
+  },
+  "keywords": [
+    "agent",
+    "axi",
+    "mcp",
+    "documentation",
+    "html",
+    "pdf",
+    "living-docs",
+    "telemetry",
+    "paper"
+  ],
+  "bin": {
+    "living-docs-axi": "bin/living-docs-axi.js",
+    "living-docs-mcp": "bin/living-docs-mcp.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./render": "./src/render/index.js",
+    "./ingest": "./src/ingest/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "samples",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test tests/cli.test.js tests/ingest.test.js tests/mcp.test.js tests/render.test.js tests/style.test.js tests/validate.test.js",
+    "samples": "node scripts/build-samples.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "unpdf": "^2.1.0"
+  }
+}

package/samples/agent-skills-audit.json

@@ -0,0 +1,274 @@
+{
+  "schemaVersion": 1,
+  "theme": "hud",
+  "meta": {
+    "title": "AI CONFIGS / OPEN SOURCE",
+    "style": { "palette": "ocean", "type": "mono", "density": "normal", "figure": "solid" },
+    "kicker": "SRC GITHUB · 5 TEAMS · 5 REPOS · 548.4K STARS · $0",
+    "runningHead": "AI configs · open source audit",
+    "date": "2026-11-10",
+    "footer": "living-docs · hud"
+  },
+  "blocks": [
+    {
+      "type": "graphScene",
+      "title": "AI CONFIGS / OPEN SOURCE",
+      "meta": ["SRC GITHUB", "5 TEAMS", "5 REPOS", "548.4K STARS", "$0"],
+      "tabs": [
+        { "label": "MATT" },
+        { "label": "ADDY", "active": true },
+        { "label": "CLOUDFLARE" },
+        { "label": "OBSIDIAN" },
+        { "label": "GOOGLE" }
+      ],
+      "command": "npx skills add adyosmani/agent-skills",
+      "graph": {
+        "counts": "5,932 NODES · 10,231 LINKS",
+        "azimuth": "AZ 154.1° Z 227",
+        "seed": 11,
+        "nodeCount": 210,
+        "labels": [
+          "ci-cd-and-automation",
+          "idea-refine",
+          "debugging-and-error-recovery",
+          "spec-driven-development",
+          "code-review-and-quality",
+          "design-doc",
+          "interview-me",
+          "context-engineering"
+        ],
+        "active": {
+          "id": "shipping-and-launch",
+          "badge": "/ MATCHED",
+          "card": {
+            "title": "shipping-and-launch",
+            "rows": [
+              { "k": "REPO", "v": "adyosmani/agent-skills" },
+              { "k": "KIND", "v": "SHIP" },
+              { "k": "DOES", "v": "checklists before anything goes live" }
+            ],
+            "footer": "ADDY"
+          }
+        }
+      },
+      "action": { "label": "ship it", "right": "ADDY OSMANI" },
+      "status": {
+        "seq": "03.80",
+        "kind": "skill",
+        "text": "shipping-and-launch matched",
+        "tail": "adyosmani/agent-skills"
+      }
+    },
+    {
+      "type": "panels",
+      "columns": 4,
+      "items": [
+        {
+          "index": "01",
+          "title": "REPO",
+          "tag": "02 / 05",
+          "kind": "repo",
+          "data": {
+            "name": "adyosmani/agent-skills",
+            "stars": "113.9K",
+            "by": "by Ady Osmani",
+            "note": "production-grade engineering skills for AI coding agents"
+          }
+        },
+        {
+          "index": "02",
+          "title": "STAR BOARD",
+          "tag": "LIVE",
+          "kind": "bars",
+          "data": {
+            "rows": [
+              { "label": "MAT", "value": 307.2, "display": "307.2K" },
+              { "label": "ADY", "value": 113.9, "display": "113.9K", "active": true },
+              { "label": "CFL", "value": 63.9, "display": "63.9K" },
+              { "label": "OBS", "value": 50.0, "display": "50.0K" },
+              { "label": "GBL", "value": 13.4, "display": "13.4K" }
+            ]
+          }
+        },
+        {
+          "index": "03",
+          "title": "SKILL INSPECTOR",
+          "tag": "TRACE",
+          "kind": "list",
+          "data": {
+            "title": "shipping-and-launch",
+            "rows": [
+              { "k": "KIND", "v": "SHIP" },
+              { "k": "DOES", "v": "checklists before anything goes live" }
+            ]
+          }
+        },
+        {
+          "index": "04",
+          "title": "SKILL RADAR",
+          "tag": "SCAN",
+          "kind": "radar",
+          "data": {
+            "value": "25",
+            "max": 25,
+            "sub": "SKILLS",
+            "subvalue": "02",
+            "subvalueLabel": "REPO",
+            "found": "found 25 / 25"
+          }
+        },
+        {
+          "index": "05",
+          "title": "SKILL TREE",
+          "tag": "25 SKILLS",
+          "kind": "tree",
+          "data": {
+            "root": "adyosmani/agent-skills/",
+            "items": [
+              { "name": "spec-driven-development/", "tag": "SKILL.md" },
+              { "name": "test-driven-development/", "tag": "SKILL.md" },
+              { "name": "code-review-and-quality/", "tag": "SKILL.md" },
+              { "name": "shipping-and-launch/", "tag": "SKILL.md", "active": true },
+              { "name": "interview-me/", "tag": "SKILL.md" },
+              { "name": "idea-refine/", "tag": "SKILL.md" },
+              { "name": "context-engineering/", "tag": "SKILL.md" }
+            ]
+          }
+        },
+        {
+          "index": "06",
+          "title": "AGENT LOG",
+          "tag": "TAIL · F",
+          "kind": "log",
+          "data": {
+            "lines": [
+              { "n": 18, "verb": "add", "text": "adyosmani/agent-skills" },
+              { "n": 21, "verb": "define", "text": "spec-driven-development" },
+              { "n": 22, "verb": "plan", "text": "break into tasks" },
+              { "n": 23, "verb": "build", "text": "tests drive the impl" },
+              { "n": 24, "verb": "review", "text": "quality gate passed" },
+              { "n": 25, "verb": "ship", "text": "launch checklist" }
+            ]
+          }
+        },
+        {
+          "index": "07",
+          "title": "COVERAGE",
+          "tag": "REPOS × JOBS",
+          "kind": "heat",
+          "data": {
+            "cols": ["SPEC", "TEST", "REVI", "AUDI", "NOTE", "DESI"],
+            "rows": ["MAT", "ADY", "CFL", "OBS", "GBL"],
+            "cells": [
+              [true, true, true, false, true, true],
+              [true, true, true, true, true, true],
+              [false, false, true, true, false, true],
+              [true, false, false, true, true, false],
+              [true, true, false, false, false, true]
+            ],
+            "footer": "5 / 6 JOBS · ADY"
+          }
+        },
+        {
+          "index": "08",
+          "title": "FREE STARS",
+          "tag": "GITHUB",
+          "kind": "big",
+          "data": { "value": "421.1K", "note": "stars · 0 prompts from zero" }
+        },
+        {
+          "index": "09",
+          "title": "SKILL.md",
+          "tag": "YAML",
+          "kind": "code",
+          "data": {
+            "file": "SKILL.md",
+            "tag": "YAML",
+            "lines": [
+              "---",
+              "name: shipping-and-launch",
+              "description: checklists before anything goes live",
+              "kind: SHIP",
+              "---",
+              "",
+              "# trigger",
+              "\"ship it\"",
+              "",
+              "-> load -> run -> verify"
+            ]
+          }
+        },
+        {
+          "index": "10",
+          "title": "TOKEN STREAM",
+          "tag": "LIVE",
+          "kind": "hist",
+          "data": {
+            "values": [22, 38, 51, 30, 44, 39, 63, 52, 41, 68, 58, 73, 46, 88, 62, 70, 95, 81],
+            "activeIndex": 17,
+            "rate": "2.1k tok/s",
+            "note": "ctx 43%",
+            "footer": "cache hit 94.0%"
+          }
+        },
+        {
+          "index": "11",
+          "title": "RUN METRICS",
+          "tag": "SESSION",
+          "kind": "metrics",
+          "data": {
+            "groups": [
+              { "label": "PHASES", "value": "6/6" },
+              { "label": "TASKS", "value": "12" },
+              { "label": "CHECKS", "value": "18" },
+              { "label": "FROM ZERO", "value": "0" }
+            ]
+          }
+        },
+        {
+          "index": "12",
+          "title": "GIT DIFF",
+          "tag": "HEAD",
+          "kind": "diff",
+          "data": {
+            "head": "commit b2daba",
+            "lines": [
+              { "sign": "+", "text": "agent-skills/shipping-and-launch/SKILL.md" },
+              { "sign": "+", "text": "+72 lines · 0 from scratch" },
+              { "sign": "-", "text": "0x3e88 21 8a 4d cc 1e 79 ed 59" },
+              { "sign": "+", "text": "0x3e88 31 22 47 fa fb d3 e4" }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "type": "ticker",
+      "text": "03.80 skill :: shipping-and-launch matched · adyosmani/agent-skills · coverage 5/6 · 421.1K stars · cache 94.0%"
+    },
+    {
+      "type": "heading",
+      "title": "What this snapshot measures",
+      "level": 2
+    },
+    {
+      "type": "prose",
+      "markdown": "This page is a single moment in a repository audit: one matched skill, its repository, and the run that surfaced it. Every number on the console is a fact about that snapshot, not a projection. The graph counts nodes and links across five repositories; the coverage grid marks which job families each repository actually covers."
+    },
+    {
+      "type": "stats",
+      "items": [
+        { "label": "Repositories scanned", "value": "5", "note": "github" },
+        { "label": "Skills indexed", "value": "25", "note": "SKILL.md" },
+        { "label": "Stars in scope", "value": "548.4K" },
+        { "label": "Cost", "value": "$0", "note": "local reads" }
+      ]
+    },
+    {
+      "type": "callout",
+      "tone": "note",
+      "title": "Reading the console",
+      "body": "Panels are independent: each one answers a different question about the same snapshot. The hero graph shows adjacency, not importance; the coverage grid is the only panel that scores completeness."
+    }
+  ]
+}