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

package/docs/help/index.md

@@ -0,0 +1,181 @@
+# cms-edit — Help Index
+
+`cms-edit` is an opinionated CLI for reading and editing Contentful draft content across SE Studio apps. It provides a snapshot → ref → edit → save workflow. **All writes create drafts — nothing is published automatically.**
+
+---
+
+## How to Get Help
+
+| Command | What you get |
+|---|---|
+| `cms-edit` | Command list + one-line descriptions |
+| `cms-edit <command> --help` | Options and synopsis for a command |
+| `cms-edit guide [topic]` | Short getting-started markdown for hosted MCP (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) |
+| `cms-edit help <topic>` | Detailed CLI playbooks with examples (this index lists topics) |
+
+Available topics for `cms-edit help <topic>`:
+
+| Topic | Contents |
+|---|---|
+| `workflow` | Standard editing workflow — open, snapshot, edit, save |
+| `create-from-json` | Create a new page or article from a JSON file (single-shot) |
+| `taxonomy-from-json` | Batch-create tagType, articleType, and tag entries from JSON |
+| `person-from-json` | Batch-create person/author entries from JSON |
+| `article-tags-from-json` | Set tags on multiple articles from JSON |
+| `bulk-rtf-replace` | Find-replace plain text across Rich Text fields in entry trees |
+| `batch` | Edit multiple entries by Contentful entry ID, then save once |
+| `batch-run` | Execute a JSON script of operations (`batch run --json`) |
+| `fields` | Overview of all content types |
+| `fields-page` | All fields on a `page` entry |
+| `fields-article` | All fields on an `article` entry |
+| `fields-component` | All fields on a `component` entry |
+| `fields-collection` | All fields on a `collection` entry |
+| `fields-taxonomy` | All fields on `tagType`, `articleType`, and `tag` entries |
+| `index-sync` | Build and use the local content index (CDA sync) |
+| `asset-review` | Visual asset quality review (filename, alt, size, dimensions) |
+| `lookup` | Flat flags for `open`, `resolve`, and `nav open` |
+
+---
+
+## Quick-Start One-Liners
+
+```bash
+# See what pages exist (catalog index; auto-syncs if needed)
+cms-edit list --type page
+
+# Open a page and inspect it
+cms-edit open --page-slug /about
+cms-edit snapshot
+
+# Edit a field
+cms-edit set @c1 heading "New heading"
+cms-edit save
+
+# Create a complete new page from a JSON definition
+cms-edit create from-json --json '{...}'
+
+# Validate a JSON file without writing anything
+cms-edit create from-json --json '{...}' --dry-run
+
+# Bootstrap taxonomy for import scripts
+cms-edit create taxonomy-from-json --json '{...}' --if-not-exists
+
+# Import authors from JSON
+cms-edit create person-from-json --json '{...}' --if-not-exists
+
+# Bulk retag articles
+cms-edit article-tags-from-json --json '{...}'
+
+# Sitewide rich-text find-replace (dry-run first)
+cms-edit bulk-rtf-replace --find "Old" --replace-plain "New" --dry-run
+
+# Run a batch of edits
+cms-edit batch run --json '[...]'
+```
+
+---
+
+## Commands by Category
+
+### Navigation & Discovery
+
+**Content discovery** uses the local catalog index (`index sync`) and `list --type <type>`. Catalog types: `page`, `article`, `pageVariant`, `template`, `articleType`, `tagType`, `tag`, `navigation`, `navigationItem`. Other types (e.g. `person`, `customType`, `pageTest`): `list --type <type> --force-cma`.
+
+| Command | Description |
+|---|---|
+| `open --page-slug <slug>` | Load a page into the session (see `help lookup`) |
+| `open --resume` | Re-print active session; **keeps** staged edits (no refetch) |
+| `open --overwrite …` | Replace session even if dirty (discards staged field edits) |
+| `set <ref\|id> <field> <value>` | Set field; bare entry IDs allowed mid-session |
+| `set <id>:field=value …` | Scalar multi-set by entry ID (stays on current session) |
+| `open --id <id>` | Load by Contentful entry ID |
+| `peek --page-slug <slug>` | Print content tree + root field values without creating a session |
+| `peek --id <id>` | Same by Contentful entry ID |
+| `snapshot` | Re-print the current session's content tree with @refs |
+| `read [@ref] [field]` | Read fields from the active session (@refs from snapshot) |
+| `read <id> --id [field]` | Read entry fields by ID without an open session |
+| `list --type <ct>` | List catalog entries (page, article, pageVariant, template, taxonomy, nav, …) |
+| `search <query>` | Full-text search across entries |
+| `resolve <id>` | Resolve a Contentful entry or asset ID |
+| `resolve --page-slug <slug>` | Resolve an entry by flat lookup flag (no session); see `help lookup` |
+| `create tag-type\|tag\|article-type … --if-not-exists` | Idempotent taxonomy create (returns existing entry if slug matches) |
+| `schema types <content-type>` | List valid type-discriminator values |
+| `schema colours` | List valid backgroundColour / textColour values |
+| `schema <content-type>` | Display field definitions for a content type |
+| `health` | Check Contentful API connectivity |
+
+### Editing
+| Command | Description |
+|---|---|
+| `set <ref> <field> <value>` | Set a scalar, link, or array field |
+| `rtf <ref> <field> <markdown>` | Set a rich text field from markdown |
+| `add <type> <contentType>` | Create and link a new child entry |
+| `remove <ref>` | Unlink an entry from its parent |
+| `move <ref> <position>` | Reorder an entry in its parent array |
+| `links <subcommand>` | Manage CTA link entries |
+| `nav <subcommand>` | Manage navigation entries |
+| `asset <subcommand>` | Work with assets |
+
+### Session Management
+| Command | Description |
+|---|---|
+| `diff` | Show unsaved changes |
+| `save` | Write changes to Contentful as drafts |
+| `discard` | Discard unsaved changes |
+
+### Content Creation
+| Command | Description |
+|---|---|
+| `create from-json` | Create a page/article from a JSON file |
+| `create taxonomy-from-json` | Batch-create tagType, articleType, and tag entries |
+| `create person-from-json` | Batch-create person entries from JSON |
+| `create person` | Create a person entry (draft) |
+| `article-tags-from-json` | Set tags on articles from JSON |
+| `bulk-rtf-replace` | Find-replace in Rich Text across entry trees |
+| `create tag-type` | Create a tagType entry (draft) |
+| `create article-type` | Create an articleType entry (draft) |
+| `create tag` | Create a tag entry (draft) |
+| `create page` | Create a blank page interactively |
+| `create article` | Create a blank article interactively |
+
+### Batch Operations
+| Command | Description |
+|---|---|
+| `batch set <entryId>:field=value …` | Queue scalar updates by ID (page session OK mid-edit; then `save`) |
+| `batch diff` / `batch save` / `batch discard` | Review and commit batch session |
+| `batch run --json <json> or --json-base64 <encoded>` | Execute a JSON batch of operations |
+
+### Utilities
+| Command | Description |
+|---|---|
+| `asset review` | Audit visual assets (filename, alt, size, dimensions) |
+| `preview url` | Generate a page preview URL |
+| `preview showcase` | Generate a component/collection showcase URL |
+| `preview` | Generate preview URLs |
+
+Agent skills: `npx skills add @se-studio/skills`
+
+---
+
+## Global Options
+
+| Option | Description |
+|---|---|
+| `--space <name>` | Override the default space from config |
+| `--config <path>` | Path to `.contentful-cms.json` |
+| `--session <name>` | Named session for concurrent workflows |
+| `--json` | Machine-readable JSON output |
+| `--docs` | Print path to the full README |
+
+---
+
+## Further Reading
+
+- `cms-edit guide overview` — hosted/MCP getting started
+- `cms-edit help workflow` — step-by-step editing guide
+- `cms-edit help create-from-json` — single-shot page creation
+- `cms-edit help taxonomy-from-json` — batch taxonomy bootstrap
+- `cms-edit help fields-taxonomy` — tagType, articleType, and tag field reference
+- `cms-edit help batch-run` — JSON operation scripts and variable binding
+- `cms-edit help fields-page` — complete page field reference
+- `cms-edit --docs` — full README path (for reading in an editor)

package/docs/help/lookup.md

@@ -0,0 +1,132 @@
+# Flat lookup flags (`open`, `resolve`, `nav open`)
+
+cms-edit resolves entries using **explicit flags** — not positional slugs. Provide **exactly one** primary lookup flag per command. Scope flags (for example `--tag-type-name` with `--tag-name`) do not count as a second primary.
+
+Run `cms-edit index sync` once per space (or let commands auto-sync) so catalog types resolve from the local index.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `cms-edit open` | Start an editing session |
+| `cms-edit peek` | Preview tree + root fields without a session |
+| `cms-edit resolve` | Print entry summary or `--json` (no session) |
+| `cms-edit nav open` | Open a `navigation` entry session |
+
+## Entry ID
+
+```bash
+cms-edit open --id 4xKj2abcDefGhijK
+cms-edit resolve --id 4xKj2abcDefGhijK
+```
+
+## Pages
+
+| Flag | Contentful field |
+|------|------------------|
+| `--page-slug` | `slug` (leading/trailing `/` stripped) |
+| `--page-title` | `title` |
+| `--page-cms-label` | `cmsLabel` |
+
+**Homepage (SE Studio standard):** Contentful slug is `index`; public URL is `/`. These are equivalent:
+
+```bash
+cms-edit open --page-slug /
+cms-edit open --page-slug /index
+```
+
+`list --type page` shows slugs as stored in Contentful. Non-standard homepage slugs (e.g. Pedestal `home`) are documented in the editor-pack `routing` resource; open with `--page-slug /` or the CMS slug from routing.
+
+```bash
+cms-edit open --page-slug /pricing/
+cms-edit peek --page-slug /pricing/
+cms-edit open --page-cms-label "Hepatology Solutions Page"
+cms-edit resolve --page-title "Test page for nick"
+```
+
+## Articles
+
+| Flag | Contentful field |
+|------|------------------|
+| `--article-slug` | `slug` |
+| `--article-title` | `title` |
+| `--article-cms-label` | `cmsLabel` |
+
+```bash
+cms-edit open --article-slug resources/publications/my-post
+cms-edit list --type article --article-type-name "Publications"
+```
+
+## Page variants
+
+| Flag | Contentful field |
+|------|------------------|
+| `--page-variant-slug` | `slug` |
+| `--page-variant-title` | `title` |
+| `--page-variant-cms-label` | `cmsLabel` |
+
+## Taxonomy
+
+| Type | Slug | Name | cmsLabel |
+|------|------|------|----------|
+| tag | `--tag-slug` | `--tag-name` | `--tag-cms-label` |
+| tagType | `--tag-type-slug` | `--tag-type-name` | — |
+| articleType | `--article-type-slug` | `--article-type-name` | — |
+
+Scope tags under a tag type (optional):
+
+```bash
+cms-edit resolve --tag-name "Hepatology" --tag-type-name "Therapeutic Area"
+cms-edit list --type tag --tag-type-slug therapeutic-area
+```
+
+Templates use **cmsLabel** only:
+
+```bash
+cms-edit open --template-label "Default page template"
+cms-edit resolve --label "Default page template"   # alias for --template-label
+```
+
+## Navigation
+
+Navigation entries use the **`name`** field (not slug).
+
+| Flag | Resolves |
+|------|----------|
+| `--nav-id` | `navigation` entry ID |
+| `--nav-name` | `navigation.fields.name` |
+| `--nav-item-id` | `navigationItem` entry ID |
+| `--nav-item-title` | `navigationItem.fields.title` |
+
+When multiple nav items share a title, add **`--nav-id`** to scope:
+
+```bash
+cms-edit nav open --nav-name "Main header"
+cms-edit resolve --nav-item-title "Contact" --nav-id <navigation-entry-id>
+```
+
+## List filters (index)
+
+```bash
+cms-edit list --type page
+cms-edit list --type article --article-type-slug resources/publications
+cms-edit list --type tag --tag-type-name "Therapeutic Area"
+cms-edit list --type navigation
+cms-edit list --type navigationItem
+```
+
+Use `--force-cma` to paginate via the Management API instead of the catalog.
+
+## Breaking changes (1.x → catalog flags)
+
+| Old | New |
+|-----|-----|
+| `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` |
+
+## Ambiguity
+
+If two entries share the same slug, title, or cmsLabel in the index, cms-edit prints all matching IDs and exits with an error. Fix duplicates in Contentful or resolve by `--id`.

package/docs/help/person-from-json.md

@@ -0,0 +1,82 @@
+# cms-edit create person-from-json — Batch Author Import
+
+`create person-from-json` creates multiple `person` entries from a single JSON file. Use it for spreadsheet-to-CMS author imports and team directory bootstraps.
+
+```bash
+cms-edit create person-from-json --json '{...}' --dry-run
+cms-edit create person-from-json --json '{...}' --if-not-exists
+```
+
+All entries are created as **drafts**. Nothing is published automatically.
+
+**Not transactional:** If the command fails partway through, entries created earlier remain in the space. Re-run with `--if-not-exists` to continue idempotently.
+
+---
+
+## JSON schema
+
+```jsonc
+{
+  "persons": [
+    {
+      "slug": "jane-smith",
+      "name": "Jane Smith",
+      "jobTitle": "Chief Medical Officer",
+      "description": "Short card blurb",
+      "emailAddress": "jane@example.com",
+      "phoneNumber": "+1 555 0100",
+      "bioMarkdown": "## Bio\n\nMarkdown converted to Rich Text.",
+      "fields": {
+        "location": "Boston"
+      }
+    }
+  ]
+}
+```
+
+| Key | Required | Description |
+|---|---|---|
+| `slug` | Yes | URL slug |
+| `name` | Yes | Display name |
+| `cmsLabel` | No | CMS label (defaults to `name`) |
+| `jobTitle` | No | Job title (CLI flags override JSON `fields` on single-entry create) |
+| `description` | No | Short description |
+| `emailAddress` | No | Email |
+| `phoneNumber` | No | Phone |
+| `bioMarkdown` | No | Bio as Markdown (converted to Rich Text `bio` field) |
+| `fields` | No | Additional Contentful field values |
+
+You can also pass a full Rich Text document on `bio` inside `fields` instead of `bioMarkdown`.
+
+---
+
+## Single-entry alternative
+
+```bash
+cms-edit create person --slug jane-smith --name "Jane Smith" --job-title "CMO" --bio-file bio.md
+cms-edit create person --slug jane-smith --name "Jane Smith" --if-not-exists
+```
+
+---
+
+## Link authors to articles
+
+After import, link person IDs to articles in a session:
+
+```bash
+cms-edit open --article-slug blog/my-post
+cms-edit set @p0 authors <personId1>,<personId2> --links
+cms-edit diff && cms-edit save
+```
+
+Or batch-link in a `cms-edit batch run` ops file.
+
+---
+
+## Related commands
+
+| Command | Purpose |
+|---|---|
+| `cms-edit create person` | Create one person |
+| `cms-edit create person … --if-not-exists` | Idempotent single create |
+| `cms-edit help fields` | Field overview |

package/docs/help/taxonomy-from-json.md

@@ -0,0 +1,115 @@
+# cms-edit create taxonomy-from-json — Batch Taxonomy Bootstrap
+
+`create taxonomy-from-json` creates multiple `tagType`, `articleType`, and `tag` entries from a single JSON file. It is the recommended way to bootstrap taxonomy for import scripts and publication workflows.
+
+```bash
+cms-edit create taxonomy-from-json --json '{...}' --dry-run
+cms-edit create taxonomy-from-json --json '{...}' --if-not-exists
+```
+
+Processing order: **tagTypes → articleTypes → tags** (tags depend on tagTypes).
+
+All entries are created as **drafts**. Nothing is published automatically.
+
+**Not transactional:** If the command fails partway through (e.g. a tag fails validation), entries created earlier in the same run remain in the space. Re-run with `--if-not-exists` to continue idempotently, or fix the JSON and run again.
+
+**Not parallel-safe:** `--if-not-exists` is check-then-create. Running two imports concurrently for the same slug can create duplicates. Process items sequentially per slug, or re-run to converge.
+
+---
+
+## JSON schema
+
+```jsonc
+{
+  "tagTypes": [
+    {
+      "slug": "presentation-type",
+      "name": "Presentation Type",
+      "fields": { "show": true }
+    }
+  ],
+  "articleTypes": [
+    {
+      "slug": "resources/publications",
+      "name": "Publications",
+      "cmsLabel": "Publications",
+      "fields": { "indexed": true, "hidden": false }
+    }
+  ],
+  "tags": [
+    {
+      "slug": "asco-2025",
+      "name": "ASCO 2025",
+      "tagTypeSlug": "conference-venue",
+      "fields": { "description": "ASCO Annual Meeting 2025" }
+    }
+  ]
+}
+```
+
+Each item supports the same field shorthands as single-entry creates. See `cms-edit help fields-taxonomy` for the full field reference and link shorthand table.
+
+| Key | Required on item | Description |
+|---|---|---|
+| `slug` | Yes | URL slug |
+| `name` | Yes | Display name |
+| `cmsLabel` | No | CMS label (articleType/tag) |
+| `fields` | No | Raw Contentful field values |
+| `tagTypeSlug` / `tagTypeId` | Tags only | Parent tagType link |
+
+Top-level link shorthands (`templateId`, `featuredImageId`, `topContentIds`, etc.) can also appear on each item.
+
+---
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--json <json> or --json-base64 <encoded>` | Path to taxonomy JSON (required) |
+| `--if-not-exists` | Skip creation when slug already exists; return existing ID |
+| `--dry-run` | Validate all entries and link targets without writing |
+
+---
+
+## Output
+
+Human mode prints a summary per entry. JSON mode (`CMS_EDIT_JSON=1` or `--json-output`):
+
+```json
+{
+  "ok": true,
+  "tagTypes": [{ "id": "...", "slug": "...", "contentType": "tagType", "status": "created" }],
+  "articleTypes": [{ "id": "...", "slug": "...", "contentType": "articleType", "status": "existing" }],
+  "tags": [{ "id": "...", "slug": "...", "contentType": "tag", "status": "created" }]
+}
+```
+
+---
+
+## Idempotent import pattern
+
+Combine batch bootstrap with `create … --if-not-exists` and `resolve` for script-friendly imports:
+
+```bash
+# One-time taxonomy bootstrap
+cms-edit create taxonomy-from-json --json '{...}' --if-not-exists
+
+# Look up IDs in scripts
+cms-edit resolve --tag-type-slug presentation-type --json
+cms-edit resolve --tag-slug asco-2025 --json
+
+# Add a single entry idempotently
+cms-edit create tag --slug new-tag --name "New Tag" --tag-type presentation-type --if-not-exists
+```
+
+---
+
+## Related commands
+
+| Command | Purpose |
+|---|---|
+| `cms-edit create tag-type` | Create one tagType |
+| `cms-edit create article-type` | Create one articleType |
+| `cms-edit create tag` | Create one tag |
+| `cms-edit create … --if-not-exists` | Idempotent single-entry create |
+| `cms-edit help fields-taxonomy` | Full field reference |