@se-studio/skills 1.0.36 → 1.0.38

package/CHANGELOG.md

@@ -1,9 +1,32 @@
 # @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
+
+- Bulk version bump: patch for all packages
+
 ## 1.0.36
 
 ### Patch Changes
 
+- Version bump: patch for changed packages
 - 17d37e2: Fix skill descriptions not appearing in Claude Code selector (#30): standardize SKILL.md frontmatter (name matches directory, single-line quoted description, no extra YAML fields). Add `pnpm skills:validate`. Skill slash names now match directory names (e.g. `contentful-cms-core` instead of `contentful-cms:core`).
 
 ## 1.0.35

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.36",
+  "version": "1.0.38",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/skills/contentful-cms-cms-guidelines/README.md

@@ -18,7 +18,7 @@ Guidelines are short markdown fragments — one per CMS type — that describe h
    pnpm --filter <appName> generate-showcase
    ```
    This writes `src/generated/showcase-examples.json`.
-3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
+3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](../se-marketing-sites-curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
 4. **Generate field list** — parse TypeScript types to produce structured field metadata:
    ```bash
    # From the app directory:
@@ -27,7 +27,7 @@ Guidelines are short markdown fragments — one per CMS type — that describe h
    # Or from repo root:
    pnpm --filter <appName> exec cms-generate-field-list --app-dir .
    ```
-5. **Generate guidelines** — run the [Generate CMS guidelines skill](.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md).
+5. **Generate guidelines** — run the [Generate CMS guidelines skill](../contentful-cms-generate-cms-guidelines/SKILL.md).
 
 Steps 1–3 only need to be repeated when content or component code changes significantly. Step 4 only needs to be repeated when TypeScript types change. Step 5 can be re-run at any time.
 
@@ -35,7 +35,7 @@ Steps 1–3 only need to be repeated when content or component code changes sign
 
 ## How to run guideline generation
 
-Use the Cursor skill at [`.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md`](.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
+Use the Cursor skill at [`../contentful-cms-generate-cms-guidelines/SKILL.md`](../contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
 
 | Mode | When to use |
 |---|---|
@@ -43,25 +43,29 @@ Use the Cursor skill at [`.agents/skills/contentful-cms-generate-cms-guidelines/
 | `single` | Regenerate one component after code changes |
 | `merge-only` | Rebuild `COMPONENT_GUIDELINES_FOR_LLM.md` after manual fragment edits |
 
-**Example: full from scratch for `example-om1`**
+**Example: full from scratch**
 
 Start the app:
+
 ```bash
-pnpm --filter example-om1 dev
+pnpm dev
+# Note the port from dev server output, or read devBaseUrl from .contentful-cms.json
 ```
 
 Then invoke the skill with:
-- App directory: `apps/example-om1`
+
+- App directory: `<appDir>` (e.g. `.` in an external project)
 - Mode: `full`
-- Discovery URL: `http://localhost:3013/api/cms/discovery/`
+- Discovery URL: `http://localhost:<PORT>/api/cms/discovery/`
 
 **Example: single component**
 
 Invoke the skill with:
-- App directory: `apps/example-se2026`
+
+- App directory: `<appDir>`
 - Mode: `single`
 - Type name: `Hero`
-- Discovery URL: `http://localhost:3012/api/cms/discovery/`
+- Discovery URL: `http://localhost:<PORT>/api/cms/discovery/`
 
 **Example: merge only**
 
@@ -109,8 +113,8 @@ New project-independent CLI. Reads the discovery API and writes collection and e
 
 ```bash
 cms-generate-collection-guidelines \
-  --discovery-url http://localhost:3010/api/cms/discovery/ \
-  --app-dir apps/example-brightline
+  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
+  --app-dir <appDir>
 ```
 
 Options:

package/skills/contentful-cms-cms-guidelines/generation-prompt.md

@@ -115,7 +115,7 @@ Also provided:
 - The field list from generated/cms-discovery/field-list.json.
 - The project theme from generated/cms-discovery/theme-context.md (palette names + typography scale).
 - The screenshot index from docs/cms-guidelines/screenshots/index.json (lists captured screenshots).
-- The app's devBaseUrl from .contentful-cms.json (e.g. "http://localhost:3010").
+- The app's devBaseUrl from .contentful-cms.json (e.g. "http://localhost:<PORT>").
 
 Produce a single markdown fragment for <COMPONENT_TYPE> following EXACTLY this structure:
 

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>`):

package/skills/contentful-cms-generate-all-guidelines/SKILL.md

@@ -65,9 +65,9 @@ All of these must be true before starting. Check each one.
 
 | Input | Example |
 |-------|---------|
-| App directory (absolute or repo-relative) | `apps/example-se2026` or `/home/nick/source/se/se-website-2026` |
-| Discovery URL | `http://localhost:3012/api/cms/discovery/` |
-| Port | `3012` |
+| App directory (absolute or repo-relative) | `apps/my-site` or `/path/to/project` |
+| Discovery URL | `http://localhost:<PORT>/api/cms/discovery/` |
+| Port / base URL | From `pnpm dev` output, or `devBaseUrl` in `<appDir>/.contentful-cms.json` |
 
 ---
 
@@ -197,9 +197,9 @@ IMPORTANT: Screenshots have already been captured. Skip Phase A entirely.
 Go straight to Phase B.
 
 Files to read before starting:
-- packages/skills/skills/contentful-cms-cms-guidelines/generation-prompt.md  (Phase B instructions)
-- packages/skills/skills/contentful-cms-cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
-- packages/skills/skills/contentful-cms-cms-guidelines/validation-prompt.md   (Phase D instructions)
+- ../contentful-cms-cms-guidelines/generation-prompt.md  (Phase B instructions)
+- ../contentful-cms-cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
+- ../contentful-cms-cms-guidelines/validation-prompt.md   (Phase D instructions)
 - <APP_DIR>/src/project/components/<TypeName>.tsx  (component source)
 - <APP_DIR>/generated/cms-discovery/field-list.json
 - <APP_DIR>/src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json

package/skills/contentful-cms-generate-cms-guidelines/SKILL.md

@@ -32,7 +32,7 @@ Guidelines are only meaningful when the showcase is populated with realistic dat
    pnpm --filter <appName> generate-showcase
    ```
    This writes `src/generated/showcase-examples.json` to the app.
-3. **Curate showcase mocks:** Follow the [curate-showcase-mocks skill](.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md) to produce `showcase-mocks.json`.
+3. **Curate showcase mocks:** Follow the [curate-showcase-mocks skill](../se-marketing-sites-curate-showcase-mocks/SKILL.md) to produce `showcase-mocks.json`.
 4. **Generate field list:**
    ```bash
    # From the app directory:
@@ -51,17 +51,14 @@ Guidelines are only meaningful when the showcase is populated with realistic dat
 | **App directory** | Repo-relative path, e.g. `apps/example-om1` or `apps/example-se2026` |
 | **Mode** | `full` \| `single` \| `merge-only` |
 | **Type name** | Required for `single` mode — the exact type name from discovery, e.g. `"Hero"` or `"Cards Grid"` |
-| **Discovery URL** | URL to the live app's discovery endpoint, e.g. `http://localhost:3013/api/cms/discovery/` |
+| **Discovery URL** | `http://localhost:<PORT>/api/cms/discovery/` — `<PORT>` from the running dev server (`pnpm dev`) |
+| **Port / base URL** | Dev script output, or `devBaseUrl` in `<appDir>/.contentful-cms.json` |
 
-**App ports** (app must be running for `full` and `single` modes):
+The app must be running for `full` and `single` modes. Confirm with:
 
-| App | Port | Discovery URL |
-|---|---|---|
-| example-brightline | 3010 | `http://localhost:3010/api/cms/discovery/` |
-| example-se2026 | 3012 | `http://localhost:3012/api/cms/discovery/` |
-| example-om1 | 3013 | `http://localhost:3013/api/cms/discovery/` |
-| example-empty | 3014 | `http://localhost:3014/api/cms/discovery/` |
-| example-brightlifekids | 3015 | `http://localhost:3015/api/cms/discovery/` |
+```bash
+curl -sL http://localhost:<PORT>/api/cms/discovery/ | head -c 100
+```
 
 ---
 
@@ -115,7 +112,7 @@ Example of a completed `## Fields & Schema` section:
 ### Step 3 — Generate component guidelines
 
 For each component in discovery order, run the full per-component pipeline defined in
-[`packages/skills/skills/contentful-cms-cms-guidelines/generate-component-guidelines.md`](../../../packages/skills/skills/contentful-cms-cms-guidelines/generate-component-guidelines.md).
+[`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md).
 
 To find unfinished components:
 1. Fetch `<discoveryUrl>` and collect all `components[].name` values.
@@ -131,12 +128,12 @@ Run a Cursor subagent with this prompt, substituting `<COMPONENT_TYPE>` and `<AP
 Run the full guideline generation pipeline for <COMPONENT_TYPE>.
 Target app: <APP_DIR> (all paths relative to repo root / that directory).
 
-Read these pipeline docs first (they are in packages/skills/skills/contentful-cms-cms-guidelines/):
-- generate-component-guidelines.md  (overall pipeline)
-- variant-loop.md                   (Phase A: variant loop)
-- generation-prompt.md              (Phase B: generation)
-- colour-hint-prompt.md             (Phase C: colour hint)
-- validation-prompt.md              (Phase D: validation)
+Read these pipeline docs first (sibling directory contentful-cms-cms-guidelines/):
+- ../contentful-cms-cms-guidelines/generate-component-guidelines.md  (overall pipeline)
+- ../contentful-cms-cms-guidelines/variant-loop.md                   (Phase A: variant loop)
+- ../contentful-cms-cms-guidelines/generation-prompt.md              (Phase B: generation)
+- ../contentful-cms-cms-guidelines/colour-hint-prompt.md             (Phase C: colour hint)
+- ../contentful-cms-cms-guidelines/validation-prompt.md              (Phase D: validation)
 
 === Phase A: Variant loop ===
 Follow variant-loop.md.
@@ -271,8 +268,8 @@ Each component guideline contains a `## Screenshots` section with image links:
 
 | Variant | Preview |
 |---------|---------|
-| Default | ![Default](http://localhost:3010/cms/screenshot?file=components/hero-default.png) |
-| Navy    | ![Navy](http://localhost:3010/cms/screenshot?file=components/hero-navy.png) |
+| Default | ![Default](<devBaseUrl>/cms/screenshot?file=components/hero-default.png) |
+| Navy    | ![Navy](<devBaseUrl>/cms/screenshot?file=components/hero-navy.png) |
 ```
 
 These links:
@@ -285,7 +282,7 @@ These links:
 
 ## Pipeline reference
 
-All per-component pipeline docs live in `packages/skills/skills/contentful-cms-cms-guidelines/`:
+All per-component pipeline docs live in the sibling directory [`contentful-cms-cms-guidelines/`](../contentful-cms-cms-guidelines/):
 
 | File | Purpose |
 |---|---|

package/skills/contentful-cms-update-cms-guidelines/SKILL.md

@@ -45,21 +45,11 @@ If they insist on “everything” / “from scratch” / “totally regenerate
 
 | Input | Example |
 |---|---|
-| App directory (repo-relative or absolute) | `apps/example-se2026` |
-| Port | `3012` |
-| Discovery URL | `http://localhost:3012/api/cms/discovery/` |
+| App directory (repo-relative or absolute) | `apps/my-site` |
+| Discovery URL | `http://localhost:<PORT>/api/cms/discovery/` |
+| Port / base URL | From `pnpm dev` output, or `devBaseUrl` in `<appDir>/.contentful-cms.json` |
 | Mode | `fresh` \| `sync` \| `merge-only` |
 
-**App ports:**
-
-| App | Port |
-|---|---|
-| example-brightline | 3010 |
-| example-se2026 | 3012 |
-| example-om1 | 3013 |
-| example-empty | 3014 |
-| example-brightlifekids | 3015 |
-
 ---
 
 ## Mode: fresh
@@ -108,7 +98,7 @@ grep -E "CONTENTFUL_SPACE_ID|CONTENTFUL_ACCESS_TOKEN|OPENAI_API_KEY|ANTHROPIC_AP
 ### Step 2 — Curate showcase mocks
 
 Read and follow the **curate-showcase-mocks** skill:
-`.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md`
+[`../se-marketing-sites-curate-showcase-mocks/SKILL.md`](../se-marketing-sites-curate-showcase-mocks/SKILL.md)
 
 This produces `src/generated/showcase-mocks.json` (committed) and
 `src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<slug>.json` (often gitignored — **some apps commit them**; follow the app’s `.gitignore`).
@@ -146,7 +136,7 @@ Produces `generated/cms-discovery/field-list.json` (discovery API reads from thi
 ### Step 5 — Run generate-all-guidelines
 
 Read and follow the **generate-all-guidelines** skill:
-`.agents/skills/contentful-cms-generate-all-guidelines/SKILL.md`
+[`../contentful-cms-generate-all-guidelines/SKILL.md`](../contentful-cms-generate-all-guidelines/SKILL.md)
 
 Skip its prerequisite check (you already verified everything through Step 4).
 Run Phases 0–5 from that skill with **full regeneration rules**:
@@ -338,7 +328,7 @@ All under `<appDir>`:
 
 | Purpose | Skill |
 |---|---|
-| Curate showcase mocks (Step 2 of `fresh`) | `.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md` |
-| Full-site bulk generation (Step 4 of `fresh`: Phases 0–5) | `.agents/skills/contentful-cms-generate-all-guidelines/SKILL.md` |
-| Single-type regeneration (after code change) | `.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md` (mode: single) |
-| Per-component pipeline detail | `packages/skills/skills/contentful-cms-cms-guidelines/generate-component-guidelines.md` |
+| Curate showcase mocks (Step 2 of `fresh`) | [`../se-marketing-sites-curate-showcase-mocks/SKILL.md`](../se-marketing-sites-curate-showcase-mocks/SKILL.md) |
+| Full-site bulk generation (Step 4 of `fresh`: Phases 0–5) | [`../contentful-cms-generate-all-guidelines/SKILL.md`](../contentful-cms-generate-all-guidelines/SKILL.md) |
+| Single-type regeneration (after code change) | [`../contentful-cms-generate-cms-guidelines/SKILL.md`](../contentful-cms-generate-cms-guidelines/SKILL.md) (mode: single) |
+| Per-component pipeline detail | [`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md) |