# Articles — Brightline


## 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

Brightline blog articles live under the **learning hub**:

| Concept | Value |
|---------|-------|
| Public base | `/learning-hub/` |
| Blog article type slug | `blog` |
| Article URL | `https://www.brightline.com/learning-hub/blog/{slug}/` |
| Topics base | `/learning-hub/topics/` |
| Primary tag in URL | **No** — tags do not appear in article paths |

Read `cms-edit://customer/routing` for the live constants on this site.

## Article type vs tags

| Field | Contentful type | Brightline usage |
|-------|-----------------|------------------|
| `articleType` | `articleType` | Required. All blog posts use slug **`blog`**. |
| `tags` | `tag` (many) | Topic labels for filters, related content, and search. Managed via the **blog tag matrix** sheet — see `cms-edit://customer/blog-tag-matrix`. |

Do not confuse **article type** (always `blog` for the learning hub) with **tags** (ADHD, Anxiety, School, etc.).

## Common article components

See `cms-edit://customer/components-index`:

- **Article hero** — hero on article detail pages
- **Blog rich text** — main body (`Blog rich text`)
- **Articles filter** — topic/type filter chips on listing pages

## Listing and discovery

```bash
cms-edit list --type article --sort date -n 20
cms-edit list --type article --has-field tags
cms-edit list --type tag
cms-edit list --type articleType
```

Articles sort by publication `date`, not `sys.updatedAt`.

## Reading article fields

```bash
cms-edit open --article-slug understanding-your-childs-anxiety-key-questions-to-ask
cms-edit read @root
cms-edit read @root tags
```

Use `@root` for the article entry itself (not a content component).

## Setting tags on an article

Tags are an **array of entry links**. Resolve tag slugs to entry IDs first:

```bash
cms-edit list --type tag --json
```

Then open the article and replace the full `tags` array:

```bash
cms-edit open --id <article-entry-id>
cms-edit set @root tags <tagId1>,<tagId2>,<tagId3> --links
cms-edit diff
cms-edit save
```

Use comma-separated **entry IDs** (no spaces). An empty value clears all tags: `cms-edit set @root tags --links` with no IDs after `tags`.

## Blog tag matrix (spreadsheet workflow)

Marketing maintains topic tags in an xlsx spreadsheet via Claude. See:

- **`cms-edit://customer/task-export-blog-tag-matrix`** — export Contentful → `Brightline_Blog_Tag_Matrix.xlsx`
- **`cms-edit://customer/task-import-blog-tag-matrix`** — apply sheet tag changes to Contentful drafts
- **`cms-edit://customer/task-suggest-blog-tags`** — propose tags for untagged articles (no auto-save)
- **`cms-edit://customer/blog-tag-matrix`** — sheet layout, `Y` / blank rules, shared schema

## Publish handoff

`save` creates **drafts only** — cms-edit never publishes. After tag changes are saved, a reviewer publishes the article in the Contentful UI when ready.

## Featured images

Read `cms-edit://customer/defaults` for the decision tree (custom image → article type default → site default asset).