@aopslab/domain-tooling-docman 0.1.4

package/dist/tools.js

@@ -0,0 +1,926 @@
+import { buildDocmanDomainCapabilityManifest as buildDocmanDomainCapabilityManifestFromKit, buildDocmanHostRouteProjection as buildDocmanHostRouteProjectionFromKit, clearDocmanKitEnvConfigCache, clearDocmanKitOperationCaches, listDocmanOperationSpecs as listDocmanOperationSpecsFromKit, parseDocmanToolInput, runDocmanKitOperationById, } from '@aopslab/domain-kit-docman';
+import { DOCMAN_TOOL_SPECS } from '@aopslab/domain-ops-docman/specs';
+const DEFAULT_DOCMAN_SCOPE_ID = '00000000-0000-4000-8000-000000000000';
+const DOCMAN_MANIFEST_ARTIFACTS = [
+    {
+        id: 'dcm',
+        title: 'Domain Capability Manifest',
+        summary: 'Canonical capability source derived from Docman kit contracts, docs, policies, and schemas.',
+        canonicalRole: 'canonical',
+    },
+    {
+        id: 'routes',
+        title: 'Host Route Projection',
+        summary: 'HTTP route projection derived from the canonical DCM.',
+        canonicalRole: 'projection',
+    },
+    {
+        id: 'agent',
+        title: 'Agent Tool Manifest',
+        summary: 'Agent-oriented tool descriptor projection derived from DCM docs, aliases, and policy.',
+        canonicalRole: 'projection',
+    },
+    {
+        id: 'cli',
+        title: 'CLI Projection',
+        summary: 'Derived command/help projection for standalone CLI users and local agents. DCM remains canonical.',
+        canonicalRole: 'projection',
+    },
+    {
+        id: 'host-registration',
+        aliases: ['hrm'],
+        title: 'Host Registration Manifest',
+        summary: 'AOPS/runtime registration payload. HRM is not a capability source.',
+        canonicalRole: 'registration',
+    },
+    {
+        id: 'ops',
+        aliases: ['operations'],
+        title: 'Operation Specs',
+        summary: 'Resolved shared operation specs and contract args used by tooling/CLI surfaces.',
+        canonicalRole: 'list',
+    },
+];
+function normalizeIdentifier(value) {
+    return String(value ?? '').trim().toLowerCase().replace(/^\/+/, '');
+}
+function normalizeOperationId(value) {
+    return normalizeIdentifier(value)
+        .replace(/^operations\//, '')
+        .replace(/^api\/docman\/operations\//, '')
+        .replace(/\//g, '.')
+        .replace(/\.+/g, '.')
+        .replace(/^docman\./, '');
+}
+function normalizeNonEmptyString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function toOperationPath(operationId) {
+    return `operations/${operationId.replace(/\./g, '/')}`;
+}
+function toGatewayToolId(operationId) {
+    return `docman.${operationId}`;
+}
+function toLocalFallbackToolId(operationId) {
+    return `docman-${operationId.replace(/\./g, '-')}`;
+}
+function buildAliases(spec) {
+    const aliases = new Set();
+    const opId = normalizeOperationId(spec.operationId);
+    const gatewayToolId = toGatewayToolId(opId);
+    const localToolId = normalizeIdentifier(spec.toolId);
+    aliases.add(opId);
+    aliases.add(gatewayToolId);
+    aliases.add(localToolId);
+    aliases.add(toLocalFallbackToolId(opId));
+    aliases.add(toOperationPath(opId));
+    aliases.add('/' + toOperationPath(opId));
+    return [...aliases];
+}
+function buildOperationAliasIndex(specs) {
+    const index = new Map();
+    for (const spec of specs) {
+        for (const alias of buildAliases(spec)) {
+            index.set(normalizeIdentifier(alias), spec.operationId);
+        }
+    }
+    return index;
+}
+function toOperationMap(specs) {
+    return new Map(specs.map((spec) => [normalizeOperationId(spec.operationId), spec]));
+}
+function toOperationRefMap(manifest) {
+    return new Map(manifest.capabilities.operations.map((operation) => [normalizeOperationId(operation.operationId), operation]));
+}
+function toRouteMap(routes) {
+    return new Map(routes.map((route) => [normalizeOperationId(route.operation), route]));
+}
+function toRecord(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return {};
+    return input;
+}
+function toStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => String(entry ?? '').trim())
+        .filter(Boolean);
+}
+function mergeStringLists(...groups) {
+    const merged = new Set();
+    for (const group of groups) {
+        if (!group)
+            continue;
+        for (const entry of group) {
+            const normalized = String(entry ?? '').trim();
+            if (!normalized)
+                continue;
+            merged.add(normalized);
+        }
+    }
+    return [...merged];
+}
+function toKebabCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[_\s.]+/g, '-')
+        .toLowerCase();
+}
+function appendSection(target, title, lines) {
+    const normalized = lines.map((line) => String(line ?? '').trimEnd()).filter(Boolean);
+    if (normalized.length === 0)
+        return;
+    target.push({ title, lines: normalized });
+}
+function buildExampleValueHint(option) {
+    const name = String(option.name ?? '').trim();
+    const type = String(option.type ?? '').trim().toLowerCase();
+    if (type === 'json') {
+        if (name === 'filter')
+            return '\'{}\'';
+        if (name === 'options')
+            return '\'{"limit":5}\'';
+        if (name === 'data')
+            return '\'{"...":"..."}\'';
+        if (name === 'patch')
+            return '\'{"...":"..."}\'';
+        return '\'{}\'';
+    }
+    if (type === 'number')
+        return '1';
+    if (type === 'boolean')
+        return 'true';
+    return String(option.valueHint ?? `<${name || 'value'}>`).trim();
+}
+function buildOptionLabel(option) {
+    const flag = String(option.flag ?? '').trim();
+    const valueHint = String(option.valueHint ?? '').trim();
+    if (!flag)
+        return '';
+    const withValue = valueHint ? `${flag} ${valueHint}` : flag;
+    return option.required ? `${withValue} (required)` : withValue;
+}
+function buildSugarUsage(commandSpec) {
+    const tokens = [...commandSpec.command];
+    for (const option of commandSpec.options ?? []) {
+        const label = buildOptionLabel(option);
+        if (!label)
+            continue;
+        tokens.push(option.required ? label.replace(' (required)', '') : `[${label}]`);
+    }
+    tokens.push('[--help]');
+    return tokens.join(' ');
+}
+function buildSugarExample(commandSpec) {
+    const tokens = [...commandSpec.command];
+    const options = [...(commandSpec.options ?? [])];
+    const selected = options.filter((option) => option.required);
+    if (selected.length === 0) {
+        const filterOption = options.find((option) => option.name === 'filter');
+        if (filterOption)
+            selected.push(filterOption);
+    }
+    for (const option of selected) {
+        if (!option.flag)
+            continue;
+        tokens.push(option.flag);
+        if (option.type !== 'boolean') {
+            tokens.push(buildExampleValueHint(option));
+        }
+    }
+    return tokens.join(' ');
+}
+function buildOperationArgRows(spec, commandSpec) {
+    if (commandSpec && (commandSpec.options?.length ?? 0) > 0) {
+        return (commandSpec.options ?? []).map((option) => {
+            const label = buildOptionLabel(option);
+            const details = [
+                option.description ? String(option.description).trim() : '',
+                option.type ? `type=${option.type}` : '',
+            ].filter(Boolean);
+            return details.length > 0 ? `${label}  ${details.join('; ')}` : label;
+        });
+    }
+    return spec.args.map((arg) => {
+        const flag = `--${toKebabCase(arg.name)}`;
+        const label = arg.optional ? `${flag} <${arg.name}>` : `${flag} <${arg.name}> (required)`;
+        return `${label}  Contract arg`;
+    });
+}
+function buildCommonRuntimeHelpRows(includeNoHook) {
+    const rows = [
+        '--repo-url <repo-url>  Override runtime repo URL for this invocation',
+        '--scope-id <id>  Override scope id for this invocation',
+        '--tenant-id <uuid>  Override tenant id for this invocation',
+        '--execution-mode <host|tooling>  Force host or tooling execution mode',
+        '--host-config <path>  Resolve runtime env from an explicit host config file',
+        '--log-level <level>  Override log level for this invocation',
+        '--help  Show command help without executing the command',
+    ];
+    if (includeNoHook)
+        rows.splice(rows.length - 1, 0, '--no-hook  Generated sugar only; bypass alias hook adaptation');
+    return rows;
+}
+function findCommandSpecForOperation(operationId) {
+    const localFallbackToolId = toLocalFallbackToolId(normalizeOperationId(operationId));
+    return DOCMAN_TOOL_SPECS.find((spec) => String(spec.id ?? '').trim().toLowerCase() === localFallbackToolId);
+}
+function createCommandDescriptor(input) {
+    return {
+        id: input.id,
+        kind: input.kind,
+        title: input.title,
+        command: input.command,
+        aliases: [...new Set((input.aliases ?? []).map((entry) => String(entry ?? '').trim()).filter(Boolean))],
+        ...(input.summary ? { summary: input.summary } : {}),
+        ...(input.operationId ? { operationId: input.operationId } : {}),
+        ...(input.toolId ? { toolId: input.toolId } : {}),
+        ...(input.localToolId ? { localToolId: input.localToolId } : {}),
+        sections: input.sections,
+    };
+}
+function buildRootCommandDescriptor() {
+    const sections = [];
+    appendSection(sections, 'IMPORTANT NOTICE', [
+        'This is a beta CLI. Do not point it at production Docman databases unless you already have backups and rollback procedures.',
+        'For AI-agent experiments, strongly prefer a temporary or non-production repo URL first.',
+    ]);
+    appendSection(sections, 'Purpose', [
+        'docman-cli is a standalone Docman runtime for document graphs, versions, sections, pages, snippets, embeds, compose/render flows, and manifest-driven CRUD/operation execution.',
+        'It can run directly against PostgreSQL or SQLite, persist local CLI config under ~/.aops/docman.config.json, default to ~/.aops/docman.aops.sqlite when no Docman-specific repo source is configured, and expose the same manifest surface to AOPS when needed.',
+    ]);
+    appendSection(sections, 'Standalone usage', [
+        '1. If no Docman repo source is set, docman auto-uses ~/.aops/docman.aops.sqlite.',
+        '2. Inspect tools, ops, or manifest before mutating data.',
+        '3. Prefer canonical tool / op calls when the exact contract matters.',
+        '4. Generated sugar is useful for short CRUD flows; use --no-hook to bypass alias hooks.',
+        '5. Generic AOPS_PG_URL / DEV_PG_URL env values do not override standalone default sqlite.',
+    ]);
+    appendSection(sections, 'AOPS alternative', [
+        '1. If AOPS is installed, register Docman from `docman manifest host-registration`.',
+        '2. Typical path: `aops-cli host register --from-command \'docman manifest host-registration\'`.',
+        '3. Discover via `aops-cli agent tools --domain docman --workspace-name Default` or `GET /api/agent/tools?domain=docman`.',
+        '4. Read tool detail first when discovery/docs/examples matter, then invoke through `aops-cli agent invoke ...` or `POST /api/agent/tools/<toolId>/invoke`.',
+        '5. Prefer AOPS-first when you want shared discovery, auth, host diagnostics, or routing.',
+        '6. Canonical content owner is `scopeId`; AOPS `workspace-name` / `project-id` values are resolver helpers.',
+    ]);
+    appendSection(sections, 'Usage', [
+        'docman <command> [subcommand] [--options]',
+        'docman <command> --help',
+        'docman help <command> [subcommand]',
+        'docman --version',
+    ]);
+    appendSection(sections, 'Core commands', [
+        'docman tools',
+        'docman ops',
+        'docman manifest [dcm|routes|agent|cli|host-registration|ops]',
+        'docman manifest get <artifact> [--path <dot.path>]',
+        'docman manifest show <artifact> [--path <dot.path>]',
+        'docman config show',
+        'docman config set --repo-url <repo-url>',
+        'docman version',
+        'docman tool --id <tool-or-operation-id> --input <json|@file>',
+        'docman op <operation-or-tool-id> [--input <json|@file>] [--arg value]',
+        'Not: op/operation/run raw-canonical moddur; hooklar default olarak BYPASS edilir.',
+    ]);
+    appendSection(sections, 'Generated sugar commands (manifest-driven aliases)', [
+        'docman <resource> <action> [--flags]',
+        'or directly: docman <operation.id> [--flags]',
+    ]);
+    appendSection(sections, 'Runtime options', [
+        '--repo-url <repo-url>            (precedence: flag -> DOCMAN_REPO_URL/DOCMAN_SQLITE_URL/DOCMAN_PG_URL -> ~/.aops/docman.config.json -> aops config -> default ~/.aops/docman.aops.sqlite)',
+        `--scope-id <id>                  (default: ${DEFAULT_DOCMAN_SCOPE_ID})`,
+        '--tenant-id <uuid>               (default: DEFAULT_TENANT_AS_UUID_STRING)',
+        '--execution-mode <host|tooling>  (default: host)',
+        '--host-config <path>             (opsiyonel; single-domain host config. yoksa local resolver kullanilir)',
+        '--no-hook                        (generated sugar komutlarinda domain hooklarini kapatir)',
+        '--log-level <level>              (default: LOG_LEVEL env)',
+        '--help',
+    ]);
+    appendSection(sections, 'Typical repo-url patterns', [
+        '--repo-url postgres://user:pass@host:5432/dbname',
+        '--repo-url file:/absolute/path/docman.sqlite',
+        'no --repo-url                    => varsayilan sqlite (~/.aops/docman.aops.sqlite; exact path icin: docman config show)',
+        'export DOCMAN_PG_URL=postgres://user:pass@host:5432/dbname',
+        'export DOCMAN_SQLITE_URL=file:/absolute/path/docman.sqlite',
+        `docman config set --repo-url file:/absolute/path/docman.sqlite --scope-id ${DEFAULT_DOCMAN_SCOPE_ID}`,
+        'For temporary AI-agent trials, prefer an isolated database or local sqlite file.',
+    ]);
+    appendSection(sections, 'Common AI-agent scenarios', [
+        'inspect catalog and examples before mutate',
+        'persist one safe repo-url once, then reuse docman without repeating --repo-url',
+        'create/list/get documents and versions',
+        'compose or render markdown from an existing document version',
+        'exercise hooks for convenience, then fall back to canonical op/tool when needed',
+        'inspect detailed command help generated from DCM/contract docs before invoke',
+        'inspect DCM/CLI/HRM artifacts via `manifest get` or `manifest show` before autonomous invoke',
+    ]);
+    appendSection(sections, 'Examples', [
+        'docman config show',
+        'docman config set --help',
+        'docman document list --help',
+        'docman op docman.document.compose.fetch --help',
+        'docman manifest cli',
+        'docman manifest get dcm --path docs.operations.document.list',
+        'docman manifest show hrm',
+        'docman document list --filter \'{}\'                  # default local sqlite if no repo source is configured',
+        `docman config set --repo-url postgres://user:pass@host:5432/docman --scope-id ${DEFAULT_DOCMAN_SCOPE_ID}`,
+        `docman config set --repo-url file:/tmp/docman.sqlite --scope-id ${DEFAULT_DOCMAN_SCOPE_ID}`,
+        'docman tool --id docman.document.list --input \'{"filter":{},"options":{"limit":5}}\'',
+        'docman op docman.document.list --input \'{"filter":{},"options":{"limit":5}}\'',
+        'docman document list --filter \'{}\' --options \'{"limit":5}\'',
+        'docman tool --id docman.document.create --input \'{"data":{"documentUid":"DOC-001","title":"Sample","status":"draft","visibility":"internal"}}\'',
+        'docman document get --document-id <id>             # hook alias',
+        'docman document get --document-id <id> --no-hook   # hook disabled => requires --id',
+        'docman op docman.document.compose.fetch --document-version-id <id>',
+        'docman op docman.document.compose.fetch --input \'{"documentVersionId":"<id>","pageNumber":1}\'',
+    ]);
+    return createCommandDescriptor({
+        id: 'docman',
+        kind: 'root',
+        title: 'docman-cli',
+        command: ['docman'],
+        aliases: ['docman', 'help'],
+        summary: 'Standalone Docman CLI runtime and manifest browser.',
+        sections,
+    });
+}
+function buildConfigCommandDescriptors() {
+    const commonAliases = ['config'];
+    const configSections = [];
+    appendSection(configSections, 'Usage', [
+        'docman config show',
+        'docman config set --repo-url <repo-url>',
+        'docman config --help',
+    ]);
+    appendSection(configSections, 'Subcommands', [
+        'show  Inspect stored/default/effective runtime config',
+        'set  Persist CLI defaults under ~/.aops/docman.config.json',
+    ]);
+    appendSection(configSections, 'Examples', [
+        'docman config show',
+        `docman config set --repo-url file:/tmp/docman.sqlite --scope-id ${DEFAULT_DOCMAN_SCOPE_ID}`,
+    ]);
+    const showSections = [];
+    appendSection(showSections, 'Usage', ['docman config show', 'docman config show --help']);
+    appendSection(showSections, 'Purpose', [
+        'Display stored CLI config, resolved defaults, and effective runtime values without mutating anything.',
+        'Output includes defaultSqlitePath/defaultSqliteRepoUrl when standalone fallback is active.',
+    ]);
+    appendSection(showSections, 'Fields', [
+        'configPath / exists / stored  Stored CLI config under ~/.aops/docman.config.json',
+        'defaults.aopsConfigRepoUrl  Repo URL discovered from ~/.aops/aops.config.json when present',
+        'defaults.defaultSqlitePath / defaultSqliteRepoUrl  Standalone fallback target under ~/.aops/',
+        'effective.*  Final runtime values and their sources',
+    ]);
+    appendSection(showSections, 'Examples', ['docman config show']);
+    const setSections = [];
+    appendSection(setSections, 'Usage', [
+        'docman config set [--repo-url <repo-url>] [--scope-id <id>] [--tenant-id <uuid>]',
+        'docman config set [--execution-mode <host|tooling>] [--host-config <path>] [--log-level <level>]',
+        'docman config set --help',
+    ]);
+    appendSection(setSections, 'Purpose', [
+        'Persist CLI defaults under ~/.aops/docman.config.json.',
+        'Only provided keys are updated; omitted keys stay unchanged.',
+    ]);
+    appendSection(setSections, 'Options', [
+        '--repo-url <repo-url>  Persist PostgreSQL or SQLite repo URL',
+        '--scope-id <id>  Persist default scope id',
+        '--tenant-id <uuid>  Persist default tenant id',
+        '--execution-mode <host|tooling>  Persist default execution mode',
+        '--host-config <path>  Persist explicit host config path',
+        '--log-level <level>  Persist default log level',
+        '--help  Show command help without writing config',
+    ]);
+    appendSection(setSections, 'Examples', [
+        `docman config set --repo-url file:/tmp/docman.sqlite --scope-id ${DEFAULT_DOCMAN_SCOPE_ID} --execution-mode host`,
+        'docman config set --repo-url postgresql://host:5432/docman --execution-mode tooling',
+    ]);
+    return [
+        createCommandDescriptor({
+            id: 'config',
+            kind: 'static',
+            title: 'docman config',
+            command: ['docman', 'config'],
+            aliases: commonAliases,
+            summary: 'Inspect or persist standalone CLI config.',
+            sections: configSections,
+        }),
+        createCommandDescriptor({
+            id: 'config.show',
+            kind: 'static',
+            title: 'docman config show',
+            command: ['docman', 'config', 'show'],
+            aliases: ['config show'],
+            summary: 'Display stored/default/effective runtime config.',
+            sections: showSections,
+        }),
+        createCommandDescriptor({
+            id: 'config.set',
+            kind: 'static',
+            title: 'docman config set',
+            command: ['docman', 'config', 'set'],
+            aliases: ['config set'],
+            summary: 'Persist standalone CLI defaults.',
+            sections: setSections,
+        }),
+    ];
+}
+function buildManifestCommandDescriptors() {
+    const manifestSections = [];
+    appendSection(manifestSections, 'Usage', [
+        'docman manifest [all|dcm|routes|agent|cli|host-registration|ops]',
+        'docman manifest get <artifact> [--path <dot.path>]',
+        'docman manifest show <artifact> [--path <dot.path>]',
+        'docman manifest --help',
+    ]);
+    appendSection(manifestSections, 'Subcommands', [
+        'all  Emit dcm + routes + agent + cli + host-registration + operations',
+        'dcm  Emit Domain Capability Manifest; canonical capability source',
+        'routes  Emit host route projection derived from DCM',
+        'agent  Emit agent-oriented tool descriptor manifest',
+        'cli  Emit derived CLI projection/help manifest',
+        'host-registration  Emit installed host registration payload (HRM; runtime registration only)',
+        'ops  Emit shared operation spec list',
+        'get  Extract raw JSON from a manifest artifact or a sub-path',
+        'show  Render a manifest artifact or a sub-path as human-readable text',
+    ]);
+    appendSection(manifestSections, 'Artifacts', DOCMAN_MANIFEST_ARTIFACTS.map((artifact) => {
+        const aliasLabel = artifact.aliases?.length ? ` (aliases: ${artifact.aliases.join(', ')})` : '';
+        return `${artifact.id}${aliasLabel}  ${artifact.summary}`;
+    }));
+    const dcmSections = [];
+    appendSection(dcmSections, 'Usage', ['docman manifest dcm', 'docman manifest dcm --help']);
+    appendSection(dcmSections, 'Purpose', [
+        'Emit Docman Domain Capability Manifest (DCM).',
+        'DCM is the canonical capability source; CLI/agent/routes are derived projections.',
+    ]);
+    appendSection(dcmSections, 'Typical Consumers', [
+        'CLI contextual help',
+        'AOPS discovery and tool projection',
+        'Agent-side contract/schema inspection',
+    ]);
+    const routesSections = [];
+    appendSection(routesSections, 'Usage', ['docman manifest routes', 'docman manifest routes --help']);
+    appendSection(routesSections, 'Purpose', [
+        'Emit host route projection derived from the Docman manifest.',
+        'Useful when you want HTTP method/pattern visibility for each operation.',
+    ]);
+    const agentSections = [];
+    appendSection(agentSections, 'Usage', ['docman manifest agent', 'docman manifest agent --help']);
+    appendSection(agentSections, 'Purpose', [
+        'Emit agent-oriented tool descriptor list derived from DCM docs, aliases, routes, and policy.',
+        'Useful for discovery surfaces that need tool ids, aliases, notes, examples, and schema refs.',
+    ]);
+    const cliSections = [];
+    appendSection(cliSections, 'Usage', ['docman manifest cli', 'docman manifest cli --help']);
+    appendSection(cliSections, 'Purpose', [
+        'Emit the derived CLI projection used by standalone help, manifest show/get, and local agent browse flows.',
+        'This is a read-only projection. DCM remains the canonical source of truth.',
+    ]);
+    const hrmSections = [];
+    appendSection(hrmSections, 'Usage', ['docman manifest host-registration', 'docman manifest host-registration --help']);
+    appendSection(hrmSections, 'Purpose', [
+        'Emit installed-host registration payload for AOPS host registration.',
+        'HRM is runtime registration metadata; it is not a second capability source.',
+        'Typical path: aops-cli host register --from-command \'docman manifest host-registration\'',
+    ]);
+    const opsSections = [];
+    appendSection(opsSections, 'Usage', ['docman manifest ops', 'docman manifest ops --help']);
+    appendSection(opsSections, 'Purpose', [
+        'Emit the shared resolved operation spec list that powers tooling/CLI projection.',
+        'Use when you want raw operation summaries, args, and examples without the wider DCM envelope.',
+    ]);
+    const getSections = [];
+    appendSection(getSections, 'Usage', [
+        'docman manifest get <artifact>',
+        'docman manifest get <artifact> --path <dot.path>',
+        'docman manifest get dcm --path docs.operations.document.list',
+        'docman manifest get cli --path commandsById.document.list',
+    ]);
+    appendSection(getSections, 'Purpose', [
+        'Print raw JSON from a selected manifest artifact or sub-path.',
+        'Dot paths support dotted map keys such as docs.operations.document.list or commandsById.config.set.',
+    ]);
+    const showSections = [];
+    appendSection(showSections, 'Usage', [
+        'docman manifest show <artifact>',
+        'docman manifest show <artifact> --path <dot.path>',
+        'docman manifest show hrm',
+        'docman manifest show dcm --path docs.operations.document.list',
+    ]);
+    appendSection(showSections, 'Purpose', [
+        'Render a selected manifest artifact or sub-path as human-readable text.',
+        'Useful for humans and AI agents that need to inspect summaries, notes, examples, and command sections before invoke.',
+    ]);
+    return [
+        createCommandDescriptor({
+            id: 'manifest',
+            kind: 'static',
+            title: 'docman manifest',
+            command: ['docman', 'manifest'],
+            aliases: ['manifest'],
+            summary: 'Browse canonical and derived Docman manifests.',
+            sections: manifestSections,
+        }),
+        createCommandDescriptor({
+            id: 'manifest.dcm',
+            kind: 'static',
+            title: 'docman manifest dcm',
+            command: ['docman', 'manifest', 'dcm'],
+            aliases: ['manifest dcm'],
+            summary: 'Emit canonical Docman DCM.',
+            sections: dcmSections,
+        }),
+        createCommandDescriptor({
+            id: 'manifest.routes',
+            kind: 'static',
+            title: 'docman manifest routes',
+            command: ['docman', 'manifest', 'routes'],
+            aliases: ['manifest routes'],
+            summary: 'Emit host route projection.',
+            sections: routesSections,
+        }),
+        createCommandDescriptor({
+            id: 'manifest.agent',
+            kind: 'static',
+            title: 'docman manifest agent',
+            command: ['docman', 'manifest', 'agent'],
+            aliases: ['manifest agent'],
+            summary: 'Emit agent tool projection.',
+            sections: agentSections,
+        }),
+        createCommandDescriptor({
+            id: 'manifest.cli',
+            kind: 'static',
+            title: 'docman manifest cli',
+            command: ['docman', 'manifest', 'cli'],
+            aliases: ['manifest cli'],
+            summary: 'Emit derived CLI projection.',
+            sections: cliSections,
+        }),
+        createCommandDescriptor({
+            id: 'manifest.host-registration',
+            kind: 'static',
+            title: 'docman manifest host-registration',
+            command: ['docman', 'manifest', 'host-registration'],
+            aliases: ['manifest host-registration', 'manifest hrm'],
+            summary: 'Emit host registration payload.',
+            sections: hrmSections,
+        }),
+        createCommandDescriptor({
+            id: 'manifest.ops',
+            kind: 'static',
+            title: 'docman manifest ops',
+            command: ['docman', 'manifest', 'ops'],
+            aliases: ['manifest ops', 'manifest operations'],
+            summary: 'Emit shared operation spec list.',
+            sections: opsSections,
+        }),
+        createCommandDescriptor({
+            id: 'manifest.get',
+            kind: 'static',
+            title: 'docman manifest get',
+            command: ['docman', 'manifest', 'get'],
+            aliases: ['manifest get'],
+            summary: 'Extract raw JSON from a manifest artifact.',
+            sections: getSections,
+        }),
+        createCommandDescriptor({
+            id: 'manifest.show',
+            kind: 'static',
+            title: 'docman manifest show',
+            command: ['docman', 'manifest', 'show'],
+            aliases: ['manifest show'],
+            summary: 'Render a manifest artifact as text.',
+            sections: showSections,
+        }),
+    ];
+}
+function buildToolsCommandDescriptor() {
+    const sections = [];
+    appendSection(sections, 'Usage', ['docman tools', 'docman tools --help']);
+    appendSection(sections, 'Purpose', [
+        'List Docman tool descriptors used by AOPS/agent discovery.',
+        'Each item includes tool id, aliases, summary, notes, examples, policy, route, and schema refs.',
+    ]);
+    appendSection(sections, 'Follow-up', [
+        'Use docman tool --id <toolId> --help for command-level invoke guidance.',
+        'Use docman manifest agent for the full agent manifest payload.',
+    ]);
+    return createCommandDescriptor({
+        id: 'tools',
+        kind: 'static',
+        title: 'docman tools',
+        command: ['docman', 'tools'],
+        aliases: ['tools'],
+        summary: 'List agent-facing Docman tool descriptors.',
+        sections,
+    });
+}
+function buildOpsCommandDescriptor() {
+    const sections = [];
+    appendSection(sections, 'Usage', ['docman ops', 'docman ops --help']);
+    appendSection(sections, 'Purpose', [
+        'List canonical Docman operation specs resolved from the shared contract surface.',
+        'Use when you want to inspect operation ids before invoking via docman op or docman tool.',
+    ]);
+    appendSection(sections, 'Follow-up', [
+        'Use docman op <operationId> --help for per-operation details.',
+        'Use docman manifest dcm for summaries/examples/contracts.',
+    ]);
+    return createCommandDescriptor({
+        id: 'ops',
+        kind: 'static',
+        title: 'docman ops',
+        command: ['docman', 'ops'],
+        aliases: ['ops'],
+        summary: 'List canonical Docman operation specs.',
+        sections,
+    });
+}
+function buildToolCommandDescriptor() {
+    const sections = [];
+    appendSection(sections, 'Usage', [
+        'docman tool --id <tool-or-operation-id> --input <json|@file>',
+        'docman tool --id docman.document.list --help',
+        'docman tool --help',
+    ]);
+    appendSection(sections, 'Purpose', [
+        'Invoke the exact canonical contract with an explicit JSON input payload.',
+        'This is the safest CLI surface when examples/docs/contracts matter.',
+    ]);
+    appendSection(sections, 'Options', [
+        '--id <tool-or-operation-id>  Accepts tool id, local alias, or operation id',
+        '--input <json|@file>  Exact operation input payload as inline JSON or @file',
+        ...buildCommonRuntimeHelpRows(false),
+    ]);
+    return createCommandDescriptor({
+        id: 'tool',
+        kind: 'static',
+        title: 'docman tool',
+        command: ['docman', 'tool'],
+        aliases: ['tool', 'invoke'],
+        summary: 'Invoke canonical Docman operations by explicit JSON input.',
+        sections,
+    });
+}
+function buildOpCommandDescriptor() {
+    const sections = [];
+    appendSection(sections, 'Usage', [
+        'docman op <operation-or-tool-id> [--input <json|@file>] [--arg value]',
+        'docman op docman.document.list --help',
+        'docman op --help',
+    ]);
+    appendSection(sections, 'Purpose', [
+        'Invoke canonical operations directly by operation id or tool id.',
+        'Raw op/operation/run mode bypasses generated sugar hooks by default.',
+    ]);
+    appendSection(sections, 'Options', [
+        '--input <json|@file>  Exact operation input payload',
+        'Or provide generated flags that match operation args, such as --id or --document-version-id',
+        ...buildCommonRuntimeHelpRows(false),
+    ]);
+    return createCommandDescriptor({
+        id: 'op',
+        kind: 'static',
+        title: 'docman op',
+        command: ['docman', 'op'],
+        aliases: ['op', 'operation', 'run'],
+        summary: 'Invoke canonical Docman operations directly.',
+        sections,
+    });
+}
+function buildVersionCommandDescriptor() {
+    const sections = [];
+    appendSection(sections, 'Usage', ['docman --version', 'docman version']);
+    appendSection(sections, 'Purpose', ['Print the installed @aopslab/domain-cli-docman package version and exit.']);
+    return createCommandDescriptor({
+        id: 'version',
+        kind: 'static',
+        title: 'docman version',
+        command: ['docman', 'version'],
+        aliases: ['version', '--version'],
+        summary: 'Print the installed CLI package version.',
+        sections,
+    });
+}
+function buildOperationCommandDescriptor(spec, manifest, routeMap) {
+    const normalizedOperationId = normalizeOperationId(spec.operationId);
+    const fullOperationId = toGatewayToolId(normalizedOperationId);
+    const localFallbackToolId = toLocalFallbackToolId(normalizedOperationId);
+    const gatewayToolId = toGatewayToolId(normalizedOperationId);
+    const operationDoc = toRecord(toRecord(toRecord(manifest.docs).operations)[normalizedOperationId]);
+    const route = routeMap.get(normalizedOperationId);
+    const commandSpec = findCommandSpecForOperation(spec.operationId);
+    const tags = mergeStringLists(spec.tags, toStringList(operationDoc.tags));
+    const examples = mergeStringLists(spec.examples, toStringList(operationDoc.examples)).slice(0, 2);
+    const notes = mergeStringLists(spec.docs?.notes, toStringList(operationDoc.notes));
+    const antiPatterns = mergeStringLists(spec.docs?.antiPatterns, toStringList(operationDoc.antiPatterns));
+    const preconditions = mergeStringLists(spec.docs?.preconditions, toStringList(operationDoc.preconditions));
+    const postconditions = mergeStringLists(spec.docs?.postconditions, toStringList(operationDoc.postconditions));
+    const summary = normalizeNonEmptyString(operationDoc.summary)
+        ?? normalizeNonEmptyString(spec.summary)
+        ?? normalizeNonEmptyString(route?.summary)
+        ?? fullOperationId;
+    const summaryLines = mergeStringLists([summary], commandSpec?.description && commandSpec.description !== summary ? [commandSpec.description] : undefined);
+    const usageLines = [
+        ...(commandSpec ? [buildSugarUsage(commandSpec)] : []),
+        `docman op ${fullOperationId} [--input <json|@file>] [--arg value] [--help]`,
+        `docman tool --id ${gatewayToolId} --input <json|@file> [--help]`,
+    ];
+    const sections = [];
+    appendSection(sections, 'Summary', summaryLines);
+    appendSection(sections, 'Identity', [
+        `operation: ${fullOperationId}`,
+        `tool id: ${gatewayToolId}`,
+        `local alias: ${localFallbackToolId}`,
+        spec.sideEffect ? `side effect: ${spec.sideEffect}` : '',
+        tags.length > 0 ? `tags: ${tags.join(', ')}` : '',
+    ]);
+    appendSection(sections, 'Usage', usageLines);
+    appendSection(sections, 'Host Route', route ? [`${route.method} ${route.pattern}`] : ['No host route projection found']);
+    appendSection(sections, 'Arguments', [
+        ...buildOperationArgRows(spec, commandSpec),
+        ...buildCommonRuntimeHelpRows(Boolean(commandSpec)),
+    ]);
+    const exampleLines = [];
+    if (commandSpec) {
+        exampleLines.push(buildSugarExample(commandSpec));
+    }
+    for (const example of examples) {
+        exampleLines.push(`docman op ${fullOperationId} --input '${example}'`);
+        exampleLines.push(`docman tool --id ${gatewayToolId} --input '${example}'`);
+    }
+    appendSection(sections, 'Examples', exampleLines);
+    appendSection(sections, 'Notes', notes);
+    appendSection(sections, 'Preconditions', preconditions);
+    appendSection(sections, 'Postconditions', postconditions);
+    appendSection(sections, 'Anti-Patterns', antiPatterns);
+    const capabilityOperation = manifest.capabilities.operations.find((operation) => normalizeOperationId(operation.operationId) === normalizedOperationId);
+    appendSection(sections, 'Schema Refs', [
+        capabilityOperation?.inputSchemaRef ? `input: ${capabilityOperation.inputSchemaRef}` : '',
+        capabilityOperation?.outputSchemaRef ? `output: ${capabilityOperation.outputSchemaRef}` : '',
+    ]);
+    appendSection(sections, 'Source', [
+        'Generated from Docman DCM docs, shared contract args/examples, host route projection, and CLI sugar specs.',
+    ]);
+    const aliases = new Set([
+        normalizedOperationId,
+        fullOperationId,
+        gatewayToolId,
+        localFallbackToolId,
+        toOperationPath(normalizedOperationId),
+        '/' + toOperationPath(normalizedOperationId),
+    ]);
+    if (commandSpec) {
+        aliases.add(commandSpec.command.join(' '));
+        aliases.add(commandSpec.command.slice(1).join(' '));
+    }
+    return createCommandDescriptor({
+        id: normalizedOperationId,
+        kind: 'operation',
+        title: commandSpec ? commandSpec.command.join(' ') : fullOperationId,
+        command: commandSpec?.command ?? ['docman', fullOperationId],
+        aliases: [...aliases],
+        summary,
+        operationId: fullOperationId,
+        toolId: gatewayToolId,
+        localToolId: localFallbackToolId,
+        sections,
+    });
+}
+export function listDocmanToolingOperations(options) {
+    return listDocmanOperationSpecsFromKit(options).map((spec) => ({ ...spec }));
+}
+export function getDocmanOperationSpecById(identifier, options) {
+    const specs = listDocmanToolingOperations(options);
+    const aliases = buildOperationAliasIndex(specs);
+    const operationId = aliases.get(normalizeIdentifier(identifier));
+    if (!operationId)
+        return null;
+    const map = toOperationMap(specs);
+    return map.get(normalizeOperationId(operationId)) ?? null;
+}
+export function resolveDocmanOperationIdByToolId(identifier, options) {
+    const specs = listDocmanToolingOperations(options);
+    const aliases = buildOperationAliasIndex(specs);
+    const operationId = aliases.get(normalizeIdentifier(identifier));
+    return operationId ? normalizeOperationId(operationId) : null;
+}
+export function resolveDocmanToolIdByOperationId(operationId, options) {
+    const spec = getDocmanOperationSpecById(operationId, options);
+    if (!spec)
+        return null;
+    return toGatewayToolId(normalizeOperationId(spec.operationId));
+}
+export function listDocmanToolingTools(options) {
+    const manifest = buildDocmanDomainCapabilityManifestFromKit({
+        includeDocs: true,
+        refresh: options?.refresh,
+    });
+    const docsByOperation = manifest.docs?.operations ?? {};
+    const policyByOperation = manifest.policies?.operations ?? {};
+    const operationRefMap = toOperationRefMap(manifest);
+    const routeMap = toRouteMap(buildDocmanHostRouteProjectionFromKit({ refresh: options?.refresh }));
+    const specs = listDocmanToolingOperations(options);
+    const tools = [];
+    for (const spec of specs) {
+        const operationId = normalizeOperationId(spec.operationId);
+        const op = operationRefMap.get(operationId);
+        const doc = docsByOperation[operationId];
+        const route = routeMap.get(operationId);
+        const aliases = buildAliases(spec);
+        tools.push({
+            toolId: toGatewayToolId(operationId),
+            localToolId: spec.toolId,
+            domain: 'docman',
+            operationId,
+            title: op?.title ?? spec.summary,
+            summary: doc?.summary ?? spec.summary ?? op?.title,
+            sideEffect: op?.sideEffect,
+            tags: op?.tags,
+            inputSchemaRef: op?.inputSchemaRef,
+            outputSchemaRef: op?.outputSchemaRef,
+            policy: policyByOperation[operationId],
+            aliases,
+            notes: mergeStringLists(spec.docs?.notes, toStringList(doc?.notes)),
+            examples: mergeStringLists(spec.examples, toStringList(doc?.examples)),
+            ...(route ? { route: { method: route.method, pattern: route.pattern } } : {}),
+        });
+    }
+    return tools.sort((left, right) => left.operationId.localeCompare(right.operationId));
+}
+export function buildDocmanAgentManifest(options) {
+    return {
+        kind: 'docman-agent-manifest',
+        version: 'v1',
+        domain: 'docman',
+        generatedAt: new Date().toISOString(),
+        tools: listDocmanToolingTools(options),
+    };
+}
+export function buildDocmanCliProjection(options) {
+    const manifest = buildDocmanDomainCapabilityManifestFromKit({
+        includeDocs: true,
+        refresh: options?.refresh,
+    });
+    const routes = buildDocmanHostRouteProjectionFromKit({ refresh: options?.refresh });
+    const routeMap = toRouteMap(routes);
+    const operations = listDocmanToolingOperations(options);
+    const commands = [
+        buildRootCommandDescriptor(),
+        ...buildConfigCommandDescriptors(),
+        ...buildManifestCommandDescriptors(),
+        buildToolsCommandDescriptor(),
+        buildOpsCommandDescriptor(),
+        buildToolCommandDescriptor(),
+        buildOpCommandDescriptor(),
+        buildVersionCommandDescriptor(),
+        ...operations.map((spec) => buildOperationCommandDescriptor(spec, manifest, routeMap)),
+    ];
+    return {
+        kind: 'docman-cli-projection',
+        version: 'v1',
+        domain: 'docman',
+        generatedAt: new Date().toISOString(),
+        sourceOfTruth: {
+            canonical: 'dcm',
+            notes: [
+                'DCM remains the single canonical capability source.',
+                'CLI/help/agent/routes are derived projections and should not drift from DCM/contract metadata.',
+                'HRM is runtime registration metadata only; it is not a capability source.',
+            ],
+        },
+        artifacts: DOCMAN_MANIFEST_ARTIFACTS.map((artifact) => ({ ...artifact })),
+        commands,
+        commandsById: Object.fromEntries(commands.map((command) => [command.id, command])),
+    };
+}
+export async function runDocmanOperationById(operationId, input = {}, options) {
+    const spec = getDocmanOperationSpecById(operationId, options);
+    if (!spec) {
+        throw new Error(`unknown_docman_operation:${operationId}`);
+    }
+    const normalizedInput = toRecord(input);
+    const parsedInput = parseDocmanToolInput(spec.operationId, normalizedInput);
+    return runDocmanKitOperationById(spec.operationId, parsedInput);
+}
+export async function runDocmanToolById(identifier, input = {}, options) {
+    const operationId = resolveDocmanOperationIdByToolId(identifier, options);
+    if (!operationId) {
+        throw new Error(`unknown_docman_tool_or_operation:${identifier}`);
+    }
+    return runDocmanOperationById(operationId, input, options);
+}
+export function clearDocmanToolingRuntimeCaches() {
+    clearDocmanKitEnvConfigCache();
+    clearDocmanKitOperationCaches();
+}
+export const buildDocmanDomainCapabilityManifest = buildDocmanDomainCapabilityManifestFromKit;
+export const buildDocmanHostRouteProjection = buildDocmanHostRouteProjectionFromKit;