@warlock.js/core 5.30.0 → 5.31.0

package/esm/tooling/agents-md/agents-md-markers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md-markers.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/agents-md-markers.ts"],"mappings":";;cAGa,cAAA;;cAGA,eAAA;;cAGA,aAAA;AAHb;;;;AAA4B;AAG5B;;;;AAA0B;AAoC1B;;;;AAAoF;;AAvCpF,iBAuCgB,sBAAA,CAAuB,QAAA,sBAA8B,OAAe"}

package/esm/tooling/agents-md/agents-md-markers.mjs

@@ -0,0 +1,59 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+
+//#region ../../packages/core/src/tooling/agents-md/agents-md-markers.ts
+/** The file `warlock agents-md --write` and `warlock dev` maintain, at the project root. */
+const AGENTS_MD_FILE = "AGENTS.md";
+/** Opens the generated section. Everything outside the two markers is hand-written. */
+const AGENTS_MD_START = "<!-- warlock:generated:start -->";
+/** Closes the generated section. */
+const AGENTS_MD_END = "<!-- warlock:generated:end -->";
+/** Every index at which `needle` occurs in `text`. */
+function occurrences(text, needle) {
+	const found = [];
+	let index = text.indexOf(needle);
+	while (index !== -1) {
+		found.push(index);
+		index = text.indexOf(needle, index + needle.length);
+	}
+	return found;
+}
+/** The line break the file already uses, so an inserted section matches it. */
+function lineBreakOf(text) {
+	return text.includes("\r\n") ? "\r\n" : "\n";
+}
+/**
+* Put `section` between the generated-section markers of `existing`.
+*
+* - `existing` undefined (no file): the markers and the section, alone.
+* - no markers: the existing text unchanged, then a blank line, then the
+*   markers and the section at the end.
+* - one start marker followed by one end marker: only the bytes between them
+*   are replaced; the markers and everything outside them stay byte-for-byte.
+*
+* Throws `WL7501` when the markers are malformed (one without the other, a
+* duplicate, or the end before the start) — rather than guess which part is
+* hand-written.
+*
+* @param existing The current file content, or `undefined` when the file does not exist.
+* @param section The generated markdown, without markers.
+*/
+function upsertGeneratedSection(existing, section) {
+	const eol = existing === void 0 ? "\n" : lineBreakOf(existing);
+	const block = `${AGENTS_MD_START}${eol}${section.replace(/\r?\n/g, eol).replace(/(?:\r?\n)+$/, "")}${eol}${AGENTS_MD_END}`;
+	if (existing === void 0) return `${block}${eol}`;
+	const starts = occurrences(existing, AGENTS_MD_START);
+	const ends = occurrences(existing, AGENTS_MD_END);
+	if (starts.length === 0 && ends.length === 0) {
+		if (existing.length === 0) return `${block}${eol}`;
+		return `${existing}${existing.endsWith(eol) ? eol : `${eol}${eol}`}${block}${eol}`;
+	}
+	const [start] = starts;
+	const [end] = ends;
+	if (starts.length !== 1 || ends.length !== 1 || start === void 0 || end === void 0) throw new WarlockError("WL7501", `AGENTS.md has ${starts.length} "${AGENTS_MD_START}" and ${ends.length} "${AGENTS_MD_END}" marker(s); expected exactly one of each. Fix the markers by hand — nothing was written.`);
+	if (end < start) throw new WarlockError("WL7501", `AGENTS.md has "${AGENTS_MD_END}" before "${AGENTS_MD_START}". Fix the markers by hand — nothing was written.`);
+	return `${existing.slice(0, start)}${block}${existing.slice(end + 30)}`;
+}
+
+//#endregion
+export { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, upsertGeneratedSection };
+//# sourceMappingURL=agents-md-markers.mjs.map

package/esm/tooling/agents-md/agents-md-markers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md-markers.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/agents-md-markers.ts"],"sourcesContent":["import { WarlockError } from \"../../errors/warlock-error\";\n\n/** The file `warlock agents-md --write` and `warlock dev` maintain, at the project root. */\nexport const AGENTS_MD_FILE = \"AGENTS.md\";\n\n/** Opens the generated section. Everything outside the two markers is hand-written. */\nexport const AGENTS_MD_START = \"<!-- warlock:generated:start -->\";\n\n/** Closes the generated section. */\nexport const AGENTS_MD_END = \"<!-- warlock:generated:end -->\";\n\n/** Every index at which `needle` occurs in `text`. */\nfunction occurrences(text: string, needle: string): number[] {\n  const found: number[] = [];\n  let index = text.indexOf(needle);\n\n  while (index !== -1) {\n    found.push(index);\n    index = text.indexOf(needle, index + needle.length);\n  }\n\n  return found;\n}\n\n/** The line break the file already uses, so an inserted section matches it. */\nfunction lineBreakOf(text: string): string {\n  return text.includes(\"\\r\\n\") ? \"\\r\\n\" : \"\\n\";\n}\n\n/**\n * Put `section` between the generated-section markers of `existing`.\n *\n * - `existing` undefined (no file): the markers and the section, alone.\n * - no markers: the existing text unchanged, then a blank line, then the\n *   markers and the section at the end.\n * - one start marker followed by one end marker: only the bytes between them\n *   are replaced; the markers and everything outside them stay byte-for-byte.\n *\n * Throws `WL7501` when the markers are malformed (one without the other, a\n * duplicate, or the end before the start) — rather than guess which part is\n * hand-written.\n *\n * @param existing The current file content, or `undefined` when the file does not exist.\n * @param section The generated markdown, without markers.\n */\nexport function upsertGeneratedSection(existing: string | undefined, section: string): string {\n  const eol = existing === undefined ? \"\\n\" : lineBreakOf(existing);\n  const body = section.replace(/\\r?\\n/g, eol).replace(/(?:\\r?\\n)+$/, \"\");\n  const block = `${AGENTS_MD_START}${eol}${body}${eol}${AGENTS_MD_END}`;\n\n  if (existing === undefined) return `${block}${eol}`;\n\n  const starts = occurrences(existing, AGENTS_MD_START);\n  const ends = occurrences(existing, AGENTS_MD_END);\n\n  if (starts.length === 0 && ends.length === 0) {\n    if (existing.length === 0) return `${block}${eol}`;\n\n    const separator = existing.endsWith(eol) ? eol : `${eol}${eol}`;\n\n    return `${existing}${separator}${block}${eol}`;\n  }\n\n  const [start] = starts;\n  const [end] = ends;\n\n  if (starts.length !== 1 || ends.length !== 1 || start === undefined || end === undefined) {\n    throw new WarlockError(\n      \"WL7501\",\n      `AGENTS.md has ${starts.length} \"${AGENTS_MD_START}\" and ${ends.length} \"${AGENTS_MD_END}\" marker(s); expected exactly one of each. Fix the markers by hand — nothing was written.`,\n    );\n  }\n\n  if (end < start) {\n    throw new WarlockError(\n      \"WL7501\",\n      `AGENTS.md has \"${AGENTS_MD_END}\" before \"${AGENTS_MD_START}\". Fix the markers by hand — nothing was written.`,\n    );\n  }\n\n  return `${existing.slice(0, start)}${block}${existing.slice(end + AGENTS_MD_END.length)}`;\n}\n"],"mappings":";;;;AAGA,MAAa,iBAAiB;;AAG9B,MAAa,kBAAkB;;AAG/B,MAAa,gBAAgB;;AAG7B,SAAS,YAAY,MAAc,QAA0B;CAC3D,MAAM,QAAkB,CAAC;CACzB,IAAI,QAAQ,KAAK,QAAQ,MAAM;CAE/B,OAAO,UAAU,IAAI;EACnB,MAAM,KAAK,KAAK;EAChB,QAAQ,KAAK,QAAQ,QAAQ,QAAQ,OAAO,MAAM;CACpD;CAEA,OAAO;AACT;;AAGA,SAAS,YAAY,MAAsB;CACzC,OAAO,KAAK,SAAS,MAAM,IAAI,SAAS;AAC1C;;;;;;;;;;;;;;;;;AAkBA,SAAgB,uBAAuB,UAA8B,SAAyB;CAC5F,MAAM,MAAM,aAAa,SAAY,OAAO,YAAY,QAAQ;CAEhE,MAAM,QAAQ,GAAG,kBAAkB,MADtB,QAAQ,QAAQ,UAAU,GAAG,CAAC,CAAC,QAAQ,eAAe,EACvB,IAAI,MAAM;CAEtD,IAAI,aAAa,QAAW,OAAO,GAAG,QAAQ;CAE9C,MAAM,SAAS,YAAY,UAAU,eAAe;CACpD,MAAM,OAAO,YAAY,UAAU,aAAa;CAEhD,IAAI,OAAO,WAAW,KAAK,KAAK,WAAW,GAAG;EAC5C,IAAI,SAAS,WAAW,GAAG,OAAO,GAAG,QAAQ;EAI7C,OAAO,GAAG,WAFQ,SAAS,SAAS,GAAG,IAAI,MAAM,GAAG,MAAM,QAEzB,QAAQ;CAC3C;CAEA,MAAM,CAAC,SAAS;CAChB,MAAM,CAAC,OAAO;CAEd,IAAI,OAAO,WAAW,KAAK,KAAK,WAAW,KAAK,UAAU,UAAa,QAAQ,QAC7E,MAAM,IAAI,aACR,UACA,iBAAiB,OAAO,OAAO,IAAI,gBAAgB,QAAQ,KAAK,OAAO,IAAI,cAAc,0FAC3F;CAGF,IAAI,MAAM,OACR,MAAM,IAAI,aACR,UACA,kBAAkB,cAAc,YAAY,gBAAgB,kDAC9D;CAGF,OAAO,GAAG,SAAS,MAAM,GAAG,KAAK,IAAI,QAAQ,SAAS,MAAM,MAAM,EAAoB;AACxF"}

package/esm/tooling/agents-md/agents-md-refresher.d.mts

@@ -0,0 +1,36 @@
+import { InspectReport } from "../inspect/inspect-report.types.mjs";
+import { WriteAgentsMdResult } from "./write-agents-md.mjs";
+
+//#region ../../packages/core/src/tooling/agents-md/agents-md-refresher.d.ts
+/** Options of {@link createAgentsMdRefresher}. */
+type AgentsMdRefresherOptions = {
+  /** Project root. Default: `process.cwd()`. */cwd?: string; /** Produce a fresh report (the dev server calls `inspectApp()` in-process). */
+  collect: () => Promise<InspectReport>; /** Quiet period after the last `schedule()` before a refresh runs. Default: 1000 ms. */
+  debounceMs?: number; /** Create AGENTS.md when it is missing. Default: `true`. */
+  create?: boolean; /** Called with each refresh's result. */
+  onWrite?: (result: WriteAgentsMdResult) => void; /** Called when a refresh fails; the error never escapes the timer. */
+  onError?: (error: unknown) => void;
+};
+/** A debounced AGENTS.md refresher. */
+type AgentsMdRefresher = {
+  /** Ask for a refresh; calls within `debounceMs` of each other collapse into one. */schedule(): void; /** Run a pending (or, with none pending, a fresh) refresh now and wait for it. */
+  flush(): Promise<void>; /** Cancel a pending refresh; later `schedule()` calls do nothing. */
+  dispose(): void;
+};
+/**
+ * Keep AGENTS.md's generated section current while `warlock dev` runs: the
+ * server calls `schedule()` on boot and after each reload that changed
+ * routes or modules, and one refresh runs once the burst settles. Refreshes
+ * never overlap; a request made during one runs after it.
+ *
+ * @example
+ * const refresher = createAgentsMdRefresher({
+ *   collect: () => inspectApp({ sections: ["routes", "models", "packages"] }),
+ *   onError: (error) => devLogWarn(`AGENTS.md not refreshed: ${String(error)}`),
+ * });
+ * refresher.schedule();
+ */
+declare function createAgentsMdRefresher(options: AgentsMdRefresherOptions): AgentsMdRefresher;
+//#endregion
+export { AgentsMdRefresher, AgentsMdRefresherOptions, createAgentsMdRefresher };
+//# sourceMappingURL=agents-md-refresher.d.mts.map

package/esm/tooling/agents-md/agents-md-refresher.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md-refresher.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/agents-md-refresher.ts"],"mappings":";;;;;KAIY,wBAAA;EAAA,8CAEV,GAAA;EAEA,OAAA,QAAe,OAAA,CAAQ,aAAA,GAAR;EAEf,UAAA,WAIsC;EAFtC,MAAA,YANA;EAQA,OAAA,IAAW,MAAA,EAAQ,mBAAA,WANJ;EAQf,OAAA,IAAW,KAAA;AAAA;;KAID,iBAAA;EANS,oFAQnB,QAAA,UANA;EAQA,KAAA,IAAS,OAAO,QARS;EAUzB,OAAA;AAAA;;;;;;;;;AAAO;AAgBT;;;;iBAAgB,uBAAA,CAAwB,OAAA,EAAS,wBAAA,GAA2B,iBAAiB"}

package/esm/tooling/agents-md/agents-md-refresher.mjs

@@ -0,0 +1,72 @@
+import { writeAgentsMd } from "./write-agents-md.mjs";
+
+//#region ../../packages/core/src/tooling/agents-md/agents-md-refresher.ts
+/**
+* Keep AGENTS.md's generated section current while `warlock dev` runs: the
+* server calls `schedule()` on boot and after each reload that changed
+* routes or modules, and one refresh runs once the burst settles. Refreshes
+* never overlap; a request made during one runs after it.
+*
+* @example
+* const refresher = createAgentsMdRefresher({
+*   collect: () => inspectApp({ sections: ["routes", "models", "packages"] }),
+*   onError: (error) => devLogWarn(`AGENTS.md not refreshed: ${String(error)}`),
+* });
+* refresher.schedule();
+*/
+function createAgentsMdRefresher(options) {
+	const debounceMs = options.debounceMs ?? 1e3;
+	let timer;
+	let running = Promise.resolve();
+	let disposed = false;
+	const refresh = async () => {
+		try {
+			const report = await options.collect();
+			const result = writeAgentsMd({
+				cwd: options.cwd,
+				report,
+				create: options.create
+			});
+			options.onWrite?.(result);
+		} catch (error) {
+			options.onError?.(error);
+		}
+	};
+	const run = () => {
+		running = running.then(refresh);
+		return running;
+	};
+	return {
+		schedule() {
+			if (disposed) return;
+			if (timer !== void 0) clearTimeout(timer);
+			timer = setTimeout(() => {
+				timer = void 0;
+				run();
+			}, debounceMs);
+			timer.unref?.();
+		},
+		async flush() {
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				timer = void 0;
+			}
+			if (disposed) {
+				await running;
+				return;
+			}
+			await run();
+		},
+		dispose() {
+			disposed = true;
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				timer = void 0;
+			}
+		}
+	};
+}
+
+//#endregion
+export { createAgentsMdRefresher };
+//# sourceMappingURL=agents-md-refresher.mjs.map

package/esm/tooling/agents-md/agents-md-refresher.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md-refresher.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/agents-md-refresher.ts"],"sourcesContent":["import type { InspectReport } from \"../inspect/inspect-report.types\";\nimport { writeAgentsMd, type WriteAgentsMdResult } from \"./write-agents-md\";\n\n/** Options of {@link createAgentsMdRefresher}. */\nexport type AgentsMdRefresherOptions = {\n  /** Project root. Default: `process.cwd()`. */\n  cwd?: string;\n  /** Produce a fresh report (the dev server calls `inspectApp()` in-process). */\n  collect: () => Promise<InspectReport>;\n  /** Quiet period after the last `schedule()` before a refresh runs. Default: 1000 ms. */\n  debounceMs?: number;\n  /** Create AGENTS.md when it is missing. Default: `true`. */\n  create?: boolean;\n  /** Called with each refresh's result. */\n  onWrite?: (result: WriteAgentsMdResult) => void;\n  /** Called when a refresh fails; the error never escapes the timer. */\n  onError?: (error: unknown) => void;\n};\n\n/** A debounced AGENTS.md refresher. */\nexport type AgentsMdRefresher = {\n  /** Ask for a refresh; calls within `debounceMs` of each other collapse into one. */\n  schedule(): void;\n  /** Run a pending (or, with none pending, a fresh) refresh now and wait for it. */\n  flush(): Promise<void>;\n  /** Cancel a pending refresh; later `schedule()` calls do nothing. */\n  dispose(): void;\n};\n\n/**\n * Keep AGENTS.md's generated section current while `warlock dev` runs: the\n * server calls `schedule()` on boot and after each reload that changed\n * routes or modules, and one refresh runs once the burst settles. Refreshes\n * never overlap; a request made during one runs after it.\n *\n * @example\n * const refresher = createAgentsMdRefresher({\n *   collect: () => inspectApp({ sections: [\"routes\", \"models\", \"packages\"] }),\n *   onError: (error) => devLogWarn(`AGENTS.md not refreshed: ${String(error)}`),\n * });\n * refresher.schedule();\n */\nexport function createAgentsMdRefresher(options: AgentsMdRefresherOptions): AgentsMdRefresher {\n  const debounceMs = options.debounceMs ?? 1000;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let running: Promise<void> = Promise.resolve();\n  let disposed = false;\n\n  const refresh = async (): Promise<void> => {\n    try {\n      const report = await options.collect();\n      const result = writeAgentsMd({ cwd: options.cwd, report, create: options.create });\n\n      options.onWrite?.(result);\n    } catch (error) {\n      options.onError?.(error);\n    }\n  };\n\n  const run = (): Promise<void> => {\n    running = running.then(refresh);\n    return running;\n  };\n\n  return {\n    schedule() {\n      if (disposed) return;\n      if (timer !== undefined) clearTimeout(timer);\n\n      timer = setTimeout(() => {\n        timer = undefined;\n        void run();\n      }, debounceMs);\n      timer.unref?.();\n    },\n    async flush() {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n\n      if (disposed) {\n        await running;\n        return;\n      }\n\n      await run();\n    },\n    dispose() {\n      disposed = true;\n\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA0CA,SAAgB,wBAAwB,SAAsD;CAC5F,MAAM,aAAa,QAAQ,cAAc;CACzC,IAAI;CACJ,IAAI,UAAyB,QAAQ,QAAQ;CAC7C,IAAI,WAAW;CAEf,MAAM,UAAU,YAA2B;EACzC,IAAI;GACF,MAAM,SAAS,MAAM,QAAQ,QAAQ;GACrC,MAAM,SAAS,cAAc;IAAE,KAAK,QAAQ;IAAK;IAAQ,QAAQ,QAAQ;GAAO,CAAC;GAEjF,QAAQ,UAAU,MAAM;EAC1B,SAAS,OAAO;GACd,QAAQ,UAAU,KAAK;EACzB;CACF;CAEA,MAAM,YAA2B;EAC/B,UAAU,QAAQ,KAAK,OAAO;EAC9B,OAAO;CACT;CAEA,OAAO;EACL,WAAW;GACT,IAAI,UAAU;GACd,IAAI,UAAU,QAAW,aAAa,KAAK;GAE3C,QAAQ,iBAAiB;IACvB,QAAQ;IACR,AAAK,IAAI;GACX,GAAG,UAAU;GACb,MAAM,QAAQ;EAChB;EACA,MAAM,QAAQ;GACZ,IAAI,UAAU,QAAW;IACvB,aAAa,KAAK;IAClB,QAAQ;GACV;GAEA,IAAI,UAAU;IACZ,MAAM;IACN;GACF;GAEA,MAAM,IAAI;EACZ;EACA,UAAU;GACR,WAAW;GAEX,IAAI,UAAU,QAAW;IACvB,aAAa,KAAK;IAClB,QAAQ;GACV;EACF;CACF;AACF"}

package/esm/tooling/agents-md/index.mjs

@@ -0,0 +1,7 @@
+import { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, upsertGeneratedSection } from "./agents-md-markers.mjs";
+import { listInstalledSkills, parseSkillFrontMatter, shortSkillLine } from "./installed-skills.mjs";
+import { listAppModules, renderAgentsMdSection } from "./render-agents-md.mjs";
+import { writeAgentsMd } from "./write-agents-md.mjs";
+import { createAgentsMdRefresher } from "./agents-md-refresher.mjs";
+
+export { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, createAgentsMdRefresher, listAppModules, listInstalledSkills, parseSkillFrontMatter, renderAgentsMdSection, shortSkillLine, upsertGeneratedSection, writeAgentsMd };

package/esm/tooling/agents-md/installed-skills.d.mts

@@ -0,0 +1,30 @@
+//#region ../../packages/core/src/tooling/agents-md/installed-skills.d.ts
+/** One `SKILL.md` an installed `@warlock.js/*` package ships. */
+type InstalledSkill = {
+  /** The package, e.g. `@warlock.js/core`. */package: string; /** The skill folder name, e.g. `warlock-inspect`. */
+  slug: string; /** The `name` from the front matter (the slug when absent). */
+  name: string; /** The full `description` from the front matter (empty when absent). */
+  description: string; /** Project-relative POSIX path of the `SKILL.md`. */
+  file: string;
+};
+/** The `name` and `description` of a `SKILL.md`'s front matter. */
+declare function parseSkillFrontMatter(content: string): {
+  name?: string;
+  description?: string;
+};
+/**
+ * The first sentence of a skill description, capped at `max` characters —
+ * the one line an agent reads to decide whether to open the skill.
+ */
+declare function shortSkillLine(description: string, max?: number): string;
+/**
+ * Every skill the installed `@warlock.js/*` packages ship, read from
+ * `<cwd>/node_modules/@warlock.js/<package>/skills/<slug>/SKILL.md`.
+ * Sorted by package, then slug. Reads only the local install: no network.
+ *
+ * @param cwd The project root.
+ */
+declare function listInstalledSkills(cwd: string): InstalledSkill[];
+//#endregion
+export { InstalledSkill, listInstalledSkills, parseSkillFrontMatter, shortSkillLine };
+//# sourceMappingURL=installed-skills.d.mts.map

package/esm/tooling/agents-md/installed-skills.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installed-skills.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/installed-skills.ts"],"mappings":";;KAIY,cAAA;EAAc,4CAExB,OAAA,UAFwB;EAIxB,IAAA;EAEA,IAAA,UAEA;EAAA,WAAA,UAEI;EAAJ,IAAA;AAAA;;iBAiCc,qBAAA,CAAsB,OAAA;EAAoB,IAAA;EAAe,WAAA;AAAA;;;AAAW;AAepF;iBAAgB,cAAA,CAAe,WAAA,UAAqB,GAAS;;;AAAA;AAc7D;;;;iBAAgB,mBAAA,CAAoB,GAAA,WAAc,cAAc"}

package/esm/tooling/agents-md/installed-skills.mjs

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+
+//#region ../../packages/core/src/tooling/agents-md/installed-skills.ts
+function directories(directory) {
+	try {
+		return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() || entry.isSymbolicLink()).map((entry) => entry.name).sort();
+	} catch {
+		return [];
+	}
+}
+/** Read a front-matter scalar, unquoting YAML single/double-quoted values. */
+function frontMatterValue(frontMatter, key) {
+	const raw = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(frontMatter)?.[1]?.trim();
+	if (raw === void 0 || raw.length === 0) return void 0;
+	if (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2) return raw.slice(1, -1).replace(/''/g, "'");
+	if (raw.startsWith("\"") && raw.endsWith("\"") && raw.length >= 2) return raw.slice(1, -1).replace(/\\"/g, "\"");
+	return raw;
+}
+/** The `name` and `description` of a `SKILL.md`'s front matter. */
+function parseSkillFrontMatter(content) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!match?.[1]) return {};
+	return {
+		name: frontMatterValue(match[1], "name"),
+		description: frontMatterValue(match[1], "description")
+	};
+}
+/**
+* The first sentence of a skill description, capped at `max` characters —
+* the one line an agent reads to decide whether to open the skill.
+*/
+function shortSkillLine(description, max = 120) {
+	const compact = description.replace(/\s+/g, " ").trim();
+	const sentence = /^(.+?[.!?])(?:\s|$)/.exec(compact)?.[1] ?? compact;
+	return sentence.length > max ? `${sentence.slice(0, max - 1).trimEnd()}…` : sentence;
+}
+/**
+* Every skill the installed `@warlock.js/*` packages ship, read from
+* `<cwd>/node_modules/@warlock.js/<package>/skills/<slug>/SKILL.md`.
+* Sorted by package, then slug. Reads only the local install: no network.
+*
+* @param cwd The project root.
+*/
+function listInstalledSkills(cwd) {
+	const scope = path.join(cwd, "node_modules", "@warlock.js");
+	const skills = [];
+	for (const packageFolder of directories(scope)) {
+		const skillsRoot = path.join(scope, packageFolder, "skills");
+		for (const slug of directories(skillsRoot)) {
+			const file = path.join(skillsRoot, slug, "SKILL.md");
+			if (!existsSync(file)) continue;
+			let content;
+			try {
+				content = readFileSync(file, "utf8");
+			} catch {
+				continue;
+			}
+			const front = parseSkillFrontMatter(content);
+			skills.push({
+				package: `@warlock.js/${packageFolder}`,
+				slug,
+				name: front.name ?? slug,
+				description: front.description ?? "",
+				file: path.relative(cwd, file).split(path.sep).join("/")
+			});
+		}
+	}
+	return skills;
+}
+
+//#endregion
+export { listInstalledSkills, parseSkillFrontMatter, shortSkillLine };
+//# sourceMappingURL=installed-skills.mjs.map

package/esm/tooling/agents-md/installed-skills.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"installed-skills.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/installed-skills.ts"],"sourcesContent":["import { existsSync, readdirSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/** One `SKILL.md` an installed `@warlock.js/*` package ships. */\nexport type InstalledSkill = {\n  /** The package, e.g. `@warlock.js/core`. */\n  package: string;\n  /** The skill folder name, e.g. `warlock-inspect`. */\n  slug: string;\n  /** The `name` from the front matter (the slug when absent). */\n  name: string;\n  /** The full `description` from the front matter (empty when absent). */\n  description: string;\n  /** Project-relative POSIX path of the `SKILL.md`. */\n  file: string;\n};\n\nfunction directories(directory: string): string[] {\n  try {\n    return readdirSync(directory, { withFileTypes: true })\n      .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())\n      .map((entry) => entry.name)\n      .sort();\n  } catch {\n    return [];\n  }\n}\n\n/** Read a front-matter scalar, unquoting YAML single/double-quoted values. */\nfunction frontMatterValue(frontMatter: string, key: string): string | undefined {\n  const match = new RegExp(`^${key}:[ \\\\t]*(.*)$`, \"m\").exec(frontMatter);\n  const raw = match?.[1]?.trim();\n\n  if (raw === undefined || raw.length === 0) return undefined;\n\n  if (raw.startsWith(\"'\") && raw.endsWith(\"'\") && raw.length >= 2) {\n    return raw.slice(1, -1).replace(/''/g, \"'\");\n  }\n\n  if (raw.startsWith('\"') && raw.endsWith('\"') && raw.length >= 2) {\n    return raw.slice(1, -1).replace(/\\\\\"/g, '\"');\n  }\n\n  return raw;\n}\n\n/** The `name` and `description` of a `SKILL.md`'s front matter. */\nexport function parseSkillFrontMatter(content: string): { name?: string; description?: string } {\n  const match = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---/.exec(content);\n\n  if (!match?.[1]) return {};\n\n  return {\n    name: frontMatterValue(match[1], \"name\"),\n    description: frontMatterValue(match[1], \"description\"),\n  };\n}\n\n/**\n * The first sentence of a skill description, capped at `max` characters —\n * the one line an agent reads to decide whether to open the skill.\n */\nexport function shortSkillLine(description: string, max = 120): string {\n  const compact = description.replace(/\\s+/g, \" \").trim();\n  const sentence = /^(.+?[.!?])(?:\\s|$)/.exec(compact)?.[1] ?? compact;\n\n  return sentence.length > max ? `${sentence.slice(0, max - 1).trimEnd()}…` : sentence;\n}\n\n/**\n * Every skill the installed `@warlock.js/*` packages ship, read from\n * `<cwd>/node_modules/@warlock.js/<package>/skills/<slug>/SKILL.md`.\n * Sorted by package, then slug. Reads only the local install: no network.\n *\n * @param cwd The project root.\n */\nexport function listInstalledSkills(cwd: string): InstalledSkill[] {\n  const scope = path.join(cwd, \"node_modules\", \"@warlock.js\");\n  const skills: InstalledSkill[] = [];\n\n  for (const packageFolder of directories(scope)) {\n    const skillsRoot = path.join(scope, packageFolder, \"skills\");\n\n    for (const slug of directories(skillsRoot)) {\n      const file = path.join(skillsRoot, slug, \"SKILL.md\");\n\n      if (!existsSync(file)) continue;\n\n      let content: string;\n\n      try {\n        content = readFileSync(file, \"utf8\");\n      } catch {\n        continue;\n      }\n\n      const front = parseSkillFrontMatter(content);\n\n      skills.push({\n        package: `@warlock.js/${packageFolder}`,\n        slug,\n        name: front.name ?? slug,\n        description: front.description ?? \"\",\n        file: path.relative(cwd, file).split(path.sep).join(\"/\"),\n      });\n    }\n  }\n\n  return skills;\n}\n"],"mappings":";;;;AAiBA,SAAS,YAAY,WAA6B;CAChD,IAAI;EACF,OAAO,YAAY,WAAW,EAAE,eAAe,KAAK,CAAC,CAAC,CACnD,QAAQ,UAAU,MAAM,YAAY,KAAK,MAAM,eAAe,CAAC,CAAC,CAChE,KAAK,UAAU,MAAM,IAAI,CAAC,CAC1B,KAAK;CACV,QAAQ;EACN,OAAO,CAAC;CACV;AACF;;AAGA,SAAS,iBAAiB,aAAqB,KAAiC;CAE9E,MAAM,MADQ,IAAI,OAAO,IAAI,IAAI,gBAAgB,GAAG,CAAC,CAAC,KAAK,WAC3C,CAAC,GAAG,EAAE,EAAE,KAAK;CAE7B,IAAI,QAAQ,UAAa,IAAI,WAAW,GAAG,OAAO;CAElD,IAAI,IAAI,WAAW,GAAG,KAAK,IAAI,SAAS,GAAG,KAAK,IAAI,UAAU,GAC5D,OAAO,IAAI,MAAM,GAAG,EAAE,CAAC,CAAC,QAAQ,OAAO,GAAG;CAG5C,IAAI,IAAI,WAAW,IAAG,KAAK,IAAI,SAAS,IAAG,KAAK,IAAI,UAAU,GAC5D,OAAO,IAAI,MAAM,GAAG,EAAE,CAAC,CAAC,QAAQ,QAAQ,IAAG;CAG7C,OAAO;AACT;;AAGA,SAAgB,sBAAsB,SAA0D;CAC9F,MAAM,QAAQ,8BAA8B,KAAK,OAAO;CAExD,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC;CAEzB,OAAO;EACL,MAAM,iBAAiB,MAAM,IAAI,MAAM;EACvC,aAAa,iBAAiB,MAAM,IAAI,aAAa;CACvD;AACF;;;;;AAMA,SAAgB,eAAe,aAAqB,MAAM,KAAa;CACrE,MAAM,UAAU,YAAY,QAAQ,QAAQ,GAAG,CAAC,CAAC,KAAK;CACtD,MAAM,WAAW,sBAAsB,KAAK,OAAO,CAAC,GAAG,MAAM;CAE7D,OAAO,SAAS,SAAS,MAAM,GAAG,SAAS,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK;AAC9E;;;;;;;;AASA,SAAgB,oBAAoB,KAA+B;CACjE,MAAM,QAAQ,KAAK,KAAK,KAAK,gBAAgB,aAAa;CAC1D,MAAM,SAA2B,CAAC;CAElC,KAAK,MAAM,iBAAiB,YAAY,KAAK,GAAG;EAC9C,MAAM,aAAa,KAAK,KAAK,OAAO,eAAe,QAAQ;EAE3D,KAAK,MAAM,QAAQ,YAAY,UAAU,GAAG;GAC1C,MAAM,OAAO,KAAK,KAAK,YAAY,MAAM,UAAU;GAEnD,IAAI,CAAC,WAAW,IAAI,GAAG;GAEvB,IAAI;GAEJ,IAAI;IACF,UAAU,aAAa,MAAM,MAAM;GACrC,QAAQ;IACN;GACF;GAEA,MAAM,QAAQ,sBAAsB,OAAO;GAE3C,OAAO,KAAK;IACV,SAAS,eAAe;IACxB;IACA,MAAM,MAAM,QAAQ;IACpB,aAAa,MAAM,eAAe;IAClC,MAAM,KAAK,SAAS,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG;GACzD,CAAC;EACH;CACF;CAEA,OAAO;AACT"}

package/esm/tooling/agents-md/render-agents-md.d.mts

@@ -0,0 +1,33 @@
+import { InspectReport } from "../inspect/inspect-report.types.mjs";
+import { InstalledSkill } from "./installed-skills.mjs";
+
+//#region ../../packages/core/src/tooling/agents-md/render-agents-md.d.ts
+/** Options of {@link renderAgentsMdSection}. */
+type RenderAgentsMdOptions = {
+  /** Installed skills to list (see `listInstalledSkills`). Default: none listed. */skills?: readonly InstalledSkill[]; /** Module folder names under `src/app` (see `listAppModules`); merged with the ones routes and models name. */
+  modules?: readonly string[]; /** How many routes the compact list shows before pointing at `warlock inspect`. Default: 60. */
+  maxRoutes?: number;
+};
+/**
+ * The module folders under `<cwd>/src/app`, sorted. Empty when there is none.
+ *
+ * @param cwd The project root.
+ */
+declare function listAppModules(cwd: string): string[];
+/**
+ * Render the app-specific AGENTS.md section from an inspect report: the app
+ * and its Warlock packages, modules, a routes summary (unguarded writes
+ * flagged), models, the conventions `warlock check` enforces, the installed
+ * skills and the verify commands.
+ *
+ * Deterministic: no timestamps and stable ordering, so regenerating an
+ * unchanged app yields the same bytes and `writeAgentsMd` writes nothing.
+ * Returned without the markers.
+ *
+ * @param report An `inspectApp()` report (routes, models and packages are read when present).
+ * @param options Skills and module folders to include.
+ */
+declare function renderAgentsMdSection(report: InspectReport, options?: RenderAgentsMdOptions): string;
+//#endregion
+export { RenderAgentsMdOptions, listAppModules, renderAgentsMdSection };
+//# sourceMappingURL=render-agents-md.d.mts.map

package/esm/tooling/agents-md/render-agents-md.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-agents-md.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/render-agents-md.ts"],"mappings":";;;;;KAMY,qBAAA;EAAA,kFAEV,MAAA,YAAkB,cAAc;EAEhC,OAAA,sBAFA;EAIA,SAAA;AAAA;;;AAAS;AAcX;;iBAAgB,cAAA,CAAe,GAAW;;AAAA;AAqO1C;;;;;;;;;AAEqC;;iBAFrB,qBAAA,CACd,MAAA,EAAQ,aAAA,EACR,OAAA,GAAS,qBAA0B"}

package/esm/tooling/agents-md/render-agents-md.mjs

@@ -0,0 +1,195 @@
+import { shortSkillLine } from "./installed-skills.mjs";
+import path from "node:path";
+import { readdirSync } from "node:fs";
+
+//#region ../../packages/core/src/tooling/agents-md/render-agents-md.ts
+/** Methods that change state; one of these without an auth guard is flagged. */
+const MUTATING_METHODS = new Set([
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+/** Fixed method order for the per-method counts. */
+const METHOD_ORDER = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+];
+/**
+* The module folders under `<cwd>/src/app`, sorted. Empty when there is none.
+*
+* @param cwd The project root.
+*/
+function listAppModules(cwd) {
+	try {
+		return readdirSync(path.join(cwd, "src", "app"), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+	} catch {
+		return [];
+	}
+}
+/** The module a project-relative source path belongs to (`src/app/<module>/…`). */
+function moduleOf(file) {
+	return file ? /^src\/app\/([^/]+)\//.exec(file.split("\\").join("/"))?.[1] : void 0;
+}
+function compare(first, second) {
+	return first < second ? -1 : first > second ? 1 : 0;
+}
+function isUnguardedWrite(route) {
+	return MUTATING_METHODS.has(route.method.toUpperCase()) && !route.auth.required && !route.isPage;
+}
+function routeLine(route) {
+	const guard = route.auth.required ? " [auth]" : "";
+	const name = route.name ? ` ${route.name}` : "";
+	return `- \`${route.method} ${route.path}\`${guard}${name}`;
+}
+function sortRoutes(routes) {
+	return [...routes].sort((first, second) => compare(first.path, second.path) || METHOD_ORDER.indexOf(first.method) - METHOD_ORDER.indexOf(second.method) || compare(first.method, second.method));
+}
+function appSection(report) {
+	const lines = [`## ${report.app.name ?? "This app"}${report.app.version ? ` ${report.app.version}` : ""} — generated facts`, ""];
+	const packages = [...report.packages ?? []].sort((first, second) => compare(first.name, second.name));
+	if (packages.length > 0) lines.push(`Warlock packages: ${packages.map((entry) => `\`${entry.name}@${entry.version}\``).join(", ")}.`, "");
+	return lines;
+}
+function modulesSection(report, extra) {
+	const routeCounts = /* @__PURE__ */ new Map();
+	const modelCounts = /* @__PURE__ */ new Map();
+	for (const route of report.routes ?? []) {
+		const module = moduleOf(route.sourceFile);
+		if (module) routeCounts.set(module, (routeCounts.get(module) ?? 0) + 1);
+	}
+	for (const model of report.models ?? []) {
+		const module = moduleOf(model.sourceFile);
+		if (module) modelCounts.set(module, (modelCounts.get(module) ?? 0) + 1);
+	}
+	const modules = [...new Set([
+		...extra,
+		...routeCounts.keys(),
+		...modelCounts.keys()
+	])].sort();
+	if (modules.length === 0) return [];
+	return [
+		"### Modules",
+		"",
+		"Each lives in `src/app/<module>/`.",
+		"",
+		"| Module | Routes | Models |",
+		"| ------ | ------ | ------ |",
+		...modules.map((module) => `| \`${module}\` | ${routeCounts.get(module) ?? 0} | ${modelCounts.get(module) ?? 0} |`),
+		""
+	];
+}
+function routesSection(report, maxRoutes) {
+	const routes = sortRoutes(report.routes ?? []);
+	if (routes.length === 0) return [];
+	const counts = /* @__PURE__ */ new Map();
+	for (const route of routes) counts.set(route.method, (counts.get(route.method) ?? 0) + 1);
+	const methods = [...counts.keys()].sort((first, second) => (METHOD_ORDER.indexOf(first) + 1 || 99) - (METHOD_ORDER.indexOf(second) + 1 || 99) || compare(first, second));
+	const unguarded = routes.filter(isUnguardedWrite);
+	const lines = [
+		"### Routes",
+		"",
+		`${routes.length} route(s): ${methods.map((method) => `${counts.get(method) ?? 0} ${method}`).join(", ")}.`,
+		""
+	];
+	if (unguarded.length > 0) lines.push(`Mutating routes without an auth guard (confirm each is meant to be public): ${unguarded.map((route) => `\`${route.method} ${route.path}\``).join(", ")}.`, "");
+	lines.push(...routes.slice(0, maxRoutes).map(routeLine));
+	if (routes.length > maxRoutes) lines.push(`- +${routes.length - maxRoutes} more — run \`npx warlock inspect --json --section routes\``);
+	lines.push("");
+	return lines;
+}
+function modelsSection(report) {
+	const models = [...report.models ?? []].sort((first, second) => compare(first.name, second.name));
+	if (models.length === 0) return [];
+	return [
+		"### Models",
+		"",
+		...models.map((model) => {
+			const module = moduleOf(model.sourceFile);
+			const table = model.table ? ` → \`${model.table}\`` : "";
+			return `- \`${model.name}\`${table}${module ? ` (module \`${module}\`)` : ""}`;
+		}),
+		""
+	];
+}
+/** The rules `warlock check` enforces (WL9001–WL9012) and the layout every skill assumes. */
+const CONVENTIONS = [
+	"- Features live in `src/app/<module>/`; flow is one-way: `routes.ts` → controllers → services → repositories → models. Resources only map output.",
+	"- Never import auto-loaded files: `src/app/main.ts`, `src/app/<module>/routes.ts`, `main.ts`, `worker.ts`, `events/*.ts` (`WL9001`).",
+	"- No `.js` extensions in import paths (`WL9002`).",
+	"- Cross-module imports use the `app/<module>/...` alias, not `../../` (`WL9003`); relative paths stay inside a module.",
+	"- Cascade uses standard decorators: never set `\"experimentalDecorators\": true` (`WL9004`).",
+	"- Controllers are thin and read input with `request.validated()`, never `request.all()` (`WL9005`); schemas live in `schema/<action>.schema.ts` and export the value and its `Infer` type. One controller per file (`WL9011`).",
+	"- Every POST/PUT/PATCH/DELETE route is inside `guarded()` (or has auth middleware) or says `public: true` (`WL9006`).",
+	"- Redirect targets from request input go through `safeRedirect()` / `safeRedirectTarget()` (`WL9007`); logs never carry raw emails, credentials or request bodies (`WL9008`); regexes run on request input have bounded quantifiers (`WL9009`).",
+	"- Import each API from its home package: `v` from `@warlock.js/seal`, `Model` from `@warlock.js/cascade`, `router` from `@warlock.js/core`."
+];
+function skillsSection(skills) {
+	if (skills.length === 0) return [];
+	const byPackage = /* @__PURE__ */ new Map();
+	for (const skill of skills) byPackage.set(skill.package, [...byPackage.get(skill.package) ?? [], skill]);
+	const lines = [
+		"### Skills",
+		"",
+		"Installed with the packages, at `node_modules/<package>/skills/<slug>/SKILL.md`. Read the matching one before changing that area.",
+		""
+	];
+	for (const packageName of [...byPackage.keys()].sort()) {
+		lines.push(`**${packageName}**`, "");
+		const entries = [...byPackage.get(packageName) ?? []].sort((first, second) => compare(first.slug, second.slug));
+		for (const skill of entries) {
+			const line = shortSkillLine(skill.description);
+			lines.push(`- \`${skill.slug}\`${line ? ` — ${line}` : ""}`);
+		}
+		lines.push("");
+	}
+	return lines;
+}
+const VERIFY = [
+	"### Verify a change",
+	"",
+	"- `npx warlock check --changed --json` — typecheck, lint, affected tests and conventions; exit 1 = your code, 2 = this machine.",
+	"- `npx warlock inspect --json` — routes, models, config keys, events, pages, jobs from the booted app.",
+	"- `npx warlock explain <code>` — what a `WLxxxx` code means and how to fix it.",
+	"- `npx warlock trace <method> <url> --json` — send a request to the running `warlock dev` and print its devtools timeline.",
+	"- `npx warlock mcp` — the same facts and actions as an MCP server.",
+	""
+];
+/**
+* Render the app-specific AGENTS.md section from an inspect report: the app
+* and its Warlock packages, modules, a routes summary (unguarded writes
+* flagged), models, the conventions `warlock check` enforces, the installed
+* skills and the verify commands.
+*
+* Deterministic: no timestamps and stable ordering, so regenerating an
+* unchanged app yields the same bytes and `writeAgentsMd` writes nothing.
+* Returned without the markers.
+*
+* @param report An `inspectApp()` report (routes, models and packages are read when present).
+* @param options Skills and module folders to include.
+*/
+function renderAgentsMdSection(report, options = {}) {
+	return `${[
+		"<!-- Generated by `warlock agents-md` and refreshed by `warlock dev`. Write your own notes outside the warlock:generated markers; everything between them is replaced. -->",
+		"",
+		...appSection(report),
+		...modulesSection(report, options.modules ?? []),
+		...routesSection(report, options.maxRoutes ?? 60),
+		...modelsSection(report),
+		"### Conventions in force",
+		"",
+		...CONVENTIONS,
+		"",
+		...skillsSection(options.skills ?? []),
+		...VERIFY
+	].join("\n").replace(/\n+$/, "")}\n`;
+}
+
+//#endregion
+export { listAppModules, renderAgentsMdSection };
+//# sourceMappingURL=render-agents-md.mjs.map

package/esm/tooling/agents-md/render-agents-md.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-agents-md.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/render-agents-md.ts"],"sourcesContent":["import { readdirSync } from \"node:fs\";\nimport path from \"node:path\";\nimport type { InspectReport, InspectRoute } from \"../inspect/inspect-report.types\";\nimport { type InstalledSkill, shortSkillLine } from \"./installed-skills\";\n\n/** Options of {@link renderAgentsMdSection}. */\nexport type RenderAgentsMdOptions = {\n  /** Installed skills to list (see `listInstalledSkills`). Default: none listed. */\n  skills?: readonly InstalledSkill[];\n  /** Module folder names under `src/app` (see `listAppModules`); merged with the ones routes and models name. */\n  modules?: readonly string[];\n  /** How many routes the compact list shows before pointing at `warlock inspect`. Default: 60. */\n  maxRoutes?: number;\n};\n\n/** Methods that change state; one of these without an auth guard is flagged. */\nconst MUTATING_METHODS = new Set([\"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\n/** Fixed method order for the per-method counts. */\nconst METHOD_ORDER = [\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\", \"HEAD\", \"OPTIONS\"];\n\n/**\n * The module folders under `<cwd>/src/app`, sorted. Empty when there is none.\n *\n * @param cwd The project root.\n */\nexport function listAppModules(cwd: string): string[] {\n  try {\n    return readdirSync(path.join(cwd, \"src\", \"app\"), { withFileTypes: true })\n      .filter((entry) => entry.isDirectory())\n      .map((entry) => entry.name)\n      .sort();\n  } catch {\n    return [];\n  }\n}\n\n/** The module a project-relative source path belongs to (`src/app/<module>/…`). */\nfunction moduleOf(file: string | null): string | undefined {\n  return file ? /^src\\/app\\/([^/]+)\\//.exec(file.split(\"\\\\\").join(\"/\"))?.[1] : undefined;\n}\n\nfunction compare(first: string, second: string): number {\n  return first < second ? -1 : first > second ? 1 : 0;\n}\n\nfunction isUnguardedWrite(route: InspectRoute): boolean {\n  return MUTATING_METHODS.has(route.method.toUpperCase()) && !route.auth.required && !route.isPage;\n}\n\nfunction routeLine(route: InspectRoute): string {\n  const guard = route.auth.required ? \" [auth]\" : \"\";\n  const name = route.name ? ` ${route.name}` : \"\";\n\n  return `- \\`${route.method} ${route.path}\\`${guard}${name}`;\n}\n\nfunction sortRoutes(routes: readonly InspectRoute[]): InspectRoute[] {\n  return [...routes].sort(\n    (first, second) =>\n      compare(first.path, second.path) ||\n      METHOD_ORDER.indexOf(first.method) - METHOD_ORDER.indexOf(second.method) ||\n      compare(first.method, second.method),\n  );\n}\n\nfunction appSection(report: InspectReport): string[] {\n  const name = report.app.name ?? \"This app\";\n  const version = report.app.version ? ` ${report.app.version}` : \"\";\n  const lines = [`## ${name}${version} — generated facts`, \"\"];\n  const packages = [...(report.packages ?? [])].sort((first, second) =>\n    compare(first.name, second.name),\n  );\n\n  if (packages.length > 0) {\n    lines.push(\n      `Warlock packages: ${packages.map((entry) => `\\`${entry.name}@${entry.version}\\``).join(\", \")}.`,\n      \"\",\n    );\n  }\n\n  return lines;\n}\n\nfunction modulesSection(report: InspectReport, extra: readonly string[]): string[] {\n  const routeCounts = new Map<string, number>();\n  const modelCounts = new Map<string, number>();\n\n  for (const route of report.routes ?? []) {\n    const module = moduleOf(route.sourceFile);\n    if (module) routeCounts.set(module, (routeCounts.get(module) ?? 0) + 1);\n  }\n\n  for (const model of report.models ?? []) {\n    const module = moduleOf(model.sourceFile);\n    if (module) modelCounts.set(module, (modelCounts.get(module) ?? 0) + 1);\n  }\n\n  const modules = [...new Set([...extra, ...routeCounts.keys(), ...modelCounts.keys()])].sort();\n\n  if (modules.length === 0) return [];\n\n  return [\n    \"### Modules\",\n    \"\",\n    \"Each lives in `src/app/<module>/`.\",\n    \"\",\n    \"| Module | Routes | Models |\",\n    \"| ------ | ------ | ------ |\",\n    ...modules.map(\n      (module) =>\n        `| \\`${module}\\` | ${routeCounts.get(module) ?? 0} | ${modelCounts.get(module) ?? 0} |`,\n    ),\n    \"\",\n  ];\n}\n\nfunction routesSection(report: InspectReport, maxRoutes: number): string[] {\n  const routes = sortRoutes(report.routes ?? []);\n\n  if (routes.length === 0) return [];\n\n  const counts = new Map<string, number>();\n\n  for (const route of routes) {\n    counts.set(route.method, (counts.get(route.method) ?? 0) + 1);\n  }\n\n  const methods = [...counts.keys()].sort(\n    (first, second) =>\n      (METHOD_ORDER.indexOf(first) + 1 || 99) - (METHOD_ORDER.indexOf(second) + 1 || 99) ||\n      compare(first, second),\n  );\n  const unguarded = routes.filter(isUnguardedWrite);\n  const lines = [\n    \"### Routes\",\n    \"\",\n    `${routes.length} route(s): ${methods.map((method) => `${counts.get(method) ?? 0} ${method}`).join(\", \")}.`,\n    \"\",\n  ];\n\n  if (unguarded.length > 0) {\n    lines.push(\n      `Mutating routes without an auth guard (confirm each is meant to be public): ${unguarded\n        .map((route) => `\\`${route.method} ${route.path}\\``)\n        .join(\", \")}.`,\n      \"\",\n    );\n  }\n\n  lines.push(...routes.slice(0, maxRoutes).map(routeLine));\n\n  if (routes.length > maxRoutes) {\n    lines.push(\n      `- +${routes.length - maxRoutes} more — run \\`npx warlock inspect --json --section routes\\``,\n    );\n  }\n\n  lines.push(\"\");\n\n  return lines;\n}\n\nfunction modelsSection(report: InspectReport): string[] {\n  const models = [...(report.models ?? [])].sort((first, second) =>\n    compare(first.name, second.name),\n  );\n\n  if (models.length === 0) return [];\n\n  return [\n    \"### Models\",\n    \"\",\n    ...models.map((model) => {\n      const module = moduleOf(model.sourceFile);\n      const table = model.table ? ` → \\`${model.table}\\`` : \"\";\n\n      return `- \\`${model.name}\\`${table}${module ? ` (module \\`${module}\\`)` : \"\"}`;\n    }),\n    \"\",\n  ];\n}\n\n/** The rules `warlock check` enforces (WL9001–WL9012) and the layout every skill assumes. */\nconst CONVENTIONS = [\n  \"- Features live in `src/app/<module>/`; flow is one-way: `routes.ts` → controllers → services → repositories → models. Resources only map output.\",\n  \"- Never import auto-loaded files: `src/app/main.ts`, `src/app/<module>/routes.ts`, `main.ts`, `worker.ts`, `events/*.ts` (`WL9001`).\",\n  \"- No `.js` extensions in import paths (`WL9002`).\",\n  \"- Cross-module imports use the `app/<module>/...` alias, not `../../` (`WL9003`); relative paths stay inside a module.\",\n  '- Cascade uses standard decorators: never set `\"experimentalDecorators\": true` (`WL9004`).',\n  \"- Controllers are thin and read input with `request.validated()`, never `request.all()` (`WL9005`); schemas live in `schema/<action>.schema.ts` and export the value and its `Infer` type. One controller per file (`WL9011`).\",\n  \"- Every POST/PUT/PATCH/DELETE route is inside `guarded()` (or has auth middleware) or says `public: true` (`WL9006`).\",\n  \"- Redirect targets from request input go through `safeRedirect()` / `safeRedirectTarget()` (`WL9007`); logs never carry raw emails, credentials or request bodies (`WL9008`); regexes run on request input have bounded quantifiers (`WL9009`).\",\n  \"- Import each API from its home package: `v` from `@warlock.js/seal`, `Model` from `@warlock.js/cascade`, `router` from `@warlock.js/core`.\",\n];\n\nfunction skillsSection(skills: readonly InstalledSkill[]): string[] {\n  if (skills.length === 0) return [];\n\n  const byPackage = new Map<string, InstalledSkill[]>();\n\n  for (const skill of skills) {\n    byPackage.set(skill.package, [...(byPackage.get(skill.package) ?? []), skill]);\n  }\n\n  const lines = [\n    \"### Skills\",\n    \"\",\n    \"Installed with the packages, at `node_modules/<package>/skills/<slug>/SKILL.md`. Read the matching one before changing that area.\",\n    \"\",\n  ];\n\n  for (const packageName of [...byPackage.keys()].sort()) {\n    lines.push(`**${packageName}**`, \"\");\n\n    const entries = [...(byPackage.get(packageName) ?? [])].sort((first, second) =>\n      compare(first.slug, second.slug),\n    );\n\n    for (const skill of entries) {\n      const line = shortSkillLine(skill.description);\n\n      lines.push(`- \\`${skill.slug}\\`${line ? ` — ${line}` : \"\"}`);\n    }\n\n    lines.push(\"\");\n  }\n\n  return lines;\n}\n\nconst VERIFY = [\n  \"### Verify a change\",\n  \"\",\n  \"- `npx warlock check --changed --json` — typecheck, lint, affected tests and conventions; exit 1 = your code, 2 = this machine.\",\n  \"- `npx warlock inspect --json` — routes, models, config keys, events, pages, jobs from the booted app.\",\n  \"- `npx warlock explain <code>` — what a `WLxxxx` code means and how to fix it.\",\n  \"- `npx warlock trace <method> <url> --json` — send a request to the running `warlock dev` and print its devtools timeline.\",\n  \"- `npx warlock mcp` — the same facts and actions as an MCP server.\",\n  \"\",\n];\n\n/**\n * Render the app-specific AGENTS.md section from an inspect report: the app\n * and its Warlock packages, modules, a routes summary (unguarded writes\n * flagged), models, the conventions `warlock check` enforces, the installed\n * skills and the verify commands.\n *\n * Deterministic: no timestamps and stable ordering, so regenerating an\n * unchanged app yields the same bytes and `writeAgentsMd` writes nothing.\n * Returned without the markers.\n *\n * @param report An `inspectApp()` report (routes, models and packages are read when present).\n * @param options Skills and module folders to include.\n */\nexport function renderAgentsMdSection(\n  report: InspectReport,\n  options: RenderAgentsMdOptions = {},\n): string {\n  const lines = [\n    \"<!-- Generated by `warlock agents-md` and refreshed by `warlock dev`. Write your own notes outside the warlock:generated markers; everything between them is replaced. -->\",\n    \"\",\n    ...appSection(report),\n    ...modulesSection(report, options.modules ?? []),\n    ...routesSection(report, options.maxRoutes ?? 60),\n    ...modelsSection(report),\n    \"### Conventions in force\",\n    \"\",\n    ...CONVENTIONS,\n    \"\",\n    ...skillsSection(options.skills ?? []),\n    ...VERIFY,\n  ];\n\n  return `${lines.join(\"\\n\").replace(/\\n+$/, \"\")}\\n`;\n}\n"],"mappings":"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"}

package/esm/tooling/agents-md/write-agents-md.d.mts

@@ -0,0 +1,33 @@
+import { InspectReport } from "../inspect/inspect-report.types.mjs";
+import { InstalledSkill } from "./installed-skills.mjs";
+
+//#region ../../packages/core/src/tooling/agents-md/write-agents-md.d.ts
+/** What {@link writeAgentsMd} did. */
+type AgentsMdWriteStatus = "created" | "updated" | "unchanged" | "skipped";
+/** Options of {@link writeAgentsMd}. */
+type WriteAgentsMdOptions = {
+  /** Project root. Default: `process.cwd()`. */cwd?: string; /** The inspect report to render. */
+  report: InspectReport; /** Create AGENTS.md when it does not exist. Default: `true`; `false` reports `skipped`. */
+  create?: boolean; /** Skills to list. Default: `listInstalledSkills(cwd)`. */
+  skills?: readonly InstalledSkill[]; /** Module folders. Default: `listAppModules(cwd)`. */
+  modules?: readonly string[];
+};
+/** The result of {@link writeAgentsMd}. */
+type WriteAgentsMdResult = {
+  /** Absolute path of AGENTS.md. */file: string;
+  status: AgentsMdWriteStatus; /** The generated section, without markers. */
+  section: string;
+};
+/**
+ * Render the generated section and put it between the markers of
+ * `<cwd>/AGENTS.md`, preserving every byte outside them. Writes only when the
+ * content changed (atomically: temp file + rename). Throws `WL7501` on
+ * malformed markers, before writing anything.
+ *
+ * @example
+ * const { status } = writeAgentsMd({ report: await inspectApp() });
+ */
+declare function writeAgentsMd(options: WriteAgentsMdOptions): WriteAgentsMdResult;
+//#endregion
+export { AgentsMdWriteStatus, WriteAgentsMdOptions, WriteAgentsMdResult, writeAgentsMd };
+//# sourceMappingURL=write-agents-md.d.mts.map

package/esm/tooling/agents-md/write-agents-md.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-agents-md.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/write-agents-md.ts"],"mappings":";;;;;KAQY,mBAAA;AAAZ;AAAA,KAGY,oBAAA;gDAEV,GAAA,WAL6B;EAO7B,MAAA,EAAQ,aAAA,EAJsB;EAM9B,MAAA,YAEgC;EAAhC,MAAA,YAAkB,cAAc,IAJhC;EAMA,OAAA;AAAA;;KAIU,mBAAA;EAJV,kCAMA,IAAA;EACA,MAAA,EAAQ,mBAAmB,EAHjB;EAKV,OAAA;AAAA;;;;;;;AAAO;AAYT;;iBAAgB,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,mBAAmB"}