Frequently Asking Questions

Jekyll blog (frequently-asking-questions.com, GitHub Pages) with Supabase auth, comments, subscriptions and AI-pre-moderated reader questions. Stack: Jekyll + vanilla ES5 JS · Supabase Postgres + Edge Functions (Deno TS) · OpenAI for moderation · GitHub Actions.

Source of truth: SPEC.md (§V invariants, §T tasks, §B bugs). When this file and SPEC disagree, SPEC wins. Map of the code: ARCHITECTURE.md. Dev environment, test users, deploys: docs/live/dev-environment.md.

Commands

npm ci                                            # Node deps (jsdom) — tests need them
bundle exec jekyll build --drafts --config _config.yml,_config.dev.yml   # build-output tests read _site/
npm test                                          # full suite (node:test), CI: .github/workflows/test.yml
npm run test:deno                                 # Edge Function unit tests (supabase/functions/**/*_test.ts), CI too
npm run build:article-summaries                   # after any _posts/ change; commit the JSON (CI checks)
npm run build:raw-guides                          # after editing the agentic-repo-prep post or prep-repo/
bash scripts/serve-dev.sh                         # localhost:4000 against DEV Supabase (paused 2026-10-01)
CODEX_MODEL=<id> scripts/review/codex_review.sh <base>...HEAD [paths]   # read-only cross-model review

No linter or formatter is configured.

Definition of done (every change)

  1. Build (command above) succeeds and npm test + npm run test:deno green. Show the output tail, don’t assert it.
  2. Behavior change → a test that fails without it. Bug fix → §B entry + §V guard (backprop skill).
  3. Every LIVING doc that describes code you touched is updated in the same commit (SPEC §T status, ARCHITECTURE, the docs/live/ page). A stale line is a bug.
  4. Separate review pass on the diff before calling it done: scripts/review/codex_review.sh (read-only). Verify each finding before acting. Green tests are not “done”.
  5. UI change → check the running site: npm run e2e (Playwright, docs/live/e2e_testing.md) or scripts/serve-dev.sh by hand, as the relevant test user; look at the screenshots.

Docs map

Path Role Currency
SPEC.md / FORMAT.md Contract §G §C §I §V §T §B §D / how SPEC is written LIVING (spec skill only)
ARCHITECTURE.md Where things live, how they connect LIVING
docs/live/ How subsystem X works now (+ README with header rule) LIVING, audited by check
docs/design/ Plans, feature write-ups at a date; tasks/tN_*_plan.md FROZEN
docs/journal/ Dated “why” + AI-collaboration notes; legacy/ = old docs verbatim FROZEN, append-only
docs/templates/ task plan, journal entry, handoff LIVING
.github/copilot-instructions.md Visual design rules LIVING
CNAME, post permalinks, guides/agentic-repo-prep/*, assets/**, feed.xml, sitemap.xml, supabase/migrations/* names Served / externally registered never move

Workflow (skills in .claude/skills/, plain Markdown for other tools)

  • Required reading before editing code for a §T task: the §T row + every §V that could apply → ARCHITECTURE section → docs/live/ doc → the touched code itself (cite file:line). Docs lie; code wins.
  • plan §T.n → docs/design/tasks/tN_*_plan.md, ends in “SPEC changes needed”.
  • spec → sole mutator of SPEC.md (bug: … for backprop). build §T.n → one row; failure → backprop, never blind retry. check → read-only drift audit.
  • Journal after milestones: docs/journal/YYYY-MM-DD_topic.md, Process notes mandatory.
  • One task per session. Several → loop one §T row at a time, state in SPEC/docs/commits.
  • Work spanning sessions (a release, a multi-PR effort) → docs/design/<topic>-HANDOFF.md from docs/templates/handoff.md, updated in the same commit as the work; FROZEN when it merges.
  • Stuck twice on the same setup problem: stop guessing, read the live official docs, cite the URL.
  • Bug found, not fixed now → gh issue create --label bug (symptom, cause, fix idea, guard idea).

Hard rules

  • Never read or edit .env.dev* or other secrets. Dev secrets live in Bitwarden; humans run scripts/vault/*.sh. Never paste keys into tracked files (tests/secrets.test.js fails).
  • Never write to PROD Supabase (pxqcmkzvyapuhkqqlxgx); prod MCP is read-only. DEV writes OK.
  • Stage explicit paths only. Never git add -A / . / -u, never git commit -a.
  • Branch before committing. Never commit to main.
  • Schema change → new supabase/migrations/0NN_*.sql + update supabase/supabase-schema.sql. Never rename or edit an applied migration.
  • New Edge Function → [functions.<name>] with verify_jwt = false + comment on its auth in supabase/config.toml; function authenticates itself (SPEC V.1).
  • Frontend JS: ES5, one IIFE module per file, no bundler. Don’t grow files >400 lines (T.12).
  • Don’t hand-edit generated files: article-summaries.json, guides/*/GUIDE.md, prep-repo.tar.gz.
  • Guards are best effort, not a sandbox. Read the block’s reason. If it names a file, folder or history the command really reads or writes: stop and ask, never a puzzle to solve. If the named word only appears in text the command never opens (a message, a search pattern, echoed text), it’s collateral: rephrase the text. Never disguise a path to get past a guard. To edit a doc that merely mentions a secret path, use the Edit tool, not shell.
  • After any blocked or failed command, re-check the real state before writing it up as done.