@oxygen-agent/cli 1.263.0 → 1.272.83

package/dist/skills.js

@@ -3,17 +3,67 @@ import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { OxygenError, toFailure } from "@oxygen/shared";
-import { defaultApiUrl, normalizeApiUrl } from "./credentials.js";
+import { defaultApiUrl, loadCredentials, normalizeApiUrl } from "./credentials.js";
+import { requestOxygen } from "./http-client.js";
 import { resolveCmdShimInvocation } from "./windows-shim.js";
 const DEFAULT_SKILL_AGENTS = ["codex", "claude-code", "cursor"];
 const SKILL_INDEX_PATH = "/.well-known/skills/index.json";
-export async function listAgentSkills(options) {
+const SKILLS_ACCESS_API_PATH = "/api/cli/skills/access";
+/**
+ * Resolves where to install skills from. Logged-in CLIs mint a short-lived
+ * org-bound access URL (the skills surface is gated; anonymous serving is
+ * being retired). Any failure falls back to the plain well-known URL so
+ * installs never regress while older deployments are still in circulation.
+ */
+export async function resolveSkillsInstallSource(options) {
+    const publicSource = (reason) => ({
+        authenticated: false,
+        install_url: skillIndexUrl(options.apiUrl),
+        index_url: skillIndexUrl(options.apiUrl),
+        fallback_reason: reason,
+    });
+    let credentials;
+    try {
+        credentials = options.credentials !== undefined ? options.credentials : await loadCredentials();
+    }
+    catch (error) {
+        const code = error instanceof OxygenError ? error.code : "unknown_error";
+        return publicSource(`credentials_unavailable:${code}`);
+    }
+    if (!credentials)
+        return publicSource("not_logged_in");
+    if (normalizeApiUrl(credentials.apiUrl) !== options.apiUrl)
+        return publicSource("api_url_mismatch");
+    try {
+        const access = await requestOxygen(SKILLS_ACCESS_API_PATH, {
+            method: "POST",
+            credentials,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        });
+        if (!access?.base_url?.trim() || !access?.index_url?.trim()) {
+            return publicSource("invalid_access_response");
+        }
+        return {
+            authenticated: true,
+            install_url: access.base_url,
+            index_url: access.index_url,
+            ...(access.expires_at ? { expires_at: access.expires_at } : {}),
+        };
+    }
+    catch (error) {
+        const code = error instanceof OxygenError ? error.code : "unknown_error";
+        return publicSource(`access_unavailable:${code}`);
+    }
+}
+export async function listAgentSkills(options, runtime = {}) {
     const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
-    const indexUrl = skillIndexUrl(apiUrl);
-    const index = await inspectSkillIndex(indexUrl);
+    const source = await resolveSkillsInstallSource({ apiUrl, ...runtime });
+    const index = await inspectSkillIndex(source.index_url, runtime.fetch);
     const installed = detectInstalledAgentSkills();
     return {
-        index_url: indexUrl,
+        index_url: source.index_url,
+        authenticated: source.authenticated,
+        ...(source.fallback_reason ? { access_fallback: source.fallback_reason } : {}),
         available: {
             detected: index.reachable,
             names: index.skill_names,
@@ -25,14 +75,16 @@ export async function listAgentSkills(options) {
         install_command_args: recommendedSkillsInstallArgs(apiUrl),
     };
 }
-export async function doctorAgentSkills(options) {
+export async function doctorAgentSkills(options, runtime = {}) {
     const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
-    const indexUrl = skillIndexUrl(apiUrl);
-    const index = await inspectSkillIndex(indexUrl);
+    const source = await resolveSkillsInstallSource({ apiUrl, ...runtime });
+    const index = await inspectSkillIndex(source.index_url, runtime.fetch);
     const installer = inspectSkillsInstaller();
     const installed = detectInstalledAgentSkills();
     const data = {
-        index_url: indexUrl,
+        index_url: source.index_url,
+        authenticated: source.authenticated,
+        ...(source.fallback_reason ? { access_fallback: source.fallback_reason } : {}),
         index,
         installer,
         installed,
@@ -53,15 +105,19 @@ export async function doctorAgentSkills(options) {
     }
     return data;
 }
-export function installAgentSkills(// skipcq: JS-R1005
+export async function installAgentSkills(// skipcq: JS-R1005
 options, runtime = {}) {
     const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
-    const indexUrl = skillIndexUrl(apiUrl);
+    const source = await resolveSkillsInstallSource({
+        apiUrl,
+        ...(runtime.credentials !== undefined ? { credentials: runtime.credentials } : {}),
+        ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
+    });
     const agents = readWords(options.agents ?? DEFAULT_SKILL_AGENTS);
     const skill = readOption(options.skill) ?? "*";
     const env = runtime.env ?? process.env;
     const platform = runtime.platform ?? process.platform;
-    const args = installerAddArgs(indexUrl, agents, skill);
+    const args = installerAddArgs(source.install_url, agents, skill);
     if (!options.project)
         args.push("--global");
     if (options.copy)
@@ -81,7 +137,8 @@ options, runtime = {}) {
         const message = result.error instanceof Error ? result.error.message : null;
         throw new OxygenError("skills_install_failed", "Unable to install Oxygen agent skills.", {
             details: {
-                index_url: indexUrl,
+                index_url: source.index_url,
+                authenticated: source.authenticated,
                 executable: invocation.label,
                 exit_code: typeof result.status === "number" ? result.status : null,
                 stdout: stdout.slice(0, 2000),
@@ -91,8 +148,11 @@ options, runtime = {}) {
         });
     }
     return {
-        indexUrl,
-        index_url: indexUrl,
+        indexUrl: source.index_url,
+        index_url: source.index_url,
+        install_url: source.install_url,
+        authenticated: source.authenticated,
+        ...(source.fallback_reason ? { access_fallback: source.fallback_reason } : {}),
         agents,
         skill,
         scope: options.project ? "project" : "global",
@@ -131,7 +191,7 @@ function wrapExecFileSync(exec) {
         }
     });
 }
-export function runAutomaticSkillsInstall(options = {}) {
+export async function runAutomaticSkillsInstall(options = {}) {
     const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
     const env = options.env ?? process.env;
     const platform = options.platform ?? process.platform;
@@ -139,8 +199,23 @@ export function runAutomaticSkillsInstall(options = {}) {
         return skippedAutomaticSkillsInstall("OXYGEN_SKIP_SKILLS=1", apiUrl);
     }
     const command = recommendedSkillsInstallCommand(apiUrl);
+    // The skills surface requires a logged-in identity; without credentials the
+    // unattended install would only produce a confusing installer error. A stale
+    // OXYGEN_PROFILE or unreadable credential store must not fail the parent
+    // command (e.g. `oxygen update`) — auto-install is strictly best-effort.
+    let credentials;
+    try {
+        credentials = options.credentials !== undefined ? options.credentials : await loadCredentials(env);
+    }
+    catch (error) {
+        const failure = toFailure("skills install", error);
+        return { attempted: false, ok: false, command, error: failure.error };
+    }
+    if (!credentials) {
+        return skippedAutomaticSkillsInstall("not_logged_in", apiUrl);
+    }
     try {
-        installAgentSkills({
+        await installAgentSkills({
             apiUrl,
             agents: DEFAULT_SKILL_AGENTS,
             skill: "*",
@@ -151,6 +226,8 @@ export function runAutomaticSkillsInstall(options = {}) {
         }, {
             env,
             platform,
+            credentials,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
             ...(options.execFileSync ? { execFileSync: options.execFileSync } : {}),
             ...(options.spawnSync ? { spawnSync: options.spawnSync } : {}),
         });
@@ -178,12 +255,12 @@ export function skippedAutomaticSkillsInstall(reason, apiUrl = normalizeApiUrl(d
         reason,
     };
 }
-async function inspectSkillIndex(indexUrl) {
+async function inspectSkillIndex(indexUrl, fetchImpl = fetch) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 10_000);
     timeout.unref?.();
     try {
-        const response = await fetch(indexUrl, {
+        const response = await fetchImpl(indexUrl, {
             headers: { Accept: "application/json" },
             signal: controller.signal,
         });

package/dist/update.d.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { type AutomaticSkillsInstallResult, type ExecFileSyncLike } from "./skills.js";
+import { type AutomaticSkillsInstallResult, type ExecFileSyncLike, type SkillsSourceRuntime } from "./skills.js";
 type SpawnResult = ReturnType<typeof spawnSync>;
 type SpawnSyncLike = (command: string, args: string[], options: {
     encoding: BufferEncoding;
@@ -27,7 +27,7 @@ export declare function updateCli(options: UpdateOptions, runtime?: {
     modulePath?: string;
     spawnSync?: SpawnSyncLike;
     execFileSync?: ExecFileSyncLike;
-}): UpdateResult;
+} & SkillsSourceRuntime): Promise<UpdateResult>;
 export declare function detectCliInstallPrefix(modulePath?: string): string | null;
 export declare function detectCliInstallPrefixFromPath(modulePath: string): string | null;
 export declare function resolveNpmExecutables(platform?: NodeJS.Platform): string[];

package/dist/update.js

@@ -5,7 +5,7 @@ import { runAutomaticSkillsInstall, skippedAutomaticSkillsInstall, } from "./ski
 import { quoteWindowsCmdArg } from "./windows-shim.js";
 const DEFAULT_CLI_PACKAGE_SPEC = "@oxygen-agent/cli@latest";
 // skipcq: JS-R1005 — handles platform/install-mode/dry-run combinations end-to-end
-export function updateCli(options, runtime = {}) {
+export async function updateCli(options, runtime = {}) {
     const env = runtime.env ?? process.env;
     const platform = runtime.platform ?? process.platform;
     const spawn = runtime.spawnSync ?? spawnSync;
@@ -52,9 +52,11 @@ export function updateCli(options, runtime = {}) {
                 command,
                 dry_run: false,
                 updated: true,
-                skills_install: runAutomaticSkillsInstall({
+                skills_install: await runAutomaticSkillsInstall({
                     env,
                     platform,
+                    ...(runtime.credentials !== undefined ? { credentials: runtime.credentials } : {}),
+                    ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
                     ...(runtime.execFileSync ? { execFileSync: runtime.execFileSync } : {}),
                 }),
             };

package/node_modules/@oxygen/shared/dist/index.d.ts

@@ -10,6 +10,9 @@ export * from "./credit-guidance.js";
 export * from "./directory.js";
 export * from "./email-tracking-token.js";
 export * from "./email-unsubscribe-token.js";
+export * from "./knowledge-constants.js";
+export * from "./knowledge-links.js";
+export * from "./knowledge-markdown.js";
 export * from "./linkedin-post-url.js";
 export * from "./linkedin-sequences.js";
 export * from "./networks.js";

package/node_modules/@oxygen/shared/dist/index.js

@@ -10,6 +10,9 @@ export * from "./credit-guidance.js";
 export * from "./directory.js";
 export * from "./email-tracking-token.js";
 export * from "./email-unsubscribe-token.js";
+export * from "./knowledge-constants.js";
+export * from "./knowledge-links.js";
+export * from "./knowledge-markdown.js";
 export * from "./linkedin-post-url.js";
 export * from "./linkedin-sequences.js";
 export * from "./networks.js";

package/node_modules/@oxygen/shared/dist/knowledge-constants.d.ts

@@ -0,0 +1,38 @@
+export declare const KNOWLEDGE_PAGE_TYPES: readonly ["playbook", "strategy", "campaign", "positioning", "persona", "competitor", "research_note", "message_playbook", "proposed_playbook_bullet", "voice", "brand", "other", "entity", "topic", "source_summary", "report", "schema"];
+export type KnowledgePageType = typeof KNOWLEDGE_PAGE_TYPES[number];
+export declare const KNOWLEDGE_META_PAGE_TYPES: readonly ["schema", "source_summary", "report"];
+export declare const KNOWLEDGE_PAGE_STATUSES: readonly ["draft", "active", "archived"];
+export type KnowledgePageStatus = typeof KNOWLEDGE_PAGE_STATUSES[number];
+export declare const RESERVED_KNOWLEDGE_SLUGS: readonly ["index", "log", "schema", "company-profile", "readme"];
+export declare const KNOWLEDGE_SLUG_MAX_LENGTH = 120;
+export declare const KNOWLEDGE_SLUG_PATTERN: RegExp;
+export declare function isValidKnowledgeSlug(value: string): boolean;
+/**
+ * Coerce arbitrary text (a title, a [[wikilink]] target) into slug form:
+ * lowercase, diacritics stripped, every non-alphanumeric run collapsed to one
+ * dash, trimmed, capped at KNOWLEDGE_SLUG_MAX_LENGTH. Returns "" when nothing
+ * survives — callers must validate with isValidKnowledgeSlug before writing.
+ */
+export declare function normalizeKnowledgeSlug(input: string): string;
+/**
+ * The ONE resolution key for [[wikilink]] targets, shared by the tenant-db link
+ * recompute, the graph API, gap-fill, and the web click path. Strips an
+ * Obsidian-style |alias and #heading, then normalizes to slug form, so
+ * [[Founder Voice|our voice]] and [[founder-voice#tone]] both key to
+ * "founder-voice".
+ */
+export declare function knowledgeLinkKey(target: string): string;
+export declare const KNOWLEDGE_LOG_EVENTS: readonly ["seed", "create", "update", "archive", "pin", "ingest", "synth", "lint", "relink", "approve", "reject", "query_filed", "note", "decision"];
+export type KnowledgeLogEvent = typeof KNOWLEDGE_LOG_EVENTS[number];
+export declare const KNOWLEDGE_EXTERNAL_LOG_EVENTS: readonly ["note", "query_filed", "decision"];
+export type KnowledgeExternalLogEvent = typeof KNOWLEDGE_EXTERNAL_LOG_EVENTS[number];
+export declare const KNOWLEDGE_LOG_ACTOR_KINDS: readonly ["user", "agent", "run"];
+export type KnowledgeLogActorKind = typeof KNOWLEDGE_LOG_ACTOR_KINDS[number];
+export declare const KNOWLEDGE_PAGE_SOURCE_KINDS: readonly ["message", "email_message", "meeting", "run", "workflow_run", "table", "table_row", "signal", "url", "manual"];
+export type KnowledgePageSourceKind = typeof KNOWLEDGE_PAGE_SOURCE_KINDS[number];
+export declare const KNOWLEDGE_PAGE_BODY_MAX_CHARS = 120000;
+export declare const KNOWLEDGE_PAGE_SUMMARY_MAX_CHARS = 1000;
+export declare const KNOWLEDGE_GRAPH_DEFAULT_MAX_NODES = 500;
+export declare const KNOWLEDGE_GRAPH_MAX_NODES = 2000;
+export declare const KNOWLEDGE_SYNC_MAX_PAGE_BATCH = 200;
+export declare const RESERVED_KNOWLEDGE_FRONTMATTER_KEYS: readonly ["oxygen_page", "id", "slug", "type", "title", "status", "tags", "canonical", "summary", "revision", "updated_at", "web_url"];

package/node_modules/@oxygen/shared/dist/knowledge-constants.js

@@ -0,0 +1,137 @@
+// Knowledge Graph (workspace wiki) shared constants — the single source of truth
+// for page types, slug grammar, reserved names, log events, and caps across every
+// surface (tenant-db write core, /api/cli/knowledge routes, CLI, MCP tools, web,
+// sync mirror). The Knowledge Graph primitive evolves the legacy "context" store
+// (ox_context.context_assets) into slug-addressed, wikilinked pages; these values
+// must stay in lockstep with the 0103_knowledge_pages.sql CHECK constraints, so
+// change them only together with a migration.
+// All 17 page types: the 12 legacy context-asset types (unchanged wire values —
+// existing rows, canonical pins, and playbookAssetId consumers keep working) plus
+// the 5 wiki page types added by migration 0103.
+export const KNOWLEDGE_PAGE_TYPES = [
+    "playbook",
+    "strategy",
+    "campaign",
+    "positioning",
+    "persona",
+    "competitor",
+    "research_note",
+    "message_playbook",
+    "proposed_playbook_bullet",
+    "voice",
+    "brand",
+    "other",
+    "entity",
+    "topic",
+    "source_summary",
+    "report",
+    "schema",
+];
+// Meta page types that describe the wiki itself (or summarize raw sources) rather
+// than carrying company knowledge — excluded from AI retrieval presets (Phase 3).
+export const KNOWLEDGE_META_PAGE_TYPES = ["schema", "source_summary", "report"];
+export const KNOWLEDGE_PAGE_STATUSES = ["draft", "active", "archived"];
+// Slugs the write path refuses (the scaffold seeder may create `schema`): they are
+// computed projections or virtual pages, never ordinary rows.
+export const RESERVED_KNOWLEDGE_SLUGS = [
+    "index",
+    "log",
+    "schema",
+    "company-profile",
+    "readme",
+];
+export const KNOWLEDGE_SLUG_MAX_LENGTH = 120;
+// Flat kebab grammar: lowercase alphanumeric + dashes, no leading/trailing dash,
+// no slashes (pages are a flat namespace; the graph, tags, and types organize).
+export const KNOWLEDGE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,119}$/;
+export function isValidKnowledgeSlug(value) {
+    return KNOWLEDGE_SLUG_PATTERN.test(value);
+}
+/**
+ * Coerce arbitrary text (a title, a [[wikilink]] target) into slug form:
+ * lowercase, diacritics stripped, every non-alphanumeric run collapsed to one
+ * dash, trimmed, capped at KNOWLEDGE_SLUG_MAX_LENGTH. Returns "" when nothing
+ * survives — callers must validate with isValidKnowledgeSlug before writing.
+ */
+export function normalizeKnowledgeSlug(input) {
+    const collapsed = input
+        .trim()
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/gu, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "");
+    return collapsed.slice(0, KNOWLEDGE_SLUG_MAX_LENGTH).replace(/-+$/, "");
+}
+/**
+ * The ONE resolution key for [[wikilink]] targets, shared by the tenant-db link
+ * recompute, the graph API, gap-fill, and the web click path. Strips an
+ * Obsidian-style |alias and #heading, then normalizes to slug form, so
+ * [[Founder Voice|our voice]] and [[founder-voice#tone]] both key to
+ * "founder-voice".
+ */
+export function knowledgeLinkKey(target) {
+    const bare = (target.split("|")[0] ?? "").split("#")[0] ?? "";
+    return normalizeKnowledgeSlug(bare);
+}
+// Append-only knowledge_log event vocabulary. Must match the CHECK constraint in
+// migration 0103 exactly; render/validation/descriptors derive from this list.
+export const KNOWLEDGE_LOG_EVENTS = [
+    "seed",
+    "create",
+    "update",
+    "archive",
+    "pin",
+    "ingest",
+    "synth",
+    "lint",
+    "relink",
+    "approve",
+    "reject",
+    "query_filed",
+    "note",
+    "decision",
+];
+// The subset external agents may append directly (POST /knowledge/log): filings
+// and free-form notes. Structural events are emitted only by the write core.
+export const KNOWLEDGE_EXTERNAL_LOG_EVENTS = ["note", "query_filed", "decision"];
+export const KNOWLEDGE_LOG_ACTOR_KINDS = ["user", "agent", "run"];
+// Provenance source kinds for page_sources (CHECK in 0103): where a page's
+// knowledge came from. Raw sources are cited by reference, never copied.
+export const KNOWLEDGE_PAGE_SOURCE_KINDS = [
+    "message",
+    "email_message",
+    "meeting",
+    "run",
+    "workflow_run",
+    "table",
+    "table_row",
+    "signal",
+    "url",
+    "manual",
+];
+// Caps. Body cap is TS-enforced (the write core), not a DB CHECK, so it can move
+// without a migration; graph/sync caps bound response payloads.
+export const KNOWLEDGE_PAGE_BODY_MAX_CHARS = 120_000;
+export const KNOWLEDGE_PAGE_SUMMARY_MAX_CHARS = 1_000;
+export const KNOWLEDGE_GRAPH_DEFAULT_MAX_NODES = 500;
+export const KNOWLEDGE_GRAPH_MAX_NODES = 2_000;
+export const KNOWLEDGE_SYNC_MAX_PAGE_BATCH = 200;
+// Frontmatter keys the deterministic renderer owns; user `data` keys colliding
+// with these are skipped at render time (the stored jsonb keeps them).
+export const RESERVED_KNOWLEDGE_FRONTMATTER_KEYS = [
+    "oxygen_page",
+    "id",
+    "slug",
+    "type",
+    "title",
+    "status",
+    "tags",
+    "canonical",
+    "summary",
+    "revision",
+    "updated_at",
+    "web_url",
+];

package/node_modules/@oxygen/shared/dist/knowledge-links.d.ts

@@ -0,0 +1,16 @@
+export type KnowledgeWikilink = {
+    /** Normalized resolution key (slug form) — matches pages by slug. */
+    key: string;
+    /** The bare target as written, alias/heading stripped, untrimmed case kept. */
+    target: string;
+    /** How many times this key occurs in the body. */
+    occurrences: number;
+    /** Character offset of the first occurrence's `[[`. */
+    firstPosition: number;
+};
+/**
+ * Extract every [[wikilink]] from a markdown body, deduplicated by resolution
+ * key with occurrence counts and first positions. Targets that normalize to an
+ * empty key (e.g. [[---]]) are dropped.
+ */
+export declare function extractKnowledgeLinks(body: string | null | undefined): KnowledgeWikilink[];

package/node_modules/@oxygen/shared/dist/knowledge-links.js

@@ -0,0 +1,38 @@
+// The ONE [[wikilink]] parser for the Knowledge Graph. The tenant-db write core
+// recomputes page_links from it on every body write, the graph/lint APIs and the
+// web vault renderer resolve through the same keys, so extraction semantics live
+// here and nowhere else. The regex + alias/heading stripping mirror the vault
+// component's original parser (apps/web/src/components/vault/vault.ts), which
+// now delegates here — [[Target|alias]] and [[Target#heading]] both link to
+// Target.
+import { knowledgeLinkKey } from "./knowledge-constants.js";
+const WIKILINK_RE = /\[\[([^\]]+)\]\]/g;
+/**
+ * Extract every [[wikilink]] from a markdown body, deduplicated by resolution
+ * key with occurrence counts and first positions. Targets that normalize to an
+ * empty key (e.g. [[---]]) are dropped.
+ */
+export function extractKnowledgeLinks(body) {
+    if (!body)
+        return [];
+    const byKey = new Map();
+    WIKILINK_RE.lastIndex = 0;
+    let match;
+    while ((match = WIKILINK_RE.exec(body))) {
+        const inner = match[1] ?? "";
+        const target = (((inner.split("|")[0] ?? "").split("#")[0] ?? "")).trim();
+        if (!target)
+            continue;
+        const key = knowledgeLinkKey(target);
+        if (!key)
+            continue;
+        const existing = byKey.get(key);
+        if (existing) {
+            existing.occurrences += 1;
+        }
+        else {
+            byKey.set(key, { key, target, occurrences: 1, firstPosition: match.index });
+        }
+    }
+    return [...byKey.values()];
+}

package/node_modules/@oxygen/shared/dist/knowledge-markdown.d.ts

@@ -0,0 +1,23 @@
+export type KnowledgePageRenderInput = {
+    id: string;
+    slug: string;
+    type: string;
+    title: string;
+    status: string;
+    tags: string[];
+    canonical: boolean;
+    summary: string | null;
+    revision: number;
+    /** ISO timestamp string — pass a pre-formatted value for determinism. */
+    updatedAt: string;
+    webUrl: string;
+    /** Page frontmatter (the row's `data` jsonb). Only scalar values render. */
+    data: Record<string, unknown>;
+    body: string | null;
+};
+/**
+ * Render a page to its canonical markdown bytes: fixed-order reserved
+ * frontmatter, then the page's own scalar `data` keys sorted, then the body
+ * verbatim with exactly one trailing newline.
+ */
+export declare function renderKnowledgePageMarkdown(page: KnowledgePageRenderInput): string;

package/node_modules/@oxygen/shared/dist/knowledge-markdown.js

@@ -0,0 +1,57 @@
+// Deterministic markdown rendering for Knowledge Graph pages. The SERVER renders
+// every page to bytes with this function and hashes the result (sync/manifest
+// content_sha256); sync clients write those bytes verbatim — the local mirror
+// never re-renders, so renderer drift can't mass-quarantine mirrors. Pure string
+// building (no node imports): safe for web bundles; hashing happens in the API
+// layer. The frontmatter is intentionally parseable by the simple line-based
+// parser in the vault component (key: value lines, tags as [a, b]).
+import { RESERVED_KNOWLEDGE_FRONTMATTER_KEYS } from "./knowledge-constants.js";
+const RESERVED_KEYS = new Set(RESERVED_KNOWLEDGE_FRONTMATTER_KEYS);
+// Frontmatter values are single-line by contract: collapse whitespace runs
+// (including newlines) so the line-based parser can never be broken by content.
+function scalar(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function renderDataValue(value) {
+    if (typeof value === "string")
+        return scalar(value);
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    return null; // objects/arrays/null stay in the stored jsonb only
+}
+/**
+ * Render a page to its canonical markdown bytes: fixed-order reserved
+ * frontmatter, then the page's own scalar `data` keys sorted, then the body
+ * verbatim with exactly one trailing newline.
+ */
+export function renderKnowledgePageMarkdown(page) {
+    const lines = [
+        "---",
+        "oxygen_page: true",
+        `id: ${scalar(page.id)}`,
+        `slug: ${scalar(page.slug)}`,
+        `type: ${scalar(page.type)}`,
+        `title: ${scalar(page.title)}`,
+        `status: ${scalar(page.status)}`,
+        `tags: [${page.tags.map((tag) => scalar(tag)).filter(Boolean).join(", ")}]`,
+        `canonical: ${page.canonical ? "true" : "false"}`,
+        `summary: ${page.summary ? scalar(page.summary) : ""}`,
+        `revision: ${Math.trunc(page.revision)}`,
+        `updated_at: ${scalar(page.updatedAt)}`,
+        `web_url: ${scalar(page.webUrl)}`,
+    ];
+    const extraKeys = Object.keys(page.data)
+        .filter((key) => !RESERVED_KEYS.has(key) && /^[A-Za-z0-9_-]+$/.test(key))
+        .sort();
+    for (const key of extraKeys) {
+        const rendered = renderDataValue(page.data[key]);
+        if (rendered === null)
+            continue;
+        lines.push(`${key}: ${rendered}`);
+    }
+    lines.push("---", "");
+    const body = (page.body ?? "").replace(/\r\n/g, "\n").replace(/\n+$/, "");
+    return `${lines.join("\n")}\n${body}\n`;
+}

package/node_modules/@oxygen/shared/dist/object-storage.d.ts

@@ -3,7 +3,12 @@ export declare function buildImportObjectKey(input: {
     organizationId: string;
     fileName?: string | null;
 }): string;
+export declare function buildPublishingMediaObjectKey(input: {
+    organizationId: string;
+    fileName?: string | null;
+}): string;
 export declare function isImportObjectKeyForOrganization(key: string, organizationId: string): boolean;
+export declare function isPublishingMediaObjectKeyForOrganization(key: string, organizationId: string): boolean;
 export type PresignedImportUpload = {
     uploadUrl: string;
     bucket: string;
@@ -12,20 +17,40 @@ export type PresignedImportUpload = {
     provider: "s3";
     expiresInSeconds: number;
 };
+export type PresignedPublishingMediaUpload = PresignedImportUpload;
 export declare function presignImportUpload(input: {
     organizationId: string;
     fileName?: string | null;
     contentType?: string | null;
     contentLength: number;
 }): Promise<PresignedImportUpload>;
+export declare function presignPublishingMediaUpload(input: {
+    organizationId: string;
+    fileName?: string | null;
+    contentType?: string | null;
+    contentLength: number;
+}): Promise<PresignedPublishingMediaUpload>;
 export declare function getImportObjectMetadata(input: {
     storageKey: string;
 }): Promise<{
     contentLength: number | null;
 }>;
+export declare function getPublishingMediaObjectMetadata(input: {
+    storageKey: string;
+}): Promise<{
+    contentLength: number | null;
+    contentType: string | null;
+}>;
 export declare function openImportObjectStream(input: {
     storageKey: string;
 }): Promise<NodeJS.ReadableStream>;
+export declare function openPublishingMediaObjectStream(input: {
+    storageKey: string;
+}): Promise<NodeJS.ReadableStream>;
+export declare function presignPublishingMediaDownload(input: {
+    storageKey: string;
+    expiresInSeconds?: number;
+}): Promise<string>;
 export declare function deleteImportObject(input: {
     storageKey: string;
 }): Promise<void>;