SCS — SEO Content System

SCS (SEO Content System) is the operational tooling layer for SEO content. It is a local-first, CSV-driven system — modelled on PlanWil — that keeps keyword research, topic clustering, content briefs, publishing, and performance tracking in one reusable place for all owned blog sites and future client sites.

info

Sections 01–12 of this documentation describe the method (SEO content strategy, keyword discovery, optimisation, generation, publishing, tracking). This section (13+) describes the system (SCS) that operationalises that method.

Goals

1. One system for every site — owned blogs, client sites, and projects. A new site is added by registering it, not by rebuilding the workflow.
2. Structured data in terminal — CSV files explored with VisiData, markdown written in Neovim (LazyVim), folders browsed with Yazi, stored on the VPS.
3. Front matter everywhere — every generated markdown file carries YAML front matter populated from its CSV row, so files are self-describing and portable. The brief and the article share one file under md/.
4. Automated opportunity scoring — Golden Opportunity Score (GOS) and its supporting gos_tier are computed by the system, not typed by hand. The human decision remains the selection gate.
5. Reusable keybindings — the VisiData zP (open the row's markdown) and gp (copy its path) bindings work for SCS rows exactly as they do for PlanWil.
6. Documented and versioned — every development step is recorded here and in the Changelog.

Relationship to PlanWil

SCS borrows PlanWil's proven shape and re-purposes it for SEO content:

Concept	PlanWil	SCS
Board/CSV	one CSV per project (data/<project>/<project>.csv)	six linked, workspace-prefixed CSVs in data/<workspace>/
Primary key	pid = <prefix>-<nn>	pid = <PREFIX>-<NNNN> (site prefix)
Generated markdown	md/<pid>--….md with YAML front matter	data/<workspace>/md/<pid>--….md with YAML front matter, populated from linked CSV rows
Generator	plan_sync.py (CSV → front matter markdown)	scs.py sync --workspace NAME (CSV → front matter markdown)
Editor/explorer	VisiData + Neovim + Yazi	VisiData + Neovim + Yazi
Keybindings	zP popup, gp copy path	zP popup, gp copy path (SCS-aware)
Scope	tasks/plans	keyword → publishing pipeline

The key difference: PlanWil has one CSV per board, while each SCS named workspace (created with scs NAME) has separate, name-prefixed CSVs for keywords, clusters, briefs, publishing, and performance. Those CSVs share pid, site_id, title, and keyword so they can be joined. The workspace name is independent of the registered target site; site_id preserves the site/PID-prefix relationship.

Scope

SCS is local-first and terminal-first. The working loop is:

1. Import keyword exports and score them with GOS as a supporting metric.
2. Research each PID in research/<pid>/ with manual SERP review and opencode.
3. Record a human decision (go / hold / no).
4. Plan the cluster and internal links.
5. Render and approve a Markdown brief in md/<pid>--<slug>.md.
6. Write the article after the <!-- scs:article --> marker.
7. Set the publishing state from the terminal; review the rendered post in WordPress.
8. Pull GSC performance and refresh or prune.

The bridge creates or updates drafts and reads status back. Pending, scheduled, and published transitions use the site's approved WordPress workflow. WordPress is the visual review surface. The QA gate reads the WordPress/ACF review fields; SCS does not duplicate the review checklist.

API automation is not part of SCS. Data enters as manual exports from the SEO tools you already use — see Data Sources and Tools.

Terminology

Term	Meaning
SCS	SEO Content System — this system.
Site	A target domain (owned or client) registered in sites.csv.
pid	Primary ID for a keyword/content row: <PREFIX>-<NNNN>.
Keyword row	The master unit of work, created in keywords.csv and referenced by pid from every other CSV.
GOS	Golden Opportunity Score — composite keyword opportunity score.
KC	Keyword Cluster role: Topic, Pillar Page, Keyword Cluster, Sub Topic, Supporting.
Stage CSV	One of the linked CSVs that represent a phase of the lifecycle.
Front matter contract	The rule that each generated markdown file's YAML front matter mirrors its CSV row.

Guiding principles

1. CSV is the source of truth. Markdown is a rendered, self-describing view.
2. Link by pid, duplicate the essentials. Every stage CSV carries pid, title, and keyword so a single file is usable on its own.
3. Files over databases. Plain CSV + markdown, Git-friendly, terminal-first.
4. Compute, don't type. Any column that can be derived (GOS, gos_tier, paths, dates) is computed by the system.
5. Human in the loop. The system proposes candidates and scores; the operator selects pillars/clusters/supporting content and approves briefs.
6. Add a site, not a system. Onboarding a new site is a registry row plus a prefix, not a new workflow.