## What the Audit Reports

`pnpm tags:audit` runs the package-owned audit CLI. It walks the content directories declared by the default `TagCliConfig` export in `src/config/tag-vocabulary.ts`, collects the `tags:` arrays from each page's frontmatter, and reports three kinds of finding against that module's named `tagVocabulary` export.

- **Unknown tags** — the string does not exactly match a canonical id. Either add a vocabulary entry, replace it with the intended id, or remove it from the page. Under [`tagGovernance: "strict"`](https://zudo-doc.takazudomodular.com/docs/guides/tag-governance), unknowns fail the build.
- **Near-duplicates** — two distinct tags that look like variants of each other (high string similarity, or the same singular form). Pick one canonical id and update the content using the other.
- **Orphan vocabulary entries** — canonical ids that no page references. Remove an entry only after updating or removing every reference.

A clean run prints `✓ No tag issues found`.

## CLI Config and Package Script

The scaffold binds the explicit config module in `package.json`:

```json
{
  "scripts": {
    "tags:audit": "tags-audit --config src/config/tag-vocabulary.ts"
  }
}
```

The config path is resolved from the project root. The CLI exits with a clear error if `--config` is missing, cannot be loaded, or does not default-export a valid `TagCliConfig`. Keep the named `tagVocabulary` export too—the generated `zfb.config.ts` consumes the same module, so runtime governance and CLI auditing share one source of truth.

Options can be forwarded through the package manager with `--`, which works consistently with pnpm and npm:

## Reading the Report

The default output is colorized text grouped by category. For machine consumption, pass `--json`:

```sh
pnpm tags:audit -- --json > audit.json
```

The JSON payload is an `AuditReport` with `unknowns`, `nearDuplicates`, `orphans`, `filesScanned`, and an exact-id `frequency` map. This is what CI dashboards should consume.

## CI Integration via `b4push`

The project's pre-push validation script ([`pnpm b4push`](https://zudo-doc.takazudomodular.com/docs/guides/development-workflow)) runs the audit with `--ci`:

```sh
pnpm tags:audit -- --ci
```

`--ci` forces a non-zero exit on any **hard issue** (an unknown tag) regardless of the configured `tagGovernance` mode. This means:

- Under `tagGovernance: "warn"` — `pnpm build` still passes with unknowns present (intentional, so migrations aren't blocked), but `pnpm b4push` refuses to push them.
- Under `tagGovernance: "strict"` — the build already fails on unknowns; `--ci` keeps b4push aligned when enforcement is later relaxed.

This two-layer setup — lenient build, strict push — is the sweet spot for multi-author doc bases: drafts can experiment locally without fighting Zod, but no broken tags make it onto `main`.

## Related

- [Tag governance](https://zudo-doc.takazudomodular.com/docs/guides/tag-governance) — vocabulary file, governance modes, the faceted tag pattern.
- [Tag suggestions](https://zudo-doc.takazudomodular.com/docs/guides/tags-suggest) — opt-in LLM helper for picking canonical tags on new pages.