From 210b19261366d381c4dc33602f35a707f77959ff Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sat, 8 Aug 2026 19:38:14 +0000
Subject: [PATCH] docs(lint): add docs index for Vale research docs

plugins/lint/docs/research/docs/vale/ had no top-level index pointing
into it, unlike plugins/kyberforge/docs/README.md which indexes its
own research directories. Add plugins/lint/docs/README.md mirroring
that convention: one line per file describing what it covers, plus a
provenance note tying the directory back to plugins/lint/sources.md
and the vale-config/vale-run skills that consume it.

Closes out a follow-up item from PR #85's review.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 plugins/lint/docs/README.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 plugins/lint/docs/README.md

diff --git a/plugins/lint/docs/README.md b/plugins/lint/docs/README.md
new file mode 100644
index 0000000..371f066
--- /dev/null
+++ b/plugins/lint/docs/README.md
@@ -0,0 +1,27 @@
+# docs/
+
+Plugin documentation. Not read automatically by Claude Code or GitHub Copilot CLI — reference specific files from skill bodies or agent prompts as needed.
+
+## research/
+
+Upstream reference material gathered during skill authoring. Not shipped with the plugin — used at development time only.
+
+| Path | Purpose |
+|------|---------|
+| `research/docs/vale/` | Vale documentation (vale.sh), gathered while authoring `vale-config`/`vale-run` — see below |
+
+### research/docs/vale/
+
+| File | Covers |
+|------|--------|
+| `overview.md` | What Vale is; the style/rule/check configuration model; the built-in `Vale` style's four rules; styles directory layout |
+| `installation.md` | Installing Vale via OS package managers (Homebrew, Snap, Chocolatey) and Docker |
+| `configuration.md` | `.vale.ini` structure — global, `[formats]`, and per-glob sections |
+| `cli-reference.md` | Core invocation and key subcommands/flags (`vale sync`, `vale ls-config`, etc.) |
+| `examples.md` | Walkthroughs — project initialization, typical `.vale.ini` configs |
+| `troubleshooting.md` | Suppressing false positives via inline markup (format-specific `vale off`/`vale on` syntax, spelling ignore lists) |
+| `sources.md` | Provenance record for this directory — source URL, description, and which files above were extracted from it |
+
+Each file's frontmatter carries a `source_keys` entry keyed to the same provenance record. The plugin-level provenance file, `plugins/lint/sources.md`, cross-references this directory from the `context7-websites-vale-sh` entry and lists the agents/skills whose content drew on it.
+
+`vale-config` and `vale-run` are the skills that consume this research — read the relevant file here before changing either skill's Vale-facing behavior.