🪦 Rotkeeper

"What lives in /bones/ may yet render again."

Rotkeeper is a Bash-native static-site and content system with Oliver HTML rendering, integrity scanning, documentation improvement, archiving, and release packaging. No Node, NPM, or application framework is required — just Markdown, Bash, and standard Unix tooling. The outputs are raw, static, and immortal.

Why this exists

We wanted a system that survives the heat death of the modern JavaScript ecosystem. Rotkeeper turns flat-file Markdown hoards into rendered static sites through disposable Unix tools, and treats its own documentation as a first-class artifact.

The BHO model

Rotkeeper organizes everything around BHO (Bones, Home, Output) — system, then content, then artifacts.

• bones/ (System): scripts (rc-*.sh), HTML templates, configuration, logs, metadata sidecars, reports, and archives.
• home/ (Content): your Markdown (home/content/) and static assets (home/assets/). This is author-managed source material.
• output/ (Artifacts): rendered HTML and generated site structures. Never edit it directly — change source and re-render.

bones/ stays the system root in every layout; the content and output directories shift with your chosen layout style:

Style	Content	Templates	Assets	Output
crypt (default)	home/content	bones/templates	home/assets	output
busy	home/content	templates	assets	output
sterile	src/content	config/templates	src/assets	dist

Quickstart

Check that the renderer is available, initialize a site, and render it:

./rotkeeper.sh preflight   # Oliver found, executable, and runnable?
./rotkeeper.sh init --with-sample   # Initialize layout, config, sample content
./rotkeeper.sh render      # Convert Markdown to HTML
./rotkeeper.sh status      # Environment health and content report

If preflight fails, install Oliver (or set RK_OLIVER_BIN=/path/to/oliver) and re-run it. Full install steps are in home/content/docs/oliver-contract.md.

Common workflows

Publish a static site: init → write Markdown (or new <file> to scaffold) → render → scan → deploy output/ (or dist/).

Ship a framework release: test → bump 0.5.2 → release 0.5.2 → the canonical zip lands in bones/archive/releases/, verified against an explicit allowlist and manifest.

Audit documentation: dip reports documentation coverage; book --docbook binds the documentation into one retrieval artifact.

The full end-to-end walkthrough lives in home/content/docs/workflow.md.

Requirements

• macOS or Linux with Bash 4+
• yq v4+ (the Go implementation by mikefarah)
• gawk (GNU Awk)
• sha256sum (or shasum on macOS)
• jq
• rsync
• zip, zipinfo, and tar (for release and pack)

Rendering: Oliver is the only renderer (Pandoc was removed). Put oliver on PATH or set RK_OLIVER_BIN=/path/to/oliver. bash rotkeeper.sh preflight is the single diagnostic for finding, executability, and runnability.

Command reference

Command	Description
init	Initialize the environment and configuration (--with-sample adds starter content)
new <file>	Scaffold a new Markdown file with frontmatter
render	Convert Markdown into HTML with Oliver
preflight	Report Oliver availability, compatibility, and runnability
pack	Archive rendered HTML into a versioned tarball
release [VERSION]	Package the canonical framework zip (allowlist + manifest verified)
bump	Record a microrelease and sync version markers
scan	Verify manifest entries against generated files
assets	Generate the asset manifest
glue	Generate navigation glue for unindexed content directories
links	Audit links and local assets in rendered HTML
showcase	Generate showcase content for every template/theme
dip	Audit documentation coverage
book	Generate aggregated documentation book targets
autopsy	Catalog script help and behavior
status	Display environment health status reports
test / smoke	Run the integration harness (all layout styles, hermetic fixtures)

Run any command with --help, --version, or --dry-run (where supported) — help is non-mutating.

A note for agents and contributors

Read AGENTS.md before modifying the crypt. It contains the architectural constraints, the BHO rules, required validation gates, and the dispatcher contract. Documentation generated by DIP is reference material, not ground truth — verify against source scripts.

Troubleshooting

Symptom	Likely cause	Fix
render fails before reanimating	Oliver missing/incompatible	bash rotkeeper.sh preflight and follow its message
preflight reports Oliver missing	Oliver not installed or not on PATH	Install Oliver (see oliver-contract.md) or set RK_OLIVER_BIN
yq or gawk errors	Missing dependency	Install mikefarah/yq v4+ and gawk; require_* checks exit 2 with hints
Layout path mismatch error	Repository moved or config paths stale	Run ./rotkeeper.sh init to heal path mappings
Malformed YAML	Broken frontmatter or rotkeeper.yaml	Validate with yq eval '.' <file>
Stale pages persist	Rendered output not pruned (output tree has no ownership marker)	Re-run render; it writes the ownership marker and prunes stale HTML on subsequent passes

License

MIT. You may rot freely.