Skip to content

Docs carryover checklist from shuttle to sepia

Structural / cosmetic items to carry over

  • Use nav-style .pages files at the root and for journal/ and plans/.
  • Keep plans/_template.md as a lifecycle-oriented template with explicit status, dates, goals, steps, verification, rollback, and related references.
  • Keep journal/_template.md as a structured log template with summary, context, changes, decisions, issues, and next steps.
  • Keep the distinction between journal and plans in index.md.
  • Keep date-prefixed filenames for journal entries and completed plans.
  • Keep completed plans under plans/completed/ and active plans under plans/active/.
  • Keep the docs tree overview and quick-reference sections in index.md.
  • Keep docs Dockerfile hygiene, including git config --global --add safe.directory /opt.
  • Keep .dockerignore minimal but allow the docs Dockerfile to be tracked.

Pre-commit / quality-gate carryovers from /opt

Suggested hooks to mirror for docs hygiene:

  • trailing-whitespace
  • end-of-file-fixer
  • check-yaml
  • check-json
  • check-toml
  • check-added-large-files
  • check-merge-conflict
  • mixed-line-ending
  • check-case-conflict
  • markdownlint for .md / .mdx
  • detect-private-key
  • ruff / ruff-format for Python files if docs tooling includes Python scripts
  • hadolint for docs Dockerfiles

Shuttle-specific items to avoid copying verbatim

  • Hostnames, service counts, and app inventories that only apply to shuttle.
  • App-specific reference pages that sepia does not use.
  • Any branch-local setup for unrelated tooling unless sepia uses the same tool.

Notes

  • The pre-commit list above is intentionally split into generic docs/file hygiene and broader repo hygiene.
  • If sepia adopts a .pre-commit-config.yaml, prefer the smallest useful subset first: whitespace, EOF, YAML/JSON/TOML validity, merge-conflict markers, markdown lint, and Dockerfile lint for docs images.