@drkmttr/adhere 0.18.1 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.18.1",
+  "version": "0.23.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -34,36 +34,39 @@
     "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.0-rc.118"
+    "effect": "4.0.3",
+    "mdast-util-from-markdown": "^2.1.0"
   },
   "devDependencies": {
-    "@effect/platform-bun": "4.0.0-rc.118",
+    "@effect/platform-bun": "4.0.3",
     "@types/bun": "^1.4.2",
-    "@types/node": "^24.13.6",
+    "@types/node": "^26.0.0",
     "release-it": "^21.1.0",
-    "typescript": "7.1.0-dev.20261009.1",
+    "typescript": "7.1.0-dev.20261012.1",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
     "vite-plus": "1.1.0",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "overrides": {
-    "@effect/platform-node-shared": "4.0.0-rc.118",
+    "@effect/platform-node-shared": "4.0.3",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "devEngines": {
     "packageManager": {
       "name": "bun",
-      "version": "1.4.2",
+      "version": "1.4.3",
       "onFail": "download"
     },
     "runtime": {
       "name": "node",
-      "version": "24.21.0",
+      "version": "26.11.1",
       "onFail": "download"
     }
   },
@@ -90,10 +93,10 @@
     "--force"
   ],
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.18.1",
-    "@drkmttr/adhere-darwin-x64": "0.18.1",
-    "@drkmttr/adhere-linux-arm64": "0.18.1",
-    "@drkmttr/adhere-linux-x64": "0.18.1",
-    "@drkmttr/adhere-win32-x64": "0.18.1"
+    "@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

@@ -0,0 +1,140 @@
+# Presets
+
+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](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.
+- **Checked by a linter instead.** The preset has no rules for these, since
+  typescript-eslint and ESLint check them 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`).
+
+- [`typescript/async/concurrent-independent-work`](./typescript/async/concurrent-independent-work/RULE.md): Independent awaited calls run concurrently, not one after another.
+- [`typescript/async/network-calls-have-timeouts`](./typescript/async/network-calls-have-timeouts/RULE.md): HTTP requests carry a timeout or an abort signal.
+- [`typescript/design/no-argument-mutation`](./typescript/design/no-argument-mutation/RULE.md): Functions return changed copies instead of mutating arguments.
+- [`typescript/errors/no-swallowed-errors`](./typescript/errors/no-swallowed-errors/RULE.md): Caught errors are handled, rethrown, or returned as failures.
+- [`typescript/errors/release-on-every-path`](./typescript/errors/release-on-every-path/RULE.md): Acquired resources are released on every path, including errors.
+- [`typescript/testing/assert-outcomes`](./typescript/testing/assert-outcomes/RULE.md): Tests assert results and effects, not only that code ran.
+- [`typescript/testing/independent-tests`](./typescript/testing/independent-tests/RULE.md): Each test sets up its own state and relies on no other test.
+- [`typescript/types/assertions-only-when-proven`](./typescript/types/assertions-only-when-proven/RULE.md): Type assertions claim only what surrounding code has proven.
+- [`typescript/types/derive-dont-restate`](./typescript/types/derive-dont-restate/RULE.md): Types are derived from their source instead of restated by hand.
+- [`typescript/types/unrepresentable-invalid-states`](./typescript/types/unrepresentable-invalid-states/RULE.md): Types make invalid field combinations unrepresentable.
+- [`typescript/types/validate-external-data`](./typescript/types/validate-external-data/RULE.md): Data from outside is checked at runtime before use.
+
+## react
+
+- **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).
+- **Checked by a linter instead.** The preset has no rules for these, since
+  the React Compiler's lint rules check them, 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`).
+
+- [`react/effects/clean-up-what-they-start`](./react/effects/clean-up-what-they-start/RULE.md): Effects return cleanup that undoes what they started.
+- [`react/effects/event-logic-in-handlers`](./react/effects/event-logic-in-handlers/RULE.md): Code responding to a user action runs in its event handler.
+- [`react/effects/external-stores-use-sync-external-store`](./react/effects/external-stores-use-sync-external-store/RULE.md): External stores are read with `useSyncExternalStore`.
+- [`react/effects/fetches-ignore-stale-responses`](./react/effects/fetches-ignore-stale-responses/RULE.md): Effects that fetch ignore or abort stale responses.
+- [`react/effects/notify-parents-in-handlers`](./react/effects/notify-parents-in-handlers/RULE.md): Parents are notified in the handler that makes the change.
+- [`react/server/no-private-data-to-client`](./react/server/no-private-data-to-client/RULE.md): Client Components receive only the fields they show.
+- [`react/server/server-functions-authorize-and-validate`](./react/server/server-functions-authorize-and-validate/RULE.md): Server Functions authorize callers and validate arguments.
+- [`react/state/no-contradictory-state`](./react/state/no-contradictory-state/RULE.md): One status value replaces booleans that can contradict.
+- [`react/state/no-props-copied-into-state`](./react/state/no-props-copied-into-state/RULE.md): Props are read during render, not copied into state.
+- [`react/state/store-ids-not-copies`](./react/state/store-ids-not-copies/RULE.md): State holds a selected item's id, not a copy of the item.
+
+## security
+
+- **Source.** OWASP's cheat sheets.
+
+- [`security/constant-time-secret-compare`](./security/constant-time-secret-compare/RULE.md): Received secrets are compared in constant time.
+- [`security/no-secrets-in-output`](./security/no-secrets-in-output/RULE.md): Secrets stay out of logs, errors, and HTTP responses.
+- [`security/no-untrusted-input-in-commands-or-paths`](./security/no-untrusted-input-in-commands-or-paths/RULE.md): Untrusted input stays out of command strings and unchecked paths.
+- [`security/parameterized-queries`](./security/parameterized-queries/RULE.md): SQL values from outside are passed as bound parameters.
+
+## effect
+
+- **Source.** The
+  [effect-solutions](https://github.com/kitlangton/effect-solutions) docs and
+  the [effect/platform](https://effect.website/docs/platform/introduction/)
+  docs.
+
+- [`effect/basics/gen-for-sequencing`](./effect/basics/gen-for-sequencing/RULE.md): Sequential effectful steps use `Effect.gen` and `yield*`.
+- [`effect/basics/instrument-with-pipe`](./effect/basics/instrument-with-pipe/RULE.md): Timeouts, retries, logging, and spans attach with `.pipe`.
+- [`effect/config/business-logic-depends-on-config-service`](./effect/config/business-logic-depends-on-config-service/RULE.md): Business logic depends on a config service, not Config reads.
+- [`effect/config/secrets-are-redacted`](./effect/config/secrets-are-redacted/RULE.md): Tokens, passwords, and keys are read with `Config.Redacted`.
+- [`effect/config/tests-provide-values-directly`](./effect/config/tests-provide-values-directly/RULE.md): Tests supply config with `Layer.succeed` on the config service.
+- [`effect/config/validate-with-schema`](./effect/config/validate-with-schema/RULE.md): Constrained config values are validated as they are read.
+- [`effect/data/brand-meaningful-primitives`](./effect/data/brand-meaningful-primitives/RULE.md): Meaningful primitives in domain types are branded schemas.
+- [`effect/data/variants-are-tagged-unions`](./effect/data/variants-are-tagged-unions/RULE.md): Domain variants are tagged schemas in a union.
+- [`effect/errors/catch-defects-at-boundaries-only`](./effect/errors/catch-defects-at-boundaries-only/RULE.md): Defects are caught only at system boundaries.
+- [`effect/errors/defects-for-bugs`](./effect/errors/defects-for-bugs/RULE.md): Bugs and invariant violations are defects, not typed errors.
+- [`effect/errors/wrap-external-errors`](./effect/errors/wrap-external-errors/RULE.md): External errors are wrapped in tagged errors.
+- [`effect/services/dependencies-through-layers`](./effect/services/dependencies-through-layers/RULE.md): Service dependencies are yielded inside the service's Layer.
+- [`effect/services/fresh-layer-per-test`](./effect/services/fresh-layer-per-test/RULE.md): Each `it.effect` test provides its own layer.
+- [`effect/services/memoize-parameterized-layers`](./effect/services/memoize-parameterized-layers/RULE.md): Parameterized layers are built once and stored in a constant.
+- [`effect/services/no-mutable-state`](./effect/services/no-mutable-state/RULE.md): Service interfaces expose only readonly members.
+- [`effect/testing/test-clock-for-time`](./effect/testing/test-clock-for-time/RULE.md): Tests that depend on time use `TestClock`.
+
+## alchemy
+
+- **Source.** alchemy's docs and blog.
+
+- [`alchemy/apis/match-remote-errors-by-tag`](./alchemy/apis/match-remote-errors-by-tag/RULE.md): Remote errors are matched by tag and data, not `instanceof`.
+- [`alchemy/apis/schemas-at-trust-boundaries`](./alchemy/apis/schemas-at-trust-boundaries/RULE.md): Outside input is schema-validated at trust boundaries.
+- [`alchemy/data/commit-migrations-then-deploy`](./alchemy/data/commit-migrations-then-deploy/RULE.md): Migrations are committed ahead of time and applied as committed.
+- [`alchemy/data/hyperdrive-direct-origin`](./alchemy/data/hyperdrive-direct-origin/RULE.md): Hyperdrive points at the database's direct endpoint.
+- [`alchemy/data/migrations-use-direct-url`](./alchemy/data/migrations-use-direct-url/RULE.md): Migration runners connect with the database's direct URL.
+- [`alchemy/data/never-disable-tls-verification`](./alchemy/data/never-disable-tls-verification/RULE.md): Database connections verify the server's TLS certificate.
+- [`alchemy/data/private-endpoint-at-runtime`](./alchemy/data/private-endpoint-at-runtime/RULE.md): Service code reaches its database through the private binding.
+- [`alchemy/data/single-migration-owner`](./alchemy/data/single-migration-owner/RULE.md): Each database has exactly one migration owner.
+- [`alchemy/durable/idempotent-event-handlers`](./alchemy/durable/idempotent-event-handlers/RULE.md): Handlers for at-least-once events are idempotent.
+- [`alchemy/durable/io-inside-steps`](./alchemy/durable/io-inside-steps/RULE.md): Workflow I/O runs inside steps; replayed code stays deterministic.
+- [`alchemy/durable/no-self-triggering-bucket-writes`](./alchemy/durable/no-self-triggering-bucket-writes/RULE.md): Bucket handlers filter out events from their own writes.
+- [`alchemy/durable/stable-step-names`](./alchemy/durable/stable-step-names/RULE.md): Workflow step names stay stable across replays.
+- [`alchemy/durable/webhook-state-is-truth`](./alchemy/durable/webhook-state-is-truth/RULE.md): Paid access depends on webhook-recorded state, not success URLs.
+- [`alchemy/providers/diff-guards-unresolved-props`](./alchemy/providers/diff-guards-unresolved-props/RULE.md): Provider diffs guard unresolved props with `isResolved`.
+- [`alchemy/providers/idempotent-delete`](./alchemy/providers/idempotent-delete/RULE.md): Provider delete treats an already-gone resource as success.
+- [`alchemy/providers/lazy-layer-construction`](./alchemy/providers/lazy-layer-construction/RULE.md): Provider layers defer credentials and connections until use.
+- [`alchemy/providers/reconcile-from-observed-state`](./alchemy/providers/reconcile-from-observed-state/RULE.md): Provider reconcile converges from the resource's live state.
+- [`alchemy/resources/anchor-paths-with-import-meta`](./alchemy/resources/anchor-paths-with-import-meta/RULE.md): Path props of resources declared outside the run directory use `import.meta`.
+- [`alchemy/resources/idempotent-actions-and-seeds`](./alchemy/resources/idempotent-actions-and-seeds/RULE.md): Actions and seed files are safe to run again.
+- [`alchemy/resources/previews-reference-shared-resources`](./alchemy/resources/previews-reference-shared-resources/RULE.md): Preview stages reference shared resources and add cheap pieces.
+- [`alchemy/resources/protect-irreplaceable-data`](./alchemy/resources/protect-irreplaceable-data/RULE.md): Buckets and databases with irreplaceable data are retained.
+- [`alchemy/resources/remote-state-for-ci`](./alchemy/resources/remote-state-for-ci/RULE.md): CI and multi-machine stacks use a shared state store.
+- [`alchemy/resources/stable-logical-ids`](./alchemy/resources/stable-logical-ids/RULE.md): Resource logical ids stay the same across deploys.
+- [`alchemy/resources/stage-unique-physical-names`](./alchemy/resources/stage-unique-physical-names/RULE.md): Global physical names are derived per stage.
+- [`alchemy/runtime/bind-tag-not-implementation`](./alchemy/runtime/bind-tag-not-implementation/RULE.md): Other runtimes bind the Tag; only the Stack provides the Layer.
+- [`alchemy/runtime/deterministic-config-defaults`](./alchemy/runtime/deterministic-config-defaults/RULE.md): Config defaults and fallbacks are deterministic.
+- [`alchemy/runtime/disposables-in-request-scope`](./alchemy/runtime/disposables-in-request-scope/RULE.md): Disposables are acquired inside handlers, within request scope.
+- [`alchemy/runtime/lambda-no-post-response-work`](./alchemy/runtime/lambda-no-post-response-work/RULE.md): Lambda handlers write durable work before responding.
+- [`alchemy/runtime/no-per-request-work-at-construction`](./alchemy/runtime/no-per-request-work-at-construction/RULE.md): Construction builds resources and handlers, not per-request work.
+- [`alchemy/runtime/resolve-config-and-bindings-at-construction`](./alchemy/runtime/resolve-config-and-bindings-at-construction/RULE.md): Config and bindings are resolved at construction, not in handlers.
+- [`alchemy/secrets/let-alchemy-mint-infra-secrets`](./alchemy/secrets/let-alchemy-mint-infra-secrets/RULE.md): Infrastructure tokens are minted once by alchemy, not hardcoded.
+- [`alchemy/secrets/none-in-browser-env`](./alchemy/secrets/none-in-browser-env/RULE.md): Browser-inlined env values hold only public configuration.
+- [`alchemy/secrets/redacted-until-use`](./alchemy/secrets/redacted-until-use/RULE.md): Secrets stay `Redacted` until the call that needs the raw string.
+- [`alchemy/secrets/unwrap-before-compare-or-send`](./alchemy/secrets/unwrap-before-compare-or-send/RULE.md): `Redacted` values are unwrapped before compare, send, or serialize.
+- [`alchemy/security/authorize-public-endpoints`](./alchemy/security/authorize-public-endpoints/RULE.md): Public handlers authenticate and authorize every caller.
+- [`alchemy/security/github-secret-not-variable`](./alchemy/security/github-secret-not-variable/RULE.md): Sensitive CI values use `GitHub.Secret`, not `GitHub.Variable`.
+- [`alchemy/security/identity-from-verified-session`](./alchemy/security/identity-from-verified-session/RULE.md): The acting user comes from the verified session or token.
+- [`alchemy/security/keep-auth-protections-on`](./alchemy/security/keep-auth-protections-on/RULE.md): Auth checks and protections stay enabled.
+- [`alchemy/security/least-privilege-bindings`](./alchemy/security/least-privilege-bindings/RULE.md): Runtimes bind the narrowest capability their calls need.
+- [`alchemy/security/least-privilege-ci-credentials`](./alchemy/security/least-privilege-ci-credentials/RULE.md): CI credentials are scoped to what the stack deploys.
+- [`alchemy/security/lookup-failure-is-not-anonymous`](./alchemy/security/lookup-failure-is-not-anonymous/RULE.md): A failed session lookup is an error, not an anonymous user.

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,10 +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]       # 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
@@ -32,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
@@ -58,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
 ---
@@ -123,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:
@@ -173,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. Rule-level `reads`, in Markdown
-front matter, `defineRule`, or inline rules, is rejected with guidance to move
-it to the config. 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;
@@ -301,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
 
@@ -346,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