holocron/plugins/lint/.apm/skills/vale-run/SKILL.md

---
name: vale-run
description: >
  Use when running Vale (a prose/style linter) on a project that already has a
  .vale.ini and acting on its output — even when the user does not say "Vale",
  as in "lint the docs", "check prose style", or "why is CI failing on the docs
  check". Not setting up Vale config or styles -> `vale-config`.
metadata:
  version: "0.1.3"
  category: lint
  source_keys:
    - context7-websites-vale-sh
    - house-vale-3-15-2-repro
---

## Gotchas

- Vale's exit code keys off `error`-level alerts only — `warning` and `suggestion` alerts print and still exit `0`, and `MinAlertLevel`/`--minAlertLevel` filter what is displayed, never the exit code — no flag makes warnings fail. A rule that must gate CI or a commit hook has to be `level: error`. This is the most common way a Vale gate silently passes everything.
- Check whether the target repo documents its own `vale` wrapper script (README, CONTRIBUTING, pre-commit config, `scripts/`) before calling the binary. Some projects wrap `vale` to work around real bugs — e.g. a `text.frontmatter.<key>` scope that silently stops matching multi-line values (`>` folded scalars, plain continuation lines and quoted multi-line scalars all go unmatched; a `|` literal block scalar still works) — so bare `vale` skips whatever the wrapper fixes. Invoke the documented wrapper with the same arguments.

## Running vale

Default invocation (when the target repo has no documented Vale wrapper — see Gotchas):

```bash
vale <path-or-glob>
```

Key flags:

| Flag | Purpose |
|---|---|
| `--output=<style>` | Output format/template: `CLI` (default, human-readable), `line` (compact, one alert per line, good for grep/piping), `JSON` (for programmatic parsing), or a custom template. |
| `--minAlertLevel=<suggestion\|warning\|error>` | Overrides `MinAlertLevel` from `.vale.ini` for this run only, without editing config. Filters what is displayed; does not affect the exit code. |
| `--no-exit` | Suppresses the nonzero exit that `error`-level alerts would otherwise cause; a no-op when no rule is `error`-level. Use in CI stages that should surface lint output without hard-failing the build. |
| `--ignore-syntax` | Treats input as plain text, skipping format-aware parsing — use when a file's syntax-aware parser produces noisy or wrong results. |

`vale sync` downloads the packages/styles declared in `.vale.ini` — that's a one-time-per-change setup step (vale-config's territory), not part of a normal lint run. If a run behaves as though no styles are active, check `vale ls-config` before concluding it is a sync problem — an unrun `vale sync` is the usual cause, and not a `vale-run` problem. `ls-config` resolves config files, styles and `StylesPath` search paths; it never enumerates rules, so it cannot tell you a given rule is live.

Prefer `--output=JSON` whenever the caller (a script, a CI step, another agent) needs to act on individual alerts rather than just get a pass/fail signal — `CLI` and `line` are for humans reading the terminal.

## Fixing false positives

Before writing any inline suppression markup (steps 2 and 3 below), read `references/troubleshooting.md`: the form follows the parser the config picks, not the file extension, and the wrong form suppresses nothing while Vale reports no error.

`.mdx` is the trap — the two parsers take opposite forms, so read `.vale.ini` first. Under `[formats] mdx = md` (what `vale-config` recommends) it is Markdown: `<!-- vale off -->` suppresses, `{/* vale off */}` does not. Without that mapping Vale takes the native MDX path, which needs the external `mdx2vast` binary (`npm install -g mdx2vast`); missing, the whole invocation dies — `E100 [lintMDX] ... mdx2vast not found`, exit 2 — leaving every other file in the run unlinted too.

Scope the fix as narrowly as possible, in this order:

1. **Mentioning banned phrasing rather than using it**: wrap it in backticks or a fenced code block. Vale skips code spans and fences, so no suppression is needed at all. Try this before any suppression markup.
2. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup.
3. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (in Markdown, e.g. `<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->` ... `= YES`), rather than the whole rule.
4. **Known project term failing spell check**: add it to the style's `ignore` list, not an inline suppression — and put the listed file at the `StylesPath` root, because an `ignore` path that resolves nowhere is a silent no-op (`references/troubleshooting.md`).

Never disable a rule project-wide to fix one false positive — editing `.vale.ini`/`BasedOnStyles` is vale-config's job, and it silences the rule everywhere, not just the false-positive case.

If output looks wrong because Vale mis-parsed a file's format, rerun with `--ignore-syntax` before assuming the rule itself is broken.

For CI that fails solely because Vale returned non-zero on `error`-level alerts — not because the content is wrong for that pipeline stage — add `--no-exit` rather than disabling the rule. If the failing alerts are warnings or suggestions, Vale is not what failed the build; look elsewhere.

If a rule appears not to apply, if you need the spelling-ignore syntax, if a CI failure still needs diagnosing, or if setting Vale up as a pre-commit hook, read `references/troubleshooting.md`.