@drkmttr/adhere 0.2.1 → 0.3.0

package/{adhere.config.ts → .adhere/config.ts}

@@ -1,4 +1,4 @@
-import type { Config } from "./src/index.ts";
+import type { Config } from "../src/index.ts";
 
 // Type-only import: erased at runtime, so the compiled binary loads this file
 // without resolving the package (see README, "Configuration").

package/.github/workflows/ci.yaml

@@ -16,4 +16,12 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bun run typecheck
       - run: bun run test
-      - run: bun run build
+      - run: bun run build:npm
+      - name: Run the launcher against the linux-x64 package
+        run: |
+          # Outside the checkout, where the launcher has no source to fall back to.
+          launcher="$RUNNER_TEMP/launcher"
+          mkdir -p "$launcher/node_modules/@drkmttr"
+          cp -r bin "$launcher/bin"
+          ln -s "$PWD/dist/npm/linux-x64" "$launcher/node_modules/@drkmttr/adhere-linux-x64"
+          node "$launcher/bin/adhere.js" --version

package/.github/workflows/publish.yaml

@@ -1,8 +1,18 @@
 name: Publish
 
 on:
-  release:
-    types: [published]
+  workflow_call:
+    inputs:
+      tag_name:
+        description: "Release tag to publish, for example v0.3.0."
+        required: true
+        type: string
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: "Release tag to publish, for example v0.3.0."
+        required: true
+        type: string
 
 permissions:
   id-token: write
@@ -23,15 +33,36 @@ jobs:
           node-version: "24"
           registry-url: "https://registry.npmjs.org"
       - name: Verify release tag matches package version
+        env:
+          TAG_NAME: ${{ inputs.tag_name }}
         run: |
-          version="${GITHUB_REF_NAME#v}"
+          version="${TAG_NAME#v}"
+          if [[ "$version" == "$TAG_NAME" || ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-.+][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Release tags must look like vX.Y.Z, optionally with a prerelease/build suffix." >&2
+            exit 1
+          fi
           package_version="$(node -p "require('./package.json').version")"
           if [ "$version" != "$package_version" ]; then
-            echo "Release tag $GITHUB_REF_NAME does not match package.json version $package_version." >&2
+            echo "Release tag $TAG_NAME does not match package.json version $package_version." >&2
             exit 1
           fi
       - run: bun install --frozen-lockfile
       - run: bun run typecheck
       - run: bun run test
-      - run: bun run build
-      - run: npm publish --access public --provenance
+      - run: bun run build:npm
+      - name: Publish the platform packages
+        run: |
+          for directory in dist/npm/*/; do
+            name="$(node -p "require('./${directory}package.json').name")"
+            version="$(node -p "require('./${directory}package.json').version")"
+            # A rerun after a partial publish skips the versions already on npm.
+            if npm view "$name@$version" version >/dev/null 2>&1; then
+              echo "$name@$version is already published."
+            else
+              npm publish "$directory" --access public --provenance
+            fi
+          done
+      - name: Publish @drkmttr/adhere with the platform packages as optional dependencies
+        run: |
+          bun scripts/npm-packages.ts pin
+          npm publish --access public --provenance

package/.github/workflows/release.yaml

@@ -55,8 +55,17 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bun run typecheck
       - run: bun run test
-      - run: bun run build
+      - run: bun run build:npm
       - name: Create GitHub release
         run: bun run release -- --ci "${{ steps.release.outputs.version }}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release
+    uses: ./.github/workflows/publish.yaml
+    permissions:
+      contents: read
+      id-token: write
+    with:
+      tag_name: ${{ github.ref_name }}

package/README.md

@@ -9,13 +9,107 @@ report uses the same frame as `vp lint`.
 
 Deterministic rules (substring matches, type checks) belong in a normal linter.
 
+## Install
+
+```sh
+npm install --global @drkmttr/adhere   # or: bun add --global @drkmttr/adhere
+```
+
+To pin the version in a repo, for CI or scripts, add it as a dev dependency
+and run `npx adhere`. To try it without installing, run
+`npx @drkmttr/adhere` or `bunx @drkmttr/adhere`.
+
+`adhere` is a prebuilt executable for macOS and Linux on arm64 and x64 and for
+Windows on x64. It needs Node to start, and no Bun.
+
+adhere sends each file it judges to Jev at `api.typesafe.ai`, authenticated
+with a TypeSafe AI API key in `TYPESAFE_API_KEY`.
+
+## Quick start
+
+```sh
+adhere init                          # .adhere/config.ts and two example rules
+adhere validate                      # check the config and rules, without Jev
+echo ".adhere/cache/" >> .gitignore
+export TYPESAFE_API_KEY=...
+adhere lint                          # audit the working directory
+```
+
+Without a config or rules, `adhere lint --preset effect` audits against the
+built-in Effect rules. A finding looks like this:
+
+```text
+  × data/brand-ports (0.93): A port is a branded, range-checked integer, not a bare number.
+   ╭─[src/server.ts:4:1]
+ 4 │ const port: number = Number(process.env.PORT ?? 3000);
+   · ──────────────────────────────────────────────────────
+   ╰────
+  hint: const Port = Schema.Int.pipe(
+          Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
+          Schema.brand("Port"),
+        );
+
+Found 1 error.
+42 files, 3 judged, 39 cached.
+```
+
+The header is the rule id, Jev's probability, and the rule's description. The
+hint is the rule's reference. The exit code is 0 when nothing is reported and 1
+when something is. It is also 1 when the run refuses, for example on an invalid
+config or rule file, a missing `TYPESAFE_API_KEY`, or an unknown command or
+flag; a refusal prints its reason.
+
+## Usage
+
+```sh
+adhere lint                    # audit the working directory
+adhere lint --preset effect    # add a built-in rule set; the config becomes optional
+adhere lint --threshold 0.8    # replace the config's threshold; per-rule thresholds still apply
+adhere validate                # load the config and rules without Jev, check for contradictions
+adhere init [--force]          # scaffold .adhere/config.ts and two example rules
+adhere skill                   # print the agent skill (below)
+```
+
+Bare `adhere` prints the help, which lists the commands, and
+`adhere <command> --help` lists a command's flags. `adhere --completions <shell>`
+prints a completion script.
+
+### What gets read
+
+`adhere lint` reads the `.ts` files under the working directory, except `.d.ts`,
+`.test.ts`, and config files. When the working directory contains `agents/`,
+`apps/`, or `packages/`, only those trees are read. Paths under
+`node_modules/`, `dist/`, `coverage/`, `vendor/`, `e2e/`, `references/`,
+`.adhere/`, `.agents/`, `.claude/`, `.direnv/`, `.alchemy/`, or `.vite/` are
+skipped. `.tsx` files are not read, and `.gitignore` is not consulted.
+
+### Init
+
+`adhere init` writes `.adhere/config.ts` and two example rules. It is safe to
+rerun: by default it reports existing files as skipped and does not clobber
+them. `--force` overwrites them. A config already at another accepted path is
+kept, and no second one is added, even with `--force`.
+
+### Validate
+
+`adhere validate` loads the config, rule files, and presets the way `lint`
+does, without calling Jev, so a file that fails to decode refuses here too, and
+it prints how many rules it loaded. `--preset` adds a built-in rule set, as for
+`lint`. It then checks the rules for local textual contradictions: it exits 1
+and prints the conflicting rule files when overlapping rule scopes contain
+opposite textual directives for the same topic, such as "Use service classes
+for IO" and "Do not use service classes for IO". Same-id nested rules are
+treated as intentional shadowing rather than contradictions.
+
 ## Config
 
-A config file in the working directory of the repo being audited, at one of
-these paths (keep one):
+A config file is optional. Without one, adhere reads the rule files in
+`.adhere/` and any `--preset`. A config names presets, sets the model and
+thresholds, or gives rules inline. It sits 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
 - `adhere.config.ts`
-- `.adhere/config.ts`
 - `.adhere.config.ts`
 
 ```ts
@@ -40,33 +134,22 @@ type UserId = typeof UserId.Type
 ```
 
 The default export is decoded with Effect `Schema`. An invalid shape refuses
-the run. The `import type` is erased at runtime, so the file also loads under
-the native executable, where `@drkmttr/adhere` is not installed. With the
-package installed, `defineConfig({...})` does the same thing.
-
-### Rules as Markdown files
-
-A repo's own rules live in `.adhere/`, one `*.md` file per rule. The path
-without `.md` is the rule id, so `.adhere/data/brand-ports.md` is
-`data/brand-ports`. When that directory exists, it is read without any config.
-A repo that already has a `docs/` directory may prefer `docs/adhere/`, so the
-rules sit with the rest of its documentation; point `rules` at it:
+the run. The `import type` is erased at runtime. `defineConfig({...})` from
+`@drkmttr/adhere` does the same thing as `satisfies Config`, and the executable
+supplies it whether or not the repo has the package installed; the editor's
+types come from the package as a dev dependency. A config can import other
+files by relative path, but no packages besides `@drkmttr/adhere`: the
+executable does not resolve `node_modules`.
 
-```ts
-export default { presets: ["effect"], rules: "./docs/adhere" } satisfies Config;
-```
+`rules` in the config, inline as above or as a directory (below), replaces the
+`.adhere/` rule files: none of them, root or nested, is read then.
 
-A config is otherwise needed only to name presets or set thresholds.
+### Rules as Markdown files
 
-Nested `.adhere/` directories are also discovered. A rule in
-`packages/api/.adhere/data/brand-ports.md` has the same id,
-`data/brand-ports`, but applies only to files under `packages/api/`. Root
-`.adhere/` rules apply project-wide. 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. There is no broader
-priority system: presets are global, project rules override preset rules with
-the same id, and nested project rules override less-specific project rules with
-the same id for files in their subtree.
+A repo's own rules live in `.adhere/`, one `*.md` file per rule, next to the
+config and the cache (neither is read as a rule). The path without `.md` is the
+rule id, so `.adhere/data/brand-ports.md` is `data/brand-ports`. When that
+directory exists, it is read without any config.
 
 A file is front matter, then a body. The first fenced code block in the body
 is the reference; prose around it renders on GitHub and is ignored. Without a
@@ -92,6 +175,30 @@ const Port = Schema.Int.pipe(
 validation refuses the run with its path in the message. `loadRules(directory)`
 from the package root does the same load for your own tooling.
 
+Nested `.adhere/` directories are also discovered. A rule in
+`packages/api/.adhere/data/brand-ports.md` has the same id,
+`data/brand-ports`, but applies only to files under `packages/api/`. Root
+`.adhere/` rules apply project-wide. 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. There is no broader
+priority system: presets are global, project rules override preset rules with
+the same id, and nested project rules override less-specific project rules with
+the same id for files in their subtree.
+
+`.adhere/` is the default rather than `docs/adhere/` because it keeps
+everything adhere owns in one directory: the config and the cache are tool
+state, not documentation, and would stay in `.adhere/` anyway. A nested
+`.adhere/` also scopes its rules to the directory that contains it (above). The
+cost is visibility: a dot directory is hidden from `ls`, and from `rg` without
+`--hidden`. A repo that would rather keep its rules with the rest of its
+documentation can point `rules` at `docs/adhere/`:
+
+```ts
+export default { presets: ["effect"], rules: "./docs/adhere" } satisfies Config;
+```
+
+Rules read through `rules` apply project-wide.
+
 ### Presets
 
 A preset has the shape of a config without `presets`: `rules`, and optionally
@@ -100,7 +207,7 @@ A preset has the shape of a config without `presets`: `rules`, and optionally
 [effect-solutions](https://github.com/kitlangton/effect-solutions) docs and the
 [effect/platform](https://effect.website/docs/platform/introduction/) docs.
 Name it in the config, or on the command line with `--preset effect`, in which
-case `adhere.config.ts` is optional.
+case the config file is optional.
 
 ### Precedence
 
@@ -109,40 +216,52 @@ order (a later preset wins), then the defaults `jev-latest` and `0.7`. A rule
 in `rules` replaces a preset rule with the same id. A rule's own `threshold`
 beats all of the above for that rule.
 
-## Run
+## How a file is judged
 
-From a checkout, with Bun:
+1. One Jev request per file, with the file's numbered lines and every rule as
+   the state, and one `noul` (yes/no probability) question per rule. Every
+   question shares the state cost of the request.
+2. A second request only when at least one rule's probability is above its
+   threshold: one `choice` question per flagged rule over the file's non-blank
+   lines, which yields the line to report. A file with more than 255 non-blank
+   lines is located in two steps (a block of 20 lines, then a line inside it).
+   Files longer than 5100 lines are skipped and counted in the summary.
 
-```sh
-bun install
-bun link          # puts `adhere` on PATH
-adhere --preset effect
-```
+## Cache
 
-`adhere` audits the working directory. When that directory contains `agents/`,
-`apps/`, or `packages/`, only those trees are read. Exit code 1 when there is
-at least one finding.
+Judgments are cached in `.adhere/cache/` (add it to `.gitignore`), one entry
+per file. An entry stores the file's content hash and, per rule, the
+probability, the located line, and a fingerprint of the rule's text and model.
+A changed file re-judges every rule for that file. An edited rule re-judges
+only that rule. A lowered threshold locates cached judgments that are newly
+above it without judging again. Entries depend on content, not on the
+machine, so restoring `.adhere/cache/` between CI runs skips unchanged files.
 
-Initialize a new project with a config and example rules:
+`TYPESAFE_API_KEY` is read only when a request is about to be sent. A run
+where every file is cached needs no key and no network.
 
-```sh
-adhere init
-adhere init --force  # overwrite the scaffold files if they already exist
-```
+## Agent skill
 
-The command is safe to rerun: by default it reports existing files as skipped
-and does not clobber them.
+[`skills/adhere/SKILL.md`](./skills/adhere/SKILL.md) teaches an agent to
+gather a repo's conventions into rule files, configure adhere, and calibrate
+thresholds. Install it with the [skills](https://github.com/vercel-labs/skills)
+CLI: `skills add darkmatter/adhere`. The binary carries the same file:
+`adhere skill` prints it, so `adhere skill > .agents/skills/adhere/SKILL.md`
+works without a checkout.
 
-Check only this project's configured rules for local textual contradictions:
+## Development
+
+From a checkout, with Bun:
 
 ```sh
-adhere contradictions
+bun install
+bun link          # puts `adhere` on PATH
+adhere lint --preset effect
 ```
 
-It exits 1 and prints the conflicting rule files when overlapping rule scopes
-contain opposite textual directives for the same topic, such as "Use service
-classes for IO" and "Do not use service classes for IO". Same-id nested rules
-are treated as intentional shadowing rather than contradictions.
+In a checkout no platform package is installed, so `bin/adhere.js` runs
+`src/main.ts` with Bun instead. `bun run typecheck` runs `tsc` and the linter,
+and `bun run test` runs the tests.
 
 ### Native executable
 
@@ -151,9 +270,16 @@ are treated as intentional shadowing rather than contradictions.
 [`--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.
-For another platform, add `--target`, for example `bun-darwin-arm64`.
+`bun run build:npm` compiles it for every published platform instead, each
+into its package under `dist/npm/`
+([`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. The package's `bin/adhere.js` finds it and runs it with Node.
 
-## Release
+### Release
 
 Releases are cut by CI from pushed version tags. From a clean, up-to-date
 `main`, push the release tag:
@@ -168,39 +294,17 @@ derives `0.3.0` from `v0.3.0`, and runs `bun run release -- --ci 0.3.0`.
 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.
 
-Publishing stays in `.github/workflows/publish.yaml`: the published GitHub
-Release triggers the OIDC trusted-publisher job, which verifies that
-`package.json` matches the release tag and then runs
-`npm publish --access public --provenance`. No npm token is used.
-
-## How a file is judged
-
-1. One Jev request per file, with the file's numbered lines and every rule as
-   the state, and one `noul` (yes/no probability) question per rule. Every
-   question shares the state cost of the request.
-2. A second request only when at least one rule's probability is above its
-   threshold: one `choice` question per flagged rule over the file's non-blank
-   lines, which yields the line to report. A file with more than 255 non-blank
-   lines is located in two steps (a block of 20 lines, then a line inside it).
-   Files longer than 5100 lines are skipped and counted in the summary.
-
-## Cache
-
-Judgments are cached in `.adhere/cache/` (add it to `.gitignore`), one entry
-per file. An entry stores the file's content hash and, per rule, the
-probability, the located line, and a fingerprint of the rule's text and model.
-A changed file re-judges every rule for that file. An edited rule re-judges
-only that rule. A lowered threshold locates cached judgments that are newly
-above it without judging again.
-
-`TYPESAFE_API_KEY` is read only when a request is about to be sent. A run
-where every file is cached needs no key and no network.
-
-## Agent skill
-
-[`skills/adhere/SKILL.md`](./skills/adhere/SKILL.md) teaches an agent to
-gather a repo's conventions into rule files, configure adhere, and calibrate
-thresholds. Install it with the [skills](https://github.com/vercel-labs/skills)
-CLI: `skills add darkmatter/adhere`. The binary carries the same file:
-`adhere skill` prints it, so `adhere skill > .agents/skills/adhere/SKILL.md`
-works without a checkout.
+Publishing stays in `.github/workflows/publish.yaml`: after release-it
+finishes, `.github/workflows/release.yaml` calls the reusable publish workflow
+directly, avoiding a chained GitHub Release event created by `GITHUB_TOKEN`.
+The publish workflow verifies that `package.json` matches the release tag,
+builds the platform packages, and publishes each of them before
+`@drkmttr/adhere`, which it first lists them in as `optionalDependencies` at
+the same version. 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: `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 platform packages whose version
+is already on npm.

package/bin/adhere.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * `adhere` on PATH. Runs the executable compiled for this machine, which the
+ * install fetched as the optional dependency `@drkmttr/adhere-<platform>-<arch>`
+ * (see scripts/npm-packages.ts). A checkout has none installed, so there it
+ * runs src/main.ts with Bun instead.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const platform = `${process.platform}-${process.arch}`;
+const platformPackage = `@drkmttr/adhere-${platform}`;
+const executable = process.platform === "win32" ? "adhere.exe" : "adhere";
+const args = process.argv.slice(2);
+
+const resolveExecutable = () => {
+  try {
+    return createRequire(import.meta.url).resolve(`${platformPackage}/bin/${executable}`);
+  } catch {
+    return undefined;
+  }
+};
+
+const run = (command, commandArgs) => {
+  const result = spawnSync(command, commandArgs, { stdio: "inherit" });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+};
+
+const prebuilt = resolveExecutable();
+if (prebuilt) run(prebuilt, args);
+else if (existsSync(new URL("../.git", import.meta.url)))
+  run("bun", [fileURLToPath(new URL("../src/main.ts", import.meta.url)), ...args]);
+else {
+  console.error(
+    `adhere: ${platformPackage} is not installed, so there is no executable for ${platform}.` +
+      " It is an optional dependency of @drkmttr/adhere: reinstall without --omit=optional or --no-optional." +
+      " If it is still missing, adhere does not ship an executable for this platform.",
+  );
+  process.exitCode = 1;
+}

package/bun.lock

@@ -5,10 +5,10 @@
     "": {
       "name": "@drkmttr/adhere",
       "dependencies": {
-        "@effect/platform-bun": "4.0.0-rc.112",
         "effect": "4.0.0-rc.112",
       },
       "devDependencies": {
+        "@effect/platform-bun": "4.0.0-rc.112",
         "@types/bun": "^1.4.2",
         "@types/node": "^24.13.6",
         "release-it": "^21.1.0",

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
-  "description": "Lints a repository against reference code in adhere.config.ts, judged by Jev.",
+  "description": "Lints a repository against reference code in .adhere/, judged by Jev.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/darkmatter/adhere.git"
   },
   "bin": {
-    "adhere": "src/main.ts"
+    "adhere": "bin/adhere.js"
   },
   "type": "module",
   "imports": {
@@ -26,13 +26,14 @@
     "test": "vp test",
     "typecheck": "tsc --noEmit && bun run lint",
     "build": "bun build --compile --minify --sourcemap src/main.ts --asset ./presets --outfile dist/adhere",
+    "build:npm": "bun scripts/npm-packages.ts build",
     "release": "release-it"
   },
   "dependencies": {
-    "@effect/platform-bun": "4.0.0-rc.112",
     "effect": "4.0.0-rc.112"
   },
   "devDependencies": {
+    "@effect/platform-bun": "4.0.0-rc.112",
     "@types/bun": "^1.4.2",
     "@types/node": "^24.13.6",
     "release-it": "^21.1.0",
@@ -58,5 +59,12 @@
       "allowSameVersion": true,
       "publish": false
     }
+  },
+  "optionalDependencies": {
+    "@drkmttr/adhere-darwin-arm64": "0.3.0",
+    "@drkmttr/adhere-darwin-x64": "0.3.0",
+    "@drkmttr/adhere-linux-arm64": "0.3.0",
+    "@drkmttr/adhere-linux-x64": "0.3.0",
+    "@drkmttr/adhere-win32-x64": "0.3.0"
   }
 }

package/scripts/npm-packages.ts

@@ -0,0 +1,68 @@
+/**
+ * The npm packages that carry the compiled executable, one per platform. Each
+ * is an optional dependency of `@drkmttr/adhere` limited by `os` and `cpu`, so
+ * an install fetches only its own machine's, and `bin/adhere.js` runs it.
+ *
+ *   bun scripts/npm-packages.ts build   compile every platform into dist/npm/
+ *   bun scripts/npm-packages.ts pin     list them in package.json at its version
+ *
+ * Only the publish job runs `pin`. The committed package.json leaves them out
+ * because a version is not on npm until that job has published it.
+ */
+import packageJson from "../package.json";
+import { $ } from "bun";
+import { rm } from "node:fs/promises";
+
+process.chdir(new URL("../", import.meta.url).pathname);
+
+/** `os` and `cpu` are Node's `process.platform` and `process.arch`, which the launcher names the package from. */
+const platforms = [
+  { os: "darwin", cpu: "arm64", target: "bun-darwin-arm64" },
+  { os: "darwin", cpu: "x64", target: "bun-darwin-x64" },
+  { os: "linux", cpu: "arm64", target: "bun-linux-arm64" },
+  { os: "linux", cpu: "x64", target: "bun-linux-x64" },
+  { os: "win32", cpu: "x64", target: "bun-windows-x64" },
+] as const;
+
+type Platform = (typeof platforms)[number];
+
+const packageName = ({ os, cpu }: Platform) => `${packageJson.name}-${os}-${cpu}`;
+
+const writeJson = (path: string, value: unknown) =>
+  Bun.write(path, `${JSON.stringify(value, null, 2)}\n`);
+
+const build = async () => {
+  for (const platform of platforms) {
+    const directory = `dist/npm/${platform.os}-${platform.cpu}`;
+    const executable = platform.os === "win32" ? "adhere.exe" : "adhere";
+    await rm(directory, { recursive: true, force: true });
+    await $`bun build --compile --minify --sourcemap --target=${platform.target} src/main.ts --asset ./presets --outfile ${directory}/bin/${executable}`;
+    await writeJson(`${directory}/package.json`, {
+      name: packageName(platform),
+      version: packageJson.version,
+      description: `The adhere executable for ${platform.os}-${platform.cpu}. Install ${packageJson.name}, which depends on it.`,
+      repository: packageJson.repository,
+      os: [platform.os],
+      cpu: [platform.cpu],
+      files: [`bin/${executable}`],
+      preferUnplugged: true,
+      publishConfig: packageJson.publishConfig,
+    });
+  }
+};
+
+const pin = () =>
+  writeJson("package.json", {
+    ...packageJson,
+    optionalDependencies: Object.fromEntries(
+      platforms.map((platform) => [packageName(platform), packageJson.version]),
+    ),
+  });
+
+const command = Bun.argv[2];
+if (command === "build") await build();
+else if (command === "pin") await pin();
+else {
+  console.error("usage: bun scripts/npm-packages.ts build|pin");
+  process.exit(2);
+}

package/skills/adhere/SKILL.md

@@ -38,15 +38,17 @@ Keep rules about intent, shape, and placement:
 - "Business logic depends on a config service, not on `Config.*` reads."
 - "Domain errors are `Schema.TaggedError` classes, not thrown `Error`."
 
-Skip rules a preset already covers. Run `adhere --help` and read
+Skip rules a preset already covers. Run `adhere lint --help` and read
 `presets/effect/` in the adhere repo before writing Effect rules; extend with
 `presets: ["effect"]` and add only what is specific to this repo.
 
 ## 3. Write each rule as a file
 
-Default location `.adhere/<topic>/<slug>.md`. If the repo already has `docs/`,
-use `docs/adhere/<topic>/<slug>.md` and set `rules: "./docs/adhere"` in the
-config. The path without `.md` is the rule id.
+Default location `.adhere/<topic>/<slug>.md`, next to the config and the
+cache. Use `docs/adhere/<topic>/<slug>.md` with `rules: "./docs/adhere"` in the
+config only when the user wants rules kept with the repo's docs; rules read
+that way apply project-wide, and nested `.adhere/` directories are not read.
+The path without `.md` is the rule id.
 
 ````md
 ---
@@ -73,10 +75,10 @@ Rules for the rule:
 
 ## 4. Configure
 
-Pick one config location: `adhere.config.ts`, `.adhere/config.ts`, or
-`.adhere.config.ts`. A config is optional when `.adhere/` exists or a preset is
-passed on the command line. Use a type-only import so the file also loads
-under the native binary:
+Put the config at `.adhere/config.ts`. `adhere.config.ts` and
+`.adhere.config.ts` also load; keep one. A config is optional when `.adhere/`
+exists or a preset is passed on the command line. Use a type-only import so
+the file also loads under the native binary:
 
 ```ts
 import type { Config } from "@drkmttr/adhere";
@@ -93,8 +95,9 @@ uncached files; in this org it comes from SOPS via `just shell`.
 ## 5. Run and calibrate
 
 ```sh
-adhere                     # or: adhere --preset effect
-adhere --threshold 0.9     # re-reads the cache, sends nothing
+adhere validate              # decodes the config and rules, checks contradictions
+adhere lint                  # or: adhere lint --preset effect
+adhere lint --threshold 0.9  # re-reads the cache, sends nothing
 ```
 
 Then, per rule, read the findings and decide:

package/src/cli.ts

@@ -6,7 +6,7 @@ import { render, runAudit } from "#workflows/audit.ts";
 import type { Overrides } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
 import { initProject } from "#init.ts";
-import { presetNames } from "#presets.ts";
+import { type PresetName, presetNames } from "#presets.ts";
 import { globalRuleSet } from "#rules.ts";
 import {
   Console,
@@ -39,16 +39,9 @@ class ContradictionsReported extends Schema.TaggedError<ContradictionsReported>(
   readonly [Runtime.errorReported] = false;
 }
 
-class UsageReported extends Schema.TaggedError<UsageReported>()(
-  "UsageReported",
-  { message: Schema.String },
-) {
-  readonly [Runtime.errorReported] = false;
-}
-
 const preset = Flag.choice("preset", presetNames).pipe(
   Flag.optional,
-  Flag.withDescription("Add a built-in rule set. With a preset, adhere.config.ts is optional."),
+  Flag.withDescription("Add a built-in rule set. With a preset, .adhere/config.ts is optional."),
 );
 
 const threshold = Flag.float("threshold").pipe(
@@ -58,6 +51,14 @@ const threshold = Flag.float("threshold").pipe(
   ),
 );
 
+const force = Flag.boolean("force").pipe(
+  Flag.withDefault(false),
+  Flag.withDescription("Overwrite existing scaffold files."),
+);
+
+const chosenPresets = (flag: Option.Option<PresetName>): ReadonlyArray<PresetName> =>
+  Option.isSome(flag) ? [flag.value] : [];
+
 export const auditLayer = (overrides: Overrides) =>
   Layer.mergeAll(
     SourceWalkerLive,
@@ -65,14 +66,8 @@ export const auditLayer = (overrides: Overrides) =>
     JevLive.pipe(Layer.provide(FetchHttpClient.layer)),
   ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
 
-/** `adhere skill`: the agent skill for writing rules, as shipped in the binary. */
-export const skillCommand = Command.make("skill", {}, () => Console.log(skill.trimEnd())).pipe(
-  Command.withDescription(
-    "Print the agent skill that gathers a repo's conventions into rules and configures adhere. Pipe it into .agents/skills/adhere/SKILL.md or hand it to an agent.",
-  ),
-);
-
-const audit = Command.make("adhere", { preset, threshold }, () =>
+/** `adhere lint`: the audit. */
+export const lintCommand = Command.make("lint", { preset, threshold }, () =>
   Effect.gen(function* () {
     const result = yield* runAudit;
     const stdio = yield* Stdio.Stdio;
@@ -86,89 +81,70 @@ const audit = Command.make("adhere", { preset, threshold }, () =>
   }),
 ).pipe(
   Command.withDescription(
-    "Audit the working directory against reference code from adhere.config.ts or a preset, judged by Jev.",
+    "Audit the working directory against reference code from .adhere/config.ts or a preset, judged by Jev.",
   ),
   Command.provide((input) =>
     auditLayer({
-      presets: Option.isSome(input.preset) ? [input.preset.value] : [],
+      presets: chosenPresets(input.preset),
       threshold: Option.getOrUndefined(input.threshold),
     }),
   ),
 );
 
-const INIT_HELP = `Usage: adhere init [--force]
-
-Scaffold adhere.config.ts and example Markdown rules.
-
-Options:
-  --force   Overwrite existing scaffold files
-  --help    Show this help
-
-Examples:
-  adhere init
-  adhere init --force`;
-
-const CONTRADICTIONS_HELP = `Usage: adhere contradictions
-
-Check this project's configured adhere rules for local textual contradictions.
-
-Examples:
-  adhere contradictions`;
-
-export const runInitCommand = (args: ReadonlyArray<string>) =>
+/**
+ * `adhere validate`: everything `lint` loads, without Jev. A config, rule file,
+ * or preset that does not decode refuses here the way it would refuse `lint`.
+ */
+export const validateCommand = Command.make("validate", { preset }, () =>
   Effect.gen(function* () {
-    if (args.includes("--help") || args.includes("-h")) {
-      yield* Console.log(INIT_HELP);
-      return;
-    }
-    const unknown = args.filter((arg) => arg !== "--force");
-    if (unknown.length > 0) {
-      yield* Console.error(`Unknown option for adhere init: ${unknown.join(", ")}`);
-      yield* Console.error(INIT_HELP);
-      return yield* UsageReported.make({ message: "invalid init arguments" });
+    const config = yield* AdhereConfig;
+    const path = yield* Path.Path;
+    const entries = config.scopedRules ?? globalRuleSet(config.rules, path.resolve());
+    const contradictions = findContradictions(entries);
+    const loaded = `${entries.length} ${entries.length === 1 ? "rule" : "rules"} loaded.`;
+    yield* Console.log([loaded, formatContradictions(contradictions)].join("\n"));
+    if (contradictions.length > 0) {
+      return yield* ContradictionsReported.make({ count: contradictions.length });
     }
+  }),
+).pipe(
+  Command.withDescription(
+    "Load the config, rule files, and presets the way lint does, without calling Jev, and check the rules for contradictions.",
+  ),
+  Command.provide((input) => AdhereConfigLive({ presets: chosenPresets(input.preset) })),
+);
+
+/** `adhere init`: the scaffold. */
+export const initCommand = Command.make("init", { force }, (input) =>
+  Effect.gen(function* () {
     const path = yield* Path.Path;
-    const result = yield* initProject(path.resolve(), {
-      force: args.includes("--force"),
-    });
+    const result = yield* initProject(path.resolve(), { force: input.force });
     const lines = [
-      result.created.length > 0
-        ? `created: ${result.created.join(", ")}`
-        : "created: none",
-      result.skipped.length > 0
-        ? `skipped: ${result.skipped.join(", ")}`
-        : "skipped: none",
+      result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
+      result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
     ];
     yield* Console.log(lines.join("\n"));
-  });
+  }),
+).pipe(Command.withDescription("Scaffold .adhere/config.ts and example Markdown rules."));
 
-export const runContradictionsCommand = (args: ReadonlyArray<string>) =>
-  Effect.gen(function* () {
-    if (args.includes("--help") || args.includes("-h")) {
-      yield* Console.log(CONTRADICTIONS_HELP);
-      return;
-    }
-    if (args.length > 0) {
-      yield* Console.error(
-        `Unknown option for adhere contradictions: ${args.join(", ")}`,
-      );
-      yield* Console.error(CONTRADICTIONS_HELP);
-      return yield* UsageReported.make({
-        message: "invalid contradictions arguments",
-      });
-    }
-    const config = yield* AdhereConfig;
-    const path = yield* Path.Path;
-    const root = path.resolve();
-    const entries = config.scopedRules ?? globalRuleSet(config.rules, root);
-    const contradictions = findContradictions(entries);
-    yield* Console.log(formatContradictions(contradictions));
-    if (contradictions.length > 0) {
-      return yield* ContradictionsReported.make({
-        count: contradictions.length,
-      });
-    }
-  });
+/** `adhere skill`: the agent skill for writing rules, as shipped in the binary. */
+export const skillCommand = Command.make("skill", {}, () => Console.log(skill.trimEnd())).pipe(
+  Command.withDescription(
+    "Print the agent skill that gathers a repo's conventions into rules and configures adhere. Pipe it into .agents/skills/adhere/SKILL.md or hand it to an agent.",
+  ),
+);
 
-/** The whole CLI: `adhere` audits, `adhere skill` prints the skill. */
-export const auditCommand = audit.pipe(Command.withSubcommands([skillCommand]));
+/** The whole CLI. Bare `adhere` prints its help. */
+export const cli = Command.make("adhere").pipe(
+  Command.withDescription("Lint a repository against reference code in .adhere/, judged by Jev."),
+  Command.withExamples([
+    { command: "adhere init", description: "Scaffold .adhere/config.ts and two example rules" },
+    { command: "adhere validate", description: "Check the config and rules without calling Jev" },
+    { command: "adhere lint", description: "Audit the working directory" },
+    {
+      command: "adhere lint --preset effect",
+      description: "Audit against the built-in Effect rules",
+    },
+  ]),
+  Command.withSubcommands([lintCommand, validateCommand, initCommand, skillCommand]),
+);

package/src/config.ts

@@ -32,6 +32,12 @@ export const AdhereConfig = Schema.Struct({
 /** Where a repo keeps its rule files by default. The cache lives under it. */
 export const ADHERE_DIRECTORY = ".adhere";
 export const CACHE_DIRECTORY = `${ADHERE_DIRECTORY}/cache`;
+/** Where a config may live, relative to the working directory. Exactly one may exist. */
+export const CONFIG_FILES = [
+  `${ADHERE_DIRECTORY}/config.ts`,
+  "adhere.config.ts",
+  ".adhere.config.ts",
+] as const;
 export interface AdhereConfig extends Schema.Schema.Type<typeof AdhereConfig> {}
 
 /** The shape a config file default-exports. */

package/src/init.ts

@@ -1,5 +1,6 @@
 import { access, mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
+import { CONFIG_FILES } from "#config.ts";
 import { Effect } from "effect";
 
 export interface InitResult {
@@ -44,8 +45,10 @@ export const loadCustomerProfile = (customerId: CustomerId) =>
 \`\`\`
 `;
 
+const CONFIG_PATH = CONFIG_FILES[0];
+
 const files = [
-  ["adhere.config.ts", CONFIG],
+  [CONFIG_PATH, CONFIG],
   [".adhere/style/prefer-small-files.md", SMALL_FILES],
   [".adhere/style/name-domain-actions.md", NAME_EFFECTS],
 ] as const;
@@ -56,6 +59,15 @@ const exists = (path: string): Promise<boolean> =>
     () => false,
   );
 
+/** A config at another accepted path. Scaffolding a second one would refuse every run. */
+const otherConfig = (root: string) =>
+  Effect.promise(async () => {
+    for (const file of CONFIG_FILES) {
+      if (file !== CONFIG_PATH && (await exists(join(root, file)))) return file;
+    }
+    return undefined;
+  });
+
 const writeScaffoldFile = (root: string, path: string, contents: string, options: InitOptions) =>
   Effect.tryPromise({
     try: async () => {
@@ -79,7 +91,12 @@ export const initProject = (
   Effect.gen(function* () {
     const created: Array<string> = [];
     const skipped: Array<string> = [];
+    const existing = yield* otherConfig(root);
     for (const [path, contents] of files) {
+      if (path === CONFIG_PATH && existing !== undefined) {
+        skipped.push(existing);
+        continue;
+      }
       const status = yield* writeScaffoldFile(root, path, contents, options);
       if (status === "created") {
         created.push(relative(root, join(root, path)));

package/src/main.ts

@@ -1,21 +1,23 @@
 #!/usr/bin/env bun
-import { auditCommand, runContradictionsCommand, runInitCommand } from "#cli.ts";
-import { AdhereConfigLive } from "#services/AdhereConfig.ts";
+import { cli } from "#cli.ts";
+import * as adhere from "#index.ts";
 import { version } from "#version.ts";
 import { BunRuntime, BunServices } from "@effect/platform-bun";
+import { plugin } from "bun";
 import { Effect } from "effect";
 import { Command } from "effect/unstable/cli";
 
-const [subcommand, ...args] = Bun.argv.slice(2);
+// A config file may import `@drkmttr/adhere`, for `defineConfig`. The compiled
+// executable resolves no packages from disk, so it answers that import with
+// its own copy, whether or not the audited repo has the package installed.
+plugin({
+  name: "@drkmttr/adhere",
+  setup: (build) => {
+    build.module("@drkmttr/adhere", () => ({ exports: { ...adhere }, loader: "object" }));
+  },
+});
 
-const program =
-  subcommand === "init"
-    ? runInitCommand(args)
-    : subcommand === "contradictions"
-      ? runContradictionsCommand(args).pipe(Effect.provide(AdhereConfigLive({})))
-      : Command.run(auditCommand, { version });
-
-program.pipe(
+Command.run(cli, { version }).pipe(
   // oxlint-disable-next-line effecttsgo/strict-effect-provide -- this executable entrypoint supplies Bun's process services.
   Effect.provide(BunServices.layer),
   BunRuntime.runMain,

package/src/services/AdhereConfig.ts

@@ -1,6 +1,7 @@
 import {
   ADHERE_DIRECTORY,
   type AdhereConfig as Decoded,
+  CONFIG_FILES,
   ConfigUnavailable,
   decodeConfig,
   type Loaded,
@@ -20,9 +21,6 @@ import {
 } from "#rules.ts";
 import { Context, Effect, FileSystem, Layer, Path, Record } from "effect";
 
-/** Where a config may live, relative to the working directory. Exactly one may exist. */
-export const CONFIG_FILES = ["adhere.config.ts", ".adhere/config.ts", ".adhere.config.ts"] as const;
-
 export class AdhereConfig extends Context.Service<
   AdhereConfig,
   ResolvedConfig

package/test/audit.test.ts

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Crypto, Effect, FileSystem, Layer, Path, Record } from "effect";
@@ -433,7 +433,7 @@ describe("init", () => {
   it("scaffolds config and example rules without clobbering existing files", async () => {
     const root = join(tmpdir(), `adhere-init-${Date.now()}`);
     await Effect.runPromise(initProject(root));
-    const config = await readFile(join(root, "adhere.config.ts"), "utf8");
+    const config = await readFile(join(root, ".adhere", "config.ts"), "utf8");
     const rule = await readFile(join(root, ".adhere", "style", "prefer-small-files.md"), "utf8");
 
     expect(config).toContain("satisfies Config");
@@ -441,9 +441,21 @@ describe("init", () => {
 
     const second = await Effect.runPromise(initProject(root));
     expect(second.created).toEqual([]);
-    expect(second.skipped).toContain("adhere.config.ts");
+    expect(second.skipped).toContain(".adhere/config.ts");
     expect(second.skipped).toContain(".adhere/style/prefer-small-files.md");
   });
+
+  it("keeps a config at another accepted path instead of adding a second one", async () => {
+    const root = join(tmpdir(), `adhere-init-existing-${Date.now()}`);
+    await mkdir(root, { recursive: true });
+    await writeFile(join(root, "adhere.config.ts"), "export default {};\n", "utf8");
+
+    const result = await Effect.runPromise(initProject(root, { force: true }));
+
+    expect(result.skipped).toContain("adhere.config.ts");
+    expect(result.created).not.toContain(".adhere/config.ts");
+    await expect(access(join(root, ".adhere", "config.ts"))).rejects.toThrow();
+  });
 });
 
 describe("pipeline", () => {

package/test/cli.test.ts

@@ -1,9 +1,13 @@
 import { execFile } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { promisify } from "node:util";
 import packageJson from "../package.json";
 import { describe, expect, it } from "vite-plus/test";
 
 const execFileAsync = promisify(execFile);
+const main = join(process.cwd(), "src", "main.ts");
 
 describe("cli", () => {
   it("reports the package version", async () => {
@@ -14,4 +18,28 @@ describe("cli", () => {
     expect(stderr).toBe("");
     expect(stdout.trim()).toBe(`adhere v${packageJson.version}`);
   });
+
+  it("prints help listing every command when run bare", async () => {
+    const { stdout } = await execFileAsync("bun", [main], { cwd: process.cwd() });
+    const subcommands = stdout.slice(stdout.indexOf("SUBCOMMANDS"), stdout.indexOf("EXAMPLES"));
+
+    for (const name of ["lint", "validate", "init", "skill"]) {
+      expect(subcommands).toMatch(new RegExp(`^  ${name} `, "m"));
+    }
+  });
+
+  it("validates a repo's rules without calling Jev", async () => {
+    const root = join(tmpdir(), `adhere-validate-${Date.now()}`);
+    await mkdir(join(root, ".adhere"), { recursive: true });
+    await writeFile(
+      join(root, ".adhere", "ports.md"),
+      '---\ndescription: A port is a branded integer.\n---\n\nconst Port = Schema.Int.pipe(Schema.brand("Port"))\n',
+      "utf8",
+    );
+
+    const { stdout } = await execFileAsync("bun", [main, "validate"], { cwd: root });
+
+    expect(stdout).toContain("1 rule loaded.");
+    expect(stdout).toContain("No contradictions found among configured rules.");
+  });
 });

package/tsconfig.json

@@ -21,6 +21,6 @@
       "#*": ["./src/*"]
     }
   },
-  "include": ["src/**/*.ts", "test/**/*.ts", "adhere.config.ts"],
+  "include": ["src/**/*.ts", "test/**/*.ts", "scripts/**/*.ts", ".adhere/config.ts"],
   "exclude": ["dist", "node_modules"]
 }