@se-studio/contentful-cms 1.0.1

package/skills/core/SKILL.md

@@ -0,0 +1,483 @@
+# Skill: contentful-cms CLI
+
+Use this skill when you need to read or edit content in Contentful CMS using the `cms-edit` CLI tool.
+
+## Overview
+
+`cms-edit` lets you read and edit Contentful draft content without publishing. It uses a **snapshot → ref → edit → save** workflow:
+
+1. `open` a page to load the content tree into a session
+2. `snapshot` to see the tree with `@ref` labels
+3. `read` an entry to inspect its fields
+4. `set` / `rtf` to modify fields
+5. `diff` to review changes
+6. `save` to write drafts to Contentful (NEVER publishes)
+
+## Safety Rules
+
+**This tool CANNOT and WILL NOT:**
+- Publish any entry
+- Unpublish any entry
+- Archive or delete published entries
+- Upload new assets
+
+All `save` operations create **draft** versions. A human must review and publish in Contentful.
+
+## Prerequisites
+
+- `.contentful-cms.json` must exist in the project root (or ancestor directory)
+- A Contentful Management Token with editor-only permissions (no publish rights) must be set as an env var and referenced in the config
+
+To get the path to the full README (e.g. for an LLM to read): `cms-edit --docs`
+
+## Core Workflow
+
+### Step 1: Open a page
+
+```bash
+# By slug
+cms-edit open /pricing
+
+# By slug with explicit space
+cms-edit --space om1 open /pricing
+
+# By Contentful entry ID
+cms-edit open 4xKj2abcDef --id
+
+# Home page (slug is 'index')
+cms-edit open /
+```
+
+### Step 2: Read the snapshot
+
+```bash
+cms-edit snapshot
+```
+
+Output:
+```
+Page: /pricing  [4xKj2abc | published]  ·  om1
+
+  @c0   Component[HeroSimple]    "Transparent Pricing"        [published]
+  @c1   Component[RichText]      "How it works"               [published]
+  @c2   Collection[CardGrid]     "Plans"                      [published]
+    @c3   Component[Card]          "Starter"                  [published]
+    @c4   Component[Card]          "Pro"                      [draft]
+  @c5   Component[CTA]           "Get started today"          [published]
+```
+
+Use `snapshot -c` for compact output (types only, no labels).
+
+### Step 3: Read entry fields
+
+```bash
+# All fields summary
+cms-edit read @c0
+
+# Specific field (shows plain text for scalars, Markdown for rich text)
+cms-edit read @c0 heading
+cms-edit read @c1 body
+```
+
+### Step 4: Edit fields
+
+**Scalar fields** (heading, title, slug, showHeading, etc.):
+```bash
+cms-edit set @c0 heading "New heading text"
+cms-edit set @c0 showHeading true
+cms-edit set @c0 preHeading "Featured"
+cms-edit set @c0 anchor "hero-section"
+```
+
+**Entry link fields** (template, articleType, etc. — value is the linked entry ID):
+```bash
+cms-edit set @c0 template 3I0HxGKbUd173wIpFCsbVr --link
+```
+
+**Content arrays** (topContent, content, bottomContent, contents — replace or append entry links):
+```bash
+cms-edit set @p0 content @c1,@c2,@c3 --links
+cms-edit set @p0 bottomContent @c4 --links --append
+```
+
+**Rich text fields** (body, additionalCopy):
+```bash
+cms-edit rtf @c1 body "## Why it matters\n\nOur platform helps teams **move faster** with [confidence](https://example.com).\n\n- Instant setup\n- No code required\n- 99.9% uptime"
+```
+
+Markdown support:
+- `# Heading 1` through `###### Heading 6`
+- `**bold**`, `_italic_`, `***bold italic***`
+- `[link text](https://url)`
+- `- item` for unordered lists, `1. item` for ordered
+- `> blockquote`
+- `` `inline code` ``
+- `---` for horizontal rule
+
+Use `\n` for newlines when passing multiline Markdown as a shell argument. For long content, use a file or stdin:
+
+```bash
+cms-edit rtf @c1 body --file path/to/file.md
+cms-edit rtf @c1 body - < path/to/file.md
+```
+
+### Step 5: Review changes
+
+```bash
+cms-edit diff
+```
+
+Shows a diff of all modified fields across all changed entries.
+
+### Step 6: Save
+
+```bash
+cms-edit save
+```
+
+Writes all changes to Contentful as **drafts**. The changes are visible in Contentful's web app but NOT live until a human publishes them.
+
+After saving, the session is cleared automatically if all changes were saved.
+
+### Discard
+
+```bash
+cms-edit discard
+```
+
+Throws away all unsaved local changes without writing to Contentful.
+
+## Content Field Names
+
+Based on the SE Studio content model:
+
+### Component fields
+| Field | Type | Notes |
+|-------|------|-------|
+| `cmsLabel` | string | Internal name (required) |
+| `componentType` | string | Type discriminator (e.g. `HeroSimple`) |
+| `heading` | string | Main heading (only shown when `showHeading` is true) |
+| `showHeading` | boolean | Whether to display the heading |
+| `preHeading` | string | Text above the heading |
+| `postHeading` | string | Text below the heading |
+| `body` | rich text | Main body copy |
+| `additionalCopy` | rich text | Secondary body copy |
+| `anchor` | string | Section anchor ID |
+| `backgroundColour` | string | Background colour name |
+| `textColour` | string | Text colour name |
+
+### Collection fields
+Same as Component plus:
+| Field | Type | Notes |
+|-------|------|-------|
+| `collectionType` | string | Type discriminator (e.g. `CardGrid`) |
+
+### Page fields
+| Field | Type | Notes |
+|-------|------|-------|
+| `slug` | string | URL slug (no leading slash in CMS) |
+| `title` | string | SEO/display title |
+| `description` | string | Meta description |
+| `indexed` | boolean | Whether to index in search engines |
+
+## Order of operations: article + CTA
+
+When adding body content and a CTA (e.g. PDF download) to an article:
+
+1. `cms-edit open <article-slug>` (or `open <id> --id`)
+2. Set body: `cms-edit rtf @<ref> body "..."` or `--file path/to.md`. If you need to add a body component first, use `add` then `rtf`.
+3. `cms-edit add CTA --target bottomContent`
+4. Set CTA links: use `--type external --label "Download PDF" --href <url>` for an external PDF URL, or `--type download --label "Download PDF" --asset-id <asset-id>` for a Contentful asset (get the ID from `cms-edit asset search "..."` or `asset info <id>`).
+5. `cms-edit save`
+
+## Structure Commands
+
+### Add a new component
+
+```bash
+# Add at the end of page content
+cms-edit add HeroSimple
+
+# Add to article/page bottomContent (when session is an article or page)
+cms-edit add CTA --target bottomContent
+
+# Add after a specific component
+cms-edit add HeroSimple --after @c1
+
+# Add inside a collection
+cms-edit add Card --parent @c2
+
+# Add an explicit collection type
+cms-edit add CardGrid --content-type collection
+```
+
+Discover available types first:
+```bash
+cms-edit types component
+cms-edit types collection
+```
+
+### Remove a component
+
+```bash
+cms-edit remove @c3
+```
+
+If the entry is a draft and unreferenced elsewhere, it will be deleted on save. If it's published, it's unlinked only.
+
+### Move/reorder
+
+```bash
+# Move @c3 to after @c1
+cms-edit move @c3 --after @c1
+
+# Move to before @c1
+cms-edit move @c3 --before @c1
+
+# Move to first position
+cms-edit move @c3
+```
+
+## Links (CTAs)
+
+Put the ref **after the subcommand** (e.g. `links add @c5`). The `links add` command creates the link entry and attaches it to the CTA in one step.
+
+- **External:** `--type external --label "..." --href <url>` (required: `--href`)
+- **Internal:** use `--slug /page` to look up by slug, or `--id <entry-id>` to reference by Contentful entry ID (required: `--slug` or `--id`)
+- **Download:** `--type download --label "..." --asset-id <asset-id>` (required: `--asset-id`; get the ID from `asset search` or `asset info`)
+
+```bash
+# List current links
+cms-edit links list @c5
+
+# Add an external link
+cms-edit links add @c5 --type external --label "Learn more" --href https://example.com
+
+# Add an external PDF CTA (URL to the file)
+cms-edit links add @c5 --type external --label "Download PDF" --href "https://www.example.com/whitepaper.pdf"
+
+# Add an internal link by slug
+cms-edit links add @c5 --type internal --label "Pricing" --slug /pricing
+
+# Add an internal link by entry ID
+cms-edit links add @c5 --type internal --label "About" --id 4xKj2abcDef
+
+# Add a download link (Contentful asset)
+cms-edit links add @c5 --type download --label "Download PDF" --asset-id 5xKj2abcDef
+
+# Remove link at index 1
+cms-edit links remove @c5 1
+
+# Move link from index 2 to index 0
+cms-edit links move @c5 2 0
+```
+
+## Assets
+
+```bash
+# Search for an asset
+cms-edit asset search "hero background"
+
+# Get asset details
+cms-edit asset info 5xKj2abcDef
+
+# Set a visual field
+cms-edit asset set @c0 visual 5xKj2abcDef
+```
+
+## Navigation
+
+```bash
+# Open a navigation entry
+cms-edit nav open main-navigation
+
+# Add an item
+cms-edit nav add --label "Pricing" --slug /pricing
+cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
+```
+
+## Create New Entries
+
+```bash
+# Create a new page (session opens on the new entry)
+cms-edit create page --slug /about-us --title "About Us" --description "Learn about our team"
+
+# Create a new article (requires articleType entry ID)
+cms-edit create article --slug /blog/my-post --title "My Post" --article-type-id 3abcDef456
+```
+
+## Search and Discovery
+
+```bash
+# Search entries full-text
+cms-edit search "pricing page"
+cms-edit search "hero" --type component
+
+# List valid type values
+cms-edit types component
+cms-edit types collection
+```
+
+## Multi-space
+
+```bash
+# Specify space explicitly
+cms-edit --space brightline open /home
+cms-edit --space om1 open /pricing
+```
+
+Or set `CMS_EDIT_SPACE=om1` environment variable.
+
+## Complete Example: Update a Hero Section
+
+```bash
+# 1. Open the page
+cms-edit open /about-us
+
+# 2. Find the hero component
+cms-edit snapshot
+
+# 3. Read it to understand current state
+cms-edit read @c0
+
+# 4. Update the heading
+cms-edit set @c0 heading "We build for the future"
+
+# 5. Update the body copy
+cms-edit rtf @c0 body "## Our mission\n\nWe help companies **ship faster** and _smarter_.\n\n- Founded in 2018\n- 500+ clients\n- [Join us](/careers)"
+
+# 6. Review
+cms-edit diff
+
+# 7. Save as draft
+cms-edit save
+# → "Saved 1 entry as draft. A human must publish for changes to go live."
+```
+
+## Common Patterns
+
+### Update an existing article
+```bash
+cms-edit open /blog/old-title --id  # or by slug
+cms-edit set @p0 title "New Article Title"
+cms-edit set @p0 slug new-article-slug
+cms-edit set @p0 description "Updated description"
+cms-edit save
+```
+
+### Add a new section to a page
+```bash
+cms-edit open /products
+cms-edit types component  # discover what's available
+cms-edit add CTA --after @c3
+cms-edit set @c4 heading "Ready to get started?"
+cms-edit rtf @c4 body "Join thousands of teams who trust us."
+cms-edit links add @c4 --type external --label "Start free trial" --href https://app.example.com
+cms-edit save
+```
+
+### Reorder page sections
+```bash
+cms-edit open /home
+cms-edit snapshot  # see current order
+cms-edit move @c3 --after @c1  # move section 3 to position 2
+cms-edit save
+```
+
+## Screenshots
+
+The `screenshot` command captures a PNG of a component, collection, external component, person, or page using [agent-browser](https://github.com/vercel-labs/agent-browser).
+
+**Prerequisites:** `npm install -g agent-browser && agent-browser install`. For `@ref` and `--json-file`, the app must be running at `devBaseUrl`.
+
+**Config:** Add `devBaseUrl` to the space in `.contentful-cms.json` so the CLI knows where your dev server runs:
+```json
+{
+  "spaces": {
+    "om1": {
+      "devBaseUrl": "http://localhost:3013"
+    }
+  }
+}
+```
+If omitted, defaults to `http://localhost:3000` with a warning.
+
+### From session ref (full-fidelity)
+
+`cms-edit screenshot @c0` uses the app's convert API and `/cms-preview/render-json` so **all** entry types render with real converted data: component, collection, externalComponent, person. No separate "mock vs live" for refs.
+
+```bash
+# Any entry type (component, collection, externalComponent, person)
+cms-edit screenshot @c0
+
+# Full-page capture (auto-applied for component/collection)
+cms-edit screenshot @c0 --full
+
+# Just print URL
+cms-edit screenshot @c0 --url-only
+```
+
+### From JSON file (no Contentful)
+
+Screenshot an IBase* JSON file (e.g. exported from `cms-edit read @c0 --json` or a fixture). App must be running.
+
+```bash
+cms-edit screenshot --json-file path/to/component.json
+```
+
+### By type (showcase mock, no session)
+
+Uses `/cms-showcase/render` with mock data. Fast, no preview token.
+
+```bash
+cms-edit screenshot --component HeroSimple
+cms-edit screenshot --collection CardGrid
+cms-edit screenshot @c0 --embedded --full   # when using ref with showcase-style capture
+```
+
+### Page screenshots
+
+```bash
+# Current open page (uses session root slug)
+cms-edit screenshot
+
+# Explicit page slug
+cms-edit screenshot /pricing
+cms-edit screenshot /about-us --full
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--json-file <path>` | Read IBase* JSON from file and screenshot via render-json (no Contentful) |
+| `--live` | Legacy: use `/cms-preview/render?id=...` for ref (optional; @ref is already full-fidelity) |
+| `--out <path>` | Output file path (default: `./screenshot-<type>-<timestamp>.png`) |
+| `--full` | Full-page capture (passed to `agent-browser screenshot --full`) |
+| `--embedded` | Append `&embedded=true` to showcase URL (suppresses IframeHeightReporter) |
+| `--wait <ms>` | Wait milliseconds after page load before capturing (default: 500) |
+| `--url-only` | Print URL only, do not invoke agent-browser |
+| `--json` | Output `{ ok, url, file }` as JSON |
+
+### Visual diffing
+
+Use `agent-browser diff screenshot` to compare before/after a content change:
+
+```bash
+# 1. Capture baseline before editing
+cms-edit screenshot @c0 --out before.png
+
+# 2. Edit content
+cms-edit set @c0 heading "New heading"
+cms-edit save
+
+# 3. Capture after
+cms-edit screenshot @c0 --out after.png
+
+# 4. Diff
+agent-browser diff screenshot --baseline before.png after.png
+```
+
+## Related skills
+
+For templates see the **templates** skill; for navigation see the **navigation** skill; for rich text and embeds see the **rich-text** skill; for screenshots see the **screenshots** skill.

package/skills/manifest.json

@@ -0,0 +1,7 @@
+{
+  "core": "Main workflow, refs, session, and all cms-edit commands",
+  "templates": "Create and edit templates (preContent, postContent, menu, footer, colours)",
+  "navigation": "Create navigation, nav open/add, set nav item fields, remove",
+  "rich-text": "Rich text (rtf) and embeds (append/insert); Markdown support",
+  "screenshots": "Screenshot command, agent-browser requirement, mock vs live, --url-only"
+}

package/skills/navigation/SKILL.md

@@ -0,0 +1,18 @@
+# Skill: contentful-cms — Navigation
+
+Use this skill when creating or editing **navigation** entries and their items in Contentful via `cms-edit`.
+
+## Workflow
+
+1. **Create** a navigation: `cms-edit create navigation --label 'Main menu'`
+2. **Open** the nav: `cms-edit nav open <slug-or-id>` (or after create, use the printed open command)
+3. **Add** items: `cms-edit nav add --label "Pricing" --slug /pricing` or `--label "Docs" --href https://docs.example.com`; use `--after @cN` to insert after a ref.
+4. **Set** nav item fields (use snapshot refs): `cms-edit set @c1 label "New label"`, `cms-edit set @c1 page <entry-id> --link`, `cms-edit set @c1 externalUrl "https://..."`.
+5. **Remove** an item: `cms-edit remove @cN`
+6. **Save**: `cms-edit save`
+
+Navigation entries are often linked from templates as **menu** or **footer**; set those with `set ... menu <nav-id> --link` from a template session.
+
+## Related skills
+
+See the **core** skill for session, refs, and all commands. For templates that use menu/footer see the **templates** skill.

package/skills/rich-text/SKILL.md

@@ -0,0 +1,23 @@
+# Skill: contentful-cms — Rich text and embeds
+
+Use this skill when editing **rich text** fields (body, additionalCopy) and inserting **embedded entries/assets** via `cms-edit`.
+
+## Rich text (rtf)
+
+- **Replace** body with Markdown: `cms-edit rtf @c1 body "## Heading\n\nParagraph with **bold** and [link](https://example.com)."`
+- Use `--file path/to/file.md` or stdin (`-`) for long content.
+- Markdown supported: headings, bold/italic, links, lists, blockquote, inline code, `---`.
+
+Use **set** for scalar and link fields; use **rtf** only for rich text fields.
+
+## Embeds (v1: append/insert only)
+
+- **Append** an embedded entry: `cms-edit rtf embed @c1 body <entry-id>`
+- **Insert** at position: `cms-edit rtf embed @c1 body <entry-id> --at 0`
+- **Asset** embed: `cms-edit rtf embed @c1 body <asset-id> --asset`
+
+Editing or moving existing embeds is **not supported in v1**.
+
+## Related skills
+
+See the **core** skill for workflow, refs, and all commands.

package/skills/screenshots/SKILL.md

@@ -0,0 +1,32 @@
+# Skill: contentful-cms — Screenshots
+
+Use this skill when capturing **screenshots** of components, collections, pages, or persons with `cms-edit`. **Requires agent-browser** to be installed.
+
+## Prerequisites
+
+- `npm install -g agent-browser && agent-browser install`
+- Without agent-browser, the command exits with install instructions (use `--url-only` to only print the URL).
+- For `@ref` and `--json-file`: the app must be running at `devBaseUrl` (see `.contentful-cms.json`).
+
+## Commands
+
+- **From session ref** (full-fidelity): `cms-edit screenshot @c0` — uses the convert API and `/cms-preview/render-json` so **all** entry types render with real data: component, collection, externalComponent, person. Add `--full` for full-page capture (auto-applied for component/collection).
+- **From JSON file** (no Contentful): `cms-edit screenshot --json-file path/to/entry.json` — reads an IBase* JSON (e.g. from `read @c0 --json` or an export), base64-encodes it, and opens `/cms-preview/render-json?data=...`. Use to validate or screenshot without a session or preview token.
+- **By type** (no session, mock): `cms-edit screenshot --component HeroSimple`, `cms-edit screenshot --collection CardGrid` — uses `/cms-showcase/render` with mock data.
+- **Page**: `cms-edit screenshot` (current open page) or `cms-edit screenshot /pricing`
+- **URL only** (no agent-browser needed): `cms-edit screenshot @c0 --url-only`
+
+## Mock vs live (type-only mode only)
+
+When using `--component <type>` or `--collection <type>` (no session), the default is **mock** (showcase). Use `--live` with a ref to prefer the legacy direct preview URL; for `@ref`, full-fidelity is already the default via convert → render-json.
+
+- **Mock:** `/cms-showcase/render` with mock data; fast, no preview token.
+- **Live** (with ref): `cms-edit screenshot @c0 --live` — uses `/cms-preview/render?id=...`; equivalent for component/collection/externalComponent to the default @ref path.
+
+## Checking your work
+
+After editing content, run `cms-edit screenshot @ref` or `cms-edit screenshot /slug` to capture and verify. Use `--out before.png` / `--out after.png` and `agent-browser diff screenshot` for visual diffing. To validate a component from exported JSON, use `cms-edit screenshot --json-file <path>`.
+
+## Related skills
+
+See the **core** skill for session, open, and snapshot.

package/skills/templates/SKILL.md

@@ -0,0 +1,16 @@
+# Skill: contentful-cms — Templates
+
+Use this skill when creating or editing **templates** (layout shells with preContent, postContent, menu, footer) in Contentful via `cms-edit`.
+
+## Workflow
+
+1. **Create** a template: `cms-edit create template --label 'Campaign Landing'`
+2. **List** templates: `cms-edit list --type template`
+3. **Open** by ID: `cms-edit open <template-id> --id`
+4. Edit content: set **preContent** and **postContent** (content arrays) via session snapshot refs; use `add`, `set`, `remove`, `move` as for pages. Set **menu** and **footer** (single navigation links) with `cms-edit set @ref menu <nav-entry-id> --link` and same for `footer`.
+5. Set **colours**: `cms-edit set @ref backgroundColour Navy`, `cms-edit set @ref textColour White` (or project colour names).
+6. **Save**: `cms-edit save`
+
+## Related skills
+
+See the **core** skill for the full workflow (open, snapshot, set, save). For menu/footer navigation entries use the **navigation** skill.