From 8d07c89859e004e8ba8e66623b814d2b8eb8ae63 Mon Sep 17 00:00:00 2001
From: Tauan BF <11513929+tauanbinato@users.noreply.github.com>
Date: Fri, 25 Sep 2026 19:22:55 -0300
Subject: [PATCH 1/2] Publish a documentation site

site/ is an mdBook: guide pages from the README's sections, pages on coding agents and troubleshooting, and rules, configuration and command-line reference pages generated from the binary, jevgate.schema.json and --help. The Docs workflow builds it on pull requests and publishes it to GitHub Pages from main.
---
 .github/workflows/docs.yml   |  50 +++
 .gitignore                   |   4 +
 CONTRIBUTING.md              |   4 +
 site/book.toml               |  19 ++
 site/build.sh                |   9 +
 site/generate.py             | 154 ++++++++++
 site/src/SUMMARY.md          |  31 ++
 site/src/changelog.md        |   3 +
 site/src/ci.md               |  52 ++++
 site/src/configuration.md    |  43 +++
 site/src/how-it-works.md     | 567 +++++++++++++++++++++++++++++++++++
 site/src/install.md          |  14 +
 site/src/introduction.md     |  27 ++
 site/src/languages.md        |  48 +++
 site/src/limits.md           |   6 +
 site/src/output.md           |  23 ++
 site/src/privacy-and-cost.md |   7 +
 site/src/quick-start.md      |  26 ++
 site/src/troubleshooting.md  |  41 +++
 site/src/what-it-finds.md    |  41 +++
 20 files changed, 1169 insertions(+)
 create mode 100644 .github/workflows/docs.yml
 create mode 100644 site/book.toml
 create mode 100755 site/build.sh
 create mode 100644 site/generate.py
 create mode 100644 site/src/SUMMARY.md
 create mode 100644 site/src/changelog.md
 create mode 100644 site/src/ci.md
 create mode 100644 site/src/configuration.md
 create mode 100644 site/src/how-it-works.md
 create mode 100644 site/src/install.md
 create mode 100644 site/src/introduction.md
 create mode 100644 site/src/languages.md
 create mode 100644 site/src/limits.md
 create mode 100644 site/src/output.md
 create mode 100644 site/src/privacy-and-cost.md
 create mode 100644 site/src/quick-start.md
 create mode 100644 site/src/troubleshooting.md
 create mode 100644 site/src/what-it-finds.md

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..1166642
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,50 @@
+name: Docs
+# Builds the documentation site (site/build.sh) and publishes it to GitHub
+# Pages from main. Pull requests that touch what the site is made from only
+# build it, so a broken page or include fails before it merges.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths: ["site/**", "README.md", "CHANGELOG.md", "docs/classification-cascade.md", "jevgate.schema.json", ".github/workflows/docs.yml"]
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+env:
+  MDBOOK_VERSION: 0.5.4
+  MDBOOK_SHA256: 5222beabd3e37dc5be0d18ff99b79058469354db5c220153a1b92db5ba12be89
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install Rust
+        run: rustup toolchain install stable --profile minimal
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      - name: Install mdBook
+        run: |
+          archive="mdbook-v$MDBOOK_VERSION-x86_64-unknown-linux-musl.tar.gz"
+          curl -fsSL -o "$RUNNER_TEMP/$archive" "https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_VERSION/$archive"
+          echo "$MDBOOK_SHA256  $RUNNER_TEMP/$archive" | sha256sum -c -
+          mkdir -p "$RUNNER_TEMP/bin" && tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP/bin"
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+      - run: site/build.sh
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site/book
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
diff --git a/.gitignore b/.gitignore
index 6b3d85b..ea9bd8a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,3 +29,7 @@ GEMINI.md
 *.log
 /video/
 /roadmap.md
+
+# The documentation site is built by site/build.sh; its reference pages are generated.
+/site/book/
+/site/src/reference/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ead9ec6..82b6fd5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -38,6 +38,10 @@ JevGate asks the model small questions and decides findings in code. When you ch
 
 [docs/classification-cascade.md](docs/classification-cascade.md) describes the evidence units and composition rules.
 
+## Documentation site
+
+The site at <https://tech-byte-frontier.github.io/jevgate/> is built from `site/` with [mdBook](https://rust-lang.github.io/mdBook/): `site/build.sh` generates the rules, configuration and command-line reference pages from a release build, then builds the book into `site/book`. Guide pages are in `site/src`; the reference pages are generated, so change the rule catalog, the configuration types or the `--help` text instead.
+
 ## Pull requests
 
 - Keep a pull request to one change, with tests.
diff --git a/site/book.toml b/site/book.toml
new file mode 100644
index 0000000..f7b2701
--- /dev/null
+++ b/site/book.toml
@@ -0,0 +1,19 @@
+[book]
+title = "JevGate"
+description = "A code-review gate for CI and coding agents"
+authors = ["Tech Byte Frontier"]
+language = "en"
+src = "src"
+
+[build]
+build-dir = "book"
+create-missing = false
+
+[output.html]
+site-url = "/jevgate/"
+git-repository-url = "https://github.com/Tech-Byte-Frontier/jevgate"
+edit-url-template = "https://github.com/Tech-Byte-Frontier/jevgate/edit/main/site/{path}"
+no-section-label = true
+
+[output.html.search]
+limit-results = 20
diff --git a/site/build.sh b/site/build.sh
new file mode 100755
index 0000000..2b27c86
--- /dev/null
+++ b/site/build.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Build the documentation site into site/book: the reference pages are
+# generated from a release build of JevGate, so they match its --help,
+# `jevgate rules` and jevgate.schema.json. Needs mdbook on PATH.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+cargo build --release --locked --quiet
+python3 site/generate.py target/release/jevgate jevgate.schema.json site/src/reference
+mdbook build site
diff --git a/site/generate.py b/site/generate.py
new file mode 100644
index 0000000..e59e570
--- /dev/null
+++ b/site/generate.py
@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Write the site's reference pages from JevGate itself.
+
+    generate.py JEVGATE SCHEMA OUT_DIR
+
+rules.md comes from `jevgate rules --format json`, configuration.md from
+jevgate.schema.json, and cli.md from each command's --help, so the pages
+always describe the binary they were built with.
+"""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+COMMANDS = ["auth", "check", "baseline", "rules", "init", "completions", "man", "serve"]
+GROUPS = {
+    "maintainability": "On by default.",
+    "tests": "On by default; judged with `--include-tests` or `include_tests = true`.",
+    "security": "Opt-in: `--rule security`, or a level in `[rules]`.",
+    "documentation": "Opt-in: `--rule documentation`, or a level in `[rules]`.",
+}
+
+
+def run(binary, *args):
+    return subprocess.run([binary, *args], check=True, capture_output=True, text=True).stdout
+
+
+def rules_page(binary):
+    rules = json.loads(run(binary, "rules", "--format", "json"))
+    version = run(binary, "--version").strip()
+    lines = [
+        "# Rules reference",
+        "",
+        f"Generated from `jevgate rules --format json` ({version}). A rule is named by its ID,",
+        "its key or its group anywhere a rule is accepted: `--rule`, `--skip-rule`,",
+        "`--fail-on TARGET=LEVEL`, `[rules]` and `[[scope]]`.",
+        "",
+        "| Rule | Key | Default | Question |",
+        "|---|---|---|---|",
+    ]
+    for rule in rules:
+        anchor = rule["id"].replace("/", "-")
+        default = "yes" if rule["default_enabled"] else "opt-in"
+        lines.append(
+            f"| [`{rule['id']}`](#{anchor}) | `{rule['key']}` | {default} | {cell(rule['inspection'])} |"
+        )
+    group = None
+    for rule in rules:
+        if rule["group"] != group:
+            group = rule["group"]
+            lines += ["", f"## {group.capitalize()}", "", GROUPS.get(group, "")]
+        anchor = rule["id"].replace("/", "-")
+        lines += [
+            "",
+            f'<a id="{anchor}"></a>',
+            f"### `{rule['id']}`",
+            "",
+            f"**Question:** {rule['inspection']}",
+            "",
+            f"- **Key:** `{rule['key']}` · **Version:** {rule['version']}"
+            + (" · **Needs tests:** yes" if rule["requires_tests"] else ""),
+            f"- **Looks at:** {rule['scope']}",
+            f"- **Evidence unit:** {rule['unit']}",
+            f"- **Acceptable:** {rule['acceptable_example']}",
+        ]
+    policy = rules[0]["decision_policy"]
+    lines += [
+        "",
+        "## Decision policy",
+        "",
+        "Answers become findings in code, at the same thresholds for every rule:",
+        "",
+        "| Setting | Value |",
+        "|---|---|",
+    ]
+    lines += [f"| `{name}` | {value:g} |" for name, value in sorted(policy.items())]
+    return "\n".join(lines) + "\n"
+
+
+def configuration_page(schema_path):
+    schema = json.loads(Path(schema_path).read_text())
+    lines = [
+        "# Configuration reference",
+        "",
+        "Generated from [`jevgate.schema.json`](https://github.com/Tech-Byte-Frontier/jevgate/blob/main/jevgate.schema.json),",
+        "which is generated from the configuration types. [Configuration](../configuration.md) explains",
+        "how the keys work together.",
+        "",
+        "| Key | Type | Meaning |",
+        "|---|---|---|",
+    ]
+    for name, spec in sorted(schema["properties"].items()):
+        lines.append(f"| `{name}` | {kind(spec, schema)} | {cell(spec.get('description', ''))} |")
+    scope = schema["$defs"]["Scope"]
+    lines += ["", "## `[[scope]]`", "", cell(scope.get("description", "")), "", "| Key | Type | Meaning |", "|---|---|---|"]
+    for name, spec in sorted(scope["properties"].items()):
+        lines.append(f"| `{name}` | {kind(spec, schema)} | {cell(spec.get('description', ''))} |")
+    levels = schema["$defs"]["Level"]["anyOf"][0]["enum"]
+    names = schema["$defs"]["Scope"]["properties"]["rules"]["propertyNames"]["enum"]
+    lines += [
+        "",
+        "## Levels",
+        "",
+        ", ".join(f"`{level}`" for level in levels) + ". `off` is accepted in `[rules]` only.",
+        "",
+        "## Rule names",
+        "",
+        ", ".join(f"`{name}`" for name in names) + ".",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def kind(spec, schema):
+    if "$ref" in spec:
+        return "rules list or table"
+    if spec.get("type") == "array":
+        items = spec.get("items", {})
+        return "list of tables" if "$ref" in items else "list of " + items.get("type", "value") + "s"
+    return spec.get("type", "value")
+
+
+def cli_page(binary):
+    lines = [
+        "# Command-line reference",
+        "",
+        f"Generated from `--help` ({run(binary, '--version').strip()}). "
+        "`jevgate man COMMAND` prints the same text as a man page.",
+        "",
+        "## `jevgate`",
+        "",
+        "```text",
+        run(binary, "--help").rstrip(),
+        "```",
+    ]
+    for command in COMMANDS:
+        lines += ["", f"## `jevgate {command}`", "", "```text", run(binary, command, "--help").rstrip(), "```"]
+    return "\n".join(lines) + "\n"
+
+
+def cell(text):
+    return text.replace("|", "\\|").replace("\n", " ")
+
+
+def main():
+    binary, schema, out = sys.argv[1:4]
+    out = Path(out)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "rules.md").write_text(rules_page(binary))
+    (out / "configuration.md").write_text(configuration_page(schema))
+    (out / "cli.md").write_text(cli_page(binary))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/site/src/SUMMARY.md b/site/src/SUMMARY.md
new file mode 100644
index 0000000..a343011
--- /dev/null
+++ b/site/src/SUMMARY.md
@@ -0,0 +1,31 @@
+# Summary
+
+[JevGate](introduction.md)
+
+# Getting started
+
+- [Install](install.md)
+- [Quick start](quick-start.md)
+- [What it finds](what-it-finds.md)
+- [Supported languages and frameworks](languages.md)
+
+# Using JevGate
+
+- [Continuous integration](ci.md)
+- [Coding agents](agents.md)
+- [Configuration](configuration.md)
+- [Output and exit codes](output.md)
+- [Privacy and cost](privacy-and-cost.md)
+- [Troubleshooting](troubleshooting.md)
+
+# Background
+
+- [How it works](how-it-works.md)
+- [Limits](limits.md)
+- [Changelog](changelog.md)
+
+# Reference
+
+- [Rules](reference/rules.md)
+- [Configuration keys](reference/configuration.md)
+- [Command line](reference/cli.md)
diff --git a/site/src/changelog.md b/site/src/changelog.md
new file mode 100644
index 0000000..91e0332
--- /dev/null
+++ b/site/src/changelog.md
@@ -0,0 +1,3 @@
+# Changelog
+
+{{#include ../../CHANGELOG.md:3:}}
diff --git a/site/src/ci.md b/site/src/ci.md
new file mode 100644
index 0000000..ab31710
--- /dev/null
+++ b/site/src/ci.md
@@ -0,0 +1,52 @@
+# Continuous integration
+
+A pull request review on GitHub Actions, with the [JevGate action](https://github.com/Tech-Byte-Frontier/jevgate-action):
+
+```yaml
+name: JevGate
+on: pull_request
+permissions:
+  contents: read
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # --base compares with the fork point
+      - uses: Tech-Byte-Frontier/jevgate-action@v1
+        with:
+          api-key: ${{ secrets.TYPESAFE_API_KEY }}
+          version: 0.17.0
+```
+
+The action installs a checked release binary, keeps `.jevgate/cache` in the Actions cache and runs `jevgate check --base <pull request base> --format github`; `args` passes more flags, such as `--rule security`. It runs on Linux, macOS and Windows runners.
+
+`--format github` annotates the changed lines with each finding. A finding that fails the gate is an error; the others are warnings. A Markdown table goes to the job summary, and the usual text goes to the log. The full JSON report is always at `.jevgate/latest.json` if you want to keep it as an artifact.
+
+- **Changed files only:** `--base` reviews what changed since the fork point with that revision, the same files a pull request diff shows, plus uncommitted and untracked files. It needs the history, so check out with `fetch-depth: 0`. When no supported file changed, the run passes without any request.
+- **Cache:** answers are stored under a hash of the exact request: source, questions and model. Restoring an older cache is always safe, and unchanged code costs nothing on the next run.
+- **Advisory or blocking:** `fail_on = ["none"]` in `jevgate.toml` or `--fail-on none` reports findings without failing. A run that could not finish (missing key, provider rejection, request budget reached) still exits 2, so an outage never passes as a clean review.
+- **A policy the change cannot edit:** a pull request can edit `jevgate.toml`. To apply the reviewed policy of the base branch instead, read it with `--config`:
+
+  ```sh
+  git show "$BASE_SHA:jevgate.toml" > "$RUNNER_TEMP/jevgate.toml"
+  jevgate check --config "$RUNNER_TEMP/jevgate.toml" --base "$BASE_SHA" --format github
+  ```
+
+- **Forks:** GitHub withholds secrets from pull requests opened from forks, so there the run exits 2 with "No API key configured". Skip the job for forks, or run it only on branches of the repository.
+- **Budgets:** `max_requests` caps the API attempts of one run. Reaching it leaves the run incomplete instead of passing on partial evidence. `--dry-run` counts the planned requests the cache already answers, so its estimate covers only what the cache lacks; follow-ups depend on answers and are not counted.
+- **Transient failures:** rate limits, overload and server or edge errors (HTTP 408, 429, 500, 502–504, 520–524, 529) are retried up to four attempts; a timeout or dropped connection is retried once, since the first send may have run.
+- **Report-only paths:** give tooling its own level with `[[scope]]` (below), so scripts are reported while product code gates.
+
+Before each commit, with [pre-commit](https://pre-commit.com), review what is staged:
+
+```yaml
+repos:
+  - repo: https://github.com/Tech-Byte-Frontier/jevgate
+    rev: v0.18.0
+    hooks:
+      - id: jevgate-system   # the jevgate on PATH; `jevgate` builds it with Rust instead
+```
+
+Other CI systems work the same way: install with `install.sh` or `cargo binstall`, set `TYPESAFE_API_KEY`, keep `.jevgate/cache` between runs, and read the exit code or the JSON report.
diff --git a/site/src/configuration.md b/site/src/configuration.md
new file mode 100644
index 0000000..e9358c3
--- /dev/null
+++ b/site/src/configuration.md
@@ -0,0 +1,43 @@
+# Configuration
+
+`jevgate init` writes a commented `jevgate.toml` at the repository root. The command line wins over the file, except that upload patterns and budgets in the file are ceilings that flags can only narrow. Unknown keys are errors. Its first line points editors with TOML schema support (Even Better TOML, Taplo) to [`jevgate.schema.json`](https://github.com/Tech-Byte-Frontier/jevgate/blob/main/jevgate.schema.json), which completes keys, rule names and levels and flags mistakes as you type.
+
+```toml
+upload_allow = ["src/**", "tests/**"]   # only these paths may be uploaded
+upload_deny = ["**/.env*", "**/*.pem", "**/*.key"]
+include_tests = true
+max_requests = 300
+
+[rules]                                  # a level per group or rule
+maintainability = "review"               # judge, and fail the gate on review findings
+tests = "consider"
+security = "consider"                    # opt-in group, enabled by naming it
+"maintainability/hardcoded-values" = "report"   # judge but never fail; "off" skips it
+
+[[scope]]                                # levels for the files these paths match
+paths = ["scripts/**", "tools/**"]
+fail_on = ["report"]                     # every rule: judge, never fail
+rules = { security = "consider" }        # except these
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `upload_allow` | every path | Globs of the paths that may be uploaded, including instruction files and context |
+| `upload_deny` | none | Globs never uploaded, even when allowed |
+| `generated` | built-in names | Globs of generated files, which are skipped |
+| `tests` | built-in conventions | Globs of additional test files |
+| `context` | none | Files always sent as related evidence, like `--context` |
+| `rules` | the `default` group | A list selects rules. A table gives each group or rule a level: `review`, `consider`, `uncertain`, `report` (judge, never fail) or `off` |
+| `[[scope]]` | none | `paths` (globs), with `fail_on` for every rule and `rules` for rules or groups, as above; `off` is not accepted (use `upload_deny`). The last scope that matches a file and addresses a rule wins; flags win over scopes |
+| `fail_on` | `["review"]` | The level for rules without their own, like `--fail-on` |
+| `include_tests` | `false` | Judge tests, like `--include-tests` |
+| `model` | `jev-1.13.0` | TypeSafe model; a pinned version keeps results repeatable |
+| `cache_ttl_secs` | `3600` | Cache lifetime for the `jev-latest` and `jev-preview` aliases; pinned versions never expire |
+| `max_requests` | unlimited | Ceiling on API attempts per invocation |
+| `concurrency` | `6` | Ceiling on simultaneous requests (1–8) |
+| `max_file_bytes` | `262144` | Files larger than this are reported as needs-context, never truncated; generated and vendored files are skipped instead |
+| `max_context_bytes` | `32768` | Ceiling on context bytes per request |
+
+Rules are named by ID (`maintainability/shared-logic`), key (`shared_logic`) or group (`maintainability`, `tests`, `security`, `documentation`, `default`, `all`). The same names work in `--rule`, `--skip-rule` and `--fail-on TARGET=LEVEL`, and the most specific entry wins.
+
+The [configuration reference](reference/configuration.md) lists every key with its type, and the rule names and levels it accepts.
diff --git a/site/src/how-it-works.md b/site/src/how-it-works.md
new file mode 100644
index 0000000..374e66e
--- /dev/null
+++ b/site/src/how-it-works.md
@@ -0,0 +1,567 @@
+# How it works
+
+1. **Local analysis, nothing uploaded.** Tree-sitter parsers find functions, methods, types and registered callbacks, such as route handlers written inline in `app.post('/pages', async (c) => …)`. They measure nesting, group a file's members, find renamed copies, map tests to the functions they call, and list the statements where a value reaches another program. This evidence locates and scopes; it never decides a finding.
+2. **Small, literal questions.** Each request covers one small unit and asks a few questions, such as "Would splitting this function make it easier to understand?" or "Does this function put a variable into the text of an SQL query instead of binding it?"
+3. **Follow-ups only where needed.** When an answer is split, JevGate gathers more evidence (callee signatures, callers, a specific check) and asks once more instead of guessing.
+4. **Composition in code.** Answers become `review`, `consider`, `note`, `clear` or `uncertain` at a 0.80 threshold. Raw probabilities stay in the JSON report.
+
+The rest of this page describes the evidence units and composition rules in detail.
+
+## Evidence units
+
+JevGate asks Jev short, literal questions about small units of evidence that code
+has already built, then composes the answers in code.
+
+### Why units
+
+A single request per file carried the whole source, every rule's candidates and
+several broad questions. Large states lowered decisiveness, and reconciling
+file-wide answers with per-operation probes let decisive concerns disappear.
+Units send only what one question needs: one function's source, a file's member
+signatures, or one candidate pair.
+
+### Pipeline
+
+1. **Eligibility and purpose.** Deterministic roles, generated-code headers,
+   compiled or minified output (a trailing source map reference, or nine tenths
+   of the file in lines of 1,000 bytes or more) and structural test markers
+   decide which code the application rules and the test rules see. Only a test
+   path without structural tests gets a file-purpose request. Go tests are
+   `Test…`, `Benchmark…` and `Fuzz…` functions taking `*testing.T`, `.B` or `.F`.
+   C# tests are whole classes marked `[TestFixture]` or `[TestClass]` or
+   holding a method marked `[Fact]`, `[Theory]`, `[Test]`, `[TestCase]`,
+   `[TestCaseSource]`, `[TestMethod]` or `[DataTestMethod]`, and every C# file
+   of a test project directory named like `Shop.Tests`; `.Designer.cs`,
+   `.g.cs` and `.g.i.cs` files are generated.
+   Ruby tests are RSpec groups and examples written as statements
+   (`describe`, `context`, `it`, `specify`, `its`, titled by a string or not
+   at all, so a Rakefile's `test(:unit) do` is not one) and classes whose
+   superclass ends in `Test`, `TestCase` or `Spec` (`Minitest::Test`,
+   `ActiveSupport::TestCase`) with `test_*` methods or `test "…" do` blocks;
+   `*_spec.rb` files and Ruby files under `spec/` are test files.
+   PHP tests are the `test…`, `@test` or `#[Test]` methods of a class
+   extending a `…TestCase`, and Pest `test(…)`/`it(…)` calls; `…Test.php`
+   files are test paths.
+   A Java class is a test class, whole, when it holds a method annotated
+   `@Test`, `@ParameterizedTest` or another test annotation (a composed one
+   whose name ends in `Test` included), a JUnit lifecycle method such as
+   `@BeforeEach`, a nested test class, or extends JUnit 3's `TestCase`;
+   `…Test`, `…Tests`, `…TestCase` and `…IT` files are test paths. A test
+   that sends a request to a literal path (MockMvc's `get("/owners/{id}")`,
+   RestTemplate's `RequestEntity.get(…)`) calls the Spring controller method
+   whose `@GetMapping`, `@PostMapping` or `@RequestMapping` route serves it,
+   under its class's prefix, by full name, the most literal route winning:
+   controllers share method names such as `initCreationForm`, and a request
+   names no method, so such tests had no code under test.
+   Astro, Vue and
+   Svelte files are parsed as their scripts: Astro frontmatter and `<script>`
+   contents, with every other byte a space, so lines stay the file's.
+2. **Local analysis** (`src/analysis/`). Units with signatures, calls, references
+   and control-flow nesting; callbacks registered through calls, including
+   module-level route handlers named by their registration
+   (`app.post('/pages')`); member groups by average linkage; callers that
+   import the file (application code only, since tests calling a group do not
+   make it a dependency); for file organization, each member's line count and
+   the file's, and for a test file, its cases with their enclosing
+   `describe`, class or module and the functions under test they call, grouped
+   by shared suite, subject or helper. A subject that one type in scope owns
+   is named with it (`StringUtil::isBlank`); a Java test file's top-level
+   class is not a suite, since every case would share it, while `@Nested`
+   classes are. A pair of similar tests is about a function they share that
+   is neither a camelCase getter or setter nor called by most of the file's
+   tests (a fixture or client every test uses), and that the fewest tests
+   call: the first shared name made `setBirthDate` the subject of validator
+   tests and grouped unrelated pairs under a shared `create_user` fixture.
+   Test files get this outline without
+   `--include-tests`; their finding is at most a consider. Who calls a group is
+   evidence only: gating a split on callers of its own hid large files whose
+   single caller is the rest of the program; Type-2 clone candidates grouped by overlapping copies, only
+   within one package or packages linked by a local dependency (copies in side
+   by side templates or example apps are separate projects); test cases with
+   their subjects and similar pairs. A PHP file's top-level statements
+   outside functions and classes (and its `<?= … ?>` echoes) are one more
+   unit, `top-level code`: a page script reads the request and writes the
+   response there, so every security rule judges it like a function, while
+   other languages' top-level statements are judged for unsafe settings
+   only. Closures registered through calls (`$app->get('/users', …)`,
+   `Route::post(…)`) or returned by a configuration file
+   (`return function (App $app) {…}`) are functions of their own.
+   A Java constructor's statements that store
+   a parameter, another object's field or a literal in a field break a copy:
+   two constructors filling different fields matched as copies and stayed
+   undecided. So does a Java setter given one literal
+   (`owner.setCity("Madison")`): a fixture built in a helper and an owner
+   built inside a test matched as copies whose only differences were the
+   values. Java `equals` and `hashCode` overrides offer no copies or
+   values, and neither does an initial capacity (`new ArrayList<>(4)`) or the
+   number a method returns whole (`int cost() { return 7; }`), which the
+   method's name already names.
+3. **First pass** (`src/units/`). One dispatch of every unit request. Functions,
+   for simplification, hardcoded values and security, are packed eight per
+   request within runs of functions, a run ending after a function whose name
+   hashes to one of four values, so a function added, removed or resized
+   re-asks only its run: packed in file order, one added function re-sent
+   every later pack of the file (5 of 5 simplification requests of
+   `compose.rs`, against 1 now). Runs add requests (25% to 106%, and 33% to
+   300% for instruction files), and every request is billed about 280 input
+   tokens beyond its size, so a full first pass bills 4% to 7% more input
+   (functions 6% to 13%, values 4% to 7%, security 3% to 5%). A function
+   removed re-asks 24% to 47% fewer tokens, so the runs pay back after 19 to
+   30 edits. One in eight names ending runs cost under half as much extra on
+   a full pass but saved a half to two thirds as much per edit, and left
+   whole files in one run (`clones.rs`, `literals.rs`); one in four
+   overtakes it after 31 to 40 edits.
+   Tests are sent one per request, because unrelated
+   tests in the same state left more answers undecided. State uses literal paths
+   such as `functions[2].source`; group IDs are Choice options. Stage and freshness
+   hashes stay in local `jevgate` metadata that is not uploaded.
+4. **Follow-ups.** One recheck per uncertain unit, with callee signatures, the
+   enclosing functions or the file's application source; a decisive recheck
+   replaces the first answer and both are kept. A hardcoded-value unit is asked
+   instead whether every value is of an acceptable kind; that check can only
+   clear, since re-asking the concern per value added false findings. The
+   unnamed-value check lists the kinds in its question: asked whether each
+   value "explains itself", it cleared none, even of field names.
+   A function or file-organization note whose middle and top levels both
+   stay under 0.50 gets the same recheck, and a decisive answer replaces it.
+   An outline whose recheck stays undecided is asked, in a request of its
+   own, what kind of file it is: one algorithm, type, resource, component,
+   set of definitions, helpers or coordination serves one feature; the same
+   kind of code written out per feature, or several unrelated features,
+   serves several. Kinds that serve one feature at 0.80 clear it, and the
+   others at 0.80 raise a consider. Weighing a split stayed near a third per
+   level on such files, while naming the kind was decisive; asked beside the
+   recheck, the kind moved the recheck's own answers. A file too long to send
+   whole gets no recheck, so its undecided first answer is asked the kind
+   from the outline alone; large Java classes and their test files otherwise
+   stayed uncertain.
+   A test left undecided on whether it re-implements the code or checks only
+   its mocks is asked again with the bodies of the functions it calls and its
+   file's imports, mocks and setup hooks (a part too long is left out, never
+   cut); each answer replaces the first unless only the first is decisive.
+   A Ruby test is sent with the groups it is declared in, since an RSpec
+   example reads as a sentence continuing them and the outer group often names
+   the class under test. Its recheck shows, instead of every hook of the
+   file, what runs for it: its groups' `before`, `around` and `setup` hooks,
+   `let!`, and the `let` and `subject` definitions it reads (directly or
+   through another), then the test helpers it and those hooks call, from its
+   own file or the nearest support file (one without test cases sharing a
+   directory with it; an RSpec group's methods stay in its file). The note
+   says a value built there is input to the code under test unless a mock
+   returns it: with the file's setup described as mocks, factory definitions
+   and `mock_app` routes read as mocks, and a third of such tests stayed
+   undecided. Ruby test pairs carry their groups and hooks when these differ,
+   and are also asked whether each test checks something the other does not
+   (another method, matcher, attribute, option or code path); "one adds
+   nothing" is a review only when that is ruled out at 0.80. Copied RSpec
+   examples for an alias and its original (`each` and `each_pair`) or for two
+   predicates of one record were otherwise reviews.
+   A controller method a test reaches through a request carries that route.
+   The first pass names a literal worked out by hand, even with the
+   arithmetic in a comment, as not re-implementing the code. Its "checks only
+   its mocks" question names tests without any stub (a setter read back, a
+   round trip, a benchmark), and tests checking which stub the code chose or
+   the view and status a handler chose for stubbed data, as not hollow: those
+   stayed near a third, as if every assertion were about the mocks.
+   A pair of tests whose overlap spreads over the three levels is asked
+   again with the body of the function both call: whether it throws before
+   the rest of a test runs is in that body.
+   Then one locate Choice per split finding picks the body block to extract,
+   and one per hardcoded-value review or consider names the value it is about.
+   Special-case findings in different files that name the same identity
+   become one finding at the strongest site; the others are notes pointing at
+   it. Numbers and paths are not grouped: `1000` meant metres per kilometre in
+   one file and an image height in another.
+   Security units whose presence answers are not clear get one trace before the
+   rechecks: specific literal checks per kind, a Choice among the unit's sites,
+   and the origin of its values (or whether it runs only in development). One
+   broad "is every value bound, escaped or checked?" stayed undecided even for
+   `eval` of model output; a check per kind decides and names the kind. An
+   injection whose origin stays unclear or is the function's parameters is
+   asked its origin and checks again with up to three callers; its answer
+   replaces the traced one unless only the traced one is decisive.
+   The markup check names text shown as a JSX child and CSS values or class
+   names as escaped or inert; sending where each built string goes did not
+   settle React units, the examples did. A sensitive-data trace lists the
+   message argument of each error the function creates and asks which one,
+   if any, carries another error's text: the response is often written by an
+   error handler in another file, and adding the handler to every unit also
+   cleared real leaks. Each registered error handler (`.onError(…)`,
+   `.setErrorHandler(…)`, Express four-parameter `.use(…)` middleware, Flask
+   and FastAPI decorators, NestJS `@Catch` filters, axum `IntoResponse` and
+   actix-web `ResponseError` for an error type, Rocket catchers, ASP.NET Core
+   `UseExceptionHandler` lambdas, exception filters, `IExceptionHandler` and
+   middleware classes whose `Invoke` catches what the pipeline throws; a path
+   given to `UseExceptionHandler` re-executes a page judged as its own code)
+   is asked once
+   whether it sends clients more than the program's own messages and codes,
+   with the program's `…Error` classes (Rust enums with their `#[error]`
+   messages) and the functions of its file that it calls. A registration
+   inside a comment or string literal registers nothing. An injection trace
+   also gets the definitions of enums its sites name (`ConfigKey.aiTag`), so
+   a fixed choice does not read as a parameter.
+   Questions about C# files carry ASP.NET Core's names for what they ask
+   (`FromSqlInterpolated` binds, `ServerCertificateCustomValidationCallback`
+   returning true skips certificates, `ValidateIssuer` checks claims, not
+   certificates), and C# traces ask three more weak-setting checks (developer
+   exception pages outside development, token signature or lifetime checks
+   turned off, signing keys written in the code) and one injection check
+   (types named by input or chosen by deserialized data). An unsafe-settings
+   trace in C# also gets the `const` and `static readonly` fields the code
+   names, often declared in another file, so a key written in the code does
+   not read as configuration. Other languages keep their wording: the
+   additions were measured on ASP.NET Core projects only. A broad weak-setting
+   answer that none of the specific checks leans toward names no setting to
+   change and is at most a note: on an action marked `[AllowAnonymous]` on
+   purpose it was 0.85 while every check stayed at 0.30 or less.
+   In a package that depends on `next`, a file's path names its role
+   (`app/**/route.ts`, `pages/api/**`, `middleware.ts` or `proxy.ts`,
+   `app/**/error.tsx`, pages and layouts, `next.config.*`), and in any
+   package a leading `'use server'` or `'use client'` directive, or a
+   function body that starts with `'use server'`, marks Server Actions or a
+   client component. The role goes into the file state of security and
+   hardcoded-value questions as `framework`, and every such question's note
+   points to it: stated only in the state, a client component's role did not
+   clear its browser requests. Questions about how code reads (splits,
+   outlines, tests) get no role: there it moved split answers without
+   informing them. With it, a
+   Server Action's parameters read as client input (an injection that was a
+   consider on its parameters became a review) and an error boundary as the
+   browser's own page. The injection trace asks one more literal check,
+   whether a redirect target from a variable is checked (CWE-601): without
+   it, `redirect(next)` and `NextResponse.redirect(returnTo)` were notes about
+   URLs "it requests". Only targets a request carries count: a link
+   shortener's redirect to the destination its owner saved was a review.
+   The SQL check names tagged templates that bind (`sql`, `$queryRaw`) as
+   handled and `$queryRawUnsafe` and `sql.raw` as not, the
+   markup check names `dangerouslySetInnerHTML` (also a site), and the unsafe
+   settings ask whether a secret comes from a variable the build puts into
+   browser code (`NEXT_PUBLIC_`). A `next.config` file's setup is every
+   top-level statement that holds an object, with its innermost objects as
+   sites, since `headers()` settings call nothing.
+   Django code (Python that imports Django or Django REST framework, and
+   settings modules) is asked Django's names in the checks that have them
+   and three more; other code keeps the common ones, so its cached answers
+   stay valid. They name raw SQL (`raw`, `extra`, `RawSQL`), `mark_safe` and
+   templates that write values with `|safe`, `redirect()` to route names or
+   the program's own paths, the storage API, Django's password hashers and
+   validation errors, and add deserializers of request data (`pickle`,
+   `yaml.load`), debug mode, `csrf_exempt` and literal secret keys, and
+   `request.META` or the settings sent to a client. A view is sent with the
+   URL routes that reach it (a `\d+` parameter holds digits), the templates
+   it renders that write values unescaped, and the module constants it
+   names; a management command is marked as run by hand, since its options
+   came back as another party's. A settings module is one unit whose
+   statements are its settings, with secret literals redacted to their
+   length (a dotted path such as a secret-key getter is not a secret). It is
+   sent with the lines that select it (`DJANGO_SETTINGS_MODULE` in a
+   Dockerfile, CI or `manage.py`) and with the settings modules that import
+   it, directly or through others, each with its own selections and its
+   assignments of the settings it sets again; a `setdefault` in
+   `manage.py` or `wsgi.py` is marked as only a default, since shown bare it
+   read as the deployed choice and made shared CORS settings that production
+   sets again a review. Its sites put security settings first, then
+   assignments into a setting (`OPTIONS["ssl_cert_reqs"] = None`), which
+   URLs joined with paths had crowded out. Presence alone found a
+   development `DEBUG = True` or a signed webhook's `csrf_exempt` weak as
+   surely as a deployed one, so a Django weak setting must be named by a
+   specific check at the review threshold to be a consider or review;
+   otherwise it is a note, and settings only development or tests run with
+   are two levels lower. The secret, cookie and CORS checks ask about the
+   deployed site, since asked about the module alone they flagged base
+   settings that production sets again. The markup Choice asks a Django view
+   what it sends back, since views that only redirect or render an escaping
+   template split on the markup check. Since nearly every Django view places
+   request values somewhere, an injection note that no check found (values
+   from another party, every check undecided or clear) gets the settle
+   Choices too: on django.nV, redirects to the view's own paths with ids in
+   them left seven such notes, which the redirect-target Choice cleared. The
+   CSRF check names forms for visitors who are not signed in, such as a
+   password reset request, as not acting for a user. Django error views
+   (`handler500 = …`), middleware `process_exception` and Django REST
+   framework's `EXCEPTION_HANDLER` are error handlers, asked with the
+   framework's errors written for the user named as acceptable.
+   A security unit still uncertain after its trace and recheck is asked, per
+   undecided check and in a request of its own, one literal Choice that can
+   only clear that check: where its URLs come from (a host of the program's
+   own at 0.80 clears an undecided URL check; a configured host sent another
+   URL to fetch does not) and where the code runs (only in the user's
+   browser clears it); where its redirect targets come from (written in the
+   code, returned by its own server or what callers pass, checked, or no
+   redirect); how its markup is rendered (escaped by JSX or a template, or
+   shown as text; PHP units are asked what they join instead, see below); which sites may send credentialed requests (none, listed
+   origins, or any origin without credentials); what its logs write (only
+   messages, ids and caught errors); or where its text goes (anywhere but a
+   remote client at 0.80 clears undecided error details). Offered beside
+   "a whole URL handed to it", the browser lost for a client component's
+   fetch helper, which is why where code runs is its own Choice. A consider
+   or note that rests on an undecided error-detail or URL check gets the
+   destination or runs-in question, since it claims the text likely reaches
+   a client or the request leaves a server. On three Next.js apps these
+   Choices took the uncertain files from 56 to 34, most of them client
+   components that navigate to fixed paths or render values as attributes.
+   A Choice about what a query builder joins into SQL (its own clauses,
+   numbers, or values handed to it) was tried for considers on parameters
+   and dropped: it cleared a sort column taken from the request as readily
+   as clauses with placeholders. The same question about paths cleared real
+   traversals, reading names stored in an index as the program's own, so path
+   checks stay undecided until callers show more. The SQL check counts
+   identifiers quoted by doubling embedded quotes as handled (identifiers
+   cannot be bound), and the URL check excludes requests a web page sends from
+   the user's browser; on fresh repositories both had flagged such code, while
+   the SQL and SSRF advisory functions kept their answers.
+   PHP units read the presence questions and checks in PHP's own terms
+   (`src/units/questions/php.rs`), naming its functions (`echo`,
+   `shell_exec` and backticks, `mysqli_real_escape_string`, `password_hash`,
+   `CURLOPT_SSL_VERIFYPEER`); every other language keeps the general wording,
+   so its requests and cached answers are unchanged. The PHP SQL check counts
+   driver escaping inside quotes and numbers as handled: asked only about
+   binding, DVWA's escaped and quoted guestbook inserts were reviews. Text a
+   page writes with `echo` is its response, not a log; a page that only calls
+   `generateSessionToken()` or a session helper is not judged for what that
+   helper does; the message of an exception class the program defines,
+   caught by name, is its own text (four BookStack upload controllers
+   returning `FileUploadException` messages were error-detail reviews); and
+   only variables placed into a query or path count for the origin, not an
+   uploaded file's contents. `unserialize` and uploaded file names are PHP
+   checks, asked only of source that names `unserialize` or an upload; a page
+   that only showed an upload form stayed near 0.4 on whether it saves
+   uploads.
+   PHP units have three settle Choices of their own, asked whenever their
+   check is not clear, even when it found a concern, since each can clear
+   it: what the unit joins into HTML unescaped (request values, stored
+   records and parameters holding text keep the check; escaped values and
+   numbers, text the program produces such as errors and command output,
+   HTML other code builds such as a page body an included file sets, and
+   element data clear it), what its command lines hold (values each checked
+   against a strict format, such as octets that pass `is_numeric`, clear it;
+   values with some characters stripped do not), and where its paths come
+   from (constants and a file name a `switch` picks clear it; names stored
+   in a database or file are their own option). A page that reads a request
+   also joins ids converted with `intval` and database errors, and the
+   markup check found those at 0.9 while the origin question answered for
+   the request. A markup check that found a variable which the Choice names
+   as a request value or stored record is a review whatever the origin
+   question said: an access log joining user names from the database stayed
+   uncertain with the origin split. A page script's consider or note names
+   values whose origin it does not show, not parameters. On DVWA the PHP
+   Choices left 13 of 329 injection units undecided, from 46.
+   Agent instruction files (`src/docs/`) are found by name even when hidden
+   or ignored, including Kiro steering files, Junie guidelines and rules,
+   and Roo Code rules, each loaded by its harness's documented rules (a Kiro
+   `inclusion`, a Roo Code mode folder, Junie's precedence of its own
+   `AGENTS.md`). Each file's heading sections, or the top-level blocks of a
+   long section, are sent packed, within runs of sections that end after a
+   heading hashing to one of four values (a long section's blocks share its
+   heading and stay together; brstocks `CLAUDE.md` went from 1 request to
+   4, billing 18% more input on a full run and 57% less when one section
+   is removed), beside the nearest manifests (with the
+   runtime versions they require: `engines`, `packageManager`,
+   `requires-python`, `rust-version`), the configured linters and the
+   directories. A section whose signals stay undecided is asked, alone,
+   which kind of section it is (instructions, a description, a command
+   list, generic advice or a record): its own kind at 0.80 raises the
+   undecided signal, that kind at 0.20 or less clears it, and instructions
+   clear an undecided "restates the repository". On vercel/ai, API tables and
+   import maps stayed near the middle on "only describes", while naming the
+   kind was decisive. The linter question asks whether a section is only
+   style the listed tools check with their usual settings; asked whether it
+   asked for such style, a list of `Do Not` rules with one import rule, or
+   file naming no configured rule checks, stayed undecided.
+   Code decides which harness loads each file and
+   when, from its documented discovery rules. It also records loading facts:
+   copies, unresolved imports, and files a harness skips or truncates. These
+   are reported, never judged.
+   Project documentation is Markdown, MDX, reStructuredText or AsciiDoc,
+   read as Markdown with the file's own lines (`src/docs/format.rs`): MDX
+   drops imports, exports, comments and component markup but keeps the prose
+   components carry, reStructuredText titles become headings by the order of
+   their adornment styles, AsciiDoc titles by their `=` level, comments and
+   attribute entries are dropped, and code directives, literal and listing
+   blocks are fenced with their language. A document of 300 or more lines is
+   sent as its headings only, with `#` marks for nesting. A split finding is
+   then located with one Choice among its top-level parts; a split that stays
+   undecided is asked which kind of document it is (a guide, a reference, a
+   migration guide, an introduction, or a collection of unrelated subjects).
+   The kinds that serve one subject at 0.80 clear it and a collection at
+   0.80 raises a consider: a quickstart, a migration guide and a package
+   README each stayed near a third per level on the split.
+   Per-section questions on
+   project docs were dropped: on a labeled sample they found almost nothing,
+   and they cost about five times more than an outline.
+   Staleness and duplication candidates come from code. Staleness candidates
+   are paths and scripts a section names that the repository lacks, with what
+   Git shows about each. A span written with a code role (`:attr:`,
+   `:class:`) is not a path, nor is a link that climbs above the repository
+   (a README badge's `../../actions/...`); a path the ignore files cover
+   (a bare name also as a directory, so `backend/app/frontend/` covers a
+   build output), or one the section writes out for a code block (its
+   `filename=`, or the one path the paragraph before it names), is the
+   reader's own; a script where no command starts, such as "make sure", is
+   not one, and dependencies count as scripts, since `pnpm tsx` runs one. A
+   missing name whose one tracked namesake sits under the document's
+   directory, such as `.tsx` for `.ts`, is named beside it. A check that
+   stays undecided is asked, apart, what the section treats the names as (a
+   current part of the repository, the reader's own project, an example,
+   not a file at all, or something removed); the repository at 0.20 or less
+   clears it. A protocol method (`tools/call`), skill-relative example
+   paths and a migration guide's `pnpm drizzle-kit` stayed near 0.25 to
+   0.50 on the check and were decisive as a kind.
+   Duplication candidates are section pairs where 30%
+   of the smaller section's three-word sequences recur in the other, at most
+   three per pair of documents. Sequences come from the prose; a section
+   with too little prose is compared on its prose, commands and settings,
+   and program code is never compared: pairing on code sent hundreds of
+   vercel/ai pages that shared a `streamText` call and nothing else. Project
+   documents of separate packages are not paired, since each package's
+   README is read alone. A section that pairs with two or more others heads
+   a family, and its members are asked against it alone. A document whose release is tagged, or whose
+   named paths were deleted, is asked from its headings whether it is a plan;
+   a plan with those facts is one finding, and its own candidates are not
+   asked. The section check and the pair questions (does A state everything
+   B states, and the reverse, as Scores whose middle "mostly" is acceptable;
+   do they disagree, a Score whose middle "only in detail" is acceptable; are
+   they about one subject; is one a translation of the other?) are
+   follow-ups for the other documents, sent with each document's title. A
+   translation clears the repetition answers but not a disagreement.
+   Different subjects settle what stays undecided, never a decided answer.
+   A pair still undecided is asked, apart, how the two sections relate
+   (one repeats the other, they overlap, they are written alike for
+   different subjects, they contradict each other, or they describe
+   different things); a repetition or a contradiction at 0.20 or less
+   clears that check. Weighing coverage stayed near the middle for one step
+   of two quickstarts or one option of guide and reference, while naming
+   the relation was decisive: 18 of 654 pairs undecided on vercel/ai became
+   1. The repetition findings that share a section are one finding at the
+   section most of them name, listing the others. A Score on how much two
+   sections overlap, asked of every pair, stayed on its middle level for
+   almost every pair, so it is not asked.
+   Code comments (`documentation/comments`) are collected from the parse
+   tree of application code, outside tests: runs of line comments on
+   consecutive lines are one comment, and Python docstrings are comments of
+   the definition or module they open. License headers, tool directives
+   (`eslint-disable`, `# noqa`, `//go:`), JSDoc type annotations, shebangs
+   and comments without letters are left out. Each comment is sent with the
+   code it is about: the declaration it documents (its signature when
+   longer than 40 lines), the lines below it up to a blank line, another
+   comment or the end of its block, the line it ends, or for a file's own
+   documentation the signatures of its definitions; with where it sits and
+   the signature of the definition it sits in. Comments are packed eight per
+   request within runs of definitions, a run ending after a definition
+   whose name hashes to one of four values, so a comment added or removed
+   re-asks only its run: packed in file order, one added comment re-sent
+   every later pack of the file (6 of 6 requests of `compose.rs`, against 1
+   now), and a pack per definition doubled the requests. They are asked
+   whether they only repeat that code (a Score whose
+   middle level holds headings over a group of lines), whether sentences
+   could go without losing anything (only comments of 20 or more words),
+   whether they describe an edit instead of the code as it is, and whether
+   they are code turned off (only comments whose lines read like
+   statements). Asked of every comment, those two stayed near 0.5 on
+   two-word trailing comments and on docstrings holding usage examples;
+   asked only where they apply, psf/requests' undecided comments went from
+   78 of 519 to 63 with the code check and to 35 with the wordiness one. The first
+   wording of the wordiness question ("could it say the same in far fewer
+   words?") called every multi-line JSDoc block that explains a rounding
+   rule or a matching strategy wordy; asked whether sentences add nothing,
+   with parameter entries named by whether the signature writes their
+   types, the Sphinx `:param` entries of untyped functions stopped reading
+   as filler while `numerator: The numerator value.` still does. A flag's
+   meaning (`"-x",  # Extract audio`), a unit (`// 16px` beside
+   `1rem`) and a category heading (`// Fixed` above fixed costs) are
+   named as acceptable. A comment left undecided is asked again with the
+   whole definition it sits in, then, alone, what kind of comment it is (a
+   reason, caveat, reference, usage, summary or heading, against repeating
+   the code, narrating steps, an edit or code turned off).
+   SQL files (`security/access-control`) are split into statements that honor
+   comments, quotes and dollar quotes. Each project's files, grouped above
+   their `supabase` or `migrations` directory, are read in path order, so a
+   dropped or replaced policy or function is not judged. Each policy is sent
+   with its table, the functions it calls, and the functions that set the
+   token claims it reads, such as a custom access token hook: without the
+   hook, 63 of one project's policies stayed undecided on whether users can
+   change the claim. A SECURITY DEFINER function goes with its grants and
+   revokes of EXECUTE; a grant with whether its table has row-level security.
+   The criteria name role checks, service roles, restrictive policies and
+   trigger functions, which a literal "other users' rows" question flagged.
+   SpacetimeDB modules (TypeScript files that import `spacetimedb/server`,
+   Rust files with `#[table]`, `#[reducer]` or `#[view]` attributes) are read
+   for access control too, whatever the application: each public table with
+   the columns that name users, and each view and reducer with up to six functions it calls (two
+   deep, in the module's package). Lifecycle reducers are left out; a Rust
+   reducer is sent with the table line that schedules it (`scheduled_by`), since
+   the schedule is declared on the table. The framework version comes from the
+   package's `package.json` or `Cargo.toml`, since scheduled reducers are
+   private in 2.x and callable by clients in 1.x; with no version, both are
+   stated. Each definition gets a Score whose two lower
+   levels are acceptable (the caller's own data; data meant for every user)
+   and concern Nouls: for a reducer, two literal checks (a row chosen by an
+   argument without an ownership check; an admin-only change without checking
+   the owner, an admin or a granting role). One broad Noul left most real definitions undecided and
+   most broken reducers under 0.80. When access control is the only code
+   rule, only the files of module packages are collected.
+   Workflow jobs (`security/workflows`) are split by indentation. The parser
+   lists the `${{ }}` expressions inside `run` scripts, and Jev is asked
+   whether one can hold text outside people write: one question over the
+   whole job scored obvious injections 0.57 to 0.79. Jobs of workflows that
+   run on `pull_request_target` or `workflow_run` are asked whether they run
+   pull request code with secrets.
+5. **Composition** (`src/units/compose.rs`). Pure. On a Score whose top level is
+   the actionable concern: review at 0.80 on the top level, consider at 0.80 on
+   middle-or-top, clear when the top level is ruled out at 0.80, otherwise
+   uncertain. Where the middle level says the code is fine as it is, a consider
+   also needs the top level at 0.50; middle mass alone is an optional note. For hardcoded values and security, an answer still
+   undecided after its follow-up is a note when it leans toward the concern
+   (0.50, the leading probability) and stays uncertain otherwise: undecided
+   answers leaning away were almost all acceptable code, and leaning toward
+   held both real positives of the labeled set. When the own-messages check
+   finds another error's text in an error message, an error-detail answer
+   leaning toward a client is a consider. Instruction sections are
+   cleanups, so their findings are at most a consider. Comments are cleanups
+   too: at most a consider, and documentation that only repeats the
+   declaration it documents is at most a note, since documentation tools and docstring
+   linters expect a summary even when it says what the name says. A
+   definition's comments that reach a consider are one finding, listing
+   each comment with what is wrong with it, and when they span fewer than
+   three lines in all they are a note. Undecided answers do not
+   lean into notes, because on the labeled set that added notes to kept sections.
+   A large document's undecided history answer does lean into a note. Policies,
+   grants and an open `search_path` are at most a consider, since a policy
+   may cover data meant for everyone; an unchecked SECURITY DEFINER function
+   and workflow findings can be reviews. A SpacetimeDB definition is a review
+   when a concern Noul or the Score's top level reaches 0.80, and clear when
+   the Score's acceptable levels do and nothing is at review; public tables
+   and views are at most a consider, reducers can be reviews. A
+   hardcoded-value review or consider whose value the locate Choice could not
+   name is one level lower. Messages show the probability that set a finding's
+   level (a consider shows the middle-or-top mass, not the top level); notes
+   show none. Finished plans in one directory become one finding identified by
+   the directory, and the others become notes pointing at it. On its
+   labeled set, no living document leaned past 0.50. Questions ask whether a change would help a reader ("would splitting
+   it make it easier to understand?"), not how many tasks or purposes there are:
+   Jev does not count reliably and reads "tasks" literally. Copies inside test
+   cases are one level lower. Copies of three lines or fewer are at most a
+   consider: in Java such a copy was as often an idiom, a pooled builder
+   borrowed and released around one call, as a missing helper. A test that
+   checks several unrelated behaviors is at most a note: on labeled tests,
+   tables of inputs and browser journeys rated as high as tests that really
+   mix behaviors. Overlapping test pairs of one subject become one consider
+   for three or more tests only when the pairs connect them: two pairs that
+   share no test stay two pairs (a pair of redirect tests and a pair of deny
+   tests of `get` are not four overlapping tests). A review always carries a
+   finding.
+6. **Gate.** `--fail-on`, `[[scope]]` levels per path and the baseline act on
+   composed findings only. Baseline entries can carry a reason (`intended`,
+   `later`, `wrong`) that survives rewrites; `baseline stats` counts them.
+
+### Constraints
+
+- Syntax supplies units, candidates, locations and eligibility (size, nesting),
+  never verdicts; a unit below an eligibility floor is too small, never clear.
+- Keep questions atomic and literal; no thresholds, hashes or self-descriptions in
+  uploaded state or questions.
+- Preserve raw answers, uncertainty and needs-context outcomes.
+- Version question wording (`units::questions::VERSION`) and composition
+  (`schema::COMPOSITION`); question changes invalidate the cache by content.
+- Validate on small frozen sets through the CLI; keep results in ignored
+  `.jevgate/evaluation/`.
diff --git a/site/src/install.md b/site/src/install.md
new file mode 100644
index 0000000..e6d01b9
--- /dev/null
+++ b/site/src/install.md
@@ -0,0 +1,14 @@
+# Install
+
+```sh
+brew install tech-byte-frontier/tap/jevgate   # macOS and Linux, with Homebrew
+curl -fsSL https://raw.githubusercontent.com/Tech-Byte-Frontier/jevgate/main/install.sh | sh   # Linux and macOS
+cargo binstall jevgate            # any platform, with cargo-binstall
+cargo install jevgate --locked    # build from source; needs Rust 1.90 or later
+```
+
+Each [release](https://github.com/Tech-Byte-Frontier/jevgate/releases) has binaries for Linux (x86_64 and arm64, static), macOS (Apple silicon and Intel) and Windows (x86_64), with SHA-256 checksums and build provenance: `gh attestation verify <archive> --repo Tech-Byte-Frontier/jevgate`. The install script checks the checksum and installs to `~/.local/bin`; set `JEVGATE_VERSION` or `JEVGATE_INSTALL_DIR` to change the version or place.
+
+`jevgate completions bash|zsh|fish|powershell` prints a shell completion script and `jevgate man` a man page; Homebrew installs both.
+
+Reviewing needs a [TypeSafe API key](https://console.typesafe.ai/settings/keys). Git is needed only for `--base` and the staleness rule.
diff --git a/site/src/introduction.md b/site/src/introduction.md
new file mode 100644
index 0000000..f4c58bf
--- /dev/null
+++ b/site/src/introduction.md
@@ -0,0 +1,27 @@
+# JevGate
+
+**JevGate is a code-review gate. It asks small, precise questions about your code and turns the answers into findings you can act on.**
+
+JevGate parses your repository locally and builds small units of evidence: a function, a file outline, a pair of copies, a test, a documentation section. It asks [TypeSafe Jev](https://docs.typesafe.ai) short, typed questions about each one. Code, not a chat model, combines the answers into a verdict. Each finding has a location, a probability and a concrete next step, so an agent or CI job can act on it and a person can check it quickly.
+
+```text
+JevGate: consider · gate passed · 42 files · 118 API requests · 263410 input tokens · ~$0.0111
+
+Consider (2):
+  src/billing/invoices.ts:88 [maintainability/shared-logic] `createInvoice` and `createReceipt`
+    perform the same steps for the same purpose (0.93). Differences: `invoices`→`receipts`.
+    → Move the shared steps into one implementation
+  src/api/search.py:41 [security/injection] `search_orders` places its parameters into a
+    database query without binding, escaping or checking them; a caller passing outside
+    input would make it exploitable (0.88).
+    → Pass the values as bound query parameters
+```
+
+## Where to start
+
+- [Install](install.md) and follow the [quick start](quick-start.md): a dry run shows exactly what would be uploaded, free and offline.
+- [What it finds](what-it-finds.md) and the [rules reference](reference/rules.md) describe every rule and the question it asks.
+- [Continuous integration](ci.md) sets JevGate up on pull requests with the GitHub Action, pre-commit or any other CI.
+- [How it works](how-it-works.md) explains the evidence units and how code, not a chat model, turns answers into findings.
+
+JevGate is open source under MIT or Apache-2.0: [source, issues and releases on GitHub](https://github.com/Tech-Byte-Frontier/jevgate).
diff --git a/site/src/languages.md b/site/src/languages.md
new file mode 100644
index 0000000..da3a116
--- /dev/null
+++ b/site/src/languages.md
@@ -0,0 +1,48 @@
+# Supported languages and frameworks
+
+✅ judged · ➖ not applicable
+
+| Language or file | Extensions | Maintainability | Tests | Security | Documentation |
+|---|---|:---:|:---:|:---:|:---:|
+| Rust | `.rs` | ✅ | ✅ `#[test]`, `#[cfg(test)]` | ✅ | ✅ comments |
+| Python | `.py` | ✅ | ✅ pytest, unittest | ✅ | ✅ comments |
+| JavaScript | `.js` `.jsx` `.mjs` `.cjs` | ✅ | ✅ `describe`/`it`/`test` | ✅ | ✅ comments |
+| TypeScript | `.ts` `.tsx` `.mts` `.cts` | ✅ | ✅ `describe`/`it`/`test` | ✅ | ✅ comments |
+| Go | `.go` | ✅ | ✅ `Test…(t *testing.T)` | ✅ | ✅ comments |
+| C# | `.cs` | ✅ | ✅ xUnit, NUnit, MSTest | ✅ | ✅ comments |
+| Ruby | `.rb` | ✅ | ✅ RSpec, Minitest, Rails `test "…" do` | ✅ no Ruby framework handlers yet | ✅ comments |
+| PHP | `.php` `.phtml` | ✅ | ✅ PHPUnit `…TestCase` classes, Pest `test`/`it` | ✅ | ✅ comments |
+| Java | `.java` | ✅ | ✅ JUnit 4 and 5, TestNG: `@Test`, `@ParameterizedTest`, `@Nested`, JUnit 3 `TestCase` | ✅ | ✅ comments |
+| Astro, Vue, Svelte | `.astro` `.vue` `.svelte` | ✅ scripts only | ➖ | ✅ scripts only | ✅ script comments |
+| SQL (PostgreSQL, Supabase) | `.sql` | ➖ | ➖ | ✅ access control | ➖ |
+| GitHub Actions | `.github/workflows/*.yml` | ➖ | ➖ | ✅ workflows | ➖ |
+| Markdown, MDX | `.md` `.mdx` at the root, in `docs/` or `doc/`, READMEs and CONTRIBUTING files; agent instruction files | ➖ | ➖ | ➖ | ✅ |
+| reStructuredText, AsciiDoc | `.rst` `.adoc` `.asciidoc`, in the same places | ➖ | ➖ | ➖ | ✅ |
+
+| Framework or platform | What JevGate understands |
+|---|---|
+| Hono, Express, Fastify, Koa | Route handlers written inline (`app.post('/pages', async (c) => …)`); error handlers (`app.onError`, `setErrorHandler`, four-parameter Express middleware) |
+| NestJS | Exception filters (`@Catch`) |
+| Next.js (App Router and Pages Router) | Route handlers (`app/**/route.ts`), Server Actions (`'use server'` files and functions), `pages/api` routes, middleware, client components, error boundaries and pages are named to Jev with who calls them and where they run, so a Server Action's arguments read as client input and a client component's requests as the user's own; `dangerouslySetInnerHTML`, redirects to client-chosen URLs, raw Prisma and Drizzle queries (`$queryRawUnsafe`, `sql.raw`) as opposed to their binding tagged templates, `NEXT_PUBLIC_` secrets, and `next.config` headers |
+| SvelteKit | Server load functions and form actions (`+page.server.js`, `export const actions = {…}`), endpoints (`+server.js`) and server hooks are named to Jev with who calls them, so their request, form data, URL and cookies read as client input, and `cookies.set` is read with its secure defaults |
+| Flask, FastAPI | Error handlers (`@app.errorhandler`, `@app.exception_handler`) |
+| Django, Django REST framework | Views and viewsets with the URL routes that reach them, the templates they render with `\|safe` or autoescaping off, and the module constants they use; settings modules, with secret literals redacted, the settings modules that import and override them, and the files that select them (`DJANGO_SETTINGS_MODULE`); management commands as run by hand; `handler500`-style error views, middleware `process_exception` and `EXCEPTION_HANDLER` as error handlers |
+| PHP pages, Slim, Laravel | A file's top-level code is judged like a function, since a page script reads the request and writes the response; route closures (`$app->get('/users', function …)`, `Route::post(…)`) and configuration closures (`return function (App $app) {…}`); error handlers (`set_exception_handler`, subclasses of Slim's `ErrorHandler` and Laravel's `ExceptionHandler`) |
+| axum, actix-web, Rocket | Error responses (`IntoResponse` or `ResponseError` for an error type, `#[catch]`) |
+| MDX sites (Next.js, Nextra, Docusaurus, Astro) | Imports, exports, comments and component markup are dropped, but the prose components carry (a `<Note>`'s text, a properties table's descriptions, with names and types as code) is read; frontmatter `title` names the page |
+| Sphinx, AsciiDoc | Section titles by their adornment or `=` level; comments, attribute entries and options dropped; code directives, literal and listing blocks read as code; `:file:` and `include::` targets checked as paths, `:attr:` and `:class:` read as code, and `_build/` skipped |
+| ASP.NET Core | Controller actions, minimal API route handlers (`app.MapGet("/orders", …)`) and inline middleware; exception handlers (`UseExceptionHandler` with a handler, `IExceptionFilter`, `IExceptionHandler`, middleware classes that catch what the pipeline throws); Entity Framework Core raw and interpolated SQL, CORS and cookie options, `UseDeveloperExceptionPage`, JWT validation options and the constants a setup names |
+| .NET projects | Test projects named like `Shop.Tests` or `Shop.UnitTests`, and classes of `[Fact]`, `[Theory]`, `[Test]` or `[TestMethod]` methods anywhere; designer and source-generated files (`.Designer.cs`, `.g.cs`) are skipped as generated |
+| Supabase and PostgreSQL | Row-level security policies, `SECURITY DEFINER` functions, grants, and the claims an access token hook sets |
+| SpacetimeDB (TypeScript and Rust modules) | Public tables, views and reducers, checked against the caller (`ctx.sender`) and the framework version's scheduling rules |
+| React | JSX components and hooks as functions; text shown as a JSX child is not treated as markup injection |
+| RSpec, Minitest | Examples with the groups they are declared in, the `before` hooks and the `let`/`subject` definitions they read, and the helpers they call from support files such as `spec/support` and `test_helper.rb` |
+| Sinatra and other Ruby DSLs | Methods of classes and modules (`def`, `def self.`, `class << self`, `define_method`); blocks passed at class or file level as units named by their call (`get('/invoices')`); constants as hardcoded values |
+| Monorepos and examples | Copies are compared within a package and across packages linked by a local dependency, not across separate example apps, templates or variants of one example (`examples/login/raw` and `examples/login/sdk`); copies inside example code are notes |
+| Java classes | Methods and constructors belong to their class, interface, enum constant or record; `static` fields are constants; `equals` and `hashCode` overrides, constructors storing fields and setters given literals are boilerplate or data, never copies; initial capacities and a number a method returns whole are not values to name; a class of the same package counts as imported |
+| Spring MVC | A MockMvc or RestTemplate test request reaches the controller method whose `@GetMapping`, `@PostMapping` or `@RequestMapping` route serves it, so the test is judged with that method as its code under test |
+| Bundlers and compilers | Minified and compiled output (a source map reference, very long lines) is skipped as generated |
+| Copied libraries | A library copied into the repository (a versioned file name such as `jquery-3.6.0.js`, the readable build beside a `.min.js`, a license banner naming a version, or a script under `assets`, `static` or `vendor` that opens with a whole license and copyright) is skipped as vendored, whatever its size |
+| Migrations | Directories named `migrations`, Rails' `db/migrate` and timestamped scripts under `db/`, and Alembic's `alembic/versions` are skipped as migrations; SQL migrations are still read for access control |
+
+Other files, such as Kotlin, are listed as skipped with the reason and never fail the gate.
diff --git a/site/src/limits.md b/site/src/limits.md
new file mode 100644
index 0000000..099b274
--- /dev/null
+++ b/site/src/limits.md
@@ -0,0 +1,6 @@
+# Limits
+
+- **Languages and frameworks:** see [the support table](languages.md). Astro, Vue and Svelte markup is not read, only their scripts. PHP's inline HTML is read only for its `<?= … ?>` echoes, and variables a page gets from the files it includes are not followed there: they are judged where those files set them.
+- **Security scope:** one function plus at most one hop of callers. This is not whole-program data-flow analysis. Access control reads the final state of policies, SECURITY DEFINER functions and grants across a project's SQL files in path order, leaving out uninstall, teardown, rollback and down scripts; with `--base`, unchanged migrations are read for that state but not judged. It does not judge application-level authorization or dynamic SQL inside database functions.
+- **Documentation scope:** staleness works only from the paths, scripts, tags and deletions that Git and the manifests show; it does not compare prose with code behavior. Paraphrases that share little wording are not found as duplicates, nor are code examples that share only code; a translation is not a duplicate. Sphinx and AsciiDoc includes are not followed, and MDX expressions are not evaluated. A code comment is judged with the code next to it, not against what the whole program does, so a comment that no longer matches its code is not found. Token counts are estimates at four bytes per token.
+- **Probabilities:** these are model judgments, not measured accuracy. JevGate complements linters, type checkers, tests and dedicated security scanners; it does not replace them.
diff --git a/site/src/output.md b/site/src/output.md
new file mode 100644
index 0000000..e2a6fbe
--- /dev/null
+++ b/site/src/output.md
@@ -0,0 +1,23 @@
+# Output and exit codes
+
+| Format | Use |
+|---|---|
+| `agent` (default) | Ranked findings with locations and next steps, for people and coding agents |
+| `json` | The full report: every file, finding, raw answer and probability, gate and usage |
+| `jsonl` | One compact report per line; one per evaluation with `--watch` |
+| `github` | GitHub Actions annotations and job summary, then the agent text |
+| `sarif` | A SARIF 2.1.0 log for [GitHub code scanning](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github) and other SARIF readers: the findings the annotations show, `error` when they fail the gate |
+
+Agent output is colored on a terminal; `--color never`, or `NO_COLOR` set to any value, turns it off, and `--color always` or `CLICOLOR_FORCE` turns it on for pipes and logs.
+
+Findings are `review` (act on it), `consider` (worth a look) or `note` (optional, shown with `--verbose`, never failing the gate). A file whose answers stay undecided is `uncertain`, and one that cannot be judged without more evidence is `needs-context`; neither is hidden or counted as clear. A finding's message shows the probability that set its level; a note shows none, and the JSON report keeps every raw value. Finished plans that share a directory are one finding. A hardcoded-value finding that cannot name its value is one level lower.
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Gate passed, or no supported file changed since `--base` |
+| 1 | Gate failed |
+| 2 | Run incomplete, invalid configuration or invalid usage |
+
+`--fail-on review|consider|uncertain|none` sets what fails the gate; `--fail-on security=consider` sets it for one group or rule. Baselined findings and notes never fail it.
+
+`jevgate baseline` can record why each finding was accepted: `intended` (right, and meant to be so), `later` (right, to fix later) or `wrong` (mistaken), with `--reason` or `jevgate baseline mark`. Reasons survive later rewrites of the baseline, and `jevgate baseline stats` reports each rule's share of findings marked wrong: labels from daily use, not the model's own probabilities.
diff --git a/site/src/privacy-and-cost.md b/site/src/privacy-and-cost.md
new file mode 100644
index 0000000..25992e4
--- /dev/null
+++ b/site/src/privacy-and-cost.md
@@ -0,0 +1,7 @@
+# Privacy and cost
+
+- **What is uploaded:** only the selected units of source, bounded by `upload_allow` and `upload_deny`. `--dry-run --show-requests` prints every initial request body without credentials or network access.
+- **Instruction files:** uploaded only when a documentation rule is selected, and still bounded by the upload patterns.
+- **Credentials:** a check reads `TYPESAFE_API_KEY` from the environment, then `--env-file` or the repository's `.env`, then the key saved by `jevgate auth login` (OS credential store, or an owner-only file). The key is never printed or written to reports.
+- **Cost:** every run prints its input tokens and an estimated cost. Cached answers cost nothing.
+- **Secrets:** out of scope on purpose, because judging secrets would mean uploading them. Use a local secret scanner.
diff --git a/site/src/quick-start.md b/site/src/quick-start.md
new file mode 100644
index 0000000..d9717e1
--- /dev/null
+++ b/site/src/quick-start.md
@@ -0,0 +1,26 @@
+# Quick start
+
+```sh
+jevgate init                              # write a commented jevgate.toml for this repository
+jevgate auth login                        # validate and save your TypeSafe API key
+jevgate check --dry-run --show-requests   # see exactly what would be uploaded; free and offline
+jevgate check --report                    # review, then open a local HTML dashboard
+jevgate baseline                          # accept today's findings; later checks fail only on new ones
+```
+
+More ways to run it:
+
+```sh
+jevgate check src/billing --verbose               # one directory, with notes and per-file detail
+jevgate check --rule default --rule security      # add the security group
+jevgate check --rule documentation                # agent instruction files, project docs and code comments
+jevgate check --rule comments                     # only code comments
+jevgate check --include-tests                     # also judge tests
+jevgate check --base origin/main --format json    # changed files only, for agents and scripts
+jevgate check --watch                             # re-check on save
+jevgate baseline --merge                          # after a --base or path check: accept its findings, keep the rest
+jevgate baseline mark wrong src/api/search.ts:41  # record why an accepted finding was accepted
+jevgate baseline stats                            # each rule's rate of findings marked wrong
+```
+
+Every command documents itself: `jevgate --help` gives the workflow, exit codes, files and environment, and `jevgate check --help` explains each flag and the JSON report. `-h` prints a short summary.
diff --git a/site/src/troubleshooting.md b/site/src/troubleshooting.md
new file mode 100644
index 0000000..f911a55
--- /dev/null
+++ b/site/src/troubleshooting.md
@@ -0,0 +1,41 @@
+# Troubleshooting
+
+## The run exits 2
+
+Exit code 2 means the run could not finish, or the configuration or command line is invalid. The message says which; an outage never passes as a clean review.
+
+**`No API key configured. Run jevgate auth login, set TYPESAFE_API_KEY, or provide --env-file PATH`**
+: A check reads `TYPESAFE_API_KEY` from the environment, then `--env-file` or the repository's `.env`, then the key saved by `jevgate auth login`. `jevgate auth status` shows which one a check would use and verifies it. On GitHub Actions, pull requests from forks don't receive secrets: skip the job for them (`if: github.event.pull_request.head.repo.full_name == github.repository`).
+
+**`Cannot find revision …; in CI, fetch it (for example fetch-depth: 0)`**, or **`… and HEAD share no history`**
+: `--base` needs the history back to the fork point. Check out with `fetch-depth: 0`.
+
+**`TypeSafe HTTP 403 (blocked by the provider's edge protection)`**
+: The provider's firewall rejected a request because of what it contained, such as a test fixture holding an attack string. Find the file with `--dry-run --show-requests`, and exclude it with `upload_deny`; JevGate's own repository does this for its HTML report's escaping test.
+
+**`Cannot connect to TypeSafe; request was not sent`**
+: A network problem before anything was sent. Rerun; cached answers are kept.
+
+**`Session API request budget exhausted; restart with an explicit larger --max-requests`**
+: `max_requests` or `--max-requests` capped the run. Raise it, or check fewer files with `--base` or paths; `--dry-run` estimates what a run will ask.
+
+**`Another JevGate session owns latest.json`**
+: Another `check` or `--watch` is running in the same repository. Stop it first.
+
+Rate limits, overload and server errors (HTTP 408, 429, 500, 502–504, 520–524, 529) are retried up to four attempts before the run gives up, and a timeout or dropped connection is retried once.
+
+## Many files are uncertain
+
+A file is `uncertain` when some of its answers stayed undecided after the follow-up questions. JevGate reports this instead of hiding it or counting the file as clear. `--verbose` lists each undecided unit and the question it stayed undecided on. It never fails the gate unless you ask for that with `--fail-on uncertain`.
+
+## A finding is wrong
+
+Accept it with `jevgate baseline`, and record why with `jevgate baseline mark wrong PATH:LINE`; `jevgate baseline stats` counts each rule's mistaken findings. Reporting it with the [wrong finding template](https://github.com/Tech-Byte-Frontier/jevgate/issues/new?template=wrong_finding.yml), with the finding from `.jevgate/latest.json` and a small piece of the code, is how the rules improve.
+
+## A file is skipped
+
+Skipped files are listed with the reason: generated, vendored or minified code, migrations, an unsupported language, or a path outside the upload patterns. `generated`, `tests` and the upload patterns in `jevgate.toml` change what is selected. A file larger than `max_file_bytes` is not skipped but reported as `needs-context`, never truncated.
+
+## No colors, or escape codes in a log
+
+Agent output is colored only on a terminal. `--color never` or `NO_COLOR` turns it off, and `--color always` or `CLICOLOR_FORCE` turns it on for pipes and logs.
diff --git a/site/src/what-it-finds.md b/site/src/what-it-finds.md
new file mode 100644
index 0000000..5c5a063
--- /dev/null
+++ b/site/src/what-it-finds.md
@@ -0,0 +1,41 @@
+# What it finds
+
+**Maintainability** (on by default)
+
+| Rule | Example finding |
+|---|---|
+| File organization | This file holds several features that would be easier to find apart; the upload helpers would be most useful as their own module. Test files are judged too, at most as a consider. |
+| Function simplification | `sync_accounts` mixes separate jobs in long blocks; lines 40–71 would be most useful as their own function. |
+| Shared logic | `createInvoice` and `createReceipt` perform the same steps; one shared implementation would serve both. |
+| Hardcoded values | Module constants fix a value that differs between deployments; `apply_discount` special-cases one specific customer. |
+
+**Tests** (with `--include-tests`; file organization judges test files without it)
+
+| Rule | Example finding |
+|---|---|
+| Test value | `test_total` computes its expected value with the logic it tests. |
+| Test redundancy | Three tests of `parse_date` check the same behavior; one parameterized test could hold them. |
+
+**Security** (opt-in with `--rule security`; each finding names a CWE)
+
+| Rule | Covers |
+|---|---|
+| Injection | Variables reaching SQL, shell commands, evaluated code, HTML, file paths, outbound URLs or redirect targets without binding, escaping or checks; in C#, types named by input or chosen by the data being deserialized; in Django code, request data given to `pickle` or `yaml.load`; in PHP, `unserialize` and uploaded file names |
+| Sensitive data | Passwords, tokens or personal data written to logs; internal error details sent to clients, judged per error message and once per error handler (`app.onError`, `setErrorHandler`, Express error middleware, Flask and FastAPI handlers, Django error views and `process_exception` middleware, Django REST framework's `EXCEPTION_HANDLER`, NestJS filters, axum `IntoResponse` and actix-web `ResponseError` for error types, ASP.NET Core exception handlers, PHP `set_exception_handler`, Slim and Laravel handler classes); in Django code, also the server's environment or settings sent to clients (`request.META`) |
+| Unsafe settings | Certificate checks turned off, weak password hashing, non-cryptographic random secrets, permissive CORS, session cookies without `Secure`/`HttpOnly`, secrets in environment variables the build puts into browser code (`NEXT_PUBLIC_`, `VITE_`); in C#, also developer exception pages outside development, token signature or lifetime checks turned off, signing keys written in the code, and secrets derived from data others know; in Django code, also debug mode for the deployed site, `csrf_exempt` views and secret keys written in settings |
+| Access control | SQL row-level policies that let every user reach other users' rows or trust `user_metadata`; SECURITY DEFINER functions without a fixed `search_path` or a caller check; grants that open writes to every user. SpacetimeDB modules (TypeScript and Rust, any kind of application): public tables of users' private data, views that return other users' rows, reducers that change rows their arguments choose or admin-only settings without checking the caller, and scheduled reducers clients can call in 1.x |
+| Workflows | GitHub Actions `run` scripts that execute text outside people write (`${{ github.event.pull_request.title }}`); `pull_request_target` or `workflow_run` jobs that run pull request code with secrets |
+
+**Documentation** (opt-in with `--rule documentation`)
+
+| Rule | Example finding |
+|---|---|
+| Agent context | A section of `CLAUDE.md` only lists the scripts `package.json` already shows, and six harnesses load it at the start of every session. |
+| Large docs | `docs/operations/runbook.md` holds several unrelated subjects; `docs/plans/v0.2-plan.md` mainly records finished work. |
+| Staleness | `docs/plans/v0.4-auth.md` is a plan whose work is finished: the repository has a release tag v0.4.0, and 6 paths it names were since removed. |
+| Duplication | Section `Release Workflow` of `CLAUDE.md` states everything section `Release` of `README.md` states. |
+| Code comments | `save_skill` has 3 comments to clean up: at lines 214, 218 and 222 they repeat the code (`# Create skill directory` above `skill_dir.mkdir(…)`). A module docstring saying it was "split out of `portfolio.py` to stay under the 500-line budget" narrates an edit instead of the code as it is. |
+
+The documentation rules read the instruction files that coding agents load (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and Claude, Cursor, Copilot, Windsurf, Cline, Kiro, Junie and Roo Code rules), even when hidden or gitignored. Each section is asked whether it only restates the stack, the manifest's commands, generic advice or a configured linter's rules, and whether text loaded in every session applies to only one directory. Project documentation in Markdown, MDX, reStructuredText or AsciiDoc of 300 or more lines is judged from its headings alone. Code finds staleness and duplication candidates: named paths or scripts that no longer exist, release tags, deleted files, and shared wording outside code examples. Jev then judges each candidate. Code comments and docstrings of application code are judged one at a time with the code they are about (the declaration they document, the lines below them or the line they end): whether they only repeat that code, hold sentences that add nothing, narrate an edit instead of the code as it is, or are code turned off. License headers, tool directives, type annotations, authorship tags and Sphinx version notes are left out; documentation that only repeats its declaration or says it at length (framework section banners included) is at most a `note`, as is every such comment in a project whose README says its code is written for learners; and the comments of one definition that span fewer than three lines in all are a `note`. Documentation findings are at most `consider`. The run also estimates the tokens each harness loads at session start; these estimates are evidence and never fail the gate.
+
+`jevgate rules` prints every rule with its question and default; the [rules reference](reference/rules.md) lists them with what each one looks at.

From b927883e657a73c0f1c1ccd53c9f2b2ce32e1e25 Mon Sep 17 00:00:00 2001
From: Tauan BF <11513929+tauanbinato@users.noreply.github.com>
Date: Fri, 25 Sep 2026 19:26:06 -0300
Subject: [PATCH 2/2] Name the coding agents page so AGENTS.md's ignore rule
 misses it

---
 site/src/SUMMARY.md       |  2 +-
 site/src/coding-agents.md | 41 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 site/src/coding-agents.md

diff --git a/site/src/SUMMARY.md b/site/src/SUMMARY.md
index a343011..881eafb 100644
--- a/site/src/SUMMARY.md
+++ b/site/src/SUMMARY.md
@@ -12,7 +12,7 @@
 # Using JevGate
 
 - [Continuous integration](ci.md)
-- [Coding agents](agents.md)
+- [Coding agents](coding-agents.md)
 - [Configuration](configuration.md)
 - [Output and exit codes](output.md)
 - [Privacy and cost](privacy-and-cost.md)
diff --git a/site/src/coding-agents.md b/site/src/coding-agents.md
new file mode 100644
index 0000000..fe2ab2e
--- /dev/null
+++ b/site/src/coding-agents.md
@@ -0,0 +1,41 @@
+# Coding agents
+
+JevGate's default output is written for coding agents as much as for people: ranked findings, each with a location, a probability and a next step, and nothing hidden when an answer stays undecided.
+
+## Check before finishing
+
+Ask the agent to review its own change before it reports back, for example in `AGENTS.md` or `CLAUDE.md`:
+
+```markdown
+Before finishing, run `jevgate check --base origin/main`. Fix each `review` finding;
+for a `consider`, fix it or say why the code should stay as it is.
+```
+
+`--base` limits the review to the files changed since that revision, plus uncommitted and untracked files, so a check costs only what the change touches, and cached answers make reruns free. The exit code says what to do next:
+
+| Exit code | Meaning for the agent |
+|---|---|
+| 0 | The gate passed; `consider` findings may still be worth a look |
+| 1 | The gate failed: act on the findings listed |
+| 2 | The run could not finish (no key, provider rejection, request budget); report it, don't treat it as a pass |
+
+## Structured output
+
+`--format json` prints the full report: every file, finding, raw answer and probability, and the gate. The same report is always written to `.jevgate/latest.json`, whatever the output format, so an agent can run the check once and read the details after. `jevgate check --help` explains its fields.
+
+`jevgate rules --format json` lists every rule with the question it asks, so an agent can tell what a finding means without guessing.
+
+## Watching while editing
+
+`jevgate check --watch` re-checks the selected files after each save and prints one JSON report per line. Alongside it, `jevgate serve` answers local tools, never browser pages, with read-only JSON:
+
+| Path | What it returns |
+|---|---|
+| `/snapshot` | The full latest report |
+| `/evidence` | Findings and context per file |
+| `/context-requests` | Evidence a file still needs |
+| `/changes?since=GENERATION` | What changed since a report generation |
+
+## Documentation for agents
+
+The opt-in documentation rules judge the instruction files agents load at the start of every session (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and Cursor, Copilot, Windsurf, Cline, Kiro, Junie and Roo Code rules): sections that only restate the manifest or generic advice, and text loaded in every session that applies to one directory. `jevgate check --rule documentation` also estimates the tokens each harness loads.