@cat-factory/agents 0.40.13 → 0.42.0

package/dist/agents/kinds/code-commenter.d.ts

@@ -0,0 +1,10 @@
+import type { AgentKindDefinition, AgentKindRegistry } from './registry.js';
+export declare const CODE_COMMENTER_KIND = "code-commenter";
+/** The in-source comment annotator kind (initiative-presets slice 7). */
+export declare const CODE_COMMENTER_AGENT_KINDS: AgentKindDefinition[];
+/**
+ * Register the code-commenter kind on the given registry. Called by `defaultAgentKindRegistry()`;
+ * idempotent (the registry replaces by kind).
+ */
+export declare function registerCodeCommenterAgent(registry: AgentKindRegistry): void;
+//# sourceMappingURL=code-commenter.d.ts.map

package/dist/agents/kinds/code-commenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-commenter.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/code-commenter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AA+B3E,eAAO,MAAM,mBAAmB,mBAAmB,CAAA;AAuDnD,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,EAAE,mBAAmB,EAoB3D,CAAA;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAE5E"}

package/dist/agents/kinds/code-commenter.js

@@ -0,0 +1,106 @@
+import { DOC_AWARE_TRAIT } from './traits.js';
+import { PLATFORM_DELIVERY_CONTRACT } from '../prompts/delivery-contract.js';
+import { STANDARDS_FOOTER } from '../prompts/shared.js';
+import { linkedContextSection } from '../prompts/standard.js';
+// ---------------------------------------------------------------------------
+// `code-commenter` — adds and clarifies WHY-not-what comments in EXISTING source, with no
+// behaviour change (initiative-presets slice 7, the in-source-comments leg of the docs-refresh
+// preset).
+//
+// It is the ONE genuinely-new capability the docs-refresh preset needs: every other doc type it
+// authors is a document a writer already produces (READMEs and diagrams reuse `doc-writer`; a
+// Mermaid `.md` is just Markdown; business rules reuse `business-documenter`). Comments are the
+// opposite — an IN-PLACE edit of existing `.ts`/`.py`/… files, comment-only, that must not change
+// behaviour. That directly contradicts `doc-writer`'s load-bearing contract ("write ONLY that
+// document — do not touch code"), so no document writer can express it, and `coder` (whose role is
+// to CHANGE code) would fight its own prompt. Hence a dedicated kind with a hard comment-only
+// contract; the pipeline's `ci` step is the backstop that proves the diff is behaviour-neutral.
+//
+// It runs the SAME generic container-coding lifecycle as `doc-writer` / `coder`
+// (`buildRegisteredAgentBody` with `clone: { branch: 'work' }`), so it needs NO bespoke harness
+// handler and NO executor-harness image bump. Its product is a pushed commit, so — like the
+// coder / doc-writer — it must NOT carry `FINAL_ANSWER_IN_REPLY` (`applySurfaceDirectives`
+// already withholds it from a `container-coding` kind). It is `doc-aware` so the engine folds the
+// block's writing-style fragments (anti-LLM-isms, concise & actionable) into its prompt — comments
+// are writing, so the same style guidance applies (the `code-aware` analogue for authored text).
+//
+// See `docs/initiatives/initiative-presets-and-docs-refresh.md` (slice 7).
+// ---------------------------------------------------------------------------
+export const CODE_COMMENTER_KIND = 'code-commenter';
+/** The docs-refresh spawn (slice 8) sets this per item (the module to comment); standalone runs leave it unset. */
+function targetPath(context) {
+    return context.block.taskTypeFields?.targetPath?.trim() || undefined;
+}
+const CODE_COMMENTER_SYSTEM_PROMPT = [
+    'You are a senior engineer improving a codebase’s in-source comments. Add and clarify comments',
+    'that explain the WHY — intent, invariants, trade-offs, non-obvious constraints and gotchas —',
+    'not the what a reader can already see from the code itself.',
+    '',
+    'Absolute rule — NO behaviour change:',
+    '- Touch ONLY comments and docstrings. Do not change any executable code: no edits to logic,',
+    '  control flow, signatures, names, imports, or types, and no reformatting or reordering of code.',
+    '  The build, the linters and the tests must pass unchanged — the pipeline’s CI step verifies',
+    '  this, so a comment-only diff is the whole deliverable.',
+    '- Remove or fix comments that are now wrong or misleading, and delete dead/commented-out code',
+    '  only when it is plainly obsolete; when unsure, leave it.',
+    '',
+    'Approach:',
+    '- Read the code first, then focus on what is hardest to understand: complex algorithms, subtle',
+    '  concurrency or ordering, workarounds, security- or money-sensitive paths, and public APIs that',
+    '  lack a docstring. Do not comment self-evident lines (no `// increment i`).',
+    '- Match the file’s existing comment style and the language’s docstring convention. Keep comments',
+    '  concise and accurate; a wrong comment is worse than none.',
+    '',
+    PLATFORM_DELIVERY_CONTRACT,
+    '',
+    STANDARDS_FOOTER,
+].join('\n');
+function codeCommenterUserPrompt(context) {
+    const lines = [
+        `Pipeline: ${context.pipelineName}`,
+        `Task: ${context.block.title}`,
+        `Brief: ${context.block.description?.trim() || '(none provided — infer the scope from the title and the code)'}`,
+    ];
+    const path = targetPath(context);
+    if (path)
+        lines.push(`Comment the code under: \`${path}\`.`);
+    const linked = linkedContextSection(context, { materialized: true });
+    if (linked)
+        lines.push(linked);
+    if (context.priorOutputs.length) {
+        lines.push('', 'Work from earlier steps in this pipeline (build on it, do not repeat it):');
+        for (const p of context.priorOutputs)
+            lines.push(`### ${p.agentKind}`, p.output ?? '');
+    }
+    lines.push('', 'Add and clarify WHY-not-what comments on the hardest-to-follow code in scope. Change comments', 'and docstrings ONLY — no code, formatting or behaviour changes (CI will verify). The platform', 'commits your changes and opens the pull request — do not run git yourself.');
+    return lines.filter(Boolean).join('\n');
+}
+/** The in-source comment annotator kind (initiative-presets slice 7). */
+export const CODE_COMMENTER_AGENT_KINDS = [
+    {
+        kind: CODE_COMMENTER_KIND,
+        systemPrompt: CODE_COMMENTER_SYSTEM_PROMPT,
+        userPrompt: codeCommenterUserPrompt,
+        // Container-coding with a `work` clone ⇒ branch off base, edit only comments, push the work
+        // branch and open a PR (coder-like). The pipeline's CI tail proves the diff is behaviour-neutral.
+        agent: { surface: 'container-coding', clone: { branch: 'work' } },
+        // Doc-aware: the engine folds the block's writing-style fragments (anti-LLM-isms, concise &
+        // actionable) into the prompt — comments are writing, so the style guidance applies.
+        traits: [DOC_AWARE_TRAIT],
+        presentation: {
+            label: 'Code Commenter',
+            icon: 'i-lucide-message-square-code',
+            color: '#818cf8',
+            description: 'Adds and clarifies why-not-what comments in the source with no behaviour change, opening a pull request.',
+            category: 'docs',
+        },
+    },
+];
+/**
+ * Register the code-commenter kind on the given registry. Called by `defaultAgentKindRegistry()`;
+ * idempotent (the registry replaces by kind).
+ */
+export function registerCodeCommenterAgent(registry) {
+    registry.registerAll(CODE_COMMENTER_AGENT_KINDS);
+}
+//# sourceMappingURL=code-commenter.js.map

package/dist/agents/kinds/code-commenter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-commenter.js","sourceRoot":"","sources":["../../../src/agents/kinds/code-commenter.ts"],"names":[],"mappings":"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"}

package/dist/agents/kinds/registry.d.ts

@@ -113,7 +113,8 @@ export interface AgentKindDefinition {
  * `Map`, no `clear*()` test cruft, and no external-adapter module-identity gotcha: a
  * deployment registers extra kinds by reference (`registry.register(def)`) on the instance the
  * facade injects. The built-in kinds (`bug-investigator` / `repro-test` / `environment-analyst`
- * / the document + initiative kinds) are pre-loaded by the factory, not by an import side effect.
+ * / `code-commenter` / the document + initiative kinds) are pre-loaded by the factory, not by an
+ * import side effect.
  */
 export declare class AgentKindRegistry {
     private readonly registry;

package/dist/agents/kinds/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"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"}

package/dist/agents/kinds/registry.js

@@ -1,6 +1,7 @@
 import { registerBugInvestigatorAgent } from './bug-investigator.js';
 import { registerReproTestAgent } from './repro-test.js';
 import { registerDocumentAgents } from './document.js';
+import { registerCodeCommenterAgent } from './code-commenter.js';
 import { registerInitiativeAgents } from './initiative.js';
 import { registerEnvironmentAnalystAgent } from './environment-analyst.js';
 /**
@@ -22,7 +23,8 @@ function withDerivedOutput(definition) {
  * `Map`, no `clear*()` test cruft, and no external-adapter module-identity gotcha: a
  * deployment registers extra kinds by reference (`registry.register(def)`) on the instance the
  * facade injects. The built-in kinds (`bug-investigator` / `repro-test` / `environment-analyst`
- * / the document + initiative kinds) are pre-loaded by the factory, not by an import side effect.
+ * / `code-commenter` / the document + initiative kinds) are pre-loaded by the factory, not by an
+ * import side effect.
  */
 export class AgentKindRegistry {
     registry = new Map();
@@ -126,6 +128,7 @@ export function defaultAgentKindRegistry() {
     registerBugInvestigatorAgent(registry);
     registerReproTestAgent(registry);
     registerDocumentAgents(registry);
+    registerCodeCommenterAgent(registry);
     registerInitiativeAgents(registry);
     registerEnvironmentAnalystAgent(registry);
     return registry;

package/dist/agents/kinds/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { type AcceptanceAgentKind, ACCEPTANCE_AGENT_KINDS, acceptanceSystemPromp
 export { type CompanionDefinition, COMPANIONS, isCompanionKind, companionFor, companionTargets, isContainerBackedCompanion, } from './agents/kinds/companions.js';
 export { companionSystemPrompt } from './agents/prompts/companion.js';
 export { DOC_RESEARCHER_KIND, DOC_OUTLINER_KIND, DOC_WRITER_KIND, DOC_FINALIZER_KIND, DOC_REVIEWER_KIND, DOC_FIXER_KIND, DOCUMENT_AGENT_KINDS, registerDocumentAgents, resolveDocumentTarget, type DocumentTarget, } from './agents/kinds/document.js';
+export { CODE_COMMENTER_KIND, CODE_COMMENTER_AGENT_KINDS, registerCodeCommenterAgent, } from './agents/kinds/code-commenter.js';
 export { type DocTemplate, type DocTemplateSection, DOC_TEMPLATES, registerDocTemplate, registerDocTemplates, clearRegisteredDocTemplates, docTemplateFor, resolveDocTemplate, requiredSectionTitles, renderTemplateSkeleton, } from './agents/kinds/doc-templates.js';
 export { INITIATIVE_BREAKDOWN_KIND, INITIATIVE_AGENT_KINDS, registerInitiativeAgents, } from './agents/kinds/initiative.js';
 export { READ_ONLY_AGENT_KINDS, READ_ONLY_GUARDRAIL, isReadOnlyAgentKind, } from './agents/kinds/read-only.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,2BAA2B,EAAE,MAAM,8BAA8B,CAAA;AAChG,OAAO,EACL,KAAK,sBAAsB,EAC3B,+BAA+B,EAC/B,kCAAkC,EAClC,sBAAsB,EACtB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAA;AAMrE,OAAO,EACL,KAAK,mBAAmB,EACxB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,iBAAiB,EACjB,8BAA8B,EAC9B,yBAAyB,EACzB,kCAAkC,EAClC,kCAAkC,GACnC,MAAM,gCAAgC,CAAA;AAGvC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,sBAAsB,GACvB,MAAM,qCAAqC,CAAA;AAI5C,OAAO,EACL,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,iBAAiB,EACjB,wBAAwB,EACxB,SAAS,EACT,QAAQ,EACR,gBAAgB,GACjB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAGlG,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EACL,qCAAqC,EACrC,qCAAqC,EACrC,4CAA4C,EAC5C,4CAA4C,GAC7C,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AACjE,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,eAAe,GACrB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,KAAK,aAAa,EAClB,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,oBAAoB,EACpB,wBAAwB,EACxB,WAAW,GACZ,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,KAAK,mBAAmB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,KAAK,mBAAmB,EACxB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AAKrE,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,cAAc,GACpB,MAAM,4BAA4B,CAAA;AAQnC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,EAC3B,cAAc,EAId,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,4BAA4B,GAC7B,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EACL,wBAAwB,EACxB,+BAA+B,EAC/B,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,+BAA+B,GAChC,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AACxF,OAAO,EACL,KAAK,sBAAsB,EAC3B,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAA;AAClF,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,4BAA4B,CAAA;AAMnC,OAAO,EACL,KAAK,YAAY,EACjB,sBAAsB,EACtB,UAAU,EACV,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAI7B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAI9C,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAKnE,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,0BAA0B,CAAA;AAKjC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,mCAAmC,EACnC,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,8BAA8B,EAC9B,KAAK,WAAW,EAChB,qBAAqB,EACrB,0BAA0B,EAC1B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,sBAAsB,EACtB,KAAK,kCAAkC,GACxC,MAAM,6CAA6C,CAAA;AACpD,OAAO,EACL,qBAAqB,EACrB,KAAK,iCAAiC,EACtC,KAAK,6BAA6B,GACnC,MAAM,4CAA4C,CAAA;AACnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAA;AAClG,OAAO,EACL,mBAAmB,EACnB,KAAK,+BAA+B,GACrC,MAAM,0CAA0C,CAAA;AACjD,OAAO,EACL,KAAK,oBAAoB,EACzB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,mBAAmB,GACpB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,KAAK,mBAAmB,MAAM,4CAA4C,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -43,6 +43,11 @@ export { companionSystemPrompt } from './agents/prompts/companion.js';
 // first-class kinds in every deployment (Worker / Node / local). `doc-reviewer` — the
 // writer's companion — lives in the COMPANIONS catalog above.
 export { DOC_RESEARCHER_KIND, DOC_OUTLINER_KIND, DOC_WRITER_KIND, DOC_FINALIZER_KIND, DOC_REVIEWER_KIND, DOC_FIXER_KIND, DOCUMENT_AGENT_KINDS, registerDocumentAgents, resolveDocumentTarget, } from './agents/kinds/document.js';
+// The in-source comment annotator (`code-commenter`), pre-loaded by `defaultAgentKindRegistry()`
+// so it is a first-class kind in every deployment (Worker / Node / local) — the in-source-comments
+// leg of the docs-refresh preset (diagrams / READMEs reuse `doc-writer`, business rules reuse
+// `business-documenter`, so it is the one genuinely-new authoring capability the preset needs).
+export { CODE_COMMENTER_KIND, CODE_COMMENTER_AGENT_KINDS, registerCodeCommenterAgent, } from './agents/kinds/code-commenter.js';
 // Per-`DocKind` document templates: the single source of truth for a kind's expected shape,
 // woven into the outliner/writer prompts and (later) read by the doc-quality gate. The
 // built-in `DOC_TEMPLATES` are the fallback; a deployment overrides via `registerDocTemplate`.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAoC,MAAM,8BAA8B,CAAA;AAChG,OAAO,EAEL,+BAA+B,EAC/B,kCAAkC,EAClC,sBAAsB,EACtB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EAKL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAA;AACrE,wFAAwF;AACxF,sEAAsE;AACtE,yFAAyF;AACzF,oFAAoF;AACpF,0DAA0D;AAC1D,OAAO,EAEL,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,iBAAiB,EACjB,8BAA8B,EAC9B,yBAAyB,EACzB,kCAAkC,EAClC,kCAAkC,GACnC,MAAM,gCAAgC,CAAA;AACvC,6FAA6F;AAC7F,mFAAmF;AACnF,OAAO,EAGL,sBAAsB,GACvB,MAAM,qCAAqC,CAAA;AAC5C,uFAAuF;AACvF,wFAAwF;AACxF,gFAAgF;AAChF,OAAO,EAGL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,iBAAiB,EACjB,wBAAwB,EACxB,SAAS,EACT,QAAQ,EACR,gBAAgB,GACjB,MAAM,0BAA0B,CAAA;AACjC,wFAAwF;AACxF,0FAA0F;AAC1F,OAAO,EAA2C,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAClG,6EAA6E;AAC7E,iEAAiE;AACjE,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAA;AAClC,0CAA0C;AAC1C,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,6BAA6B,CAAA;AACpC,mEAAmE;AACnE,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,kCAAkC,CAAA;AACzC,kDAAkD;AAClD,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,6BAA6B,CAAA;AACpC,gDAAgD;AAChD,OAAO,EACL,qCAAqC,EACrC,qCAAqC,EACrC,4CAA4C,EAC5C,4CAA4C,GAC7C,MAAM,gCAAgC,CAAA;AACvC,OAAO,EAGL,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AACjE,OAAO,EACL,mBAAmB,EACnB,wBAAwB,GAEzB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAEL,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,oBAAoB,EACpB,wBAAwB,EACxB,WAAW,GACZ,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAEL,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EAEL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AACrE,mFAAmF;AACnF,mFAAmF;AACnF,sFAAsF;AACtF,8DAA8D;AAC9D,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,GAEtB,MAAM,4BAA4B,CAAA;AACnC,4FAA4F;AAC5F,uFAAuF;AACvF,+FAA+F;AAC/F,+FAA+F;AAC/F,0FAA0F;AAC1F,wFAAwF;AACxF,gGAAgG;AAChG,OAAO,EAGL,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,EAC3B,cAAc;AACd,iGAAiG;AACjG,4FAA4F;AAC5F,8FAA8F;AAC9F,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,EAEhB,4BAA4B,GAC7B,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EACL,wBAAwB,EACxB,+BAA+B,EAC/B,sBAAsB,EAEtB,+BAA+B,GAChC,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAEhB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AACxF,OAAO,EAEL,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAA;AAClF,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,4BAA4B,CAAA;AAEnC,4EAA4E;AAC5E,sFAAsF;AACtF,qFAAqF;AACrF,4DAA4D;AAC5D,OAAO,EAEL,sBAAsB,EACtB,UAAU,EACV,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAC7B,oFAAoF;AACpF,qFAAqF;AACrF,gDAAgD;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,yFAAyF;AACzF,0FAA0F;AAC1F,kEAAkE;AAClE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACnE,yFAAyF;AACzF,0FAA0F;AAC1F,0FAA0F;AAC1F,uEAAuE;AACvE,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,0BAA0B,CAAA;AAEjC,8EAA8E;AAC9E,kFAAkF;AAClF,oFAAoF;AACpF,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EAItB,yBAAyB,EACzB,uBAAuB,EAIvB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,mCAAmC,EACnC,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,8BAA8B,EAE9B,qBAAqB,EACrB,0BAA0B,EAC1B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,sBAAsB,GAEvB,MAAM,6CAA6C,CAAA;AACpD,OAAO,EACL,qBAAqB,GAGtB,MAAM,4CAA4C,CAAA;AACnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAA;AAClG,OAAO,EACL,mBAAmB,GAEpB,MAAM,0CAA0C,CAAA;AACjD,OAAO,EAEL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,mBAAmB,GACpB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,KAAK,mBAAmB,MAAM,4CAA4C,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/presets/docs-refresh/docs-detect.logic.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The narrow slice of the checkout-free repo API the detector needs — a `RepoFiles`
+ * satisfies it structurally, and a test supplies an in-memory fake. A MISSING path yields
+ * `null` / `[]`, so the heuristics degrade gracefully on partial repos. A genuine read
+ * fault (auth/permission revoked, rate limit, transport error) may THROW — the real
+ * GitHub/GitLab reader throws on any non-404 status. The detector NEVER propagates it: the
+ * shared {@link BudgetedRepoScanner} swallows the fault (records it, keeps scanning
+ * best-effort) and this probe simply ignores `readFault`, so it can only ever return
+ * defaults, never reject — a prefill must never block create.
+ */
+export interface DocsRepoReader {
+    getFile(path: string, gitRef?: string): Promise<{
+        content: string;
+    } | null>;
+    listDirectory(path: string, gitRef?: string): Promise<{
+        name: string;
+        type: string;
+        path: string;
+    }[]>;
+}
+/**
+ * The detected documentation layout — the docs-refresh preset's placement DEFAULTS plus two
+ * intel facts for the analyst. All fields are always present (a partial/unreadable repo
+ * yields the conventional defaults), so the caller never has to null-check.
+ */
+export interface DocsLayoutDetection {
+    /**
+     * How docs are placed: `root` (one top-level docs tree) vs `per-service` (each package
+     * carries its own docs — the monorepo shape). Drives the `placementMode` form default.
+     */
+    placementMode: 'root' | 'per-service';
+    /** The repo-relative docs root directory (no trailing slash), e.g. `docs`. */
+    docsRoot: string;
+    /** The repo-relative diagrams directory (no trailing slash), e.g. `docs/diagrams`. */
+    diagramsDir: string;
+    /** The repo-relative business-rules directory (no trailing slash), e.g. `docs/business-logic`. */
+    businessRulesDir: string;
+    /**
+     * Whether the repo already carries mermaid diagram SOURCES — a standalone `.mmd`/`.mermaid`
+     * file or a `mermaid` directory in a scanned location. A hint for the analyst; it is NOT
+     * authoritative (embedded ```mermaid fences inside `.md` files aren't detected — reading
+     * doc bodies is out of the probe's checkout-free budget; the analyst finds those after clone).
+     */
+    hasExistingMermaid: boolean;
+    /**
+     * Whether the repo looks like a monorepo (a workspace manifest, a `workspaces` package.json
+     * field, or a conventional `packages`/`apps`/`services`/`libs` directory). Distinct from
+     * `placementMode`: a monorepo can still keep one root docs tree.
+     */
+    monorepo: boolean;
+}
+/**
+ * Detect the documentation layout of a repo for the docs-refresh preset's form prefill.
+ *
+ * Deterministic, bounded (a hard read budget), and TOTAL — it never throws and never rejects,
+ * so an unwired GitHub / a partial or unreadable repo simply yields the conventional defaults
+ * (`root` placement, `docs`, `docs/diagrams`, `docs/business-logic`). The result is a set of
+ * non-binding FORM DEFAULTS; the user's edits win and the analyst confirms placement at
+ * planning time.
+ */
+export declare function detectDocsLayout(reader: DocsRepoReader): Promise<DocsLayoutDetection>;
+//# sourceMappingURL=docs-detect.logic.d.ts.map

package/dist/presets/docs-refresh/docs-detect.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-detect.logic.d.ts","sourceRoot":"","sources":["../../../src/presets/docs-refresh/docs-detect.logic.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;IAC3E,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAA;CAC3D;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,aAAa,EAAE,MAAM,GAAG,aAAa,CAAA;IACrC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAA;IAChB,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAA;IACnB,kGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,kBAAkB,EAAE,OAAO,CAAA;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAA;CAClB;AAyGD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiD3F"}

package/dist/presets/docs-refresh/docs-detect.logic.js

@@ -0,0 +1,170 @@
+// ---------------------------------------------------------------------------
+// Documentation-refresh preset — repo LAYOUT AUTODETECTION (slice 6).
+//
+// A deterministic, bounded, checkout-free heuristic that proposes the docs-refresh
+// preset's placement DEFAULTS (where docs live, whether the repo documents per-service,
+// which subfolders hold diagrams / business rules) by reading a targeted, tiny slice of
+// the repo over a {@link DocsRepoReader}-shaped reader. No LLM, no clone — just a handful
+// of directory listings plus the root workspace manifests. Mirrors the spirit of
+// `provision-detect.logic.ts` (integrations): high-confidence facts are inferred
+// deterministically; everything is a NON-BINDING prefill the user (and later the analyst
+// during planning) confirms or overrides.
+//
+// This is the pure logic behind the preset's `detect` hook (slice 8), which maps the
+// result onto the form's `InitiativePresetInputs`. Detected values are FORM DEFAULTS: a
+// user edit wins, and both freeze on `presetInputs` at create. The analyst confirms /
+// refines placement at planning time and records deviations as `decisions` — it never
+// silently rewrites the frozen inputs. See
+// `docs/initiatives/initiative-presets-and-docs-refresh.md` (slice 6).
+// ---------------------------------------------------------------------------
+import { BudgetedRepoScanner, joinRepoPath } from '@cat-factory/kernel';
+const DEFAULT_DOCS_ROOT = 'docs';
+// Root directory names that hold documentation, most-conventional first (first present wins).
+const DOCS_ROOT_NAMES = ['docs', 'doc', 'documentation'];
+// Subfolder names (under the docs root) that hold diagrams, most-conventional first.
+const DIAGRAMS_DIR_NAMES = ['diagrams', 'diagram', 'architecture', 'arch'];
+// Subfolder names (under the docs root) that hold business rules / domain docs. `business-logic`
+// first — it matches the `business-documenter` agent's default placement.
+const BUSINESS_RULES_DIR_NAMES = ['business-logic', 'business', 'domain', 'rules'];
+// Conventional monorepo package roots — listed to sample per-service docs placement.
+const WORKSPACE_DIRS = ['packages', 'apps', 'services', 'libs'];
+// Root files that declare a workspace/monorepo (presence alone is the signal — never parsed).
+const MONOREPO_MANIFESTS = [
+    'pnpm-workspace.yaml',
+    'lerna.json',
+    'turbo.json',
+    'nx.json',
+    'rush.json',
+];
+// Standalone mermaid source extensions (directory-listing signal for `hasExistingMermaid`).
+const MERMAID_FILE_RE = /\.(mmd|mermaid)$/i;
+// The most packages we sample when deciding per-service placement — bounds the read fan-out.
+const MAX_SAMPLED_PACKAGES = 6;
+// Hard ceiling on reads so a pathological repo can't fan out without bound. A typical repo
+// resolves in ~10 reads (root + a root manifest + the docs tree + a few sampled packages); the
+// cap only bites on a decoy-heavy tree, where the scan simply stops and returns what it has.
+const READ_BUDGET = 32;
+/** Immediate child directory names of a listing. */
+function dirNames(entries) {
+    return new Set(entries.filter((e) => e.type === 'dir').map((e) => e.name));
+}
+/** Immediate child file names of a listing. */
+function fileNames(entries) {
+    return new Set(entries.filter((e) => e.type !== 'dir').map((e) => e.name));
+}
+/** The first of `candidates` present as a child dir of `dirs`, else undefined. */
+function firstPresent(dirs, candidates) {
+    return candidates.find((c) => dirs.has(c));
+}
+/** True when any listed entry is a standalone mermaid source file or a `mermaid` directory. */
+function listingHasMermaid(entries) {
+    return entries.some((e) => (e.type === 'dir' && e.name === 'mermaid') ||
+        (e.type !== 'dir' && MERMAID_FILE_RE.test(e.name)));
+}
+/**
+ * Read the root `package.json` and report whether it declares a `workspaces` field (the
+ * npm/yarn/bun monorepo marker). Best-effort: an absent/unparseable manifest ⇒ false. This is
+ * the only file the probe reads beyond directory listings, and it is a root workspace manifest.
+ */
+async function hasNpmWorkspaces(scanner) {
+    const content = await scanner.getFile('package.json');
+    if (!content)
+        return false;
+    try {
+        const pkg = JSON.parse(content);
+        const ws = pkg.workspaces;
+        // Array form (`["packages/*"]`) OR yarn's object form (`{ packages: ["packages/*"] }`) — a
+        // monorepo marker only when it actually declares globs. An empty `[]`/`{}` (or `{ nohoist }`
+        // with no `packages`) declares no workspaces, so it's not a monorepo signal.
+        if (Array.isArray(ws))
+            return ws.length > 0;
+        if (ws !== null && typeof ws === 'object') {
+            const packages = ws.packages;
+            return Array.isArray(packages) && packages.length > 0;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sample up to {@link MAX_SAMPLED_PACKAGES} packages across the present workspace dirs and count
+ * how many carry their own docs directory. Returns the vote (`sampled`/`withDocs`) plus whether
+ * any sampled package held a mermaid source. Bounded by the sample cap + the global read budget.
+ */
+async function samplePackageDocs(scanner, workspaceDirs) {
+    let sampled = 0;
+    let withDocs = 0;
+    let mermaid = false;
+    for (const wsDir of workspaceDirs) {
+        if (sampled >= MAX_SAMPLED_PACKAGES)
+            break;
+        const children = (await scanner.listDir(wsDir)).filter((e) => e.type === 'dir');
+        for (const child of children) {
+            if (sampled >= MAX_SAMPLED_PACKAGES)
+                break;
+            sampled++;
+            const entries = await scanner.listDir(joinRepoPath(wsDir, child.name));
+            if (firstPresent(dirNames(entries), DOCS_ROOT_NAMES))
+                withDocs++;
+            if (listingHasMermaid(entries))
+                mermaid = true;
+        }
+    }
+    return { sampled, withDocs, mermaid };
+}
+/**
+ * Detect the documentation layout of a repo for the docs-refresh preset's form prefill.
+ *
+ * Deterministic, bounded (a hard read budget), and TOTAL — it never throws and never rejects,
+ * so an unwired GitHub / a partial or unreadable repo simply yields the conventional defaults
+ * (`root` placement, `docs`, `docs/diagrams`, `docs/business-logic`). The result is a set of
+ * non-binding FORM DEFAULTS; the user's edits win and the analyst confirms placement at
+ * planning time.
+ */
+export async function detectDocsLayout(reader) {
+    const scanner = new BudgetedRepoScanner(reader, READ_BUDGET);
+    const rootEntries = await scanner.listDir('');
+    const rootDirs = dirNames(rootEntries);
+    const rootFiles = fileNames(rootEntries);
+    // --- docs root -------------------------------------------------------------------------------
+    const docsRoot = firstPresent(rootDirs, DOCS_ROOT_NAMES) ?? DEFAULT_DOCS_ROOT;
+    let diagramsDir = joinRepoPath(docsRoot, 'diagrams');
+    let businessRulesDir = joinRepoPath(docsRoot, 'business-logic');
+    // Root listing signal: a standalone `.mmd`/`.mermaid` file OR a `mermaid` directory (the root
+    // is a scanned location, so both halves of the signal count here — not just the file half).
+    let hasExistingMermaid = listingHasMermaid(rootEntries);
+    // --- known subfolders under the docs root ----------------------------------------------------
+    if (rootDirs.has(docsRoot)) {
+        const docsEntries = await scanner.listDir(docsRoot);
+        const docsDirs = dirNames(docsEntries);
+        const diagramsChild = firstPresent(docsDirs, DIAGRAMS_DIR_NAMES);
+        if (diagramsChild)
+            diagramsDir = joinRepoPath(docsRoot, diagramsChild);
+        const businessChild = firstPresent(docsDirs, BUSINESS_RULES_DIR_NAMES);
+        if (businessChild)
+            businessRulesDir = joinRepoPath(docsRoot, businessChild);
+        hasExistingMermaid = hasExistingMermaid || listingHasMermaid(docsEntries);
+        // Peek inside the diagrams dir once for standalone mermaid sources (budget permitting).
+        if (diagramsChild && !hasExistingMermaid) {
+            hasExistingMermaid = listingHasMermaid(await scanner.listDir(joinRepoPath(docsRoot, diagramsChild)));
+        }
+    }
+    // --- monorepo shape + per-service placement --------------------------------------------------
+    const workspaceDirs = WORKSPACE_DIRS.filter((d) => rootDirs.has(d));
+    const monorepoManifest = MONOREPO_MANIFESTS.some((m) => rootFiles.has(m)) || (await hasNpmWorkspaces(scanner));
+    const monorepo = monorepoManifest || workspaceDirs.length > 0;
+    let placementMode = 'root';
+    if (monorepo && workspaceDirs.length > 0) {
+        const { sampled, withDocs, mermaid } = await samplePackageDocs(scanner, workspaceDirs);
+        hasExistingMermaid = hasExistingMermaid || mermaid;
+        // Per-service when MOST sampled packages document themselves (a strict majority — an even
+        // split stays on the safe `root` default). A monorepo we can't sample (manifest-only, no
+        // conventional package dir) stays `root` too — the safe, common default.
+        if (sampled > 0 && withDocs * 2 > sampled)
+            placementMode = 'per-service';
+    }
+    return { placementMode, docsRoot, diagramsDir, businessRulesDir, hasExistingMermaid, monorepo };
+}
+//# sourceMappingURL=docs-detect.logic.js.map

package/dist/presets/docs-refresh/docs-detect.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-detect.logic.js","sourceRoot":"","sources":["../../../src/presets/docs-refresh/docs-detect.logic.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/agents",
-  "version": "0.40.13",
+  "version": "0.42.0",
   "description": "Agent catalog, routing, prompts and fragment library for the Agent Architecture Board.",
   "repository": {
     "type": "git",
@@ -31,14 +31,14 @@
     "ai": "^6.0.219",
     "handlebars": "^4.7.9",
     "valibot": "^1.4.2",
-    "@cat-factory/contracts": "0.117.0",
-    "@cat-factory/kernel": "0.104.4",
-    "@cat-factory/prompt-fragments": "0.10.26"
+    "@cat-factory/contracts": "0.118.0",
+    "@cat-factory/kernel": "0.106.0",
+    "@cat-factory/prompt-fragments": "0.10.27"
   },
   "devDependencies": {
     "typescript": "7.0.1-rc",
     "vitest": "^4.1.9",
-    "@cat-factory/caching": "0.6.4"
+    "@cat-factory/caching": "0.6.6"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json",