Skip to content
himmel

himmel docs

Map of the docs/ tree. New here? Start at getting-started.md.

Start here

  • why-himmel.md — the case for the harness: the five failure modes it exists for, the evidence, and what it costs you.
  • adoption-trail.html — the eight-level adoption trail, as a page you open in a browser: what each level turns on, what it changes, and what it does not. Public URL: https://yotamleo-org.github.io/Himmel/adoption-trail.html (how the site is published)
  • system-design.md — the narrative design document: goals, the parts, one ticket’s flow from file to merge, the trust and safety model, and the trade-offs behind the key decisions.
  • architecture.md — five diagrams: the enforcement layers, the handover system, the fleet/chief model, the Jira seam, the observability chain.
  • getting-started.md — clone to your first PR-gated loop in ~15 minutes.
  • daily-loop.md — one full loop (worktree → PR → merge → clean → handover), with every hook and gate explained where it fires.
  • configuration.md — the canonical configuration + control-surface reference: the chains (mermaid), every gate classified HARD / auth-gated / warn-only, every knob by surface, and the off-switches. Pairs with .env.example, the per-key flag map.
  • ui.md — the UI surfaces: the himmelctl ui config UI, the chief’s board, and the roadmap tracker; what each is, how to start it, where it opens.

Setup

  • setup/new-machine.md — fresh-machine setup: required tools + per-platform (Linux / macOS) install.
  • setup/install.md — install himmel into an existing repo with himmelctl: scopes, install profiles, and the adaptation checklist.
  • setup/migrating.md — converge an older himmel install (old adopt.sh, hand-wired, or a pre-himmelctl station) onto the current installer.
  • setup/updating.md — update the harness (/himmel-update) and upgrade luna vaults (/luna-upgrade); also points to the symmetric scripts/uninstall.sh teardown.
  • setup/global-claude-md.md — Claude Code global config (~/.claude/).
  • setup/vms.md — VM-based dev machines for cross-platform testing.
  • setup/rtk-md.md — the rtk token-cost proxy.

Daily use & reference

  • glossary.md — the one definition site for the handover vocabulary: chief, judge, relay, worker, dependency chain, parallel wave, arming, manual override.
  • commands-catalog.md — every project-local slash command.
  • tooling-catalog.md — every tool, script, and plugin in active use.
  • himmelctl.md — every himmelctl verb (status, ensure, update, scope, profile, config, deps, gaps, trust, --version --all) with its exit codes.
  • troubleshooting.md — each message a starter install can show, why it appears, and the fix.
  • cadences.md — every recurring job you can arm: what it does, when the wizard offers it, how to arm, status and disarm it.
  • launchers.md — the claude-codex, claude-openrouter and claude-deepseek launchers, their gates and exit codes; the GLM lane is dormant.
  • himmel-bus.md — early. The local session-to-session message bus: CLI, MCP tools, identity, delivery guarantees.
  • jarvis-subsystems.md — adopter usage map of the optional agentic-OS subsystems (the dormant GLM lane, quota-gauge, escalation channel, statusline, clipper pipeline).
  • operator-conventions.md — durable operator working-habits.
  • contributing.md — the contribution workflow.
  • token-economy.md — per-boundary token-optimizer policy: who owns which token cost and where it’s paid.

How enforcement works (internals)

Orchestration & lanes

Integrations

Setup (continued)

Process, security & audits

Publishing these docs (GitHub Pages)

The public repo serves a built docs site at https://yotamleo-org.github.io/Himmel/ (sidebar, search, readable pages). Raw files stay at their old paths, for example /Himmel/setup/install.md and /Himmel/setup/settings-template.json, and /Himmel/adoption-trail.html is unchanged.

  • Source. site/ is the Starlight workspace and docs/ is its content. .github/workflows/pages.yml runs npm ci and npm run build in site/, uploads site/dist and deploys it. It runs once a day (cron 17 3 * * *, 03:17 UTC) and on demand with gh workflow run pages.yml; a push that changes docs/** does not redeploy, so the change goes live at the next daily run or on the manual command. site/allowlist.txt lists the pages and site/astro.config.mjs holds the sidebar; a page in docs/ that is on neither list is not on the site. docs/.nojekyll stays so a plain static serve of docs/ matches the raw files.
  • Preview locally. bash scripts/docs-site/serve.sh builds the site and serves it at http://127.0.0.1:4321/Himmel/. The raw files alone: python3 -m http.server 8000 --directory docs.
  • Check before you merge. bash scripts/docs-site/test-site-build.sh builds the site and checks titles, links (a broken link fails the build), search and the raw files. bash scripts/docs/test-adoption-trail.sh resolves every link on the trail page and pins the claims that have drifted before (cadence count, lanes menu, plugin provenance) to the tree.
  • Check after. Once the Pages run succeeds, curl -s https://yotamleo-org.github.io/Himmel/adoption-trail.html | cmp - docs/adoption-trail.html prints nothing when the live page matches your checkout.

Historical / working records (not a navigation target)

patches/ (dated point-fix logs) holds dated, single-purpose artifacts kept for provenance rather than day-to-day reference. Browse the directory rather than looking for an index here.

Working as an LLM in this repo? The machine-readable map is ../llms.txt.