Front Matter

Every generated article carries YAML front matter. It is the writer-facing view of the CSV metadata and the input for publishing checks.

Structure

---
# Public fields consumed by the site
title: "What Is a Balance Sheet? A Beginner's Guide"
description: null
category: "Investing"
tags:
  - "balance sheet"
  - "financial statements"
content_type: "reference"
status: "Draft"
date: null
slug: null

# Writer context
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"
---

Field ownership

Field	Source	Notes
title	keywords.title	Article title
description	publishing.meta_description	SEOPress description
category	publishing.wp_category	WordPress category
tags	publishing.wp_tag	YAML list
content_type	publishing.wp_content_format	Article format, not ACF
status	publishing.wp_status	Draft / Pending / Scheduled / Published
date	publishing.publish_date	ISO date or null
slug	publishing.slug	Post slug
scs.identity.pid	keywords.pid	Stable content ID
scs.writing.*	keywords + briefs + clusters	Writer context
scs.links.internal	links.csv	to_pid, anchor, placement
scs.editorial.*	briefs	Reviewer, due date, disclosure
scs.research.*	workspace + research/<pid>/	Research folder and status

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.

Brief and article markers

The brief and the article share one file. Two HTML comments separate them:

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

Rules:

1. scs brief --check validates only the brief half.
2. scs publish sends only the article half.
3. scs sync regenerates the front matter and preserves the body.
4. Files without markers are treated as legacy: the whole body is used for both.
5. Keep the brief half intact after approval; it is the audit trail.

First creation requirements

scs brief --workspace bs --pid FS-0001 creates the first Markdown file and front matter. The minimum required data is:

• an existing workspace (data/<workspace>/)
• a keywords.csv row for that PID with at least pid, title (falls back to keyword, then the PID), site_id, and keyword

Missing briefs.csv, clusters.csv, publishing.csv, or links.csv rows are tolerated and render as empty/null fields. Matching rows enrich the front matter: clusters.csv drives brief_depth and writer fields, publishing.csv supplies public CMS fields, and links.csv supplies internal links. The research path is auto-constructed as data/<workspace>/research/<PID>/.

Approval requires more: decision=go, a cluster row, research evidence, and a filled brief body that passes scs brief --check.

Regeneration

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

• CSV is authoritative for metadata.
• The Markdown body is authoritative for prose.
• Never hand-edit generated fields unless repairing data; change the CSV and re-render.