@geraldmaron/construct 1.2.0 → 1.2.2

package/lib/auto-docs.mjs

@@ -11,7 +11,7 @@
  *
  * buildSite() is retained for compatibility; the public site now renders docs/
  * directly through Next.js (apps/docs/) and buildFumadocsReference() emits
- * generated reference Markdown into docs/reference/.
+ * generated reference Markdown into docs/guides/reference/.
  */
 
 import fs from 'node:fs';
@@ -78,7 +78,7 @@ function buildCoreDocsContract() {
     '| `.cx/context.md` | Human-readable resumable project context | Active work, decisions, architecture assumptions, or open questions change |',
     '| `.cx/context.json` | Machine-readable resumable context | Context state needs to stay in sync with `.cx/context.md` |',
     '| `docs/README.md` | Docs index and maintenance contract | Core docs set or maintenance expectations change |',
-    '| `docs/concepts/architecture.mdx` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
+    '| `docs/guides/concepts/architecture.mdx` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
     '',
     '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed; durable work belongs in the tracker (Beads or external).',
     '',
@@ -191,7 +191,7 @@ function buildAgentsTable(rootDir) {
 // --- public API ---
 
 /**
- * Regenerate all AUTO regions in README.md, docs/README.md, and docs/concepts/architecture.mdx.
+ * Regenerate all AUTO regions in README.md, docs/README.md, and docs/guides/concepts/architecture.mdx.
  * Returns { changed: string[], checked: boolean }.
  * With check:true writes nothing and sets changed to files that would differ.
  */
@@ -209,7 +209,7 @@ export async function regenerateDocs({ rootDir, check = false } = {}) {
       },
     },
     {
-      file: path.join(rootDir, 'docs', 'concepts', 'architecture.mdx'),
+      file: path.join(rootDir, 'docs', 'guides', 'concepts', 'architecture.mdx'),
       regions: {
         agents: buildAgentsTable(rootDir),
       },
@@ -268,7 +268,7 @@ export function checkDocsCoverage({ rootDir } = {}) {
   // Build a combined corpus: docs/README.md + every linked guide file
   let corpus = docsReadme;
   for (const target of linkTargets) {
-    if (!target.startsWith('./how-to/') && !target.startsWith('./cookbook/')) continue;
+    if (!target.startsWith('./guides/cookbook/')) continue;
     const filePath = path.join(rootDir, 'docs', target.replace(/^\.\//, ''));
     const content = readFile(filePath);
     if (content) corpus += '\n' + content;
@@ -368,7 +368,9 @@ function renderCommandPage(category, commands) {
       lines.push('**Subcommands**');
       lines.push('');
       for (const sub of cmd.subcommands) {
-        lines.push(`- \`${sub}\``);
+        const name = typeof sub === 'string' ? sub : sub.name;
+        const description = typeof sub === 'string' ? '' : (sub.desc || sub.description || '');
+        lines.push(`- \`${name}\`${description ? ` — ${description}` : ''}`);
       }
       lines.push('');
     }
@@ -421,7 +423,7 @@ function renderAgentsPage(rootDir) {
 }
 
 /**
- * Emit MDX reference pages into docs/reference/ for the Next.js docs site
+ * Emit MDX reference pages into docs/guides/reference/ for the Next.js docs site
  * in apps/docs/. Mirrors the data sources behind AUTO regions and buildSite()
  * but writes Markdown files the docs app can pull in directly (no MkDocs
  * intermediate). Name kept for backwards compatibility with callers that
@@ -430,7 +432,7 @@ function renderAgentsPage(rootDir) {
  */
 export function buildFumadocsReference({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();
-  const refDir = path.join(rootDir, 'docs', 'reference');
+  const refDir = path.join(rootDir, 'docs', 'guides', 'reference');
   const cliDir = path.join(refDir, 'cli');
   fs.mkdirSync(cliDir, { recursive: true });
 
@@ -466,7 +468,7 @@ export function buildFumadocsReference({ rootDir } = {}) {
       const slug = slugify(cat);
       const commands = CLI_COMMANDS_BY_CATEGORY[cat] ?? [];
       if (!commands.length) return null;
-      return `- [${cat}](/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
+      return `- [${cat}](/guides/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
     }).filter(Boolean),
     '',
   ].join('\n');
@@ -497,7 +499,7 @@ export function buildFumadocsReference({ rootDir } = {}) {
 
 export function checkFumadocsReferenceDrift({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();
-  const refDir = path.join(rootDir, 'docs', 'reference');
+  const refDir = path.join(rootDir, 'docs', 'guides', 'reference');
   const cliDir = path.join(refDir, 'cli');
   const drift = [];
 
@@ -532,7 +534,7 @@ export function checkFumadocsReferenceDrift({ rootDir } = {}) {
       const slug = slugify(cat);
       const commands = CLI_COMMANDS_BY_CATEGORY[cat] ?? [];
       if (!commands.length) return null;
-      return `- [${cat}](/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
+      return `- [${cat}](/guides/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
     }).filter(Boolean),
     '',
   ].join('\n');

package/lib/bootstrap/built-ins.mjs

@@ -14,8 +14,8 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import os from 'node:os';
 import { registerResource, getResource } from './resources.mjs';
+import { cacheDir } from '../config/xdg.mjs';
 
 function probeCommandVersion(cmd, args = ['--version']) {
   const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 3000 });
@@ -56,8 +56,8 @@ async function probePostgresContainer() {
 
 async function probeEmbeddingModel() {
   const cachePath = join(
-    os.homedir(),
-    '.construct', 'cache', 'embeddings',
+    cacheDir(),
+    'embeddings',
     'Xenova', 'all-MiniLM-L6-v2', 'onnx', 'model_quantized.onnx'
   );
   if (existsSync(cachePath)) {

package/lib/boundary.mjs

@@ -3,7 +3,7 @@
  *
  * Verifies a parent Construct instance is reachable, validates an HMAC
  * signature over `childInstanceId|nonce` when a shared secret is configured,
- * and persists the binding to ~/.construct/boundary.json (mode 0600). A
+ * and persists the binding to boundary.json in the XDG config dir (mode 0600). A
  * different parent rotates the registration only when explicitly allowed via
  * CONSTRUCT_BOUNDARY_ALLOW_OVERRIDE=1; prior configs are archived alongside
  * the active one. Exposed as a standalone module so the dashboard endpoint
@@ -16,11 +16,12 @@ import { homedir } from 'node:os';
 import { createHmac, timingSafeEqual, randomBytes } from 'node:crypto';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
+import { configDir } from './config/xdg.mjs';
 
 export const BOUNDARY_VERSION = '1.0';
 
 function boundaryDir(home = homedir()) {
-  return join(home, '.construct');
+  return configDir(home);
 }
 
 export function boundaryConfigPath(home = homedir()) {

package/lib/brand-prose.mjs

@@ -37,7 +37,7 @@ const EXCLUDE_PATH =
   /(node_modules|\.git|audit-artifacts|scripts\/audit|CHANGELOG\.md|fonts\/legacy\/|\.next\/|\/out\/|tests\/e2e\/reports\/|package-lock\.json)/;
 
 const DOC_EXEMPT =
-  /(?:^|\/)(docs\/STYLE\.md|docs\/reference\/branding\.md|templates\/distribution\/fonts\/README\.md)$/;
+  /(?:^|\/)(docs\/STYLE\.md|docs\/guides\/reference\/branding\.md|templates\/distribution\/fonts\/README\.md)$/;
 
 const HOOK_SCOPED =
   /^(docs\/|skills\/|specialists\/|personas\/|templates\/|rules\/|apps\/(dashboard|docs|chat)\/)/;

package/lib/cache-governor.js

@@ -10,10 +10,10 @@
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { normalizeCostEntry } from './cost.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 
-const STRATEGY_PATH = join(homedir(), '.cx', 'cache-strategy.json');
+const STRATEGY_PATH = join(doctorRoot(), 'cache-strategy.json');
 const REVIEW_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes between adjustments
 
 function readStrategy() {
@@ -27,7 +27,7 @@ function readStrategy() {
 
 function writeStrategy(data) {
   try {
-    mkdirSync(join(homedir(), '.cx'), { recursive: true });
+    mkdirSync(doctorRoot(), { recursive: true });
     writeFileSync(STRATEGY_PATH, JSON.stringify(data, null, 2));
   } catch { /* best effort */ }
 }
@@ -153,7 +153,7 @@ export function onPostToolUse({ costLogPath, provider, dryRun = false } = {}) {
   // Read cost log
   const entries = [];
   try {
-    const logPath = costLogPath || join(homedir(), '.cx', 'session-cost.jsonl');
+    const logPath = costLogPath || join(doctorRoot(), 'session-cost.jsonl');
     if (!existsSync(logPath)) return { adjusted: false, reason: 'No cost log' };
 
     const lines = readFileSync(logPath, 'utf8')

package/lib/certification/document-io-fixtures.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/certification/document-io-fixtures.mjs — intake fixture catalog for document I/O tests.
  *
- * Maps docs/reference/document-io.md supported intake categories to committed
+ * Maps docs/guides/reference/document-io.md supported intake categories to committed
  * files under tests/fixtures/document-io/<category>/.
  */
 

package/lib/chat/config.mjs

@@ -14,8 +14,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 import { resolveProjectScopedPath } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 export const LAYER_KEYS = ['thinking', 'path', 'specialists', 'tools', 'observability'];
 export const PERMISSION_MODES = ['ask', 'allow_once', 'allow_always', 'reject'];
@@ -64,7 +64,7 @@ function mergeConfig(base, override) {
 }
 
 export function globalConfigPath() {
-  return path.join(os.homedir(), '.cx', CONFIG_BASENAME);
+  return path.join(doctorRoot(), CONFIG_BASENAME);
 }
 
 export function projectConfigPath({ cwd = process.cwd() } = {}) {

package/lib/chat/desktop-binary.mjs

@@ -1,8 +1,8 @@
 /**
  * lib/chat/desktop-binary.mjs — resolve the Construct chat desktop window binary.
  *
- * Search order: CONSTRUCT_CHAT_DESKTOP_BIN, repo dev build, ~/.construct/bin,
- * then packaged sidecar next to construct.
+ * Search order: CONSTRUCT_CHAT_DESKTOP_BIN, repo dev build, the bin/ subdir of
+ * the XDG state dir, then packaged sidecar next to construct.
  */
 
 import fs from 'node:fs';
@@ -10,6 +10,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { stateDir } from '../config/xdg.mjs';
+
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(HERE, '..', '..');
 
@@ -50,7 +52,7 @@ export function desktopBinaryCandidates({ repoRoot = REPO_ROOT, homeDir = os.hom
     env.CONSTRUCT_CHAT_DESKTOP_BIN,
     path.join(tauriRoot, 'release', name),
     path.join(tauriRoot, 'debug', name),
-    path.join(homeDir, '.construct', 'bin', name),
+    path.join(stateDir(homeDir), 'bin', name),
     path.join(repoRoot, 'apps', 'chat', 'desktop', 'bin', name),
   ].filter(Boolean);
 }

package/lib/chat/present.mjs

@@ -225,6 +225,7 @@ export function sessionMetaToSsePayload({ session, layers, workingBranch, oracle
   return {
     type: 'session_meta',
     model: session?.model || null,
+    demoLabel: session?.demoGuide ? (session.demoTitle || 'scripted') : null,
     modelMode: session?.modelMode || 'pinned',
     sandbox: session?.sandbox || null,
     permissionMode: session?.permissionMode || null,

package/lib/cli-commands.mjs

@@ -330,12 +330,14 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Export markdown to PDF, DOCX, HTML, and other Pandoc formats via Pandoc + Typst (optional system binaries; ADR-0024)',
-    usage: 'construct export <markdown-file> --to=<pdf|docx|deck|pptx|html|rtf|odt|epub|tex|txt|md|mdx> [--output=<path>] [--figures] [--detect]',
+    usage: 'construct export <markdown-file> --to=<pdf|docx|deck|pptx|html|rtf|odt|epub|tex|txt|md|mdx> [--output=<path>] [--figures|--no-figures] [--plain] [--detect]',
     strictFlags: true,
     options: [
       { flag: '--to=<format>', desc: 'pdf, docx, deck, pptx, html, rtf, odt, epub, tex, txt, md, mdx' },
       { flag: '--output=<path>', desc: 'Output path' },
       { flag: '--figures', desc: 'Render d2/mermaid via pandoc-ext/diagram filter' },
+      { flag: '--no-figures', desc: 'Skip diagram rendering' },
+      { flag: '--plain, --no-brand', desc: 'Explicitly opt out of Construct branding for a brand-capable output' },
       { flag: '--detect', desc: 'Report binary availability (JSON)' },
     ],
   },
@@ -658,10 +660,11 @@ export const CLI_COMMANDS = [
     emoji: '📋',
     category: 'Work',
     core: false,
-    description: 'Validate typed document artifacts against the release gate',
-    usage: 'construct artifact validate <path> --type=<doc-type> [--json]',
+    description: 'Plan or locally execute manifest-backed artifact workflows with execution provenance',
+    usage: 'construct artifact <validate|workflow> ...',
     subcommands: [
       { name: 'validate', desc: 'Run manifest structure, citation, and reviewer checks' },
+      { name: 'workflow', desc: 'Return a truthful plan/run report; --apply only runs local validation/export after approval' },
     ],
   },
   {
@@ -772,6 +775,20 @@ export const CLI_COMMANDS = [
     description: 'Deployment mode configuration',
     usage: 'construct config <get|set>',
   },
+  {
+    name: 'sources',
+    emoji: '🔗',
+    category: 'Advanced',
+    core: false,
+    description: 'Manage typed integration source targets in construct.config.json',
+    usage: 'construct sources list|add|remove|validate',
+    subcommands: [
+      { name: 'list', desc: 'Show config targets, legacy env merge, and effective set' },
+      { name: 'add <provider> <id> <selector-json>', desc: 'Add a typed target (github, jira, linear, slack)' },
+      { name: 'remove <id>', desc: 'Remove a config target by id' },
+      { name: 'validate', desc: 'Validate sources.targets in construct.config.json' },
+    ],
+  },
   {
     name: 'uninstall',
     emoji: '🧹',
@@ -1095,7 +1112,7 @@ export const CLI_COMMANDS = [
     emoji: '📄',
     category: 'Diagnostics',
     core: false,
-    description: 'Regenerate generated reference pages under docs/reference/',
+    description: 'Regenerate generated reference pages under docs/guides/reference/',
     usage: 'construct docs:site [--check]',
   },
   {
@@ -1129,7 +1146,7 @@ export const CLI_COMMANDS = [
   { name: 'specialist',        category: 'Internal', core: false, internal: true, description: 'Maintainer tool: scaffold, edit, and lint specialist prompts', usage: 'construct specialist <create|edit|lint>' },
   { name: 'registry:status',   category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Dev: capability registry inspector', usage: 'construct registry:status [--json]' },
   { name: 'registry:validate', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Validate registry/capabilities.json against repo reality', usage: 'construct registry:validate [--json]' },
-  { name: 'registry:generate-docs', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Generate docs/reference/capabilities.md from registry', usage: 'construct registry:generate-docs' },
+  { name: 'registry:generate-docs', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Generate docs/guides/reference/capabilities.md from registry', usage: 'construct registry:generate-docs' },
   { name: 'oracle', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Oracle meta-controller — fleet health review and bounded-auto maintenance', usage: 'construct oracle start|status|review|pending|approve|gaps|reconcile' },
   { name: 'matrix', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Living dependency matrix — build/inspect the typed file↔capability↔workflow↔test graph', usage: 'construct matrix build|stat|query <node-id> [--json]' },
   { name: 'impact', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Change-impact analysis — map changed files to affected tests, capabilities, and workflows', usage: 'construct impact [files…] [--stdin] [--run] [--json]' },
@@ -1254,7 +1271,7 @@ export function formatCommandHelp(name, { colors = false } = {}) {
     lines.push(`${c.dim}Next:${c.reset} ${next}`);
     lines.push('');
   }
-  lines.push(`${c.dim}See also:${c.reset} run \`construct --help\` for all commands; full reference in docs/reference/cli/.`);
+  lines.push(`${c.dim}See also:${c.reset} run \`construct --help\` for all commands; full reference in docs/guides/reference/cli/.`);
   lines.push('');
   return lines.join('\n');
 }

package/lib/cli-service-inventory.mjs

@@ -0,0 +1,42 @@
+/**
+ * lib/cli-service-inventory.mjs — auditable public CLI/catalog/docs inventory.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { CLI_COMMANDS } from './cli-commands.mjs';
+
+function slugify(category) {
+  return category.toLowerCase().replace(/&/g, 'and').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function handlerNames(rootDir) {
+  const source = fs.readFileSync(path.join(rootDir, 'bin', 'construct'), 'utf8');
+  const names = new Set();
+  for (const match of source.matchAll(/\n {2,3}\[\s*'([^']+)'\s*,/g)) names.add(match[1]);
+  return names;
+}
+
+/**
+ * The catalog is the public-service source of truth. This projection joins it
+ * to runtime dispatch and the generated reference pages so drift is observable
+ * without treating internal handlers as public services.
+ */
+export function buildCliServiceInventory({ rootDir = process.cwd() } = {}) {
+  const handlers = handlerNames(rootDir);
+  return CLI_COMMANDS.filter((spec) => !spec.internal).map((spec) => {
+    const page = path.join(rootDir, 'docs', 'guides', 'reference', 'cli', `${slugify(spec.category)}.md`);
+    const pageText = fs.existsSync(page) ? fs.readFileSync(page, 'utf8') : '';
+    return {
+      name: spec.name,
+      category: spec.category,
+      runnable: handlers.has(spec.name),
+      documented: pageText.includes(`## construct ${spec.name}`),
+      usage: spec.usage,
+      subcommands: (spec.subcommands ?? []).map((sub) => ({
+        name: typeof sub === 'string' ? sub : sub.name,
+        documented: typeof sub === 'string' ? true : Boolean(sub.desc || sub.description),
+      })),
+    };
+  });
+}

package/lib/comment-lint.mjs

@@ -34,11 +34,15 @@ const MD_HEADER_GLOBS = [
 // Scope is deliberately narrow — READMEs, cookbook, concepts, and reference are
 // unaffected. The patterns live in BANNED_ARTIFACT below; the severity (block
 // vs warn) is controlled by CONSTRUCT_ARTIFACT_LINT_MODE.
+// Match this repo's bucketed layout (docs/specs/prd, docs/decisions/adr, …) and
+// the flat init-lane layout that `construct init` scaffolds downstream (docs/prd,
+// docs/adr, …), so artifact-prose linting fires in either project shape.
+
 const ARTIFACT_PATH_GLOBS = [
-  /^docs\/prd\//,
-  /^docs\/adr\//,
-  /^docs\/rfc\//,
-  /^docs\/research\//,
+  /^docs\/(?:specs\/)?prd\//,
+  /^docs\/(?:decisions\/)?adr\//,
+  /^docs\/(?:decisions\/)?rfc\//,
+  /^docs\/(?:notes\/)?research\//,
   /^\.cx\/knowledge\//,
   /^\.cx\/handoffs\//,
   /^\.cx\/research\//,
@@ -55,7 +59,7 @@ function isArtifactPath(rel) {
 // Deliverable surfaces where a tool-identity leak (rules/common/tool-invisibility.md)
 // matters: project docs and the durable .cx knowledge / research / handoff / strategy
 // stores. Broader than the fabrication-scoped ARTIFACT_PATH_GLOBS because a strategy
-// lands in docs/ root, not only docs/prd.
+// lands in docs/ root, not only docs/specs/prd.
 
 const DELIVERABLE_LEAK_GLOBS = [
   /^docs\/.*\.md$/,

package/lib/config/alias.mjs

@@ -3,7 +3,7 @@
  *
  * Lookup precedence:
  *   1. CONSTRUCT_ALIAS env var (per-session override)
- *   2. ~/.construct/config.json.aliasOverride (user-level, lets each
+ *   2. config.json.aliasOverride in the XDG config dir (user-level, lets each
  *      user on the same project see their own branding without
  *      committing it)
  *   3. construct.config.json.alias (project-level, committed)
@@ -17,6 +17,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { loadProjectConfig } from './project-config.mjs';
+import { configDir } from './xdg.mjs';
 
 export const DEFAULT_ALIAS = 'Construct';
 export const ALIAS_ENV_KEY = 'CONSTRUCT_ALIAS';
@@ -29,7 +30,7 @@ export function resolveAlias({ cwd = process.cwd(), env = process.env, homeDir =
   }
 
   try {
-    const userCfgPath = path.join(homeDir, '.construct', 'config.json');
+    const userCfgPath = path.join(configDir(homeDir), 'config.json');
     if (fs.existsSync(userCfgPath)) {
       const userCfg = JSON.parse(fs.readFileSync(userCfgPath, 'utf8'));
       const userAlias = userCfg?.aliasOverride;

package/lib/config/intake-policy.mjs

@@ -0,0 +1,139 @@
+/**
+ * lib/config/intake-policy.mjs — project-scoped intake watcher policy.
+ *
+ * Resolves the canonical drop zone, scan depth, and additional directories from
+ * construct.config.json intakePolicy (the only config source), with env
+ * overrides and a default when intakePolicy is absent.
+ *
+ * Single-zone model (ADR-0045 §C): the only drop zone is the project-root
+ * `inbox/`, always watched. `additionalDirs` (opt-in extra dirs) and `maxDepth`
+ * remain configurable. There are no other zones — `.cx/inbox/` and `docs/intake/`
+ * are not watched and not scaffolded.
+ */
+
+import { isAbsolute, join, resolve } from 'node:path';
+import { loadProjectConfig, writeProjectConfig, findProjectConfigPath, PROJECT_CONFIG_FILENAME } from './project-config.mjs';
+import {
+  INTAKE_DEFAULT_MAX_DEPTH,
+  INTAKE_HARD_MAX_DEPTH,
+  INTAKE_DEPTH_GUIDANCE,
+  describeIntakeDepth,
+} from '../intake/constants.mjs';
+
+export { INTAKE_DEFAULT_MAX_DEPTH, INTAKE_HARD_MAX_DEPTH, INTAKE_DEPTH_GUIDANCE, describeIntakeDepth };
+
+export const DEFAULT_INTAKE_POLICY = Object.freeze({
+  maxDepth: INTAKE_DEFAULT_MAX_DEPTH,
+  additionalDirs: [],
+});
+
+function clampDepth(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return INTAKE_DEFAULT_MAX_DEPTH;
+  return Math.min(Math.floor(n), INTAKE_HARD_MAX_DEPTH);
+}
+
+function normalizeDir(dir, rootDir) {
+  if (typeof dir !== 'string') return null;
+  const trimmed = dir.trim();
+  if (!trimmed) return null;
+  return isAbsolute(trimmed) ? trimmed : resolve(rootDir, trimmed);
+}
+
+function parseEnvDirs(env) {
+  const raw = String(env?.CX_INBOX_DIRS ?? '').trim();
+  if (!raw) return [];
+  return raw.split(':').map((p) => p.trim()).filter(Boolean);
+}
+
+export function intakePolicyFromProjectConfig(config) {
+  const raw = config?.intakePolicy ?? {};
+  return {
+    maxDepth: clampDepth(raw.maxDepth ?? DEFAULT_INTAKE_POLICY.maxDepth),
+    additionalDirs: Array.isArray(raw.additionalDirs)
+      ? raw.additionalDirs.map((d) => String(d).trim()).filter(Boolean)
+      : [],
+  };
+}
+
+export function loadIntakePolicy(rootDir, env = process.env) {
+  const { config, path: configPath, raw } = loadProjectConfig(rootDir, env);
+  let policy;
+  let source = 'default';
+
+  if (configPath && raw?.intakePolicy) {
+    policy = intakePolicyFromProjectConfig(config);
+    source = 'project-config';
+  } else {
+    policy = structuredClone(DEFAULT_INTAKE_POLICY);
+    source = 'default';
+  }
+
+  const envDirs = parseEnvDirs(env).map((dir) => normalizeDir(dir, rootDir)).filter(Boolean);
+  const additionalDirs = []
+    .concat(policy.additionalDirs.map((dir) => normalizeDir(dir, rootDir)).filter(Boolean))
+    .concat(envDirs);
+
+  const seen = new Set();
+  const uniqueDirs = [];
+  for (const dir of additionalDirs) {
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    uniqueDirs.push(dir);
+  }
+
+  const envDepth = env?.CX_INTAKE_MAX_DEPTH;
+  const maxDepth = clampDepth(envDepth ?? policy.maxDepth);
+
+  return {
+    maxDepth,
+    additionalDirs: uniqueDirs,
+    source,
+  };
+}
+
+export function resolvedIntakeConfig(rootDir, env = process.env) {
+  const policy = loadIntakePolicy(rootDir, env);
+  return {
+    parentDirs: policy.additionalDirs,
+    maxDepth: policy.maxDepth,
+    source: policy.source,
+  };
+}
+
+export function saveIntakePolicy(rootDir, patch = {}, options = {}) {
+  const configPath = findProjectConfigPath(rootDir) ?? join(rootDir, PROJECT_CONFIG_FILENAME);
+  const { config } = loadProjectConfig(rootDir, {});
+  const current = intakePolicyFromProjectConfig(config.intakePolicy ? config : { intakePolicy: DEFAULT_INTAKE_POLICY });
+
+  const next = {
+    maxDepth: clampDepth(patch.maxDepth ?? current.maxDepth),
+    additionalDirs: Array.isArray(patch.additionalDirs)
+      ? patch.additionalDirs.map((dir) => normalizeDir(dir, rootDir)).filter(Boolean)
+      : current.additionalDirs,
+  };
+
+  if (patch.addDir) {
+    const dir = normalizeDir(patch.addDir, rootDir);
+    if (dir && !next.additionalDirs.includes(dir)) {
+      next.additionalDirs = [...next.additionalDirs, dir];
+    }
+  }
+  if (patch.removeDir) {
+    const dir = normalizeDir(patch.removeDir, rootDir);
+    next.additionalDirs = next.additionalDirs.filter((d) => d !== dir);
+  }
+
+  const updated = {
+    ...config,
+    version: config.version ?? 1,
+    intakePolicy: next,
+  };
+
+  if (options.dryRun) {
+    return { policy: next, configPath, dryRun: true };
+  }
+
+  writeProjectConfig(configPath, updated);
+  return { policy: next, configPath };
+}