diff --git a/.gitignore b/.gitignore index 13872f7..ac2968e 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,4 @@ vectorlint.ini # .agent/ /.idea /npm -VECTORLINT.md .vectorlint/runs/ -docs diff --git a/docs/VECTORLINT.md b/docs/VECTORLINT.md new file mode 100644 index 0000000..9fe79f7 --- /dev/null +++ b/docs/VECTORLINT.md @@ -0,0 +1,77 @@ +# VectorLint example styling rules + +{/* This file is prepended to the system prompt for every VectorLint evaluation + This file defines global style instructions for all VectorLint evaluations. + VectorLint prepends its contents to the system prompt for every rule it runs. + Keep this file under ~800 tokens to avoid performance and cost issues. + Adapt the rules below to match your team's style guide. +*/} + +## Voice and tone + +- Write in active voice. Never use passive constructions. +- Use present tense throughout. +- Address the reader as "you." Do not use "the user," "the developer," or "one." +- Do not call any step or feature "simple," "easy," "straightforward," or "just." +- Do not use marketing language, superlatives, or exclamation marks. +- Do not use filler phrases: "please note," "at this time," "it is worth mentioning." +- Do not use weasel words when the correct answer is known: "might," "could," "generally," "typically." +- Do not attribute motivations or feelings to software. Systems execute; they do not think, want, or know. +- Do not use "execute" to refer to using software. Use "run," "deploy," or "instantiate" depending on the context. +- Contractions are acceptable and preferred when they sound natural. + +## Structure + +- Every page must open with a short description (1–2 sentences) stating what the page covers and who it is for. +- Do not duplicate the page title in the short description. +- Use sentence case for all headings. Capitalize only the first word and proper nouns. +- Do not end headings with punctuation. +- Do not skip heading levels. +- Do not stack two headings with no body content between them. +- Start procedure headings with an imperative verb, not a gerund. + +## Lists + +- Introduce every list with a complete sentence ending in a colon. +- Do not let a list complete a sentence that begins above it. +- All items in a list must follow parallel grammatical structure. +- Do not create a list with fewer than two items. Use prose instead. +- Do not nest lists more than two levels deep. + +## Procedures + +- Use numbered steps for sequential tasks. +- Write one action per step. +- Start each step with an imperative verb. +- List prerequisites before step one under a "Before you begin" or "Prerequisites" heading. +- Include a verification step when the outcome is not visually obvious. + +## Code and technical content + +- Put every command the reader must type in a code block, not inline prose. +- Include a language identifier on every fenced code block. +- Format command names, file names, and parameter names as inline code. +- Format UI element names in bold, not inline code. +- Use `` format for values the reader must replace. +- Explain every placeholder immediately after the code block. + +## Language + +- Define every acronym on first use: full term, then acronym in parentheses. +- After first use, use the acronym consistently. Do not alternate. +- Do not use "e.g.," "i.e.," or "etc." Use "for example," "that is," and "and so on." +- Spell out numbers zero through nine. Use numerals for 10 and above. +- Always use numerals for measurements, versions, and technical values. + +## Terminology + +- Use one term per concept. Do not introduce synonyms to avoid repetition. +- Use the official name of a product exactly as the project spells and capitalizes it. + +## Admonitions + +- Use admonitions sparingly. Do not use more than one per section. +- Keep admonition content to one or two sentences. +- Do not begin admonition content with the admonition type label ("Note:", "Warning:"). +- Use Warning only for risks of data loss, system failure, or security vulnerability. +- Use Tip only for optional techniques. Do not put required steps in a Tip. diff --git a/docs/best-practices.mdx b/docs/best-practices.mdx new file mode 100644 index 0000000..05c6ad8 --- /dev/null +++ b/docs/best-practices.mdx @@ -0,0 +1,140 @@ +--- +title: Best practices +description: Proven patterns for getting accurate, low-noise results from VectorLint across your content workflow. +--- + +These practices are drawn from the patterns that appear throughout the VectorLint documentation — consolidated here so you can apply them without reading every page first. + +## Start with VECTORLINT.md, not rule pack files + +Start with `VECTORLINT.md`. It requires no configuration, activates immediately, and brings your most important standards in plain language before you commit to structured prompts. + +After you run `VECTORLINT.md` against your content library and complete your first assessments, you can begin tuning the rules in 'VECTORLINT.md' based on your initial findings. This way, you'll have a sense of if you have styling gaps that warrant a dedicated rule pack file. + +## Keep VECTORLINT.md under 800 tokens + +VectorLint emits a warning at 4,000 tokens, but a practical target is *much* lower. Under 800 tokens leaves headroom for rule-specific prompts to add context without the combined system prompt becoming unwieldy. Long context degrades LLM precision and increases API costs on every evaluation. + +If your `VECTORLINT.md` is growing, that's usually a sign that some rules are specific enough to belong in a dedicated rule pack file instead. + +## Write specific prompts, not general ones + +The quality of VectorLint's findings is directly proportional to the specificity of your prompts. Vague prompts produce vague findings — or worse, inconsistent findings that vary by run. + +Instead of: +``` +Check if the writing is clear. +``` + +Write: +``` +You are a clarity evaluator for developer documentation. Flag sentences that: +1. Exceed 25 words +2. Use passive voice where active voice is possible +3. Contain filler phrases: "it is important to note", "please be aware", "in order to" +``` + +The second prompt gives the LLM a defined audience, measurable criteria, and specific examples. It will produce consistent, actionable findings. + +## Give rules domain context + +LLMs evaluate content relative to an implied standard. Make that standard explicit with a context block in your rule prompt. Tell the model who the audience is, what they value, and what good looks like for your specific content type. + +```markdown +## CONTEXT BANK + +**Audience**: Software engineers and DevOps practitioners who value: +- Technical precision over marketing language +- Practical examples over theory +- Direct answers without lengthy preambles +``` + +A grammar rule without context produces generic grammar findings. The same rule with a developer audience context produces findings calibrated to technical writing conventions. + +## Use weights that reflect real priorities + +In judge rules, weights are the single most important configuration decision. They determine which criteria actually control the final score. Treat them as a statement of your content team's values — not arbitrary numbers. + +```yaml +criteria: + - name: Technical Accuracy + weight: 40 # Factual errors erode user trust — this matters most + - name: Clarity + weight: 30 # Unclear docs generate support tickets + - name: Tone + weight: 20 # Important but recoverable in editing + - name: SEO + weight: 10 # Nice to have, never at the expense of the above +``` + +If everything has the same weight, nothing is prioritized. + +## Tier strictness by content type + +Not all content deserves the same quality bar. Apply strictness in proportion to how much a failure costs — measured in user trust, support load, or brand impact. + +```ini +# Customer-facing API docs — every error matters +[content/docs/**/*.md] +GrammarChecker.strictness=strict + +# Blog posts — quality matters, tone is flexible +[content/blog/**/*.md] +GrammarChecker.strictness=standard + +# Internal drafts — let writers write +[content/drafts/**/*.md] +RunRules= +``` + +Setting the same strictness everywhere produces either too much noise on low-stakes content or too little signal on high-stakes content. + +## Start permissive, tighten over time + +When rolling VectorLint out to a team for the first time, resist the urge to apply strict settings immediately. A workflow that generates too many findings on day one loses the team's trust before it earns it. + +1. Start with `CONFIDENCE_THRESHOLD=0.75` and `standard` strictness +2. Run against your existing content library and review findings as a team +3. Identify which findings are consistently useful vs. consistently dismissed +4. Raise strictness on your highest-stakes content first +5. Raise `CONFIDENCE_THRESHOLD` once your rules are stable + +The goal is a workflow where every finding is worth reading. That takes iteration. + +## Set a higher confidence threshold in CI than locally + +In CI, a false positive blocks a merge. Set `CONFIDENCE_THRESHOLD` higher in your CI environment than in local development so only the highest-confidence findings gate a merge. Lower-confidence candidates still surface locally where a writer can evaluate them in context. + +```bash +# Local development — catch more, review in context +CONFIDENCE_THRESHOLD=0.75 + +# CI environment — only high-confidence findings block merges +CONFIDENCE_THRESHOLD=0.85 +``` + +## Gate CI only on production-bound content + +Limit your CI workflow's `paths` filter to directories that actually ship to users. Checking drafts or work-in-progress in CI creates unnecessary friction and noise. + +```yaml +on: + pull_request: + paths: + - 'content/docs/**' + - 'content/api/**' +``` + +Drafts should have `RunRules=` in `.vectorlint.ini` — VectorLint skips them entirely and they never reach CI. + +## Validate new rules before raising strictness + +When you write a new rule, run it at `lenient` strictness and low `CONFIDENCE_THRESHOLD` first. Review everything it flags. Once you're confident the rule's coverage is correct and its false positive rate is acceptable, raise both settings to production levels. + +Skipping this step leads to rules that look correct on paper but produce noise in practice — which erodes team confidence in the entire workflow. + +## Next steps + +- [Tuning evaluation precision](/false-positive-tuning) — detailed guidance on CONFIDENCE_THRESHOLD and strictness +- [CI Integration](/ci-integration) — set up content quality gates in your pipeline +- [Customize style rules](/customize-style-rules) — write effective prompts for rule pack files diff --git a/docs/ci-integration.mdx b/docs/ci-integration.mdx new file mode 100644 index 0000000..0b34eec --- /dev/null +++ b/docs/ci-integration.mdx @@ -0,0 +1,160 @@ +--- +title: CI integration +description: Gate merges on content quality by running VectorLint in your CI pipeline. +--- + +VectorLint exits with a non-zero status code when it finds violations, making it a natural fit for CI pipelines. Add it as a pre-merge check and content that fails your quality thresholds never reaches production. + +## How it works in CI + +When VectorLint finds violations it exits with code `1`. When content passes all checks it exits with code `0`. Most CI systems treat a non-zero exit as a failed step and block the merge automatically — no additional configuration needed. + +| Exit code | Meaning | +|-----------|---------| +| `0` | All files passed — no violations found | +| `1` | One or more violations found | + +## GitHub Actions + +### Basic setup + +Add a workflow file at `.github/workflows/vectorlint.yml`: + +```yaml +name: Content quality check + +on: + pull_request: + paths: + - 'content/**/*.md' + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: lts/* + + - name: Install VectorLint + run: npm install -g vectorlint + + - name: Run content check + run: vectorlint content/**/*.md + env: + LLM_PROVIDER: openai + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + CONFIDENCE_THRESHOLD: 0.85 +``` + +The `paths` filter limits the workflow to runs where content files actually changed — it won't fire on code-only PRs. + +### Storing API keys + +Never commit API keys to your repository. Store them as GitHub Actions secrets: + +1. Go to your repository **Settings → Secrets and variables → Actions** +2. Add a new secret for each key (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) +3. Reference them in your workflow with `${{ secrets.SECRET_NAME }}` + +### Checking only changed files + +For large content libraries, checking every file on every PR is slow and expensive. Use `git diff` to check only the files changed in the PR: + +```yaml + - name: Get changed files + id: changed + run: | + echo "files=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep '\.md$' | tr '\n' ' ')" >> $GITHUB_OUTPUT + + - name: Run content check + if: steps.changed.outputs.files != '' + run: vectorlint ${{ steps.changed.outputs.files }} + env: + LLM_PROVIDER: openai + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} +``` + +## Recommended CI configuration + +CI environments should be stricter than local development. A finding a writer might dismiss in review becomes a merge blocker in CI — so surface only high-confidence violations. + +**Raise `CONFIDENCE_THRESHOLD` in CI.** Set it higher than your local default so only the most certain findings block a merge: + +```yaml +env: + CONFIDENCE_THRESHOLD: 0.85 +``` + +**Gate checks only on production-bound content.** Limit the workflow `paths` filter to directories that ship to users, not drafts or internal docs: + +```yaml +on: + pull_request: + paths: + - 'content/docs/**' + - 'content/api/**' +``` + +**Use strict strictness on gated content.** In your `.vectorlint.ini`, apply strict scoring to the files that CI checks: + +```ini +[content/docs/**/*.md] +RunRules=TechDocs +GrammarChecker.strictness=strict + +[content/drafts/**/*.md] +RunRules= +``` + +Drafts never reach CI — the empty `RunRules=` means VectorLint skips them entirely. + +## Other CI systems + +VectorLint works with any CI system that supports running shell commands. The pattern is the same: install VectorLint, set environment variables from secrets, run the check. + +**GitLab CI:** + +```yaml +content-quality: + image: node:lts + script: + - npm install -g vectorlint + - vectorlint content/docs/**/*.md + variables: + LLM_PROVIDER: openai + OPENAI_API_KEY: $OPENAI_API_KEY + rules: + - changes: + - content/**/*.md +``` + +**CircleCI:** + +```yaml +jobs: + content-check: + docker: + - image: cimg/node:lts + steps: + - checkout + - run: + name: Install VectorLint + command: npm install -g vectorlint + - run: + name: Run content check + command: vectorlint content/**/*.md + environment: + LLM_PROVIDER: openai +``` + +Store API keys in your CI system's secret or environment variable manager — never in the workflow file itself. + +## Next steps + +- [Tuning evaluation precision](/false-positive-tuning) — set `CONFIDENCE_THRESHOLD` and strictness for CI +- [Project Configuration](/project-config) — configure which files CI checks +- [CLI reference](/cli-reference) — full command and exit code reference diff --git a/docs/cli-reference.mdx b/docs/cli-reference.mdx new file mode 100644 index 0000000..febe11c --- /dev/null +++ b/docs/cli-reference.mdx @@ -0,0 +1,103 @@ +--- +title: CLI reference +description: Complete reference for the VectorLint command-line interface — commands, flags, and exit codes. +--- + +VectorLint runs from the command line. You invoke it against one or more files and it prints findings to standard output. This page is the complete reference for all commands, flags, and exit behavior. + +## Basic usage + +```bash +vectorlint [flags] [files...] +``` + +Run a check against one file: + +```bash +vectorlint doc.md +``` + +Run against multiple files or a glob pattern: + +```bash +vectorlint content/docs/**/*.md +``` + +## Commands + +### `vectorlint init` + +Initializes VectorLint in your project. Generates configuration files based on the mode you choose. + +```bash +vectorlint init +``` + +Creates two files: + +| File | Location | Purpose | +|------|----------|---------| +| `.vectorlint.ini` | Project root | File patterns, rule packs, strictness overrides | +| `config.toml` | `~/.vectorlint/` | LLM provider API keys | + +#### `--quick` flag + +```bash +vectorlint init --quick +``` + +Zero-config mode. Creates only a `VECTORLINT.md` file in your project root. VectorLint detects it automatically and creates a "Style Guide Compliance" rule from its contents — no `.vectorlint.ini` required. + +### `vectorlint --help` + +Prints available commands and flags. + +```bash +vectorlint --help +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--help` | Print help and exit | +| `--version` | Print the installed VectorLint version and exit | + +## Output + +VectorLint prints findings to standard output. Each finding includes the rule that triggered it, the location in the file, the specific violation, and a suggested fix. + +A file with no violations produces no output. + +## Exit codes + +| Code | Meaning | +|------|---------| +| `0` | No violations found — all files passed | +| `1` | One or more violations found | + +Exit codes make VectorLint suitable for CI pipelines. A non-zero exit blocks a merge when content fails quality checks. See [CI Integration](/ci-integration) for setup examples. + +## Environment variables + +VectorLint reads configuration from environment variables in addition to config files. Project-level `.env` values take precedence over the global `config.toml`. + +| Variable | Default | Description | +|----------|---------|-------------| +| `LLM_PROVIDER` | — | LLM provider to use: `openai`, `anthropic`, `gemini`, `azure` | +| `OPENAI_API_KEY` | — | API key for OpenAI | +| `ANTHROPIC_API_KEY` | — | API key for Anthropic | +| `GEMINI_API_KEY` | — | API key for Google Gemini | +| `AZURE_OPENAI_API_KEY` | — | API key for Azure OpenAI | +| `SEARCH_PROVIDER` | — | Search provider for `technical-accuracy` evaluator: `perplexity` | +| `PERPLEXITY_API_KEY` | — | API key for Perplexity search | +| `CONFIDENCE_THRESHOLD` | `0.75` | PAT pipeline confidence gate. Lower surfaces more findings; higher surfaces fewer. | + +For the full environment variable reference see [Environment variables](/env-variables). + +## Related + +- [Installation](/installation) — install VectorLint globally or run with npx +- [Configuration](/configuration) — configure VectorLint for your project +- [Tuning evaluation precision](/false-positive-tuning) — adjust `CONFIDENCE_THRESHOLD` and strictness +- [CI Integration](/ci-integration) — use exit codes to gate merges on content quality diff --git a/docs/configuration-schema.mdx b/docs/configuration-schema.mdx new file mode 100644 index 0000000..3ce62cb --- /dev/null +++ b/docs/configuration-schema.mdx @@ -0,0 +1,183 @@ +--- +title: Configuring your project +description: Set up file patterns, rule pack assignments, and quality thresholds in .vectorlint.ini. +--- + +VectorLint uses two configuration files with distinct responsibilities. `.vectorlint.ini` in your project root controls which rules run on which files, how strictly violations are scored, and the path to your custom rule packs. You store your large language model (LLM) provider credentials in `~/.vectorlint/config.toml`. For more information, see [Configuring LLM providers](/llm-providers). + +Run `vectorlint init` to generate both files with commented placeholders. + +## Global settings + +These settings go at the top of `.vectorlint.ini`, outside any file pattern section. + +| Setting | Default | Description | +|---|---|---| +| `RulesPath` | _(none)_ | Path to your custom rule packs directory. Subdirectories inside this path become available pack names. If omitted, only the bundled `VectorLint` preset is available. | +| `Concurrency` | `4` | Number of rule evaluations to run in parallel. Reduce this if you hit API rate limits. | +| `DefaultSeverity` | `warning` | Default severity for reported violations: `warning` or `error`. Individual rules can override this with their own `severity` frontmatter field. | + +```ini +# .vectorlint.ini + +RulesPath=.github/rules +Concurrency=4 +DefaultSeverity=warning +``` + +## File pattern sections + +File pattern sections map glob patterns to rule packs. VectorLint evaluates a file only if at least one pattern matches it. + +```ini +[**/*.md] +RunRules=Acme + +[**/*.mdx] +RunRules=Acme +``` + +### RunRules + +`RunRules` takes a comma-separated list of pack names to run on matching files. Pack names correspond to subdirectory names inside `RulesPath`. + +```ini +[content/docs/**/*.md] +RunRules=Acme, TechCorp +``` + +To explicitly skip a set of files, set `RunRules` to empty: + +```ini +[content/drafts/**/*.md] +RunRules= +``` + +### Using the bundled preset + +VectorLint includes a `VectorLint` preset containing rules for AI pattern detection, pseudo-advice, and repetition. You can use it without setting `RulesPath`: + +```ini +[**/*.md] +RunRules=VectorLint +``` +This is separate from the `VECTORLINT.md` file in which you write your style standards as plain-language instructions. + +## Cascading configuration + +When multiple patterns match the same file, VectorLint applies all of them — general patterns first, specific patterns second. Rule packs accumulate; settings override. + +```ini +# Applied first — all markdown files run GeneralRules at strictness 5 +[**/*.md] +RunRules=GeneralRules +Grammar.strictness=5 + +# Applied second — docs files also run TechDocs, strictness overrides to 9 +[content/docs/**/*.md] +RunRules=TechDocs +Grammar.strictness=9 +``` + +A file matching `content/docs/api.md` runs both `GeneralRules` and `TechDocs`, with a final strictness of `9`. + +## Strictness overrides + +Check rules score content based on error density. Strictness controls the penalty per percentage point of error density, letting you apply tighter standards to critical content without changing the rule itself. + +Set strictness per rule, per pattern: + +```ini +[content/docs/**/*.md] +RunRules=Acme +GrammarChecker.strictness=9 +TechnicalAccuracy.strictness=strict +``` + +### Strictness levels + +| Level | Value range | Penalty per 1% error density | +|---|---|---| +| Lenient | `1`–`3` or `lenient` | ~5 points | +| Standard | `4`–`7` or `standard` | ~10 points | +| Strict | `8`–`10` or `strict` | ~20 points | + +Use numeric values for precise control or named levels for readability. Both are valid: + +```ini +GrammarChecker.strictness=9 +GrammarChecker.strictness=strict +``` + +## Global style context (VECTORLINT.md) + +Place a `VECTORLINT.md` file in your project root to define style instructions that apply to every evaluation. VectorLint prepends its contents to the system prompt for every rule, automatically applying your tone, terminology, and baseline standards across all checks. + +Keep `VECTORLINT.md` concise. VectorLint emits a warning if the file exceeds 4,000 tokens, as large context blocks degrade evaluation performance and increase costs. + +### Zero-config mode + +If no `.vectorlint.ini` exists, VectorLint detects `VECTORLINT.md` and creates a synthetic rule from its contents automatically. This approach requires no additional configuration: + +```bash +vectorlint init --quick # creates VECTORLINT.md only +vectorlint doc.md +``` + +### Combined mode + +When `.vectorlint.ini` is present alongside `VECTORLINT.md`, the two work together. `VECTORLINT.md` sets the baseline context and rule pack files enforce specific, measurable criteria on top of it. + +## Confidence threshold + +VectorLint filters raw LLM candidates through gate checks before surfacing violations. The confidence threshold controls how aggressively this filter applies. + +Set it in your `.env` file or as an environment variable: + +```bash +CONFIDENCE_THRESHOLD=0.75 +``` + +| Value | Effect | +|---|---| +| Lower (for example `0.5`) | More findings surfaced — higher recall, more noise | +| Default (`0.75`) | Balanced precision and recall | +| Higher (for example `0.9`) | Fewer findings surfaced — higher precision, fewer false positives | + +Invalid values fall back to the default of `0.75`. + +## Complete example + +```ini +# .vectorlint.ini + +# Global settings +RulesPath=.github/rules +Concurrency=4 +DefaultSeverity=warning + +# All markdown files — run the Acme pack +[**/*.md] +RunRules=Acme +GrammarChecker.strictness=7 + +# MDX files +[**/*.mdx] +RunRules=Acme +GrammarChecker.strictness=7 + +# Technical docs — higher standards +[content/docs/**/*.md] +RunRules=Acme +GrammarChecker.strictness=9 +TechnicalAccuracy.threshold=9 + +# Marketing content — brand voice rules +[content/marketing/**/*.md] +RunRules=TechCorp +BrandVoice.strictness=8 + +# Drafts — skip all rules +[content/drafts/**/*.md] +RunRules= +``` diff --git a/docs/configuration.mdx b/docs/configuration.mdx new file mode 100644 index 0000000..4567a75 --- /dev/null +++ b/docs/configuration.mdx @@ -0,0 +1,92 @@ +--- +title: "Configuration overview" +description: "Understand VectorLint's configuration files and how they work together." +--- + +VectorLint is configured through four files. Running `vectorlint init` creates the first two automatically. + +| File | Location | Purpose | Required | +|------|----------|---------|----------| +| `VECTORLINT.md` | Project root | Global style instructions in plain language — prepended to every evaluation | Required for zero-config mode | +| `.vectorlint.ini` | Project root | File patterns, rule packs, strictness overrides | Required for rule packs and file-specific configuration | +| `config.toml` | `~/.vectorlint/` | LLM provider API keys — applies globally across projects | Always required | +| Rule pack files | `RulesPath` directory | Targeted LLM prompts for specific checks — for advanced content quality workflows | Optional | + +For more information about integrating your style guide into the `VECTORLINT.md` file, see [Your first style check](./initial-style-check). +For more information about rule pack files, see [Defining your style rules](./style-guide). + +--- + +## Initialize your project + +VectorLint provides two initialization modes depending on how much configuration you need. + +### Zero-config mode (fastest) + +If you want to check content against a style guide with no additional setup: + +```bash +vectorlint init --quick +``` + +This creates a `VECTORLINT.md` file in your project root where you paste your style guide. VectorLint automatically creates a "Style Guide Compliance" rule from it and evaluates your content against it. + +Run a check: + +```bash +vectorlint doc.md +``` + +### Full configuration + +For a comprehensive setup with custom rule packs and file-specific targets: + +```bash +vectorlint init +``` + +This creates both `.vectorlint.ini` and `~/.vectorlint/config.toml`. Edit them manually or follow the guides below. + +--- + +## Configuration guides + +Each file has its own reference page with complete field definitions, examples, and behavior details. + +- [LLM Providers](/llm-providers) — configure your LLM provider, search provider, and false-positive filtering threshold +- [Project Configuration](/project-config) — map file patterns to rule packs, set strictness overrides, and understand cascading behavior +- [Defining your style rules](/style-guide) — create `VECTORLINT.md` and write targeted rule pack files + +--- + +## Run a check + +Once your provider is configured, run a check against any Markdown file: + +```bash +vectorlint doc.md +``` + +VectorLint ships with a built-in preset containing rules for AI pattern detection and directness. The `init` command configures this automatically so you get useful output immediately. + +--- + +## Next steps + + + + Configure the model and API keys that power your evaluations. + + + Map files to rule packs and tune evaluation behavior. + + + Create VECTORLINT.md and write custom rule pack files. + + + Full reference for commands, flags, and exit codes. + + + Complete reference for all runtime configuration variables. + + diff --git a/docs/customize-style-rules.mdx b/docs/customize-style-rules.mdx new file mode 100644 index 0000000..bc39261 --- /dev/null +++ b/docs/customize-style-rules.mdx @@ -0,0 +1,124 @@ +--- +title: Customizing style rules +description: Write effective LLM prompts for your rule pack files and create targeted content quality checks. +--- + +This guide walks you through creating a rule pack file from scratch, wiring it to a file pattern, and writing prompts that produce accurate, low-noise results. By the end you'll have a working rule you can adapt for your own content standards. + +## Before you start + +You'll need a working VectorLint installation with an LLM provider configured. If you haven't done that yet, complete [Installation](/installation) and [Configuration](/configuration) first. + +## Step 1: Create your rules directory + +VectorLint looks for rule packs in the directory specified by `RulesPath` in `.vectorlint.ini`. Create the directory structure: + +```bash +mkdir -p .github/rules/MyTeam +``` + +This creates a rule pack called `MyTeam`. Pack names come from subdirectory names inside `RulesPath`. + +## Step 2: Write the rule file + +Create a new file at `.github/rules/MyTeam/grammar-checker.md`: + +```markdown +--- +id: GrammarChecker +name: Grammar Checker +evaluator: base +type: check +severity: error +--- + +Check this content for grammar issues, spelling errors, and punctuation mistakes. +Report any errors found with specific examples from the text. +``` + +That's a complete, working rule. The YAML frontmatter configures how VectorLint handles the result. The Markdown body is the prompt sent to the LLM. + +## Step 3: Configure .vectorlint.ini + +Open your `.vectorlint.ini` and add the `RulesPath` setting and a file pattern that runs your new pack: + +```ini +RulesPath=.github/rules + +[**/*.md] +RunRules=MyTeam +``` + +## Step 4: Run a check + +Point VectorLint at any Markdown file: + +```bash +vectorlint doc.md +``` + +VectorLint sends the file content to your LLM with the `GrammarChecker` prompt, filters the results through the PAT pipeline, and prints any violations with their location and suggested fix. + +A clean file produces no output and exits with status `0`. A file with violations prints each finding and exits with a non-zero status. + +## Step 5: Tune strictness (optional) + +By default, VectorLint uses standard strictness — a penalty of ~10 points per 1% error density. For technical documentation where accuracy matters more, raise it: + +```ini +[content/docs/**/*.md] +RunRules=MyTeam +GrammarChecker.strictness=strict +``` + +See [Project Configuration](/project-config) for the full strictness reference. + +## Writing effective prompts + +The Markdown body of your rule file is the prompt sent to the LLM. Specificity here directly determines evaluation quality — a vague prompt produces vague findings. + +**Be explicit about what you're looking for:** + +```markdown +# ❌ Vague +Check if the headline is good. + +# ✅ Specific +You are a headline evaluator for developer blog posts. Assess whether the headline: + +1. Clearly communicates a specific benefit to the reader +2. Uses natural, conversational language (avoid buzzwords like "leverage" or "unlock") +3. Creates curiosity without resorting to clickbait +``` + +**Give the LLM domain context:** + +```markdown +## CONTEXT BANK + +**Audience**: Software engineers, DevOps practitioners, and QA professionals who value: +- Technical precision over marketing language +- Practical examples over theory +- Direct answers over lengthy preambles +``` + +**Use meaningful weights** to reflect real-world importance. Scale them to signal what actually matters in your content workflow: + +```yaml +criteria: + - name: Technical Accuracy + id: TechnicalAccuracy + weight: 40 # Critical — factual errors erode trust + - name: Readability + id: Readability + weight: 30 # Important — but recoverable in editing + - name: SEO + id: SEO + weight: 10 # Nice to have +``` + +## Next steps + +- [Defining your style rules](/style-guide) — full reference for rule anatomy, evaluation modes, targeting, and examples +- [Project Configuration](/project-config) — control which rules run on which files +- [LLM Providers](/llm-providers) — switch providers or tune false-positive filtering diff --git a/docs/density-scoring.mdx b/docs/density-scoring.mdx new file mode 100644 index 0000000..7ae3b0f --- /dev/null +++ b/docs/density-scoring.mdx @@ -0,0 +1,8 @@ +--- +title: Density Scoring +description: This page is coming soon. +--- + + + This page is coming soon. Check back for updates, or follow the [VectorLint GitHub repository](https://github.com/TRocket-Labs/vectorlint) for the latest news. + diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..c3f300b --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,131 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "VectorLint", + "colors": { + "primary": "#7C3AED", + "light": "#A78BFA", + "dark": "#5B21B6" + }, + "favicon": "/favicon.svg", + "navigation": { + "tabs": [ + { + "tab": "Documentation", + "groups": [ + { + "group": "Overview", + "pages": [ + "introduction", + "use-cases", + "how-it-works" + ] + }, + { + "group": "Get started", + "pages": [ + "quickstart", + "installation", + "initial-style-check" + ] + }, + { + "group": "Configuration", + "pages": [ + "configuration", + "project-config", + "style-guide", + "customize-style-rules", + "llm-providers", + "presets" + ] + }, + { + "group": "Quality scoring", + "pages": [ + "quality-scoring", + "density-scoring", + "rubric-scoring" + ] + }, + { + "group": "For teams & organizations", + "pages": [ + "ci-integration", + "team-rule-packs", + "false-positive-tuning" + ] + }, + { + "group": "Best practices", + "pages": [ + "best-practices" + ] + } + ] + }, + { + "tab": "Reference", + "groups": [ + { + "group": "Reference", + "pages": [ + "cli-reference", + "configuration-schema", + "env-variables", + "frontmatter-fields", + "troubleshooting" + ] + } + ] + } + ], + "global": { + "anchors": [ + { + "anchor": "GitHub", + "href": "https://github.com/TRocket-Labs/vectorlint", + "icon": "github" + }, + { + "anchor": "npm", + "href": "https://www.npmjs.com/package/vectorlint", + "icon": "box" + } + ] + } + }, + "logo": { + "light": "/logo/logo.svg", + "dark": "/logo/logo.svg" + }, + "navbar": { + "links": [ + { + "label": "GitHub", + "href": "https://github.com/TRocket-Labs/vectorlint" + } + ], + "primary": { + "type": "button", + "label": "Get started", + "href": "https://www.npmjs.com/package/vectorlint" + } + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + "cursor", + "vscode" + ] + }, + "footer": { + "socials": { + "github": "https://github.com/TRocket-Labs/vectorlint" + } + } +} \ No newline at end of file diff --git a/docs/env-variables.mdx b/docs/env-variables.mdx new file mode 100644 index 0000000..20aced0 --- /dev/null +++ b/docs/env-variables.mdx @@ -0,0 +1,93 @@ +--- +title: Environment variables +description: Complete reference for all environment variables that configure VectorLint's runtime behavior. +--- + +VectorLint reads configuration from environment variables at runtime. You can set them in two places: + +- **`~/.vectorlint/config.toml`** — global defaults that apply across all projects +- **`.env` in your project root** — project-level overrides that take precedence over the global config + +In CI, pass them directly as pipeline environment variables or secrets. See [CI Integration](/ci-integration) for examples. + + + Never commit API keys to version control. Add `.env` to your `.gitignore`. + + +## LLM provider + +| Variable | Required | Description | +|----------|----------|-------------| +| `LLM_PROVIDER` | Yes | The LLM provider to use. Accepted values: `openai`, `anthropic`, `gemini`, `azure`. | +| `OPENAI_API_KEY` | If using OpenAI | API key for OpenAI. | +| `ANTHROPIC_API_KEY` | If using Anthropic | API key for Anthropic. | +| `GEMINI_API_KEY` | If using Gemini | API key for Google Gemini. | +| `AZURE_OPENAI_API_KEY` | If using Azure | API key for Azure OpenAI. | +| `AZURE_OPENAI_ENDPOINT` | If using Azure | Your Azure OpenAI resource endpoint URL. | +| `AZURE_OPENAI_DEPLOYMENT` | If using Azure | Your Azure OpenAI deployment name. | + +## Search provider + +Required only for rules that use the `technical-accuracy` evaluator. If not set, rules that depend on external lookup return reduced-confidence results. + +| Variable | Required | Description | +|----------|----------|-------------| +| `SEARCH_PROVIDER` | If using technical-accuracy | Search provider to use. Accepted value: `perplexity`. | +| `PERPLEXITY_API_KEY` | If using Perplexity | API key for Perplexity search. | + +## Evaluation behavior + +| Variable | Default | Description | +|----------|---------|-------------| +| `CONFIDENCE_THRESHOLD` | `0.75` | PAT pipeline confidence gate. Controls how strictly raw model candidates are filtered before surfacing violations. Accepted range: `0`–`1`. Invalid values fall back to `0.75`. | + +Lower values surface more findings (higher recall, more noise). Higher values surface fewer findings (higher precision, fewer false positives). See [Tuning evaluation precision](/false-positive-tuning) for guidance on when to adjust this. + +## Example configurations + +### OpenAI — global config.toml + +```toml +[env] +LLM_PROVIDER = "openai" +OPENAI_API_KEY = "sk-..." +``` + +### Anthropic — project .env + +```bash +LLM_PROVIDER=anthropic +ANTHROPIC_API_KEY=sk-ant-... +``` + +### With search provider + +```toml +[env] +LLM_PROVIDER = "openai" +OPENAI_API_KEY = "sk-..." +SEARCH_PROVIDER = "perplexity" +PERPLEXITY_API_KEY = "pplx-..." +``` + +### CI environment with higher confidence threshold + +```bash +LLM_PROVIDER=openai +OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }} +CONFIDENCE_THRESHOLD=0.85 +``` + +## Precedence + +When the same variable is set in multiple places, VectorLint resolves it in this order — highest precedence first: + +1. Project `.env` file +2. Global `~/.vectorlint/config.toml` +3. System environment variables + +## Related + +- [LLM Providers](/llm-providers) — configure your provider with full setup examples +- [CI Integration](/ci-integration) — pass environment variables securely in pipelines +- [Tuning evaluation precision](/false-positive-tuning) — when and how to adjust `CONFIDENCE_THRESHOLD` diff --git a/docs/false-positive-tuning.mdx b/docs/false-positive-tuning.mdx new file mode 100644 index 0000000..299d112 --- /dev/null +++ b/docs/false-positive-tuning.mdx @@ -0,0 +1,111 @@ +--- +title: Tuning evaluation precision +description: Use `CONFIDENCE_THRESHOLD` and strictness overrides together to reduce noise and get accurate findings across different content types. +--- + +VectorLint gives you two complementary levers for controlling evaluation precision. Used together, they let you calibrate how aggressively VectorLint surfaces findings — globally across your project, and per content type. + +- **`CONFIDENCE_THRESHOLD`** — controls how strictly the PAT pipeline filters raw model candidates before surfacing them. A global setting that applies to every evaluation. +- **Strictness overrides** — controls how harshly check rules score error density for specific file patterns. Set per content type in `.vectorlint.ini`. + +Understanding when to reach for each one is the key to a low-noise, high-signal workflow. + +## How the two levers differ + +`CONFIDENCE_THRESHOLD` operates at the **filtering stage** — it determines whether a candidate violation gets surfaced at all. Lower it and more candidates pass through. Raise it and only the highest-confidence findings appear. + +Strictness overrides operate at the **scoring stage** — they determine how heavily a violation is penalized once it's already been surfaced. Higher strictness means a given error density produces a lower score and triggers violations more readily. + +They're solving different problems. `CONFIDENCE_THRESHOLD` reduces noise from the model's judgment. Strictness controls how demanding your quality bar is for a given content type. + +## When to tune CONFIDENCE_THRESHOLD + +The default of `0.75` is a reasonable starting point. Adjust it when the balance between findings and noise isn't working for your team. + +```bash +CONFIDENCE_THRESHOLD=0.75 +``` + +| Value | Effect | When to use | +|-------|--------|-------------| +| Lower (e.g. `0.5`) | More findings — higher recall, more noise | Early-stage rule development, finding gaps in coverage | +| Default (`0.75`) | Balanced precision and recall | Most production workflows | +| Higher (e.g. `0.9`) | Fewer findings — higher precision, less noise | CI gates, customer-facing content, high-trust workflows | + +Set this in `~/.vectorlint/config.toml` for a global default, or in a project `.env` file to override it for a specific project. + + + When writing a new rule, temporarily lower `CONFIDENCE_THRESHOLD` to see everything the model flags. Once you've validated the rule's coverage, raise it back to filter out low-confidence candidates. + + +## When to tune strictness + +Different content types warrant different quality bars. A draft circulated internally doesn't need the same scrutiny as customer-facing API documentation. Strictness overrides in `.vectorlint.ini` let you set those bars independently. + +```ini +# Customer-facing docs — strict. Every error matters. +[content/docs/**/*.md] +RunRules=TechDocs +GrammarChecker.strictness=strict +TechnicalAccuracy.strictness=9 + +# Blog posts — standard. Quality matters, but tone is flexible. +[content/blog/**/*.md] +RunRules=TechDocs +GrammarChecker.strictness=standard + +# Marketing — brand voice is critical, grammar is secondary. +[content/marketing/**/*.md] +RunRules=TechCorp +BrandVoice.strictness=strict +GrammarChecker.strictness=lenient + +# Drafts — no checks. Let writers write. +[content/drafts/**/*.md] +RunRules= +``` + +| Level | Value | Penalty per 1% error density | Best for | +|-------|-------|------------------------------|----------| +| Lenient | `1`–`3` | ~5 points | Drafts, early-stage content | +| Standard | `4`–`7` | ~10 points | Blog posts, internal docs | +| Strict | `8`–`10` | ~20 points | Customer-facing docs, API reference | + +## Tuning for CI environments + +In CI, false positives block merges. A finding that a writer might reasonably dismiss becomes a pipeline failure that needs explaining. Two adjustments help: + +**Raise `CONFIDENCE_THRESHOLD` in CI.** Set it higher in your CI environment's `.env` than in local development. This means only the highest-confidence findings block a merge — lower-confidence candidates still get caught locally where a writer can evaluate them in context. + +```bash +# .env in CI environment +CONFIDENCE_THRESHOLD=0.85 +``` + +**Use strict patterns only on production-bound content.** Gate CI checks on the directories that actually ship, not on drafts or work-in-progress: + +```ini +# Only these files block CI +[content/docs/**/*.md] +RunRules=TechDocs +GrammarChecker.strictness=strict + +# These files are checked locally but don't gate CI +[content/drafts/**/*.md] +RunRules= +``` + +## A practical starting point for teams + +If you're rolling VectorLint out across a team for the first time, start permissive and tighten over time. A workflow that generates too many findings on day one loses the team's trust before it earns it. + +1. Start with `CONFIDENCE_THRESHOLD=0.75` and `standard` strictness across all content +2. Run against your existing content library and review the findings as a team +3. Raise strictness on your highest-stakes content types first +4. Raise `CONFIDENCE_THRESHOLD` once your rules are stable and reviewed + +## Next steps + +- [LLM Providers](/llm-providers) — set `CONFIDENCE_THRESHOLD` in your config +- [Project Configuration](/project-config) — configure strictness overrides per file pattern +- [CI Integration](/ci-integration) — gate merges on content quality diff --git a/docs/favicon.svg b/docs/favicon.svg new file mode 100644 index 0000000..d50ceed --- /dev/null +++ b/docs/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/docs/frontmatter-fields.mdx b/docs/frontmatter-fields.mdx new file mode 100644 index 0000000..82e7d93 --- /dev/null +++ b/docs/frontmatter-fields.mdx @@ -0,0 +1,143 @@ +--- +title: Frontmatter field reference +description: Complete reference for YAML frontmatter fields in VectorLint rule files. +--- + +Every VectorLint rule file begins with a YAML frontmatter block that controls how VectorLint runs the evaluation, handles the result, and reports violations. The Markdown body that follows is the prompt sent to the LLM. + +```markdown +--- +id: MyRule +name: My Rule +type: check +severity: error +--- + +Your LLM prompt goes here. +``` + +## Required fields + +| Field | Type | Description | +|---|---|---| +| `id` | string | Unique identifier for the rule. Used in CLI output and in `.vectorlint.ini` overrides. PascalCase recommended (e.g., `GrammarChecker`). | +| `name` | string | Human-readable display name shown in CLI output. | + +## Optional fields + +| Field | Default | Description | +|---|---|---| +| `specVersion` | _(none)_ | Rule spec version. Set to `1.0.0` for rules using the full judge schema. | +| `evaluator` | `base` | Evaluator type. Use `base` for standard rules. Use `technical-accuracy` for rules that verify factual claims against live web search (requires a search provider). | +| `type` | `check` | Evaluation mode. `check` finds specific, countable violations. `judge` scores content against weighted criteria on a 1–4 rubric. | +| `severity` | `warning` | How a failing result is reported. `error` causes a non-zero exit code; `warning` reports the issue without failing the run. | +| `evaluateAs` | `chunk` | Whether to evaluate content in sections (`chunk`) or as a single unit (`document`). Chunking is applied automatically to documents over 600 words. Set to `document` to disable chunking for a specific rule. | +| `target` | _(none)_ | Regex specification to extract and evaluate a specific portion of the content, such as the H1 headline. See [Target fields](#target-fields) below. | +| `criteria` | _(none)_ | Required when `type` is `judge`. Defines the scoring dimensions and their weights. See [Criteria fields](#criteria-fields) below. | + +## Target fields + +The `target` field narrows evaluation to a specific part of the document. It is an object with the following sub-fields: + +| Field | Type | Required | Description | +|---|---|---|---| +| `regex` | string | Yes | Regular expression pattern to match the target content. | +| `flags` | string | No | Regex flags (e.g., `"mu"` for multiline and Unicode). | +| `group` | number | No | Capture group index to extract. If omitted, the full match is used. | +| `required` | boolean | No | When `true`, a missing match immediately reports an `error` with the `suggestion` text and skips LLM evaluation. When `false` or omitted, a missing match causes VectorLint to evaluate the full document instead. | +| `suggestion` | string | No | Message shown when `required: true` and the pattern does not match. | + +**Example — targeting only the H1 headline:** + +```yaml +target: + regex: '^#\s+(.+)$' + flags: "mu" + group: 1 + required: true + suggestion: Add an H1 headline for the article. +``` + +## Criteria fields + +The `criteria` field is an array of criterion objects used with `type: judge`. Each criterion defines one scoring dimension. + +| Field | Type | Required | Description | +|---|---|---|---| +| `name` | string | Yes | Human-readable criterion name shown in CLI output. | +| `id` | string | Yes | Unique identifier for this criterion. PascalCase recommended (e.g., `TechnicalAccuracy`). Referenced in the Markdown body rubric as `# CriterionName `. | +| `weight` | number | No | Relative importance of this criterion in the weighted average. Higher values increase the criterion's influence on the final score. Defaults to `1`. | +| `target` | object | No | Criterion-specific content matching. Uses the same sub-fields as the top-level `target`. Overrides the rule-level target for this criterion only. | + +**Example — judge rule with two weighted criteria:** + +```yaml +criteria: + - name: Technical Accuracy + id: TechnicalAccuracy + weight: 40 + - name: Readability + id: Readability + weight: 30 +``` + +## Complete example + +The following rule uses all commonly-used fields. It targets the H1 headline, judges it against two criteria, and requires the headline to exist before evaluation runs. + +```markdown +--- +specVersion: 1.0.0 +evaluator: base +type: judge +id: HeadlineEvaluator +name: Headline Evaluator +severity: error +evaluateAs: document +target: + regex: '^#\s+(.+)$' + flags: "mu" + group: 1 + required: true + suggestion: Add an H1 headline for the article. +criteria: + - name: Value Communication + id: ValueCommunication + weight: 12 + - name: Curiosity Gap + id: CuriosityGap + weight: 2 +--- + +You are a headline evaluator for developer blog posts. + +## RUBRIC + +# Value Communication + +### Excellent +Specific, immediately appealing benefit clearly stated. + +### Good +Clear benefit but less specific impact. + +### Fair +Vague benefit implied but not stated. + +### Poor +No apparent benefit to the reader. + +# Curiosity Gap + +### Excellent +Creates genuine intrigue without being misleading. + +### Good +Mildly interesting, reader may continue. + +### Fair +Neutral — no curiosity created. + +### Poor +Actively off-putting or confusing. +``` diff --git a/docs/how-it-works.mdx b/docs/how-it-works.mdx new file mode 100644 index 0000000..93e42fc --- /dev/null +++ b/docs/how-it-works.mdx @@ -0,0 +1,65 @@ +--- +title: How it works +description: How VectorLint evaluates content using LLM-as-a-Judge, filtering, and two scoring methods. +--- + +VectorLint evaluates your content by sending it to a large language model (LLM) along with a structured prompt that defines your quality criteria. The LLM acts as a judge — reading your content, applying the criteria, and returning findings. VectorLint then filters those findings through a deterministic pipeline before surfacing violations in the CLI. + +If you haven't run your first check yet, start with the [Quickstart](/quickstart). This page is for understanding the architecture behind what you're running. + +## The evaluation pipeline + +Every time you run `vectorlint doc.md`, three things happen in sequence. + +### 1. Rule resolution + +VectorLint reads your `.vectorlint.ini` to determine which rule packs apply to the file. It loads those rule files, prepends the contents of `VECTORLINT.md` (if present) to each rule's system prompt, and assembles the evaluation context. + +If no `.vectorlint.ini` exists, VectorLint detects `VECTORLINT.md` and creates a synthetic "Style Guide Compliance" rule automatically. This is the zero-config path — the fastest way to get from nothing to a working evaluation without writing any rule pack files. + +### 2. LLM evaluation + +VectorLint sends your content to the configured LLM provider with each rule's prompt. Depending on the rule type, the model returns either: + +- **A list of specific violations** (check rules) — for countable errors like grammar mistakes or banned terms +- **A scored rubric** (judge rules) — for quality dimensions like tone, clarity, or technical accuracy rated on a 1–4 scale + +Rules run concurrently up to the `Concurrency` limit set in `.vectorlint.ini`. + +### 3. Filtering + +Raw model output contains noise — potential violations that don't hold up under scrutiny. VectorLint reduces false positives through a two-phase filtering process: + +1. **Candidate generation** — the model returns all potential violations, each tagged with required fields: rule support, exact evidence, context support, plausible non-violation, and fix quality. +2. **Deterministic surfacing** — VectorLint applies a strict filter and only surfaces violations that pass all required gates. + +The CLI output is intentionally stricter than raw model candidates with fewer results and higher confidence. + +You can tune how aggressively the filter operates with `CONFIDENCE_THRESHOLD` (default: `0.75`). Lower values surface more findings with higher recall; higher values surface fewer findings with higher precision. See [Configuring LLM providers](/llm-providers) for details. + +## Scoring + +VectorLint uses two scoring methods depending on the rule type. + +**Density-based scoring** (check rules) calculates error density, violations per 100 words. VectorLint weights a single error in a short document more heavily than the same error in a long one. This normalizes quality assessment across documents of any length. + +**Rubric-based scoring** (judge rules) normalizes the LLM's 1–4 rating to a 1–10 scale and computes a weighted average across all criteria. Criteria weights reflect your real-world priorities — technical accuracy might carry a weight of 40 while SEO carries a weight of 10. + +See [Quality scoring](/quality-scoring) for the full scoring reference. + +## Two ways to define quality + +VectorLint gives you two complementary tools for expressing your content standards: + +- **`VECTORLINT.md`** — plain-language style instructions that apply globally to every evaluation. The fastest path to useful output: no rule files, no configuration syntax, just plain English instructions that the LLM uses as context for every check. +- **Rule pack files** — structured LLM prompts for specific, measurable checks with weighted scoring criteria. Use these when you need reproducible, auditable results on a particular dimension of quality. + +The two work together: `VECTORLINT.md` sets the baseline context, and rule pack files enforce specific criteria on top of it. + +See [Defining your style rules](/style-guide) for how to create both. + +## Next steps + +- [Quickstart](/quickstart) — run your first evaluation in minutes +- [Defining your style rules](/style-guide) — create VECTORLINT.md and write custom rules +- [Configuring a project](/project-config) — map files to rule packs \ No newline at end of file diff --git a/docs/initial-style-check.mdx b/docs/initial-style-check.mdx new file mode 100644 index 0000000..2292cac --- /dev/null +++ b/docs/initial-style-check.mdx @@ -0,0 +1,73 @@ +--- +title: Running your first style check +description: Use VECTORLINT.md to run your first content evaluation without writing any rules. +--- + +The fastest way to get value from VectorLint is to create a `VECTORLINT.md` file in your project root. This is the zero-config path — no rule pack files, no `.vectorlint.ini` required. VectorLint detects the file automatically, creates a "Style Guide Compliance" rule from its contents, and evaluates your content against it. + +## Before you start + +You'll need a working VectorLint installation with an LLM provider configured. If you haven't done that yet, complete [Installation](/installation) and [Configuration](/configuration) first. + +## Step 1: Create your VECTORLINT.md + +Create a file called `VECTORLINT.md` in your project root. Write your style standards as plain-language instructions — short imperative rules grouped under headings. VectorLint passes this content directly to the LLM as context for every evaluation. + +Here's a minimal example to start from: + +```markdown +## Voice and tone + +- Write in second person. Address the reader as "you." +- Use active voice. Avoid passive constructions. +- Be direct. Remove filler phrases like "it is important to note that." + +## Terminology + +- Use "sign in" not "log in." +- Use "select" not "click" for UI actions. +- Avoid "easy," "simple," and "just" — these are subjective and dismissive. + +## Sentence structure + +- Keep sentences under 25 words. +- One idea per sentence. +- Spell out acronyms on first use. +``` + + + Keep `VECTORLINT.md` under 800 tokens. This leaves room for rule-specific context without approaching the 4,000-token warning threshold. + + +If your team already has a style guide, you don't need to write this by hand. See [Defining your style rules](/style-guide) for an extraction prompt that converts an existing style guide into a `VECTORLINT.md`-optimized file. + +## Step 2: Run a check + +Point VectorLint at any Markdown file: + +```bash +vectorlint doc.md +``` + +VectorLint reads your `VECTORLINT.md`, builds a compliance rule from it, sends your content to the LLM, and prints any violations. A clean file produces no output and exits with status `0`. A file with violations prints each finding with its location and a suggested fix. + +## Step 3: Iterate on your rules + +`VECTORLINT.md` is a living file. As you see what VectorLint flags — and what it misses — update the file to tighten or relax your standards. + +- **Too many false positives?** Make a rule more specific or remove it. +- **Missing a pattern?** Add a new rule under an existing heading or create a new one. +- **Terminology changing?** Update the Terminology section directly. + +Because `VECTORLINT.md` is plain language, anyone on your team can read and edit it without learning a configuration format. + +## Going further + +`VECTORLINT.md` handles broad, always-applicable standards well. It also supports creating custom rule pack files — targeted LLM prompts that enforce specific, measurable criteria that plain-language instructions can't capture precisely enough. + +For example, a `VECTORLINT.md` rule like "avoid passive voice" gives the LLM general guidance. A rule pack file with a structured prompt, scoring rubric, and audience context gives it precise, reproducible criteria with weighted scoring. + +When you're ready to go beyond `VECTORLINT.md`: + +- [Customize style rules](/customize-style-rules) — step-by-step guide to writing your first rule pack file and crafting effective prompts +- [Defining your style rules](/style-guide) — full reference for rule anatomy, evaluation modes, targeting, and examples diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..961bb1b --- /dev/null +++ b/docs/installation.mdx @@ -0,0 +1,58 @@ +--- +title: Installation +description: Install VectorLint globally or run it with npx. Covers Node.js requirements and verifying your installation. +--- + +## Before you begin + +VectorLint requires Node.js 18 or later. Node.js 22 LTS is recommended. If you need to install or update Node.js, use [nvm](https://github.com/nvm-sh/nvm) (recommended) or download directly from [nodejs.org](https://nodejs.org). + + +Installing VectorLint makes the CLI available, but the tool requires a configured LLM provider to evaluate content. If you run `vectorlint` against a file before completing provider configuration, you get no output and no error. After installing, complete [Configuring LLM providers](/llm-providers) before running your first check. + + +--- + +## Option 1: Global install + +Install VectorLint globally from npm: + +```bash +npm install -g vectorlint +``` + +Verify the installation: + +```bash +vectorlint --help +``` + +A global install makes the `vectorlint` command available from any directory on your machine. Use this option if you plan to run VectorLint regularly across multiple projects. + +For a full reference of commands and flags, see [CLI reference](/cli-reference). + +--- + +## Option 2: Run with npx + +Run VectorLint without installing it: + +```bash +npx vectorlint path/to/doc.md +``` + +With this option, you don't need to install or manage versions, since `npx` downloads and runs the latest version of VectorLint on demand. Use this option for one-off checks or to try VectorLint before committing to a global install. + +If you use npx regularly, pin a specific version to avoid unexpected behavior when VectorLint releases updates: + +```bash +npx vectorlint@2.5.0 path/to/doc.md +``` + +--- + +## Next steps + +- [Quickstart](/quickstart) — configure your LLM provider and run your first check end to end +- [Configuring LLM providers](/llm-providers) — set up your API key for OpenAI, Anthropic, Gemini, Azure OpenAI, or Amazon Bedrock +- [Using VECTORLINT.md](/initial-style-check) — start evaluating content without writing any rule pack files \ No newline at end of file diff --git a/docs/introduction.mdx b/docs/introduction.mdx new file mode 100644 index 0000000..02197ad --- /dev/null +++ b/docs/introduction.mdx @@ -0,0 +1,69 @@ +--- +title: "Introduction" +description: "VectorLint is a large language model (LLM)-based prose linter that enforces your style guide in one prompt." +--- + +## What is VectorLint? + +VectorLint is a command-line tool that evaluates and scores documentation using large language models (LLMs). Instead of regex patterns that can only catch surface-level issues, VectorLint uses an [LLM-as-a-Judge](https://en.wikipedia.org/wiki/LLM-as-a-Judge) approach to catch terminology misuse, technical inaccuracies, and style inconsistencies that require contextual understanding to detect. + +If you can write a prompt for it, you can lint it with VectorLint. + +## Why VectorLint exists + +Traditional prose linters like Vale work by matching text against fixed regex patterns and word lists. They catch what you explicitly tell them to catch — but they can't reason about meaning, context, or technical accuracy. + +VectorLint fills that gap. You define a rule once as a Markdown prompt, and the LLM applies it across your entire content library — scoring each document, surfacing specific violations, and explaining why each violation matters. + +This gives documentation teams something they haven't had before: a **shared, measurable definition of content quality** that scales across writers, repositories, and content types. + +## What you can check + + + + Catch outdated API references, incorrect command syntax, and factually wrong claims before they reach users. + + + Enforce tone, terminology, and voice consistently across all content — not just the pages you manually review. + + + Identify artificial writing patterns like formulaic transitions, buzzword overuse, and unnatural sentence structure. + + + Verify that content follows SEO best practices for headings, keyword usage, and metadata. + + + +## How scoring works + +VectorLint uses two scoring methods depending on the rule type: + +**Density-based scoring** is used for rules that count discrete violations (like a grammar checker). VectorLint calculates scores based on error density — errors per 100 words — so results are comparable across documents of any length. + +**Rubric-based scoring** is used for rules that measure quality on a spectrum (like tone or completeness). The LLM scores each criterion on a 1–4 scale, which VectorLint normalizes to a 1–10 scale for consistent reporting. + +## How false positives are reduced + +VectorLint filters raw LLM candidates through a series of gate checks before surfacing violations to help keep its output precise: + +1. **Candidate generation** — the LLM returns all potential violations, each with required gate-check fields: rule support, exact evidence, context support, plausible non-violation, and fix quality. +2. **Deterministic filtering** — VectorLint applies a strict filter and only surfaces violations that pass all required gates. + +VectorLint's output is intentionally stricter than raw model candidates; it reports only findings that pass all gates. You can tune how aggressively the pipeline filters findings to match your content workflow. See [Tuning evaluation precision](/false-positive-tuning). + +## Next steps + + + + Install VectorLint globally or run it with npx — no setup required. + + + Run your first content check in under five minutes. + + + Set up rule packs, file patterns, and LLM providers. + + + Write effective LLM prompts for your rule pack files to enforce your specific standards. + + diff --git a/docs/llm-providers.mdx b/docs/llm-providers.mdx new file mode 100644 index 0000000..90eecf0 --- /dev/null +++ b/docs/llm-providers.mdx @@ -0,0 +1,287 @@ +--- +title: Configuring LLM providers +description: Connect VectorLint to OpenAI, Anthropic, Azure OpenAI, Google Gemini, or Amazon Bedrock. +--- + +VectorLint sends your content to an LLM (Large Language Model) for evaluation. Configure a provider and supply credentials before running your first check. + +## Supported providers + +| Provider | `LLM_PROVIDER` value | Notes | +|---|---|---| +| OpenAI | `openai` | GPT-4o and other OpenAI models | +| Anthropic | `anthropic` | Claude Opus, Sonnet, and Haiku | +| Azure OpenAI | `azure-openai` | Azure-hosted OpenAI models | +| Google Gemini | `gemini` | Gemini Pro and other Gemini models | +| Amazon Bedrock | `amazon-bedrock` | Claude models via AWS Bedrock | + +## How VectorLint loads credentials + +VectorLint resolves credentials in this order. Later sources override earlier ones: + +1. Built-in defaults +2. Global config — `~/.vectorlint/config.toml` +3. Local `.env` file in your project root +4. Shell environment variables + +This means you can set a global default provider in `config.toml` and override it per project with a `.env` file, or override both with environment variables in Continuous Integration/Continuous Deployment (CI/CD). + +## Generate a configuration file + +Run `vectorlint init` to generate `~/.vectorlint/config.toml` with placeholder values for all supported providers. Fill in the key for the provider you want to use and leave the others blank. + +## OpenAI + +Get your API key at [platform.openai.com/api-keys](https://platform.openai.com/api-keys). + +**Global config** (`~/.vectorlint/config.toml`) + +```toml +[env] +LLM_PROVIDER = "openai" +OPENAI_API_KEY = "sk-..." +``` + +**Project `.env` file** + +```bash +LLM_PROVIDER=openai +OPENAI_API_KEY=sk-... +``` + +**Shell / CI environment variables** + +```bash +export LLM_PROVIDER=openai +export OPENAI_API_KEY=sk-... +``` + +## Anthropic + +Get your API key at [console.anthropic.com](https://console.anthropic.com/). + +**Global config** (`~/.vectorlint/config.toml`) + +```toml +[env] +LLM_PROVIDER = "anthropic" +ANTHROPIC_API_KEY = "sk-ant-..." +# Optional +ANTHROPIC_MODEL = "claude-haiku-4-5" +ANTHROPIC_MAX_TOKENS = "4096" +ANTHROPIC_TEMPERATURE = "0.2" +``` + +**Project `.env` file** + +```bash +LLM_PROVIDER=anthropic +ANTHROPIC_API_KEY=sk-ant-... +# Optional +ANTHROPIC_MODEL=claude-haiku-4-5 +ANTHROPIC_MAX_TOKENS=4096 +ANTHROPIC_TEMPERATURE=0.2 +``` + +**Shell / CI environment variables** + +```bash +export LLM_PROVIDER=anthropic +export ANTHROPIC_API_KEY=sk-ant-... +``` + +## Azure OpenAI + +In addition to the API key, Azure OpenAI requires your resource endpoint, deployment name, and API version. Find these in the [Azure portal](https://azure.microsoft.com/en-us/products/ai-services/openai-service) under your Azure OpenAI resource. + +**Global config** (`~/.vectorlint/config.toml`) + +```toml +[env] +LLM_PROVIDER = "azure-openai" +AZURE_OPENAI_API_KEY = "..." +AZURE_OPENAI_ENDPOINT = "https://your-resource.openai.azure.com" +AZURE_OPENAI_DEPLOYMENT_NAME = "your-deployment-name" +AZURE_OPENAI_API_VERSION = "2024-02-15-preview" +# Optional +AZURE_OPENAI_TEMPERATURE = "0.2" +``` + +**Project `.env` file** + +```bash +LLM_PROVIDER=azure-openai +AZURE_OPENAI_API_KEY=... +AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com +AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment-name +AZURE_OPENAI_API_VERSION=2024-02-15-preview +# Optional +AZURE_OPENAI_TEMPERATURE=0.2 +``` + +**Shell / CI environment variables** + +```bash +export LLM_PROVIDER=azure-openai +export AZURE_OPENAI_API_KEY=... +export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com +export AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment-name +export AZURE_OPENAI_API_VERSION=2024-02-15-preview +``` + +## Google Gemini + +Get your API key at [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey). + +**Global config** (`~/.vectorlint/config.toml`) + +```toml +[env] +LLM_PROVIDER = "gemini" +GEMINI_API_KEY = "..." +``` + +**Project `.env` file** + +```bash +LLM_PROVIDER=gemini +GEMINI_API_KEY=... +``` + +**Shell / CI environment variables** + +```bash +export LLM_PROVIDER=gemini +export GEMINI_API_KEY=... +``` + +## Amazon Bedrock + +VectorLint accesses Claude models through Amazon Bedrock. You can omit AWS credentials if your environment has an Identity and Access Management (IAM) role or if you've configured a credential profile in `~/.aws/credentials`. + +**Global config** (`~/.vectorlint/config.toml`) + +```toml +[env] +LLM_PROVIDER = "amazon-bedrock" +AWS_REGION = "us-east-1" +# Optional if using IAM roles or ~/.aws/credentials +AWS_ACCESS_KEY_ID = "..." +AWS_SECRET_ACCESS_KEY = "..." +# Optional +BEDROCK_MODEL = "global.anthropic.claude-sonnet-4-5-20250929-v1:0" +BEDROCK_TEMPERATURE = "0.2" +``` + +**Project `.env` file** + +```bash +LLM_PROVIDER=amazon-bedrock +AWS_REGION=us-east-1 +# Optional if using IAM roles or ~/.aws/credentials +AWS_ACCESS_KEY_ID=... +AWS_SECRET_ACCESS_KEY=... +# Optional +BEDROCK_MODEL=global.anthropic.claude-sonnet-4-5-20250929-v1:0 +BEDROCK_TEMPERATURE=0.2 +``` + +**Shell / Continuous Integration (CI) environment variables** + +```bash +export LLM_PROVIDER=amazon-bedrock +export AWS_REGION=us-east-1 +export AWS_ACCESS_KEY_ID=... +export AWS_SECRET_ACCESS_KEY=... +``` + + +If your environment already provides AWS credentials through an IAM role or `~/.aws/credentials`, you can omit AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. + + +## Search provider (optional) + +The `technical-accuracy` evaluator verifies factual claims against live web search. You need a separate search provider credential. VectorLint currently supports [Perplexity](https://www.perplexity.ai/) for this purpose. + +**Global config** (`~/.vectorlint/config.toml`) + +```toml +[env] +SEARCH_PROVIDER = "perplexity" +PERPLEXITY_API_KEY = "pplx-..." +``` + +**Project `.env` file** + +```bash +SEARCH_PROVIDER=perplexity +PERPLEXITY_API_KEY=pplx-... +``` + +You don't need a search provider for standard `base` evaluator rules. + +## Tracking LLM costs + +You can configure per-token pricing so VectorLint calculates and reports estimated costs after each run. Check your provider's pricing page for current values. + +**Global config** (`~/.vectorlint/config.toml`) + +```toml +[env] +INPUT_PRICE_PER_MILLION = "2.50" +OUTPUT_PRICE_PER_MILLION = "10.00" +``` + +**Project `.env` file** + +```bash +INPUT_PRICE_PER_MILLION=2.50 +OUTPUT_PRICE_PER_MILLION=10.00 +``` + +## Using VectorLint in CI/CD + +In GitHub Actions, store credentials as repository secrets and pass them as environment variables. Never hard-code API keys in workflow files. + +```yaml +name: Lint content + +on: [push, pull_request] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Run VectorLint + env: + LLM_PROVIDER: openai + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + run: npx vectorlint content/**/*.md +``` + +For other CI/CD systems, use the equivalent secret mechanism: GitLab CI variables, CircleCI contexts, or Jenkins credentials. + +## Security practices + +**Keep credentials out of version control.** Add `.env` and any local config files to `.gitignore`: + +``` +.env +.vectorlint.ini +``` + +**Use separate keys per project or team.** Project-scoped keys let you rotate more easily if compromised and give you granular cost tracking. + +**Rotate keys periodically.** Generate a new key in the provider dashboard, update your configuration, verify VectorLint still works, then delete the old key. + +## Troubleshooting + +**`Authentication failed` or `Invalid API key`** — Verify the key value is correct, confirm it hasn't expired, and check that your account has available credits. + +**`Unknown provider: xyz`** — Check that `LLM_PROVIDER` matches one of the supported values exactly: `openai`, `anthropic`, `azure-openai`, `gemini`, `amazon-bedrock`. The value is case-sensitive. + +**Configuration not loading** — Verify the global config is at `~/.vectorlint/config.toml` and the file is readable. Confirm the TOML syntax is valid. As a quick test, try passing the credentials as environment variables directly. + +**`Rate limit exceeded`** — Reduce the `Concurrency` setting in the `.vectorlint.ini` file in your project, upgrade your API tier with the provider, or switch to a provider with higher rate limits. diff --git a/docs/logo/dark.svg b/docs/logo/dark.svg new file mode 100644 index 0000000..54a338a --- /dev/null +++ b/docs/logo/dark.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/docs/logo/light.svg b/docs/logo/light.svg new file mode 100644 index 0000000..75fca1c --- /dev/null +++ b/docs/logo/light.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/docs/logo/logo.svg b/docs/logo/logo.svg new file mode 100644 index 0000000..b7ae5bf --- /dev/null +++ b/docs/logo/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/logo/vectorlint.png b/docs/logo/vectorlint.png new file mode 100644 index 0000000..7d1a31e Binary files /dev/null and b/docs/logo/vectorlint.png differ diff --git a/docs/presets.mdx b/docs/presets.mdx new file mode 100644 index 0000000..bb9b77d --- /dev/null +++ b/docs/presets.mdx @@ -0,0 +1,66 @@ +--- +title: Presets +description: Use VectorLint's built-in rule presets to start evaluating content without writing custom rules. +--- + +VectorLint ships with a built-in rule preset that activates automatically when you run `vectorlint init`. Presets give you immediate, useful output without requiring you to write any rules first. + +## The VectorLint preset + +The default preset includes rules for: + +- **AI pattern detection** — flags overused buzzwords, formulaic transitions, hollow openings, and excessive hedging that signal AI-generated writing +- **Directness** — identifies passive constructions, unnecessary qualifiers, and roundabout phrasing that weakens clarity + +These rules run against all Markdown files by default when the preset is active. + +## How presets are configured + +When you run `vectorlint init`, the generated `.vectorlint.ini` references the `VectorLint` preset by name: + +```ini +[**/*.md] +RunRules=VectorLint +``` + +Preset rules behave identically to custom rules — you can override their strictness, combine them with your own rule packs, or disable them for specific file patterns. + +## Combining presets with custom rules + +Run the built-in preset alongside your own pack by listing both in `RunRules`: + +```ini +[**/*.md] +RunRules=VectorLint, MyTeam +``` + +Files matching this pattern will run all VectorLint preset rules plus all rules in your `MyTeam` pack. + +## Disabling presets for specific patterns + +To skip preset rules on drafts or generated content: + +```ini +[**/*.md] +RunRules=VectorLint + +[content/drafts/**/*.md] +RunRules= +``` + +## Overriding preset strictness + +Tune how harshly a preset rule scores content using its rule ID: + +```ini +[content/docs/**/*.md] +RunRules=VectorLint +AIPatterns.strictness=strict +``` + +See [Project Configuration](/project-config) for the full strictness reference. + +## Next steps + +- [Defining your style rules](/style-guide) — write custom rules to enforce your specific standards +- [Project Configuration](/project-config) — control which rules run on which files diff --git a/docs/project-config.mdx b/docs/project-config.mdx new file mode 100644 index 0000000..e95656b --- /dev/null +++ b/docs/project-config.mdx @@ -0,0 +1,167 @@ +--- +title: Configuring a project +description: Map files to rule packs and tune evaluation behavior with .vectorlint.ini. +--- + +`.vectorlint.ini` is VectorLint's project configuration file. It lives in your project root and controls three things: global behavior settings, where VectorLint looks for custom rules, and which rule packs run on which files. + +Run `vectorlint init` to generate a starter file. You can edit it manually at any time. + +## Global Settings + +These settings apply to all evaluations in the project. + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `RulesPath` | string | _(none)_ | Root directory for custom rule packs. If omitted, only built-in presets are used. | +| `Concurrency` | integer | `4` | Number of evaluations to run in parallel. | +| `DefaultSeverity` | string | `warning` | Severity level for reported violations: `warning` or `error`. | + +```ini +# .vectorlint.ini + +RulesPath=.github/rules +Concurrency=4 +DefaultSeverity=warning +``` + +## File Pattern Sections + +Use `[glob/pattern]` sections to map file types to rule packs. Each section targets files matching the pattern and specifies which rules to run. + +```ini +[**/*.md] +RunRules=Acme + +[content/docs/**/*.md] +RunRules=Acme +GrammarChecker.strictness=9 +TechnicalAccuracy.threshold=8.0 + +[content/marketing/**/*.md] +RunRules=TechCorp +BrandVoice.strictness=8 + +[content/drafts/**/*.md] +RunRules= +``` + +### `RunRules` + +A comma-separated list of rule pack names. Pack names correspond to subdirectory names inside `RulesPath`. + +```ini +RunRules=Acme, TechDocs +``` + +Set `RunRules=` with no value to explicitly skip all rules for matching files (useful for drafts or generated content). + +## Rule Pack Directory Structure + +The `RulesPath` setting defines where VectorLint looks for rule packs. Each subdirectory becomes an available pack name. + +``` +project/ +├── .github/ +│ └── rules/ ← RulesPath +│ ├── Acme/ ← Pack: "Acme" +│ │ ├── grammar.md +│ │ └── style.md +│ └── TechCorp/ ← Pack: "TechCorp" +│ └── brand.md +└── .vectorlint.ini +``` + +Rules inside `Acme/` are available when you set `RunRules=Acme`. Nesting is supported — you can organize rules into subdirectories within a pack. + +## Cascading Configuration + +VectorLint applies configuration blocks from general to specific, similar to Vale's cascade behavior. All blocks that match a given file are applied; more specific patterns override settings from more general ones, and rule packs accumulate. + +```ini +# Applied first — general +[**/*.md] +RunRules=GeneralRules +Grammar.strictness=5 + +# Applied second — more specific +# Result: runs GeneralRules AND TechDocs; strictness is 9 (overrides 5) +[content/docs/**/*.md] +RunRules=TechDocs +Grammar.strictness=9 +``` + +**Specificity** is determined by path depth and wildcard count. `content/docs/**/*.md` is more specific than `**/*.md`. + +## Strictness Overrides + +You can tune how harshly individual check rules score content on a per-pattern basis. + +```ini +[pattern] +RuleID.strictness=value +``` + +Strictness controls the penalty weight applied to error density. Higher values penalize the same error rate more severely. + +| Level | Value | Penalty per 1% error density | Typical use | +|-------|-------|------------------------------|-------------| +| Lenient | `1`–`3` | ~5 points | Drafts | +| Standard | `4`–`7` | ~10 points | General content | +| Strict | `8`–`10` | ~20 points | Technical documentation | + +You can use named levels (`lenient`, `standard`, `strict`) or direct numeric multipliers: + +```ini +[content/docs/**/*.md] +RunRules=Acme +GrammarChecker.strictness=strict +TechnicalAccuracy.strictness=20 +``` + +## Complete Example + +```ini +# .vectorlint.ini + +RulesPath=.github/rules +Concurrency=4 +DefaultSeverity=warning + +# All markdown files — baseline checks +[**/*.md] +RunRules=Acme +GrammarChecker.strictness=5 + +# Technical docs — stricter standards +[content/docs/**/*.md] +RunRules=Acme +GrammarChecker.strictness=9 +TechnicalAccuracy.threshold=8.0 + +# Marketing — brand voice rules +[content/marketing/**/*.md] +RunRules=TechCorp +BrandVoice.strictness=8 + +# Drafts — skip all checks +[content/drafts/**/*.md] +RunRules= +``` + +## Global Style Guide (VECTORLINT.md) + +In addition to `.vectorlint.ini`, you can place a `VECTORLINT.md` file in your project root to define global style instructions in plain language. + +**Zero-config mode:** If no `.vectorlint.ini` exists, VectorLint automatically detects `VECTORLINT.md`, creates a synthetic "Style Guide Compliance" rule, and evaluates content against it. + +**Combined mode:** When `.vectorlint.ini` is present, the contents of `VECTORLINT.md` are prepended to the system prompt for every evaluation — making your global tone and terminology preferences active across all rules. + + +Keep `VECTORLINT.md` concise. VectorLint emits a warning if the file exceeds approximately 4,000 tokens, as very large contexts can degrade evaluation quality and increase API costs. + + +## Next Steps + +- [LLM Providers](/llm-providers) — configure the model that runs evaluations +- [Style Guide](/style-guide) — write custom rules for your content standards diff --git a/docs/quality-scoring.mdx b/docs/quality-scoring.mdx new file mode 100644 index 0000000..3c43f5a --- /dev/null +++ b/docs/quality-scoring.mdx @@ -0,0 +1,8 @@ +--- +title: Quality Scoring +description: This page is coming soon. +--- + + + This page is coming soon. Check back for updates, or follow the [VectorLint GitHub repository](https://github.com/TRocket-Labs/vectorlint) for the latest news. + diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx new file mode 100644 index 0000000..c6775b2 --- /dev/null +++ b/docs/quickstart.mdx @@ -0,0 +1,114 @@ +--- +title: Quickstart +description: Install VectorLint, configure your LLM provider, and run your first content check. +--- + +Set up VectorLint and run your first content evaluation in under ten minutes. You install VectorLint, add your style instructions, connect an LLM (Large Language Model) provider, and see real output on a file you own. + +## Before you begin + +VectorLint requires Node.js 18 or later. Node.js 22 LTS is recommended. If you need to install or update Node.js, use [nvm](https://github.com/nvm-sh/nvm) or download directly from [nodejs.org](https://nodejs.org). + +You will also need an API key for a supported LLM provider. VectorLint sends your content to the provider you configure for evaluation. Supported providers include: OpenAI, Anthropic, Google Gemini, Azure OpenAI, Amazon Bedrock. + + +VectorLint requires a configured LLM provider to produce output. Installing the package alone is not enough — if you skip provider configuration, running `vectorlint` against a file will return no results and no error. Complete Step 2 before running a check. + + +--- + +## Step 1: Install VectorLint + +Install VectorLint globally from npm: + +```bash +npm install -g vectorlint +``` + +Verify the installation: + +```bash +vectorlint --help +``` + +You can also run VectorLint without installing it using `npx vectorlint`. See [Installation](/installation) for details on both options. + +--- + +## Step 2: Configure your LLM provider + +Open `~/.vectorlint/config.toml` and add your provider and API key. This file is your global provider configuration and applies to all projects on your machine. + +For OpenAI: + +```toml +[env] +LLM_PROVIDER = "openai" +OPENAI_API_KEY = "sk-..." +``` + +For Anthropic: + +```toml +[env] +LLM_PROVIDER = "anthropic" +ANTHROPIC_API_KEY = "sk-ant-..." +``` + +You can also set provider values in a `.env` file in your project root. Project-level values take precedence over `config.toml`. For all supported providers and configuration options, see [Configuring LLM providers](/llm-providers). + +--- + +## Step 3: Create your VECTORLINT.md + +After you initialize VectorLint in your repository, the application generates a VECTORLINT.md file in your project root. After you copy your style standards as plain-language instructions into the file, VectorLint builds a "Style Guide Compliance" rule and applies it to your VectorLint evaluations. + +Run the quick-init command to create the file: + +```bash +npx vectorlint init --quick +``` + +Then open `VECTORLINT.md` and add your standards. A few clear instructions are enough to get meaningful output: + +```markdown +## Voice and tone + +- Write in second person. Address the reader as "you." +- Use active voice. Avoid passive constructions. +- Be direct. Remove filler phrases like "it is important to note that." + +## Terminology + +- Use "sign in" not "log in." +- Use "select" not "click" for UI actions. +- Avoid "easy," "simple," and "just" — these are subjective and dismissive. + +## Sentence structure + +- Keep sentences under 25 words. +- One idea per sentence. +- Spell out acronyms on first use. +``` + +You don't need a comprehensive style guide to start. Add rules incrementally as you learn what your rules catch and what they miss. + +--- + +## Step 4: Run a check + +Point VectorLint at any Markdown file in your project: + +```bash +vectorlint path/to/doc.md +``` + +VectorLint reads your `VECTORLINT.md`, evaluates the file against it, and prints findings in your terminal. If the file is clean, VectorLint produces no output and exits with status `0`. If the file has violations, VectorLint prints each finding with its location and a suggested fix. + +--- + +## Next steps + +- [Using VECTORLINT.md](/initial-style-check) — iterate on your style instructions and understand what makes an effective rule +- [Configuring LLM providers](/llm-providers) — full provider reference including Azure OpenAI, Google Gemini, and Amazon Bedrock +- [Configuring a project](/project-config) — set up rule packs and file pattern mapping for a full project workflow \ No newline at end of file diff --git a/docs/rubric-scoring.mdx b/docs/rubric-scoring.mdx new file mode 100644 index 0000000..b5c52e1 --- /dev/null +++ b/docs/rubric-scoring.mdx @@ -0,0 +1,8 @@ +--- +title: Rubric Scoring +description: This page is coming soon. +--- + + + This page is coming soon. Check back for updates, or follow the [VectorLint GitHub repository](https://github.com/TRocket-Labs/vectorlint) for the latest news. + diff --git a/docs/style-guide.mdx b/docs/style-guide.mdx new file mode 100644 index 0000000..1fcaccb --- /dev/null +++ b/docs/style-guide.mdx @@ -0,0 +1,281 @@ +--- +title: Defining your style rules +description: Set global style instructions and create targeted LLM prompts to evaluate content against your style guide, terminology, and content standards. +--- + +VectorLint gives you two ways to bring your style guide into evaluations. Understanding which to use and when to combine them is the starting point for any content quality workflow: + +- **`VECTORLINT.md` file**: the global style instructions in plain language. Create this file from your style guide and place it in your project root. VectorLint prepends its contents to the system prompt for every evaluation, making your tone, terminology, and baseline standards apply across all rules automatically. Use it for broad, always-applicable guidance. See [Project Configuration](/project-config) for details. + +- **Rule pack files**: the targeted LLM prompts for specific checks. Create these as separate Markdown files as described below. Each file is a structured prompt that instructs the LLM to evaluate content against one specific standard: grammar, headline quality, AI pattern detection, technical accuracy, and so on. Rules are organized into packs and mapped to file patterns in `.vectorlint.ini`. Rule pack files live in subdirectories under `RulesPath` — see [File Structure Reference](#file-structure-reference) below. + +If you can write a prompt for it, you can lint for it with VectorLint. + +## Creating your VECTORLINT.md + +Place a `VECTORLINT.md` file in your project root to define global style instructions that apply to every evaluation. VectorLint prepends its contents to the system prompt for every rule it runs. + +Keep this file concise. VectorLint emits a warning if the file exceeds approximately 4,000 tokens, as very large contexts can degrade performance and increase API costs. + +### Extract rules from an existing style guide + +If your team already has a style guide, use the following prompt with any capable LLM to convert it into a `VECTORLINT.md`-optimized file. Paste your full style guide after the prompt. + +``` +You are a technical writing rules extractor. Your job is to convert a +full technical writing style guide into a compact VECTORLINT.md file +suitable for use as a VectorLint global style guide. + +Rules for extraction: +- Output imperative rules only. No explanations, rationale, or examples. +- Group rules under short, plain-language headings. +- Remove all tables, comparison columns, governing references, and + checklists — extract only the actionable rules they contain. +- Remove any rule that is structural (document architecture, heading + levels) rather than evaluable at the sentence or paragraph level. +- Use plain markdown bullets. No bold, no nested lists beyond one level. +- Target output: under 600 words / ~800 tokens. +- Do not include a preamble or closing statement. + +Style guide to extract from: +[PASTE YOUR STYLE GUIDE HERE] +``` + + + Target your `VECTORLINT.md` file at under 800 tokens. This leaves room for rule-specific prompts without approaching the warning threshold. + + +To help you get started, the VectorLint docs repository includes an [example VECTORLINT.md](https://github.com/taz-mon/vectorlint-docs/blob/main/VECTORLINT.md) covering common technical writing rules that you can copy and adapt. + +## Creating rule pack files + +Rule pack files are optional Markdown files, each containing a targeted LLM prompt for a specific check. Unlike `VECTORLINT.md`, which sets broad context for every evaluation, rule pack files enforce precise, measurable criteria — grammar, headline quality, AI pattern detection, technical accuracy, and so on. You can create as many as your content workflow requires and organize them into packs mapped to specific file patterns in `.vectorlint.ini`. + +Each rule file has two parts: YAML frontmatter that configures how VectorLint handles the result, and a Markdown body that is the actual prompt sent to the LLM. + +## Rule Anatomy + +```markdown +--- +id: MyEval +name: My Content Evaluator +evaluator: base +type: check +severity: error +--- + +Your detailed instructions for the LLM go here. +``` + +### Required frontmatter fields + +| Field | Description | +|-------|-------------| +| `id` | Unique identifier used in CLI output and config overrides (PascalCase recommended) | +| `name` | Human-readable display name | + +### Optional frontmatter fields + +| Field | Default | Description | +|-------|---------|-------------| +| `evaluator` | `base` | Evaluator type. Use `base` for most rules; `technical-accuracy` for fact-checking rules that need search. | +| `type` | `check` | Evaluation mode: `check` or `judge`. See below. | +| `severity` | `warning` | How failures are reported: `error` or `warning`. | +| `evaluateAs` | `chunk` | Whether to evaluate content as a whole (`document`) or in sections (`chunk`). | +| `target` | _(none)_ | Regex to target a specific part of the content (e.g., only the H1 headline). | +| `criteria` | _(none)_ | Required for `judge` rules. Defines the scoring dimensions. | +| `specVersion` | _(none)_ | Rule spec version. Use `1.0.0`. | + +## Evaluation Modes + +VectorLint supports two evaluation modes, chosen with the `type` field. + +| Mode | `type` value | Best for | +|------|-------------|----------| +| Check | `check` | Finding specific, countable violations (grammar errors, banned terms) | +| Judge | `judge` | Measuring quality on a spectrum (clarity, tone, completeness) | + +### Check rules + +The LLM returns a list of specific violations. VectorLint scores the result using **error density** (violations per 100 words), so a single error in a short document weighs more than the same error in a long one. + +```markdown +--- +evaluator: base +type: check +id: GrammarChecker +name: Grammar Checker +severity: error +--- + +Check this content for grammar issues, spelling errors, and punctuation mistakes. +Report any errors found with specific examples. +``` + +**Scoring:** Start at 10. Each percentage point of error density deducts points according to the strictness level configured for this rule in `.vectorlint.ini`. A score below 10 triggers a violation at the configured severity. + +**Strictness levels** (set per-pattern in `.vectorlint.ini`): + +| Level | Penalty per 1% density | +|-------|------------------------| +| `lenient` (1–3) | ~5 points | +| `standard` (4–7) | ~10 points | +| `strict` (8–10) | ~20 points | + +### Judge rules + +The LLM scores content against multiple weighted criteria using a 1–4 rubric. VectorLint normalizes each score to a 1–10 scale and computes a weighted average. + +| LLM rating | Meaning | Normalized | +|------------|---------|------------| +| 4 | Excellent | 10.0 | +| 3 | Good | 7.0 | +| 2 | Fair | 4.0 | +| 1 | Poor | 1.0 | + +Define criteria in the frontmatter and expand each into a rubric section in the Markdown body: + +```markdown +--- +specVersion: 1.0.0 +evaluator: base +type: judge +id: HeadlineEvaluator +name: Headline Evaluator +severity: error +criteria: + - name: Value Communication + id: ValueCommunication + weight: 12 + - name: Curiosity Gap + id: CuriosityGap + weight: 2 +--- + +You are a headline evaluator for developer blog posts. + +## RUBRIC + +# Value Communication + +### Excellent +Specific, immediately appealing benefit clearly stated. + +### Good +Clear benefit but less specific impact. + +### Fair +Vague benefit implied but not stated. + +### Poor +No apparent benefit to the reader. + +# Curiosity Gap + +### Excellent +Creates genuine intrigue without being misleading. + +### Good +Mildly interesting, reader may continue. + +### Fair +Neutral — no curiosity created. + +### Poor +Actively off-putting or confusing. +``` + +## Targeting Specific Content + +The `target` field lets you evaluate a specific portion of a document — for example, only the H1 headline — rather than the full content. + +```yaml +target: + regex: '^#\s+(.+)$' # Match H1 headline + flags: "mu" # Multiline + Unicode + group: 1 # Capture group 1 (the headline text only) + required: true # Fail immediately if no match found + suggestion: Add an H1 headline for the article. +``` + +**When `required: true`:** If the pattern doesn't match, VectorLint reports an immediate `error` with the `suggestion` text, and skips LLM evaluation. + +**When `required: false` (or omitted):** If the pattern doesn't match, VectorLint evaluates the full document instead. + +## File Structure Reference + +``` +project/ +├── .github/ +│ └── rules/ ← RulesPath in .vectorlint.ini +│ ├── Acme/ ← Pack: "Acme" +│ │ ├── grammar-checker.md +│ │ ├── headline-evaluator.md +│ │ └── Technical/ ← Nested subdirectory (supported) +│ │ └── technical-accuracy.md +│ └── TechCorp/ ← Pack: "TechCorp" +│ └── brand-voice.md +└── .vectorlint.ini +``` + +To run the `Acme` pack on all Markdown files: + +```ini +[**/*.md] +RunRules=Acme +``` + +## Examples + +### AI Pattern Detector (Judge) + +```markdown +--- +specVersion: 1.0.0 +evaluator: base +type: judge +id: AIPatterns +name: AI Pattern Detector +severity: warning +criteria: + - name: Language Authenticity + id: LanguageAuthenticity + weight: 40 + - name: Structural Naturalness + id: StructuralNaturalness + weight: 30 +--- + +Detect AI-generated writing patterns in this content. + +## INSTRUCTION + +Scan for common AI patterns: + +1. **Overused buzzwords**: leverage, synergy, elevate, unlock, empower +2. **Formulaic transitions**: Moreover, Furthermore, In conclusion +3. **Hollow openings**: "In today's fast-paced world..." +4. **Excessive hedging**: "It's worth noting that...", "It's important to mention..." + +## RUBRIC + +# Language Authenticity + +### Excellent +Natural, human voice throughout. No AI patterns detected. + +### Good +Mostly natural. One or two minor patterns present. + +### Fair +Several AI patterns reduce authenticity. + +### Poor +Pervasive AI patterns throughout. +``` + +## Next Steps + +- [Customize style rules](/customize-style-rules) — learn how to write effective LLM prompts for your rule pack files +- [Project Configuration](/project-config) — assign rule packs to file patterns +- [LLM Providers](/llm-providers) — configure the model used for evaluations diff --git a/docs/team-rule-packs.mdx b/docs/team-rule-packs.mdx new file mode 100644 index 0000000..50cc7b9 --- /dev/null +++ b/docs/team-rule-packs.mdx @@ -0,0 +1,8 @@ +--- +title: Team Rule Packs +description: This page is coming soon. +--- + + + This page is coming soon. Check back for updates, or follow the [VectorLint GitHub repository](https://github.com/TRocket-Labs/vectorlint) for the latest news. + diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx new file mode 100644 index 0000000..677502d --- /dev/null +++ b/docs/troubleshooting.mdx @@ -0,0 +1,192 @@ +--- +title: Troubleshooting +description: Diagnose and fix common VectorLint issues with installation, configuration, API keys, and evaluation output. +--- + + + VectorLint's exact error message strings are not yet documented here. If you see an error not covered on this page, check the [VectorLint GitHub issues](https://github.com/TRocket-Labs/vectorlint/issues) or open a new one. + + +## Installation issues + +### VectorLint command not found after global install + +**Symptom:** Running `vectorlint` after `npm install -g vectorlint` returns "command not found." + +**Cause:** npm's global bin directory is not on your `PATH`. + +**Fix:** Find your npm global bin directory and add it to your `PATH`: + +```bash +npm bin -g +``` + +Add the output path to your shell profile (`.bashrc`, `.zshrc`, or equivalent): + +```bash +export PATH="$PATH:/path/from/npm/bin" +``` + +Restart your terminal and try again. + +--- + +### Node.js version error on install + +**Symptom:** npm returns an error referencing an unsupported Node.js version during install. + +**Cause:** VectorLint requires Node.js 18 or later. + +**Fix:** Check your current version: + +```bash +node --version +``` + +If it's below 18, upgrade using [nvm](https://github.com/nvm-sh/nvm): + +```bash +nvm install --lts +nvm use --lts +``` + +--- + +## API key and provider issues + +### No output — VectorLint runs but produces nothing + +**Symptom:** `vectorlint doc.md` completes silently with no findings and no errors. + +**Possible causes and fixes:** + +1. **`CONFIDENCE_THRESHOLD` is too high.** Lower it temporarily to see if the model is finding candidates that are being filtered out: + ```bash + CONFIDENCE_THRESHOLD=0.5 vectorlint doc.md + ``` + If findings appear, your threshold is filtering too aggressively. Adjust it in your config. + +2. **The file matches a pattern with `RunRules=` (empty).** Check your `.vectorlint.ini` for a pattern that matches the file and has no rules assigned — this is intentional skip behavior for drafts. Confirm the file path matches the pattern you expect. + +3. **The content genuinely passes.** If you've lowered the threshold and still see nothing, the content may actually meet your standards. Try a file you know has issues to confirm the rule is working. + +--- + +### Authentication error from LLM provider + +**Symptom:** VectorLint returns an authentication or authorization error when running a check. + +**Cause:** API key is missing, incorrect, or not being read from the right location. + +**Fix:** Verify the key is set and readable: + +```bash +# Check if the variable is set in your environment +echo $OPENAI_API_KEY +``` + +If empty, set it in your project `.env` file or `~/.vectorlint/config.toml`. Confirm the variable name matches exactly — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `AZURE_OPENAI_API_KEY` depending on your provider. + +Also confirm `LLM_PROVIDER` matches the key you've set: + +```toml +[env] +LLM_PROVIDER = "anthropic" +ANTHROPIC_API_KEY = "sk-ant-..." +``` + +See [Environment variables](/env-variables) for the full variable reference. + +--- + +### Search provider not working for TechnicalAccuracy rules + +**Symptom:** Rules using `evaluator: technical-accuracy` produce no findings or return an error about search. + +**Cause:** No search provider is configured. + +**Fix:** Add a search provider to your config: + +```toml +[env] +SEARCH_PROVIDER = "perplexity" +PERPLEXITY_API_KEY = "pplx-..." +``` + +Without a search provider, `technical-accuracy` evaluators cannot verify facts against external sources and will return reduced-confidence or no results. + +--- + +## Configuration issues + +### Rules not running on a file + +**Symptom:** A file you expect to be checked produces no output even though rules are configured. + +**Possible causes and fixes:** + +1. **Glob pattern doesn't match.** Test your pattern mentally against the file path. `**/*.md` matches any `.md` file in any subdirectory. `content/docs/**/*.md` only matches files under `content/docs/`. A file at `docs/api.md` would not match `content/docs/**/*.md`. + +2. **`RulesPath` not set or incorrect.** If you're using custom rule packs, confirm `RulesPath` in `.vectorlint.ini` points to the directory containing your pack subdirectories: + ```ini + RulesPath=.github/rules + ``` + +3. **Pack name doesn't match directory name.** `RunRules=Acme` looks for a subdirectory called `Acme` (case-sensitive) inside `RulesPath`. Confirm the directory exists and the name matches exactly. + +--- + +### VECTORLINT.md token warning + +**Symptom:** VectorLint emits a warning that `VECTORLINT.md` exceeds approximately 4,000 tokens. + +**Cause:** The file is too large to serve as reliable global context. Excessively large context degrades LLM precision and increases API costs. + +**Fix:** Trim `VECTORLINT.md` to under 800 tokens — the practical working target. Move specific or detailed rules into dedicated rule pack files where they can be applied selectively rather than globally. See [Defining your style rules](/style-guide) for the extraction prompt that converts a full style guide into a compact `VECTORLINT.md`. + +--- + +### Cascading configuration not behaving as expected + +**Symptom:** A file is running the wrong rules or using the wrong strictness settings. + +**Cause:** VectorLint applies all matching patterns from general to specific. More specific patterns override settings from general ones, but rule packs accumulate — a file can run rules from multiple patterns. + +**Fix:** Trace which patterns match your file path. For a file at `content/docs/api.md`, both `**/*.md` and `content/docs/**/*.md` match. The file will run rules from both patterns, with `content/docs/**/*.md` overriding any settings (like strictness) that conflict. See [Project Configuration](/project-config) for the full cascade reference. + +--- + +## CI issues + +### CI pipeline fails immediately with no findings output + +**Symptom:** The VectorLint step in CI exits with a non-zero code but prints no findings. + +**Possible causes and fixes:** + +1. **API key secret not passed to the job.** Confirm the secret is defined in your CI environment and referenced correctly in the workflow: + ```yaml + env: + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + ``` + +2. **Node.js version in CI is below 18.** Add an explicit setup step: + ```yaml + - uses: actions/setup-node@v4 + with: + node-version: lts/* + ``` + +3. **Glob pattern in the run command doesn't expand correctly.** Some CI shells don't expand globs the same way as your local shell. Quote the pattern or use `find`: + ```bash + find content/docs -name "*.md" | xargs vectorlint + ``` + +--- + +## Getting more help + +- [VectorLint GitHub issues](https://github.com/TRocket-Labs/vectorlint/issues) — search existing issues or open a new one +- [CLI reference](/cli-reference) — confirm command syntax and flags +- [Environment variables](/env-variables) — verify variable names and precedence +- [Project Configuration](/project-config) — debug `.vectorlint.ini` pattern matching diff --git a/docs/use-cases.mdx b/docs/use-cases.mdx new file mode 100644 index 0000000..84bddf7 --- /dev/null +++ b/docs/use-cases.mdx @@ -0,0 +1,91 @@ +--- +title: Use cases +description: Common ways teams use VectorLint to enforce content standards across documentation, marketing, and developer content. +--- + +VectorLint fits anywhere a team publishes written content at scale and needs consistent, measurable quality. These are the most common starting points; each one describes a problem, the path through the tool, and what you get at the end: + +## Enforce a style guide automatically + +**The problem:** Your style guide lives in a PDF or a wiki page. Writers read it once during onboarding and then drift. Manual review catches some issues but doesn't scale across dozens of files or multiple contributors. + +**The path:** Write your standards as plain-language instructions in `VECTORLINT.md`. VectorLint converts them into a "Style Guide Compliance" rule and runs it against every file, every time — no regex, no word lists, no manual review for comma usage or passive voice. + +If your team has a detailed guide, see [Defining your style rules](/style-guide) for an extraction prompt that converts it into a `VECTORLINT.md`-optimized file. For more targeted enforcement, write rule pack files that score specific criteria on a weighted rubric. + +**Who does this:** Technical writing teams, content operations teams, developer advocacy teams. + +--- + +## Catch AI-generated writing patterns + +**The problem:** Large language model (LLM)-assisted writing is now standard, but it produces recognizable patterns, such as hollow openings, overused buzzwords ("leverage," "unlock," "elevate"), formulaic transitions, and excessive hedging. These patterns erode reader trust before anyone notices what's happening. + +**The path:** VectorLint's built-in AI Pattern Detector rule flags these patterns before they reach readers. Add it to your rule pack for customer-facing content and tune the strictness level to match your team's voice — stricter for published docs, more lenient for internal drafts. + +For content-specific tuning, see [Customizing style rules](/customize-style-rules). + +**Who does this:** Developer relations, marketing, documentation teams publishing AI-assisted content. + +--- + +## Verify technical accuracy + +**The problem:** Outdated version numbers, deprecated API references, and incorrect command syntax are difficult category of errors to catch in manual review, because catching them requires domain expertise your reviewers may not have. + +**The path:** The `technical-accuracy` evaluator uses a search provider to check factual claims in your content against current external sources. Point it at your API reference pages or CLI documentation and it surfaces stale information before it ships. + +See [Defining your style rules](/style-guide) for how to configure a `technical-accuracy` rule. + +**Who does this:** Developer documentation teams, API reference authors, teams maintaining large technical content libraries. + +--- + +## Gate content quality in CI + +**The problem:** Teams can skip manual quality checks because the pipeline doesn't enforce it. + +**The path:** VectorLint exits with a non-zero status code on violations, making it a natural CI gate. Add it as a pre-merge step so content that falls below your quality threshold never reaches production. + +```yaml +# Example GitHub Actions step +- name: Lint documentation + run: vectorlint content/docs/**/*.md +``` + +For a complete CI setup including threshold configuration and failure modes, see [CI integration](/ci-integration). + +**Who does this:** Engineering teams treating docs as code, platform teams managing documentation infrastructure. + +--- + +## Apply different standards to different content types + +**The problem:** A draft blog post and a customer-facing API reference don't deserve the same scrutiny. Applying strict rules to everything creates noise; applying no rules to anything creates inconsistency. + +**The path:** VectorLint's cascading configuration lets you map different rule packs and strictness levels to different file patterns in a single `.vectorlint.ini`. Strict rules on published docs, standard rules on blog posts, nothing on drafts. + +```ini +[content/docs/**/*.md] +RunRules=TechDocs +GrammarChecker.strictness=9 + +[content/blog/**/*.md] +RunRules=TechDocs +GrammarChecker.strictness=5 + +[content/drafts/**/*.md] +RunRules= +``` + +See [Configuring a project](/project-config) for the full configuration reference. + +**Who does this:** Content teams with multiple publication channels and different quality expectations per channel. + +--- + +## Next steps + +- [Quickstart](/quickstart) — run your first evaluation in under ten minutes +- [How it works](/how-it-works) — understand the evaluation pipeline, PAT filtering, and scoring +- [Defining your style rules](/style-guide) — create VECTORLINT.md and write custom rules \ No newline at end of file