Troubleshooting
scs check failures
| Message | Cause | Fix |
|---|---|---|
research folder is missing README.md | Status is Researched or later | scs research --ws <name> --pid <pid> |
research/serp.md needs at least 3 competitor URLs | SERP evidence is thin | Add real reviewed URLs to serp.md |
brief section '…' is empty | Brief half incomplete | Fill sections 1–10; keep them above <!-- scs:article --> |
brief Markdown is missing | The file name no longer matches the title slug | SCS resolves the single md/<pid>--*.md; if there are several, remove duplicates or set article_path |
brief file not found | brief_path points at the old briefs/ layout | Re-run scs sync; brief_path now equals article_path |
status … requires decision=go | Decision not recorded | Set decision=go and the reason fields in keywords.csv |
status … requires qa_status=approved | Review gate not passed | scs qa pull, set the gate fields, scs qa check |
scs publish failures
| Message | Cause | Fix |
|---|---|---|
status must be Writing, Editing, QA, or Scheduled | Keyword row is too early | Advance the status after the brief is approved |
brief must be Approved | Brief gate not passed | scs brief --check then --approve |
article Markdown is missing | Path or title mismatch | scs sync, or check md/<pid>--*.md |
internal link target … has no wp_link | Linked page is not published | Publish the target first or fill wp_link |
WordPress post … is published | SCS refuses to downgrade a live post | Use the terminal transition rules; do not force a live post to draft |
tip
Run scs publish --dry-run first. It prints the payload and never calls
WordPress.
Markers and the single file
- Brief half: between
<!-- scs:brief -->and<!-- scs:article -->. - Article half: after
<!-- scs:article -->. - If the markers are missing, the whole body is used for both checks and publishing. Add the markers to adopt the current contract.
Keybindings do nothing
mkdir -p ~/.visidatarc.d/Keybindings
ln -sf ~/github/server-side-program/scs/integrations/visidata/scs_pid.py \
~/.visidatarc.d/Keybindings/46-scs-pid.py
scs aliases --ws <name>
Then restart VisiData. zP opens the PID's Markdown; gp copies its path.
Title changes and file names
md_path resolves, in order: the registered article_path, the single
md/<pid>--*.md, then the title slug. Changing a title does not rename an
existing file. If two files exist for one PID, delete the stale one.
Docs build fails locally
| Symptom | Cause | Fix |
|---|---|---|
Minimum Node.js version not met | Node 18 on PATH | nvm use 22 (build requires ≥ 20) |
EACCES … .docusaurus | Docker build wrote root-owned files | sudo chown -R $USER:$USER .docusaurus build |
| Broken link warnings | Page moved without a slug | Add slug: or a static/_redirects entry |