GITHUB-ISSUES-2026-03-22-readme-docs-audit.md — Build instructions for Harley

Context

Joker session: planning — README rewrite + docs audit — 2026-03-22 Covers: #257 (README rewrite), #300 (docs audit), decision-0004 (engine-root swap)

All files have been written by Joker via MCP. Harley commits, runs the engine-root swap, and opens the PR.

Rules for Harley

Run operations one at a time in the order listed
This is the FIRST TIME using the engine-root swap — read decision-0004 and the swap instructions in CLAUDE.md carefully
Confirm each result before moving to the next
Report any failures to operator immediately

Phase 0 — Setup

Operation 1 — Create feature branch

git checkout dev && git pull origin dev
git checkout -b feature/readme-docs-audit

Phase 1 — Commit content changes

These files were already written by Joker. Just verify they exist and commit.

Operation 2 — Verify new/changed files exist

Check that these files are present and have recent content:

README.md — should start with logo markup and “scaffolder” heading
CONTRIBUTING.md — should mention staging branch
STANDARDS.md — should say “doc production workflow” not “sc-doc-production”
assets/logo.svg — new file, should exist
.gitignore — should include templates/engine-root/ and .engine-root-backup/
templates/engine-root/CLAUDE.md — should exist (but is gitignored)
templates/engine-root/STANDARDS.md — should exist (but is gitignored)
templates/engine-root/PROJECT-INSTRUCTIONS.md — should exist (but is gitignored)
templates/engine-root/RELEASE-CHECKLIST.md — should exist (but is gitignored)

Operation 3 — Commit assets and contributing

git add assets/logo.svg CONTRIBUTING.md
git commit -m "docs: add placeholder logo and update CONTRIBUTING.md

- Logo SVG in assets/ (scaffolded slabs design, placeholder)
- CONTRIBUTING.md updated: added staging branch, fixed PR flow, corrected paths"

Operation 4 — Commit .gitignore

git add .gitignore
git commit -m "chore: update .gitignore for engine-root swap workflow

- Added templates/engine-root/ (local staging, not shipped)
- Added .engine-root-backup/ (temporary swap backup)
- Added ai-sessions/ (operator session state)
- Added docs/issues/, docs/plans/, docs/decisions/, docs/tasks/, docs/features/
  (operator work product)
- Per decision-0004"

Phase 2 — Engine-root swap (decision-0004)

This is the first time running the swap. Follow CLAUDE.md instructions exactly.

Operation 5 — Back up custom root files

mkdir -p .engine-root-backup
cp CLAUDE.md .engine-root-backup/
cp STANDARDS.md .engine-root-backup/
cp PROJECT-INSTRUCTIONS.md .engine-root-backup/
cp RELEASE-CHECKLIST.md .engine-root-backup/

Operation 6 — Copy engine-root templates to repo root

cp templates/engine-root/CLAUDE.md ./
cp templates/engine-root/STANDARDS.md ./
cp templates/engine-root/PROJECT-INSTRUCTIONS.md ./
cp templates/engine-root/RELEASE-CHECKLIST.md ./

Operation 7 — Commit all repo root files (generic versions + README)

git add README.md CLAUDE.md STANDARDS.md PROJECT-INSTRUCTIONS.md RELEASE-CHECKLIST.md
git commit -m "docs: README rewrite, docs audit, engine-root file swap

- Full README rewrite: spirit-first, accessible, planning philosophy,
  session continuity, scale tiers, 4 commands, fork-friendly note
- CLAUDE.md: generic product version (decision-0004 swap)
- STANDARDS.md: generic product version, fixed sc-doc-production reference
- PROJECT-INSTRUCTIONS.md: generic product version with example custom section
- RELEASE-CHECKLIST.md: generic product version
- Per decision-0004 (engine-root file swap for PRs)

Closes #257, closes #300"

Operation 8 — Restore custom files

cp .engine-root-backup/* ./
rm -rf .engine-root-backup/

Verify: cat CLAUDE.md should show the custom version (mentions Harley, Joker, canonical labels, session management). NOT the generic version.

Phase 3 — Push and PR

Operation 9 — Ensure ai-sessions/logs/ directory exists

mkdir -p ai-sessions/logs

Operation 10 — Push and open PR

git push origin feature/readme-docs-audit
gh pr create --base dev --title "docs: README rewrite, docs audit, engine-root file swap" --body "## What this does

Full README rewrite (#257): spirit-first copy, planning philosophy, session continuity,
scale tiers, 4 commands, fork-friendly note, placeholder logo.

Docs audit (#300): fixed CLAUDE.md (generic for repo), STANDARDS.md (removed stale
sc-doc-production reference), CONTRIBUTING.md (added staging, fixed PR flow and paths),
updated .gitignore for engine-root swap workflow.

First use of engine-root file swap (decision-0004): repo root files are generic product
versions, operator custom files stay local.

Closes #257, closes #300"

After this file

Release flow: dev → staging → main → tag v0.10.0 Follow RELEASE-CHECKLIST.md.