openqodex 0.1.0

package/docs/agents.md

@@ -0,0 +1,121 @@
+# Agents
+
+OpenQodex runs inside Claude Code, Cursor, Codex CLI and Cline. `openqodex init` installs it into each one it finds. The review then runs on the agent's own model, with no key.
+
+## Run init
+
+Run it in your own terminal, not inside the agent:
+
+```
+npx openqodex init
+```
+
+`init` prints every file it will write and asks once. `--agent <name>` picks agents by hand: `claude-code`, `cursor`, `codex`, `cline` or `all`. `--dry-run` prints the plan and writes nothing.
+
+## User scope and project scope
+
+The default is user scope. `init` writes into your home folder, so one install works in every repository. A file it must put inside a repository is added to `.git/info/exclude`, so `git status` does not change.
+
+`--project` writes the files into the repository instead, for a team to commit. Run it inside a git repository.
+
+## The launcher
+
+In user scope, the push gate hooks call a launcher, not npx. `init` copies the package to `~/.openqodex/runtime/<version>/` and checks the copy runs. It then writes `~/.openqodex/bin/openqodex`, a small script that runs that copy with your Node. The hooks call that script by its full path, so they do not depend on npx or your `PATH`.
+
+In project scope, the hooks call `npx -y openqodex@<version>`, because the launcher path would not exist on a teammate's machine.
+
+## Claude Code
+
+| What | User scope | Project scope |
+|---|---|---|
+| Skill | `~/.claude/skills/openqodex/SKILL.md` | `.claude/skills/openqodex/SKILL.md` |
+| Push gate hook | merged into `~/.claude/settings.json` | merged into `.claude/settings.json` |
+
+The hook is one `PreToolUse` entry. It matches the `Bash` tool and runs only for `git push` commands. It calls `openqodex hook check`.
+
+## Codex CLI
+
+| What | User scope | Project scope |
+|---|---|---|
+| Skill | `~/.agents/skills/openqodex/SKILL.md` | `.agents/skills/openqodex/SKILL.md` |
+| Instructions | not written | a marked section in `AGENTS.md` |
+| Push gate hook | merged into `~/.codex/hooks.json` | merged into `.codex/hooks.json` |
+
+Codex runs the hook before every shell command. `hook check` returns at once and prints nothing when the command is not a `git push`.
+
+Codex runs a new hook only after you trust it. Open Codex, run `/hooks`, and trust the OpenQodex hook. Until then, Codex skips the push gate. A project hook also needs the project itself to be trusted in Codex.
+
+## Cursor
+
+| What | User scope | Project scope |
+|---|---|---|
+| Skill | `~/.cursor/skills/openqodex/SKILL.md` | `.agents/skills/openqodex/SKILL.md` |
+| Rule | `.cursor/rules/openqodex.mdc` in the repository, excluded from git | `.cursor/rules/openqodex.mdc` |
+
+Cursor has no rule file in the home folder, so the rule always goes in the repository. In user scope, run `init` inside each repository where you want the rule. The rule applies to every chat and tells Cursor to review before any `git push`.
+
+OpenQodex writes no Cursor hook. The rule asks Cursor to review, but nothing stops a push from Cursor.
+
+## Cline
+
+| What | User scope | Project scope |
+|---|---|---|
+| Skill | `~/.cline/skills/openqodex/SKILL.md` | `.cline/skills/openqodex/SKILL.md` |
+| Rule | `~/Documents/Cline/Rules/openqodex.md` | `.clinerules/openqodex.md` |
+
+OpenQodex writes no Cline hook. The rule asks Cline to review before any `git push`.
+
+## What the push gate does
+
+The gate runs in Claude Code and Codex, through the hooks above. It never approves a push for you: your agent's own permission prompt for `git push` still applies.
+
+Without `review.block_on_severity` in `.openqodex.yaml`, the gate never stops a push:
+
+- When a finished review of the current change has findings, it adds the finding counts and the report path. A clean review adds nothing.
+- When none exists, it adds a note that the change was not reviewed and how to review it.
+
+With `review.block_on_severity` set, the gate denies the push unless a finished review of the current change passed. The reason names the next step.
+
+`OPENQODEX_SKIP=1` in the environment lets the push through and says so. It is your switch, not your agent's.
+
+The hook never breaks a push by accident. When `hook check` itself fails, it prints the reason on stderr and lets the agent go on.
+
+## A git hook for every tool
+
+For pushes from any tool, add a git pre-push hook to one repository:
+
+```
+npx openqodex hook install
+```
+
+It runs `openqodex scan` before each push, through the launcher. It stops the push only when `.openqodex.yaml` sets `review.block_on_severity` and the scan meets it. A scan that fails for its own reasons never stops the push. `init` never installs it. `cli` has the details.
+
+## Other ways to install
+
+- The skill alone: `npx skills add openqodex/openqodex`. This writes the skill but no hook.
+- Claude Code plugin: the repository holds a plugin marketplace with an `openqodex` plugin. The plugin carries the skill and the push gate hook. Its hook calls `npx -y openqodex@<version>`.
+
+## Inside a sandbox
+
+Some agents run commands in a sandbox that cannot reach the network or write outside the project. There, the first review cannot download scanners. Each scanner reports why it was left out, and the review runs with what is available. Run this once in your own terminal to fix it:
+
+```
+npx openqodex doctor --install
+```
+
+The review writes its files inside the repository, in `.openqodex/`. So it works in a sandbox that can write only the project.
+
+## Uninstall
+
+```
+npx openqodex init --uninstall
+```
+
+Add `--project` to remove project files. `init` records what it wrote in `~/.openqodex/install.json`. `--uninstall` removes only what that record holds:
+
+- A skill or rule file is removed only when it is unchanged since `init` wrote it.
+- The hook entry is removed from the settings file. Other settings stay. When `init` saved a backup and nothing else changed, the backup is put back.
+- The `.git/info/exclude` lines are removed.
+- The launcher and the runtime copies are removed when no hook still calls them. The git pre-push hook counts as one.
+
+Scanners stay in `~/.openqodex/tools/`. Delete that folder to remove them too.

package/docs/cli.md

@@ -0,0 +1,161 @@
+# Commands
+
+Run every command with `npx openqodex <command>`, or `openqodex <command>` when the package is installed.
+
+## Exit codes
+
+- `0`: clean, or warnings only.
+- `1`: a finding at or above `review.block_on_severity`. Without that key, no command exits 1.
+- `2`: OpenQodex itself failed: a wrong flag, an invalid config, not a git repository, a stale review, or an internal error. `doctor` prints its table first and then exits 2.
+
+A scanner that fails or is missing never changes the exit code. The report lists it with the reason.
+
+## Which change is checked
+
+By default the change is the commits not yet pushed plus everything uncommitted, untracked files included. OpenQodex finds the base in this order:
+
+1. `--base <ref>`: the point where the current branch left that ref.
+2. `--uncommitted`: the last commit, `HEAD`. Only uncommitted work counts.
+3. The point where the branch left its upstream branch.
+4. The point where the branch left the remote's default branch (`origin/HEAD`).
+5. The last commit, `HEAD`.
+
+A repository with no commits checks every file. OpenQodex never fetches from a remote.
+
+## Shared flags
+
+`scan`, `review`, `doctor`, `trust` and `guide` accept these flags. `demo` accepts only `--no-color`, `--quiet`, `--verbose`, `--no-install` and `--offline`. `init` and `hook` accept none of them.
+
+- `--cwd <dir>`: find the repository from `<dir>`. A relative `--output` path still resolves from the folder you ran the command in.
+- `--config <path>`: read this config file instead of `.openqodex.yaml` at the repo root.
+- `--format <terminal|markdown|json|sarif>`: the report format. The default is `terminal`. Only `scan` and `review` use it.
+- `--output <file>`: write the report to `<file>` instead of stdout. Only `scan` and `review` use it.
+- `--no-color`: no colour. `NO_COLOR` set in the environment does the same.
+- `--quiet`: no progress lines on stderr.
+- `--verbose`: print the stack when OpenQodex itself fails.
+- `--no-install`: do not download missing scanners. The report lists them as not installed.
+- `--offline`: no built-in scanner goes online. osv-scanner and semgrep are skipped and listed as disabled. Scanner downloads are off.
+
+`doctor --install` together with `--offline` or `--no-install` exits 2.
+
+Progress goes to stderr. The report goes to stdout.
+
+`openqodex --version` prints the version. `openqodex --help` lists the commands.
+
+## review
+
+```
+openqodex review [--agent | --finalize [path]] [--base <ref>] [--uncommitted] [--only <list>] [--skip <list>]
+```
+
+- `--agent`: run the scanners, write the brief and print it. Your agent runs this.
+- `--finalize [path]`: check the agent's findings and write the report. Without a path it reads `agent-findings.json` in the newest report folder. With a path it finds the run by the `change_id` in that file.
+- Neither flag: the same as `scan`, plus one line on how to get the AI review from your agent.
+- `--base`, `--uncommitted`: see "Which change is checked".
+- `--only <list>`: run only these scanners, comma separated.
+- `--skip <list>`: skip these scanners, comma separated.
+
+A scanner name is a built-in name such as `semgrep`, or `custom:<name>` for a custom scanner.
+
+`--finalize` exits 2 when:
+
+- the findings file breaks the shape, naming the first wrong field;
+- the change moved since the brief;
+- the config changed since the brief;
+- a finding cites a scanner rule or candidate that is not in this scan.
+
+It never repairs a finding. Fix what it names, or run `review --agent` again.
+
+## scan
+
+```
+openqodex scan [--base <ref>] [--uncommitted] [--only <list>] [--skip <list>]
+```
+
+Runs the scanners on the change and prints the report. No model is involved. The git hook, the pre-commit hook and the GitHub Action run this command.
+
+## init
+
+```
+openqodex init [--agent <name>]... [--project] [--yes] [--uninstall] [--dry-run]
+```
+
+Installs OpenQodex into your coding agents.
+
+- `--agent <name>`: `claude-code`, `cursor`, `codex`, `cline` or `all`. Repeat it for several. Without it, `init` uses every agent it finds.
+- `--project`: write the files into the repository for a team to commit. The default writes them in your home folder.
+- `--yes`, `-y`: do not ask. Without a terminal, `init` needs this flag.
+- `--uninstall`: remove what `init` wrote. A file you edited after `init` is left in place.
+- `--dry-run`: print the plan and write nothing.
+
+`init` does not take the flags listed under "Flags every command below accepts". `agents` lists each file it writes.
+
+## doctor
+
+```
+openqodex doctor [--install] [--json]
+```
+
+Prints the Node and git versions, the repository, the config, the OpenQodex home folder and the state of each scanner. It lists custom scanners with their approval state.
+
+- `--install`: download every scanner that fits this machine, and wait for all of them.
+- `--json`: print the same facts as JSON.
+
+`doctor` always prints its table. It then exits 2 in three cases:
+
+- git is missing;
+- the config does not load;
+- the `--cwd` folder does not exist.
+
+## trust
+
+```
+openqodex trust [--yes] [--list] [--revoke <name>]
+```
+
+Approves the custom scanners in `.openqodex.yaml`. For each new or changed entry, it downloads the release asset. It shows what will run and asks yes or no.
+
+- `--yes`: approve every pending entry without asking. Use it only for entries you have read.
+- `--list`: print each custom scanner and its state: trusted, not approved, or changed since approval.
+- `--revoke <name>`: remove the approval for one scanner.
+
+Without a terminal and without `--yes`, `trust` exits 2. `custom-scanners` explains the whole step.
+
+## hook
+
+```
+openqodex hook check
+openqodex hook install [--force]
+openqodex hook uninstall
+```
+
+- `hook check`: the push gate. The Claude Code and Codex hooks call it before a shell command. It reads the hook's JSON on stdin. It always exits 0.
+- `hook install`: add a git pre-push hook to this repository. It also sets up the launcher in `~/.openqodex/`, which the hook calls. The hook runs `scan` before each push. It stops the push only when the scan exits 1. A scan that fails for its own reasons never stops the push.
+- `hook install` refuses to replace a hook it did not write. `--force` replaces it and keeps the old hook as `pre-push.openqodex.bak`.
+- `hook uninstall`: remove that hook and put back the one it replaced. A hook you edited after install is left in place.
+
+When the repository uses husky or lefthook, `hook install` writes nothing. It prints the line to add to their pre-push hook.
+
+`init` never installs the git hook. `agents` explains the push gate.
+
+## guide
+
+```
+openqodex guide [topic]
+```
+
+Prints the skill without a topic. With a topic, it prints that page of these docs. An unknown topic lists the topics and exits 2.
+
+## demo
+
+```
+openqodex demo [dir]
+```
+
+Builds the demo repository in `<dir>`, or in a new temporary folder. A relative `<dir>` resolves from the folder you run the command in. The folder must be empty or new. The demo commits a clean baseline, then adds a change with planted bugs and leaves it uncommitted. It scans that change and prints the report. When some scanners are still installing, it says so and asks you to run `scan` again. The secret in the demo is generated each time and works nowhere.
+
+## Environment variables
+
+- `OPENQODEX_HOME`: where OpenQodex keeps scanners, the launcher and approvals. The default is `~/.openqodex`.
+- `OPENQODEX_SKIP=1`: the push gate lets the push through and says so. It is your switch, not your agent's.
+- `NO_COLOR`: no colour in the terminal report.

package/docs/config.md

@@ -0,0 +1,165 @@
+# Configuration
+
+OpenQodex reads `.openqodex.yaml` at the root of the repository. Every key is optional. With no file, the defaults apply, and OpenQodex warns but never blocks.
+
+`--config <path>` reads another file instead.
+
+An unknown key prints a warning and is ignored. A value of the wrong type stops the run with exit 2 and names the key.
+
+## A full example
+
+```yaml
+version: 1
+review:
+  block_on_severity: critical
+  paths:
+    exclude: ["vendor/**", "**/*.min.js", "*.min.js"]
+  disabled_rules: ["gitleaks:generic-api-key", "lens:react-*"]
+  include_fixtures: false
+scanners:
+  disable: [brakeman]
+  custom:
+    - source: https://github.com/aquasecurity/trivy
+      run: trivy config --format sarif --output {report} {target}
+```
+
+## Severity
+
+OpenQodex uses one scale: `critical`, `major`, `minor`, `nitpick`, `info`. Scanner severities map onto it:
+
+- critical to `critical`
+- high to `major`
+- medium to `minor`
+- low to `nitpick`
+- info to `info`
+
+## version
+
+`1`, the only version. Optional.
+
+## review.block_on_severity
+
+One of `critical`, `major`, `minor`, `nitpick`, `info`. The default is unset.
+
+- Unset: OpenQodex warns and never blocks. No command exits 1. The push gate never denies a push.
+- Set: the verdict is `blocked` when a finding on a changed line is at or above this severity. `scan` and `review` exit 1. The push gate denies a push unless a finished review of the current change passed.
+
+Findings outside the changed lines never count toward the verdict.
+
+## review.paths.exclude
+
+A list of globs. The default is an empty list. A matching file is left out of the change. The brief does not show it, and no finding in it is kept. Scanners do not receive it as a changed file. A scanner that reads a whole project, such as brakeman or golangci-lint, may still read it.
+
+Globs match the path from the repository root, with forward slashes:
+
+- `*` matches any characters except `/`.
+- `**` matches any characters, `/` included.
+- `?` matches one character except `/`.
+
+There is no negation and no character class.
+
+A `**/` prefix does not match a file at the repository root. `**/*.min.js` matches `web/app.min.js` but not `app.min.js`. To match both, list `**/*.min.js` and `*.min.js`.
+
+## review.disabled_rules
+
+A list of globs matched against a finding's citation, `<source>:<rule>`. A matching finding is dropped. The default is an empty list.
+
+- `gitleaks:generic-api-key` drops one gitleaks rule.
+- `semgrep:python.lang.*` drops a family of semgrep rules.
+- `lens:react-*` drops agent findings that cite a review pattern whose name starts with `react-`.
+- `custom:trivy:*` drops every finding of the custom scanner named `trivy`.
+
+## review.include_fixtures
+
+`true` or `false`. The default is `false`.
+
+With `false`, scanner findings in test fixtures, mocks, stubs, fakes and snapshots are dropped. A path counts when one of its folders is `fixtures`, `__fixtures__`, `mocks`, `__mocks__`, `snapshots`, `__snapshots__`, `fakes`, `stubs` or `testdata`. It also counts when the file name holds `.fixture.`, `.mock.` or `.stub.` (or their plurals), or ends in `.snap`. Test files themselves are not dropped.
+
+## scanners.disable
+
+A list of built-in scanner names to switch off. The names are `semgrep`, `gitleaks`, `sqllint`, `osv-scanner`, `actionlint`, `hadolint`, `shellcheck`, `ruff`, `brakeman`, `rubocop`, `bandit`, `oxlint` and `golangci`. A disabled scanner is listed in the report as disabled.
+
+## scanners.custom
+
+A list of custom scanners. Each one needs two keys:
+
+```yaml
+scanners:
+  custom:
+    - source: https://github.com/aquasecurity/trivy
+      run: trivy config --format sarif --output {report} {target}
+```
+
+A custom scanner never runs until you approve it with `openqodex trust`. `custom-scanners` explains the step.
+
+### source
+
+The GitHub link of the scanner's repository, `https://github.com/<owner>/<repo>`. Required.
+
+### run
+
+The command line. Required. OpenQodex splits it into words and starts the first word as the program. It never runs the line through a shell, so pipes, `&&` and `$VAR` have no effect.
+
+Three placeholders are filled in:
+
+- `{report}`: the file the scanner writes its report to.
+- `{target}`: the files to scan. See `target`.
+- `{repo}`: the repository root.
+
+### name
+
+The scanner's name in the report, as `custom:<name>`. The default is the repository name from `source`. Letters, digits, dot, dash and underscore only. Two entries cannot share a name.
+
+### version
+
+The release to use, such as `0.58.1`. The default is the latest release at the time you run `openqodex trust`.
+
+### format
+
+`sarif` or `json-map`. The default is `sarif`. `json-map` reads any JSON report through a `map` block.
+
+### map
+
+Required when `format` is `json-map`. Each value is a dotted path into the report, with `[n]` for a list index.
+
+- `items`: the path to the list of results. `.` means the report itself is the list. Required.
+- `file`: the file path in one result. Required.
+- `line`: the start line. Required.
+- `end_line`: the end line. Optional.
+- `rule`: the rule id. Required.
+- `severity`: the scanner's severity. Optional.
+- `message`: the message. Required.
+- `reference`: a link for the rule. Optional.
+- `severity_map`: maps the scanner's severity words to `critical`, `high`, `medium`, `low` or `info`. A word not in the map reads as `medium`.
+
+`custom-scanners` has a worked example.
+
+### paths
+
+A list of globs. The scanner runs only when a changed file matches one, and receives only matching files. The default is every changed file.
+
+### target
+
+`changed` or `repo`. The default is `changed`.
+
+- `changed`: `{target}` is the changed files.
+- `repo`: `{target}` is the repository root.
+
+Either way, only findings on changed lines are kept.
+
+### timeout_seconds
+
+A whole number of seconds. The default is `120`.
+
+### install
+
+How OpenQodex gets the scanner. The default downloads the GitHub release asset that fits your machine. Use one of these forms instead:
+
+- `install: path`: use the program already on your `PATH`. Nothing is downloaded.
+- `install: { asset: <name> }`: the release asset to download, when OpenQodex cannot pick one.
+- `install: { binary: <path> }`: the program's path inside the asset, when it is not at the top.
+- `install: { sha256: <hex> }`: the expected sha256 of the asset, in lowercase hex.
+- `install: { npm: <package@version> }`: install the scanner from npm.
+- `install: { uv: <package==version> }`: install the scanner from PyPI through uv.
+
+`asset`, `binary` and `sha256` combine. `npm` and `uv` stand alone.

package/docs/custom-scanners.md

@@ -0,0 +1,164 @@
+# Custom scanners
+
+You can add any scanner by its GitHub link. Its findings join the same report as the built-in scanners. Only findings on changed lines are kept.
+
+A custom scanner is an arbitrary command that runs on your machine with your permissions. Only `openqodex trust` downloads a custom scanner, and it asks you first. `scan` and `review` never download one. Nothing is installed or run before you approve that exact entry.
+
+## Add one
+
+Two lines in `.openqodex.yaml` at the root of your repository:
+
+```yaml
+scanners:
+  custom:
+    - source: https://github.com/aquasecurity/trivy
+      run: trivy config --format sarif --output {report} {target}
+```
+
+- `source`: the scanner's GitHub repository.
+- `run`: the command line. OpenQodex splits it into words and starts the first word as the program. It never uses a shell.
+
+Three placeholders are filled in:
+
+- `{report}`: the file the scanner writes its report to.
+- `{target}`: the changed files, or the repository root when `target: repo` is set.
+- `{repo}`: the repository root.
+
+`config` lists every optional key: `name`, `version`, `format`, `map`, `paths`, `target`, `timeout_seconds` and `install`.
+
+## Approve it
+
+```
+npx openqodex trust
+```
+
+For each entry that is new or changed, `trust` does these steps:
+
+1. It reads the release from the GitHub API. Without `version`, it takes the latest release.
+2. It picks the release asset for your system and CPU.
+3. It downloads the asset to a quarantine folder. Nothing is unpacked onto the tool path or run yet.
+4. It checks the asset against the project's checksum file, when the project publishes one.
+5. It prints what will run and asks yes or no.
+
+The printout shows the name, source, version, install form, asset, download URL and sha256. It also shows the checksum check, the program path, the run line, the paths and the target. Read it before you answer.
+
+On yes, the asset is installed and the approval is stored. On no, the scanner is skipped until you approve it.
+
+## How the asset is chosen
+
+OpenQodex matches words in each asset's file name:
+
+- system: `darwin`, `macos`, `osx`, `apple` or `linux`;
+- CPU: `arm64`, `aarch64`, `x86_64`, `amd64`, `x64` or `64bit`;
+- format: `.tar.gz`, `.tar.xz`, `.zip`, or a bare program.
+
+When no asset matches, or more than one does, `trust` stops. It prints the candidates and the line to add. Name the asset by hand. `{version}`, `{os}` and `{arch}` stand for the version and the name words above, so one line fits every machine:
+
+```yaml
+    - source: https://github.com/aquasecurity/trivy
+      run: trivy config --format sarif --output {report} {target}
+      install:
+        asset: "trivy_{version}_{os}-{arch}.tar.gz"
+```
+
+The name must match exactly one asset.
+
+Other install forms:
+
+- `install: path`: use the program on your `PATH`. Nothing is downloaded. `trust` records the program's sha256. When the program changes, the scanner is skipped until you approve it again.
+- `install: { npm: <package@1.2.3> }`: install from npm. The spec must name an exact version.
+- `install: { uv: <package==1.2.3> }`: install from PyPI through uv. The spec must name an exact version.
+
+## What the stored hash means
+
+`trust` records the sha256 of the asset it downloaded.
+
+When the project publishes a checksum file and the asset matched it, that hash was checked against upstream. Otherwise the stored hash is only the hash of your first download. This is trust on first use: it does not prove the first download was genuine. The printout says which of the two applies.
+
+## Where approvals are stored
+
+Approvals live in `~/.openqodex/trust.json`. Each one is keyed by the repository root and a hash of the entry and the resolved asset. An approval in one repository does not cover another.
+
+Any edit to the entry changes its hash. The scanner is then skipped as `untrusted` until you run `openqodex trust` again.
+
+- `openqodex trust --list` shows each custom scanner and its state.
+- `openqodex trust --revoke <name>` removes one approval.
+- `openqodex doctor` shows the state of each custom scanner too.
+
+## Report formats
+
+### SARIF
+
+SARIF is a standard JSON format for scanner results. Many scanners write it with a flag. It is the default `format`.
+
+OpenQodex reads each result's rule id, file, start and end line, and message. The severity comes from a `security-severity` score. A score on the result wins over a score on its rule:
+
+- 9 or more: critical
+- 7 or more: high
+- 4 or more: medium
+- above 0: low
+- 0: info
+
+Without a score, the SARIF level decides: `error` is high, `warning` is medium, `note` is low, `none` is info. Anything else is medium.
+
+### Worked example: trivy with SARIF
+
+trivy checks infrastructure files such as Terraform and Kubernetes manifests.
+
+```yaml
+scanners:
+  custom:
+    - source: https://github.com/aquasecurity/trivy
+      run: trivy config --format sarif --output {report} {target}
+      paths: ["**/*.tf", "*.tf", "**/*.yaml", "*.yaml"]
+      target: repo
+```
+
+- `paths` limits the scanner to changes that hold Terraform or YAML files.
+- `target: repo` passes the repository root, because `trivy config` scans a folder.
+- Findings appear in the report as `custom:trivy:<rule id>`.
+
+### json-map
+
+For a scanner that cannot write SARIF, `json-map` reads its JSON report through a `map` block. Each value is a dotted path into the report, with `[n]` for a list index. `items` points at the list of results. The other paths are read from each result.
+
+### Worked example: gosec with json-map
+
+gosec checks Go code for security problems. Its JSON report looks like this:
+
+```json
+{
+  "Issues": [
+    { "severity": "HIGH", "rule_id": "G101", "details": "Potential hardcoded credentials",
+      "file": "/home/me/app/config.go", "line": "12" }
+  ]
+}
+```
+
+The entry:
+
+```yaml
+scanners:
+  custom:
+    - source: https://github.com/securego/gosec
+      run: gosec -fmt json -out {report} -no-fail {repo}/...
+      paths: ["**/*.go", "*.go"]
+      format: json-map
+      map:
+        items: Issues
+        file: file
+        line: line
+        rule: rule_id
+        severity: severity
+        message: details
+        severity_map:
+          HIGH: high
+          MEDIUM: medium
+          LOW: low
+```
+
+- `items: Issues` points at the list.
+- `file` may be absolute. OpenQodex turns a path inside the repository into a repository path.
+- `line` may be a number or a string of digits. A result without a file or a line is skipped.
+- `severity_map` turns gosec's words into the scanner scale. A word not in the map reads as medium.
+- `-no-fail` keeps gosec from exiting with an error when it finds something.

package/docs/faq.md

@@ -0,0 +1,54 @@
+# FAQ
+
+## Do I need an API key or an account?
+
+No. The review runs on the model your coding agent already uses. OpenQodex itself calls no model.
+
+## Does OpenQodex send my code anywhere?
+
+Not through the built-in scanners. Their network use is listed in `security`: scanner downloads, Semgrep rule packs, and dependency names and versions sent to osv.dev. Your agent's model sees what your agent reads, as it always does. A custom scanner you approved does whatever its own command does.
+
+## Will it block my push?
+
+Not by default. Without `review.block_on_severity` in `.openqodex.yaml`, OpenQodex only warns. Set that key to block pushes at a severity. `OPENQODEX_SKIP=1` lets one push through.
+
+## Why did a scanner not run?
+
+The report lists every selected scanner with a status and a reason. The usual reasons:
+
+- The change holds no file it reads.
+- It is still downloading on first use. It joins the next run.
+- It needs Ruby or Go, which OpenQodex does not install.
+- The agent's sandbox cannot download it. Run `npx openqodex doctor --install` in your own terminal.
+
+## Why is a finding missing that the scanner reports on my whole repo?
+
+OpenQodex keeps only findings on the lines your change adds or edits. Findings elsewhere belong to code you did not touch. A finding the agent places outside the changed lines is listed separately and never counts toward the verdict.
+
+## Why were findings in my test fixtures dropped?
+
+Scanner findings in fixtures, mocks, stubs, fakes and snapshots are dropped by default, because those files hold throwaway data. Set `review.include_fixtures: true` to keep them.
+
+## How do I leave files out of the review?
+
+List globs under `review.paths.exclude`. A `**/` prefix does not match a file at the repository root. To match both, list `**/x` and `x`. `config` has the rules.
+
+## Can I use a scanner that is not built in?
+
+Yes, by its GitHub link. Add two lines to `.openqodex.yaml` and approve the entry with `openqodex trust`. `custom-scanners` explains how.
+
+## Does it change my repository?
+
+The review writes only inside `.openqodex/`, which ignores itself in git. `git status` does not change. The built-in scanners run with fixes switched off, and their caches live outside the repository. A custom scanner you approved does whatever its own command does. `init` in user scope adds any repository file it writes to `.git/info/exclude`.
+
+## Where are the reports?
+
+In `.openqodex/reviews/<time>-<id>/` in the repository: `report.md` to read, `report.json` and `report.sarif` for tools. `.openqodex/latest.json` points at the newest one.
+
+## Does it work on Windows?
+
+Through WSL. OpenQodex runs on macOS and Linux.
+
+## How do I remove it?
+
+`npx openqodex init --uninstall` removes what `init` wrote. Delete `~/.openqodex/` to remove the scanners as well.