@aopslabs/aops 0.3.30 → 0.3.32

package/dist/lib/user-guide-sections.js

@@ -0,0 +1,488 @@
+export const COMMAND_CATALOG_START = '<!-- aops-generated:cli-command-catalog:start -->';
+export const COMMAND_CATALOG_END = '<!-- aops-generated:cli-command-catalog:end -->';
+export const DISCOVERY_GUIDE_START = '<!-- aops-generated:capability-discovery:start -->';
+export const DISCOVERY_GUIDE_END = '<!-- aops-generated:capability-discovery:end -->';
+export const DOCMAN_COMMAND_CATALOG_START = '<!-- aops-generated:docman-command-catalog:start -->';
+export const DOCMAN_COMMAND_CATALOG_END = '<!-- aops-generated:docman-command-catalog:end -->';
+export const DOCMAN_DISCOVERY_GUIDE_START = '<!-- aops-generated:docman-discovery:start -->';
+export const DOCMAN_DISCOVERY_GUIDE_END = '<!-- aops-generated:docman-discovery:end -->';
+export const CHATV3_COMMAND_CATALOG_START = '<!-- aops-generated:chatv3-command-catalog:start -->';
+export const CHATV3_COMMAND_CATALOG_END = '<!-- aops-generated:chatv3-command-catalog:end -->';
+export const CHATV3_DISCOVERY_GUIDE_START = '<!-- aops-generated:chatv3-discovery:start -->';
+export const CHATV3_DISCOVERY_GUIDE_END = '<!-- aops-generated:chatv3-discovery:end -->';
+export const AGENTSPACE_COMMAND_CATALOG_START = '<!-- aops-generated:agentspace-command-catalog:start -->';
+export const AGENTSPACE_COMMAND_CATALOG_END = '<!-- aops-generated:agentspace-command-catalog:end -->';
+export const AGENTSPACE_DISCOVERY_GUIDE_START = '<!-- aops-generated:agentspace-discovery:start -->';
+export const AGENTSPACE_DISCOVERY_GUIDE_END = '<!-- aops-generated:agentspace-discovery:end -->';
+export const TASKER_COMMAND_CATALOG_START = '<!-- aops-generated:tasker-command-catalog:start -->';
+export const TASKER_COMMAND_CATALOG_END = '<!-- aops-generated:tasker-command-catalog:end -->';
+export const TASKER_DISCOVERY_GUIDE_START = '<!-- aops-generated:tasker-discovery:start -->';
+export const TASKER_DISCOVERY_GUIDE_END = '<!-- aops-generated:tasker-discovery:end -->';
+export const APPENDICES_HEADING = '## Appendices';
+const COMPATIBILITY_COMMAND_TREES = new Map([
+    ['chatv3', 'chat'],
+]);
+const AGENTSPACE_COMMAND_FAMILIES = [
+    'mem',
+    'exp',
+    'project',
+    'playbook',
+    'prompt',
+    'resource',
+    'artifact',
+    'skill',
+    'agent-profile',
+    'activity',
+    'discuss',
+];
+function oneLine(value) {
+    return value.replace(/\s+/gu, ' ').trim();
+}
+function tableCell(value) {
+    return oneLine(value).replace(/\|/gu, '\\|');
+}
+function isHidden(command) {
+    return command._hidden === true;
+}
+function collectCommands(root) {
+    const rootName = root.name();
+    const descriptors = [];
+    const visit = (parentPath, command) => {
+        if (isHidden(command))
+            return;
+        const segments = [...parentPath, command.name()];
+        const commandPath = [rootName, ...segments].join(' ');
+        descriptors.push({
+            path: commandPath,
+            description: oneLine(command.description()),
+            aliases: command.aliases().map(oneLine).filter(Boolean).sort(),
+            depth: segments.length,
+            family: segments[0] ?? command.name(),
+            leaf: command.commands.length === 0,
+            compatibilityOf: COMPATIBILITY_COMMAND_TREES.get(segments[0] ?? ''),
+        });
+        for (const child of [...command.commands].sort((left, right) => left.name().localeCompare(right.name()))) {
+            visit(segments, child);
+        }
+    };
+    for (const command of [...root.commands].sort((left, right) => left.name().localeCompare(right.name()))) {
+        visit([], command);
+    }
+    return descriptors.sort((left, right) => left.path.localeCompare(right.path));
+}
+function commandLabel(command) {
+    const aliases = command.aliases.length > 0 ? ` (aliases: ${command.aliases.join(', ')})` : '';
+    return `\`${command.path}\`${aliases}`;
+}
+function commandPurpose(command) {
+    const description = command.description || `Run \`${command.path} --help\` for the current command contract.`;
+    if (command.depth === 1 && command.compatibilityOf) {
+        return `Compatibility command tree for canonical \`aops ${command.compatibilityOf}\`. ${description}`;
+    }
+    return description;
+}
+export function renderCommandCatalog(root) {
+    const commands = collectCommands(root);
+    const families = commands.filter((command) => command.depth === 1);
+    const nestedByFamily = new Map();
+    for (const command of commands.filter((entry) => entry.depth > 1)) {
+        const familyCommands = nestedByFamily.get(command.family) ?? [];
+        familyCommands.push(command);
+        nestedByFamily.set(command.family, familyCommands);
+    }
+    const lines = [
+        COMMAND_CATALOG_START,
+        '### Generated CLI command catalog',
+        '',
+        '> This section is generated from the public Commander program registered by `buildCommunityProgram()`. Do not edit it by hand; regenerate it with `aops docs user-guide`.',
+        '',
+        '#### Command families',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...families.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+    ];
+    for (const family of families) {
+        const nested = nestedByFamily.get(family.family) ?? [];
+        if (nested.length === 0)
+            continue;
+        lines.push('', `#### \`${root.name()} ${family.family}\` commands`, '');
+        if (family.compatibilityOf) {
+            lines.push(`> Compatibility command tree for canonical \`${root.name()} ${family.compatibilityOf}\`. It is retained for existing automation; prefer \`${root.name()} ${family.compatibilityOf}\` for new workflows.`, '');
+        }
+        lines.push('| Command | Purpose |', '| --- | --- |', ...nested.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`));
+    }
+    lines.push('', COMMAND_CATALOG_END);
+    return `${lines.join('\n')}\n`;
+}
+function findCommand(root, path) {
+    const descriptors = collectCommands(root);
+    const fullPath = [root.name(), ...path].join(' ');
+    const match = descriptors.find((command) => command.path === fullPath);
+    if (!match)
+        throw new Error(`user_guide_command_missing:${fullPath}`);
+    return match;
+}
+export function renderCapabilityDiscoveryGuide(root) {
+    const discoveryCommands = [
+        findCommand(root, ['agent', 'tools']),
+        findCommand(root, ['agent', 'schema']),
+        findCommand(root, ['agent', 'openapi']),
+        findCommand(root, ['agent', 'invoke']),
+    ];
+    const lines = [
+        DISCOVERY_GUIDE_START,
+        '### Generated capability discovery guide',
+        '',
+        '> AOPS does not copy a fixed hosted-tool list into this guide. The server catalog is discovered live, so newly registered domain capabilities appear without rewriting prose.',
+        '',
+        '#### Source-of-truth model',
+        '',
+        '1. **DCM (Domain Capability Manifest)** is the canonical domain capability source.',
+        '2. Host routes, the agent catalog, OpenAPI, JSON Schema, and domain CLI projections are derived views of that capability source.',
+        '3. **HRM (Host Registration Manifest)** tells the host how a domain is registered; it is not a second capability source.',
+        '4. AOPS sugar commands come from the public Commander program and are cataloged separately above.',
+        '',
+        '#### Live discovery commands',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...discoveryCommands.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+        '',
+        'Use the smallest useful read:',
+        '',
+        '```bash',
+        'aops agent tools --domain <domain> --summary --json',
+        'aops agent schema --tool <tool-id> --summary --json',
+        'aops agent openapi --domain <domain> --out ./openapi.json',
+        '```',
+        '',
+        DISCOVERY_GUIDE_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function renderDocmanCommandCatalog(root) {
+    const prefix = `${root.name()} doc`;
+    const commands = collectCommands(root).filter((command) => command.path === prefix || command.path.startsWith(`${prefix} `));
+    if (commands.length === 0)
+        throw new Error(`user_guide_command_missing:${prefix}`);
+    const lines = [
+        DOCMAN_COMMAND_CATALOG_START,
+        '### Generated Docman command catalog',
+        '',
+        '> This appendix is generated from the public `aops doc` Commander registrations. Do not edit it by hand; regenerate it with `aops docs user-guide --guide docman`.',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...commands.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+        '',
+        DOCMAN_COMMAND_CATALOG_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function renderDocmanDiscoveryGuide(root) {
+    const commands = [
+        findCommand(root, ['doc', 'outline', 'get']),
+        findCommand(root, ['doc', 'index', 'build']),
+        findCommand(root, ['doc', 'summary', 'build']),
+        findCommand(root, ['doc', 'search']),
+        findCommand(root, ['doc', 'scope', 'search']),
+        findCommand(root, ['doc', 'answer']),
+        findCommand(root, ['doc', 'source']),
+        findCommand(root, ['doc', 'mirror', 'pull']),
+        findCommand(root, ['agent', 'tools']),
+        findCommand(root, ['agent', 'schema']),
+    ];
+    const lines = [
+        DOCMAN_DISCOVERY_GUIDE_START,
+        '### Generated Docman discovery and retrieval guide',
+        '',
+        '> Docman operations and schemas are discovered from the running server. This appendix keeps the retrieval gates current without copying a fixed hosted-tool inventory into prose.',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...commands.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+        '',
+        'Use the smallest useful read:',
+        '',
+        '```bash',
+        'aops doc search --local --q "<keywords>" --ensure summary --json',
+        'aops doc scope search --project-slug <slug> --q "<keywords>" --json',
+        'aops doc answer --document-version-id <id> --q "<question>" --ensure summary --json',
+        'aops agent tools --domain docman --summary --json',
+        'aops agent schema --tool <docman-tool-id> --summary --json',
+        '```',
+        '',
+        DOCMAN_DISCOVERY_GUIDE_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function renderChatv3CommandCatalog(root) {
+    const prefix = `${root.name()} chat`;
+    const commands = collectCommands(root).filter((command) => command.leaf && command.path.startsWith(`${prefix} `));
+    if (commands.length === 0)
+        throw new Error(`user_guide_command_missing:${prefix}`);
+    const lines = [
+        CHATV3_COMMAND_CATALOG_START,
+        '> This appendix is generated from the public `aops chat` Commander registrations. `aops chatv3` is a compatibility command tree and is not duplicated here. Regenerate with `aops docs user-guide --guide chatv3`.',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...commands.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+        '',
+        CHATV3_COMMAND_CATALOG_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function renderChatv3DiscoveryGuide(root) {
+    const commands = [
+        findCommand(root, ['agent', 'tools']),
+        findCommand(root, ['agent', 'schema']),
+        findCommand(root, ['agent', 'invoke']),
+    ];
+    const lines = [
+        CHATV3_DISCOVERY_GUIDE_START,
+        '> `aops chat` is the convenience CLI, not the complete ChatV3 domain. Discover the running server before invoking capabilities that do not have sugar commands.',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...commands.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+        '',
+        'Use the smallest useful read:',
+        '',
+        '```bash',
+        'aops chat --help',
+        'aops chat channels --json',
+        'aops chat session list --json',
+        'aops chat read --help',
+        'aops chat listen --help',
+        'aops agent tools --domain chatv3 --summary --json',
+        'aops agent schema --tool <chatv3-tool-id> --summary --json',
+        '```',
+        '',
+        CHATV3_DISCOVERY_GUIDE_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function renderAgentspaceCommandCatalog(root) {
+    const commands = collectCommands(root);
+    const rows = AGENTSPACE_COMMAND_FAMILIES.map((familyName) => {
+        const prefix = `${root.name()} ${familyName}`;
+        const family = commands.find((command) => command.path === prefix);
+        if (!family)
+            throw new Error(`user_guide_command_missing:${prefix}`);
+        const leaves = commands.filter((command) => command.leaf && command.path.startsWith(`${prefix} `));
+        if (leaves.length === 0)
+            throw new Error(`user_guide_command_missing:${prefix}:leaf`);
+        const leafLabels = leaves
+            .map((command) => `\`${command.path.slice(prefix.length + 1)}\``)
+            .join(', ');
+        return `| ${commandLabel(family)} | ${tableCell(leafLabels)} | ${tableCell(commandPurpose(family))} |`;
+    });
+    const lines = [
+        AGENTSPACE_COMMAND_CATALOG_START,
+        '### Generated Agentspace command families',
+        '',
+        '> This compact appendix is generated from the public Commander registrations. It groups current leaf commands into eleven owner families instead of copying a large command-by-command or hosted-tool catalog. Regenerate it with `aops docs user-guide --guide agentspace`.',
+        '',
+        '| Family | Registered leaf commands | Purpose |',
+        '| --- | --- | --- |',
+        ...rows,
+        '',
+        AGENTSPACE_COMMAND_CATALOG_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function renderAgentspaceDiscoveryGuide(root) {
+    const commands = [
+        findCommand(root, ['skill', 'search']),
+        findCommand(root, ['skill', 'ask']),
+        findCommand(root, ['agent', 'tools']),
+        findCommand(root, ['agent', 'schema']),
+        findCommand(root, ['agent', 'invoke']),
+    ];
+    const lines = [
+        AGENTSPACE_DISCOVERY_GUIDE_START,
+        '### Generated Agentspace discovery and routing guide',
+        '',
+        '> Sugar commands cover common Agentspace workflows. The running server catalog remains authoritative for hosted operations, so this guide does not freeze tool ids or tool counts.',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...commands.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+        '',
+        'Use the smallest useful read:',
+        '',
+        '```bash',
+        'aops skill ask --q "<need>" --limit 3 --json',
+        'aops agent tools --domain agentspace --q "<capability>" --limit 20 --summary --json',
+        'aops agent schema --tool <agentspace-tool-id> --summary --json',
+        '```',
+        '',
+        '| Need | Specialized route |',
+        '| --- | --- |',
+        '| Encrypted coordination and wake | `aops chat` and the `aops-cli-chat` skill |',
+        '| Structured decision and consensus | `aops discuss` and the `aops-cli-discuss` skill |',
+        '| Tasks, sprints, issues, and review truth | `aops pm` and the `aops-cli-projectman` skill |',
+        '| Versioned documents and retrieval | `aops doc` and the `aops-cli-docman` skill |',
+        '| File snapshots and lineage | `aops agent tools --domain fileman` and the `aops-cli-fileman` skill |',
+        '',
+        AGENTSPACE_DISCOVERY_GUIDE_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function renderTaskerCommandCatalog(root) {
+    const commands = collectCommands(root).filter((command) => command.leaf
+        && (command.path.startsWith(`${root.name()} tasker `) || command.path.startsWith(`${root.name()} runner `)));
+    if (commands.length === 0)
+        throw new Error('user_guide_command_missing:aops tasker-or-runner');
+    const lines = [
+        TASKER_COMMAND_CATALOG_START,
+        '### Generated Tasker and Runner command catalog',
+        '',
+        '> This compact appendix is generated from the public `aops tasker` and `aops runner` Commander registrations. Do not edit it by hand; regenerate it with `aops docs user-guide --guide tasker`.',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...commands.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+        '',
+        TASKER_COMMAND_CATALOG_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function renderTaskerDiscoveryGuide(root) {
+    const commands = [
+        findCommand(root, ['agent', 'tools']),
+        findCommand(root, ['agent', 'schema']),
+        findCommand(root, ['agent', 'invoke']),
+    ];
+    const lines = [
+        TASKER_DISCOVERY_GUIDE_START,
+        '### Generated Tasker capability discovery guide',
+        '',
+        '> Tasker and Runner sugar cover common operator workflows. The running server catalog remains authoritative for the complete hosted capability set, so this guide does not freeze a second tool inventory.',
+        '',
+        '| Command | Purpose |',
+        '| --- | --- |',
+        ...commands.map((command) => `| ${commandLabel(command)} | ${tableCell(commandPurpose(command))} |`),
+        '',
+        'Use the smallest useful read:',
+        '',
+        '```bash',
+        'aops tasker --help',
+        'aops runner --help',
+        'aops agent tools --domain tasker --summary --json',
+        'aops agent schema --tool <tasker-tool-id> --summary --json',
+        '```',
+        '',
+        TASKER_DISCOVERY_GUIDE_END,
+    ];
+    return `${lines.join('\n')}\n`;
+}
+function headingIdentity(line) {
+    const match = /^(#{2,6})\s+(?:\d+(?:\.\d+)*\s+)?(.+?)\s*$/u.exec(line);
+    if (!match)
+        return undefined;
+    return `${match[1]}:${match[2]}`;
+}
+function preserveMaterializedHeadingNumbers(existing, rendered) {
+    const existingHeadings = new Map();
+    for (const line of existing.split('\n')) {
+        const identity = headingIdentity(line);
+        if (identity)
+            existingHeadings.set(identity, line);
+    }
+    const lines = rendered
+        .split('\n')
+        .map((line) => existingHeadings.get(headingIdentity(line) ?? '') ?? line);
+    const existingLines = existing.split('\n');
+    if (existingLines[1] === '' && lines[1] !== '')
+        lines.splice(1, 0, '');
+    const overviewLine = existingLines.find((line) => headingIdentity(line)?.endsWith(':Overview'));
+    const renderedHasOverview = lines.some((line) => headingIdentity(line)?.endsWith(':Overview'));
+    if (overviewLine && !renderedHasOverview) {
+        const firstHeadingIndex = lines.findIndex((line) => headingIdentity(line) !== undefined);
+        if (firstHeadingIndex >= 0)
+            lines.splice(firstHeadingIndex + 1, 0, '', overviewLine);
+    }
+    return lines.join('\n');
+}
+function replaceGeneratedBlock(source, start, end, rendered) {
+    const startIndex = source.indexOf(start);
+    const endIndex = source.indexOf(end);
+    if (startIndex < 0 || endIndex < 0 || endIndex < startIndex) {
+        throw new Error(`user_guide_markers_missing_or_invalid:${start}:${end}`);
+    }
+    if (source.indexOf(start, startIndex + start.length) >= 0 || source.indexOf(end, endIndex + end.length) >= 0) {
+        throw new Error(`user_guide_markers_duplicated:${start}:${end}`);
+    }
+    const existingBlock = source.slice(startIndex, endIndex + end.length);
+    const compatibleRendered = preserveMaterializedHeadingNumbers(existingBlock, rendered);
+    return `${source.slice(0, startIndex)}${compatibleRendered.trimEnd()}${source.slice(endIndex + end.length)}`;
+}
+function findAppendicesIndex(source) {
+    const match = /^## (?:\d+(?:\.\d+)* )?Appendices\s*$/mu.exec(source);
+    return match?.index ?? -1;
+}
+function assertGeneratedSectionsAreAppendices(source, commandMarker, discoveryMarker) {
+    const appendicesIndex = findAppendicesIndex(source);
+    const commandIndex = source.indexOf(commandMarker);
+    const discoveryIndex = source.indexOf(discoveryMarker);
+    if (appendicesIndex < 0) {
+        throw new Error('user_guide_generated_sections_must_be_appendices');
+    }
+    if (commandIndex < 0 || discoveryIndex < 0)
+        return;
+    if (commandIndex < appendicesIndex || discoveryIndex < commandIndex) {
+        throw new Error('user_guide_generated_sections_must_be_appendices');
+    }
+    const nextTopLevelSection = source.indexOf('\n## ', appendicesIndex + APPENDICES_HEADING.length);
+    if (nextTopLevelSection >= 0 && (commandIndex > nextTopLevelSection || discoveryIndex > nextTopLevelSection)) {
+        throw new Error('user_guide_generated_sections_must_be_appendices');
+    }
+}
+export function renderGeneratedUserGuideSections(root) {
+    return `${renderCommandCatalog(root)}\n${renderCapabilityDiscoveryGuide(root)}`;
+}
+export function refreshGeneratedUserGuideSections(source, root) {
+    assertGeneratedSectionsAreAppendices(source, COMMAND_CATALOG_START, DISCOVERY_GUIDE_START);
+    const withCommands = replaceGeneratedBlock(source, COMMAND_CATALOG_START, COMMAND_CATALOG_END, renderCommandCatalog(root));
+    const refreshed = replaceGeneratedBlock(withCommands, DISCOVERY_GUIDE_START, DISCOVERY_GUIDE_END, renderCapabilityDiscoveryGuide(root));
+    return refreshed.endsWith('\n') ? refreshed : `${refreshed}\n`;
+}
+export function renderGeneratedDocmanGuideSections(root) {
+    return `${renderDocmanCommandCatalog(root)}\n${renderDocmanDiscoveryGuide(root)}`;
+}
+export function refreshGeneratedDocmanGuideSections(source, root) {
+    assertGeneratedSectionsAreAppendices(source, DOCMAN_COMMAND_CATALOG_START, DOCMAN_DISCOVERY_GUIDE_START);
+    const withCommands = replaceGeneratedBlock(source, DOCMAN_COMMAND_CATALOG_START, DOCMAN_COMMAND_CATALOG_END, renderDocmanCommandCatalog(root));
+    const refreshed = replaceGeneratedBlock(withCommands, DOCMAN_DISCOVERY_GUIDE_START, DOCMAN_DISCOVERY_GUIDE_END, renderDocmanDiscoveryGuide(root));
+    return refreshed.endsWith('\n') ? refreshed : `${refreshed}\n`;
+}
+export function renderGeneratedChatv3GuideSections(root) {
+    return `${renderChatv3CommandCatalog(root)}\n${renderChatv3DiscoveryGuide(root)}`;
+}
+export function refreshGeneratedChatv3GuideSections(source, root) {
+    assertGeneratedSectionsAreAppendices(source, CHATV3_COMMAND_CATALOG_START, CHATV3_DISCOVERY_GUIDE_START);
+    const withCommands = replaceGeneratedBlock(source, CHATV3_COMMAND_CATALOG_START, CHATV3_COMMAND_CATALOG_END, renderChatv3CommandCatalog(root));
+    const refreshed = replaceGeneratedBlock(withCommands, CHATV3_DISCOVERY_GUIDE_START, CHATV3_DISCOVERY_GUIDE_END, renderChatv3DiscoveryGuide(root));
+    return refreshed.endsWith('\n') ? refreshed : `${refreshed}\n`;
+}
+export function renderGeneratedAgentspaceGuideSections(root) {
+    return `${renderAgentspaceCommandCatalog(root)}\n${renderAgentspaceDiscoveryGuide(root)}`;
+}
+export function refreshGeneratedAgentspaceGuideSections(source, root) {
+    assertGeneratedSectionsAreAppendices(source, AGENTSPACE_COMMAND_CATALOG_START, AGENTSPACE_DISCOVERY_GUIDE_START);
+    const withCommands = replaceGeneratedBlock(source, AGENTSPACE_COMMAND_CATALOG_START, AGENTSPACE_COMMAND_CATALOG_END, renderAgentspaceCommandCatalog(root));
+    const refreshed = replaceGeneratedBlock(withCommands, AGENTSPACE_DISCOVERY_GUIDE_START, AGENTSPACE_DISCOVERY_GUIDE_END, renderAgentspaceDiscoveryGuide(root));
+    return refreshed.endsWith('\n') ? refreshed : `${refreshed}\n`;
+}
+export function renderGeneratedTaskerGuideSections(root) {
+    return `${renderTaskerCommandCatalog(root)}\n${renderTaskerDiscoveryGuide(root)}`;
+}
+export function refreshGeneratedTaskerGuideSections(source, root) {
+    assertGeneratedSectionsAreAppendices(source, TASKER_COMMAND_CATALOG_START, TASKER_DISCOVERY_GUIDE_START);
+    const withCommands = replaceGeneratedBlock(source, TASKER_COMMAND_CATALOG_START, TASKER_COMMAND_CATALOG_END, renderTaskerCommandCatalog(root));
+    const refreshed = replaceGeneratedBlock(withCommands, TASKER_DISCOVERY_GUIDE_START, TASKER_DISCOVERY_GUIDE_END, renderTaskerDiscoveryGuide(root));
+    return refreshed.endsWith('\n') ? refreshed : `${refreshed}\n`;
+}

package/dist/main.js

@@ -39,6 +39,10 @@ import { makeTargetCommand } from './commands/target.js';
 import { makeVersionCommand } from './commands/version.js';
 import { makeCodexCommand } from './commands/codex.js';
 import { makeGlobalUpdateCommand } from './commands/global-update.js';
+import { makeDocsCommand } from './commands/docs.js';
+import { makeLoopCommand } from './commands/loop.js';
+import { makeTaskerCommand } from './commands/tasker.js';
+import { makeRunnerCommand } from './commands/runner.js';
 import { launchBundledTui, shouldLaunchBundledTui } from './lib/tui-launcher.js';
 import { CommunityDiagnosticError, formatCommunityDiagnostic, } from './lib/community-diagnostic.js';
 import { resolveCliApiBaseUrl } from './utils/api.js';
@@ -56,7 +60,7 @@ function renderTrustedLocalLicenseStatus(command) {
         profile: 'trusted-local',
         commercialAvailable: false,
         southRequired: false,
-        builtInDomains: ['agentspace', 'chatv3', 'docman', 'projectman', 'sys'],
+        builtInDomains: ['agentspace', 'chatv3', 'docman', 'projectman', 'sys', 'tasker'],
         next: 'South-backed licensing and external domains are not available in this public profile.',
     };
     const json = command.optsWithGlobals().json === true;
@@ -157,9 +161,13 @@ export function buildCommunityProgram() {
     program.addCommand(makeVersionCommand());
     program.addCommand(makeCodexCommand());
     program.addCommand(makeGlobalUpdateCommand());
+    program.addCommand(makeDocsCommand(() => program));
+    program.addCommand(makeLoopCommand());
+    program.addCommand(makeTaskerCommand());
+    program.addCommand(makeRunnerCommand());
     program.addHelpText('after', `
 AOPS Community is a single-user, self-hosted/local-trusted distribution.
-Canonical writes go to the local AOPS server; .aops/** remains a read-only cache.
+Canonical writes go to the local AOPS server; generated mirrors and views live under the read-only .aops-cache/** tree.
 
 Quick checks:
   aops setup ai

package/dist/seeds/agents-md.js

@@ -3,7 +3,7 @@ export const AOPS_AGENTS_MD_TEMPLATE_SEEDS = [
         slug: 'aops-collaborative-startup',
         title: 'AOPS Collaborative Startup',
         description: 'Default solo-first session starter; boots the aops-collaborative-work skill (collaboration and chat are operator-opt-in).',
-        mirrorPath: '.aops/hosted/prompts/aops-collaborative-startup.md',
+        mirrorPath: '.aops-cache/hosted/prompts/aops-collaborative-startup.md',
         promptRef: 'prompt:aops-collaborative-startup',
         tags: ['default', 'starter', 'solo-first', 'coordination-optional'],
         snippet: [
@@ -22,7 +22,7 @@ export const AOPS_AGENTS_MD_TEMPLATE_SEEDS = [
         slug: 'aops-task-execution-template',
         title: 'AOPS Task Execution Template',
         description: 'Operator-fillable, PM-backed generic execution checklist template.',
-        mirrorPath: '.aops/hosted/prompts/aops-task-execution-template.md',
+        mirrorPath: '.aops-cache/hosted/prompts/aops-task-execution-template.md',
         promptRef: 'prompt:aops-task-execution-template',
         tags: ['pm', 'closeout', 'template'],
         snippet: [
@@ -37,7 +37,7 @@ export const AOPS_AGENTS_MD_TEMPLATE_SEEDS = [
         slug: 'aops-cli-discuss',
         title: 'AOPS Discuss / Decision Protocol',
         description: 'Standalone discuss decision/consensus discipline; coordination via aops-cli-chat, review via aops-cli-projectman; canonical mechanics in the aops-cli-discuss hosted skill.',
-        mirrorPath: '.aops/hosted/skills/aops-cli-discuss.md',
+        mirrorPath: '.aops-cache/hosted/skills/aops-cli-discuss.md',
         promptRef: 'skill:aops-cli-discuss',
         tags: ['discuss', 'decision', 'consensus'],
         snippet: [

package/dist/utils/agents-md.js

@@ -236,7 +236,7 @@ export async function updateAgentsMdFile(options = {}) {
         throw new Error('This command updates AGENTS.md. Retry with --apply or use --preview.');
     }
     if (options.preview === true && options.syncHosted === true) {
-        throw new Error('--sync-hosted mutates .aops/hosted mirrors. Use `aops-cli agents-md update --sync-hosted --apply`.');
+        throw new Error('--sync-hosted mutates .aops-cache/hosted mirrors. Use `aops-cli agents-md update --sync-hosted --apply`.');
     }
     const target = resolveAgentsMdTarget(options.root);
     const selectedTemplates = selectAgentsMdTemplates(options);

package/dist/utils/guide-paths.js

@@ -4,26 +4,26 @@ import { fileURLToPath } from 'node:url';
 const PACKAGE_ROOT_URL = new URL('../../', import.meta.url);
 const GUIDE_TARGETS = {
     operator: {
-        mirrorPath: path.join('.aops', 'docman', 'aops-guides', 'aops-cli-user-guide.md'),
+        mirrorPath: path.join('.aops-cache', 'docman', 'aops-guides', 'aops-cli-user-guide.md'),
     },
     agentspace: {
-        mirrorPath: path.join('.aops', 'docman', 'domain-guides', 'agentspace-user-guide.md'),
+        mirrorPath: path.join('.aops-cache', 'docman', 'domain-guides', 'agentspace-user-guide.md'),
     },
     projectman: {
-        mirrorPath: path.join('.aops', 'docman', 'domain-guides', 'projectman-user-guide.md'),
+        mirrorPath: path.join('.aops-cache', 'docman', 'domain-guides', 'projectman-user-guide.md'),
     },
     docman: {
-        mirrorPath: path.join('.aops', 'docman', 'domain-guides', 'docman-user-guide.md'),
+        mirrorPath: path.join('.aops-cache', 'docman', 'domain-guides', 'docman-user-guide.md'),
     },
     fileman: {
-        mirrorPath: path.join('.aops', 'docman', 'domain-guides', 'fileman-user-guide.md'),
+        mirrorPath: path.join('.aops-cache', 'docman', 'domain-guides', 'fileman-user-guide.md'),
     },
     tasker: {
-        mirrorPath: path.join('.aops', 'docman', 'domain-guides', 'tasker-user-guide.md'),
+        mirrorPath: path.join('.aops-cache', 'docman', 'domain-guides', 'tasker-user-guide.md'),
     },
     agentAssets: {
         fallbackPath: './docs/agent-assets-bootstrap.md',
-        mirrorPath: path.join('.aops', 'docman', 'aops-guides', 'aops-agent-assets-bootstrap.md'),
+        mirrorPath: path.join('.aops-cache', 'docman', 'aops-guides', 'aops-agent-assets-bootstrap.md'),
     },
 };
 function resolvePackagePath(relativePath) {

package/dist/utils/hosted-workspace.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { normalizeNonEmpty } from './command.js';
 import { parseFrontmatterDocument, renderFrontmatterDocument } from './memory-workspace.js';
+import { resolveAopsCacheRoot } from './repo-first-storage.js';
 import { writeFileWithRetry } from './transient-fs.js';
 function slugify(value) {
     return value
@@ -98,7 +99,7 @@ function hostedProjectKeyFromFrontmatter(frontmatter) {
     });
 }
 export function resolveHostedWorkspacePaths(repoRoot) {
-    const root = path.join(repoRoot, '.aops', 'hosted');
+    const root = path.join(resolveAopsCacheRoot(repoRoot), 'hosted');
     return {
         root,
         skillsRoot: path.join(root, 'skills'),

package/dist/utils/repo-first-storage.js

@@ -1,13 +1,38 @@
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import { normalizeNonEmpty } from './command.js';
+import { writeFileWithRetry } from './transient-fs.js';
+export const AOPS_CONTROL_DIR = '.aops';
+export const AOPS_CACHE_DIR = '.aops-cache';
+export const AOPS_PRIVATE_GITIGNORE_ENTRIES = [`/${AOPS_CONTROL_DIR}/`, `/${AOPS_CACHE_DIR}/`];
 export function resolveRepoFirstWorkspaceRoot(context) {
     const repoRoot = typeof context === 'string' ? context : context.repoRoot;
     const localRoot = typeof context === 'string' ? undefined : normalizeNonEmpty(context.localRoot);
     if (!localRoot)
-        return path.join(repoRoot, '.aops');
+        return path.join(repoRoot, AOPS_CACHE_DIR);
     return path.isAbsolute(localRoot) ? localRoot : path.join(repoRoot, localRoot);
 }
 export function resolveRepoFirstWorkspaceRelativeRoot(context) {
     const repoRoot = typeof context === 'string' ? context : context.repoRoot;
     return path.relative(repoRoot, resolveRepoFirstWorkspaceRoot(context)).split(path.sep).join('/') || '.';
 }
+export function resolveAopsCacheRoot(repoRoot) {
+    return path.join(repoRoot, AOPS_CACHE_DIR);
+}
+export async function ensureAopsPrivatePathsIgnored(repoRoot) {
+    const gitignorePath = path.join(repoRoot, '.gitignore');
+    let content = '';
+    try {
+        content = await fs.readFile(gitignorePath, 'utf8');
+    }
+    catch {
+        content = '';
+    }
+    const lines = new Set(content.split(/\r?\n/));
+    const missing = AOPS_PRIVATE_GITIGNORE_ENTRIES.filter((entry) => !lines.has(entry));
+    if (missing.length === 0)
+        return;
+    const prefix = content.trimEnd();
+    const next = `${prefix}${prefix ? '\n' : ''}${missing.join('\n')}\n`;
+    await writeFileWithRetry(gitignorePath, next, 'utf8');
+}