Set up citations in one repository

Your pages and the code they describe live in one repository. This page wires manni cite into it once, so that a bare manni cite check covers the right pages and finds the right sources. That is the whole of the setup for a single repository. There are two more pages beside this one for the repositories that need more.

Get started teaches the loop, meaning pin, check, read the finding, fix, re-pin. This page is the repository around that loop.

Every transcript below is real output from the built tool.

What you configure, and what you do not

Thing	Where it comes from
Which pages are checked	A collection in `manni.config.yaml`, read by every manni tool.
Where `source.file` resolves from	The git root, unless you say otherwise. One repository rarely says otherwise.
Where an entry is written	The page’s frontmatter, unless a collection declares a sidecar manifest.
Which findings fail the build	The default severities, unless the team moves one.

Declare the pages as a collection. collections: is a top-level key of the family’s one config file, not a cite: key. Every tool reads it, so the pages you validate metadata on are the pages you check citations on:
manni.config.yaml
```
collections:
  - name: docs-pages
    paths: ["docs/**/*.md"]
    exclude: ["docs/drafts/**"]
```
paths and exclude are globs, relative to the config file. With this in place, manni cite check with no arguments covers every declared collection, and --collection docs-pages narrows a run to one of them. Named paths on the command line beat both.

Every key of a collection is in the metadata tool’s configuration reference. The cite: keys, all six of them, are in the configuration reference for this tool.

A file that declares collections: and nothing else is this tool’s config. The documents are declared, and every cite: key takes its default. Add a cite: section when you want to move one of them.
Leave the root alone. A source.file is a path relative to one root, settled once per run. In a single repository that root is the git root above your working directory, which is what you want, so there is nothing to set. cd docs && manni cite check reaches the same sources as a run from the top.

You find out when the root is wrong, because the source end reads missing rather than resolving to the wrong file:
```
✗ docs/limits.md
    ✗ fetch-timeout   :16 current   lib/limits.ts:2 missing

1 file checked, 0 passed, 1 failed, 1 finding
```
Sources resolve through tracked files only, from git ls-files, under a realpath containment check. So a file you have not committed is missing too. Where sources resolve from has the full order, and --root is how a second checkout is reached.

Mint the first citation. add takes the page with its lines, then the source with its lines. --dry-run prints the diff and writes nothing:

manni cite add docs/limits.md:6 lib/limits.ts:2 --id fetch-timeout --dry-run

--- docs/limits.md
+++ docs/limits.md
@@ -2,2 +2,12 @@
 title: Limits
+citations:
+  - id: fetch-timeout
+    claim:
+      lines: 3
+      integrity: sha256-921b21cccab21a4577f224ec4171aa56a3414bb3a5a4704ab8b6f314c46aa094
+    source:
+      file: lib/limits.ts
+      lines: 2
+      integrity: sha256-78af1d3321f9cbb177a7e4c958e39be56fd14cb93c1e441778bc4232e0fe4b1f
+      commit-sha: 9265563d8ea84a13fea0001b7e531c119f47d070
 ---

Drop --dry-run to write it. The report names both pins and the line each end sits on:

docs/limits.md: added fetch-timeout to frontmatter (claim at line 16, sha256-921b21cc…; source lib/limits.ts:2, sha256-78af1d33…, 9265563)

You typed line 6 and the report says line 16, because the entry pushed the sentence down by ten lines. The entry itself stored lines: 3, which counts the page body rather than the file, so editing the frontmatter never moves a claim. Body lines and file lines states the rule once.

Run the first check. With the collection declared, no arguments are needed:
Terminal window
```
manni cite check
```
```
✓ docs/limits.md
    ✓ fetch-timeout   :16 current   lib/limits.ts:2 current

1 file checked, 1 passed, 0 failed, 0 findings
```
Both ends read in file lines, whatever the entry stored. -q hides the clean files once the corpus is larger than a screen. Read a result decodes the row, and Fix a failing check decodes every status it can carry.
Commit the page and the config, then gate it. manni cite check is something CI runs on every push, next to the metadata gate. Run it in CI has the workflow, the output formats and the exit-code contract. It also has the baseline, which lets an existing backlog ramp in rather than block the first pull request.

When nothing is declared and nothing is named

A run with no positional paths and no config is an operational error, exit 2, rather than a silently empty pass:

manni cite check --no-config

manni: No files to check. Pass paths/globs, or declare a collection under `collections:` in manni.config.yaml.

That is the metadata tool’s shared input model, which check and update both follow. add is the exception, because it takes one page and one source rather than a set.

Where entries are written

By default an entry goes into the page’s own frontmatter, and nothing in the body repeats it. Two things change that, and each has a page of its own.

Keep citations out of the pageDeclare a manifest that owns the citations key for a collection, so the pages carry no citation YAML at all.

Require citations in the standardCompose the citations vocabulary into your house schema, require the key on a class of pages, and choose the severities.

Public docs, private codeEncrypt a private repository's source paths, so a public docs site can cite it without publishing them.

Run it in CIPR annotations, SARIF and JUnit output, the exit-code contract, and the baseline ramp.