Adaptive documentation infrastructure

Alpha. APIs may change between minor versions. Pin exact versions in production. Breaking changes are documented in the CHANGELOG.

---

Nous reads Markdown documentation and produces machine-readable outputs for LLMs, autonomous agents, RAG pipelines, and search engines. The pipeline infers semantic metadata from prose at build time and emits structured outputs across multiple agent-readability protocols. No new format to learn. No annotations required.

For teams that want a full documentation platform, Nous also ships an HTML renderer with a first-class design system (four theme presets, glassmorphic surfaces, depth tokens). Same source files, dual output: human-readable HTML and machine-readable agent metadata.

Two Products, One CLI

Nous Engine — Pipeline Only

nous engine

Reads .md, .mdx, .kd, .adoc, .rst files. Infers annotations at build time and emits structured outputs without HTML rendering.

Nous Docs — Full Platform

nous build

Everything the engine does, plus: HTML rendering, design system, full-text search, dev server with hot reload.

Quick Start

pnpm create nous my-docs
cd my-docs
pnpm nous dev          # full platform (HTML + agent outputs)
# or
pnpm nous engine       # pipeline only (agent outputs)

What Nous Produces

From plain .md files with zero configuration:

Output	Protocol	Consumer
.well-known/agent.json	A2A v1.0.0	Agent platforms
.well-known/agents.json	agents.json v0.1.3	Agent orchestrators
.well-known/openapi.json	OpenAPI 3.1	API consumers
rag-chunks.json	Custom	RAG pipelines
mcp-resources.json	MCP	MCP servers
schema.jsonld	Schema.org	Search engines / AI
AGENTS.md	AGENTS.md	Coding agents
cross-refs.json	Custom	Tooling
code-examples.json	Custom	Coding agents
llms.txt / llms-full.txt	llms.txt	LLMs

How It Works

flowchart TD
    Sources[".md · .mdx · .kd · .adoc · .rst"]

    Sources --> Parsers["Parsers & Adapters"]

    Parsers --> NDM["Nous Document Model\n(immutable semantic AST)"]

    NDM --> Infer["Annotation Inference"]

    Infer --> Transforms["Plugin Transforms"]

    Transforms --> Renderer["HTML Renderer\n(Nous Docs only)"]
    Transforms --> AgentMeta["Agent Metadata Emitters"]

    AgentMeta --> Discovery["A2A · agents.json · OpenAPI"]
    AgentMeta --> Ingest["RAG Chunks · MCP Resources"]
    AgentMeta --> Structured["Schema.org · AGENTS.md\nCode Examples · Cross-Refs"]

Loading

The pipeline infers type and audience from heading structure and content signals. Inferred annotations carry _inferred: true so downstream consumers can distinguish human-authored from machine-inferred metadata. See the Benchmarks page for measured inference accuracy.

KD: Optional Precision Override

Most teams write plain Markdown. For cases where inference produces an incomplete result (declaring what question a block answers, setting confidence levels, adding temporal validity), KD extends CommonMark with block annotations:

## API Authentication
{type: "guide", audience: "agent", answers: "How does API authentication work?", confidence: 0.95}

OAuth 2.0 with PKCE is the recommended flow for public clients.

:::warning{validUntil: "2027-01-01"}
The legacy API key flow is deprecated and will be removed in v3.
:::

KD is a strict CommonMark superset. Every .md file is a valid .kd file. Annotations are additive; the format imposes zero migration cost.

Design System

For teams using the full platform (nous build):

Preset	Character
Radiance	Dark, luminous violet, glassmorphic surfaces
Obsidian	True black, cool indigo, minimal chrome
Terminal	Green-on-black, monospace, retro CRT
Meridian	Light, warm cream, serif typography

Every surface, color, and atmosphere effect is overridable through CSS custom properties.

MCP Server

Nous includes a built-in MCP server that serves documentation as queryable resources:

nous serve-mcp --dist dist/

Tools: search_docs, list_topics, list_by_type, list_by_audience. Agents query documentation through the MCP protocol and receive results with semantic metadata (type, audience, answers, confidence).

Packages

Package	Description
@nousdev/cli	nous engine, nous build, nous dev, nous serve-mcp
@nousdev/core	Pipeline, inference engine, transform orchestration
@nousdev/types	NDM types, defineConfig, defineEngineConfig
@nousdev/agent-metadata	Structured metadata emission (Schema.org, A2A, MCP, RAG, OpenAPI)
@nousdev/mcp-server	MCP server with search, filtering, and resources
@nousdev/parser-kd	KD parser (CommonMark + block annotations)
@nousdev/parser-md	Markdown + GFM adapter (wraps remark)
@nousdev/parser-mdx	MDX adapter (wraps mdx-js)
@nousdev/parser-adoc	AsciiDoc adapter (wraps asciidoctor.js)
@nousdev/parser-rst	reStructuredText adapter
@nousdev/renderer-html	HTML renderer with design system
@nousdev/themes	Preset themes and CSS custom properties
@nousdev/search	Full-text search index
@nousdev/agents	LLM-powered documentation agents for coverage analysis
@nousdev/plugin-shiki	Syntax highlighting via Shiki

Development

git clone https://github.com/salmad3/nousdev.git
cd nousdev
pnpm install
pnpm build

Run the documentation site locally:

pnpm nous dev

See CONTRIBUTING.md for development workflow and pull request conventions.

License

MIT

Authors

• salmad3
• Claude (Anthropic)