@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.4

package/dist/packs.js

@@ -1,17 +1,25 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Loads pack manifests from `templates/packs/<name>/pack.json` and installs
  * a pack's files + JSON wiring into a freshly-bootstrapped project. Adopt
  * mode never calls `installPack` -- it surveys packs into the report
- * (`observeWiring`, `stagePackFiles`) and defers installation to
- * `/customize`, which reads a project's real gate runner before translating
- * a pack's wiring (see inventory.ts).
+ * (`observeWiring`; `pack-stage.ts`'s `stagePacks` stages them, inert) and
+ * defers installation to `/customize`, which reads a project's real gate
+ * runner before translating a pack's wiring (see inventory.ts). Both modes call `loadPack` for every
+ * pack they handle (fresh mode: each `--pack`; adopt mode: every pack)
+ * before writing anything, and `loadPack` refuses a prototype-sensitive
+ * key in `wiring.settings`, `wiring.settingsTopLevel` or
+ * `wiring.packageScripts`, so such a pack is neither installed nor staged.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { resolveAsset } from "./assets.js";
 import { emitTemplate } from "./emit.js";
 import { parseJsonc } from "./jsonc.js";
-import { isRecord, mergePackageScripts, mergeSettingsHooks, mergeSettingsTopLevel, mergeVerifySteps, } from "./merge-json.js";
+import { blockedAbsentNote } from "./survey/internal/blocked-path.js";
+import { probePath, readFailure, recordedReadCode, unreadableNote, } from "./survey/internal/read-guard.js";
+import { isPrototypeSensitiveKey, isRecord, mergePackageScripts, mergeSettingsHooks, mergeSettingsTopLevel, mergeVerifySteps, } from "./merge-json.js";
 /** `templates/packs`, resolved the same way `templatesCoreDir()` resolves `templates/core`. */
 export function packsRootDir() {
     return resolveAsset({ repo: "templates/packs", local: "templates/packs" });
@@ -26,7 +34,111 @@ export function listPackNames(root = packsRootDir()) {
         .map((entry) => entry.name)
         .sort();
 }
-/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown or malformed. */
+/** A pack's own `name` becomes a path segment under `.groundwork/packs/`, so it must be a bare lowercase identifier: no separators, no `..`. */
+const PACK_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const CAP_KEYS = [
+    "agents",
+    "skills",
+    "hooks",
+    "workflows",
+    "scripts",
+];
+/** True when `budget` has an own non-negative integer for every {@link CapCounts} key (one read per key). */
+function isValidBudget(budget) {
+    if (!isRecord(budget))
+        return false;
+    return CAP_KEYS.every((key) => {
+        if (!Object.hasOwn(budget, key))
+            return false;
+        const value = budget[key];
+        return Number.isInteger(value) && value >= 0;
+    });
+}
+/** The two CLI modes a pack's `modes` may name (see mode.ts). */
+const PACK_MODES = ["fresh", "adopt"];
+/** The `bin/lib/verify-steps.mjs` groups a pack's verify step may join. */
+const VERIFY_GROUPS = [
+    "format",
+    "lint",
+    "typecheck",
+    "build",
+    "test",
+];
+/** Throws, naming the entry's 0-based `index` and the offending field, when one `wiring.verifySteps[]` entry isn't an object, lacks a string `id`/`name`, lacks a non-empty string-array `cmd`, or names an unknown `group`. Each field is read once into a local before it is checked. */
+function assertValidVerifyStep(name, step, index) {
+    const where = `pack "${name}": pack.json's wiring.verifySteps[${String(index)}]`;
+    if (!isRecord(step)) {
+        throw new Error(`${where} must be an object, got ${String(JSON.stringify(step))}`);
+    }
+    for (const key of ["id", "name"]) {
+        const value = Object.hasOwn(step, key) ? step[key] : undefined;
+        if (typeof value !== "string") {
+            throw new Error(`${where}.${key} must be a string, got ${String(JSON.stringify(value))}`);
+        }
+    }
+    const cmd = Object.hasOwn(step, "cmd") ? step["cmd"] : undefined;
+    if (!Array.isArray(cmd) ||
+        cmd.length === 0 ||
+        !cmd.every((part) => typeof part === "string")) {
+        throw new Error(`${where}.cmd must be a non-empty array of strings, got ${String(JSON.stringify(cmd))}`);
+    }
+    const group = Object.hasOwn(step, "group")
+        ? step["group"]
+        : undefined;
+    if (typeof group !== "string" || !VERIFY_GROUPS.includes(group)) {
+        throw new Error(`${where} group ${String(JSON.stringify(group))} must be one of ${VERIFY_GROUPS.join(", ")}`);
+    }
+}
+/**
+ * Throws, naming the pack, the field and the key, when one of `fragment`'s own
+ * enumerable keys is prototype-sensitive ({@link isPrototypeSensitiveKey}).
+ * `Object.keys` sees a `__proto__` key here because `parseJsonc`, like
+ * `JSON.parse`, creates it as an ordinary own data property. Only the
+ * fragment's own top-level keys are checked: they are the names a merge
+ * writes, while everything nested below them is an opaque value.
+ */
+function assertNoPrototypeSensitiveKeys(name, field, fragment) {
+    for (const key of Object.keys(fragment)) {
+        if (isPrototypeSensitiveKey(key)) {
+            throw new Error(`pack "${name}": pack.json's wiring.${field} must not use the prototype-sensitive key ${JSON.stringify(key)}`);
+        }
+    }
+}
+/**
+ * Throws, naming the offending key or value, when `wiring.settings`/`packageScripts` is missing or isn't an object, `verifySteps` is missing or isn't an array, any `verifySteps[]` entry is malformed (see {@link assertValidVerifyStep}), or `settings`, `packageScripts` or (when it is an object) `settingsTopLevel` has a prototype-sensitive own key (see {@link assertNoPrototypeSensitiveKeys}).
+ * Those three are the only wiring fields whose keys a merge writes; `verifySteps` ids are values. An absent or non-object `settingsTopLevel` is not rejected here.
+ */
+function assertValidWiringShape(name, wiring) {
+    for (const key of ["settings", "packageScripts"]) {
+        const value = Object.hasOwn(wiring, key) ? wiring[key] : undefined;
+        if (!isRecord(value)) {
+            throw new Error(`pack "${name}": pack.json's wiring.${key} must be an object`);
+        }
+        assertNoPrototypeSensitiveKeys(name, key, value);
+    }
+    const topLevel = Object.hasOwn(wiring, "settingsTopLevel")
+        ? wiring["settingsTopLevel"]
+        : undefined;
+    if (isRecord(topLevel)) {
+        assertNoPrototypeSensitiveKeys(name, "settingsTopLevel", topLevel);
+    }
+    const steps = Object.hasOwn(wiring, "verifySteps")
+        ? wiring["verifySteps"]
+        : undefined;
+    if (!Array.isArray(steps)) {
+        throw new Error(`pack "${name}": pack.json's wiring.verifySteps must be an array`);
+    }
+    steps.forEach((step, index) => {
+        assertValidVerifyStep(name, step, index);
+    });
+}
+/** True when `steps` is a non-empty array of non-empty strings, none containing a line break -- each is printed as one indented line. */
+function isValidSetupSteps(steps) {
+    return (Array.isArray(steps) &&
+        steps.length > 0 &&
+        steps.every((step) => typeof step === "string" && step !== "" && !/[\r\n]/.test(step)));
+}
+/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown; throws naming the pack and the problem if malformed, including a prototype-sensitive key in its wiring (see {@link assertValidWiringShape}) or a `setupSteps` that is present but not a non-empty array of single-line, non-empty strings. */
 export function loadPack(name, root = packsRootDir()) {
     const packDir = join(root, name);
     const manifestPath = join(packDir, "pack.json");
@@ -38,10 +150,47 @@ export function loadPack(name, root = packsRootDir()) {
     if (!parsed.ok) {
         throw new Error(`pack "${name}": pack.json failed to parse -- ${parsed.error}`);
     }
-    const manifest = parsed.value;
+    const raw = parsed.value;
+    if (!isRecord(raw)) {
+        throw new Error(`pack "${name}": pack.json must be an object, got ${String(JSON.stringify(raw))}`);
+    }
+    const manifest = raw;
     if (manifest.schemaVersion !== 1) {
         throw new Error(`pack "${name}": unsupported pack.json schemaVersion ${JSON.stringify(manifest.schemaVersion)}`);
     }
+    const manifestName = manifest.name;
+    if (typeof manifestName !== "string" ||
+        !PACK_NAME_PATTERN.test(manifestName)) {
+        throw new Error(`pack "${name}": pack.json's pack name ${JSON.stringify(manifestName)} must match ${String(PACK_NAME_PATTERN)} (a bare lowercase identifier, no path separators)`);
+    }
+    const modes = manifest.modes;
+    if (!Array.isArray(modes) ||
+        modes.length === 0 ||
+        !modes.every((mode) => typeof mode === "string")) {
+        throw new Error(`pack "${name}": pack.json's modes must be a non-empty array of strings`);
+    }
+    const badMode = modes.find((mode) => !PACK_MODES.includes(mode));
+    if (badMode !== undefined) {
+        throw new Error(`pack "${name}": pack.json's mode ${JSON.stringify(badMode)} must be one of ${PACK_MODES.join(", ")}`);
+    }
+    const wiring = manifest.wiring;
+    if (!isRecord(wiring)) {
+        throw new Error(`pack "${name}": pack.json's wiring must be an object`);
+    }
+    assertValidWiringShape(name, wiring);
+    const budget = manifest.budget;
+    if (!isValidBudget(budget)) {
+        throw new Error(`pack "${name}": pack.json's budget must set ${CAP_KEYS.join(", ")} to non-negative integers`);
+    }
+    const setupSteps = manifest.setupSteps;
+    if (setupSteps !== undefined && !isValidSetupSteps(setupSteps)) {
+        throw new Error(`pack "${name}": pack.json's setupSteps must be a non-empty array of single-line, non-empty strings`);
+    }
+    // pack-stage.ts's stagePacks keys each pack's staging directory on
+    // manifest.name, so a mismatch would let two pack directories collide.
+    if (manifestName !== name) {
+        throw new Error(`pack "${name}": pack.json's name "${manifestName}" does not match its directory name "${name}"`);
+    }
     return { manifest, filesDir: join(packDir, "files") };
 }
 function readJsonOrThrow(path) {
@@ -126,35 +275,96 @@ export function installPack(pack, targetDir, tokens) {
     return { filesWritten, budget: manifest.budget };
 }
 /**
- * Copies a pack's `pack.json` + `files/` tree, unmodified, into
- * `<groundworkDir>/packs/<name>/` -- adopt mode's staging area. `/customize`
- * installs from this self-contained copy rather than from `templateRoot`
- * (an absolute path that may not exist by the time it runs). Token
- * substitution is a no-op here (`{}`): staging a project's real name into
- * pack content is `/customize`'s job, not this offline copy's.
+ * Reads `.claude/settings.json` for {@link observeWiring}. A failure that is
+ * a fact about the project's own tree -- a permission failure
+ * (`EACCES`/`EPERM`), a directory at the path (`EISDIR`), the file vanishing
+ * after the exists probe or a dangling symlink (`ENOENT`), a symlink loop
+ * (`ELOOP`) -- is recorded as an observation naming the path and errno, and
+ * once in `undetermined` (so the adoption report shows it), and `undefined`
+ * is returned; any other errno is about the machine and throws, naming the
+ * path with the original failure as `cause`.
  */
-export function stagePackFiles(pack, groundworkDir) {
-    const destDir = join(groundworkDir, "packs", pack.manifest.name);
-    const { filesWritten } = emitTemplate(pack.filesDir, join(destDir, "files"), {});
-    writeJson(join(destDir, "pack.json"), pack.manifest);
-    return [...filesWritten.map((f) => join("files", f)), "pack.json"];
+function readSettingsOrObserve(settingsPath, observations, undetermined) {
+    try {
+        return readFileSync(settingsPath, "utf8");
+    }
+    catch (error) {
+        const code = recordedReadCode(error);
+        if (code === undefined)
+            throw readFailure(settingsPath, error);
+        observations.push(`.claude/settings.json (${settingsPath}) exists but could not be read (${code})`);
+        // Called once per pack against the same file: record the note once.
+        const note = unreadableNote(settingsPath, code);
+        if (!undetermined.includes(note))
+            undetermined.push(note);
+        return undefined;
+    }
+}
+/**
+ * Whether `path` exists, for {@link observeWiring}. A real `stat`, never
+ * `existsSync`, so a file under a directory this process cannot search is
+ * not observed as missing: an `EACCES`/`EPERM`/`ELOOP` is recorded as an
+ * observation naming the path and errno, and `undefined` is returned so the
+ * caller states neither "found" nor "not found". `ENOENT`/`ENOTDIR` answers
+ * `false` only when nothing is really there: a dangling symlink at the path
+ * or an ancestor, or a regular file blocking an ancestor, is observed and
+ * recorded once in `undetermined` (the same note `conflicts.ts` records via
+ * `blockedAbsentNote`) and answers `undefined`. Any other errno throws (see
+ * `probePath`).
+ */
+function existsOrObserve(path, targetDir, observations, undetermined) {
+    const probe = probePath(path);
+    if (probe.kind === "unresolvable") {
+        observations.push(`could not check whether ${path} exists (${probe.code}) -- left undetermined, not reported missing`);
+        return undefined;
+    }
+    if (probe.kind === "present")
+        return true;
+    const note = blockedAbsentNote(path, targetDir);
+    if (note === undefined)
+        return false;
+    observations.push(`${note} -- left undetermined, not reported missing`);
+    // Called once per pack against the same path: record the note once.
+    if (!undetermined.includes(note))
+        undetermined.push(note);
+    return undefined;
 }
 /**
  * Index-level, adopt-mode-only facts about how a pack's wiring would land
  * against a real project's current `.claude/settings.json` and
  * `bin/lib/verify-steps.packs.json` -- never a verdict on whether it will
- * work, which is `/customize`'s Step 0 judgment call to make after reading
- * the project's real gate runner and hook config.
+ * work. That verdict is a judgment call for `/customize`'s Step 0 (the
+ * adopt-mode reconcile step in `/customize`) to make after reading the
+ * project's real gate runner and hook config. A path this process cannot
+ * reach (`EACCES`/`EPERM`/`ELOOP`) is observed with its errno, never as
+ * "not found"; nor is a dangling symlink or a file blocking an ancestor
+ * directory, which is also recorded once in `undetermined`. A
+ * `.claude/settings.json` that exists but cannot be read for a reason that
+ * is a property of the project's tree (`EACCES`/`EPERM`, `EISDIR`, `ENOENT`,
+ * `ELOOP`) is observed with its errno and also recorded once in
+ * `undetermined` -- adopt mode passes the survey's own list, so the report
+ * shows it; any other errno throws.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const observations = observeWiring(targetDir, pack.manifest, undetermined);
+ * ```
  */
-export function observeWiring(targetDir, manifest) {
+export function observeWiring(targetDir, manifest, undetermined = []) {
     const observations = [];
     const settingsPath = join(targetDir, ".claude", "settings.json");
-    if (!existsSync(settingsPath)) {
+    const settingsExists = existsOrObserve(settingsPath, targetDir, observations, undetermined);
+    if (settingsExists === false) {
         observations.push("no .claude/settings.json found");
     }
-    else {
-        const parsed = parseJsonc(readFileSync(settingsPath, "utf8"));
-        if (!parsed.ok || !isRecord(parsed.value)) {
+    else if (settingsExists) {
+        const content = readSettingsOrObserve(settingsPath, observations, undetermined);
+        const parsed = content === undefined ? undefined : parseJsonc(content);
+        if (parsed === undefined) {
+            // Unreadable -- already recorded as an observation.
+        }
+        else if (!parsed.ok || !isRecord(parsed.value)) {
             observations.push(".claude/settings.json exists but could not be parsed");
         }
         else {
@@ -172,14 +382,17 @@ export function observeWiring(targetDir, manifest) {
             }
         }
     }
-    if (existsSync(join(targetDir, ".claude", "settings.local.json"))) {
+    if (existsOrObserve(join(targetDir, ".claude", "settings.local.json"), targetDir, observations, undetermined) === true) {
         observations.push(".claude/settings.local.json is present and may shadow a merged hook entry");
     }
     if (manifest.wiring.verifySteps.length > 0) {
         const stepsPath = join(targetDir, "bin", "lib", "verify-steps.packs.json");
-        observations.push(existsSync(stepsPath)
-            ? "bin/lib/verify-steps.packs.json exists"
-            : "no bin/lib/verify-steps.packs.json found -- no bin/verify.mjs-shaped gate runner detected");
+        const stepsExist = existsOrObserve(stepsPath, targetDir, observations, undetermined);
+        if (stepsExist !== undefined) {
+            observations.push(stepsExist
+                ? "bin/lib/verify-steps.packs.json exists"
+                : "no bin/lib/verify-steps.packs.json found -- no bin/verify.mjs-shaped gate runner detected");
+        }
     }
     return observations;
 }

package/dist/palette.d.ts

@@ -0,0 +1,23 @@
+/**
+ * GENERATED FILE -- do not hand-edit. Run `node bin/build-design-tokens.mjs`
+ * to regenerate from design/source/dtcg (the vendored m3l-design tokens).
+ * `--check` (used by `pnpm verify`) fails instead of writing on drift.
+ * Source of truth: design/source/dtcg (DTCG 2025.10). See design/README.md.
+ */
+/** One role's resolved terminal color, per theme -- see term.ts's `paint()`. */
+export interface PaletteRoleColors {
+    readonly success: string;
+    readonly info: string;
+    readonly warning: string;
+    readonly danger: string;
+    readonly accent: string;
+    readonly secondary: string;
+}
+/** {@link PaletteRoleColors} for each theme -- see term.ts's `resolveThemeId()`. */
+export interface Palette {
+    readonly light: PaletteRoleColors;
+    readonly dark: PaletteRoleColors;
+}
+/** The resolved terminal palette, light and dark -- see term.ts's `paint()`. */
+export declare const PALETTE: Palette;
+//# sourceMappingURL=palette.d.ts.map

package/dist/palette.js

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/** The resolved terminal palette, light and dark -- see term.ts's `paint()`. */
+export const PALETTE = {
+    light: {
+        success: "#086d31",
+        info: "#065da0",
+        warning: "#7d4f0a",
+        danger: "#963730",
+        accent: "#692746",
+        secondary: "#554d50",
+    },
+    dark: {
+        success: "#89d298",
+        info: "#8ac3fe",
+        warning: "#ebb16c",
+        danger: "#fda297",
+        accent: "#d1789e",
+        secondary: "#cdc5c8",
+    },
+};
+//# sourceMappingURL=palette.js.map

package/dist/plugin.d.ts

@@ -1,22 +1,138 @@
+/**
+ * What an install wrote.
+ *
+ * @example
+ * ```ts
+ * import { installCustomizeSkill } from "./plugin.js";
+ *
+ * const { filesWritten } = installCustomizeSkill("/work/app");
+ * filesWritten.at(-1); // ".claude/skills/customize/SKILL.md"
+ * ```
+ */
 export interface InstallPluginResult {
+    /** Paths relative to the project root, in write order (`SKILL.md` last); empty when the destination already held this exact payload. */
     filesWritten: string[];
 }
 /**
  * Installs the skill into `<targetDir>/.claude/skills/customize/`. Used by
- * fresh-bootstrap mode, where the directory is always new.
+ * fresh-bootstrap mode, where the directory is normally new (`--force` may
+ * point it at a non-empty one or an earlier install). An earlier install
+ * that is already byte-identical to this payload is left untouched
+ * (`filesWritten` is empty); otherwise any existing `SKILL.md` is removed
+ * first, then each payload file is removed and recreated. A symlinked
+ * `.claude`, `.claude/skills` or `.claude/skills/customize` is refused, not
+ * routed around.
+ *
+ * @throws `Error` ("could not install the /customize skill ...", raw error
+ * as `cause`) on a missing or unreadable source file, a directory at any
+ * payload name, a payload name or existing file that cannot be `lstat`ed,
+ * or an existing regular file whose read fails with anything other than
+ * `EACCES`/`EPERM` (all before anything is removed or written), a symlinked
+ * or non-directory directory component, any fs failure, or a failed write
+ * -- after removing every file this call wrote. An existing regular file
+ * whose read fails with `EACCES` or `EPERM` is not a failure: it is replaced
+ * like any stale copy. Entries it replaced before the failure are not
+ * restored; the error names them. A failure to locate the default
+ * `sourceDir` is thrown the same way. The message ends, once, by saying to
+ * fix the cause (for a symlink: remove it), then retry
+ * the same command with `--fresh --force` added -- a plain re-run would
+ * adopt the now-non-empty target -- and nowhere in the error chain gives
+ * adopt mode's bare "re-run the CLI" advice.
+ *
+ * @example
+ * ```ts
+ * import { installCustomizeSkill } from "./plugin.js";
+ *
+ * installCustomizeSkill("/work/app").filesWritten.length; // 5
+ * ```
  */
 export declare function installCustomizeSkill(targetDir: string, sourceDir?: string): InstallPluginResult;
 type InstallLocation = "claude" | "groundwork" | "already-present";
+/**
+ * What the adopt-mode install did, and where.
+ *
+ * @example
+ * ```ts
+ * import { installCustomizeSkillGuarded } from "./plugin.js";
+ *
+ * const result = installCustomizeSkillGuarded("/work/app");
+ * if (result.fallbackReason !== undefined) console.log(result.fallbackReason);
+ * ```
+ */
 export interface GuardedInstallResult {
+    /** Paths relative to the project root, in write order (`SKILL.md` last); empty for `"already-present"`. */
     filesWritten: string[];
     location: InstallLocation;
+    /**
+     * Set on every `"groundwork"` result, and only then: why
+     * `.claude/skills/customize/` could not be used, naming the path
+     * responsible -- a symlinked or non-directory component, or the existing
+     * project entry under one of the skill's payload names.
+     */
+    fallbackReason?: string;
+    /**
+     * Set exactly when `fallbackReason` is: `"component"` when a
+     * `.claude`/`.claude/skills`/`.claude/skills/customize` component is a
+     * symlink or not a directory (no project-local copy of the skill exists),
+     * `"entry"` when a project-owned entry sits under one of the skill's
+     * payload names (a project copy exists, and is what a user would replace).
+     */
+    fallbackCause?: "entry" | "component";
 }
 /**
- * Adopt-mode install: purely additive, never overwrites. If the project
- * already has its own `.claude/skills/customize/SKILL.md` and its content
- * differs from what this CLI ships, the skill is written to
- * `.groundwork/customize/` instead -- reported in the adoption report
- * rather than silently overwriting whatever the project already had there.
+ * Adopt-mode install: purely additive, never overwrites or removes a project
+ * entry under `.claude/skills/customize/`.
+ *
+ * - If `.claude`, `.claude/skills` or `.claude/skills/customize` is a
+ *   symlink or not a directory, the skill is written to
+ *   `.groundwork/customize/` instead, `fallbackReason` names that path and
+ *   `fallbackCause` is `"component"` -- the entry (and any link target) is
+ *   left untouched.
+ * - Otherwise, if every payload file already there is a regular file
+ *   matching what this CLI ships byte-for-byte: with all five present the
+ *   result is `"already-present"` (nothing written); with no `SKILL.md` file
+ *   (none at all, or an install interrupted before writing it) the missing
+ *   files are written into `.claude/skills/customize/`, `SKILL.md` last,
+ *   never rewriting or removing the correct ones.
+ * - Anything else under a payload name (a differing file, a regular file
+ *   that cannot be read, a symlink -- dangling or not -- a directory, a
+ *   `SKILL.md` without its data; detected by `lstat`) is kept as the
+ *   project's own: the skill is written to `.groundwork/customize/` instead,
+ *   `fallbackReason` names that entry (saying so when it could not be read)
+ *   and `fallbackCause` is `"entry"`. Adopt mode never guesses at a project
+ *   entry it cannot compare, and the fallback does not guess either: it
+ *   leaves that entry exactly as it was. Claude Code does not load a skill
+ *   from there; the caller must say so.
+ *
+ * Writes into `.claude/skills/customize/` use `"wx"` only, so an entry that
+ * appears there mid-install fails the run (rolled back) rather than being
+ * replaced. Writes into the CLI-owned `.groundwork/customize/` replace that
+ * directory's payload files (any `SKILL.md` removed first, then each file
+ * removed and recreated with `"wx"`); a symlinked `.groundwork` or
+ * `.groundwork/customize`, or a directory at any payload name there, is
+ * refused, never routed around.
+ *
+ * @throws `Error` ("could not install the /customize skill ...", raw error
+ * as `cause`) on a missing or unreadable source file (before anything is
+ * written), a payload name under `.claude/skills/customize/` that cannot be
+ * `lstat`ed or read (a regular file there whose read is refused with
+ * `EACCES`/`EPERM` falls back instead; any other read failure throws before
+ * anything is written), any other fs failure while probing or writing, a
+ * symlinked `.groundwork`/`.groundwork/customize`, or a directory at a
+ * payload name there -- after removing every file this call wrote. A failed
+ * `.groundwork/customize/` install also names why the fallback was taken.
+ * A failure to locate the default `sourceDir` is thrown the same way. The
+ * message ends by
+ * saying to fix the cause (for a symlink: remove it) and re-run the CLI,
+ * once.
+ *
+ * @example
+ * ```ts
+ * import { installCustomizeSkillGuarded } from "./plugin.js";
+ *
+ * const { location } = installCustomizeSkillGuarded("/work/app");
+ * // "claude" | "groundwork" | "already-present"
+ * ```
  */
 export declare function installCustomizeSkillGuarded(targetDir: string, sourceDir?: string): GuardedInstallResult;
 export {};