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

package/docs/help/workflow.md

@@ -0,0 +1,239 @@
+# cms-edit — Standard Editing Workflow
+
+The standard workflow is: **open → snapshot → read/edit → diff → save**.
+
+---
+
+## Step 1: Discover What Exists
+
+```bash
+# List all pages with slugs
+cms-edit list --type page
+
+# Search for entries by text
+cms-edit search "hepatology"
+```
+
+---
+
+## Step 2: Open a Page or Article
+
+```bash
+cms-edit open --page-slug /solutions/hepatology
+# or by entry ID:
+cms-edit open --id 4xKpzQ2abc123
+# include template menu/footer/nav (off by default):
+cms-edit open --include-chrome --page-slug /solutions/hepatology
+```
+
+`open` fetches the page/article tree (and the template entry) and saves it to a local session file. It does **not** walk template menu/footer/navigation unless you pass `--include-chrome`. All subsequent commands operate on this session without re-fetching from Contentful until you `save`.
+
+### Critical: do not re-open while edits are staged
+
+`set` / `rtf` / parent links from `add` stay in the session until `save`. Calling `open` again **replaces** the session.
+
+| Situation | Command |
+|-----------|---------|
+| Session has unsaved changes, need tree again | `cms-edit open --resume` (no refetch; keeps staged edits) |
+| Intentionally abandon staged work and load another entry | `cms-edit open --overwrite --id <id>` (or `discard` then `open`) |
+| Plain `open` while dirty | **Hard fail** with remediation steps |
+
+```bash
+cms-edit open --resume
+cms-edit diff
+cms-edit save
+# or abandon:
+cms-edit discard
+cms-edit open --id <other>
+```
+
+**Output:**
+```
+✓ Opened /solutions/hepatology (12 entries)
+
+@c0   page              [draft]    solutions/hepatology
+  @c1   component         [draft]    Image Hero
+  @c2   component         [draft]    Text Block
+  @c3   collection        [draft]    Timeline
+    @c4   component         [draft]    Timeline Item 1
+    @c5   component         [draft]    Timeline Item 2
+  @c6   component         [draft]    Disease Areas
+```
+
+---
+
+## Step 3: Inspect the Content Tree
+
+```bash
+# Re-print the tree at any time
+cms-edit snapshot
+
+# Read all fields on an entry
+cms-edit read @c2
+
+# Read a specific field
+cms-edit read @c2 heading
+```
+
+**Example `read @c2` output:**
+```
+@c2  component  [draft]  Text Block
+  heading:      "Our Approach"
+  body:         (rich text, 2 paragraphs)
+  backgroundColour: null
+```
+
+---
+
+## Step 4: Edit Fields
+
+### Scalar fields (text, boolean, number)
+```bash
+cms-edit set @c2 heading "New Heading"
+cms-edit set @c2 backgroundColour "Navy"
+```
+
+### Mid-session by Contentful entry ID (e.g. media autoplay)
+
+You do **not** need to leave the page session:
+
+```bash
+# Bare entry ID (fetched into the session if not in the tree)
+cms-edit set 5uMh54rIsJRFRQSXDuJiG autoplay true
+
+# Same shape as batch set — stays on the current page session
+cms-edit set 5uMh54rIsJRFRQSXDuJiG:autoplay=true 5uMh54rIsJRFRQSXDuJiG:loop=true
+# or: cms-edit batch set … (also allowed mid-page; then cms-edit save)
+```
+
+### Entry links: `--link` vs `--links` (strict)
+
+| Field shape | Flag | Notes |
+|-------------|------|--------|
+| Single Entry link | `--link` | Exactly one id |
+| Array of Entry links | `--links` | Full replace of the array |
+| Append to array | `--links --append` | Add ids |
+| Wrong flag | hard error | Never silently coerces |
+
+```bash
+cms-edit set @c1 visual <mediaEntryId> --link
+cms-edit set @c2 contents <id1>,<id2> --links
+# To change one array item: read the array, edit the list, write all ids back with --links
+```
+
+### Rich text fields
+```bash
+# Inline markdown (short content)
+cms-edit rtf @c2 body "## Overview\n\nFirst paragraph.\n\nSecond paragraph."
+
+# From a file (long content)
+cms-edit rtf @c2 body --content "# ..."
+```
+
+### Multi-value: replacing inline content
+```bash
+# Replace a specific text phrase in a rich text field
+cms-edit rtf replace @c2 body --find "old phrase" --replace-plain "new phrase"
+```
+
+### Links (CTAs)
+```bash
+# Add a new external CTA link
+cms-edit links add @c2 --type external --label "Learn More" --href "https://example.com"
+
+# Add an internal link (to another page by slug)
+cms-edit links add @c2 --type internal --label "Our Team" --slug /team
+```
+
+### Adding new entries
+```bash
+# Add a new component to the page's content array
+cms-edit add HeroSimple component
+
+# Add a child item to a collection
+cms-edit add Generic component --parent @c3
+
+# Add after a specific entry
+cms-edit add Generic component --after @c5
+```
+
+**Important:** After any `add` or `remove`, re-run `cms-edit snapshot` — @ref numbers change after structural edits.
+
+---
+
+## Step 5: Review Changes
+
+```bash
+cms-edit diff
+```
+
+Shows a summary of which entries have been modified and which fields changed.
+
+---
+
+## Step 6: Save
+
+```bash
+cms-edit save
+```
+
+Writes all changes to Contentful as **drafts**. Nothing is published. A human must review and publish in the Contentful web app.
+
+---
+
+## Common Patterns
+
+### Edit a specific component's heading and body
+```bash
+cms-edit open --page-slug /about
+cms-edit snapshot
+cms-edit set @c3 heading "Updated heading"
+cms-edit rtf @c3 body "New body text\n\nSecond paragraph."
+cms-edit diff
+cms-edit save
+```
+
+### Add a new section to an existing page
+```bash
+cms-edit open --page-slug /home
+cms-edit snapshot
+# Add a new Text Block after @c2
+cms-edit add TextBlock component --after @c2
+cms-edit snapshot   # re-snapshot to see the new ref
+cms-edit set @c3 heading "New Section"
+cms-edit rtf @c3 body "Section content.\n\nMore detail."
+cms-edit save
+```
+
+### Fix a field on multiple pages
+Use `--session` to work on multiple pages without losing state:
+```bash
+cms-edit --session fix-1 open --page-slug /page-one
+cms-edit --session fix-1 set @c1 heading "Fixed"
+cms-edit --session fix-1 save
+
+cms-edit --session fix-2 open --page-slug /page-two
+cms-edit --session fix-2 set @c1 heading "Fixed"
+cms-edit --session fix-2 save
+```
+
+---
+
+## Creating New Pages
+
+For creating complete new pages with components, use `create from-json` instead of the interactive `add` workflow:
+
+```bash
+cms-edit help create-from-json
+```
+
+---
+
+## Status Badges
+
+| Badge | Meaning |
+|---|---|
+| `[published]` | Entry is live in Contentful (no draft changes) |
+| `[draft]` | Entry has unpublished changes or has never been published |
+| `[changed]` | Entry has been modified in this session (unsaved) |
+| `[pending]` | Entry is scheduled for deletion in this session |

package/docs/mcp/e2e-test-prompt.md

@@ -0,0 +1,159 @@
+# Hosted MCP end-to-end test prompts
+
+How to create and run **copy-paste QA prompts** for cms-edit hosted MCP (Claude Desktop Integrations + OAuth).
+
+**Example instance:** [Brightline `MCP-E2E-TEST.md`](https://github.com/Brightline-Marketing/brightline-sites/blob/develop/docs/cms-edit/MCP-E2E-TEST.md) in `brightline-sites/docs/cms-edit/`.
+
+---
+
+## When to run
+
+| Trigger | Action |
+|---------|--------|
+| Bumped `@se-studio/contentful-cms` in customer repo | Regen editor pack → push → run E2E prompt |
+| Regenerated `editor-pack/` | Push → run E2E prompt |
+| OAuth / Redis / session bugs reported | Run phases 0 + 4 + session tips in [hosted-guide.md](./hosted-guide.md) |
+| Major cms-edit CLI prune (e.g. 2.6.0) | Include **phase 9** negative tests for removed commands |
+
+---
+
+## Prerequisites
+
+1. Claude Desktop with the site's **custom connector** connected (Contentful OAuth complete).
+2. Editor has **AI Editor** role on the space.
+3. Hosted deployment healthy: `curl -s https://<host>/api/health | jq` — `config`, `redis`, `oauth` ok.
+4. Do **not** pass `--space` in `cms_edit` args on hosted MCP.
+
+---
+
+## Where to store site-specific prompts
+
+| Repo layout | Recommended path |
+|-------------|------------------|
+| Customer monorepo (Brightline, Pedestal, SE Studio) | `docs/cms-edit/MCP-E2E-TEST.md` |
+| Optional per-site in multi-site repo | `docs/cms-edit/<site>/MCP-E2E-TEST.md` |
+
+Link from:
+
+- Customer `cms-edit/README.md`
+- Customer `AGENTS.md` (under CMS editing section)
+- `docs/CMS_EDIT_SETUP.md` customer table (this monorepo)
+
+---
+
+## How to create a new site prompt
+
+### 1. Gather site facts
+
+Read the deployed editor pack (or regenerate locally):
+
+```bash
+cms-edit project doctor --project-config cms-edit/<site>/project.json
+```
+
+From `cms-edit://customer/routing` and `capabilities.json`, note:
+
+- Homepage CMS slug (`index` vs `home`)
+- Articles base path, tags enabled/disabled
+- Which tasks in `tasks-index` are enabled
+- Example page slug for peek/open (pick a stable page, not a campaign LP)
+- One real `componentType` for `preview showcase`
+
+### 2. Use the phase template
+
+Every E2E prompt should cover these phases (trim for smoke tests):
+
+| Phase | Purpose | Customize per site |
+|-------|---------|-------------------|
+| **0** Connector | version, health, guide, help | Expected version range |
+| **1** Customer resources | tasks-index, capabilities, routing, indexes | Confirm routing bullets |
+| **2** Discovery | index status, list, resolve, search | `index status` may show not built on a cold hosted instance before any sync; re-check after `list` or `open`. Article/tag types if enabled |
+| **3** Peek | Tree without session | Fallback slug if `/about` missing |
+| **4** Session | open → snapshot → read → diff | Homepage slug from routing |
+| **5** Schema | `schema colours`, `schema types`, `schema fields` | Any site-specific content types |
+| **6** Media | Read `task-media-review`; `asset review`, optional `--include-usage --usage-limit 5` | Skip if index empty; do not combine `--include-passing` + `--include-usage` without a limit on hosted MCP |
+| **7** Dry-run writes | set+discard, bulk-rtf dry-run, create from-json dry-run | Skip taxonomy if disabled |
+| **8** Preview | `preview url`, `preview showcase` | Real component type name |
+| **9** Negatives | Removed commands (sitemap, ensure, run, …) | Update when CLI changes |
+
+### 3. Safety rules (always include)
+
+```
+- Do NOT pass --space on hosted MCP.
+- Do NOT save or create without --dry-run.
+- If you set fields, run discard before finishing.
+- Report PASS / FAIL / SKIP per step.
+```
+
+### 4. Final report format
+
+Require a markdown results table and P0/P1/P2 fix list so runs are comparable across releases.
+
+### 5. Ship with the customer repo
+
+1. Add `docs/cms-edit/MCP-E2E-TEST.md` with site name, MCP URL, health URL, expected version.
+2. Link from `cms-edit/README.md` and `AGENTS.md`.
+3. Commit + push to deploy branch — **do not** `vercel deploy` manually (see `Agents.md`).
+
+---
+
+## Skeleton template
+
+Copy into a new customer doc and replace `{{…}}` placeholders:
+
+```markdown
+# Hosted MCP end-to-end test ({{SITE_NAME}})
+
+| MCP URL | {{MCP_URL}} |
+| Expected cms-edit | {{VERSION}} |
+| Deploy branch | {{BRANCH}} |
+
+## Prompt
+
+\`\`\`
+You are exercising the {{SITE_NAME}} cms-edit hosted MCP end-to-end.
+
+RULES
+- Do NOT pass --space …
+- Do NOT save …
+- discard after any set …
+
+PHASE 0 — …
+PHASE 1 — Confirm: homepage slug `{{HOMEPAGE_SLUG}}`, articles `{{ARTICLES_BASE}}`
+…
+PHASE 9 — Negatives: sitemap, ensure, run
+FINAL REPORT — table + P0/P1/P2
+\`\`\`
+```
+
+---
+
+## Shorter smoke variant
+
+Document a **5-minute** subset in the same file:
+
+- Phases **0, 1, 2, 4, 9** only — enough to catch connector, knowledge, discovery, session, and CLI regressions.
+
+---
+
+## Built-in MCP prompts (lighter alternative)
+
+For ad-hoc checks without the full E2E script:
+
+| Prompt | Covers |
+|--------|--------|
+| `cms_edit_verify` | version + health + customer resources load |
+| `cms_edit_explore` | list + open homepage + snapshot |
+
+The full E2E prompt is for **release QA** and **regression matrices** after CLI or editor-pack changes.
+
+---
+
+## Related docs
+
+| Doc | Purpose |
+|-----|---------|
+| [hosted-guide.md](./hosted-guide.md) | Editor + agent MCP reference |
+| [HOSTED.md](../../HOSTED.md) | Editor onboarding |
+| [../../docs/CMS_EDIT_SETUP.md](../../../../docs/CMS_EDIT_SETUP.md) | Customer deploy runbooks |
+| Skill `contentful-cms-regenerate-editor-pack` | Regen + push workflow |