@drkmttr/adhere 0.10.0 → 0.12.0

package/src/cli.ts

@@ -23,6 +23,7 @@ import {
 import type { Flags } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
 import { type Install, initProject } from "#init.ts";
+import { installRules, listRules, parseSource } from "#install.ts";
 import { formatLinterCheck, tallyProjectRules } from "#mechanical.ts";
 import { type PresetName, presetNames } from "#presets.ts";
 import { globalRuleSet } from "#rules.ts";
@@ -99,6 +100,13 @@ const threshold = Flag.float("threshold").pipe(
   ),
 );
 
+const sufficiencyThreshold = Flag.float("sufficiency-threshold").pipe(
+  Flag.optional,
+  Flag.withDescription(
+    "Warn on a finding when Jev's probability that the file shows enough to decide it is below this value, 0 to 1. Replaces the config's sufficiencyThreshold; the default is 0.6.",
+  ),
+);
+
 const limit = Flag.integer("limit").pipe(
   Flag.filter(
     (checks) => checks >= 0,
@@ -219,7 +227,7 @@ export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
 /** `adhere lint`: the audit. */
 export const lintCommand = Command.make(
   "lint",
-  { preset, threshold, yes, limit, rpm, filter, denyWarnings },
+  { preset, threshold, sufficiencyThreshold, yes, limit, rpm, filter, denyWarnings },
   (input) =>
     Effect.gen(function* () {
       const stdio = yield* Stdio.Stdio;
@@ -264,6 +272,7 @@ export const lintCommand = Command.make(
       {
         presets: input.preset,
         threshold: Option.getOrUndefined(input.threshold),
+        sufficiencyThreshold: Option.getOrUndefined(input.sufficiencyThreshold),
         rpm: Option.getOrUndefined(input.rpm),
       },
       input.filter,
@@ -318,7 +327,7 @@ export const validateCommand = Command.make("validate", { preset }, () =>
 const installLine = (install: Install): string => {
   switch (install.status) {
     case "installed":
-      return `installed: @drkmttr/adhere with ${install.packageManager}`;
+      return `installed: ${install.what} with ${install.packageManager}`;
     case "listed":
       return "installed: none, @drkmttr/adhere is already in package.json";
     case "no-package-json":
@@ -326,11 +335,25 @@ const installLine = (install: Install): string => {
   }
 };
 
+const shared = Flag.string("shared").pipe(
+  Flag.filter(
+    (repo) => /^[\w.-]+\/[\w.-]+$/.test(repo),
+    (repo) => `--shared names a GitHub repo as org/repo, not ${repo}.`,
+  ),
+  Flag.optional,
+  Flag.withDescription(
+    "Scaffold a repo of rules other repos copy with adhere install, named org/repo on GitHub: example rules, a README, a CI workflow that runs adhere validate, and an alchemy.run.ts that creates the repo and its TYPESAFE_API_KEY secret.",
+  ),
+);
+
 /** `adhere init`: the scaffold. */
-export const initCommand = Command.make("init", { force }, (input) =>
+export const initCommand = Command.make("init", { force, shared }, (input) =>
   Effect.gen(function* () {
     const path = yield* Path.Path;
-    const result = yield* initProject(path.resolve(), { force: input.force });
+    const result = yield* initProject(path.resolve(), {
+      force: input.force,
+      ...Option.match(input.shared, { onNone: () => ({}), onSome: (repo) => ({ shared: repo }) }),
+    });
     const lines = [
       result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
       result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
@@ -344,6 +367,58 @@ export const initCommand = Command.make("init", { force }, (input) =>
   ),
 );
 
+const source = Argument.string("source").pipe(
+  Argument.filterMap(
+    (spec) => Option.fromNullishOr(parseSource(spec)),
+    (spec) => `org/repo, then optionally a topic or rule and #ref, not ${spec}`,
+  ),
+  Argument.withDescription(
+    "A GitHub repo with rules in .adhere/, as org/repo, optionally followed by a topic or a rule, as in org/repo/data/brand-ports, and by #branch or #tag.",
+  ),
+);
+
+/** `adhere list org/repo`: the rules another repo's `.adhere/` holds. */
+export const listCommand = Command.make("list", { source }, (input) =>
+  Effect.gen(function* () {
+    const rules = yield* listRules(input.source);
+    const width = Math.max(...rules.map(({ id }) => id.length));
+    yield* Console.log(
+      rules.map(({ id, description }) => `${id.padEnd(width)}  ${description}`).join("\n"),
+    );
+  }),
+).pipe(
+  Command.withDescription(
+    "List the rules in a GitHub repo's .adhere/, each with its description, for adhere install. Clones with git, so a private repo needs git's credentials for it.",
+  ),
+);
+
+/** `adhere install org/repo`: another repo's rules, copied into this one's `.adhere/`. */
+export const installCommand = Command.make(
+  "install",
+  {
+    source,
+    force: Flag.boolean("force").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Overwrite rule files already in .adhere/."),
+    ),
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const result = yield* installRules(path.resolve(), input.source, { force: input.force });
+      yield* Console.log(
+        [
+          result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
+          result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
+        ].join("\n"),
+      );
+    }),
+).pipe(
+  Command.withDescription(
+    "Copy the rules in a GitHub repo's .adhere/, or one topic or rule of them, into this repo's .adhere/<org>/<repo>/. They are this repo's own rules from then on, to edit or keep in step by hand. Existing files are skipped unless --force.",
+  ),
+);
+
 /**
  * The key typed at a masked prompt, or piped in: `adhere login < key.txt`.
  * Whitespace around it, like the newline a pipe ends with, is dropped.
@@ -431,6 +506,10 @@ export const cli = Command.make("adhere").pipe(
     },
     { command: "adhere login", description: "Save your TypeSafe AI API key for later runs" },
     { command: "adhere lint", description: "Audit the working directory" },
+    {
+      command: "adhere install org/repo",
+      description: "Copy another repo's .adhere/ rules into this one",
+    },
     {
       command: "adhere lint --preset effect",
       description: "Audit against the built-in Effect rules",
@@ -440,6 +519,8 @@ export const cli = Command.make("adhere").pipe(
     lintCommand,
     validateCommand,
     initCommand,
+    listCommand,
+    installCommand,
     loginCommand,
     logoutCommand,
     skillCommand,

package/src/config.ts

@@ -28,6 +28,17 @@ const RuleFields = Schema.Struct({
    * findings, which does not.
    */
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
+  /**
+   * Where the rule applies, each a description of code that breaks it: Jev is
+   * asked of each whether any code that breaks the rule is as it describes,
+   * and a finding stands only when it says yes to every one.
+   */
+  appliesTo: Schema.optionalKey(Schema.Array(Schema.String)),
+  /**
+   * Where the rule does not apply: Jev is asked of each whether all the code
+   * that breaks the rule is as it describes, and a yes to any drops the finding.
+   */
+  excludeIf: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
 /** Before 0.7, a rule's examples were `reference` and `avoid`: read as `must` and `never`. */
@@ -112,6 +123,12 @@ export const AdhereConfig = Schema.Struct({
    * The minimum confidence threshold for a positive match. Defaults to 0.8
    */
   threshold: Schema.optionalKey(Schema.Finite),
+  /**
+   * Below this, Jev's probability that a file shows enough to decide a
+   * finding's rule adds a warning to the finding: check what the code relies
+   * on outside the file. Defaults to 0.6
+   */
+  sufficiencyThreshold: Schema.optionalKey(Schema.Finite),
   /**
    * The presets to use for rule matching. Defaults to an empty array. Current presets
    * include "effect" and "alchemy". Subcategories can be expanded by appending `/<subcategory>`.
@@ -175,13 +192,17 @@ export const SKIPPED_DIRECTORIES: ReadonlySet<string> = new Set([
 /**
  * Directories whose files are tests, matched as whole path segments below the
  * working directory, as skipped directories are. Only a rule that says `tests`
- * judges them, or a `.test.ts` or `.spec.ts` file anywhere.
+ * judges them, or a `.test` or `.spec` file, such as `a.test.tsx`, anywhere.
  */
 export const TEST_DIRECTORIES: ReadonlySet<string> = new Set([
   "test",
   "tests",
   "__tests__",
+  "testing",
   "fixtures",
+  "fixture",
+  "__fixtures__",
+  "__mocks__",
 ]);
 
 /** The shape a config file default-exports: the schema's input, where `presets` is optional. */
@@ -212,11 +233,14 @@ export type Loaded<T extends { readonly rules?: unknown }> = Omit<T, "rules"> &
 
 export const DEFAULT_MODEL = "jev-latest";
 export const DEFAULT_THRESHOLD = 0.8;
+export const DEFAULT_SUFFICIENCY_THRESHOLD = 0.6;
 
 /** A config with its presets folded in and every default applied. */
 export interface ResolvedConfig {
   readonly model: string;
   readonly threshold: number;
+  /** Below this, a finding's sufficiency adds a warning to it. */
+  readonly sufficiencyThreshold: number;
   readonly rules: Rules;
   readonly scopedRules?: RuleSet;
   /** Requests to Jev a minute, at most. Unset, requests go out as fast as they are made. */
@@ -232,6 +256,8 @@ export interface Flags {
   readonly presets?: ReadonlyArray<PresetName>;
   /** Replaces the config's global threshold. Per-rule thresholds still win. */
   readonly threshold?: number | undefined;
+  /** Replaces the config's sufficiency threshold. */
+  readonly sufficiencyThreshold?: number | undefined;
   /** Throttles requests to Jev to at most this many a minute. */
   readonly rpm?: number | undefined;
 }
@@ -271,6 +297,8 @@ export const resolveConfig = (
   return {
     model: config.model ?? last("model") ?? DEFAULT_MODEL,
     threshold: flags.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
+    sufficiencyThreshold:
+      flags.sufficiencyThreshold ?? config.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD,
     rules: Object.assign({}, ...applied.map((preset) => preset.rules), config.rules),
     ...(flags.rpm === undefined ? {} : { rpm: flags.rpm }),
     ...(config.exclude === undefined ? {} : { exclude: config.exclude }),

package/src/excerpt.ts

@@ -1,20 +1,12 @@
 import { scan } from "#highlight.ts";
 
-/**
- * The lines a finding shows: the statement its line is in, such as the
- * function around it, and a few lines on either side of the line.
- */
+/** The lines a finding shows: the section of the file it is in. */
 export interface Excerpt {
   /** The number of the first line, counting from 1. */
   readonly start: number;
   readonly lines: ReadonlyArray<string>;
 }
 
-/** How far an excerpt reaches on either side of the finding's line, in whole statements. */
-const AROUND = 3;
-/** The most lines a statement can have and still be shown whole. */
-const WHOLE = 30;
-
 /** Lines of the code, first to last, counting from 1. */
 export interface Range {
   readonly first: number;
@@ -48,19 +40,13 @@ const ROLES: Readonly<Record<string, Piece["role"]>> = {
   ",": "separator",
 };
 
-/**
- * The code as pieces, without whitespace and comments, and the comments and
- * literals that span lines: a line that starts inside one does not read as
- * code on its own.
- */
+/** The code as pieces, without whitespace and comments. */
 const piecesOf = (code: string) => {
   const pieces: Array<Piece> = [];
-  const spans: Array<Range> = [];
   let line = 1;
   let spaced = true;
   for (const { text, kind } of scan(code)) {
     const end = line + text.split("\n").length - 1;
-    if (kind !== undefined && end > line) spans.push({ first: line, last: end });
     if (kind === "comment" || text.trim().length === 0) {
       spaced = true;
     } else if (kind !== undefined || /^[\w$]/.test(text)) {
@@ -75,7 +61,7 @@ const piecesOf = (code: string) => {
     }
     line = end;
   }
-  return { pieces, spans };
+  return { pieces };
 };
 
 /**
@@ -209,6 +195,75 @@ const statementsAround = (
   ];
 };
 
+/** The most lines a section holds, unless one statement with no group to split is longer. */
+const SECTION = 30;
+
+/**
+ * The file in sections, each ending where a statement does: its top-level
+ * statements, such as its imports, constants, and functions, packed in
+ * order into sections of at most `SECTION` lines, a decorator with what it
+ * decorates. A statement longer than that splits into the statements of its
+ * largest group, such as a class's methods or a component's body, the lines
+ * around that group going with the first and last of them. Every line is in
+ * one section: the comments and blank lines above a statement go with it,
+ * and the last section runs to the end.
+ */
+export const sectionsOf = (lines: ReadonlyArray<string>): ReadonlyArray<Range> => {
+  const { pieces } = piecesOf(lines.join("\n"));
+  const closes = closesOf(pieces);
+  const lineOf = (index: number) => pieces[index]?.line ?? 0;
+  /** Statements as ranges of at most `SECTION` lines where they can be split. */
+  const units = (statements: ReadonlyArray<Statement>): ReadonlyArray<Range> =>
+    statements.flatMap((statement): ReadonlyArray<Range> => {
+      if (statement.last - statement.first < SECTION) return [statement];
+      const largest = statement.groups.reduce<readonly [number, number] | undefined>(
+        (best, group) =>
+          best === undefined ||
+          lineOf(group[1]) - lineOf(group[0]) > lineOf(best[1]) - lineOf(best[0])
+            ? group
+            : best,
+        undefined,
+      );
+      const inner =
+        largest === undefined
+          ? []
+          : units(statementsIn(pieces, closes, largest[0] + 1, largest[1]));
+      const [head, tail] = [inner[0], inner.at(-1)];
+      if (head === undefined || tail === undefined || inner.length < 2) return [statement];
+      return [
+        { first: statement.first, last: head.last },
+        ...inner.slice(1, -1),
+        { first: tail.first, last: statement.last },
+      ];
+    });
+  const sections: Array<Range> = [];
+  /** A decorator, such as `@Command({…})`, waiting for the declaration it decorates. */
+  let decorator: Range | undefined;
+  for (const found of units(statementsIn(pieces, closes, 0, pieces.length))) {
+    if ((lines[found.first - 1] ?? "").trimStart().startsWith("@")) {
+      decorator = { first: decorator?.first ?? found.first, last: found.last };
+      continue;
+    }
+    const unit = { first: decorator?.first ?? found.first, last: found.last };
+    decorator = undefined;
+    const previous = sections.at(-1);
+    if (previous !== undefined && unit.last - previous.first < SECTION) {
+      sections[sections.length - 1] = { first: previous.first, last: unit.last };
+    } else {
+      sections.push({ first: unit.first, last: unit.last });
+    }
+  }
+  if (decorator !== undefined) sections.push(decorator);
+  // A file of comments alone, with no statement, is one section.
+  if (sections.length === 0) return lines.length === 0 ? [] : [{ first: 1, last: lines.length }];
+  // Each section starts where the one before it ends, and the last one ends with the file.
+  return sections.flatMap((section, index): ReadonlyArray<Range> => {
+    const first = (sections[index - 1]?.last ?? 0) + 1;
+    const last = index === sections.length - 1 ? lines.length : section.last;
+    return last < first ? [] : [{ first, last }];
+  });
+};
+
 /**
  * The statement that starts on `line`, such as a property, a function, or a
  * call that opens there: the outermost statement around `line` whose first
@@ -218,48 +273,3 @@ export const statementFrom = (lines: ReadonlyArray<string>, line: number): Range
   const { pieces } = piecesOf(lines.join("\n"));
   return statementsAround(pieces, closesOf(pieces), line).find((range) => range.first === line);
 };
-
-/**
- * The excerpt for a finding on `line`: the outermost statement around it
- * with at most `WHOLE` lines, such as the function it is in, and up to
- * `AROUND` lines on either side of `line`. A comment or template literal
- * that spans lines counts as a statement inside the one it is in.
- *
- * Around `line`, the excerpt shows only whole statements, never the end of
- * the one above or the start of the one below, so it cannot start partway
- * through a comment, whose lines do not read as code on their own. What
- * `line` itself is in can show in part: a long function's first line, above
- * the statement of its body. It ends at code, since a comment at the end
- * would be about code the excerpt leaves out.
- */
-export const excerptOf = (lines: ReadonlyArray<string>, line: number): Excerpt => {
-  const { pieces, spans } = piecesOf(lines.join("\n"));
-  const closes = closesOf(pieces);
-  /** What a line is in, outermost first. */
-  const around = (at: number): ReadonlyArray<Range> => [
-    ...statementsAround(pieces, closes, at),
-    ...spans.filter((span) => holds(span, at)),
-  ];
-  const scope = around(line).find((range) => range.last - range.first < WHOLE);
-  const top = Math.max(1, Math.min(scope?.first ?? line, line - AROUND));
-  const bottom = Math.min(lines.length, Math.max(scope?.last ?? line, line + AROUND));
-  /** What a line is in that `line` is not, which an edge shows whole or not at all. */
-  const beside = (at: number) => around(at).filter((range) => !holds(range, line));
-  let first = Math.max(
-    top,
-    ...beside(top)
-      .filter((range) => range.first < top)
-      .map((range) => range.last + 1),
-  );
-  let last = Math.min(
-    bottom,
-    ...beside(bottom)
-      .filter((range) => range.last > bottom)
-      .map((range) => range.first - 1),
-  );
-  const isBlank = (at: number) => (lines[at - 1] ?? "").trim().length === 0;
-  const hasCode = (at: number) => pieces.some((piece) => piece.line <= at && at <= piece.end);
-  while (first < line && isBlank(first)) first += 1;
-  while (last > line && !hasCode(last)) last -= 1;
-  return { start: first, lines: lines.slice(first - 1, last) };
-};

package/src/highlight.ts

@@ -30,6 +30,8 @@ const CLASSES = ["comment", "string", "constant"] as const;
 /** One group per token class, tried in order at each position. A template literal is read apart. */
 const TOKEN = new RegExp(
   [
+    // A URL outside a string is JSX text, as in `<a>https://example.com</a>`, and its `//` no comment.
+    /(?<url>[a-z][\w+.-]*:\/\/[^\s<>{}"'`]*)/,
     /(?<comment>\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$))/,
     /(?<string>"(?:[^"\\\n]|\\.)*"?|'(?:[^'\\\n]|\\.)*'?)/,
     /(?<constant>0[box][\da-f_]+n?|\d[\d_]*(?:\.\d[\d_]*)?(?:e[+-]?\d+)?n?)/,

package/src/init.ts

@@ -12,12 +12,22 @@ export interface InitResult {
 }
 
 export type Install =
-  | { readonly status: "installed"; readonly packageManager: PackageManager }
+  | {
+      readonly status: "installed";
+      /** @drkmttr/adhere, added, or in a shared repo, package.json, installed. */
+      readonly what: string;
+      readonly packageManager: PackageManager;
+    }
   | { readonly status: "listed" }
   | { readonly status: "no-package-json" };
 
 export interface InitOptions {
   readonly force?: boolean;
+  /**
+   * `org/repo`: scaffold a repo whose rules other repos copy with `adhere
+   * install`, rather than one that lints itself.
+   */
+  readonly shared?: string;
 }
 
 // adhere-ignore-file rules/import-written-files -- src/index.ts exports initProject, so a Bun text import here breaks loading the package on Node and in Vitest (checked 2026-09-26), and the compiled executable has no files beside it to read.
@@ -100,18 +110,155 @@ export const handle = (id: string) =>
 \`\`\`
 `;
 
+const sharedReadme = (org: string, repo: string) => `# ${repo}
+
+Shared [adhere](https://github.com/darkmatter/adhere) rules for ${org}'s
+repositories. Each rule is a Markdown file in \`.adhere/\`, and a repo that
+copies it in has Jev judge its files against it when it runs \`adhere lint\`.
+
+## Use these rules
+
+List the rules, then copy them into a repo, all of them or one topic or rule:
+
+\`\`\`sh
+adhere list ${org}/${repo}
+adhere install ${org}/${repo}
+adhere install ${org}/${repo}/style
+adhere install ${org}/${repo}/style/prefer-small-files
+\`\`\`
+
+The copies land in \`.adhere/${org}/${repo}/\` and are that repo's own from then
+on, to edit or to start other rules from. To take a later version of a rule,
+install it again with \`--force\`, which overwrites local edits.
+
+## Add a rule
+
+Add a Markdown file under \`.adhere/<topic>/\`; its path is its id. See
+[Rules as Markdown files](https://github.com/darkmatter/adhere#rules-as-markdown-files)
+and the [rule writing tips](https://github.com/darkmatter/adhere#rule-writing-tips).
+\`adhere validate\` checks each rule's wording and asks Jev whether any two
+contradict. CI runs it on every push to main and every pull request.
+
+## Setup
+
+\`alchemy.run.ts\` creates this repository on GitHub, or adopts it when it
+exists, and sets the \`TYPESAFE_API_KEY\` secret CI's \`adhere validate\` needs.
+Install, which init already did, deploy once, then push:
+
+\`\`\`sh
+npm install
+TYPESAFE_API_KEY=... npx alchemy deploy
+git init && git add -A && git commit -m "Add shared adhere rules"
+git remote add origin git@github.com:${org}/${repo}.git && git push -u origin main
+\`\`\`
+
+Deploying again updates the secret, as after rotating the key.
+`;
+
+const SHARED_WORKFLOW = `name: adhere
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx --yes @drkmttr/adhere validate
+        env:
+          TYPESAFE_API_KEY: \${{ secrets.TYPESAFE_API_KEY }}
+`;
+
+const sharedStack = (org: string, repo: string) => `import * as Alchemy from "alchemy";
+import * as GitHub from "alchemy/GitHub";
+import * as Output from "alchemy/Output";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+
+const owner = "${org}";
+
+export default Alchemy.Stack(
+  "${repo}",
+  { providers: GitHub.providers(), state: Alchemy.localState() },
+  Effect.gen(function* () {
+    const repository = yield* GitHub.Repository("rules", {
+      owner,
+      name: "${repo}",
+      description: "Shared adhere rules",
+      visibility: "private",
+    });
+    // CI's adhere validate asks Jev whether any two rules contradict. Naming
+    // the repository by its output makes alchemy create it before the secret.
+    yield* GitHub.Secret("typesafe-api-key", {
+      owner,
+      repository: Output.map(repository.fullName, (fullName) => fullName.split("/")[1] ?? ""),
+      name: "TYPESAFE_API_KEY",
+      value: yield* Config.Redacted("TYPESAFE_API_KEY"),
+    });
+    return { url: repository.htmlUrl };
+  }).pipe(Effect.orDie),
+);
+`;
+
+/**
+ * alchemy's CLI runs on effect and its Node platform. They are pinned, as is
+ * the platform's own dependency, since a range of prereleases takes the newest:
+ * effect 4.0.0-rc.118 moved modules alchemy 2.0.0-beta.79 imports (checked
+ * 2026-09-28).
+ */
+const sharedPackage = (repo: string) =>
+  `${JSON.stringify(
+    {
+      name: repo,
+      private: true,
+      type: "module",
+      devDependencies: {
+        "@effect/platform-node": "4.0.0-rc.117",
+        alchemy: "2.0.0-beta.79",
+        effect: "4.0.0-rc.117",
+      },
+      overrides: { "@effect/platform-node-shared": "4.0.0-rc.117" },
+    },
+    null,
+    2,
+  )}\n`;
+
+const SHARED_GITIGNORE = `node_modules/
+.alchemy/
+`;
+
 const CONFIG_PATH = CONFIG_FILES[0];
 
 /** The config's own project, which only a config at `.adhere/config.ts` needs. */
 const CONFIG_PROJECT = ".adhere/tsconfig.json";
 
-const files = [
-  [CONFIG_PATH, CONFIG],
-  [CONFIG_PROJECT, TSCONFIG],
+const EXAMPLES = [
   [".adhere/style/prefer-small-files.md", SMALL_FILES],
   [".adhere/style/name-domain-actions.md", NAME_EFFECTS],
 ] as const;
 
+/**
+ * A shared repo has no config: \`adhere install\` copies only rule files, and
+ * \`validate\` reads \`.adhere/\` without one.
+ */
+const filesFor = (shared: string | undefined): ReadonlyArray<readonly [string, string]> => {
+  if (shared === undefined) {
+    return [[CONFIG_PATH, CONFIG], [CONFIG_PROJECT, TSCONFIG], ...EXAMPLES];
+  }
+  const [org = "", repo = ""] = shared.split("/");
+  return [
+    ["README.md", sharedReadme(org, repo)],
+    [".github/workflows/adhere.yaml", SHARED_WORKFLOW],
+    ["alchemy.run.ts", sharedStack(org, repo)],
+    ["package.json", sharedPackage(repo)],
+    [".gitignore", SHARED_GITIGNORE],
+    ...EXAMPLES,
+  ];
+};
+
 const exists = (path: string): Promise<boolean> =>
   access(path).then(
     () => true,
@@ -177,19 +324,27 @@ const addFlags: Record<PackageManager, ReadonlyArray<string>> = {
   npm: [],
 };
 
-/** Adds adhere to devDependencies, so the config's `import type` resolves. */
-const installAdhere = (root: string) =>
+/**
+ * Adds adhere to devDependencies, so the config's `import type` resolves. A
+ * shared repo's package.json, which init writes, lists what it needs already,
+ * so there it installs that instead.
+ */
+const installPackages = (root: string, shared: boolean) =>
   Effect.tryPromise({
     try: async (): Promise<Install> => {
       const manifest = await readFile(join(root, "package.json"), "utf8").catch(() => undefined);
       if (manifest === undefined) return { status: "no-package-json" };
       const { dependencies, devDependencies } = JSON.parse(manifest);
-      if (dependencies?.[PACKAGE] !== undefined || devDependencies?.[PACKAGE] !== undefined) {
+      if (
+        !shared &&
+        (dependencies?.[PACKAGE] !== undefined || devDependencies?.[PACKAGE] !== undefined)
+      ) {
         return { status: "listed" };
       }
       const packageManager = await packageManagerAt(root);
+      const args = shared ? ["install"] : ["add", "-D", PACKAGE, ...addFlags[packageManager]];
       await new Promise<void>((resolve, reject) => {
-        spawn(packageManager, ["add", "-D", PACKAGE, ...addFlags[packageManager]], {
+        spawn(packageManager, args, {
           cwd: root,
           stdio: "inherit",
         })
@@ -198,11 +353,11 @@ const installAdhere = (root: string) =>
             code === 0 ? resolve() : reject(new Error(`${packageManager} exited with ${code}`)),
           );
       });
-      return { status: "installed", packageManager };
+      return { status: "installed", what: shared ? "package.json" : PACKAGE, packageManager };
     },
     catch: (cause) =>
       new Error(
-        `Could not add ${PACKAGE} to package.json: ${cause instanceof Error ? cause.message : String(cause)}`,
+        `Could not install ${shared ? "package.json" : PACKAGE}: ${cause instanceof Error ? cause.message : String(cause)}`,
       ),
   });
 
@@ -213,8 +368,8 @@ 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) {
+    const existing = options.shared === undefined ? yield* otherConfig(root) : undefined;
+    for (const [path, contents] of filesFor(options.shared)) {
       if (path === CONFIG_PATH && existing !== undefined) {
         skipped.push(existing);
         continue;
@@ -228,6 +383,6 @@ export const initProject = (
         skipped.push(relative(root, join(root, path)));
       }
     }
-    const install = yield* installAdhere(root);
+    const install = yield* installPackages(root, options.shared !== undefined);
     return { created, skipped, install };
   });