@se-studio/skills 1.0.37 → 1.0.38

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @se-studio/skills
 
+## 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.38",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

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

@@ -341,10 +341,32 @@ 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 also indexes **templates**, **articleType**, **tagType**, and **tag** for fast `list --type` and taxonomy `--if-not-exists`. Default sync uses the **Preview API** (draft content). See `cms-edit help index-sync`.
+
 ```bash
-# Search for an asset
+cms-edit index sync
+cms-edit index status
+cms-edit list --type template
+cms-edit resolve --type tagType --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,6 +374,10 @@ 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
@@ -384,8 +410,34 @@ 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 presentation-type
+
+# 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
 ```
 
+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 --type tag-type --slug presentation-type
+```
+
+`resolve --type` accepts `page`, `article`, `articleType`, `tagType`, `tag` (kebab aliases such as `tag-type`).
+
 ## Search and Discovery
 
 ```bash
@@ -405,7 +457,14 @@ cms-edit list --type article --has-field tags      # articles where tags field i
 # 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 --type tagType --slug presentation-type
+cms-edit resolve --type tag --slug asco-2025
 cms-edit resolve <id> --json                       # full Contentful object
+
+# 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>`):