@open-agent-toolkit/cli 0.2.54 → 0.2.56

package/dist/commands/config/index.d.ts

@@ -10,6 +10,7 @@ interface ConfigCommandDependencies {
     resolveProjectRoot: (cwd: string) => Promise<string>;
     readOatConfig: (repoRoot: string) => Promise<OatConfig>;
     readOatConfigForDefaultScopeRepair: (repoRoot: string) => Promise<OatConfig>;
+    readOatConfigForDocumentationExcludesRepair: (repoRoot: string) => Promise<OatConfig>;
     writeOatConfig: (repoRoot: string, config: OatConfig) => Promise<void>;
     readOatLocalConfig: (repoRoot: string) => Promise<OatLocalConfig>;
     writeOatLocalConfig: (repoRoot: string, config: OatLocalConfig) => Promise<void>;

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAmBzC,OAAO,EAML,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAgBhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0GpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kCAAkC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC7C,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAqkFD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsKT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAmBzC,OAAO,EAML,KAAK,SAAS,EACd,KAAK,cAAc,EAGnB,KAAK,UAAU,EAiBhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC3B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2GpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kCAAkC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,2CAA2C,EAAE,CAC3C,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC7C,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,0BAA0B,EAAE,OAAO,0BAA0B,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAunFD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsKT"}

package/dist/commands/config/index.js

@@ -9,7 +9,7 @@ import { compileDispatchCeilingPreset } from '../../config/dispatch-ceiling-pres
 import { normalizeDispatchMatrix, validateDispatchRouteTarget, walkDispatchMatrix, } from '../../config/dispatch-matrix.js';
 import { formatDispatchNotices, terminalReviewerNoticesForMatrix, } from '../../config/dispatch-notices.js';
 import { dispatchPolicyModeDescription, dispatchPolicyPolicyDescription, managedDispatchPolicyValueList, } from '../../config/dispatch-policy-options.js';
-import { VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
+import { VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
 import { resolveEffectiveConfig, } from '../../config/resolve.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
@@ -38,6 +38,7 @@ const KEY_ORDER = [
     'documentation.root',
     'documentation.tooling',
     'documentation.config',
+    'documentation.excludes',
     'documentation.requireForProjectCompletion',
     'explainers.defaults.style',
     'explainers.defaults.palette',
@@ -177,6 +178,17 @@ const CONFIG_CATALOG = [
         owningCommand: 'oat config set documentation.config <value>',
         description: 'Repository-relative path to the primary documentation tool config file.',
     },
+    {
+        key: 'documentation.excludes',
+        group: 'Shared Repo (.oat/config.json)',
+        file: '.oat/config.json',
+        scope: 'shared repo',
+        type: 'string[]',
+        defaultValue: 'unset',
+        mutability: 'read/write',
+        owningCommand: 'oat config set documentation.excludes <glob[,glob...]>',
+        description: 'Comma-separated globs, relative to the docs directory, excluded from `oat docs generate-index`. Repeated `--exclude` flags extend this list; an empty value clears the key.',
+    },
     {
         key: 'documentation.requireForProjectCompletion',
         group: 'Shared Repo (.oat/config.json)',
@@ -854,6 +866,7 @@ const DEFAULT_DEPENDENCIES = {
     resolveProjectRoot,
     readOatConfig,
     readOatConfigForDefaultScopeRepair,
+    readOatConfigForDocumentationExcludesRepair,
     writeOatConfig,
     readOatLocalConfig,
     writeOatLocalConfig,
@@ -916,6 +929,20 @@ function normalizeSharedRoot(value) {
     }
     return trimmed.replace(/\/+$/, '');
 }
+/**
+ * Split the one array-valued config key's comma-separated grammar.
+ *
+ * Entries are trimmed and de-duplicated in order; blank entries are dropped, so
+ * an empty (or all-blank) value yields an empty list, which the caller treats
+ * as "clear the key" rather than as an error.
+ */
+function parseDocumentationExcludes(rawValue) {
+    const parsed = rawValue
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return [...new Set(parsed)];
+}
 function parseExplainerValue(key, rawValue, surface) {
     const value = rawValue.trim();
     if (!value) {
@@ -1633,7 +1660,12 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
         });
         return { key, value: defaultScope, source: 'shared' };
     }
-    const config = await dependencies.readOatConfig(repoRoot);
+    // `documentation.excludes` is the one shared key whose own validation error
+    // names `oat config set` as the repair, so it reads leniently: a strict read
+    // would reject the very value the operator is trying to replace.
+    const config = key === 'documentation.excludes'
+        ? await dependencies.readOatConfigForDocumentationExcludesRepair(repoRoot)
+        : await dependencies.readOatConfig(repoRoot);
     if (key.startsWith('documentation.')) {
         const doc = { ...config.documentation };
         if (key === 'documentation.root') {
@@ -1645,6 +1677,17 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
         else if (key === 'documentation.config') {
             doc.config = normalizeSharedRoot(rawValue);
         }
+        else if (key === 'documentation.excludes') {
+            const excludes = parseDocumentationExcludes(rawValue);
+            if (excludes.length === 0) {
+                // Unlike the scalar shared keys, an empty value is the documented way
+                // to clear this list rather than an error.
+                delete doc.excludes;
+            }
+            else {
+                doc.excludes = excludes;
+            }
+        }
         else if (key === 'documentation.requireForProjectCompletion') {
             doc.requireForProjectCompletion =
                 rawValue.trim().toLowerCase() === 'true';
@@ -1655,7 +1698,9 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
         });
         const resultValue = key === 'documentation.requireForProjectCompletion'
             ? String(doc.requireForProjectCompletion ?? false)
-            : (doc[key.replace('documentation.', '')] ?? null);
+            : key === 'documentation.excludes'
+                ? (doc.excludes ?? null)
+                : (doc[key.replace('documentation.', '')] ?? null);
         return {
             key,
             value: resultValue,
@@ -1990,7 +2035,9 @@ async function runSet(keyArg, rawValue, surface, context, dependencies) {
             });
         }
         else {
-            context.logger.info(`${result.key}=${result.value ?? ''}`);
+            // `formatResolvedValue` renders an array-valued key the same way `get`
+            // does, rather than leaning on implicit `Array.prototype.toString`.
+            context.logger.info(`${result.key}=${formatResolvedValue(result.value) ?? ''}`);
         }
         process.exitCode = 0;
     }

package/dist/commands/docs/index-generate/generator.d.ts

@@ -4,6 +4,48 @@ export interface IndexEntry {
     path: string;
     children?: IndexEntry[];
 }
-export declare function generateIndex(docsDir: string): Promise<IndexEntry[]>;
+export interface GenerateIndexOptions {
+    /**
+     * Glob patterns whose matches are left out of the index. See
+     * {@link createExclusionMatcher} for the grammar; an empty or omitted list
+     * indexes everything, byte-identically to the pre-exclusion behavior.
+     */
+    excludes?: string[];
+}
+/**
+ * A compiled exclusion list.
+ *
+ * Files and directories are asked separately so a trailing-slash pattern can
+ * mean "directories only" while every other pattern applies to both.
+ */
+export interface ExclusionMatcher {
+    excludesFile: (relativePath: string) => boolean;
+    excludesDirectory: (relativePath: string) => boolean;
+}
+/**
+ * Compile exclusion globs matched against **docs-root-relative POSIX paths**
+ * (`api/auth.md`, `api/nested`), never against absolute or CWD-relative ones.
+ *
+ * Grammar, defined once and documented in
+ * `apps/oat-docs/docs/reference/oat-directory-structure.md`:
+ *
+ * - `*` matches any run of characters inside a single path segment.
+ * - `**` spans `/` only as a whole segment, where it covers zero or more
+ *   segments: `**\/CLAUDE.md` matches `CLAUDE.md` and `api/CLAUDE.md`. Inside a
+ *   segment (`a**b`) it is an ordinary single-segment wildcard.
+ * - Patterns are anchored at both ends against the whole relative path, so a
+ *   bare `CLAUDE.md` matches only the root-level file. Use `**\/CLAUDE.md` for
+ *   every depth.
+ * - A trailing `/` restricts a pattern to directories: `drafts/` prunes the
+ *   `drafts` directory and everything beneath it, and never matches a file.
+ *   Without it, a pattern that matches a directory path prunes it too.
+ * - Matching is case-sensitive, `/` is the separator on every platform, and
+ *   `*` is the only metacharacter — `.`, `+`, and friends are literal.
+ *
+ * Entries are trimmed; a leading `./` or `/` is stripped so both spellings
+ * anchor at the docs root. Blank entries are ignored.
+ */
+export declare function createExclusionMatcher(patterns: readonly string[]): ExclusionMatcher;
+export declare function generateIndex(docsDir: string, options?: GenerateIndexOptions): Promise<IndexEntry[]>;
 export declare function renderIndex(entries: IndexEntry[]): string;
 //# sourceMappingURL=generator.d.ts.map

package/dist/commands/docs/index-generate/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/generator.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB;AA4ED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAiC1E;AAmBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAMzD"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/generator.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD,iBAAiB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;CACtD;AAmHD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,gBAAgB,CAwClB;AAqID,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,UAAU,EAAE,CAAC,CAMvB;AAmBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAMzD"}

package/dist/commands/docs/index-generate/generator.js

@@ -1,5 +1,155 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+const NO_EXCLUSIONS = {
+    excludesFile: () => false,
+    excludesDirectory: () => false,
+};
+/**
+ * Match one path segment against one pattern segment, where `*` is the only
+ * metacharacter and never crosses `/`.
+ *
+ * This is the classic greedy two-pointer wildcard match, deliberately not a
+ * compiled regular expression: a pattern like `*a*a*a...` translates to
+ * nested-quantifier alternatives that backtrack exponentially, and exclusion
+ * patterns come from config and flags where a typo should not hang generation.
+ * Restarting from the last `*` instead bounds the work at O(pattern x text).
+ */
+function matchSegment(pattern, text) {
+    let patternIndex = 0;
+    let textIndex = 0;
+    let starPatternIndex = -1;
+    let starTextIndex = 0;
+    while (textIndex < text.length) {
+        if (pattern[patternIndex] === '*') {
+            // Collapse a run of stars: within a segment they are all equivalent.
+            while (pattern[patternIndex] === '*') {
+                patternIndex += 1;
+            }
+            if (patternIndex === pattern.length) {
+                return true;
+            }
+            starPatternIndex = patternIndex;
+            starTextIndex = textIndex;
+            continue;
+        }
+        if (patternIndex < pattern.length &&
+            pattern[patternIndex] === text[textIndex]) {
+            patternIndex += 1;
+            textIndex += 1;
+            continue;
+        }
+        if (starPatternIndex === -1) {
+            return false;
+        }
+        // Give the last star one more character and retry from just after it.
+        starTextIndex += 1;
+        patternIndex = starPatternIndex;
+        textIndex = starTextIndex;
+    }
+    while (pattern[patternIndex] === '*') {
+        patternIndex += 1;
+    }
+    return patternIndex === pattern.length;
+}
+/**
+ * Match a docs-root-relative path against a pattern, segment by segment, where
+ * a whole-segment `**` spans zero or more path segments.
+ *
+ * Same greedy-restart shape as {@link matchSegment}, one level up, so a pattern
+ * full of `**` segments stays bounded too.
+ */
+function matchPath(patternSegments, pathSegments) {
+    let patternIndex = 0;
+    let pathIndex = 0;
+    let starPatternIndex = -1;
+    let starPathIndex = 0;
+    while (pathIndex < pathSegments.length) {
+        if (patternSegments[patternIndex] === '**') {
+            while (patternSegments[patternIndex] === '**') {
+                patternIndex += 1;
+            }
+            if (patternIndex === patternSegments.length) {
+                return true;
+            }
+            starPatternIndex = patternIndex;
+            starPathIndex = pathIndex;
+            continue;
+        }
+        if (patternIndex < patternSegments.length &&
+            matchSegment(patternSegments[patternIndex], pathSegments[pathIndex])) {
+            patternIndex += 1;
+            pathIndex += 1;
+            continue;
+        }
+        if (starPatternIndex === -1) {
+            return false;
+        }
+        starPathIndex += 1;
+        patternIndex = starPatternIndex;
+        pathIndex = starPathIndex;
+    }
+    while (patternSegments[patternIndex] === '**') {
+        patternIndex += 1;
+    }
+    return patternIndex === patternSegments.length;
+}
+/**
+ * Compile exclusion globs matched against **docs-root-relative POSIX paths**
+ * (`api/auth.md`, `api/nested`), never against absolute or CWD-relative ones.
+ *
+ * Grammar, defined once and documented in
+ * `apps/oat-docs/docs/reference/oat-directory-structure.md`:
+ *
+ * - `*` matches any run of characters inside a single path segment.
+ * - `**` spans `/` only as a whole segment, where it covers zero or more
+ *   segments: `**\/CLAUDE.md` matches `CLAUDE.md` and `api/CLAUDE.md`. Inside a
+ *   segment (`a**b`) it is an ordinary single-segment wildcard.
+ * - Patterns are anchored at both ends against the whole relative path, so a
+ *   bare `CLAUDE.md` matches only the root-level file. Use `**\/CLAUDE.md` for
+ *   every depth.
+ * - A trailing `/` restricts a pattern to directories: `drafts/` prunes the
+ *   `drafts` directory and everything beneath it, and never matches a file.
+ *   Without it, a pattern that matches a directory path prunes it too.
+ * - Matching is case-sensitive, `/` is the separator on every platform, and
+ *   `*` is the only metacharacter — `.`, `+`, and friends are literal.
+ *
+ * Entries are trimmed; a leading `./` or `/` is stripped so both spellings
+ * anchor at the docs root. Blank entries are ignored.
+ */
+export function createExclusionMatcher(patterns) {
+    const filePatterns = [];
+    const directoryPatterns = [];
+    for (const rawPattern of patterns) {
+        const trimmedPattern = rawPattern.trim();
+        if (!trimmedPattern) {
+            continue;
+        }
+        const directoryOnly = trimmedPattern.endsWith('/');
+        const normalized = trimmedPattern
+            .replace(/\/+$/, '')
+            .replace(/^\.\//, '')
+            .replace(/^\/+/, '');
+        if (!normalized) {
+            continue;
+        }
+        const segments = normalized.split('/');
+        directoryPatterns.push(segments);
+        if (!directoryOnly) {
+            filePatterns.push(segments);
+        }
+    }
+    if (directoryPatterns.length === 0) {
+        return NO_EXCLUSIONS;
+    }
+    const matches = (compiled, relativePath) => {
+        const pathSegments = relativePath.split('/');
+        return compiled.some((segments) => matchPath(segments, pathSegments));
+    };
+    return {
+        excludesFile: (relativePath) => matches(filePatterns, relativePath),
+        excludesDirectory: (relativePath) => matches(directoryPatterns, relativePath),
+    };
+}
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
 const HEADING_RE = /^#\s+(.+)$/m;
 function fileNameToTitle(fileName) {
@@ -60,15 +210,25 @@ function prefixEntryPath(entry, prefix) {
         children: entry.children?.map((child) => prefixEntryPath(child, prefix)),
     };
 }
-export async function generateIndex(docsDir) {
+/** Docs-root-relative POSIX path used for matching, never for reading files. */
+function relativeKey(base, name) {
+    return base ? `${base}/${name}` : name;
+}
+async function collectEntries(docsDir, relativeBase, matcher) {
     const entries = [];
     const subdirs = [];
     const dirEntries = await readdir(docsDir, { withFileTypes: true });
     for (const entry of dirEntries) {
+        const relativePath = relativeKey(relativeBase, entry.name);
         if (entry.isDirectory()) {
-            subdirs.push(entry.name);
+            if (!matcher.excludesDirectory(relativePath)) {
+                subdirs.push(entry.name);
+            }
         }
         else if (entry.isFile() && entry.name.endsWith('.md')) {
+            if (matcher.excludesFile(relativePath)) {
+                continue;
+            }
             const filePath = join(docsDir, entry.name);
             const content = await readFile(filePath, 'utf8');
             const { title, description } = resolveTitle(content, entry.name);
@@ -80,7 +240,10 @@ export async function generateIndex(docsDir) {
         }
     }
     for (const subdir of subdirs.sort()) {
-        const children = await generateIndex(join(docsDir, subdir));
+        const children = await collectEntries(join(docsDir, subdir), relativeKey(relativeBase, subdir), matcher);
+        // A directory with no surviving children emits no heading. This already
+        // pruned genuinely empty directories; exclusion simply empties more of
+        // them, and it composes upward through the recursion.
         if (children.length > 0) {
             entries.push({
                 title: fileNameToTitle(subdir),
@@ -91,6 +254,9 @@ export async function generateIndex(docsDir) {
     }
     return sortEntries(entries);
 }
+export async function generateIndex(docsDir, options = {}) {
+    return collectEntries(docsDir, '', createExclusionMatcher(options.excludes ?? []));
+}
 function renderEntries(entries, indent) {
     const lines = [];
     const prefix = '  '.repeat(indent);

package/dist/commands/docs/index-generate/index.d.ts

@@ -1,13 +1,18 @@
 import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
+import { type OatConfig } from '../../../config/oat-config.js';
 import { Command } from 'commander';
 export declare const GENERATED_INDEX_WARNING = "<!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->";
 interface IndexGenerateFileDependencies {
-    generateIndex: (docsDir: string) => Promise<import('./generator.js').IndexEntry[]>;
+    generateIndex: (docsDir: string, options: import('./generator.js').GenerateIndexOptions) => Promise<import('./generator.js').IndexEntry[]>;
     renderIndex: (entries: import('./generator.js').IndexEntry[]) => string;
     writeFile: (path: string, content: string, encoding: BufferEncoding) => Promise<void>;
-    readOatConfig: (repoRoot: string) => Promise<import('../../../config/oat-config.js').OatConfig>;
-    writeOatConfig: (repoRoot: string, config: import('../../../config/oat-config.js').OatConfig) => Promise<void>;
+    readOatConfig: (repoRoot: string) => Promise<OatConfig>;
+    writeOatConfig: (repoRoot: string, config: OatConfig) => Promise<void>;
     resolveRepoRoot: (cwd: string) => Promise<string>;
+    dirExists: (path: string) => Promise<boolean>;
+    readFileIfPresent: (path: string) => Promise<string | null>;
+    realpath: (path: string) => Promise<string>;
+    readLinkIfSymlink: (path: string) => Promise<string | null>;
 }
 interface IndexGenerateDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;

package/dist/commands/docs/index-generate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAOjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAqFD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAuBjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,aAAa,EAAE,oBAAoB,KAChD,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAggBD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAgCT"}