# Capability: Create an article

## Intent phrases

- create a blog post
- new article
- add publication
- press release
- case study

## Requires capabilities

`articles`

## Prerequisites

- Read `cms-edit://customer/articles`, `defaults`, `routing`, `components-index`
- `cms_edit ["index", "sync"]`
- `cms_edit ["list", "--type", "articleType"]` — every article needs an article type
- **External package** (Drive, Figma, brief, zip, multi-file): complete **`task-source-readiness-review`** first, then treat the soft-proof as the composition plan
- Field-only creates (title/slug/type already decided, no external pack): readiness optional

## Steps

1. Resolve article type slug/name (`list --type articleType`)
2. Read site **`articles`** playbook for required fields, tags, lab rules, and which components belong in `content`
3. **Check template hierarchy** — inspect `articleType.articleTemplate` (`peek --id <template-id>`). Do not add hero/layout components to `content` when the template's `preContent` / `postContent` already provides them
4. **Composition follows the site playbook and the soft-proof** — prefer **source sequence**. Do not invent side-by-side / pair layouts unless the source is a true pair. Merge continuous prose into fewer body blocks when nothing visual sits between.
5. **Do not rewrite source copy** — structure and place only; flag issues for the human
6. Ask about custom images; apply `defaults` and playbook rules for `featuredImage` and `visuals` (set explicitly when the playbook requires both). Prefer reuse (`task-media-reuse-and-upload`); use labeled placeholders for missing soft-proof slots
7. Build `create from-json` payload (article fields + body components per playbook) **or** incremental `add` / `set` / `rtf` for multi-block work
8. `cms_edit ["create", "from-json", "--json", "<compact-json>", "--dry-run", "--strict"]`
9. On approval, create and `save`
10. `task-preview-verify` — include multi-block soft-proof QA when the article is multi-block

Or minimal shell (simple creates only):

```
cms_edit ["create", "article", "--slug", "<slug>", "--title", "<title>", "--article-type-slug", "<type>"]
```

## Before save

Confirm (site playbook may add more):

- [ ] `title`, `slug`, `date`, `articleType` correct
- [ ] `description` set and under ~160 characters when used for SEO meta (site playbook may require 120–160 and refuse thin text)
- [ ] `tags` / primary tag set when URL includes a topic segment
- [ ] `featuredImage` and `visuals` per playbook (`featuredImage` landscape for OG when used for social)
- [ ] `content` matches soft-proof order; only component types the playbook allows (no duplicate heroes from template)
- [ ] No invented pairs/headings; missing art still represented as placeholders when GO-WITH-GAPS
- [ ] Component `cmsLabel` values renamed from defaults ("New …")
- [ ] `indexed` / `hidden` per playbook (lab ports often `hidden: true`, `indexed: false`)
- [ ] `diff` reviewed, then `save`

## Confirmation gates

1. Source readiness + soft-proof when building from an external package
2. Confirm slug, title, article type, tags, and image choices with the user (light **yes** is enough)
3. `--dry-run --strict` before create when using from-json
4. `diff` before `save`

## Out of scope

- Publish
- Rewriting source copy
- Inventing layout not in the source / soft-proof

## Related resources

- `cms-edit://customer/articles`
- `cms-edit://customer/defaults`
- `task-source-readiness-review`
- `task-create-from-document`
- `task-preview-verify`
- `task-media-reuse-and-upload`
- `cms-edit help fields-article` — field reference and template hierarchy