# Library Overview

`doc-weaver` turns RDFC-compliant TypeScript JSDoc into maintainable reference
documentation. It never edits source comments; it reads them, renders them, and
assembles documentation from all available material — exactly as `doc-forge`
does for Python docstrings.

Analysis is static: source is parsed by the TypeScript compiler API via TypeDoc
and is never executed.

---

## 🧭 Which Build Should You Use?

| Flag                  | Source                | Output                                            |
|-----------------------|-----------------------|---------------------------------------------------|
| `--docs` (`--mkdocs`, `--lib`) | JSDoc comments | `site/lib/**` TypeDoc HTML (the MkDocs parallel) |
| `--mcp`               | JSDoc comments + model | `docs/mcp/**` doc-forge-shaped JSON             |
| `--api`               | OpenAPI spec          | reserved                                          |
| `--wiki`              | Hand-written markdown | `docs/wiki/**` (unchanged)                        |

---

## 🏗️ Architecture

```
TypeScript + JSDoc
       |
  TypeDoc (loader)             -> serialized reflection JSON
       |
  TypeDocJsonToMCP (renderer)  -> MCP bundle (docs/mcp/)
  generateHumanDocs (renderer) -> TypeDoc HTML site (site/lib/)
```

The MCP renderer and the human renderer never depend on each other: both read
the same serialized reflections, so the machine bundle and the human site can
never disagree about a symbol.

---

## 🔄 MCP bundle shape

`docs/mcp/**` is a self-contained, machine-readable reference whose shape is
byte-compatible with `doc-forge`:

```
docs/mcp/
  index.json            { project, type: "docforge-model", modules_count, source }
  nav.json              [ { module, resource: "docs://modules/<module>" } ]
  modules/<module>.json { module, content: { path, docstring, objects } }
```

`doc-weaver serve --mcp --module doc-weaver` serves it over stdio. See the
[RDFC Guide](02_rdfc.md) for how to write the JSDoc that fills it.

---

## ➡️ Read Next

- [02 – RDFC Guide](02_rdfc.md)