From c4f52e053f126ac68bdb0227c441f67eb665e308 Mon Sep 17 00:00:00 2001
From: "brujoand-agent[bot]"
 <300433439+brujoand-agent[bot]@users.noreply.github.com>
Date: Fri, 10 Jul 2026 15:00:48 +0200
Subject: [PATCH] docs: track CLAUDE.md, ignore CLAUDE.local.md instead

.gitignore listed CLAUDE.md, which blocks the shared, tracked file rather than
the personal one. CLAUDE.local.md is the untracked variant, so swap the ignore
and commit a real CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore |  2 +-
 CLAUDE.md  | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 CLAUDE.md

diff --git a/.gitignore b/.gitignore
index e4ab8a6..3f9fa4c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,4 +10,4 @@ config/sbp/hook.log
 dotfiles/gitrc/git-piano
 dotfiles/config/nvim/plugged/*
 config/sbc/repos
-CLAUDE.md
+CLAUDE.local.md
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b072248
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,54 @@
+# dotfiles
+
+Personal bash environment: prompt, shell helpers ("cogs"), nvim and tmux config.
+Installed by `install_dotfiles.bash`.
+
+## Hard rules
+
+- **Never push to `main`/`master`.** Feature branch + PR, always. Open the PR,
+  report the URL, stop — **only the human merges.**
+- **Conventional Commits** (`feat:`, `fix:`, `chore:`, …). Never hand-bump a version.
+- **`pre-commit` is the gate.** Run `pre-commit run --files <changed>` before
+  declaring a change done, and report the result.
+- **`mise` provisions the toolchain** (`mise install`). New worktrees need `mise trust`.
+- Plan every non-trivial task. If the plan fails, restart planning.
+
+## Workflow
+
+Default branch is `master`. CI (`ci.yml`) runs `pre-commit run --all-files` plus a
+syntax check of the install script; `docker-publish.yml` builds and cosign-signs
+an image on pushes to `master` and on a daily cron.
+
+## Architecture
+
+- `cogs/` — 17 sourced bash modules, one per topic: `git`, `k8s`, `flux`, `java`,
+  `tmux`, `neovim`, `network`, `osx`, `linux`, `security`, `text`, `navigation`,
+  `completion`, `env`, `gtd`, `mgr`, `leftovers`
+- `bin/` — standalone scripts (`brew_update.sh`, `md_cal.sh`, `weather_update.sh`)
+- `config/` — nvim, and config for the prompt and cog loader
+- `dotfiles/` — the files that get linked into `$HOME` (gitconfig, inputrc,
+  tmux.conf.local, .hammerspoon)
+- `packages/` — brew config, keyboard layouts, bootstrap
+
+## Commands
+
+```bash
+mise install
+bash -n install_dotfiles.bash          # what CI checks
+pre-commit run --files <changed files>
+pre-commit run --all-files
+```
+
+There is no test suite.
+
+## Gotchas
+
+- **17 vim-plugin submodules** under `nvim/bundle/`, all with `git@github.com:`
+  SSH URLs — `git submodule update --init` needs working SSH, not the HTTPS
+  credential helper.
+- The README says `bin/install_dotfiles.sh`; the tracked file is
+  `install_dotfiles.bash`.
+- Bash standards, enforced by pre-commit: `#!/usr/bin/env bash`, `set -e`, `[[`
+  not `[`, `$()` not backticks, `local` in functions, no emojis, 2-space indent.
+  shellcheck runs on `*.bash`; shfmt with `-w -s -i 2`.
+- Personal, untracked notes belong in `CLAUDE.local.md`, which is gitignored.