vigiles 2.0.0

package/docs/agent-setup.md

@@ -0,0 +1,85 @@
+# Agent Setup Guide
+
+How to set up vigiles when an AI agent is doing the installation (non-interactive).
+
+## What an Agent Can Do
+
+| Action                    | Agent can do it? | How                                         |
+| ------------------------- | ---------------- | ------------------------------------------- |
+| Create spec file          | Yes              | `npx vigiles init` (non-interactive wizard) |
+| Generate types            | Yes              | `npx vigiles generate-types`                |
+| Compile specs             | Yes              | `npx vigiles compile`                       |
+| Add CI step               | Yes              | Edit `.github/workflows/*.yml` directly     |
+| Install hooks             | Yes              | Write to `.claude/settings.json` directly   |
+| Install plugin via skills | **No**           | Requires user to run `npx skills add`       |
+
+The `skills add` command requires user action — an agent can't install plugins for itself. But it CAN write the hook configuration directly to `.claude/settings.json`, which achieves the same result.
+
+## Non-Interactive Setup
+
+### Step 1: Run the wizard
+
+```bash
+npx vigiles init
+```
+
+This works non-interactively. It auto-detects the project, creates a spec, generates types, compiles, and adds a CI step. No prompts.
+
+### Step 2: Install hooks directly
+
+Instead of `npx skills add zernie/vigiles`, the agent can write the hooks to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty') && case \"$FILE\" in *.md) [ -f \"$FILE\" ] && head -1 \"$FILE\" | grep -q 'vigiles:sha256:' && { echo \"BLOCKED: Edit the .spec.ts source instead.\" >&2; exit 2; } ;; esac; exit 0"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty') && case \"$(basename \"$FILE\")\" in eslint.config.*|.eslintrc*|package.json|pyproject.toml|Cargo.toml) npx vigiles generate-types 2>&1 || true ;; esac && case \"$FILE\" in *.spec.ts) npx vigiles compile 2>&1 || true ;; esac"
+      }
+    ]
+  }
+}
+```
+
+This is equivalent to what the plugin installs, but written directly without the skills system.
+
+### Step 3: Edit the spec
+
+The agent should read the generated `.spec.ts` file and fill in the project's actual conventions — sections, key files, commands, and rules. Use the `edit-spec` skill instructions as a guide for the spec format.
+
+### Step 4: Compile and verify
+
+```bash
+npx vigiles compile
+npx vigiles audit
+```
+
+## Recommended Agent Prompt
+
+If you want an agent to set up vigiles in a project, use this prompt:
+
+```
+Set up vigiles for this project:
+1. Run `npx vigiles init`
+2. Read the generated .spec.ts file
+3. Fill in the project's actual conventions based on the codebase
+4. Add hooks to .claude/settings.json for auto-compilation
+5. Run `npx vigiles compile` to verify everything works
+6. Commit the .spec.ts, compiled .md, .vigiles/generated.d.ts, and settings changes
+```
+
+## What the Agent Gets Wrong
+
+Common issues when agents set up vigiles:
+
+- **Editing CLAUDE.md directly** — the PreToolUse hook prevents this if installed
+- **Using wrong rule names** — `enforce("no-console")` instead of `enforce("eslint/no-console")`. The compiler catches this.
+- **Forgetting to compile** — the PostToolUse hook handles this automatically
+- **Adding headers inside sections** — the compiler catches `#`/`##` headers in section content

package/docs/agent-workflows.md

@@ -0,0 +1,103 @@
+# Agent Workflows
+
+vigiles compiles typed specs to markdown instruction files. Different AI agents read different files, but the compilation and validation pipeline is the same.
+
+## Auto-Detection
+
+`vigiles init` scans your project and auto-detects:
+
+| Signal                                     | What it means                                     |
+| ------------------------------------------ | ------------------------------------------------- |
+| `CLAUDE.md` exists                         | Claude Code in use — suggest migration if no spec |
+| `AGENTS.md` exists                         | Codex / GitHub Copilot in use                     |
+| `.claude/` directory                       | Claude Code project config                        |
+| `.cursorrules`                             | Cursor in use — suggest rule-porter               |
+| `.github/copilot-instructions.md`          | GitHub Copilot custom instructions                |
+| `.windsurfrules`                           | Windsurf in use                                   |
+| `rule-porter` / `rulesync` in package.json | Sync tool already installed                       |
+| Symlinked instruction files                | Notes them in output                              |
+
+The wizard creates specs for detected targets, generates types, compiles, and adds a CI step. No `--target` flag needed unless you want to override the auto-detection.
+
+## Claude Code
+
+**Instruction file:** `CLAUDE.md`
+
+**Setup:**
+
+```bash
+npx vigiles init
+npx skills add zernie/vigiles
+```
+
+**What the plugin does:**
+
+| Hook        | Trigger                                         | Action                                   |
+| ----------- | ----------------------------------------------- | ---------------------------------------- |
+| PreToolUse  | Agent tries to Edit/Write a compiled `.md` file | Blocks the edit, redirects to `.spec.ts` |
+| PostToolUse | Agent edits a `.spec.ts` file                   | Auto-runs `vigiles compile`              |
+| PostToolUse | Agent edits linter config or `package.json`     | Auto-runs `vigiles generate-types`       |
+
+**Without the plugin**, you must run `vigiles compile` manually after editing specs. CI still catches stale files.
+
+## Codex / GitHub Copilot
+
+**Instruction file:** `AGENTS.md`
+
+**Setup:**
+
+```bash
+npx vigiles init --target=AGENTS.md
+```
+
+Codex and GitHub Copilot read `AGENTS.md` directly. There is no plugin or hook system — these agents don't support it. The enforcement path is:
+
+1. Edit `AGENTS.md.spec.ts` (the source of truth)
+2. Run `npx vigiles compile` to regenerate `AGENTS.md`
+3. CI verifies freshness: `npx vigiles audit && npx vigiles generate-types --check`
+
+If you also use Claude Code, install the plugin (`npx skills add zernie/vigiles`) to get auto-recompilation.
+
+## Multi-Agent (Claude + Codex)
+
+Use a single spec with multiple targets:
+
+```typescript
+export default claude({
+  target: ["CLAUDE.md", "AGENTS.md"],
+  rules: { ... },
+});
+```
+
+One spec, two outputs. Both files are compiled from the same source of truth with the same linter verification.
+
+```bash
+npx vigiles init                      # for CLAUDE.md (primary)
+npx vigiles init --target=AGENTS.md   # adds AGENTS.md target
+```
+
+Or just set `target: ["CLAUDE.md", "AGENTS.md"]` in your spec directly.
+
+## Cursor / Windsurf / Other Formats
+
+vigiles compiles to **markdown only** (CLAUDE.md, AGENTS.md). For non-markdown formats (`.cursorrules`, `.github/copilot-instructions.md`, Windsurf), use a sync tool to convert from the compiled markdown:
+
+- [rule-porter](https://github.com/nichochar/rule-porter) — bidirectional conversion between agent formats
+- [rulesync](https://github.com/dyoshikawa/rulesync) — unified rule management across 10+ tools
+
+vigiles is the source of truth compiler. Sync tools handle the last mile.
+
+## CI Pipeline
+
+All agents share the same CI step:
+
+```yaml
+- name: Verify specs
+  run: npx vigiles audit && npx vigiles generate-types --check
+```
+
+This catches:
+
+- Hash mismatches (someone edited the compiled `.md` directly)
+- Missing specs (`require-spec` rule — every `.md` should have a `.spec.ts`)
+- Stale generated types (linter config changed but types weren't regenerated)

package/docs/comparison.md

@@ -0,0 +1,71 @@
+# What Changes With vigiles
+
+## Claude Code
+
+|                                     | Without vigiles              | With vigiles                                                   |
+| ----------------------------------- | ---------------------------- | -------------------------------------------------------------- |
+| **Instructions**                    | Hand-written CLAUDE.md       | Compiled from `.spec.ts` (build artifact)                      |
+| **Linter rule references**          | Trust-based (nobody checks)  | Verified at compile time against real config                   |
+| **File paths**                      | Rot silently when renamed    | `file()` references checked against filesystem                 |
+| **Commands**                        | Stale scripts go unnoticed   | `cmd()` references checked against package.json                |
+| **Direct edits to CLAUDE.md**       | Anyone can, nobody knows     | PreToolUse hook blocks edits, redirects to spec                |
+| **Linter config changes**           | CLAUDE.md drifts out of sync | PostToolUse hook auto-regenerates types                        |
+| **Spec edits**                      | N/A                          | PostToolUse hook auto-compiles to markdown                     |
+| **guidance → enforce upgrades**     | Manual guesswork             | `/strengthen` reads per-linter docs, suggests upgrades         |
+| **New lint rules from PR feedback** | Copy-paste from review       | `/pr-to-lint-rule` generates rule + tests + spec entry         |
+| **CI**                              | Nothing to verify            | `vigiles audit` catches hash drift, disabled rules, stale refs |
+
+## Codex
+
+|                               | Without vigiles                  | With vigiles                                            |
+| ----------------------------- | -------------------------------- | ------------------------------------------------------- |
+| **Instructions**              | Hand-written AGENTS.md           | Compiled from `.spec.ts`                                |
+| **Linter rule references**    | Trust-based                      | Verified at compile time                                |
+| **File paths / commands**     | Rot silently                     | Checked at compile time                                 |
+| **Direct edits to AGENTS.md** | Undetected                       | CI catches hash mismatch                                |
+| **Hooks / auto-compile**      | Not available (no plugin system) | Not available — run `vigiles compile` manually or in CI |
+| **CI**                        | Nothing to verify                | Same `vigiles audit` pipeline as Claude                 |
+
+Codex has no hook or plugin system. The compile-time verification and CI enforcement still work — the difference is there's no auto-recompilation on edit. You run `vigiles compile` before committing, and CI catches drift.
+
+## What's Deterministic vs What's Not
+
+| Check                            | Deterministic? | How                                                                                  |
+| -------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
+| Linter rule exists in catalog    | Yes            | Node API (`builtinRules`) or CLI (`ruff rule`, `rubocop --show-cops`)                |
+| Linter rule is enabled in config | Yes            | `calculateConfigForFile` (ESLint), `--show-settings` (Ruff), `--show-cops` (RuboCop) |
+| File path exists                 | Yes            | `fs.existsSync`                                                                      |
+| npm script exists                | Yes            | Parsed from `package.json`                                                           |
+| SHA-256 hash matches             | Yes            | Recompute and compare                                                                |
+| Duplicate rule detection         | Yes            | Normalized Compression Distance (NCD) with fixed threshold                           |
+| guidance → enforce suggestion    | **No**         | Agent reads linter docs, reasons about intent — `/strengthen` skill                  |
+| PR comment → lint rule           | **No**         | Agent generates custom rule code — `/pr-to-lint-rule` skill                          |
+| Spec content authoring           | **No**         | Agent or human writes the spec — vigiles verifies it                                 |
+
+Everything vigiles compiles and audits is deterministic — same input, same output, no LLM in the loop. The non-deterministic parts (authoring specs, suggesting upgrades, writing custom rules) are agent skills that run outside the compilation pipeline.
+
+## Flow
+
+```
+                        DETERMINISTIC                          AGENT-ASSISTED
+                  ┌─────────────────────────┐          ┌──────────────────────────┐
+                  │                         │          │                          │
+  .spec.ts ──────┤  vigiles compile         │          │  /strengthen             │
+       │         │    ✓ linter rules exist   │          │    guidance → enforce    │
+       │         │    ✓ rules enabled        │          │                          │
+       │         │    ✓ file paths valid     │          │  /pr-to-lint-rule        │
+       │         │    ✓ commands valid       │          │    PR comment → rule     │
+       │         │    → CLAUDE.md + hash     │          │                          │
+       │         └─────────────────────────┘          │  /edit-spec              │
+       │                                               │    agent edits .spec.ts  │
+       │         ┌─────────────────────────┐          └──────────────────────────┘
+       └────────▶│  vigiles audit           │                     │
+                 │    ✓ hash integrity      │                     │
+                 │    ✓ inline rule checks  │                     ▼
+                 │    ✓ duplicate detection  │          ┌──────────────────────────┐
+                 │    ✓ coverage gaps       │          │  hooks (Claude Code)     │
+                 └─────────────────────────┘          │    auto-compile on edit  │
+                                                       │    auto-regen types      │
+                                                       │    block direct md edits │
+                                                       └──────────────────────────┘
+```

package/docs/freshness.md

@@ -0,0 +1,124 @@
+# Freshness Detection
+
+vigiles detects when compiled instruction files are out of date. The `freshness` validation rule catches drift between your specs and the compiled markdown.
+
+## Configuration
+
+In `.vigilesrc.json`:
+
+```json
+{
+  "rules": {
+    "freshness": "error"
+  },
+  "freshnessMode": "strict"
+}
+```
+
+### Severity
+
+| Value              | Behavior                                  |
+| ------------------ | ----------------------------------------- |
+| `"error"`          | `vigiles audit` exits non-zero (CI fails) |
+| `"warn"` (default) | Prints warning, exits 0                   |
+| `false`            | Skip freshness checks entirely            |
+
+### Mode
+
+| Mode                 | What it checks                                                 | Cost          | False positives                         | False negatives               |
+| -------------------- | -------------------------------------------------------------- | ------------- | --------------------------------------- | ----------------------------- |
+| `"strict"` (default) | Recompiles in memory, diffs against existing output            | 2-5s per spec | Zero                                    | Zero                          |
+| `"input-hash"`       | Compares stored input fingerprint against current file state   | <100ms        | Possible (whitespace changes in config) | Possible (transitive deps)    |
+| `"output-hash"`      | Only checks if the `.md` was hand-edited (existing hash check) | <1ms          | Zero                                    | Many (misses all input drift) |
+
+**Strict mode** is the correct default. It catches every kind of staleness with zero false positives. The cost is running a full recompile in memory on every `vigiles audit`.
+
+**Input-hash mode** is faster. Use it when compilation is slow (many specs, heavy linter config loading). It tracks a fingerprint of all input files (spec source, linter configs, lock files, keyFiles, generated types). When any input changes, audit flags the output as stale. To use it, set `freshnessMode: "input-hash"` — `vigiles compile` will embed the input fingerprint in the compiled markdown.
+
+**Output-hash mode** is the minimal option. It only detects hand-edits to the compiled markdown (the pre-existing hash check). It won't catch disabled linter rules, deleted files, or spec changes.
+
+## What Counts as an Input
+
+In input-hash mode, vigiles tracks these files:
+
+| Category         | Files                                                                                                                                                                                                                                    | Why                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Spec source      | `CLAUDE.md.spec.ts`                                                                                                                                                                                                                      | Any spec change should force recompile                 |
+| Linter configs   | `eslint.config.*`, `.eslintrc.*`, `pyproject.toml`, `ruff.toml`, `Cargo.toml`, `clippy.toml`, `.pylintrc`, `.rubocop.yml`, `.stylelintrc.*`, `setup.cfg`                                                                                 | Disabling a rule makes `enforce()` claims stale        |
+| Package manifest | `package.json`                                                                                                                                                                                                                           | Scripts (`cmd()` refs) and deps (linter plugins)       |
+| Lock files       | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`, `Gemfile.lock`, `poetry.lock`, `uv.lock`, `pdm.lock`, `Cargo.lock`, `go.sum`, `composer.lock`, `packages.lock.json`, `Package.resolved`, `mix.lock`, `requirements.txt` | Dependency version changes can add/remove linter rules |
+| Referenced files | Every `file()` path in `keyFiles`                                                                                                                                                                                                        | Deletion or rename makes the reference stale           |
+| Generated types  | `.vigiles/generated.d.ts`                                                                                                                                                                                                                | If types are stale, rule references may be invalid     |
+| Extra inputs     | Configured via `freshnessInputs`                                                                                                                                                                                                         | For non-standard files (e.g., monorepo root lock file) |
+
+All files are auto-detected by checking existence at `basePath`. Lock files and linter configs cover 6+ ecosystems (Node.js, Ruby, Python, Rust, Go, PHP, .NET, Swift, Elixir).
+
+## Extra Inputs
+
+For monorepos or non-standard layouts, add extra files to track:
+
+```json
+{
+  "freshnessMode": "input-hash",
+  "freshnessInputs": ["../../yarn.lock", "shared/eslint-config/index.js"]
+}
+```
+
+## How the Input Hash Works
+
+At compile time (`vigiles compile`), when `freshnessMode` is `"input-hash"`:
+
+1. Discover all input files (spec, configs, lock files, keyFiles, etc.)
+2. Compute SHA-256 of each file's contents (missing files hash to `MISSING:<path>`)
+3. Combine all file hashes into a single fingerprint (SHA-256 of sorted hashes)
+4. Embed the fingerprint in the compiled markdown:
+
+```html
+<!-- vigiles:sha256:a1b2c3d4e5f6g7h8 compiled from CLAUDE.md.spec.ts -->
+<!-- vigiles:inputs:f9e8d7c6b5a49382 -->
+
+# CLAUDE.md ...
+```
+
+At audit time (`vigiles audit`):
+
+1. Extract the stored input fingerprint
+2. Recompute the fingerprint from current file state
+3. If they differ → stale
+
+## Audit Output
+
+```
+Freshness check:
+
+  ✓ CLAUDE.md — fresh (strict)
+  ✗ AGENTS.md — Output would differ if recompiled — run `vigiles compile`
+```
+
+With `--summary`:
+
+```
+vigiles: 1 stale (run vigiles compile)
+```
+
+## Lock File Detection
+
+vigiles auto-detects lock files for every major ecosystem. No configuration needed — if the file exists, it's tracked.
+
+| Lock file            | Ecosystem       |
+| -------------------- | --------------- |
+| `package-lock.json`  | Node.js (npm)   |
+| `yarn.lock`          | Node.js (Yarn)  |
+| `pnpm-lock.yaml`     | Node.js (pnpm)  |
+| `bun.lockb`          | Node.js (Bun)   |
+| `Gemfile.lock`       | Ruby (Bundler)  |
+| `poetry.lock`        | Python (Poetry) |
+| `uv.lock`            | Python (uv)     |
+| `pdm.lock`           | Python (PDM)    |
+| `requirements.txt`   | Python (pip)    |
+| `Cargo.lock`         | Rust (Cargo)    |
+| `go.sum`             | Go              |
+| `composer.lock`      | PHP (Composer)  |
+| `packages.lock.json` | .NET (NuGet)    |
+| `Package.resolved`   | Swift (SPM)     |
+| `mix.lock`           | Elixir (Mix)    |

package/docs/inline-mode.md

@@ -0,0 +1,119 @@
+# Inline mode
+
+Inline mode lets you adopt vigiles **one rule at a time**, without committing
+to a `.spec.ts` compile step. You add `<!-- vigiles:enforce ... -->` HTML
+comments directly to your existing `CLAUDE.md` / `AGENTS.md`, and
+`vigiles audit` verifies them the same way it verifies spec-declared rules:
+linter-backed existence check, closest-match typo suggestions, disabled-rule
+detection, and GitHub Actions annotations.
+
+It's the vigiles equivalent of `// eslint-disable-next-line` — minimum
+commitment, maximum incrementalism.
+
+## When to use it
+
+- You already have a `CLAUDE.md` and don't want to port it to `.spec.ts`
+- You want to experiment with a single rule before committing to the full
+  vigiles workflow
+- Your project isn't a TypeScript project at all and the build step feels
+  like dead weight
+- Hesitant teammates want to see the verification work before accepting a
+  new file type in the repo
+
+If you already have a real TypeScript project and you want the strongest
+guarantees (editor-time type safety, programmatic rule composition, the
+`generate-types` moat), use spec mode instead — see the main README.
+
+## Format
+
+A single HTML comment per rule:
+
+```md
+<!-- vigiles:enforce eslint/no-console "Use structured logger for app output" -->
+```
+
+Three required pieces:
+
+1. `vigiles:enforce` — only `enforce` is supported inline. Guidance rules
+   are just paragraphs in the surrounding prose, so a `guidance` comment
+   would be a tautology.
+2. `<linter>/<rule>` — the same reference format as `enforce()` in spec
+   mode. Supports all six linters (ESLint, Stylelint, Ruff, Clippy, Pylint,
+   RuboCop) and scoped plugin names (`eslint/@typescript-eslint/...`).
+3. `"<why>"` — a simple double-quoted string. No newlines, no embedded
+   quotes. If you need either, move to spec mode.
+
+## Example
+
+```md
+# My Project
+
+<!-- vigiles:enforce eslint/no-console "Route output through logger.ts" -->
+<!-- vigiles:enforce eslint/@typescript-eslint/no-floating-promises "Await or explicitly void" -->
+<!-- vigiles:enforce ruff/F401 "No unused imports" -->
+
+## Logging
+
+All application output must go through the shared logger module.
+Do not use `console.log` directly in src/.
+
+## Async
+
+Every promise must be awaited or explicitly voided. The ESLint rule
+enforces this automatically.
+```
+
+## What audit catches
+
+Running `vigiles audit CLAUDE.md` on the above file will:
+
+- Verify each `eslint/…`, `ruff/…` reference against your actual linter
+  config
+- Emit closest-match suggestions on typos: `"no-consol"` →
+  `did you mean "eslint/no-console"?`
+- Emit `::error` annotations when running inside GitHub Actions
+- Exit with code 2 (hard error) on any failed rule, so CI fails fast
+
+## What audit does NOT do in inline mode
+
+- **No type safety at edit time.** The `.spec.ts` path gets TypeScript
+  squiggles in the editor because `StrictLinterRule` is a type union of
+  every rule in your linters. Inline mode is strings-in-markdown, so
+  typos only surface at `vigiles audit` time. Still catches them before
+  CI, just not in the editor.
+- **No programmatic composition.** You can't reuse a batch of rules from
+  a helper. Each comment is its own line.
+- **No rule deduplication via NCD.** Duplicate-rule detection runs on
+  spec-mode files; inline rules are ungrouped.
+
+All of this is fine for the adoption-onramp use case. When you outgrow it,
+port to spec mode.
+
+## Mixing inline and spec mode
+
+Spec mode wins. If a file has both `CLAUDE.md.spec.ts` and inline
+comments inside `CLAUDE.md`, the spec compiler will overwrite the markdown
+on the next compile, and your inline comments will be gone. Pick one per
+file.
+
+## Ignoring `require-spec`
+
+The built-in `require-spec` validation rule demands a `.spec.ts` sibling
+for every `CLAUDE.md` / `AGENTS.md`. Inline mode satisfies it — any file
+with at least one `<!-- vigiles:enforce ... -->` comment is treated as
+spec-equivalent, so you do not need to add a `vigiles-disable require-spec`
+comment.
+
+## Graduating to spec mode
+
+When you've accumulated a dozen or so inline rules and the prose is
+starting to feel crowded, run:
+
+```bash
+npx vigiles init --target=CLAUDE.md
+```
+
+That scaffolds a `CLAUDE.md.spec.ts` next to your existing `CLAUDE.md`.
+Copy the inline enforce rules into the `rules:` block, delete the inline
+comments, and run `vigiles compile`. The markdown output will be rebuilt
+with a `sha256` hash header, and future edits flow through the spec.

package/docs/linter-support.md

@@ -0,0 +1,166 @@
+# Linter Cross-Referencing
+
+vigiles verifies that every `enforce()` rule in your spec actually exists and is enabled in your project. This is the core differentiator -- no other tool resolves rules against 6 linter APIs and checks config-enabled status.
+
+## How It Works
+
+When you write:
+
+```ts
+enforce("eslint/no-console", "Use the project logger instead.");
+```
+
+vigiles does two things at compile time:
+
+1. **Existence check** -- verifies the rule `no-console` exists in ESLint (via `builtinRules` or plugin resolution).
+2. **Config check** -- loads your ESLint flat config, calls `calculateConfigForFile`, and confirms the rule's severity is not `0` / `"off"`.
+
+If either check fails, compilation fails with a clear error:
+
+```
+Error: Rule "no-consloe" not found in eslint
+Error: Rule "no-console" is disabled in eslint config
+```
+
+The reference format is `<linter>/<rule>` -- e.g., `eslint/no-console`, `ruff/F401`, `clippy/needless_return`.
+
+## Supported Linters
+
+| Linter    | Detection      | Existence Check                               | Config Check                                          |
+| --------- | -------------- | --------------------------------------------- | ----------------------------------------------------- |
+| ESLint    | `node_modules` | Node API (`builtinRules` + plugin resolution) | Loads flat config, checks severity > 0                |
+| Stylelint | `node_modules` | Node API (`rules` export)                     | Loads config, checks rule value is not `null`         |
+| Ruff      | `PATH`         | CLI (`ruff rule <name>`)                      | Parses `ruff check --show-settings` for enabled codes |
+| Clippy    | `PATH`         | CLI (`cargo clippy --explain <name>`)         | Parses `Cargo.toml` `[lints.clippy]` section          |
+| Pylint    | `PATH`         | CLI (`pylint --help-msg=<name>`)              | Runs `pylint --list-msgs-enabled`                     |
+| RuboCop   | `PATH`         | CLI (`rubocop --show-cops <name>`)            | Parses `Enabled: true/false` from output              |
+
+Node-based linters (ESLint, Stylelint) are resolved via `createRequire` from the project's `node_modules`. CLI-based linters (Ruff, Clippy, Pylint, RuboCop) must be available on `PATH`.
+
+## ESLint Plugin Support
+
+Plugin rules use the format `eslint/<plugin>/<rule>`. vigiles resolves the plugin package and checks its exported `rules` object.
+
+**Scoped plugins** (`@scope/plugin`):
+
+```ts
+// Resolves @typescript-eslint/eslint-plugin, checks its "no-explicit-any" rule
+enforce("eslint/@typescript-eslint/no-explicit-any", "Use `unknown` instead.");
+```
+
+Resolution order for `@scope/name`:
+
+1. `@scope/eslint-plugin-name`
+2. `@scope/eslint-plugin`
+
+For bare scopes like `@typescript-eslint`, it resolves `@typescript-eslint/eslint-plugin`.
+
+**Unscoped plugins**:
+
+```ts
+// Resolves eslint-plugin-import, checks its "no-unresolved" rule
+enforce("eslint/import/no-unresolved", "Fix the import path.");
+```
+
+Resolution: `import` becomes `eslint-plugin-import`.
+
+Config-enabled checks for plugin rules go through ESLint's `calculateConfigForFile` with the full qualified name (e.g., `@typescript-eslint/no-explicit-any`), so they respect your flat config.
+
+## Custom Linters
+
+For tools not built in, use the `linters` config option in `vigiles.json` (or `package.json` under `"vigiles"`):
+
+```json
+{
+  "linters": {
+    "my-tool": {
+      "rulesDir": "tools/my-tool/rules/"
+    }
+  }
+}
+```
+
+vigiles checks if a file matching the rule name exists in the specified directory. For example, `enforce("my-tool/no-foo")` passes if `tools/my-tool/rules/no-foo.*` exists (any extension).
+
+Multiple directories are supported via an array:
+
+```json
+{
+  "linters": {
+    "my-tool": {
+      "rulesDir": ["tools/my-tool/rules/", "tools/my-tool/extra-rules/"]
+    }
+  }
+}
+```
+
+Custom linters only support existence checks. Config-enabled status is always `"unknown"`.
+
+## generate-types
+
+`vigiles generate-types` scans all 6 linter APIs, `package.json`, and project files, then emits `.vigiles/generated.d.ts` with type unions derived from your actual project state.
+
+```sh
+npx vigiles generate-types
+```
+
+This produces a `.d.ts` file like:
+
+```ts
+/**
+ * Auto-generated by `vigiles generate-types`.
+ * DO NOT EDIT -- re-run `vigiles generate-types` to update.
+ */
+
+declare module "vigiles/generated" {
+  /** 42 enabled eslint rules (via flat config). */
+  export type EslintRule =
+    | "no-console"
+    | "no-debugger"
+    | "@typescript-eslint/no-explicit-any"
+    // ...
+
+  /** 5 enabled ruff rules (via CLI). */
+  export type RuffRule = "E501" | "F401" | "F841" | "I001" | "UP006";
+
+  /** All enabled linter rules across all detected linters. */
+  export type LinterRule = EslintRule | RuffRule;
+
+  /** 8 npm scripts from package.json. */
+  export type NpmScript = "build" | "test" | "lint" | "fmt" | "fmt:check" | ...;
+
+  /** 23 project files. */
+  export type ProjectFile = "src/cli.ts" | "src/compile.ts" | "src/linters.ts" | ...;
+}
+```
+
+The TypeScript compiler then proves references are valid at authoring time. A typo like `enforce("eslint/no-consloe")` becomes a type error in your editor before you ever run `vigiles compile`. This shifts rule-reference validation from runtime to authoring time.
+
+Discovery methods per linter:
+
+- **ESLint** -- loads flat config via `calculateConfigForFile`, collects rules with severity > 0
+- **Stylelint** -- loads config via `createLinter` + `getConfigForFile`, collects non-null rules
+- **Ruff** -- parses `ruff check --show-settings` for `linter.rules.enabled`
+- **Pylint** -- parses `pylint --list-msgs-enabled`, extracts both IDs (`C0114`) and symbolic names
+- **RuboCop** -- parses `rubocop --show-cops` output for cop names
+- **Clippy** -- reads `Cargo.toml` `[lints.clippy]` section, excludes rules set to `"allow"`
+
+Project files default to `src/**/*` but can be configured via `fileGlobs`.
+
+## Catalog-Only Mode
+
+Set `catalogOnly: true` to skip config-enabled checks and only verify that rules exist in the linter's catalog:
+
+```json
+{
+  "catalogOnly": true
+}
+```
+
+In this mode, `checkLinterRule` returns `"unknown"` for the `enabled` field instead of loading linter configs. This is useful when:
+
+- Full config loading is slow in CI (ESLint/Stylelint config resolution can take seconds)
+- You only care that referenced rules are real, not that they are currently turned on
+- The linter config is not available in the build environment
+
+The option can be set in `vigiles.json`, `package.json` under `"vigiles"`, or via the `INPUT_CATALOG_ONLY` environment variable in the GitHub Action.