> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monograph

> Retrieve detector-keyed engineering knowledge, browse keyless Books, scan edited files, and manage signed installable Book packages.

Monograph is the multi-Book “knowledge as intelligence” engine. Detector-keyed
Books answer a fired possibility band or CWE with mechanism and fix-shape
knowledge. Keyless Books route from a topic, symptom, or entry id. The same
reading plane serves embedded offline Books and verified installed Book
packages.

*Published contract: `monograph 0.6.4`, OpenCLIs build
`2026-07-12-104914`. The executing binary, OpenCLIs registry, and public CDN
metadata agree on this release.*

The full binary exposes **21 commands**: 8 retrieval/routing commands, the
`scan` carrier, 3 author/validation commands, 6 package-lifecycle commands,
and `docs`/`version`/`help`.

<Note>
  The main source manifests are already stamped `0.6.5`; this page describes the
  publicly installed `0.6.4` payload. Source state is not evidence that a command
  or fix has reached the CDN release.
</Note>

## Retrieval Order

```text theme={null}
band or CWE known → match → read → related
entry id known    → read → related
symptom only      → search or resonate → read
Book unknown      → books or open → read
edited file       → scan → gate → attached entry
```

Prefer the most specific evidence available: band, CWE, exact entry id, then
natural-language retrieval.

```bash theme={null}
monograph match --band <band-id>
monograph match --cwe <CWE-id>
monograph read <entry-id>
```

## Complete Command Reference

| Command                  | What it does                                                                                | Important controls or boundary                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `match`                  | Performs O(1) keyed lookup inside the selected/embedded Book.                               | `--band <id>` or `--cwe <id>`; see the current band-key caveat below.                           |
| `read <entry-id>`        | Prints the complete mechanism-first entry Markdown.                                         | Exact id lookup.                                                                                |
| `search <symptom>`       | Runs keyword fallback search within the opened Book.                                        | Browse path, not detector evidence.                                                             |
| `resonate <query>`       | Uses Monomento-core ranking plus cross-reference resonance.                                 | Richer natural-language fallback.                                                               |
| `related <entry-id>`     | Follows typed causal edges such as requires, precedes, mitigates, and detects.              | Exact entry id.                                                                                 |
| `toc [book]`             | Lists entries grouped by chapter.                                                           | Optional Book selection.                                                                        |
| `books`                  | Lists registered embedded and available routing Books with topic cards.                     | Read-only local catalog.                                                                        |
| `open <topic-or-query>`  | Routes to the best Book and searches within it.                                             | Topic plane above per-entry retrieval.                                                          |
| `scan <file>`            | Fires Semantics worklists, applies the surface/batch gate, and attaches matching knowledge. | `--db`, `--band`, `--json`, `--book`; `--hook-claude` is the Pre/PostToolUse carrier.           |
| `add <CWE> <slug>`       | Scaffolds a Code Bug Patterns/CWE-shaped draft entry.                                       | `--book <dir>`; `--chapter`, `--title`; refuses overwrite. Not a generic keyless-Book scaffold. |
| `lint`                   | Validates Book schema, stamps, and honesty-floor requirements.                              | Optional `--book`; read-only validation.                                                        |
| `index`                  | Prints/rebuilds the derived band/CWE-to-entry key index for authoring.                      | Derived data, not detector execution.                                                           |
| `install <id>[@version]` | Downloads and verifies an installable Book.                                                 | Ed25519 signature plus per-file SHA-256; network and filesystem write.                          |
| `update [id]`            | Moves one installed Book or every Book to the latest accepted version.                      | `--all`; downgrade refused by default.                                                          |
| `remove <id>`            | Removes an installed Book.                                                                  | Embedded Books cannot be removed.                                                               |
| `prune [id]`             | Reclaims superseded installed builds while keeping the current build.                       | `--dry-run` previews deletion.                                                                  |
| `list`                   | Lists installed Book packages.                                                              | `--available` reads the CDN catalog.                                                            |
| `verify [id]`            | Rechecks embedded digest and installed signature/tree hashes offline.                       | Optional installed Book id.                                                                     |
| `docs [topic]`           | Lists or prints embedded reference topics.                                                  | `book-distribution` explains author/publish/install/trust.                                      |
| `version`                | Prints the executing version.                                                               | Read-only.                                                                                      |
| `help`                   | Prints the full installed guide.                                                            | No arguments and `--help` do the same.                                                          |

There is no direct `monograph mcp` or `monograph mcp-schema` command. NIIA's
shared-library integration exposes retrieval separately; side-effectful Book
package operations remain standalone CLI commands.

## Scan Is the Carrier Primitive

```bash theme={null}
monogram-logos survey --project . --db /tmp/project.semantics.db
monograph scan src/main.rs --db /tmp/project.semantics.db --json
```

`scan` asks `monogram-semantics worklist` to fire candidate bands, applies the
Monograph surfacing gate, and resolves band → CWE → entry. A `surface` gate
attaches the entry; a more false-positive-leaning `batch` gate reports only the
site for later review.

For Claude Code, the same `scan --hook-claude` command is wired to both
PreToolUse and PostToolUse for Edit/Write. The pre-pass captures existing
bands; the post-pass reindexes the file and surfaces only newly introduced
band×file pairs once per session. Missing DBs, unsupported languages, no new
band, or already-shown results fail quiet.

## Grounding and Honesty

| Tier            | Meaning                                                                            |
| --------------- | ---------------------------------------------------------------------------------- |
| Sound           | The structural signal is the class itself.                                         |
| Taint candidate | The detector found a sink; attacker-derived reachability still needs confirmation. |
| Authored        | Knowledge exists but no detector owns the class yet.                               |

A hit is a candidate, never an automatic verdict. Entries remain draft until
the firing surface, a real case, and Monobench A/B evidence earn a stronger
status.

<Warning>
  In this release, `match --cwe` is the reliable keyed path. Some Book entries
  still index `--band` from `detection.signal` prose rather than the foundry band
  name, so a valid `monogram-semantics` band id may not resolve. Use its CWE id or
  exact entry id when that happens.
</Warning>

## Book Trust and Precedence

Installed Books live under `~/.openclis/books/`. A same-id installed Book wins
over an embedded copy only when its content version is newer and its saved
signature plus complete file tree verify on the serving path. Book content
versions are independent of Monograph and Monogram binary versions.

### Package lifecycle

```bash theme={null}
monograph list --available
monograph install <book-id>[@<version>]
monograph verify <book-id>
monograph update <book-id>
monograph update --all
monograph prune <book-id> --dry-run
monograph remove <book-id>
```

Install verifies the Ed25519-signed metadata, compressed archive SHA-256, and
the extracted tree in both directions before switching the Book's `current`
pointer. `update` refuses a downgrade unless `--force-downgrade` is explicit.
`verify` returns exit code 2 for an integrity failure, letting automation
separate trust failure from ordinary usage or network errors.

Embedded Books cannot be removed. A newer installed Book with the same id is
eligible to override its embed only after serve-path re-verification; an equal,
older, malformed, or invalid installed copy does not shadow the embed.

## Release Platforms

The `0.6.4` release metadata publishes five platform artifacts:

| Platform key      | Binary          |
| ----------------- | --------------- |
| `darwin-aarch64`  | `monograph`     |
| `linux-aarch64`   | `monograph`     |
| `linux-x86_64`    | `monograph`     |
| `windows-aarch64` | `monograph.exe` |
| `windows-x86_64`  | `monograph.exe` |

## Relationships

| Tool                                                        | Ownership                                                                                                    |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [Monogram Semantics](/ai-clis/monogram-semantics)           | Fires structural possibility bands and supplies the Store DB                                                 |
| [Monogram Logos](/ai-clis/monogram-logos)                   | Builds/validates the band foundry and can create a scan-ready Store                                          |
| [Monogram](/ai-clis/monogram/overview)                      | Search/navigation product; ships an embedded knowledge snapshot but not installed Book extensions in-process |
| [Code Bug Patterns](/ai-clis/monograph-code-bug-patterns)   | Offline one-Book detector/CWE distribution                                                                   |
| [Fix-Shape Patterns](/ai-clis/monograph-fix-shape-patterns) | Offline one-Book keyless fix-review distribution                                                             |
| [NIIA](/ai-clis/niia)                                       | Exposes the shared Monograph library through CLI/MCP integration                                             |