@drkmttr/adhere 0.21.2 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.21.2",
+  "version": "0.23.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -34,11 +34,14 @@
     "typecheck": "tsc --noEmit && bun run lint",
     "build": "bun build --compile --minify --sourcemap --define ADHERE_BUILD=\"\\\"$(git describe --tags --dirty --always)\\\"\" src/main.ts --asset ./presets --outfile dist/adhere",
     "build:npm": "bun scripts/npm-packages.ts build",
+    "oxlint:catalog": "bun scripts/oxlint-catalog.ts",
+    "oxlint:catalog:check": "bun scripts/oxlint-catalog.ts --check",
     "release": "release-it",
     "prepare": "vp config"
   },
   "dependencies": {
-    "effect": "4.0.3"
+    "effect": "4.0.3",
+    "mdast-util-from-markdown": "^2.1.0"
   },
   "devDependencies": {
     "@effect/platform-bun": "4.0.3",
@@ -90,10 +93,10 @@
     "--force"
   ],
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.21.2",
-    "@drkmttr/adhere-darwin-x64": "0.21.2",
-    "@drkmttr/adhere-linux-arm64": "0.21.2",
-    "@drkmttr/adhere-linux-x64": "0.21.2",
-    "@drkmttr/adhere-win32-x64": "0.21.2"
+    "@drkmttr/adhere-darwin-arm64": "0.23.0",
+    "@drkmttr/adhere-darwin-x64": "0.23.0",
+    "@drkmttr/adhere-linux-arm64": "0.23.0",
+    "@drkmttr/adhere-linux-x64": "0.23.0",
+    "@drkmttr/adhere-win32-x64": "0.23.0"
   }
 }

package/presets/README.md

@@ -2,9 +2,17 @@
 
 Every rule in adhere's built-in presets is listed below, with a one-line
 summary. Each id links to the full rule, and is the id that reports,
-`overrides`, and `adhere-ignore` comments use. [Presets](../README.md#presets)
+`overrides`, and `adhere-ignore` comments use. [Presets](https://dm.sh/adhere/presets/)
 says how to name a preset or one of its topics.
 
+Some rules declare the context they need with `reads`, such as
+`["symbols", "references"]` for a rule that compares declarations across
+files. Enable `typeAware: true` or `--type-aware` for the compiler's
+`symbols` and `references`. Without it, a bundled rule that declares either is
+left out of the run, so a preset never judges with less context than its rules
+declare. A project's own rule is different: it still runs, and lint warns that
+it may be less accurate until a declared read is enabled.
+
 ## typescript
 
 - **Source.** The TypeScript Handbook and the Google TypeScript Style Guide.

package/presets/alchemy/runtime/bind-tag-not-implementation/RULE.md

@@ -1,5 +1,6 @@
 ---
 description: When a runtime is split into a Tag class and a make Layer, other runtimes must import and bind only the Tag, and only the Stack provides the Layer; another Worker or Function must never import or provide that implementation Layer.
+reads: ["symbols", "references"]
 ---
 
 ## Must

package/presets/effect/data/brand-meaningful-primitives/RULE.md

@@ -1,5 +1,6 @@
 ---
 description: A primitive with semantic meaning in a domain type, such as an id, email, URL, or port in a service's contract, an event, or a stored record, must be declared as a branded schema, never as a bare string or number.
+reads: ["symbols", "references"]
 ---
 
 Two ids of different things are both strings, so nothing stops one being

package/presets/effect/data/variants-are-tagged-unions/RULE.md

@@ -1,5 +1,6 @@
 ---
 description: Variants of a domain type, alternatives that carry fields and that a service returns, stores, or decodes, must be tagged schemas such as Schema.TaggedClass or Schema.TaggedStruct members of a Schema.Union, never TypeScript object types joined by a tag field.
+reads: ["symbols", "references"]
 ---
 
 A tagged schema decodes each variant at the boundary and lets `Match.tag`

package/presets/typescript/types/derive-dont-restate/RULE.md

@@ -1,6 +1,7 @@
 ---
 description: A type that describes the same data as another type, a schema, a function, or a constant should be derived from it, with a utility type such as `Pick`, with `typeof` or `keyof`, or as a schema's inferred type, and should not restate its fields or values by hand.
 level: warning
+reads: ["symbols", "references"]
 ---
 
 ## Should

package/skills/adhere/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adhere
-description: Reference for adhere, the linter for coding conventions a normal linter cannot check, judged by TypeSafe AI's Jev. Covers its commands, the Markdown rule format and how to word a rule, the config, presets, shared rules, comments and suppressions, the cache, reading a report, and tuning a noisy rule. Use when writing or editing adhere rules, configuring adhere, reading its findings, or answering questions about it. To set adhere up in a repo, use adhere-setup; to fix findings, adhere-fix.
+description: Reference for adhere, the linter for coding conventions a normal linter cannot check, judged by TypeSafe AI's Jev. Covers its commands, the Markdown rule format and how to word a rule, the config, presets, shared repos and lint packages, comments and suppressions, the cache, reading a report, and tuning a noisy rule. Use when writing or editing adhere rules, configuring adhere, reading its findings, or answering questions about it. To set adhere up in a repo, use adhere-setup; to fix findings, adhere-fix.
 ---
 
 # adhere
@@ -19,11 +19,13 @@ first rules, first lint, and CI, and adhere-fix verifies and fixes findings.
 ## Commands
 
 ```sh
-adhere init [--force]            # .adhere/config.ts, two example rules, and the dev dependency
-adhere init --shared org/repo    # a repo of rules other repos install, with CI and an alchemy stack
+adhere init [--force]            # config, tsconfig, two example rules, and the dev dependency
+adhere init --shared org/repo    # rules, instructions, lint package, CI, and an alchemy stack
+adhere postinstall               # render .adhere/instructions/**/*.md into AGENTS.md
 adhere login                     # save a TypeSafe AI API key; TYPESAFE_API_KEY takes precedence
 adhere validate                  # rule wording, rules a linter could check, contradictions
-adhere rules create [idea]       # wizard: claude, codex, or omp drafts a RULE.md or RULE.ts from excerpts you judge; org rules pushed for a PR
+adhere rules create [idea]       # native rule, approved plugin, or rule file; org PR
+adhere rules readme [org/repo]   # refresh a shared repo README's managed guide
 adhere lint                      # judge the working directory; exit 1 on an error finding
 adhere lint --limit 0            # compiler-free counts/cache plan; no budgeting
 adhere lint --limit 100          # first 100 files needing requests; all pending rules per file
@@ -33,16 +35,17 @@ adhere lint --preset effect      # add a built-in rule set; the config becomes o
 adhere lint --filter 'src/**'    # read only matching files; repeat, and ! to leave out
 adhere lint --threshold 0.9      # report at another threshold from the cache; judges nothing again
 adhere lint --deny-warnings      # fail on warnings too
-adhere list org/repo             # the rules in a GitHub repo's .adhere/rules/
-adhere install org/repo[/topic[/rule]][#ref]   # copy them into .adhere/rules/org/repo/
+adhere list org/repo             # the rules in a GitHub repo's .adhere/rules/, with descriptions
+adhere install org/repo[/topic[/rule]][#ref] [--all]  # copy instructions and rules into .adhere/
 adhere skill [docs|setup|fix]    # print a skill
 ```
 
 `adhere <command> --help` lists every flag. Version, help, skills, `validate`,
 and planning with `--limit 0` do not start the native compiler. Default `lint`
-is compiler-free. With `typeAware: true` or `--type-aware`, it starts the compiler
-only during execution, after confirmation, for pending judgments or cached
-findings still needing location.
+is compiler-free, and leaves out bundled preset rules that declare native
+reads. With `typeAware: true` or `--type-aware`, it includes them and starts the
+compiler only during execution, after confirmation, for pending judgments or
+cached findings still needing location.
 
 `--limit` now counts files, not rule checks; use the same flag without an extra
 unit selector. Each request-bearing file consumes one slot for all its pending
@@ -59,11 +62,11 @@ native-context caveat before execution.
 A repo's rules live in `.adhere/rules/`, a directory per rule holding a
 `RULE.md`, or a `RULE.ts` (below). The directory's path is the rule id:
 `.adhere/rules/data/brand-ports/RULE.md` is `data/brand-ports`. Other files in
-a rule's directory are not rules. A `*.md` rule elsewhere in `.adhere/`, as
-rules were once written, refuses the run with where it goes to keep its id.
-A `.adhere/rules/` in a subdirectory holds rules for that
-subtree only, and the most specific rule with an id wins. `cache/` and the
-config in `.adhere/` are not rules.
+a rule's directory are not rules, and only `RULE.md` or `RULE.ts` in a rule's
+directory defines one: other Markdown in `.adhere/`, such as
+`.adhere/instructions/`, is ignored. A `.adhere/rules/` in a subdirectory holds
+rules for that subtree only, and the most specific rule with an id wins.
+`cache/` and the config in `.adhere/` are not rules.
 
 ````md
 ---
@@ -124,6 +127,13 @@ Front matter besides `description`, all optional:
   only when Jev says the code that breaks the rule is as every `appliesTo`
   describes and as no `excludeIf` does.
 
+- `reads: ["symbols", "references"]` declares the context the rule needs, a
+  JSON array on one line. It enables nothing: the config's `reads` and
+  `typeAware` still choose what this run sends. A project's own rule still
+  runs and lint warns that it may be less accurate until a declared read is
+  enabled; a bundled preset rule that declares either native read is left out
+  unless `typeAware` is on.
+
 A rule's directory can hold a `RULE.ts` instead, which default-exports
 `defineRule({...})` from `@drkmttr/adhere`, with the fields a config's inline
 rule takes:
@@ -174,9 +184,13 @@ Opting in with `typeAware: true` or `--type-aware` enables both `symbols` and
 `references`, regardless of `reads`. Legacy native-reader entries in `reads`
 alone do not enable the compiler; leaving them out does not disable it when
 type awareness is on. Code alone requires `reads: []` and type awareness off.
-Presets do not own or override this selection. A rule-level `reads`, in
-Markdown front matter, `defineRule`, or an inline rule, has no effect. The
-context maps are:
+Presets do not own or override this selection. A rule may declare what it
+needs with `reads`, in Markdown front matter, `defineRule`, or an inline rule;
+the declaration enables nothing. A bundled preset rule that declares `symbols`
+or `references` is left out unless `typeAware` is on, so it is never judged
+with less than it declares. A project's own rule still runs, and a declared
+read the run does not enable is a warning that it may be less accurate until
+enabled. The context maps are:
 
 - `workspacePackages`: only packages matched by this file's literal imports,
   as `{ canonicalPackageName: directory }`. Subpaths match the owning package;
@@ -302,17 +316,166 @@ https://github.com/darkmatter/adhere/tree/main/presets. A preset leaves out
 what that ecosystem's linters check exactly. Quiet a preset rule with
 `overrides` rather than copying it.
 
-## Shared rules
+## Linter-checkable rules
+
+A convention a linter can decide exactly does not belong in a `RULE.md`.
+`adhere rules create` asks the coding agent for one of three routes:
+
+- **A native Oxlint rule.** The agent answers `linter` as a plain rule-id
+  string, or null, and adhere checks it against its bundled Oxlint catalog at
+  decode time; unknown ids are rejected. It also supplies the rule's exact
+  option values, which the config puts after the severity: a rule whose
+  defaults enforce the idea prints `"error"`, while an option-dependent rule
+  prints `["error", ...options]`, because bare `"error"` would enforce
+  nothing. Banning lodash with `no-restricted-imports` becomes
+  `["error", { "paths": [{ "name": "lodash" }] }]`. A project rule prints the
+  exact config; an organization rule enables it in the shared `oxlint/rules.json`
+  and pushes a branch for a pull request with the README guide refreshed. In a
+  shared repo itself, "this project" writes `oxlint/rules.json` locally instead
+  of printing the config. A rule from a plugin Oxlint leaves off
+  by default also needs that plugin in `plugins`, whose list replaces Oxlint's
+  default set. A type-aware rule needs
+  `options.typeAware` and `oxlint-tsgolint`, which Vite+ includes.
+- **A custom Oxlint JS plugin.** Only when the convention is visible in the
+  syntax tree and scopes: a JS plugin cannot see TypeScript types, other
+  files, or another parser's AST. The plugin must be plain ESM, default-export
+  its object, and import nothing; the agent reports each diagnostic's message
+  literally, so its valid and invalid fixtures can match exact diagnostics.
+  adhere shows the plugin and fixtures, and runs nothing until the user
+  approves. It then runs the fixtures with the project's own Oxlint RuleTester,
+  through `oxlint/plugins-dev` or `vite-plus/lint/plugins-dev`, so the project
+  needs its own Oxlint or Vite+ and Node 22 or newer on `PATH`; Oxlint's
+  RuleTester refuses Bun and older Node, there is no Bun fallback, and without
+  it nothing is written and no repair is attempted. adhere bundles no Oxlint.
+  One failure goes back to the agent to repair; the user approves the repaired
+  plugin, then it runs again. Nothing is written unless the tests pass.
+- **An adhere rule**, for judgment, facts outside the file, or types.
+
+Whichever route it takes, the draft is trialled on real files before anything
+is written: the first 100 applicable files by default, the entire repo, or a
+number the user types, with the plan's known cost shown first. The authoring
+agent reads the saved report in `.adhere/trial/` and the source it names, then
+the user accepts the findings, reviews each as correct, a false positive, or
+unsure, or asks for a revision. Findings and examples take optional notes for
+the agent; a revision is re-approved and reruns the same files, so the new
+evidence is comparable. Skipping is allowed, but the write prompt then says
+`(not trialled)` and the closing line says `Not trialled: …`; nothing is called
+validated on a skipped, partial, or stale run. The trial runs for native
+settings and approved plugins too.
+
+A project plugin and its checked-in test go to
+`.adhere/oxlint/<plugin>.mjs` and `.adhere/oxlint/<plugin>.test.mjs`; the
+`.mjs` keeps ESM in a `type: commonjs` package. adhere prints the config to add
+to `oxlint.config.ts` or Vite+'s lint block:
+
+```json
+{
+  "jsPlugins": ["./.adhere/oxlint/no-foo.mjs"],
+  "rules": { "no-foo/no-foo": "error" }
+}
+```
+
+Run the test with Node 22 or newer: `node .adhere/oxlint/no-foo.test.mjs`.
+
+A native project rule without options prints only its id:
+
+```json
+{ "rules": { "typescript/no-explicit-any": "error" } }
+```
+
+A shared repo keeps plugins in `oxlint/plugins/` as `.js`, with `.test.js` beside
+them, because the shared package is `type: module`; it registers them in
+`oxlint/rules.json`. The catalog follows adhere's toolchain, not the project's
+installed Oxlint, so a suggestion may be missing on an older Oxlint or a newer
+rule may be absent from the catalog; the plugin tests always use the project's
+Oxlint. `adhere validate` reports rules left over that a linter could check.
+
+## Shared repos
+
+An organization keeps its instructions, rules, and lint settings in one repo,
+scaffolded by `adhere init --shared org/repo`. Its `README.md` carries a
+managed guide between `<!-- adhere:rules:start -->` and
+`<!-- adhere:rules:end -->`: a contents list nesting every rule under its
+topic, the rules grouped by topic with each bold statement and rule id opening
+that rule's `RULE.md` verbatim: examples and explanation, then a source link
+under a stable permalink, every enabled native setting in `oxlint/rules.json`
+with its severity, and each custom plugin's enabled rules, linked to
+`oxlint/plugins/<name>.js` when that is a local file. A `RULE.ts` is linked as
+TypeScript source only: the guide never reads or runs it, and plugin code is
+never loaded. Refresh it with `adhere rules readme [org/repo]` after renaming
+or deleting a rule; it preserves prose outside the block, omits off lint
+settings, and refuses malformed markers without writing.
+`adhere rules create` refreshes it for local writes and stages it with
+shared-repo branches.
+
+The command chooses its target by argument, then by where it runs. A named
+`org/repo` wins. Otherwise a working directory that is itself a shared repo
+(`package.json` exporting `./oxlint`) is written in place. Anywhere else,
+adhere reads the checkout's GitHub `origin` (`https`, `ssh`, or scp form) and
+infers `<owner>/standards` (`acme/app` -> `acme/standards`, never `acme/app`);
+a fork's owner is the fork's. That remote target is cloned at its default
+branch, the changed block is committed alone on a fresh
+`adhere/readme-<timestamp>` branch, pushed, and printed with a compare link.
+No pull request is opened, the consumer checkout and the default branch stay
+untouched, and an unchanged guide prints `No change, so nothing was pushed.`
+without committing. A rules-only remote works, since the `./oxlint` export is
+only required for the local write. A missing or non-GitHub `origin` fails and
+names `adhere rules readme org/repo`; name the repo explicitly when the
+organization's repo is not `<owner>/standards`.
+
+Other repos copy the first two with `adhere install`:
+
+```sh
+adhere list org/repo                  # rules and descriptions; instructions are not listed
+adhere install org/repo               # choose instruction files, then rules, at a terminal
+adhere install org/repo --all         # everything, without a terminal (CI)
+adhere install org/repo/data          # choose among the data topic's rules
+adhere install org/repo/data/ports    # exactly that rule, without asking
+adhere install org/repo#v1.0.0 --all  # everything at tag v1.0.0
+```
+
+A bare repo chooses from instruction files and rules. A topic chooses only the
+rules under it, never instructions, even a topic named `instructions`. An exact
+rule id with no rule deeper under it is copied directly. Already-installed
+items are preselected. A rerun skips what exists; `--force` replaces existing
+files and rule directories, and deselecting never deletes them.
+
+Instruction files land in `.adhere/instructions/org/repo/<path>`. Rules keep
+their whole directory in `.adhere/rules/org/repo/`, so `data/brand-ports`
+becomes the rule `org/repo/data/brand-ports`, and a copied `RULE.ts` runs
+whenever lint does. Copies are the repo's own from then on. `adhere postinstall`
+renders the instruction files into `AGENTS.md`; files whose path has at least
+three segments come first (copied files, and local files two directories deep),
+then files directly in the instructions directory, then files one directory
+deep, each group sorted by path.
+
+The shared `oxlint/` package is not copied. Pin it as a git dependency at a
+repo-wide tag (there are no per-rule or per-package tags; one tag covers rules,
+instructions, and lint together), then spread it into Vite+ or plain Oxlint:
+
+```ts
+// vite.config.ts
+import sharedLint from "@org/repo/oxlint";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  lint: { ...sharedLint, jsPlugins: [...sharedLint.jsPlugins, "./.adhere/oxlint/local.mjs"] },
+});
+```
+
+```ts
+// oxlint.config.ts: oxlint -c oxlint.config.ts
+import sharedLint from "@org/repo/oxlint";
+
+export default { ...sharedLint };
+```
+
+`oxlint/index.js` reads `oxlint/rules.json` and resolves plugin paths relative to
+the package. Paths a project adds stay relative to its own config; project
+plugins live in `.adhere/oxlint/`.
 
-An organization keeps rules in one repo's `.adhere/rules/`, scaffolded by
-`adhere init --shared org/repo`, and other repos copy them in with
-`adhere install org/repo`, or one topic or rule with
-`adhere install org/repo/<topic>[/<rule>]`. Each rule's whole directory lands
-in `.adhere/rules/org/repo/`, so `data/brand-ports` becomes the rule
-`org/repo/data/brand-ports`, and a copied `RULE.ts` runs whenever lint does.
-They are the repo's own rules from then on; a second install skips existing
-rules unless `--force`, which replaces their directories, local edits and all. The source is cloned with git,
-so a private repo needs git's credentials for GitHub.
+The source is cloned with git, so a private repo needs git's credentials for
+GitHub.
 
 ## Comments and suppressions
 
@@ -347,9 +510,10 @@ re-judges that rule; a threshold change re-judges nothing.
 
 Dependencies, related source, reader selection, shared read-context contents,
 and hook-owned external data are deliberately not fingerprinted. If `A.ts` imports
-`B.ts`, changing `B.ts` does not invalidate `A.ts`. Changing config `reads` or
-`typeAware` does not refresh its cached answers either. This keeps planning cheap but accepts
-stale dependency/context judgments.
+`B.ts`, changing `B.ts` does not invalidate `A.ts`. Changing the config's
+`reads` or `typeAware` re-judges every rule once; changing what those reads
+find does not. This keeps planning cheap but accepts stale dependency/context
+judgments.
 
 `planAudit` reads/counts/hashes code, checks the cache, and makes code plus cheap
 workspace estimates without compiler or `SourceReads` calls. It applies `--limit`

package/skills/adhere-fix/SKILL.md

@@ -163,7 +163,7 @@ rules, and in the report give the user the counts and suggest one of:
   `{ threshold: 0.9 }`;
 - for a project rule, rewording it to say what code it is about and what is
   out of scope, following the rule writing tips:
-  https://github.com/darkmatter/adhere#rule-writing-tips.
+  https://dm.sh/adhere/writing-good-rules/#rule-writing-tips.
 
 ## 7. Report
 

package/skills/adhere-setup/SKILL.md

@@ -37,12 +37,14 @@ wherever this skill says `adhere`, run it the manager's way, as in
 
 With pnpm, at a workspace root, add `--ignore-workspace-root-check`.
 
-Default lint reads code and `workspacePackages` without starting a compiler.
+Default lint reads code and `workspacePackages` without starting a compiler,
+and leaves out bundled preset rules that declare `symbols` or `references`.
 `typeAware` defaults to `false`; `typeAware: true` or `--type-aware` opts into
-both `symbols` and `references`, regardless of `reads`. `reads` now controls
-workspace context only, defaulting to `["workspacePackages"]`; legacy native
-reader entries alone do not opt in. Code alone uses `reads: []` with type
-awareness off. Explain the extra context/cost and **Ask** before opting in.
+both `symbols` and `references`, regardless of `reads`, and includes those
+rules. `reads` now controls workspace context only, defaulting to
+`["workspacePackages"]`; legacy native reader entries alone do not opt in.
+Code alone uses `reads: []` with type awareness off. Explain the extra
+context/cost and **Ask** before opting in.
 
 With type awareness enabled, native TypeScript starts only during execution,
 after confirmation, when pending judgments or cached findings needing location
@@ -91,7 +93,10 @@ from and the evidence.
 
 Keep only conventions that need judgment: about intent, shape, or placement.
 Drop any a regex, an import check, or the type checker could flag every time,
-and note where it belongs instead. Drop any a preset below already covers.
+and note where it belongs instead: a native Oxlint rule, or a convention a
+small syntax-only Oxlint JS plugin could decide. `adhere rules create` routes
+those two, and leaves the rest to adhere. Drop any a preset below already
+covers.
 
 **Presets.** Match the stack: `typescript` for TypeScript, `react` for React,
 `security` for code that handles secrets, SQL, shell commands, or paths,
@@ -100,9 +105,10 @@ and note where it belongs instead. Drop any a preset below already covers.
 https://github.com/darkmatter/adhere/tree/main/presets, to describe them and
 to avoid drafting duplicates.
 
-**A shared repo.** **Ask** whether the organization keeps adhere rules in a
-repo. If it does, `adhere list org/repo` prints its rules with their
-descriptions.
+**A shared repo.** **Ask** whether the organization keeps adhere instructions,
+rules, or lint settings in a repo. If it does, `adhere list org/repo` prints
+its rules with their descriptions; its instruction files and `oxlint/` package
+are separate, and `adhere install` offers the instruction files too.
 
 ## 3. Draft the repo's rules
 
@@ -131,7 +137,8 @@ Presets
 From acme/standards
   5. data/brand-ports          A port must be a branded, range-checked integer, never a bare number.
 Dropped as a linter's job
-  - "no default exports": eslint import/no-default-export
+  - "no default exports": native oxlint import/no-default-export
+  - "no local date formatting": custom syntax-only oxlint plugin
 ```
 
 For a preset, offer the whole preset or its topics. Show a draft's full text
@@ -152,8 +159,30 @@ the wording of any. Revise drafts the user wants changed and show them again.
   workspace context, not native maps. Only replace `reads` if the user chooses
   to limit workspace context. If requested type awareness lacks compiler resources,
   use the package launcher or a checkout; do not silently turn it off.
-- Install chosen shared rules: `adhere install org/repo/<id>` for each, or
-  `adhere install org/repo` for all of them. They land in `.adhere/rules/org/repo/`.
+- Copy chosen shared instructions and rules: run `adhere install org/repo` and
+  let the user pick at the terminal, or add `--all` only when they chose
+  everything (the non-interactive path). Name an exact rule to copy it without
+  asking. Instruction files land in `.adhere/instructions/org/repo/` and rules
+  in `.adhere/rules/org/repo/`; `adhere postinstall` renders the instructions,
+  copied files first.
+- **Ask** before adding the shared repo's lint package: pin it as a git
+  dependency at the repo-wide tag, then spread `@org/repo/oxlint` into the
+  project's Vite+ lint block or `oxlint.config.ts`. It is a package, not an
+  `adhere install` copy. Project plugins live in `.adhere/oxlint/`.
+- For a chosen linter candidate, run `adhere rules create "<convention>"` and
+  follow its route. A native Oxlint rule must be one of adhere's catalog ids;
+  an unknown id is rejected. It must carry the rule's exact option values when
+  it takes options; adhere prints `["error", ...options]`, never a bare
+  `"error"` that would enforce nothing. It prints the config for the user's lint
+  config, and adhere does not edit it. A custom syntax-only plugin is shown with
+  valid and invalid examples and runs nothing until approved, then its tests
+  use the project's Oxlint through `oxlint/plugins-dev` or
+  `vite-plus/lint/plugins-dev`. That needs its own Oxlint or Vite+ and Node 22
+  or newer on `PATH`; Oxlint's RuleTester refuses Bun and older Node, and
+  without it nothing is written and no repair is attempted. One failed run goes
+  back to the agent for repair; the user approves the repaired plugin, and it
+  runs again. Project files go to `.adhere/oxlint/` as `.mjs`; shared files go
+  to `oxlint/plugins/` as `.js` on a branch for a pull request.
 - Add `exclude` globs for generated or vendored code the default skips miss.
 
 ## 6. Validate
@@ -164,8 +193,10 @@ adhere validate
 
 It reports rules worded against the tips, rules a linter could check, and
 contradictions between rules that apply to the same files. Fix the wording
-yourself. For a linter-checkable rule or a contradiction, **Ask** the user
-which to keep, and apply it. Run it again until it reports no contradictions.
+yourself. For a linter-checkable rule, **Ask** whether to move it to a native
+Oxlint rule or an approved syntax-only plugin, or keep it as an adhere rule.
+For a contradiction, **Ask** which rule to keep and apply the change. Run it
+again until it reports no contradictions.
 
 ## 7. The first lint
 
@@ -402,9 +433,11 @@ This needs the cache committed on the base branch first.
 
 Tell the user:
 
-- the rules imported, by source, and where they are;
+- the rules imported, by source, and where they are, plus any shared
+  instruction files copied and the `oxlint/` package pinned;
 - the presets and shared repo named in the config or installed;
-- the candidates dropped as a linter's job, with where each belongs;
+- the candidates routed to native Oxlint, an approved plugin, or an adhere
+  rule, and which config registers each;
 - the last lint's findings, and what was fixed, made a warning, or suppressed;
 - the CI workflow and whether the secret is set;
 - what is left for them: pushing, setting the secret, fixing remaining findings.