@se-studio/skills 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.0.6
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.5
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
 ## 1.0.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/skills/contentful-cms-core/SKILL.md

@@ -75,6 +75,16 @@ Page: /pricing  [4xKj2abc | published]  ·  om1
 
 Use `snapshot -c` for compact output (types only, no labels).
 
+**Ref cheat sheet:**
+| Ref | Resolves to |
+|-----|-------------|
+| `@root` | Root entry of the current session (works in any session type) |
+| `@p0` | Root entry — alias for `@root` in **page** and **article** sessions only |
+| `@c0` | Same as `@root` (first entry in depth-first traversal order) |
+| `@c1`, `@c2`, … | Child entries in depth-first traversal order |
+
+In **navigation sessions**, use `@root` or `@c0` for the nav root — `@p0` is not valid.
+
 ### Step 3: Read entry fields
 
 ```bash
@@ -108,10 +118,14 @@ Each token is `@ref:fieldName=value`. All values are scalar (string, boolean, nu
 cms-edit set @c0 template 3I0HxGKbUd173wIpFCsbVr --link
 ```
 
-**Content arrays** (topContent, content, bottomContent, contents — replace or append entry links):
+**Entry link arrays** (`--links` works on any field that is an array of entry links — not just the standard page content fields):
 ```bash
+# Standard page content arrays
 cms-edit set @p0 content @c1,@c2,@c3 --links
 cms-edit set @p0 bottomContent @c4 --links --append
+
+# Navigation items array (use @root or @c0 in a nav session)
+cms-edit set @root items <id1>,<id2>,<id3> --links
 ```
 
 **Rich text fields** (body, additionalCopy):
@@ -344,9 +358,16 @@ cms-edit asset set @c0 visual 5xKj2abcDef
 # Open a navigation entry
 cms-edit nav open main-navigation
 
-# Add an item
+# Add a new item
 cms-edit nav add --label "Pricing" --slug /pricing
 cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
+
+# Link an existing NavigationItem (share items across navigations)
+cms-edit nav add --existing-id <navigationItem-entry-id>
+
+# Clone a navigation (duplicates all items)
+cms-edit nav clone <source-nav-id>
+cms-edit nav clone <source-nav-id> --label "LP Nav" --slug lp-nav
 ```
 
 ## Create New Entries
@@ -436,7 +457,7 @@ cms-edit save
 ### 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 title "New Article Title"   # @p0 works in article sessions too
 cms-edit set @p0 slug new-article-slug
 cms-edit set @p0 description "Updated description"
 cms-edit save

package/skills/contentful-cms-navigation/SKILL.md

@@ -11,12 +11,73 @@ Use this skill when creating or editing **navigation** entries and their items i
 
 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`
+3. **Add items** (new or existing):
+   ```bash
+   # Create a new nav item with a page link
+   cms-edit nav add --label "Pricing" --slug /pricing
 
-Navigation entries are often linked from templates as **menu** or **footer**; set those with `set ... menu <nav-id> --link` from a template session.
+   # Create a new nav item with an external URL
+   cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
+
+   # Link an EXISTING NavigationItem entry (e.g. to share items across navigations)
+   cms-edit nav add --existing-id <navigationItem-entry-id>
+   cms-edit nav add --existing-id <id> --after @c1
+   ```
+4. **Set** nav item fields (use snapshot refs): `cms-edit set @c1 title "New label"`, `cms-edit set @c1 internal <page-entry-id> --link`, `cms-edit set @c1 link "https://..."`.
+5. **Set the items array directly** (e.g. to replace all items at once):
+   ```bash
+   cms-edit set @root items <id1>,<id2>,<id3> --links
+   ```
+6. **Remove** an item: `cms-edit remove @cN`
+7. **Save**: `cms-edit save`
+
+## Cloning a navigation
+
+To duplicate a navigation and all its items (e.g. for a landing page variant):
+
+```bash
+cms-edit nav clone <source-nav-id>
+# Optional: provide a custom label/slug for the clone
+cms-edit nav clone <source-nav-id> --label "LP Navigation" --slug lp-nav
+```
+
+This creates new copies of every NavigationItem and links them into the new navigation. Prints the new navigation ID and an `open` command.
+
+## Session refs
+
+In a navigation session, the root navigation entry is **`@c0`** (or the universal alias **`@root`**). The `@p0` alias only works in page/article sessions.
+
+```bash
+cms-edit nav open main-navigation
+cms-edit snapshot          # root is @c0; items are @c1, @c2, …
+cms-edit read @root        # same as @c0
+```
+
+## Visual fields (media wrapper)
+
+Visual fields expect a **`media` Entry link**, not a direct Asset ID. `cms-edit asset set` now auto-creates the wrapper:
+
+```bash
+cms-edit asset set @c0 visual <asset-id>
+# → auto-creates a media entry wrapping the asset, then sets visual to that entry
+```
+
+If you need to create the media wrapper manually:
+```bash
+cms-edit create media <asset-id>   # prints the media entry ID
+cms-edit set @c0 visual <media-entry-id> --link
+```
+
+## Linking navigation from a template
+
+Navigation entries are often linked from templates as **menu** or **footer**:
+
+```bash
+cms-edit open <template-id> --id
+cms-edit set @root menu <nav-entry-id> --link
+cms-edit set @root footer <footer-nav-id> --link
+cms-edit save
+```
 
 ## Related skills
 

package/skills/contentful-cms-setup/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: "contentful-cms:setup"
+description: "Guide a user through installing and configuring the cms-edit MCP server for Claude Desktop."
+---
+
+# Skill: cms-edit Setup
+
+Use this skill when the user wants to install or configure the `cms-edit` MCP server so Claude Desktop can read and edit Contentful content.
+
+## Overview
+
+The setup wizard handles everything automatically:
+- Collects the Contentful Management Token
+- Discovers spaces and environments via the Contentful API
+- Writes `~/.contentful-cms.json`
+- Updates the Claude Desktop config to register the `cms-edit` MCP server
+
+## Prerequisites
+
+The user needs:
+1. **Node.js** installed (LTS version from [nodejs.org](https://nodejs.org))
+2. **A Contentful Management Token** — see Step 1 below
+
+## Step 1: Get a Management Token
+
+Tell the user:
+
+> To get your Contentful Management Token:
+> 1. Log in to [contentful.com](https://app.contentful.com)
+> 2. Go to **Settings → API keys**
+> 3. Click the **Content management tokens** tab
+> 4. Click **Generate personal token**, name it `Claude Desktop`, and click **Generate**
+> 5. Copy the token — you won't see it again
+
+Ask them to confirm they have the token before continuing.
+
+## Step 2: Run the Setup Wizard
+
+Tell the user to open a terminal and run:
+
+```bash
+npx @se-studio/contentful-cms@latest setup
+```
+
+Walk them through what each prompt means:
+
+| Prompt | What to enter |
+|--------|--------------|
+| **Contentful Management Token** | The token they just copied (input will be hidden) |
+| **Which Contentful space?** | Only appears if the token has multiple spaces — pick the one they want to connect |
+| **Which environment?** | Auto-selects `master`; only asks if no `master` environment exists |
+| **Short name for this project** | A slug like `my-project` or `om1` — used as the key in the config file |
+| **Staging site URL** | Optional — their Vercel preview URL (e.g. `https://my-project.vercel.app`) |
+| **Vercel bypass token** | Optional — only if their staging site has deployment protection |
+
+## Step 3: Restart Claude Desktop
+
+After the wizard completes, tell the user:
+
+> Fully quit Claude Desktop and reopen it.
+> - **Mac:** Right-click the Dock icon → **Quit** (closing the window isn't enough)
+> - **Windows/Linux:** Close and reopen from the Start menu
+
+## Step 4: Verify
+
+Once they've reopened Claude Desktop, verify the setup worked by using the `cms_edit` tool:
+
+```
+cms_edit ["open", "/"]
+```
+
+If it returns a page structure, setup is complete. If it errors, see Troubleshooting below.
+
+## Troubleshooting
+
+**"Invalid management token"**
+→ The token may have been copied incorrectly or already expired. Generate a new one in Contentful and run the wizard again.
+
+**"No spaces found"**
+→ The token doesn't have access to any spaces. Check Contentful's token permissions — it needs at least read access to one space.
+
+**`cms_edit` tool not available after restart**
+→ Check the Claude Desktop config was written correctly:
+- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+It should contain an `mcpServers.cms-edit` entry. If missing, run the wizard again.
+
+**Adding another space**
+→ Run `npx @se-studio/contentful-cms@latest setup` again — it merges the new space into the existing config.