@supatent/skills 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supatent/skills",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Claude Code and Codex CLI content authoring skills for Supatent CMS",
   "type": "module",
   "bin": {

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:**

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

@@ -168,6 +168,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
@@ -241,6 +242,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
@@ -296,3 +298,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-codex/supatent-content-landing/SKILL.md

@@ -238,6 +238,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 `#`
@@ -329,6 +330,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
@@ -382,3 +384,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-codex/supatent-core/SKILL.md

@@ -63,8 +63,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.
@@ -168,6 +169,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:
@@ -214,7 +225,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-codex/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-codex/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:**