@zvndev/darkmown 2.4.1-next.7.ge25dbba → 2.5.0

package/types/catalog.d.ts

@@ -3,15 +3,86 @@
  * @returns {DirectiveCatalog}
  */
 export function directiveCatalog(): DirectiveCatalog;
+/**
+ * One page of a built site, as it appears in the generated `llms.txt` index and
+ * `llms-full.txt` corpus.
+ * @typedef {object} SitePage
+ * @property {string} title
+ * @property {string} url Absolute URL when the site declared `site_url`, else the route path.
+ * @property {string} description "" when the page has no `description:`.
+ * @property {string} [body] The page's source body (frontmatter stripped). Only
+ *   the corpus carries it; the index omits it.
+ */
+/**
+ * The site a generated llms file describes. Plain data, passed in by the builder
+ * (the only layer that knows the routes), so this module stays a pure renderer.
+ * @typedef {object} SiteCorpus
+ * @property {string} title
+ * @property {string} description
+ * @property {string} url Site origin, or "" when the home page set no `site_url`.
+ * @property {SitePage[]} pages Every emitted route, in route order.
+ */
 /**
  * Render the catalog as a compact llms.txt-style markdown cheatsheet — the
  * artifact an app pastes into a small model's system prompt. Generated entirely
  * from {@link directiveCatalog}, so it can never disagree with what compiles.
+ *
+ * When a `site` is supplied (the build always supplies one) the cheatsheet is
+ * followed by an INDEX of the site's pages and a pointer to `llms-full.txt`,
+ * which is the llms.txt convention: a short index, with the complete corpus one
+ * fetch away.
+ * @param {SiteCorpus} [site] The built site to index.
  * @returns {string}
  */
-export function llmsText(): string;
+export function llmsText(site?: SiteCorpus): string;
+/**
+ * Render `llms-full.txt`: the COMPLETE corpus that `llms.txt` indexes. Where the
+ * cheatsheet is one line per directive, this carries the full syntax template,
+ * description, example, and reactivity for every one, plus every compile-error
+ * code with its cause and fix: and then the full source text of every page on
+ * the site. Same generator, same catalog, so index and corpus cannot disagree.
+ * @param {SiteCorpus} [site] The built site whose pages form the corpus.
+ * @returns {string}
+ */
+export function llmsFullText(site?: SiteCorpus): string;
 /** The action tokens the catalog exposes — used by the drift guard. */
 export const CATALOG_ACTION_TOKENS: string[];
+/**
+ * One page of a built site, as it appears in the generated `llms.txt` index and
+ * `llms-full.txt` corpus.
+ */
+export type SitePage = {
+    title: string;
+    /**
+     * Absolute URL when the site declared `site_url`, else the route path.
+     */
+    url: string;
+    /**
+     * "" when the page has no `description:`.
+     */
+    description: string;
+    /**
+     * The page's source body (frontmatter stripped). Only
+     * the corpus carries it; the index omits it.
+     */
+    body?: string | undefined;
+};
+/**
+ * The site a generated llms file describes. Plain data, passed in by the builder
+ * (the only layer that knows the routes), so this module stays a pure renderer.
+ */
+export type SiteCorpus = {
+    title: string;
+    description: string;
+    /**
+     * Site origin, or "" when the home page set no `site_url`.
+     */
+    url: string;
+    /**
+     * Every emitted route, in route order.
+     */
+    pages: SitePage[];
+};
 /**
  * Whether the directive
  *   ships zero JS (static), needs the reactive runtime (reactive), or can be
@@ -84,6 +155,14 @@ export type DirectiveCatalog = {
      * Logical joiners (`and`/`or`/`not`).
      */
     predicateJoiners: string[];
+    /**
+     * Frontmatter keys the framework reads.
+     */
+    frontmatterKeys: CatalogEntry[];
+    /**
+     * The `schema:` JSON-LD types the compiler can populate.
+     */
+    schemaTypes: string[];
     /**
      * The `WDxxx` code blocks.
      */

package/types/compiler/context.d.ts

@@ -66,6 +66,32 @@
  *   read threads through — the real filesystem by default, or an in-memory map
  *   for `compileFromMemory`. Set once by `createCompilation` and reached via
  *   `ctx.comp.reader` in the directive handlers (includes, loop data).
+ * @property {Symbol[]} symbols Every declared thing this compile saw, in source
+ *   order, recorded by {@link recordSymbol} from the handler that parsed it.
+ *   Surfaced on {@link CompiledPage} so a tool layer can answer "what is in this
+ *   page?" without parsing `.wd` a second time.
+ */
+/**
+ * One declared thing in a page, as the compiler saw it.
+ *
+ * `kind` is the directive family; `name` is what an author would call the thing
+ * and is what `refs` matches on. `detail` is a short human string in the same
+ * vocabulary the model writes, never a serialized AST: the tool layer's job is
+ * to hand back text a model can nearly paste, and translation is where small
+ * models lose.
+ *
+ * @typedef {object} Symbol
+ * @property {"state" | "store" | "computed" | "theme" | "fetch" | "action" | "loop" | "form" | "field" | "if" | "include" | "read"} kind
+ * @property {string} name The symbol's own name, or the thing it targets.
+ * @property {string} [detail] Short source-shaped description, e.g. `cart append p`.
+ * @property {boolean} [reactive] For loops: whether it stays reactive at runtime.
+ * @property {string} [target] For actions: the state key written.
+ * @property {string} [op] For actions: the validated action token.
+ * @property {string} file Absolute path of the file the symbol was declared in.
+ * @property {number} [endLine] For a block directive (`@loop`, `:if`), the
+ *   1-based line its closer sits on, so a tool can address the whole block.
+ * @property {number | null} line 1-based line in that file, or null for a read
+ *   recorded by {@link recordRead} (see there for why prose reads carry no line).
  */
 /**
  * A lexical scope chain for static interpolation values (include args, loop vars).
@@ -119,6 +145,8 @@
  *   `@loop` recorded, or null. The builder reads it to multiply routes.
  * @property {Set<string>} deps Absolute source-file dependencies of this compile.
  * @property {Set<string>} collectionsUsed Collection names this compile looped.
+ * @property {Symbol[]} symbols Every declared thing the compile saw, in
+ *   source order. See {@link recordSymbol}.
  */
 /**
  * A compiled page: the document plus its full HTML shell.
@@ -131,6 +159,8 @@
  *   `@loop` recorded, or null. The builder reads it to multiply routes.
  * @property {Set<string>} deps Absolute source-file dependencies of this compile.
  * @property {Set<string>} collectionsUsed Collection names this compile looped.
+ * @property {Symbol[]} symbols Every declared thing the compile saw, in
+ *   source order. See {@link recordSymbol}.
  */
 /**
  * Structured, machine-readable companion to a compile error's string message.
@@ -208,6 +238,68 @@ export function normalizeNewlines(text: string): string;
  * @returns {Compilation}
  */
 export function createCompilation(reader: import("./reader.js").Reader): Compilation;
+/**
+ * Record one declared thing as the handler that owns it parses it.
+ *
+ * This is the compiler telling a tool layer what is in a page, rather than a
+ * tool layer parsing `.wd` a second time. A shadow parser drifts, and the day it
+ * disagrees with `compilePage` it tells a model something true about a file that
+ * will not compile.
+ *
+ * Called from the `handle*` functions, where the 0-based `index` is live, so
+ * every symbol carries a real `file:line`. Include bodies share the parent's
+ * `Compilation` but compile under their own `ctx.file`, so attribution stays
+ * correct with no extra plumbing.
+ *
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index into the current body slice.
+ * @param {Omit<Symbol, "file" | "line">} sym
+ * @returns {Symbol} The pushed record, so a caller whose reactive/static decision
+ *   happens in a later branch can stamp it rather than duplicate that logic.
+ */
+export function recordSymbol(ctx: Ctx, index: number, sym: Omit<Symbol, "file" | "line">): Symbol;
+/**
+ * Record where a block directive CLOSES, so a tool layer can address the whole
+ * construct rather than only its opening line.
+ *
+ * Measured need, not speculation: with only the opener line recorded, the 1.5B
+ * targeted a `@loop` for replacement and swapped out its header, leaving the
+ * `@endloop` behind. That produced `[WD010] Stray "@endloop"` as the single
+ * most common compile failure of the round-4 tool run. A `@loop` is three or
+ * more lines and a tool has to be able to say so.
+ *
+ * The dispatcher owns this because only it has the block's extent, from
+ * `scanBlock`/`scanConditional`. `at` is the index the block handler's own
+ * symbol was pushed to; nested symbols recorded while compiling the body land
+ * after it and are left alone.
+ *
+ * @param {Ctx} ctx
+ * @param {number} at Index into `ctx.comp.symbols` the block handler wrote to.
+ * @param {number} endIndex 0-based body index of the closing line.
+ * @returns {void}
+ */
+export function stampBlockEnd(ctx: Ctx, at: number, endIndex: number): void;
+/**
+ * Record that a page READS a state key through an interpolation.
+ *
+ * Deliberately line-less. Prose is rendered a chunk at a time by markdown-it, so
+ * no 0-based body `index` is in scope at the point a `{ name }` binding resolves,
+ * and threading one through the markdown layer would mean tracking source
+ * positions inside a renderer that does not care about them.
+ *
+ * Instead the compiler records the two things only it can know: that the
+ * expression resolved to this state key, and the exact expression text. The tool
+ * layer locates the line by searching the file for that compiler-supplied
+ * string, which is a substring search for a known needle rather than a second
+ * parser. Duplicates (a static loop re-renders its body once per row) are the
+ * caller's to fold.
+ *
+ * @param {Ctx} ctx
+ * @param {string} key Resolved state key.
+ * @param {string} expr The binding expression as authored, e.g. `cart | count`.
+ * @returns {void}
+ */
+export function recordRead(ctx: Ctx, key: string, expr: string): void;
 /**
  * @param {Scope | null} parent
  * @param {Record<string, unknown>} [vars]
@@ -396,6 +488,59 @@ export type Compilation = {
      * `ctx.comp.reader` in the directive handlers (includes, loop data).
      */
     reader: import("./reader.js").Reader;
+    /**
+     * Every declared thing this compile saw, in source
+     * order, recorded by {@link recordSymbol} from the handler that parsed it.
+     * Surfaced on {@link CompiledPage} so a tool layer can answer "what is in this
+     * page?" without parsing `.wd` a second time.
+     */
+    symbols: Symbol[];
+};
+/**
+ * One declared thing in a page, as the compiler saw it.
+ *
+ * `kind` is the directive family; `name` is what an author would call the thing
+ * and is what `refs` matches on. `detail` is a short human string in the same
+ * vocabulary the model writes, never a serialized AST: the tool layer's job is
+ * to hand back text a model can nearly paste, and translation is where small
+ * models lose.
+ */
+export type Symbol = {
+    kind: "state" | "store" | "computed" | "theme" | "fetch" | "action" | "loop" | "form" | "field" | "if" | "include" | "read";
+    /**
+     * The symbol's own name, or the thing it targets.
+     */
+    name: string;
+    /**
+     * Short source-shaped description, e.g. `cart append p`.
+     */
+    detail?: string | undefined;
+    /**
+     * For loops: whether it stays reactive at runtime.
+     */
+    reactive?: boolean | undefined;
+    /**
+     * For actions: the state key written.
+     */
+    target?: string | undefined;
+    /**
+     * For actions: the validated action token.
+     */
+    op?: string | undefined;
+    /**
+     * Absolute path of the file the symbol was declared in.
+     */
+    file: string;
+    /**
+     * For a block directive (`@loop`, `:if`), the
+     * 1-based line its closer sits on, so a tool can address the whole block.
+     */
+    endLine?: number | undefined;
+    /**
+     * 1-based line in that file, or null for a read
+     * recorded by {@link recordRead} (see there for why prose reads carry no line).
+     */
+    line: number | null;
 };
 /**
  * A lexical scope chain for static interpolation values (include args, loop vars).
@@ -517,6 +662,11 @@ export type CompiledDocument = {
      * Collection names this compile looped.
      */
     collectionsUsed: Set<string>;
+    /**
+     * Every declared thing the compile saw, in
+     * source order. See {@link recordSymbol}.
+     */
+    symbols: Symbol[];
 };
 /**
  * A compiled page: the document plus its full HTML shell.
@@ -539,6 +689,11 @@ export type CompiledPage = {
      * Collection names this compile looped.
      */
     collectionsUsed: Set<string>;
+    /**
+     * Every declared thing the compile saw, in
+     * source order. See {@link recordSymbol}.
+     */
+    symbols: Symbol[];
 };
 /**
  * Structured, machine-readable companion to a compile error's string message.

package/types/compiler/page.d.ts

@@ -2,13 +2,15 @@
  * Compile a page source file into a full HTML document plus its assets.
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader }} [options]
+ * @param {{ feed?: { href: string, title: string }, site?: SiteContext, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader }} [options]
  *   When a site-wide RSS feed is emitted (the home page set `site_url` and the
  *   site has dated posts), `feed` carries its absolute href + title so every page
- *   links it. `collections` is the build-time collection index a bare-name
- *   `@loop` resolves against; `vars` seeds the document scope (the pager `page`
- *   object on a paginated route). `reader` is the source reader (fs-backed by
- *   default via `src/compiler.js`; in-memory for `compileFromMemory`).
+ *   links it. `site` carries the origin + this page's own route (and its resolved
+ *   breadcrumb trail) so the shell can state a canonical URL. `collections` is the
+ *   build-time collection index a bare-name `@loop` resolves against; `vars` seeds
+ *   the document scope (the pager `page` object on a paginated route). `reader` is
+ *   the source reader (fs-backed by default via `src/compiler.js`; in-memory for
+ *   `compileFromMemory`).
  * @returns {CompiledPage}
  */
 export function compilePage(file: string, context: Paths, options?: {
@@ -16,6 +18,7 @@ export function compilePage(file: string, context: Paths, options?: {
         href: string;
         title: string;
     };
+    site?: SiteContext;
     collections?: Map<string, import("./collections.js").CollectionRow[]>;
     vars?: Record<string, unknown>;
     reader?: import("./reader.js").Reader;
@@ -86,7 +89,7 @@ export function compileFile(file: string, context: Paths, stack: string[], scope
  * @param {Record<string, string> | Map<string, string>} files Project-relative
  *   path → source content.
  * @param {string} entryPath Project-relative path of the page to compile.
- * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, cwd?: string }} [options]
+ * @param {{ feed?: { href: string, title: string }, site?: SiteContext, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, cwd?: string }} [options]
  *   Same shell options as {@link compilePage}; `cwd` overrides the virtual
  *   project root the relative keys resolve against (defaults to `/`).
  * @returns {CompiledPage}
@@ -96,10 +99,34 @@ export function compileFromMemory(files: Record<string, string> | Map<string, st
         href: string;
         title: string;
     };
+    site?: SiteContext;
     collections?: Map<string, import("./collections.js").CollectionRow[]>;
     vars?: Record<string, unknown>;
     cwd?: string;
 }): CompiledPage;
+/**
+ * Where this page sits on a real, deployed site: the origin the home page
+ * declared with `site_url`, the concrete route this page is written to, and the
+ * breadcrumb trail the builder resolved from the routes that actually exist.
+ * Supplied by `src/builder.js`, the only layer that knows all three.
+ */
+export type SiteContext = {
+    /**
+     * Absolute site origin, e.g. `https://example.com`.
+     */
+    url: string;
+    /**
+     * Public route path for THIS page (trailing-slashed).
+     */
+    route: string;
+    /**
+     * Resolved crumb trail.
+     */
+    breadcrumbs?: {
+        name: string;
+        url: string;
+    }[] | undefined;
+};
 export type Paths = import("./context.js").Paths;
 export type Meta = import("./context.js").Meta;
 export type Scope = import("./context.js").Scope;

package/types/compiler/schema.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Whether a page's frontmatter declares an article-family `schema:` type. Used
+ * by the page shell to pick `og:type` (`article` vs `website`).
+ * @param {Meta} meta
+ * @returns {boolean}
+ */
+export function isArticleSchema(meta: Meta): boolean;
+/**
+ * Everything the JSON-LD builders may read. Only page-derived facts: the shell's
+ * already-resolved title/description/image/lang, the page's frontmatter, and the
+ * absolute URL the builder resolved for it.
+ * @typedef {object} SchemaInput
+ * @property {Meta} meta Page frontmatter.
+ * @property {string} file Source path, for compile errors.
+ * @property {string} title Resolved page title.
+ * @property {string} description Resolved page description ("" when absent).
+ * @property {string} image Absolute social image URL ("" when absent).
+ * @property {string} lang Document language.
+ * @property {string} canonical Absolute canonical URL ("" when no `site_url`).
+ * @property {{ name: string, url: string }[]} breadcrumbs Resolved crumb trail.
+ */
+/**
+ * Build the page's `<script type="application/ld+json">` block, or "" when the
+ * page opts into nothing. Two independent inputs feed it: the `schema:`
+ * frontmatter type (or types), and a breadcrumb trail the builder resolved for a
+ * nested route. Two or more nodes are emitted as a JSON array in one script,
+ * which is valid JSON-LD and one fewer tag in the head.
+ * @param {SchemaInput} input
+ * @returns {string} The script tag, or "" when there is nothing to say.
+ */
+export function buildJsonLd(input: SchemaInput): string;
+/**
+ * @typedef {import("./context.js").Meta} Meta
+ */
+/**
+ * The `schema:` types Darkmown knows how to populate from real page data:
+ * article-family types from a page's title/description/date/author, and the two
+ * site-identity types from what a home page already declares. Anything else is
+ * a compile error rather than a guess. `BreadcrumbList` is not listed because it
+ * is never opted into: it is derived automatically from routes that exist.
+ * @type {string[]}
+ */
+export const SCHEMA_TYPES: string[];
+/** A concrete, copyable `schema:` frontmatter line for docs and error hints. */
+export const SCHEMA_EXAMPLE: "schema: BlogPosting";
+/**
+ * Everything the JSON-LD builders may read. Only page-derived facts: the shell's
+ * already-resolved title/description/image/lang, the page's frontmatter, and the
+ * absolute URL the builder resolved for it.
+ */
+export type SchemaInput = {
+    /**
+     * Page frontmatter.
+     */
+    meta: Meta;
+    /**
+     * Source path, for compile errors.
+     */
+    file: string;
+    /**
+     * Resolved page title.
+     */
+    title: string;
+    /**
+     * Resolved page description ("" when absent).
+     */
+    description: string;
+    /**
+     * Absolute social image URL ("" when absent).
+     */
+    image: string;
+    /**
+     * Document language.
+     */
+    lang: string;
+    /**
+     * Absolute canonical URL ("" when no `site_url`).
+     */
+    canonical: string;
+    /**
+     * Resolved crumb trail.
+     */
+    breadcrumbs: {
+        name: string;
+        url: string;
+    }[];
+};
+export type Meta = import("./context.js").Meta;

package/types/compiler.d.ts

@@ -4,7 +4,7 @@
  * a different source (see `compileFromMemory`).
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {import("./config.js").Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader }} [options]
+ * @param {{ feed?: { href: string, title: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader }} [options]
  * @returns {CompiledPage}
  */
 export function compilePage(file: string, context: import("./config.js").Paths, options?: {
@@ -12,6 +12,7 @@ export function compilePage(file: string, context: import("./config.js").Paths,
         href: string;
         title: string;
     };
+    site?: import("./compiler/page.js").SiteContext;
     collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>;
     vars?: Record<string, unknown>;
     reader?: import("./compiler/reader.js").Reader;

package/types/feeds.d.ts

@@ -109,13 +109,56 @@ export function buildRss(channel: {
     feedUrl: string;
 }, items: RssItem[]): string;
 /**
- * Build `robots.txt`. Always allows everything (hidden/draft routes are never
- * built, so there's nothing to `Disallow`). The `Sitemap:` line is included
- * ONLY when `siteUrl` is set — a sitemap URL is only meaningful with an origin.
+ * Build `robots.txt`. The wildcard group always allows everything (hidden/draft
+ * routes are never built, so there's nothing to `Disallow`), then every
+ * {@link AI_CRAWLERS} token is named explicitly with the site's declared policy.
+ * The `Sitemap:` line is included ONLY when `siteUrl` is set: a sitemap URL is
+ * only meaningful with an origin.
  * @param {string} [siteUrl] Absolute origin, or "" / undefined to omit the line.
+ * @param {string} [policy] `"allow"` (default) or `"deny"`, from the home page's
+ *   `ai_crawlers:` frontmatter. Validated by the caller ({@link aiCrawlerPolicy}).
  * @returns {string} The robots.txt body (trailing newline).
  */
-export function buildRobots(siteUrl?: string): string;
+export function buildRobots(siteUrl?: string, policy?: string): string;
+/**
+ * Validate the home page's `ai_crawlers:` frontmatter into a policy string.
+ * Absent means `allow` (the status quo the wildcard group already grants). A
+ * value that is neither `allow` nor `deny` throws rather than defaulting: the
+ * likely intent behind a typo like `ai_crawlers: block` is to opt OUT, and
+ * silently allowing instead would be exactly the wrong failure direction.
+ * @param {import("./compiler.js").Meta} meta Home page frontmatter.
+ * @param {string} [file] Home page source path, for the error message.
+ * @returns {string} One of {@link AI_CRAWLER_POLICIES}.
+ */
+export function aiCrawlerPolicy(meta: import("./compiler.js").Meta, file?: string): string;
+/**
+ * The AI crawler and answer-engine robots.txt tokens Darkmown names explicitly.
+ *
+ * EVERY token here is copied from its own operator's published documentation
+ * (checked 2026-08-09): none are guessed, inferred from a log, or carried over
+ * from a third-party list. A wrong token is worse than a missing one: it looks
+ * like a policy the site is stating and is silently ignored by everybody.
+ *
+ * `Allow: /` for these is not a permission change (the `User-agent: *` group
+ * already allows them); it is an explicit, machine-readable statement of intent,
+ * which is what a publisher wants when the goal is to BE cited by answer engines.
+ * The same list is what `ai_crawlers: deny` turns into `Disallow: /`, which is
+ * the only form that actually changes anything.
+ *
+ * The `note` is written into the generated file next to the group. Search
+ * crawling, model training, and live user-triggered fetches are DIFFERENT
+ * permissions from the same operator, and a future reader editing robots.txt by
+ * hand needs to see that before collapsing a group.
+ * @type {{ operator: string, docs: string, note: string, agents: string[] }[]}
+ */
+export const AI_CRAWLERS: {
+    operator: string;
+    docs: string;
+    note: string;
+    agents: string[];
+}[];
+/** The accepted `ai_crawlers:` frontmatter values. */
+export const AI_CRAWLER_POLICIES: string[];
 /** Most-recent-first RSS post cap — a feed is a recent window, not an archive. */
 export const RSS_ITEM_LIMIT: 20;
 export type Route = import("./router.js").Route;

package/types/index.d.ts

@@ -5,6 +5,9 @@
 export { buildSite } from "./builder.js";
 export type { RouteManifestEntry, Paths, Assets } from "./builder.js";
 
+export { directiveCatalog, llmsText } from "./catalog.js";
+export type { DirectiveCatalog, DirectiveEntry, CatalogEntry, Reactivity } from "./catalog.js";
+
 export {
   compilePage,
   compileDocument,

package/types/scaffold.d.ts

@@ -7,7 +7,9 @@ export function availableTemplates(): string[];
  * Scaffold a new Darkmown project into `root` from a template, creating files
  * that don't already exist (never overwriting). `package.json` is generated (so
  * the name tracks the directory and the `@zvndev/darkmown` dep pins the installed
- * version); every other file is copied verbatim from the chosen template.
+ * version); `AGENTS.md` is copied from the package so coding agents find the
+ * directive reference at the project root; `CLAUDE.md` and `.gitignore` are
+ * generated; every other file is copied verbatim from the chosen template.
  * @param {string} root Absolute path to the target project directory.
  * @param {{ template?: string }} [options] `template` defaults to `"starter"`.
  * @returns {{ root: string, template: string }}

package/types/tools/apply.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Resolve one edit's target to a 1-based inclusive line range in `source`.
+ *
+ * Every rejection names what was wrong AND what would have worked, because a
+ * rejection a model cannot act on is just a failed attempt.
+ *
+ * @param {string} source
+ * @param {Edit} edit
+ * @param {import("../compiler/context.js").Symbol[]} symbols
+ * @returns {{ok: true, from: number, to: number} | {ok: false, error: string}}
+ */
+export function resolveTarget(source: string, edit: Edit, symbols: import("../compiler/context.js").Symbol[]): {
+    ok: true;
+    from: number;
+    to: number;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * TOOL ENTRY POINT.
+ *
+ * @param {Record<string, string>} files
+ * @param {string} entry File to edit, in the same key form as `files`.
+ * @param {Edit[]} [edits] Missing or empty is reported, not thrown.
+ * @returns {{ok: boolean, text: string, data: object}}
+ */
+export function apply(files: Record<string, string>, entry: string, edits?: Edit[]): {
+    ok: boolean;
+    text: string;
+    data: object;
+};
+/** The operations a caller may ask for. Closed, and validated per edit. */
+export const OPS: Set<string>;
+/**
+ * One edit, as a caller (or a model) writes it.
+ *
+ * Every field is optional because a malformed edit is REPORTED, not thrown: the
+ * whole point of this surface is that a model gets a sentence back telling it
+ * what to fix. Typing them as required would describe a contract this module
+ * deliberately does not enforce at the boundary.
+ */
+export type Edit = {
+    /**
+     * One of {@link OPS}.
+     */
+    op?: string | undefined;
+    /**
+     * 1-based line, as printed by `outline`.
+     */
+    line?: number | undefined;
+    /**
+     * A symbol target, e.g. `state:cart`.
+     */
+    symbol?: string | undefined;
+    /**
+     * Exact source text to find.
+     */
+    anchor?: string | undefined;
+    /**
+     * Replacement or inserted text.
+     */
+    text?: string | undefined;
+    /**
+     * What the caller believed is at `line`, for staleness.
+     */
+    expect?: string | undefined;
+};