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

package/CHANGELOG.md

@@ -0,0 +1,1117 @@
+# @se-studio/contentful-cms Changelog
+
+## 0.0.0-next16-20260822103555
+
+### Minor Changes
+
+- eeed547: Support Next.js 16.3 while remaining compatible with Next.js 15.5 (peer `>=15.5.0 <17`). CMS webhooks call `revalidateTag(tag, { expire: 0 })` so published content is not served stale. Template apps use `proxy.ts` on Next 16.
+
+## 3.6.2
+
+### Patch Changes
+
+- 1395ce3: Parse hosted CMA cache values that @upstash/redis already JSON-decoded. Reconnect was storing the Contentful token then failing authorization-code with missing_contentful_token.
+
+## 3.6.1
+
+### Patch Changes
+
+- 34a8a7f: Stop rotating hosted MCP refresh tokens on `/oauth/token`. Grok retries and parallel sessions were hitting `invalid_refresh_token` after the 1-hour access JWT expired. Include `refresh_token_expires_in` (30 days) on token responses.
+
+## 3.6.0
+
+### Minor Changes
+
+- Cut hosted MCP Contentful API usage: cache PAT identity for 15 minutes instead of validating on every request, republish the content-index blob after save so the next lambda hydrates instead of full Preview sync, skip template menu/footer on `open`/`peek` unless `--include-chrome`, and record CMA/CPA/index-sync counts on telemetry events.
+
+## 3.5.3
+
+### Patch Changes
+
+- Treat a present-but-invalid Contentful CMA cache like a missing cache on hosted MCP: delete the Redis token, refuse refresh and authorization-code grants, and return `WWW-Authenticate: error="invalid_token"` so Grok re-runs Contentful sign-in instead of looping on `auth required`. Contentful 5xx on token/MCP validation returns 503 (does not burn the auth code); authorization-code telemetry logs the typed CMA reason.
+
+## 3.5.2
+
+### Patch Changes
+
+- Label Contentful Management API traffic from cms-edit with `application: cms-edit/<version>` (`X-Contentful-User-Agent`) so hosted MCP and CLI writes can be distinguished from the Contentful web app in API and observability logs. Actor remains the signed-in editor; cms-edit still does not publish.
+
+## 3.5.1
+
+### Patch Changes
+
+- 35c02f0: Keep hosted MCP auth alive across Grok refresh and host deploys: slide the Contentful token TTL to 30 days, refuse MCP token grants when the CMA cache is gone, and return `invalid_token` so clients re-run Contentful sign-in instead of looping on “Failed to get tools after auth”.
+
+## 3.5.0
+
+### Minor Changes
+
+- DotLottie player for CMS animations (JSON and `.lottie`), with classic lottie-player fallback if DotLottie is not installed. Lazy load by default; honour loading/fetchPriority for eager (heroes). Server enrich reads dimensions and poster for CLS. WASM self-host helper (`/dotlottie/dotlottie-player.wasm`). Extension-first animation detection; hosted staged upload allows JSON/zip for animation packages. INavigation surfaces optional backgroundColour/textColour for footer chrome.
+
+## 3.4.8
+
+### Patch Changes
+
+- 0c0f1b4: Prepare-time `sourceNames` allowlist: encode only named Drive files on media prepare (CLI + MCP), matching import filter semantics. Avoids full-folder encode for large case-study packs.
+
+## 3.4.7
+
+### Patch Changes
+
+- Style hosted cms-edit HTML pages with subtle Something Else branding (masthead, cream surface, accent CTA, footer) shared across all customer hosts.
+
+## 3.4.6
+
+### Patch Changes
+
+- Soft-migrate pre-3.4.5 Contentful OAuth tokens into space-scoped Redis keys so MCP auth does not fail with missing_contentful_token after the multi-tenant Redis cutover.
+
+## 3.4.5
+
+### Patch Changes
+
+- Space-scope Redis active session pointers, health probes, and Contentful OAuth tokens for multi-tenant shared cmsedit-sessions Upstash.
+  - Active load is pointer-only (no KEYS “latest session” fallback)
+  - `clearAll` is space-scoped via a per-user+space SET index (no KEYS scan)
+  - OAuth token get/store takes explicit spaceId; missing space → null token (401 path), not throw on read
+
+## 3.4.4
+
+### Patch Changes
+
+- Agent success hardens from case-study feedback:
+
+  - `add`: validate parent target is an Entry-link array before createEntry; reject singular fields (e.g. visual) with guidance to `set … --link`
+  - Media import filters: `sourceNames`, `excludeSourceNames`, `onlyWithOverrides` (MCP + CLI)
+  - `preview urls`: always include contentfulLivePreview; when CMA fails, url null + unavailableReason
+  - MCP: always log cms_edit / cms_edit_media completion with durationMs
+  - Drive: folder preflight, drive_inaccessible / drive_empty_or_unshared gaps with SA email guidance
+  - Playbooks and hosted-guide pitfalls for agents
+
+## 3.4.3
+
+### Patch Changes
+
+- 1cbb0a8: Media host: cache last successful pipeline status on the job binding so brief pipeline 404s do not wipe real status; clarify status_unavailable (one prepare max, pack may have completed). Update media MCP tool description and media-pipeline-prepare playbook for host soft states vs pipeline lifecycle.
+
+## 3.4.2
+
+### Patch Changes
+
+- ff6bf38: Media status: soft `provisioning` only within 90s of prepare; then terminal `status_unavailable` and concurrent slot release. Document lifecycle for agents. Pipeline create verifies status write before returning jobId; refuse prod without Blob.
+
+## 3.4.1
+
+### Patch Changes
+
+- 0c83776: `cms-edit add` seeds only fields that exist on the content type (cmsLabel vs name for media/person). Optional `--label` and media `--asset-id`. Avoids 422 when creating media/person entries that have no cmsLabel field.
+- 4f42037: Media job status: when Redis owns a job but the pipeline returns 404 (Blob list lag), return non-terminal `provisioning` instead of `not_found` so wait/status keep polling. Peek labels use media `name`. Alpha images encode to WebP (preserve transparency) before PNG/JPEG fallback. Blob status reads prefer direct `head` + short list retry.
+
+## 3.4.0
+
+### Minor Changes
+
+- Agent session safety: dirty `open` hard-fails with clear remediation; `open --resume` keeps staged edits; `open --overwrite` abandons them. Rewrite `add` warning so field edits are clearly unsaved until `save`.
+- Strict `--link` vs `--links` (no silent array coercion). Mid-session scalar edits by Contentful entry ID (and `batch set` on page sessions). Batch assignment IDs accept non-22-char Contentful IDs with better parse errors.
+
+## 3.3.0
+
+### Minor Changes
+
+- fb60cd5: cms-edit media pipeline facade (prepare/status/catalog/wait/import) with host service auth, job ownership, and rate limits; media-pipeline preview/poster derivatives and expanded tenants
+
+## 3.2.1
+
+### Patch Changes
+
+- e0718e8: Add `task-media-pipeline-prepare` and wire create-from-document / media-reuse to normalize Drive masters via the media pipeline before CMS structure builds.
+
+## 3.2.0
+
+### Minor Changes
+
+- Add source readiness review as a core editor task, wire create-from-document / create-article / preview-verify to faithful package intake (no copy rewrite), and ship SOURCE-READINESS plus multi-site input examples for playbook authors.
+
+## 3.1.10
+
+### Patch Changes
+
+- 3273a0e: Make index catalog select resilient: drop unknown select fields on 422 (schema drift) and shrink page size on Contentful 7 MB response errors.
+
+## 3.1.9
+
+### Patch Changes
+
+- c8dcb0b: Index sync: keep field `select` for catalog types only; stop selecting media fields (SDK could omit `fields` and crash mapping). Harden media/reference mappers against missing fields.
+
+## 3.1.8
+
+### Patch Changes
+
+- 8ec0f61: Fix index sync on large spaces: catalog/media CDA fetches use field `select` + `include=0` so article rich text no longer exceeds Contentful's 7 MB response limit.
+
+## 3.1.7
+
+### Patch Changes
+
+- Media wrapper entries now default their `name` (Contentful list label) to the linked asset's title when created via `create media` or `visualAssetFilename` shorthands. Document the convention in editor playbooks and skills; avoid migration-style `Wrapper for {assetId}` labels.
+
+## 3.1.6
+
+### Patch Changes
+
+- Editor pack generation reads per-project `.site-context.json` from `cms-edit/<projectKey>/` or `docs/cms-editor/<projectKey>/` only (repo-root `.site-context.json` is no longer used). Multi-site repos can scope brand context per Contentful project without cross-site leakage.
+
+## 3.1.5
+
+### Patch Changes
+
+- Clarify preview URL labels for editors: **Live preview (publish here)** vs **Preview (staging site)**. Sort preview URLs with live preview first. Update task playbooks and MCP prompts to hand off both links after save.
+
+## 3.1.4
+
+### Patch Changes
+
+- Clarify Media entry reuse for `visuals` in task-media-reuse-and-upload (avoid duplicate wrappers on shared composites).
+
+## 3.1.3
+
+### Patch Changes
+
+- Reject `asset upload --base64` on hosted MCP and document staged upload as the only binary upload path for agents.
+
+## 3.1.2
+
+### Patch Changes
+
+- Raise hosted staged upload limits: 1000 upload URLs per user per hour (was 30) and 60-minute slot TTL (was 15 minutes). Update hosted MCP docs.
+
+## 3.1.1
+
+### Patch Changes
+
+- Add `staged-upload request` CLI command callable via `cms_edit` MCP args when `cms_edit_request_staged_upload` is unavailable in the client harness.
+
+## 3.1.0
+
+### Minor Changes
+
+- Add staged file upload for hosted MCP: `cms_edit_request_staged_upload` tool, `POST /api/staged-upload` presigned route, and `asset upload --staged` for large files without base64 in tool args.
+
+## 3.0.3
+
+### Patch Changes
+
+- Document hosted MCP asset upload workflow: `--base64` with encoded bytes (not local paths), link-after-upload (`asset set` → `save`), PNG for transparency, and `--url` fallback. Update `task-media-reuse-and-upload` and hosted MCP guide.
+
+## 3.0.2
+
+### Patch Changes
+
+- Detect `definePortedCollection('Name')` when generating editor packs.
+
+## 3.0.1
+
+### Patch Changes
+
+- Fix inline `--json` MCP input by renaming global output flag to `--json-output`. Surface Commander parse errors in MCP tool output. Map `indexed: false` and `hidden: false` in create-from-json.
+
+## 3.0.0
+
+### Major Changes
+
+- **Breaking:** Remove all filesystem and stdin input from cms-edit CLI. JSON commands require `--json` or `--json-base64`. RTF uses `--content` / `--base64`. Asset upload accepts `--url` or `--base64` only.
+
+  Adds Vercel bypass cookie on preview URLs, keeps session after save for preview, resolves preview entry IDs from slug, `create page --no-indexed` and `--featured-image-asset-filename`, and MCP-first playbook updates.
+
+## 2.8.2
+
+### Patch Changes
+
+- Fix `create from-json --dry-run --strict` failing on page/article entries with `Unknown field "name"`. Map JSON `title` to the `title` Contentful field only (not `name`).
+
+## 2.8.1
+
+### Patch Changes
+
+- Add `checks.editorPack` to hosted health endpoint. Harden `stage-site.mjs` scaffold to invoke cms-edit from hoisted node_modules.
+
+## 2.8.0
+
+### Minor Changes
+
+- Add `preview urls` for staging, production, site live preview, and Contentful entry targets. Wire multi-target preview into editor playbooks and MCP create prompts; add `pages.md` / `people.md` playbook stubs and editor-pack checklist/doctor support.
+
+## 2.7.7
+
+### Patch Changes
+
+- 0ee34af: Fix hosted MCP OAuth for Grok Build: accept loopback redirect_uri aliases (127.0.0.1 ↔ localhost) and auto-redirect authorize to Contentful sign-in.
+
+## 2.7.6
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 2.7.5
+
+### Patch Changes
+
+- Ship hosted MCP site labels: per-project server names, prefixed tool descriptions, and `cms_edit_version` fields (`projectKey`, `displayName`, `spaceId`) for multi-connector routing.
+- Generate `production-site.md` editor-pack resource from `project.json` `website.productionSiteUrl` and `website.markdownAccess`, and wire it into overview, checklist, and capabilities.
+
+## 2.7.4
+
+### Patch Changes
+
+- Expose site-specific MCP server names and tool descriptions on hosted cms-edit deployments so Cowork can route multi-connector requests (e.g. "use Brightline cms-edit") without probing each connector. `cms_edit_version` now returns `projectKey`, `displayName`, and `spaceId` on hosted deployments.
+
+## 2.7.3
+
+### Patch Changes
+
+- List site-specific editor tasks from `docs/cms-editor/<projectKey>/tasks/*.md` in generated `tasks-index.md` when building editor packs.
+
+## 2.7.2
+
+### Patch Changes
+
+- Add `task-media-review` editor playbook with production URL support, registry entry, and updated media-review skills for multi-customer Claude workflows.
+
+## 2.7.1
+
+### Patch Changes
+
+- Document article template hierarchy, featuredImage vs visuals, and pre-save checklist in create-article task and fields-article help. Extend generated editor-pack defaults.md with explicit field and landscape OG guidance.
+
+## 2.7.0
+
+### Minor Changes
+
+- Add shared content index invalidation and Redis SQLite blob cache for hosted MCP. Committed writes mark the index dirty; lazy incremental/full sync on the next index command. Local file cache fallback for CLI.
+
+## 2.6.1
+
+### Patch Changes
+
+- Cap `asset review --include-usage` with `--usage-limit` (default 50) to avoid hosted MCP timeouts on large spaces. Document usage-limit in asset-review help and media-review skill.
+
+## 2.6.0
+
+### Minor Changes
+
+- aa6f11b: Breaking cms-edit CLI prune (2.6.0):
+
+  **Removed**
+
+  - `ensure` — use `create … --if-not-exists`
+  - `skill` command (including `skill install`) — use `npx skills add @se-studio/skills`
+  - `contentful-cms` bin alias — use `cms-edit` only
+  - top-level `audit` (`images`, `tree`) — use `asset review --include-usage` and `list`/`open`/`peek`
+  - `backup`, `restore`, `revert` — use `diff` + `discard` + Contentful UI
+  - top-level `run` — use `batch run --file`
+  - top-level `colours`, `types` — use `schema colours`, `schema types <content-type>`
+  - `contentful-cms-image-guide` skill — merged into `contentful-cms-media-review`
+
+  **Added**
+
+  - `create from-json --if-not-exists`
+  - `asset review --include-usage` (slug-bearing usage ancestry)
+  - `batch run` subcommand
+
+  **Migration**
+
+  | Old                                      | New                                            |
+  | ---------------------------------------- | ---------------------------------------------- |
+  | `cms-edit ensure tag-type …`             | `cms-edit create tag-type … --if-not-exists`   |
+  | `cms-edit run --file x.json`             | `cms-edit batch run --file x.json`             |
+  | `cms-edit colours`                       | `cms-edit schema colours`                      |
+  | `cms-edit types component`               | `cms-edit schema types component`              |
+  | `cms-edit audit images`                  | `cms-edit --json asset review --include-usage` |
+  | `cms-edit backup` / `restore` / `revert` | `diff` + `discard`; Contentful UI              |
+  | `cms-edit skill install`                 | `npx skills add @se-studio/skills`             |
+
+- 1262175: Remove `cms-edit sitemap` command. Use `list --type <type>` for content discovery. Update skills, MCP prompts, and editor task playbooks.
+
+## Unreleased
+
+### Breaking Changes
+
+- **Removed `cms-edit sitemap`** — use `cms-edit list --type <type>` (catalog index) instead. Pages: `list --type page`. Articles: `list --type article --sort date`. Full catalog: `index dump --reference-only`. MCP prompts and skills updated.
+
+## 2.5.1
+
+### Patch Changes
+
+- Include `docs/editor-tasks` in the published npm package so `cms-edit editor-pack generate` can copy task playbooks.
+
+## 2.5.0
+
+### Minor Changes
+
+- bc538fd: Editor-pack capabilities router (`capabilities.json`, `tasks-index`, task playbooks), batch commands (`article-tags-from-json`, `bulk-rtf-replace`, `create person` / `person-from-json`, `ensure person`), and `cms-edit project doctor`.
+
+  Hosted-first MCP: setup wizard, `cms-edit setup`, `cms-edit-setup` and `cms-edit-mcp` bins, and local install scripts removed. Editors connect via `/cms-edit` OAuth; developers use `cms-edit` CLI (`npx @se-studio/contentful-cms` aliases the CLI).
+
+  **Breaking:** Do not use local `mcpServers.cms-edit` or `cms-edit setup` — those entry points are removed.
+
+### Patch Changes
+
+- bc538fd: chore: dependency updates (contentful-management, live-preview, hubspot api-client, js-yaml, biome js-api)
+
+## 2.4.0
+
+### Minor Changes
+
+- Remove `cms-edit screenshot` command and agent-browser from cms-edit install/health docs. Add `preview url` / `preview showcase` for preview URLs (open with browser MCP). Refactor `cms-capture-screenshots` to call `cms-edit preview showcase --json` and drive agent-browser directly (no npm dependency on contentful-cms).
+
+  **Breaking:** `cms-edit screenshot` is removed (no `@ref`, `--json-file`, `--live`, or viewport flags). Use `preview url` / `preview showcase` instead. Guidelines PNG capture stays on `cms-capture-screenshots` only.
+
+## 2.3.0
+
+### Minor Changes
+
+- Add `cms-edit asset review` to audit visual assets (filename, alt text, dimensions, file size, GIF) from the Preview API index, plus the `contentful-cms-media-review` skill for spreadsheet workflows.
+- Remove `cms-edit screenshot`. Use `cms-edit preview url` and `cms-edit preview showcase` for preview URLs (open with a browser MCP). Guidelines tooling (`cms-capture-screenshots`) shells out to `preview showcase`. Remove agent-browser from install scripts and `cms-edit health`.
+
+### Breaking Changes
+
+- **Removed:** `cms-edit screenshot` and the `contentful-cms-screenshots` skill. No PNG capture, `@ref` render-json URLs, `--json-file`, `--live`, or `--width`/`--height` via cms-edit.
+- **Replacement:** `cms-edit preview url <slug>` for pages; `cms-edit preview showcase --component|--collection` for showcase mock URLs. CMS guidelines batch capture remains `cms-capture-screenshots` in `@se-studio/project-build` (requires agent-browser).
+
+### Patch Changes
+
+- a72a7c9: Add `cms-edit customer` CLI subcommand so `cms_edit ["customer", "resource=index"]` works when Claude Integrations does not expose `cms_edit_customer`.
+
+## 2.2.3
+
+### Patch Changes
+
+- Add `cms-edit customer` CLI subcommand so `cms_edit ["customer", "index"]` and `cms_edit ["customer", "resource=index"]` work when Claude Integrations does not expose the separate `cms_edit_customer` tool.
+
+## 2.2.2
+
+### Patch Changes
+
+- Add `cms_edit_customer` MCP tool and hosted playbook routes (`/api/customer/*`, `/cms-edit/playbooks/*`) so Claude Integrations can read site editor-pack playbooks without MCP resources.
+
+## 2.2.1
+
+### Patch Changes
+
+- Fix hosted MCP connection failure when editor packs include both `defaults.md` and `defaults.json` (duplicate `cms-edit://customer/defaults` registration). Prefer markdown for MCP resources when both formats exist. Log MCP handler 500 errors to stderr for Vercel visibility.
+
+## 2.2.0
+
+### Minor Changes
+
+- Bulk version bump: minor for all packages
+
+## 2.1.1
+
+### Patch Changes
+
+- Wire hosted cms-edit deployments to use server-side `CONTENTFUL_PREVIEW_ACCESS_TOKEN` and `CONTENTFUL_ACCESS_TOKEN` from Vercel env for index sync, so AI Editor roles work without CMA api_keys access.
+
+## 2.1.0
+
+### Minor Changes
+
+- First-class article support for hosted cms-edit: MCP prompts (`cms_edit_create_article`, `cms_edit_edit_article`, `cms_edit_create_article_from_doc`), editor-pack `defaults` resources, and article playbook wiring.
+
+  - Add `create article` / `create from-json` article-type resolution by slug, name, or ID; featured-image fallback chain (explicit → articleType → site default).
+  - Add `editor.defaults` and `website.customerName` / `website.siteTitle` to `project.json`; gate hosted deploy (`project validate`, `host stage`) until a site default featured image is declared.
+  - Fix `create from-json --dry-run` strict mode for `articleTypeSlug` / `articleTypeName` JSON fields.
+  - Remove unused `editor.contentfulUi` schema field.
+
+## 2.0.4
+
+### Patch Changes
+
+- Add OAuth `refresh_token` grant for hosted cms-edit MCP so Claude can silently renew MCP access tokens (30-day refresh token, 1-hour access JWT). Fixes auth dropout after ~1 hour without re-connecting.
+- Add Axiom telemetry for `/oauth/token` success and failure (`authorization-code`, `refresh-token` subcommands).
+
+## 2.0.3
+
+### Patch Changes
+
+- Fix Axiom telemetry ingest URL: use `/v1/datasets/{dataset}/ingest` (the previous `/v1/ingest/{dataset}` path returned 404 and events were silently dropped).
+
+## 2.0.2
+
+### Patch Changes
+
+- Add opt-in Axiom telemetry for hosted cms-edit MCP: aggregate command outcomes by `project_key` with no PII. Enable with `CMS_EDIT_TELEMETRY=1`, `AXIOM_TOKEN`, and `AXIOM_DATASET`. OAuth `link-contentful` failures emit stable reason codes. See `packages/contentful-cms/docs/TELEMETRY_AXIOM.md`.
+
+## 2.0.1
+
+### Patch Changes
+
+- Add OAuth auth failure logging for hosted cms-edit (`[cms-edit:oauth]`). Auth failures always log to stderr; set `LOG_CMS_OAUTH=1` for verbose connect traces.
+
+## 2.0.0
+
+### Major Changes
+
+- Replace `.mcpb` bridge with OAuth-first hosted MCP. Add `@se-studio/contentful-cms/hosted/next` exports and `cms-edit host scaffold` / `cms-edit host stage` CLI commands. Remove `cms-edit mcpb pack` and the `mcpb/` package tree.
+
+## 1.4.0
+
+### Minor Changes
+
+- Sort articles by publication `date` instead of `sys.updatedAt`. Index schema v4 stores article dates for fast `list --type article --sort date`. `search --type article` and `sitemap --sort date` also use publication date. MCP guide and skills clarify that `peek`/`open` support drafts (only `--published` is published-only).
+
+## 1.3.7
+
+### Patch Changes
+
+- Improve cms-edit MCPB install trust: enrich manifest with long_description, tools, privacy_policies, and onboarding links; add editor-facing install-warning FAQ to HOSTED.md and cms-edit-host onboarding page.
+
+## 1.3.6
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.3.5
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.3.4
+
+### Patch Changes
+
+- Show cms-edit version on the hosted homepage. Add outputFileTracingRoot for customer-repo workspace deploys. Document workspace pattern for cms-edit/host in customer repos.
+
+## 1.3.3
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.3.2
+
+### Patch Changes
+
+- Document SE Studio homepage CMS slug (`index`): clarify `/` vs `/index` in hosted guide, editor-pack routing, and onboarding prompts.
+
+## 1.3.1
+
+### Patch Changes
+
+- Use `/tmp` for cms-edit local data on Vercel/serverless so `open` and `peek` can build the content index.
+
+## 1.3.0
+
+### Minor Changes
+
+- Add cms-edit project config, editor-pack generation, customer MCP resources, mcpb pack CLI, and hosted onboarding improvements.
+
+## 1.2.5
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.2.4
+
+### Patch Changes
+
+- Resolve person **`bio`** rich text on **`IPersonLink`** so team cards, related-people collections, and search/markdown pipelines can use CMS bios without fetching full person pages.
+
+  **@se-studio/core-data-types** — Add **`IResolvedRichText`** (`{ json, customStyles? }`) as the shared resolved RTF shape. **`IPersonLink.bio`** and **`ILinkProps.longText`** use it. **`contentfulAllPersonLinks`** consumers get typed **`IPersonLink[]`**.
+
+  **@se-studio/contentful-rest-api** — Include `fields.bio` in **`PERSON_LINK_FIELDS`**. **`basePersonLinkConverter`** returns **`IPersonLink`** with resolved bio. **`contentfulAllPersonLinks`** return type is **`CmsResponse<IPersonLink[]>`**.
+
+  **@se-studio/markdown-renderer** — **`MarkdownConverter`** exports person-link **`bio`** to Markdown (search/index pipelines). Uses **`isPersonLink`** type guard.
+
+  **@se-studio/core-ui** — **`FetchHelpers.getAllPersonLinks`** for collection use via **`rendererConfig.fetchHelpers`** (no cms-server import). **`getAllPersonLinks`** and sitemap deps typed as **`IPersonLink[]`**.
+
+  **@se-studio/contentful-cms** / **@se-studio/skills** — Document Person **`bio`** RTF authoring in cms-edit skills and functional spec.
+
+## 1.2.3
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.2.2
+
+### Patch Changes
+
+- Add ordered `article.authors` CMS field support (first author = primary) with shared helpers in `@se-studio/core-data-types`: `getArticleAuthors`, `getPrimaryArticleAuthor`, `formatArticleAuthorNames`, and `normalizeResolvedArticleAuthors`. Legacy single `author` remains populated as `authors[0]` during migration.
+
+  **@se-studio/contentful-rest-api** — Resolve and normalize `authors` on full articles and article links; include `fields.authors` in link-only fetches. Related-articles scoring matches any listed co-author.
+
+  **@se-studio/core-ui** — Structured data context exposes multi-author JSON-LD (`article.authors`); related-articles fallback uses all article authors. Omits authors without a display name.
+
+  **@se-studio/search** / **@se-studio/markdown-renderer** — Index and export comma-separated multi-author bylines via `formatArticleAuthorNames`.
+
+  **@se-studio/contentful-cms** — Fetch and audit entry trees traverse `authors` links; shared `linkedEntryFields` module deduplicates traversal logic.
+
+  **@se-studio/skills** — Add `contentful-cms-sync-schema` skill; document multi-author Schema.org variables.
+
+  Run migration `scripts/migrations/17-add-article-authors.js` on live spaces after deploying packages.
+
+## 1.2.1
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.2.0
+
+### Minor 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`
+
+## Unreleased
+
+### Patch Changes
+
+- **Fix:** schema v2 index databases no longer fail to open with `no such column: cmsLabel`. Column migration now runs before v3 index creation so `open`, `index sync`, and `ensureContentIndex` work on existing indexes.
+
+### Minor Changes
+
+- **Content catalog (schema v3)** — index `page`, `article`, `pageVariant`, `navigation`, `navigationItem` alongside taxonomy and templates; stores `cmsLabel`, `tagTypeSlug`, and `articleTypeSlug` for scoped list/lookup.
+- **Flat lookup flags** — `open`, `resolve`, and `nav open` use explicit flags (`--page-slug`, `--page-cms-label`, `--nav-name`, etc.). Positional `open <slug>` and `resolve --type` / `--slug` removed.
+- **`list` index-first** for all catalog types; `--tag-type-slug|name` and `--article-type-slug|name` filters.
+- **Tag cmsLabel** — `create tag` derives `"<tagType name> — <tag name>"` when `--cms-label` is omitted; `--tag-type-slug` and `--tag-type-name` on create.
+- **Tag create flags** — `create tag` and `ensure tag` accept `--description` and `--featured-image <asset-id>` so import workflows can set all tag fields in one command.
+- **Slug normalization** — trailing slashes stripped on slug flags.
+- **Verbose index sync** — `cms-edit index sync --verbose` (or `LOG_CMS_INDEX=1`) logs CDN fetch and SQLite write progress on stderr.
+- **Index sync lock** — if another sync holds the lock file, fail immediately (exit 1) instead of waiting up to 10 minutes.
+- **Fix:** first-time `index sync` no longer fails with a misleading “already in progress” error when the index directory did not exist yet (lock file was never created).
+
+### Breaking Changes
+
+- `cms-edit open /pricing` → `cms-edit open --page-slug pricing`
+- `cms-edit peek /pricing` → `cms-edit peek --page-slug pricing`
+- `cms-edit open <id> --id` → `cms-edit open --id <id>`
+- `cms-edit nav open footer` → `cms-edit nav open --nav-name "Footer"`
+- `cms-edit resolve --type tag --slug x` → `cms-edit resolve --tag-slug x`
+
+### Minor Changes (continued)
+
+- **Content index (schema v2)** — extends the local SQLite index with a reference catalog (`template`, `articleType`, `tagType`, `tag`) for fast `list`, `resolve`, and taxonomy `--if-not-exists` flows.
+- **Automatic index sync** — index-backed commands call `ensureContentIndex` internally. You do not need to run `cms-edit index sync` first in normal agent workflows. If the index is **missing**, on an **outdated schema**, or **older than 24 hours**, cms-edit syncs automatically (full rebuild for missing/schema mismatch; incremental upsert when only stale). Manual `cms-edit index sync` always performs a full rebuild.
+- **`requireMediaIndex` removed** — replaced by async `ensureContentIndex` (auto-sync instead of fail-fast when the index is absent or out of date).
+- **`resolve --type template --label`** — resolve templates by cmsLabel; `list --type template --slug` filters by cmsLabel.
+- **`index dump --reference-only`** / **`--reference-type`** — browse the reference catalog.
+- **Bundled skills sync** — `pnpm --filter @se-studio/contentful-cms sync:skills` copies a subset of cms-edit skills from `@se-studio/skills`; setup wizard can install them into `.agents/skills`.
+
+### Notes
+
+- Incremental auto-sync only upserts rows changed since the last sync. Entries deleted in Contentful may remain until the next manual full `index sync`.
+- Duplicate slug/label rows in the index cause `resolve` to fail with an explicit ambiguity error.
+
+## 1.1.0
+
+### Minor Changes
+
+- f666197: Add taxonomy create/ensure commands, multi-source asset upload, and a local media index for fast asset/media discovery.
+
+  - **`create tag-type` / `create article-type` / `create tag`** — draft taxonomy entries with `--json-file`, `--if-not-exists`, and `--dry-run`
+  - **`create taxonomy-from-json`** — batch taxonomy import from JSON
+  - **`ensure`** — idempotent create-or-resolve for taxonomy entries
+  - **`resolve --type` / `--slug`** — resolve entries by content type and slug
+  - **`asset upload`** — upload from `--file`, `--base64`, or `--url`; optional `--with-media`, `--if-exists-by-filename`
+  - **`asset search` / `asset audit`** — index-backed title and filename search
+  - **`list --type media`** — filter by `--asset-id` or `--asset-filename*`
+  - **`index sync` / `index status` / `index dump`** — Preview API SQLite index (default draft; `--published` for Delivery API)
+  - Config: optional `previewAccessToken`, `deliveryAccessToken`, and delivery key resolution via CMA
+
+  Fixes #42.
+
+- **`create from-json`** — asset and Media/visual link shorthands on page, article, and component `fields` (`featuredImage`, `featuredImageAssetFilename`, `visualAssetFilename`, `visualMedia`, etc.); unknown-field warnings; `--strict` and strict validation on `--dry-run` (aligned with `taxonomy-from-json` dry-run behaviour)
+
+  Fixes #43.
+
+## 1.0.91
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+- Dependency upgrades: `commander` 15, `@anthropic-ai/mcpb` 2.1.2, `esbuild` 0.28; monorepo `vitest` 4.1.8 and `vite` 7.3.3 override (security); root Node engine minimum raised to 22.12.0
+
+## 1.0.90
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.89
+
+### Patch Changes
+
+- **`cms-edit batch`** — edit multiple entries by Contentful entry ID (`batch set`, `batch diff`, `batch save`, `batch discard`); uses `--session batch` by default; parallel entry fetch; schema-aware scalar coercion and enum validation
+- **`cms-edit links set`** — set any scalar field on a link entry: `links set <ref> <index> <field> <value>` (e.g. `variant link`); `--variant` retained as deprecated alias; `--variant` on `links add`
+- **Content type schema cache** — session `contentTypes` plus `~/.contentful-cms/content-types/` disk cache (24h TTL) for field types and validations
+- **`cms-edit set`** — detects batch-style tokens and points users to `cms-edit batch set`
+- Shared `buildLinkEntryFields` helper and `resolveScalarValueForField` for link creation and scalar sets across CLI, `run`, and `create from-json`
+
+## 1.0.88
+
+### Patch Changes
+
+- Embed package version and hosted MCP guide at build time (fixes ENOENT when Next.js bundles the package)
+- cms-edit-host: externalize `@se-studio/contentful-cms` and trace docs for serverless deploys
+
+## 1.0.86
+
+### Patch Changes
+
+- `peek` now includes root field values in output (`rootFields` in JSON; human mode shows fields for standalone entries)
+- Add `diagnose` command for MCP session debugging (store type, userId, active session key)
+- Clarify peek/read docs — entry IDs require `--id`; peek does not chain to `read`
+
+## 1.0.85
+
+### Patch Changes
+
+- Clarify `peek` vs `open` vs `read` in MCP tool description and docs (entry IDs require `--id`; peek is one-shot with no chainable read)
+- Document session logging env var (`LOG_CMS_SESSION=1`) in hosted troubleshooting
+
+## 1.0.82
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.81
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.80
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.79
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.78
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.77
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.76
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.75
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.74
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.73
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.72
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.71
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.70
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.69
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.68
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## Unreleased
+
+### Breaking Changes
+
+- **`cms-edit rtf` and `cms-edit rtf edit`**: the input-format flag `--json` has been renamed to `--rtf-json`. This resolves an ambiguity where the global `--json` output flag (machine-readable JSON mode) was intercepting the subcommand flag, silently storing JSON file content as a plain-text paragraph instead of a Rich Text document. Migration: replace `--json` with `--rtf-json` in any `rtf` or `rtf edit` invocations. The `--rtf-json` name is now consistent with `cms-edit set --rtf-json`.
+
+## 1.0.66
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.65
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.64
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.63
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.60
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.59
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.58
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.57
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.56
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.55
+
+### Breaking Changes / Behaviour
+
+- **`cms-edit rtf`** adds `--text`, `--markdown`, `--html`, `--json` (mutually exclusive). **Default when omitted is `--markdown`** — typical Markdown flows behave like before; document scripts with explicit flags where clarity matters.
+- **`cms-edit set`** can set Rich Text fields directly with `--rtf-text` \| `--rtf-markdown` (default when converting strings to RTF) \| `--rtf-html` \| `--rtf-json`; `--file`/`--json` for Rich Text must supply a full Rich Text document object.
+- **`create from-json`** auto-detects HTML and Rich Text JSON strings in addition to Markdown heuristics; use `{ "value", "format" }` for explicit conversion.
+- **`rtf replace`** / **`rtf patch`**: new `--replace-html`, `--replace-json`, `replaceIsHtml`, `replaceIsJson`, `replaceFormat`.
+
+## 1.0.54
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.49
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.48
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.47
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.46
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.45
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.44
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.43
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.42
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.41
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.40
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.39
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.38
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.36
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.35
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.34
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.33
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.32
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.31
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.29
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.27
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.23
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.22
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.21
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.20
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.19
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.18
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.17
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.16
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.15
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.14
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.13
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.12
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.11
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.10
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.9
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.8
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.7
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.6
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.5
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.4
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.3
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.2
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.1
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.0
+
+- Initial release.
+- **Added:** `set <ref> <field> <entry-id> --link` to set entry link fields (e.g. page template).
+- **Added:** `links <ref> add --type internal --id <entry-id>` to add an internal link by Contentful entry ID (in addition to `--slug`).
+- **Added:** `links <ref> add --type download --label "..." --asset-id <asset-id>` to add a download link referencing a Contentful asset by ID.
+- **Fixed:** `open <slug>` with Contentful Management API: slug lookup now queries one content type at a time (page, then article). Navigation entries are not findable by slug (use `nav open` by id/slug).