CSV Data Model

SCS stores operational state in several linked CSVs. Every stage row carries the shared keys so it can be read alone or joined on pid.

For every field, owner, and gate, see Field Reference.

Shared keys

Column	Role
pid	Primary key: <PREFIX>-<NNNN>
site_id	Foreign key to config/sites.csv
title	Working title
keyword	Primary target query
created, updated	ISO dates

pid scheme

pid = <PREFIX>-<NNNN>

Prefixes are unique per site. Numbers are never reused; the high-water mark is in config/pids.reserved.

The CSVs

config/sites.csv

The site registry and WordPress connection:

Field	Description
site_id	Site registry ID; foreign key on every row
prefix	2–4 uppercase PID prefix
domain	Site hostname
name	Display name
status	active, development, or inactive
focus	Short content focus
nw_project	NeuronWriter project
wp_root	WordPress root on the server
wp_url	Site URL
wp_user	System user for WP-CLI
ssh_host	SSH alias
notes	Free text
created	ISO date (auto)

<workspace>-keywords.csv

The master row. Demand metrics, intent/business/SERP evidence, the human decision, GOS, gos_tier, and lifecycle status. See Field Reference for every keyword field.

<workspace>-clusters.csv

The portfolio plan:

Field	Description
kc_type	Cluster role: Topic, Pillar Page, Keyword Cluster, Sub Topic, Supporting
topic	SEO subject area
pillar_pid, parent_pid	Cluster relationships
funnel	TOFU / MOFU / BOFU
coverage_status	planned / in_progress / covered / gap / not_needed
coverage_goal	Whole-number target
coverage_notes	Scope and gaps
entity_coverage	Pipe-separated entities
cluster_priority	P0–P3
comp_gap	Competitor gap notes
notes	Free text

All stage rows also carry the shared keys.

<workspace>-briefs.csv

The production spec index:

Field	Description
brief_status	Draft / Review / Approved / Rejected
brief_depth	full / standard / light
framework	One of the seowriting frameworks
content_type	Editorial format
word_count, tone, author_role	Optional editorial guidance
audience	Who the page is for
hook_angle	Opening promise
angle_type	fresher data / first-hand experience / niche audience / contrarian / superior depth / better format
differentiation	One-sentence angle
information_gain	Original element
cta, kpi, target	Conversion and success metric
model, prompt_instructions	Generation notes
reviewer, due_date	Review owner and deadline
nw_brief_path	Optional raw NeuronWriter export path
brief_path, article_path	Same file (brief + article)
notes	Free text

The rich brief lives in the same md/<pid>--*.md file as the article; brief_path and article_path point to that file.

<workspace>-links.csv

The internal-link plan:

Field	Description
from_pid, to_pid	Source and target pages
anchor_text	Required anchor
link_type	hub / pillar / cluster / supporting / cross-cluster
placement	intro / body / faq / conclusion / sidebar
status	planned / added / verified / broken
verified_date	ISO date
notes	Free text

<workspace>-publishing.csv

WordPress state:

Field	Description
wp_category, wp_tag, wp_authority_topic	WordPress taxonomy
wp_content_format	Article format taxonomy (content_format)
wp_status	Draft / Pending / Scheduled / Published
wp_link	WordPress edit URL
publish_date	ISO date
wp_post_id, wp_author_id	WordPress IDs
slug	Post slug
meta_title, meta_description	SEO metadata
schema_type, schema_file	JSON-LD type/file
featured_image	Featured image reference
qa_status, qa_reviewer, qa_date, qa_scope, qa_notes	QA gate snapshot
index_status	Indexing state
notes	Free text

<workspace>-performance.csv

Query-level GSC history:

Field	Description
period	Reporting period
query	Search query
url	Page URL
pulled	Pull date
gsc_clicks, gsc_impressions, gsc_ctr, gsc_position	GSC metrics
notes	Free text

Store query rows only; derive page totals.

Relationships

• keywords.csv is the master.
• clusters, briefs, and publishing are effectively 1:1.
• links is many-to-many through PIDs.
• performance is 1:N by period and query.

v0.2 additions

Area	Change
Decision	decision, decision_reason, decision_factors, decided_by, decided_on
GOS	priority renamed gos_tier; GOS is supporting only
Research	per-PID folder, no new CSV
Brief	Markdown brief + depth/framework/audience/differentiation/information-gain fields, in the article file
Links	new links.csv
QA	WordPress ACF review; snapshot in publishing.csv
Publishing	wp_post_id, wp_author_id, slug, metadata, wp_content_format
Performance	url, pulled

Conventions

• Dates: ISO YYYY-MM-DD.
• Lists: pipe-separated (Images|PAA).
• Enums: lowercase snake_case.
• Empty means unknown; never invent a value.
• CSV is authoritative for metadata; Markdown body is authoritative for prose.

warning

content_type in the WordPress ACF group means hub/pillar/cluster/supporting. The article format taxonomy is content_format. Do not conflate them.