@zerotal/arch 1.7.5 → 1.8.1

package/src/install/ArchInstallCommand.ts

@@ -16,9 +16,12 @@ import type { Application } from "@zerotal/core";
 import { ArchConfig } from "../config.ts";
 import type { ArchConfigShape } from "../config.ts";
 import { NoProjectRootError } from "../errors.ts";
-import { installedPackages } from "../probe/topics.ts";
+import { declaredPackages } from "../probe/topics.ts";
 import { detectAgents } from "./detect.ts";
 import { agentsPreamble, buildGuidelines, claudeShim } from "./guidelines.ts";
+import { detectShape } from "./shape.ts";
+import { selectSkills, renderSkill, skillPaths, SKILL_MARKER } from "./skills.ts";
+import type { ProjectShape } from "./shape.ts";
 import { applyBlock } from "./markers.ts";
 import { applyMcpConfig } from "./mcpConfig.ts";
 
@@ -51,12 +54,18 @@ export class ArchInstallCommand extends Command {
     const config = this._config();
 
     const detected = await detectAgents(root);
-    const packages = (await installedPackages(root)).map((pkg) => pkg.name);
+    // Declared, not installed: what an install layout hoists into node_modules
+    // differs between machines, and the guidance must not.
+    const packages = (await declaredPackages(root)).map((pkg) => pkg.name);
+    // Read off disk rather than from a booted app: a project that will not boot is
+    // often exactly why someone is installing the agent surface.
+    const shape = await detectShape(root);
 
     const changes: Change[] = [
       ...(config.mcpConfig ? await this._mcpChanges(root, config, detected.targets) : []),
-      ...(config.agentsFile ? [await this._agentsChange(root, config, packages)] : []),
+      ...(config.agentsFile ? [await this._agentsChange(root, config, packages, shape)] : []),
       ...(config.claudeFile ? [await this._claudeChange(root)] : []),
+      ...(config.skills ? await this._skillChanges(root, packages, shape, detected.agents) : []),
     ];
 
     this.section(dry ? "arch:install — dry run" : "arch:install");
@@ -77,7 +86,7 @@ export class ArchInstallCommand extends Command {
         continue;
       }
       if (change.status === "unchanged") {
-        this.dim(`  · ${change.path} — already up to date`);
+        this.dim(`  · ${change.path} — ${change.detail ?? "already up to date"}`);
         continue;
       }
       if (!dry && change.text !== undefined) {
@@ -153,10 +162,11 @@ export class ArchInstallCommand extends Command {
     root: string,
     config: ArchConfigShape,
     packages: string[],
+    shape: ProjectShape,
   ): Promise<Change> {
     const outcome = applyBlock(
       await readIfPresent(join(root, "AGENTS.md")),
-      buildGuidelines({ packages, serverName: config.serverName }),
+      buildGuidelines({ packages, serverName: config.serverName, shape }),
       agentsPreamble(),
     );
     return outcome.status === "conflict"
@@ -164,6 +174,41 @@ export class ArchInstallCommand extends Command {
       : { path: "AGENTS.md", status: outcome.status, text: outcome.text };
   }
 
+  /**
+   * The skill files, one per applicable skill per agent directory.
+   *
+   * A file without {@link SKILL_MARKER} is left exactly as it is. That is the
+   * whole override mechanism: to replace a skill this ships, edit it and delete
+   * the marker line. Anything cleverer would be a second config to keep in step
+   * with the thing it configures.
+   */
+  private async _skillChanges(
+    root: string,
+    packages: string[],
+    shape: ProjectShape,
+    agents: string[],
+  ): Promise<Change[]> {
+    const changes: Change[] = [];
+
+    for (const skill of selectSkills(packages, shape)) {
+      const text = renderSkill(skill, shape);
+      for (const path of skillPaths(skill.name, agents)) {
+        const existing = await readIfPresent(join(root, path));
+        if (existing !== undefined && !existing.includes(SKILL_MARKER)) {
+          changes.push({ path, status: "unchanged", detail: "yours — left alone" });
+          continue;
+        }
+        changes.push(
+          existing === text
+            ? { path, status: "unchanged" }
+            : { path, status: existing === undefined ? "created" : "updated", text },
+        );
+      }
+    }
+
+    return changes;
+  }
+
   private async _claudeChange(root: string): Promise<Change> {
     const outcome = applyBlock(await readIfPresent(join(root, "CLAUDE.md")), claudeShim());
     return outcome.status === "conflict"

package/src/install/guidelines.ts

@@ -11,6 +11,8 @@
  * would summarise are the ones those tools return in full.
  */
 
+import type { ProjectShape } from "./shape.ts";
+
 /** A block contributed by one installed package. */
 interface PackageBlock {
   /** The package that triggers it. */
@@ -144,6 +146,11 @@ export interface GuidelineOptions {
   packages: string[];
   /** The key the MCP server is registered under, so the text names it correctly. */
   serverName: string;
+  /**
+   * How this project is configured, from {@link detectShape}. Omitted, the block
+   * is what it always was — a function of the package list.
+   */
+  shape?: ProjectShape;
 }
 
 /**
@@ -191,6 +198,9 @@ export function buildGuidelines(options: GuidelineOptions): string {
     );
   }
 
+  const shape = options.shape ? shapeSection(options.shape) : "";
+  if (shape) sections.push("", shape);
+
   sections.push(rulesSection());
 
   return sections
@@ -258,6 +268,80 @@ function commandSection(): string {
   ].join("\n");
 }
 
+/**
+ * What this project is configured to be, where that changes what to write.
+ *
+ * The rest of this file describes the framework; this describes *this app*. The
+ * distinction matters because the framework's contracts are not uniform, and the
+ * places they differ are places where guessing wrong compiles cleanly and fails
+ * at runtime. An `EmailVerification` mixin needs a migration in one app and not
+ * in another, and the app that needed one lost 419 tests to a column that was
+ * never created.
+ *
+ * Only facts that change an instruction are emitted. "This app uses SQLite" is
+ * trivia; "migrations own the schema here, so a new column needs one" is a
+ * decision the agent would otherwise get wrong half the time.
+ */
+function shapeSection(shape: ProjectShape): string {
+  const lines: string[] = [];
+
+  if (shape.schemaSource === "migrations") {
+    lines.push(
+      "- **Migrations own the schema.** A new or changed column needs a migration — including " +
+        "columns a mixin registers imperatively, which are added to tables that already exist " +
+        "but never create one. Generate with `bun zt make:migration`, guard an added column " +
+        "with `Schema.hasColumn`, and never hand-edit a migration that has run.",
+    );
+  } else if (shape.schemaSource === "models") {
+    lines.push(
+      "- **The models own the schema** (`database.synchronize`). The table is built from what " +
+        "the models declare, so a `@column` is the whole change and there is no migration to " +
+        "write. Check `schema` after adding one to confirm it landed.",
+    );
+  } else if (shape.schemaSource === "both") {
+    lines.push(
+      "- **Both `database.synchronize` and migrations are present**, which is deliberate in " +
+        "some apps (sync locally, migrations in production) and a mistake in others. Run " +
+        "`doctor` and read what it says about the source of truth before adding a column — " +
+        "the answer decides whether a migration is required or would collide.",
+    );
+  }
+
+  if (shape.routeTypes) {
+    lines.push(
+      "- **Route names are typed.** `types/routes.generated.ts` exists, so `route()` is checked " +
+        "against it and a stale file turns a working call into a type error. Run " +
+        "`bun zt route:types` after any route change.",
+    );
+  }
+
+  if (shape.strict.exactOptionalPropertyTypes) {
+    lines.push(
+      "- **`exactOptionalPropertyTypes` is on.** `{ x: undefined }` is not assignable to " +
+        "`{ x?: T }`. Build optional properties conditionally — `...(v ? { x: v } : {})` — " +
+        "rather than assigning `undefined` and expecting the key to be treated as absent.",
+    );
+  }
+
+  if (shape.strict.noUncheckedIndexedAccess) {
+    lines.push(
+      "- **`noUncheckedIndexedAccess` is on.** Every index read is `T | undefined`. Narrow it; " +
+        "do not reach for `!` to silence it.",
+    );
+  }
+
+  if (shape.hasTests) {
+    lines.push(
+      "- **This app has tests.** Run `bun zt test` before calling a task done — `doctor` checks " +
+        "configuration, not behaviour, and only one of the two notices that a change broke " +
+        "something.",
+    );
+  }
+
+  if (lines.length === 0) return "";
+  return ["### How this app is set up", "", ...lines].join("\n");
+}
+
 function rulesSection(): string {
   return [
     "",

package/src/install/shape.ts

@@ -0,0 +1,177 @@
+/**
+ * What this project is configured to be, as distinct from what it has installed.
+ *
+ * The guidance in `guidelines.ts` was a function of the package list alone, and
+ * a package list cannot answer the questions that actually decide what an agent
+ * should write. The framework's contracts are not uniform: the same mixin needs a
+ * migration in one app and not in another, `route()` is checked against generated
+ * names in one and unchecked in another, and an optional property is written one
+ * way under `exactOptionalPropertyTypes` and another way without it.
+ *
+ * An agent that guesses wrong there does not get a type error. It gets a working
+ * build and a runtime failure — `no such column: email_verified_at`, hundreds of
+ * tests down at once, in an app whose schema is owned by migrations and whose
+ * `AGENTS.md` never said so.
+ *
+ * ## Read from files, not from a booted app
+ *
+ * `arch:install` runs in a project that may not boot — that is often *why*
+ * someone is installing the agent surface. Everything here comes off disk.
+ *
+ * ## What is deliberately not read
+ *
+ * `.env`, and anything else holding credentials. This output is written into a
+ * file that is committed and pasted into prompts; a detector that reads secrets
+ * is one refactor away from emitting them. Where a fact is available from both a
+ * config file and the environment, the config file is the only source used.
+ */
+import { join } from "node:path";
+
+/** How the database schema comes to exist, which decides who must write a column. */
+export type SchemaSource = "migrations" | "models" | "both" | "unknown";
+
+export interface ProjectShape {
+  schemaSource: SchemaSource;
+  /** `types/routes.generated.ts` exists, so `route()` names are checked. */
+  routeTypes: boolean;
+  /** tsconfig flags that change how correct code is written, not just how it is checked. */
+  strict: {
+    exactOptionalPropertyTypes: boolean;
+    noUncheckedIndexedAccess: boolean;
+    strict: boolean;
+  };
+  /** A `tests/` directory with something in it. */
+  hasTests: boolean;
+}
+
+/** Read `root`'s shape. Every probe fails soft: an unknown fact is simply not stated. */
+export async function detectShape(root: string): Promise<ProjectShape> {
+  const [schemaSource, routeTypes, strict, hasTests] = await Promise.all([
+    _schemaSource(root),
+    _exists(join(root, "types", "routes.generated.ts")),
+    _strictness(root),
+    _hasFiles(join(root, "tests")),
+  ]);
+  return { schemaSource, routeTypes, strict, hasTests };
+}
+
+/**
+ * Migrations, models, or both.
+ *
+ * Mirrors `zt doctor`'s `synchronize-vs-migrations` check, which decides the same
+ * question from the same two inputs — but reports it as a *problem* when both are
+ * on. Here both is a legitimate answer worth stating plainly, because an agent
+ * needs to know it is looking at an app where either route might be the intended
+ * one and it should ask rather than assume.
+ */
+async function _schemaSource(root: string): Promise<SchemaSource> {
+  const migrations = await _hasFiles(join(root, "database", "migrations"));
+  const synchronize = await _synchronizeOn(root);
+
+  if (migrations && synchronize) return "both";
+  if (migrations) return "migrations";
+  if (synchronize) return "models";
+  return "unknown";
+}
+
+/**
+ * Whether `database.synchronize` is on.
+ *
+ * Read as text rather than by importing the config, which would need the app's
+ * environment and its whole provider graph. The value is commonly an expression —
+ * `env("APP_ENV") !== "production"` — so a literal `false` is the only confident
+ * "off"; anything else is treated as "may be on", which errs toward telling the
+ * agent the arrangement is ambiguous rather than asserting the wrong half.
+ */
+async function _synchronizeOn(root: string): Promise<boolean> {
+  const source = await _read(join(root, "config", "database.ts"));
+  if (!source) return false;
+  const match = /\bsynchronize\s*:\s*([^,\n}]+)/.exec(source);
+  if (!match) return false;
+  const value = (match[1] ?? "").trim();
+  return value !== "false";
+}
+
+/**
+ * Read the strictness flags through the whole `extends` chain.
+ *
+ * Reading only the project's own `tsconfig.json` gets this wrong for most real
+ * apps, and wrong in the quiet direction: a workspace app that extends a strict
+ * base has none of these flags in its own file, so every one reads as off and the
+ * guidance says nothing. The app the framework itself ships did exactly that —
+ * detected as unstrict while compiling under a base that turns all three on.
+ *
+ * Nearest wins, as tsc resolves it: a flag set in the extending file overrides
+ * the one it inherits, including turning an inherited flag off.
+ */
+async function _strictness(root: string): Promise<ProjectShape["strict"]> {
+  const chain = await _tsconfigChain(join(root, "tsconfig.json"));
+
+  const on = (flag: string): boolean => {
+    for (const source of chain) {
+      const match = new RegExp(`"${flag}"\\s*:\\s*(true|false)`).exec(source);
+      if (match) return match[1] === "true";
+    }
+    return false;
+  };
+
+  // The two that matter here are not implied by `strict` — each has to be asked
+  // for, which is why they are worth reporting separately from it.
+  return {
+    strict: on("strict"),
+    exactOptionalPropertyTypes: on("exactOptionalPropertyTypes"),
+    noUncheckedIndexedAccess: on("noUncheckedIndexedAccess"),
+  };
+}
+
+/** A tsconfig and everything it extends, nearest first. */
+async function _tsconfigChain(path: string, depth = 0): Promise<string[]> {
+  // Bounded rather than cycle-tracked: a chain this long is already pathological,
+  // and the cost of being wrong here is a missing line of guidance.
+  if (depth > 8) return [];
+
+  const source = await _read(path);
+  if (source === undefined) return [];
+
+  const extended = /"extends"\s*:\s*"([^"]+)"/.exec(source)?.[1];
+  if (!extended) return [source];
+
+  // Only a relative path is resolvable from here. A package reference
+  // (`@tsconfig/bun`) lives in node_modules under a layout this does not chase.
+  if (!extended.startsWith(".")) return [source];
+
+  const { dirname, resolve: resolvePath } = await import("node:path");
+  const next = resolvePath(
+    dirname(path),
+    extended.endsWith(".json") ? extended : `${extended}.json`,
+  );
+  return [source, ...(await _tsconfigChain(next, depth + 1))];
+}
+
+async function _read(path: string): Promise<string | undefined> {
+  try {
+    const file = Bun.file(path);
+    return (await file.exists()) ? await file.text() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function _exists(path: string): Promise<boolean> {
+  try {
+    return await Bun.file(path).exists();
+  } catch {
+    return false;
+  }
+}
+
+/** A directory that exists and holds at least one file. */
+async function _hasFiles(dir: string): Promise<boolean> {
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(dir);
+    return entries.some((entry) => !entry.startsWith("."));
+  } catch {
+    return false;
+  }
+}

package/src/install/skills.ts

@@ -0,0 +1,271 @@
+/**
+ * Depth that costs nothing until it is needed.
+ *
+ * `guidelines.ts` opens by saying that every prompt its output lands in pays for
+ * its whole length, and that is why the block there is short and points rather
+ * than teaches. The cost is real, and so is what it buys: an agent gets a map and
+ * no detail, and the detail is where the expensive mistakes live. Knowing that
+ * migrations exist is not the same as knowing that a mixin's column needs one
+ * here and not in the app next door.
+ *
+ * A skill is the other half. It sits on disk with a one-line description, costs
+ * nothing while it is not relevant, and is loaded whole when it is — so the depth
+ * that could never be afforded upfront can be written out properly.
+ *
+ * ## What belongs here rather than in the block
+ *
+ * Anything procedural. The block says what exists and who owns it; a skill says
+ * how to do one thing correctly, including the parts that look optional and are
+ * not. If a line would only ever matter to someone already doing the task, it is
+ * a skill.
+ *
+ * ## What does not belong here at all
+ *
+ * Anything the tools answer better. `api_surface` gives exact signatures for the
+ * installed version and `search_docs` gives the pages; a skill that paraphrases
+ * either is a copy that starts wrong on the next release. These describe
+ * *sequences and traps* — what the documentation is worst at and what costs the
+ * most to learn by hitting it.
+ */
+import type { ProjectShape } from "./shape.ts";
+
+/**
+ * Marks a file as this tool's to rewrite.
+ *
+ * Placed as the first body line, after the frontmatter, because frontmatter has
+ * to open the file. A `SKILL.md` without it is somebody's own and is never
+ * touched — overriding a shipped skill should be as simple as editing it.
+ */
+export const SKILL_MARKER = "<!-- zerotal:arch:generated -->";
+
+export interface Skill {
+  /** Directory name, and the name in the frontmatter. */
+  name: string;
+  /** The one line an agent reads to decide whether to load the rest. */
+  description: string;
+  /** Packages that must be installed for this skill to apply. */
+  requires?: string[];
+  /** Body, given the project's shape. Empty means "not applicable here". */
+  body: (shape: ProjectShape | undefined) => string;
+}
+
+const SCHEMA_SKILL: Skill = {
+  name: "zerotal-schema-changes",
+  description:
+    "Add or change a database column in a Zerotal app — deciding whether a migration is " +
+    "required, writing one that is safe to re-run, and the mixin columns that need one even " +
+    "though nothing declares them.",
+  requires: ["@zerotal/orm"],
+  body: (shape) => {
+    const source = shape?.schemaSource ?? "unknown";
+
+    // Emphasis is written `_like this_`, not `*like this*`. These files land in
+    // somebody's repository and are checked by their formatter, and a generator
+    // whose output fails the project's own format check is one nobody can run in
+    // CI.
+    const owner =
+      source === "migrations"
+        ? "**Migrations own the schema in this app.**"
+        : source === "models"
+          ? "**The models own the schema in this app** (`database.synchronize` is on)."
+          : source === "both"
+            ? "**Both are in play here** — `database.synchronize` is on _and_ migrations exist. " +
+              "Run `doctor` and read the source-of-truth line before you touch anything."
+            : "**Which one owns the schema here is not obvious from the config.** Run `doctor` " +
+              "and read the source-of-truth line first.";
+
+    return `
+# Changing the schema
+
+${owner}
+
+## Decide who owns the schema before writing anything
+
+Two arrangements, and they need different work for the same change:
+
+- **Models own it** (\`database.synchronize\`). The table is built from what the models
+  declare. A \`@column\` is the whole change; there is no migration to write.
+- **Migrations own it.** The table is built from what a migration says. A \`@column\` alone
+  changes nothing on disk, and every query touching it fails at runtime.
+
+\`bun zt doctor\` reports which. Ask it rather than guessing — the failure mode for guessing
+wrong is a clean type-check and a runtime error under load.
+
+## The columns nothing declares
+
+Some mixins register a column imperatively rather than with \`@column\` — \`EmailVerification\`
+adds \`email_verified_at\`, \`Authenticatable\` adds \`remember_token\`. A boot-time concern
+adds those to their table **if the table already exists**.
+
+It never creates a table, and it never revisits one. So where migrations own the schema, a
+\`create users\` migration that does not mention \`email_verified_at\` produces a table
+without it, permanently:
+
+\`\`\`
+SQLiteError: no such column: email_verified_at
+\`\`\`
+
+Composing such a mixin in a migrations-owned app means writing the migration too.
+
+## Write the migration so it can meet a database that already has the column
+
+The concern above may already have added it — on any database that has booted the app since
+the mixin was composed. An unguarded \`ALTER TABLE\` then fails with \`duplicate column name\`,
+during the release's \`migrate\` step:
+
+\`\`\`ts
+import { Schema } from "@zerotal/orm";
+
+export default class extends Migration {
+  async up(): Promise<void> {
+    if (!(await Schema.hasColumn("users", "email_verified_at"))) {
+      await Schema.table("users", (table) => {
+        table.dateTime("email_verified_at").nullable();
+      });
+    }
+  }
+}
+\`\`\`
+
+## Sequence
+
+1. \`bun zt doctor\` — who owns the schema.
+2. \`bun zt make:migration\` if migrations do. Never hand-edit one that has run: the runner
+   records it as applied and will not run it again, so the edit reaches no database that
+   already migrated.
+3. Call the \`schema\` tool afterwards to confirm the column is really there. It reads the
+   database, not the models, which is the difference that matters here.
+4. \`bun zt test\`.
+`.trim();
+  },
+};
+
+const RELEASE_SKILL: Skill = {
+  name: "zerotal-releases",
+  description:
+    "Ship a Zerotal app — ordering the release steps, replacing built assets rather than " +
+    "merging into them, and the proxy and shell settings that fail quietly in production.",
+  body: () =>
+    `
+# Shipping a release
+
+## Name your own steps
+
+\`deploy:<env>\` runs the steps named in \`config/deploy.ts\`, defaulting to build-and-migrate.
+A preflight command of your own runs only if you name it, and nothing prompts you to:
+
+\`\`\`ts
+// config/deploy.ts
+export default {
+  targets: {
+    production: {
+      url: "https://example.com",
+      steps: ["release:check", "assets:build", "inertia:build", "migrate"],
+    },
+  },
+};
+\`\`\`
+
+Put the check first. A step that fails stops the release, and a check that runs after the
+migration has missed its moment.
+
+\`deploy:<env>\` runs **where the app runs**, with that environment's variables. It does not
+reach another machine.
+
+## Replace the asset directory, do not merge into it
+
+Each build emits a fresh set of content-hashed chunks and cleans up the set it replaced. It
+can only clean a directory it is run in. A release unpacked over the top of the running one
+— \`tar -xzf\` into the app directory, \`rsync\` without \`--delete\` — merges: files in the
+archive are written, files not in it are left exactly where they were. Nothing on that
+machine ever runs a build, so last release's bundles stay, and they stay **publicly
+fetchable at their hashed URLs**. Copy you withdrew is still readable by anyone with the
+link.
+
+\`\`\`bash
+rm -rf "$APP_DIR/public/assets"    # before extracting
+tar -xzf release.tgz -C "$APP_DIR"
+
+# or
+rsync -a --delete public/assets/ "$HOST:$APP_DIR/public/assets/"
+\`\`\`
+
+Clearing takes the running release's bundles away, so do it close to the swap, or stage into
+a new directory and move it into place.
+
+\`--clean\` on \`assets:build\` / \`inertia:build\` removes anything in the output directory the
+build did not write. It is for output some other naming produced; it does not help a
+directory nothing runs in, and it refuses \`public/\` itself.
+
+## Rate limiting counts the proxy, not the visitor
+
+Behind a proxy every request arrives from the same address, so one bucket is shared by
+everybody and a single client can lock the site out. Say how many proxies are in front:
+
+\`\`\`ts
+ThrottleMiddleware.with({ maxAttempts: 60, trustedProxies: 1 });
+\`\`\`
+
+It defaults to zero because \`X-Forwarded-For\` is client-written until something trusted
+overwrites it. Count the proxies you actually run — too many reads an entry the client
+supplied.
+
+## A pipe hides the exit status
+
+\`\`\`bash
+bun test 2>&1 | tail -3     # the status is tail's. Always 0, however the suite went.
+\`\`\`
+
+A deploy script gated that way prints \`1 fail\` and carries on to upload and restart. Use
+\`set -o pipefail\`, or capture the status. \`set -e\` alone does not cover it — the pipeline
+succeeded, as far as the shell is concerned.
+`.trim(),
+};
+
+/** Everything that could be installed, before the project narrows it. */
+export const SKILLS: Skill[] = [SCHEMA_SKILL, RELEASE_SKILL];
+
+/** The skills that apply to a project with these packages and this shape. */
+export function selectSkills(
+  packages: readonly string[],
+  shape: ProjectShape | undefined,
+  all: readonly Skill[] = SKILLS,
+): Skill[] {
+  const installed = new Set(packages);
+  return all.filter(
+    (skill) =>
+      (skill.requires ?? []).every((pkg) => installed.has(pkg)) &&
+      skill.body(shape).trim().length > 0,
+  );
+}
+
+/** One `SKILL.md`: frontmatter, the marker, then the body. */
+export function renderSkill(skill: Skill, shape: ProjectShape | undefined): string {
+  return [
+    "---",
+    `name: ${skill.name}`,
+    // Quoted: descriptions contain commas and colons, which unquoted YAML reads
+    // as structure.
+    `description: ${JSON.stringify(skill.description)}`,
+    "---",
+    "",
+    SKILL_MARKER,
+    "",
+    skill.body(shape),
+    "",
+  ].join("\n");
+}
+
+/**
+ * Where a skill directory goes.
+ *
+ * `.agents/skills` is the cross-client path; `.claude/skills` is read by Claude
+ * Code, and some clients scan it too. Written to both when that agent is present,
+ * because a skill in the wrong directory is not a degraded skill — it is an
+ * inert file that looks installed.
+ */
+export function skillPaths(name: string, agents: readonly string[]): string[] {
+  const paths = [`.agents/skills/${name}/SKILL.md`];
+  if (agents.includes("Claude Code")) paths.push(`.claude/skills/${name}/SKILL.md`);
+  return paths;
+}