Architecture
Repository Structure
This document maps every top-level path in the repository to its purpose. Skim it once and you should be able to answer:
- Where is the
dotCLI? →bin/dot(the source-of-truth file). At runtime it lives at~/.local/bin/dot. - Why are there 20+
dot_*files at root? → chezmoi convention: adot_Xsource file deploys to~/.Xon apply. Same forexecutable_*(gains+x),private_*(0600),run_onchange_*(re-runs when source changes). - What's the framework vs. the maintainer's personal config? → Everything under
scripts/,install/,tools/,lib/, anddefaults/.chezmoitemplates/is framework code. Everything underdefaults/dot_config/,defaults/dot_warp/,defaults/private_dot_ssh/is user-facing default configuration (chezmoi auto-rebases via.chezmoiroot).
The Debian/aws-cli-style root layout shipped in v0.2.503: bin/ (dispatcher), lib/ (shared bash libs), defaults/ (all chezmoi-tracked source files, rebased via .chezmoiroot). Repo root now hosts only project/CI/docs paths. See docs/operations/ROADMAP_V0_2_503.md for the full history.
Top-level paths
| Path | Kind | Purpose |
|---|---|---|
| CLI + framework | ||
dot_local/bin/ | framework | executable_dot (CLI entrypoint) and helper scripts. Deploys to ~/.local/bin/. |
dot_local/share/ | framework | Man pages, zsh completions. Deploys to ~/.local/share/. |
scripts/ | framework | Runtime-invoked scripts (dot CLI dispatch + specialised subtrees). See scripts/README.md. |
tools/ | repo-ops | Repo-only ops: CI helpers, release, maintenance, docs-generation. Not distributable. See tools/README.md. |
lib/dot/ | framework | Shared bash library sourced by every dot subcommand and the dispatcher. Reorganised here from scripts/dot/lib/ per RFC Phase 1. See lib/dot/README.md. |
lib/ | framework | Library tree (lib/dot/ + the dot-sys Rust crate in lib/wasm-tools/, built for wasm32-wasip1 and run under wasmtime by dot attest --verify). |
install/ | framework | Bootstrap logic + distribution-channel manifests (homebrew/, scoop/, aur/). See install/README.md. install/provision/ runs on chezmoi apply via run_onchange_* triggers. |
install.sh | framework | Top-level installer. SHA256-verified chezmoi fetch + initial apply. |
.chezmoitemplates/ | framework | Reusable Go-template partials (aliases, functions, paths). Sourced by dot_*.tmpl files. |
| User-facing defaults | ||
dot_bashrc, dot_zshrc, dot_zshenv, dot_zprofile, dot_profile, dot_vimrc, etc. | defaults | Shell + editor rc files. Deploy to ~/.X. |
dot_config/ | defaults | XDG config (~/.config/*). Largest tree — 80+ tool configs. |
dot_local/ (non-bin/share) | defaults | Per-user state files for tools (dot_local/state/, etc.). |
dot_cargo/, dot_etc/, dot_warp/ | defaults | Tool-specific roots (cargo, system etc, Warp terminal). |
private_dot_ssh/ | defaults | SSH config — chezmoi private_ prefix forces 0600. Does NOT contain private keys. |
dot_claude/ | defaults | Claude Code per-user skills and config. |
| Templates + data | ||
templates/ | framework | Non-chezmoi templates (e.g. for dot agents render). |
.chezmoidata/ | data | Hardware presets (macbook-t2, surface-pro) read by templates. |
.chezmoidata.toml | data | Feature flags + version. Single source-of-truth for dotfiles_version. |
.chezmoi.toml.tmpl | framework | Per-host chezmoi config generated on first apply. |
.chezmoiignore / .chezmoiignore.tmpl | framework | Tells chezmoi which paths NOT to deploy. |
| Docs + tests | ||
docs/ | docs | All documentation: manual/ (user guide), operations/ (audits, roadmaps), reference/ (lookup tables), security/. |
tests/ | tests | Test suite: framework/ (runner + assertions + mocks), unit/, integration/, regression/, fuzz/, snapshots/. |
examples/ | docs | Standalone examples (mise plugin, AI patterns, ops scripts). |
| CI + release | ||
.github/ | ci | GitHub Actions workflows + issue/PR templates + repo-level SECURITY/CODEOWNERS. |
.devcontainer/ | ci | Dev Container spec for reproducible contributor onboarding. |
Dockerfile.test | ci | Container baseline for the CI test job. |
.pre-commit-config.yaml → config/pre-commit-config.yaml | ci | Pre-commit hooks (shellcheck, shfmt, luacheck, gitleaks, typos, conventional-commits). |
flake.nix / flake.lock | ci | Nix flake for reproducible dev shell. |
mise.toml / mise-versions.lock.json | ci | Pinned tool versions (mise as the package manager). |
| Misc + agents | ||
AGENTS.md | docs | Cross-harness AI agent context (the standard read by Codex/Cursor/etc.). |
.cursor/, .codex/, .windsurf/, .zed/, .roo/, .clinerules, .aider.conf.yml, .continuerc.json, .jules/, .agy/ | agents | Per-harness AGENTS.md renderings. Generated by dot agents render. Each one points back at CLAUDE.md as canonical. |
CLAUDE.md | docs | Project guidelines (the canonical source — dot agents render propagates it). |
CONTRIBUTING.md | docs | Contributor guide (must stay at root for GitHub auto-discovery). |
docs/CONFIG_STRATEGY.md, docs/OPENCODE.md | docs | Strategy + OpenCode-CLI guidance. Moved out of root for cleanliness in v0.2.503. |
README.md / CHANGELOG.md / LICENSE | docs | Standard project files. |
Justfile.tmpl / Makefile | dev | Task runners. |
dist/ | build | Build artefacts directory. |
coverage/, nightly-reports/ | build | CI output directories (gitignored). |
nix/ | build | Nix flake source. |
.well-known/ | misc | RFC-compliant .well-known/ content (currently used for WKD GPG key publication). |
.version-sync-backup/ | misc | Backup directory used by scripts/version-sync.sh during release prep. |
Chezmoi naming contract
| Prefix / suffix | Effect on deployment |
|---|---|
dot_foo | Deploys as .foo (the dot_ is consumed). |
executable_foo | Adds +x permission. |
private_foo | Sets 0600 permission. |
run_onchange_foo.sh | Script re-executes when its hash changes. |
*.tmpl | Processed as a Go template with chezmoi data before deployment. |
Critical gotcha: executable_dot_foo deploys as .foo (not dot_foo). The dot_ prefix is consumed by chezmoi after the executable_ prefix. Renaming a deployed file silently can leave stale state in ~/.config/chezmoi/.
Where to make changes
| Goal | File(s) to edit |
|---|---|
Add a new dot <subcommand> | scripts/dot/commands/<subcommand>.sh + dispatch in bin/dot + entry in docs/manual/03-reference/01-dot-cli.md + entry in docs/manual/command-index.md. |
| Change an alias | .chezmoitemplates/aliases/<file>.aliases.sh (sourced by dot_zshrc.tmpl, etc.). |
| Add a feature flag | [features] block in .chezmoidata.toml + doc entry in docs/manual/03-reference/05-feature-flags.md. |
Add a new file deployed to ~/.X | Create dot_X at root (or under a chezmoi-managed subtree). |
| Add a new chezmoi template | dot_X.tmpl at root, then use {{ }} for chezmoi data. |
| Add a CI workflow | .github/workflows/<name>.yml. |
| Add a test | tests/unit/<domain>/test_<name>.sh or tests/integration/test_<name>.sh. |
See also
scripts/README.md— map of thescripts/subtree.CONTRIBUTING.md— code-style + commit-message + signing requirements.CLAUDE.md— AI-assistant guidelines (the canonical source fordot agents render).docs/operations/ROADMAP_V0_2_503.md— current release scope, including the v0.2.503 reorganisation plan.