@supatent/skills 0.4.0 → 0.5.1

package/README.md

@@ -1,10 +1,10 @@
 # @supatent/skills
 
-Claude Code content authoring skills for [Supatent CMS](https://supatent.ai).
+Claude Code and Codex CLI content authoring skills for [Supatent CMS](https://supatent.ai).
 
 ## What this does
 
-Installs AI-powered content authoring skills into your Claude Code environment. Once installed, Claude Code can create and manage CMS content through natural conversation — blog posts, landing pages, and more.
+Installs AI-powered content authoring skills for Claude Code and Codex CLI. Once installed, agents can create and manage CMS content through natural conversation — blog posts, landing pages, and more.
 
 ## Quick start
 
@@ -12,15 +12,40 @@ Installs AI-powered content authoring skills into your Claude Code environment.
 npx @supatent/skills
 ```
 
-This installs skill files to `.claude/skills/` in your project. Then use `/supatent:core` in Claude Code to get started.
+In interactive terminals, the installer prompts for a target:
+
+- `claude`
+- `codex`
+- `both`
+
+In non-interactive environments (CI), the default is `claude`.
+
+### Explicit target selection
+
+```bash
+# Claude Code
+npx @supatent/skills --target claude
+
+# Codex CLI
+npx @supatent/skills --target codex
+
+# Both
+npx @supatent/skills --target both
+```
+
+Use `--codex-home` to override Codex install location (default: `$CODEX_HOME` or `~/.codex`):
+
+```bash
+npx @supatent/skills --target codex --codex-home /path/to/codex-home
+```
 
 ## Included skills
 
-| Skill | Command | Description |
-|-------|---------|-------------|
-| Core | `/supatent:core` | Schema management, content operations, validation |
-| Blog | `/supatent:blog` | Create and edit blog posts with structured fields |
-| Landing | `/supatent:landing` | Build landing pages with configurable sections |
+| Skill | Claude Code | Codex CLI | Description |
+|-------|-------------|-----------|-------------|
+| Core | `/supatent:core` | `supatent-core` | Schema management, content operations, validation |
+| Blog | `/supatent:content-blog` | `supatent-content-blog` | Create and edit blog posts with structured fields |
+| Landing | `/supatent:content-landing` | `supatent-content-landing` | Build landing pages with configurable sections |
 
 ## Updating
 
@@ -36,7 +61,7 @@ npx @supatent/skills --force
 
 - Node.js >= 20
 - A Supatent CMS project with `@supatent/cli` configured
-- Claude Code
+- Claude Code and/or Codex CLI
 
 ## License
 

package/bin/install.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 // bin/install.mjs - Self-contained zero-dependency installer for @supatent/skills
-// Copies bundled skill files to .claude/skills/ with manifest tracking.
+// Copies bundled skill files to Claude Code and/or Codex CLI skill directories.
 
 import { readFile, writeFile, mkdir, copyFile, readdir, stat } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 
 // ---------------------------------------------------------------------------
@@ -16,8 +17,10 @@ import { createInterface } from 'node:readline/promises';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const SKILLS_SOURCE_DIR = join(__dirname, '..', 'skills');
-const TARGET_SUBDIR = join('.claude', 'skills');
+const CLAUDE_SKILLS_SOURCE_DIR = join(__dirname, '..', 'skills');
+const CODEX_SKILLS_SOURCE_DIR = join(__dirname, '..', 'skills-codex');
+const CLAUDE_TARGET_SUBDIR = join('.claude', 'skills');
+const VALID_TARGETS = new Set(['claude', 'codex', 'both']);
 
 // ---------------------------------------------------------------------------
 // Exported helpers (for testability)
@@ -65,6 +68,109 @@ export async function confirm(message, { force = false } = {}) {
   }
 }
 
+/**
+ * Prompt install target when not explicitly provided.
+ * Defaults to "claude" when stdin is non-interactive.
+ */
+export async function promptInstallTarget({ force = false } = {}) {
+  if (force || !process.stdin.isTTY) return 'claude';
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log('Select installation target:');
+    console.log('  1) Claude Code');
+    console.log('  2) Codex CLI');
+    console.log('  3) Both');
+
+    while (true) {
+      const answer = (await rl.question('Target [1/2/3] (default: 1): ')).trim().toLowerCase();
+
+      if (answer === '' || answer === '1' || answer === 'claude') {
+        return 'claude';
+      }
+      if (answer === '2' || answer === 'codex') {
+        return 'codex';
+      }
+      if (answer === '3' || answer === 'both') {
+        return 'both';
+      }
+
+      console.log('Invalid choice. Enter 1, 2, 3, claude, codex, or both.');
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Parse command line args.
+ */
+export function parseArgs(argv) {
+  const parsed = {
+    force: false,
+    help: false,
+    target: null,
+    codexHome: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '--force' || arg === '-f' || arg === '--yes' || arg === '-y') {
+      parsed.force = true;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+      continue;
+    }
+
+    if (arg === '--target') {
+      i += 1;
+      if (!argv[i]) {
+        throw new Error('Missing value for --target. Use: claude, codex, or both.');
+      }
+      parsed.target = argv[i];
+      continue;
+    }
+
+    if (arg.startsWith('--target=')) {
+      parsed.target = arg.slice('--target='.length);
+      continue;
+    }
+
+    if (arg === '--codex-home') {
+      i += 1;
+      if (!argv[i]) {
+        throw new Error('Missing value for --codex-home.');
+      }
+      parsed.codexHome = argv[i];
+      continue;
+    }
+
+    if (arg.startsWith('--codex-home=')) {
+      parsed.codexHome = arg.slice('--codex-home='.length);
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (parsed.target) {
+    parsed.target = parsed.target.toLowerCase();
+    if (!VALID_TARGETS.has(parsed.target)) {
+      throw new Error(`Invalid --target value: ${parsed.target}. Use: claude, codex, or both.`);
+    }
+  }
+
+  return parsed;
+}
+
 /**
  * Read and parse .manifest.json. Returns null if missing or invalid.
  */
@@ -161,60 +267,76 @@ export async function getVersion() {
   return pkg.version;
 }
 
-// ---------------------------------------------------------------------------
-// Main installer flow
-// ---------------------------------------------------------------------------
-
-async function main() {
-  const args = process.argv.slice(2);
-  const force = args.includes('--force');
+/**
+ * Resolve default Codex home.
+ */
+export function getDefaultCodexHome() {
+  return process.env.CODEX_HOME ? resolve(process.env.CODEX_HOME) : join(homedir(), '.codex');
+}
 
-  const version = await getVersion();
-  const cwd = process.cwd();
-  const claudeDir = join(cwd, '.claude');
-  const targetDir = join(cwd, TARGET_SUBDIR);
-  const manifestPath = join(targetDir, 'supatent-core', '.manifest.json');
+function printHelp() {
+  console.log('Usage: npx @supatent/skills [options]');
+  console.log('');
+  console.log('Options:');
+  console.log('  --target <claude|codex|both>  Installation target (prompts when omitted in TTY)');
+  console.log('  --codex-home <path>           Override Codex home (default: $CODEX_HOME or ~/.codex)');
+  console.log('  -f, --force                   Auto-confirm prompts and overwrite user-modified files');
+  console.log('  -y, --yes                     Alias for --force');
+  console.log('  -h, --help                    Show this help');
+}
 
-  // -----------------------------------------------------------------------
-  // Step a: Check .claude/ directory
-  // -----------------------------------------------------------------------
-  let claudeExists = false;
+async function ensureDirectoryExists(dirPath, missingMessage, { force }) {
+  let exists = false;
   try {
-    const s = await stat(claudeDir);
-    claudeExists = s.isDirectory();
+    const s = await stat(dirPath);
+    exists = s.isDirectory();
   } catch {
     // does not exist
   }
 
-  if (!claudeExists) {
-    console.log('\x1b[33m!\x1b[0m No .claude/ directory found. This installer creates skill files for Claude Code.');
-    const ok = await confirm('Create .claude/ directory and continue?', { force });
-    if (!ok) {
-      console.log('Aborted.');
-      process.exitCode = 1;
-      return;
-    }
-    await mkdir(claudeDir, { recursive: true });
+  if (exists) return true;
+
+  if (missingMessage) {
+    console.log(`\x1b[33m!\x1b[0m ${missingMessage}`);
   }
 
+  const ok = await confirm(`Create ${dirPath} and continue?`, { force });
+  if (!ok) {
+    console.log('Aborted.');
+    return false;
+  }
+
+  await mkdir(dirPath, { recursive: true });
+  return true;
+}
+
+async function installSkillBundle({
+  sourceDir,
+  targetDir,
+  manifestPath,
+  targetLabel,
+  startHint,
+  force,
+  version,
+}) {
   // -----------------------------------------------------------------------
-  // Step b: Walk source skills/ directory and build source map
+  // Step a: Build source map
   // -----------------------------------------------------------------------
-  const sourceMap = await buildSourceMap(SKILLS_SOURCE_DIR);
+  const sourceMap = await buildSourceMap(sourceDir);
   const sourceFiles = Object.keys(sourceMap);
 
   // -----------------------------------------------------------------------
-  // Step c: Read existing manifest
+  // Step b: Read existing manifest
   // -----------------------------------------------------------------------
   const manifest = await readManifest(manifestPath);
 
   // -----------------------------------------------------------------------
-  // Step d: Compute diff
+  // Step c: Compute diff
   // -----------------------------------------------------------------------
   const diff = await computeDiff(sourceMap, manifest, targetDir);
 
   // -----------------------------------------------------------------------
-  // Step e: Handle user-modified files
+  // Step d: Handle user-modified files
   // -----------------------------------------------------------------------
   const filesToCopy = [...diff.newFiles, ...diff.changed];
   const skippedFiles = [];
@@ -232,14 +354,14 @@ async function main() {
   // Check if anything to do
   // -----------------------------------------------------------------------
   if (filesToCopy.length === 0 && skippedFiles.length === 0) {
-    console.log(`\x1b[32m\u2713\x1b[0m Already up to date (v${version})`);
+    console.log(`\x1b[32m\u2713\x1b[0m Already up to date (${targetLabel}, v${version})`);
     console.log('');
-    console.log('  Run \x1b[36m/supatent:core\x1b[0m to get started');
+    console.log(`  ${startHint}`);
     return;
   }
 
   // -----------------------------------------------------------------------
-  // Step f: Copy files
+  // Step e: Copy files
   // -----------------------------------------------------------------------
   const isFreshInstall = !manifest;
 
@@ -263,7 +385,7 @@ async function main() {
   }
 
   // -----------------------------------------------------------------------
-  // Step g: Write manifest
+  // Step f: Write manifest
   // -----------------------------------------------------------------------
   const manifestFiles = {};
 
@@ -293,16 +415,103 @@ async function main() {
   await writeFile(manifestPath, JSON.stringify(manifestData, null, 2) + '\n');
 
   // -----------------------------------------------------------------------
-  // Step h: Print summary
+  // Step g: Print summary
   // -----------------------------------------------------------------------
   console.log('');
   if (isFreshInstall) {
-    console.log(`\x1b[32m\u2713\x1b[0m Installed ${filesToCopy.length} files to ${TARGET_SUBDIR}/ (v${version})`);
+    console.log(`\x1b[32m\u2713\x1b[0m Installed ${filesToCopy.length} files to ${targetDir} (${targetLabel}, v${version})`);
   } else {
-    console.log(`\x1b[32m\u2713\x1b[0m Updated ${filesToCopy.length} file${filesToCopy.length === 1 ? '' : 's'} in ${TARGET_SUBDIR}/ (v${version})`);
+    console.log(`\x1b[32m\u2713\x1b[0m Updated ${filesToCopy.length} file${filesToCopy.length === 1 ? '' : 's'} in ${targetDir} (${targetLabel}, v${version})`);
   }
   console.log('');
-  console.log('  Run \x1b[36m/supatent:core\x1b[0m to get started');
+  console.log(`  ${startHint}`);
+}
+
+async function installClaude({ cwd, force, version }) {
+  const claudeDir = join(cwd, '.claude');
+  const targetDir = join(cwd, CLAUDE_TARGET_SUBDIR);
+  const manifestPath = join(targetDir, 'supatent-core', '.manifest.json');
+
+  const ok = await ensureDirectoryExists(
+    claudeDir,
+    'No .claude/ directory found. This installer creates skill files for Claude Code.',
+    { force },
+  );
+  if (!ok) {
+    process.exitCode = 1;
+    return;
+  }
+
+  await installSkillBundle({
+    sourceDir: CLAUDE_SKILLS_SOURCE_DIR,
+    targetDir,
+    manifestPath,
+    targetLabel: 'Claude Code',
+    startHint: 'Run \x1b[36m/supatent:core\x1b[0m to get started',
+    force,
+    version,
+  });
+}
+
+async function installCodex({ force, version, codexHomeOverride = null }) {
+  const codexHome = codexHomeOverride ? resolve(codexHomeOverride) : getDefaultCodexHome();
+  const targetDir = join(codexHome, 'skills');
+  const manifestPath = join(targetDir, 'supatent-core', '.manifest.json');
+
+  const ok = await ensureDirectoryExists(
+    codexHome,
+    `No Codex home directory found at ${codexHome}.`,
+    { force },
+  );
+  if (!ok) {
+    process.exitCode = 1;
+    return;
+  }
+
+  await installSkillBundle({
+    sourceDir: CODEX_SKILLS_SOURCE_DIR,
+    targetDir,
+    manifestPath,
+    targetLabel: 'Codex CLI',
+    startHint: 'Restart Codex CLI to pick up new skills',
+    force,
+    version,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main installer flow
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const version = await getVersion();
+  const cwd = process.cwd();
+  const force = args.force;
+
+  const target = args.target || await promptInstallTarget({ force });
+
+  if (target === 'both') {
+    console.log('Installing Supatent skills for Claude Code...');
+    await installClaude({ cwd, force, version });
+    console.log('');
+    console.log('Installing Supatent skills for Codex CLI...');
+    await installCodex({ force, version, codexHomeOverride: args.codexHome });
+    return;
+  }
+
+  if (target === 'codex') {
+    await installCodex({ force, version, codexHomeOverride: args.codexHome });
+    return;
+  }
+
+  await installClaude({ cwd, force, version });
 }
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@supatent/skills",
-  "version": "0.4.0",
-  "description": "Claude Code content authoring skills for Supatent CMS",
+  "version": "0.5.1",
+  "description": "Claude Code and Codex CLI content authoring skills for Supatent CMS",
   "type": "module",
   "bin": {
     "supatent-skills": "bin/install.mjs"
   },
   "files": [
     "bin",
-    "skills"
+    "skills",
+    "skills-codex"
   ],
   "devDependencies": {
     "eslint": "^9.16.0",
@@ -21,6 +22,7 @@
     "supatent",
     "cms",
     "claude-code",
+    "codex-cli",
     "skills",
     "content-authoring"
   ],

package/skills/supatent-content-blog/SKILL.md

@@ -170,6 +170,7 @@ Generate a URL-friendly slug from the title (lowercase, hyphens, no special char
 **Body content:**
 - Default length: 1000-1500 words
 - Format: markdown with headings (H2, H3), paragraphs, lists, and emphasis as the content demands
+- For Supatent assets in the `body`, use slug links: `![Alt](asset-slug)`, `[Link](asset-slug)`, or `<img src="asset-slug" ...>`
 - SEO-conscious writing: include target keywords in the first paragraph, use semantic keyword variations throughout, structure headings around searchable concepts
 - Content-driven structure: do NOT use a rigid template. Let the topic dictate whether the post needs numbered lists, narrative flow, comparison tables, or a mix.
 - Match the tone and style the user selected in the interview
@@ -243,6 +244,7 @@ After writing, check `.supatent/.validation-status.json` for errors. Common JSON
 |-------|-------|-----|
 | `unsupported @type` | Using BlogPosting instead of Article | Change `@type` to `"Article"` |
 | `image: expected uri format` | Using asset slug instead of URL | Remove `image` or use a full URL |
+| `markdown references missing asset slug` | `body` contains an asset slug link with no matching local asset | Add/update `.supatent/assets/{slug}.{locale}.json` or change link target |
 | `required property 'name' is missing` | Author object missing name | Add `"name"` to the author Person object |
 
 ## Multi-Locale Translation
@@ -298,3 +300,4 @@ Format the guidance as:
 > Here are the images you will need for this post: [list with recommended sizes and format notes]
 
 Remind the user that images can be uploaded via the Supatent dashboard (drag-and-drop) or via the CLI asset upload flow. After uploading, set the `cover-image` field value to the asset slug returned by the upload.
+For in-body assets, embed with slug syntax (`![Alt](asset-slug)` or `<img src="asset-slug" ...>`), not raw URLs.

package/skills/supatent-content-landing/SKILL.md

@@ -240,6 +240,7 @@ Confirm these counts with the user during adaptive questions. Adjust if requeste
 - If context is too vague for a section, ask the user for more detail rather than generating filler
 - Match the tone preference from the interview throughout all sections
 - `features-list` on pricing tiers: use markdown bullet list format, one feature per line
+- In markdown fields, reference Supatent assets by slug: `![Alt](asset-slug)`, `[Link](asset-slug)`, or `<img src="asset-slug" ...>`
 - `is-featured` on pricing tiers: set `"true"` on the recommended/most popular tier, `"false"` on others
 - Image fields: leave empty string `""` -- note images needed in the Image Guidance section
 - CTA URLs: use the website URL from the interview if provided, otherwise use placeholder `#`
@@ -331,6 +332,7 @@ After writing, check `.supatent/.validation-status.json` for errors. Common JSON
 |-------|-------|-----|
 | `unsupported @type` | Using WebPage instead of Organization | Change `@type` to `"Organization"` |
 | `image: expected uri format` | Using asset slug instead of URL | Remove `image` or use a full URL |
+| `markdown references missing asset slug` | Markdown content references an unknown asset slug | Add/update `.supatent/assets/{slug}.{locale}.json` or change link target |
 | `mainEntity: required` | FAQPage missing Question array | Add at least one Question to `mainEntity` |
 
 ## Multi-Locale Translation
@@ -384,3 +386,4 @@ After content generation, provide a section-by-section image checklist. Only inc
 | Metadata | -- | -- | No images |
 
 Images can be uploaded via the Supatent dashboard (drag-and-drop) or the CLI asset upload flow. After uploading, set the image field value to the asset slug returned by the upload.
+For markdown fields, embed/link those assets with slug syntax (`![Alt](asset-slug)` or `<img src="asset-slug" ...>`).

package/skills/supatent-core/SKILL.md

@@ -64,8 +64,9 @@ npm view @supatent/skills version 2>/dev/null
 |------|-----------|--------------|
 | `text` | `textInput`, `textarea` | Plain string |
 | `number` | `numberInput` | Numeric value |
-| `image` | `singleImage`, `multiImage` | Image reference object(s) |
-| `markdown` | `markdownEditor` | Markdown string |
+| `image` | `singleImage`, `multiImage` | Asset slug string (`string`/`string[]`) or legacy object |
+| `video` | `singleVideo`, `multiVideo` | Asset slug string (`string`/`string[]`) or legacy object |
+| `markdown` | `markdownEditor` | Markdown string (supports asset slugs in links and image embeds) |
 | `jsonLd` | `jsonLdEditor` | JSON-LD structured data object |
 
 **Interface determines the UI editor**, not the storage format. For example, `text` with `textInput` gives a single-line input; `text` with `textarea` gives a multi-line editor.
@@ -169,6 +170,16 @@ Write a JSON file to `.supatent/content/{schemaSlug}/{itemSlug}.{locale}.json`:
 
 Field keys must match the field slugs defined in the schema. Each locale gets its own file (e.g., `my-post.en.json`, `my-post.fr.json`).
 
+### Markdown asset slug links
+
+For markdown fields, use asset slugs directly when linking or embedding Supatent assets:
+
+- `![Alt text](asset-slug)`
+- `[Link text](asset-slug)`
+- `<img src="asset-slug" width="1200" height="630" alt="...">`
+
+Do not use file extensions or full API URLs when referencing Supatent assets in markdown. Missing slugs generate warning-only `markdown-asset` validation warnings.
+
 ### Validating
 
 If dev mode is running, validation happens automatically on file save. Otherwise:
@@ -215,7 +226,7 @@ The `interface` value is not valid for the given `type`. Each field type only su
 
 ### "Unknown field type"
 
-Only five field types are supported: `text`, `number`, `image`, `markdown`, `jsonLd`. Check for typos or capitalization errors (`jsonLd` not `jsonld` or `JsonLd`).
+Six field types are supported: `text`, `number`, `image`, `video`, `markdown`, `jsonLd`. Check for typos or capitalization errors (`jsonLd` not `jsonld` or `JsonLd`).
 
 ### "Singleton must use default slug"
 

package/skills/supatent-references/schema-reference.md

@@ -13,6 +13,8 @@ Every field in a schema has a `type` and an `interface`. The type determines the
 | `number` | `numberInput` | `number` or `null` | Numeric input; `null` represents empty (distinct from `0`) |
 | `image` | `singleImage` | `string` or `null` | Asset slug string (e.g., `"hero-image"`), or legacy object with `assetPath` |
 | `image` | `multiImage` | `string[]` | Array of asset slug strings (e.g., `["hero", "banner"]`) |
+| `video` | `singleVideo` | `string` or `null` | Asset slug string (e.g., `"promo-video"`), or legacy object with `assetPath` |
+| `video` | `multiVideo` | `string[]` | Array of asset slug strings (e.g., `["intro-video", "demo-video"]`) |
 | `markdown` | `markdownEditor` | `string` | Markdown-formatted text |
 | `jsonLd` | `jsonLdEditor` | `object` | JSON-LD object with `@context` and `@type` |
 
@@ -24,6 +26,7 @@ Every field in a schema has a `type` and an `interface`. The type determines the
 text       -> textInput, textarea
 number     -> numberInput
 image      -> singleImage, multiImage
+video      -> singleVideo, multiVideo
 markdown   -> markdownEditor
 jsonLd     -> jsonLdEditor
 ```
@@ -75,7 +78,7 @@ Schema files live at `.supatent/schema/{slug}.json`. The complete structure:
 | `slug` | Yes | `string` | Unique within the schema. Lowercase alphanumeric with hyphens. |
 | `name` | Yes | `string` | Display name. Minimum 1 character. |
 | `description` | No | `string` | Optional description of the field's purpose. |
-| `type` | Yes | `string` | One of: `text`, `number`, `image`, `markdown`, `jsonLd` |
+| `type` | Yes | `string` | One of: `text`, `number`, `image`, `video`, `markdown`, `jsonLd` |
 | `interface` | Yes | `string` | Must be valid for the field's type (see compatibility map above). |
 | `order` | Yes | `number` | Integer >= 0. Controls display order in the editor. |
 
@@ -163,9 +166,25 @@ The file is a flat JSON object where keys are field slugs from the schema:
 | `number` | `number` or `null` | `42` or `null` |
 | `image` (singleImage) | `string` (asset slug) or `null` | `"hero-image"` |
 | `image` (multiImage) | `string[]` (asset slugs) | `["photo-1", "photo-2"]` |
+| `video` (singleVideo) | `string` (asset slug) or `null` | `"promo-video"` |
+| `video` (multiVideo) | `string[]` (asset slugs) | `["intro-video", "demo-video"]` |
 | `markdown` | `string` | `"# Heading\n\nParagraph"` |
 | `jsonLd` | `object` | `{ "@context": "https://schema.org", "@type": "Article" }` |
 
+### Markdown Asset Slug Syntax
+
+Markdown fields support direct asset slug references. Use these forms inside markdown content:
+
+- Image embed (resolved to optimized image URL): `![Alt text](asset-slug)`
+- Asset link (resolved to asset URL): `[Download file](asset-slug)`
+- HTML image tag (resolved to optimized image URL): `<img src="asset-slug" width="1200" height="630" alt="Hero">`
+
+Rules:
+
+- Use raw slugs only (example: `hero-image`), not full URLs and not file extensions.
+- Slugs must match `^[a-z0-9]+(?:-[a-z0-9]+)*$`.
+- Missing slugs produce `markdown-asset` warnings (non-blocking).
+
 ### File Naming
 
 - Collection: `{itemSlug}.{locale}.json` (e.g., `my-post.en.json`, `my-post.fr.json`)

package/skills/supatent-references/workflow-reference.md

@@ -173,6 +173,7 @@ All Supatent files live under the `.supatent/` directory in the project root:
 - `text` -> `textInput`, `textarea`
 - `number` -> `numberInput`
 - `image` -> `singleImage`, `multiImage`
+- `video` -> `singleVideo`, `multiVideo`
 - `markdown` -> `markdownEditor`
 - `jsonLd` -> `jsonLdEditor`
 
@@ -208,6 +209,19 @@ All Supatent files live under the `.supatent/` directory in the project root:
 
 **Fix:** Add the missing field to the content file with the correct value type.
 
+### Missing Markdown Asset Slug (Warning)
+
+**Warning:** `Field 'body': markdown references missing asset slug 'hero-image'`
+
+**Cause:** A markdown field references an asset slug that does not exist in local asset metadata. Checked forms include:
+- `![alt](asset-slug)`
+- `[text](asset-slug)`
+- `<img src="asset-slug" ...>`
+
+**Fix:** Create the asset metadata/file for that slug (for example `.supatent/assets/hero-image.en.json`) or update the markdown link to an existing slug.
+
+**Agent note:** This is warning-only (`type: "markdown-asset"`). It appears in `supatent validate`, `supatent dev`, and pre-push validation, but does not block sync.
+
 ### JSON-LD Validation Errors
 
 **Error:** `Field 'structured-data': @root: Missing required property "@context"` or `Missing required property "@type"`
@@ -333,7 +347,7 @@ The `.validation-status.json` file is written by `supatent validate` and `supate
 **Key fields for AI agents:**
 - `valid`: `true` if no errors (warnings are acceptable)
 - `errors[]`: Each error includes `path`, `message`, and `help` (actionable fix instruction)
-- `warnings[]`: Non-blocking issues (locale coverage, empty JSON-LD fields)
+- `warnings[]`: Non-blocking issues (locale coverage, empty JSON-LD fields, missing markdown asset slugs)
 - `trigger`: What caused this validation (`"file-change"`, `"manual"`, or `"startup"`)
 
 **Workflow for AI agents:**