@se-studio/contentful-cms 0.0.0-next16-20260822103555

package/skills/editor-tasks/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: contentful-cms-editor-tasks
+description: "Route CMS editing intents to site task playbooks via tasks-index (hosted MCP resources or local editor-pack files)."
+---
+
+# Skill: cms-edit editor tasks
+
+Use this skill **before any Contentful edit** to pick the right capability playbook for the user's goal. Do not improvise workflows — read the site brain first.
+
+## Pit-of-success order
+
+1. **tasks-index** — which tasks apply on this site
+2. **capabilities** — what content types and bulk mechanisms exist
+3. **checklist** — pre-flight checks
+4. **overview** + **routing** — site rules and URL shapes
+5. **task-*** playbook — steps, confirmation gates, out-of-scope
+6. **components-index** — when creating or editing page content
+
+## Hosted (Claude Integrations + OAuth)
+
+Claude cannot read `cms-edit://customer/*` URIs directly — use the MCP tools:
+
+```text
+cms_edit ["customer", "tasks-index"]
+cms_edit ["customer", "capabilities"]
+cms_edit ["customer", "checklist"]
+cms_edit ["customer", "task-create-article"]   # example — pick from tasks-index
+```
+
+Or `cms_edit_customer` with resource `tasks-index`, then the `task-*` name from the index.
+
+**Never pass `--space`** on hosted MCP — the deployment is already bound to one site.
+
+After connect, verify with: `Read the cms-edit guide and tasks-index`.
+
+## Local (Cursor / Grok / Codex / CLI)
+
+Read committed files in the customer repo (paths vary by layout):
+
+| Layout | Editor pack |
+|--------|-------------|
+| Single-site | `cms-edit/editor-pack/` |
+| Multi-site | `cms-edit/<site>/editor-pack/` |
+
+Minimum reads:
+
+- `capabilities.json`
+- `tasks-index.md`
+- `checklist.md`
+- Matching `task-*.md` for the user's intent
+
+Then use **`contentful-cms-core`** for `cms-edit` CLI commands.
+
+## Confirmation gates (all tasks)
+
+Capability playbooks require:
+
+1. **Propose** scope to the user — wait for approval
+2. **Dry-run** when available (`--dry-run`, `bulk-rtf-replace --dry-run`, etc.)
+3. **`diff`** before every `save`
+4. **Summarize** what changed; remind that publish is manual in Contentful
+
+## Media default
+
+**Search and reuse assets first** (`index sync` → `asset search`). Upload only when no match; use `--if-exists-by-filename` when uploading.
+
+**Space-wide media audit** (filename, alt, size, dimensions, usage) → read **`task-media-review`**, then skill **`contentful-cms-media-review`** for the spreadsheet.
+
+## When the pack is stale
+
+Run `contentful-cms-regenerate-editor-pack` after:
+
+- New component/collection registrations
+- `docs/cms-guidelines/**` changes
+- `constants.ts` routing changes
+
+Then `cms-edit project doctor --project-config cms-edit/<site>/project.json`.
+
+## Related skills
+
+| Skill | When |
+|-------|------|
+| `contentful-cms-core` | CLI command reference |
+| `contentful-cms-setup` | First-time hosted MCP connect |
+| `contentful-cms-regenerate-editor-pack` | Refresh editor-pack in git |
+| `contentful-cms-media-review` | Space-wide asset audit + Excel report |

package/skills/manifest.json

@@ -0,0 +1,6 @@
+{
+  "core": "Use cms-edit CLI to read/edit Contentful content (open → snapshot → read → set/rtf → diff → save).",
+  "editor-tasks": "Route CMS editing intents to site task playbooks via tasks-index (hosted MCP resources or local editor-pack files).",
+  "templates": "Create or edit templates (preContent, postContent, menu, footer, colours) in Contentful via cms-edit.",
+  "setup": "Guide a user through connecting hosted cms-edit MCP for Claude or Grok (OAuth)."
+}

package/skills/setup/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: contentful-cms-setup
+description: "Guide a user through connecting hosted cms-edit MCP for Claude or Grok (OAuth)."
+---
+
+# Skill: cms-edit Setup
+
+Use this skill when the user wants to connect Claude or Grok to their Contentful site via **hosted cms-edit MCP**.
+
+Local stdio MCP and the setup wizard are **not supported**. Editors connect through the site's `/cms-edit` onboarding flow.
+
+---
+
+## Hosted setup (Claude Integrations + OAuth)
+
+Use when SE sent an **onboarding link** (e.g. `https://your-site.content.se.studio/cms-edit`).
+
+### Step 1: Connect to Claude
+
+1. Open the link SE sent (or **Connect to Claude** on `/cms-edit`)
+2. Confirm the connector in Claude Desktop or claude.ai
+3. Sign in with **Contentful** when prompted (same account SE invited to the space)
+
+Manual alternative: Claude → **Customize → Connectors** → Add custom connector → paste the MCP URL (`…/api/mcp`) → Connect.
+
+Full editor guide: `packages/contentful-cms/HOSTED.md`
+
+### Step 2: Verify
+
+In Claude, ask to read the cms-edit guide and **tasks-index**, then verify the connection. If `cms_edit` returns content, setup is complete.
+
+Use skill **`contentful-cms-editor-tasks`** for the tasks-index → capability playbook workflow.
+
+**Reconnect:** Settings → Integrations → Connect again if the connection stops working.
+
+---
+
+## Hosted setup (Grok Build)
+
+Use when the user wants cms-edit in **Grok Build** (not local stdio MCP).
+
+### Step 1: Configure Grok
+
+Add to `~/.grok/config.toml`:
+
+```toml
+[mcp_servers.cms-edit-<projectKey>]
+url = "https://<host>/api/mcp"
+enabled = true
+```
+
+The URL **must** end with `/api/mcp`. Use the MCP URL from the site's `/cms-edit` page.
+
+### Step 2: Connect
+
+1. In Grok, run `/mcps`
+2. Select the cms-edit server
+3. Press **`i`** to initiate OAuth (not just enable)
+4. Sign in with Contentful when prompted
+
+### Step 3: Verify
+
+Run `grok mcp doctor cms-edit-<projectKey>` or call `cms_edit_version` in a Grok session.
+
+**Reconnect:** `/mcps` → press `i` again if OAuth expires.
+
+Full guide: `packages/contentful-cms/docs/mcp/hosted-guide.md` (Grok Build section).
+
+---
+
+## Developers (CLI + skills, not local MCP)
+
+For engineering work in a site repo (Cursor, Grok, terminal):
+
+1. Configure `.contentful-cms.json` in the project (or `~/.contentful-cms.json`) with space credentials
+2. Run `npx skills add @se-studio/skills` or `pnpm skills:sync` in the monorepo
+3. Bundled cms-edit skills (`core`, `setup`, etc.) are included when you run `npx skills add @se-studio/skills`
+4. Read `cms-edit/<site>/editor-pack/tasks-index.md` before editing content
+
+Do **not** register a local `mcpServers.cms-edit` entry in Claude Desktop — use the hosted connector URL instead.
+
+---
+
+## Troubleshooting
+
+**OAuth / sign-in fails**
+→ Confirm the user was invited to the Contentful space and is signing in with the correct account. In Grok, use `/mcps` → press `i` (not just toggle). Confirm config URL ends with `/api/mcp`.
+
+**Grok: Failed to get tools after auth / auth required**
+→ On Vercel look for `[cms-edit:oauth] auth_failure`. `invalid_refresh_token` means the MCP refresh UUID is gone (rotation + parallel Grok sessions); cms-edit **3.6.1+** keeps the same refresh token. `missing_contentful_token` / `invalid_contentful_token` means the CMA cache is missing or Contentful rejected it — **3.5.3+** deletes the dead cache and returns `invalid_token` so Grok re-runs Contentful sign-in. If it still loops, delete the server’s entry in `~/.grok/mcp_credentials.json`, then `/mcps` → `i` and complete Contentful sign-in.
+
+**Grok browser flashes and closes**
+→ Usually a redirect_uri mismatch before cms-edit v2.7.7+; upgrade the hosted deployment and retry OAuth.
+
+**`cms_edit` tool not available**
+→ Reconnect via `/cms-edit` or Claude Integrations. Remove any legacy local MCP or `.mcpb` extension entries.
+
+**Connection works but wrong site**
+→ Each connector URL is site-specific; use the URL from the project's `/cms-edit` page.
+
+**Multiple cms-edit connectors enabled (Cowork)**
+→ Hosted MCP tools are labeled per site: server name `cms-edit-<projectKey>`, descriptions `[Site Name cms-edit] …`. Say “use **Brightline** cms-edit” and match that label. Verify with `cms_edit_version` → `projectKey`. Disable other cms-edit connectors for single-site work.

package/skills/templates/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: contentful-cms-templates
+description: "Create or edit templates (preContent, postContent, menu, footer, colours) in Contentful via cms-edit."
+---
+
+# 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 cmsLabel or ID: `cms-edit open --template-label "Default"` or `cms-edit open --id <template-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.