chore(lint): register lint plugin in marketplace and document scope

Adds the lint plugin entry to both marketplace manifests and records
the resolved scope/structure decisions from grilling in CONTEXT.md:
standalone repo-agnostic plugin, split vale-config/vale-run skills,
report-only lint-runner agent, audit-pipeline wiring deferred.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn

.claude-plugin/marketplace.json

@@ -38,7 +38,12 @@
         "repo": "mattpocock/skills",
         "source": "github"
       }
+    },
+    {
+      "description": "Skills and agents for configuring and running linters, starting with Vale.",
+      "name": "lint",
+      "source": "./plugins/lint"
     }
   ],
-  "version": "0.2.0"
+  "version": "0.3.0"
 }

.github/plugin/marketplace.json

@@ -38,7 +38,12 @@
         "repo": "mattpocock/skills",
         "source": "github"
       }
+    },
+    {
+      "description": "Skills and agents for configuring and running linters, starting with Vale.",
+      "name": "lint",
+      "source": "./plugins/lint"
     }
   ],
-  "version": "0.2.0"
+  "version": "0.3.0"
 }

CONTEXT.md

@@ -66,5 +66,8 @@ A skill pair in the `core` plugin for writing, updating, and reviewing a target
 ### provider-adapter-author
 A companion skill (`core` plugin) that detects a target repo's provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) and, where it duplicates content AGENTS.md should own, converts it into a thin adapter that imports AGENTS.md — mirroring this repo's own ADR-0002/ADR-0003 two-tier adapter pattern. Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`: checks for an import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — the check is mechanical, so a script suffices per governance.md's "prefer deterministic code for repeatable tasks." `agentsmd-author` calls this skill via skill composition when it detects an existing provider file with overlapping content.
 
+### lint plugin
+A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling, and not (yet) wired into `skill-audit`/`agent-audit`. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Wiring Vale into the audit pipeline as a prefilter (the original motivation captured in branch `feat/84-vale-audit-prefilter`) is deferred to a follow-up task once this plugin exists standalone. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
+
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.

plugins/kyberforge/docs/README.md

@@ -17,4 +17,5 @@ Upstream reference material gathered during skill authoring. Not shipped with th
 |------|---------|
 | `research/docs/agentskillsio/` | agentskills.io spec, skill authoring, description optimization, eval design, scripts |
 | `research/docs/agentsmd/` | agents.md format spec and cross-tool configuration reference |
+| `research/docs/vale/` | Vale (vale.sh) prose linter — config, styles/rules/checks model, CLI reference, installation |
 | `research/examples/skill-write/` | Upstream skill examples reviewed when authoring skill-write and skill-audit |

plugins/lint/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "author": {
+    "name": "Defame1297",
+    "url": "https://git.dev.rkdr.net/Defame1297/"
+  },
+  "description": "Skills and agents for configuring and running linters, starting with Vale.",
+  "displayName": "Lint",
+  "keywords": [
+    "lint",
+    "vale",
+    "style",
+    "prose",
+    "linter"
+  ],
+  "license": "MIT",
+  "name": "lint",
+  "version": "1.1.0"
+}

plugins/lint/.mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

plugins/lint/agents/lint-runner.agent.md

@@ -0,0 +1,38 @@
+---
+name: lint-runner
+
+description: Runs a linter sweep over a target file or directory scope and reports findings. Currently backs onto Vale (prose/style linting) via the vale-config and vale-run skills; built to add other linters later without changing its own contract. Use when a caller needs a lint pass run in an isolated context and wants findings back, not fixes applied.
+
+tools: ["execute", "read", "search"]
+
+---
+
+You are a linter runner. When invoked, you run the appropriate linter(s) over the requested scope, collect their findings, and report them back in a structured, reviewable form. You never edit files.
+
+## Inputs
+
+- **scope:** file path, directory path, or glob to lint
+- **linter:** which linter to run (defaults to `vale` — the only backend currently wired up)
+- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini`); if none exists, say so in your report rather than inventing one
+
+## Process
+
+1. Determine whether the target scope already has linter configuration in place (e.g. `.vale.ini` for Vale). If not, use the `vale-config` skill to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
+2. Use the `vale-run` skill to invoke the linter over the scope and interpret its raw output.
+3. Normalize findings into one shape regardless of backend linter: file, line, rule/check, severity, message.
+4. Do not edit, fix, or rewrite any flagged content. If a finding looks trivially fixable, note that in the report — do not act on it.
+5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), report that as a blocking finding rather than attempting to install or configure it silently.
+
+## Output
+
+Report findings as a flat list, most-severe first:
+
+```
+- file: <path>
+  line: <line number or range>
+  rule: <check/rule name>
+  severity: <error | warning | suggestion>
+  message: <finding text>
+```
+
+Follow with a one-line summary: total findings by severity, and whether the run was blocked (e.g. linter not configured). If there are zero findings, say so explicitly — do not omit the report.

plugins/lint/agents/lint-runner.md

@@ -0,0 +1,38 @@
+---
+name: lint-runner
+
+description: Runs a linter sweep over a target file or directory scope and reports findings. Currently backs onto Vale (prose/style linting) via the vale-config and vale-run skills; built to add other linters later without changing its own contract. Use when a caller needs a lint pass run in an isolated context and wants findings back, not fixes applied.
+
+tools: Bash, Read, Grep, Glob
+
+---
+
+You are a linter runner. When invoked, you run the appropriate linter(s) over the requested scope, collect their findings, and report them back in a structured, reviewable form. You never edit files.
+
+## Inputs
+
+- **scope:** file path, directory path, or glob to lint
+- **linter:** which linter to run (defaults to `vale` — the only backend currently wired up)
+- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini`); if none exists, say so in your report rather than inventing one
+
+## Process
+
+1. Determine whether the target scope already has linter configuration in place (e.g. `.vale.ini` for Vale). If not, use the `vale-config` skill to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
+2. Use the `vale-run` skill to invoke the linter over the scope and interpret its raw output.
+3. Normalize findings into one shape regardless of backend linter: file, line, rule/check, severity, message.
+4. Do not edit, fix, or rewrite any flagged content. If a finding looks trivially fixable, note that in the report — do not act on it.
+5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), report that as a blocking finding rather than attempting to install or configure it silently.
+
+## Output
+
+Report findings as a flat list, most-severe first:
+
+```
+- file: <path>
+  line: <line number or range>
+  rule: <check/rule name>
+  severity: <error | warning | suggestion>
+  message: <finding text>
+```
+
+Follow with a one-line summary: total findings by severity, and whether the run was blocked (e.g. linter not configured). If there are zero findings, say so explicitly — do not omit the report.

plugins/lint/docs/research/docs/vale/cli-reference.md

@@ -0,0 +1,29 @@
+---
+topic: cli-reference
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Core Invocation
+
+```bash
+$ vale README.md
+```
+
+Lints the given file(s)/glob against the styles configured in `.vale.ini`.
+
+## Key Flags and Subcommands
+
+| Command/Flag | Purpose |
+|---|---|
+| `vale sync` | Downloads and installs packages/styles declared in `.vale.ini`. Run after install and whenever `Packages` changes. |
+| `vale ls-config` | Prints the currently active, fully-resolved configuration as JSON. Useful for debugging what settings actually apply to a file. |
+| `--output=<style>` | Sets the output format/template: `line`, `JSON`, `CLI` (default), or a custom template. |
+| `--no-exit` | Suppresses the non-zero exit code Vale normally returns when alerts are found — useful in CI pipelines that shouldn't hard-fail on lint output. |
+| `--ignore-syntax` | Treats input as plain, unformatted text, skipping syntax-aware parsing (Markdown/HTML/etc). |
+| `--minAlertLevel=<level>` | Overrides `MinAlertLevel` from the config for this run (`suggestion`, `warning`, `error`). |
+| `--version` | Prints the Vale binary version. |
+
+## Exit Codes
+
+By default, `vale` exits non-zero when it finds any alert at or above `MinAlertLevel` — this is what makes it usable as a CI gate. Pass `--no-exit` to always exit `0` regardless of findings.

plugins/lint/docs/research/docs/vale/configuration.md

@@ -0,0 +1,106 @@
+---
+topic: configuration
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## `.vale.ini` Structure
+
+Configuration is INI-formatted with three sections, in order:
+
+```ini
+# Core settings appear at the top
+# (the "global" section).
+
+[formats]
+# Format associations appear under
+# the optional "formats" section.
+
+[*]
+# Format-specific settings appear
+# under a user-provided "glob"
+# pattern.
+```
+
+Core (global) settings apply application-wide; glob sections (`[*]`, `[*.md]`, etc.) scope settings to files matching that pattern.
+
+## Core Settings
+
+| Key | Type | Purpose |
+|---|---|---|
+| `StylesPath` | string | Path to all Vale-related resources (styles, dictionaries, vocab). |
+| `Packages` | string[] | Packages to download and install via `vale sync`. |
+| `Vocab` | string[] | Vocabularies to load. |
+| `MinAlertLevel` | enum | Minimum severity to report: `suggestion`, `warning`, or `error`. |
+| `IgnoredScopes` | enum | Inline-level HTML tags to ignore. |
+| `SkippedScopes` | enum | Block-level HTML tags to ignore entirely. |
+
+Example:
+
+```ini
+StylesPath = styles
+MinAlertLevel = suggestion
+
+[*.md]
+BasedOnStyles = Vale
+```
+
+## Format Associations
+
+Map an unrecognized extension onto a supported one so Vale lints it with the right parser. This is an extension-level substitution only — it does not add new file-type support:
+
+```ini
+[formats]
+mdx = md
+```
+
+## Vocabularies
+
+Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
+
+```ini
+StylesPath = styles
+
+Vocab = Blog
+
+[*]
+BasedOnStyles = Vale, MyStyle
+```
+
+## Packages
+
+Third-party style packages are declared via `Packages` and then activated per glob with `BasedOnStyles`:
+
+```ini
+Packages = Google, write-good
+
+[*.md]
+BasedOnStyles = Vale, Google, write-good
+```
+
+## Local Overrides
+
+A project can layer a local `.vale.ini` that overrides `StylesPath`, adds packages, and changes `BasedOnStyles` for a subset of files — local settings merge with or override the global ones:
+
+```ini
+StylesPath = localpath
+
+Packages = write-good
+
+[*.md]
+BasedOnStyles = write-good
+```
+
+## Rule Header Fields
+
+Individual rule YAML files (under a style's directory) support these header fields:
+
+| Field | Required | Default | Purpose |
+|---|---|---|---|
+| `extends` | yes | — | Check this rule extends (e.g. `existence`). |
+| `message` | yes | — | Message shown when triggered; supports `%s` formatting per check type. |
+| `level` | no | `suggestion` | Severity: `suggestion`, `warning`, or `error`. |
+| `scope` | no | `text` | Scope the rule applies to (e.g. `heading`). |
+| `link` | no | — | URL with more info about the rule. |
+| `limit` | no | — | Max number of triggers per file. |
+| `vocab` | no | `true` | Set `false` to disable active vocabularies for this rule. |

plugins/lint/docs/research/docs/vale/examples.md

@@ -0,0 +1,52 @@
+---
+topic: examples
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Project Initialization Walkthrough
+
+```bash
+$ cd some-project
+# create .vale.ini with StylesPath + BasedOnStyles
+$ vale sync         # downloads declared packages/styles into StylesPath
+$ ls styles          # confirms styles were installed
+$ vale README.md     # lint a file
+```
+
+The `.vale.ini` file must exist before `vale sync` — it declares which packages to fetch.
+
+## Typical Project Config
+
+```ini
+StylesPath = styles
+MinAlertLevel = error
+
+[*.md]
+BasedOnStyles = ProjectStyle
+```
+
+## pre-commit Integration
+
+Vale ships a pre-commit hook definition. A typical setup runs `vale sync` once (with `pass_filenames: false`) plus the actual lint pass with CI-appropriate flags:
+
+```yaml
+repos:
+  - repo: https://github.com/errata-ai/vale
+    rev: 16d3a7f
+    hooks:
+      - id: vale
+        name: vale sync
+        pass_filenames: false
+        args: [sync]
+      - id: vale
+        args: [--output=line, --minAlertLevel=error]
+```
+
+## CI Output for Machine Parsing
+
+```bash
+$ vale --output=JSON README.md
+```
+
+Use `--output=JSON` when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.

plugins/lint/docs/research/docs/vale/installation.md

@@ -0,0 +1,41 @@
+---
+topic: installation
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Package Managers
+
+Vale is distributed via standard OS package managers:
+
+```bash
+brew install vale      # macOS
+snap install vale      # Linux
+```
+
+```powershell
+choco install vale      # Windows
+```
+
+## Docker
+
+An official image is available on Docker Hub:
+
+```bash
+docker pull jdkato/vale
+```
+
+## Post-Install: Syncing Styles
+
+Installing the `vale` binary alone does not install any styles. After install, run `vale sync` to download and install the styles/packages declared in `.vale.ini`:
+
+```bash
+$ vale sync
+```
+
+## Format-Specific Extras
+
+Some input formats need an external converter installed separately before Vale can process them:
+
+- reStructuredText: `pip install docutils` (provides `rst2html`)
+- MDX: `npm install -g mdx2vast`

plugins/lint/docs/research/docs/vale/overview.md

@@ -0,0 +1,43 @@
+---
+topic: overview
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## What Vale Is
+
+Vale is a cross-platform command-line tool that brings code-like linting to prose. Rather than checking general grammar, it enforces project-specific writing style rules — consistency of terminology, phrasing, and formatting — the same way a linter enforces a code style guide.
+
+## Styles, Rules, and Checks
+
+Vale's configuration model has three layers:
+
+- **Styles** — a named collection of rules (e.g. the built-in `Vale` style, or third-party styles like `Google` or `write-good`). A project can apply multiple styles at once via `BasedOnStyles`.
+- **Rules** — individual YAML files that define one specific check (e.g. flag a term, enforce a heading capitalization pattern). Each rule `extends` a check and sets a `message`, `level`, and other header fields.
+- **Checks** — the underlying functions a rule extends to perform analysis: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`.
+
+## Built-in Style
+
+Vale ships with a default `Vale` style containing four rules:
+
+- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
+- `Vale.Terms` — enforces the project's accepted vocabulary terms.
+- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
+- `Vale.Repetition` — flags repeated words (e.g. "the the").
+
+## Styles Directory Layout
+
+Styles live under `StylesPath` in a nested folder structure, one subdirectory per style, each holding YAML rule files:
+
+```
+styles/
+├── base/
+│   ├── ComplexWords.yml
+│   ├── SentenceLength.yml
+├── blog/
+│   ├── TechTerms.yml
+└── docs/
+    ├── Branding.yml
+```
+
+This lets a project mix a shared base style with format- or section-specific styles, all activated per-glob in `.vale.ini`.

plugins/lint/docs/research/docs/vale/sources.md

@@ -0,0 +1,8 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, CLI commands and flags, installation across package managers and Docker, format-specific inline disable syntax, pre-commit integration, spelling ignore lists.
+- **Contributing files:** overview.md, installation.md, configuration.md, cli-reference.md, examples.md, troubleshooting.md
+- **Status:** `extracted`

plugins/lint/docs/research/docs/vale/troubleshooting.md

@@ -0,0 +1,56 @@
+---
+topic: troubleshooting
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Suppressing False Positives Inline
+
+Vale supports inline markup comments to disable checks for a section of content. Syntax varies by format:
+
+Markdown/MDX:
+```mdx
+{/* vale off */}
+This text will be ignored.
+{/* vale on */}
+```
+
+Org mode:
+```org
+# vale off
+This text will be ignored.
+# vale on
+```
+
+## Disabling a Specific Rule for Specific Matches
+
+Rather than disabling all checks, target one rule and specific known-exception strings, then re-enable:
+
+```mdx
+{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
+This is some text ACT test
+{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}
+```
+
+This is the preferred fix for recurring false positives on specific terms — it keeps the rule active everywhere else instead of disabling it project-wide.
+
+## Ignoring Words in Spell Check
+
+The `spelling` check accepts an `ignore` list of external plain-text files, so known project-specific terms don't need touching the dictionary:
+
+```yaml
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+ignore:
+  - ignore1.txt
+  - ignore2.txt
+```
+
+## Plain-Text Fallback
+
+If a file's syntax-aware parsing produces noisy/incorrect results (e.g. an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.
+
+## CI Failing Unexpectedly
+
+If a CI job fails solely because Vale returns a non-zero exit code on found alerts (not because the content is actually wrong for that pipeline stage), add `--no-exit` rather than suppressing the rule itself — this preserves the lint output while not gating the build on it.

plugins/lint/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

plugins/lint/plugin.json

@@ -0,0 +1,23 @@
+{
+  "agents": "agents/",
+  "author": {
+    "email": "defame1297@rkdr.net",
+    "name": "Defame1297"
+  },
+  "description": "Skills and agents for configuring and running linters, starting with Vale.",
+  "hooks": "hooks.json",
+  "keywords": [
+    "lint",
+    "vale",
+    "style",
+    "prose",
+    "linter"
+  ],
+  "license": "MIT",
+  "mcpServers": ".mcp.json",
+  "name": "lint",
+  "skills": [
+    "skills/"
+  ],
+  "version": "1.1.0"
+}

plugins/lint/skills/vale-config/README.md

@@ -0,0 +1,23 @@
+# vale-config
+
+Install and configure Vale, the prose/style linter — `.vale.ini`, `StylesPath`, built-in/third-party/custom styles, and activation via `BasedOnStyles`.
+
+## What it does
+
+Covers the setup side of Vale: getting a project from no config to a working `.vale.ini` where `vale sync` runs clean and every declared style is actually activated for the right files. Does not run Vale or interpret its output — see `vale-run` for that.
+
+## Usage
+
+```
+/vale-config
+```
+
+Describe what you want configured: initial setup, adding a third-party style package, or a custom rule. The skill covers install, `StylesPath` layout, `.vale.ini` structure, and `BasedOnStyles` activation.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/configuration-reference.md` | Full `.vale.ini` field and rule-header reference |
+| `references/sources.md` | Research sources backing the Vale configuration guidance |

plugins/lint/skills/vale-config/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: vale-config
+
+description: >
+  Use when installing or configuring Vale, the cross-platform prose/style linter — setting up
+  .vale.ini, choosing a StylesPath, adding built-in, third-party, or custom styles, and activating
+  them per file glob via BasedOnStyles. Covers the setup side of Vale only: getting a project from
+  "no Vale config" to "vale sync runs clean and BasedOnStyles is wired up correctly". Use even if the
+  user doesn't say "Vale" explicitly — "set up prose linting", "lint our docs for style", "enforce a
+  vocabulary/terminology list in markdown" all apply. Do not use when the user wants to actually run
+  Vale and interpret its output on existing config — use vale-run for that.
+
+metadata:
+  category: lint
+  version: "0.1.0"
+  source_keys:
+    - context7-websites-vale-sh
+---
+
+## Gotchas
+
+- Installing the `vale` binary installs no styles. A fresh `.vale.ini` with `BasedOnStyles` set will fail or find nothing until `vale sync` runs and downloads the `Packages` it declares.
+- `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob.
+- `Packages` (top-level, fetched by `vale sync`) and `BasedOnStyles` (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget.
+
+## Setup workflow
+
+- [ ] **Install** the `vale` binary: `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or `docker pull jdkato/vale`.
+- [ ] **Pick a `StylesPath`** (conventionally `styles`) and create it. This is where all styles, dictionaries, and vocab live.
+- [ ] **Write `.vale.ini`** at the project root with at minimum:
+  ```ini
+  StylesPath = styles
+  MinAlertLevel = suggestion
+
+  [*.md]
+  BasedOnStyles = Vale
+  ```
+  `Vale` here is the built-in style (`Vale.Spelling`, `Vale.Terms`, `Vale.Avoid`, `Vale.Repetition`) — no download needed, it always works.
+- [ ] **Add third-party styles** (optional) by declaring them in `Packages`, then activating them in the same or another glob's `BasedOnStyles`:
+  ```ini
+  Packages = Google, write-good
+
+  [*.md]
+  BasedOnStyles = Vale, Google, write-good
+  ```
+- [ ] **Sync**: run `vale sync` to download everything listed in `Packages` into `StylesPath`.
+- [ ] **Verify activation**: confirm every style named in `Packages` also appears in at least one glob's `BasedOnStyles` — an unreferenced package downloads but never lints anything.
+
+For the full `.vale.ini` field reference (formats mapping, vocab, local overrides, custom rule header fields), read `references/configuration-reference.md`.
+
+## Custom styles
+
+A custom style is just a new subdirectory under `StylesPath`, holding one YAML file per rule:
+
+```
+styles/
+└── MyStyle/
+    └── NoJargon.yml
+```
+
+Each rule file needs `extends` (the check it implements, e.g. `existence`) and `message` at minimum. Activate the style the same way as any other: add `MyStyle` to `BasedOnStyles` for the relevant glob. See `references/configuration-reference.md` for the full rule header field table.

plugins/lint/skills/vale-config/references/configuration-reference.md

@@ -0,0 +1,78 @@
+---
+topic: configuration-reference
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Core Settings
+
+| Key | Type | Purpose |
+|---|---|---|
+| `StylesPath` | string | Path to all Vale-related resources (styles, dictionaries, vocab). |
+| `Packages` | string[] | Packages to download and install via `vale sync`. |
+| `Vocab` | string[] | Vocabularies to load. |
+| `MinAlertLevel` | enum | Minimum severity to report: `suggestion`, `warning`, or `error`. |
+| `IgnoredScopes` | enum | Inline-level HTML tags to ignore. |
+| `SkippedScopes` | enum | Block-level HTML tags to ignore entirely. |
+
+## Format Associations
+
+Map an unrecognized extension onto a supported one so Vale lints it with the right parser — an extension-level substitution only, it does not add new file-type support:
+
+```ini
+[formats]
+mdx = md
+```
+
+## Vocabularies
+
+Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
+
+```ini
+StylesPath = styles
+
+Vocab = Blog
+
+[*]
+BasedOnStyles = Vale, MyStyle
+```
+
+## Local Overrides
+
+A project can layer a local `.vale.ini` that overrides `StylesPath`, adds packages, and changes `BasedOnStyles` for a subset of files — local settings merge with or override the global ones:
+
+```ini
+StylesPath = localpath
+
+Packages = write-good
+
+[*.md]
+BasedOnStyles = write-good
+```
+
+## Rule Header Fields
+
+Individual rule YAML files (under a style's directory) support these header fields:
+
+| Field | Required | Default | Purpose |
+|---|---|---|---|
+| `extends` | yes | — | Check this rule extends (e.g. `existence`). |
+| `message` | yes | — | Message shown when triggered; supports `%s` formatting per check type. |
+| `level` | no | `suggestion` | Severity: `suggestion`, `warning`, or `error`. |
+| `scope` | no | `text` | Scope the rule applies to (e.g. `heading`). |
+| `link` | no | — | URL with more info about the rule. |
+| `limit` | no | — | Max number of triggers per file. |
+| `vocab` | no | `true` | Set `false` to disable active vocabularies for this rule. |
+
+## Checks
+
+The underlying functions a rule's `extends` field can reference: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`.
+
+## Built-in Style
+
+Vale ships with a default `Vale` style containing four rules, usable without `vale sync`:
+
+- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
+- `Vale.Terms` — enforces the project's accepted vocabulary terms.
+- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
+- `Vale.Repetition` — flags repeated words (e.g. "the the").

plugins/lint/skills/vale-config/references/sources.md

@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, installation across package managers and Docker.
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Contributing files:** SKILL.md, references/configuration-reference.md
+- **Status:** `extracted`

plugins/lint/skills/vale-run/README.md

@@ -0,0 +1,23 @@
+# vale-run
+
+Run Vale (a prose/style linter) against an already-configured project and interpret its results.
+
+## What it does
+
+This skill covers invoking the `vale` CLI against files or directories, choosing an output format (human-readable CLI, `line`, or machine-parseable `JSON`), filtering by severity via `--minAlertLevel`, and handling exit codes in scripts and CI. It also covers resolving common runtime issues: false positives, format-specific inline suppression, and CI failures caused solely by Vale's non-zero exit code. It assumes the project already has a working `.vale.ini` and installed styles — setting those up is the sibling `vale-config` skill's job.
+
+## Usage
+
+```
+/vale-run
+```
+
+Describe what you want to lint and how (human-readable output, CI/JSON output, filtered by severity). The skill will pick the right flags and, if results include false positives, walk through the narrowest applicable fix.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Core invocation, key flags, output format guidance, false-positive triage order |
+| `references/troubleshooting.md` | Inline suppression syntax, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases |
+| `references/sources.md` | Research provenance |

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

@@ -0,0 +1,61 @@
+---
+name: vale-run
+description: >
+  Use when running Vale (a prose/style linter) against files or directories in an
+  already-configured project — one that already has a .vale.ini — and interpreting
+  or reporting its results: choosing an output format for humans vs. CI, filtering
+  by severity, handling Vale's exit codes in scripts, or resolving common runtime
+  issues like false positives and unexpected CI failures. Use even if the user
+  doesn't say "vale" explicitly, e.g. "lint the docs", "check prose style", "run
+  the style linter", "why is CI failing on the docs check". Do not use when the
+  project has no .vale.ini yet, or needs styles installed/configured — that's the
+  vale-config skill.
+metadata:
+  version: "0.1.0"
+  category: lint
+  source_keys:
+    - context7-websites-vale-sh
+---
+
+## Gotchas
+
+- Vale exits non-zero whenever it finds an alert at or above `MinAlertLevel` — that's what makes it usable as a CI gate, not a sign the invocation failed. Read the output before concluding the command errored.
+- `vale ls-config` prints the fully-resolved, currently active configuration as JSON — the fastest way to check why a rule "isn't applying" is what's actually active, not what's written in `.vale.ini`.
+- Inline suppression syntax is format-specific: Markdown/MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. Don't assume one syntax works across formats.
+
+## Running vale
+
+Default invocation:
+
+```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. |
+| `--no-exit` | Forces exit code `0` regardless of findings. 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, that's a sign `vale sync` hasn't been run yet, not a `vale-run` problem.
+
+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
+
+Scope the fix as narrowly as possible, in this order:
+
+1. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup.
+2. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (e.g. `{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}` ... `= YES`), rather than the whole rule.
+3. **Known project term failing spell check**: add it to the style's `ignore` list, not an inline suppression.
+
+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 found alerts — not because the content is wrong for that pipeline stage — add `--no-exit` rather than disabling the rule.
+
+If setting up Vale as a pre-commit hook or need the full inline-suppression/spelling-ignore syntax reference, read `references/troubleshooting.md`.

plugins/lint/skills/vale-run/references/sources.md

@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, CLI commands and flags, installation across package managers and Docker, format-specific inline disable syntax, pre-commit integration, spelling ignore lists.
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Contributing files:** SKILL.md, references/troubleshooting.md
+- **Status:** `extracted`

plugins/lint/skills/vale-run/references/troubleshooting.md

@@ -0,0 +1,78 @@
+---
+source_keys:
+  - context7-websites-vale-sh
+---
+
+# Vale troubleshooting reference
+
+## Inline suppression syntax by format
+
+Markdown/MDX:
+```mdx
+{/* vale off */}
+This text will be ignored.
+{/* vale on */}
+```
+
+Org mode:
+```org
+# vale off
+This text will be ignored.
+# vale on
+```
+
+## Disabling a specific rule for specific matches
+
+Targets one rule and specific known-exception strings, then re-enables — the preferred fix for a recurring false positive on a specific term, since it keeps the rule active everywhere else:
+
+```mdx
+{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
+This is some text ACT test
+{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}
+```
+
+## Ignoring words in spell check
+
+The `spelling` check accepts an `ignore` list of external plain-text files, so project-specific terms don't need touching the dictionary:
+
+```yaml
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+ignore:
+  - ignore1.txt
+  - ignore2.txt
+```
+
+## Plain-text fallback
+
+If a file's syntax-aware parsing produces noisy or incorrect results (an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.
+
+## CI failing unexpectedly
+
+If a CI job fails solely because Vale returns a non-zero exit code on found alerts — not because the content is actually wrong for that pipeline stage — add `--no-exit` rather than suppressing the rule itself. This preserves the lint output while not gating the build on it.
+
+## pre-commit integration
+
+Vale ships a pre-commit hook definition. A typical setup runs `vale sync` once (with `pass_filenames: false`) plus the actual lint pass with CI-appropriate flags:
+
+```yaml
+repos:
+  - repo: https://github.com/errata-ai/vale
+    rev: 16d3a7f
+    hooks:
+      - id: vale
+        name: vale sync
+        pass_filenames: false
+        args: [sync]
+      - id: vale
+        args: [--output=line, --minAlertLevel=error]
+```
+
+## CI output for machine parsing
+
+```bash
+$ vale --output=JSON README.md
+```
+
+Use `--output=JSON` when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.