openqodex 0.2.1 → 0.4.0

package/docs/agents.md

@@ -30,6 +30,24 @@ Inside a repository, `init` also asks: "Add the git pre-push hook, so every push
 
 The tables below name the file for each agent. Cursor has no instruction file in the home folder, so its rule in the repository carries the same section. In an existing file, the section is appended and your own text stays as it is. `--uninstall` removes exactly that section, and nothing around it.
 
+## The team section in the repository
+
+Inside a repository, `init` in user scope also asks: "Add a review section to this repo's CLAUDE.md and AGENTS.md, so teammates' agents review before they push too?" The default is yes, and `--yes` answers yes. `--no-repo` answers no. The answer is recorded for that repository and asked no more; `--yes` or `--no-repo` on a later `init` replaces it.
+
+The section goes into `CLAUDE.md` and `AGENTS.md` at the root of the repository, and `init` creates a file that is not there. It is meant for a teammate who has installed nothing, so it names only the pinned `npx` command:
+
+```
+<!-- openqodex:start -->
+## Review with OpenQodex before you push
+- Before any `git push`, run `npx -y openqodex@<version> review --agent` from the repository root and follow the brief it prints to the end, including the finalize command it names.
+- Run that review in a separate subagent when your agent has one: the agent that wrote the code does not judge its own work.
+- Do not push on a blocked verdict unless the developer says so after seeing the findings.
+- The report is in `.openqodex/reviews/`.
+<!-- openqodex:end -->
+```
+
+The two files show in `git status`, and `init` says to commit them. `init` writes neither file through a symbolic link. A section you edited is yours: a later `init` and `--uninstall` leave it as it is. `--uninstall` removes our untouched section, and deletes a file only when `init` created it and nothing else is in it. In project scope the same two files carry the instruction section instead, never both.
+
 ## The review runs in a separate subagent
 
 The skill hands the review to a subagent whose only task is the review, so the agent that wrote the code does not judge its own work. In Claude Code, that is a subagent started with the Agent tool. In Codex, Cursor and other hosts, the skill uses their sub-task or background agent feature when there is one. Where the host has none, the agent tells you the review is not independent, and the report's summary says so on its first line.
@@ -47,15 +65,17 @@ Both are meant to be committed, so the whole team shares them. A file that exist
 
 ## User scope and project scope
 
-The default is user scope. `init` writes into your home folder, so one install works in every repository. A rule file it must put inside a repository is added to `.git/info/exclude`, so it does not show in `git status`. The two repo folder files below are the exception: they are meant to be committed.
+The default is user scope. `init` writes into your home folder, so one install works in every repository. A rule file it must put inside a repository is added to `.git/info/exclude`, so it does not show in `git status`. The two repo folder files and the team section above are the exception: they are meant to be committed.
 
 `--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 user scope, the push gate hooks, the skill and the Cursor and Cline rules call a launcher, not npx. Every user-scope install gets it, with or without a hook. `init` copies the package to `~/.openqodex/runtime/<version>/` and checks the copy runs. It writes the version to the first line of `~/.openqodex/runtime/current`, then writes `~/.openqodex/bin/openqodex`, a small script that runs the copy that line names with your Node. When the line is missing, is not a version, or names a copy that is gone, the script runs the version `init` installed. The hooks and the skill's commands call that script by its full path, so they do not depend on npx or your `PATH`. A copy is never changed once written: when a folder of the same version with other contents is in the way, `init` stops and names it.
+
+The user-scope skill is a short stub: when to run, who reviews (a separate subagent where the host has one), and one command, `<launcher> guide skill`, which prints the full procedure of the version the launcher runs, with every command written for the launcher. No file `init` writes in user scope names a version or holds the procedure, so an update changes none of them. In user scope the Cursor and Cline rules call the launcher too, and say to run `<launcher> guide skill` when the skill is not loaded.
 
-In project scope, the hooks call `npx -y openqodex@<version>`, because the launcher path would not exist on a teammate's machine.
+In project scope, the hooks, the skill and the rules call `npx -y openqodex@<version>` and the skill holds the full procedure, because the launcher path would not exist on a teammate's machine. These files, and the review section `init` adds to a repository's `CLAUDE.md` and `AGENTS.md`, stay on the version they name: an update never changes them. Run `init` again to move them.
 
 ## Claude Code
 
@@ -64,9 +84,16 @@ In project scope, the hooks call `npx -y openqodex@<version>`, because the launc
 | Skill | `~/.claude/skills/openqodex/SKILL.md` | `.claude/skills/openqodex/SKILL.md` |
 | Push gate hook | merged into `~/.claude/settings.json` | merged into `.claude/settings.json` |
 | Instructions | a marked section in `~/.claude/CLAUDE.md` | a marked section in `CLAUDE.md` |
+| Permission rules | merged into `permissions.allow` of `~/.claude/settings.json` | none |
 
 The hook is one `PreToolUse` entry. It matches the `Bash` tool and runs only for `git push` commands. It calls `openqodex hook check`.
 
+In user scope, `init` adds rules so Claude Code runs these review commands without asking, and the agent can review unattended: `<launcher> review --agent`, `review --finalize`, `review --agent --all` and `review --finalize --all`, each also with ` --offline` at the end, plus `guide`, `guide skill` and `guide <topic>`. Each rule matches one exact line, so the same command with any other flag, such as `--output` or `--config`, or chained with `&&`, still asks you. `scan`, `doctor`, `trust`, `update`, `init` and `report` still ask you. The brief's finalize command is one of these lines too, unless the review was run with `--config`. Project scope writes no permission rule: a committed settings file would decide for every teammate. A rule you already had is left alone, and `init --uninstall` removes only the rules `init` added. When a later version grants a different set, the next `init` removes the rules an earlier version added and adds the new ones. When your home path holds a space or another character the shell would read, the launcher is written in single quotes in the skill and in the rules alike. When the launcher's path holds `*`, which Claude Code reads as a wildcard, `init` writes no rule and says so in one line; Claude Code then asks before each review command.
+
+A skill, rule or permission rule an earlier `init` wrote, such as the full-text skill of 0.2.1, is replaced by the next `init` only while it is still exactly as written. One you edited is left as it is, and `init` says so.
+
+Neither the skill `init` writes nor `guide skill` carries the sentence that tells an agent to prefer `~/.openqodex/bin/openqodex`: in user scope the launcher already runs every command, and in project scope the skill keeps the version the team committed.
+
 ## Codex CLI
 
 | What | User scope | Project scope |

package/docs/cli.md

@@ -1,6 +1,6 @@
 # Commands
 
-Run every command with `npx openqodex <command>`, or `openqodex <command>` when the package is installed.
+Run every command with `npx openqodex <command>`, or `openqodex <command>` when the package is installed. `openqodex --help` lists the four commands below: `init`, `review`, `update` and `trust`. The commands that hooks, the skill and the Action call (`scan`, `doctor`, `hook`, `guide`, `demo`, `report`) still work; `plumbing` describes them.
 
 ## Exit codes
 
@@ -22,11 +22,11 @@ By default the change is the commits not yet pushed plus everything uncommitted,
 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.
+A repository with no commits checks every file. A review of your own change never fetches from a remote; a review of a branch or a pull request does (see "Reviewing a branch or a pull request").
 
 ## 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.
+`scan`, `review`, `doctor`, `trust` and `guide` accept these flags. `demo` accepts only `--no-color`, `--quiet`, `--verbose`, `--no-install` and `--offline`. `init`, `hook` and `update` 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.
@@ -36,7 +36,7 @@ A repository with no commits checks every file. OpenQodex never fetches from a r
 - `--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.
+- `--offline`: no built-in scanner goes online. osv-scanner and semgrep are skipped and listed as disabled. Scanner downloads are off. The daily version check does not start after this run.
 
 `doctor --install` together with `--offline` or `--no-install` exits 2.
 
@@ -47,12 +47,15 @@ Progress goes to stderr. The report goes to stdout.
 ## review
 
 ```
-openqodex review [--agent | --finalize [path]] [--all | --base <ref> | --uncommitted] [--no-graph] [--only <list>] [--skip <list>]
+openqodex review [--agent] [--all | --base <ref> | --uncommitted] [--no-graph] [--only <list>] [--skip <list>]
+openqodex review [--agent] <branch | #number | pull request link> [--base <ref>] [--no-graph] [--only <list>] [--skip <list>]
+openqodex review --finalize [--run <id> | path]
 ```
 
 - `--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.
+- `--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. `--run <id>` names the run folder instead; a review of a branch or a pull request is finalized only that way.
+- `<branch>`, `#<number>` or a pull request link: review that branch or pull request instead of your own change. See "Reviewing a branch or a pull request".
+- Neither flag: run the scanners on the change and print their report, with the formats, flags and exit codes above. Then one line on stderr says how to get the full review from your agent, so `--format json` stays one JSON document. `scan` (see `plumbing`) does the same without that line.
 - `--base`, `--uncommitted`: see "Which change is checked".
 - `--all`: review the whole repository instead of the change. See "Reviewing the whole repository".
 - `--no-graph`: do not build the code graph for this run.
@@ -66,10 +69,44 @@ A scanner name is a built-in name such as `semgrep`, or `custom:<name>` for a cu
 - 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.
+- a finding cites a scanner rule or candidate that is not in this scan;
+- the brief was written by another openqodex version that is not installed in `~/.openqodex/runtime/`;
+- for a branch or a pull request, the temporary checkout moved from the reviewed commit or is gone.
+
+When the launcher started the review, the brief's finalize command is the plain line `<launcher> review --finalize`, with `--all` and `--offline` as the review had them, run from the repository root; it finds the run through `.openqodex/latest.json` (`latest-all.json` for `--all`). With `--config`, or when npx started the review, the command names the repository, the config and the findings file, so it works from any folder. When the version that runs `--finalize` is not the one that wrote the brief, and that one is installed by `init` or an update, it hands the run to that version by its findings file and exits with its code. A version reached that way never hands off again.
 
 It never repairs a finding. Fix what it names, or run `review --agent` again.
 
+### Deleted lines
+
+A finding counts toward the verdict only on a line the change added or modified. A change that only deletes lines, such as a removed check, has no such line, so the lines next to each deletion count too: the line just above and the line just below it in the new file. The brief lists each deletion point ("2 lines deleted after line 14 of app/auth.py") and tells the agent to cite one of those lines and say what was removed. Any other line the change did not touch stays under "Outside the changed lines".
+
+### Reviewing a branch or a pull request
+
+`review <branch>` reviews a branch that is not your current work, and `review '#42'` or `review https://github.com/<owner>/<repo>/pull/42` a pull request. Quote `#42` in a shell, where `#` starts a comment. A bare number is a branch name. The branch may be local, `origin/<name>`, or a branch on the remote that is fetched on demand.
+
+```
+openqodex review --agent feature/login
+openqodex review --agent '#42'
+```
+
+The change is what the target added since it left its base: from the merge base of the two to the target's head, read from the commits, never from a work tree. Commits that landed on the base after the split are not part of it. The base is, in this order:
+
+1. `--base <ref>`.
+2. The pull request's base, which `gh` names when it is installed and signed in. For a branch, only when it has exactly one open pull request.
+3. `review.default_base`.
+4. The remote's default branch (`origin/HEAD`), read without the network.
+
+Without `gh`, a branch review uses the next source, and a review of `#<number>` says in one line that the pull request's base is not known. The first line of the output and the brief say which base was used and where it came from.
+
+The head is fetched first: a branch from its remote, so a stale `origin/<name>` is brought up to date, and a pull request from `pull/<number>/head`, the ref GitHub keeps for every pull request. That ref is the one host convention OpenQodex uses. A base named as `<remote>/<branch>` is fetched too, even when this clone has never seen it. Fetches use git and its own credentials; OpenQodex reads no token. A fetch writes only `refs/remotes/<remote>/<branch>` for a branch, or a ref of its own under `refs/openqodex/tmp/` for a pull request, removed when the review ends: no configured fetch mapping, no tags, no pruning, so your branches and tags never change. A pull request link must name a remote of this repository whose host is exactly `github.com`. In a partial clone, a file that is not downloaded is never fetched for the checkout and the review stops with one line; this needs git 2.44 or newer. An older git fetches such a file itself, so with `--offline` a target review in a partial clone refuses to start on it. For `#<number>`, when `gh` names the repository the pull request was opened against and one of your remotes points at it, the head and the base are fetched from that remote, and a line says which. A local branch is read as it is. `--offline` fetches nothing and calls no `gh`, and says in one line when the target is not available locally.
+
+The files are read in a temporary checkout of the head in `~/.openqodex/checkouts/`, a folder only you can open. Making it, and every later git call in it (the code graph included), runs nothing from the repository: no git hook, no file system monitor, no clean, smudge or process filter (including one an include adds only for linked work trees), no submodule. Files stored in Git LFS hold their pointers, and one line says so. Your settings apply, never the target's: the config and `custom-instructions.md` are read from your repository. Checking the target out runs nothing from it, and a link in it becomes a small plain file holding the link's target. The scanners you approved for this repository do run on the target's files, with this repository's settings; one named only in the target's config never runs. If you review pull requests from people you do not trust, approve only custom scanners that do not execute the code they scan. When the target is your current commit and your work tree is clean, the files are read in place. With uncommitted work, the committed head is reviewed in a checkout, and one line says your uncommitted work is not part of it.
+
+Without `--agent`, the scanners report on the change and the checkout is removed at the end. With `--agent`, the brief names the checkout, tells the agent to read the code there and never to run its tests or scripts, and prints the finalize line with `--run <id>`, run from your repository. The run folder stays in your repository. Finalize checks that the checkout is still at the reviewed commit. It removes the checkout when it succeeds or when the review must be run again, and keeps it after an error the agent can fix in its findings file. A target review writes no receipt, so it never replaces the review of the change you are about to push. A later `review` removes a checkout left for more than 24 hours.
+
+`review --all` and `--uncommitted` cannot be combined with a target.
+
 ### Reviewing the whole repository
 
 `review --all` treats every file in the repository as the change: every tracked file and every untracked file git does not ignore, as they are on disk, minus `exclude` and `.openqodex/`. Every line of every text file is in scope, so the scanners report on the whole repository with no changed-line filter. Submodules, symbolic links, unreadable files and files over 5 MB are listed in the brief as left out.
@@ -82,18 +119,10 @@ The brief includes `.openqodex/custom-instructions.md` when the repo has one; a
 
 `--all` cannot be combined with `--base` or `--uncommitted`. The git hook and the GitHub Action never run it.
 
-## 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] [--hook <pre-push|none>] [--yes] [--uninstall] [--dry-run]
+openqodex init [--agent <name>]... [--project] [--hook <pre-push|none>] [--no-repo] [--yes] [--uninstall] [--dry-run]
 ```
 
 Installs OpenQodex into your coding agents.
@@ -101,29 +130,13 @@ 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.
 - `--hook <pre-push|none>`: answer the pre-push hook question without asking. Without it, `init` asks once per repository and records the answer.
-- `--yes`, `-y`: do not ask, and add the pre-push hook unless this repository answered no before. Without a terminal, `init` needs this flag.
+- `--no-repo`: do not add the team review section to the repository's `CLAUDE.md` and `AGENTS.md`. Without it, `init` without `--project` asks once per repository (default yes) and records the answer; `--yes` or `--no-repo` on a later run replaces the recorded answer. A file the repository's git ignore rules hide is left alone, with one line saying why, since it could not be committed.
+- `--yes`, `-y`: do not ask. It adds the team review section, even where this repository answered no before (only `--no-repo` keeps it out), and adds the pre-push hook unless this repository answered no to it before or `--hook none` says so. 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
 
 ```
@@ -138,59 +151,27 @@ Approves the custom scanners in `.openqodex.yaml`. For each new or changed entry
 
 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 `hook pre-push`, which scans each commit the push sends against the remote's tip of its branch (`agents` has the details). 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: `npx -y openqodex@<version> hook pre-push || [ $? -ne 1 ]`. The part after `||` makes the line stop the push only on exit 1, as the hook `hook install` writes does: a scan that fails for its own reasons (exit 2) never stops the push.
-
-`init` asks whether to install the git hook. `agents` explains the push gate.
-
-## guide
+## update
 
 ```
-openqodex guide [topic]
+openqodex update [--now | --rollback | --off | --on | --status]
 ```
 
-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.
-
-## report
-
-```
-openqodex report "<what went wrong>"
-openqodex report --send-last
-```
-
-- `report "<what went wrong>"`: report a problem with OpenQodex. It prints the issue it would create and the two choices, the same as after a failure. It exits 0. Words that hold a path, a file name, a key or token, or an email address are refused with exit 2: remove them and run it again. Your user name and the repository's name are replaced with `<name>`.
-- `report --send-last`: print the last issue shown in this repository again, then create it exactly as it was shown. Outside a repository it uses the last one shown outside a repository. It refuses a saved issue that is a link, is not in the saved shape, or changed after it was shown.
-
-The issue holds only the command and its flags, a short diagnostic, the status of each scanner, the operating system, the CPU type and the Node version. For a scanner the diagnostic is its failure class only, such as `exited with code 2` or `timed out after 60 s`, never its output. For an internal error it is the error's class and first line, cut to 120 characters. Every path, file name, key or token, email address, user name and repository name is removed first, and a custom scanner is shown as `custom scanner`. It never holds code, diffs, findings, config or logs.
+Checks npm for a newer release and installs it now, in the foreground, the same way the daily check does. It works only for an install made with `npx openqodex init`: run through `~/.openqodex/bin/openqodex`, which hooks and the installed skill call. Run any other way (npx, a project-scope file), it exits 2 and says to run `npx openqodex init`.
 
-When the issue could not be saved, OpenQodex says so and does not offer `--send-last`.
+- No flag: install the newest release that is at least 24 hours old and whose build record verifies, then print what happened.
+- `--now`: also install a release younger than 24 hours. Verification is the same.
+- `--rollback`: turn updates off, then point the launcher back at the version that was active before the last update. It exits 2 and changes nothing when that version's copy is gone or when `update: off` cannot be written.
+- `--off`, `--on`: write `update: off` or `update: on` to `~/.openqodex/config.yaml`. `init --uninstall` removes that file when `update` created it and it is unchanged, and removes the update state.
+- `--status`: print the same update lines as `doctor`.
 
-In a terminal, press 1 or 2. Any other key, Enter, Ctrl-C or the end of input counts as 2. Without a terminal (an agent, a git hook, CI), OpenQodex prints the issue and how to create it later with `openqodex report --send-last`; doing nothing ignores it.
+Each release is checked before anything of it runs: its sha512 must match the registry's, and its npm provenance must be signed by this repository's release workflow on `main` (see `security`). A release that fails is skipped, recorded, and not downloaded again for 7 days. An update writes no agent file and never writes inside a repository: the user-scope skill asks the launcher for the procedure with `guide skill`, so it always matches the active version. A foreground `update`, `--rollback`, `--off` and `--on` wait up to 60 seconds while another `init`, uninstall or update runs, then exit 2 with one line. `update` also removes runtime copies older than 7 days, except the one `init` installed, the current one and the previous one.
 
-Choice 1 creates the issue with the GitHub CLI when `gh auth status` says you are signed in. Otherwise it opens the new issue page on GitHub with the title and body filled in, and prints the link. OpenQodex never signs you in. Choice 2 sends nothing. Nothing leaves your machine without choice 1. The last issue shown is kept in `.openqodex/last-report.json`, which git ignores.
+After an update the next command prints one line on stderr: `openqodex updated to X (was Y). Roll back: openqodex update --rollback`. The agent push hook does not print it.
 
 ## 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.
+- `OPENQODEX_AUTO_UPDATE=0`: no daily version check. `OPENQODEX_OFFLINE=1` and a set `CI` variable do the same.
 - `NO_COLOR`: no colour in the terminal report.

package/docs/config.md

@@ -216,3 +216,12 @@ The code graph lists the callers and importers of the code a change touches, for
 - `graph.budget_ms`: the time the graph may take, in milliseconds. The default is `10000`.
 - `graph.max_files`: the most files the graph reads. The default is `4000`.
 - `graph.max_file_bytes`: a file larger than this, in bytes, is left out of the graph. The default is `524288`.
+
+## The user config, ~/.openqodex/config.yaml
+
+One file in your home folder holds what is yours, not the team's. It has one key today, and `OPENQODEX_HOME` moves it with the rest of `~/.openqodex/`.
+
+- `update`: `on` or `off`. The default is `on`. `off` stops the daily version check. `openqodex update --off` and `--on` write it.
+
+A file that does not parse, or an `update` value that is neither `on` nor `off`, turns updates off until it is fixed. `openqodex doctor` says why updates are off.
+

package/docs/github-action.md

@@ -59,7 +59,7 @@ The repository also ships a pre-commit hook for the pre-push stage. Add this to
 ```yaml
 repos:
   - repo: https://github.com/openqodex/openqodex
-    rev: v0.2.1
+    rev: v0.4.0
     hooks:
       - id: openqodex-scan
 ```

package/docs/llms.txt

@@ -7,6 +7,7 @@
 - [FAQ](faq.md)
 - [GitHub Action](github-action.md)
 - [OpenQodex docs](index.md)
+- [Plumbing commands](plumbing.md)
 - [Quickstart](quickstart.md)
 - [Scanners](scanners.md)
 - [Security](security.md)

package/docs/plumbing.md

@@ -0,0 +1,93 @@
+# Plumbing commands
+
+`openqodex --help` lists four commands: `init`, `review`, `update` and `trust`. The commands below still work the same way. They are hidden from `--help` because hooks, the skill, the Action or OpenQodex itself call them, not people in daily use.
+
+## scan
+
+Plain `openqodex review` does the same. Kept under this name for the git pre-push hook of earlier releases, the pre-commit hook and the GitHub Action, which call it.
+
+```
+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.
+
+## doctor
+
+For you, when a scanner is missing or slow to install. The skill asks you to run `doctor --install` once when the agent runs in a sandbox.
+
+```
+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.
+
+Under "Updates" it prints the running version and whether the launcher started it, the newest version the last check saw and when, the last check, whether updates are on (and why not), and the last update error. For a version not started through the launcher (npx, a project-scope file), it says when that pinned version is behind the newest one a check saw. Without a check on this machine, it says nothing about that.
+
+`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.
+
+## hook
+
+Called by the agent push hooks and the git pre-push hook that `init` writes. You run `hook install` and `hook uninstall` yourself when you want the git hook without `init`.
+
+```
+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 `hook pre-push`, which scans each commit the push sends against the remote's tip of its branch (`agents` has the details). 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: `npx -y openqodex@<version> hook pre-push || [ $? -ne 1 ]`. The part after `||` makes the line stop the push only on exit 1, as the hook `hook install` writes does: a scan that fails for its own reasons (exit 2) never stops the push.
+
+`init` asks whether to install the git hook. `agents` explains the push gate.
+
+## guide
+
+For agents: the skill reads the docs offline with it.
+
+```
+openqodex guide [skill | topic]
+```
+
+`guide skill`, and `guide` with no topic, print the full review procedure of the running version: the shipped skill with every command written for the runner that started it, the launcher's full path when the launcher started it, else `npx -y openqodex@<version>`. The skill `init` writes in user scope is a short stub that tells the agent to run `<launcher> guide skill` and follow what it prints. With a topic, it prints that page of these docs. An unknown topic lists the topics and exits 2.
+
+## demo
+
+For a first look: builds a repo with planted bugs to scan.
+
+```
+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.
+
+## report
+
+Offered by OpenQodex itself after an internal failure.
+
+```
+openqodex report "<what went wrong>"
+openqodex report --send-last
+```
+
+- `report "<what went wrong>"`: report a problem with OpenQodex. It prints the issue it would create and the two choices, the same as after a failure. It exits 0. Words that hold a path, a file name, a key or token, or an email address are refused with exit 2: remove them and run it again. Your user name and the repository's name are replaced with `<name>`.
+- `report --send-last`: print the last issue shown in this repository again, then create it exactly as it was shown. Outside a repository it uses the last one shown outside a repository. It refuses a saved issue that is a link, is not in the saved shape, or changed after it was shown.
+
+The issue holds only the command and its flags, a short diagnostic, the status of each scanner, the operating system, the CPU type and the Node version. For a scanner the diagnostic is its failure class only, such as `exited with code 2` or `timed out after 60 s`, never its output. For an internal error it is the error's class and first line, cut to 120 characters. Every path, file name, key or token, email address, user name and repository name is removed first, and a custom scanner is shown as `custom scanner`. It never holds code, diffs, findings, config or logs.
+
+When the issue could not be saved, OpenQodex says so and does not offer `--send-last`.
+
+In a terminal, press 1 or 2. Any other key, Enter, Ctrl-C or the end of input counts as 2. Without a terminal (an agent, a git hook, CI), OpenQodex prints the issue and how to create it later with `openqodex report --send-last`; doing nothing ignores it.
+
+Choice 1 creates the issue with the GitHub CLI when `gh auth status` says you are signed in. Otherwise it opens the new issue page on GitHub with the title and body filled in, and prints the link. OpenQodex never signs you in. Choice 2 sends nothing. Nothing leaves your machine without choice 1. The last issue shown is kept in `.openqodex/last-report.json`, which git ignores.

package/docs/quickstart.md

@@ -53,6 +53,15 @@ review my whole repo with openqodex
 
 The agent runs `openqodex review --all --agent`. The scanners check every file, and the brief tells the agent where to start: the most-called functions and the files with the most scanner hits. See `docs/cli.md` for the details.
 
+To review a teammate's branch or a pull request before it merges, without leaving your own work, say:
+
+```
+review the branch feature/login with openqodex
+review pull request #42 with openqodex
+```
+
+The agent runs `openqodex review --agent feature/login` or `openqodex review --agent '#42'`. OpenQodex fetches the branch or the pull request, checks it out in a temporary folder and reviews what it added since it left its base. Your working folder is not touched. See "Reviewing a branch or a pull request" in `docs/cli.md`.
+
 ## 3. Read the report
 
 The agent tells you the verdict and the most serious findings. The full report is in `.openqodex/reviews/<time>-<id>/report.md` in your repo. `.openqodex/.gitignore` keeps the reports out of git; `git status` shows only the two files above and that `.gitignore`, the first time.

package/docs/scanners.md

@@ -35,6 +35,12 @@ The report lists every selected scanner with one status. A scanner left out with
 
 A scanner problem never changes the exit code.
 
+## Changed scanner settings
+
+Several scanners read settings or an ignore list from the repository, as OpenQodex runs them. At the repository root only: gitleaks `.gitleaks.toml`, `gitleaks.toml` and `.gitleaksignore`; semgrep `.semgrepignore`; hadolint `.hadolint.yaml` and `.hadolint.yml`; actionlint `.github/actionlint.yaml` and `.github/actionlint.yml`. In any folder: ruff `ruff.toml` and `.ruff.toml`, and `pyproject.toml` when the change touches its `[tool.ruff` table; shellcheck `.shellcheckrc` and `shellcheckrc`; osv-scanner `osv-scanner.toml`. A change to one of them can hide that scanner's findings.
+
+In a review, each such changed file is a major candidate of that scanner, rule `settings-file`, on its first changed line; the reviewer verifies it and raises it or drops it with a reason. In a scan (`scan`, plain `review`, the git hook, the Action) nobody can clear it, so the report lists it under "This change edits a scanner settings file" and it never counts toward the verdict. `--only`, `--skip` and `scanners.disable` leave it out with its scanner.
+
 ## semgrep
 
 - Version: 1.94.0.

package/docs/security.md

@@ -25,7 +25,7 @@ npx openqodex trust
 
 The stored sha256 is checked against the project's checksum file when the project publishes one. Otherwise it is the hash of your first download. `custom-scanners` explains the difference.
 
-Agents that follow the OpenQodex skill are told never to run `openqodex trust` without asking you.
+Agents that follow the OpenQodex skill are told never to run `openqodex trust` without asking you. In user scope, `init` adds rules so Claude Code runs exactly `review --agent`, `review --finalize`, `review --agent --all` and `review --finalize --all` (each also with ` --offline`), `guide` and `guide <topic>` through the launcher without asking. An `ask` or `deny` rule in your own or your organisation's managed Claude Code settings still wins over these. Any other flag, any other command (`scan`, `doctor`, `trust`, `update`, `init`, `report`) and `init --project` grant nothing.
 
 ## What is sent where
 
@@ -37,10 +37,35 @@ OpenQodex and the built-in scanners use the network for these things only:
 - Semgrep rule packs. semgrep fetches `p/default`, `p/security-audit` and `p/secrets` from the Semgrep registry on each run. Its metrics are off. The rules are never bundled in the package.
 - The dependency check. When the change holds a lockfile, osv-scanner sends the names and versions of the dependencies in it to osv.dev. It never sends code.
 - Custom scanners. `openqodex trust` reads the release from the GitHub API and downloads the asset. After approval, a custom scanner does whatever its own command does.
+- The daily version check, for an install made with `init`. See "Updates" below.
+- A review of a branch or a pull request (`review <branch>`, `review '#<number>'`). git fetches the branch or `pull/<number>/head` from your remote with its own credentials, and `gh`, when it is installed and signed in, is asked for the pull request's base. OpenQodex reads no token. The target is checked out in `~/.openqodex/checkouts/`, a folder only you can open, with every git hook and filter switched off, so checking it out runs nothing from it, and a link in it becomes a small plain file. The scanners you approved for this repository do run on the target's files, with this repository's settings; one named only in the target's config never runs. If you review pull requests from people you do not trust, approve only custom scanners that do not execute the code they scan.
 
 golangci-lint runs with the Go module proxy off, so it downloads no modules.
 
-`--offline` skips osv-scanner and semgrep, which the report lists as disabled. It also turns scanner downloads off.
+`--offline` skips osv-scanner and semgrep, which the report lists as disabled. It also turns scanner downloads off and the version check. A review of a branch or a pull request with `--offline` fetches nothing and calls no `gh`.
+
+## Updates
+
+An install made with `npx openqodex init` runs through the launcher `~/.openqodex/bin/openqodex`. After a `review`, `scan`, `hook check` or `hook pre-push` that the launcher started, at most once every 24 hours, OpenQodex starts a background process and the command exits without waiting for it.
+
+What it sends: GET requests to `registry.npmjs.org` only, over https, with no body and no header but the user agent `openqodex/<version>`. First the openqodex package's release list. Then, for a newer release, its tarball and its attestations. Nothing about you, your code or your repository is sent. Every redirect must stay on `registry.npmjs.org`.
+
+What it installs: a release that is newer than the running one, in the same major version, at least 24 hours old, not deprecated, not a prerelease, and fit for your Node. Before any of its code runs:
+
+- the tarball's sha512 must equal the registry's `dist.integrity`;
+- its SLSA provenance must verify in full with Sigstore: the certificate chain to the Fulcio roots, the certificate transparency entry, the transparency log entry and the signature;
+- the signing certificate must be issued to `https://github.com/openqodex/openqodex/.github/workflows/release.yml@refs/heads/main` by `https://token.actions.githubusercontent.com`, compared exactly;
+- the signed statement must name `pkg:npm/openqodex@<version>` with the downloaded tarball's sha512.
+
+A stolen npm publish token is therefore not enough to reach your machine: the release must come out of this repository's release workflow on `main`. The 24 hour age is a window to deprecate a bad release before installs take it.
+
+The Sigstore trust data (Fulcio roots, log keys) ships inside each release, so verification makes no other network call. When Sigstore rotates a key that an old release does not know, that release cannot verify newer ones. It stays on its version and says once how to update by hand: `npx openqodex@latest init`.
+
+A verified release is unpacked into a temporary folder under `~/.openqodex/runtime/`. A link in the tarball, or a path that leaves the folder, stops it. No install script runs. The new copy must print its own version. Only then, holding the lock below, the updater checks again that updates are still on, that OpenQodex is still installed and that no other update, rollback or `init` changed the active version meanwhile. It then renames the copy to `~/.openqodex/runtime/<version>/` and switches `~/.openqodex/runtime/current` by a second rename. A version folder is never replaced: when one with other contents is already there, the release is skipped. An update writes no agent file and nothing inside a repository.
+
+The lock: while `init`, `init --uninstall`, `hook install`, `update --rollback`, `update --off`, `update --on` or an update's switch runs, OpenQodex briefly opens a listener on 127.0.0.1, on a port between 20000 and 32000 derived from the path of `~/.openqodex`, so that two of them never run at once; it accepts no data and answers nothing, and the operating system closes it when the process ends, however it ends. When the listener cannot be opened at all, those commands stop with one line saying why, and the daily check skips the switch. The port is predictable, so a local program that holds it stops install, uninstall and updates until it lets go; nothing is installed or changed while it is held. A command that waited 60 seconds for it names the port and the line that shows the holder (`lsof -nP -iTCP:<port> -sTCP:LISTEN`), and the daily check records the same as its last error, which `openqodex update --status` and `doctor` show.
+
+Updates are off with `openqodex update --off`, `update: off` in `~/.openqodex/config.yaml`, `OPENQODEX_AUTO_UPDATE=0`, `--offline` or `OPENQODEX_OFFLINE=1`, and whenever `CI` is set. A run through `npx` or a project-scope file never checks.
 
 OpenQodex sends no telemetry. See `telemetry`.
 
@@ -59,7 +84,10 @@ In your home folder, under `~/.openqodex/` (`OPENQODEX_HOME` moves it):
 - `tools/<scanner>/<version>/`: the scanners.
 - `tools/uv-python/`: the Python 3.11 for semgrep and bandit.
 - `cache/`: the download caches for uv and npm.
-- `runtime/<version>/` and `bin/openqodex`: the copy of the package and the launcher that the hooks call, written by `init`.
+- `runtime/<version>/` and `bin/openqodex`: the copy of the package and the launcher that the hooks call, written by `init`. Updates add copies beside it; a copy is never changed after it is written. `init` and `openqodex update` remove copies older than 7 days, except the one `init` installed, the current one and the previous one.
+- `runtime/current`: the version the launcher runs, and on a second line the version a rollback goes back to.
+- `update.json`: the state of the version check, private to you.
+- `config.yaml`: your own settings; today only `update`.
 - `install.json`: what `init` and `hook install` wrote, so an uninstall removes only that.
 - `trust.json`: your approvals of custom scanners.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openqodex",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Open source code review that runs inside your coding agent, before you push.",
   "type": "module",
   "license": "Apache-2.0",
@@ -41,16 +41,18 @@
     "LICENSE",
     "NOTICE"
   ],
-  "dependencies": {},
   "devDependencies": {
     "@clack/prompts": "^1.8.1",
+    "@sigstore/bundle": "5.0.0",
+    "@sigstore/protobuf-specs": "0.5.2",
+    "@sigstore/verify": "4.1.2",
     "commander": "^14.0.3",
     "picocolors": "^1.1.1",
     "yaml": "^2.9.1",
     "zod": "^4.6.5",
     "@openqodex/core": "0.1.0",
-    "@openqodex/scanners": "0.1.0",
-    "@openqodex/graph": "0.1.0"
+    "@openqodex/graph": "0.1.0",
+    "@openqodex/scanners": "0.1.0"
   },
   "scripts": {
     "build": "tsup",