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

package/docs/help/fields-component.md

@@ -0,0 +1,165 @@
+# cms-edit — Component Field Reference
+
+A `component` entry is an individual content section — a hero, text block, card, timeline item, etc. The `componentType` field picks which visual variant to render.
+
+---
+
+## Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `cmsLabel` | Text | Human-readable label in Contentful's entry list |
+| `componentType` | Text | Variant discriminator — e.g. `HeroSimple`, `TextBlock`, `Generic`. Run `cms-edit schema types component` to see valid values |
+| `heading` | Text | Main heading text |
+| `preHeading` | Text | Small label above the heading. Rendered as `<p>`, not a heading tag |
+| `postHeading` | Text | Small label below the heading. Rendered as `<p>`, not a heading tag |
+| `body` | RichText | Main body content. Accepts markdown in `create from-json` and `run rtf` |
+| `links` | Array of Links | CTA link entries attached to this component |
+| `visual` | Link (Asset or Entry) | Primary visual: image asset or responsive visual entry |
+| `mobileVisual` | Link (Asset or Entry) | Alternative visual for mobile viewports |
+| `backgroundColour` | Text | Named colour. Run `cms-edit schema colours` to see valid values |
+| `textColour` | Text | Named colour for text. Run `cms-edit schema colours` to see valid values |
+
+Not all components use all fields — unused fields are simply null.
+
+---
+
+## Reading Component Fields
+
+```bash
+cms-edit open --page-slug /solutions/hepatology
+cms-edit snapshot
+cms-edit read @c1              # all fields on the first component
+cms-edit read @c1 heading      # just the heading
+cms-edit read @c1 body         # rich text summary
+```
+
+---
+
+## Setting Scalar Fields
+
+```bash
+cms-edit set @c1 heading "New Heading"
+cms-edit set @c1 preHeading "Our Speciality"
+cms-edit set @c1 postHeading null          # clear the field
+cms-edit set @c1 backgroundColour "Navy"
+cms-edit set @c1 textColour "White"
+```
+
+---
+
+## Setting Rich Text (body)
+
+```bash
+# Inline markdown
+cms-edit rtf @c1 body "## Overview\n\nFirst paragraph.\n\nSecond paragraph."
+
+# From a file
+cms-edit rtf @c1 body --content "# ..."
+
+# Find and replace within existing rich text
+cms-edit rtf replace @c1 body --find "old text" --replace-plain "new text"
+```
+
+**Rich text rules:**
+- Single sentences must include `\n\n` to be converted to a paragraph: `"One sentence.\n\n"`
+- The `body` field is always RichText — the schema ensures correct conversion
+- Headings, lists, bold, italic, and links are all supported in markdown
+
+**Markdown examples:**
+```
+# Heading 1
+## Heading 2
+
+Plain paragraph text.
+
+**Bold text** and _italic text_.
+
+- List item one
+- List item two
+  - Nested item
+
+[Link text](https://example.com)
+
+> A blockquote
+```
+
+---
+
+## Managing CTA Links
+
+```bash
+# List existing links
+cms-edit links list @c1
+
+# Add a new external link
+cms-edit links add @c1 --type external --label "Learn More" --href "https://example.com"
+
+# Add an internal link (resolves slug to entry)
+cms-edit links add @c1 --type internal --label "Our Team" --slug /about/team
+
+# Add a download link
+cms-edit links add @c1 --type download --label "Download PDF" --asset-id <assetId>
+
+# Set link variant (text link vs button — see cms-edit schema link)
+cms-edit links set @c1 0 variant link
+
+# Remove a link (by index)
+cms-edit links remove @c1 0
+
+# Reorder links
+cms-edit links move @c1 1 0   # move index 1 to index 0
+```
+
+---
+
+## Setting Visuals
+
+```bash
+# Link an asset directly
+cms-edit set @c1 visual --asset <assetId>
+
+# Search for assets
+cms-edit asset search "hepatology"
+
+# Get asset info
+cms-edit asset info <assetId>
+```
+
+---
+
+## In create from-json
+
+```json
+{
+  "contentType": "component",
+  "type": "HeroSimple",
+  "cmsLabel": "Homepage Hero",
+  "fields": {
+    "heading": "Headline text",
+    "preHeading": "Label above",
+    "postHeading": "Label below",
+    "body": "Opening paragraph.\n\nSecond paragraph.",
+    "backgroundColour": "Navy",
+    "textColour": "White"
+  },
+  "links": [
+    { "type": "internal", "label": "Learn More", "slug": "/about" },
+    { "type": "external", "label": "Contact", "href": "https://example.com/contact" }
+  ]
+}
+```
+
+Use explicit visual shorthands in `fields` (see `cms-edit help create-from-json`). Examples:
+
+```json
+"fields": {
+  "visualId": "<existing-media-entry-id>",
+  "visualAssetFilename": "hero.jpg",
+  "visualMedia": { "assetId": "<asset-id>", "name": "Homepage Hero", "position": "Middle", "width": 40 }
+}
+```
+
+**Media entry `name`:** This is the label editors see in Contentful's entry list. Set it to the **linked asset's title** (same as `asset info` / Contentful asset title). Do not use `visual-{assetId}`, `Wrapper for {assetId}`, or raw filenames.
+
+Do not put a bare filename on `visual` — use `visualAssetFilename`. Requires `cms-edit index sync` for `*AssetFilename` keys.

package/docs/help/fields-page.md

@@ -0,0 +1,123 @@
+# cms-edit — Page Field Reference
+
+A `page` entry is the root of a web page's content tree. It has a slug, metadata, and arrays of content components.
+
+---
+
+## Top-Level Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `slug` | Text | Yes | URL slug without leading or trailing slash. Example: `part1/part2/part3`. Use `index` for the home page. |
+| `title` | Text | Yes | Page title used in `<title>` and headings |
+| `description` | Text | No | SEO meta description |
+| `cmsLabel` | Text | No | Label shown in Contentful's entry list. Defaults to `title` |
+| `indexed` | Boolean | No | Whether the page is indexed by search engines |
+| `hidden` | Boolean | No | Whether the page is excluded from the sitemap |
+| `template` | Link (Entry) | No | Link to a `template` entry for shared layout slots |
+| `featuredImage` | Link (Asset) | No | Featured image asset for social sharing |
+
+---
+
+## Content Arrays
+
+A page has three content slot arrays. Components are rendered in order within each slot.
+
+| Field | Type | Description |
+|---|---|---|
+| `topContent` | Array of Links | Content rendered above the main content area (e.g. sticky nav, announcement bar) |
+| `content` | Array of Links | Main content area. **Default target for `add` and `create from-json`** |
+| `bottomContent` | Array of Links | Content rendered below the main content area (e.g. newsletter signup) |
+
+Each array entry is a link to a `component`, `collection`, or `externalComponent` entry.
+
+---
+
+## Reading Page Fields
+
+```bash
+cms-edit open --page-slug /solutions
+cms-edit read @c0           # read all fields on the page entry
+cms-edit read @c0 title     # read just the title
+cms-edit read @c0 slug
+```
+
+---
+
+## Setting Page Fields
+
+```bash
+cms-edit set @c0 title "New Title"
+cms-edit set @c0 description "Updated SEO description."
+cms-edit set @c0 indexed true
+cms-edit set @c0 hidden false
+```
+
+---
+
+## Linking a Template
+
+To link a template to a page, use the template entry ID:
+
+```bash
+cms-edit set @c0 template --link <templateEntryId>
+```
+
+Or in `create from-json`:
+```json
+{
+  "slug": "/new-page",
+  "title": "New Page",
+  "templateId": "<templateEntryId>"
+}
+```
+
+Find template IDs with:
+```bash
+cms-edit list --type template
+```
+
+---
+
+## Adding Content to a Page
+
+```bash
+# Add a new component to the default content array
+cms-edit add HeroSimple component
+
+# Add to topContent
+cms-edit add AnnouncementBar component --target topContent
+
+# Add to bottomContent
+cms-edit add NewsletterSignup component --target bottomContent
+
+# Insert after a specific entry
+cms-edit add TextBlock component --after @c3
+```
+
+---
+
+## In create from-json
+
+```json
+{
+  "type": "page",
+  "slug": "/solutions/hepatology",
+  "title": "Hepatology Solutions",
+  "description": "Evidence generation for hepatology research.",
+  "cmsLabel": "Hepatology Solutions Page",
+  "templateId": "optionalTemplateId",
+  "featuredImage": "<asset-id>",
+  "featuredImageAssetFilename": "social-share.jpg",
+  "indexed": true,
+  "hidden": false,
+  "components": [
+    {
+      "contentType": "component",
+      "type": "HeroSimple",
+      "target": "content",
+      "fields": { "heading": "Hepatology Solutions" }
+    }
+  ]
+}
+```

package/docs/help/fields-taxonomy.md

@@ -0,0 +1,158 @@
+# cms-edit — Taxonomy Field Reference
+
+Taxonomy entries (`tagType`, `articleType`, `tag`) can be created as **drafts** with the CLI. Use `--json-file` for full field control, or `--slug` / `--name` for minimal creates.
+
+```bash
+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
+cms-edit create tag --slug easl-congress-2026 --name "EASL Congress 2026" --tag-type publication-source \
+  --description "Research presented at EASL Congress 2026." --featured-image <logoAssetId>
+
+# Idempotent import helpers
+cms-edit create tag-type --slug conference-venue --name "Conference Venue" --if-not-exists
+cms-edit resolve --tag-type-slug presentation-type
+```
+
+All creates are draft-only. See `cms-edit help taxonomy-from-json` for batch bootstrap.
+
+---
+
+## tagType fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | Text | Yes | Display name |
+| `slug` | Text | No | URL slug without leading or trailing slash. Example: `part1/part2`. Optional. |
+| `show` | Boolean | No | Whether tags of this type show visually on cards/detail |
+| `template` | Link (Entry) | No | Template for tag detail pages |
+| `topContent` | Array of Links | No | Content above main area on tag detail |
+| `menu` | Link (Entry) | No | Navigation entry |
+| `footer` | Link (Entry) | No | Footer navigation entry |
+| `indexPageTemplate` | Link (Entry) | No | Template for tag-type index page |
+| `indexPageTopContent` | Array of Links | No | Top content on tag-type index |
+
+---
+
+## articleType fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | Text | Yes | Display name |
+| `cmsLabel` | Text | Yes | Label in Contentful entry list (defaults to `--name`) |
+| `slug` | Text | Yes | URL slug without leading or trailing slash. Example: `part1/part2/part3`. Use `index` for the home page. |
+| `indexPageTitle` | Text | Yes | Title on article index page (defaults to `--name`) |
+| `indexPageDescription` | Text | Yes | Description on article index (defaults to `""`) |
+| `featuredImage` | Link (Asset) | No | Featured image for index/social |
+| `menu` | Link (Entry) | No | Navigation entry |
+| `footer` | Link (Entry) | No | Footer navigation entry |
+| `indexPageTemplate` | Link (Entry) | No | Template for article index |
+| `indexPageTopContent` | Array of Links | No | Top content on article index |
+| `indexPageStructuredData` | Array of Links | No | Schema entries for index page |
+| `visuals` | Array of Links | No | Media/externalVideo entries |
+| `articleTemplate` | Link (Entry) | No | Template for article detail pages |
+| `articlePageTopContent` | Array of Links | No | Top content on article detail |
+| `structuredData` | Array of Links | No | Schema entries for article pages |
+| `backgroundColour` | Symbol | No | Valid values: `cms-edit schema colours` |
+| `textColour` | Symbol | No | Valid values: `cms-edit schema colours` |
+| `indexed` | Boolean | Yes | Search indexing (default: `true`) |
+| `hidden` | Boolean | Yes | Sitemap visibility (default: `false`) |
+| `indexPageHidden` | Boolean | No | Hide article index page |
+| `articlePageHidden` | Boolean | No | Hide article detail pages |
+| `flags` | Array of Symbols | No | e.g. `"Sticky nav"` |
+| `searchTemplate` | Link (Entry) | No | Template for search results |
+| `searchTopContent` | Array of Links | No | Top content on search results |
+| `breadcrumbTitle` | Text | No | Override for breadcrumb label |
+
+---
+
+## tag fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `cmsLabel` | Text | Yes | Label in Contentful (defaults to `--name`) |
+| `name` | Text | Yes | Display name |
+| `tagType` | Link (Entry) | Yes | Parent tagType entry |
+| `slug` | Text | Yes | URL slug without leading or trailing slash. Example: `part1/part2`. |
+| `description` | Text | No | Short description |
+| `featuredImage` | Link (Asset) | No | Featured image |
+| `visuals` | Array of Links | No | Media/externalVideo entries |
+| `menu` | Link (Entry) | No | Navigation entry |
+| `footer` | Link (Entry) | No | Footer navigation entry |
+| `template` | Link (Entry) | No | Template for tag detail |
+| `topContent` | Array of Links | No | Top content on tag detail |
+| `structuredData` | Array of Links | No | Schema entries |
+| `backgroundColour` | Symbol | No | Valid values: `cms-edit schema colours` |
+| `textColour` | Symbol | No | Valid values: `cms-edit schema colours` |
+| `indexed` | Boolean | Yes | Search indexing (default: `true`) |
+| `hidden` | Boolean | Yes | Sitemap visibility (default: `false`) |
+| `show` | Boolean | No | Visual display on cards/detail |
+| `breadcrumbTitle` | Text | No | Override for breadcrumb label |
+
+Tags require `--tag-type <slug>` or `--tag-type-id <id>` (or `tagTypeSlug` / `tagTypeId` in JSON).
+
+---
+
+## JSON file shape
+
+Use `--json-file` with any taxonomy create command. CLI flags override JSON values.
+
+```jsonc
+{
+  "fields": {
+    "name": "Poster Presentation",
+    "slug": "poster-presentation",
+    "description": "Poster session at ASCO 2025",
+    "show": true,
+    "indexed": true,
+    "hidden": false,
+    "backgroundColour": "White",
+    "textColour": "Navy"
+  },
+  "tagTypeSlug": "presentation-type",
+  "featuredImageId": "abc123",
+  "templateId": "tmpl456",
+  "topContentIds": ["comp1", "comp2"]
+}
+```
+
+### Link shorthands
+
+These top-level keys resolve to Contentful Entry/Asset links (same conventions as `create from-json`):
+
+| Shorthand | Resolves to field |
+|---|---|
+| `tagTypeId`, `tagTypeSlug` | `tagType` (tags only) |
+| `templateId` | `template` |
+| `indexPageTemplateId` | `indexPageTemplate` |
+| `articleTemplateId` | `articleTemplate` |
+| `searchTemplateId` | `searchTemplate` |
+| `menuId` | `menu` |
+| `footerId` | `footer` |
+| `featuredImageId` | `featuredImage` |
+| `topContentIds` | `topContent` |
+| `indexPageTopContentIds` | `indexPageTopContent` |
+| `articlePageTopContentIds` | `articlePageTopContent` |
+| `searchTopContentIds` | `searchTopContent` |
+| `structuredDataIds` | `structuredData` |
+| `indexPageStructuredDataIds` | `indexPageStructuredData` |
+| `visualsIds` | `visuals` |
+
+---
+
+## Common options
+
+| Option | Description |
+|---|---|
+| `--slug <slug>` | Required URL slug |
+| `--name <name>` | Required display name |
+| `--cms-label <label>` | CMS label (articleType/tag; defaults to name) |
+| `--description <desc>` | Short description (tags only) |
+| `--featured-image <asset-id>` | Asset ID for featured image (tags only) |
+| `--json-file <path>` | Full field spec (see above) |
+| `--if-not-exists` | Return existing entry ID when slug matches (exit 0) |
+| `--dry-run` | Validate field build and link resolution without writing |
+
+**Idempotency:** `--if-not-exists` checks Contentful then creates. They work for **sequential** import scripts. Do not run two creates for the same slug in parallel — both may succeed. Re-run with `--if-not-exists` to converge.
+
+Use `CMS_EDIT_JSON=1` or `--json-output` for machine-readable output: `{ ok, id, slug, contentType, status: "created"|"existing"|"dry-run" }` (`id` is empty on dry-run).

package/docs/help/fields.md

@@ -0,0 +1,60 @@
+# cms-edit — Content Type Field Reference
+
+This page lists the content types managed by `cms-edit` and links to their field references.
+
+---
+
+## Content Types
+
+| Content Type | Used For | Detail |
+|---|---|---|
+| `page` | Web pages with a slug and content tree | `cms-edit help fields-page` |
+| `article` | Blog posts and news items | `cms-edit help fields-article` |
+| `component` | Individual content sections (hero, text block, card, etc.) | `cms-edit help fields-component` |
+| `collection` | Groups of components (card grids, timelines, etc.) | `cms-edit help fields-collection` |
+| `link` | CTA button entries | Managed via `cms-edit links` |
+| `template` | Reusable page shell (header, footer slots) | Used via `templateId` in `create from-json` |
+| `navigation` | Site navigation entries | Managed via `cms-edit nav` |
+
+---
+
+## Type Discriminators
+
+Many content types have a `*Type` field that picks a specific variant:
+
+| Content Type | Discriminator Field | Values |
+|---|---|---|
+| `component` | `componentType` | `HeroSimple`, `TextBlock`, `CardGrid`, `Generic`, etc. |
+| `collection` | `collectionType` | `CardGrid`, `Timeline`, `CategoryExplorer`, etc. |
+
+Run `cms-edit schema types <content-type>` to see all valid discriminator values for the current space.
+
+---
+
+## Colour Fields
+
+The `backgroundColour` and `textColour` fields accept named values, not hex codes.
+
+Run `cms-edit schema colours` to see valid values for the current space.
+
+Common values: `"Navy"`, `"White"`, `"Grey"`, `"Black"`, `"Brand"`.
+
+---
+
+## Ref Addressing
+
+When a session is open (after `cms-edit open`), entries are addressed by `@ref`:
+
+- `@c0` — the root page/article entry
+- `@c1`, `@c2`, ... — entries in depth-first traversal order
+
+Run `cms-edit snapshot` to see current refs.
+
+---
+
+## Field Detail Pages
+
+- `cms-edit help fields-page` — page entry fields
+- `cms-edit help fields-article` — article entry fields
+- `cms-edit help fields-component` — component entry fields
+- `cms-edit help fields-collection` — collection entry fields

package/docs/help/index-sync.md

@@ -0,0 +1,136 @@
+# Content index sync
+
+cms-edit keeps a **local SQLite index** per space/environment for fast asset, media, and **content catalog** discovery. The default index is built from the **Content Preview API** (draft content) — matching cms-edit’s draft-only workflow.
+
+## What gets indexed
+
+| Table | Content |
+|-------|---------|
+| `assets` | All CDN assets (filename, title, MIME, dimensions) |
+| `media` | Media wrapper entries linked to assets |
+| `reference_entries` | Content catalog metadata (no content trees) |
+
+Catalog and media pages use Contentful `select` + `include=0` so only index fields are fetched.
+That keeps responses under Contentful’s ~7 MB limit on large spaces (e.g. many articles with rich text).
+
+### Catalog content types (schema v3)
+
+Typically fewer than ~1000 rows each: `page`, `article`, `pageVariant`, `template`, `articleType`, `tagType`, `tag`, `navigation`, `navigationItem`.
+
+Each catalog row stores:
+
+| Column | Purpose |
+|--------|---------|
+| `slug` | Normalized URL slug when the type has `slug` |
+| `label` | List line: `title`, `name`, or template cmsLabel |
+| `cmsLabel` | `cmsLabel` when present (page, article, pageVariant, tag, template) |
+| `tagTypeSlug` | Parent tag type slug (tags only) |
+| `articleTypeSlug` | Parent article type slug (articles only) |
+| `date` | Publication date `YYYY-MM-DD` (articles only; schema v4) |
+
+## When you need it
+
+These commands **require** a built index:
+
+- `cms-edit asset search` (title, `--filename`, `--filename-match`)
+- `cms-edit asset audit`
+- `cms-edit list --type media --asset-id <id>`
+- `cms-edit list --type media --asset-filename …` / `--asset-filename-match …`
+- `cms-edit asset upload --if-exists-by-filename` (lookup uses the index)
+- `*AssetFilename` keys in `create from-json`
+
+Catalog commands **prefer** the index when present (CMA fallback if a row is missing):
+
+- `cms-edit list --type page|article|pageVariant|template|articleType|tagType|tag|navigation|navigationItem`
+- `cms-edit open`, `cms-edit resolve`, `cms-edit nav open` — see [lookup.md](./lookup.md)
+- `cms-edit create … --if-not-exists` for taxonomy
+- `tagTypeSlug` / `tagTypeName` shorthands in JSON create flows
+
+For `--type template`, `--slug` filters by **cmsLabel** (not URL slug).
+
+Use `--force-cma` on `list` to bypass the catalog and paginate via CMA.
+
+## Commands
+
+```bash
+# Full rebuild (draft/preview content — default)
+cms-edit index sync
+
+# Progress on stderr (per-page fetches, catalog types, SQLite write)
+cms-edit index sync --verbose
+# Same via env (also applies to automatic background sync):
+LOG_CMS_INDEX=1 cms-edit index sync
+
+# Check freshness and row counts
+cms-edit index status
+
+# Browse index contents in the terminal
+cms-edit index dump
+cms-edit index dump --all
+cms-edit index dump --type image/ -n 20
+cms-edit index dump --assets-only --skip 50
+cms-edit index dump --reference-only
+cms-edit index dump --reference-type page
+
+# Published content only (separate database file suffix -published)
+cms-edit index sync --published
+cms-edit index status --published
+```
+
+Index path: `~/.contentful-cms/index/<spaceId>/<environment>/media.db` (add `-published` suffix for published-only mode).
+
+## Automatic sync (simplicity)
+
+Commands that depend on the index call **`ensureContentIndex`** internally. You do not need to run `index sync` first in normal agent workflows.
+
+| Condition | Auto-sync behaviour |
+|-----------|---------------------|
+| Index missing | **Hydrate** from shared cache blob if valid, else **full** rebuild |
+| Schema version outdated (e.g. v2 → v3) | **Full** rebuild |
+| Committed write invalidated index (incremental) | **Incremental** upsert on next index command |
+| Committed write invalidated index (full — slug change or catalog delete) | **Full** rebuild on next index command |
+| Last sync older than **24 hours** | **Incremental** upsert (`sys.updatedAt[gte]` last `syncedAt`) |
+| Index fresh | No sync |
+
+Manual `cms-edit index sync` always performs a **full** rebuild.
+
+**Invalidation (lazy, no thrashing):** `save`, `create page|article|…`, `asset upload`, and similar **committed** writes mark the index dirty (Redis on hosted MCP; `invalidation.json` locally). They do **not** sync immediately. The next `list`, `open`, `asset search`, etc. refreshes the index. In-session `set` / `rtf` edits do **not** invalidate.
+
+**Shared cache (hosted MCP):** After sync, the SQLite file is gzipped into Redis (~sub-MB for typical spaces). Cold serverless instances restore from Redis instead of re-fetching all assets from the Preview API.
+
+**Incremental limitations:** Only rows changed since the last sync are fetched. Entries deleted in Contentful may remain in the index until the next **full** invalidation/sync. Duplicate slug/label/cmsLabel rows in the index cause lookup commands to fail with an explicit error (fix in Contentful, then full sync).
+
+**Single writer:** File lock beside `media.db` plus a shared Redis lock on hosted MCP. If another sync is in progress, the command **fails immediately** (exit code 1). Stale file locks (>30 min or dead pid) are removed automatically.
+
+## Preview / delivery API token
+
+The management token cannot call the CDN. For default `index sync`:
+
+| Config field | Purpose |
+|--------------|---------|
+| `previewAccessToken` | Explicit Preview API token (`${CONTENTFUL_PREVIEW_ACCESS_TOKEN}`) |
+| *(auto)* | Linked preview key from a space delivery key via CMA |
+
+For `index sync --published`:
+
+| Config field | Purpose |
+|--------------|---------|
+| `deliveryAccessToken` | Explicit CDA token (`${CONTENTFUL_ACCESS_TOKEN}`) |
+| `deliveryApiKeyName` | Pick a space delivery key by name via CMA |
+| *(auto)* | First delivery key matching the configured environment |
+| `autoCreateDeliveryApiKey` | Create `cms-edit-index` key if none match (needs PAT permissions; warns when used) |
+
+If CMA cannot read API keys, set `previewAccessToken` or `deliveryAccessToken` manually.
+
+## Typical workflow before imports
+
+```bash
+cms-edit index sync
+cms-edit asset search --filename-match 'istock.*'
+cms-edit list --type page
+cms-edit list --type article --article-type-name "Publications"
+cms-edit resolve --tag-type-slug topic
+cms-edit open --page-slug /about
+```
+
+See [lookup.md](./lookup.md) for all `open` / `resolve` flags. See [MEDIA_INDEX_PLAN.md](../MEDIA_INDEX_PLAN.md) for architecture details.