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

package/docs/FUNCTIONAL_SPEC.md

@@ -0,0 +1,303 @@
+# Functional Specification: cms-edit
+
+## 1. Purpose
+
+`cms-edit` is a CLI tool and MCP server for reading and writing draft content in a Contentful CMS space. It is designed to be operated by an AI agent or a human via the command line. All write operations produce Contentful drafts; no publish, unpublish, archive, or delete operation is exposed.
+
+---
+
+## 2. Interfaces
+
+**CLI binary (`cms-edit`)** — invoked with subcommands and arguments from a terminal or shell script.
+
+**Hosted MCP server** — deployed per site at `/api/mcp` (OAuth). Exposes `cms_edit`, `cms_edit_help`, `cms_edit_customer`, guide/customer resources, and onboarding prompts. Local stdio MCP is not supported; IDE/terminal agents use the `cms-edit` CLI directly.
+
+---
+
+## 3. Configuration
+
+A project-level `.contentful-cms.json` file defines one or more Contentful spaces. Each space entry holds:
+
+- `spaceId` — Contentful space identifier
+- `environment` — Contentful environment name (e.g., `master`)
+- `managementToken` — Contentful Management API token, expressed as an env var reference (e.g., `${CMS_EDIT_TOKEN_OM1}`)
+- `defaultLocale` — locale string (e.g., `en-US`)
+- `devBaseUrl` — local app URL for `preview url` and `preview showcase`
+
+A `defaultSpace` key selects the active space when none is specified. The `--space` flag overrides per invocation.
+
+**Environment variables:**
+
+| Variable | Purpose |
+|---|---|
+| `CMS_EDIT_TOKEN_<SPACE>` | Management token per space |
+| `CMS_EDIT_JSON=1` | Force JSON output mode globally |
+| `CONTENTFUL_CMS_SESSION=<name>` | Select a named session for concurrent workflows |
+
+---
+
+## 4. Session Model
+
+A session is the unit of work. It is created when content is opened and persists on the local filesystem until saved or discarded. Multiple named sessions can be active concurrently.
+
+Each session holds:
+- The loaded entry tree with assigned `@ref` labels (`@c0`, `@c1`, …)
+- A change log (set of modified fields per entry)
+- Entries queued for deletion (drafts unlinked during the session)
+
+Commands within a session reference entries by their `@ref` label. The session is explicitly ended by `save` or `discard`.
+
+---
+
+## 5. Supported Contentful Entity Types
+
+The tool operates on the following Contentful content types:
+
+| Type | Discriminator field | Notes |
+|---|---|---|
+| Page | — | Top-level container; identified by `slug` |
+| Article | — | Blog/editorial entry; identified by `slug` |
+| Component | `componentType` | Inline content block (Hero, RichText, CTA, Card, …) |
+| Collection | `collectionType` | Container with a `contents` array of child entries |
+| ExternalComponent | `externalComponentType` | Embeds (data viz, research charts) |
+| Template | — | Layout with `preContent`/`postContent` arrays |
+| Navigation | — | Menu tree with nested `items`/`navigationItems` |
+| Person | — | Author/team member; `bio` is rich text (`rtf` in cms-edit) |
+| ArticleType | — | Article taxonomy tag |
+| Tag | — | General taxonomy |
+| Media | — | Wrapper entry around an asset |
+| Asset | — | Image, PDF, or file (read-only; no upload capability) |
+
+---
+
+## 6. Entry Tree Resolution
+
+When content is opened, the tool recursively fetches linked entries to build a tree:
+
+- Content arrays: `topContent`, `content`, `bottomContent` (on pages/articles/templates), `contents` (on collections)
+- Single-link fields: `template`, `articleType`, `author`, `menu`, `footer`
+- Navigation trees: `items`, `navigationItems`
+- Template layout: `preContent`, `postContent`
+
+Each resolved entry is assigned a stable `@ref` label (`@c0` = the root, `@c1`, `@c2`, … for children in tree order). The tree is rebuilt on each `snapshot` call.
+
+---
+
+## 7. Command Reference
+
+### 7.1 Discovery and Navigation
+
+| Command | Function |
+|---|---|
+| `open --page-slug <slug>` | Load entry by flat lookup flag (see `docs/help/lookup.md`) |
+| `open --id <id>` | Load by Contentful entry ID |
+| `peek --page-slug <slug>` | Fetch and display content tree and root field values without creating a session |
+| `peek --id <id>` | Same as peek, but look up by Contentful entry ID |
+| `snapshot` | Print the current session's entry tree with @refs, entry types, field labels, and publish status |
+| `read <ref>` | Print all fields of an entry in the active session |
+| `read <ref> <field>` | Print a specific field (rich text rendered as Markdown) |
+| `read <id> --id [field]` | Print entry fields by ID without an open session |
+| `search <query>` | Full-text search across entries; returns matching entries |
+| `list --type <type>` | List all entries of a given content type |
+| `index sync` | Rebuild local SQLite media index from Content Preview API (draft; default). Use `--published` for Delivery API only |
+| `index status` | Show index path, sync time, and row counts |
+| `index dump` | Pretty-print index contents (assets, media, type breakdown) for terminal inspection |
+| `list --type media --asset-id <id>` | List Media entries linked to an asset (index) |
+| `list --type media --asset-filename <name>` | List Media entries by exact asset fileName (index) |
+| `list --type page` | List pages from the content catalog (index-backed) |
+| `resolve --id <id>` | Resolve an entry or asset ID to its details |
+| `resolve --page-slug <slug>` | Resolve by flat lookup flag (no session). See `docs/help/lookup.md` |
+| `open --page-slug <slug>` | Open a page session (one lookup flag required) |
+
+### 7.2 Session Management
+
+| Command | Function |
+|---|---|
+| `diff` | Show all unsaved field changes across all modified entries in the session |
+| `save` | Write all queued changes to Contentful as drafts; delete queued draft-only entries |
+| `discard` | Clear all unsaved changes; end the session |
+| `discard --all` | Clear all active sessions |
+
+### 7.3 Field Mutations
+
+| Command | Function |
+|---|---|
+| `set <ref> <field> <value>` | Set a scalar field (string, boolean, number, date) |
+| `set <ref> <field> <id> --link` | Set a single entry-link field |
+| `set <ref> <field> @c1,@c2 --links` | Replace a content-array field with the given refs |
+| `set <ref> <field> @c1,@c2 --links --append` | Append refs to an existing content array |
+| `set <ref> <field> --file <path>` | Set a JSON/Object field from a local file |
+| `set <ref> <field> --json '<json>'` | Set a JSON/Object field from an inline string |
+| `set @c1:field="val" @c2:field="val" …` | Bulk set scalar fields across multiple entries in one command |
+| `rtf <ref> <field> "<markdown>"` | Set a rich text field from Markdown |
+| `rtf <ref> <field> --file <path>` | Set a rich text field from a Markdown file |
+| `rtf <ref> <field> -` | Set a rich text field from stdin |
+| `rtf replace <ref> <field> --find "X" --replace-plain "Y"` | Surgical per-text-node replacement within existing rich text (does not rewrite the entire field) |
+| `rtf embed <ref> <field> <entry-id>` | Embed an entry block into an existing rich text field |
+| `rtf embed <ref> <field> <asset-id> --asset` | Embed an asset block into an existing rich text field |
+| `asset set <ref> <field> <asset-id>` | Set a visual/asset link field |
+
+### 7.4 Entry Creation
+
+| Command | Function |
+|---|---|
+| `create page --slug /x --title "X"` | Create a new page entry and open it in a session |
+| `create article --slug /x --title "X" --article-type-id <id>` | Create a new article entry and open it in a session |
+| `create template --label "X"` | Create a new template entry |
+| `create media --asset-id <id> --name "X"` | Create a Media wrapper entry around an existing asset |
+| `create from-json --file <path>` | Bulk-create a page or article with all its components from a declarative JSON file |
+| `create taxonomy-from-json --file <path>` | Batch-create tagType, articleType, and tag entries from JSON |
+| `create tag-type --slug <slug> --name "X"` | Create a tagType entry (draft) |
+| `create article-type --slug <slug> --name "X"` | Create an articleType entry (draft) |
+| `create tag --slug <slug> --name "X" --tag-type <slug>` | Create a tag entry (draft); `--tag-type-slug`, `--tag-type-name`; `--description`, `--featured-image`; cmsLabel auto `"<tagType> — <name>"` |
+| `create tag-type\|tag\|article-type … --if-not-exists` | Idempotent taxonomy create (returns existing entry when slug matches) |
+| `add <entry-type> --content-type <ct>` | Create a new child entry of a given content type, link it into the current open entry's content array, and assign it a @ref |
+
+### 7.5 Entry Removal and Reordering
+
+| Command | Function |
+|---|---|
+| `remove <ref>` | Unlink an entry from its parent. If the entry is a draft that has never been published, it is queued for deletion on `save`. Published entries are only unlinked. |
+| `move <ref> --after <ref2>` | Move an entry to a new position within its parent content array |
+
+### 7.6 CTA Links
+
+CTA link lists are nested within component entries.
+
+| Command | Function |
+|---|---|
+| `links list <ref>` | List all CTA links on an entry |
+| `links add <ref> --type external --label "X" --href <url>` | Add an external URL link |
+| `links add <ref> --type internal --label "X" --slug /page` | Add an internal link by page slug |
+| `links add <ref> --type internal --label "X" --id <id>` | Add an internal link by entry ID |
+| `links add <ref> --type download --label "X" --asset-id <id>` | Add a download link to an asset |
+| `links add <ref> … --variant <value>` | Set link variant on create |
+| `links set <ref> <index> <field> <value>` | Set a scalar field on an existing link entry |
+| `links move <ref> <from-index> <to-index>` | Reorder links by index |
+| `links remove <ref> <index>` | Remove a link by index |
+
+### 7.7 Batch edit (by entry ID)
+
+| Command | Function |
+|---|---|
+| `batch set <entryId>:field=value …` | Queue scalar field updates for unrelated entries |
+| `batch diff` | Show pending batch session changes |
+| `batch save` | Write all batch changes as drafts |
+| `batch discard` | Clear batch session without saving |
+
+Default session name: `batch`. Scalar fields only in v1.
+
+### 7.8 Navigation
+
+| Command | Function |
+|---|---|
+| `nav open --nav-name <name>` | Open a navigation entry in a session (`--nav-id` also supported) |
+| `nav add --label "X" --slug /page` | Add a navigation item |
+
+---
+
+## 8. Rich Text Conversion
+
+The `rtf` command sets Rich Text fields from one of four input modes (exactly one flag; **`--markdown` is the default** when omitted):
+
+| Mode | Flag | Behaviour |
+|---|---|---|
+| Plain text | `--text` | Paragraphs from `\n\n` or `\n`; inline markers (`**bold**`, links, …) use the same inline rules as Markdown. |
+| Markdown | `--markdown` | Full document Markdown (see table below). |
+| HTML | `--html` | Subset of HTML (`h1`–`h6`, `p`, lists, `blockquote`, `table`, inline tags). |
+| Rich Text JSON | `--json` | Full Contentful Rich Text document JSON (`nodeType: document`). |
+
+Input may be passed as positional argument, `--content`, `--base64`, `--file`, or stdin (`-`). The same modes apply to `cms-edit set` on Rich Text fields via `--rtf-text`, `--rtf-markdown`, `--rtf-html`, `--rtf-json`; `create from-json` auto-detects Markdown / HTML / JSON document strings or accepts `{ "value", "format" }`; `rtf patch` ops support `replaceIsMarkdown`, `replaceIsHtml`, `replaceIsJson`, or `replaceFormat`.
+
+Markdown syntax (when using `--markdown`):
+
+| Markdown | Rich text output |
+|---|---|
+| `#` through `######` | heading-1 through heading-6 |
+| `**text**` | bold |
+| `_text_` | italic |
+| `***text***` | bold-italic |
+| `` `code` `` | inline code |
+| `[text](url)` | hyperlink |
+| `- item` | unordered list item |
+| `1. item` | ordered list item |
+| Indented list items | nested lists |
+| `> text` | blockquote |
+| `---` | horizontal rule |
+| `\| col \| col \|` (GFM) | table |
+
+The `rtf replace` command performs surgical replacement at the text-node level. Replacements may be supplied as plain text, inline Markdown, inline HTML, or a JSON array of inline nodes (`--replace-plain`, `--replace`, `--replace-html`, `--replace-json`).
+
+---
+
+## 9. Write Behaviour and Optimistic Locking
+
+On `save`:
+
+1. For each modified entry, the tool fetches the current live version from Contentful.
+2. Local changes are merged on top of the fetched version (handles concurrent edits from other sources).
+3. The merged entry is written using the Contentful Management API `update` method (not `publish`).
+4. Draft-only entries queued for deletion are deleted.
+5. Success and failure counts are reported.
+
+If a version conflict cannot be resolved cleanly, an error is returned and the entry is not written.
+
+---
+
+## 10. Permission Constraints
+
+The tool enforces a hard boundary between editing and publishing:
+
+**Permitted:**
+- Read entries and assets
+- Create draft entries
+- Update draft and published entries (saving as new draft versions)
+- Delete draft-only entries (never-published)
+
+**Not permitted (not exposed by the tool):**
+- Publish entries
+- Unpublish entries
+- Archive entries
+- Delete published entries
+
+This boundary is enforced at two levels: the tool exposes no publish/unpublish/archive/delete commands, and the expected Contentful management token role should not have those permissions either.
+
+---
+
+## 11. Output Modes
+
+**Human-readable mode (default):** Coloured console output with info, success, warning, and error messages.
+
+**JSON mode** (`--json-output` flag or `CMS_EDIT_JSON=1`): Structured JSON on stdout. Schema varies by command:
+
+| Command | JSON output |
+|---|---|
+| `snapshot` | Entry tree with refs, types, labels, publish status |
+| `read` | Entry object with all fields, or single field value |
+| `diff` | Array of changed entries, each with before/after field values |
+| `search` / `list` | Array of matching entry objects |
+| `save` | Success/failure counts and per-entry messages |
+| `resolve` | Asset or entry metadata |
+
+---
+
+## 12. Preview URLs
+
+When `devBaseUrl` is configured, `preview url` and `preview showcase` build URLs for pages and showcase renders. Visual verification is done via a browser MCP (e.g. Chrome DevTools), not built into cms-edit. CMS guidelines batch capture uses `cms-capture-screenshots` from `@se-studio/project-build` (separate tool, requires agent-browser).
+
+---
+
+## 13. Telemetry
+
+Opt in with `CMS_EDIT_TELEMETRY=1` (opt out with `0`). The tool emits telemetry events recording the command name, outcome (`success`, `error`, or `exit`), duration, package version, and deployment `project_key`. No user ids, emails, slugs, field values, entry IDs, query text, or error messages are included.
+
+- **Local CLI:** newline-delimited JSON at `~/.contentful-cms/telemetry.log`
+- **Hosted (Vercel):** batched ingest to Axiom when `AXIOM_TOKEN` and `AXIOM_DATASET` are set
+
+See [TELEMETRY_AXIOM.md](./TELEMETRY_AXIOM.md) for env vars, schema, and example queries.
+
+---
+
+## 14. Concurrency
+
+Multiple sessions can be active simultaneously using the `--session <name>` flag or `CONTENTFUL_CMS_SESSION` env var. Sessions are isolated; changes in one session do not affect another. The optimistic locking on `save` handles the case where two sessions modify the same entry.

package/docs/MEDIA_INDEX_PLAN.md

@@ -0,0 +1,256 @@
+# Media & asset search — local index plan
+
+## Implementation status (2026-06)
+
+**Implemented** in `@se-studio/contentful-cms`:
+
+- `cms-edit index sync` / `index status` (Preview API draft default + `--published`)
+- SQLite index at `~/.contentful-cms/index/<spaceId>/<environment>/media.db` via `node:sqlite`
+- Delivery token resolution: `deliveryAccessToken` → `deliveryApiKeyName` → environment match → optional `autoCreateDeliveryApiKey`
+- **Index required** (no CMA fallback) for: `asset search`, `asset audit`, `list --type media` with `--asset-id` / `--asset-filename*`, upload `--if-exists-by-filename`
+- **Reference catalog** (index-preferred, CMA fallback): `template`, `articleType`, `tagType`, `tag` in `reference_entries` table (schema v2)
+- `list --type template|articleType|tagType|tag`, `resolve --type … --slug`, taxonomy `--if-not-exists`, and `tagTypeSlug` shorthands use the catalog when the index exists
+- Bulk CMA asset pagination and N+1 `links_to_asset` scans removed from those paths
+
+Help: [help/index-sync.md](./help/index-sync.md).
+
+---
+
+## Problem
+
+Today, cms-edit discovers assets and Media entries via the **Contentful Management API (CMA)**:
+
+| Operation | CMA approach | Pain |
+|-----------|--------------|------|
+| Exact `fileName` | `fields.file.fileName` filter | Fast |
+| Regex `fileName` | Paginate assets (+ optional `[match]` prefix), filter client-side | Slow on large spaces |
+| `list --type media --asset-filename*` | Find assets, then **N×** `links_to_asset` queries for Media | Very slow at scale |
+| Title search | `fields.title[match]` | OK for small result sets |
+
+CMA is rate-limited, optimized for writes, and regex scans can mean thousands of round trips. Publication-import and deduplication workflows need **fast repeated lookups** by `fileName`, title, MIME type, and “which Media wraps this asset?”.
+
+## Goal
+
+A **local, per-space index** built from the **Content Delivery API (CDA)** (read-only, cache-friendly) that powers:
+
+- Sub-second filename / regex / title search over all assets
+- Reverse lookup: asset ID → Media entry IDs
+- Optional freshness via incremental sync or scheduled rebuild
+
+CMA remains the source of truth for **creates/updates** (`asset upload`, `create media`, taxonomy).
+
+## Non-goals (v1)
+
+- Full-text search across entry bodies
+- Replacing CMA for asset upload or processing
+- Cross-space search
+- Publishing or preview-mode mixing in one index (pick one: published CDA or preview CPA — see below)
+
+## Proposed architecture
+
+```mermaid
+flowchart LR
+  subgraph sync [Index sync]
+    CMA_keys[CMA API keys]
+    CDA[Contentful CDA]
+    SyncCmd["cms-edit index sync"]
+    Store[(Local index)]
+    CMA_keys -->|"resolve accessToken"| SyncCmd
+    SyncCmd --> CDA
+    CDA --> Store
+  end
+  subgraph query [Search]
+    CLI[cms-edit asset search]
+    List[cms-edit list --type media]
+    CLI --> Store
+    List --> Store
+  end
+  subgraph write [Writes unchanged]
+    CMA[Contentful CMA]
+    Upload[asset upload]
+    Upload --> CMA
+  end
+```
+
+### Index store
+
+**Location:** `~/.contentful-cms/index/<spaceId>/<environment>/` (or project-local `.contentful-cms/index/` when `--config` is set).
+
+**Format (v1):** SQLite via `better-sqlite3` or embedded JSONL + in-memory Map for zero native deps. Prefer **SQLite** for regex scans and stable pagination on 10k+ assets.
+
+**Tables (conceptual):**
+
+| Table | Key fields | Purpose |
+|-------|------------|---------|
+| `assets` | `id`, `fileName`, `title`, `description`, `contentType`, `url`, `width`, `height`, `size`, `updatedAt` | Asset search |
+| `media` | `id`, `name`, `assetId`, `updatedAt` | Media wrapper lookup |
+| `meta` | `syncedAt`, `assetCount`, `mediaCount`, `cdaTokenHash` | Freshness |
+
+Indexes: `assets.fileName`, `assets.title`; `media.assetId`.
+
+### Sync command
+
+```bash
+# Full rebuild (paginate CDA assets + media entries)
+cms-edit index sync
+
+# Incremental (if sync token / updatedSince supported)
+cms-edit index sync --since <iso>
+
+# Status
+cms-edit index status
+```
+
+**CDA pagination:** Use `contentful` JS SDK or fetch `https://cdn.contentful.com/.../assets` and `.../entries?content_type=media` with `limit=1000`, following `skip` until complete.
+
+**Preview vs published:** Default index = **Preview API** (draft content, matches CMA uploads). Optional `--published` uses Delivery API for published assets only (separate DB file suffix `-published`).
+
+### Delivery token resolution (CMA → CDA)
+
+The **management token is not a delivery token** — it cannot call `cdn.contentful.com`. For index sync we only need a **read-only** CDA (or CPA) access token. That token can be obtained without asking operators to copy a second secret, by using the **same CMA client** cms-edit already uses.
+
+Contentful exposes delivery keys on the space via the [Management API — API keys](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/api-keys): list/create delivery keys; each key includes an `accessToken` for CDA. Creating a delivery key also creates a linked preview key (resolve separately for `--preview` sync).
+
+**Resolution order** (first match wins):
+
+| Priority | Source | Notes |
+|----------|--------|--------|
+| 1 | Explicit override | Space config `deliveryAccessToken` or `${CONTENTFUL_ACCESS_TOKEN}` / `${CONTENTFUL_DELIVERY_TOKEN}` — same vars as marketing apps |
+| 2 | Named key via CMA | `deliveryApiKeyName` in `.contentful-cms.json` → `space.getApiKeys()` → match `name` |
+| 3 | Environment match via CMA | Pick first delivery key whose `environments` includes the configured `environment` (default `master`) |
+| 4 | Auto-create (optional) | If PAT has API-key manage rights and no key matches: create `cms-edit-index` delivery key scoped to that environment |
+
+Implement as `resolveDeliveryAccessToken(space, { preview?: boolean })` in `src/contentful/delivery-token.ts` (or similar), called at the start of `index sync` only — not on every search (cache resolved token in `meta` as a hash + key id, not the raw token).
+
+**SDK sketch (contentful-management, already a dependency):**
+
+```typescript
+const client = createClient({ accessToken: space.managementToken }, { type: 'plain' });
+const spaceApi = await client.getSpace(space.spaceId);
+const { items: keys } = await spaceApi.getApiKeys();
+const key = pickDeliveryKey(keys, { name: space.deliveryApiKeyName, environment: space.environment });
+const deliveryToken = key.accessToken; // CDA
+// preview: await spaceApi.getPreviewApiKey(key.preview_api_key.sys.id) → accessToken
+```
+
+**What does not work:**
+
+- Passing `managementToken` directly to the CDA client.
+- Assuming any single PAT can read API keys (editor-only tokens may lack `ContentDelivery` / key read rights — fail with a clear error and point to explicit `deliveryAccessToken`).
+
+**Caveats:**
+
+| Topic | Guidance |
+|-------|----------|
+| Permissions | PAT needs rights to read (and optionally create) space API keys; document in hosted/CLI setup guides |
+| Multiple keys | Never “first key in list” without environment/name filter |
+| Propagation | New keys may 401 for a few seconds after create — retry with backoff |
+| Secrets | Do not log `accessToken`; store only `cdaTokenHash` + `apiKeyId` in index `meta` |
+| Preview index | Resolve linked preview key when `index sync --preview` |
+
+**Config additions** (`.contentful-cms.json` per space, all optional):
+
+```json
+{
+  "deliveryAccessToken": "${CONTENTFUL_ACCESS_TOKEN}",
+  "deliveryApiKeyName": "Production",
+  "autoCreateDeliveryApiKey": false
+}
+```
+
+If only `managementToken` is configured, `index sync` should still work when CMA can list a suitable delivery key — aligning with agent setups that already have cms-edit credentials.
+
+### Query integration (implemented)
+
+1. **`asset search`** — Requires index; queries SQLite (title `LIKE`, filename exact/regex, MIME filter).
+2. **`list --type media --asset-filename*`** — Single index query (assets + joined media rows); no CMA.
+3. **`--if-exists-by-filename`** — Index exact `fileName` lookup; optional post-upload row upsert.
+
+Stale index: warn when `syncedAt` > 24h; no `--no-index` CMA fallback.
+
+### Freshness
+
+| Strategy | When |
+|----------|------|
+| Manual `index sync` | Before large import jobs |
+| `index sync` in CI nightly | Keeps agents fast |
+| Post-upload hook (optional) | After `asset upload`, upsert one row into index |
+
+Webhook-driven incremental sync is out of scope for v1 but fits the same schema.
+
+## Implementation phases
+
+### Phase 1 — Foundation (MVP)
+
+- [x] Add `contentful` delivery client dependency
+- [x] `resolveDeliveryAccessToken()` — explicit config, then CMA `getApiKeys()` (+ optional `createApiKey`)
+- [x] Config fields: `deliveryAccessToken`, `deliveryApiKeyName`, `autoCreateDeliveryApiKey`
+- [x] `cms-edit index sync` full rebuild → SQLite (CDA pagination after token resolve)
+- [x] `cms-edit index status`
+- [x] Unit tests: delivery token, index queries
+
+### Phase 2 — Wire search
+
+- [x] `asset search --filename` / `--filename-match` uses index (required)
+- [x] `findAssetByExactFilename` replaced by index lookup
+- [x] README / help document index requirement
+
+### Phase 3 — Media discovery
+
+- [x] Index `media` entries with `assetId` and denormalized `assetFileName`
+- [x] `list --type media --asset-id` / `--asset-filename*` without N+1 CMA
+- [x] JSON output for indexed media list
+
+### Phase 3b — Reference catalog
+
+- [x] Index `template`, `articleType`, `tagType`, `tag` in `reference_entries` (schema v2)
+- [x] `list --type` for reference types from index (`--force-cma` escape hatch)
+- [x] `resolve --type … --slug` and taxonomy `--if-not-exists` prefer index
+- [x] Post-create upsert for taxonomy and template creates
+- [x] `index dump --reference-only` / `--reference-type`
+
+### Phase 3c — Auto-sync and incremental refresh
+
+- [x] `ensureContentIndex` — auto full rebuild when missing or schema mismatch
+- [x] Incremental upsert when only stale (>24h), same schema (`sys.updatedAt[gte]` last `syncedAt`)
+- [x] Manual `index sync` always full rebuild
+- [x] File lock — single writer per index database
+- [x] Duplicate slug/label detection in reference catalog (index + CMA)
+
+### Phase 4 — Operator UX
+
+- [x] Auto-sync on index-backed commands (see [help/index-sync.md](./help/index-sync.md))
+- [ ] Optional `index sync` before bulk upload scripts (skill note — partial)
+- [ ] MCP tool exposure if hosted MCP should search assets
+
+## Dependencies & package boundaries
+
+- Keep index code inside `packages/contentful-cms` (CLI owns agent workflows).
+- **Do not** pull `@se-studio/contentful-rest-api` into cms-edit unless we need shared cache tags; a thin CDA client keeps the CLI package self-contained.
+- SQLite: evaluate `node:sqlite` (Node 22+) vs `better-sqlite3` for install size in npx usage.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Index stale vs CMA | Show `syncedAt` in search output; exact match confirm via CMA before skip-upload |
+| Draft assets missing from CDA | Default index uses Preview API; use `--published` only when you need published-only discovery |
+| Disk size | 10k assets ≈ few MB in SQLite |
+| Token sprawl | Prefer CMA-resolve when only `managementToken` is set; optional explicit `deliveryAccessToken` for CI |
+| CMA cannot read API keys | Clear error; require `deliveryAccessToken` in config |
+| Leaked delivery token in logs | Never log; `meta.cdaTokenHash` only |
+| New API key 401 | Retry CDA requests after create (Contentful propagation delay) |
+
+## Success criteria
+
+- Regex search over 5k assets completes in **< 2s** locally after sync
+- `list --type media --asset-filename-match` does **not** scale with asset count via N+1 CMA calls
+- No change to write paths; tests cover index-off fallback
+
+## References
+
+- Current CMA helpers: `src/contentful/assets.ts`, `src/contentful/media.ts`
+- CMA client: `src/contentful/client.ts` (`managementToken` per space)
+- Contentful: [API keys (CMA)](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/api-keys), [Authentication](https://www.contentful.com/developers/docs/references/authentication/)
+- App delivery env vars (override): `CONTENTFUL_ACCESS_TOKEN`, `CONTENTFUL_PREVIEW_ACCESS_TOKEN` in `contentful-rest-api`
+- Issue context: #42 publication import (GITHUB_ISSUES_IMPLEMENTATION_STATUS.md)

package/docs/SKILLS.md

@@ -0,0 +1,29 @@
+# cms-edit and agent skills
+
+## Two skill channels
+
+| Channel | Package | Install | Use case |
+|---------|---------|---------|----------|
+| **Full SE Studio skills** | `@se-studio/skills` | `npx skills add @se-studio/skills`, `pnpm skills:sync` in monorepo, or auto-sync via `prepare` in consumer sites (see `packages/project-build/README.md`) | Marketing sites, CMS guidelines, app tasks |
+| **Bundled cms-edit skills** | `@se-studio/contentful-cms` | `npx skills add @se-studio/skills` | Minimal set shipped with the CLI (`core`, `editor-tasks`, `templates`, `setup`) |
+
+## Where to edit
+
+1. **Always edit** `packages/skills/skills/<skill-dir>/SKILL.md` in this monorepo.
+2. Run `pnpm skills:validate` then `pnpm skills:sync` to update `.agents/skills/`.
+3. Bundled cms-edit copies are regenerated by `pnpm --filter @se-studio/contentful-cms sync:skills` (also runs on `build` and `test`).
+
+Never edit:
+
+- `.agents/skills/` or `.cursor/skills/` by hand (generated)
+- `packages/contentful-cms/skills/` by hand (generated — see `skills/README.md`)
+- `.claude/skills/` in the repo (untracked local installs; not a source of truth)
+
+## `.claude/skills` vs `.agents/skills`
+
+- **`.agents/skills/`** — Monorepo target for `pnpm skills:sync`; gitignored; symlinked to `.cursor/skills/`.
+- **`.claude/skills/`** — Optional per-machine path used by some Claude setups; **intentionally untracked**. Skills should come from this repo (`@se-studio/skills`) or third-party skill packs — not from committed copies under `.claude/`.
+
+## Installing bundled skills
+
+`npx skills add @se-studio/skills` installs cms-edit skills into `.agents/skills/` in the current project. In the monorepo, prefer `pnpm skills:sync` from `@se-studio/skills`.

package/docs/TELEMETRY_AXIOM.md

@@ -0,0 +1,93 @@
+# cms-edit telemetry (Axiom)
+
+Hosted cms-edit deployments can emit aggregate usage telemetry to [Axiom](https://axiom.co). Events contain command names, outcomes, and durations only — no user ids, emails, slugs, entry ids, or error messages.
+
+## Enable on Vercel
+
+Set on each cms-edit host project (`se-website-2026-cms-edit-host`, `pedestal-cms-edit`, `headwater-cms-edit`, dev `cms-edit-host`):
+
+| Variable | Value |
+|----------|-------|
+| `CMS_EDIT_TELEMETRY` | `1` |
+| `AXIOM_TOKEN` | Axiom ingest token (sensitive) |
+| `AXIOM_DATASET` | `cms-edit` |
+| `AXIOM_DOMAIN` | Optional; default `api.axiom.co` |
+| `CMS_EDIT_PROJECT_KEY` | Already required — used as `project_key` for aggregation |
+
+Opt out: `CMS_EDIT_TELEMETRY=0`.
+
+## Event schema
+
+Each event is one JSON object:
+
+| Field | Description |
+|-------|-------------|
+| `event_id` | UUID for deduplication |
+| `timestamp` | ISO 8601 completion time |
+| `command` | e.g. `open`, `save`, `oauth` |
+| `subcommand` | Optional, e.g. `replace`, `link-contentful` |
+| `outcome` | `success`, `error`, or `exit` |
+| `exit_code` | When `outcome` is `exit` |
+| `error_name` | Error class or stable reason code (never message text) |
+| `duration_ms` | Wall-clock duration |
+| `cms_edit_version` | Package version |
+| `mode` | `hosted-mcp` on Vercel, `cli` locally |
+| `project_key` | From `CMS_EDIT_PROJECT_KEY` |
+| `node_version` | Node runtime |
+| `platform` | `process.platform` |
+
+OAuth events emit `command: oauth` with route-specific `subcommand` values:
+
+| `subcommand` | When |
+|--------------|------|
+| `link-contentful` | Contentful sign-in link step (failures only today) |
+| `authorization-code` | Initial MCP connect via `/oauth/token` (`authorization_code` grant) |
+| `refresh-token` | Silent token refresh via `/oauth/token` (`refresh_token` grant) |
+
+`error_name` uses stable reason codes only — never token values, user ids, or emails. Examples: `invalid_contentful_token`, `space_access_denied`, `invalid_refresh_token`, `refresh_client_mismatch`, `invalid_authorization_code`.
+
+## Local development
+
+With `CMS_EDIT_TELEMETRY=1` and no Axiom env vars, events append to `~/.contentful-cms/telemetry.log` as NDJSON.
+
+## Example Axiom queries
+
+**Commands per project (last 24h):**
+
+```apl
+['cms-edit']
+| where _time > ago(24h)
+| summarize count() by project_key, command, outcome
+| order by count_ desc
+```
+
+**OAuth failures by reason:**
+
+```apl
+['cms-edit']
+| where command == "oauth" and outcome == "error"
+| summarize count() by project_key, error_name
+```
+
+**Token refresh health (success vs failure):**
+
+```apl
+['cms-edit']
+| where command == "oauth" and subcommand == "refresh-token"
+| summarize count() by project_key, outcome
+| order by count_ desc
+```
+
+**p95 duration by command:**
+
+```apl
+['cms-edit']
+| where outcome == "success"
+| summarize percentile(duration_ms, 95) by project_key, command
+```
+
+## Flow
+
+MCP request → `runCmsEditArgs` → Commander hooks record outcome → `flush()` POSTs buffered events to `https://{AXIOM_DOMAIN}/v1/datasets/{AXIOM_DATASET}/ingest` before the HTTP response returns. OAuth `link-contentful` failures record and flush in the route handler.
+
+After adding or changing `AXIOM_*` env vars on Vercel, **redeploy** — serverless only reads env at deploy time.