@drkmttr/adhere 0.21.2 → 0.24.0

package/src/create/ask.ts

@@ -5,15 +5,44 @@
  */
 import { type Agent, askAgent } from "#create/agents.ts";
 import { spinning } from "#create/look.ts";
-import { Effect, Schema } from "effect";
+import { type OxlintCatalog, oxlintCatalog, oxlintRuleIds } from "#oxlint/catalog.ts";
+import { Effect, Schema, SchemaGetter } from "effect";
 import skill from "../../skills/adhere/SKILL.md" with { type: "text" };
 
 export class RuleNotCreated extends Schema.TaggedError<RuleNotCreated>()("RuleNotCreated", {
   message: Schema.String,
 }) {}
 
+const KNOWN_LINTERS = new Set(oxlintRuleIds);
+
+/**
+ * What a rule's options look like on the wire: one plain JSON string, parsed
+ * once here. Not `Schema.fromJsonString`, which marks it with a
+ * `contentMediaType` that strict structured outputs reject.
+ */
+const OptionsFromJson = Schema.String.pipe(
+  Schema.decodeTo(Schema.Array(Schema.Json), {
+    decode: SchemaGetter.parseJson() as SchemaGetter.Getter<ReadonlyArray<Schema.Json>, string>,
+    encode: SchemaGetter.stringifyJson(),
+  }),
+);
+
+/**
+ * A native rule id, a plain string on the wire: the catalog has more ids than
+ * a provider's largest enum takes, so the catalog check runs here instead.
+ */
+const Linter = Schema.String.check(
+  Schema.makeFilter((id) =>
+    KNOWN_LINTERS.has(id) ? undefined : "not an oxlint rule in adhere's catalog",
+  ),
+);
+
+/** The agent's answer: `linter` and its options are compact on the wire, a decoded pair here. */
 export const Shape = Schema.Struct({
-  linter: Schema.NullOr(Schema.String),
+  linter: Schema.NullOr(Linter),
+  linterOptions: OptionsFromJson,
+  mechanical: Schema.Boolean,
+  mechanicalReason: Schema.String,
   scope: Schema.Literals(["project", "org"]),
   scopeReason: Schema.String,
   format: Schema.Literals(["markdown", "typescript"]),
@@ -35,6 +64,41 @@ const Candidate = Schema.Struct({
 export type Candidate = typeof Candidate.Type;
 export const Candidates = Schema.Struct({ candidates: Schema.Array(Candidate) });
 
+/**
+ * A diagnostic location on the wire: strict structured outputs require every
+ * property, so agents send `null` when a location does not matter. Internally
+ * `null` decodes to `undefined`, which `JSON.stringify` then omits.
+ */
+const Location = Schema.NullOr(Schema.Int).pipe(
+  Schema.decodeTo(Schema.UndefinedOr(Schema.Int), {
+    decode: SchemaGetter.transform((value: number | null) => value ?? undefined),
+    encode: SchemaGetter.transform((value: number | undefined) => value ?? null),
+  }),
+);
+
+/** One diagnostic an oxlint plugin must report for an invalid example. */
+const PluginError = Schema.Struct({
+  message: Schema.String,
+  line: Location,
+  column: Location,
+});
+
+/** An invalid example for an oxlint plugin: code and the diagnostics it must produce. */
+const PluginInvalid = Schema.Struct({
+  code: Schema.String,
+  errors: Schema.Array(PluginError),
+});
+
+/** An agent's oxlint JS plugin rule, and the examples that show it works. */
+export const PluginDraft = Schema.Struct({
+  plugin: Schema.String,
+  pluginName: Schema.String,
+  ruleName: Schema.String,
+  valid: Schema.Array(Schema.String),
+  invalid: Schema.Array(PluginInvalid),
+});
+export type PluginDraft = typeof PluginDraft.Type;
+
 /** Code from the repo the user has judged: where it is, as the file holds it, and whether it breaks the rule. */
 export interface Reviewed {
   readonly where: string;
@@ -42,16 +106,22 @@ export interface Reviewed {
   readonly violation: boolean;
   /** Whether the user's call matched the agent's. */
   readonly agreed: boolean;
+  /** What the user added to the call, when they did. */
+  readonly note?: string;
 }
 
 export const shapePrompt = (
   idea: string,
+  catalog: OxlintCatalog = oxlintCatalog,
 ) => `You are helping write a rule for adhere, a linter for conventions a normal linter cannot check: a model, Jev, judges each source file against each rule. A rule lives in .adhere/rules/<topic>/<name>/, either in this repository, for its own code, or in the organization's shared rules repository, which every repository installs from.
 
 The user wants a rule for: ${idea}
 
 Look at this repository as much as you need, then answer:
-- linter: an existing linter rule (ESLint, oxlint, TypeScript, or the like) that already checks this, by name, or null.
+- linter: a string holding the id of one native oxlint rule listed below that already checks exactly this, or null. Do not name a rule that is not listed.
+- linterOptions: a string holding that rule's own settings as a JSON array, exactly as a config writes them after the severity; for example the string '[{"paths": [{"name": "lodash"}]}]' for no-restricted-imports banning lodash, or '[{"max": 200}]' for max-lines. Use '[]' only when the rule's default settings already enforce this idea; a rule that does nothing until configured (no-restricted-imports, no-restricted-globals, no-restricted-properties, no-restricted-exports, id-length, max-lines, max-params, no-magic-numbers, unicorn/filename-case, typescript/no-restricted-types) always needs its settings here. When linter is null, use '[]'.
+- mechanical: true when a small custom oxlint JS plugin that sees only the syntax tree and its scopes could decide this; false when it needs TypeScript types, the text of other files, a different parser, or anything else oxlint's JS plugins cannot see. When typeAware is true, mechanical must be false.
+- mechanicalReason: one sentence saying why.
 - scope: "project" when the rule is about this repository's own code, "org" when it would hold in any of the organization's repositories.
 - scopeReason: one sentence saying why.
 - format: "markdown" for a RULE.md, the rule's text and examples; nearly every rule is one. "typescript" for a RULE.ts, only when judging a file needs something neither the file nor the shared context below shows, such as a schema or a list another file holds: its appendState hook reads it and adds it to what Jev reads for that rule.
@@ -59,7 +129,11 @@ Look at this repository as much as you need, then answer:
 - typeAware: true when judging needs the compiler's view of the file: the types of the names it uses, or the declarations of what it uses from other files. It is slower and costs more, so false unless the file cannot show it.
 - reads: the shared context it needs: "workspacePackages", the workspace packages the file imports and their directories, and "dependents", what depends on the file. Empty when the code is enough.
 - contextReason: one sentence saying why typeAware and reads are as you set them.
-- names: three ids for the rule, each "topic/rule-name" in lowercase kebab case. Reuse a topic from .adhere/rules/ where one fits.`;
+- names: three ids for the rule, each "topic/rule-name" in lowercase kebab case. Reuse a topic from .adhere/rules/ where one fits.
+
+The catalog below is bundled with adhere and was generated from oxlint ${catalog.version}; the oxlint installed in this repository may be a different version, so a listed rule can be absent there and an installed native rule can be missing from this list. Its native rules follow, one per line as "id — what it checks". Use these ids exactly; a rule not listed here is not one adhere treats as native.
+
+${catalog.rules.map((rule) => `- ${rule.id} — ${rule.summary} (${rule.category}${rule.typeAware ? ", type-aware" : ""})`).join("\n")}`;
 
 export const examplesPrompt = (
   idea: string,
@@ -75,16 +149,33 @@ const contextOf = (shape: Shape) =>
     ...(shape.typeAware ? ["`symbols`", "`references`"] : []),
   ].join(", ");
 
+const readsInstruction = (shape: Shape) => {
+  const reads = [...shape.reads, ...(shape.typeAware ? ["symbols", "references"] : [])];
+  if (reads.length === 0) return "Declare no `reads`: the code alone is enough.";
+  return `Declare the context Jev needs beside the code as \`reads: [${reads.map((read) => `"${read}"`).join(", ")}]\` ${shape.format === "typescript" ? "in `defineRule({...})`" : "in its front matter"}. A rule's \`reads\` is a declaration, not an enablement: the project's config still decides what Jev reads, and lint warns that the rule may be less accurate until a declared read is enabled.`;
+};
+
+/**
+ * What a rule may do to narrow the files it judges at all: a mechanical
+ * filter, taught when a rule is written or revised, never to an oxlint rule.
+ */
+const filtersInstruction = (shape: Shape) =>
+  `A rule may also narrow the files it judges before Jev sees them, with optional \`include\` and \`exclude\` objects. Each holds \`paths\`, globs relative to the repository root with forward slashes, matched as \`--filter\` matches them, and \`content\`, JavaScript regular expression sources without / delimiters or flags, tested against each file's original text, comments included. Any entry in a list suffices; \`include\` applies only when every list it sets matches, while a match in either \`exclude\` list drops the file. An absent object or an empty list restricts nothing. A filter is silent: a file it drops is never judged, so a wrong one is a false negative. Use \`paths\` for where the rule applies and \`content\` for what a file says; a filter is not a substitute for \`appliesTo\` or \`excludeIf\`, which ask Jev about the code. \`content\` can match a named package's import specifier, such as from "effect", or a directive, but a regular expression cannot resolve aliases or re-exports, know whether a name is a type or a value, or reliably tell code from comments and other strings; use \`paths\`, \`appliesTo\`, or a TypeScript rule for that. Because \`content\` entries are strings, escape a regex's backslashes: a regex ^\\s*import is written "^\\\\s*import" in both front matter JSON and a RULE.ts string. ${
+    shape.format === "typescript"
+      ? 'Set them in defineRule({...}) as object literals, such as include: { paths: ["src/**"] }.'
+      : 'Set them in the front matter as one-line JSON objects, such as include: {"paths": ["src/**"]}.'
+  }`;
+
 const typescriptFormat = (shape: Shape) =>
-  `Write it as a RULE.ts, because ${shape.formatReason} It imports defineRule from "@drkmttr/adhere" and default-exports defineRule({ description, details, must, never, appendState }). appendState(state, file, Bun) runs before each request for the rule: file is { path, contents }, its path absolute, and Bun is Bun's API, as in Bun.file(path).text() or new Bun.Glob(pattern). What it returns is spread over the request's state; name each key it adds in the description, in backticks. Helpers go in the same file.`;
+  `Write it as a RULE.ts, because ${shape.formatReason} It imports defineRule from "@drkmttr/adhere" and default-exports defineRule({ description, details, must, never, reads, appendState }). appendState(state, file, Bun) runs before each request for the rule: file is { path, contents }, its path absolute, and Bun is Bun's API, as in Bun.file(path).text() or new Bun.Glob(pattern). What it returns is spread over the request's state; name each key it adds in the description, in backticks. Helpers go in the same file.`;
 
 const reviewedOf = (reviewed: ReadonlyArray<Reviewed>) =>
   reviewed.length === 0
     ? "No code from the repository was judged: write short examples of your own."
     : `The user judged this code from the repository. Base the rule's examples on what shows it best; you need not use all of it. Where the user overruled your first call, word the rule so the difference is clear.\n\n${reviewed
         .map(
-          ({ where, code, violation, agreed }) =>
-            `${violation ? "Breaks the rule" : "Does not break the rule"}, ${where}${agreed ? "" : " (overruled)"}\n\`\`\`\n${code}\n\`\`\``,
+          ({ where, code, violation, agreed, note }) =>
+            `${violation ? "Breaks the rule" : "Does not break the rule"}, ${where}${agreed ? "" : " (overruled)"}${note === undefined ? "" : `\nThe user's note: ${note}`}\n\`\`\`\n${code}\n\`\`\``,
         )
         .join("\n\n")}`;
 
@@ -102,12 +193,167 @@ Using the reference above, write the rule file for this adhere rule.
 Rule id: ${id}
 What it enforces: ${idea}
 What Jev reads beside the rule: ${contextOf(shape)}
+${readsInstruction(shape)}
+${filtersInstruction(shape)}
+Leave them out unless the idea itself names a kind of file, such as API routes or React components; the trial will settle whether they are needed.
 ${shape.format === "typescript" ? typescriptFormat(shape) : "Write it as a RULE.md."}
 
 ${reviewedOf(reviewed)}
 
 Reply with only the file's contents, starting with its ${shape.format === "typescript" ? "imports" : "front matter"}.`;
 
+/**
+ * Asks for an oxlint JS plugin rule. The reply is a self-contained ESLint v9
+ * plain-ESM plugin: oxlint loads it as written, so no TypeScript, imports, or
+ * build-tool helpers.
+ */
+export const pluginPrompt = (
+  idea: string,
+  id: string,
+  reviewed: ReadonlyArray<Reviewed>,
+) => `Write one rule for oxlint as a JS plugin. The rule is called ${id}; it enforces: ${idea}
+
+Oxlint's JS plugin API is ESLint v9's. Write a plain ESM module:
+- No TypeScript, no imports, no Vite+ or build-tool helpers, no dependencies: oxlint loads the file as it is.
+- Default-export { meta: { name: "<pluginName>" }, rules: { "<ruleName>": rule } }.
+- The rule is { meta: { schema: [], messages: {...} }, create(context) { return { SomeNode(node) { ... } }; } }.
+- Report with context.report({ message: "a literal message", node }) so the expected diagnostic is exact. Do not use messageId.
+- Judge only the syntax tree and scopes. Oxlint JS plugins cannot see TypeScript types, other files' contents, or another parser's AST; do not reach for them.
+- pluginName and ruleName are lowercase kebab case. pluginName must not be one oxlint has natively, such as eslint, typescript, react, import, jsdoc, jest, vitest, unicorn, jsx-a11y, nextjs, node, promise, vue, oxc, or react-perf.
+- Give at least two valid snippets that must report nothing, and at least two invalid snippets. Each invalid snippet carries every diagnostic it must produce: message exactly as context.report writes it; line (1-based) and column (0-based) are always present: use null when a diagnostic's position does not matter.
+
+${reviewedOf(reviewed)}
+
+Answer with JSON: plugin (the module's whole source), pluginName, ruleName, valid (code strings), invalid (objects with code and errors, each { message, line, column }, with line and column null when unspecified).`;
+
+/** What to send back to the agent once its plugin or examples fail oxlint's RuleTester. */
+export const pluginFixPrompt = (
+  prompt: string,
+  draft: PluginDraft,
+  problems: ReadonlyArray<string>,
+) => `${prompt}
+
+Your last answer failed its own tests:
+${problems.map((problem) => `- ${problem}`).join("\n")}
+
+The plugin was:
+
+\`\`\`js
+${draft.plugin}
+\`\`\`
+
+The examples were:
+${draft.valid.map((code, index) => `Valid ${index + 1}:\n\`\`\`\n${code}\n\`\`\``).join("\n")}
+${draft.invalid
+  .map(
+    (example, index) =>
+      `Invalid ${index + 1}:\n\`\`\`\n${example.code}\n\`\`\`\nExpected: ${JSON.stringify(example.errors.map((error) => ({ message: error.message, line: error.line ?? null, column: error.column ?? null })))}`,
+  )
+  .join("\n")}
+
+Fix the rule or the examples so every valid example reports nothing and every invalid example reports exactly the diagnostics it expects. Reply with only the corrected JSON.`;
+
+/** The agent's revised native settings, as the wire holds them: a JSON array in a string. */
+export const NativeRevision = Schema.Struct({ options: OptionsFromJson });
+export type NativeRevision = typeof NativeRevision.Type;
+
+/**
+ * What the trial found, as the agent reads it: the saved report's path, the
+ * files it judged, and what the user made of each finding.
+ */
+export const inspectionPrompt = (report: string, id: string) =>
+  `adhere trialled the rule ${id} on real files without installing it. The full report is at ${report}. Read it, and read the source files it names, then answer in plain text:
+- Whether the rule catches what it should and what it should not, citing the report's findings.
+- Which findings look like false positives or false negatives, and why.
+- Concrete changes to the rule's wording or examples, if any.
+Do not edit files. Keep it short.`;
+
+/**
+ * The first trial of an adhere rule asks the authoring agent, explicitly,
+ * whether the rule should narrow which files it judges. A filter is a silent
+ * false negative, so the agent names exact entries or says why none fit.
+ */
+export const filterAdvicePrompt = (report: string, id: string) =>
+  `adhere trialled the adhere rule ${id} on real files without installing it. The full report is at ${report}, and it holds the rule's source. Read the report, the rule, and the files it names, then answer in plain text:
+- Whether the rule should carry \`include\` or \`exclude\` filters at all.
+- If it should, the exact entries, as the rule's file writes them: in a RULE.md's front matter, one-line JSON objects such as include: {"paths": ["src/**"]}; in a RULE.ts, object literals such as include: { paths: ["src/**"] }. Say which list each entry belongs to and what it leaves out or keeps.
+- If it should not, one sentence saying why the rule is better judging every file Jev reads.
+
+Filters are mechanical and silent: a file one leaves out is never judged, so a wrong filter hides real violations. \`paths\` are repository-root-relative globs with forward slashes, matched as \`--filter\` matches them. \`content\` entries are JavaScript regex source strings without / delimiters or flags, tested against original text including comments. Content filters may match a named package's import specifier, for example from "effect". They cannot resolve aliases or re-exports, and matching text in comments or strings does not prove the file imports the package. Escape regex backslashes in JSON and TypeScript strings: the regex ^\\s*import is written "^\\\\s*import". Within each list, any entry may match; all nonempty inclusion lists must match, and a match in either exclusion list vetoes the file. Empty lists impose no restriction. Recommend a filter only when the evidence supports that boundary.
+
+Do not suggest filters for an oxlint rule: those have no such fields. Do not edit files. Keep it short.`;
+
+/** Asks for the adhere rule again, with what the trial found and what the user made of it. */
+export const adhereRevisionPrompt = (
+  idea: string,
+  id: string,
+  shape: Shape,
+  draft: string,
+  evidence: string,
+) => `${skill}
+
+---
+
+Revise the adhere rule ${id}. It enforces: ${idea}
+What Jev reads beside the rule: ${contextOf(shape)}
+${readsInstruction(shape)}
+${filtersInstruction(shape)}
+Apply, change, or remove \`include\` and \`exclude\` as the trial, the recommendation, and the user's verdicts support; keep a filter only while the evidence supports it.
+${shape.format === "typescript" ? typescriptFormat(shape) : "Write it as a RULE.md."}
+
+A trial judged real files against the current rule. What it found, and what the user made of it:
+
+${evidence}
+
+The current file:
+
+${draft}
+
+Keep what the evidence supports and change what it contradicts, including its filter recommendation. Reply with only the corrected file, starting with its ${shape.format === "typescript" ? "imports" : "front matter"}.`;
+
+/** Asks for the oxlint plugin again, with what the trial found and what the user made of it. */
+export const pluginRevisionPrompt = (
+  idea: string,
+  id: string,
+  draft: PluginDraft,
+  evidence: string,
+) => `Revise the oxlint JS plugin rule ${id}; it enforces: ${idea}
+
+A trial ran the current plugin on real files. What it found, and what the user made of it:
+
+${evidence}
+
+The current plugin:
+
+\`\`\`js
+${draft.plugin}
+\`\`\`
+
+Its examples were:
+${draft.valid.map((code, index) => `Valid ${index + 1}:\n\`\`\`\n${code}\n\`\`\``).join("\n")}
+${draft.invalid
+  .map(
+    (example, index) =>
+      `Invalid ${index + 1}:\n\`\`\`\n${example.code}\n\`\`\`\nExpected: ${JSON.stringify(example.errors.map((error) => ({ message: error.message, line: error.line ?? null, column: error.column ?? null })))}`,
+  )
+  .join("\n")}
+
+Keep the API rules: plain ESM, no imports, default-export { meta, rules }, and report with context.report({ message, node }). Reply with only JSON: plugin, pluginName, ruleName, valid, invalid, as before.`;
+
+/** Asks for the native rule's settings again, with what the trial found and what the user made of it. */
+export const nativeRevisionPrompt = (
+  idea: string,
+  id: string,
+  options: ReadonlyArray<unknown>,
+  evidence: string,
+) => `Revise the settings for the oxlint rule ${id}; it should enforce: ${idea}
+
+A trial ran it on real files with the settings ${JSON.stringify(options)}. What it found, and what the user made of it:
+
+${evidence}
+
+Answer with JSON: options, a string holding the rule's settings as a JSON array, exactly as a config writes them after the severity. Use "[]" only when the rule's default settings enforce the idea.`;
+
 /** An agent's reply as the file it holds, without the fence it may wrap it in. */
 export const unfenced = (text: string) =>
   /^\s*```[a-z]*\n([\s\S]*?)\n```\s*$/.exec(text)?.[1] ?? text.trim();
@@ -122,12 +368,12 @@ export const asking = (agent: Agent, what: string, cwd: string, prompt: string,
     }),
   );
 
-export const askingFor = <A>(
+export const askingFor = <A, I>(
   agent: Agent,
   what: string,
   cwd: string,
   prompt: string,
-  Answer: Schema.Codec<A, A>,
+  Answer: Schema.Codec<A, I>,
 ) =>
   asking(
     agent,

package/src/create/examples.ts

@@ -0,0 +1,94 @@
+/**
+ * Code from the repository that shows a rule, read from the file itself and
+ * put to the user, who says whether each excerpt breaks the rule.
+ */
+import { type Agent } from "#create/agents.ts";
+import {
+  type Candidate,
+  Candidates,
+  type Reviewed,
+  askingFor,
+  examplesPrompt,
+} from "#create/ask.ts";
+import { excerpt, line, note, said, warn } from "#create/look.ts";
+import { Effect, FileSystem, Option, Path } from "effect";
+import { Prompt } from "effect/cli";
+
+/**
+ * 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.
+ */
+export 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 }),
+      );
+      const note = (yield* Prompt.run(
+        Prompt.String({ message: "Note for the agent (optional)", default: "" }),
+      )).trim();
+      reviewed.push({
+        where: at,
+        code: lines.slice(start - 1, end).join("\n"),
+        violation,
+        agreed: violation === candidate.violation,
+        ...(note === "" ? {} : { note }),
+      });
+    }
+    if (missing > 0) {
+      yield* note(
+        "Left out " + missing + " excerpt" + (missing === 1 ? "" : "s") + " not found in the repo.",
+      );
+    }
+    return reviewed;
+  });
+
+/**
+ * Asks the agent for excerpts in the project the user is in, then puts them to
+ * the user. An agent that cannot search the repo leaves the examples to the
+ * rule's draft.
+ */
+export const reviewedInRepository = (agent: Agent, root: string, idea: string, id: string) =>
+  Effect.gen(function* () {
+    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: [] })),
+      ),
+    );
+    return yield* review(agent, root, found.candidates);
+  });

package/src/create/look.ts

@@ -8,33 +8,74 @@ import { Status, clearingStatus } from "#services/Status.ts";
 import { Console, Duration, Effect, Fiber } from "effect";
 import { Prompt } from "effect/cli";
 
+const rgbColor = (r: number, g: number, b: number) => `\x1B[38;2;${r};${g};${b}m`;
+const colorCode = (n: number) => `\x1B[38;5;${n}m`;
+const COLORS = {
+  PURPLE: colorCode(99),
+  KIWI: colorCode(156),
+  PINK: colorCode(212),
+  FG: rgbColor(220, 220, 240),
+  MUTED: rgbColor(180, 180, 190),
+  RED: colorCode(197),
+  ACCENT: rgbColor(242, 205, 205),
+};
+
+/** One column of left padding, so the whole wizard sits clear of the terminal's edge. */
+const PAD = " ";
+
 /**
- * The prompts' theme. Every row's text starts in the fourth column: after the
- * prompt's symbol and two spaces, a select's pointer and its two-wide paging
- * arrow, or the paging arrow and a space before a multi-select's checkbox.
+ * The prompts' theme. Every symbol carries `PAD`, so each prompt's rows start
+ * where the rail's do; `pointerSmall` also pads a validation error and adds
+ * one space before the `›` that ends an active row.
  */
 export const look: Partial<Prompt.Theme> = {
-  prefix: "◆ ",
-  tick: "◇ ",
-  pointer: "●",
+  // primaryColor: `\x1B[0;37m`,
+  // mutedColor: COLORS.MUTED,
+  successColor: COLORS.KIWI,
+  submittedColor: COLORS.PURPLE,
+  errorColor: COLORS.RED,
+  // toggleSeparator: " / ",
+  // passwordMask: `${COLORS.MUTED}*${ESC}`,
+  // prefix: `│\n│${COLORS.PINK} ◇${ESC}`,
+  // prefix: `\n ◇`,
+  // tick: `\n ✓`,
+  // tick: `│\n│${COLORS.KIWI} ✓${ESC}`,
+  // pointer: `${COLORS.PURPLE}‣${ESC}`,
   arrowUp: "↑ ",
   arrowDown: "↓ ",
-  pointerSmall: "",
-  ellipsis: "",
-  descriptionSeparator: "\n   ",
-  checkboxOn: "◼",
-  checkboxOff: "◻",
+  prefix: `${PAD}?`,
+  pointer: `${PAD}❯`,
+  pointerSmall: `${PAD}›`,
+  ellipsis: "…",
+  tick: `${PAD}✔`,
+  descriptionSeparator: "\n\n  - ",
+  checkboxOn: "󰄲",
+  checkboxOff: "",
+  colors: true,
 };
 
 const columns = () => process.stderr.columns ?? 80;
 
-/** `text` wrapped to the terminal, each further line indented under a choice's title as the first is. */
+/** `text` wrapped to the terminal, each further line indented under the separator as the first is. */
 export const indented = (text: string) =>
-  Bun.wrapAnsi(text, Math.max(columns() - 4, 20)).replaceAll("\n", "\n   ");
+  Bun.wrapAnsi(text, Math.max(columns() - 5, 20)).replaceAll("\n", "\n    ");
+
+/** Renders Markdown for preview with Bun's native Markdown-to-ANSI renderer. */
+export const renderMarkdown = (text: string) =>
+  Effect.gen(function* () {
+    const theme = yield* Prompt.Theme;
+    return Bun.markdown
+      .ansi(text, {
+        colors: theme.colors,
+        columns: Math.max(columns() - 4, 20),
+      })
+      .trimEnd();
+  });
 
 type Color = (theme: Prompt.Theme) => string;
 const muted: Color = (theme) => theme.mutedColor;
 const primary: Color = (theme) => theme.primaryColor;
+const accent: Color = (_theme) => COLORS.PINK;
 
 const paint = (theme: Prompt.Theme, text: string, color?: Color) =>
   theme.colors && color !== undefined ? `${color(theme)}${text}\x1b[0m` : text;
@@ -46,14 +87,16 @@ const paint = (theme: Prompt.Theme, text: string, color?: Color) =>
 const rail = (symbol: string, symbolColor: Color, text: string, textColor?: Color, bar = "│") =>
   Effect.gen(function* () {
     const theme = yield* Prompt.Theme;
-    const [first = "", ...rest] = Bun.wrapAnsi(text, Math.max(columns() - 3, 20), {
+    const [first = "", ...rest] = Bun.wrapAnsi(text, Math.max(columns() - 4, 20), {
       hard: true,
       trim: false,
     }).split("\n");
     yield* Console.error(
       [
-        `${paint(theme, symbol, symbolColor)}  ${paint(theme, first, textColor)}`,
-        ...rest.map((line) => `${paint(theme, bar, muted)}  ${paint(theme, line, textColor)}`),
+        `${PAD}${paint(theme, symbol, symbolColor)}  ${paint(theme, first, textColor)}`,
+        ...rest.map(
+          (line) => `${PAD}${paint(theme, bar, muted)}  ${paint(theme, line, textColor)}`,
+        ),
       ].join("\n"),
     );
   });
@@ -91,7 +134,7 @@ export const excerpt = (
   Effect.gen(function* () {
     const theme = yield* Prompt.Theme;
     const width = String(range.to).length;
-    const room = Math.max(columns() - width - 8, 20);
+    const room = Math.max(columns() - width - 9, 20);
     const cut = lines.slice(range.from - 1, range.to).map((text) => {
       const flat = text.replaceAll("\t", "  ");
       return flat.length > room ? `${flat.slice(0, room - 1)}…` : flat;
@@ -105,7 +148,7 @@ export const excerpt = (
       const body = inside
         ? `${paint(theme, number, muted)}  ${colored[index] ?? text}`
         : paint(theme, `${number}  ${text}`, muted);
-      return `${paint(theme, "│", muted)}  ${marker} ${body}`;
+      return `${PAD}${paint(theme, "│", muted)}  ${marker} ${body}`;
     });
     yield* Console.error(rows.join("\n"));
   });
@@ -127,7 +170,7 @@ export const spinning = <A, E, R>(text: string, effect: Effect.Effect<A, E, R>)
     const spinner = yield* Effect.forkChild(
       Effect.suspend(() =>
         status.show(
-          `${paint(theme, frames[frame++ % frames.length] ?? "", primary)}  ${paint(theme, `${text}…`, muted)}`,
+          `${PAD}${paint(theme, frames[frame++ % frames.length] ?? "", accent)}  ${paint(theme, `${text}…`, muted)}`,
         ),
       ).pipe(Effect.andThen(Effect.sleep("110 millis")), Effect.forever),
     );