@oxygen-agent/cli 1.1011.326 → 1.1011.440

package/dist/knowledge-repository-commands.js

@@ -1,6 +1,7 @@
 import { readFile, writeFile, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
+import { OxygenError } from "@oxygen/shared/cli-result";
 import { requestOxygen } from "./http-client.js";
 const post = (path, body) => {
     if (Buffer.byteLength(JSON.stringify(body)) > 2_000_000)
@@ -99,21 +100,14 @@ export function registerKnowledgeRepositoryCommands(program, handle) {
         .option("--cursor <cursor>", "Continue the previous page.")
         .option("--limit <number>", "Maximum files, up to 500.", "100")
         .option("--json", "Print a JSON envelope.")
-        .action((o) => handle("knowledge files list", o, () => post("files/list", {
-        mountId: o.mountId,
-        limit: Number(o.limit),
-        ...(o.cursor ? { cursor: o.cursor } : {}),
-    })));
+        .action((o) => handle("knowledge files list", o, () => requestOxygen(`/api/cli/knowledge/files/list?${new URLSearchParams({ mountId: String(o.mountId), limit: String(o.limit), ...(o.cursor ? { cursor: String(o.cursor) } : {}) })}`)));
     files
         .command("get")
         .description("Read original file content, properties and download link at an optional immutable revision.")
         .requiredOption("--id <id>", "File ID from files list.")
         .option("--revision <number>", "Specific saved file revision.")
         .option("--json", "Print a JSON envelope.")
-        .action((o) => handle("knowledge files get", o, () => post("files/get", {
-        id: o.id,
-        ...(o.revision ? { revision: Number(o.revision) } : {}),
-    })));
+        .action((o) => handle("knowledge files get", o, () => requestOxygen(`/api/cli/knowledge/files/get?${new URLSearchParams({ id: String(o.id), ...(o.revision ? { revision: String(o.revision) } : {}) })}`)));
     files
         .command("upsert")
         .description("Create or replace an original file, or update frontmatter properties. Canonical copy still requires a proposal.")
@@ -122,11 +116,15 @@ export function registerKnowledgeRepositoryCommands(program, handle) {
         .option("--path <path>", "Exact repository-relative path; required for new files.")
         .requiredOption("--expected-revision <number>", "Reviewed file revision; 0 creates a new file.")
         .option("--file <path>", "Complete local file, including any frontmatter or binary bytes.")
-        .option("--properties-json <json>", "Frontmatter properties to change; mutually exclusive with --file.")
+        .option("--text <text>", "Exact UTF-8 content; exclusive with --file and --properties-json.")
+        .option("--properties-json <json>", "Frontmatter properties to change; exclusive with --file and --text.")
         .option("--json", "Print a JSON envelope.")
         .action((o) => handle("knowledge files upsert", o, async () => {
-        if (Boolean(o.file) === Boolean(o.propertiesJson))
-            throw new Error("Provide exactly one of --file or --properties-json.");
+        if ([o.file, o.text, o.propertiesJson].filter((value) => value !== undefined).length !== 1)
+            throw new OxygenError("invalid_request", "Provide exactly one of --file, --text or --properties-json.", { exitCode: 2 });
+        const expectedRevision = Number(o.expectedRevision);
+        if (!String(o.expectedRevision ?? "").trim() || !Number.isSafeInteger(expectedRevision) || expectedRevision < 0)
+            throw new OxygenError("invalid_request", "--expected-revision must be a nonnegative integer.", { exitCode: 2 });
         if (o.file && (await stat(String(o.file))).size > 1_500_000)
             throw new Error("Inline file uploads must fit a 2 MB JSON request (including base64). Add larger attachments through the connected GitHub repository.");
         const patch = o.propertiesJson
@@ -139,12 +137,12 @@ export function registerKnowledgeRepositoryCommands(program, handle) {
             mountId: o.mountId,
             ...(o.id ? { id: o.id } : {}),
             ...(o.path ? { path: o.path } : {}),
-            expectedFileRevision: Number(o.expectedRevision),
+            expectedFileRevision: expectedRevision,
             ...(o.file
                 ? {
                     bytesBase64: (await readFile(String(o.file))).toString("base64"),
                 }
-                : { propertyPatch: patch }),
+                : o.text !== undefined ? { text: String(o.text) } : { propertyPatch: patch }),
         });
     }));
     files

package/dist/mailbox-ramp-notice.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A mailbox's campaign ramp-up as one terminal line, after `mailboxes get`,
+ * `mailboxes ramp set` and `mailboxes cap set`. The blind baselines (2026-10-01)
+ * had to work out by hand on which sending day a custom ramp reaches the daily
+ * cap, and agents read the end of the output, so the schedule, today's limit and
+ * that day are restated here from the envelope's `effective_cap`.
+ *
+ * Returns null unless the envelope carries `effective_cap.ramp_schedule`, so
+ * every other command prints nothing.
+ */
+export declare function formatMailboxRampNotice(data: unknown): string | null;

package/dist/mailbox-ramp-notice.js

@@ -0,0 +1,53 @@
+import { isRecord } from "./util.js";
+/**
+ * A mailbox's campaign ramp-up as one terminal line, after `mailboxes get`,
+ * `mailboxes ramp set` and `mailboxes cap set`. The blind baselines (2026-10-01)
+ * had to work out by hand on which sending day a custom ramp reaches the daily
+ * cap, and agents read the end of the output, so the schedule, today's limit and
+ * that day are restated here from the envelope's `effective_cap`.
+ *
+ * Returns null unless the envelope carries `effective_cap.ramp_schedule`, so
+ * every other command prints nothing.
+ */
+export function formatMailboxRampNotice(data) {
+    if (!isRecord(data) || !isRecord(data.effective_cap))
+        return null;
+    const cap = data.effective_cap;
+    if (!Array.isArray(cap.ramp_schedule))
+        return null;
+    const steps = cap.ramp_schedule.flatMap((step) => isRecord(step) && typeof step.per_day === "number" ? [step.per_day] : []);
+    const configured = numberOrNull(cap.configured_daily_cap);
+    const today = numberOrNull(cap.effective_daily_cap);
+    const fullOn = numberOrNull(cap.full_cap_on_sending_day);
+    const sendingDays = numberOrNull(cap.sending_days) ?? 0;
+    if (configured === null || today === null || steps.length === 0)
+        return null;
+    const address = isRecord(data.mailbox) && typeof data.mailbox.emailAddress === "string"
+        ? ` for ${data.mailbox.emailAddress}`
+        : "";
+    const todayLine = `today up to ${today}.`;
+    if (cap.ramp_mode === "off") {
+        return `Campaign ramp-up${address}: off, the daily cap of ${configured} applies from the first sending day; ${todayLine}`;
+    }
+    const mode = cap.ramp_mode === "custom" ? "custom" : "standard";
+    const currentDay = sendingDays + 1;
+    if (fullOn !== null && currentDay >= fullOn) {
+        return `Campaign ramp-up${address} (${mode}) is complete: ${todayLine}`;
+    }
+    const schedule = `${formatSteps(steps)} a day`;
+    const end = fullOn === null
+        ? `It holds at ${steps[steps.length - 1]} a day and never reaches the daily cap of ${configured}.`
+        : `It reaches the daily cap of ${configured} on sending day ${fullOn}.`;
+    return `Campaign ramp-up${address} (${mode}): ${schedule}. Today is sending day ${currentDay}: up to ${today}. ${end}`
+        + " A day counts toward the ramp once it has accepted campaign sends (UTC).";
+}
+function numberOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/** "5 → 10 → 20 → 25", shortened to its first three and last two levels past eight. */
+function formatSteps(levels) {
+    const shown = levels.length > 8
+        ? [...levels.slice(0, 3).map(String), "…", ...levels.slice(-2).map(String)]
+        : levels.map(String);
+    return shown.join(" → ");
+}

package/dist/settings-commands.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { type ContractFlagOverlay } from "./contract-flags.js";
+type JsonOptions = {
+    json?: boolean;
+};
+type Handle = (command: string, options: JsonOptions, action: () => Promise<unknown>) => Promise<void>;
+export declare const WORKSPACE_PAGES_FLAG_OVERLAY: ContractFlagOverlay;
+/** The POST body for the flags given; --hide, --show or --show-all is required. */
+export declare function buildWorkspacePagesBody(options: Record<string, unknown>): Record<string, unknown>;
+export declare function registerSettingsCommands(program: Command, handle: Handle): void;
+export {};

package/dist/settings-commands.js

@@ -0,0 +1,73 @@
+// `oxygen settings`: workspace settings every member reads and admins change.
+// Its family today is `settings pages`, the web app's sidebar pages a workspace
+// hides for everyone (Settings → Customise). The set command's flags come from
+// the shared contract that also generates `oxygen_settings_pages_update` and
+// validates the route, so the CLI and MCP cannot disagree about what can be set.
+import { Command } from "commander";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { WORKSPACE_PAGES_GET_OPERATION, WORKSPACE_PAGES_UPDATE_OPERATION } from "@oxygen/shared/contracts/workspace-pages";
+import { addContractFlags, readContractFlags } from "./contract-flags.js";
+import { requestOxygen } from "./http-client.js";
+const list = WORKSPACE_PAGES_GET_OPERATION;
+const update = WORKSPACE_PAGES_UPDATE_OPERATION;
+export const WORKSPACE_PAGES_FLAG_OVERLAY = {
+    hide: {
+        help: "Pages to hide from the sidebar for everyone, comma-separated, each by its path (/unibox) or name (Unibox) from `settings pages list`. Hiding a section hides its sub-pages.",
+        valueName: "<pages>",
+    },
+    show: {
+        help: "Hidden pages to show again, comma-separated, by path or name.",
+        valueName: "<pages>",
+    },
+    show_all: {
+        help: "Show every page again. With --hide, only those pages stay hidden.",
+        // `--no-show-all` would change nothing, and reads like "hide all".
+        noNegate: true,
+    },
+};
+function names(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+/** The POST body for the flags given; --hide, --show or --show-all is required. */
+export function buildWorkspacePagesBody(options) {
+    const body = readContractFlags(options, update.contract, WORKSPACE_PAGES_FLAG_OVERLAY);
+    if (!names(body.hide) && !names(body.show) && body.show_all !== true) {
+        throw new OxygenError("invalid_request", "Nothing to change: pass --hide <pages> to hide pages for everyone, --show <pages> to show hidden ones again, or --show-all. `settings pages list` names every page.", { exitCode: 1 });
+    }
+    return body;
+}
+export function registerSettingsCommands(program, handle) {
+    const settings = program
+        .command("settings")
+        .description("Workspace settings: what every member of this workspace sees. "
+        + "`settings pages` is Settings → Customise in the web app: hide or show pages in the sidebar navigation (the left menu) for everyone. "
+        + "`settings pages list` shows each page and whether it is hidden; an admin or owner changes it with `settings pages set --hide <pages>`, `--show <pages>` or `--show-all`. "
+        + "Nothing is deleted: a hidden page stays reachable by URL. Free.");
+    const pages = new Command("pages")
+        .description("The web app's sidebar pages this workspace hides for every member (Settings → Customise): page visibility in the navigation menu. "
+        + "`list` shows every page with its section and whether it is hidden or visible; `set` hides or shows pages (admins and owners only). "
+        + "Hiding a section hides its sub-pages. Presentation only: nothing is deleted, and a hidden page stays reachable by URL and deep-link. Every response carries its `web_url`.");
+    pages.addCommand(new Command(list.cli.path.at(-1) ?? "list")
+        .description(list.cli.summary)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handle("settings pages list", options, () => requestOxygen(list.route, { method: list.method }));
+    }));
+    pages.addCommand(addContractFlags(new Command(update.cli.path.at(-1) ?? "set").description(update.cli.summary), update.contract, WORKSPACE_PAGES_FLAG_OVERLAY)
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Examples:
+  oxygen settings pages list
+  oxygen settings pages set --hide Unibox,Publishing
+  oxygen settings pages set --show /unibox
+  oxygen settings pages set --show-all
+  oxygen settings pages set --show-all --hide Workflows
+`)
+        .action(async (options) => {
+        await handle("settings pages set", options, () => requestOxygen(update.route, {
+            method: update.method,
+            body: buildWorkspacePagesBody(options),
+        }));
+    }));
+    settings.addCommand(pages);
+}

package/dist/skills.d.ts

@@ -18,7 +18,9 @@ export type SkillsListOptions = {
 export type SkillsSearchOptions = SkillsListOptions & {
     limit?: string;
 };
-export type SkillsGetOptions = SkillsListOptions;
+export type SkillsGetOptions = SkillsListOptions & {
+    file?: string;
+};
 export type SkillsDoctorOptions = {
     json?: boolean;
     apiUrl?: string;
@@ -49,9 +51,8 @@ export type SkillsSourceRuntime = {
 };
 /**
  * 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.
+ * org-bound access URL. Any failure leaves public metadata discovery usable;
+ * downloading instruction bodies always requires the authenticated source.
  */
 export declare function resolveSkillsInstallSource(options: {
     apiUrl: string;

package/dist/skills.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, posix, resolve } from "node:path";
 import { OxygenError, errorMessage, inferUserCapabilityRoute, serializeCapabilityRoute, toFailure, } from "@oxygen/shared";
 import { defaultApiUrl, loadCredentials, normalizeApiUrl } from "./credentials.js";
 import { requestOxygen } from "./http-client.js";
@@ -22,9 +22,8 @@ const AGENT_DISPLAY_NAMES = {
 };
 /**
  * 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.
+ * org-bound access URL. Any failure leaves public metadata discovery usable;
+ * downloading instruction bodies always requires the authenticated source.
  */
 export async function resolveSkillsInstallSource(options) {
     const publicSource = (reason) => ({
@@ -51,7 +50,7 @@ export async function resolveSkillsInstallSource(options) {
             credentials,
             ...(options.fetch ? { fetch: options.fetch } : {}),
         });
-        if (!access?.base_url?.trim() || !access?.index_url?.trim()) {
+        if (!isValidSkillsAccessResponse(access, options.apiUrl)) {
             return publicSource("invalid_access_response");
         }
         return {
@@ -66,8 +65,21 @@ export async function resolveSkillsInstallSource(options) {
         return publicSource(`access_unavailable:${code}`);
     }
 }
+function isValidSkillsAccessResponse(access, apiUrl) {
+    try {
+        const base = new URL(access.base_url);
+        const api = new URL(apiUrl);
+        return base.origin === api.origin && !base.username && !base.password && !base.search && !base.hash
+            && /^\/skills-access\/[^/]+$/.test(base.pathname)
+            && access.index_url === `${access.base_url}/.well-known/skills/index.json`
+            && Number.isFinite(Date.parse(access.expires_at)) && Date.parse(access.expires_at) > Date.now();
+    }
+    catch {
+        return false;
+    }
+}
 function requireSkillContentAccess(index, source) {
-    if (!index.authentication_required)
+    if (source.authenticated && !index.authentication_required)
         return;
     throw new OxygenError("skills_authentication_required", "Sign in to download Oxygen agent instructions.", {
         details: {
@@ -122,7 +134,7 @@ export async function searchAgentSkills(query, options, runtime = {}) {
         .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
     return {
         query: normalized,
-        route: serializeCapabilityRoute(route),
+        route: serializeCapabilityRoute(route, { visibleSkills: index.skill_names }),
         total_matches: matches.length,
         returned: Math.min(limit, matches.length),
         skills: matches.slice(0, limit).map(({ skill, score, matching_documents }) => ({
@@ -140,41 +152,27 @@ export async function searchAgentSkills(query, options, runtime = {}) {
 }
 export async function getAgentSkill(skillName, options, runtime = {}) {
     const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
-    const source = await resolveSkillsInstallSource({ apiUrl, ...runtime });
-    const index = await inspectSkillIndex(source.index_url, runtime.fetch);
-    if (!index.reachable) {
-        throw new OxygenError("skills_index_unreachable", "Oxygen skill index is not reachable.", {
-            details: { index_url: source.index_url, error: index.error },
-            exitCode: 1,
+    const credentials = runtime.credentials !== undefined ? runtime.credentials : await loadCredentials();
+    if (!credentials || normalizeApiUrl(credentials.apiUrl) !== apiUrl) {
+        throw new OxygenError("skills_authentication_required", "Sign in to download Oxygen agent instructions.", {
+            details: { next_step: "Run `oxygen login`, then retry `oxygen skills get`." }, exitCode: 1,
         });
     }
-    requireSkillContentAccess(index, source);
     const normalized = skillName.trim();
-    const skill = index.skills.find((entry) => entry.name === normalized);
-    if (!skill) {
-        throw new OxygenError("skill_not_found", `Unknown Oxygen skill: ${normalized}`, {
-            details: { available_names: index.skill_names },
+    const file = readOption(options.file)?.trim() ?? "SKILL.md";
+    if (!isSafeSkillName(normalized) || !isSafeSkillFile(file)) {
+        throw new OxygenError("skill_file_not_found", `Unknown file in Oxygen skill ${normalized}.`, {
+            details: { file },
             exitCode: 2,
         });
     }
-    if (!skill.entrypoint) {
-        throw new OxygenError("skill_entrypoint_missing", `Oxygen skill ${normalized} has no entrypoint.`, {
-            exitCode: 1,
-        });
-    }
-    const fetchImpl = runtime.fetch ?? fetch;
-    const response = await fetchImpl(skill.entrypoint, { headers: { Accept: "text/markdown" } });
-    if (!response.ok) {
-        throw new OxygenError("skill_entrypoint_unreachable", `Unable to hydrate Oxygen skill ${normalized}.`, {
-            details: { status: response.status },
-            exitCode: 1,
-        });
-    }
-    const content = await response.text();
+    const params = new URLSearchParams({ name: normalized, file });
+    const skill = await requestOxygen(`/api/cli/skills/get?${params}`, {
+        method: "GET", credentials, ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
+    });
     return {
         ...skill,
-        content,
-        install: `oxygen skills install --skill ${skill.name} --json`,
+        install: `oxygen skills install --skill ${normalized} --json`,
     };
 }
 export async function doctorAgentSkills(options, runtime = {}) {
@@ -215,12 +213,10 @@ options, runtime = {}) {
         ...(runtime.credentials !== undefined ? { credentials: runtime.credentials } : {}),
         ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
     });
-    if (!source.authenticated) {
-        // Public discovery remains usable. New servers explicitly mark that their
-        // instruction bodies require a signed workspace link; never invoke the
-        // installer against that discovery-only catalog.
-        requireSkillContentAccess(await inspectSkillIndex(source.index_url, runtime.fetch), source);
-    }
+    // The client also fails closed against older servers whose catalog predates
+    // authentication_required. Metadata can never authorize a content download.
+    if (!source.authenticated)
+        requireSkillContentAccess(emptySkillIndexInspection({ status: null, error: { code: "skills_authentication_required", message: "Sign in to download skills." } }), source);
     const agents = readWords(options.agents ?? DEFAULT_SKILL_AGENTS);
     const skill = readOption(options.skill) ?? "*";
     const env = runtime.env ?? process.env;
@@ -236,9 +232,8 @@ options, runtime = {}) {
         .join(", ")}\n`);
     // A specific shortcut skill can declare prerequisite skills that its SKILL.md
     // invokes (e.g. oxygen-clay-migration → oxygen-gtm, whose recipes it lives in).
-    // Installing it alone would leave those missing, so pull them in too. Best-
-    // effort (an unreachable/unparseable index just installs the requested skill),
-    // and skipped for "*", which already installs everything.
+    // Installing it alone would leave those missing, so resolve its full graph
+    // before writing files. "*" already installs every visible skill.
     const dependencySkills = skill === "*"
         ? []
         : await resolveSkillInstallDependencies(skill, source.index_url, runtime.fetch);
@@ -247,18 +242,15 @@ options, runtime = {}) {
     // reach the installer's argv — any local process can read a child's
     // arguments. Stage the requested skill content to a private temp dir (the
     // tokenized URLs stay inside this process on the fetches) and hand the
-    // installer that local path instead. The public, non-secret index URL is
-    // passed straight through as before.
+    // installer that local path instead.
     let stagingDir = null;
     const outputs = [];
     const skippedTargets = [];
     try {
         let installSource = source.install_url;
-        if (source.authenticated) {
-            stagingDir = mkdtempSync(join(tmpdir(), "oxygen-skills-"));
-            await stageAuthenticatedSkills(stagingDir, source, targets, runtime.fetch ?? fetch);
-            installSource = stagingDir;
-        }
+        stagingDir = mkdtempSync(join(tmpdir(), "oxygen-skills-"));
+        await stageAuthenticatedSkills(stagingDir, source, targets, runtime.fetch ?? fetch);
+        installSource = stagingDir;
         for (const target of targets) {
             const args = installerAddArgs(installSource, agents, target);
             if (!options.project)
@@ -393,6 +385,10 @@ async function stageAuthenticatedSkills(dir, source, targets, fetchImpl) {
     const wanted = targets.includes("*")
         ? entries
         : entries.filter((entry) => targets.includes(entry.name));
+    const missing = targets.includes("*") ? [] : targets.filter((target) => !wanted.some((entry) => entry.name === target));
+    if (wanted.length === 0 || missing.length > 0) {
+        throw stagingFailure("select_skills", { missing_skills: missing });
+    }
     // `<base>/.well-known/skills/index.json` → `<base>/.well-known/skills`; the
     // installer reads a skill's files from `<root>/<name>/<file>`.
     const skillsRoot = source.index_url.replace(/\/index\.json$/i, "");
@@ -412,7 +408,7 @@ async function stageAuthenticatedSkills(dir, source, targets, fetchImpl) {
                     const content = await fetchStagedSkillFile(`${skillsRoot}/${entry.name}/${file}`, fetchImpl);
                     const destination = join(dir, entry.name, ...file.split("/"));
                     mkdirSync(dirname(destination), { recursive: true });
-                    writeFileSync(destination, content);
+                    writeFileSync(destination, localizeSkillLinks(content, skillsRoot, entry.name, file));
                 }
                 catch (error) {
                     failure ??= error;
@@ -430,7 +426,7 @@ const STAGED_FILE_RETRY_DELAYS_MS = [250, 1_000];
 async function fetchStagedSkillEntries(indexUrl, fetchImpl) {
     let response;
     try {
-        response = await fetchImpl(indexUrl, { headers: { Accept: "application/json" } });
+        response = await fetchImpl(indexUrl, { headers: { Accept: "application/json" }, redirect: "error" });
     }
     catch (error) {
         throw stagingFailure("fetch_index", { index_url: indexUrl, message: errorMessage(error) });
@@ -448,14 +444,21 @@ async function fetchStagedSkillEntries(indexUrl, fetchImpl) {
     if (!isRecord(parsed) || !Array.isArray(parsed.skills)) {
         throw stagingFailure("parse_index", { index_url: indexUrl, message: "skills array missing" });
     }
+    if (parsed.authentication_required === true) {
+        throw stagingFailure("fetch_index", { message: "Authenticated skill content is unavailable." });
+    }
     const entries = [];
     for (const entry of parsed.skills) {
-        if (!isRecord(entry) || typeof entry.name !== "string" || !entry.name.trim())
-            continue;
+        if (!isRecord(entry) || typeof entry.name !== "string" || !isSafeSkillName(entry.name)) {
+            throw stagingFailure("parse_index", { message: "Invalid skill name." });
+        }
         const files = Array.isArray(entry.files)
             ? entry.files.filter((file) => typeof file === "string" && file.trim().length > 0)
             : [];
-        entries.push({ name: entry.name.trim(), files });
+        if (!files.includes("SKILL.md") || files.some((file) => !isSafeSkillFile(file)) || new Set(files).size !== files.length || entries.some((candidate) => candidate.name === entry.name)) {
+            throw stagingFailure("parse_index", { message: "Invalid skill files.", skill: entry.name });
+        }
+        entries.push({ name: entry.name, files });
     }
     return entries;
 }
@@ -464,7 +467,7 @@ async function fetchStagedSkillFile(url, fetchImpl) {
     for (let attempt = 0;; attempt += 1) {
         let details;
         try {
-            const response = await fetchImpl(url, { signal: AbortSignal.timeout(STAGED_FILE_TIMEOUT_MS) });
+            const response = await fetchImpl(url, { signal: AbortSignal.timeout(STAGED_FILE_TIMEOUT_MS), redirect: "error" });
             if (response.ok)
                 return await response.text();
             if (response.status !== 429 && response.status < 500) {
@@ -483,6 +486,28 @@ async function fetchStagedSkillFile(url, fetchImpl) {
         await new Promise((resolve) => setTimeout(resolve, delay));
     }
 }
+function isSafeSkillName(name) {
+    return name.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
+function isSafeSkillFile(file) {
+    return /^[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)*$/.test(file)
+        && file.split("/").every((part) => part !== "." && part !== "..");
+}
+/** Installed references survive token expiry and stay within installed skills. */
+function localizeSkillLinks(content, skillsRoot, skill, file) {
+    if (!file.endsWith(".md"))
+        return content;
+    return content.replace(/\]\((https?:\/\/[^)\s]+)\)/g, (match, url) => {
+        if (!url.startsWith(`${skillsRoot}/`))
+            return match;
+        const target = url.slice(skillsRoot.length + 1);
+        const [name, ...parts] = target.split("/");
+        const relativeFile = parts.join("/").split("#")[0];
+        if (!name || !isSafeSkillName(name) || !isSafeSkillFile(relativeFile))
+            return match;
+        return `](${posix.relative(posix.dirname(`${skill}/${file}`), target)})`;
+    });
+}
 // Mirror the installer-failure error so a staging failure surfaces identically
 // (code, message, exitCode) to the caller — never as a silent URL fallback.
 function stagingFailure(stage, details) {
@@ -491,31 +516,33 @@ function stagingFailure(stage, details) {
         exitCode: 1,
     });
 }
-// Best-effort resolution of a skill's declared prerequisite skills from the
-// index. Any failure (unreachable index, parse error, unknown skill) yields no
-// dependencies so a dependency lookup can never block or fail an install.
+// A dependency is part of the selected skill's operable contract. Resolve the
+// full graph before installation; missing dependencies and cycles fail closed.
 async function resolveSkillInstallDependencies(skill, indexUrl, fetchImpl) {
-    try {
-        const index = await inspectSkillIndex(indexUrl, fetchImpl ?? fetch);
-        if (!index.reachable)
-            return [];
-        const entry = index.skills.find((candidate) => candidate.name === skill);
+    const index = await inspectSkillIndex(indexUrl, fetchImpl ?? fetch);
+    if (!index.reachable)
+        throw stagingFailure("fetch_index", { message: "Unable to resolve skill dependencies." });
+    const resolved = [];
+    const visited = new Set();
+    const visiting = new Set();
+    const visit = (name) => {
+        if (visiting.has(name))
+            throw stagingFailure("skill_dependencies", { message: "Circular skill dependency.", skill: name });
+        if (visited.has(name))
+            return;
+        const entry = index.skills.find((candidate) => candidate.name === name);
         if (!entry)
-            return [];
-        // Drop self-references and duplicates; preserve declared order.
-        const seen = new Set([skill]);
-        const resolved = [];
-        for (const dep of entry.dependencies) {
-            if (seen.has(dep))
-                continue;
-            seen.add(dep);
-            resolved.push(dep);
-        }
-        return resolved;
-    }
-    catch {
-        return [];
-    }
+            throw stagingFailure("select_skills", { missing_skills: [name] });
+        visiting.add(name);
+        for (const dependency of entry.dependencies)
+            visit(dependency);
+        visiting.delete(name);
+        visited.add(name);
+        if (name !== skill)
+            resolved.push(name);
+    };
+    visit(skill);
+    return resolved;
 }
 // Adapt the legacy `execFileSync` runtime hook into a spawnSync-shaped return so
 // existing test fixtures (update.test.ts) keep working without a coordinated

package/dist/tool-catalog-detail-command.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+type Handle = (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>;
+/** Legacy no-flag invocation keeps the complete descriptor. */
+export declare function createToolCatalogDetailCommand(handle: Handle): Command;
+export {};

package/dist/tool-catalog-detail-command.js

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import { toolCatalogDetailQueryContract } from "@oxygen/shared/contracts/tool-catalog-detail";
+import { addContractFlags, readContractFlags } from "./contract-flags.js";
+import { requestOxygen } from "./http-client.js";
+/** Legacy no-flag invocation keeps the complete descriptor. */
+export function createToolCatalogDetailCommand(handle) {
+    return addContractFlags(new Command("get")
+        .description("Get native tool metadata. Full by default; explicit views report omissions and retain exact schemas. Executable MCP definitions use capabilities schema.")
+        .argument("<tool_id>", "Tool id.")
+        .option("--json", "Print a JSON envelope."), toolCatalogDetailQueryContract)
+        .action(async (toolId, options) => {
+        await handle("tools get", options, async () => {
+            const query = readContractFlags(options, toolCatalogDetailQueryContract);
+            const params = new URLSearchParams(Object.entries(query).map(([key, value]) => [key, Array.isArray(value) ? value.join(",") : String(value)]));
+            const suffix = params.size ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/tools/${encodeURIComponent(toolId)}${suffix}`);
+        });
+    });
+}

package/dist/tool-catalog-search-window.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+export declare function addToolCatalogSearchWindowFlag(command: Command): Command;
+export declare function readToolCatalogSearchWindow(options: Record<string, unknown>): {
+    max_chars?: number;
+    include_native?: boolean;
+};

package/dist/tool-catalog-search-window.js

@@ -0,0 +1,12 @@
+import { toolCatalogSearchWindowContract } from "@oxygen/shared/contracts/tool-catalog-search-window";
+import { addContractFlags, readContractFlags } from "./contract-flags.js";
+export function addToolCatalogSearchWindowFlag(command) {
+    return addContractFlags(command, toolCatalogSearchWindowContract, { workflow_eligible: { omit: true } });
+}
+export function readToolCatalogSearchWindow(options) {
+    const body = readContractFlags(options, toolCatalogSearchWindowContract, { workflow_eligible: { omit: true } });
+    return {
+        ...(typeof body.max_chars === "number" ? { max_chars: body.max_chars } : {}),
+        ...(typeof body.include_native === "boolean" ? { include_native: body.include_native } : {}),
+    };
+}

package/dist/transcript.js

@@ -129,6 +129,7 @@ const SECRET_PATTERNS = [
     [/\bgh[pousr]_[A-Za-z0-9]{20,}/g, "ghx_[REDACTED]"],
     [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, "xox-[REDACTED]"],
     [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{6,}/g, "[REDACTED_JWT]"],
+    [/\/skills-access\/v1\.[A-Za-z0-9_-]+\.\d+\.[A-Za-z0-9_-]+/g, "/skills-access/[REDACTED_GRANT]"],
     [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{16,}/gi, "$1 [REDACTED]"],
     // "secret-ish key": "value"  /  secret_ish_key=value  (JSON + env shapes)
     [/("?(?:api[_-]?key|apikey|secret|password|passwd|token|access[_-]?token|refresh[_-]?token|client[_-]?secret|authorization|auth[_-]?token|private[_-]?key)"?\s*[:=]\s*"?)([^"\s,}]{6,})/gi, "$1[REDACTED]"],

package/node_modules/@oxygen/shared/dist/bounded-read-result.d.ts

@@ -0,0 +1,4 @@
+/** Complete native receipt sizing for optional bounded JSON reads. Binary
+ * windows have their own outer-envelope budget and must not use this helper.
+ * The surface is a formatting hint, never authorization or spend authority. */
+export declare function boundedReadResultFits(command: string, data: Record<string, unknown>, maxChars: number | undefined, surface: string | null | undefined, maxAgentResultChars?: number): boolean;