docs: version 0.46.0 docs (#1322)

* docs: version 0.46.0 docs and update site data

* docs: pin versioned source links to release tags

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: avifenesh

.github/workflows/release.yml

@@ -592,6 +592,50 @@ jobs:
       - name: Cut versioned docs snapshot
         run: npm --prefix website run version:cut -- "${{ steps.version.outputs.version }}"
 
+      - name: Pin versioned docs links to the release tag
+        run: |
+          set -euo pipefail
+          VERSION="${{ steps.version.outputs.version }}"
+          SNAPSHOT="website/versioned_docs/version-${VERSION}"
+          python3 - "$SNAPSHOT" "$VERSION" <<'PY'
+          from pathlib import Path
+          import sys
+
+          snapshot = Path(sys.argv[1])
+          version = sys.argv[2]
+          replacements = {
+              "https://github.com/agent-sh/agnix/blob/main/":
+                  f"https://github.com/agent-sh/agnix/blob/v{version}/",
+              "https://github.com/agent-sh/agnix/tree/main/":
+                  f"https://github.com/agent-sh/agnix/tree/v{version}/",
+          }
+
+          changed = 0
+          for path in snapshot.rglob("*.md"):
+              content = path.read_text(encoding="utf-8")
+              pinned = content
+              for moving, tagged in replacements.items():
+                  pinned = pinned.replace(moving, tagged)
+              if pinned != content:
+                  path.write_text(pinned, encoding="utf-8")
+                  changed += 1
+
+          remaining = [
+              str(path)
+              for path in snapshot.rglob("*.md")
+              if any(
+                  moving in path.read_text(encoding="utf-8")
+                  for moving in replacements
+              )
+          ]
+          if remaining:
+              raise SystemExit(
+                  "Versioned docs still contain moving repository links: "
+                  + ", ".join(remaining)
+              )
+          print(f"Pinned repository links in {changed} versioned docs files")
+          PY
+
       - name: Update lastVersion in Docusaurus config
         run: |
           set -euo pipefail

tests/release_workflow.rs

@@ -1,4 +1,5 @@
 use std::fs;
+use std::path::PathBuf;
 
 #[test]
 fn release_publish_jobs_are_gated_by_tests() {
@@ -105,6 +106,72 @@ fn release_workflow_scopes_attestation_and_release_permissions() {
     );
 }
 
+#[test]
+fn release_workflow_pins_latest_versioned_docs_to_the_release_tag() {
+    let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let workflow = fs::read_to_string(root.join(".github/workflows/release.yml"))
+        .expect("failed to read release workflow")
+        .replace("\r\n", "\n");
+
+    assert!(
+        workflow.contains("- name: Pin versioned docs links to the release tag"),
+        "release workflow must pin repository links after cutting a docs snapshot"
+    );
+    assert!(
+        workflow.contains("agnix/blob/v{version}/") && workflow.contains("agnix/tree/v{version}/"),
+        "release workflow must retarget both file and directory links"
+    );
+
+    let versions: Vec<String> = serde_json::from_str(
+        &fs::read_to_string(root.join("website/versions.json"))
+            .expect("failed to read docs versions"),
+    )
+    .expect("website/versions.json must contain a JSON string array");
+    let latest = versions
+        .first()
+        .expect("docs must contain a latest version");
+    let snapshot = root.join(format!("website/versioned_docs/version-{latest}"));
+    let moving_links = [
+        "https://github.com/agent-sh/agnix/blob/main/",
+        "https://github.com/agent-sh/agnix/tree/main/",
+    ];
+    let pinned_links = [
+        format!("https://github.com/agent-sh/agnix/blob/v{latest}/"),
+        format!("https://github.com/agent-sh/agnix/tree/v{latest}/"),
+    ];
+    let mut stack = vec![snapshot];
+    let mut pinned_link_count = 0;
+
+    while let Some(path) = stack.pop() {
+        for entry in fs::read_dir(&path)
+            .unwrap_or_else(|error| panic!("failed to read {}: {error}", path.display()))
+        {
+            let entry = entry.expect("failed to read versioned docs entry");
+            let path = entry.path();
+            if path.is_dir() {
+                stack.push(path);
+            } else if path.extension().is_some_and(|extension| extension == "md") {
+                let content = fs::read_to_string(&path)
+                    .unwrap_or_else(|error| panic!("failed to read {}: {error}", path.display()));
+                assert!(
+                    moving_links.iter().all(|link| !content.contains(link)),
+                    "{} contains a repository link to moving main",
+                    path.display()
+                );
+                pinned_link_count += pinned_links
+                    .iter()
+                    .filter(|link| content.contains(link.as_str()))
+                    .count();
+            }
+        }
+    }
+
+    assert!(
+        pinned_link_count > 0,
+        "latest versioned docs must contain release-tagged repository links"
+    );
+}
+
 #[test]
 fn action_download_script_verifies_release_checksum() {
     let root = env!("CARGO_MANIFEST_DIR");

website/docusaurus.config.js

@@ -80,7 +80,7 @@ const config = {
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl: 'https://github.com/agent-sh/agnix/tree/main/website/',
           showLastUpdateTime: true,
-          lastVersion: '0.45.0',
+          lastVersion: '0.46.0',
           ...(includedDocVersions ? { onlyIncludeVersions: includedDocVersions } : {}),
           versions: {
             current: {

website/versioned_docs/version-0.46.0/api-reference.md

@@ -0,0 +1,88 @@
+---
+title: API Reference
+description: "agnix CLI flags, output formats, MCP server tools, and LSP capabilities."
+---
+
+# API Reference
+
+## CLI
+
+```bash
+agnix [OPTIONS] [PATH]
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `[PATH]` | Directory or file to validate (default: `.`) |
+| `--target <TOOL>` | Single tool focus (`generic`, `claude-code`, `cursor`, `codex`, `kiro`) |
+| `--fix` | Apply HIGH and MEDIUM confidence fixes |
+| `--dry-run` | Preview fixes without modifying files |
+| `--fix-safe` | Apply only HIGH confidence fixes |
+| `--fix-unsafe` | Apply all fixes, including LOW confidence fixes |
+| `--show-fixes` | Show proposed fix diffs in text output |
+| `--format <FMT>` | Output format: `text` (default), `json`, `sarif` |
+| `--strict` | Treat warnings as errors (exit code 1) |
+| `--config <PATH>` | Config file path (default: `.agnix.toml`) |
+| `--watch`, `-w` | Watch mode - re-validate on file changes |
+| `--locale <LOCALE>` | Set output locale, e.g. `en`, `es`, `zh-CN` |
+| `--list-locales` | List supported locales and exit |
+| `--max-files <N>` | Maximum number of files to validate |
+| `--verbose`, `-v` | Verbose output |
+| `--version` | Print version |
+| `--help` | Print help |
+
+### Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `agnix validate [PATH]` | Validate agent configs explicitly |
+| `agnix init` | Initialize a config file |
+| `agnix eval <FILE>` | Evaluate rule efficacy against labeled test cases |
+| `agnix schema [--output FILE] [--fix]` | Output or regenerate JSON Schema for `.agnix.toml` |
+| `agnix tools check` | Check configured tool versions |
+| `agnix tools detect` | Detect installed tool versions |
+| `agnix telemetry <status\|enable\|disable>` | Manage telemetry settings |
+
+### Output formats
+
+- **text** - Human-readable terminal output with colors
+- **json** - Machine-readable JSON object with diagnostics and summary metadata (e.g. version, files_checked, diagnostics, summary, category, rule_severity, applies_to_tool)
+- **sarif** - SARIF format for GitHub Code Scanning integration
+
+## MCP server
+
+```bash
+cargo install agnix-mcp
+agnix-mcp
+```
+
+The MCP server exposes these tools:
+
+| Tool | Description |
+|------|-------------|
+| `validate_file` | Validate a single configuration file |
+| `validate_project` | Validate all config files in a project |
+| `get_rules` | List all available validation rules |
+| `get_rule_docs` | Get documentation for a specific rule |
+
+## LSP server
+
+```bash
+cargo install agnix-lsp
+agnix-lsp
+```
+
+Supported LSP capabilities:
+
+- `textDocument/publishDiagnostics` - real-time validation
+- `textDocument/codeAction` - auto-fix suggestions
+- `textDocument/hover` - rule documentation on hover
+- `workspace/didChangeConfiguration` - runtime config updates
+- `workspace/executeCommand` - project-level validation (`agnix.validateProjectRules` command)
+
+## References
+
+- [SPEC.md](https://github.com/agent-sh/agnix/blob/v0.46.0/SPEC.md) - full technical specification
+- [MCP Protocol](https://modelcontextprotocol.io) - MCP specification

website/versioned_docs/version-0.46.0/configuration.md

@@ -0,0 +1,63 @@
+---
+title: Configuration
+description: "Configure agnix with .agnix.toml - target tools, disable rules, set output format, and more."
+---
+
+# Configuration
+
+agnix works with zero configuration. To customize, add `.agnix.toml` to your project root.
+
+## Example
+
+```toml
+target = "ClaudeCode"
+tools = ["claude-code"]
+max_files_to_validate = 10000
+locale = "en"
+
+[rules]
+disabled_rules = []
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `target` | string | `Generic` | Legacy single tool focus: `Generic`, `ClaudeCode`, `Cursor`, `Codex`, `Kiro` |
+| `tools` | string[] | `[]` | Multi-tool targeting. Overrides `target`. Use values like `claude-code`, `cursor`, `codex`, `kiro`, `github-copilot`, `cline`, `opencode`, `gemini-cli`, `amp`, `roo-code`, `windsurf`, `generic`. |
+| `severity` | string | `Warning` | Minimum severity level: `Warning`, `Error`, or `Info` |
+| `max_files_to_validate` | int | `10000` | Maximum files to scan |
+| `locale` | string | `"en"` | Output locale |
+| `[rules].disabled_rules` | string[] | `[]` | Rule IDs to skip (e.g. `["CC-MEM-005"]`) |
+| `[rules].disabled_validators` | string[] | `[]` | Validator names to skip |
+| `[files]` | table | default excludes | Include or exclude non-standard files |
+| `[[overrides]]` | table array | `[]` | Per-file disabled rule overrides |
+
+## CLI flags
+
+CLI flags override `.agnix.toml` values:
+
+```bash
+# Target a specific tool
+agnix --target cursor .
+
+# Apply fixes
+agnix --fix .
+
+# JSON output for CI
+agnix --format json .
+
+# SARIF output for GitHub Code Scanning
+agnix --format sarif .
+
+# Strict mode
+agnix --strict .
+```
+
+`--strict`, `--fix`, `--fix-safe`, `--fix-unsafe`, `--dry-run`, `--show-fixes`, and `--format` are CLI flags, not `.agnix.toml` keys.
+
+## Full reference
+
+For the complete configuration specification, see
+[docs/CONFIGURATION.md](https://github.com/agent-sh/agnix/blob/v0.46.0/docs/CONFIGURATION.md)
+in the repository.

website/versioned_docs/version-0.46.0/contributing.md

@@ -0,0 +1,49 @@
+---
+title: Contributing
+description: "How to contribute to agnix - report bugs, request rules, improve docs, or write code."
+---
+
+# Contributing
+
+Contributions are welcome and appreciated.
+
+## Found something off?
+
+agnix validates against 445 rules, but the agent config ecosystem moves fast. If a rule is wrong, missing, or too noisy, I want to know.
+
+- [Report a bug](https://github.com/agent-sh/agnix/issues/new)
+- [Request a rule](https://github.com/agent-sh/agnix/issues/new)
+
+Your real-world configs are the best test suite I could ask for.
+
+## Contribute code
+
+Good first issues are labeled and ready:
+[good first issues](https://github.com/agent-sh/agnix/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+
+Adding a new rule is one of the best ways to get started. Each rule is a self-contained unit with clear inputs, outputs, and test patterns. Find a similar existing rule to use as your template.
+
+## Improve docs
+
+This documentation site is in `website/`. To run locally:
+
+```bash
+npm --prefix website ci
+npm --prefix website run generate:rules
+npm --prefix website start
+```
+
+## Where canonical content lives
+
+Long-form source-of-truth docs remain in the repository:
+
+- `README.md`
+- `SPEC.md`
+- `knowledge-base/`
+
+This website assembles and links that content for navigation and search.
+
+## References
+
+- [CONTRIBUTING.md](https://github.com/agent-sh/agnix/blob/v0.46.0/CONTRIBUTING.md) - full contribution guidelines
+- [SECURITY.md](https://github.com/agent-sh/agnix/blob/v0.46.0/SECURITY.md) - security policy