auggy 0.3.0

package/src/cli/scaffold-skills.ts

@@ -0,0 +1,158 @@
+/**
+ * Scaffold-skill helpers — copy bundled `src/augments/<name>/skill/` folders
+ * into a scaffolded agent's `<agent-dir>/skills/<augment-name>/` directory,
+ * and render identity.md from the bundled template.
+ *
+ * Per ADR-025 (augment-as-folder + skill bundling) Decision 3 and ADR-030
+ * (model-facing skill surface separation): identity.md no longer carries
+ * the skill manifest. The runtime's `skills` augment surfaces the listing
+ * from each SKILL.md's YAML frontmatter; this module only handles disk-copy
+ * + template substitution for the three identity-level placeholders
+ * (AGENT_NAME, PURPOSE, OPERATOR_NAME).
+ */
+
+import { cpSync, existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Augment-name resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Map an augment `type` (the YAML `type:` field, e.g. `webFetch`) to the
+ * folder name under `src/augments/`. The folder convention is kebab-case;
+ * the type identifier is camelCase. This lookup is the inverse of the
+ * augment-resolver dispatch.
+ *
+ * Returned name doubles as the `<agent-dir>/skills/<name>/` directory name
+ * so the scaffolded layout matches what the runtime `skills` augment scans.
+ */
+const TYPE_TO_AUGMENT_FOLDER: Record<string, string> = {
+  filesystem: "filesystem",
+  layeredMemory: "layered-memory",
+  webFetch: "web-fetch",
+  orgContext: "org-context",
+  bash: "bash",
+  notify: "notify",
+  turnControl: "turn-control",
+  visitorAuth: "visitor-auth",
+  // Augments below intentionally have no skill folder today (no model-callable
+  // tools, transport-only, or legacy). Listed for completeness so a lookup
+  // never silently returns undefined for a known type.
+  fileMemory: "file-memory",
+  supabaseMemory: "supabase-memory",
+  budgets: "budgets",
+  webTransport: "web-transport",
+  telegramTransport: "telegram-transport",
+  // ADR-030: the 'skills' augment is the runtime skill surface itself; it
+  // carries no SKILL.md of its own (the augment IS the listing).
+  skills: "skills",
+};
+
+/** Return the augment folder name for a YAML `type:` value, or `null` if unknown. */
+export function augmentFolderForType(type: string): string | null {
+  return TYPE_TO_AUGMENT_FOLDER[type] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Bundled-skill source resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the on-disk location of the bundled `src/augments/<folder>/skill/`
+ * directory relative to this module. Returns `null` if the augment has no
+ * bundled skill folder.
+ */
+function bundledSkillDir(folder: string): string | null {
+  const dir = resolve(import.meta.dir, "../augments", folder, "skill");
+  return existsSync(dir) ? dir : null;
+}
+
+// ---------------------------------------------------------------------------
+// Skill copy
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy the bundled skill folder for the given augment type into the agent
+ * directory. No-op when the augment has no bundled skill (e.g. budgets,
+ * file-memory, transport-only augments, the `skills` augment itself) or when
+ * the source folder is not present on disk.
+ *
+ * Idempotent: re-running overwrites existing files (per ADR-025 Decision 2 —
+ * operators opt into updates by re-scaffolding).
+ */
+export function copyBundledSkill(type: string, agentDir: string): boolean {
+  const folder = TYPE_TO_AUGMENT_FOLDER[type];
+  if (!folder) return false;
+  const src = bundledSkillDir(folder);
+  if (!src) return false;
+  const dest = join(agentDir, "skills", folder);
+  cpSync(src, dest, { recursive: true });
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// identity.md template substitution
+// ---------------------------------------------------------------------------
+
+/**
+ * The on-disk path to the identity.md template shipped under
+ * `src/scaffold-templates/`. Resolved relative to this module so it works
+ * both from source (Bun) and from a bundle that preserves the layout.
+ */
+const IDENTITY_TEMPLATE_PATH = resolve(import.meta.dir, "../scaffold-templates/identity.md");
+
+/**
+ * Read the identity.md template once. The template is part of the source
+ * tree, never user-supplied, so failure to read it is a programming error.
+ */
+function readIdentityTemplate(): string {
+  return readFileSync(IDENTITY_TEMPLATE_PATH, "utf-8");
+}
+
+export interface IdentityTemplateValues {
+  /** The agent's name as written in agent.yaml. */
+  agentName: string;
+  /** A one-sentence agent purpose ("a helpful assistant" by default). */
+  purpose: string;
+  /** The operator's name ("the operator" by default). */
+  operatorName: string;
+}
+
+/**
+ * Render identity.md from the bundled template using the provided values.
+ *
+ * Substitution targets three placeholder tokens by exact name (`{AGENT_NAME}`,
+ * `{PURPOSE}`, `{OPERATOR_NAME}`) — not a generic `{...}` regex — so
+ * operator-supplied values containing literal braces pass through unmodified.
+ * Single-pass replacement means an operator-supplied value containing
+ * `{AGENT_NAME}` or any other placeholder is emitted verbatim and is NOT
+ * re-scanned by a subsequent substitution.
+ *
+ * Per ADR-030: the previous `{SKILL_MANIFEST}` placeholder is gone. Skill
+ * discovery is the runtime `skills` augment's responsibility, not the
+ * identity file's.
+ *
+ * Limitation: operator values land inside markdown text. An operator who
+ * names their agent something that looks like a heading (`# Sneaky`) will
+ * break the document's outline — but only for their own identity.md, with
+ * no security impact (security rules sit outside the substitution targets
+ * and the `{OPERATOR_NAME}` reference is inline prose, not a structural
+ * element). Documented for posterity; not mitigated at v1.0.
+ */
+export function renderIdentityFromTemplate(values: IdentityTemplateValues): string {
+  const template = readIdentityTemplate();
+
+  return template.replace(/\{(AGENT_NAME|PURPOSE|OPERATOR_NAME)\}/g, (match, token: string) => {
+    switch (token) {
+      case "AGENT_NAME":
+        return values.agentName;
+      case "PURPOSE":
+        return values.purpose;
+      case "OPERATOR_NAME":
+        return values.operatorName;
+      default:
+        return match;
+    }
+  });
+}

package/src/cli/scaffold.ts

@@ -0,0 +1,291 @@
+/**
+ * Scaffold — generates a new agent directory with auggy create.
+ *
+ * Creates the standard agent directory convention:
+ *   <name>/
+ *     agent.yaml         Config (source of truth) — uses `identity:` shorthand
+ *     .env               Secrets template (gitignored)
+ *     identity.md        Who the agent is — security rules + skill manifest
+ *     learned.md         What the agent has learned (mutable)
+ *     skills/            Skill folders (read-only fs mount), one per
+ *                        tool-providing augment, copied from src/augments/<name>/skill/
+ *     workspace/         Agent's mutable workspace
+ *     augments/          Custom augments directory
+ *     .gitignore         Ignores .env, workspace/, *.log, *.db, memory.sqlite
+ *
+ * Per ADR-025 (augment-as-folder + skill bundling) and the PR α foundation
+ * spec: scaffold copies bundled skills, uses the `identity:` YAML shorthand,
+ * includes layeredMemory by default, and writes identity.md from a template
+ * with the four security rules baked in.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { copyBundledSkill, renderIdentityFromTemplate } from "./scaffold-skills";
+
+export interface ScaffoldOptions {
+  /** Agent name. */
+  name: string;
+  /** Target directory (defaults to ./<name>). */
+  targetDir?: string;
+  /** Optional purpose string for the agent (default: "a helpful assistant"). */
+  purpose?: string;
+  /**
+   * Operator name used to populate the operator-identity reference in the
+   * scaffolded identity.md security rules and the agent.yaml `operators[]`
+   * array. Defaults to "the operator" — matches the security-eval test
+   * fixture's fallback behavior so non-interactive scaffolding stays
+   * compatible with the canonical eval suite.
+   */
+  operatorName?: string;
+}
+
+/** Default values used when prompts are skipped (non-interactive). */
+const DEFAULT_OPERATOR_NAME = "the operator";
+const DEFAULT_PURPOSE = "a helpful assistant";
+
+/**
+ * Scaffold a new agent directory.
+ * Throws if the target directory already exists.
+ */
+export function scaffoldAgent(opts: ScaffoldOptions): string {
+  const dir = resolve(opts.targetDir ?? `./${opts.name}`);
+
+  if (existsSync(dir)) {
+    throw new Error(`Directory already exists: ${dir}`);
+  }
+
+  const id = `aug1_${randomUUID()}`;
+  const purpose = opts.purpose ?? DEFAULT_PURPOSE;
+  const operatorName = opts.operatorName ?? DEFAULT_OPERATOR_NAME;
+
+  // The augment types this scaffold installs by default. Drives the bundled-
+  // skill copy (which copies SKILL.md files into <agent>/skills/<augment>/).
+  // The runtime `skills` augment surfaces them to the model from disk at
+  // every context() call — no longer threaded into identity.md per ADR-030.
+  const augmentTypes = [
+    "fileMemory", // identity (mounted via shorthand) + learned.md
+    "filesystem",
+    "layeredMemory",
+    "budgets",
+    "webFetch",
+    "turnControl",
+    "webTransport",
+  ];
+
+  // Tool-providing types whose bundled skills should be copied. Subset of
+  // augmentTypes — fileMemory / budgets / webTransport contribute no tools.
+  const skillProvidingTypes = augmentTypes.filter((t) =>
+    ["filesystem", "layeredMemory", "webFetch", "turnControl"].includes(t),
+  );
+
+  // Create directory structure.
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(join(dir, "skills"), { recursive: true });
+  mkdirSync(join(dir, "workspace"), { recursive: true });
+  mkdirSync(join(dir, "augments"), { recursive: true });
+
+  // Copy bundled skill folders for each tool-providing augment. Idempotent —
+  // re-running the scaffold overwrites; per ADR-025 Decision 2 operators opt
+  // into updates by re-scaffolding.
+  for (const type of skillProvidingTypes) {
+    copyBundledSkill(type, dir);
+  }
+
+  // Write identity.md from the bundled template (security rules only —
+  // skill manifest moved out per ADR-030).
+  writeFileSync(
+    join(dir, "identity.md"),
+    renderIdentityFromTemplate({
+      agentName: opts.name,
+      purpose,
+      operatorName,
+    }),
+  );
+
+  // Write learned.md (empty, agent appends as it learns).
+  writeFileSync(join(dir, "learned.md"), "");
+
+  // Write agent.yaml using the identity: shorthand (per α-5).
+  writeFileSync(join(dir, "agent.yaml"), agentYamlTemplate(id, opts.name, purpose, operatorName));
+
+  // Write .env with empty values — operator fills in secrets before first run.
+  writeFileSync(join(dir, ".env"), ENV_TEMPLATE);
+
+  // Write .gitignore.
+  writeFileSync(join(dir, ".gitignore"), GITIGNORE_TEMPLATE);
+
+  return dir;
+}
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a string as a YAML-safe scalar. Operator-supplied free-text values
+ * (purpose, operatorName) reach this function; without escaping, a value
+ * containing a quote, newline, or backslash would corrupt the generated
+ * agent.yaml. JSON-encoded strings are valid YAML scalars in flow shape,
+ * so JSON.stringify produces a double-quoted, escaped form that YAML parses
+ * back to the original string.
+ *
+ * The interactive `auggy create` flow already routes operator input through
+ * yaml.stringify; this helper closes the parallel gap in `scaffoldAgent`,
+ * the programmatic entry point used by tests and any third-party scaffolder.
+ */
+function yamlScalar(s: string): string {
+  return JSON.stringify(s);
+}
+
+function agentYamlTemplate(
+  id: string,
+  name: string,
+  purpose: string,
+  operatorName: string,
+): string {
+  return `# Agent configuration — the source of truth for this Auggy agent.
+# See docs at augment-1/docs/ for field reference.
+
+id: ${yamlScalar(id)}
+name: ${yamlScalar(name)}
+purpose: ${yamlScalar(purpose)}
+operators:
+  - ${yamlScalar(operatorName)}
+
+# identity shorthand — synthesizes a fileMemory@system entry from ./identity.md
+# at parse time. Operators wanting non-default options (e.g. mutable: true)
+# should drop this and add an explicit fileMemory augment instead.
+identity: ./identity.md
+
+engine:
+  provider: anthropic        # or: openai, openrouter
+  model: claude-sonnet-4-6   # openai: gpt-5 | openrouter: qwen/qwen3.5-397b-a17b
+  maxContextTokens: 200000   # for openrouter, set per-model — defaults vary
+  maxTokens: 4096            # sent as max_completion_tokens for openai/openrouter
+  # reasoningEffort: medium  # optional: none|minimal|low|medium|high|xhigh
+  # providerRouting:         # openrouter only — slugs not semantically validated
+  #   only: [OpenAI]
+  #   sort: price
+
+settings:
+  compactionStrategy: truncate
+  maxInferenceLoops: 10
+
+augments:
+  - name: learned
+    type: fileMemory
+    options:
+      label: learned
+      source: ./learned.md
+      mutable: true
+      origin: system
+      priority: high
+      placement: preamble
+      eviction: drop
+
+  - name: memory
+    type: layeredMemory
+    options:
+      backend: sqlite
+      namespace: ${yamlScalar(name)}
+      dbPath: ./memory.sqlite
+      retentionDays: 90
+
+  - name: budgets
+    type: budgets
+    options:
+      dbPath: ./budgets.db
+      caps:
+        public:
+          recognized:
+            maxTurnsPerThread: 20
+            maxTurnsPerDay: 50
+            maxUsdPerDay: 1
+          anonymous:
+            maxTurnsPerThread: 5
+      anonymousGlobalLimit: 30
+      dailyBudgetUsd: 5
+
+  - name: files
+    type: filesystem
+    options:
+      mounts:
+        - name: skills
+          path: ./skills
+          writable: false
+        - name: workspace
+          path: ./workspace
+          writable: true
+          deletable: true
+
+  # ADR-030: surfaces the skill manifest to the model (name + description from
+  # each SKILL.md's YAML frontmatter). Activation is fs_read via the filesystem
+  # mount above. Required for the model to discover its skills.
+  - name: skills
+    type: skills
+    options:
+      dir: ./skills
+
+  - name: fetch
+    type: webFetch
+    options:
+      timeoutMs: 15000
+
+  - name: turn-control
+    type: turnControl
+
+  - name: web
+    type: webTransport
+    options:
+      port: 8080
+      auth:
+        type: bearer
+        token: \${AUGGY_WEB_TOKEN}
+      visitorTokens:
+        # signingKey is NOT set here — visitorAuth is the single source of truth
+        # and the resolver injects it at boot. Setting it here would trigger the
+        # duplicate-key warning on every start.
+        agentBinding: \${AUGGY_AGENT_ID}
+`;
+}
+
+const ENV_TEMPLATE = `# Auggy agent secrets — this file is gitignored.
+# Add your API keys and tokens here. Only the key matching the
+# configured engine.provider in agent.yaml needs to be filled in.
+
+ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# OPENROUTER_API_KEY=
+AUGGY_WEB_TOKEN=
+# Uncomment when visitorAuth augment is added (signingKey is owned by visitorAuth,
+# injected into webTransport at boot — no need to set it in webTransport's config).
+# VISITOR_SIGNING_KEY=
+# Stable identifier for visitor-auth tokens — must be unique per agent
+# if multiple agents share VISITOR_SIGNING_KEY (otherwise tokens are
+# cross-replayable). Pattern: short slug or the agent's id.
+AUGGY_AGENT_ID=
+# SUPABASE_URL=
+# SUPABASE_SERVICE_KEY=
+`;
+
+const GITIGNORE_TEMPLATE = `.env
+.env.local
+workspace/
+*.log
+*.err
+node_modules/
+memory.sqlite
+memory.sqlite-journal
+memory.sqlite-wal
+memory.sqlite-shm
+memory.db
+memory.db-journal
+memory.db-wal
+memory.db-shm
+budgets.db
+budgets.db-journal
+budgets.db-wal
+budgets.db-shm
+`;

package/src/cli/skill-frontmatter.ts

@@ -0,0 +1,51 @@
+/**
+ * Skill frontmatter reader for ADR-030.
+ *
+ * Reads the YAML frontmatter block from a SKILL.md file. Returns null when the
+ * frontmatter is absent, malformed, or missing required fields — callers
+ * always have a graceful-fallback path (skill is not listed) rather than a
+ * crash. The boot-time skill validator (`skill-validator.ts`) catches the
+ * "tool-providing augment with no parseable frontmatter" case separately.
+ *
+ * Source of truth for skill `name` + `description` per agentskills.io.
+ */
+
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+
+export interface SkillFrontmatter {
+  name: string;
+  description: string;
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+
+export function parseSkillFrontmatter(content: string): SkillFrontmatter | null {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+  const raw = match[1]!;
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch {
+    return null;
+  }
+
+  if (parsed === null || typeof parsed !== "object") return null;
+  const obj = parsed as Record<string, unknown>;
+  if (typeof obj.name !== "string" || obj.name.length === 0) return null;
+  if (typeof obj.description !== "string" || obj.description.length === 0) return null;
+
+  return { name: obj.name, description: obj.description };
+}
+
+export function readSkillFrontmatter(path: string): SkillFrontmatter | null {
+  let content: string;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+  return parseSkillFrontmatter(content);
+}

package/src/cli/skill-validator.ts

@@ -0,0 +1,151 @@
+/**
+ * Boot-time skill validator.
+ *
+ * Per ADR-025 Decision 5 + PR α foundation spec §H. After augments are
+ * resolved at agent boot, scan: for each augment that contributes tools
+ * to the model but lacks a corresponding `<agent-dir>/skills/<augment-
+ * folder>/SKILL.md`, emit a one-line warning. Operators see the gap at
+ * startup, not in production-failure mode where the model guesses.
+ *
+ * Discriminator (model-perspective): an augment contributes tools if EITHER
+ *  (a) `augment.tools.length > 0` — tools declared on the factory return,
+ *  (b) `augment.memory?.owns?.kind === "namespace"` — namespace memory
+ *      provider; the kernel-synthesized memory-bus exposes 5 generic
+ *      tools (memory_read / memory_write / memory_search / memory_list /
+ *      memory_forget — see src/memory/tools.ts) keyed off its prefix.
+ *
+ * The model can't tell where the tools came from; from its perspective
+ * both routes produce model-callable tools that need teaching. The strict
+ * spec wording ("non-empty tools[]") would have missed (b), and (b) is
+ * the most common real case — layered-memory is the default-scaffold
+ * memory augment.
+ *
+ * Tool-less augments (fileMemory + supabaseMemory static providers,
+ * transports, budgets) intentionally do NOT trigger the warning — they
+ * contribute only `context()` blocks or admission gates, no model-
+ * callable tools.
+ *
+ * Warning, not error. The agent still boots successfully. An opt-out
+ * flag is deferred per spec §Decision 7.
+ */
+
+/**
+ * Number of tools the kernel memory-bus synthesizes for a namespace
+ * memory provider. Source: src/memory/tools.ts (memory_read / memory_write
+ * / memory_search / memory_list / memory_forget). If that surface changes,
+ * update this constant — tests asserting the count will catch drift.
+ */
+const NAMESPACE_MEMORY_TOOL_COUNT = 5;
+
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import type { Augment } from "../types";
+import type { AugmentConfig } from "./types";
+import { augmentFolderForType } from "./scaffold-skills";
+
+/**
+ * Filesystem probe outcome for the skill SKILL.md file.
+ *
+ * - "present": file exists and is readable as a regular file.
+ * - "missing": parent dir is reachable; SKILL.md is absent (ENOENT). The
+ *   normal "operator hasn't installed this skill" case.
+ * - "unreadable": stat surfaced a non-ENOENT error (e.g. EACCES). The
+ *   skill MAY be present on disk but the runtime cannot confirm; surfaced
+ *   as a different warning class so an operator with a misconfigured
+ *   permissions setup doesn't get fooled into thinking the skill is there.
+ */
+type SkillProbe =
+  | { kind: "present" }
+  | { kind: "missing" }
+  | { kind: "unreadable"; reason: string };
+
+function probeSkillFile(skillPath: string): SkillProbe {
+  try {
+    const stats = statSync(skillPath);
+    if (stats.isFile()) return { kind: "present" };
+    // SKILL.md exists but is a directory or other non-file — surface as
+    // unreadable rather than silently treating as present. Rare misconfig.
+    return { kind: "unreadable", reason: `path is not a regular file` };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { kind: "missing" };
+    return {
+      kind: "unreadable",
+      reason: `${code ?? "unknown"}: ${(err as Error).message}`,
+    };
+  }
+}
+
+/**
+ * Scan resolved augments paired with their source configs and warn for
+ * any tool-providing augment whose skill is missing or unreadable. Walks
+ * configs and augments in lockstep — `resolveAugments` preserves order
+ * and never drops entries, so index alignment is exact.
+ *
+ * Hook point: called from `resolveAugments` after all augment factories
+ * have run, so the agent's tool surface is finalized before the warning
+ * decision is made.
+ */
+export function validateBundledSkills(
+  configs: AugmentConfig[],
+  augments: Augment[],
+  agentDir: string,
+): void {
+  // Defensive: if the caller passed mismatched arrays, skip validation
+  // entirely rather than emit confusing warnings against the wrong
+  // augment. resolveAugments today always produces matched pairs.
+  if (configs.length !== augments.length) return;
+
+  for (let i = 0; i < augments.length; i++) {
+    const aug = augments[i]!;
+    const cfg = configs[i]!;
+
+    const factoryToolCount = aug.tools?.length ?? 0;
+    const isNamespaceMemory = aug.memory?.owns?.kind === "namespace";
+    const toolCount = factoryToolCount + (isNamespaceMemory ? NAMESPACE_MEMORY_TOOL_COUNT : 0);
+    if (toolCount === 0) continue;
+
+    // Custom augments (operator-authored) do not have a bundled skill folder
+    // by convention; the operator owns their own teaching. Don't warn —
+    // the `auggy add-skill` command is built-in-only too.
+    if (cfg.type === "custom") continue;
+
+    const folder = augmentFolderForType(cfg.type);
+    if (!folder) {
+      // Unknown built-in type. resolveAugments would have thrown earlier;
+      // this branch only fires if the type-to-folder map drifts from
+      // the resolver's switch. Emit a diagnostic so the drift is visible.
+      console.warn(
+        `[augment-resolver] augment "${aug.name}" (type "${cfg.type}") exposes ${toolCount} ` +
+          `tool${toolCount === 1 ? "" : "s"} but has no folder mapping in scaffold-skills. ` +
+          `Skill validation skipped — file an issue if this augment ships skill content.`,
+      );
+      continue;
+    }
+
+    const skillPath = join(agentDir, "skills", folder, "SKILL.md");
+    const probe = probeSkillFile(skillPath);
+    if (probe.kind === "present") continue;
+
+    if (probe.kind === "missing") {
+      console.warn(
+        `[augment-resolver] augment "${folder}" exposes ${toolCount} tool${
+          toolCount === 1 ? "" : "s"
+        } with no skill mounted at\n` +
+          `  ${skillPath}. Model will guess at tool usage.\n` +
+          `  Run \`auggy add-skill ${folder}\` to install the bundled teaching, OR copy\n` +
+          `  src/augments/${folder}/skill/* into the agent's skills/${folder}/ directory.`,
+      );
+      continue;
+    }
+
+    // probe.kind === "unreadable"
+    console.warn(
+      `[augment-resolver] augment "${folder}" exposes ${toolCount} tool${
+        toolCount === 1 ? "" : "s"
+      } and a skill file at\n` +
+        `  ${skillPath} is unreadable (${probe.reason}).\n` +
+        `  Skill teaching cannot be confirmed; check filesystem permissions.`,
+    );
+  }
+}