@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/knowledge.js

@@ -0,0 +1,874 @@
+import { addCompactListReadFlags, appendCompactListReadQuery } from "../compact-list-flags.js";
+import { emitCliFailure } from "../cli-output.js";
+import { parseJsonObject, readPositiveInt } from "../cli-values.js";
+import { KNOWLEDGE_SYNC_DEFAULT_TTL_MINUTES, buildContextResolveBody, isUuid, knowledgeMirrorTargetFor, readCsvOption, readNonNegativeNumber, readPositiveNumber, resolveKnowledgeMirrorTarget, runKnowledgeMirrorSync, runKnowledgeMirrorSyncAll } from "../command-support.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { loadCredentials } from "../credentials.js";
+import { requestOxygen } from "../http-client.js";
+import { acquireMirrorLock, clearConflictFiles, listConflictFiles, listLocalMirrors, localPageSha256, markMirrorStale, mirrorExists, pageFilePath, planMirrorPush, purgeMirror, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, writeMirrorState } from "../knowledge-mirror.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { knowledgeIndexReadContract, knowledgePageReadContract } from "@oxygen/shared/contracts/knowledge-content-reads";
+import { knowledgeProposalWindowContract } from "@oxygen/shared/contracts/knowledge-proposal-reads";
+import { KNOWLEDGE_BOOTSTRAP_MAX_CREDITS } from "@oxygen/shared/knowledge-bootstrap";
+import { KNOWLEDGE_PAGE_TYPES } from "@oxygen/shared/knowledge-constants";
+import { parseKnowledgePageMarkdown } from "@oxygen/shared/knowledge-markdown";
+import { Command } from "commander";
+import { existsSync, readFileSync } from "node:fs";
+// The wiki index counts the whole wiki even when the page list is a window, so
+// name both numbers: "200 of 512 pages" is honest, "200 pages" is not.
+function writeKnowledgeIndexCapNotice(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const index = data.index;
+    if (!index || typeof index !== "object" || Array.isArray(index))
+        return;
+    const block = index;
+    if (block.capped !== true)
+        return;
+    const counts = block.counts;
+    const returned = typeof counts?.returned === "number" ? counts.returned : null;
+    const total = typeof counts?.total === "number" ? counts.total : null;
+    const shown = returned === null
+        ? "a window of this wiki's pages"
+        : `${returned}${total === null ? "" : ` of ${total}`} page(s)`;
+    process.stderr.write(`note: listing ${shown}, most recently updated first; counts cover the whole wiki — raise --limit (max 1000) or pass --all.\n`);
+}
+function buildKnowledgePageUpsertBody(options) {
+    const tags = readCsvOption(options.tags);
+    const expectedRevision = options.expectedRevision === undefined ? undefined : Number(options.expectedRevision);
+    if (expectedRevision !== undefined && (!options.expectedRevision?.trim() || !Number.isInteger(expectedRevision) || expectedRevision < 0)) {
+        throw new OxygenError("invalid_request", "--expected-revision must be a nonnegative integer.", { exitCode: 2 });
+    }
+    const folder = readOption(options.folder);
+    return {
+        ...(folder ? { folderId: folder === "root" ? null : folder } : {}),
+        ...(options.createOnly ? { createOnly: true } : {}),
+        ...(readOption(options.slug) ? { slug: readOption(options.slug) } : {}),
+        ...(readOption(options.id) ? { id: readOption(options.id) } : {}),
+        ...(readOption(options.type) ? { type: readOption(options.type) } : {}),
+        ...(readOption(options.title) ? { title: readOption(options.title) } : {}),
+        ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(readOption(options.summary) ? { summary: readOption(options.summary) } : {}),
+        ...(readOption(options.body) ? { body: readOption(options.body) } : {}),
+        ...(options.dataJson ? { data: parseJsonObject(options.dataJson) } : {}),
+        ...(expectedRevision !== undefined ? { expected_revision: expectedRevision } : {}),
+        ...(options.approved ? { approved: true } : {}),
+    };
+}
+function buildKnowledgePageListBody(options) {
+    const tags = readCsvOption(options.tags);
+    const limit = readPositiveInt(options.limit);
+    return {
+        ...(readOption(options.type) ? { type: readOption(options.type) } : {}),
+        ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+    };
+}
+function knowledgeReadPath(path, parameters) {
+    const query = new URLSearchParams(Object.entries(parameters)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, String(value)]));
+    return query.size ? `${path}?${query}` : path;
+}
+function buildKnowledgeGraphBody(options) {
+    const maxNodes = readPositiveInt(options.maxNodes);
+    const center = readOption(options.center);
+    const depth = readPositiveInt(options.depth);
+    return {
+        ...(maxNodes !== undefined ? { max_nodes: maxNodes } : {}),
+        ...(center ? { center } : {}),
+        ...(depth !== undefined ? { depth } : {}),
+    };
+}
+function buildKnowledgeLogListBody(options) {
+    const limit = readPositiveInt(options.limit);
+    return {
+        ...(readOption(options.cursor) ? { cursor: readOption(options.cursor) } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+    };
+}
+function buildKnowledgeLogAppendBody(options) {
+    return {
+        ...(readOption(options.event) ? { event: readOption(options.event) } : {}),
+        ...(readOption(options.slug) ? { slug: readOption(options.slug) } : {}),
+        ...(readOption(options.summary) ? { summary: readOption(options.summary) } : {}),
+        ...(options.dataJson ? { data: parseJsonObject(options.dataJson) } : {}),
+    };
+}
+function buildKnowledgeSearchBody(query, options) {
+    const tags = readCsvOption(options.tags);
+    const limit = readPositiveInt(options.limit);
+    return {
+        query: query.trim(),
+        ...(readOption(options.type) ? { type: readOption(options.type) } : {}),
+        ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+    };
+}
+// Post-write staleness hook for `knowledge page upsert|pin|archive`: clearing
+// last_sync_at makes the next `knowledge sync --if-stale` run for real. A byte-
+// perfect single-page refresh needs a dedicated sync endpoint (deferred); the
+// hook is deliberately local-only — no whoami round-trip — and best-effort.
+async function markKnowledgeMirrorStaleAfterWrite() {
+    try {
+        const credentials = await loadCredentials().catch(() => null);
+        if (!credentials)
+            return;
+        const cached = credentials.activeOrganization ?? credentials.identity?.organization ?? null;
+        const ref = process.env.OXYGEN_ORG?.trim() || cached?.id || cached?.slug;
+        if (!ref)
+            return;
+        // Resolve the ref to an org id offline — the hook stays network-free so a page
+        // write is never slowed by a whoami round-trip. A non-cached slug override
+        // (`--org <slug>` for an org we haven't cached) can't be mapped without a
+        // network call, so that mirror isn't stale-marked here; the 15-min --if-stale
+        // TTL and `knowledge sync --all` are the safety net.
+        let orgId = null;
+        if (cached && (ref === cached.id || ref === cached.slug))
+            orgId = cached.id;
+        else if (isUuid(ref))
+            orgId = ref;
+        if (!orgId)
+            return;
+        const target = knowledgeMirrorTargetFor(credentials.apiUrl, orgId);
+        if (mirrorExists(target.dir))
+            markMirrorStale(target.dir);
+    }
+    catch {
+        // A broken local mirror must never fail the page write itself.
+    }
+}
+// One page's push: parse the local file, guard identity, upsert with the manifest
+// revision as the optimistic-concurrency base, and translate the two expected
+// gate outcomes (approval proposal, revision conflict) into statuses.
+async function pushOneMirrorPage(dir, state, candidate) {
+    const { slug, kind, record } = candidate;
+    let contents;
+    try {
+        contents = readFileSync(pageFilePath(dir, slug), "utf8");
+    }
+    catch {
+        return { slug, kind, status: "skipped", reason: "file_unreadable" };
+    }
+    const parsed = parseKnowledgePageMarkdown(contents);
+    if (record && parsed.id && parsed.id !== record.id) {
+        return { slug, kind, status: "skipped", reason: "id_mismatch_with_manifest" };
+    }
+    if (parsed.slug && parsed.slug !== slug) {
+        return { slug, kind, status: "skipped", reason: "frontmatter_slug_differs_from_filename" };
+    }
+    const body = {
+        slug,
+        body: parsed.body,
+        ...(parsed.title ? { title: parsed.title } : {}),
+        ...(parsed.type ? { type: parsed.type } : {}),
+        ...(parsed.status ? { status: parsed.status } : {}),
+        ...(parsed.tags ? { tags: parsed.tags } : {}),
+        // A frontmatter block owns the summary line: pushing an emptied summary
+        // clears it server-side; a plain new file leaves summary untouched.
+        ...(parsed.hasFrontmatter ? { summary: parsed.summary } : {}),
+        ...(record ? { expected_revision: record.revision } : {}),
+    };
+    try {
+        const data = await requestOxygen("/api/cli/knowledge/pages/upsert", { method: "POST", body });
+        const page = data.page ?? {};
+        if (typeof page.id === "string" && typeof page.revision === "number") {
+            // Record the pushed bytes as the manifest truth so the follow-up sync
+            // overwrites this file with the server rendering instead of quarantining
+            // the very edit we just pushed.
+            const localSha = localPageSha256(dir, slug);
+            if (localSha) {
+                state.pages[slug] = { id: page.id, revision: page.revision, content_sha256: localSha };
+            }
+        }
+        return {
+            slug,
+            kind,
+            status: "pushed",
+            ...(typeof page.revision === "number" ? { revision: page.revision } : {}),
+        };
+    }
+    catch (error) {
+        if (error instanceof OxygenError && error.code === "knowledge_approval_required") {
+            const details = (error.details ?? {});
+            return {
+                slug,
+                kind,
+                status: "proposal_created",
+                // The API sends snake_case details; camelCase never matched, so push hid the proposal.
+                ...(typeof details.proposal_id === "string" ? { proposal_id: details.proposal_id } : {}),
+                ...(typeof details.proposal_slug === "string" ? { proposal_slug: details.proposal_slug } : {}),
+                ...(typeof details.proposal_web_url === "string" ? { proposal_web_url: details.proposal_web_url } : {}),
+                reason: typeof details.reason === "string" ? details.reason : "sensitive_page",
+            };
+        }
+        if (error instanceof OxygenError && error.code === "knowledge_page_conflict") {
+            return { slug, kind, status: "conflict", reason: "revision_moved_run_knowledge_sync_first" };
+        }
+        if (error instanceof OxygenError) {
+            return { slug, kind, status: "failed", reason: error.code };
+        }
+        throw error;
+    }
+}
+// `oxygen knowledge push` — the write half of the local mirror: locally edited
+// (dirty) and brand-new mirror files upsert back to the workspace wiki through
+// the same gate as every other write surface, then a delta sync converges the
+// mirror onto the server rendering. This is what lets a local agent (Claude
+// Code, Codex) work the wiki as plain markdown files.
+async function runKnowledgeMirrorPush(options) {
+    const target = await resolveKnowledgeMirrorTarget();
+    const state = readMirrorState(target.dir);
+    if (!state) {
+        throw new OxygenError("knowledge_mirror_missing", "No local knowledge mirror exists for this organization yet. Run `oxygen knowledge sync` first.", {
+            details: { mirror_path: target.dir },
+            exitCode: 1,
+        });
+    }
+    const plan = planMirrorPush(target.dir, state);
+    if (options.dryRun) {
+        return {
+            dry_run: true,
+            candidates: plan.candidates.map(({ slug, kind, record }) => ({
+                slug,
+                kind,
+                ...(record ? { base_revision: record.revision } : {}),
+            })),
+            skipped: plan.skipped,
+            mirror_path: target.dir,
+            web_url: target.webUrl,
+        };
+    }
+    // Hold the mirror lock through the push phase so a concurrent sync can't
+    // rewrite files or the manifest mid-push; released before the convergence
+    // sync below, which takes the lock itself.
+    if (!acquireMirrorLock(target.dir)) {
+        throw new OxygenError("knowledge_sync_locked", "Another knowledge sync is running for this mirror. Retry shortly; a crashed sync's lock self-clears after 10 minutes.", {
+            details: { mirror_path: target.dir },
+            exitCode: 1,
+        });
+    }
+    const outcomes = [];
+    let pushedCount = 0;
+    try {
+        for (const candidate of plan.candidates) {
+            outcomes.push(await pushOneMirrorPage(target.dir, state, candidate));
+        }
+        pushedCount = outcomes.filter((outcome) => outcome.status === "pushed").length;
+        if (pushedCount > 0) {
+            writeMirrorState(target.dir, state);
+        }
+    }
+    finally {
+        releaseMirrorLock(target.dir);
+    }
+    // Converge: pull the server's rendering of everything just pushed (plus any
+    // proposal draft pages the gate filed) so local bytes match the server again.
+    let syncedAfter = false;
+    if (pushedCount > 0 || outcomes.some((outcome) => outcome.status === "proposal_created")) {
+        await runKnowledgeMirrorSync({});
+        syncedAfter = true;
+    }
+    return {
+        pushed: pushedCount,
+        proposals: outcomes.filter((outcome) => outcome.status === "proposal_created"),
+        conflicts: outcomes.filter((outcome) => outcome.status === "conflict"),
+        failures: outcomes.filter((outcome) => outcome.status === "failed"),
+        skipped: [
+            ...plan.skipped,
+            ...outcomes
+                .filter((outcome) => outcome.status === "skipped")
+                .map(({ slug, reason }) => ({ file: `${slug}.md`, reason: reason ?? "skipped" })),
+        ],
+        outcomes,
+        synced_after: syncedAfter,
+        mirror_path: target.dir,
+        web_url: target.webUrl,
+    };
+}
+async function runKnowledgeMirrorStatus(options) {
+    const target = await resolveKnowledgeMirrorTarget();
+    const clearedConflicts = options.clearConflicts ? clearConflictFiles(target.dir) : undefined;
+    const state = readMirrorState(target.dir);
+    const conflicts = listConflictFiles(target.dir);
+    return {
+        mirror_path: target.dir,
+        exists: mirrorExists(target.dir),
+        pages_total: state ? Object.keys(state.pages).length : 0,
+        last_sync_at: state?.last_sync_at ?? null,
+        cursor: state?.cursor ?? null,
+        conflicts,
+        conflict_count: conflicts.length,
+        ...(clearedConflicts !== undefined ? { cleared_conflicts: clearedConflicts } : {}),
+        web_url: target.webUrl,
+    };
+}
+// `knowledge status --all` — freshness report across every locally mirrored
+// workspace for the active API host. Pure filesystem read (no network): enumerate
+// the org-id mirror dirs, read each `MirrorState`, and flag any whose last sync is
+// older than the default TTL. Slugs are cross-referenced from the cached active
+// org only (offline); other orgs report `org_id` alone.
+async function runKnowledgeMirrorStatusAll() {
+    const credentials = await loadCredentials();
+    if (!credentials) {
+        throw new OxygenError("not_logged_in", "Run `oxygen login` before using CLI commands.", { exitCode: 1 });
+    }
+    const apiHost = new URL(credentials.apiUrl).host;
+    const orgIds = listLocalMirrors({ configDir: resolveDefaultConfigDir(), apiHost });
+    const cached = credentials.activeOrganization ?? credentials.identity?.organization ?? null;
+    const ttlMs = KNOWLEDGE_SYNC_DEFAULT_TTL_MINUTES * 60_000;
+    const mirrors = orgIds.map((orgId) => {
+        const target = knowledgeMirrorTargetFor(credentials.apiUrl, orgId);
+        const state = readMirrorState(target.dir);
+        const conflicts = listConflictFiles(target.dir);
+        const lastSyncMs = state?.last_sync_at ? Date.parse(state.last_sync_at) : Number.NaN;
+        const stale = !Number.isFinite(lastSyncMs) || Date.now() - lastSyncMs >= ttlMs;
+        return {
+            org_id: orgId,
+            ...(cached && cached.id === orgId ? { slug: cached.slug ?? null } : {}),
+            mirror_path: target.dir,
+            exists: mirrorExists(target.dir),
+            pages_total: state ? Object.keys(state.pages).length : 0,
+            last_sync_at: state?.last_sync_at ?? null,
+            stale,
+            conflict_count: conflicts.length,
+            web_url: target.webUrl,
+        };
+    });
+    return {
+        api_host: apiHost,
+        count: mirrors.length,
+        mirrors,
+        web_url: `${credentials.apiUrl.replace(/\/$/, "")}/knowledge`,
+    };
+}
+async function runKnowledgeMirrorPurge() {
+    const target = await resolveKnowledgeMirrorTarget();
+    const existed = existsSync(target.dir);
+    purgeMirror(target.dir);
+    return { purged: existed, mirror_path: target.dir, web_url: target.webUrl };
+}
+// `--print-path` emits the bare directory path (for shell substitution and
+// editor tooling), not a JSON envelope — errors still use the failure envelope.
+async function handleKnowledgeMirrorPrintPathAction() {
+    try {
+        const target = await resolveKnowledgeMirrorTarget();
+        process.stdout.write(`${target.dir}\n`);
+    }
+    catch (error) {
+        emitCliFailure("knowledge status", error);
+    }
+}
+// Knowledge page routes accept either a UUID (`id`) or a slug (`slug`); split
+// the single CLI argument the same way the templates commands do.
+function knowledgePageRefBody(slugOrId) {
+    return isUuid(slugOrId) ? { id: slugOrId } : { slug: slugOrId };
+}
+function knowledgeProposalRefBody(idOrSlug) {
+    return isUuid(idOrSlug) ? { proposal_id: idOrSlug } : { slug: idOrSlug };
+}
+export function registerKnowledgeFamily(program, handleAsyncAction) {
+    // `knowledge bootstrap` is declared here, not inline in the group chain,
+    // because it is a command that both ACTS and owns a subcommand, and both
+    // levels take --json. Commander resolves a repeated option to the outer
+    // command, so `knowledge bootstrap status --json` sets the flag on THIS
+    // command, not on `status` — the same collision the `commands` group above
+    // handles. The named reference lets `status` read the parent's flag back.
+    const knowledgeBootstrapCommand = new Command("bootstrap")
+        .description(`Check saved company research with bootstrap status, or preview a manual company-research pass. Manual research uses direct LinkedIn company enrichment and website reads, saving company facts, a cited wiki note, and separate inferred GTM hypotheses. A bare call previews this manual pass for free; execution is customer-funded and requires --live plus --max-credits (hard cap ${KNOWLEDGE_BOOTSTRAP_MAX_CREDITS}). Automatic signup research is a separate platform-funded pass, runs once under the consent recorded at workspace creation, and may also research the creator. Check status before spending; an existing marker blocks a repeat unless --force re-arms it.`)
+        .option("--domain <domain>", "Company domain to research. Defaults to the recorded workspace domain; if none is available, the preview asks for one.")
+        .option("--linkedin <url>", "Optional company LinkedIn URL to use for the direct lookup. The returned company website must still match the domain.")
+        .option("--live", "Authorize this manual run to spend and write. Requires --max-credits. Without it the command previews and nothing is billed.")
+        .option("--approved", "Same as --live. Accepted because the global help footer names --approved as the way to authorize a credit-spending command.")
+        .option("--max-credits <credits>", `Hard credit ceiling for the whole pass. Required with --live, and clamped server-side to ${KNOWLEDGE_BOOTSTRAP_MAX_CREDITS}.`)
+        .option("--force", "Re-arm past an existing once-ever marker, the one deliberate way to research the same workspace twice. Without --live it only previews the re-arm for free: nothing is cleared or written. With --live it replaces the marker with a new pass and spends again.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge bootstrap", options, () => {
+            const parameters = {
+                mode: options.live || options.approved ? "live" : "dry_run",
+                ...(readOption(options.domain) ? { domain: readOption(options.domain) } : {}),
+                ...(readOption(options.linkedin) ? { linkedin_url: readOption(options.linkedin) } : {}),
+                ...(readPositiveNumber(options.maxCredits) !== undefined
+                    ? { max_credits: readPositiveNumber(options.maxCredits) }
+                    : {}),
+                ...(options.force ? { force: true } : {}),
+            };
+            return parameters.mode === "live"
+                ? requestOxygen("/api/cli/knowledge/bootstrap", { method: "POST", body: parameters })
+                : requestOxygen(knowledgeReadPath("/api/cli/knowledge/bootstrap", parameters));
+        });
+    })
+        .addCommand(new Command("status")
+        .description("Report the once-ever bootstrap marker for this workspace: status (queued, running, completed, partial, skipped, failed, or never attempted), when it ran, its system run id, the credits it actually spent, the domain researched, the reason it stopped, and the pages it wrote. Free, reads only, and the honest way to find out whether the automatic pass already happened before you spend on a manual one.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        // Commander hands a repeated --json to the outer command, so read the
+        // parent's flag back before deciding the output shape. Without this a
+        // machine caller asking for an envelope silently gets bare JSON.
+        const outputOptions = {
+            ...options,
+            json: options.json || Boolean(knowledgeBootstrapCommand.opts().json),
+        };
+        await handleAsyncAction("knowledge bootstrap status", outputOptions, () => requestOxygen("/api/cli/knowledge/bootstrap?status=true"));
+    }));
+    program
+        .command("knowledge")
+        .description("Company knowledge wiki: slug-addressed pages, a [[wikilink]] graph, and a decision log.")
+        .addCommand(new Command("folders")
+        .description("Browse, create, and move nested folders for knowledge pages; slugs and wikilinks stay stable.")
+        .addCommand(addCompactListReadFlags(new Command("list")
+        .description("List workspace folders and page locations, including empty folders. Read-only, 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options, command) => {
+        await handleAsyncAction("knowledge folders list", options, () => {
+            const params = new URLSearchParams();
+            appendCompactListReadQuery(params, command, "folders");
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/knowledge/folders${qs}`);
+        });
+    }), "folders"))
+        .addCommand(new Command("create")
+        .description("Create a persistent knowledge folder, optionally inside another folder.")
+        .requiredOption("--name <name>", "Folder name.")
+        .option("--parent <folder_id>", "Parent folder UUID from knowledge folders list. Omit for root.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge folders create", options, () => requestOxygen("/api/cli/knowledge/folders/create", {
+            method: "POST",
+            body: {
+                name: options.name,
+                ...(readOption(options.parent) ? { parentId: readOption(options.parent) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("move")
+        .description("Move a folder and its contents to another folder or the workspace root.")
+        .argument("<id>", "Folder UUID from knowledge folders list.")
+        .requiredOption("--parent <folder_id|root>", "Destination folder UUID, or root.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("knowledge folders move", options, () => requestOxygen("/api/cli/knowledge/folders/move", {
+            method: "POST",
+            body: { id, parentId: options.parent === "root" ? null : options.parent },
+        }));
+    })))
+        .addCommand(new Command("page")
+        .description("Knowledge wiki pages (slug-addressed, revision-guarded).")
+        .addCommand(new Command("upsert")
+        .description("Create or update a knowledge wiki page. Free internal write; canonical edits require proposal approval.")
+        .option("--slug <slug>", "Stable page key. Omit to derive from title; an existing slug updates unless --create-only is set.")
+        .option("--folder <folder_id>", "Folder UUID, or root to clear placement; omit to preserve. Moving creates a revision and changes data.knowledge_folder_id.")
+        .option("--create-only", "Fail if the page already exists instead of updating it.")
+        .option("--id <page_id>", "Existing page UUID to update. For a new file, omit and use --create-only.")
+        .option("--type <type>", `Page type: ${KNOWLEDGE_PAGE_TYPES.join(", ")}. voice, brand and positioning are canonical copy once pinned. Defaults to other on create.`)
+        .option("--title <title>", "Page title. Required on create.")
+        .option("--status <status>", "draft, active, or archived. Restore with draft and --expected-revision; omit --body to retain content.")
+        .option("--tags <csv>", "Comma-separated page tags.")
+        .option("--summary <text>", "Short page summary.")
+        .option("--body <text>", "Page body (Markdown, supports [[wikilinks]]).")
+        .option("--data-json <json>", "Flexible JSON object for structured page data.")
+        .option("--expected-revision <n>", "Fail the write if the current page revision differs (optimistic concurrency guard).")
+        .option("--approved", "Accepted for compatibility but never honored for canonical live copy: a gated edit always files a proposal - approve it with `oxygen knowledge proposals approve <id>`.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge page upsert", options, async () => {
+            const data = await requestOxygen("/api/cli/knowledge/pages/upsert", {
+                method: "POST",
+                body: buildKnowledgePageUpsertBody(options),
+            });
+            await markKnowledgeMirrorStaleAfterWrite();
+            return data;
+        });
+    }))
+        .addCommand(addContractFlags(new Command("get")
+        .description("Read one knowledge wiki page by slug or UUID. Use --view sources for its evidence ledger or --view full for content, links and sources. Read-only, 0 credits.")
+        .argument("<slug_or_id>", "Page slug or UUID.")
+        .option("--json", "Print a JSON envelope."), knowledgePageReadContract, { slug: { omit: true }, id: { omit: true } })
+        .action(async (slugOrId, options) => {
+        await handleAsyncAction("knowledge page get", options, () => requestOxygen(`/api/cli/knowledge/pages/get?${new URLSearchParams(Object.entries({ slug: slugOrId, ...readContractFlags(options, knowledgePageReadContract, { slug: { omit: true }, id: { omit: true } }) }).map(([key, value]) => [key, String(value)]))}`));
+    }))
+        .addCommand(new Command("list")
+        .description("List knowledge wiki pages. Read-only, 0 credits.")
+        .option("--type <type>", "Filter by page type.")
+        .option("--status <status>", "Filter by draft, active, or archived.")
+        .option("--tags <csv>", "Comma-separated tags that must be present.")
+        .option("--limit <n>", "Maximum pages to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge pages", options, () => requestOxygen("/api/cli/knowledge/pages", {
+            method: "POST",
+            body: buildKnowledgePageListBody(options),
+        }));
+    }))
+        .addCommand(new Command("archive")
+        .description("Archive a knowledge wiki page while retaining its content and history. Links become unresolved. Restore with page upsert --status draft and the current --expected-revision.")
+        .argument("<slug_or_id>", "Page slug or UUID.")
+        .option("--expected-revision <n>", "Fail if the current page revision differs from the version you reviewed.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slugOrId, options) => {
+        await handleAsyncAction("knowledge page archive", options, async () => {
+            const expectedRevision = readPositiveInt(options.expectedRevision);
+            if (options.expectedRevision !== undefined && (expectedRevision === undefined || !Number.isSafeInteger(expectedRevision))) {
+                throw new OxygenError("invalid_request", "--expected-revision must be a positive integer.", { exitCode: 2 });
+            }
+            const data = await requestOxygen("/api/cli/knowledge/pages/archive", {
+                method: "POST",
+                body: {
+                    ...knowledgePageRefBody(slugOrId),
+                    ...(expectedRevision !== undefined ? { expected_revision: expectedRevision } : {}),
+                },
+            });
+            await markKnowledgeMirrorStaleAfterWrite();
+            return data;
+        });
+    }))
+        .addCommand(new Command("restore")
+        .description("Restore a knowledge wiki page to an earlier revision, as a new revision; history is kept. Use --expected-revision to refuse if the page changed since.")
+        .argument("<slug_or_id>", "Page slug or UUID.")
+        .requiredOption("--revision <n>", "The revision to restore (see knowledge page revisions).")
+        .option("--expected-revision <n>", "Fail if the current page revision differs from the version you reviewed.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slugOrId, options) => {
+        await handleAsyncAction("knowledge page restore", options, async () => {
+            const revision = readPositiveInt(options.revision);
+            const expectedRevision = readPositiveInt(options.expectedRevision);
+            if (revision === undefined || !Number.isSafeInteger(revision)) {
+                throw new OxygenError("invalid_request", "--revision must be a positive integer.", { exitCode: 2 });
+            }
+            if (options.expectedRevision !== undefined && (expectedRevision === undefined || !Number.isSafeInteger(expectedRevision))) {
+                throw new OxygenError("invalid_request", "--expected-revision must be a positive integer.", { exitCode: 2 });
+            }
+            const data = await requestOxygen("/api/cli/knowledge/pages/restore", {
+                method: "POST",
+                body: {
+                    ...knowledgePageRefBody(slugOrId),
+                    revision,
+                    ...(expectedRevision !== undefined ? { expected_revision: expectedRevision } : {}),
+                },
+            });
+            await markKnowledgeMirrorStaleAfterWrite();
+            return data;
+        });
+    }))
+        .addCommand(new Command("pin")
+        .description("Pin a knowledge wiki page as the canonical default for its type. Canonical voice/brand/positioning pages are auto-applied to AI copy generation.")
+        .argument("<slug_or_id>", "Page slug or UUID.")
+        .option("--canonical", "Pin as the canonical default for its type (default).")
+        .option("--no-canonical", "Unpin instead of pin (clears the canonical default for this type).")
+        .option("--approved", "Accepted for compatibility but never honored: pinning a sensitive type (voice, brand, positioning, playbooks) always files a proposal - approve it with `oxygen knowledge proposals approve <id>`.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slugOrId, options) => {
+        await handleAsyncAction("knowledge page pin", options, async () => {
+            const data = await requestOxygen("/api/cli/knowledge/pages/pin", {
+                method: "POST",
+                body: {
+                    ...knowledgePageRefBody(slugOrId),
+                    canonical: options.canonical !== false,
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+            await markKnowledgeMirrorStaleAfterWrite();
+            return data;
+        });
+    }))
+        .addCommand(new Command("revisions")
+        .description("List the revision history of a knowledge wiki page, newest first. Read-only, 0 credits.")
+        .argument("<slug_or_id>", "Page slug or UUID.")
+        .option("--limit <n>", "Maximum revisions to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slugOrId, options) => {
+        await handleAsyncAction("knowledge page revisions", options, () => {
+            const limit = readPositiveInt(options.limit);
+            return requestOxygen(knowledgeReadPath("/api/cli/knowledge/pages/revisions", {
+                ...knowledgePageRefBody(slugOrId),
+                ...(limit !== undefined ? { limit } : {}),
+            }));
+        });
+    }))
+        .addCommand(new Command("revision")
+        .description("Read one full revision snapshot of a knowledge wiki page. Read-only, 0 credits.")
+        .argument("<slug_or_id>", "Page slug or UUID.")
+        .argument("<revision>", "Revision number.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slugOrId, revision, options) => {
+        await handleAsyncAction("knowledge page revision", options, () => {
+            const revisionNumber = readPositiveInt(revision);
+            if (revisionNumber === undefined) {
+                throw new OxygenError("invalid_request", "Revision must be a positive integer.", {
+                    details: { revision },
+                });
+            }
+            return requestOxygen(knowledgeReadPath("/api/cli/knowledge/pages/revisions/get", {
+                ...knowledgePageRefBody(slugOrId),
+                revision: revisionNumber,
+            }));
+        });
+    })))
+        .addCommand(new Command("search")
+        .description("Search wiki pages by meaning and keywords. Read-only, 0 credits. Plain language uses hybrid retrieval when available; check match_type and semantic_status. Quotes, OR, and exclusions stay lexical. If the platform-funded embedding allowance is unavailable, keyword search still works.")
+        .argument("<query>", "Search text. Supports quoted phrases, OR, and -exclude.")
+        .option("--type <type>", "Filter by page type.")
+        .option("--status <status>", "Filter by draft, active, or archived. Omitted, archived pages are excluded.")
+        .option("--tags <csv>", "Comma-separated tags that must be present.")
+        .option("--limit <n>", "Maximum pages to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (query, options) => {
+        await handleAsyncAction("knowledge search", options, () => requestOxygen("/api/cli/knowledge/search", {
+            method: "POST",
+            body: buildKnowledgeSearchBody(query, options),
+        }));
+    }))
+        .addCommand(addContractFlags(new Command("index")
+        .description("Compact wiki index: each page's slug, one-liner, tags, link degree, plus type/status counts over the whole wiki. Lists the 200 most recently updated pages by default. Read-only, 0 credits. semantic.budget is Oxygen's platform-funded embedding safety allowance; its dollar and query counters are Oxygen's spend, never charges against your credits.")
+        .option("--limit <n>", "Maximum pages to list. Defaults to 200; hard cap is 1000. Counts always cover the whole wiki.")
+        .option("--all", "List every page instead of the most recently updated window.")
+        .option("--json", "Print a JSON envelope."), knowledgeIndexReadContract, { limit: { omit: true } })
+        .action(async (options) => {
+        await handleAsyncAction("knowledge index", options, async () => {
+            const params = new URLSearchParams();
+            const limit = readPositiveInt(options.limit);
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            if (options.all)
+                params.set("all", "true");
+            for (const [key, value] of Object.entries(readContractFlags(options, knowledgeIndexReadContract, { limit: { omit: true } })))
+                params.set(key, String(value));
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            const data = await requestOxygen(`/api/cli/knowledge/index${qs}`);
+            if (!options.json)
+                writeKnowledgeIndexCapNotice(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("graph")
+        .description("Knowledge graph of pages and their [[wikilink]] edges. Pass --center to render one page's local neighborhood instead of the whole graph. Read-only, 0 credits.")
+        .option("--max-nodes <n>", "Maximum nodes to include in the graph.")
+        .option("--center <slug_or_id>", "Center the graph on one page and show only its neighborhood (local mode).")
+        .option("--depth <n>", "Local-graph hop depth (1-3, default 1). Only applies with --center.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge graph", options, () => requestOxygen(knowledgeReadPath("/api/cli/knowledge/graph", buildKnowledgeGraphBody(options))));
+    }))
+        .addCommand(new Command("lint")
+        .description("Read-only structural wiki health report, 0 credits: orphans (unfilled seed stubs excluded), dead-ends, unresolved links, contradictions (disputed pages, conflicting trust tags, competing live-copy pages), missing canonicals, untagged pages, duplicate titles, oversized hubs, unfilled seed stubs (total plus the most-linked-to), researchable stubs, decisions missing a reversal condition, stale pages (untouched or superseded by newer sources), oversized bodies, and aged proposals.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge lint", options, () => requestOxygen("/api/cli/knowledge/lint"));
+    })
+        .addCommand(new Command("relink")
+        .description("Recompute [[wikilink]] edges (and gap-fill unlinked mentions) across wiki pages.")
+        .option("--slugs <csv>", "Comma-separated page slugs to relink. Omit to relink every page.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge lint relink", options, () => {
+            const slugs = readCsvOption(options.slugs);
+            return requestOxygen("/api/cli/knowledge/lint/relink", {
+                method: "POST",
+                body: slugs.length > 0 ? { slugs } : {},
+            });
+        });
+    })))
+        .addCommand(new Command("log")
+        .description("Knowledge decision and activity log.")
+        .addCommand(new Command("list")
+        .description("List knowledge log entries, newest first. Read-only, 0 credits.")
+        .option("--cursor <cursor>", "Pagination cursor from a previous page.")
+        .option("--limit <n>", "Maximum log entries to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge log", options, () => requestOxygen(knowledgeReadPath("/api/cli/knowledge/log", buildKnowledgeLogListBody(options))));
+    }))
+        .addCommand(new Command("append")
+        .description("Append an entry to the knowledge log.")
+        .requiredOption("--event <event>", "note, query_filed, or decision.")
+        .option("--slug <slug>", "Related page slug.")
+        .option("--summary <text>", "Short summary of the log entry.")
+        .option("--data-json <json>", "Flexible JSON object for structured log data.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge log append", options, () => requestOxygen("/api/cli/knowledge/log/append", {
+            method: "POST",
+            body: buildKnowledgeLogAppendBody(options),
+        }));
+    })))
+        .addCommand(addContractFlags(new Command("proposals")
+        .description("Review pending captured wiki changes. Optional summary traverses the live queue; exact proposal + value reads raw captured JSON. Read-only, 0 credits.")
+        .option("--status <status>", "open, decided, or all. Defaults to open.")
+        .option("--limit <n>", "Maximum proposals to return. Defaults to 50; server caps at 200.")
+        .option("--json", "Print a JSON envelope."), knowledgeProposalWindowContract)
+        .action(async (options) => {
+        await handleAsyncAction("knowledge proposals", options, () => {
+            const limit = readPositiveInt(options.limit);
+            return requestOxygen(knowledgeReadPath("/api/cli/knowledge/proposals", {
+                ...readContractFlags(options, knowledgeProposalWindowContract),
+                ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+            }));
+        });
+    })
+        .addCommand(new Command("approve")
+        .description("Approve a knowledge proposal and apply it to the target page.")
+        .argument("<id_or_slug>", "Proposal UUID or proposal page slug.")
+        .option("--force", "Apply even if the target page changed since the proposal was drafted.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (idOrSlug, options) => {
+        await handleAsyncAction("knowledge proposals approve", options, () => requestOxygen("/api/cli/knowledge/proposals/approve", {
+            method: "POST",
+            body: {
+                ...knowledgeProposalRefBody(idOrSlug),
+                ...(options.force ? { force: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("reject")
+        .description("Reject a knowledge proposal without changing the target page.")
+        .argument("<id_or_slug>", "Proposal UUID or proposal page slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (idOrSlug, options) => {
+        await handleAsyncAction("knowledge proposals reject", options, () => requestOxygen("/api/cli/knowledge/proposals/reject", {
+            method: "POST",
+            body: knowledgeProposalRefBody(idOrSlug),
+        }));
+    })))
+        .addCommand(new Command("resolve")
+        .description("Resolve task-scoped workspace GTM context with readiness and revision provenance.")
+        .option("--purpose <purpose>", "onboarding, general, lead_sourcing, qualification, outbound_copy, or workflow_design.")
+        .option("--asset-type <csv>", "Comma-separated context asset types to include.")
+        .option("--asset-status <status>", "draft, active, archived, or all. Defaults to active.")
+        .option("--tags <csv>", "Comma-separated asset tags that must be present.")
+        .option("--include-archived", "Include archived assets when no asset status is set.")
+        .option("--max-assets <n>", "Maximum assets to include. Defaults to 10, max 50.")
+        .option("--require-ready", "Exit with a conflict error when required context sections are missing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge resolve", options, () => requestOxygen("/api/cli/knowledge/resolve", {
+            method: "POST",
+            body: buildContextResolveBody(options),
+        }));
+    }))
+        .addCommand(new Command("profile")
+        .description("Company profile and ICP memory.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge profile", options, () => requestOxygen("/api/cli/knowledge/profile"));
+    })
+        .addCommand(new Command("update")
+        .description("Merge one or more profile sections into workspace GTM memory.")
+        .requiredOption("--data-json <json>", "JSON object with company, offering, icp, market, gtm_stack, or custom sections.")
+        .option("--summary <text>", "Optional concise summary for the profile.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge profile update", options, () => requestOxygen("/api/cli/knowledge/profile/update", {
+            method: "POST",
+            body: {
+                data: parseJsonObject(options.dataJson ?? "{}"),
+                ...(readOption(options.summary) ? { summary: readOption(options.summary) } : {}),
+            },
+        }));
+    })))
+        .addCommand(new Command("seed")
+        .description("Seed the knowledge starter pages: on first run creates draft ICP and Offers pages, [[wikilinked]] to each other. Idempotent; never overwrites your edits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge seed", options, () => requestOxygen("/api/cli/knowledge/seed", {
+            method: "POST",
+            body: {},
+        }));
+    }))
+        .addCommand(knowledgeBootstrapCommand)
+        .addCommand(new Command("synthesize")
+        .description("Synthesize knowledge from workspace evidence (one low-cost AI call, priced as one low-reasoning AI column cell): campaign learnings from auto-filed outreach outcomes, or your writing voice (a voice guide) learned from your sent LinkedIn and WhatsApp messages. Every run spends credits, the preview included, unless fewer than 3 sent messages exist (insufficient_source_messages, nothing charged); without --approved nothing is saved. To keep the guide a preview showed, pass its body back with --approved --body (no new AI call); --approved alone synthesizes and charges again. A saved voice guide becomes the canonical voice once a human approves its pin proposal (oxygen knowledge proposals approve <id>); it then grounds message, reply, sequence and post drafts and AI columns.")
+        .option("--kind <kind>", "What to synthesize: campaign_learnings (default) or voice (your writing voice from sent LinkedIn and WhatsApp messages).", "campaign_learnings")
+        .option("--sequence <sequence_id>", "Scope campaign learnings to one sequence's learnings page. Omit for the org-wide [[outreach-learnings]] page.")
+        .option("--approved", "Write the synthesized result (learnings page revision / voice guide saved with a pin proposal) instead of previewing.")
+        .option("--body <markdown>", "With --approved: save this body verbatim (the guide a preview showed, or your edit) with no new AI call, at 0 credits.")
+        .option("--title <title>", "Optional title for a newly created page/asset.")
+        .option("--limit <n>", "Voice only: how many recent sent messages to learn from (max 200).")
+        .option("--max-credits <n>", "Hard cap OXYGEN enforces on this call: it is charged exactly its estimate, so never more than n. A higher estimate is refused before any AI call, with nothing charged, and the refusal reports the estimate (--max-credits 0 shows it for free). --approved --body makes no AI call and needs none.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge synthesize", options, () => requestOxygen("/api/cli/knowledge/synthesize", {
+            method: "POST",
+            body: {
+                kind: options.kind ?? "campaign_learnings",
+                ...(readOption(options.sequence) ? { sequence: readOption(options.sequence) } : {}),
+                ...(options.approved ? { approved: true } : {}),
+                ...(readOption(options.body) ? { body: readOption(options.body) } : {}),
+                ...(readOption(options.title) ? { title: readOption(options.title) } : {}),
+                ...(readPositiveInt(options.limit) !== undefined ? { limit: readPositiveInt(options.limit) } : {}),
+                ...(readNonNegativeNumber(options.maxCredits) !== undefined ? { max_credits: readNonNegativeNumber(options.maxCredits) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("agent")
+        .description("The scheduled knowledge synthesis agent: unattended distillation of auto-filed sources into learnings pages (default off, spend-capped). Canonical changes still go through the proposal queue.")
+        .addCommand(new Command("get")
+        .description("Show the synthesis-agent config (enabled, cadence, per-day credit cap).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge agent get", options, () => requestOxygen("/api/cli/knowledge/agent"));
+    }))
+        .addCommand(new Command("set")
+        .description("Configure the synthesis agent. Enabling lets the background worker distill new sources on the cadence; it only writes working learnings pages.")
+        .option("--enabled", "Enable unattended synthesis.")
+        .option("--disabled", "Disable unattended synthesis.")
+        .option("--cadence-hours <n>", "Hours between synthesis cycles (1-168, default 24).")
+        .option("--max-credits-per-day <n>", "Managed-credit cap per UTC day (0-10,000, default 100).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge agent set", options, () => {
+            const body = {};
+            if (options.enabled)
+                body.enabled = true;
+            if (options.disabled)
+                body.enabled = false;
+            // Presence decides inclusion so an absent flag keeps the stored value.
+            if (options.cadenceHours !== undefined)
+                body.cadence_hours = Number(options.cadenceHours);
+            if (options.maxCreditsPerDay !== undefined)
+                body.max_credits_per_day = Number(options.maxCreditsPerDay);
+            return requestOxygen("/api/cli/knowledge/agent", { method: "POST", body });
+        });
+    })))
+        .addCommand(new Command("sync")
+        .description("Clone or refresh the local knowledge mirror: server-rendered page markdown under the CLI config dir. Pass --all to mirror every workspace the credential can access.")
+        .option("--all", "Sync every organization the credential can access, each into its own mirror; one org's failure never aborts the rest.")
+        .option("--full", "Purge the mirror (including its cursor) and re-clone every page.")
+        .option("--if-stale", "Skip when the mirror completed a sync within the TTL (or one is already running).")
+        .option("--ttl <minutes>", "Freshness window for --if-stale, in minutes. Defaults to 15.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge sync", options, () => options.all ? runKnowledgeMirrorSyncAll(options) : runKnowledgeMirrorSync(options));
+    }))
+        .addCommand(new Command("push")
+        .description("Push locally edited or newly created mirror pages back to the workspace wiki. Edits to canonical voice/brand/positioning pages become approval proposals instead of writing live.")
+        .option("--dry-run", "List what would be pushed without writing anything.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge push", options, () => runKnowledgeMirrorPush(options));
+    }))
+        .addCommand(new Command("status")
+        .description("Report the local knowledge mirror: path, page count, last sync, quarantined conflicts. Pass --all to report every locally mirrored workspace for the active API host.")
+        .option("--all", "Report every locally mirrored workspace for the active API host, with a per-mirror freshness flag.")
+        .option("--print-path", "Print only the mirror directory path.")
+        .option("--clear-conflicts", "Delete quarantined conflict copies from the mirror sidecar.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        if (options.printPath) {
+            await handleKnowledgeMirrorPrintPathAction();
+            return;
+        }
+        await handleAsyncAction("knowledge status", options, () => options.all ? runKnowledgeMirrorStatusAll() : runKnowledgeMirrorStatus(options));
+    }))
+        .addCommand(new Command("purge")
+        .description("Delete the whole local knowledge mirror for the active API host and organization.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge purge", options, () => runKnowledgeMirrorPurge());
+    }));
+}