@really-knows-ai/foundry 3.0.1 → 3.0.2

package/dist/.opencode/plugins/foundry-tools/config-law-tools.js

@@ -38,73 +38,47 @@ function findLawEnd(lines, startIdx) {
   return lines.length;
 }
 
-// Extract full markdown for a single law from file content
 function extractLawMarkdown(content, lawId) {
   const lines = content.split('\n');
   const startIdx = findLawStart(lines, lawId);
-
   if (startIdx < 0) return null;
-
   const endIdx = findLawEnd(lines, startIdx);
   const lawLines = lines.slice(startIdx, endIdx);
-  
-  while (lawLines.length > 0 && lawLines[lawLines.length - 1] === '') {
-    lawLines.pop();
-  }
-  
+  while (lawLines.length > 0 && lawLines[lawLines.length - 1] === '') lawLines.pop();
   return lawLines.join('\n') + '\n';
 }
 
 async function searchGlobalLaws(io, foundryDir, lawId) {
   const globalLawsDir = join(foundryDir, 'laws');
-  if (!(await io.exists(globalLawsDir))) {
-    return null;
-  }
-
+  if (!(await io.exists(globalLawsDir))) return null;
   const files = await io.readDir(globalLawsDir);
   for (const file of files) {
     if (!file.endsWith('.md')) continue;
     const path = join(globalLawsDir, file);
     const content = await io.readFile(path);
-    if (contentContainsLaw(content, lawId)) {
-      return { path, fullMarkdown: content, source: 'global' };
-    }
+    if (contentContainsLaw(content, lawId)) return { path, fullMarkdown: content, source: 'global' };
   }
-
   return null;
 }
 
 async function searchTypeSpecificLaws(io, foundryDir, lawId) {
   const artefactsDir = join(foundryDir, 'artefacts');
-  if (!(await io.exists(artefactsDir))) {
-    return null;
-  }
-
+  if (!(await io.exists(artefactsDir))) return null;
   const types = await io.readDir(artefactsDir);
   for (const typeId of types) {
     const typeLawsPath = join(artefactsDir, typeId, 'laws.md');
     if (!(await io.exists(typeLawsPath))) continue;
-
     const content = await io.readFile(typeLawsPath);
-    if (contentContainsLaw(content, lawId)) {
-      return { path: typeLawsPath, fullMarkdown: content, source: `type:${typeId}` };
-    }
+    if (contentContainsLaw(content, lawId)) return { path: typeLawsPath, fullMarkdown: content, source: `type:${typeId}` };
   }
-
   return null;
 }
 
 async function findLawByID(io, foundryDir, lawId) {
-  let result = await searchGlobalLaws(io, foundryDir, lawId);
-  if (result) {
-    return { found: true, ...result };
-  }
-
-  result = await searchTypeSpecificLaws(io, foundryDir, lawId);
-  if (result) {
-    return { found: true, ...result };
-  }
-
+  const global = await searchGlobalLaws(io, foundryDir, lawId);
+  if (global) return { found: true, ...global };
+  const typeSpec = await searchTypeSpecificLaws(io, foundryDir, lawId);
+  if (typeSpec) return { found: true, ...typeSpec };
   return { found: false };
 }
 
@@ -204,82 +178,92 @@ function computeTargetPath(target) {
 
 // --- add law executor --------------------------------------------------------
 
+function extractLawId(body) {
+  const match = body.match(/^## ([^\s]+)/m);
+  return match ? match[1] : null;
+}
+
+async function checkExistingLaw(io, path, lawId) {
+  if (!(await io.exists(path))) return { existedBefore: false, priorContent: null };
+  const priorContent = await io.readFile(path);
+  if (contentContainsLaw(priorContent, lawId)) {
+    return { error: `law id "${lawId}" already exists in ${path}; use foundry_config_edit_law to update it` };
+  }
+  return { existedBefore: true, priorContent };
+}
+
 async function validateAddLawPrerequisites(io, args) {
   const targetError = validateAddLawTarget(args.target);
-  if (targetError) {
-    return { error: targetError };
-  }
+  if (targetError) return { error: targetError };
 
   const path = computeTargetPath(args.target);
   const validation = await validateLaw({ body: args.body, io });
-  if (!validation.ok) {
-    return validation;
-  }
+  if (!validation.ok) return validation;
 
-  if (await io.exists(path)) {
-    return {
-      ok: false,
-      errors: [`${path} already exists; use foundry_config_edit_law to update an existing law in place`],
-    };
-  }
+  const lawId = extractLawId(args.body);
+  if (!lawId) return { error: 'could not determine law id from body (expected "## <law-id>" heading)' };
+
+  const existing = await checkExistingLaw(io, path, lawId);
+  if (existing.error) return { error: existing.error };
+  return { ok: true, path, lawId, ...existing };
+}
+
+function formatAddLawError(err) {
+  return err instanceof UnexpectedFilesError
+    ? JSON.stringify({ error: err.message, affected_files: err.files })
+    : errorJson(err);
+}
 
-  return { ok: true, path };
+function buildNextContent(existedBefore, priorContent, body) {
+  return existedBefore ? priorContent.trimEnd() + '\n\n' + body.trimStart() : body;
+}
+
+async function rollbackAddLaw(io, path, existedBefore, priorContent) {
+  if (existedBefore) await io.writeFile(path, priorContent);
+  else await io.rm(path);
 }
 
 async function executeAddLaw(args, context) {
   const io = makeAsyncIO(context.worktree);
   const execFile = makeExecFile(context.worktree);
+  let path, existedBefore, priorContent;
 
   try {
     const prereq = await validateAddLawPrerequisites(io, args);
-    if (prereq.error) {
-      return JSON.stringify({ ok: false, errors: [prereq.error] });
-    }
-    if (!prereq.ok) {
-      return JSON.stringify(prereq);
-    }
+    if (prereq.error) return JSON.stringify({ ok: false, errors: [prereq.error] });
+    if (!prereq.ok) return JSON.stringify(prereq);
 
-    const path = prereq.path;
+    ({ path, existedBefore, priorContent } = prereq);
+    const nextContent = buildNextContent(existedBefore, priorContent, args.body);
 
     await io.mkdirp(dirname(path));
-    await io.writeFile(path, args.body);
+    await io.writeFile(path, nextContent);
 
     const sha = commitWithPolicy({
       message: `config: add law ${args.name}\n\nvia foundry_config_add_law`,
       allowedPatterns: ['foundry/**'],
       execFile,
     });
-
     return JSON.stringify({ ok: true, path, sha });
   } catch (err) {
-    if (err instanceof UnexpectedFilesError) {
-      return JSON.stringify({ error: err.message, affected_files: err.files });
-    }
-    return errorJson(err);
+    if (path) await rollbackAddLaw(io, path, existedBefore, priorContent);
+    return formatAddLawError(err);
   }
 }
 
 // --- helper for preserving sibling laws -------------------------------------------------------
 
-// Replace a law in file content while preserving other laws
 function replaceLawInContent(content, lawId, newLawMarkdown) {
   const lines = content.split('\n');
   const startIdx = findLawStart(lines, lawId);
   if (startIdx < 0) return content.trimEnd() + '\n\n' + newLawMarkdown;
-  
   const endIdx = findLawEnd(lines, startIdx);
   const before = lines.slice(0, startIdx);
   const after = lines.slice(endIdx);
-  
-  // Trim trailing empty lines from before
   const beforeEnd = before.findLastIndex(l => l !== '') + 1;
   before.length = beforeEnd;
-  
-  // Trim leading empty lines from after  
   const afterStart = after.findIndex(l => l !== '');
   if (afterStart > 0) after.splice(0, afterStart);
-  
-  // newLawMarkdown includes trailing newline; split and rejoin without final empty string
   const newLines = newLawMarkdown.trimEnd().split('\n');
   return before.concat(newLines, after).join('\n') + '\n';
 }

package/dist/.opencode/plugins/foundry-tools/validate-tools.js

@@ -52,7 +52,7 @@ async function executeValidator(expanded, worktree, patterns) {
  *   JSON or missing required fields, `pattern-mismatch` for files that
  *   didn't match the artefact type's `file-patterns`.
  */
-async function runValidators(laws, patterns, patternSubstitution, worktree) {
+async function runValidators(laws, patterns, substitutions, worktree) {
   const results = {
     validatorsRun: 0,
     items: [],
@@ -61,7 +61,7 @@ async function runValidators(laws, patterns, patternSubstitution, worktree) {
 
   for (const law of laws) {
     if (!law.validators || law.validators.length === 0) continue;
-    await runLawValidators(law, patterns, patternSubstitution, worktree, results);
+    await runLawValidators(law, patterns, substitutions, worktree, results);
   }
 
   return results;
@@ -70,15 +70,15 @@ async function runValidators(laws, patterns, patternSubstitution, worktree) {
 /**
  * Run validators for a single law.
  */
-async function runLawValidators(law, patterns, patternSubstitution, worktree, results) {
+async function runLawValidators(law, patterns, substitutions, worktree, results) {
   for (const validator of law.validators) {
-    // Skip validators if pattern substitution is empty (no matching files)
-    // Self-resolving validators (npm test, tsc) omit {pattern}, so they still run
-    if (patternSubstitution === '' && validator.command.includes('{pattern}')) {
+    // Skip iff command uses {files} and there are no matching files.
+    // {pattern}-only and verbatim commands always run.
+    if (substitutions.files === '' && /(?:^|\s)\{files\}(?=\s|$)/.test(validator.command)) {
       continue;
     }
     results.validatorsRun++;
-    const expanded = expandValidatorCommand(validator.command, patternSubstitution);
+    const expanded = expandValidatorCommand(validator.command, substitutions);
     const parseResult = await executeValidator(expanded, worktree, patterns);
     collectValidatorResult(parseResult, law.id, validator.id, results);
   }
@@ -160,8 +160,11 @@ async function performValidation(args, context) {
  */
 async function runValidatorsAndReport(laws, patterns, worktree) {
   const expandedFiles = await expandPatterns(patterns, worktree);
-  const patternSubstitution = expandedFiles.map(shellQuote).join(' ');
-  const results = await runValidators(laws, patterns, patternSubstitution, worktree);
+  const substitutions = {
+    pattern: patterns.map(shellQuote).join(' '),
+    files: expandedFiles.map(shellQuote).join(' '),
+  };
+  const results = await runValidators(laws, patterns, substitutions, worktree);
 
   return JSON.stringify({
     ok: results.errors.length === 0,
@@ -235,29 +238,34 @@ async function expandPatterns(patterns, worktree) {
 }
 
 /**
- * Expand validator command by replacing {pattern} placeholder.
+ * Expand validator command by replacing {pattern} and {files} placeholders.
+ *
+ * - {pattern} → space-separated, shell-quoted globs from the artefact
+ *   type's `file-patterns:` array (e.g. "'haikus/*.md' 'drafts/*.md'").
+ * - {files}   → space-separated, shell-quoted matching file paths in the
+ *   worktree (e.g. "'haikus/one.md' 'haikus/two.md'").
  *
- * Only replaces {pattern} when it appears as a standalone token bounded by
- * whitespace or string start/end. This allows self-resolving validators
- * (e.g., npm test, tsc --noEmit) to omit the placeholder without risk of
- * accidental substitution if they contain the literal text "{pattern}" as part
- * of another string.
+ * Both placeholders are recognised only as standalone tokens, bounded
+ * by whitespace or start/end of string. Surrounding single or double
+ * quotes around the placeholder are stripped first so authors can
+ * write `rg "{pattern}"` for readability.
  *
- * @param {string} command - The validator command
- * @param {string} patternSubstitution - Shell-quoted file paths, space-separated
- * @returns {string} The expanded command
+ * @param {string} command
+ * @param {{ pattern: string, files: string }} substitutions
+ * @returns {string}
  */
-export function expandValidatorCommand(command, patternSubstitution) {
-  // First strip surrounding quotes around {pattern} to handle cases like
-  // rg "{pattern}" where authors add quotes for readability
-  const cmd = command
+export function expandValidatorCommand(command, { pattern, files }) {
+  let cmd = command
     .replace(/"\{pattern\}"/g, '{pattern}')
-    .replace(/'\{pattern\}'/g, '{pattern}');
+    .replace(/'\{pattern\}'/g, '{pattern}')
+    .replace(/"\{files\}"/g, '{files}')
+    .replace(/'\{files\}'/g, '{files}');
 
-  // Only substitute {pattern} when it appears as a standalone token
-  // (bounded by whitespace or start/end of string)
-  return cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) => {
-    const leadingSpace = match.startsWith('{') ? '' : ' ';
-    return leadingSpace + patternSubstitution;
-  });
+  cmd = cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? pattern : ' ' + pattern);
+
+  cmd = cmd.replace(/(?:^|\s)\{files\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? files : ' ' + files);
+
+  return cmd;
 }

package/dist/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## [3.0.2] - 2026-05-11
+
+A documentation and tool-correctness patch driven by a failing
+haiku-flow setup session. Closes the loop on the laws-with-validators
+migration: the validator contract is now fully documented in
+`add-law`; the `add_law` tool appends additional laws to an existing
+file and rolls back its file write when the commit fails;
+`init-foundry` seeds a `node_modules/` ignore so npm-installed
+validator dependencies never collide with the config-tier write
+guard.
+
+### Validator contract is canonical in `add-law`
+
+- `add-law` SKILL.md gains a **§7a. Validator contract** that covers
+  the JSONL output shape (`file`, `text` required; `location`,
+  `severity` optional), command placeholders, working directory, skip
+  rule, and a worked Node example. Authors no longer need to read
+  plugin source to write a validator.
+- `add-artefact-type` step 5 drops its half-duplicate contract and
+  cross-references `add-law` §7a. Step 1 and step 4 now make clear
+  that the frontmatter `name:` field equals the artefact type's id
+  (lowercase, hyphenated); human-readable labels go in the
+  `## Definition` prose. Step 9 reflects the new append-aware
+  `add_law`.
+
+### Validator command placeholders split
+
+- `{pattern}` now renders the artefact type's `file-patterns:` as
+  space-separated, shell-quoted globs (e.g.
+  `'haikus/*.md' 'drafts/*.md'`). Use it when a validator does its
+  own globbing or accepts globs directly (e.g. `rg --glob`).
+- `{files}` renders the matching files in the worktree as
+  space-separated, shell-quoted paths. Use it when the validator
+  takes an explicit list of file paths.
+- A validator is skipped iff its command contains `{files}` and there
+  are no matching files. `{pattern}`-only and verbatim commands
+  always run.
+- **Migration:** any existing validator authored against the prior
+  semantics (where `{pattern}` substituted expanded paths) must be
+  updated to use `{files}` instead. Foundry was tagged 3.0.1 only
+  12 hours before this release; no migration helper is provided.
+
+### `foundry_config_add_law` correctness
+
+- The tool now appends a new law to an existing `laws.md` instead of
+  erroring on file-exists. It only errors when a law with the same
+  id is already present in the file — in that case the caller
+  switches to `foundry_config_edit_law`.
+- File writes are atomic with the commit. If the commit fails (most
+  commonly `unexpected_files`), the tool restores `laws.md` to its
+  prior content (or deletes it if it didn't exist before the call).
+  This eliminates the orphaned-file state that previously broke the
+  next call with "already exists".
+
+### `init-foundry` seeds `node_modules/`
+
+- `.gitignore` now starts with `.snapshots/`, `node_modules/`, and
+  `.DS_Store`. The new entry stops `npm install` from immediately
+  blocking every config-tier tool with `unexpected_files`.
+
+### Migration
+
+- Update any validator commands that used `{pattern}` for file
+  expansion to use `{files}` instead.
+- No action needed for projects already on 3.0.1 that have not yet
+  authored validators using `{pattern}`.
+- Existing projects can add `node_modules/` to `.gitignore` by hand;
+  the `init-foundry` change only affects newly-initialised projects.
+
 ## [3.0.1] - 2026-05-11
 
 A documentation and cleanup patch. No runtime behaviour change. `quench`

package/dist/skills/add-artefact-type/SKILL.md

@@ -42,10 +42,12 @@ Before running this skill, verify all three of the following:
 ### 1. Gather basics
 
 From the user's prompt, establish:
-- `id` — lowercase, hyphenated identifier
-- `name` — human-readable name
-- `file-patterns` — glob patterns for files this type produces (forge's write scope is exactly these patterns)
-- A prose description of what this artefact type is
+- `id` — lowercase, hyphenated identifier (e.g. `haiku`). The
+  frontmatter `name:` field must equal this id; any human-readable
+  label goes in the `## Definition` prose, not in frontmatter.
+- `file-patterns` — glob patterns for files this type produces
+  (forge's write scope is exactly these patterns).
+- A prose description of what this artefact type is.
 
 If any of these are missing, ask.
 
@@ -87,7 +89,7 @@ Present the definition to the user:
 
 ```markdown
 ---
-name: <name>
+name: <id>
 file-patterns:
   - "<pattern>"
 ---
@@ -97,6 +99,10 @@ file-patterns:
 <description>
 ```
 
+The `name:` value must exactly match the artefact type's `id`
+(lowercase, hyphenated). If you want a human-readable label, put it
+in the `## Definition` prose.
+
 Ask: does this capture the artefact type correctly?
 
 ### 5. Laws (optional)
@@ -110,22 +116,18 @@ If yes, walk through each law using the same format as `add-law`:
 - Check for conflicts with global laws and any existing type-specific laws
 - Confirm with the user
 
-Each law may declare an optional `validators:` block. Include validators only when a deterministic check is needed. The format matches `add-law`:
-
-```markdown
-## <law-id>
-
-<What this law checks — one or two sentences.>
-
-validators:
-  - id: validator-id
-    command: ./script.sh
-    failure-means: (optional description)
-```
-
-The `validators` block is optional. When present, `quench` runs each validator for this law. Validator scripts live within the artefact type directory (e.g., `foundry/artefacts/<type>/check-foo.mjs`).
+Each law may declare an optional `validators:` block; the YAML shape,
+JSONL output contract, `{pattern}` / `{files}` placeholders, skip
+rule, working directory, and a worked example are documented once in
+the `add-law` skill under **§7a. Validator contract**. Authors of
+type-specific laws must follow that contract — do not invent a
+different one here.
 
-**Use existing libraries:** Before writing custom validation logic, search npm for well-tested libraries that solve the problem (e.g., `syllable` for syllable counting, `natural` for NLP tasks). Hand-rolled heuristics are fragile — prefer battle-tested packages. Install them as project dependencies.
+**Use existing libraries:** Before writing custom validation logic,
+search npm for well-tested libraries that solve the problem (e.g.
+`syllable` for syllable counting, `natural` for NLP tasks).
+Hand-rolled heuristics are fragile — prefer battle-tested packages.
+Install them as project dependencies.
 
 Check the project's `package.json` for `"type": "module"`:
 - If ESM (`"type": "module"`): use `import` syntax, or name scripts with `.mjs` extension
@@ -177,7 +179,12 @@ Show the user the resulting commit hash from the response.
 
 ### 9. Add laws file (if defined)
 
-The create tool writes only `definition.md`. If you drafted any type-specific laws in step 5, append them to `foundry/artefacts/<id>/laws.md` by hand on this same `config/*` branch (use the `Edit` tool to create the file) and commit that as a separate microcommit.
+If you drafted any type-specific laws in step 5, add them via
+`foundry_config_add_law` (one call per law) with
+`target: { kind: "type-specific", typeId: "<id>" }`. The first call
+creates `foundry/artefacts/<id>/laws.md`; subsequent calls append to
+that same file. Each call produces its own microcommit. See the
+`add-law` skill for the full protocol.
 
 ### 10. Confirm
 

package/dist/skills/add-law/SKILL.md

@@ -71,7 +71,9 @@ The `law-id` (heading) should be:
 - Short but descriptive
 - Unique across all laws (global and type-specific)
 
-The `validators:` block is optional. Include it only if you want to add validation commands for this law.
+The `validators:` block is optional. Include it only when a
+deterministic check can decide pass/fail. See **Validator contract**
+below for the exact shape a validator command must satisfy.
 
 ### 3. Check for conflicts
 
@@ -142,7 +144,11 @@ The tool:
 - writes the law file at the path determined by `target`;
 - produces one git commit on the current `config/*` branch.
 
-If the tool returns `{ ok: false, errors }` because the target file already exists, use `foundry_config_edit_law({ id: "<law-id>", body: "<updated-body>" })` to modify the law.
+The tool appends to an existing `laws.md` automatically when the
+new `## <law-id>` heading is not already present. It only errors when
+a law with the same id is already in the file — in that case use
+`foundry_config_edit_law({ id: "<law-id>", body: "<updated-body>" })`
+to modify the existing law in place.
 
 Show the user the resulting commit hash from the response.
 
@@ -150,6 +156,111 @@ Show the user the resulting commit hash from the response.
 
 After the file is created, confirm the law id is unique across all law files. If a collision exists, ask the user to rename and edit by hand on this branch.
 
+### 7a. Validator contract
+
+A law's `validators:` entries declare CLI commands that `quench` runs
+during a cycle. The plugin parses each command's stdout as **JSONL**
+(one JSON object per line). Authors must follow this contract exactly;
+nothing in plugin source needs to be read.
+
+#### Output format (stdout, parsed as JSONL)
+
+One JSON object per line. Empty lines are ignored. Required fields:
+
+- `file` *(string)* — path of the offending file, relative to the
+  worktree root. Must match at least one of the artefact type's
+  `file-patterns:`; otherwise the line becomes a validator-level
+  error, not feedback.
+- `text` *(string)* — the feedback message.
+
+Optional fields:
+
+- `location` *(string, e.g. `"3:1"`)* — line:column reference,
+  prepended to `text` as `file:location — text`.
+- `severity` *(string, e.g. `"error"` or `"warning"`)* — prepended to
+  `text` as `[severity] file:location — text` (or `[severity] file —
+  text` when no `location`).
+
+Anything else on the line is preserved verbatim on the parsed item.
+The validator's exit code is **ignored** — the parser reads stdout
+either way, and falls back to stderr when stdout is empty (so tools
+like `rg` that exit non-zero on hits still work).
+
+#### Command placeholders
+
+Inside `command:`, two placeholders may appear, alone, together, or
+not at all. They are recognised only as standalone tokens (bounded by
+whitespace or string start/end). Authors may wrap a placeholder in
+single or double quotes for readability — surrounding quotes are
+stripped before substitution.
+
+- `{pattern}` → the artefact type's `file-patterns:` rendered as
+  space-separated, shell-quoted globs (e.g.
+  `'haikus/*.md' 'drafts/*.md'`). Use this when the validator does
+  its own globbing or accepts globs directly (e.g. `rg --glob`).
+- `{files}` → the matching files in the worktree, rendered as
+  space-separated, shell-quoted paths (e.g.
+  `'haikus/one.md' 'haikus/two.md'`). Use this when the validator
+  takes an explicit list of file paths.
+
+A command with neither placeholder runs verbatim — useful for
+self-resolving validators such as `npm test`, `tsc --noEmit`, or
+`pnpm run lint`.
+
+#### Skip rule
+
+A validator is skipped iff its command contains `{files}` and there
+are no matching files in the worktree. Commands using `{pattern}` only,
+or no placeholders at all, always run.
+
+#### Working directory
+
+Validators run with `cwd` set to the worktree root, so root-level
+`node_modules/`, `package.json`, and project tooling all resolve
+normally. Do not assume the validator runs from inside the artefact
+type's directory.
+
+#### Worked example
+
+A validator that checks each `.md` file in `haikus/` has exactly three
+non-empty lines, attached to a haiku artefact type
+(`file-patterns: ["haikus/*.md"]`):
+
+`foundry/artefacts/haiku/check-line-count.mjs`:
+
+~~~js
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+
+for (const file of process.argv.slice(2)) {
+  const content = await readFile(file, 'utf8');
+  const lines = content
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+  if (lines.length !== 3) {
+    process.stdout.write(JSON.stringify({
+      file,
+      text: `Expected 3 non-empty lines, got ${lines.length}.`,
+      severity: 'error',
+    }) + '\n');
+  }
+}
+~~~
+
+Declared in the law:
+
+~~~markdown
+## three-lines
+
+A haiku must consist of exactly three non-empty lines.
+
+validators:
+  - id: line-count
+    command: node foundry/artefacts/haiku/check-line-count.mjs {files}
+    failure-means: The artefact file does not contain exactly three non-empty lines.
+~~~
+
 ### 8. Editing existing laws (prose or validators)
 
 When the user wants to modify an existing law — whether updating the prose description or adding/changing validators — use this flow:

package/dist/skills/init-foundry/SKILL.md

@@ -31,9 +31,24 @@ Set up the `foundry/` directory structure in the current project.
 
 3. **Update `.gitignore`**
 
-   Append `.snapshots/` to the project's `.gitignore` (creating the file if absent). This directory is where dry-run snapshots are written and must never be committed.
+   Append the following lines to the project's `.gitignore` (creating
+   the file if absent), skipping any that are already present:
 
-   The plugin will idempotently append `.foundry/` itself on first boot, so you do not need to add that line.
+   ```
+   .snapshots/
+   node_modules/
+   .DS_Store
+   ```
+
+   - `.snapshots/` keeps dry-run snapshots out of git.
+   - `node_modules/` keeps any npm dependencies (e.g. validator
+     packages) out of git. Without it, foundry's `config/*` tools
+     reject calls with `unexpected_files` as soon as the user runs
+     `npm install`.
+   - `.DS_Store` keeps macOS metadata out of git.
+
+   The plugin will idempotently append `.foundry/` itself on first
+   boot, so you do not need to add that line.
 
 4. **Generate foundry agent files**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",