@oxygen-agent/cli 1.256.13 → 1.272.83

package/dist/index.js

@@ -14,6 +14,7 @@ import { isRecipeDefinition } from "@oxygen/recipe-sdk";
 import { createBrowserLoginSession, openBrowser } from "./browser-login.js";
 import { clearCredentials, defaultApiUrl, listCredentialProfiles, loadCredentials, normalizeApiUrl, pickProfileNameForIdentity, pickProfileNameForUserSession, resolveActiveProfile, saveCredentials, switchCredentialProfile, updateActiveOrganizationForProfile, } from "./credentials.js";
 import { ensureFreshCliForApiUrl, requestOxygen } from "./http-client.js";
+import { acquireMirrorLock, clearConflictFiles, deletePageFile, emptyMirrorState, findMirrorSlugByPageId, isFileDirty, listConflictFiles, markMirrorStale, mirrorExists, purgeMirror, resetMirrorForFullResync, quarantineDirtyFile, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, resolveMirrorDir, writeGeneratedIndexFile, writeGeneratedLogFile, writeMirrorState, writePageFile, } from "./knowledge-mirror.js";
 import { waitForCliRun } from "./run-wait.js";
 import { runLocalCustomHttpColumn } from "./local-custom-http-column.js";
 import { captureCurrentTranscript, collectFeedbackEnvironment, TranscriptCaptureError, } from "./transcript.js";
@@ -308,6 +309,7 @@ function normalizeDeleteRowIds(values) {
     }
     return rowIds;
 }
+const CUSTOM_HTTP_MANIFEST_DOCS_URL = "https://oxygen-agent.com/docs/providers/custom-http";
 function readCustomIntegrationManifest(options) {
     const manifestPath = readOption(options.manifest);
     const manifestJson = readOption(options.manifestJson);
@@ -321,21 +323,38 @@ function readCustomIntegrationManifest(options) {
             exitCode: 1,
         });
     }
-    return parseJsonObject(manifestJson ?? readFileSync(resolve(manifestPath ?? ""), "utf8"));
+    if (manifestJson)
+        return parseJsonObject(manifestJson);
+    const filePath = resolve(manifestPath ?? "");
+    let content;
+    try {
+        content = readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        const notFound = error?.code === "ENOENT";
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new OxygenError("invalid_request", notFound
+            ? `Manifest file not found: ${filePath}. Pass --manifest <path.json> or --manifest-json '<json>'. See ${CUSTOM_HTTP_MANIFEST_DOCS_URL}`
+            : `Could not read manifest file ${filePath}: ${reason}. See ${CUSTOM_HTTP_MANIFEST_DOCS_URL}`, { details: { path: filePath }, exitCode: 1 });
+    }
+    try {
+        return parseJsonObject(content);
+    }
+    catch (error) {
+        if (error instanceof OxygenError) {
+            throw new OxygenError(error.code, `Manifest file ${filePath} is invalid: ${error.message} See ${CUSTOM_HTTP_MANIFEST_DOCS_URL}`, {
+                details: { path: filePath, ...(isRecord(error.details) ? error.details : {}) },
+                exitCode: error.exitCode,
+            });
+        }
+        throw error;
+    }
 }
 const CUSTOM_INTEGRATION_SECRET_KEYS = ["API_KEY", "TOKEN", "PASSWORD", "SECRET"];
 function readCustomIntegrationSecret(options) {
-    const apiKey = readOption(options.apiKey);
     const secretsFile = readOption(options.secretsFile);
-    if (apiKey && secretsFile) {
-        throw new OxygenError("invalid_request", "Pass either --api-key or --secrets-file, not both.", {
-            exitCode: 1,
-        });
-    }
-    if (apiKey)
-        return apiKey;
     if (!secretsFile) {
-        throw new OxygenError("invalid_request", "Pass --api-key or --secrets-file.", {
+        throw new OxygenError("invalid_request", "Pass --secrets-file.", {
             exitCode: 1,
         });
     }
@@ -618,6 +637,146 @@ function resolveNotetakerMode(options) {
     }
     return options.live === true ? "live" : "dry_run";
 }
+function buildPublishingPostsListPath(options) {
+    const query = new URLSearchParams();
+    const status = readOption(options.status);
+    const limit = readOption(options.limit);
+    if (status)
+        query.set("status", status);
+    if (limit)
+        query.set("limit", limit);
+    const suffix = query.toString();
+    return suffix ? `/api/cli/publishing/posts?${suffix}` : "/api/cli/publishing/posts";
+}
+function buildPublishingPostCreateBody(options) {
+    const status = resolvePublishingCreateStatus(options);
+    const body = {
+        content_text: readPublishingPostText(options, true),
+        publish_at: options.publishAt,
+        status,
+        approved: options.approved === true,
+    };
+    const sender = readOption(options.sender);
+    const provider = readOption(options.provider);
+    const channel = readOption(options.channel);
+    const providerConnection = readOption(options.providerConnection);
+    const title = readOption(options.title);
+    const timezone = readOption(options.timezone);
+    const content = buildPublishingContent(options);
+    if (provider)
+        body.provider = provider;
+    if (channel)
+        body.channel = channel;
+    if (sender)
+        body.sender_account_id = sender;
+    if (providerConnection)
+        body.provider_connection_id = providerConnection;
+    if (title)
+        body.title = title;
+    if (timezone)
+        body.timezone = timezone;
+    if (content)
+        body.content = content;
+    return body;
+}
+function buildPublishingPostUpdateBody(options) {
+    const body = {};
+    const sender = readOption(options.sender);
+    const provider = readOption(options.provider);
+    const channel = readOption(options.channel);
+    const providerConnection = readOption(options.providerConnection);
+    const title = readOption(options.title);
+    const text = readPublishingPostText(options, false);
+    const publishAt = readOption(options.publishAt);
+    const timezone = readOption(options.timezone);
+    const status = readOption(options.status);
+    const content = buildPublishingContent(options);
+    if (provider)
+        body.provider = provider;
+    if (channel)
+        body.channel = channel;
+    if (sender)
+        body.sender_account_id = sender;
+    if (providerConnection)
+        body.provider_connection_id = providerConnection;
+    if (title)
+        body.title = title;
+    if (text !== null)
+        body.content_text = text;
+    if (publishAt)
+        body.publish_at = publishAt;
+    if (timezone)
+        body.timezone = timezone;
+    if (status)
+        body.status = status;
+    if (content)
+        body.content = content;
+    return body;
+}
+function buildPublishingMediaUploadUrlBody(options) {
+    const fileName = readOption(options.fileName);
+    const contentType = readOption(options.contentType);
+    const byteLength = readPositiveInt(options.byteLength);
+    if (!fileName) {
+        throw new OxygenError("invalid_request", "--file-name is required.", { exitCode: 1 });
+    }
+    if (!contentType) {
+        throw new OxygenError("invalid_request", "--content-type is required.", { exitCode: 1 });
+    }
+    if (!byteLength) {
+        throw new OxygenError("invalid_request", "--byte-length must be a positive integer.", { exitCode: 1 });
+    }
+    const body = {
+        file_name: fileName,
+        content_type: contentType,
+        byte_length: byteLength,
+    };
+    const scheduledPost = readOption(options.scheduledPost);
+    const metadataJson = readOption(options.metadataJson);
+    if (scheduledPost)
+        body.scheduled_post_id = scheduledPost;
+    if (metadataJson)
+        body.metadata = parseJsonObject(metadataJson);
+    return body;
+}
+function buildPublishingMediaUploadedBody(options) {
+    const sha256 = readOption(options.sha256);
+    return sha256 ? { sha256 } : {};
+}
+function buildPublishingContent(options) {
+    const contentJson = readOption(options.contentJson);
+    const composioAction = readOption(options.composioAction);
+    if (!contentJson && !composioAction)
+        return null;
+    const content = contentJson ? parseJsonObject(contentJson) : {};
+    if (composioAction) {
+        const existing = content.composio && typeof content.composio === "object" && !Array.isArray(content.composio)
+            ? content.composio
+            : {};
+        content.composio = { ...existing, action_slug: composioAction };
+    }
+    return content;
+}
+function resolvePublishingCreateStatus(options) {
+    const status = readOption(options.status);
+    if (options.draft === true && status && status !== "draft") {
+        throw new OxygenError("conflicting_flags", "Pass either --draft or --status, not both.", { exitCode: 1 });
+    }
+    return options.draft === true ? "draft" : status ?? "scheduled";
+}
+function readPublishingPostText(options, required) {
+    const inlineText = readOption(options.text);
+    const textFile = readOption(options.textFile);
+    if (inlineText && textFile) {
+        throw new OxygenError("conflicting_flags", "Pass either --text or --text-file, not both.", { exitCode: 1 });
+    }
+    const text = textFile ? readFileSync(resolve(textFile), "utf8").trimEnd() : inlineText;
+    if (text?.trim())
+        return text;
+    if (!required)
+        return null;
+    throw new OxygenError("invalid_request", "Pass --text or --text-file.", { exitCode: 1 });
+}
 function buildCrmRelationshipUpsertBody(object, rowId, options) {
     return {
         object,
@@ -627,6 +786,7 @@ function buildCrmRelationshipUpsertBody(object, rowId, options) {
             ...(readOption(options.targetObject) ? { object: readOption(options.targetObject) } : {}),
             row_id: options.targetRowId,
         },
+        ...(readOption(options.role) ? { role: readOption(options.role) } : {}),
         mode: resolveCrmSetupMode(options),
     };
 }
@@ -1004,8 +1164,8 @@ export function createProgram() {
         .option("--package <npm_spec>", "Override the npm package spec.")
         .option("--dry-run", "Print the update command without running it.")
         .option("--json", "Print a JSON envelope.")
-        .action((options) => {
-        handleUpdateAction(options);
+        .action(async (options) => {
+        await handleUpdateAction(options);
     });
     program
         .command("api-keys")
@@ -1498,6 +1658,125 @@ export function createProgram() {
         .action(async (sessionId, options) => {
         await handleAsyncAction("notetaker status", options, () => requestOxygen(`/api/cli/notetaker/sessions/${encodeURIComponent(sessionId)}`));
     }));
+    program
+        .command("publishing")
+        .description("Deterministic social post scheduling commands.")
+        .addCommand(new Command("posts")
+        .description("Manage scheduled Publishing posts.")
+        .addCommand(new Command("list")
+        .description("List scheduled posts.")
+        .option("--status <status>", "Filter by draft, scheduled, queued, publishing, published, failed, or canceled.")
+        .option("--limit <n>", "Maximum posts to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing posts list", options, () => requestOxygen(buildPublishingPostsListPath(options)));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a scheduled post. Publishing requires approval before the worker can send.")
+        .requiredOption("--publish-at <iso>", "ISO date-time when the post should publish.")
+        .option("--provider <provider>", "Publishing provider: linkedin, x, instagram, tiktok, facebook, or youtube. Defaults to linkedin.")
+        .option("--channel <channel>", "Publishing channel override. Defaults to provider.")
+        .option("--sender <sender_account_id>", "LinkedIn sender account id. Required for LinkedIn before the worker can publish.")
+        .option("--provider-connection <connection_id>", "Oxygen integration connection id for Composio-backed providers.")
+        .option("--title <title>", "Internal title for the queue.")
+        .option("--text <text>", "Post text.")
+        .option("--text-file <path>", "Read post text from a local file.")
+        .option("--content-json <json>", "Optional structured provider content. For Composio providers, pass provider_arguments or composio.arguments.")
+        .option("--composio-action <slug>", "Override the Composio action slug for this scheduled post.")
+        .option("--timezone <tz>", "Display timezone for the scheduled date. Defaults to UTC.")
+        .option("--status <status>", "draft or scheduled. Defaults to scheduled.")
+        .option("--draft", "Create as a draft instead of scheduled.")
+        .option("--approved", "Mark the post approved for the scheduler.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing posts create", options, () => requestOxygen("/api/cli/publishing/posts", {
+            method: "POST",
+            body: buildPublishingPostCreateBody(options),
+        }));
+    }))
+        .addCommand(new Command("get")
+        .description("Get one scheduled post with attempt history.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts get", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}`));
+    }))
+        .addCommand(new Command("update")
+        .description("Update an editable draft, scheduled, or failed post.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--provider <provider>", "Publishing provider: linkedin, x, instagram, tiktok, facebook, or youtube.")
+        .option("--channel <channel>", "Publishing channel override.")
+        .option("--sender <sender_account_id>", "LinkedIn sender account id.")
+        .option("--provider-connection <connection_id>", "Oxygen integration connection id for Composio-backed providers.")
+        .option("--title <title>", "Internal title for the queue.")
+        .option("--text <text>", "Post text.")
+        .option("--text-file <path>", "Read post text from a local file.")
+        .option("--content-json <json>", "Optional structured provider content. For Composio providers, pass provider_arguments or composio.arguments.")
+        .option("--composio-action <slug>", "Override the Composio action slug for this scheduled post.")
+        .option("--publish-at <iso>", "ISO date-time when the post should publish.")
+        .option("--timezone <tz>", "Display timezone for the scheduled date.")
+        .option("--status <status>", "draft or scheduled.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts update", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}`, {
+            method: "PATCH",
+            body: buildPublishingPostUpdateBody(options),
+        }));
+    }))
+        .addCommand(new Command("approve")
+        .description("Approve a scheduled post so the worker can publish it when due.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts approve", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/approve`, {
+            method: "POST",
+        }));
+    }))
+        .addCommand(new Command("cancel")
+        .description("Cancel a draft, scheduled, queued, or failed post.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts cancel", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/cancel`, {
+            method: "POST",
+        }));
+    }))
+        .addCommand(new Command("retry")
+        .description("Move a failed post back to scheduled for another worker attempt.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts retry", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/retry`, {
+            method: "POST",
+        }));
+    })))
+        .addCommand(new Command("media")
+        .description("Manage Publishing media uploads.")
+        .addCommand(new Command("upload-url")
+        .description("Create a Publishing media asset and presigned object-storage upload URL.")
+        .requiredOption("--file-name <name>", "Original media filename.")
+        .requiredOption("--content-type <type>", "Media MIME type, such as image/png or video/mp4.")
+        .requiredOption("--byte-length <bytes>", "Exact media byte length.")
+        .option("--scheduled-post <post_id>", "Optional scheduled post id to associate with the media.")
+        .option("--metadata-json <json>", "Optional metadata object to store with the media asset.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing media upload-url", options, () => requestOxygen("/api/cli/publishing/media/upload-url", {
+            method: "POST",
+            body: buildPublishingMediaUploadUrlBody(options),
+        }));
+    }))
+        .addCommand(new Command("uploaded")
+        .description("Verify an uploaded Publishing media object and mark the media asset uploaded.")
+        .argument("<media_id>", "Publishing media asset id.")
+        .option("--sha256 <hex>", "Optional SHA-256 digest of the uploaded bytes.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mediaId, options) => {
+        await handleAsyncAction("publishing media uploaded", options, () => requestOxygen(`/api/cli/publishing/media/${encodeURIComponent(mediaId)}/uploaded`, {
+            method: "POST",
+            body: buildPublishingMediaUploadedBody(options),
+        }));
+    })));
     program
         .command("dashboards")
         .description("Default GTM dashboards: the stitched Command Center funnel across the sequencer, unibox, and CRM.")
@@ -1636,6 +1915,7 @@ export function createProgram() {
         .requiredOption("--relationship <slug>", "Relationship slug from the source object, such as team or company.")
         .option("--target-object <object>", "Target CRM object slug. Optional when the relationship has one target.")
         .requiredOption("--target-row-id <row_id>", "Target CRM record row id.")
+        .option("--role <role>", "Buying-committee role for a deals.stakeholders link: champion, economic_buyer, decision_maker, influencer, or end_user.")
         .option("--dry-run", "Preview the relationship write without changing edges.")
         .option("--live", "Apply the relationship write. Default is dry-run.")
         .option("--json", "Print a JSON envelope.")
@@ -2571,6 +2851,315 @@ export function createProgram() {
             body: { id: assetId },
         }));
     })));
+    program
+        .command("knowledge")
+        .description("Company knowledge wiki: slug-addressed pages, a [[wikilink]] graph, and a decision log.")
+        .addCommand(new Command("page")
+        .description("Knowledge wiki pages (slug-addressed, revision-guarded).")
+        .addCommand(new Command("upsert")
+        .description("Create or update a knowledge wiki page.")
+        .option("--slug <slug>", "Stable page slug to create or address. Omit to create by title.")
+        .option("--id <page_id>", "Existing page UUID to update. Omit to create.")
+        .option("--type <type>", "Page type (positioning, competitor, research_note, playbook, strategy, other). Defaults to other on create.")
+        .option("--title <title>", "Page title. Required on create.")
+        .option("--status <status>", "draft, active, or archived.")
+        .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", "Mark the write as human-approved.")
+        .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(new Command("get")
+        .description("Read one knowledge wiki page by slug or UUID.")
+        .argument("<slug_or_id>", "Page slug or UUID.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slugOrId, options) => {
+        await handleAsyncAction("knowledge page get", options, () => requestOxygen("/api/cli/knowledge/pages/get", {
+            method: "POST",
+            body: { slug: slugOrId },
+        }));
+    }))
+        .addCommand(new Command("list")
+        .description("List knowledge wiki pages.")
+        .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.")
+        .argument("<slug_or_id>", "Page slug or UUID.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slugOrId, options) => {
+        await handleAsyncAction("knowledge page archive", options, async () => {
+            const data = await requestOxygen("/api/cli/knowledge/pages/archive", {
+                method: "POST",
+                body: knowledgePageRefBody(slugOrId),
+            });
+            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", "Mark the pin as human-approved (required for sensitive types: voice, brand, positioning).")
+        .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.")
+        .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("/api/cli/knowledge/pages/revisions", {
+                method: "POST",
+                body: {
+                    ...knowledgePageRefBody(slugOrId),
+                    ...(limit !== undefined ? { limit } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("revision")
+        .description("Read one full revision snapshot of a knowledge wiki page.")
+        .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("/api/cli/knowledge/pages/revisions/get", {
+                method: "POST",
+                body: {
+                    ...knowledgePageRefBody(slugOrId),
+                    revision: revisionNumber,
+                },
+            });
+        });
+    })))
+        .addCommand(new Command("search")
+        .description("Full-text search across knowledge wiki pages, ranked by relevance.")
+        .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.")
+        .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(new Command("index")
+        .description("Compact wiki index: every page's slug, one-liner, tags, link degree, plus type/status counts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge index", options, () => requestOxygen("/api/cli/knowledge/index"));
+    }))
+        .addCommand(new Command("graph")
+        .description("Knowledge graph of pages and their [[wikilink]] edges.")
+        .option("--max-nodes <n>", "Maximum nodes to include in the graph.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge graph", options, () => requestOxygen("/api/cli/knowledge/graph", {
+            method: "POST",
+            body: buildKnowledgeGraphBody(options),
+        }));
+    }))
+        .addCommand(new Command("lint")
+        .description("Structural wiki health report: orphans, unresolved links, missing canonicals, stale/oversized pages, 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.")
+        .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("/api/cli/knowledge/log", {
+            method: "POST",
+            body: 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(new Command("proposals")
+        .description("Draft change proposals against wiki pages, awaiting human review.")
+        .option("--status <status>", "open, decided, or all. Defaults to open.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge proposals", options, () => requestOxygen("/api/cli/knowledge/proposals", {
+            method: "POST",
+            body: {
+                ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+            },
+        }));
+    })
+        .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>", "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 wiki with starter pages.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge seed", options, () => requestOxygen("/api/cli/knowledge/seed", {
+            method: "POST",
+            body: {},
+        }));
+    }))
+        .addCommand(new Command("sync")
+        .description("Clone or refresh the local knowledge mirror: server-rendered page markdown under the CLI config dir.")
+        .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, () => runKnowledgeMirrorSync(options));
+    }))
+        .addCommand(new Command("status")
+        .description("Report the local knowledge mirror: path, page count, last sync, quarantined conflicts.")
+        .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, () => 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());
+    }));
     program
         .command("blueprints")
         .description("Portable Oxygen blueprints: bundle a workflow + tables + columns + prompts as shareable JSON.")
@@ -3248,9 +3837,11 @@ export function createProgram() {
         .requiredOption("--table <table>", "Table id or slug.")
         .option("--status <status>", "Filter by active, queued, running, paused, completed, completed_with_errors, failed, canceling, or canceled. Defaults to active.")
         .option("--limit <n>", "Maximum runs to return. Defaults to 20.")
+        .option("--format <format>", "Format run history as json, jsonl, csv, or table (same serializer as `tables export`). Omit to keep the default envelope output.")
+        .option("--output <path>", "Write the formatted run history to a file instead of embedding it in the response.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("table-runs list", options, () => requestOxygen(tableRunsListPath(options)));
+        await handleAsyncAction("table-runs list", options, () => listTableRuns(options));
     }))
         .addCommand(new Command("get")
         .description("Get one durable table action run.")
@@ -4459,7 +5050,6 @@ export function createProgram() {
         .addCommand(new Command("connect")
         .description("Attach the credential (bearer token, API key, or basic password) for an applied custom HTTP integration.")
         .argument("<slug>", "Custom integration slug from the applied manifest.")
-        .option("--api-key <value>", "Credential value. Prefer --secrets-file to keep it out of shell history.")
         .option("--secrets-file <path>", "Path to a .env-style file holding the credential (a single entry, or one named API_KEY/TOKEN/PASSWORD/SECRET).")
         .option("--json", "Print a JSON envelope.")
         .action(async (slug, options) => {
@@ -6272,7 +6862,7 @@ export function createProgram() {
         });
     }))
         .addCommand(new Command("update")
-        .description("Update a DRAFT sequence's name, journey, channels, senders, email binding, or LinkedIn credit cap. The journey is re-validated; the email binding stays editable only while the sequence is a draft. --max-credits is locked once the sequence has been started (re-run `sequences start`). Pass only the fields you want to change.")
+        .description("Update a DRAFT sequence's name, journey, channels, senders, email binding, or LinkedIn credit cap, plus the always-editable open/click tracking toggles (--[no-]tracking-opens / --[no-]tracking-clicks, default on). The journey is re-validated; the email binding stays editable only while the sequence is a draft. --max-credits is locked once the sequence has been started (re-run `sequences start`). Pass only the fields you want to change.")
         .argument("<sequence>", "Sequence id or slug.")
         .option("--name <name>", "New human-readable sequence name.")
         .option("--steps-file <path>", "Path to a JSON file: { \"steps\": [...] } replacing the journey.")
@@ -6294,6 +6884,10 @@ export function createProgram() {
         .option("--schedule-template <name>", "Name of a saved schedule template (oxygen schedules) backing the sending window.")
         .option("--esp-matching <mode>", "Native-email ESP matching: 'off' (default) rotates mailboxes freely; 'prefer' biases toward a mailbox on the recipient's own provider; 'strict' requires a same-provider mailbox and defers the send when none exists.")
         .option("--no-stop-on-bounce", "Keep a lead's enrollment running after a hard bounce (default: stop it). The bounce is still recorded as an email_bounced signal either way.")
+        .option("--tracking-opens", "Turn open-pixel tracking ON for this sequence's native email sends (the default; injection still needs a verified tracking domain — see `oxygen domains tracking`).")
+        .option("--no-tracking-opens", "Turn OFF the open pixel for this sequence's native email sends (a deliverability knob — a pixel is spam-filter surface).")
+        .option("--tracking-clicks", "Turn click-link tracking ON for this sequence's native email sends (the default; same verified-tracking-domain gate as opens).")
+        .option("--no-tracking-clicks", "Turn OFF click-link rewriting for this sequence's native email sends (links go out untouched).")
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
         await handleAsyncAction("sequences update", options, () => {
@@ -6320,6 +6914,12 @@ export function createProgram() {
             const settings = readSequenceSettings(options);
             if (settings)
                 body.settings = settings;
+            // Tri-state tracking toggles: only send the key when a flag was
+            // explicitly passed, so an unrelated update never flips tracking.
+            if (options.trackingOpens !== undefined)
+                body.tracking_opens = options.trackingOpens;
+            if (options.trackingClicks !== undefined)
+                body.tracking_clicks = options.trackingClicks;
             if (options.clearEmail) {
                 body.email = null;
             }
@@ -6329,7 +6929,7 @@ export function createProgram() {
                     body.email = email;
             }
             if (Object.keys(body).length === 0) {
-                throw new Error("Provide at least one field to update (--name, --steps-file, --channels, --senders, --email-*, --clear-email, --max-credits, --max-live-sends, --max-emails-per-mailbox-per-day, --send-window-file, or --no-stop-on-bounce).");
+                throw new Error("Provide at least one field to update (--name, --steps-file, --channels, --senders, --email-*, --clear-email, --max-credits, --max-live-sends, --max-emails-per-mailbox-per-day, --send-window-file, --no-stop-on-bounce, or --[no-]tracking-opens / --[no-]tracking-clicks).");
             }
             return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}`, {
                 method: "PATCH",
@@ -6597,7 +7197,7 @@ export function createProgram() {
                     to: readOption(options.to),
                     subject: readOption(options.subject),
                     body: bodyText,
-                    ...(htmlBody && htmlBody.trim() ? { html: htmlBody } : {}),
+                    ...(htmlBody?.trim() ? { html: htmlBody } : {}),
                     ...(readOption(options.displayName) ? { display_name: readOption(options.displayName) } : {}),
                     ...(cc.length > 0 ? { cc } : {}),
                     ...(bcc.length > 0 ? { bcc } : {}),
@@ -7033,6 +7633,26 @@ export function createProgram() {
         .option("--json", "Print a JSON envelope.")
         .action(async (domain, options) => {
         await handleAsyncAction("domains tracking status", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/tracking`));
+    })))
+        .addCommand(new Command("postmaster")
+        .description("Google Postmaster Tools onboarding for a sending domain: register it with Postmaster, publish the DNS verification TXT via its Cloudflare zone, and check verification status. FREE — 0 Oxygen credits.")
+        .addCommand(new Command("onboard")
+        .description("Register the domain with Google Postmaster Tools and publish the DNS verification TXT automatically via the domain's Cloudflare zone (or return the record for manual DNS); verification then completes automatically in the background. Without --approve, returns a preview. FREE — 0 Oxygen credits.")
+        .argument("<domain>", "Sending domain, such as acme.com.")
+        .option("--approve", "Perform the onboarding. Without this flag, returns a preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains postmaster onboard", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/postmaster`, {
+            method: "POST",
+            body: { ...(options.approve ? { approved: true } : {}) },
+        }));
+    }))
+        .addCommand(new Command("status")
+        .description("Show the Google Postmaster Tools onboarding status for a domain: registration, DNS verification state, and whether reputation data is available. Read-only — 0 Oxygen credits.")
+        .argument("<domain>", "Sending domain, such as acme.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("domains postmaster status", options, () => requestOxygen(`/api/cli/domains/${encodeURIComponent(domain)}/postmaster`));
     })))
         .addCommand(new Command("add")
         .description("Onboard a domain registered elsewhere by creating a Cloudflare zone for it, so its DNS can be managed here. Returns the nameservers to set at your registrar. Idempotent.")
@@ -7489,8 +8109,7 @@ export function createProgram() {
         .option("--copy", "Copy skill files instead of symlinking when supported by npx skills. Default on Windows, where symlinks need Developer Mode or admin.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        // skipcq: JS-0116 — async Promise-wraps the synchronous installAgentSkills helper to satisfy handleAsyncAction's Promise<unknown> action
-        await handleAsyncAction("skills install", options, async () => installAgentSkills(options));
+        await handleAsyncAction("skills install", options, () => installAgentSkills(options));
     }));
     return program;
 }
@@ -7551,36 +8170,36 @@ function readBundledSdkDts(pkg) {
 }
 function renderStarterRecipe(id, name) {
     return [
-        `import { defineRecipe, type RecipeContext } from "@oxygen/recipe-sdk";`,
-        ``,
-        `// A durable recipe is the default export of defineRecipe(...); it compiles into an`,
-        `// Oxygen workflow. Recipes reach external systems ONLY through catalog tools —`,
-        `// raw fetch/network is disabled in the recipe sandbox.`,
-        `//`,
+        'import { defineRecipe, type RecipeContext } from "@oxygen/recipe-sdk";',
+        "",
+        "// A durable recipe is the default export of defineRecipe(...); it compiles into an",
+        "// Oxygen workflow. Recipes reach external systems ONLY through catalog tools —",
+        "// raw fetch/network is disabled in the recipe sandbox.",
+        "//",
         `// Deploy:  oxygen workflows apply --file ./${id}.ts`,
-        `// Dry-run: oxygen workflows call <workflow-id> --mode dry_run --json`,
-        `// Docs:    https://oxygen-agent.com/docs/authoring/recipes`,
-        `export default defineRecipe({`,
+        "// Dry-run: oxygen workflows call <workflow-id> --mode dry_run --json",
+        "// Docs:    https://oxygen-agent.com/docs/authoring/recipes",
+        "export default defineRecipe({",
         `  id: ${JSON.stringify(id)},`,
         `  name: ${JSON.stringify(name)},`,
-        `  // Allowlist of every tool id this recipe may call — including native table`,
-        `  // ops, which dispatch through oxygen.* tools (e.g. oxygen.rows_upsert for`,
-        `  // ctx.rows.upsert). Discover provider tools with: oxygen tools search <query>`,
-        `  tools: ["firecrawl.scrape", "oxygen.rows_upsert"],`,
-        `  trigger: { type: "api" },`,
-        `  inputSchema: {`,
-        `    type: "object",`,
-        `    properties: {},`,
-        `  },`,
-        `  async run(ctx: RecipeContext) {`,
-        `    ctx.log("info", "recipe started", { mode: ctx.mode });`,
-        `    // Example: pull data through a tool, then persist it to a table.`,
-        `    //   const page = await ctx.tools.run("firecrawl.scrape", { url }, { key: "scrape" });`,
-        `    //   await ctx.rows.upsert("my_table", rows, { key: "save", upsertKey: "id" });`,
-        `    return { ok: true, at: await ctx.now() };`,
-        `  },`,
-        `});`,
-        ``,
+        "  // Allowlist of every tool id this recipe may call — including native table",
+        "  // ops, which dispatch through oxygen.* tools (e.g. oxygen.rows_upsert for",
+        "  // ctx.rows.upsert). Discover provider tools with: oxygen tools search <query>",
+        '  tools: ["firecrawl.scrape", "oxygen.rows_upsert"],',
+        '  trigger: { type: "api" },',
+        "  inputSchema: {",
+        '    type: "object",',
+        "    properties: {},",
+        "  },",
+        "  async run(ctx: RecipeContext) {",
+        '    ctx.log("info", "recipe started", { mode: ctx.mode });',
+        "    // Example: pull data through a tool, then persist it to a table.",
+        '    //   const page = await ctx.tools.run("firecrawl.scrape", { url }, { key: "scrape" });',
+        '    //   await ctx.rows.upsert("my_table", rows, { key: "save", upsertKey: "id" });',
+        "    return { ok: true, at: await ctx.now() };",
+        "  },",
+        "});",
+        "",
     ].join("\n");
 }
 function renderRecipeTsconfig() {
@@ -7646,7 +8265,7 @@ function scaffoldRecipeProject(options) {
         next_steps: [
             `Edit ${recipeFileName}, then find tools with: oxygen tools search <query>`,
             `Deploy it:  oxygen workflows apply --file ./${recipeFileName}`,
-            `Dry-run it: oxygen workflows call <workflow-id> --mode dry_run --json`,
+            "Dry-run it: oxygen workflows call <workflow-id> --mode dry_run --json",
         ],
     };
 }
@@ -9375,7 +9994,7 @@ async function runDomainsDnsPlan(domain, options) {
 }
 // Apply an approved DNS plan (writes records). Requires --plan <hash> with
 // --approved, mirroring `domains buy --quote`.
-async function runDomainsDnsApply(domain, options) {
+function runDomainsDnsApply(domain, options) {
     const planHash = readOption(options.plan);
     if (options.approved && !planHash) {
         throw new Error("--plan <hash> is required with --approved. Run `domains dns plan` first to get the plan and its hash.");
@@ -9503,6 +10122,33 @@ async function exportRows(table, options) {
         ...(formatted.rescuedCount > 0 ? { rescuedNumericCells: formatted.rescuedCount } : {}),
     };
 }
+// `table-runs list --format` routes run history through the same serializer
+// `tables export` uses, so csv/jsonl/table run exports behave exactly like row
+// exports (header = union of run keys; nested objects like counts are
+// JSON-stringified by escapeCsvField). Without --format/--output the command
+// keeps its original envelope response untouched.
+async function listTableRuns(options) {
+    const rawFormat = readOption(options.format);
+    const outputPath = readOption(options.output);
+    if (!rawFormat && !outputPath)
+        return requestOxygen(tableRunsListPath(options));
+    // Validate the format before spending the API call.
+    const format = normalizeExportRowsFormat(rawFormat ?? undefined);
+    const result = await requestOxygen(tableRunsListPath(options));
+    const runs = Array.isArray(result.runs) ? result.runs.filter(isRecord) : [];
+    const formatted = formatRows(runs, format);
+    if (outputPath)
+        writeFileSync(outputPath, formatted.content);
+    return {
+        table: result.table ?? null,
+        status: result.status ?? null,
+        format,
+        runCount: runs.length,
+        output: outputPath ?? null,
+        ...(outputPath ? {} : { content: formatted.content }),
+        ...(typeof result.web_url === "string" ? { web_url: result.web_url } : {}),
+    };
+}
 const TABLE_BUNDLE_SCHEMA_VERSION = 1;
 const TABLE_BUNDLE_MAX_PAGE_SIZE = 1000;
 const TABLE_BUNDLE_DEFAULT_PAGE_SIZE = 500;
@@ -10445,9 +11091,9 @@ async function handleLogoutAction(options) {
         process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
     }
 }
-function handleUpdateAction(options) {
+async function handleUpdateAction(options) {
     try {
-        const result = updateCli(options);
+        const result = await updateCli(options);
         if (options.json) {
             writeJson(success("update", result));
             return;
@@ -10522,7 +11168,7 @@ async function login(options) {
         renamed = picked.renamed;
     }
     const profile = await saveCredentials(credentials, process.env, { profile: chosenProfile });
-    const skillsInstall = runAutomaticSkillsInstall({ apiUrl: credentials.apiUrl });
+    const skillsInstall = await runAutomaticSkillsInstall({ apiUrl: credentials.apiUrl, credentials });
     if (!options.json) {
         process.stdout.write(formatLoginSuccessForResolved(loginIdentity, profile, { renamed, skillsInstall }));
         const hint = await buildPostLoginHint(profile);
@@ -11900,6 +12546,332 @@ function buildContextAssetUpsertBody(options) {
         ...(options.default ? { is_default: true } : {}),
     };
 }
+function buildKnowledgePageUpsertBody(options) {
+    const tags = readCsvOption(options.tags);
+    const expectedRevision = readPositiveInt(options.expectedRevision);
+    return {
+        ...(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 buildKnowledgeGraphBody(options) {
+    const maxNodes = readPositiveInt(options.maxNodes);
+    return {
+        ...(maxNodes !== undefined ? { max_nodes: maxNodes } : {}),
+    };
+}
+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 } : {}),
+    };
+}
+// ── Knowledge mirror (local wiki clone) ─────────────────────────────────────────
+// `oxygen knowledge sync` maintains <configDir>/knowledge/<api-host>/<org-id>/ with
+// SERVER-rendered page markdown written verbatim — the server hashes those exact
+// bytes (content_sha256) and the client never re-renders, so renderer drift can't
+// mass-quarantine mirrors. Pure directory mechanics live in knowledge-mirror.ts.
+const KNOWLEDGE_SYNC_DEFAULT_TTL_MINUTES = 15;
+// 500 batches × the server's 100-page default is far above any v1 wiki; the cap
+// only exists so a misbehaving server can never wedge the CLI in a loop.
+const KNOWLEDGE_SYNC_MAX_BATCHES = 500;
+// Envelope error codes meaning this org can no longer be read with the stored
+// token (revoked membership, expired key, org mismatch). The mirror is a local
+// cache of tenant data and must not outlive access to it.
+const KNOWLEDGE_SYNC_ACCESS_REVOKED_CODES = new Set([
+    "unauthorized",
+    "forbidden",
+    "forbidden_origin",
+    "organization_not_found",
+    "organization_mismatch",
+]);
+function knowledgeMirrorTargetFor(apiUrl, orgId) {
+    const apiHost = new URL(apiUrl).host;
+    return {
+        dir: resolveMirrorDir({ configDir: resolveDefaultConfigDir(), apiHost, orgId }),
+        apiHost,
+        orgId,
+        webUrl: `${apiUrl.replace(/\/$/, "")}/knowledge`,
+    };
+}
+// The org id every other command resolves implicitly (X-Oxygen-Organization from
+// OXYGEN_ORG / the stored profile) must be pinned explicitly here because it names
+// the mirror directory. Null when the cached identity can't answer for the
+// selected org — e.g. env-token logins or an OXYGEN_ORG/--org override.
+function knowledgeMirrorTargetFromCredentials(credentials) {
+    const cached = credentials.activeOrganization ?? credentials.identity?.organization ?? null;
+    if (!cached)
+        return null;
+    const selected = process.env.OXYGEN_ORG?.trim();
+    if (selected && selected !== cached.id && selected !== cached.slug)
+        return null;
+    return knowledgeMirrorTargetFor(credentials.apiUrl, cached.id);
+}
+async function resolveKnowledgeMirrorTarget() {
+    const credentials = await loadCredentials();
+    if (!credentials) {
+        throw new OxygenError("not_logged_in", "Run `oxygen login` before using CLI commands.", {
+            exitCode: 1,
+        });
+    }
+    const local = knowledgeMirrorTargetFromCredentials(credentials);
+    if (local)
+        return local;
+    const identity = await requestOxygen("/api/cli/whoami", {
+        enforceMinimumCliVersion: false,
+    });
+    return knowledgeMirrorTargetFor(credentials.apiUrl, identity.organization.id);
+}
+// 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);
+        const target = credentials ? knowledgeMirrorTargetFromCredentials(credentials) : null;
+        if (!target || !mirrorExists(target.dir))
+            return;
+        markMirrorStale(target.dir);
+    }
+    catch {
+        // A broken local mirror must never fail the page write itself.
+    }
+}
+function knowledgeSyncSummary(target, state, extra) {
+    return {
+        synced: 0,
+        deleted: 0,
+        quarantined: 0,
+        pages_total: state ? Object.keys(state.pages).length : 0,
+        cursor: state?.cursor ?? null,
+        last_sync_at: state?.last_sync_at ?? null,
+        mirror_path: target.dir,
+        web_url: target.webUrl,
+        ...extra,
+    };
+}
+function applyKnowledgeSyncPage(dir, state, page, counters) {
+    if (page.rendered_markdown === undefined || page.content_sha256 === undefined || !page.slug) {
+        // Tombstone (archived or slug-less): delete the file this page owns locally,
+        // matching by slug first and falling back to the page id (slug re-use).
+        const localSlug = page.slug && state.pages[page.slug]?.id === page.id
+            ? page.slug
+            : findMirrorSlugByPageId(state, page.id);
+        if (localSlug) {
+            deletePageFile(dir, localSlug);
+            delete state.pages[localSlug];
+            counters.deleted += 1;
+        }
+        return;
+    }
+    // Slug renames: drop the file this page previously owned under its old slug.
+    const previousSlug = findMirrorSlugByPageId(state, page.id);
+    if (previousSlug && previousSlug !== page.slug) {
+        deletePageFile(dir, previousSlug);
+        delete state.pages[previousSlug];
+        counters.deleted += 1;
+    }
+    // Quarantine only bytes WE didn't write (differ from the manifest's recorded
+    // sha) that this write would destroy (differ from the incoming server bytes).
+    const recordedSha = state.pages[page.slug]?.content_sha256;
+    if (isFileDirty(dir, page.slug, recordedSha ?? page.content_sha256)
+        && isFileDirty(dir, page.slug, page.content_sha256)) {
+        quarantineDirtyFile(dir, page.slug);
+        counters.quarantined += 1;
+    }
+    writePageFile(dir, page.slug, page.rendered_markdown);
+    state.pages[page.slug] = {
+        id: page.id,
+        revision: page.revision,
+        content_sha256: page.content_sha256,
+    };
+    counters.synced += 1;
+}
+async function runKnowledgeMirrorSync(options) {
+    const target = await resolveKnowledgeMirrorTarget();
+    const ttlMinutes = readPositiveInt(options.ttl) ?? KNOWLEDGE_SYNC_DEFAULT_TTL_MINUTES;
+    if (options.ifStale && !options.full) {
+        const state = readMirrorState(target.dir);
+        const lastSyncMs = state?.last_sync_at ? Date.parse(state.last_sync_at) : Number.NaN;
+        if (Number.isFinite(lastSyncMs) && Date.now() - lastSyncMs < ttlMinutes * 60_000) {
+            return knowledgeSyncSummary(target, state, { skipped: true, reason: "fresh" });
+        }
+    }
+    if (!acquireMirrorLock(target.dir)) {
+        if (options.ifStale) {
+            return knowledgeSyncSummary(target, readMirrorState(target.dir), { skipped: true, reason: "locked" });
+        }
+        throw new OxygenError("knowledge_sync_locked", "Another knowledge sync is already running for this mirror. Retry shortly; a crashed sync's lock self-clears after 10 minutes.", {
+            details: { mirror_path: target.dir },
+            exitCode: 1,
+        });
+    }
+    try {
+        // --full re-clones from scratch but keeps the never-silently-clobber promise:
+        // dirty local files are quarantined into .oxygen/conflicts/ (which survives)
+        // first. Done AFTER acquiring the mirror lock above so a concurrent --full
+        // can't delete files out from under another running sync before locking.
+        const fullResetQuarantined = options.full
+            ? resetMirrorForFullResync(target.dir).quarantined
+            : 0;
+        const state = readMirrorState(target.dir)
+            ?? emptyMirrorState({ apiHost: target.apiHost, orgId: target.orgId });
+        const counters = { synced: 0, deleted: 0, quarantined: fullResetQuarantined };
+        let webUrl = target.webUrl;
+        let cursor = state.cursor;
+        let lastSeen = null;
+        let completed = false;
+        for (let batch = 0; batch < KNOWLEDGE_SYNC_MAX_BATCHES; batch += 1) {
+            const delta = await requestOxygen("/api/cli/knowledge/sync/delta", {
+                method: "POST",
+                body: cursor ? { cursor } : {},
+            });
+            if (delta.web_url)
+                webUrl = delta.web_url;
+            for (const page of delta.pages) {
+                applyKnowledgeSyncPage(target.dir, state, page, counters);
+                lastSeen = { updated_at: page.updated_at, id: page.id };
+            }
+            if (!delta.has_more) {
+                // Completed. Persist the watermark AFTER the last seen page — the delta
+                // keyset is (updated_at, id) ascending and updated_at is the server's own
+                // ISO rendering, so `<updated_at>|<id>` is exactly the server cursor and
+                // the next sync fetches only pages updated since.
+                if (lastSeen)
+                    state.cursor = `${lastSeen.updated_at}|${lastSeen.id}`;
+                completed = true;
+                break;
+            }
+            if (!delta.next_cursor || delta.next_cursor === cursor) {
+                throw new OxygenError("knowledge_sync_stalled", "The sync cursor did not advance between batches; aborting to avoid a loop.", {
+                    details: { cursor, mirror_path: target.dir },
+                    exitCode: 1,
+                });
+            }
+            cursor = delta.next_cursor;
+            // Persist per batch so an interrupted clone resumes exactly where it stopped.
+            state.cursor = cursor;
+            writeMirrorState(target.dir, state);
+        }
+        if (!completed) {
+            throw new OxygenError("knowledge_sync_incomplete", "The sync batch cap was reached before the wiki finished; re-run `knowledge sync` to resume from the stored cursor.", {
+                details: { cursor: state.cursor, mirror_path: target.dir, batch_cap: KNOWLEDGE_SYNC_MAX_BATCHES },
+                exitCode: 1,
+            });
+        }
+        // Generated summaries come from the server's own projections, not a client-side
+        // recomputation. A real wiki page may own the `index`/`log` slug — page bytes win.
+        const index = await requestOxygen("/api/cli/knowledge/index");
+        const logPage = await requestOxygen("/api/cli/knowledge/log", {
+            method: "POST",
+            body: {},
+        });
+        if (!state.pages.index)
+            writeGeneratedIndexFile(target.dir, index.index);
+        if (!state.pages.log)
+            writeGeneratedLogFile(target.dir, logPage.entries);
+        state.last_sync_at = new Date().toISOString();
+        writeMirrorState(target.dir, state);
+        return knowledgeSyncSummary(target, state, { ...counters, ...(options.full ? { full: true } : {}), web_url: webUrl });
+    }
+    catch (error) {
+        if (error instanceof OxygenError && KNOWLEDGE_SYNC_ACCESS_REVOKED_CODES.has(error.code)) {
+            purgeMirror(target.dir);
+            throw new OxygenError("knowledge_mirror_access_revoked", "This organization can no longer be read with the stored credentials (membership revoked or token expired). The local knowledge mirror was purged.", {
+                details: { org_id: target.orgId, mirror_path: target.dir, cause: error.code },
+                exitCode: 1,
+            });
+        }
+        throw error;
+    }
+    finally {
+        releaseMirrorLock(target.dir);
+    }
+}
+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,
+    };
+}
+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) {
+        const failure = toFailure("knowledge status", error);
+        writeJson(failure);
+        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+    }
+}
+// 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 };
+}
 function buildEnrichColumnBody(// skipcq: JS-R1005 -- CLI body builder maps enrichment aliases, selection, provider order, and safety caps.
 table, options) {
     const limit = readPositiveInt(options.limit);