docs: comprehensive documentation audit and enhancement

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug report
+about: Report a defect in Codefang
+title: 'bug: '
+labels: bug
+---
+
+<!-- Template source: Good Docs Project issue templates (CC-BY 4.0). Fields mirror site/contributing/index.md §Reporting Bugs. -->
+
+### Codefang version
+
+<!-- Output of `codefang --version`. -->
+
+### Operating system and architecture
+
+<!-- For example, `Linux x86_64`, `macOS arm64`. -->
+
+### Steps to reproduce
+
+<!-- Minimal command or configuration to trigger the bug. -->
+
+1.
+2.
+3.
+
+### Expected behavior
+
+<!-- What you expected to happen. -->
+
+### Actual behavior
+
+<!-- What actually happened. Include error messages and stack traces. -->
+
+### Repository
+
+<!-- If applicable, a public repository or minimal reproducer. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Propose a new analyzer, output format, or integration
+title: 'feat: '
+labels: enhancement
+---
+
+<!-- Template source: Good Docs Project issue templates (CC-BY 4.0). Fields mirror site/contributing/index.md §Feature Requests. -->
+
+### Use case
+
+<!-- Describe the problem you are trying to solve. -->
+
+### Expected behavior
+
+<!-- What the feature should do, including example input and output if possible. -->
+
+### Alternatives considered
+
+<!-- Any workarounds you have tried or other tools that provide similar functionality. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+<!-- Template source: site/contributing/index.md §PR Description Template + §Before Opening a PR. -->
+
+## Scope
+
+<!-- What does this PR change and why? -->
+
+## Test matrix
+
+<!-- What tests were added or modified? What edge cases are covered? -->
+
+## Link to FRD/BUG
+
+<!-- Reference any related feature request document or bug issue, e.g. Closes #123. -->
+
+Closes #
+
+## Breaking changes
+
+<!-- Call out any breaking changes to public APIs or output formats. Write "None" if there are none. -->
+
+---
+
+### Before opening this PR
+
+- [ ] All tests pass locally (`make test`)
+- [ ] Linting is clean (`make lint`)
+- [ ] Dead code analysis passes (`make deadcode`)
+- [ ] Commit messages follow conventional commits
+- [ ] Documentation is updated if needed

.github/workflows/docs.yml

@@ -11,7 +11,13 @@ on:
     branches: [main]
     paths:
       - 'site/**'
+      - '**/*.md'
       - 'mkdocs.yml'
+      - '.markdownlint.jsonc'
+      - '.vale.ini'
+      - 'cspell.json'
+      - '.lycheeignore'
+      - '.github/workflows/docs.yml'
   workflow_dispatch:
 
 permissions:
@@ -68,3 +74,115 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+
+  markdownlint:
+    name: Lint Markdown (markdownlint)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run markdownlint-cli2
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          # Scope to the documentation surface only. Harness/spec markdown
+          # (.agents/**, .claude/**, specs/**, AGENTS.md, …) is not user-facing
+          # documentation and is not gated by the doc-quality rules.
+          globs: |
+            site/**/*.md
+            docs/**/*.md
+            README.md
+            CONTRIBUTING.md
+            CODE_OF_CONDUCT.md
+            SECURITY.md
+            SUPPORT.md
+            GOVERNANCE.md
+            THIRD_PARTY_NOTICES.md
+            CHANGELOG.md.proposed.md
+
+  vale:
+    name: Prose style (Vale, advisory)
+    runs-on: ubuntu-latest
+    # Advisory for the first iteration: surface findings without blocking the
+    # workflow until the R-STYLE-02 sentence-case migration lands.
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run Vale (Microsoft + Google packs)
+        uses: errata-ai/vale-action@reviewdog
+        # Step-level continue-on-error keeps this advisory check GREEN even when
+        # Vale/reviewdog exits non-zero (it does so on any error-level finding,
+        # independent of fail_on_error). Job-level continue-on-error only unblocks
+        # the run; it does not flip the reported check conclusion to success.
+        continue-on-error: true
+        with:
+          fail_on_error: false
+          reporter: github-pr-check
+          files: '["site", "README.md", "CONTRIBUTING.md", "docs"]'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  cspell:
+    name: Spell check (cspell, advisory)
+    runs-on: ubuntu-latest
+    # Advisory for the first iteration: project jargon is seeded in cspell.json,
+    # but the dictionary is still maturing, so do not block the workflow yet.
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run cspell
+        uses: streetsidesoftware/cspell-action@v6
+        # Advisory check: keep it green even if a new term is not yet in the
+        # dictionary. The dictionary is currently clean over the doc surface.
+        continue-on-error: true
+        with:
+          config: cspell.json
+          files: |
+            site/**/*.md
+            docs/**/*.md
+            README.md
+            CONTRIBUTING.md
+            CODE_OF_CONDUCT.md
+            SECURITY.md
+            SUPPORT.md
+            GOVERNANCE.md
+            THIRD_PARTY_NOTICES.md
+            CHANGELOG.md.proposed.md
+          incremental_files_only: false
+
+  lychee:
+    name: Check links (lychee)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run lychee link checker
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # NB: mailto:/tel: links are excluded by default in current lychee
+          # (and via .lycheeignore); the old --exclude-mail flag was removed
+          # upstream and now errors out, so it is intentionally omitted.
+          args: >-
+            --no-progress
+            --verbose
+            --max-concurrency 8
+            'site/**/*.md'
+            'docs/**/*.md'
+            'README.md'
+            'CONTRIBUTING.md'
+            'CODE_OF_CONDUCT.md'
+            'SECURITY.md'
+            'SUPPORT.md'
+            'GOVERNANCE.md'
+            'THIRD_PARTY_NOTICES.md'
+            'CHANGELOG.md.proposed.md'
+            'llms.txt'
+            'llms-full.txt'
+          fail: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.lycheeignore

@@ -0,0 +1,32 @@
+# lychee link-checker ignore list (one regex per line).
+# Reference: https://github.com/lycheeverse/lychee#ignoring-links
+# Patterns here are known-unreachable or context-dependent links that would
+# otherwise produce false negatives in CI.
+
+# Localhost / loopback endpoints used in MCP and observability examples.
+^https?://localhost
+^https?://127\.0\.0\.1
+^https?://0\.0\.0\.0
+^https?://\[::1\]
+
+# Private / link-local address ranges from large-scale-scanning examples.
+^https?://10\.
+^https?://192\.168\.
+^https?://172\.(1[6-9]|2[0-9]|3[01])\.
+
+# Example/placeholder hosts.
+example\.com
+example\.org
+your-org
+<.*>
+
+# The project's own GitHub Pages site is built and published by this same
+# workflow; on a PR the new pages may 404 until deploy completes.
+sumatoshi-tech\.github\.io
+
+# pkg.go.dev rate-limits aggressive crawlers and 404s modules until first fetch.
+pkg\.go\.dev
+
+# mailto and tel links — checked separately via --exclude-mail in the job.
+^mailto:
+^tel:

.markdownlint.jsonc

@@ -0,0 +1,40 @@
+// markdownlint-cli2 configuration for codefang docs.
+// Rule reference: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+// Tuned for the existing site/ + root *.md + docs/adr/ corpus so the first CI run
+// is signal, not a wall of false positives.
+{
+  "default": true,
+
+  // MD013 line-length: docs use long prose lines and wide tables/links.
+  // Disable the hard wrap requirement rather than enforce an arbitrary column.
+  "MD013": false,
+
+  // MD033 inline HTML: analyzer pages and the README use raw HTML
+  // (<p align="center">, <img>, admonition blocks, grid cards).
+  "MD033": false,
+
+  // MD041 first-line-h1: MkDocs pages sometimes open with front matter or
+  // an attr_list/admonition block instead of a top-level heading.
+  "MD041": false,
+
+  // MD024 duplicate headings: Keep a Changelog repeats Added/Changed/Fixed
+  // across versions, and ADRs repeat section names. Allow when not siblings.
+  "MD024": { "siblings_only": true },
+
+  // MD046 code-block-style: allow both fenced and indented blocks.
+  "MD046": false,
+
+  // MD007 unordered-list indentation: MkDocs material renders 4-space nesting.
+  "MD007": { "indent": 4 },
+
+  // MD036 emphasis-as-heading: the README uses bold lead-ins as pseudo-headings.
+  "MD036": false,
+
+  // MD034 bare URLs: badges and reference links occasionally use bare URLs.
+  "MD034": false,
+
+  // MD025 single-title: MkDocs Material pages carry a YAML front-matter
+  // `title:` (for nav/browser title) AND a rendered `# H1`. Both are
+  // intentional, so don't treat the front-matter title as a second H1.
+  "MD025": { "front_matter_title": "" }
+}

.vale.ini

@@ -0,0 +1,30 @@
+; Vale configuration for codefang docs.
+; Reference: https://vale.sh/docs/topics/config/
+; The Microsoft and Google style packs are pulled by the CI action's
+; `vale sync` step (PackageStyles). Advisory for the first iteration:
+; the CI job runs with continue-on-error so findings are visible but do
+; not block the workflow until the R-STYLE-02 sentence-case migration lands.
+
+StylesPath = .github/styles
+
+MinAlertLevel = suggestion
+
+; Pull the Microsoft and Google rule packs.
+Packages = Microsoft, Google
+
+[*.md]
+BasedOnStyles = Vale, Microsoft, Google
+
+; Project jargon and proper nouns Vale's spelling rule would otherwise flag.
+Vale.Terms = NO
+
+; Sentence-case headings are enforced after the R-STYLE-02 migration.
+Google.Headings = YES
+Microsoft.Headings = suggestion
+
+; Allow contractions and first-person — the README voice is intentionally casual.
+Google.Contractions = NO
+Google.FirstPerson = NO
+
+; Allow exclamation points used sparingly in the marketing-flavoured README.
+Google.Exclamation = NO