docs(kyberforge): add vale.sh research docs

Prep work for issue #84 - gathers Vale (vale.sh) config, styles/rules,
CLI, installation, and troubleshooting reference material into
plugins/kyberforge/docs/research/docs/vale/ alongside the existing
research topics.

Refs #84

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/kyberforge/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/kyberforge/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/kyberforge/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/kyberforge/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/kyberforge/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/kyberforge/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/kyberforge/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.