@clipit-ai/cli 0.2.9 → 0.3.0

package/README.md

@@ -59,6 +59,10 @@ clipit auth open-settings
 clipit auth profiles --json
 clipit auth use <profile>
 clipit skills list --json
+clipit skills describe <skill-or-bundle-id> --json
+clipit skills manifest --json
+clipit media-guides list --json
+clipit media-guides describe <guide-id> --json
 clipit tools list --json
 clipit tools describe <functionName> --json
 clipit run <functionName> --params @params.json --max-credits 25 --json
@@ -110,7 +114,7 @@ clipit exports wait <jobId> --stream
 clipit exports download <jobId> --open
 clipit exports cancel <jobId> --confirm --json
 
-clipit deliverables create --export-id <exportId> --title "Client-ready clip" --confirm --json
+clipit deliverables create --export-id <exportId> --confirm --json
 clipit deliverables list --status selected --json
 
 clipit assets list --json
@@ -204,7 +208,14 @@ clipit workflow approve <jobId> --approval-id <approvalId> --decision cheaper
 
 ## MCP Stdio Bridge
 
-Use `clipit mcp stdio` from MCP-compatible clients that can launch a local command. It speaks standard MCP `Content-Length` framed JSON-RPC over stdio, exposes ClipIt agent tools through the authenticated CLI profile, supports `initialize`, `tools/list`, and `tools/call`, and delegates execution to `/api/v1/agent/execute`.
+Use `clipit mcp stdio` from MCP-compatible clients that can launch a local command. It speaks standard MCP `Content-Length` framed JSON-RPC over stdio and exposes both executable ClipIt tools and read-only capability resources through the authenticated CLI profile. Tool calls delegate to `/api/v1/agent/execute`; capability resources are resolved from the live permission-scoped agent registry.
+
+Supported MCP methods include `initialize`, `tools/list`, `tools/call`, `resources/list`, and `resources/read`. The resource catalog uses stable URIs:
+
+- `clipit://instructions` — the installed agent operating contract
+- `clipit://manifest` — versions, checksums, available capabilities, and the current model estate
+- `clipit://skills/<id>` — one full skill or workflow-bundle guide
+- `clipit://media-guides/<id>` — one provider-aware media prompting guide
 
 Paid generation, publishing, deletion, and other metered tools still require an explicit confirmation step. If a tool call may spend credits or mutate user-visible ClipIt state, the MCP bridge returns a `requiresConfirmation` result instead of executing it; retry only after the user approves and include `confirmed: true` in the tool arguments.
 
@@ -218,7 +229,11 @@ clipit links clip <clipId> --download --json
 
 ## Agent Skills
 
-Install credential-free instructions for a shell-capable agent. The CLI fetches server-rendered instructions from `/api/v1/agent/instructions?target=<agent>&format=json` when authenticated. If the fetch fails or the CLI is offline, it installs a generic fallback skill and records the source in `SKILL.meta.json` next to `SKILL.md`.
+Install credential-free instructions for a shell-capable agent. The CLI fetches server-rendered instructions from `/api/v1/agent/instructions?target=<agent>&format=json` when authenticated. A server-rendered install contains a concise root `SKILL.md` plus permission-scoped `references/` for editorial workflow, state/time/trust rules, the capability manifest, relevant skills and workflows, and media prompting guides. The agent loads those references progressively as the edit requires them instead of carrying the entire platform manual in every turn.
+
+The root skill establishes one execution owner for mutating work and a repeatable edit loop: inspect, plan, edit, review, render, and deliver. Live tool schemas, the capability manifest, provider contracts, and server estimates remain authoritative over copied examples or remembered model behavior.
+
+If the fetch fails or the CLI is offline, the installer writes a generic fallback skill and records the source in `SKILL.meta.json` next to `SKILL.md`.
 
 ```bash
 clipit agent install codex
@@ -227,7 +242,7 @@ clipit agent install hermes
 clipit agent install generic
 ```
 
-Inspect or remove generated skills:
+Inspect, refresh, or remove generated skills:
 
 ```bash
 clipit agent doctor codex --json
@@ -237,6 +252,8 @@ clipit agent uninstall codex
 clipit agent print-skill generic
 ```
 
+`agent doctor` validates the generated root skill and its reference files against the sidecar hashes. Install/update also rejects a live pack whose declared minimum CLI version is newer than the running CLI and tells the operator to install `@clipit-ai/cli@latest`. After reconnecting, run `agent update` to replace an offline fallback or refresh a stale capability-manifest version.
+
 ## Profiles And Environment
 
 The default profile is `default`.
@@ -274,7 +291,7 @@ Only use `--allow-custom-host` for hosts you control or trust. It permits the CL
 | Area | Commands | Notes |
 | --- | --- | --- |
 | Auth and setup | `login`, `setup`, `logout`, `doctor`, `auth status`, `auth set-key`, `auth open-settings`, `auth profiles`, `auth use` | Browser-link login, manual key fallback, and fail-closed named workspace profiles. |
-| Agent tools | `skills list`, `tools list`, `tools describe`, `run`, `ask`, `workflow status/wait/approve`, `mcp stdio` | Direct tool execution, natural-language Clippy workflows, and MCP stdio access. |
+| Agent tools | `skills list/describe/manifest`, `media-guides list/describe`, `tools list/describe`, `run`, `ask`, `workflow status/wait/approve`, `mcp stdio` | Permission-scoped discovery, provider-aware prompt guidance, direct execution, Clippy workflows, and MCP tools/resources. |
 | Context and navigation | `context use/show/clear/build`, `open`, `links`, `examples` | Persist active IDs and open ClipIt review surfaces. |
 | Videos and clips | `videos list/get/upload/abort-upload/import-url/transcribe/transcript/suggest-clips/delete`, `clips list/get/create/update/render/download/delete`, `jobs get/wait` | Core media and render job helpers. |
 | Credits | `credits balance`, `credits usage`, `credits estimate` | Estimate accepts `--metrics @file.json`. |
@@ -284,4 +301,4 @@ Only use `--allow-custom-host` for hosts you control or trust. It permits the CL
 | Assets | `assets list/upload/delete` | Upload signs, PUTs the file to object storage, then finalizes the library asset. Delete requires `--confirm`. |
 | Thumbnails and B-Roll | `thumbnails generate/get/list`, `broll plan/generate/list/get` | Paid generation commands require `--confirm`. |
 | Social | `social accounts/post/schedule/posts/get/cancel` | Publish/schedule/cancel require `--confirm`; `x` maps to the server `twitter` platform. |
-| Agent skills | `agent install/update/uninstall/doctor/print-skill/list` | `doctor` reports whether the installed skill came from the server or fallback. |
+| Agent skills | `agent install/update/uninstall/doctor/print-skill/list` | Installs a progressive multi-file editor skill; `doctor` validates source, root content, references, and capability-manifest freshness. |

package/bin/clipit.mjs

@@ -9,7 +9,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-const VERSION = '0.2.9';
+const VERSION = '0.3.0';
 const DEFAULT_BASE_URL = 'https://clipit.dev';
 const DEFAULT_SCOPES = [
   'clippy_agent',
@@ -53,17 +53,17 @@ const API_REQUEST_TIMEOUT_MS = readPositiveIntegerEnv(
 const MAX_CREDITS_ESTIMATE_MAP = Object.freeze({
   'exports start': [{ operationType: 'lambda_render', provider: 'aws_lambda', modelId: 'remotion-4.0', metrics: 'remotion-render' }],
   'thumbnails generate': [{ operationType: 'thumbnail_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'one-generation' }],
-  'broll plan': [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'minimax/minimax-m2.7', metrics: 'broll-plan' }],
+  'broll plan': [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'openai/gpt-5.6-terra-pro', metrics: 'broll-plan' }],
   'broll generate': [
     { operationType: 'image_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'broll-images' },
-    { operationType: 'video_generation', provider: 'replicate', modelId: 'alibaba/happyhorse-1.0', metrics: 'broll-video' },
+    { operationType: 'video_generation', provider: 'fal', modelId: 'minimax/h3-max/image-to-video', metrics: 'broll-video' },
   ],
   'clips create': [{ operationType: 'clip', provider: 'deepgram', metrics: 'clip-create' }],
   'clips render': [{ operationType: 'lambda_render', provider: 'aws_lambda', modelId: 'remotion-4.0', metrics: 'remotion-render' }],
   'videos upload': [{ operationType: 'video_storage', provider: 'railway_s3', metrics: 'video-upload-storage' }],
   'videos import-url': [{ operationType: null, provider: null, metrics: 'url-import' }],
   'videos transcribe': [{ operationType: 'transcription', provider: 'deepgram', modelId: 'nova-3', metrics: 'transcription-video' }],
-  'videos suggest-clips': [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'x-ai/grok-4.20-beta', metrics: 'suggest-clips' }],
+  'videos suggest-clips': [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'openai/gpt-5.6-sol-pro', metrics: 'suggest-clips' }],
   'social post': [{ operationType: 'social_post', provider: 'zernio', metrics: 'social-platforms' }],
   'social schedule': [{ operationType: 'social_post', provider: 'zernio', metrics: 'social-platforms' }],
 });
@@ -77,9 +77,9 @@ const RUN_MAX_CREDITS_ESTIMATE_MAP = Object.freeze({
   generateImage: [{ operationType: 'image_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'one-generation' }],
   generateBRoll: MAX_CREDITS_ESTIMATE_MAP['broll generate'],
   generateVoiceover: [{ operationType: 'tts_generation', provider: 'replicate', modelId: 'google/gemini-3.1-flash-tts', metrics: 'tts-provider-cost' }],
-  generateMusicBed: [{ operationType: 'music_generation', provider: 'replicate', modelId: 'minimax/music-2.5', metrics: 'one-generation' }],
-  generateVideoAlter: [{ operationType: 'video_alter_generation', provider: 'replicate', modelId: 'kwaivgi/kling-v3-omni-video', metrics: 'video-alter-provider-cost' }],
-  generatePlatformCaption: [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'anthropic/claude-opus-4.7', metrics: 'platform-caption' }],
+  generateMusicBed: [{ operationType: 'music_generation', provider: 'replicate', modelId: 'minimax/music-2.6', metrics: 'one-generation' }],
+  generateVideoAlter: [{ operationType: 'video_alter_generation', provider: 'fal', modelId: 'google/gemini-omni-flash/v1.1/edit', metrics: 'video-alter-provider-cost' }],
+  generatePlatformCaption: [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'openai/gpt-5.6-terra-pro', metrics: 'platform-caption' }],
   applyHookToFront: REMOTION_RUN_ESTIMATE,
   addLibraryAssetToClip: REMOTION_RUN_ESTIMATE,
   renderClipWithRemotion: REMOTION_RUN_ESTIMATE,
@@ -441,6 +441,29 @@ function hashText(value) {
   return createHash('sha256').update(String(value)).digest('hex');
 }
 
+function compareSemver(left, right) {
+  const parse = (value) => {
+    const match = String(value || '').match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+    if (!match) return null;
+    return {
+      numbers: match.slice(1, 4).map(Number),
+      prerelease: match[4] || null,
+    };
+  };
+  const current = parse(left);
+  const minimum = parse(right);
+  if (!current || !minimum) return null;
+  for (let index = 0; index < current.numbers.length; index += 1) {
+    if (current.numbers[index] !== minimum.numbers[index]) {
+      return current.numbers[index] > minimum.numbers[index] ? 1 : -1;
+    }
+  }
+  if (current.prerelease === minimum.prerelease) return 0;
+  if (!current.prerelease) return 1;
+  if (!minimum.prerelease) return -1;
+  return current.prerelease.localeCompare(minimum.prerelease, undefined, { numeric: true });
+}
+
 function usage() {
   return [
     'ClipIt CLI',
@@ -458,6 +481,9 @@ function usage() {
     '  clipit context use [--video-id id] [--clip-id id] [--project-id id] [--sequence-id id]',
     '  clipit context show|clear|build [--json]',
     '  clipit skills list [--json]',
+    '  clipit skills describe <skill-or-workflow> [--json]',
+    '  clipit skills manifest [--json]',
+    '  clipit media-guides list|describe [guide-id] [--json]',
     '  clipit tools list [--skill clip] [--json]',
     '  clipit tools describe <functionName>',
     '  clipit ask "<prompt>" [--video-id id] [--clip-id id] [--conversation-id id] [--quick] [--auto-confirm-costly] [--stream] [--json]',
@@ -465,6 +491,7 @@ function usage() {
     '  clipit workflow approve <jobId> --approval-id id [--decision approved|cheaper|cancelled]',
     '  clipit mcp [stdio]',
     '  clipit run <functionName> [--params @file.json] [--clip-id id] [--video-id id] [--confirm] [--max-credits n]',
+    '  clipit run setCaptionStyle --clip-id id --params @caption-style.json   # exact style or bounded captionDirective; no render',
     '  clipit videos list|get|upload|abort-upload|import-url|transcribe|transcript|suggest-clips|delete ...',
     '  clipit clips list|get|delivery-state|create|update|initialize-snapshot|render|download|delete ...',
     '  clipit jobs get|wait <jobId>',
@@ -485,6 +512,59 @@ function usage() {
 }
 
 function commandUsage(command, subcommand) {
+  if (command === 'run' && subcommand === 'setCaptionStyle') {
+    return [
+      'Usage:',
+      '  clipit run setCaptionStyle --clip-id <id> --params <json|@file> --json',
+      '',
+      'The params object must pin expectedEditorVersion, expectedEditorStateHash, and expectedClipSettingsRevision,',
+      'then supply exactly one of captionStyle or captionDirective.',
+      '',
+      'captionDirective accepts the strict form: caption size <50-300>% <auto|single|single-line|stacked>.',
+      'Example: "caption size 200% single" changes only fontSizeScale to 2 and captionLineMode to single-line;',
+      'it preserves wordsPerLine and every other current caption-style field.',
+    ].join('\n');
+  }
+  if (command === 'clips' && subcommand === 'initialize-snapshot') {
+    return [
+      'Usage:',
+      '  clipit clips initialize-snapshot <clipId> [options]',
+      '',
+      'Required:',
+      '  <clipId>                    Clip to initialize or safely reinitialize',
+      '',
+      'Optional:',
+      '  --aspect-ratio <ratio>      16:9, 9:16, 1:1, or 4:5',
+      '  --fit-background <mode>     black or blur',
+      '  --quality <quality>         standard, high, or 4k',
+      '  --captions <true|false>     Explicitly enable or disable captions',
+      '  --caption-style <style>     bold, minimal, neon, or classic',
+      '  --params <json|@file>        Supply the full initializer request, including captionPresetId or a strict rich captionStyle object',
+      '  --profile <name>            Named ClipIt credential profile',
+      '  --json                      Emit machine-readable JSON',
+      '',
+      'Omitted snapshot settings preserve the clip\'s exact current editor state.',
+    ].join('\n');
+  }
+  if (command === 'exports' && subcommand === 'start') {
+    return [
+      'Usage:',
+      '  clipit exports start --clip-id <id> --confirm [options]',
+      '',
+      'Required:',
+      '  --clip-id <id>           Clip to export from its verified current snapshot',
+      '  --confirm                Confirm the export mutation',
+      '',
+      'Optional:',
+      '  --params <json|@file>    Additional export settings',
+      '  --idempotency-key <key>  Stable retry identity; generated when omitted',
+      '  --max-credits <n>        Refuse an estimated client charge above this amount',
+      '  --profile <name>         Named ClipIt credential profile',
+      '  --json                   Emit machine-readable JSON',
+      '',
+      'The CLI pins the current editor version and state hash before starting the export.',
+    ].join('\n');
+  }
   if (command === 'social' && subcommand === 'schedule') {
     return [
       'Usage:',
@@ -511,19 +591,17 @@ function commandUsage(command, subcommand) {
   if (command === 'deliverables' && subcommand === 'create') {
     return [
       'Usage:',
-      '  clipit deliverables create --export-id <id> --title <text> --confirm',
+      '  clipit deliverables create --export-id <id> --confirm',
       '',
       'Required:',
       '  --export-id <id>   Exact completed export to deliver',
-      '  --title <text>     Client-facing deliverable title',
       '  --confirm          Confirm the delivery mutation',
       '',
       'Optional:',
-      '  --note <text>      Client-facing note',
       '  --profile <name>   Named ClipIt credential profile',
       '  --json             Emit machine-readable JSON',
       '',
-      'The response includes clientSelectionUrl; the client must select the delivery before enterprise social publishing.',
+      'The CLI pins the export execution, snapshot, caption-style hash, object fingerprint, outro policy, and verified artifact duration. ClipIt derives the title and note from canonical metadata.',
     ].join('\n');
   }
   return null;
@@ -1000,8 +1078,9 @@ function normalizeCreditEstimateRequest(request) {
 }
 
 function brollVideoProviderCostUsd(durationSeconds, resolution) {
-  const perSecondUsd = resolution === '1080p' ? 0.28 : 0.14;
-  return Math.max(0, durationSeconds * perSecondUsd);
+  const billableDuration = Math.max(5, Math.min(15, Math.round(durationSeconds)));
+  const perSecondUsd = resolution === '480p' ? 0.05 : 0.08;
+  return billableDuration * perSecondUsd;
 }
 
 function brollImageProviderCostUsd(quality) {
@@ -1019,10 +1098,8 @@ function ttsProviderCostUsd(text, prompt) {
 }
 
 function videoAlterProviderCostUsd(durationSeconds, mode) {
-  const perSecond = mode === 'pro'
-    ? Number(process.env.KLING_OMNI_PRO_COST_PER_SECOND_USD ?? '0.56')
-    : Number(process.env.KLING_OMNI_STANDARD_COST_PER_SECOND_USD ?? '0.28');
-  return Math.max(0, durationSeconds * (Number.isFinite(perSecond) ? perSecond : 0.28));
+  const perSecond = mode === 'pro' ? 0.15 : 0.10;
+  return Math.max(0, durationSeconds * perSecond);
 }
 
 function durationFromClip(clip, body = {}) {
@@ -1096,7 +1173,7 @@ async function buildMaxCreditsEstimateRequest(config, options, spec, context = {
 
   if (spec.metrics === 'broll-images') {
     const mode = context.body?.mode || 'single_image';
-    const generationCount = mode === 'start_end_frame' ? 3 : 1;
+    const generationCount = mode === 'start_end_frame' ? 2 : 1;
     return {
       ...spec,
       metrics: {
@@ -1108,7 +1185,7 @@ async function buildMaxCreditsEstimateRequest(config, options, spec, context = {
 
   if (spec.metrics === 'broll-video') {
     const durationSeconds = Number(context.body?.durationSeconds ?? context.body?.duration ?? 6);
-    const resolution = context.body?.resolution || '720p';
+    const resolution = context.body?.resolution || '768p';
     if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) return null;
     return {
       ...spec,
@@ -1158,7 +1235,7 @@ async function buildMaxCreditsEstimateRequest(config, options, spec, context = {
   return null;
 }
 
-async function buildStaticRunEstimates(config, options, functionName, parameters, payload) {
+async function buildStaticRunEstimates(config, options, functionName, parameters, payload, maxCredits = null) {
   const specs = RUN_MAX_CREDITS_ESTIMATE_MAP[functionName];
   if (!specs) return null;
 
@@ -1181,12 +1258,19 @@ async function buildStaticRunEstimates(config, options, functionName, parameters
 
   const estimates = [];
   for (const request of requests) {
-    const estimate = await apiFetch(config, options, 'POST', '/api/v1/credits/estimate', request);
+    const estimate = await apiFetch(config, options, 'POST', '/api/v1/credits/preflight', compactObject({
+      ...request,
+      maxCredits,
+    }));
     estimates.push({
       operationType: request.operationType,
       provider: request.provider,
       modelId: request.modelId,
-      estimatedCostClip: Number(estimate?.estimatedCostClip ?? 0),
+      estimatedCostClip: Number(estimate?.internalEstimatedUsageClip ?? 0),
+      internalEstimatedUsageClip: Number(estimate?.internalEstimatedUsageClip ?? 0),
+      clientCreditChargeClip: Number(estimate?.clientCreditChargeClip ?? 0),
+      settlementMode: estimate?.settlementMode ?? 'direct',
+      withinApprovalCap: estimate?.withinApprovalCap !== false,
       affordable: estimate?.affordable,
       spendLimitViolation: estimate?.spendLimitViolation ?? null,
     });
@@ -1217,7 +1301,7 @@ function throwMaxCreditsEstimateUnavailable(commandKey) {
 
 function estimatedClipCostFromData(data) {
   if (!data || typeof data !== 'object') return null;
-  for (const key of ['estimatedCostClip', 'totalEstimatedCostClip', 'costClip', 'totalCostClip']) {
+  for (const key of ['internalEstimatedUsageClip', 'estimatedCostClip', 'totalEstimatedCostClip', 'costClip', 'totalCostClip']) {
     const value = Number(data[key]);
     if (Number.isFinite(value)) return value;
   }
@@ -1253,12 +1337,19 @@ async function enforceMaxCredits(config, options, commandKey, context = {}) {
 
   const estimates = [];
   for (const request of requests) {
-    const estimate = await apiFetch(config, options, 'POST', '/api/v1/credits/estimate', request);
+    const estimate = await apiFetch(config, options, 'POST', '/api/v1/credits/preflight', {
+      ...request,
+      maxCredits: limit,
+    });
     estimates.push({
       operationType: request.operationType,
       provider: request.provider,
       modelId: request.modelId,
-      estimatedCostClip: Number(estimate?.estimatedCostClip ?? 0),
+      estimatedCostClip: Number(estimate?.internalEstimatedUsageClip ?? 0),
+      internalEstimatedUsageClip: Number(estimate?.internalEstimatedUsageClip ?? 0),
+      clientCreditChargeClip: Number(estimate?.clientCreditChargeClip ?? 0),
+      settlementMode: estimate?.settlementMode ?? 'direct',
+      withinApprovalCap: estimate?.withinApprovalCap !== false,
       affordable: estimate?.affordable,
       spendLimitViolation: estimate?.spendLimitViolation ?? null,
     });
@@ -1269,15 +1360,18 @@ async function enforceMaxCredits(config, options, commandKey, context = {}) {
   warnIfEstimateUnaffordable(estimates);
 
   const estimatedCostClip = estimates.reduce((sum, estimate) => sum + estimate.estimatedCostClip, 0);
-  if (estimatedCostClip > limit) {
+  const clientCreditChargeClip = estimates.reduce((sum, estimate) => sum + estimate.clientCreditChargeClip, 0);
+  if (estimatedCostClip > limit || estimates.some((estimate) => !estimate.withinApprovalCap)) {
     throw Object.assign(
-      new Error(`Estimated cost ${clipCostLabel(estimatedCostClip)} exceeds --max-credits ${clipCostLabel(limit)} for ${commandKey}.`),
+      new Error(`Internal estimated usage ${clipCostLabel(estimatedCostClip)} exceeds --max-credits ${clipCostLabel(limit)} for ${commandKey}; client credit charge is ${clipCostLabel(clientCreditChargeClip)}.`),
       {
         exitCode: EXIT.CONFIRMATION,
         data: {
           command: commandKey,
           maxCredits: limit,
           estimatedCostClip,
+          internalEstimatedUsageClip: estimatedCostClip,
+          clientCreditChargeClip,
           estimates,
         },
       },
@@ -1309,7 +1403,7 @@ async function enforceRunMaxCredits(config, options, functionName, parameters =
 
   let staticEstimates = null;
   if (!runEstimate && (limit !== null || needsConfirmationPreflight)) {
-    staticEstimates = await buildStaticRunEstimates(config, options, functionName, parameters, payload);
+    staticEstimates = await buildStaticRunEstimates(config, options, functionName, parameters, payload, limit);
   }
 
   if (limit === null) {
@@ -1347,7 +1441,7 @@ async function enforceRunMaxCredits(config, options, functionName, parameters =
     warnIfEstimateUnaffordable(staticEstimates);
 
     const estimatedCostClip = staticEstimates.reduce((sum, estimate) => sum + estimate.estimatedCostClip, 0);
-    if (estimatedCostClip > limit) {
+    if (estimatedCostClip > limit || staticEstimates.some((estimate) => !estimate.withinApprovalCap)) {
       throw Object.assign(
         new Error(`Estimated cost ${clipCostLabel(estimatedCostClip)} exceeds --max-credits ${clipCostLabel(limit)} for run ${functionName}.`),
         {
@@ -1625,6 +1719,28 @@ async function listSkills(config, options) {
   output(await apiFetch(config, options, 'GET', '/api/v1/agent/skills'), options);
 }
 
+async function describeSkill(config, options, id) {
+  if (!id) throw Object.assign(new Error('Skill or workflow ID is required.'), { exitCode: EXIT.USAGE });
+  output(await apiFetch(config, options, 'GET', `/api/v1/agent/skills/${encodeURIComponent(id)}`), options);
+}
+
+async function capabilityManifest(config, options) {
+  output(await apiFetch(config, options, 'GET', '/api/v1/agent/capability-manifest'), options);
+}
+
+async function mediaGuides(config, options, action, id) {
+  if (action === 'list') {
+    output(await apiFetch(config, options, 'GET', '/api/v1/agent/media-guides'), options);
+    return;
+  }
+  if (action === 'describe') {
+    if (!id) throw Object.assign(new Error('Media guide ID is required.'), { exitCode: EXIT.USAGE });
+    output(await apiFetch(config, options, 'GET', `/api/v1/agent/media-guides/${encodeURIComponent(id)}`), options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown media-guides command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
 async function listTools(config, options) {
   const params = new URLSearchParams();
   if (options.skill) params.set('skill', String(options.skill));
@@ -1769,6 +1885,57 @@ function normalizeAgentExecuteResult(result) {
   });
 }
 
+function resolveToolResultContext(result, fallback = {}) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return null;
+  const data = result.result && typeof result.result === 'object' && !Array.isArray(result.result)
+    ? result.result
+    : result;
+  const libraryClip = data.libraryClip && typeof data.libraryClip === 'object' && !Array.isArray(data.libraryClip)
+    ? data.libraryClip
+    : null;
+  const batchItems = [
+    ...(Array.isArray(data.created) ? data.created : []),
+    ...(Array.isArray(data.skipped) ? data.skipped : []),
+  ].filter((item) => item && typeof item === 'object' && !Array.isArray(item));
+  const selectedClipIds = batchItems
+    .map((item) => item.libraryClipId || item.clipId || item.id)
+    .filter(Boolean)
+    .map(String);
+  const batchVideoIds = [...new Set(batchItems
+    .map((item) => (
+      item.libraryClip && typeof item.libraryClip === 'object' && !Array.isArray(item.libraryClip)
+        ? item.libraryClip.videoId
+        : item.videoId
+    ))
+    .filter(Boolean)
+    .map(String))];
+  const clipId = data.libraryClipId
+    || libraryClip?.id
+    || data.clipId
+    || (selectedClipIds.length === 1 ? selectedClipIds[0] : null);
+  const resultVideoId = libraryClip?.videoId
+    || data.videoId
+    || (batchVideoIds.length === 1 ? batchVideoIds[0] : null);
+  if (!clipId && selectedClipIds.length === 0 && !resultVideoId) return null;
+  const nextClipId = clipId ? String(clipId) : fallback.clipId;
+  const selectedTargetsChanged = selectedClipIds.length > 0
+    && JSON.stringify(selectedClipIds) !== JSON.stringify(fallback.selectedClipIds || []);
+  const clipTargetChanged = Boolean(
+    nextClipId
+    && fallback.clipId
+    && String(nextClipId) !== String(fallback.clipId),
+  );
+  const videoId = resultVideoId
+    ? String(resultVideoId)
+    : clipTargetChanged || selectedTargetsChanged ? undefined : fallback.videoId;
+  return compactObject({
+    ...fallback,
+    videoId,
+    clipId: nextClipId,
+    selectedClipIds: selectedClipIds.length ? selectedClipIds : fallback.selectedClipIds,
+  });
+}
+
 async function runTool(config, options, functionName) {
   if (!functionName) throw Object.assign(new Error('Function name is required.'), { exitCode: EXIT.USAGE });
   if (RUN_CONFIRMATION_LABELS[functionName]) {
@@ -1807,7 +1974,23 @@ async function runTool(config, options, functionName) {
     process.exitCode = EXIT.CONFIRMATION;
     return;
   }
+  if (result?.success !== false) {
+    const nextContext = resolveToolResultContext(result, context);
+    if (nextContext) {
+      const recent = [
+        { type: 'video', id: nextContext.videoId },
+        { type: 'clip', id: nextContext.clipId },
+        ...(Array.isArray(nextContext.selectedClipIds)
+          ? nextContext.selectedClipIds.map((id) => ({ type: 'clip', id }))
+          : []),
+      ].filter((entry) => entry.id);
+      await persistActiveContext(config, options, nextContext, recent);
+    }
+  }
   output(outputResult, options);
+  if (result?.success === false) {
+    process.exitCode = EXIT.SERVER;
+  }
 }
 
 function workflowEndpoint(jobId) {
@@ -3107,7 +3290,7 @@ async function exportsCommand(config, options, action, args) {
   throw Object.assign(new Error(`Unknown exports command: ${action || ''}`), { exitCode: EXIT.USAGE });
 }
 
-function enterpriseClientSelectionUrl(config, options, selectionPath = '/enterprise?tab=delivered') {
+function enterpriseClientSelectionUrl(config, options, selectionPath = '/enterprise/workspace?tab=delivered') {
   return new URL(selectionPath, getBaseUrl(config, options)).toString();
 }
 
@@ -3127,16 +3310,55 @@ async function deliverables(config, options, action) {
   }
   if (action === 'create') {
     const exportId = requiredString(options['export-id'], '--export-id');
-    const title = requiredString(options.title, '--title');
     requireConfirm(options, 'Delivering an export to the enterprise client');
+    const exactExport = await apiFetch(
+      config,
+      options,
+      'GET',
+      `/api/v1/exports/${encodeURIComponent(exportId)}`,
+    );
+    const expectations = {
+      enterpriseExecutionId: exactExport?.enterpriseExecutionId,
+      snapshotId: exactExport?.snapshotId,
+      editorVersion: exactExport?.editorVersion,
+      editorStateHash: exactExport?.editorStateHash,
+      outputObjectFingerprint: exactExport?.outputObjectFingerprint,
+      captionStyleHash: exactExport?.captionStyleHash,
+      includeOutro: exactExport?.includeOutro,
+      artifactDuration: exactExport?.approvedArtifactDuration,
+    };
+    const actualArtifactDuration = exactExport?.artifactDuration;
+    const exactIdentityReady = exactExport?.status === 'completed'
+      && typeof expectations.enterpriseExecutionId === 'string'
+      && typeof expectations.snapshotId === 'string'
+      && Number.isSafeInteger(expectations.editorVersion)
+      && typeof expectations.editorStateHash === 'string'
+      && /^[a-f0-9]{64}$/i.test(expectations.editorStateHash)
+      && typeof expectations.outputObjectFingerprint === 'string'
+      && /^[a-f0-9]{64}$/i.test(expectations.outputObjectFingerprint)
+      && typeof expectations.captionStyleHash === 'string'
+      && /^[a-f0-9]{64}$/i.test(expectations.captionStyleHash)
+      && typeof expectations.includeOutro === 'boolean'
+      && typeof expectations.artifactDuration === 'number'
+      && Number.isFinite(expectations.artifactDuration)
+      && expectations.artifactDuration > 0
+      && typeof actualArtifactDuration === 'number'
+      && Number.isFinite(actualArtifactDuration)
+      && actualArtifactDuration > 0
+      && Math.abs(actualArtifactDuration - expectations.artifactDuration) <= 0.15;
+    if (!exactIdentityReady) {
+      throw Object.assign(
+        new Error('The export is not a completed, exact enterprise artifact with verified snapshot, caption-style, object, outro, and duration lineage.'),
+        { exitCode: EXIT.SERVER, data: exactExport },
+      );
+    }
     const result = await apiFetch(config, options, 'POST', '/api/v1/deliverables', {
       exportId,
-      title,
-      note: options.note,
+      expectations,
     });
     output({
       ...result,
-      clientSelectionPath: '/enterprise?tab=delivered',
+      clientSelectionPath: '/enterprise/workspace?tab=delivered',
       clientSelectionUrl: enterpriseClientSelectionUrl(config, options),
     }, options);
     return;
@@ -3408,7 +3630,7 @@ async function resolveEnterpriseSelectedDelivery(config, options, clipId, export
   const current = deliveries.find((delivery) => (
     delivery?.clipId === clipId && delivery?.exportId === exportId
   )) ?? null;
-  const clientSelectionPath = result?.clientSelectionPath || '/enterprise?tab=delivered';
+  const clientSelectionPath = result?.clientSelectionPath || '/enterprise/workspace?tab=delivered';
   throw Object.assign(
     new Error('The client has not selected this delivered export for publishing.'),
     {
@@ -3861,6 +4083,91 @@ async function handleLocalMcpBillingTool(config, options, name, parameters = {})
   throw Object.assign(new Error(`Unknown local billing tool: ${name}`), { exitCode: EXIT.USAGE });
 }
 
+function mcpCapabilityResource(capability) {
+  return {
+    uri: `clipit://skills/${encodeURIComponent(capability.id)}`,
+    name: capability.name || capability.id,
+    description: `${capability.type === 'bundle' ? 'Workflow' : 'Skill'}: ${capability.description || ''}`.trim(),
+    mimeType: 'application/json',
+  };
+}
+
+function mcpMediaGuideResource(guide) {
+  return {
+    uri: `clipit://media-guides/${encodeURIComponent(guide.id)}`,
+    name: guide.name || guide.id,
+    description: `${guide.purpose} guide${guide.providerModelId ? ` for ${guide.providerModelId}` : ''}`,
+    mimeType: 'text/markdown',
+  };
+}
+
+async function fetchMcpResources(config, options) {
+  const [skills, mediaGuides] = await Promise.all([
+    apiFetch(config, options, 'GET', '/api/v1/agent/skills'),
+    apiFetch(config, options, 'GET', '/api/v1/agent/media-guides'),
+  ]);
+  return [
+    {
+      uri: 'clipit://instructions',
+      name: 'ClipIt agent instructions',
+      description: 'Permission-scoped operating instructions for the authenticated ClipIt profile.',
+      mimeType: 'text/markdown',
+    },
+    {
+      uri: 'clipit://manifest',
+      name: 'ClipIt capability manifest',
+      description: 'Version, parity checksums, model estate, and live capability counts.',
+      mimeType: 'application/json',
+    },
+    ...(Array.isArray(skills?.capabilities) ? skills.capabilities.map(mcpCapabilityResource) : []),
+    ...(Array.isArray(mediaGuides?.guides) ? mediaGuides.guides.map(mcpMediaGuideResource) : []),
+  ];
+}
+
+function parseClipItResourceUri(value) {
+  if (typeof value !== 'string') return null;
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'clipit:') return null;
+  const id = parsed.pathname.replace(/^\/+/, '');
+  try {
+    return { kind: parsed.hostname, id: id ? decodeURIComponent(id) : null };
+  } catch {
+    return null;
+  }
+}
+
+async function readMcpResource(config, options, uri) {
+  const parsed = parseClipItResourceUri(uri);
+  if (!parsed) return null;
+
+  if (parsed.kind === 'instructions' && !parsed.id) {
+    const response = await apiFetch(config, options, 'GET', '/api/v1/agent/instructions?target=generic&format=json');
+    return { uri, mimeType: 'text/markdown', text: response.markdown };
+  }
+  if (parsed.kind === 'manifest' && !parsed.id) {
+    const response = await apiFetch(config, options, 'GET', '/api/v1/agent/capability-manifest');
+    return { uri, mimeType: 'application/json', text: JSON.stringify(redactDeep(response), null, 2) };
+  }
+  if (parsed.kind === 'skills' && parsed.id) {
+    const response = await apiFetch(config, options, 'GET', `/api/v1/agent/skills/${encodeURIComponent(parsed.id)}`);
+    return { uri, mimeType: 'application/json', text: JSON.stringify(redactDeep(response), null, 2) };
+  }
+  if (parsed.kind === 'media-guides' && parsed.id) {
+    const response = await apiFetch(config, options, 'GET', `/api/v1/agent/media-guides/${encodeURIComponent(parsed.id)}`);
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: [response.contract, response.guide].filter(Boolean).join('\n\n---\n\n'),
+    };
+  }
+  return null;
+}
+
 async function handleMcpRequest(config, options, message) {
   if (!message || typeof message !== 'object' || Array.isArray(message)) {
     return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid JSON-RPC request.' } };
@@ -3877,7 +4184,10 @@ async function handleMcpRequest(config, options, message) {
       id,
       result: {
         protocolVersion: message.params?.protocolVersion || '2024-11-05',
-        capabilities: { tools: {} },
+        capabilities: {
+          tools: {},
+          resources: { subscribe: false, listChanged: false },
+        },
         serverInfo: { name: 'clipit', version: VERSION },
       },
     };
@@ -3900,6 +4210,30 @@ async function handleMcpRequest(config, options, message) {
     };
   }
 
+  if (method === 'resources/list') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: { resources: await fetchMcpResources(config, options) },
+    };
+  }
+
+  if (method === 'resources/read') {
+    const uri = typeof message.params?.uri === 'string' ? message.params.uri : null;
+    if (!uri) {
+      return { jsonrpc: '2.0', id, error: { code: -32602, message: 'resources/read requires params.uri.' } };
+    }
+    const resource = await readMcpResource(config, options, uri);
+    if (!resource) {
+      return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown ClipIt resource: ${uri}` } };
+    }
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: { contents: [resource] },
+    };
+  }
+
   if (method === 'tools/call') {
     const name = typeof message.params?.name === 'string' ? message.params.name : null;
     if (!name) {
@@ -4150,6 +4484,8 @@ async function examples(options) {
     thumbnail: 'clipit thumbnails generate --clip-id <clipId> --prompt "Expressive high-contrast thumbnail" --confirm --json',
     brollPlan: 'clipit broll plan <clipId> --count 3 --confirm --json',
     socialPost: 'clipit social post --clip-id <clipId> --platforms x,tiktok --account-ids x=<xAccountId>,tiktok=<tiktokAccountId> --caption "New clip" --confirm --json',
+    setExactCaptionStyle: 'clipit run setCaptionStyle --clip-id <clipId> --params @caption-style.json --json',
+    setCaptionDirective: 'clipit run setCaptionStyle --clip-id <clipId> --params \'{"expectedEditorVersion":1,"expectedEditorStateHash":"<sha256>","expectedClipSettingsRevision":1,"captionDirective":"caption size 200% single"}\' --json',
     runTool: 'clipit run <functionName> --clip-id <clipId> --params @params.json --json',
     reviewLink: 'clipit links clip <clipId> --json',
   };
@@ -4161,7 +4497,14 @@ async function examples(options) {
 }
 
 function skillMarkdown(agent) {
-  return `# ClipIt CLI
+  return `---
+name: clipit-cli
+description: Edit and create video with ClipIt through its live CLI or MCP tools, including review-first workflows, generated media, audio, QA, export, and publishing.
+metadata:
+  pack-version: "offline-${VERSION}"
+---
+
+# ClipIt CLI
 
 Use the ClipIt CLI to operate ClipIt through the user's authenticated account. This is the generic offline fallback skill; when possible, run \`clipit agent update ${agent}\` after login to fetch server-rendered instructions scoped to the current API key.
 
@@ -4169,12 +4512,18 @@ Rules:
 - Run \`clipit auth status --json\` before assuming ClipIt is connected.
 - If not connected, ask the user to run \`clipit login\` and approve the browser link.
 - Never ask the user to paste API keys into chat.
-- Use \`clipit skills list --json\` and \`clipit tools list --json\` to discover capability.
-- Use \`clipit mcp stdio\` when an MCP-compatible client can launch local stdio servers; it speaks standard \`Content-Length\` framed JSON-RPC.
+- Use \`clipit skills list --json\`, \`clipit skills describe <id> --json\`, and \`clipit skills manifest --json\` for progressive discovery. Use \`clipit tools list --json\` and \`clipit tools describe <name> --json\` for the current execution schema.
+- Use \`clipit media-guides list --json\` and \`clipit media-guides describe <id> --json\` before generated image, video, Alter, voiceover, or music work.
+- Use \`clipit mcp stdio\` when an MCP-compatible client can launch local stdio servers; it exposes tools plus \`clipit://instructions\`, \`clipit://manifest\`, skill/workflow, and media-guide resources.
+- Keep one execution owner per task: orchestrate direct CLI/MCP calls or delegate the workflow through \`clipit ask\`, never both independently.
+- Establish the audience, platform, target duration, communication goal, hook, story arc, exact text, references, preservation invariants, source-audio authority, and definition of done before creative mutation.
+- Work in passes: inspect; propose lightweight candidates; obtain selection; refine story, pacing, timeline, framing, captions, media, and audio; run QA; then export or publish.
+- Preserve real-person identity and performance. Provider completion is not creative acceptance; inspect generated media before applying it and run final delivery QA.
 - Prefer friendly commands such as \`clipit videos list --json\`, \`clipit clips list --json\`, \`clipit credits balance --json\`, and \`clipit jobs wait <jobId> --json\`.
 - Use \`clipit ask "..."\` for natural-language Clippy workflows, and \`clipit workflow wait <jobId> --json\` or \`clipit workflow approve <jobId> --approval-id <id>\` for workflow follow-through.
 - Use \`clipit ask "..." --auto-confirm-costly\` only when the human has asked you to work autonomously on ClipIt-only cost-spending tasks. It never authorizes social publishing/scheduling or destructive actions.
 - Use \`clipit run <functionName> --params @file.json --json\` for exact Clippy tools.
+- For exact captions, run \`clipit run setCaptionStyle --clip-id <clipId> --params @caption-style.json --json\`; the params file pins expectedEditorVersion, expectedEditorStateHash, and expectedClipSettingsRevision and supplies exactly one of a strict \`captionStyle\` object or \`captionDirective\`. The literal \`caption size 200% single\` maps to scale 2 plus \`single-line\` without changing wordsPerLine or other current style fields. Verify the normalized style/hash/capability response before approving any render.
 - Treat paid generation, publishing, deletion, broad mutation, and \`requiresConfirmation\` responses as user approval checkpoints.
 - Treat exit code 13 as insufficient credits or an API key spend-limit block; top up billing or adjust the key's spend limit in ClipIt Settings.
 - When credits are insufficient, discover payment rails with \`clipit billing capabilities --json\` and \`clipit billing catalog --json\`.
@@ -4190,6 +4539,9 @@ Useful commands:
 clipit doctor --json
 clipit auth status --json
 clipit skills list --json
+clipit skills describe broll --json
+clipit skills manifest --json
+clipit media-guides list --json
 clipit tools list --json
 clipit tools describe <functionName> --json
 clipit mcp stdio
@@ -4217,6 +4569,7 @@ clipit analytics overview --days 30 --json
 clipit exports start --clip-id <clipId> --confirm --json
 clipit thumbnails generate --clip-id <clipId> --prompt "High contrast thumbnail" --confirm --json
 clipit social post --clip-id <clipId> --platforms x,tiktok --account-ids x=<xAccountId>,tiktok=<tiktokAccountId> --caption "New clip" --confirm --json
+clipit run setCaptionStyle --clip-id <clipId> --params @caption-style.json --json
 clipit run renderClipWithRemotion --clip-id <clipId> --params @params.json --confirm --json
 \`\`\`
 
@@ -4236,6 +4589,7 @@ function mcpSkillAddendum() {
     '## MCP Stdio Bridge',
     '- If your agent runtime supports MCP stdio servers, prefer launching `clipit mcp stdio` from the user\'s machine instead of manually shelling every command.',
     '- The bridge uses the authenticated CLI profile, speaks standard `Content-Length` framed JSON-RPC over stdio, and exposes the same live tools as `clipit tools list --json` / `GET /api/v1/agent/tools`.',
+    '- Use `resources/list` and `resources/read` for `clipit://instructions`, `clipit://manifest`, `clipit://skills/<id>`, and `clipit://media-guides/<id>` so only the relevant guide enters context.',
     '- `tools/call` delegates to `/api/v1/agent/execute`, inherits the active CLI context from `clipit context use`, and preserves confirmation gates for paid generation, publishing, deletion, export, and other mutating calls.',
     '- The bridge also exposes local billing discovery tools: `getPaymentCapabilities`, `getBillingCatalog`, `createPaymentAttempt`, `getPaymentAttempt`, `getPaymentReceipt`, and `getBillingSubscription`.',
     '- `createPaymentAttempt` returns a payment URL for direct x402, Stripe-managed x402, or Stripe MPP/Link SPT settlement and requires `confirmed:true`; do not retry it until the human approves the product, amount, rail, and budget policy.',
@@ -4257,6 +4611,7 @@ function fallbackSkillResult(target, reason) {
   const generatedAt = new Date().toISOString();
   return {
     markdown: skillMarkdown(target),
+    references: [],
     source: 'fallback',
     fallbackReason: reason,
     meta: {
@@ -4302,9 +4657,27 @@ async function resolveAgentSkill(config, options, target) {
     });
   }
 
+  if (response.meta.minimumCliVersion !== undefined) {
+    const compatibility = compareSemver(VERSION, response.meta.minimumCliVersion);
+    if (compatibility === null) {
+      throw Object.assign(new Error('Instructions endpoint returned an invalid minimum CLI version.'), {
+        exitCode: EXIT.SERVER,
+        data: { minimumCliVersion: response.meta.minimumCliVersion },
+      });
+    }
+    if (compatibility < 0) {
+      throw Object.assign(new Error(
+        `ClipIt CLI ${VERSION} is too old for agent pack ${response.meta.packVersion || 'current'}; install @clipit-ai/cli@latest (minimum ${response.meta.minimumCliVersion}).`,
+      ), { exitCode: EXIT.SERVER });
+    }
+  }
+
+  const references = validateAgentInstructionReferences(response.references);
+
   const augmented = withLocalCliSkillAddenda(response.markdown);
   return {
     markdown: augmented.markdown,
+    references,
     source: 'server',
     meta: compactObject({
       ...response.meta,
@@ -4325,12 +4698,83 @@ async function readAgentSkillMeta(baseDir) {
   }
 }
 
+function safeAgentReferencePath(value) {
+  if (typeof value !== 'string') return null;
+  if (value.includes('\0')) return null;
+  const normalized = path.posix.normalize(value.replace(/\\/g, '/'));
+  if (
+    !normalized.startsWith('references/')
+    || normalized === 'references/'
+    || normalized.endsWith('/')
+    || normalized.includes('../')
+    || path.posix.isAbsolute(normalized)
+  ) {
+    return null;
+  }
+  return normalized;
+}
+
+function validateAgentInstructionReferences(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 256) {
+    throw Object.assign(new Error('Instructions endpoint returned an invalid references collection.'), {
+      exitCode: EXIT.SERVER,
+    });
+  }
+
+  const references = [];
+  const paths = new Set();
+  let totalBytes = 0;
+  for (const entry of value) {
+    const relativePath = safeAgentReferencePath(entry?.path);
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || !relativePath || typeof entry.content !== 'string') {
+      throw Object.assign(new Error('Instructions endpoint returned an invalid or unsafe generated reference.'), {
+        exitCode: EXIT.SERVER,
+      });
+    }
+    if (paths.has(relativePath)) {
+      throw Object.assign(new Error(`Instructions endpoint returned duplicate reference path: ${relativePath}`), {
+        exitCode: EXIT.SERVER,
+      });
+    }
+    paths.add(relativePath);
+    totalBytes += Buffer.byteLength(entry.content, 'utf8');
+    if (totalBytes > 10 * 1024 * 1024) {
+      throw Object.assign(new Error('Instructions endpoint references exceed the 10 MiB install limit.'), {
+        exitCode: EXIT.SERVER,
+      });
+    }
+
+    const actualSha256 = hashText(entry.content);
+    if (entry.sha256 !== undefined && (typeof entry.sha256 !== 'string' || entry.sha256.toLowerCase() !== actualSha256)) {
+      throw Object.assign(new Error(`Instructions endpoint reference checksum mismatch: ${relativePath}`), {
+        exitCode: EXIT.SERVER,
+      });
+    }
+    references.push({ ...entry, path: relativePath, sha256: actualSha256 });
+  }
+  return references;
+}
+
+function agentSkillContentHash(markdown, references = []) {
+  const referenceContent = references
+    .map((entry) => ({ path: safeAgentReferencePath(entry.path), content: String(entry.content || '') }))
+    .filter((entry) => entry.path)
+    .sort((left, right) => left.path.localeCompare(right.path));
+  return hashText(JSON.stringify({ markdown: String(markdown || ''), references: referenceContent }));
+}
+
 function agentSkillSidecar(target, skill) {
   return compactObject({
     target,
     source: skill.source,
     generatedAt: skill.meta?.generatedAt,
     markdownHash: hashText(skill.markdown),
+    contentHash: agentSkillContentHash(skill.markdown, skill.references),
+    references: skill.references?.map((entry) => compactObject({
+      path: safeAgentReferencePath(entry.path),
+      sha256: entry.sha256 || hashText(entry.content),
+    })).filter((entry) => entry.path),
     serverMeta: skill.source === 'server' ? skill.meta : undefined,
     fallbackReason: skill.fallbackReason,
   });
@@ -4360,6 +4804,19 @@ async function installedAgentStatus(target, options) {
       fs.readFile(skillPath, 'utf8'),
     ]);
     const sidecar = await readAgentSkillMeta(baseDir);
+    const references = Array.isArray(sidecar?.references)
+      ? await Promise.all(sidecar.references.map(async (entry) => {
+          const relativePath = safeAgentReferencePath(entry?.path);
+          if (!relativePath) return null;
+          try {
+            return { path: relativePath, content: await fs.readFile(path.join(baseDir, relativePath), 'utf8') };
+          } catch {
+            return { path: relativePath, content: null };
+          }
+        }))
+      : [];
+    const missingReferences = references.filter((entry) => entry && entry.content === null).map((entry) => entry.path);
+    const installedReferences = references.filter((entry) => entry && typeof entry.content === 'string');
     return {
       target,
       installed: true,
@@ -4369,6 +4826,11 @@ async function installedAgentStatus(target, options) {
       generatedAt: sidecar?.generatedAt || null,
       fallbackReason: sidecar?.fallbackReason || null,
       markdownHash: sidecar?.markdownHash || hashText(markdown),
+      contentHash: missingReferences.length === 0
+        ? agentSkillContentHash(markdown, installedReferences)
+        : null,
+      referenceCount: references.length,
+      missingReferences,
       serverMeta: sidecar?.serverMeta || null,
     };
   } catch {
@@ -4381,6 +4843,14 @@ function agentFreshnessReason(status, currentSkill) {
   if (status.skillSource !== currentSkill.source) {
     return `installed source ${status.skillSource || 'unknown'} differs from current source ${currentSkill.source}`;
   }
+  if (status.missingReferences?.length) {
+    return `installed skill is missing ${status.missingReferences.length} generated reference file(s)`;
+  }
+  if (status.serverMeta?.manifestHash
+    && currentMeta?.manifestHash
+    && status.serverMeta.manifestHash !== currentMeta.manifestHash) {
+    return 'installed capability manifest differs from the live registry';
+  }
   if (status.serverMeta?.toolCount !== undefined
     && currentMeta?.toolCount !== undefined
     && status.serverMeta.toolCount !== currentMeta.toolCount) {
@@ -4394,6 +4864,28 @@ function agentFreshnessReason(status, currentSkill) {
   return 'installed skill content differs from current generated instructions';
 }
 
+async function writeAgentReferences(baseDir, references, previousMeta) {
+  const currentPaths = new Set();
+  for (const entry of references || []) {
+    const relativePath = safeAgentReferencePath(entry.path);
+    if (!relativePath) {
+      throw Object.assign(new Error(`Instructions endpoint returned an unsafe reference path: ${entry.path}`), {
+        exitCode: EXIT.SERVER,
+      });
+    }
+    currentPaths.add(relativePath);
+    const destination = path.join(baseDir, relativePath);
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    await fs.writeFile(destination, entry.content, 'utf8');
+  }
+
+  for (const previous of previousMeta?.references || []) {
+    const relativePath = safeAgentReferencePath(previous?.path);
+    if (!relativePath || currentPaths.has(relativePath)) continue;
+    await fs.rm(path.join(baseDir, relativePath), { force: true });
+  }
+}
+
 async function agent(config, options, action, args) {
   const target = args[0] || 'generic';
   const baseDir = agentInstallDir(target, options);
@@ -4435,8 +4927,8 @@ async function agent(config, options, action, args) {
           status.stale = null;
           status.freshnessError = `Cannot verify installed skill freshness: ${currentSkill.fallbackReason || 'current instructions unavailable'}`;
         } else {
-          const currentHash = hashText(currentSkill.markdown);
-          status.upToDate = status.markdownHash === currentHash;
+          const currentHash = agentSkillContentHash(currentSkill.markdown, currentSkill.references);
+          status.upToDate = status.contentHash === currentHash;
           status.stale = !status.upToDate;
           if (status.stale) {
             status.staleReason = agentFreshnessReason(status, currentSkill);
@@ -4452,7 +4944,9 @@ async function agent(config, options, action, args) {
     const skill = await resolveAgentSkill(config, options, target);
     printFallbackNotice(skill, true);
     await fs.mkdir(baseDir, { recursive: true });
+    const previousMeta = await readAgentSkillMeta(baseDir);
     await fs.writeFile(path.join(baseDir, 'SKILL.md'), skill.markdown, 'utf8');
+    await writeAgentReferences(baseDir, skill.references, previousMeta);
     await fs.writeFile(agentSkillMetaPath(baseDir), `${JSON.stringify(agentSkillSidecar(target, skill), null, 2)}\n`, 'utf8');
     output({
       success: true,
@@ -4461,6 +4955,7 @@ async function agent(config, options, action, args) {
       path: baseDir,
       skillSource: skill.source,
       generatedAt: skill.meta?.generatedAt || null,
+      referenceCount: skill.references?.length || 0,
       fallback: skill.source === 'fallback',
     }, options);
     return;
@@ -4501,6 +4996,9 @@ async function main() {
   if (command === 'auth' && subcommand === 'use') return useProfile(config, options, rest[0]);
   if (command === 'context') return contextCommand(config, options, subcommand);
   if (command === 'skills' && subcommand === 'list') return listSkills(config, options);
+  if (command === 'skills' && subcommand === 'describe') return describeSkill(config, options, rest[0]);
+  if (command === 'skills' && subcommand === 'manifest') return capabilityManifest(config, options);
+  if (command === 'media-guides') return mediaGuides(config, options, subcommand, rest[0]);
   if (command === 'tools' && subcommand === 'list') return listTools(config, options);
   if (command === 'tools' && subcommand === 'describe') return describeTool(config, options, rest[0]);
   if (command === 'ask') return askWorkflow(config, options, [subcommand, ...rest]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipit-ai/cli",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "ClipIt CLI for connecting shell-capable agents to ClipIt.",
   "type": "module",
   "bin": {