@se-studio/skills 1.0.37 → 1.0.39

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @se-studio/skills
 
+## 1.0.39
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.38
+
+### Patch Changes
+
+- Extend the local content index with a reference catalog, automatic sync, and bundled skills for cms-edit.
+
+  - **Content index (schema v2)** — index `template`, `articleType`, `tagType`, and `tag` in SQLite alongside assets and media
+  - **Automatic index sync** — index-backed commands call `ensureContentIndex`; full rebuild when missing or schema-outdated, incremental upsert when stale (>24h). Manual `index sync` always full rebuilds
+  - **`list --type template|articleType|tagType|tag`** — index-preferred listing with `--force-cma` escape hatch; template `--slug` filters by cmsLabel
+  - **`resolve --type template --label`** — resolve templates by cmsLabel; reference types use index with CMA fallback
+  - **`index dump --reference-only` / `--reference-type`** — browse the reference catalog
+  - **Duplicate detection** — ambiguous slug/label matches throw `ReferenceCatalogAmbiguityError`
+  - **File lock** — single writer per index database during sync
+  - **`requireMediaIndex` removed** — replaced by async `ensureContentIndex`
+  - **Bundled skills** — `sync:skills` copies cms-edit skills from `@se-studio/skills`; setup wizard can install into `.agents/skills`
+
 ## 1.0.37
 
 ### Patch Changes

package/README.md

@@ -57,6 +57,26 @@ Claude Code uses a naive frontmatter parser; violations cause descriptions to si
 3. Sync: `pnpm skills:sync`
 4. Add a changeset if publishing `@se-studio/skills`
 
+### cms-edit bundled skills (`@se-studio/contentful-cms`)
+
+The CLI ships a **subset** of skills under `packages/contentful-cms/skills/` for `cms-edit skill install`. Those files are **generated** from this package:
+
+| Canonical source (`packages/skills/skills/`) | Bundled name (`packages/contentful-cms/skills/`) |
+|---------------------------------------------|--------------------------------------------------|
+| `contentful-cms-core` | `core` |
+| `contentful-cms-templates` | `templates` |
+| `contentful-cms-setup` | `setup` |
+
+After editing any `contentful-cms-*` skill here, run:
+
+```bash
+pnpm --filter @se-studio/contentful-cms sync:skills
+```
+
+Do not edit `packages/contentful-cms/skills/` directly. See `packages/contentful-cms/docs/SKILLS.md`.
+
+**Do not use `.claude/skills/` in the repo** as a skill source — it is untracked and local. Use `.agents/skills/` (via `pnpm skills:sync`) or `cms-edit skill install`.
+
 ## References
 
 - [Anthropic skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)

package/package.json

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

package/skills/contentful-cms-alt-text-audit/SKILL.md

@@ -17,7 +17,7 @@ If no brand context is available, ask the user about any brand-specific terms be
 
 1. **Get all pages**: `cms-edit sitemap`
 2. **For each page** (or a specific page if the user specified one):
-   a. `cms-edit open /<slug>`
+   a. `cms-edit open --page-slug /<slug>` (or `--article-slug` for articles)
    b. `cms-edit snapshot` — identify components with visual/image/media fields
    c. For each image-bearing component:
       - `cms-edit read @ref` to inspect fields

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

@@ -40,20 +40,23 @@ To get the path to the full README (e.g. for an LLM to read): `cms-edit --docs`
 ### Step 1: Open a page
 
 ```bash
-# By slug
-cms-edit open /pricing
+# By page slug (trailing slash OK)
+cms-edit open --page-slug /pricing
+
+# By page cmsLabel (when editors use cmsLabel heavily)
+cms-edit open --page-cms-label "Pricing page"
 
 # By slug with explicit space
-cms-edit --space om1 open /pricing
+cms-edit --space om1 open --page-slug /pricing
 
 # By Contentful entry ID
-cms-edit open 4xKj2abcDef --id
+cms-edit open --id 4xKj2abcDef
 
 # Home page (slug is 'index')
-cms-edit open /
+cms-edit open --page-slug /
 ```
 
-**Slug `open`:** matches **page**, **article**, **articleType**, and **tag** by `fields.slug` (in that order; first match wins). For **template** or **navigation**, use `open <id> --id` or `cms-edit nav open`.
+**Flat lookup flags:** provide **exactly one** primary flag per `open` / `resolve` / `nav open`. See `cms-edit help lookup`. Run `cms-edit index sync` so catalog types resolve from the local index.
 
 ### Step 2: Read the snapshot
 
@@ -236,7 +239,7 @@ Same as Component plus:
 
 When adding body content and a CTA (e.g. PDF download) to an article:
 
-1. `cms-edit open <article-slug>` (or `open <id> --id`)
+1. `cms-edit open --article-slug <slug>` (or `open --id <id>`)
 2. Set body: `cms-edit rtf @<ref> body --markdown "..."` or `--markdown --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>`).
@@ -341,10 +344,33 @@ cms-edit set @c5 links linkId4 --links --append
 
 ## Assets
 
+**Content index:** Run `cms-edit index sync` once per space before asset search, media-by-filename list, asset audit, or `--if-exists-by-filename`. The same sync indexes the full **content catalog** (pages, articles, taxonomy, navigation, templates) for fast `list`, `open`, and `resolve`. Default sync uses the **Preview API** (draft content). See `cms-edit help index-sync` and `cms-edit help lookup`.
+
 ```bash
-# Search for an asset
+cms-edit index sync
+cms-edit index status
+cms-edit list --type page
+cms-edit list --type template
+cms-edit resolve --tag-type-slug topic
+
+# Published-only index (optional)
+cms-edit index sync --published
+
+# Search for an asset by title (requires index)
 cms-edit asset search "hero background"
 
+# Search by fileName
+cms-edit asset search --filename istockphoto-123.jpg
+cms-edit asset search --filename-match 'istockphoto-.*'
+
+# Upload from local file, URL, or base64
+cms-edit asset upload ./poster.jpg --title "Poster"
+cms-edit asset upload --url https://example.com/image.jpg --if-exists-by-filename
+cms-edit asset upload --base64 "$B64" --mime image/png --file-name poster.png
+
+# Upload and create a Media wrapper in one step
+cms-edit asset upload ./figure.png --with-media --media-name "Figure 1" --media-position Middle
+
 # Get asset details
 cms-edit asset info 5xKj2abcDef
 
@@ -352,11 +378,15 @@ cms-edit asset info 5xKj2abcDef
 cms-edit asset set @c0 visual 5xKj2abcDef
 ```
 
+JSON output for upload (`CMS_EDIT_JSON=1`): `{ ok, id, fileName, url, mediaId?, mediaIds? }`. Max upload size is **10MB** per file.
+
+**Idempotent upload:** `--if-exists-by-filename` is check-then-create. Do not upload the same `fileName` in parallel — serialize per fileName or re-run to converge.
+
 ## Navigation
 
 ```bash
-# Open a navigation entry
-cms-edit nav open main-navigation
+# Open a navigation entry (navigation uses `name`, not slug)
+cms-edit nav open --nav-name "Main navigation"
 
 # Add a new item
 cms-edit nav add --label "Pricing" --slug /pricing
@@ -384,8 +414,39 @@ cms-edit create page --slug /about-us --title "About Us" \
 
 # Create a new article (requires articleType entry ID)
 cms-edit create article --slug /blog/my-post --title "My Post" --article-type-id 3abcDef456
+
+# Create taxonomy entries (draft only)
+cms-edit create tag-type --slug conference-venue --name "Conference Venue"
+cms-edit create article-type --slug resources/publications --name "Publications"
+cms-edit create tag --slug poster-presentation --name "Poster Presentation" --tag-type-slug presentation-type
+# cmsLabel defaults to "<tagType name> — <tag name>" when --cms-label omitted
+cms-edit create tag --slug easl-congress-2026 --name "EASL Congress 2026" --tag-type publication-source \
+  --description "Research presented at EASL Congress 2026." --featured-image <logoAssetId>
+
+# Full fields via JSON
+cms-edit create tag --json-file tag.json --tag-type presentation-type --if-not-exists
+
+# Batch bootstrap
+cms-edit create taxonomy-from-json --file taxonomy.json --if-not-exists
+
+# Idempotent single-entry creates
+cms-edit ensure tag-type --slug conference-venue --name "Conference Venue"
+cms-edit ensure tag --slug asco-2025 --name "ASCO 2025" --tag-type conference-venue \
+  --description "Annual ASCO conference." --featured-image <logoAssetId>
+```
+
+See `cms-edit help fields-taxonomy` and `cms-edit help taxonomy-from-json` for field reference and batch schema.
+
+**Idempotent taxonomy:** `--if-not-exists` / `ensure` are check-then-create — safe for sequential imports, not for parallel creates on the same slug.
+
+```bash
+# Resolve taxonomy IDs without a session
+cms-edit resolve --tag-type-slug presentation-type
+cms-edit resolve --tag-name "ASCO 2025" --tag-type-name "Conference Venue"
 ```
 
+Use flat flags: `--page-slug`, `--article-cms-label`, `--tag-slug`, `--template-label`, etc. (`cms-edit help lookup`).
+
 ## Search and Discovery
 
 ```bash
@@ -403,9 +464,16 @@ cms-edit list --type article --slug my-article    # article with a specific slug
 cms-edit list --type article --has-field tags      # articles where tags field is non-empty
 
 # Resolve any entry or asset by ID (no open session required)
-cms-edit resolve 4xKj2abcDefGhijK                 # entry: shows type, title, slug, status
-cms-edit resolve 7pQrStuvWxyzAbc                  # asset: shows title, fileName, URL
-cms-edit resolve <id> --json                       # full Contentful object
+cms-edit resolve --id 4xKj2abcDefGhijK             # entry: shows type, title, slug, status
+cms-edit resolve --id 7pQrStuvWxyzAbc              # asset: shows title, fileName, URL
+cms-edit resolve --tag-type-slug presentation-type
+cms-edit resolve --tag-slug asco-2025 --tag-type-slug conference-venue
+cms-edit resolve --tag-type-slug presentation-type --json
+
+# Find Media entries by asset
+cms-edit list --type media --asset-id 7pQrStuvWxyzAbc
+cms-edit list --type media --asset-filename istockphoto-123.jpg
+cms-edit list --type media --asset-filename-match 'istockphoto-.*'
 ```
 
 To resolve a **tag entry ID** to its slug or label (e.g. for constructing article URLs such as `/resources/publications/<tag>/<slug>`):
@@ -420,8 +488,8 @@ cms-edit resolve <tag-entry-id>
 
 ```bash
 # Specify space explicitly
-cms-edit --space brightline open /home
-cms-edit --space om1 open /pricing
+cms-edit --space brightline open --page-slug /home
+cms-edit --space om1 open --page-slug /pricing
 ```
 
 Or set `CMS_EDIT_SPACE=om1` environment variable.
@@ -430,7 +498,7 @@ Or set `CMS_EDIT_SPACE=om1` environment variable.
 
 ```bash
 # 1. Open the page
-cms-edit open /about-us
+cms-edit open --page-slug /about-us
 
 # 2. Find the hero component
 cms-edit snapshot
@@ -456,7 +524,7 @@ cms-edit save
 
 ### Update an existing article
 ```bash
-cms-edit open /blog/old-title --id  # or by slug
+cms-edit open --article-slug /blog/old-title  # or cms-edit open --id <id>
 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"
@@ -465,7 +533,7 @@ cms-edit save
 
 ### Add a new section to a page
 ```bash
-cms-edit open /products
+cms-edit open --page-slug /products
 cms-edit types component  # discover what's available
 cms-edit add CTA --after @c3
 cms-edit set @c4 heading "Ready to get started?"
@@ -476,7 +544,7 @@ cms-edit save
 
 ### Reorder page sections
 ```bash
-cms-edit open /home
+cms-edit open --page-slug /home
 cms-edit snapshot  # see current order
 cms-edit move @c3 --after @c1  # move section 3 to position 2
 cms-edit save
@@ -623,8 +691,8 @@ cms-edit sitemap --include page,article  # Include articles too
 Inspect a page without affecting your active session.
 
 ```bash
-cms-edit peek /pricing   # Show snapshot of /pricing; your active session is unchanged
-cms-edit peek <id> --id  # Look up by entry ID
+cms-edit peek --page-slug /pricing   # Show snapshot of /pricing; your active session is unchanged
+cms-edit peek --id <entryId>         # Look up by entry ID
 ```
 
 ## Batch Operations (run)
@@ -805,8 +873,8 @@ cms-edit sitemap --include page,article      # Include articles
 Use `--session <name>` or `CONTENTFUL_CMS_SESSION=<name>` to isolate parallel workflows.
 
 ```bash
-cms-edit --session agent-1 open /pricing
-cms-edit --session agent-2 open /blog
+cms-edit --session agent-1 open --page-slug /pricing
+cms-edit --session agent-2 open --article-slug /blog
 ```
 
 ## Related skills

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

@@ -10,7 +10,7 @@ Use this skill when creating or editing **navigation** entries and their items i
 ## 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)
+2. **Open** the nav: `cms-edit nav open --nav-name "Main menu"` or `cms-edit nav open --nav-id <id>` (printed after create/clone)
 3. **Add items** (new or existing):
    ```bash
    # Create a new nav item with a page link
@@ -48,7 +48,7 @@ This creates new copies of every NavigationItem and links them into the new navi
 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 nav open --nav-name "Main menu"
 cms-edit snapshot          # root is @c0; items are @c1, @c2, …
 cms-edit read @root        # same as @c0
 ```
@@ -73,7 +73,7 @@ cms-edit set @c0 visual <media-entry-id> --link
 Navigation entries are often linked from templates as **menu** or **footer**:
 
 ```bash
-cms-edit open <template-id> --id
+cms-edit open --id <template-id>
 cms-edit set @root menu <nav-entry-id> --link
 cms-edit set @root footer <footer-nav-id> --link
 cms-edit save

package/skills/contentful-cms-seo-descriptions/SKILL.md

@@ -19,7 +19,7 @@ If no brand context is available, ask the user about their brand voice and targe
 2. **For each page** (or a specific page):
    a. **Read page content** using `fetch_page_markdown` (from the site-workflows MCP server) to understand what the page covers
    b. **Check current SEO**:
-      - `cms-edit open /<slug>`
+      - `cms-edit open --page-slug /<slug>` (or `--article-slug` for articles)
       - `cms-edit read @page seoDescription` (or `read @page` for all fields)
    c. **Analyse** the page — primary purpose, problem it solves, desired user action
    d. **Generate** a meta description following the guidelines below

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

@@ -11,7 +11,7 @@ Use this skill when creating or editing **templates** (layout shells with preCon
 
 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`
+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`