@supatent/skills 0.1.0

package/skills/references/schema-reference.md

@@ -0,0 +1,289 @@
+# Schema Reference
+
+> **Source of truth:** `packages/cli/src/constants.ts` and `packages/cli/src/types.ts` define the canonical field types, interfaces, and validation rules. `packages/jsonld-schemas/src/registry.ts` defines supported JSON-LD types. Phase 45 CI drift check will verify this file stays in sync with those sources.
+
+## Field Types and Interfaces
+
+Every field in a schema has a `type` and an `interface`. The type determines the data format; the interface determines the editing UI.
+
+| Type | Interface | Value Format | Notes |
+|------|-----------|-------------|-------|
+| `text` | `textInput` | `string` | Single-line text input |
+| `text` | `textarea` | `string` | Multi-line text area |
+| `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"]`) |
+| `markdown` | `markdownEditor` | `string` | Markdown-formatted text |
+| `jsonLd` | `jsonLdEditor` | `object` | JSON-LD object with `@context` and `@type` |
+
+**Important:** Each interface is valid only for its corresponding type. Using `textarea` with a `number` type (or any other mismatch) will fail validation.
+
+### Interface-Type Compatibility Map
+
+```
+text       -> textInput, textarea
+number     -> numberInput
+image      -> singleImage, multiImage
+markdown   -> markdownEditor
+jsonLd     -> jsonLdEditor
+```
+
+## Schema File Structure
+
+Schema files live at `.supatent/schema/{slug}.json`. The complete structure:
+
+```json
+{
+  "slug": "blog-post",
+  "name": "Blog Post",
+  "description": "Articles for the company blog",
+  "isSingleton": false,
+  "fields": [
+    {
+      "slug": "title",
+      "name": "Title",
+      "description": "The post headline",
+      "type": "text",
+      "interface": "textInput",
+      "order": 0
+    },
+    {
+      "slug": "body",
+      "name": "Body",
+      "type": "markdown",
+      "interface": "markdownEditor",
+      "order": 1
+    }
+  ]
+}
+```
+
+### Property Reference
+
+| Property | Required | Type | Description |
+|----------|----------|------|-------------|
+| `slug` | Yes | `string` | Must match filename (without `.json`). Lowercase alphanumeric with hyphens. |
+| `name` | Yes | `string` | Display name. Minimum 1 character. |
+| `description` | No | `string` | Optional description of the schema's purpose. |
+| `isSingleton` | Yes | `boolean` | Whether this schema has exactly one content item per locale. |
+| `fields` | Yes | `array` | Array of field definitions. |
+
+### Field Property Reference
+
+| Property | Required | Type | Description |
+|----------|----------|------|-------------|
+| `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` |
+| `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. |
+
+## Validation Rules
+
+These rules are enforced by `packages/cli/src/lib/validation.ts` using AJV (JSON Schema draft-07).
+
+### Slug Pattern
+
+All slugs (schema slugs, field slugs, content item slugs) must match:
+
+```
+^[a-z0-9]+(?:-[a-z0-9]+)*$
+```
+
+Valid: `blog-post`, `title`, `cover-image`, `my-post-1`
+Invalid: `Blog_Post`, `my post`, `_title`, `post--double`, `-leading`
+
+### Required Schema Properties
+
+The top-level object requires: `slug`, `name`, `isSingleton`, `fields`.
+
+### Required Field Properties
+
+Each field object requires: `slug`, `name`, `type`, `interface`, `order`.
+
+### Additional Rules
+
+- **Slug-filename match:** The `slug` value must match the filename (e.g., `blog-post.json` must have `"slug": "blog-post"`).
+- **Unique field slugs:** No two fields within the same schema can share a slug.
+- **Interface-type compatibility:** The `interface` must be valid for the given `type` (see compatibility map).
+- **Order minimum:** The `order` field must be a number >= 0.
+- **Name minimum length:** Both schema `name` and field `name` must have at least 1 character.
+
+## Singleton vs Collection
+
+### Singleton (`isSingleton: true`)
+
+One content item per locale. The content file **must** use slug `"default"`.
+
+File path: `.supatent/content/{schemaSlug}/default.{locale}.json`
+
+Use for: site settings, homepage hero, footer, navigation, about page, any content that exists as a single instance.
+
+Example schemas: `site-settings`, `homepage-hero`, `footer`, `about-page`
+
+### Collection (`isSingleton: false`)
+
+Multiple content items, each with its own slug.
+
+File path: `.supatent/content/{schemaSlug}/{itemSlug}.{locale}.json`
+
+Use for: blog posts, team members, FAQ items, product listings, testimonials, any content with multiple entries.
+
+Example schemas: `blog-post`, `team-member`, `faq-item`, `product`
+
+### Decision Guide
+
+| Question | Yes -> Singleton | No -> Collection |
+|----------|-----------------|-----------------|
+| Is there only ever one of this? | Singleton | Collection |
+| Would "list all X" make sense? | Collection | Singleton |
+| Does it have its own slug/URL? | Collection | Singleton |
+
+## Content File Structure
+
+Content files live at `.supatent/content/{schemaSlug}/{itemSlug}.{locale}.json`.
+
+The file is a flat JSON object where keys are field slugs from the schema:
+
+```json
+{
+  "title": "My First Blog Post",
+  "body": "# Welcome\n\nThis is the post content in **markdown**.",
+  "cover-image": "blog-hero",
+  "read-time": 5
+}
+```
+
+### Value Types by Field Type
+
+| Field Type | Expected Value | Example |
+|------------|---------------|---------|
+| `text` | `string` | `"Hello world"` |
+| `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"]` |
+| `markdown` | `string` | `"# Heading\n\nParagraph"` |
+| `jsonLd` | `object` | `{ "@context": "https://schema.org", "@type": "Article" }` |
+
+### File Naming
+
+- Collection: `{itemSlug}.{locale}.json` (e.g., `my-post.en.json`, `my-post.fr.json`)
+- Singleton: `default.{locale}.json` (e.g., `default.en.json`)
+- Locale format: `xx` or `xx-XX` (e.g., `en`, `en-US`, `fr`, `fr-CA`)
+
+### Content Validation Behavior
+
+- **Unknown fields** (not in schema) produce errors with "did you mean?" suggestions using Levenshtein distance.
+- **Missing fields** produce errors (required), except `jsonLd` fields which produce warnings.
+- **Wrong value types** produce errors with examples of correct format.
+
+## JSON-LD Types
+
+Supatent supports 23 JSON-LD types for structured data, validated by the `@supatent/jsonld-schemas` package. Types are organized by category.
+
+To use JSON-LD: add a field with `type: "jsonLd"` and `interface: "jsonLdEditor"`. The content value must include `@context` and `@type`:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "My Article Title",
+  "author": { "@type": "Person", "name": "Jane Doe" }
+}
+```
+
+### Commerce
+
+| @type | Label | Description |
+|-------|-------|-------------|
+| `Product` | Product | Physical or digital products for sale |
+| `SoftwareApplication` | Software App | Software applications and tools |
+| `VacationRental` | Vacation Rental | Short-term rental properties |
+
+### Content
+
+| @type | Label | Description |
+|-------|-------|-------------|
+| `Article` | Article | News articles, blog posts, editorial content |
+| `Recipe` | Recipe | Cooking and food preparation instructions |
+| `FAQPage` | FAQ Page | Frequently asked questions pages |
+| `Review` | Review | Product or service reviews |
+| `DiscussionForumPosting` | Discussion Forum Posting | Forum threads and community posts |
+| `QAPage` | Q&A Page | Question and answer pages |
+
+### Local
+
+| @type | Label | Description |
+|-------|-------|-------------|
+| `LocalBusiness` | Local Business | Physical business locations |
+| `Event` | Event | Events, conferences, meetups |
+
+### Education
+
+| @type | Label | Description |
+|-------|-------|-------------|
+| `Course` | Course | Educational courses and programs |
+| `Quiz` | Education Q&A | Educational quizzes and assessments |
+| `MathSolver` | Math Solver | Mathematical problem solvers |
+
+### Media
+
+| @type | Label | Description |
+|-------|-------|-------------|
+| `VideoObject` | Video | Video content and clips |
+| `Movie` | Movie | Feature films and movies |
+| `ImageMetadata` | Image Metadata | Image licensing and attribution |
+
+### People and Organizations
+
+| @type | Label | Description |
+|-------|-------|-------------|
+| `Organization` | Organization | Companies, nonprofits, institutions |
+| `ProfilePage` | Profile Page | Personal or professional profile pages |
+| `EmployerAggregateRating` | Employer Rating | Aggregated employer ratings and reviews |
+| `JobPosting` | Job Posting | Job listings and opportunities |
+
+### Navigation
+
+| @type | Label | Description |
+|-------|-------|-------------|
+| `BreadcrumbList` | Breadcrumb List | Site navigation breadcrumbs |
+
+### Data
+
+| @type | Label | Description |
+|-------|-------|-------------|
+| `Dataset` | Dataset | Structured data collections |
+
+### JSON-LD Validation
+
+- The `@context` field must be `"https://schema.org"`.
+- The `@type` must be one of the 23 supported types listed above.
+- Additional properties are validated against schema.org specifications by the `@supatent/jsonld-schemas` package (deep property checking).
+- Deprecated types generate warnings, not errors.
+- Empty `jsonLd` fields (missing from content) produce warnings rather than errors.
+
+## Naming Conventions
+
+### Schema Slugs
+
+Use lowercase-hyphenated: `blog-post`, `site-settings`, `team-member`
+
+Do not use: `blogPost`, `Blog_Post`, `BLOG-POST`
+
+### Field Slugs
+
+Use lowercase-hyphenated: `cover-image`, `read-time`, `full-name`
+
+Do not use: `coverImage`, `cover_image`, `CoverImage`
+
+### Display Names
+
+Use Title Case: `"Blog Post"`, `"Cover Image"`, `"Read Time"`
+
+### Content Item Slugs
+
+Use lowercase-hyphenated: `my-first-post`, `about-us`, `john-doe`
+
+Singleton items always use: `default`

package/skills/references/workflow-reference.md

@@ -0,0 +1,345 @@
+# Workflow Reference
+
+> **Source of truth:** `packages/cli/src/commands/*.ts` define CLI command behavior and flags. `packages/cli/src/lib/validation.ts` defines error messages. This file documents the content authoring workflow for AI agents operating through the Supatent CLI.
+
+## Content Authoring Flow
+
+The standard workflow for creating and managing content:
+
+1. **Initialize** (first time only):
+   ```bash
+   supatent init
+   ```
+   Sets up `.supatent/` directory with `config.json` and `credentials.json`.
+
+2. **Pull existing content:**
+   ```bash
+   supatent pull
+   ```
+   Downloads schemas, content, and assets from the remote CMS.
+
+3. **Start dev mode** (recommended for continuous work):
+   ```bash
+   supatent dev
+   ```
+   Enables bidirectional real-time sync via Convex WebSocket. File changes are automatically validated and pushed.
+
+4. **Create or edit schemas** in `.supatent/schema/` -- see schema-reference.md for field types and validation rules.
+
+5. **Create or edit content** in `.supatent/content/{schemaSlug}/` -- content files are flat JSON objects with field slugs as keys.
+
+6. **Validate** (automatic in dev mode, or manual):
+   ```bash
+   supatent validate
+   ```
+
+7. **Push** (automatic in dev mode, or manual):
+   ```bash
+   supatent push
+   ```
+
+8. **Check status** at any time:
+   ```bash
+   supatent status
+   ```
+
+## CLI Command Reference
+
+### `supatent init`
+
+Initialize Supatent in the current directory. Creates `.supatent/` with configuration files.
+
+| Flag | Description |
+|------|-------------|
+| `--base-url <url>` | Supatent app URL (default: `https://app.supatent.ai`) |
+| `--api-key <key>` | API key for authentication |
+| `--project <slug>` | Project slug to connect to |
+| `-y, --yes` | Skip confirmation prompts (non-interactive mode) |
+
+The init process auto-discovers the Convex HTTP URL via the Next.js discovery endpoint (`GET {baseUrl}/api/v1/discover`).
+
+### `supatent pull`
+
+Download schemas, content, and assets from the remote CMS. Uses delta pulling -- only downloads items that have changed since last sync.
+
+| Flag | Description |
+|------|-------------|
+| `--schema` | Pull schemas only |
+| `--content` | Pull content only |
+| `--no-assets` | Skip downloading asset binary files |
+| `-f, --force` | Overwrite local changes without confirmation |
+| `-v, --verbose` | Show detailed output |
+
+### `supatent push`
+
+Upload local changes to the remote CMS. Validates content before pushing. Uses batch atomic push.
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Show what would change without applying |
+| `--schema` | Push schemas only |
+| `--content` | Push content only |
+| `-f, --force` | Overwrite remote conflicts |
+| `-v, --verbose` | Show detailed output |
+
+### `supatent status`
+
+Show changes between local files and the remote CMS. Compares checksums to detect additions, modifications, and deletions in both directions.
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON (machine-readable) |
+| `-v, --verbose` | Show unchanged files too |
+
+### `supatent validate`
+
+Validate local schema, content, and asset files against the defined rules. Writes results to `.validation-status.json`.
+
+| Flag | Description |
+|------|-------------|
+| `[path]` | Optional path to validate (e.g., `schema/`, `content/`, or a specific file) |
+| `--json` | Output validation results as JSON |
+
+### `supatent dev`
+
+Start continuous bidirectional sync with the CMS. Watches for local file changes and subscribes to remote changes via Convex WebSocket.
+
+| Flag | Description |
+|------|-------------|
+| `-v, --verbose` | Show detailed output (watcher events, sync operations) |
+| `--no-watch` | Disable local file watching (pull-only mode) |
+| `--no-pull` | Disable remote change pulling (push-only mode) |
+
+### `supatent merge`
+
+Resolve conflicts between local and remote versions. Shows diffs and prompts for resolution strategy.
+
+| Flag | Description |
+|------|-------------|
+| `--schema <slug>` | Filter conflicts by schema slug |
+| `--content-slug <slug>` | Target specific content item (requires `--schema`) |
+| `--theirs` | Accept all remote changes (non-interactive) |
+| `--mine` | Keep all local changes (non-interactive) |
+| `-v, --verbose` | Show detailed output |
+
+## File Locations
+
+All Supatent files live under the `.supatent/` directory in the project root:
+
+| Path | Purpose | Git |
+|------|---------|-----|
+| `.supatent/config.json` | Project configuration (base URL, Convex URL, project slug) | Tracked |
+| `.supatent/credentials.json` | API key storage | Gitignored |
+| `.supatent/schema/{slug}.json` | Schema definitions | Tracked |
+| `.supatent/content/{schemaSlug}/{itemSlug}.{locale}.json` | Content items | Tracked |
+| `.supatent/assets/{slug}.{ext}` | Asset binary files | Tracked |
+| `.supatent/assets/{slug}.{locale}.json` | Asset metadata sidecars (alt, title, description) | Tracked |
+| `.supatent/.supatent-lock.json` | Sync state and checksums | Gitignored |
+| `.supatent/.validation-status.json` | Last validation results (for AI agents) | Gitignored |
+
+## Common Validation Errors and Fixes
+
+### Slug Pattern Error
+
+**Error:** `root: must match pattern "^[a-z0-9]+(?:-[a-z0-9]+)*$"` or `fields[N].slug: must match pattern`
+
+**Cause:** Slug contains invalid characters (uppercase, underscores, spaces, consecutive hyphens, leading/trailing hyphens).
+
+**Fix:** Use only lowercase letters, numbers, and single hyphens. Example: `my-field-name`, not `myFieldName` or `my_field`.
+
+### Missing Required Property
+
+**Error:** `root: must have required property 'slug'` (or `name`, `isSingleton`, `fields`, `type`, `interface`, `order`)
+
+**Cause:** A required property is missing from the schema or field definition.
+
+**Fix:** Add the missing property. Required schema properties: `slug`, `name`, `isSingleton`, `fields`. Required field properties: `slug`, `name`, `type`, `interface`, `order`.
+
+### Unknown Field in Content
+
+**Error:** `Unknown field 'fieldName' is not defined in the schema`
+
+**Cause:** The content file contains a key that does not match any field slug in the schema.
+
+**Fix:** Check the schema's field slugs and use the exact slug. The validator suggests close matches (e.g., "Did you mean 'title'?"). Valid fields are listed in the error message.
+
+### Interface Not Valid for Type
+
+**Error:** `Field 'fieldSlug': interface 'textarea' is not valid for type 'number'`
+
+**Cause:** The field's `interface` is not compatible with its `type`.
+
+**Fix:** Use a compatible interface. Valid combinations:
+- `text` -> `textInput`, `textarea`
+- `number` -> `numberInput`
+- `image` -> `singleImage`, `multiImage`
+- `markdown` -> `markdownEditor`
+- `jsonLd` -> `jsonLdEditor`
+
+### Filename-Slug Mismatch
+
+**Error:** `Slug 'my-post' doesn't match filename 'blog-post.json'`
+
+**Cause:** The `slug` value inside the JSON file does not match the filename (without `.json`).
+
+**Fix:** Either change the `slug` property to match the filename, or rename the file to match the slug.
+
+### Duplicate Field Slugs
+
+**Error:** `Duplicate field slug: 'title' (appears at index 0 and 2)`
+
+**Cause:** Two fields in the same schema have identical slugs.
+
+**Fix:** Rename one of the duplicate fields to a unique slug.
+
+### Singleton Slug Error
+
+**Error:** `Singleton content file must use slug 'default', got 'my-settings'`
+
+**Cause:** A content file for a singleton schema uses a slug other than `"default"`.
+
+**Fix:** Rename the content file to `default.{locale}.json` (e.g., `default.en.json`).
+
+### Missing Content Field
+
+**Error:** `Field 'body' is missing from content`
+
+**Cause:** A field defined in the schema is not present in the content file.
+
+**Fix:** Add the missing field to the content file with the correct value type.
+
+### JSON-LD Validation Errors
+
+**Error:** `Field 'structured-data': @root: Missing required property "@context"` or `Missing required property "@type"`
+
+**Cause:** The JSON-LD object is missing required schema.org properties.
+
+**Fix:** Ensure the object includes at minimum:
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article"
+}
+```
+
+The `@type` must be one of the 23 supported types (see schema-reference.md for the full list). Additional property validation is handled by the `@supatent/jsonld-schemas` package.
+
+## JSON-LD Creation Guidance
+
+To add structured data to a schema:
+
+1. **Add a JSON-LD field to the schema:**
+   ```json
+   {
+     "slug": "structured-data",
+     "name": "Structured Data",
+     "type": "jsonLd",
+     "interface": "jsonLdEditor",
+     "order": 10
+   }
+   ```
+
+2. **Add the JSON-LD value in the content file:**
+   ```json
+   {
+     "structured-data": {
+       "@context": "https://schema.org",
+       "@type": "Article",
+       "headline": "My Article Title",
+       "author": {
+         "@type": "Person",
+         "name": "Jane Doe"
+       },
+       "datePublished": "2026-01-15"
+     }
+   }
+   ```
+
+3. **Requirements:**
+   - `@context` must be `"https://schema.org"` (required)
+   - `@type` must be one of the 23 supported types (required)
+   - Additional properties follow schema.org specifications for that type
+   - Deep property validation is handled by `@supatent/jsonld-schemas`
+
+4. **Common patterns:**
+   - Blog posts: `@type: "Article"` with `headline`, `author`, `datePublished`
+   - Products: `@type: "Product"` with `name`, `description`, `offers`
+   - FAQ sections: `@type: "FAQPage"` with `mainEntity` array of `Question` items
+   - Business pages: `@type: "LocalBusiness"` with `name`, `address`, `telephone`
+
+5. **Empty JSON-LD fields** produce warnings (not errors) -- they are optional for SEO enhancement.
+
+## Dev Mode Details
+
+Dev mode (`supatent dev`) provides continuous bidirectional sync:
+
+**Local to Remote (file watcher):**
+- Uses chokidar to watch the `.supatent/` directory for file changes
+- Debounces changes (300ms) to batch rapid edits
+- Auto-validates before pushing -- invalid files are not pushed
+- Updates the lock file after successful push
+
+**Remote to Local (Convex WebSocket):**
+- Subscribes to `draftWatch.draftChangeIndicator` reactive query via ConvexClient
+- Receives change events when any draft schema, content, or asset changes remotely
+- Triggers delta-pull on change, checking for conflicts first
+- Updates the lock file after successful pull
+
+**Remote checksum cache:** Dev mode caches remote checksums for 5 seconds to reduce API calls during rapid local edits. The cache is invalidated when a remote change event arrives.
+
+**If dev mode is not running:** Use `supatent validate` to check files after editing, and `supatent push` when ready to upload.
+
+## Validation Status File
+
+The `.validation-status.json` file is written by `supatent validate` and `supatent dev` after each validation run. AI agents should read this file to confirm whether their changes are valid.
+
+**Location:** `.supatent/.validation-status.json`
+
+**Structure:**
+```json
+{
+  "valid": true,
+  "timestamp": "2026-01-15T14:30:00.000Z",
+  "trigger": "file-change",
+  "summary": {
+    "filesChecked": 12,
+    "filesValid": 12,
+    "filesInvalid": 0,
+    "errorCount": 0,
+    "warningCount": 2
+  },
+  "errors": [],
+  "warnings": [
+    {
+      "path": "content/blog/my-post",
+      "type": "locale",
+      "message": "Missing locales: fr",
+      "help": "Create files: my-post.fr.json"
+    }
+  ],
+  "localeCoverage": {
+    "expected": ["en", "fr"],
+    "stats": [
+      {
+        "schemaSlug": "blog",
+        "totalItems": 5,
+        "completeItems": 3
+      }
+    ]
+  }
+}
+```
+
+**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)
+- `trigger`: What caused this validation (`"file-change"`, `"manual"`, or `"startup"`)
+
+**Workflow for AI agents:**
+1. Make changes to schema or content files
+2. If dev mode is running, wait for auto-validation
+3. If dev mode is not running, execute `supatent validate`
+4. Read `.supatent/.validation-status.json`
+5. If `valid: false`, read `errors[]` and fix each issue using the `help` text
+6. Repeat until `valid: true`