@drkmttr/adhere 0.21.2 → 0.23.0

package/src/create/wizard.ts

@@ -11,33 +11,34 @@
 import { CONFIG_FILES, DEFAULT_READS } from "#config.ts";
 import { AGENTS, type Agent, installedAgents, run } from "#create/agents.ts";
 import {
-  type Candidate,
-  Candidates,
-  type Reviewed,
   RuleNotCreated,
   Shape,
+  adhereRevisionPrompt,
   asking,
   askingFor,
-  examplesPrompt,
   shapePrompt,
   unfenced,
   writePrompt,
 } from "#create/ask.ts";
+import { reviewedInRepository } from "#create/examples.ts";
+import { createOxlintRule } from "#create/oxlint.ts";
+import { trialAndReview, trialStatus, trialWriteSuffix } from "#create/trial-review.ts";
+import { oxlintRule } from "#oxlint/catalog.ts";
 import {
   decided,
-  excerpt,
   indented,
   intro,
   line,
   look,
   note,
   outro,
-  said,
+  renderMarkdown,
   spinning,
   warn,
 } from "#create/look.ts";
 import { cloned } from "#install.ts";
 import { parseRuleMarkdown } from "#markdown.ts";
+import { isSharedRepo, refreshIndexIfShared, refreshReadme, validateReadme } from "#readme.ts";
 import { importRule } from "#rules.ts";
 import { findConfigFile, loadConfigFile } from "#services/AdhereConfig.ts";
 import { adhereConfigDirectory } from "#services/Credentials.ts";
@@ -112,58 +113,6 @@ const failed = (cause: unknown) =>
 const git = (cwd: string, args: ReadonlyArray<string>) =>
   Effect.tryPromise({ try: () => run("git", args, cwd, ""), catch: failed });
 
-/**
- * Shows the user each excerpt the agent found, read from the file itself with
- * three lines either side, and asks whether it breaks the rule. An excerpt
- * that does not match the repo is left out.
- */
-const review = (agent: Agent, root: string, candidates: ReadonlyArray<Candidate>) =>
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const reviewed: Array<Reviewed> = [];
-    let missing = 0;
-    for (const [index, candidate] of candidates.entries()) {
-      const file = path.resolve(root, candidate.file);
-      const where = path.relative(root, file);
-      const text = where.startsWith("..")
-        ? Option.none()
-        : yield* fs.readFileString(file).pipe(Effect.option);
-      const lines = Option.getOrElse(text, () => "").split("\n");
-      const start = candidate.startLine;
-      if (Option.isNone(text) || start < 1 || start > lines.length) {
-        missing++;
-        continue;
-      }
-      const end = Math.min(Math.max(candidate.endLine, start), start + 14, lines.length);
-      const at = `${where}:${start === end ? start : `${start}-${end}`}`;
-      yield* line("");
-      yield* line(`${at} (${index + 1} of ${candidates.length})`);
-      yield* excerpt(lines, {
-        from: Math.max(1, start - 3),
-        to: Math.min(lines.length, end + 3),
-        start,
-        end,
-      });
-      yield* said(
-        `${agent}: ${candidate.violation ? "breaks it" : "follows it"}. ${candidate.reason}`,
-      );
-      const violation = yield* Prompt.run(
-        Prompt.Confirm({ message: "Is this a violation?", initial: candidate.violation }),
-      );
-      reviewed.push({
-        where: at,
-        code: lines.slice(start - 1, end).join("\n"),
-        violation,
-        agreed: violation === candidate.violation,
-      });
-    }
-    if (missing > 0) {
-      yield* note(`Left out ${missing} excerpt${missing === 1 ? "" : "s"} not found in the repo.`);
-    }
-    return reviewed;
-  });
-
 /**
  * What adhere can say of a draft without running it: for a RULE.md, what
  * `validate` would; for a RULE.ts, whether it parses and has a default export.
@@ -184,11 +133,29 @@ const problemsOf = (text: string, file: string, format: Shape["format"]) =>
         Effect.catch((message) => Effect.succeed([`It does not parse: ${message}`])),
       );
 
+/**
+ * Shows a draft as the user reads it: a RULE.md rendered from Markdown with
+ * its frontmatter and source intact, a RULE.ts as written, either on the rail.
+ * Only the preview is rendered; the draft itself stays raw for the agent, the
+ * trial, and the file.
+ */
+const showDraft = (text: string, format: Shape["format"]) =>
+  Effect.gen(function* () {
+    const shown = format === "markdown" ? yield* renderMarkdown(text) : text;
+    yield* line(`\n${shown}\n`);
+  });
+
+/** A RULE.ts that imported, with its wording strays, or one that did not import. */
+export type LoadedDraft =
+  | { readonly _tag: "Loaded"; readonly warnings: ReadonlyArray<string> }
+  | { readonly _tag: "Unavailable"; readonly problems: ReadonlyArray<string> };
+
 /**
  * What `validate` would say of a RULE.ts the user has approved: imported from
- * a temporary directory, so its code runs.
+ * a temporary directory, so its code runs. A wording stray is a warning about
+ * a rule that still runs; only a failure to import makes it untriallable.
  */
-const loadedProblems = (text: string, shown: string) =>
+export const loadedDraft = (text: string, shown: string) =>
   Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -198,16 +165,45 @@ const loadedProblems = (text: string, shown: string) =>
     );
     yield* fs.writeFileString(file, text);
     return yield* importRule(file).pipe(
-      Effect.map((rule) => strayingOf(rule).map(sentenceOf)),
-      Effect.catchTag("ConfigUnavailable", ({ message }) =>
-        Effect.succeed([message.replaceAll(file, shown)]),
+      Effect.map((rule): LoadedDraft => ({
+        _tag: "Loaded",
+        warnings: strayingOf(rule).map(sentenceOf),
+      })),
+      Effect.catchTag("ConfigUnavailable", ({ message }): Effect.Effect<LoadedDraft> =>
+        Effect.succeed({
+          _tag: "Unavailable",
+          problems: [message.replaceAll(file, shown)],
+        }),
       ),
     );
   });
 
+/**
+ * Whether the trial may import and run the draft: a RULE.md has no code, while
+ * a RULE.ts is imported only after the user approves it.
+ */
+const approveDraft = (text: string, format: Shape["format"], shown: string) =>
+  Effect.gen(function* () {
+    if (format === "markdown") return { _tag: "Approved", draft: text } as const;
+    const run = yield* Prompt.run(
+      Prompt.Confirm({
+        message: "adhere will import this RULE.ts and run its code to trial it. Run it?",
+        initial: true,
+      }),
+    );
+    if (!run) return { _tag: "Declined" } as const;
+    const loaded = yield* loadedDraft(text, shown);
+    if (loaded._tag === "Unavailable") {
+      return { _tag: "Unavailable", problems: loaded.problems } as const;
+    }
+    for (const warning of loaded.warnings) yield* warn(warning);
+    return { _tag: "Approved", draft: text } as const;
+  });
+
 /**
  * The config settings the rule needs that `config` lacks, as they would be
- * written in it. Reads and type awareness are config-wide, not per rule.
+ * written in it. The rule declares its reads, but the config still enables
+ * them and type awareness.
  */
 const settingsFor = (
   shape: Shape,
@@ -249,14 +245,23 @@ export const createRule = Effect.fn("createRule")(
       : yield* Prompt.run(Prompt.String({ message: "What should the rule enforce?" }));
 
     const shape = yield* askingFor(agent, "how to shape it", root, shapePrompt(idea), Shape);
-    if (shape.linter !== null) {
-      const anyway = yield* Prompt.run(
-        Prompt.Confirm({
-          message: `A linter could check this: ${shape.linter}. Write an adhere rule anyway?`,
-          initial: false,
+    const native = shape.linter === null ? undefined : oxlintRule(shape.linter);
+    if (native !== undefined) {
+      return yield* createOxlintRule({ agent, idea, shape, root, shared });
+    }
+    if (shape.mechanical && !shape.typeAware) {
+      const approach = yield* Prompt.run(
+        Prompt.Select({
+          message: "A custom oxlint JS plugin can check this. Which do you want?",
+          choices: [
+            { title: "Write an oxlint plugin", value: "plugin" as const },
+            { title: "Write an adhere rule", value: "adhere" as const },
+          ],
         }),
       );
-      if (!anyway) return yield* outro("Nothing written.");
+      if (approach === "plugin") {
+        return yield* createOxlintRule({ agent, idea, shape, root, shared });
+      }
     }
     const ruleFile = shape.format === "typescript" ? "RULE.ts" : "RULE.md";
     yield* decided(`A ${ruleFile}`, shape.formatReason);
@@ -327,20 +332,7 @@ export const createRule = Effect.fn("createRule")(
           }),
         );
 
-    // Excerpts are optional: an agent that cannot search the repo, such as codex
-    // without its sandbox, leaves the rule's examples to the draft.
-    const found = yield* askingFor(
-      agent,
-      "for code to judge",
-      root,
-      examplesPrompt(idea, id),
-      Candidates,
-    ).pipe(
-      Effect.catch(({ message }) =>
-        warn(`No code from the repo: ${message}`).pipe(Effect.as({ candidates: [] })),
-      ),
-    );
-    const reviewed = yield* review(agent, root, found.candidates);
+    const reviewed = yield* reviewedInRepository(agent, root, idea, id);
 
     const file = path.join(rules, id, ruleFile);
     const branch = `adhere/${id}`;
@@ -360,31 +352,66 @@ export const createRule = Effect.fn("createRule")(
           );
     const problems = yield* problemsOf(text, file, shape.format);
 
-    yield* line(`\n${text}\n`);
+    yield* showDraft(text, shape.format);
     for (const problem of problems) yield* warn(problem);
+    const shown = path.relative(root, file);
+    const outcome = yield* trialAndReview({
+      agent,
+      root,
+      id,
+      draft: text,
+      toDraft: (source) => ({ kind: "adhere", id, format: shape.format, source }),
+      approve: (source) => approveDraft(source, shape.format, shown),
+      revise: (source, evidence) =>
+        Effect.gen(function* () {
+          const revised = unfenced(
+            yield* asking(
+              agent,
+              "to revise the rule",
+              root,
+              adhereRevisionPrompt(idea, id, shape, source, evidence),
+            ),
+          );
+          for (const problem of yield* problemsOf(revised, file, shape.format)) {
+            yield* warn(problem);
+          }
+          return revised;
+        }),
+      show: (source) => showDraft(source, shape.format),
+    });
+    if (outcome._tag === "Cancelled") return yield* outro("Nothing written.");
+    const finalText = outcome.draft;
+    const finalProblems = yield* problemsOf(finalText, file, shape.format);
+    if (finalText !== text) {
+      yield* showDraft(finalText, shape.format);
+      for (const problem of finalProblems) yield* warn(problem);
+    }
     const write = yield* Prompt.run(
       Prompt.Confirm({
         message:
-          scope === "project"
+          (scope === "project"
             ? `Write ${path.relative(root, file)}?`
-            : `Push it to ${shared} on the branch ${branch}?`,
-        initial: problems.length === 0,
+            : `Push it to ${shared} on the branch ${branch}?`) + trialWriteSuffix(outcome),
+        initial: finalProblems.length === 0 && outcome._tag === "Accepted",
       }),
     );
     if (!write) return yield* outro("Nothing written.");
     // A RULE.ts is only imported, and its code run, once the user has read it.
     if (shape.format === "typescript") {
-      const loaded = yield* loadedProblems(text, path.relative(root, file));
-      for (const problem of loaded) yield* warn(problem);
+      const loaded = yield* loadedDraft(finalText, path.relative(root, file));
+      const problems = loaded._tag === "Loaded" ? loaded.warnings : loaded.problems;
+      for (const problem of problems) yield* warn(problem);
       if (
-        loaded.length > 0 &&
+        problems.length > 0 &&
         !(yield* Prompt.run(Prompt.Confirm({ message: "Write it anyway?", initial: false })))
       ) {
         return yield* outro("Nothing written.");
       }
     }
+    const sharedHere = scope === "project" ? yield* isSharedRepo(root) : false;
+    if (sharedHere) yield* validateReadme(root);
     yield* fs.makeDirectory(path.dirname(file), { recursive: true });
-    yield* fs.writeFileString(file, `${text}\n`);
+    yield* fs.writeFileString(file, `${finalText}\n`);
 
     if (scope === "project") {
       const configFile = yield* findConfigFile(root).pipe(Effect.orElseSucceed(() => undefined));
@@ -400,8 +427,9 @@ export const createRule = Effect.fn("createRule")(
           `${id} needs ${needed.join(" and ")} in ${configFile ?? CONFIG_FILES[0]}${shape.typeAware ? " (or lint --type-aware)" : ""}. Until then, lint judges it without that context.`,
         );
       }
+      const refreshed = sharedHere ? yield* refreshReadme(root) : undefined;
       return yield* outro(
-        `Wrote ${path.relative(root, file)}.\nRun adhere validate to check it against your other rules.`,
+        `Wrote ${path.relative(root, file)}.\n${trialStatus(outcome)}\n${refreshed === undefined ? "" : `${refreshed.message}\n`}Run adhere validate to check it against your other rules.`,
       );
     }
     const needed = settingsFor(shape, {});
@@ -409,8 +437,13 @@ export const createRule = Effect.fn("createRule")(
       needed.length === 0
         ? []
         : [`Repos that install it need ${needed.join(" and ")} in their adhere config.`];
+    // A shared repo's index joins the rule in one commit and one pull request;
+    // a legacy rules-only repo has no index to refresh.
+    const indexed = yield* refreshIndexIfShared(repo);
     yield* git(repo, ["switch", "--quiet", "--create", branch]);
-    yield* git(repo, ["add", "--", path.relative(repo, file)]);
+    const staged = [path.relative(repo, file)];
+    if (indexed) staged.push("README.md");
+    yield* git(repo, ["add", "--", ...staged]);
     yield* git(repo, [
       "commit",
       "--quiet",
@@ -422,6 +455,7 @@ export const createRule = Effect.fn("createRule")(
     yield* outro(
       [
         `Pushed ${branch} to ${shared}.`,
+        trialStatus(outcome),
         ...needs,
         `Open the pull request: https://github.com/${shared}/compare/${branch}?expand=1`,
       ].join("\n"),

package/src/init.ts

@@ -2,6 +2,17 @@ import { spawn } from "node:child_process";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { CONFIG_FILES } from "#config.ts";
+import {
+  SHARED_LINT_DIRECTORY,
+  SHARED_LINT_INDEX,
+  SHARED_LINT_RULES,
+  SHARED_LINT_RULES_JSON,
+  SHARED_LINT_TYPES,
+  SHARED_LINT_TYPES_SOURCE,
+  sharedPackageJson,
+  sharedPackageName,
+} from "#oxlint/shared.ts";
+import { README_END, README_START, refreshReadme } from "#readme.ts";
 import { Effect, Schema } from "effect";
 
 export interface InitResult {
@@ -87,6 +98,16 @@ export const renderInvoice = (invoice: Invoice) => Html.table(invoice.lines);
 \`\`\`
 `;
 
+const INSTRUCTIONS = `# Working with adhere
+
+- Run \`adhere lint\` before you commit, and fix what it reports.
+- A rule belongs in \`.adhere/rules/\`: one sentence saying what code must be,
+  with code that shows it.
+- Run \`adhere validate\` after changing a rule. When a finding is wrong for
+  this code alone, say why in a suppression comment instead of weakening the
+  rule.
+`;
+
 const NAME_EFFECTS = `---
 description: A function must be named after the domain action it performs, never after a generic verb like handle.
 threshold: 0.8
@@ -116,35 +137,135 @@ 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 directory in \`.adhere/rules/\` that holds a
-\`RULE.md\`, or a \`RULE.ts\`, and a repo that copies it in has Jev judge its
-files against it when it runs \`adhere lint\`.
+Shared [adhere](https://github.com/darkmatter/adhere) rules and lint settings
+for ${org}'s repositories. \`.adhere/rules/\` holds the rules Jev judges files
+against, \`.adhere/instructions/\` holds instruction files for \`AGENTS.md\`, and
+\`oxlint/\` is a plain ESM Oxlint config package for rules a linter can check
+exactly.
 
 ## Use these rules
 
-List the rules, then copy them into a repo, all of them or one topic or rule:
+List the rules, then copy them into a repo: every one, one topic, or one rule.
 
 \`\`\`sh
 adhere list ${org}/${repo}
-adhere install ${org}/${repo}
+adhere install ${org}/${repo}                        # choose at a terminal
+adhere install ${org}/${repo} --all                  # everything, without a prompt
 adhere install ${org}/${repo}/style
 adhere install ${org}/${repo}/style/prefer-small-files
 \`\`\`
 
-The copies land in \`.adhere/rules/${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.
+At a terminal, a bare install lists what it can copy: instruction files
+first, then rules grouped by topic. \`--all\` copies every instruction file and
+rule the source names without asking and needs no terminal. Without either, a
+run without a terminal fails and names the matches. A topic is the same list
+filtered to that topic, and an exact rule's path copies just that rule;
+neither copies instructions.
+
+Rules land in \`.adhere/rules/${org}/${repo}/\` and instructions in
+\`.adhere/instructions/${org}/${repo}/\`, and are that repo's own from then on,
+to edit or to start other rules from. To take a later version, install again
+with \`--force\`, which overwrites local edits; deselecting a file never
+deletes it.
+
+## Use its lint settings
+
+The lint package is not published. Pin this repo as a git dependency, at a
+tag: tags are repo-wide, covering the rules, the instructions, and \`oxlint/\`
+together.
+
+\`\`\`sh
+bun add -D "github:${org}/${repo}#v1.0.0"
+\`\`\`
+
+Then spread it into Vite+'s config, or plain Oxlint's:
+
+\`\`\`ts
+import sharedLint from "${sharedPackageName(org, repo)}/oxlint";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  lint: {
+    ...sharedLint,
+    jsPlugins: [...sharedLint.jsPlugins, "./.adhere/oxlint/local.mjs"],
+    rules: {
+      ...sharedLint.rules,
+      "local/my-rule": "error",
+    },
+  },
+});
+\`\`\`
+
+\`\`\`ts
+// oxlint.config.ts, with plain Oxlint: oxlint -c oxlint.config.ts
+import sharedLint from "${sharedPackageName(org, repo)}/oxlint";
+
+export default { ...sharedLint };
+\`\`\`
+
+\`oxlint/index.js\` reads \`oxlint/rules.json\` and resolves the shared package's
+plugin paths, so spreading its export works from any directory. Paths you add
+stay relative to your config. Your project's own JS plugins live in
+\`.adhere/oxlint/\` as \`.mjs\` files.
+
+## Rules and lint settings
+
+The guide below is generated from \`.adhere/rules/\` and \`oxlint/rules.json\` by
+\`adhere rules readme\`. Run it after adding, renaming, or deleting a rule, or
+after changing a lint setting; it replaces only the block between its markers.
+Rules are grouped by topic, and each entry opens its own statement, examples,
+and explanation, with a link to the file it came from.
+
+${README_START}
+${README_END}
 
 ## Add a rule
 
 Add a directory under \`.adhere/rules/<topic>/\` with the rule in a \`RULE.md\`;
 its path is the rule's 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).
+[Rules as Markdown files](https://dm.sh/adhere/rule-format/#rules-as-markdown-files)
+and the [rule writing tips](https://dm.sh/adhere/writing-good-rules/#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.
 
+## Add a lint setting or plugin
+
+\`oxlint/rules.json\` starts \`{}\` and takes \`rules\`, \`jsPlugins\`, \`plugins\`, and
+\`options\`. \`options\` is Oxlint's own options object; Vite+ uses the same
+\`lint.options\` shape, and type-aware rules need \`oxlint-tsgolint\`, which Vite+
+includes. Turn on a built-in rule by naming it:
+
+\`\`\`json
+{ "rules": { "typescript/no-explicit-any": "error" } }
+\`\`\`
+
+A rule from a built-in plugin that Oxlint leaves off by default (\`react\`,
+\`import\`, \`jsdoc\`, \`jest\`, \`vitest\`, \`jsx-a11y\`, \`nextjs\`, \`react-perf\`,
+\`promise\`, \`node\`, \`vue\`) also needs that plugin in \`plugins\`. The list
+replaces Oxlint's default set (\`eslint\`, \`typescript\`, \`unicorn\`, \`oxc\`), so
+name every plugin you still want:
+
+\`\`\`json
+{
+  "plugins": ["eslint", "typescript", "unicorn", "oxc", "react"],
+  "rules": { "react/jsx-no-target-blank": "error" }
+}
+\`\`\`
+
+A custom plugin is a plain ESM file in \`oxlint/plugins/\`; register it by a path
+relative to \`oxlint/\`, and enable one of its rules by the plugin's name:
+
+\`\`\`json
+{
+  "jsPlugins": ["./plugins/${repo}.js"],
+  "rules": { "${repo}/no-foo": "error" }
+}
+\`\`\`
+
+Keep the keys you are not changing. A project writes its own \`.mjs\` plugins to
+\`.adhere/oxlint/\` and registers them in its \`vite.config.ts\` or
+\`oxlint.config.ts\` instead; see the lint settings above.
+
 ## Setup
 
 \`alchemy.run.ts\` creates this repository on GitHub, or adopts it when it
@@ -159,6 +280,17 @@ git remote add origin git@github.com:${org}/${repo}.git && git push -u origin ma
 \`\`\`
 
 Deploying again updates the secret, as after rotating the key.
+
+## Tag a release
+
+Tag the whole repo after committing rules, instructions, or lint changes. One
+tag covers all of them, and consumers pin that tag; there are no per-rule
+tags.
+
+\`\`\`sh
+git tag v1.0.0
+git push origin v1.0.0
+\`\`\`
 `;
 
 const SHARED_WORKFLOW = `name: adhere
@@ -214,29 +346,6 @@ export default Alchemy.Stack(
 );
 `;
 
-/**
- * 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/
 `;
@@ -246,30 +355,38 @@ const CONFIG_PATH = CONFIG_FILES[0];
 /** The project of the config at `.adhere/config.ts`, and of the rules written in TypeScript beside it. */
 const CONFIG_PROJECT = ".adhere/tsconfig.json";
 
-const EXAMPLES = [
+const RULE_EXAMPLES = [
   [".adhere/rules/style/prefer-small-files/RULE.md", SMALL_FILES],
   [".adhere/rules/style/name-domain-actions/RULE.md", NAME_EFFECTS],
 ] as const;
 
+const SHARED_EXAMPLES = [
+  [".adhere/instructions/00-workflow.md", INSTRUCTIONS],
+  ...RULE_EXAMPLES,
+] as const;
+
 /**
- * A shared repo has no config: \`adhere install\` copies only rules, and
- * \`validate\` reads \`.adhere/rules/\` without one.
+ * A shared repo has no config: \`adhere install\` copies its rules and
+ * instructions, and \`validate\` reads \`.adhere/rules/\` without one.
  */
 const filesFor = (
   shared: string | undefined,
   visibility: Visibility,
 ): ReadonlyArray<readonly [string, string]> => {
   if (shared === undefined) {
-    return [[CONFIG_PATH, CONFIG], [CONFIG_PROJECT, TSCONFIG], ...EXAMPLES];
+    return [[CONFIG_PATH, CONFIG], [CONFIG_PROJECT, TSCONFIG], ...RULE_EXAMPLES];
   }
   const [org = "", repo = ""] = shared.split("/");
   return [
     ["README.md", sharedReadme(org, repo)],
     [".github/workflows/adhere.yaml", SHARED_WORKFLOW],
     ["alchemy.run.ts", sharedStack(org, repo, visibility)],
-    ["package.json", sharedPackage(repo)],
+    ["package.json", sharedPackageJson(org, repo)],
+    [`${SHARED_LINT_DIRECTORY}/index.js`, SHARED_LINT_INDEX],
+    [SHARED_LINT_TYPES, SHARED_LINT_TYPES_SOURCE],
+    [SHARED_LINT_RULES, SHARED_LINT_RULES_JSON],
     [".gitignore", SHARED_GITIGNORE],
-    ...EXAMPLES,
+    ...SHARED_EXAMPLES,
   ];
 };
 
@@ -406,6 +523,15 @@ export const initProject = (
       }
       // A config at another path is in the project's own tsconfig, or not ours to place.
       if (path === CONFIG_PROJECT && existing !== undefined) continue;
+      // A shared README holds the author's prose; refresh its managed block instead.
+      if (
+        options.shared !== undefined &&
+        path === "README.md" &&
+        (yield* Effect.promise(() => exists(join(root, path))))
+      ) {
+        skipped.push(relative(root, join(root, path)));
+        continue;
+      }
       const status = yield* writeScaffoldFile(root, path, contents, options);
       if (status === "created") {
         created.push(relative(root, join(root, path)));
@@ -413,6 +539,9 @@ export const initProject = (
         skipped.push(relative(root, join(root, path)));
       }
     }
+    if (options.shared !== undefined) {
+      yield* refreshReadme(root).pipe(Effect.mapError((cause) => new Error(cause.message)));
+    }
     const install = yield* installPackages(root, options.shared !== undefined);
     return { created, skipped, install };
   });