@drkmttr/adhere 0.18.1 → 0.21.2

package/README.md

@@ -1,142 +1,137 @@
 <div align="center">
 <h1>adhere</h1>
-  <sup>A linter for non-deterministic rules. Powered by Typesafe</sup>
+  <br/>
+  <sup>A linter for non-deterministic rules. Powered by TypeSafe AI.</sup><br><br/>
+  <a href="https://dm.sh/adhere/"><img src="https://img.shields.io/website?url=https%3A%2F%2Fdm.sh%2Fadhere%2Fgetting-started%2F&up_message=healthy&logo=readme&logoColor=%23dddddd&label=docs&labelColor=%23000000" /></a>
+  &nbsp;
+  <img src="https://img.shields.io/npm/dm/%40drkmttr%2Fadhere?style=flat&logo=github&labelColor=%23181926&color=%23000000" />
+  &nbsp;
+  <a href="https://www.npmjs.com/package/@drkmttr/adhere"><img src="https://img.shields.io/npm/v/%40drkmttr%2Fadhere" /></a>
 </div>
 
-A linter for rules a normal linter cannot check, such as "Business logic should live in services", or "modules should expose lots of functionality behind a small API". Define rules as formatted markdown:
+<br />
+
+A linter for rules a normal linter cannot check, such as "business logic should
+live in services" or "modules should expose lots of functionality behind a
+small API". You can write a rule as a Markdown file, with code that shows it:
 
 ````md
 ---
-description: A third party API going offline should not also take our app down.
+description: A third-party API going offline should not also take our app down.
 ---
 
-Our APIs should never be coupled to some third party API on a critical path. The user facing
-side should be unaffected if it goes offline, and ingestion should happen in a separate asynchronous process.
+Our APIs should not depend on a third-party API on a critical path. The
+user-facing side should be unaffected if it goes offline, and ingestion should
+happen in a separate, asynchronous process.
 
 ## Should
 
 ```ts
-import googleMaps from "./lib/maps"
-import db from "./lib/db"
-import redis from "redis"
-import cron from "node-cron"
-
-// asume this is called by /api/restaurants/:zipcode
-export async function findRestaurants(zipCode: number) {
-  const results = db.restaurants.find({ where: { zipCode }})
-  return results
-}
+import db from "./lib/db";
+import googleMaps from "./lib/maps";
 
-export async startWorker() {
-  cron("0 0 * * *", async () => {
-    const since = Number(await redis.get("maps:sync:timestamp"))
-    const items = await googlemaps.findAll({ since, limit: 100 })
-    const syncItem = item => db.restaurants.upsert(item)
-    const next = items.sort((a, b) => b.id < a.id).at(-1)?.timestamp
-    const touch = () => redis.set("maps:sync:timestamp", next ?? Date.now())
+// GET /api/restaurants/:zipCode reads only our own database.
+export async function findRestaurants(zipCode: string) {
+  return db.restaurants.find({ where: { zipCode } });
+}
 
-    return Promise.all(items.map(item => syncItem(item))).then(touch)
-  })
+// A scheduled job copies new restaurants in, off the request path.
+export async function syncRestaurants(since: Date) {
+  const restaurants = await googleMaps.findAll({ updatedSince: since });
+  await Promise.all(restaurants.map((restaurant) => db.restaurants.upsert(restaurant)));
 }
 ```
 
-## Never
+## Should not
 
 ```ts
 import googleMaps from "./lib/maps";
-import db from "./lib/db";
 
-// asume this is called by /api/restaurants/:zipcode
-export async function findRestaurants(zipCode: number) {
-  // what happens when google maps goes down? how about latency? how about costs?
-  const results = await googleMaps.findAll({ where: { zipCode }, limit: 100 });
-  return results;
+// GET /api/restaurants/:zipCode
+export async function findRestaurants(zipCode: string) {
+  // When Google Maps is down, slow, or over quota, so is this endpoint.
+  return googleMaps.findAll({ where: { zipCode } });
 }
 ```
 ````
 
-Your rules are parsed, then adhere asks [Jev](https://typesafe.ai) (TypeSafe AI's
-System One model) whether the file breaks each rule, gets a calibrated
-probability per rule, and reports the ones above a threshold with the section of
-the file Jev points at. The report uses the same frame as `vp lint`.
-
-Here's a demo of what the output looks like.
+adhere asks [Jev](https://typesafe.ai), TypeSafe AI's System One model, whether
+each file breaks each rule. Jev answers with a calibrated probability. adhere
+reports each rule whose probability is above a threshold, and shows the part of
+the file Jev points at. The report looks like Oxlint's, the linter `vp lint`
+runs:
 
-<details>
-  <summary>
-    <h3>Demo 🎬</h3>
-  </summary>
-  <img alt="demo" align="center"  src="https://github.com/darkmatter/adhere/raw/main/eval/demo.gif" />
-</details>
-
-Presets for TypeScript, React, security, Effect, and alchemy are included.
-Run them to quickly adhere your agent to recommended rules.
-
-```sh
-bun add -g @drkmttr/adhere
-adhere login # save your typesafe api key
-adhere lint --preset typescript,react
-```
+![adhere lint demo](https://github.com/darkmatter/adhere/raw/main/eval/demo.gif)
 
 Rules a normal linter can check exactly, such as a banned import or a type
-error, belong in that linter. While it lints, adhere asks Jev whether a normal
-linter could check each of your rules. [`adhere validate`](#check-for-contradictions) lists the
-ones it thinks belong in a regular linter, and detects contradictions between
-your rules.
+error, belong in that linter. [`adhere validate`](#validating-rules) lists the
+rules Jev thinks a linter could check, and finds rules that contradict each
+other.
 
 ## Contents
 
 - [Install](#install)
-- [Quick start](#quick-start)
-- [Generate rules from your repo](#generate-rules-from-your-repo)
-- [Install rules from other repos](#install-rules-from-other-repos)
-- [Check for contradictions](#check-for-contradictions)
-- [Live evals](#live-evals)
-- [Writing good rules](#writing-good-rules)
-- [Commands](#commands)
-- [Reading the report](#reading-the-report)
-- [Rule format](#rule-format)
-- [Config](#config)
-- [Other Providers](#providers)
-- [Running lint](#running-lint)
-- [Comments and suppressions](#comments-and-suppressions)
-- [Cache](#cache)
+- [Getting Started](#getting-started)
+- **Rules**
+  - [Rule format](#rule-format)
+  - [Writing good rules](#writing-good-rules)
+  - [Generate rules from your repo](#generate-rules-from-your-repo)
+  - [Install rules from other repos](#install-rules-from-other-repos)
+  - [Presets](#presets)
+- **Usage**
+  - [Reading the report](#reading-the-report)
+  - [Config](#config)
+  - [Running lint](#running-lint)
+  - [Commands](#commands)
+- **Validate & improve rules**
+  - [Validating rules](#validating-rules)
+  - [Live evals](#live-evals)
+- **Advanced features**
+  - [State Hooks and Type-Awareness](#state-hooks-and-type-awareness)
+  - [Providers](#providers)
+  - [Comments and suppressions](#comments-and-suppressions)
 - [Agent skills](#agent-skills)
-- [How a file is judged](#how-a-file-is-judged)
-- [Upgrading](#upgrading)
-- [Development](#development)
+- **Reference**
+  - [Cache](#cache)
+  - [How a file is judged](#how-a-file-is-judged)
+- [Compose your AGENTS.md](#compose-your-agentsmd)
+- [Contributing](#contributing)
 - [License](#license)
 
 ## Install
 
-Add adhere to your repo's dev dependencies, and run it with `npx adhere` or
-`bunx adhere`:
+Install the standalone executable. It needs no Node or Bun, and runs in any
+directory, inside a repo or not:
 
 ```sh
-npm install -D @drkmttr/adhere
+curl -fsSL https://github.com/darkmatter/adhere/raw/main/scripts/install.sh | sh
 ```
 
-Or download the standalone executable, which needs no Node or Bun:
+It installs to `~/.local/bin`. If your shell can't find `adhere` afterwards, add
+that directory to your `PATH`.
+
+To pin adhere's version in a repo, so the team and CI run the same one, add it
+as a dev dependency and run it from the package:
 
 ```sh
-curl -fsSL --create-dirs -o ~/.local/bin/adhere \
-  https://github.com/darkmatter/adhere/releases/latest/download/adhere-$(uname -s)-$(uname -m)
-chmod +x ~/.local/bin/adhere
+bun add -d @drkmttr/adhere
+bun run adhere lint
 ```
 
-- The npm package brings its own TypeScript compiler. Opt in with
-  `--type-aware` or `typeAware: true` to add both
-  [`symbols` and `references`](#what-jev-reads); type awareness is off by default.
-  No other compiler setup is needed.
-- The standalone executable has no compiler. It runs the default, compiler-free
-  audit with workspace context, or code alone with `reads: []`. Type-aware audits
-  require the npm package or a checkout with its development dependencies.
-  It suits a global install that your agent config can always call.
-- It is built for macOS and Linux, on arm64 and x64, and for Windows x64:
-  download `adhere-Windows-x86_64.exe` from the
-  [latest release](https://github.com/darkmatter/adhere/releases/latest).
-- adhere sends each file it judges, with what it [reads](#what-jev-reads)
-  beside it, to Jev at `api.typesafe.ai`, authenticated with a TypeSafe AI API
+With npm or pnpm, add it the same way and run `npm exec adhere` or
+`pnpm exec adhere`. The package is `@drkmttr/adhere`: `adhere` on npm is an
+unrelated package.
+
+- The package includes the TypeScript compiler that
+  [type awareness](#what-jev-reads) needs. The standalone executable does not,
+  so it runs every audit except type-aware ones.
+- The [install script](scripts/install.sh) puts this machine's executable from
+  the [latest release](https://github.com/darkmatter/adhere/releases/latest) in
+  `~/.local/bin`. Run it again to update. The executable is built for macOS and
+  Linux, on arm64 and x64, and for Windows x64: download
+  `adhere-Windows-x86_64.exe` from the release.
+- adhere sends each file it judges to Jev at `api.typesafe.ai`, with what it
+  [reads](#what-jev-reads) beside it, authenticated with a TypeSafe AI API
   key.
 
 ### Login
@@ -154,298 +149,62 @@ adhere logout --openai   # deletes it, and only it
   saved beside the TypeSafe AI one, for a config whose provider is
   `openai()`; see [Providers](#providers).
 - `TYPESAFE_API_KEY`, when set, takes precedence over the saved key, so CI can
-  pass a key without a login. `OPENAI_API_KEY` does the same for OpenAI's.
-- The key is read only when a request is about to be sent. A run the cache
-  answers in full needs no key and no network.
-
-## Quick start
-
-```sh
-npx adhere init        # .adhere/config.ts, two example rules, and the dependency
-npx adhere login       # save your TypeSafe AI API key, once
-npx adhere validate    # check your rules' wording, and ask Jev whether any contradict
-npx adhere lint        # audit the working directory
-git add .adhere        # commit the rules, and the judgments they cost
-```
-
-### Init
-
-`adhere init` creates a config file, some example rules, and adds adhere as a
-dev dependency.
-
-It is safe to rerun: existing files are reported as skipped, and only `--force`
-overwrites them.
-
-## Generate rules from your repo
-
-Let an agent write your first rules with you. The
-[`adhere-setup`](./skills/adhere-setup/SKILL.md) skill walks it through setting
-adhere up in your repo:
-
-1. It reads where your conventions live: `AGENTS.md`, `CONTRIBUTING.md`, docs
-   and ADRs, your lint config, recent review comments, and the code others copy
-   from.
-2. It drafts the conventions a normal linter cannot check as rules, each with
-   real code from your repo, and sets aside the ones a linter could check.
-3. It adds the presets that fit your stack, and rules from your organization's
-   [shared repo](#install-rules-from-other-repos), if you have one.
-4. It shows every candidate in one list, with its evidence, and imports the ones
-   you choose.
-5. It validates them, walks you through the first lint and what it costs, and
-   adds adhere to CI.
-
-It stops to ask you at each of those decisions, and never asks for your API key.
-
-```sh
-skills add darkmatter/adhere   # install adhere's skills for your agent
-```
+  pass a key without a login. `OPENAI_API_KEY` does the same for the saved
+  OpenAI key.
+- The key is read only when a request is about to be sent. A run that the
+  cache answers in full needs no key and no network.
 
-Then ask your agent to set adhere up.
-
-## Install rules from other repos
+## Getting Started
 
-An organization's rules can live in one repo's `.adhere/rules/`, and other repos
-copy them in with `adhere install`:
+Install the executable (see [Install](#install)) and save your TypeSafe AI API
+key once (see [Login](#login)), then try the built-in presets on your code
+before you write a rule of your own. The executable runs in any directory:
 
 ```sh
-adhere list darkmatter/standards                        # each rule there, with its description
-adhere install darkmatter/standards                     # every rule
-adhere install darkmatter/standards/data                # the data topic
-adhere install darkmatter/standards/data/brand-ports    # one rule
-adhere install darkmatter/standards#v3                  # every rule, as tagged v3
+adhere login
+adhere lint --preset typescript,react
 ```
 
-- Copies land in this repo's `.adhere/rules/org/repo/`. So `data/brand-ports`
-  from darkmatter/standards is
-  `.adhere/rules/darkmatter/standards/data/brand-ports/`, the rule
-  `darkmatter/standards/data/brand-ports`, and two repos' rules never collide.
-- The copies are the repo's own rules from then on: commit them, edit them, or
-  start new rules from them. Nothing tracks where they came from.
-- A later install skips a rule already there, as init does. `--force` replaces
-  its directory, edits and all.
-- A rule's whole directory is copied. The source's config, its inline rules, and
-  its cache are not.
-
-> **Read what you install.** A `RULE.ts` is copied with the helpers beside it,
-> and runs whenever lint does, in CI too. `adhere list` names a `RULE.ts`
-> without its description, since reading it would run it.
-
-The source is cloned with `git` from `https://github.com/org/repo.git`, so a
-private repo needs git's credentials for GitHub, as `gh auth setup-git` sets up.
-To clone over SSH instead, let git rewrite the URL:
-`git config --global url.git@github.com:.insteadOf https://github.com/`.
-
-### Creating a shared repo
-
-`adhere init --shared org/repo` scaffolds a repo whose rules other repos copy in
-with `adhere install`, instead of one that lints itself. It writes the two
-example rules and no config, since install copies only rule files, and with
-them:
-
-| File                            | What it is for                                                                                                                                                                  |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `README.md`                     | Says what the repo is for, how to install its rules, and how to add one.                                                                                                        |
-| `.github/workflows/adhere.yaml` | Runs `adhere validate` on every push to main and every pull request, with the `TYPESAFE_API_KEY` secret. A pull request from a fork gets no secrets, so validate refuses there. |
-| `alchemy.run.ts`                | An [alchemy](https://alchemy.run) stack that creates the GitHub repo, or adopts it, and sets that secret from `TYPESAFE_API_KEY` when deployed with `npx alchemy deploy`.       |
-| `package.json`, `.gitignore`    | alchemy and effect, pinned to versions that work together, which init installs, and a `.gitignore` for them and alchemy's state.                                                |
-
-The repo is public unless you answer yes when init asks, at a terminal, whether
-to make it private. Other repos then need git's credentials for it to list and
-install its rules. Without a terminal it is public: change `visibility` in the
-stack to make it private.
-
-## Check for contradictions
+Without installing anything, `npx @drkmttr/adhere` or `bunx @drkmttr/adhere`
+runs the same commands. Presets cover TypeScript, React, security, Effect, and
+alchemy. See [Presets](#presets).
 
-Two rules contradict when no code can follow both, such as one that says errors
-must be thrown and one that says they must be returned. Each rule reads fine on
-its own, so a contradiction shows up only as code that breaks one rule or the
-other whatever you do. `adhere validate` finds them before lint does:
+To set up rules of your own in a repo:
 
 ```sh
-adhere validate                  # your rules
-adhere validate --preset effect  # your rules beside a preset's
-```
-
-```text
-Found 1 contradiction among configured rules:
-
-1. No code can follow both (0.91):
-   - errors/throw-tagged-errors (/repo/.adhere/rules/errors/throw-tagged-errors/RULE.md)
-     A function that fails must throw a tagged error, never return an error value.
-   - errors/return-results (/repo/packages/api/.adhere/rules/errors/return-results/RULE.md)
-     A function that fails must return a Result, never throw.
-
-Resolve by editing one rule, narrowing a nested rule's scope, or using the same rule id when the nested rule is meant to shadow the root rule.
-```
-
-It asks Jev about each pair of rules that apply to the same files, so it needs
-the API key, as `lint` does. A contradiction fails it, with exit code 1, so it
-can gate a pull request that adds a rule, as the workflow
-[`adhere init --shared`](#creating-a-shared-repo) writes does.
-
-It also runs two checks that are advice and never fail it:
-
-- **Wording**: each rule worded otherwise than the
-  [rule writing tips](#rule-writing-tips) recommend, with its file and how.
-- **The linter check**: while `lint` judges a file against one of your rules, it
-  also asks Jev whether a linter or type checker could decide the rule exactly,
-  on 10 files per rule. A rule flagged on 7 or more of them probably belongs in
-  a regular linter. One flagged on 3 to 6 reads differently from file to file,
-  so its description should say more precisely what it applies to. Preset rules
-  are left out.
-
-Two rules with the same id are never compared: a nested rule that shares an id
-shadows the other on purpose.
-
-## Live evals
-
-Try a change to a rule on your own code before you rely on it: run the current
-rule and the changed one side by side, and compare what each flags.
-
-1. Copy the rule's directory under a new id:
-
-   ```sh
-   cp -r .adhere/rules/data/brand-ports .adhere/rules/data/brand-ports-next
-   ```
-
-2. Give the copy `level: warning` in its front matter. Its findings show in
-   amber and never fail the run, so the experiment can sit in the repo, and in
-   CI, while you watch it.
-3. Change the copy: its description, its examples, its `appliesTo` or
-   `excludeIf`. To try giving Jev more to read, make the copy a `RULE.ts` with
-   an [`appendState`](#rules-as-typescript-files) hook.
-4. Run `adhere lint`, or `adhere lint --filter '<glob>'` to try it on part of
-   the repo first, and compare the two rules' findings on the same files.
-
-Judge the two by recall, the share of real violations each catches, and
-precision, the share of its flags that are real. Check the findings by hand, or
-with the [`adhere-fix`](./skills/adhere-fix/SKILL.md) skill, which verifies each
-one against its rule and the code. Then keep the better version under the
-original id, and delete the other.
-
-- **The copy costs nothing until you change it.** Judgments are cached by the
-  rule's text, not by its id, its level, or its threshold, so a copy that reads
-  the same as the original answers from the original's cache. Each change after
-  that judges the copy, and only the copy, once per file.
-- **Keeping the winner is free.** Moving the winning text to the original id
-  reuses its cached judgments.
-- **Counting each rule's findings** takes a pipe:
-  `adhere lint --yes | grep -c 'data/brand-ports-next:'`.
-
-## Writing good rules
-
-We've evaluated how Jev reads a rule, on the presets and on other repos, to
-catch the most violations with the fewest false positives. The
-[eval](eval/README.md#studies) has every study; these are the lessons for
-writing a rule.
-
-### Rule writing tips
-
-- **Say "must" and "never"**, in the description and in the headings over the
-  code, or "should" and "should not" for a guideline. Rewording the presets'
-  descriptions this way, with a bad example per rule, was the largest gain of
-  any study: at 0.8, as many caught, and 1 wrong where there had been 5 or 6
-  ([study](eval/studies/must-never.md)).
-- **Give one example of each kind**: one `must` block and one `never` block. A
-  bad example helped every wording, and at 0.9 caught 24 violations with none
-  wrong, where there had been 17
-  ([study](eval/studies/rule-vocabulary.md)). Either kind alone did worse, and
-  three of each did no better, for 1.58 times the tokens
-  ([study](eval/studies/example-count.md)).
-
-`adhere validate` lists each rule worded otherwise.
-
-### What else the studies found
-
-| Lesson                                                 | What the study found                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "Should" is for people, not a weaker check.            | Rules written with "should" and with "must" scored nearly the same ([study](eval/studies/rule-vocabulary.md)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| A wrong finding is usually the rule's fault.           | Above 0.8, 31 of 35 wrong findings repeated within a rule: a scope its words reach past, or the same misreading again. Fixing the wording fixes them together. Below 0.8, one-off misreads grow, to about one finding in six at 0.6 to 0.7 ([study](eval/studies/presets.md)).                                                                                                                                                                                                                                                                                                    |
-| Narrow a rule in its description.                      | Jev scores an `excludeIf` near 0.5 for real and false findings alike, so it thins a rule's findings about as much as a higher threshold ([study](eval/studies/presets.md)). Narrowing the description moves the judgment itself: scoping alchemy's idempotent-delete rule to providers' delete handlers dropped its findings elsewhere from 0.67–0.88 to 0.08–0.21, with nothing real lost ([study](eval/studies/idempotent-delete.md)).                                                                                                                                          |
-| Beware rules that turn on what the file does not show. | The weakest preset rules hinged on facts outside the file: whether a client has a default timeout, whether a script is an entry point, whether a key is public ([study](eval/studies/presets.md)). Warning below a context of 0.7 marked one finding in five, and those were real about half the time, where the rest were real three times in four ([study](eval/studies/sufficiency.md)). Make such a rule a warning, or give Jev the fact with [`typeAware` or workspace `reads`](#what-jev-reads), an [`appendState`](#rules-as-typescript-files) hook, or an `@adhere` note. |
-| Jev believes comments.                                 | Eight of nine real violations of the idempotent-delete rule carried a comment wrongly saying they were fine, and scored 0.31 to 0.62; without comments, all nine scored 0.81 or more ([study](eval/studies/idempotent-delete.md)). That is why adhere takes comments out. A fact Jev needs, such as an exemption, goes in an `@adhere` note, which stays ([study](eval/studies/comments.md)).                                                                                                                                                                                     |
-
-## Commands
-
-| Command                           | What it does                                                                                                              |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `adhere lint`                     | Audit the working directory. See [Running lint](#running-lint).                                                           |
-| `adhere validate`                 | Check the rules' wording, and ask Jev whether any contradict. See [Check for contradictions](#check-for-contradictions).  |
-| `adhere init [--force]`           | Scaffold `.adhere/config.ts` and two example rules. See [Init](#init).                                                    |
-| `adhere init --shared org/repo`   | Scaffold a repo of rules other repos install. See [Creating a shared repo](#creating-a-shared-repo).                      |
-| `adhere list org/repo`            | List the rules in another repo's `.adhere/rules/`. See [Install rules from other repos](#install-rules-from-other-repos). |
-| `adhere install org/repo`         | Copy them into this repo's `.adhere/rules/org/repo/`.                                                                     |
-| `adhere login`, `adhere logout`   | Save or delete a TypeSafe AI API key, or with `--openai`, an OpenAI one. See [Login](#login).                             |
-| `adhere skill [docs\|setup\|fix]` | Print an agent skill. See [Agent skills](#agent-skills).                                                                  |
-
-Bare `adhere` prints the help. `adhere <command> --help` lists a command's
-flags, and `adhere --completions <shell>` prints a completion script.
-
-## Reading the report
-
-A finding looks like this:
-
-```text
-  × data/brand-ports: A port must be a branded, range-checked integer, never a bare number.
-    confidence 0.93 · context 0.88
-   ╭─[src/server.ts:6:3]
- 1 │ import { Effect } from "effect";
- 2 │ import { listen } from "./listen.ts";
- 3 │
- 4 │ export const serve = Effect.gen(function* () {
- 5 │   const host = process.env.HOST ?? "localhost";
- 6 │   const port: number = Number(process.env.PORT ?? 3000);
-   ·   ──────────────────────────────────────────────────────
- 7 │   yield* listen({ host, port });
- 8 │   yield* Effect.log(`Listening on ${host}:${port}`);
- 9 │ });
-   ╰────
-  hint: const Port = Schema.Int.pipe(
-          Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
-          Schema.brand("Port"),
-        );
-
-  confidence  0–0.74 < 0.8 < 0.85–1  Jev's probability that the file breaks the rule
-  context     0–0.49 < 0.6 < 0.70–1  its probability that the file shows enough to decide
-
-Found 1 error.
-42 files, 3 judged, 39 cached.
+adhere init                # .adhere/config.ts, two example rules, and the dev dependency
+bun run adhere validate    # check your rules' wording, and ask Jev whether any contradict
+bun run adhere lint        # audit the working directory
+git add .adhere            # commit the rules, and the judgments they cost
 ```
 
-| Part               | What it tells you                                                                                                                                   |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `×` or `⚠`         | An error, or a warning, in amber, from a rule whose `level` is `warning`. Only errors fail the run.                                                 |
-| `data/brand-ports` | The rule's id, then its description. A preset's rule has the preset's name first, as in `effect/basics/gen-for-sequencing`.                         |
-| `confidence`       | Jev's probability that the file breaks the rule.                                                                                                    |
-| `context`          | Jev's probability that it sees enough to decide that.                                                                                               |
-| The excerpt        | The section of the file Jev points at. The line it names is underlined, or the lines, when it names several, are marked with a bar beside the code. |
-| `hint:`            | The rule's code that must be written. A rule with only code that must never be written shows that code instead, labeled `never:`.                   |
-| The legend         | Under the last finding: each score's threshold, between its range in red and its range in green.                                                    |
-
-**Score colors.** On a terminal, each score is colored by where it sits around
-its threshold:
-
-- If you're near the threshold (orange), consider adjustments.
-- Red is below the threshold, so lint never reports it: only the legend shows
-  that range.
+### Init
 
-**Low context.** Jev sees the file and what adhere [reads](#what-jev-reads)
-beside it, not your whole repo. So we also ask whether that shows enough to
-decide the rule at all. When `context` is below 0.6, it means Jev thinks it
-needs more info, which you can add with an `@adhere` comment. You may also see a
-hint:
+`adhere init` creates a config file and some example rules and, in a repo with
+a `package.json`, adds adhere as a dev dependency.
 
-```text
-  warning: this file may not show enough to check this rule
-     help: add what the code relies on outside this file as a note Jev reads:
-           // @adhere <the fact>, and how you know it
-```
+It is safe to rerun: existing files are reported as skipped, and only `--force`
+overwrites them.
 
-- On the eval, most findings with this warning were false, where about one in
-  five of all findings was ([study](eval/studies/sufficiency.md)). Check what
-  the code relies on outside the file before acting on it.
-- If you feel the threshold is too low/high, override it using `sufficiencyThreshold`
-  in the config.
+### The day-to-day loop
+
+After that, using adhere is a short loop:
+
+1. **Write or edit a rule** in `.adhere/rules/`. A rule is one sentence saying
+   what code must be, with code that shows it: see
+   [Rule format](#rule-format).
+2. **Run `adhere lint`.** It says what it found and what judging takes, and
+   asks before it sends anything: see [Running lint](#running-lint).
+3. **Read the findings.** Each finding names the rule, Jev's probability, and
+   the lines it points at: see [Reading the report](#reading-the-report).
+4. **Fix the code, the rule, or neither.** A wrong finding is usually the
+   rule's wording reaching too far: see
+   [Writing good rules](#writing-good-rules). Suppress a finding that is wrong
+   for this code alone with a comment that says why: see
+   [Comments and suppressions](#comments-and-suppressions).
+5. **Commit `.adhere/`, cache included.** Judgments are cached by file content
+   and rule text, so the next run, and CI, only pay for what changed: see
+   [Cache](#cache).
 
 ## Rule format
 
@@ -500,7 +259,7 @@ const port: number = Number(process.env.PORT);
 
 | Front matter             | Meaning                                                                                                                                        |
 | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `description`            | Required. One sentence saying what code must be, and never be.                                                                                 |
+| `description`            | Required. One sentence that says what code must be and what it must never be.                                                                  |
 | `threshold`              | The rule's own cutoff, in place of the config's.                                                                                               |
 | `level`                  | `warning` reports the rule's findings as warnings, which do not fail the run. Use it for a nit, or for a rule that tends to flag code wrongly. |
 | `tests`                  | Rules skip tests by default. `only` is for a rule about tests, which judges nothing else. `include` is for one that holds in tests as well.    |
@@ -517,8 +276,8 @@ const port: number = Number(process.env.PORT);
   not"), and cannot mix the two.
 - A rule with only a `never` block suits a rule with no single correct form to
   show, such as a hand-rolled retry loop or an error caught and dropped.
-- Neither goes in the other's place: code that must never be written, under
-  `must`, reads to Jev as the pattern to follow.
+- Put neither kind of code in the other's place: code that must never be
+  written, under `must`, reads to Jev as the pattern to follow.
 - Prose around the code is the rule's details: Jev reads it after the
   description, so use it to say why the rule holds or where it does not apply.
   The report shows the description alone.
@@ -532,7 +291,7 @@ const port: number = Number(process.env.PORT);
 - Only a heading that is the word alone names code, in any case and with or
   without a colon: `## Never:` does, `## Never do this` does not.
 - A fence can instead name its code after its language, as in `ts never`, which
-  GitHub does not show. A fence's own word wins over its heading's.
+  GitHub does not show. A fence's own word wins over its heading's word.
 - A rule inline in a config takes the same keys, with its code under `must`,
   `never`, `should`, and `shouldNot`, and its prose under `details`.
 - `loadRules(directory)` from the package root does the same load for your own
@@ -571,215 +330,296 @@ finding its matchers dropped, with their scores.
 > scored an `excludeIf` near 0.5 for real and false findings alike. See
 > [Writing good rules](#writing-good-rules).
 
-### What Jev reads
+### Rules as TypeScript files
 
-By default, Jev reads the file's code and its imported workspace packages, with
-no native compiler startup. Opt in with `typeAware: true` in the config or
-`adhere lint --type-aware` to add both compiler context maps for every rule:
+A rule's directory can hold a `RULE.ts` instead of a `RULE.md`. It
+default-exports `defineRule({...})`, which takes the same fields as a config's
+inline rule. TypeScript adds what a `RULE.md` cannot have: a
+[state hook](#state-hooks), which adds to what Jev reads for the rule, and
+[rule options](#rule-options), which each project that uses the rule sets.
 
-| Name                | What Jev reads                                                                                                                                                                              |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `workspacePackages` | The repo's own packages the file imports, each name with its directory, as in `{ "orders-core": "packages/orders" }`. A package it imports that is not listed is an installed one.          |
-| `symbols`           | The compiler's type blocks for each name, plus compiler documentation and JSDoc tags; not literal editor hover text.                                                                        |
-| `references`        | Whole declarations of symbols the code uses from other files of the repo, keyed by `symbol:repository-relative pathname`: a function with its body, a method without the rest of its class. |
+- adhere imports a `RULE.ts`, as it imports a config, so its code runs on
+  every lint.
+- It can import other files by relative path, such as a helper beside it in
+  its directory. The executable resolves no packages besides
+  `@drkmttr/adhere`.
+- A `RULE.ts` that default-exports no rule refuses the run.
 
-`symbols` omits standard-library and Node/Bun runtime built-ins, including their
-methods. Project and third-party symbols remain, even when they share a built-in
-name. Built-in type names can still appear inside those symbols' type signatures.
+### Where rules live
 
-`references` is a flat string-to-string map. Keys keep the symbol's name as used
-in the target code, including import aliases, and the pathname's original casing.
-Values are complete declaration excerpts, not incoming reference call sites.
-Overlapping declarations under one key are merged; disjoint excerpts are joined
-with `…` between them. For example, code importing `twice as scale` can receive:
+- Rules in the root `.adhere/rules/` apply project-wide.
+- A nested `.adhere/` scopes its rules to the directory that contains it. A rule
+  in `packages/api/.adhere/rules/data/brand-ports/RULE.md` has the same id,
+  `data/brand-ports`, but applies only to files under `packages/api/`.
+- If a nested rule has the same id as a root rule, the nearest containing
+  `.adhere/` shadows the less-specific rule for that subtree. Outside that
+  subtree, the root rule still applies.
+- Nested `.adhere/` directories are not discovered under `node_modules/`,
+  `dist/`, and the other [skipped directories](#what-gets-read).
 
-```json
-{
-  "references": {
-    "__comment": "Declarations of symbols used by the target code, provided only as context. Keys are symbol:repository-relative pathname; values are source excerpts, not incoming call sites.",
-    "scale:src/Math.ts": "export function twice(value: number): number {\n  return value * 2;\n}"
-  }
-}
+To keep your rules with the rest of your documentation, point `rules` at a
+directory such as `docs/adhere/`:
+
+```ts
+export default defineConfig({ presets: ["effect"], rules: "./docs/adhere" });
 ```
 
-When sent to Jev, each enabled `references`, `symbols`, and `workspacePackages`
-map includes a reserved `__comment` explaining its contents. These comments are
-included before `appendState` hooks and restored after hooks. Top-level guidance
-also tells Jev that these maps are context only: judge the target `code`, not the
-additional declarations or metadata.
+That directory holds a directory per rule, as `.adhere/rules/` does, and its
+rules apply project-wide.
 
-Each symbol's complete resolved content is truncated to 256 characters by
-default. Set `maxSymbolLength` in the config to change this limit. Documentation
-and JSDoc tags are first capped separately by `maxSymbolDocumentationLength`, also
-256 by default; `0` omits documentation and tags. Smaller limits reduce request
-size but can cut off type signatures, overloads, useful details, or examples.
+## Writing good rules
 
-`typeAware` defaults to `false`. When enabled, it adds **both** `symbols` and
-`references`, regardless of `reads`. The `reads` setting now chooses workspace
-context only: its default is `["workspacePackages"]`; `[]` omits that map.
-Legacy `"symbols"` or `"references"` entries in `reads` alone do not enable native
-context, and leaving them out does not disable it when `typeAware` is true.
+The [eval](eval/README.md#studies) measured how Jev reads a rule, on the
+presets and on other repos, to catch the most violations with the fewest false
+positives. It has every study. These are its lessons for writing a rule.
 
-```ts
-// .adhere/config.ts
-import { defineConfig } from "@drkmttr/adhere";
+### Rule writing tips
 
-export default defineConfig({
-  typeAware: true, // opt in to both symbols and references
-  reads: [], // omit workspacePackages, not compiler context
-});
-```
+- **Say "must" and "never"**, in the description and in the headings over the
+  code, or "should" and "should not" for a guideline. Rewording the presets'
+  descriptions this way, with a bad example per rule, was the largest gain of
+  any study: at 0.8 it caught as many violations as before, with 1 wrong
+  finding where there had been 5 or 6 ([study](eval/studies/must-never.md)).
+- **Give one example of each kind**: one `must` block and one `never` block. A
+  bad example helped every wording, and at 0.9 caught 24 violations with none
+  wrong, where there had been 17
+  ([study](eval/studies/rule-vocabulary.md)). Either kind alone did worse, and
+  three of each did no better, for 1.58 times the tokens
+  ([study](eval/studies/example-count.md)).
 
-For code alone, use `reads: []` with type awareness off; do not pass
-`--type-aware`. To retain workspace context without a compiler, leave the
-settings at their defaults.
+`adhere validate` lists each rule worded otherwise.
 
-Each name is the key Jev reads it under, so a rule's description can name it in
-backticks, as the questions name `code`:
+### What else the studies found
 
-````md
----
-description: A function imported from one of this repository's own packages, which the file's `workspacePackages` names, must be called through the package's namespace, never imported by its own name.
----
+- **"Should" is for people, not a weaker check.** Rules written with "should"
+  and with "must" scored nearly the same
+  ([study](eval/studies/rule-vocabulary.md)).
+- **A wrong finding is usually the rule's fault.** Above 0.8, 31 of 35 wrong
+  findings repeated within a rule: a scope its words reach past, or the same
+  misreading again. Fixing the wording fixes them together. Below 0.8, one-off
+  misreads grow, to about one finding in six at 0.6 to 0.7
+  ([study](eval/studies/presets.md)).
+- **Narrow a rule in its description.** Jev scores an `excludeIf` near 0.5 for
+  real and false findings alike, so it thins a rule's findings about as much as
+  a higher threshold ([study](eval/studies/presets.md)). Narrowing the
+  description moves the judgment itself: scoping alchemy's idempotent-delete
+  rule to providers' delete handlers dropped its findings elsewhere from
+  0.67–0.88 to 0.08–0.21, with nothing real lost
+  ([study](eval/studies/idempotent-delete.md)).
+- **Beware rules that turn on what the file does not show.** The weakest preset
+  rules hinged on facts outside the file: whether a client has a default
+  timeout, whether a script is an entry point, whether a key is public
+  ([study](eval/studies/presets.md)). Warning below a context of 0.7 marked one
+  finding in five, and those were real about half the time, where the rest were
+  real three times in four ([study](eval/studies/sufficiency.md)). Make such a
+  rule a warning, or give Jev the fact with
+  [`typeAware` or workspace `reads`](#what-jev-reads), an
+  [`appendState`](#state-hooks) hook, or an `@adhere` note.
+- **Jev believes comments.** Eight of nine real violations of the
+  idempotent-delete rule carried a comment wrongly saying they were fine, and
+  scored 0.31 to 0.62, while without comments all nine scored 0.81 or more
+  ([study](eval/studies/idempotent-delete.md)). That is why adhere takes
+  comments out. A fact Jev needs, such as an exemption, goes in an `@adhere`
+  note, which stays ([study](eval/studies/comments.md)).
 
-## Must
+## Generate rules from your repo
 
-```ts
-import * as Orders from "orders-core";
+Let an agent write your first rules with you. The
+[`adhere-setup`](./skills/adhere-setup/SKILL.md) skill walks the agent through
+setting adhere up in your repo:
+
+1. It reads where your conventions live: `AGENTS.md`, `CONTRIBUTING.md`, docs
+   and ADRs, your lint config, recent review comments, and the code others copy
+   from.
+2. It drafts the conventions a normal linter cannot check as rules, each with
+   real code from your repo, and sets aside the ones a linter could check.
+3. It adds the presets that fit your stack, and rules from your organization's
+   [shared repo](#install-rules-from-other-repos), if you have one.
+4. It shows every candidate in one list, with its evidence, and imports the ones
+   you choose.
+5. It validates them, walks you through the first lint and what it costs, and
+   adds adhere to CI.
+
+It stops to ask you at each of those decisions, and never asks for your API key.
+
+```sh
+skills add darkmatter/adhere   # install adhere's skills for your agent
 ```
 
-## Never
+Then ask your agent to set adhere up.
 
-```ts
-import { parse } from "orders-core";
+## Install rules from other repos
+
+An organization's rules can live in one repo's `.adhere/rules/`, and other repos
+copy them in with `adhere install`:
+
+```sh
+adhere list darkmatter/standards                        # each rule there, with its description
+adhere install darkmatter/standards                     # every rule
+adhere install darkmatter/standards/data                # the data topic
+adhere install darkmatter/standards/data/brand-ports    # one rule
+adhere install darkmatter/standards#v3                  # every rule, as tagged v3
 ```
-````
 
-- `symbols` and `references` use the SDK and native compiler pinned to exactly
-  `7.1.0-dev.20261009.1`, which the npm package installs. This prerelease contains
-  the tuple-reference serialization fix from [microsoft/TypeScript#64080](https://github.com/microsoft/TypeScript/issues/64080);
-  SDK and native executable must match that exact version. They use each file's
-  `tsconfig.json`, and work without one.
-- `symbols` is still a name-to-string map. Distinct binding/narrowing types get
-  distinct blocks; docs and JSDoc tags appear once per canonical symbol per file.
-  It has no IDE labels or selected-call overload presentation. Symbol/type queries
-  are batched, with independent SDK requests chunked to at most 8.
-- A name adhere does not have refuses the run, so a misspelled one does not go
-  unnoticed. So does `reads` in a rule: it is the config's alone.
-- What adhere has no name for, such as a file of the repository's, a rule in
-  TypeScript adds with [`appendState`](#rules-as-typescript-files).
-
-**Cost and privacy.** Opting into type awareness sends Jev more than the file it
-judges: whole declarations from other files, plus compiler-provided documentation
-and JSDoc tags in `symbols`, even with `includeComments` off. It also starts the
-native compiler during execution. The plan's estimate leaves those tokens out.
-Keep `typeAware` off to avoid that extra context and compiler work; changing
-`reads` only changes workspace context.
+- Copies land in this repo's `.adhere/rules/org/repo/`, so `data/brand-ports`
+  from darkmatter/standards lands in
+  `.adhere/rules/darkmatter/standards/data/brand-ports/` as the rule
+  `darkmatter/standards/data/brand-ports`, and two repos' rules never collide.
+- The copies are the repo's own rules from then on: commit them, edit them, or
+  start new rules from them. Nothing tracks where they came from.
+- A later install skips a rule already there, just as init does. `--force`
+  replaces its directory, edits and all.
+- A rule's whole directory is copied. The source's config, its inline rules, and
+  its cache are not.
 
-<details>
-<summary>Where the packages come from</summary>
+> **Read what you install.** A `RULE.ts` is copied with the helpers beside it,
+> and runs whenever lint does, in CI too. `adhere list` names a `RULE.ts`
+> without its description, since reading the description would run the file.
 
-- The packages are read on every run from the working directory's
-  `package.json`, whose `workspaces` npm, Bun, and Yarn read, and from
-  `pnpm-workspace.yaml`'s `packages`.
-- In a pattern, `*` is any directory and `**` any depth of them, and one that
-  starts with `!` leaves out what it matches. Each matched directory's
-  `package.json` gives the name, and its directory is given from the working
-  directory.
-- Nothing need be installed, so a run in CI reads the same packages as one on a
-  laptop.
-- A working directory that is not a workspace's root has none.
-- Only an import whose path is a plain string counts, and one of a subpath, such
-  as `orders-core/client`, counts as its package's.
+The source is cloned with `git` from `https://github.com/org/repo.git`, so a
+private repo needs git's credentials for GitHub, which `gh auth setup-git` sets
+up. To clone over SSH instead, let git rewrite the URL:
+`git config --global url.git@github.com:.insteadOf https://github.com/`.
 
-</details>
+### Creating a shared repo
 
-### Rules as TypeScript files
+`adhere init --shared org/repo` scaffolds a repo whose rules other repos copy in
+with `adhere install`, instead of one that lints itself. It writes the two
+example rules and no config, since install copies only rule files, and with
+them:
 
-A rule's directory can hold it as a `RULE.ts` instead, which default-exports
-`defineRule({...})`, taking the fields a config's inline rule does. What
-TypeScript adds is `appendState`, a hook on what Jev reads for the rule:
+- **`README.md`** says what the repo is for, how to install its rules, and how
+  to add one.
+- **`.github/workflows/adhere.yaml`** runs `adhere validate` on every push to
+  main and every pull request, with the `TYPESAFE_API_KEY` secret. A pull
+  request from a fork gets no secrets, so validate refuses there.
+- **`alchemy.run.ts`** is an [alchemy](https://alchemy.run) stack that creates
+  the GitHub repo, or adopts it, and sets that secret from `TYPESAFE_API_KEY`
+  when deployed with `npx alchemy deploy`.
+- **`package.json`** pins alchemy and effect, which init installs, to versions
+  that work together.
+- **`.gitignore`** keeps the installed packages and alchemy's state out of git.
 
-```ts
-// .adhere/rules/data/columns/RULE.ts
-import { defineRule } from "@drkmttr/adhere";
+The repo is public unless you answer yes when init asks, at a terminal, whether
+to make it private. Other repos then need git's credentials for it to list and
+install its rules. Without a terminal it is public: change `visibility` in the
+stack to make it private.
 
-export default defineRule({
-  description:
-    "A query must name only columns its table has in `schema`, and never a column it lacks.",
-  must: 'db.select("id", "email").from("users")',
-  never: 'db.select("mail").from("users")',
-  appendState: async (state, file, Bun) => ({
-    schema: await Bun.file("db/schema.sql").text(),
-  }),
-});
-```
+## Presets
 
-- The hook runs right before each request about the rule goes out. It gets the
-  request's state, the file the request is about, and Bun's API, and what it
-  returns is spread over the state.
-- The description can name a key the hook adds, in backticks, as the questions
-  name `code`.
-- A `RULE.ts` is imported, as a config is, so its code runs on every lint.
-- A rule with a hook goes to Jev in requests of its own, so only that rule reads
-  what its hook adds. Each of those requests sends the file and its context
-  again.
-- What the hook reads outside the file is not part of the cache: when
-  `db/schema.sql` changes, a file already judged is not judged again until it or
-  the rule changes.
+Built-in rule sets. Name one, or one of its topics, in the config's `presets`
+or with `--preset`:
+
+| Preset                                | Rules | For                                                   | What it asks for                                                                                                                                                                                                                                                                                |
+| ------------------------------------- | ----- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`typescript`](./presets/typescript/) | 11    | any TypeScript project                                | Data from outside checked at runtime, invalid states unrepresentable, errors never swallowed, resources released on every path, arguments not mutated, and tests that assert outcomes and stand alone.                                                                                          |
+| [`react`](./presets/react/)           | 10    | components and hooks                                  | Logic for an event in its handler rather than an effect, effects that clean up and ignore stale fetches, `useSyncExternalStore` for outside stores, state that neither copies props nor contradicts itself, and Server Functions and Server Components that guard what crosses to the client.   |
+| [`security`](./presets/security/)     | 4     | any project                                           | Secrets kept out of logs, error messages, and responses; parameterized SQL; no untrusted input in shell commands, `eval`, or file paths; and secrets compared in constant time. From OWASP's cheat sheets.                                                                                      |
+| [`effect`](./presets/effect/)         | 16    | code written with Effect                              | Steps sequenced with `Effect.gen`, instrumentation attached with `.pipe`, config read through a service and validated, secrets redacted, branded primitives and tagged unions, defects kept apart from typed errors, services built by layers, and tests with their own layers and `TestClock`. |
+| [`alchemy`](./presets/alchemy/)       | 41    | code that deploys with [alchemy](https://alchemy.run) | Where Config and bindings are read, which resources keep their data, how secrets stay out of bundles and logs, authorization on public URLs, migrations, durable workflows, and custom providers.                                                                                               |
+
+- Name presets in the config's `presets`, or on the command line with
+  `--preset`, repeated or separated by commas, as in `--preset effect,alchemy`.
+  Naming presets on the command line makes the config file optional, and
+  presets named in both places apply together.
+- A topic, one of a preset's subdirectories, is a preset of its own:
+  `--preset effect/basics` applies only the rules under
+  `presets/effect/basics/`, and `alchemy/secrets` applies only alchemy's
+  secrets rules. `security` has no topics.
+- To change a preset's rule without copying it, use [Overrides](#overrides).
+- [presets/README.md](./presets/README.md) lists every rule in each preset,
+  with a one-line summary and a link to the full rule.
 
 <details>
-<summary>More on the hook</summary>
+<summary>What every preset does</summary>
 
-- The state is what Jev reads beside each question: `code`, the file's sections
-  as Jev reads them, under their numbers from 1, as in
-  `{ code: { "1": "import …", "2": "export const …" } }`, beside what the
-  config's [`reads` and `typeAware`](#what-jev-reads) enable.
-- `file` is the file's absolute `path`, and its `contents` as written, comments
-  and all.
-- Nothing the hook returns is checked, so it can change `code` too, or replace
-  it: a hook can break its own rule's answers, and adhere does not stop it.
-- It can be async, and one that throws refuses the run, naming the rule. A
-  `RULE.ts` that default-exports no rule refuses the run too.
-- The plan counts the rule's requests, but not the tokens a hook adds, which
-  are not known until it runs. A request over Jev's context skips the file, as a
-  file too long does.
-- A `RULE.ts` can import other files by relative path, such as a helper beside
-  it in its directory, but the executable resolves no packages besides
-  `@drkmttr/adhere`.
-- `Bun` is typed when `@types/bun` is installed and `.adhere/tsconfig.json`
-  lists it, as `"types": ["bun"]`, and is `unknown` otherwise.
-- A config's inline rules can have `appendState` too.
+- It has no rules for what a linter checks exactly.
+  [presets/README.md](./presets/README.md) names the lint rules to turn on
+  instead.
+- A preset rule says "must" only where its source makes a requirement, and
+  "should" where the source gives advice.
+- A topic's rules keep the ids they have in the whole preset, so a topic and its
+  preset share cached judgments, and naming both applies each rule once.
+- `effect` and `alchemy` have no rule that `typescript` or `security` already
+  has, so a project on Effect or alchemy names `typescript` and `security` too.
 
 </details>
 
-### Where rules live
+## Reading the report
 
-- Rules in the root `.adhere/rules/` apply project-wide.
-- A nested `.adhere/` scopes its rules to the directory that contains it. A rule
-  in `packages/api/.adhere/rules/data/brand-ports/RULE.md` has the same id,
-  `data/brand-ports`, but applies only to files under `packages/api/`.
-- If a nested rule has the same id as a root rule, the nearest containing
-  `.adhere/` shadows the less-specific rule for that subtree. Outside that
-  subtree, the root rule still applies.
-- Nested `.adhere/` directories are not discovered under `node_modules/`,
-  `dist/`, and the other [skipped directories](#what-gets-read).
+A finding looks like this:
+
+```text
+  × data/brand-ports: A port must be a branded, range-checked integer, never a bare number.
+    confidence 0.93 · context 0.88
+   ╭─[src/server.ts:6:3]
+ 1 │ import { Effect } from "effect";
+ 2 │ import { listen } from "./listen.ts";
+ 3 │
+ 4 │ export const serve = Effect.gen(function* () {
+ 5 │   const host = process.env.HOST ?? "localhost";
+ 6 │   const port: number = Number(process.env.PORT ?? 3000);
+   ·   ──────────────────────────────────────────────────────
+ 7 │   yield* listen({ host, port });
+ 8 │   yield* Effect.log(`Listening on ${host}:${port}`);
+ 9 │ });
+   ╰────
+  hint: const Port = Schema.Int.pipe(
+          Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
+          Schema.brand("Port"),
+        );
 
-A repo that would rather keep its rules with the rest of its documentation can
-point `rules` at a directory such as `docs/adhere/`:
+  confidence  0–0.74 < 0.8 < 0.85–1  Jev's probability that the file breaks the rule
+  context     0–0.49 < 0.6 < 0.70–1  its probability that the file shows enough to decide
 
-```ts
-export default defineConfig({ presets: ["effect"], rules: "./docs/adhere" });
+Found 1 error.
+42 files, 3 judged, 39 cached.
+```
+
+| Part               | What it tells you                                                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `×` or `⚠`         | `×` marks an error. `⚠`, in amber, marks a warning from a rule whose `level` is `warning`. Only errors fail the run.                       |
+| `data/brand-ports` | The rule's id, then its description. A preset rule's id starts with the preset's name, as in `effect/basics/gen-for-sequencing`.           |
+| `confidence`       | Jev's probability that the file breaks the rule.                                                                                           |
+| `context`          | Jev's probability that it sees enough to decide that.                                                                                      |
+| The excerpt        | The section of the file Jev points at. When Jev names one line, it is underlined. When it names several, a bar beside the code marks them. |
+| `hint:`            | The rule's code that must be written. A rule with only code that must never be written shows that code instead, labeled `never:`.          |
+| The legend         | Under the last finding: each score's threshold, between its red range and its green range.                                                 |
+
+**Score colors.** On a terminal, each score is colored by where it sits around
+its threshold. The legend shows each color's range:
+
+- **Green** is well above the threshold.
+- **Amber** is near it, on either side. When many scores are amber, the
+  threshold may be too low or too high for the rule.
+- **Red** is well below it. `lint` never reports a `confidence` this low, so
+  only the legend shows that range. A red `context` marks the finding to doubt
+  first.
+
+**Low context.** Jev sees the file and what adhere [reads](#what-jev-reads)
+beside it, not your whole repo, so adhere also asks Jev whether that shows
+enough to decide the rule at all: the `context` score. When `context` is below
+the sufficiency threshold, 0.6 by default, Jev needs more than it sees, and the
+finding carries a warning:
+
+```text
+  warning: this file may not show enough to check this rule
+     help: add what the code relies on outside this file as a note Jev reads:
+           // @adhere <the fact>, and how you know it
 ```
 
-That directory holds its rules as `.adhere/rules/` does, a directory per rule,
-and they apply project-wide.
+- On the eval, most findings with this warning were false, compared with about
+  one in five of all findings ([study](eval/studies/sufficiency.md)). Check what
+  the code relies on outside the file before acting on such a finding.
+- Give Jev a fact it lacks with an `@adhere` note (see [Comments](#comments)).
+- Change the threshold with `sufficiencyThreshold` in the config, or with
+  `--sufficiency-threshold` for one run.
 
 ## Config
 
 A config file is optional. Without one, adhere reads the rules in
 `.adhere/rules/` and any `--preset`. A config names presets, sets the model,
-the thresholds, and what Jev reads, or gives rules inline. It sits in the
+the thresholds, and what Jev reads, or gives rules inline. Put it in the
 working directory of the repo being audited, at one of these paths (keep one):
 
 - `.adhere/config.ts`, the default, next to the rules
@@ -790,14 +630,8 @@ working directory of the repo being audited, at one of these paths (keep one):
 import { defineConfig } from "@drkmttr/adhere";
 
 export default defineConfig({
-  model: "jev-latest",
   threshold: 0.8,
-  sufficiencyThreshold: 0.6,
-  reads: ["workspacePackages"],
-  typeAware: true, // optional; false by default
   presets: ["effect"],
-  maxSymbolDocumentationLength: 256,
-  maxSymbolLength: 256,
   exclude: ["**/generated/**"],
   overrides: { "effect/basics/instrument-with-pipe": "off" },
   rules: {
@@ -815,25 +649,54 @@ type UserId = typeof UserId.Type
 });
 ```
 
-| Key                            | Default                 | Meaning                                                                                                                                                                |
-| ------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `model`                        | `"jev-latest"`          | The model id sent to TypeSafe.                                                                                                                                         |
-| `threshold`                    | `0.8`                   | Report a rule when Jev's probability is above this.                                                                                                                    |
-| `sufficiencyThreshold`         | `0.6`                   | Below it, a finding warns that Jev may not see enough to decide.                                                                                                       |
-| `presets`                      | none                    | Built-in rule sets, or their topics. See [Presets](#presets).                                                                                                          |
-| `rules`                        | `.adhere/rules/`        | Rules inline, as above, or a directory (see [Where rules live](#where-rules-live)). Either replaces `.adhere/rules/`: none of its rules, root or nested, is read then. |
-| `exclude`                      | none                    | Globs, relative to the working directory, of files no rule judges.                                                                                                     |
-| `overrides`                    | none                    | Settings for a rule by its id. See [Overrides](#overrides).                                                                                                            |
-| `includeComments`              | `false`                 | Send every comment to Jev. See [Comments](#comments).                                                                                                                  |
-| `reads`                        | `["workspacePackages"]` | Chooses workspace context only. `[]` omits it; native read entries do not enable type awareness. See [What Jev reads](#what-jev-reads).                                |
-| `typeAware`                    | `false`                 | Opt in to both compiler `symbols` and declaration `references`, regardless of `reads`. Also enabled by `--type-aware`.                                                 |
-| `maxSymbolDocumentationLength` | `256`                   | Maximum characters of each symbol's combined documentation and JSDoc tags, before `maxSymbolLength` applies. A non-negative integer; `0` omits them.                   |
-| `maxSymbolLength`              | `256`                   | Maximum characters of each complete `symbols[name]` string, including type signatures and documentation. A non-negative integer; `0` leaves names with empty content.  |
-| `provider`                     | TypeSafe's Jev          | Where the questions go instead, with its own model. See [Providers](#providers).                                                                                       |
-
-- An invalid shape refuses the run.
-- A config can import other files by relative path, but no packages besides
-  `@drkmttr/adhere`: the executable does not resolve `node_modules`.
+Every key, grouped by what it changes:
+
+**What adhere loads**
+
+- `presets` — default: none. Built-in rule sets, or their topics. See
+  [Presets](#presets).
+- `rules` — default: `.adhere/rules/`. Rules inline, as above, or a directory
+  (see [Where rules live](#where-rules-live)). Either form replaces
+  `.adhere/rules/`: none of its rules, root or nested, is read then.
+- `overrides` — default: none. Settings for a rule by its id. See
+  [Overrides](#overrides).
+- `exclude` — default: none. Globs, relative to the working directory, for
+  files no rule judges.
+- `instructions` — default: `.adhere/instructions/`, then
+  `.agents/instructions/`. Instructions directory relative to the config file,
+  used by `adhere postinstall`.
+
+**Thresholds**
+
+- `threshold` — default: `0.8`. Report a rule when Jev's probability is above
+  this.
+- `sufficiencyThreshold` — default: `0.6`. Below it, a finding warns that Jev
+  may not see enough to decide.
+
+**What Jev reads**
+
+- `reads` — default: `["workspacePackages"]`. The workspace context Jev
+  reads. See [What Jev reads](#what-jev-reads).
+- `typeAware` — default: `false`. Add the compiler's `symbols` and
+  `references`, as `--type-aware` does.
+- `includeComments` — default: `false`. Send every comment to Jev. See
+  [Comments](#comments).
+- `maxSymbolDocumentationLength` — default: `256`. Maximum characters of each
+  symbol's combined documentation and JSDoc tags, before `maxSymbolLength`
+  applies. A non-negative integer; `0` omits them.
+- `maxSymbolLength` — default: `256`. Maximum characters of each complete
+  `symbols[name]` string, including type signatures and documentation. A
+  non-negative integer; `0` leaves names with empty content.
+
+**Model**
+
+- `model` — default: `"jev-latest"`. The model id sent to TypeSafe AI.
+- `provider` — default: TypeSafe AI's Jev. Where the questions go instead, with
+  its own model. See [Providers](#providers).
+
+An invalid shape refuses the run. A config can import other files by relative
+path, but no packages besides `@drkmttr/adhere`: the executable does not
+resolve `node_modules`.
 
 <details>
 <summary>More on types in the editor</summary>
@@ -853,9 +716,531 @@ type UserId = typeof UserId.Type
 
 </details>
 
-### Providers
+### Overrides
+
+Use `overrides` to change a rule without copying its text into `rules`. Name
+the rule by the id the report shows. A preset rule's id starts with the
+preset's name, as in `alchemy/providers/idempotent-delete`:
+
+```ts
+export default defineConfig({
+  presets: ["effect", "alchemy"],
+  overrides: {
+    "alchemy/providers/idempotent-delete": { level: "warning", threshold: 0.9 },
+    "effect/basics/instrument-with-pipe": "off",
+  },
+});
+```
+
+| Value                           | Effect                                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `"off"`                         | drops the rule                                                                         |
+| `"warning"`, `"error"`          | sets its level                                                                         |
+| `{ level, threshold, options }` | sets any of them; `options` only for a rule that takes them ([options](#rule-options)) |
+
+An id that no preset or project rule has refuses the run, so a typo does not go
+unnoticed. A rule of a preset that the run does not name is accepted.
+
+### Precedence
+
+For the model and the threshold, highest first:
+
+1. `--threshold` on the command line
+2. the config file
+3. presets, in order (a later preset wins)
+4. the defaults, `jev-latest` and `0.8`
+
+For one rule:
+
+- A rule's own `threshold` beats all of the above for that rule.
+- An entry in `overrides` beats the rule's own `threshold` and `level`.
+- A rule in `rules` replaces a preset rule with the same id.
+
+`--sufficiency-threshold` beats the config's `sufficiencyThreshold`, which beats
+the default, `0.6`.
+
+## Running lint
+
+`adhere lint` judges the TypeScript files under the working directory against
+your rules, and prints a [report](#reading-the-report) of what it finds. It
+asks before it sends anything.
+
+### Before and during a run
+
+Before it judges anything, `lint` says on stderr what it found and what judging
+takes, and asks:
+
+```text
+200 files and 14 rules: 2800 checks, 1400 cached.
+Judging 100 files takes an estimated 100 requests to Jev, plus 1 or more for each file with a finding.
+Those carry about 1.9 million input tokens: about $0.08 at $0.042 per million, and more for locating findings.
+Estimates cover only code and workspace-package context; symbol/reference input, possible extra request splits, and size-skips are determined at send time.
+? Estimates cover only code and workspace-package context; symbol/reference input, possible extra request splits, and size-skips are determined at send time. Send an estimated 100 requests to Jev, about $0.08? › (Y/n)
+```
+
+- It asks only when stdin and stdout are terminals, and only when there is
+  something to send. `--yes` sends without asking.
+- The cost is adhere's estimate of the input tokens times the model's price.
+  Jev charges only for input tokens: $0.042 a million for `jev-latest`, per
+  [TypeSafe AI's models page](https://docs.typesafe.ai/models) in
+  September 2026. When type awareness is enabled, the estimate leaves out
+  `symbols` and `references`, which adhere reads as it sends each file, so a
+  run can cost more than it says.
+- A run that stops loses nothing: files finished before it stopped are cached,
+  so running again continues from there.
+
+<details>
+<summary>More on unknown prices and blocked files</summary>
+
+- For a model adhere has no price for, the plan gives the tokens alone.
+- The firewall in front of Jev's API can refuse a request whose code reads to
+  it as an attack, with a 403 and an HTML page rather than Jev's JSON. It
+  refuses the same request every run, so that file is skipped, the run goes on,
+  and the report lists each such file with Cloudflare's Ray ID, which
+  TypeSafe AI can look the block up by.
+- When only the question that finds the line is refused, the file's judgments
+  are kept, and a rerun sends that question alone.
+
+</details>
+
+### What gets read
+
+- `adhere lint` reads the TypeScript files under the working directory: `.ts`,
+  `.tsx`, `.mts`, and `.cts`. It does not read declaration files such as
+  `.d.ts`, adhere's own config files, or JavaScript.
+- When the working directory contains `agents/`, `apps/`, or `packages/`, only
+  those trees are read.
+- Below the working directory, anything under `node_modules/`, `dist/`,
+  `coverage/`, `vendor/`, `e2e/`, `references/`, `.adhere/`, `.agents/`,
+  `.claude/`, `.direnv/`, `.alchemy/`, or `.vite/` is skipped. The directories
+  above the working directory do not count.
+- `.gitignore` is not consulted.
+- A config's `exclude` lists globs, relative to the working directory, of files
+  no rule judges, such as generated code. It leaves them out of every run, as
+  `--filter '!<glob>'` leaves them out of one:
+
+  ```ts
+  export default defineConfig({ exclude: ["**/generated/**"] });
+  ```
+
+**Tests** are judged only by rules about tests, whose front matter says `tests`
+(see [Rules as Markdown files](#rules-as-markdown-files)). A test is:
+
+- a `.test` or `.spec` file, such as `a.test.ts` or `Button.spec.tsx`;
+- a fixture or test helper named as one, such as `fixtures.ts`,
+  `GitHubHttpFixtures.ts`, `ledger-copy.fixture.ts`, `linear-test-helpers.ts`,
+  or `test-utils.ts`;
+- any file under a `test/`, `tests/`, `__tests__/`, `testing/`, `fixtures/`,
+  `fixture/`, `__fixtures__/`, or `__mocks__/` directory.
+
+### Flags
+
+| Flag                                                     | What it does                                                                                                            |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `--preset <names>`                                       | Add built-in rule sets, or their topics. The config becomes optional. See [Presets](#presets).                          |
+| `--threshold <0 to 1>`                                   | Replace the config's threshold. Per-rule thresholds still apply.                                                        |
+| `--sufficiency-threshold <0 to 1>`                       | Replace the config's `sufficiencyThreshold`: a finding warns when its `context` is below it.                            |
+| `--type-aware`                                           | Add the compiler's `symbols` and `references`. See [What Jev reads](#what-jev-reads).                                   |
+| `--yes`, `-y`                                            | Send the requests without asking first.                                                                                 |
+| `--limit <files>`, `--rpm <requests>`, `--filter <glob>` | Bound how many files a run judges, how fast it sends, and which files it judges. See [Limiting a run](#limiting-a-run). |
+| `--deny-warnings`                                        | Fail on warnings as well as errors.                                                                                     |
+| `--log-level <level>`                                    | Log the run's work on stderr. See [Logging a run](#logging-a-run).                                                      |
+| `--json`, `--md`                                         | Write one JSON or Markdown file per violated rule to `.adhere/reports/`.                                                |
+| `--stdout`                                               | Print one combined report instead of files; use with `--json` or `--md`.                                                |
+
+### JSON and Markdown reports
+
+```sh
+adhere lint --json
+adhere lint --md
+adhere lint --json --md
+adhere lint --json --stdout > report.json
+adhere lint --md --stdout > report.md
+```
+
+`--json` and `--md` write one file per violated rule under `.adhere/reports/`
+by default. Both errors and warnings are included. Filenames URL-encode the
+rule id: `data/ports` becomes `data%2Fports.json` or `data%2Fports.md`.
+Use both flags together to write both formats. File output leaves stdout
+empty and prints the destination on stderr.
+
+Add `--stdout` to print all findings together as one JSON object or one
+Markdown document, without writing or replacing report files. Choose one
+format when using `--stdout`; mixing JSON and Markdown would make the JSON
+unparseable. Without a format flag, lint keeps its usual terminal report.
+Progress, prompts, and logs stay on stderr.
+
+JSON reports include `findings`, file counts (`files`, `judged`, `cached`,
+`skipped`, `waiting`), `blocked` files, the `suppressed` finding count, and
+`threshold` and `sufficiencyThreshold`. A rule file contains only that rule's
+findings, while the file counts describe the whole run. Each finding includes
+its rule id, severity (`level`), description, file, line ranges, excerpt,
+examples, confidence (`probability`), threshold, and context score when
+available. Markdown includes locations, scores, code excerpts, examples,
+and a summary. Paths are relative to the working directory; preset rule ids
+include the preset name.
+
+The generated `.adhere/reports/` directory is replaced on each completed
+file-output run, including filtered or limited runs. A run with no findings
+leaves it empty. Keep hand-written files elsewhere, and add `.adhere/reports/`
+to `.gitignore` if reports should stay local.
+
+All output modes preserve the usual exit codes; reports are produced even
+when findings fail the run. `--limit 0` only prints the plan on stderr,
+produces no report, and leaves existing report files untouched.
+
+### Limiting a run
+
+Three flags bound what a run does:
+
+- **`--limit <files>`** sends requests for at most that many files, taken in
+  path order. The rest wait. Since judgments are cached, the next run with the
+  same limit picks up where this one stopped. `--limit 0` shows the plan and
+  sends nothing. It counts files, not requests: one file can take several.
+- **`--rpm <requests>`** sends at most that many requests to Jev a minute,
+  evenly spaced, retries included. The plan says about how long they take.
+- **`--filter <glob>`** judges only the files whose path from the working
+  directory matches, such as `src/**` or `**/*.service.ts`. Wrap a glob in
+  single quotes so the shell does not expand it. Repeat the flag for more
+  globs, and start one with `!` to leave out what it matches.
+
+```sh
+adhere lint --filter 'packages/api/**' --filter '!**/generated/**' --limit 100 --rpm 30
+```
+
+### Logging a run
+
+`--log-level` logs the run's work on stderr:
+
+- **`debug`** logs the config it loaded, how many paths it listed, and how many
+  of them it reads. It logs each request to Jev, with the file it is for, about
+  how many tokens it carries, and how long it took. A failed attempt is logged
+  even when a retry hides it, with the HTTP status, Cloudflare's Ray ID, and
+  the start of what the API said.
+- **`trace`** also logs each file as it is read, planned, and answered from the
+  cache.
+
+stdout still carries only the report, so the log can go to a file of its own:
+
+```sh
+adhere lint --log-level debug 2> adhere.log
+```
+
+### Exit codes
+
+| Code | When                                                                                                                                           |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | Nothing is reported, or only warnings.                                                                                                         |
+| 1    | An error is reported. With `--deny-warnings`, a warning too.                                                                                   |
+| 1    | The run refuses, for example on an invalid config or rule file, a missing API key, or an unknown command or flag. A refusal prints its reason. |
+
+## Commands
+
+| Command                           | What it does                                                                                                                                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `adhere lint`                     | Audit the working directory. See [Running lint](#running-lint).                                                                                                                                                    |
+| `adhere validate`                 | Check the rules' wording, list rules a linter could check, and ask Jev whether any contradict. See [Validating rules](#validating-rules).                                                                          |
+| `adhere postinstall`              | Render instruction files into a managed block in `AGENTS.md`. See [Compose your AGENTS.md](#compose-your-agentsmd).                                                                                                |
+| `adhere rules create [idea]`      | Write a rule with a local coding agent's help (`claude`, `codex`, or `omp`): judge excerpts it finds, get a `RULE.md` or `RULE.ts`; org rules are pushed to the shared repo for a PR. `--setup` re-picks defaults. |
+| `adhere init [--force]`           | Scaffold `.adhere/config.ts` and two example rules. See [Init](#init).                                                                                                                                             |
+| `adhere init --shared org/repo`   | Scaffold a repo of rules other repos install. See [Creating a shared repo](#creating-a-shared-repo).                                                                                                               |
+| `adhere list org/repo`            | List the rules in another repo's `.adhere/rules/`. See [Install rules from other repos](#install-rules-from-other-repos).                                                                                          |
+| `adhere install org/repo`         | Copy those rules into this repo's `.adhere/rules/org/repo/`.                                                                                                                                                       |
+| `adhere login`, `adhere logout`   | Save or delete a TypeSafe AI API key, or with `--openai`, an OpenAI one. See [Login](#login).                                                                                                                      |
+| `adhere skill [docs\|setup\|fix]` | Print an agent skill. See [Agent skills](#agent-skills).                                                                                                                                                           |
+
+Bare `adhere` prints the help. `adhere <command> --help` lists a command's
+flags, and `adhere --completions <shell>` prints a completion script.
+
+## Validating rules
+
+`adhere validate` checks your rules three ways:
+
+```sh
+adhere validate                  # your rules
+adhere validate --preset effect  # your rules beside a preset's
+```
+
+- **Wording.** It lists each rule whose wording differs from what the
+  [rule writing tips](#rule-writing-tips) recommend, with its file and what
+  differs.
+- **The linter check.** While `lint` judges a file against one of your rules,
+  it also asks Jev whether a linter or type checker could decide the rule
+  exactly. It stops after 10 files per rule, and `validate` reports a rule once
+  it has all 10 answers. A rule flagged on 7 or more of them probably belongs in
+  a regular linter. One flagged on 3 to 6 reads differently from file to file:
+  make its description say more precisely what it applies to. Preset rules are
+  left out.
+- **Contradictions.** It asks Jev about each pair of rules that apply to the
+  same files. When there is such a pair, it needs the API key, as `lint` does.
+
+Wording and the linter check are advice and never fail `validate`. A
+contradiction fails it with exit code 1, so `validate` can gate a pull request
+that adds a rule. The workflow that
+[`adhere init --shared`](#creating-a-shared-repo) writes does this.
+
+Two rules contradict when no code can follow both, such as one that says errors
+must be thrown and one that says they must be returned. Each rule reads fine on
+its own, so a contradiction shows up only as code that breaks one rule or the
+other, whatever you do. `validate` finds it before `lint` does:
+
+```text
+Found 1 contradiction among configured rules:
+
+1. No code can follow both (0.91):
+   - errors/throw-tagged-errors (/repo/.adhere/rules/errors/throw-tagged-errors/RULE.md)
+     A function that fails must throw a tagged error, never return an error value.
+   - errors/return-results (/repo/packages/api/.adhere/rules/errors/return-results/RULE.md)
+     A function that fails must return a Result, never throw.
+
+Resolve by editing one rule, narrowing a nested rule's scope, or using the same rule id when the nested rule is meant to shadow the root rule.
+```
+
+Two rules with the same id are never compared: a nested rule that shares an id
+shadows the other on purpose.
+
+## Live evals
+
+Try a change to a rule on your own code before you rely on it: run the current
+rule and the changed one side by side, and compare what each flags.
+
+1. Copy the rule's directory under a new id:
+
+   ```sh
+   cp -r .adhere/rules/data/brand-ports .adhere/rules/data/brand-ports-next
+   ```
+
+2. Give the copy `level: warning` in its front matter. Its findings show in
+   amber and never fail the run, so the experiment can sit in the repo, and in
+   CI, while you watch it.
+3. Change the copy: its description, its examples, its `appliesTo` or
+   `excludeIf`. To try giving Jev more to read, make the copy a `RULE.ts` with
+   an [`appendState`](#state-hooks) hook.
+4. Run `adhere lint`, or `adhere lint --filter '<glob>'` to try it on part of
+   the repo first, and compare the two rules' findings on the same files.
+
+Judge the two by recall, the share of real violations each catches, and
+precision, the share of its flags that are real. Check the findings by hand, or
+with the [`adhere-fix`](./skills/adhere-fix/SKILL.md) skill, which verifies each
+one against its rule and the code. Then keep the better version under the
+original id, and delete the other.
+
+- **The copy costs nothing until you change it.** Judgments are cached by the
+  rule's text, not by its id, its level, or its threshold, so a copy that reads
+  the same as the original answers from the original's cache. Each change after
+  that judges the copy, and only the copy, once per file.
+- **Keeping the winner is free.** Moving the winning text to the original id
+  reuses its cached judgments.
+- **Counting each rule's findings** takes a pipe:
+  `adhere lint --yes | grep -c 'data/brand-ports-next:'`.
+
+## State Hooks and Type-Awareness
+
+Jev judges a file from its state: the file's `code`, and maps of context beside
+it. The config chooses the maps every rule reads (see
+[What Jev reads](#what-jev-reads)). A rule written in TypeScript can add state
+of its own with a hook (see [State hooks](#state-hooks)), and take settings
+from each project that uses it (see [Rule options](#rule-options)).
+
+### What Jev reads
+
+The state sent for one file, `packages/orders/src/total.ts`, with every map
+on and each map's `__comment` cut short:
+
+````json
+{
+  "code": {
+    "1": "import { formatCents } from \"money\";\nimport { sum } from \"./sum\";\n\nexport const total = (prices: number[]): string => formatCents(sum(prices));\n"
+  },
+  "workspacePackages": {
+    "__comment": "Workspace packages imported by `code`; …",
+    "money": "packages/money"
+  },
+  "dependents": {
+    "__comment": "What depends on the file `code` holds. …",
+    "packages": { "web": "packages/web" },
+    "files": ["packages/orders/src/index.ts"]
+  },
+  "symbols": {
+    "__comment": "Compiler-rendered types and documentation for symbols used in `code`; …",
+    "formatCents": "```typescript\n(cents: number) => string\n```\n\nFormats cents as dollars, as in `$12.50`.",
+    "prices": "```typescript\nnumber[]\n```",
+    "sum": "```typescript\n(values: number[]) => number\n```",
+    "total": "```typescript\n(prices: number[]) => string\n```"
+  },
+  "references": {
+    "__comment": "Declarations of symbols used in `code`. …",
+    "formatCents:packages/money/src/index.ts": "export const formatCents = (cents: number): string => `$${(cents / 100).toFixed(2)}`;",
+    "sum:packages/orders/src/sum.ts": "export const sum = (values: number[]): number => values.reduce((a, b) => a + b, 0);"
+  },
+  "__comment": "Only `code` is the audit target; it is split into numbered sections. All other state entries provide context, not additional code to audit."
+}
+````
+
+- **`code`** is always sent: the file's [sections](#how-a-file-is-judged),
+  numbered from 1, without [comments](#comments) unless `includeComments` is
+  on.
+- **`workspacePackages`**, on by default: the repo's own packages the file
+  imports, each with its directory. A package the file imports that is not
+  listed is an installed one.
+- **`dependents`**, off by default: the workspace packages whose
+  `package.json` depends on the file's package, and up to 50 files that import
+  the file by a relative path, with `omittedFiles` counting the rest. Imports
+  by package name or `tsconfig` path alias do not count, nor do files that
+  `--filter` or `exclude` leaves out. To find them, lint reads every file once
+  more before it plans.
+- **`symbols`**, with type awareness: the compiler's type of each name the
+  code uses, with its documentation and JSDoc tags, leaving out
+  standard-library and runtime built-ins. `maxSymbolLength` and
+  `maxSymbolDocumentationLength` cap each one (see [Config](#config)).
+- **`references`**, with type awareness: the whole declaration of each symbol
+  the code uses from another file of the repo, keyed by the name the code uses
+  and the declaring file's path. A function comes with its body, a method
+  without the rest of its class.
+- **`__comment`**, in each map and a rule's [`options`](#rule-options), tells
+  Jev what the map holds. The top-level one says only `code` is judged. adhere
+  adds them before a [state hook](#state-hooks) runs, and again to any map the
+  hook returns without one.
+
+`reads` in the config chooses the workspace maps, and `typeAware` adds the
+compiler's:
+
+```ts
+// .adhere/config.ts
+import { defineConfig } from "@drkmttr/adhere";
+
+export default defineConfig({
+  reads: ["workspacePackages", "dependents"], // default: ["workspacePackages"]
+  typeAware: true, // or --type-aware; off by default
+});
+```
+
+- `reads: []`, with type awareness off, sends the code alone. Neither
+  workspace map needs the compiler.
+- `typeAware` adds `symbols` and `references` whatever `reads` says. The
+  compiler uses each file's `tsconfig.json`, and works without one.
+- An unknown name in `reads` refuses the run. Only the config has `reads`.
+- A rule's description can name a map in backticks, as Jev's questions name
+  `code`. To give Jev something no map covers, such as another file, add it
+  with a [state hook](#state-hooks).
+- `adhere lint --log-level debug` logs a run's first request in full.
+
+**Cost and privacy.** Type awareness sends Jev more than the file it judges:
+whole declarations from other files, and the compiler's documentation and JSDoc
+tags in `symbols`, even with `includeComments` off. It also starts the native
+compiler during the run. The plan's estimate leaves those tokens out.
+
+<details>
+<summary>Where the packages come from</summary>
+
+- The packages are read on every run from the working directory's
+  `package.json`, whose `workspaces` npm, Bun, and Yarn read, and from
+  `pnpm-workspace.yaml`'s `packages`.
+- In a pattern, `*` is any directory and `**` any depth of them, and one that
+  starts with `!` leaves out what it matches. Each matched directory's
+  `package.json` gives the name, and its directory is given from the working
+  directory.
+- Nothing need be installed, so a run in CI reads the same packages as one on a
+  laptop.
+- A working directory that is not a workspace's root has none.
+- Only an import whose path is a plain string counts, and one of a subpath, such
+  as `orders-core/client`, counts as its package's.
+
+</details>
+
+### State hooks
+
+A rule can add to what Jev reads for it with `appendState`, a hook in its
+[`RULE.ts`](#rules-as-typescript-files) or in a config's inline rule:
+
+```ts
+// .adhere/rules/data/columns/RULE.ts
+import { defineRule } from "@drkmttr/adhere";
+
+export default defineRule({
+  description:
+    "A query must name only columns its table has in `schema`, and never a column it lacks.",
+  must: 'db.select("id", "email").from("users")',
+  never: 'db.select("mail").from("users")',
+  appendState: async (state, file, Bun) => ({
+    schema: await Bun.file("db/schema.sql").text(),
+  }),
+});
+```
+
+- The hook runs right before each request about the rule goes out. It gets the
+  request's state, the file the request is about, and Bun's API. What it
+  returns is spread over the state.
+- The description can name a key the hook adds, in backticks, as the questions
+  name `code`.
+- A rule with a hook goes to Jev in requests of its own, so only that rule reads
+  what its hook adds. Each of those requests sends the file and its context
+  again.
+- What the hook reads outside the file is not part of the cache. When
+  `db/schema.sql` changes, a file already judged is not judged again until it
+  or the rule changes.
+
+<details>
+<summary>More on the hook</summary>
+
+- `state` is what Jev reads beside each question: `code`, the file's sections
+  as Jev reads them, under their numbers from 1, as in
+  `{ code: { "1": "import …", "2": "export const …" } }`, beside the maps
+  [What Jev reads](#what-jev-reads) lists.
+- `file` is the file's absolute `path`, and its `contents` as written, comments
+  and all.
+- Nothing the hook returns is checked, so it can change `code` too, or replace
+  it. A hook can break its own rule's answers, and adhere does not stop it.
+- It can be async. A hook that throws refuses the run, naming the rule.
+- The plan counts the rule's requests, but not the tokens a hook adds, which are
+  not known until it runs. A request over Jev's context skips the file, as a
+  file too long does.
+- `Bun` is typed when `@types/bun` is installed and `.adhere/tsconfig.json`
+  lists it, as `"types": ["bun"]`. Otherwise it is `unknown`.
+
+</details>
+
+### Rule options
+
+A `RULE.ts` can take settings from each project that uses it, such as which
+paths run on the edge. It declares them as `options`, with an Effect Schema, and
+a config sets them under the rule's id in [`overrides`](#overrides):
+
+```ts
+// .adhere/rules/edge/no-node/RULE.ts
+import { defineRule, Schema } from "@drkmttr/adhere";
+
+export default defineRule({
+  description: "A file under a path in `options.edgePaths` must never import a `node:` module.",
+  never: 'import { readFileSync } from "node:fs";',
+  options: Schema.Struct({ edgePaths: Schema.Array(Schema.String) }),
+});
+```
+
+```ts
+// .adhere/config.ts
+export default defineConfig({
+  overrides: { "edge/no-node": { options: { edgePaths: ["src/edge", "workers"] } } },
+});
+```
 
-adhere asks TypeSafe's Jev by default. A provider asks another decision model
+- Jev reads the decoded settings as `options`, so the description can name them
+  in backticks. A rule's `appendState` gets them too, in its `state`.
+- A key the schema does not make optional must be set. An unset or invalid
+  option refuses the run, naming the rule. Options set for a rule that takes
+  none also refuse it.
+- A rule with options goes to Jev in requests of its own, as one with a hook
+  does. Each of those requests sends the file and its context again.
+- Changing a rule's options judges that rule again, and no other.
+- The plan counts the tokens options add. A file whose options leave no room
+  for a question is skipped before any request.
+- `Schema` is Effect's, re-exported by adhere. A `RULE.ts` needs no `effect` of
+  its own, and decodes with the same copy adhere does.
+- A `RULE.md` cannot take options.
+
+## Providers
+
+adhere asks TypeSafe AI's Jev by default. A provider asks another decision model
 instead, and adhere exports one for each model
 [the providers study](eval/studies/providers.md) measured:
 
@@ -868,13 +1253,13 @@ export default defineConfig({ provider: openai() });
 
 | Provider     | Asks                                                            | Options                          |
 | ------------ | --------------------------------------------------------------- | -------------------------------- |
-| `jev`        | TypeSafe's Jev, `jev-latest` by default                         | `apiKey`, `model`                |
+| `jev`        | TypeSafe AI's Jev, `jev-latest` by default                      | `apiKey`, `model`                |
 | `openai`     | OpenAI's `gpt-6-luna`, on its Decisions API                     | `apiKey`, `model`                |
 | `cloudflare` | Cloudflare's `clef`, by default, or `clef-flash`, on Workers AI | `accountId`, `apiToken`, `model` |
 
 - Without an `apiKey`, `jev` and `openai` ask with the key from
   [Login](#login).
-- Each also takes `fetch`, what sends its requests.
+- Each provider also takes `fetch`, the function that sends its requests.
 - Clef cuts a request too long for it short rather than refuse it, so
   `cloudflare` skips a file whose request reaches clef's limit: 64,000 tokens,
   or 24,000 for clef-flash.
@@ -910,20 +1295,20 @@ export default defineConfig({ provider: mine });
 - `state` is the file's code by section under `code`, beside what adhere read
   for it.
 - Each question has an `id`, the `question` as adhere phrases it, and the
-  `fields` it names in backticks, such as `rule`, `must`, and `never`. A `noul`
-  asks whether something holds. A `choice` asks for the key of one of its
-  `options`, and can have just one.
+  `fields` it names in backticks, such as `rule`, `must`, and `never`. A
+  `noul` asks whether something holds. A `choice` asks for the key of one of
+  its `options`. Its `options` can hold just one entry.
 - `ask` returns `{ answers }`: by id, a `noul`'s probability from 0 to 1, or a
   `choice`'s key. An id left out goes unanswered: its rule is not reported, and
   is asked again on the next run.
 - A rejection stops the run, but for three errors adhere exports:
-  `ContextOverflow` gets one retry without `references` when that map is present;
-  if the request still overflows, the file is skipped. `RequestBlocked` reports
-  it blocked, and `RequestFailed` is tried again, up to three times, when its
-  `status` is 0, for no answer, or a 408, 429, or 5xx.
+  `ContextOverflow` gets one retry without `references` when that map is
+  present; if the request still overflows, the file is skipped.
+  `RequestBlocked` reports it blocked, and `RequestFailed` is tried again, up
+  to three times, when its `status` is 0, for no answer, or a 408, 429, or 5xx.
 - adhere paces calls with `--rpm`, aborts `signal` after 30 seconds, and splits
-  requests to fit Jev's 64,000 tokens. A model that takes less splits further in
-  its `ask`.
+  requests to fit Jev's 64,000 tokens. A model that takes less splits further
+  in its `ask`.
 - `model` replaces the config's `model`. The cache keeps answers by it, so a
   new model is asked again.
 - A provider that sets `savedKey` to `"typesafe"` or `"openai"` gets that key
@@ -933,334 +1318,17 @@ export default defineConfig({ provider: mine });
 
 </details>
 
-### Presets
-
-| Preset                                | Rules | For                                                   | What it asks for                                                                                                                                                                                                                                                                                |
-| ------------------------------------- | ----- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`typescript`](./presets/typescript/) | 11    | any TypeScript project                                | Data from outside checked at runtime, invalid states unrepresentable, errors never swallowed, resources released on every path, arguments not mutated, and tests that assert outcomes and stand alone.                                                                                          |
-| [`react`](./presets/react/)           | 10    | components and hooks                                  | Logic for an event in its handler rather than an effect, effects that clean up and ignore stale fetches, `useSyncExternalStore` for outside stores, state that neither copies props nor contradicts itself, and Server Functions and Server Components that guard what crosses to the client.   |
-| [`security`](./presets/security/)     | 4     | any project                                           | Secrets kept out of logs, error messages, and responses; parameterized SQL; no untrusted input in shell commands, `eval`, or file paths; and secrets compared in constant time. From OWASP's cheat sheets.                                                                                      |
-| [`effect`](./presets/effect/)         | 16    | code written with Effect                              | Steps sequenced with `Effect.gen`, instrumentation attached with `.pipe`, config read through a service and validated, secrets redacted, branded primitives and tagged unions, defects kept apart from typed errors, services built by layers, and tests with their own layers and `TestClock`. |
-| [`alchemy`](./presets/alchemy/)       | 41    | code that deploys with [alchemy](https://alchemy.run) | Where Config and bindings are read, which resources keep their data, how secrets stay out of bundles and logs, authorization on public URLs, migrations, durable workflows, and custom providers.                                                                                               |
-
-- Name presets in the config's `presets`, or on the command line with
-  `--preset`, repeated or separated by commas, as in `--preset effect,alchemy`,
-  in which case the config file is optional. Presets named in both places apply
-  together.
-- A topic, one of a preset's subdirectories, is a preset of its own:
-  `--preset effect/basics` applies only the rules under
-  `presets/effect/basics/`, and `alchemy/secrets` only alchemy's secrets rules.
-  `security` has no topics.
-- To change a preset's rule without copying it, use [Overrides](#overrides).
-
-<details>
-<summary>What every preset does</summary>
-
-- It leaves out conventions a linter checks exactly. The notes on each preset
-  say which linter checks them.
-- A preset rule says "must" only where its source makes a requirement, and
-  "should" where the source gives advice.
-- A topic's rules keep the ids they have in the whole preset, so a topic and its
-  preset share cached judgments, and naming both applies each rule once.
-- Where effect or alchemy had a rule that `typescript` or `security` has, that
-  one is kept and the other is gone. typescript's
-  `async/network-calls-have-timeouts` replaced effect's
-  `basics/external-calls-are-resilient`, and `security/parameterized-queries`
-  and `security/no-secrets-in-output` replaced alchemy's
-  `data/parameterized-sql` and `secrets/never-logged-returned-or-output`. A
-  project on Effect or alchemy names `typescript` and `security` too, for those
-  rules.
-
-</details>
-
-<details>
-<summary>Notes on <code>typescript</code></summary>
-
-- **Source.** The TypeScript Handbook and the Google TypeScript Style Guide.
-- **Left to a linter.** What typescript-eslint and ESLint check exactly:
-  unhandled promises (`no-floating-promises`), throwing non-errors
-  (`only-throw-error`), `any` (`no-explicit-any`), exhaustive switches
-  (`switch-exhaustiveness-check`), a lost `cause` (`preserve-caught-error`), and
-  empty catch blocks (`no-empty`).
-- **Warnings.** Four of its rules report warnings. Three are advice that code
-  often has reason to set aside: assertions that claim only what the code
-  established, types derived rather than restated, and independent awaits run
-  concurrently. The fourth, that HTTP requests carry a timeout, was right on
-  fewer than half its findings above 0.8 on the eval: many of the rest were
-  calls through a client with a default timeout that the file does not show.
-- **Tests.** `testing/assert-outcomes` and `testing/independent-tests` say
-  `tests: only`: they judge tests and nothing else.
-- **Gone.** Two rules the eval found mostly wrong: that tests use fake time
-  rather than real waits, and that importing a module does no work.
-
-</details>
-
-<details>
-<summary>Notes on <code>react</code></summary>
-
-- **Source.** react.dev, mostly
-  [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
-  and
-  [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure).
-- **Left to a linter.** What the React Compiler's lint rules check, in
-  [eslint-plugin-react-hooks](https://react.dev/reference/eslint-plugin-react-hooks)'s
-  recommended set and in Oxlint: pure render (`purity`), props and state never
-  mutated (`immutability`), refs not read during render (`refs`), no `setState`
-  in render or synchronously in an effect (`set-state-in-render`,
-  `set-state-in-effect`), which covers state derived in an effect, and no
-  component defined inside another (`static-components`).
-- **Files.** Its rules judge `.ts` files as well as `.tsx`, and apply only to
-  components, hooks, effects, and Server Functions, so other files cost their
-  checks and find nothing.
-- **Warnings.** `server/no-private-data-to-client` reports warnings: a file does
-  not show whether the component it passes a record to is a Client Component. So
-  does `state/store-ids-not-copies`, which also flags state that copies a string
-  or an option from a fixed list, where a copy cannot go stale.
-
-</details>
-
-<details>
-<summary>Notes on <code>effect</code></summary>
-
-- **Source.** The
-  [effect-solutions](https://github.com/kitlangton/effect-solutions) docs and
-  the [effect/platform](https://effect.website/docs/platform/introduction/)
-  docs.
-- **Tests.** Three rules say `tests: only`, so they judge tests and nothing else:
-  `testing/test-clock-for-time`, `services/fresh-layer-per-test`, and
-  `config/tests-provide-values-directly`.
-- **Guidelines.** One rule says "should": a test of code that consumes config
-  provides it through a layer.
-- **Domain types.** The data rules judge the types services exchange, return,
-  or store. A shape that mirrors a payload until it is mapped, and a view's
-  props or state, are out of their scope.
-- **What the rules allow.** Config validation accepts `Config.mapEffect` as well
-  as `Config.schema`, and the variants rule does not rule out a `switch`.
-- **Gone.** The rule that a command handler only parses input: the docs show
-  that pattern but do not ask for it. The rule that test layers are in memory,
-  which flagged tests of real services: none of its findings labeled on the eval
-  or on darkmatter/agents was real. And the rule that service operations have no
-  requirements, which `leakingRequirements` below checks exactly.
-- **Left to a linter.** Effect's language service,
-  [`@effect/tsgo`](https://github.com/Effect-TS/tsgo) on TypeScript 7, checks
-  seven conventions exactly, which the preset checked through 0.7. Most are off
-  by default. `npx @effect/tsgo setup` installs it, and these lines in its
-  plugin options in `tsconfig.json` turn them on:
-
-  ```jsonc
-  "diagnosticSeverity": {
-    "strictEffectProvide": "warning", // layers are provided once, at the entry point
-    "leakingRequirements": "warning", // service methods have no requirements
-    "effectFnOpportunity": "warning", // a named function returning an Effect uses Effect.fn
-    "preferSchemaOverJson": "warning", // JSON is decoded with Schema, not JSON.parse
-    "nodeBuiltinImport": "warning", // platform services, not node: builtins
-    "globalFetch": "warning",
-    "globalFetchInEffect": "warning",
-    "processEnv": "warning",
-    "processEnvInEffect": "warning",
-    "globalRandom": "warning", // the Random service, not Math.random
-    "globalRandomInEffect": "warning",
-    "globalErrorInEffectFailure": "warning", // tagged errors, not Error
-    "extendsNativeError": "warning"
-  }
-  ```
-
-  `npx @effect/tsgo diagnostics --project tsconfig.json` runs them in CI. Bun
-  globals, which the old platform rule also ruled out, need a lint rule of their
-  own, such as `no-restricted-globals`.
-
-- **What the linter misses.** `leakingRequirements` sees a requirement in an
-  operation's type, but not a service built by a factory function that takes its
-  dependencies as arguments, whose types have no requirements to find. The
-  preset's `services/dependencies-through-layers` asks for that.
-
-</details>
-
-<details>
-<summary>Notes on <code>alchemy</code></summary>
-
-- **Source.** alchemy's docs and blog.
-- **Warnings.** `providers/idempotent-delete` reports warnings. Whether a delete
-  fails on a resource that is already gone is a fact about the API, which the
-  file does not show, so the rule also flags deletes of APIs that succeed
-  anyway. See [the study](eval/studies/idempotent-delete.md).
-
-</details>
-
-### Overrides
-
-A config's `overrides` changes a rule by the id a report names it with, a
-preset's with the preset first, without copying its text into `rules`:
-
-```ts
-export default defineConfig({
-  presets: ["effect", "alchemy"],
-  overrides: {
-    "alchemy/providers/idempotent-delete": { level: "warning", threshold: 0.9 },
-    "effect/basics/instrument-with-pipe": "off",
-  },
-});
-```
-
-| Value                  | Effect               |
-| ---------------------- | -------------------- |
-| `"off"`                | drops the rule       |
-| `"warning"`, `"error"` | sets its level       |
-| `{ level, threshold }` | sets either, or both |
-
-An id that no preset or project rule has refuses the run, so a typo does not go
-unnoticed. A rule of a preset the run does not name is accepted.
-
-### Precedence
-
-For the model and the threshold, highest first:
-
-1. `--threshold` on the command line
-2. the config file
-3. presets, in order (a later preset wins)
-4. the defaults, `jev-latest` and `0.8`
-
-For one rule:
-
-- A rule's own `threshold` beats all of the above for that rule.
-- An entry in `overrides` beats the rule's own `threshold` and `level`.
-- A rule in `rules` replaces a preset rule with the same id.
-
-`--sufficiency-threshold` beats the config's `sufficiencyThreshold`, which beats
-the default, `0.6`.
-
-## Running lint
-
-### Flags
-
-| Flag                               | What it does                                                                                   |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `--preset <names>`                 | Add built-in rule sets, or their topics. The config becomes optional. See [Presets](#presets). |
-| `--threshold <0 to 1>`             | Replace the config's threshold. Per-rule thresholds still apply.                               |
-| `--sufficiency-threshold <0 to 1>` | Replace the config's `sufficiencyThreshold`: a finding warns when its `context` is below it.   |
-| `--type-aware`                     | Enable both compiler `symbols` and declaration `references`; off by default.                   |
-| `--yes`, `-y`                      | Send the requests without asking first.                                                        |
-| `--limit <files>`                  | Send requests for at most that many files. See [Limiting a run](#limiting-a-run).              |
-| `--rpm <requests>`                 | Send at most that many requests a minute.                                                      |
-| `--filter <glob>`                  | Judge only the files a glob matches.                                                           |
-| `--deny-warnings`                  | Fail on warnings as well as errors.                                                            |
-| `--log-level <level>`              | Log the run's work on stderr. See [Logging a run](#logging-a-run).                             |
-
-### What gets read
-
-- `adhere lint` reads the TypeScript files under the working directory: `.ts`,
-  `.tsx`, `.mts`, and `.cts`. It does not read declaration files such as
-  `.d.ts`, adhere's own config files, or JavaScript.
-- When the working directory contains `agents/`, `apps/`, or `packages/`, only
-  those trees are read.
-- Below the working directory, anything under `node_modules/`, `dist/`,
-  `coverage/`, `vendor/`, `e2e/`, `references/`, `.adhere/`, `.agents/`,
-  `.claude/`, `.direnv/`, `.alchemy/`, or `.vite/` is skipped. The directories
-  above the working directory do not count.
-- `.gitignore` is not consulted.
-- A config's `exclude` lists globs, relative to the working directory, of files
-  no rule judges, such as generated code. It leaves them out of every run, as
-  `--filter '!<glob>'` leaves them out of one:
-
-  ```ts
-  export default defineConfig({ exclude: ["**/generated/**"] });
-  ```
-
-**Tests** are judged only by rules about tests, whose front matter says `tests`
-(see [Rules as Markdown files](#rules-as-markdown-files)). A test is:
-
-- a `.test` or `.spec` file, such as `a.test.ts` or `Button.spec.tsx`;
-- a fixture or test helper named as one, such as `fixtures.ts`,
-  `GitHubHttpFixtures.ts`, `ledger-copy.fixture.ts`, `linear-test-helpers.ts`,
-  or `test-utils.ts`;
-- any file under a `test/`, `tests/`, `__tests__/`, `testing/`, `fixtures/`,
-  `fixture/`, `__fixtures__/`, or `__mocks__/` directory.
-
-### Before and during a run
-
-Before it judges anything, `lint` says on stderr what it found and what judging
-takes, and asks:
-
-```text
-200 files and 14 rules: 2800 checks, 1400 cached.
-Judging 100 files takes an estimated 100 requests to Jev, plus 1 or more for each file with a finding.
-Those carry about 1.9 million input tokens: about $0.08 at $0.042 per million, and more for locating findings.
-Estimates cover only code and workspace-package context; symbol/reference input, possible extra request splits, and size-skips are determined at send time.
-? Estimates cover only code and workspace-package context; symbol/reference input, possible extra request splits, and size-skips are determined at send time. Send an estimated 100 requests to Jev, about $0.08? › (Y/n)
-```
-
-- It asks only with a terminal on stdin and stdout, and only when there is
-  something to send. `--yes` sends without asking.
-- The cost is adhere's estimate of the input tokens times the model's price. Jev
-  charges only for input tokens: $0.042 a million for `jev-latest`, per
-  [TypeSafe AI's models page](https://docs.typesafe.ai/models) in
-  September 2026. When type awareness is enabled, the estimate leaves out
-  `symbols` and `references`, which adhere reads as it sends each file, so a run
-  can cost more than it says.
-- A run that stops loses nothing: files finished before it stopped are cached,
-  so running again continues from there.
-
-<details>
-<summary>More on unknown prices and blocked files</summary>
-
-- For a model adhere has no price for, the plan gives the tokens alone.
-- The firewall in front of Jev's API can refuse a request whose code reads to it
-  as an attack, with a 403 and an HTML page rather than Jev's JSON. It refuses
-  the same request every run, so that file is skipped, the run goes on, and the
-  report lists each such file with Cloudflare's Ray ID, which TypeSafe AI can
-  look the block up by.
-- When only the question that finds the line is refused, the file's judgments
-  are kept, and a rerun sends that question alone.
-
-</details>
-
-### Limiting a run
-
-Three flags bound what a run does:
-
-| Flag               | Effect                                                                                                                                                                                                                                                         |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--limit <files>`  | Sends requests for at most that many files, taken in path order. The rest wait, and since judgments are cached, the next run with the same limit picks up where this one stopped. `--limit 0` shows the plan and sends nothing.                                |
-| `--rpm <requests>` | Sends at most that many requests to Jev a minute, evenly spaced, retries included. The plan says about how long they take.                                                                                                                                     |
-| `--filter <glob>`  | Judges only the files whose path from the working directory matches, such as `src/**` or `**/*.service.ts`. Wrap a glob in single quotes so the shell does not expand it. Repeat the flag for more, and start a pattern with `!` to leave out what it matches. |
-
-```sh
-adhere lint --filter 'packages/api/**' --filter '!**/generated/**' --limit 100 --rpm 30
-```
-
-`--limit` counts files, not requests: one file can take several.
-
-### Logging a run
-
-| Level               | What it logs, on stderr                                                                                                                                                                                                                                                                                                       |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--log-level debug` | The config it loaded, how many paths it listed and how many of them it reads, and each request to Jev, with the file it is for, about how many tokens it carries, and how long it took. A failed attempt is logged even when a retry hides it, with the HTTP status, Cloudflare's Ray ID, and the start of what the API said. |
-| `--log-level trace` | Also each file as it is read, planned, and answered from the cache.                                                                                                                                                                                                                                                           |
-
-stdout still carries only the report, so the log can go to a file of its own:
-
-```sh
-adhere lint --log-level debug 2> adhere.log
-```
-
-### Exit codes
-
-| Code | When                                                                                                                                           |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| 0    | Nothing is reported, or only warnings.                                                                                                         |
-| 1    | An error is reported. With `--deny-warnings`, a warning too.                                                                                   |
-| 1    | The run refuses, for example on an invalid config or rule file, a missing API key, or an unknown command or flag. A refusal prints its reason. |
-
 ## Comments and suppressions
 
 ### Comments
 
 Jev reads a file's code, not its comments. adhere takes every comment out before
 it hashes or sends a file, or a declaration from
-[`references`](#what-jev-reads), blanking it so every line keeps its number.
-The report's excerpts still show them. Compiler-provided documentation and
-JSDoc tags still reach Jev in the type/docs strings [`symbols`](#what-jev-reads)
-sends when type awareness is enabled; these are not editor hovers.
+[`references`](#what-jev-reads), blanking each one so every line keeps its
+number. The report's excerpts still show comments. Compiler-provided
+documentation and JSDoc tags still reach Jev in the type and documentation
+strings that [`symbols`](#what-jev-reads) sends when type awareness is on.
+These strings are not editor hovers.
 
 Jev takes what comments claim at their word, which hid real violations in the
 studies: see [Writing good rules](#writing-good-rules).
@@ -1283,7 +1351,7 @@ checked it, with how you know:
 
 ### Suppressing a finding
 
-A finding Jev got wrong is suppressed in the code, with a comment saying why:
+Suppress a finding Jev got wrong with a comment in the code that says why:
 
 ```ts
 // adhere-ignore alchemy/providers/idempotent-delete -- DeleteActivity succeeds on a missing activity; probed 2026-09-25
@@ -1304,22 +1372,81 @@ delete: Effect.fn(function* ({ output }) {
 - Jev never reads these comments, even with `includeComments: true`.
 - The summary counts the findings they suppress.
 
+## Agent skills
+
+Three skills teach an agent to work with adhere:
+
+- **[`adhere`](./skills/adhere/SKILL.md)**, printed by `adhere skill`, is the
+  reference: the commands, how to write and word a rule, the config, presets,
+  shared rules, comments and suppressions, the cache, reading a report, and
+  tuning a rule.
+- **[`adhere-setup`](./skills/adhere-setup/SKILL.md)**, printed by
+  `adhere skill setup`, sets adhere up in a repo with you. See
+  [Generate rules from your repo](#generate-rules-from-your-repo).
+- **[`adhere-fix`](./skills/adhere-fix/SKILL.md)**, printed by
+  `adhere skill fix`, verifies and fixes the findings `lint` reports: it
+  checks each against its rule and the code, fixes the real ones, reports the
+  false ones with the evidence, and says when a rule is wrong more often than
+  right.
+
+Install them with the [skills](https://github.com/vercel-labs/skills) CLI:
+`skills add darkmatter/adhere`. The binary carries all three, so
+`adhere skill fix > .agents/skills/adhere-fix/SKILL.md` works without a
+checkout.
+
+### In CI
+
+Pipe the fix skill into an agent that runs without asking. The skill tells it
+that invoking the skill permits every `adhere lint` run and its cost, and
+`adhere skill fix` prints the skill of the adhere that runs, so its flags
+match:
+
+```sh
+adhere skill fix | codex exec --yolo
+adhere skill fix | claude -p --dangerously-skip-permissions
+```
+
+Both turn off the agent's own permission checks, which suits a runner thrown
+away after the job. To keep Codex in its sandbox, let the sandbox reach
+`api.typesafe.ai`:
+
+```sh
+adhere skill fix | codex exec --sandbox workspace-write \
+  -c sandbox_workspace_write.network_access=true -c approval_policy=never
+```
+
+- Set `TYPESAFE_API_KEY` from a secret.
+- The agent adds no `adhere-ignore` comments or `@adhere` notes unless
+  `ADHERE_ALLOW_SUPPRESSIONS=1` is set in its environment, as in
+  `adhere skill fix | ADHERE_ALLOW_SUPPRESSIONS=1 codex exec --yolo`. It then
+  suppresses a finding it shows is false, or that three fixes did not clear,
+  with the evidence in the comment. Without it, the agent leaves those
+  findings, and its report ends by naming them and the variable.
+- End the job with `adhere lint --yes`. The agent exits 0 whatever it left, so
+  this step passes or fails the job. It judges only the files the agent
+  changed, and reads the rest from the cache.
+
+> **Do not run it on pull requests from forks.** The agent reads their code
+> with your secrets in reach and the network open, so code written to steer it
+> can send them out.
+
 ## Cache
 
 Judgments are cached in `.adhere/cache/`. **Commit it.** Every judgment is a
 paid request, and Jev's answers vary a little from run to run, so a committed
-cache gives everyone and CI the same findings without paying for them again, and
-a pull request changes the judgments of only the files it changes.
-
-| What changed                                                                                 | What is judged again                                                             |
-| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| A file's code                                                                                | Every rule, for that file.                                                       |
-| A file's comments alone                                                                      | Nothing.                                                                         |
-| A file is moved or copied                                                                    | Nothing. Identical files share their judgments.                                  |
-| A rule's text, a matcher, or the source of its `appendState`                                 | That rule, for every file.                                                       |
-| Anything else Jev read: a file it imports, the workspace's packages, or the config's `reads` | Nothing, so a judgment can go stale. Delete the cache to judge every file again. |
-| The threshold is lowered                                                                     | Nothing. Cached judgments newly above it are located.                            |
-| adhere asks its questions differently, after an upgrade                                      | Every rule, once.                                                                |
+cache gives everyone and CI the same findings without paying for them again,
+and a pull request changes the judgments of only the files it changes.
+
+| What changed                                                                                                                    | What is judged again                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| A file's code                                                                                                                   | Every rule, for that file.                                                       |
+| A file's comments alone                                                                                                         | Nothing.                                                                         |
+| A file is moved or copied                                                                                                       | Nothing. Identical files share their judgments.                                  |
+| A rule's text, a matcher, the source of its `appendState`, or its options                                                       | That rule, for every file.                                                       |
+| The config's `reads`, `typeAware`, `maxSymbolLength`, or `maxSymbolDocumentationLength`, and `includeComments` with `typeAware` | Every rule, once.                                                                |
+| What the reads find: a file it imports, the workspace's packages, the file's `dependents`                                       | Nothing, so a judgment can go stale. Delete the cache to judge every file again. |
+| The threshold is lowered                                                                                                        | Nothing. Cached judgments newly above it are located.                            |
+| adhere asks its questions differently, after an upgrade                                                                         | Every rule, once.                                                                |
 
 To keep the cache out of diffs, mark it as generated in `.gitattributes`:
 
@@ -1339,11 +1466,11 @@ To keep the cache out of diffs, mark it as generated in `.gitattributes`:
 <details>
 <summary>How the cache is stored and pruned</summary>
 
-- `files/` holds Jev's answers by the content they are about. Each cache file is
-  named for the hash of a source file's content as Jev reads it, without its
-  comments.
-- Each answer sits under a fingerprint of the model and the rule: its text, its
-  matchers, and its `appendState`'s source.
+- `files/` holds Jev's answers by the content they are about. Each cache file
+  is named for the hash of a source file's content as Jev reads it, without
+  its comments.
+- Each answer sits under a fingerprint of the model and the rule: its text,
+  its matchers, and its `appendState`'s source.
 - `tallies/` keeps the linter check's answers, one tally per rule, under a key
   that changes with the rule's text and the model.
 - A cache file is written once and never changed: it is also named for the hash
@@ -1361,56 +1488,6 @@ To keep the cache out of diffs, mark it as generated in `.gitattributes`:
 
 </details>
 
-## Agent skills
-
-Three skills teach an agent to work with adhere:
-
-| Skill                                            | Print it with        | What it does                                                                                                                                                                                                      |
-| ------------------------------------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`adhere`](./skills/adhere/SKILL.md)             | `adhere skill`       | The reference: the commands, how to write and word a rule, the config, presets, shared rules, comments and suppressions, the cache, reading a report, and tuning a rule.                                          |
-| [`adhere-setup`](./skills/adhere-setup/SKILL.md) | `adhere skill setup` | Sets adhere up in a repo with you. See [Generate rules from your repo](#generate-rules-from-your-repo).                                                                                                           |
-| [`adhere-fix`](./skills/adhere-fix/SKILL.md)     | `adhere skill fix`   | Verifies and fixes the findings `lint` reports: it checks each against its rule and the code, fixes the real ones, reports the false ones with the evidence, and says when a rule is wrong more often than right. |
-
-Install them with the [skills](https://github.com/vercel-labs/skills) CLI:
-`skills add darkmatter/adhere`. The binary carries all three, so
-`adhere skill fix > .agents/skills/adhere-fix/SKILL.md` works without a
-checkout.
-
-### In CI
-
-Pipe the fix skill into an agent that runs without asking. The skill tells it
-that invoking the skill permits every `adhere lint` run and its cost, and
-`adhere skill fix` prints the skill of the adhere that runs, so its flags match:
-
-```sh
-adhere skill fix | codex exec --yolo
-adhere skill fix | claude -p --dangerously-skip-permissions
-```
-
-Both turn off the agent's own permission checks, which suits a runner thrown
-away after the job. To keep Codex in its sandbox, let the sandbox reach
-`api.typesafe.ai`:
-
-```sh
-adhere skill fix | codex exec --sandbox workspace-write \
-  -c sandbox_workspace_write.network_access=true -c approval_policy=never
-```
-
-- Set `TYPESAFE_API_KEY` from a secret.
-- The agent adds no `adhere-ignore` comments or `@adhere` notes unless
-  `ADHERE_ALLOW_SUPPRESSIONS=1` is set in its environment, as in
-  `adhere skill fix | ADHERE_ALLOW_SUPPRESSIONS=1 codex exec --yolo`. It then
-  suppresses a finding it shows is false, or that three fixes did not clear,
-  with the evidence in the comment. Without it, the agent leaves those findings,
-  and its report ends by naming them and the variable.
-- End the job with `adhere lint --yes`. The agent exits 0 whatever it left, so
-  this step passes or fails the job. It judges only the files the agent changed,
-  and reads the rest from the cache.
-
-> **Do not run it on pull requests from forks.** The agent reads their code with
-> your secrets in reach and the network open, so code written to steer it can
-> send them out.
-
 ## How a file is judged
 
 1. **Split.** adhere splits the file into sections of whole statements, in runs
@@ -1437,38 +1514,40 @@ statements of its body. Jev reads the file as these sections.
   `{ code: { "1": "…", "2": "…" } }`, without their comments (see
   [Comments](#comments)), beside what the config [`reads`](#what-jev-reads).
 - Each rule is one `noul` (yes/no probability) question that carries the rule's
-  description and details, and its code under its words, `must` and `never`, or a guideline's
-  `should` and `should_not`. It asks whether the file diverges from the pattern
-  `must` shows, with `never` as an example of diverging, or, for a rule with
-  only code that must never be written, whether the file contains that code.
+  description and details, and its code under its words, `must` and `never`, or
+  a guideline's `should` and `should_not`. It asks whether the file diverges
+  from the pattern `must` shows, with `never` as an example of diverging. For
+  a rule with only code that must never be written, it asks whether the file
+  contains that code.
 - Criteria for each answer draw the line at the rule's scope, so a file with no
   code the rule is about is a no.
 - No rule sits in the state, so a rule's probability depends only on the state
   and that rule, not on which other rules share the request. Every question
   shares the state cost of the request.
 - On up to 10 files per project rule, the rule's question has a second one
-  beside it, the linter check (see
-  [Check for contradictions](#check-for-contradictions)), with the same fields.
+  beside it, the linter check (see [Validating rules](#validating-rules)),
+  with the same fields.
 - A rule with `appendState` has requests of its own, here and below, whose
   state adds to this one.
 
 **Locate: a second request, only when at least one rule's probability is above
 its threshold.** Per flagged rule:
 
-- When the file has more than one section, one `choice` question among the
-  sections' numbers, which yields the section to report. The options carry no
-  text of their own, since each is a key of the state: describing each section
-  by its first line, or by what it declares, located no better on the eval.
-- For each section, two `choice` questions among its lines, each option the
-  line's text: the line the violation starts on and the one it ends on. The
-  chosen section's are underlined. On the eval, lines asked for in this request
-  were named as well as lines asked for on their own, and they held a violation
-  for 94% of real findings, most often as one line
-  ([study](eval/studies/pinpoint.md)).
-- One `noul` carrying the rule: whether you can tell if `code` breaks it from
-  the state alone, without knowing what other files, libraries, services, or
-  configuration do beyond what it shows. It yields the `context` score and its
-  warning.
+- When the file has more than one section, adhere asks one `choice` question
+  among the sections' numbers, which yields the section to report. The options
+  carry no text of their own, since each is a key of the state. On the eval,
+  options that described each section, by its first line or by what it
+  declares, located violations no better than options without text.
+- For each section, adhere asks two `choice` questions among its lines, each
+  option the line's text: the line the violation starts on and the one it ends
+  on. The report underlines the lines chosen in the reported section. On the
+  eval, lines asked for in this request were named as accurately as lines asked
+  for in a request of their own, and they held a violation for 94% of real
+  findings, most often as one line ([study](eval/studies/pinpoint.md)).
+- adhere asks one `noul` carrying the rule: whether you can tell if `code`
+  breaks it from the state alone, without knowing what other files, libraries,
+  services, or configuration do beyond what it shows. It yields the `context`
+  score and its warning.
 
 **Limits.** Jev reads at most 32k tokens of state and one question together, and
 64k tokens in a request. adhere estimates tokens from the JSON it sends, at
@@ -1483,121 +1562,53 @@ about three bytes a token, and leaves 1k of room for what Jev wraps around it.
   the request too large, in which case the file is skipped and counted in the
   summary. A file with more than 255 code sections is also skipped, and the rest
   of the run goes on.
-- So is a file Jev itself counts as over its context, which text denser than the
-  estimate, such as CJK, can cause.
+- A file is also skipped when Jev itself counts it as over its context. Text
+  denser than the estimate, such as CJK, can cause that.
 
 </details>
 
-## Upgrading
-
-Names and layouts from older versions:
+## Compose your AGENTS.md
 
-| Version           | What it had                                                                                                  | What happens now                                                                                                                                                                                                    |
-| ----------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| before 0.7        | A rule's examples were `reference` and `avoid` in a config, and a fence could be tagged `avoid`.             | They still read as `must` and `never`.                                                                                                                                                                              |
-| through 0.7       | The `effect` preset checked seven conventions a linter checks exactly.                                       | They are left to `@effect/tsgo`. The notes on `effect` under [Presets](#presets) say how to turn them on.                                                                                                           |
-| before 0.13       | A rule was any `*.md` file in `.adhere/`, as `.adhere/data/brand-ports.md`.                                  | A `*.md` file outside every rule's directory, but a `README.md`, refuses the run. The refusal says where each such file goes to keep its id, so `adhere-ignore` comments and `overrides` still name it.             |
-| before 0.13       | `.adhere/tsconfig.json` included only `config.ts`.                                                           | Make its `include` `["**/*.ts"]` to give rules written in TypeScript their types.                                                                                                                                   |
-| 0.13.1            | The workspace's packages had a key of their own, `includeWorkspacePackages: true`.                           | adhere no longer reads it. Jev reads the workspace's packages by default.                                                                                                                                           |
-| 0.13.1 and before | Prose around a `RULE.md`'s code was ignored.                                                                 | Jev reads it after the description, as the rule's details, so a rule with prose is judged again once. Keep prose about the rule: why it holds, or where it does not apply.                                          |
-| 0.15.0 and before | A rule named what Jev reads beside its code, in `reads`.                                                     | `reads` is the config's, for every rule, and a rule that has it refuses the run: delete it. Workspace context is on by default; compiler context requires `typeAware: true`. See [What Jev reads](#what-jev-reads). |
-| 0.15.0 and before | `--limit` counted rule checks.                                                                               | It counts files.                                                                                                                                                                                                    |
-| 0.14.0 and before | The `effect` preset had `services/test-layers-are-in-memory` and `services/operations-have-no-requirements`. | They are gone, and an `overrides` entry naming either refuses the run: remove it. `@effect/tsgo`'s `leakingRequirements` checks the second. `adhere-ignore` comments naming them suppress nothing.                  |
+`adhere postinstall` renders the Markdown files in an instructions directory,
+in name order, into a managed block in `AGENTS.md`. Set the directory with the
+config's `instructions` key, relative to the config file. Without it, adhere
+looks in `.adhere/instructions/`, then `.agents/instructions/`.
 
-Configs that previously enabled compiler context with `reads: ["symbols", "references"]`
-must now opt in with `typeAware: true`, or use `adhere lint --type-aware`.
-That switch enables both maps; `reads` only controls workspace context.
+To run it after installing dependencies, add it to your package scripts, or
+append it to your existing `postinstall` script:
 
-## Development
+```json
+{
+  "scripts": {
+    "postinstall": "adhere postinstall"
+  }
+}
+```
 
-From a checkout, with Bun:
+The command creates `AGENTS.md` if needed, and appends the block if it is
+absent. Otherwise it replaces only the content between these markers:
 
-```sh
-bun install
-bun link          # puts `adhere` on PATH
-adhere lint --preset effect
-```
+```markdown
+<!-- adhere:instructions:start -->
 
-- In a checkout no platform package is installed, so `bin/adhere.js` runs
-  `src/main.ts` with Bun instead. Type-aware audits use the checkout's own
-  TypeScript; the default audit does not start it.
-- `bun run typecheck` runs `tsc` and the linter.
-- `bun run test` runs the tests.
-- `bun scripts/verify-npm.ts`, after `bun run build:npm`, installs the built
-  packages in a scratch project and explicitly enables `typeAware: true` to
-  check `symbols` and `references`. It needs Node 24 or later, and sends Jev nothing.
-
-### Native executable
-
-| Command             | What it builds                                                                                                                                                                                                                                                                                                                                                              |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bun run build`     | `dist/adhere`, a single binary with Bun and the presets inside it, through Bun's [`--compile`](https://bun.sh/docs/bundler/executables) with `--asset ./presets`. It runs without Bun or `node_modules` on the target machine and still loads the repo's `config.ts` and Markdown rules from disk. It has no TypeScript compiler, so it reads no `symbols` or `references`. |
-| `bun run build:npm` | The same for every published platform, each into its package under `dist/npm/`, with a copy for the GitHub release in `dist/release/` ([`scripts/npm-packages.ts`](./scripts/npm-packages.ts)).                                                                                                                                                                             |
-
-Each platform's executable is its own npm package,
-`@drkmttr/adhere-<platform>-<arch>`, limited by `os` and `cpu`, and an optional
-dependency of `@drkmttr/adhere`, so an install fetches only its own machine's.
-Each depends on TypeScript's native compiler for its platform,
-`@typescript/typescript-<platform>-<arch>`, pinned to exactly
-`7.1.0-dev.20261009.1` to match the SDK. The package's
-`bin/adhere.js` finds both, and runs the executable with Node. The same
-executables are attached to each GitHub release, named for `uname -s` and
-`uname -m` as in `adhere-Linux-x86_64`, with `LICENSE` and
-`THIRD_PARTY_NOTICES.txt`, which go with any copy you redistribute.
-
-`adhere --version` tells the builds apart:
-
-| Build           | What it prints                                                                                                                                                           |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| A release       | Its version, as `adhere v0.10.0`.                                                                                                                                        |
-| `bun run build` | `git describe --tags --dirty` where it was built, as `adhere v0.10.0-16-g9a41328`: 16 commits after v0.10.0, at `9a41328`, ending in `-dirty` when the tree had changes. |
-| From source     | The checkout's version, marked `(source)`.                                                                                                                               |
-
-### Release
-
-Releases are cut by CI from pushed version tags. From a clean, up-to-date
-`main`, push the release tag:
+Generated instructions
 
-```sh
-git tag v0.3.0
-git push origin v0.3.0
+<!-- adhere:instructions:end -->
 ```
 
-1. The tag push starts `.github/workflows/release.yaml`, which checks out
-   `main`, derives `0.3.0` from `v0.3.0`, and runs
-   `bun run release -- --ci 0.3.0`.
-2. Release-it bumps `package.json`, commits `chore: release v0.3.0` back to
-   `main`, skips npm publish, and creates the GitHub Release for the existing
-   tag.
-3. `release.yaml` then calls the reusable publish workflow,
-   `.github/workflows/publish.yaml`, directly, avoiding a chained GitHub Release
-   event created by `GITHUB_TOKEN`.
-4. The publish workflow verifies that `package.json` matches the release tag,
-   builds the platform packages, attaches their executables to the GitHub
-   Release, and publishes each package before `@drkmttr/adhere`, which it first
-   lists them in as `optionalDependencies` at the same version.
-
-CI, and the publish workflow before it publishes, run `scripts/verify-npm.ts`
-on Linux and on both Macs. Windows is built, but not run.
+- Everything outside the block is kept.
+- A missing instructions directory changes nothing. An empty one clears the
+  generated content, but keeps the markers.
+- Malformed or duplicate markers in `AGENTS.md`, or a marker inside an
+  instruction file, fail the command before it writes anything.
 
-<details>
-<summary>More on publishing</summary>
-
-- Every publish is `npm publish --access public --provenance`.
-- No npm token is used, so a new package has to be published once by hand before
-  it can be given trusted publishers on npmjs.com.
-- npm checks the workflow that started the run, so every package has two trusted
-  publishers: `release.yaml`, which calls the publish workflow for tag releases,
-  and `publish.yaml`, for manual runs.
-- The publish workflow can be run manually for an already-created release tag if
-  a publish needs to be retried. It skips every package whose version is already
-  on npm, and replaces the executables on the release with ones it builds from
-  `main`.
-- The main package's `files` list keeps it to `bin/`, `src/`, `presets/`, and
-  `skills/`.
+## Contributing
 
-</details>
+To build, test, or release adhere from a checkout, see
+[CONTRIBUTING.md](.github/CONTRIBUTING.md).
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE). The executables attached to each GitHub release
+come with `LICENSE` and `THIRD_PARTY_NOTICES.txt`, which go with any copy you
+redistribute.