@codacy/verity-cli 0.31.0 → 0.31.1-experimental.4cbb87c

package/CHANGELOG.md

@@ -3,6 +3,388 @@
 All notable changes to Verity are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### 🎯 Setup finishes in one command
+
+- **`verity init` now derives the Standard itself.** When the service has nothing
+  for this repository, the CLI reads the codebase — languages counted, frameworks
+  read from the manifests (including nested ones, so a monorepo works),
+  architecture, build system, test framework — and assembles
+  `.verity/standard.yaml`, `.codacy/codacy.config.json`, Verity's own ESLint
+  config and `VERITY.md`. Then it pushes them. No Claude Code session, no model
+  turn, about two seconds, and it works offline.
+- **This closes a real hole.** Without a Standard, `analyze` answers
+  `400 STANDARD_NOT_FOUND` — so a user who ran `verity init`, started working and
+  never ran `/verity-setup` got an error on every agent turn and static-only
+  findings, in a project init had just called set up.
+- **The service still has first refusal.** If this repository already has a
+  Standard it is offered and adopted exactly as before; derivation is strictly
+  what happens when there is nothing to adopt. A local `standard.yaml` is never
+  overwritten without `--force`.
+- **An adopted Standard with no analysis config now gets one**, derived from the
+  Standard's own declared languages and mode — filling the gap without
+  re-authoring the team's rules as a competing version.
+- **New: `verity standard synthesize`** (`--intensity`, `--force`, `--push`) — the
+  same derivation on demand.
+- **`--config-only` rewrites just the analysis config** from the Standard already
+  in place. Existing projects need it: a stale config is common, and the only
+  other way to rewrite one was `--force`, which also replaces the Standard —
+  deleting hand-written `custom_patterns` to fix a file that was not the problem.
+- `verity doctor`'s advice is a command now, not "open Claude Code".
+
+**What is NOT derived:** `custom_patterns` stays empty. Project-specific rules are
+the one part of synthesis that reads for intent rather than for facts, and
+plausible-sounding rules invented from a dependency list would be enforced on
+every turn without anyone having agreed to them. `/verity-setup` remains for
+exactly that, and a later pass will propose them server-side.
+
+**The catalogue is re-derived, and an audit found more than two lists wrong.**
+Checking every curated list against the installed adapters: ESLint9 (25) and
+shellcheck (14) were already exact; **Ruff** (20) needed the adapter's slug,
+**Bandit** (10) and **Hadolint** (8) were missing their tool prefix — all 38 are
+now written as the adapter spells them. **PMD7's 12 cannot be fixed
+mechanically**: they are bare rule names and the adapter's are
+category-qualified, and the suffix is ambiguous across languages
+(`UnusedLocalVariable` exists under both `_apex_` and `_java_`), so picking one
+would enable a rule that can never fire. That is recorded in the catalogue the way
+Semgrep's gap already was, and the CLI drops PMD7 rather than configuring it.
+
+**A pinned slug still survives a rename.** Full spellings are right for a model
+copying from the catalogue, but a slug is the adapter's prose and changes between
+versions — so an id also resolves by its stable head (`Ruff_F401`), and a pinned
+long form that stops matching is not silently dropped.
+
+**Your analysis config heals itself on upgrade.** `verity init` now validates an
+existing config's ids and re-derives it from your Standard when the validator says
+they no longer resolve — and only then: a config that cannot be checked (no
+analysis adapter on the machine, which is an ordinary state since that install is
+allowed to fail) is reported as unverified and left exactly alone, never rewritten
+on a guess — the Standard is never touched, because it may carry hand-written
+`custom_patterns` and it is not the file with the problem. `verity doctor` reports
+the same state read-only (`⚠ ids do not resolve`) so it is visible without running
+anything. This is the path that matters for existing projects: an id that matches
+nothing disables its whole tool while reporting zero issues.
+
+**Carried into code, and now tested.** The analysis-config knowledge used to live
+in the skill's markdown for a model to follow: `patterns: []` means "all 2,900
+rules" rather than "none"; a mistyped pattern id disables a tool while reporting
+zero issues; ESLint must not be pointed at the project's own config or Verity's
+rule list degrades into a filter over it (VRT-108); Semgrep's ids are deliberately
+not derived yet, so the tool is dropped rather than configured empty. Every one of
+those is now an assertion.
+
+### ⌨️ The setup questions answer to arrow keys
+
+- **`verity init` no longer asks you to type a number.** Analysis intensity and
+  the review moments are arrow-key lists: `↑↓` to move, `space` to toggle a
+  moment, `enter` to confirm — with the recommended answer already under the
+  cursor and the default set already ticked, so **Enter alone still gives exactly
+  what it gave before**.
+- **Digits still work.** This prompt used to be "type a number", and muscle memory
+  should not be punished for an interface improvement — a digit moves the cursor
+  rather than confirming, so it composes with the arrows instead of being a
+  second, hidden way to answer. `j`/`k` move too.
+- **An empty moment selection is refused, not accepted.** Unticking everything and
+  pressing Enter says so instead of installing a review tool that reviews nothing
+  — the same invariant the typed prompt held by falling back.
+- **Three rungs of degradation, same default at each.** Arrow keys on a real
+  terminal; the typed number prompt when the terminal cannot do raw mode; the
+  default when there is no terminal at all or stdin ends. An interface improvement
+  must not become a new way for a setup to get stuck — CI, pipes and agent Bash
+  calls behave exactly as before.
+- **The terminal is restored on every exit,** including Ctrl+C, which restores
+  before exiting: raw mode left on outlives the process and makes the user's next
+  shell prompt unusable.
+
+## [Unreleased]
+
+### 🤝 Joining a project that already has a Standard
+
+- **`verity init` now offers the Standard the service already holds** for this
+  repository, instead of asking a model to invent a second one. Everyone after the
+  first person on a project — a teammate cloning the repo, the same person on
+  another machine, a CI box — gets the team's actual configuration
+  (`standard.yaml`, the analysis config, `.verityignore`, `VERITY.md`) written
+  straight to disk, and the model phase is skipped entirely.
+- **This is a correctness fix as much as a speed one.** `verity standard push`
+  auto-versions, so a re-synthesis does not produce a private copy — it produces
+  v4, and v4 is what the team is held to from then on.
+- **Nothing about it can block a setup.** No token, offline, a 404, a service that
+  errors: every one of those falls through to the regular flow. An unreliable
+  answer is never reported as "no Standard stored" — that would offer a fresh
+  synthesis over one the team already agreed.
+- Unattended runs (`--yes`, CI) adopt without asking, for the same reason: a CI
+  box quietly authoring a new version of the team's Standard is not an outcome
+  anyone would choose on purpose.
+- **`--no-adopt` opts out**, for a script that wants a fresh synthesis on purpose.
+  It skips the request as well as the write: asking a question whose answer is
+  discarded is a network call the user declined, and in a locked-down CI it is one
+  that can fail loudly for no reason.
+- **Declining is remembered per VERSION, never as a mute.** Say no and init stops
+  asking about *that* Standard — and offers the next one, because a new version is
+  new information. A boolean "never again" would have been the familiar
+  silent-forever failure: decline on Monday meaning to synthesize later, forget,
+  and every later run stays quiet while the project has no local config at all.
+
+### 🔧 Fixed
+
+- **An upgrade no longer removes the gates you chose.** `.verity/setup.json` only
+  exists from this release, so every project configured before it had no recorded
+  answer — including everyone who picked commit/push gates through the old
+  `/verity-setup`. The first upgraded `verity init` fell back to the shipped
+  default and reconciled those gates away, turning Stop back on. What you chose is
+  still legible in `.claude/settings.json`, so init reads it.
+- `verity doctor` names the artifact that is actually missing instead of telling
+  you to run a phase that will decline: with a Standard adopted and no analysis
+  config, `/verity-setup` would have answered "already configured".
+- The setup skill learned the same case — Standard present, analysis config
+  missing — and writes only the config rather than re-synthesizing the Standard.
+
+## [Unreleased]
+
+**Setup is one command.** `verity init` and `/verity-setup` were two half-flows
+that overlapped — and the overlap was not harmless: init wired the Stop hook,
+then the skill reconciled the hooks to a selection it asked for afterwards,
+silently removing what init had just reported installing. They are now one flow
+with one entry point.
+
+### 🎯 `verity init` is the whole setup
+
+- **It asks the questions whose answers it acts on** — analysis intensity, when
+  to review (on stop / before commit / before push), and cost & usage telemetry.
+  On the terminal, before anything is wired to them.
+- **Then it hands off to Claude Code** to finish the half that needs a model:
+  reading the codebase and synthesizing the Standard (`/verity-setup`). If Claude
+  Code isn't installed, or you are already inside a session, it prints the one
+  command instead. `verity setup` is an alias for the same command.
+- **`--yes` takes every recommended answer and asks nothing** (CI, scripts,
+  agents) — including the GitHub login, whose unattended answer is skip, so the
+  project stays local-only until you run `verity login`. `--no-setup` stops after
+  the deterministic phase. A re-run keeps the answers you gave interactively
+  instead of resetting them to the defaults.
+- **The hooks are written ONCE, to your selection.** Init reconciles instead of
+  installing-then-being-reconciled, so a project that chose commit+push no longer
+  gets a Stop hook installed and then removed. The always-on infra hooks (intent,
+  baseline, post-compact, session-end) are wired by that same path — previously
+  only the legacy installer added the last two, and `verity uninstall` left them
+  behind.
+
+### 🩺 `verity doctor`
+
+- **New command: what is set up here, and what is missing.** Prerequisites, which
+  phase has run, your recorded answers, the hook wiring, telemetry, and the
+  artifacts — plus a `next` list. `--json` is what `/verity-setup` reads, so the
+  skill no longer re-implements init's prerequisite checks (its own version told
+  you to install the analysis CLI by hand, which init had already installed for
+  you).
+
+### ✨ It looks like something now
+
+- **A wordmark on `verity init`**, and the flow is drawn as what it is: `Phase 1 of
+  2 · this machine`, then `Phase 2 of 2 · your Standard`. Steps are numbered
+  `[n/8]`, so a run that stops tells you where.
+- **Spinners on the two waits that are actually long** — the global install of
+  `@codacy/analysis-cli`, and the GitHub device flow, where the elapsed clock is
+  the difference between "waiting for you to approve" and a terminal that looks
+  hung. Nowhere else: seven of init's eight steps take milliseconds, and a spinner
+  on an instant step claims work that isn't happening. No progress bars either —
+  no step has a real percentage, so a bar would be an animation of a guess.
+- **The handoff to `/verity-setup` is framed and then verified.** Before: what
+  phase 2 does and roughly how long. After: what it actually produced, read from
+  disk (`standard.yaml`, the analysis config, `VERITY.md`), with elapsed time — so
+  quitting that session early no longer leaves you with no statement of what got
+  done. (No spinner over it: the Claude Code session owns the terminal and draws
+  its own status, so ours would be painting blind.)
+- **Colour is finally gated.** Every `[verity]` prefix used to carry raw ANSI into
+  CI logs, pipes, and agent transcripts. Colour and art now require a terminal on
+  stderr and honour `NO_COLOR` / `TERM=dumb`, with `FORCE_COLOR=1` to override.
+
+### 🧹 One writer per file
+
+- **`.gitignore`** — one whitelist block from one writer. Init used to write a
+  single `.verity/.snapshot/` line while the skill wrote a block that supersedes
+  it; an install with only the narrow line now upgrades, so `.verity/setup.json`,
+  `.baseline`, `.cache/` and whatever state file ships next are covered by
+  construction rather than by enumeration.
+- **A `.verity/` entry is repaired to `.verity/*`.** With the directory form git
+  cannot re-include the committed standard, and the symptom is not an error: a
+  project that looks configured while `.verity/standard.yaml` is silently ignored.
+  Committed machine state is also detected and offered for untracking.
+- **`CLAUDE.md`** — the post-task reflection instructions moved into the managed
+  block. The skill used to append them beside it, along with a second copy of the
+  memory pointer.
+- **A closed stdin no longer aborts an install.** A question that loses its
+  terminal (Ctrl+D, a pty that ends) falls back to the default instead of
+  crashing init between copying the skills and wiring the hooks.
+
+## [0.31.1] — 2026-08-27
+
+**Verity stops repeating itself.** A finding it had already closed could keep
+appearing on every run, for the life of the project, with no way to end it — and
+the one command you'd run to understand why would crash halfway through. Both
+are fixed.
+
+```bash
+npm install -g @codacy/verity-cli
+```
+
+### 🔁 A finding Verity has answered stops coming back
+
+- **When a finding is settled — you rebutted it, you waived it, it was
+  dispositioned — Verity now knows.** It used to keep its own local copy of what
+  it had said and never update it, so a finding that was formally closed on the
+  service still reappeared on every run. One reported case repeated six times
+  across two branches, including runs that never even looked at the file.
+- **`verity waive` stopped looking broken.** A waive worked, but this same stale
+  copy meant the finding kept printing anyway — so the disposition looked like it
+  had been ignored.
+- **Saying it again re-opens it.** If Verity raises a settled finding a second
+  time, it counts as open again. Answering a finding is not a mute switch, and
+  a real recurrence always wins.
+
+### 💬 The carried-findings notice tells the truth, and offers a way out
+
+- It **no longer calls those findings "blocking."** They did not *fail* your
+  run — a run that was otherwise passing printed "1 blocking finding(s)" every
+  turn, which reads as a failure that never happened. (It does still turn a PASS
+  into a WARN, and the notice now says only what is true.)
+- It now **names the way to resolve them**, instead of repeating a problem with
+  no stated exit.
+
+### 🐛 Fixes
+
+- **`verity status` no longer crashes partway through.** A pending item with no
+  priority threw an error mid-report, so everything below it — your active
+  tasks, your run history — silently never printed. It was also the one screen
+  that would have explained the repeating finding above.
+
+## [0.31.0] — 2026-08-25
+
+**The gate reviews exactly the change you're shipping — and people get the last
+word.** The theme of 0.31 is evidence and disposition. Every claim the gate
+makes is now bound to bytes it actually reviewed: a finding about a file that
+isn't in your change can no longer block it, leftovers from a previous run can
+no longer resurface as fresh criticals, and an old plan file that happens to be
+committed can no longer hijack what a push is judged against. Commits and
+pushes become a first-class review moment — the whole change ships for review,
+to a stronger model, on its own budget. And two new verbs, `verity waive` and
+`verity ignore`, let humans and agents put a disposition on the record that the
+gate *verifies* rather than obeys: every one is reasoned, audited, and voids
+itself the moment the evidence changes.
+
+```bash
+npm install -g @codacy/verity-cli
+verity init   # optional — refreshes the installed skill docs
+```
+
+### 🧾 No finding without the bytes
+
+- **A finding about a file that wasn't in the change can no longer block.**
+  Findings citing files whose bytes were not under review are downgraded to
+  pre-existing — downgraded, never dropped, and counted in the run's metadata.
+  This closes a real class of false blocks reproduced from production: stale
+  pending items from a previous run re-raised as blocking criticals against a
+  clean push — one of them literally labelled *"Not blocking"*.
+- **It reaches every installed CLI on deploy day** — the rule is enforced
+  server-side, with a client-side belt on top: the guard refuses to block on a
+  finding citing a file it never sent.
+- **What the gate said before is context, never a fresh finding.** Pending
+  items inform the review; they are no longer restatable as new findings.
+
+### 🚢 A commit or push is a first-class review moment
+
+- **The whole change ships for review.** Budgets at `pre-commit`/`pre-push`
+  are raised to **120 files / ~570 KB** (the interactive Stop turn is
+  unchanged at 40). A 45-file commit used to arrive as 40 files with 5
+  silently dropped — the gate was reviewing a different change than the one
+  landing.
+- **A stronger reviewer, when it matters most.** Git moments run on
+  **gpt-5.6-sol** at medium reasoning with a 3-minute budget; interactive
+  turns stay on the fast model. Overridable per project
+  (`process_constraints.git_moment_model` / `git_moment_reasoning_effort`).
+  Measured live: a 45-file, 318 KB push reviewed in ~52s.
+- **Intent is what the change contains.** Only documents that are *part of the
+  push* ride along as plans. A six-month-old committed plan can no longer gate
+  an unrelated push — and "the plan isn't fully implemented" is never a
+  finding; it informs intent alignment only.
+- The coverage line now carries the elapsed time — a longer review is fine
+  when it says so.
+
+### ✋ `verity waive` — accepted risk, on the record
+
+- **A human disposition now actually unblocks the gate.** A finding your
+  reviewers had explicitly accepted used to re-block every commit and push,
+  forever, with no documented way out.
+- `verity waive <pattern-id> --file <path> --reason "…"` — the reason is
+  mandatory (name the review, ADR, or ticket it records). The waive is bound
+  to the file's exact bytes: the same bytes pass for everyone, in any session
+  — **edit the file and the waive voids itself.** An assertion, not a mute
+  switch.
+- Every waive lands in the statements ledger, visible in run reports; at most
+  3 statements per call.
+- **A waive ends a security-pushback round.** The gate resists an *agent*
+  arguing a security finding away; a human-attributable disposition is exactly
+  the adjudication that round exists to wait for.
+
+### 🤫 `verity ignore` and `.verityignore`
+
+- **Declare a housekeeping window** — `verity ignore --turn --reason "…"` (or
+  `--for 30m`) for the agent-run `git pull` or dependency surgery that
+  shouldn't cost a review turn. **The declaration is checked, never
+  believed**: if a single file is authored during it, the whole window voids,
+  the review runs anyway, and the broken declaration is reported. Budgeted at
+  3 per session, spent on declaration — a void never refunds the attempt.
+- **`.verityignore`** — a committed, team-shared exclusion file at the repo
+  root, gitignore syntax: "is this file worth reviewing, ever?" Every
+  exclusion is named in the run's coverage ledger, never silent.
+- **You can't blind the gate in the same move.** If `.verityignore` is part of
+  a turn's change, *no* ignore rules apply to that turn at all — writing
+  `src/**` into it and the vulnerability into `src/` in one turn doesn't work.
+  Patterns that would exclude the whole repository are refused, and a pattern
+  that would have hidden a really-detected secret is warned about.
+
+### Migrating
+
+1. Server-side changes — the byte witness, the git-moment profile, waive
+   honouring — reach **every** installed client on deploy day with no action.
+2. `npm install -g @codacy/verity-cli` for the new commands (`verity waive`,
+   `verity ignore`, `verity config service-url`) and the raised git-moment
+   budget on the client side.
+3. Optionally re-run `verity init` once per repo to refresh the installed
+   skill docs; the CLAUDE.md guidance block updates automatically.
+4. To use `.verityignore`: create it at the repo root (gitignore syntax) and
+   commit it.
+
+[0.31.0]: https://github.com/codacy/verity-core/releases/tag/v0.31.0
+
+## [0.30.1] — 2026-08-24
+
+**The guard reviews the tree your command targets.** A focused release for
+everyone working with git worktrees — and the first piece of making routine
+turns free.
+
+- **Worktrees are reviewed correctly.** `cd ../wt && git push` used to review
+  the *main checkout's* push range; pushing from a worktree that had diverged
+  from its upstream reviewed drift that wasn't even on disk. The guard now
+  resolves *which repo, which tree, which range* from the command itself (cd
+  chains, `git -C`, remotes and refspecs), with ranges anchored at the
+  merge-base — worktrees can live anywhere.
+- **Named refusals over guesses.** When the command's target can't be resolved
+  (e.g. `--git-dir`, `GIT_WORK_TREE=`, or two pushes at two targets in one
+  command), the guard allows *without* review and says so loudly — it never
+  issues a verdict about a tree it guessed.
+- **Coverage is printed on every run**: the moment, tree, branch, range, the
+  files reviewed, and what was excluded and why.
+- **A user-typed `! command` turn no longer costs a Verity turn.** `! git
+  pull` used to run the full pipeline and then narrate, in Verity's voice, a
+  turn nobody took. It now exits fast and silent — keyed on evidence, never
+  the prompt: any authored file or agent tool call defeats the skip, and
+  commands that can write code (`! npm install`, redirects, pipes) are still
+  reviewed.
+
+[0.30.1]: https://github.com/codacy/verity-core/releases/tag/v0.30.1
+
 ## [0.30.0] — 2026-08-13
 
 **Verity feels smarter, and tuned to the session you're in.** The theme of 0.30

package/README.md

@@ -10,7 +10,73 @@ cd your-project
 verity init
 ```
 
-Then open the project in Claude Code and run `/verity-setup`.
+`verity init` is the whole setup, and it finishes on its own — no second tool, no
+model turn. It asks how deeply to review and when (on stop / before commit /
+before push) with arrow-key lists — `↑↓` to move, `space` to toggle, `enter` to
+confirm, and Enter alone takes the recommended answers — wires everything, offers
+the optional GitHub login, and then gets this project a Standard: **the one your
+team already has**, or one **derived from your codebase** if there isn't one yet.
+
+When it's done the gate is live on your next Claude Code session. `/verity-setup`
+is no longer part of setup; it is there when you want a model to propose
+project-specific rules.
+
+### Where the Standard comes from
+
+| Situation | What init does |
+|---|---|
+| The service has a Standard for this repo | offers it, and adopting writes it locally (see below) |
+| It doesn't, or you declined, or you're offline | **derives one from your codebase** and pushes it when signed in |
+| `.verity/standard.yaml` already exists | leaves it alone |
+
+The derivation is a lookup, not a guess: languages and frameworks are counted and
+read from your manifests, and the rules come from Verity's research-backed
+patterns reference — the same catalogue the setup skill uses. The one thing it
+does not invent is **project-specific patterns** ("every route under `api/` uses
+the auth middleware"); `custom_patterns` stays empty until a model proposes them
+or you write them by hand.
+
+### Joining a project that already uses Verity
+
+A Standard belongs to the project, not to your machine. So once you are signed in,
+init asks the service whether this repository already has one:
+
+```
+This repository already has a Standard on Verity: version 3, pushed by claude-code
+on 2026-08-12 · with analysis config and .verityignore
+Use the existing Standard? [Y/n]
+```
+
+Say yes and it writes `.verity/standard.yaml`, `.codacy/codacy.config.json`,
+`.verityignore` and `VERITY.md` straight from the service — no model phase, and no
+second version of your team's Standard (`verity standard push` auto-versions, so a
+fresh synthesis would become the version everyone is held to). Say no and it stops asking about
+that version — and offers the next one, since a new version is new information.
+With no Standard stored yet, the regular flow runs.
+`--no-adopt` opts out of the whole check, including the request. Offline, signed out, or a service
+that cannot answer: also the regular flow — setup has never needed the network and
+still doesn't.
+
+If Claude Code isn't on your PATH, or you're already inside a session, init prints
+the one command to run instead. `verity setup` is an alias for the same command.
+
+| Flag | Use |
+|------|-----|
+| `--yes` | Take the recommended answer for every question — no prompts at all (CI, scripts, agents). Includes the GitHub login, whose unattended answer is **skip**: the project stays local-only until you run `verity login`. |
+| `--no-setup` | Stop after the deterministic phase; don't launch Claude Code |
+| `--no-adopt` | Don't offer the Standard the service already holds for this repo — synthesize a fresh one. Skips the request entirely |
+| `--force` | Overwrite the installed skills even when they differ |
+
+Run `verity doctor` any time to see prerequisites, which phase is done, the hook
+wiring, and what is still missing.
+
+### Output
+
+Human output goes to **stderr**; stdout carries only data (`--json`). Colour, the
+wordmark, and the spinners appear only when stderr is a terminal, and honour
+`NO_COLOR` and `TERM=dumb`; `FORCE_COLOR=1` forces them on for a pipe that renders
+ANSI. In CI, in a pipe, or when init runs inside a Claude Code session you get the
+same information as plain lines — no art, no animation, no escape sequences.
 
 ### Permission denied?
 
@@ -49,7 +115,10 @@ No re-setup needed: your token, Standard, and run history all carry over.
 | Command | Description |
 |---------|-------------|
 | **Core** | |
-| `verity init` | Initialize Verity in current project |
+| `verity init` | Set up Verity in this project, end to end — questions, wiring, and the Standard (alias: `verity setup`) |
+| `verity doctor` | Prerequisites, setup phase, hook wiring, and what is still missing (`--json` for the machine-readable report) |
+| `verity standard synthesize` | Derive the Standard + analysis config from this codebase — no model, no network (`--push`, `--force`) |
+| `verity standard synthesize --config-only` | Rewrite only the analysis config, from the Standard already here — the fix for a stale one |
 | `verity analyze` | Run analysis on changed files (stop hook) |
 | `verity analyze --mode <mode>` | Force analysis mode (standard/plan/debug/skip) |
 | `verity review --files <paths>` | On-demand analysis (advisory) |
@@ -69,6 +138,7 @@ No re-setup needed: your token, Standard, and run history all carry over.
 | `verity logout --others` | Sign out every OTHER machine (e.g. a lost laptop) |
 | `verity logout --all` | Sign out everywhere, including here |
 | `verity hooks install` | Wire Claude Code hooks |
+| `verity hooks install --moments stop,pre-commit,pre-push` | Change WHEN Verity reviews (what `verity init` asks for) |
 | `verity standard push` | Upload project Standard |
 | **Knowledge** | |
 | `verity reflect` | Trigger knowledge extraction for current task |
@@ -85,7 +155,7 @@ No re-setup needed: your token, Standard, and run history all carry over.
 
 | Skill | Description |
 |-------|-------------|
-| `/verity-setup` | Project configuration wizard |
+| `/verity-setup` | Synthesizes the Standard + analysis config (the half of setup that needs a model; `verity init` launches it) |
 | `/verity-analyze` | On-demand analysis |
 | `/verity-status` | Project health dashboard |
 | `/verity-feedback` | Feedback (general + per-finding) |