← All playbooks · Raw API

articles

# Articles — Headwater Science


## Source packages (briefs, Drive, assets)

Before creating from an external brief or asset pack:

1. Follow **`task-source-readiness-review`** (inventory → beat sheet → GO / GO-WITH-GAPS / NO-GO → light human yes).
2. Map structure **faithfully** to this site's components — **do not rewrite source copy**.
3. Do not invent pair layouts or section titles absent from the source.
4. Prefer source order; use labeled placeholders when the verdict is GO-WITH-GAPS.

Routing and shared rules for **news** and **publications**. Use specialized playbooks for workflows:

| Article family | Playbook |
|----------------|----------|
| Press / news items | `cms-edit://customer/news-pages` |
| News portrait + OG images | `cms-edit://customer/news-images` |
| Publications, posters, manuscripts | `cms-edit://customer/publications-pages` |

Headwater shares article routing patterns with Pedestal Health (`@pedestal/site-common`).

## Article types

| Article type slug | Use for |
|-------------------|---------|
| `resources/news` | Press releases, news, conference coverage |
| `resources/publications` | Publications, posters, manuscripts |

```bash
cms-edit list --type articleType
cms-edit index sync
```

## URL shape

Primary tag in path (`enablePrimaryTagPartOfSlug` is on):

```
/resources/{articleTypeSlug}/{primaryTopic}/{slug}/
```

Example: `/resources/news/press-release/my-release-headline/`

## Primary tag rules

| Article type | Primary tag from tag type |
|--------------|---------------------------|
| `resources/news` | `asset-type` |
| `resources/publications` | `presentation-type` |

Common news `asset-type` slugs: `press-release`, `partnership-announcement`, `publication-highlight`, `conference-presentation`, `leadership-corporate`.

## Site defaults (Headwater)

| Field | Default |
|-------|---------|
| `featuredImage` (landscape OG) | `1AnckDjqLhoUCca15RKh52` (`project.json` + `defaults`) |
| `visuals` (news hero + card) | `7Gjr8l44cfJBVaVUqlNRkm` (rebrand press-release media) |

**Always set both** on news articles — do not omit expecting inheritance.

## Shared article fields

| Field | Notes |
|-------|-------|
| `articleType` | Required |
| `authors` | Ordered Person links — prefer over legacy `author` |
| `subtitle` | News hero display line |
| `content` | Body components only — see specialized playbooks |

## Hosted MCP

Connector: `https://headwater.content.se.studio/api/mcp`

## Full reference

- `apps/headwater-website/docs/cms-guide.md` § News and press releases
- Pedestal `apps/pedestal-website/src/project/ARTICLE_PATTERNS.md` for shared display-field rules

## Publish handoff

`save` creates drafts only — publish in Contentful UI when ready.