@supatent/skills 0.1.0

package/skills/content-landing/landing-sections.md

@@ -0,0 +1,360 @@
+# Landing Page Section Catalog
+
+Defines the schemas created by the landing page content skill. The SKILL.md references this file for schema generation. Each section is either a singleton (one content item) or a collection (multiple items).
+
+## Category 1: Above the Fold
+
+### landing-hero (Singleton)
+
+Main hero section with headline, subheadline, and call-to-action.
+
+```json
+{
+  "slug": "landing-hero",
+  "name": "Landing Hero",
+  "description": "Main hero section with headline, subheadline, and call-to-action",
+  "isSingleton": true,
+  "fields": [
+    { "slug": "headline", "name": "Headline", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "subheadline", "name": "Subheadline", "type": "text", "interface": "textarea", "order": 1 },
+    { "slug": "cta-text", "name": "CTA Text", "type": "text", "interface": "textInput", "order": 2 },
+    { "slug": "cta-url", "name": "CTA URL", "type": "text", "interface": "textInput", "order": 3 },
+    { "slug": "hero-image", "name": "Hero Image", "type": "image", "interface": "singleImage", "order": 4 }
+  ]
+}
+```
+
+Image guidance: Hero image: 1920x1080px or 16:9 ratio. Required for visual impact.
+
+### landing-announcement (Singleton)
+
+Top banner bar for announcements or promotions.
+
+```json
+{
+  "slug": "landing-announcement",
+  "name": "Landing Announcement",
+  "description": "Top banner bar for announcements or promotions",
+  "isSingleton": true,
+  "fields": [
+    { "slug": "text", "name": "Text", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "link-text", "name": "Link Text", "type": "text", "interface": "textInput", "order": 1 },
+    { "slug": "link-url", "name": "Link URL", "type": "text", "interface": "textInput", "order": 2 }
+  ]
+}
+```
+
+Image guidance: No images required.
+
+## Category 2: Social Proof
+
+### landing-logo (Collection)
+
+Client or partner logos for trust building.
+
+```json
+{
+  "slug": "landing-logo",
+  "name": "Landing Logo",
+  "description": "Client or partner logos for trust building",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "name", "name": "Name", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "logo-image", "name": "Logo Image", "type": "image", "interface": "singleImage", "order": 1 }
+  ]
+}
+```
+
+Default count: 5. Image guidance: Logo image: 200x80px or similar horizontal format. Required per logo.
+
+### landing-testimonial (Collection)
+
+Customer quotes and social proof.
+
+```json
+{
+  "slug": "landing-testimonial",
+  "name": "Landing Testimonial",
+  "description": "Customer quotes and social proof",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "quote", "name": "Quote", "type": "text", "interface": "textarea", "order": 0 },
+    { "slug": "author-name", "name": "Author Name", "type": "text", "interface": "textInput", "order": 1 },
+    { "slug": "author-title", "name": "Author Title", "type": "text", "interface": "textInput", "order": 2 },
+    { "slug": "author-company", "name": "Author Company", "type": "text", "interface": "textInput", "order": 3 },
+    { "slug": "author-image", "name": "Author Image", "type": "image", "interface": "singleImage", "order": 4 }
+  ]
+}
+```
+
+Default count: 3. Image guidance: Author image: 100x100px square. Optional but recommended.
+
+### landing-stat (Collection)
+
+Key metrics and statistics.
+
+```json
+{
+  "slug": "landing-stat",
+  "name": "Landing Stat",
+  "description": "Key metrics and statistics",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "value", "name": "Value", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "label", "name": "Label", "type": "text", "interface": "textInput", "order": 1 },
+    { "slug": "description", "name": "Description", "type": "text", "interface": "textInput", "order": 2 }
+  ]
+}
+```
+
+Default count: 3. Image guidance: No images required.
+
+## Category 3: Features and Info
+
+### landing-feature (Collection)
+
+Product features with title and description.
+
+```json
+{
+  "slug": "landing-feature",
+  "name": "Landing Feature",
+  "description": "Product features with title and description",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "title", "name": "Title", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "description", "name": "Description", "type": "text", "interface": "textarea", "order": 1 },
+    { "slug": "icon-image", "name": "Icon Image", "type": "image", "interface": "singleImage", "order": 2 }
+  ]
+}
+```
+
+Default count: 3. Image guidance: Icon image: 64x64px or SVG icon. Optional.
+
+### landing-pricing-tier (Collection)
+
+Pricing plans with features and CTA.
+
+```json
+{
+  "slug": "landing-pricing-tier",
+  "name": "Landing Pricing Tier",
+  "description": "Pricing plans with features and CTA",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "name", "name": "Name", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "price", "name": "Price", "type": "number", "interface": "numberInput", "order": 1 },
+    { "slug": "price-period", "name": "Price Period", "type": "text", "interface": "textInput", "order": 2 },
+    { "slug": "description", "name": "Description", "type": "text", "interface": "textarea", "order": 3 },
+    { "slug": "features-list", "name": "Features List", "type": "markdown", "interface": "markdownEditor", "order": 4 },
+    { "slug": "cta-text", "name": "CTA Text", "type": "text", "interface": "textInput", "order": 5 },
+    { "slug": "cta-url", "name": "CTA URL", "type": "text", "interface": "textInput", "order": 6 },
+    { "slug": "is-featured", "name": "Is Featured", "type": "text", "interface": "textInput", "order": 7 }
+  ]
+}
+```
+
+Default count: 3. Notes: `features-list` uses markdown with bullet list format (one feature per bullet). `is-featured` uses "true" or "false" as string values (no boolean field type in Supatent). Image guidance: No images required.
+
+### landing-team-member (Collection)
+
+Team members with name, role, and bio.
+
+```json
+{
+  "slug": "landing-team-member",
+  "name": "Landing Team Member",
+  "description": "Team members with name, role, and bio",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "name", "name": "Name", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "role", "name": "Role", "type": "text", "interface": "textInput", "order": 1 },
+    { "slug": "bio", "name": "Bio", "type": "markdown", "interface": "markdownEditor", "order": 2 },
+    { "slug": "photo", "name": "Photo", "type": "image", "interface": "singleImage", "order": 3 }
+  ]
+}
+```
+
+Default count: 3. Image guidance: Photo: 400x400px square. Required for team display.
+
+### landing-faq-item (Collection)
+
+Frequently asked questions and answers.
+
+```json
+{
+  "slug": "landing-faq-item",
+  "name": "Landing FAQ Item",
+  "description": "Frequently asked questions and answers",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "question", "name": "Question", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "answer", "name": "Answer", "type": "markdown", "interface": "markdownEditor", "order": 1 }
+  ]
+}
+```
+
+Default count: 5. Image guidance: No images required. FAQ answers use markdown for rich formatting (links, lists, emphasis).
+
+## Category 4: Conversion and Footer
+
+### landing-cta (Singleton)
+
+Primary call-to-action section.
+
+```json
+{
+  "slug": "landing-cta",
+  "name": "Landing CTA",
+  "description": "Primary call-to-action section",
+  "isSingleton": true,
+  "fields": [
+    { "slug": "headline", "name": "Headline", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "description", "name": "Description", "type": "text", "interface": "textarea", "order": 1 },
+    { "slug": "cta-text", "name": "CTA Text", "type": "text", "interface": "textInput", "order": 2 },
+    { "slug": "cta-url", "name": "CTA URL", "type": "text", "interface": "textInput", "order": 3 },
+    { "slug": "secondary-cta-text", "name": "Secondary CTA Text", "type": "text", "interface": "textInput", "order": 4 },
+    { "slug": "secondary-cta-url", "name": "Secondary CTA URL", "type": "text", "interface": "textInput", "order": 5 }
+  ]
+}
+```
+
+Image guidance: No images required.
+
+### landing-footer (Singleton)
+
+Page footer with company info.
+
+```json
+{
+  "slug": "landing-footer",
+  "name": "Landing Footer",
+  "description": "Page footer with company info",
+  "isSingleton": true,
+  "fields": [
+    { "slug": "company-name", "name": "Company Name", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "tagline", "name": "Tagline", "type": "text", "interface": "textInput", "order": 1 },
+    { "slug": "copyright-text", "name": "Copyright Text", "type": "text", "interface": "textInput", "order": 2 }
+  ]
+}
+```
+
+Image guidance: No images required.
+
+### landing-metadata (Singleton)
+
+Page metadata and structured data for SEO.
+
+```json
+{
+  "slug": "landing-metadata",
+  "name": "Landing Metadata",
+  "description": "Page metadata and structured data for SEO",
+  "isSingleton": true,
+  "fields": [
+    { "slug": "page-title", "name": "Page Title", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "page-description", "name": "Page Description", "type": "text", "interface": "textarea", "order": 1 },
+    { "slug": "json-ld", "name": "Organization Data", "type": "jsonLd", "interface": "jsonLdEditor", "order": 2 }
+  ]
+}
+```
+
+Conditional JSON-LD fields added based on section selection:
+- If FAQ section is selected, add: `{ "slug": "json-ld-faq", "name": "FAQ Data", "type": "jsonLd", "interface": "jsonLdEditor", "order": 3 }`
+- If pricing section is selected (SaaS product), add: `{ "slug": "json-ld-product", "name": "Product Data", "type": "jsonLd", "interface": "jsonLdEditor", "order": 4 }`
+
+Image guidance: No images required.
+
+## JSON-LD Guidance
+
+The landing-metadata singleton uses JSON-LD structured data fields. Each field stores a complete JSON-LD object.
+
+### Organization (always present)
+
+Used on every landing page. Stored in the `json-ld` field.
+
+- Required: `@context`, `@type`
+- Recommended: `name`, `url`, `description`
+- Optional: `sameAs` (social links array)
+- Do NOT include `logo` unless user provides an actual URL (asset slugs fail URI validation)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Company Name",
+  "url": "https://example.com",
+  "description": "Brief company description.",
+  "sameAs": [
+    "https://twitter.com/example",
+    "https://linkedin.com/company/example"
+  ]
+}
+```
+
+### FAQPage (conditional)
+
+Only when `landing-faq-item` section is selected. Stored in the `json-ld-faq` field. Generate FAQ entries from landing-faq-item content items.
+
+- Required: `@context`, `@type`, `mainEntity` (array of Question objects, min 1)
+- Each Question: `@type: "Question"`, `name`, `acceptedAnswer`
+- Each Answer: `@type: "Answer"`, `text`
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is your product?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Our product helps you do X."
+      }
+    }
+  ]
+}
+```
+
+### SoftwareApplication (conditional)
+
+Only when `landing-pricing-tier` section is selected for a SaaS product. Stored in the `json-ld-product` field. Do NOT use `Product` type -- it requires `image` which conflicts with the no-image decision. If the product is physical (not SaaS), skip the product JSON-LD entirely.
+
+- Required: `@context`, `@type`, `name`
+- Recommended: `applicationCategory`, `description`, `offers` (array of Offer objects)
+- Each Offer: `@type: "Offer"`, `price`, `priceCurrency`
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Product Name",
+  "applicationCategory": "BusinessApplication",
+  "description": "Brief product description.",
+  "offers": [
+    {
+      "@type": "Offer",
+      "price": "29",
+      "priceCurrency": "USD"
+    }
+  ]
+}
+```
+
+## Section Selection Summary
+
+| Section | Type | Default Count | Required Images |
+|---------|------|---------------|-----------------|
+| landing-hero | singleton | 1 | hero-image (1920x1080) |
+| landing-announcement | singleton | 1 | none |
+| landing-logo | collection | 5 | logo-image (200x80) |
+| landing-testimonial | collection | 3 | author-image (100x100, optional) |
+| landing-stat | collection | 3 | none |
+| landing-feature | collection | 3 | icon-image (64x64, optional) |
+| landing-pricing-tier | collection | 3 | none |
+| landing-team-member | collection | 3 | photo (400x400) |
+| landing-faq-item | collection | 5 | none |
+| landing-cta | singleton | 1 | none |
+| landing-footer | singleton | 1 | none |
+| landing-metadata | singleton | 1 | none |

package/skills/core/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: "supatent:core"
+description: "Use when working with Supatent CMS -- creating schemas, writing content, running CLI commands (init, dev, pull, push, validate), or managing the .supatent/ directory."
+user-invocable: true
+---
+
+# Supatent Core Skill
+
+Supatent is an AI-first multi-tenant SaaS CMS. This skill provides the knowledge base for working with Supatent projects: creating and editing schemas, authoring content, running CLI operations, and troubleshooting validation errors.
+
+When this skill is active, you have context for all schema field types, file conventions, CLI workflows, and common error patterns. For detailed reference material, load the supporting files listed in the Reference Files section below.
+
+## Environment Setup
+
+When this skill activates, perform these checks in order. Do not skip any.
+
+### 1. Check for project initialization
+
+Read `.supatent/config.json` in the current working directory.
+
+- **If the file exists:** The project is initialized. Extract `projectSlug` and `convexUrl` for context.
+- **If the file does not exist:** The project has not been initialized. Guide the user through setup:
+  ```bash
+  npx @supatent/cli init
+  ```
+  This creates the `.supatent/` directory with config, credentials, and initial schema/content directories.
+
+### 2. Check if dev mode is running
+
+Run:
+```bash
+pgrep -f "supatent dev"
+```
+
+- **If a process is found:** Dev mode is active. File changes will be validated and synced automatically.
+- **If no process is found:** Dev mode is not running. Offer the user these options:
+  1. Start dev mode in the background: `npx @supatent/cli dev &`
+  2. The user starts it themselves in a separate terminal
+  3. Fall back to manual validation with `npx @supatent/cli validate` after making changes
+
+Dev mode provides automatic validation on file save and real-time sync with the remote project.
+
+### 3. Check installed skill version
+
+Read the version from `.claude/skills/supatent/.manifest.json` (the `version` field).
+
+Then check the latest published version:
+```bash
+npm view @supatent/skills version 2>/dev/null
+```
+
+- **If the npm check fails** (no network, package not found): Skip silently and proceed.
+- **If the installed version matches the latest:** No action needed.
+- **If the installed version is older than the latest:** Inform the user:
+  > A newer version of the Supatent skills is available (installed: {installed}, latest: {latest}).
+  > Update with: `npx @supatent/skills@latest`
+  > Note: Claude Code must be restarted after updating for the new skill files to take effect.
+
+  If the user wants to update, run the command for them.
+
+## Quick Reference: Field Types
+
+| Type | Interfaces | Value Format |
+|------|-----------|--------------|
+| `text` | `textInput`, `textarea` | Plain string |
+| `number` | `numberInput` | Numeric value |
+| `image` | `singleImage`, `multiImage` | Image reference object(s) |
+| `markdown` | `markdownEditor` | Markdown string |
+| `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.
+
+For full details on field validation rules, constraints, and JSON-LD structured data types, read `../references/schema-reference.md`.
+
+## Quick Reference: File Locations
+
+All project files live under the `.supatent/` directory:
+
+| Path | Purpose |
+|------|---------|
+| `.supatent/config.json` | Project configuration (project slug, URLs) |
+| `.supatent/credentials.json` | API key (gitignored) |
+| `.supatent/schema/{slug}.json` | Schema definitions |
+| `.supatent/content/{schemaSlug}/{itemSlug}.{locale}.json` | Content items |
+| `.supatent/.validation-status.json` | Last validation result |
+| `.supatent/.supatent-lock.json` | Sync state (gitignored) |
+
+**Slug rules:**
+- Pattern: `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`
+- Lowercase alphanumeric with hyphens only
+- No leading or trailing hyphens, no consecutive hyphens
+
+**Singleton content** must always use the slug `default` (e.g., `content/settings/default.en.json`).
+
+## Reference Files
+
+Load these files when you need detailed information beyond the quick references above.
+
+### Schema details
+
+**File:** `../references/schema-reference.md`
+
+**Read when:** Creating or modifying schemas, adding fields, choosing field types and interfaces, working with JSON-LD structured data, or checking naming conventions.
+
+**Covers:** All field types with validation rules, interface options, field constraints, JSON-LD type catalog, schema naming best practices.
+
+### Workflow details
+
+**File:** `../references/workflow-reference.md`
+
+**Read when:** Running CLI commands (init, dev, pull, push, validate, status, merge), troubleshooting validation errors, resolving sync conflicts, or understanding the content authoring flow.
+
+**Covers:** Full CLI command reference, validation error catalog with fixes, sync conflict resolution, JSON-LD authoring guidance, content creation workflow.
+
+## Content Creation Skills
+
+For structured content creation workflows that include user interviews and multi-locale generation, use the dedicated content skills:
+
+- **Blog content:** Invoke `/supatent:content-blog` for blog posts, articles, and editorial content
+- **Landing page content:** Invoke `/supatent:content-landing` for landing pages, marketing pages, and promotional content
+
+These skills handle the full content creation workflow: interviewing the user about their content needs, generating schemas with appropriate sections, creating content across all configured locales, and validating the output.
+
+The core skill handles everything else -- schema management, CLI operations, general troubleshooting, and any task that does not require a structured content creation interview.
+
+## Common Operations
+
+### Creating a schema
+
+Write a JSON file to `.supatent/schema/{slug}.json`:
+
+```json
+{
+  "slug": "blog-post",
+  "name": "Blog Post",
+  "description": "Blog articles with title, body, and metadata",
+  "isSingleton": false,
+  "fields": [
+    {
+      "slug": "title",
+      "name": "Title",
+      "type": "text",
+      "interface": "textInput",
+      "order": 0
+    },
+    {
+      "slug": "body",
+      "name": "Body",
+      "type": "markdown",
+      "interface": "markdownEditor",
+      "order": 1
+    }
+  ]
+}
+```
+
+The filename must match the `slug` field (e.g., `blog-post.json` for slug `blog-post`).
+
+### Adding content
+
+Write a JSON file to `.supatent/content/{schemaSlug}/{itemSlug}.{locale}.json`:
+
+```json
+{
+  "title": "My First Post",
+  "body": "# Hello World\n\nThis is the body content."
+}
+```
+
+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`).
+
+### Validating
+
+If dev mode is running, validation happens automatically on file save. Otherwise:
+
+```bash
+npx @supatent/cli validate
+```
+
+Check `.supatent/.validation-status.json` for machine-readable results including error locations and fix suggestions.
+
+### Syncing with remote
+
+```bash
+# Check what has changed locally vs remotely
+npx @supatent/cli status
+
+# Download remote changes
+npx @supatent/cli pull
+
+# Upload local changes
+npx @supatent/cli push
+
+# Start continuous bidirectional sync
+npx @supatent/cli dev
+```
+
+## Troubleshooting
+
+### "Slug mismatch"
+
+The filename does not match the `slug` field inside the JSON file. Rename the file or update the slug field so they match.
+
+Example: File `my-post.json` must contain `"slug": "my-post"`.
+
+### "Invalid interface for type"
+
+The `interface` value is not valid for the given `type`. Each field type only supports specific interfaces:
+
+- `text` accepts `textInput` or `textarea`
+- `number` accepts `numberInput`
+- `image` accepts `singleImage` or `multiImage`
+- `markdown` accepts `markdownEditor`
+- `jsonLd` accepts `jsonLdEditor`
+
+### "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`).
+
+### "Singleton must use default slug"
+
+Content items for singleton schemas must use the slug `default`. Rename the file to `default.{locale}.json`.
+
+### "Duplicate field slugs"
+
+Each field within a schema must have a unique `slug`. Check for copy-paste errors in the fields array.
+
+### "Validation status file not updating"
+
+The file `.supatent/.validation-status.json` is written after each validation run. If it is not updating:
+1. Check that dev mode is running (`pgrep -f "supatent dev"`)
+2. Run validation manually: `npx @supatent/cli validate`
+3. Check file permissions on the `.supatent/` directory
+
+### "Connection refused" or "API key invalid"
+
+Verify the API key in `.supatent/credentials.json` is correct. Re-run `npx @supatent/cli init` if the project configuration has changed.