Front Matter & Markers

One file, two halves

data/<workspace>/md/<pid>--<slug>.md

---
title: "Article title"
description: null
category: "Investing"
tags:
  - "balance sheet"
content_type: "reference"
status: "Draft"
date: null
slug: null

scs:
  schema: scs-content/v3
  identity:
    pid: "FS-9001"
    site_id: "fundamentalstock"
  writing:
    audience: "Beginner investors"
    intent: "Informational"
    primary_keyword: "what is a balance sheet"
    supporting_keywords: []
    angle: "Explain the statement as a snapshot"
    differentiation: "Explain it as a connected snapshot"
    target_words: 2200
    tone: "Educational"
    author_role: "Practitioner"
    entities_to_cover:
      - "assets"
      - "liabilities"
      - "equity"
    questions_to_answer: []
  links:
    internal: []
  editorial:
    reviewer: "Sample reviewer"
    review_due: "2026-10-30"
    disclosure: null
  research:
    path: "data/fundamentalstock/research/FS-9001/"
    status: "needs_review"
---

<!-- scs:brief -->
## 1. Decision
...

<!-- scs:article -->
# Article title

...

Markers

Marker	Meaning
<!-- scs:brief -->	Start of the brief half
<!-- scs:article -->	Start of the article half

• scs brief --check validates only the brief half.
• scs publish sends only the article half.
• Files without markers use the whole body for both (legacy behaviour).
• Keep the brief half after approval; it is the audit trail.

Public fields

Key	Source
title	keywords.title
description	publishing.meta_description
category	publishing.wp_category
tags	publishing.wp_tag
content_type	publishing.wp_content_format (article format)
status	publishing.wp_status
date	publishing.publish_date
slug	publishing.slug

SCS context

Key	Source
scs.identity.pid	keywords.pid
scs.identity.site_id	keywords.site_id
scs.writing.*	keywords + briefs + clusters
scs.links.internal	links.csv
scs.editorial.*	briefs
scs.research.*	workspace + research/<pid>/

warning

Front-matter content_type is the article format (reference, checklist, comparison, …). The WordPress ACF content_type (hub / pillar / cluster / supporting) comes from clusters.kc_type and is never read from front matter.

First creation

scs brief --ws bs --pid FS-0001 creates the first Markdown file and front matter. Minimum required data: an existing workspace plus a keywords.csv row with at least pid, title (or keyword), and site_id. Missing optional CSV rows render as empty/null fields.

Regeneration

scs brief --ws bs --pid FS-0001   # render front matter + seed the brief
scs sync --ws bs                  # refresh front matter, keep the body

CSV is authoritative for metadata; the Markdown body is authoritative for prose.