Sync docs with repo, compound closed-PR lessons, fix lint parity + taskbook placement - #51
Draft
alycda wants to merge 5 commits into
Draft
Sync docs with repo, compound closed-PR lessons, fix lint parity + taskbook placement#51alycda wants to merge 5 commits into
alycda wants to merge 5 commits into
Conversation
Both the README structure diagram and CLAUDE.md's Repository Structure had drifted ~a dozen commits behind reality. Neither documented four whole top-level areas or the newer home-manager modules, so a reader (human or agent) building a mental model from the docs would miss half the repo. What was stale and is now captured: - lib/core-packages.nix — the shared pkgs list imported by BOTH the flake devShells and home-manager, so ephemeral `nix develop` and switched profiles install the same core CLI tools. This is a real architectural decision and now has its own note in CLAUDE.md. - tools/ — non-Nix tool content (agents overlay, cheat, claude rules, helix), wired in by the new home-manager/modules/tools/* modules. - secrets/ — agenix/ragenix age-encrypted secrets. - docker/ + Dockerfile — the x86_64 image for the frozen 2012 MBP. - home-manager: modules/git.nix, modules/tools/*, ide/vscode-profiles/, profiles/code.nix; darwin/modules/homebrew.nix. - Dropped the phantom darwin/profiles/alyssa.nix (ditto is the only darwinConfiguration). Docs-only; no behavior change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UGTA5cYd5qJuzCAhux7s2D
A compound-engineering pass over all 31 closed PRs (merged and abandoned), mining each PR's body, review discussion, and resulting diff for reusable rules and gotchas, then distilling the ones not already captured into the guidelines. Every claim was verified against the current tree before writing. Abandoned PRs were as instructive as merged ones — they record what NOT to do. New / expanded guidance: - New section "Tools Nix Can't Fully Manage": SDK/version managers via activation scripts not nix-shell (#3, #6); prefer Homebrew over a hand-rolled derivation and never commit lib.fakeHash (#19); the full installer-script-under-activation playbook — sanitized PATH, sessionPath over rc exports, guard on the binary path not `command -v`, pin the installer version (#32 -> #37); linkGeneration vs writeBoundary ordering for generated @imports (#38); pin a CLI to a fast-updating input to stay matched to its companion extension, with the opaque "Interrupted" failure mode (#26). - Configuration Conflicts to Avoid: don't hand-list a package a `programs.*` module already provides (#11); enable the shell or its hooks never inject (#24); runtime-mutable config must stay unmanaged (#44, #10, #38). - System vs User: fonts are system-level (#20); dock-pinned apps must be casks under cleanup="zap" (#13); pinned nix-darwin drifts against a newer brew CLI, worsened by autoUpdate (#35). - Module Organization: don't over-modularize a trivial package (#44); devShell ships the minimal build, home-manager owns the full config (#7); keep path-assuming out-of-store-symlink modules out of common.nix (#46). - Adding a Tool: shell integration is a step separate from installing the binary (#23, #24). - Testing: passing activation is not proof a tool works — verify end state in a clean VM (#37). - CI Checks: prefer `just ci`/`just lint`; flagged the deadnix parity gap (`-- .` local vs `--fail .` in CI) and floating action refs (#14, #1). Docs-only; no behavior change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UGTA5cYd5qJuzCAhux7s2D
1. deadnix parity — `just lint-deadnix` ran `deadnix -- .` (report-only) while CI runs `deadnix --fail .`, so a green `just ci` could still fail CI on dead code. Pass `--fail` locally too, restoring `just ci` as a trustworthy pre-push gate. 2. taskbook placement — taskbook (a Node closure) sat in lib/core-packages.nix, which common.nix imports into ALL profiles including the headless dev/x86 devcontainer, and which the flake devShells also pull. That bloats the disk-constrained 2012 MBP image for no container benefit — the exact thing the lean-common.nix rule exists to prevent. Moved it to the desktop profiles (home.nix, work.nix) where it's actually used, and documented core-packages as a lean, universal-CLI-only list. CLAUDE.md updated so the guidelines match the code: the deadnix-parity note now reflects the realigned state, the "don't over-modularize" note records that simplest-placement ≠ core-packages for heavy closures, and the shared-package-list section gains the keep-it-lean caveat. Docs + config only; the user runs the rebuild. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UGTA5cYd5qJuzCAhux7s2D
5 tasks
…eering-plugin-tchbun # Conflicts: # CLAUDE.md
Brings the branch up to date with main (22 commits) and resolves the three conflicts, all of which were additive — both sides appended to the same lists, so nothing had to be dropped. CLAUDE.md: - Configuration Conflicts: kept main's base-image collisions entry at #4 (main's own changelog line calls it "a fourth configuration conflict", so renumbering it would have made that line wrong) and shifted this branch's three compounded lessons to #5-#7. - CI Checks: kept both the `just lint`/CI parity note from this branch and main's Entity diff subsection — they document different jobs. - Changelog: kept all three entries, newest first. lib/core-packages.nix: took main's `gnused` and `supabase-cli`, but held this branch's removal of `taskbook`. That removal is the point of the branch — taskbook's Node closure has no business in the headless devcontainer — and it now lives in home.nix/work.nix instead. A naive "take both sides" would have silently reverted the fix. Verified before pushing: statix clean, deadnix --fail clean, nix flake check --all-systems passes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
⊕ Entity-level changesCLAUDE.md
home-manager/profiles/home.nix
home-manager/profiles/work.nix
justfile
lib/core-packages.nix
Summary: 2 added, 11 modified across 5 files (1 modified orphan) functions and classes, not lines · sem |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
A documentation + compound-engineering pass, plus two small fixes surfaced by that pass.
1. Sync the structure docs with reality (
579a593)Both the README diagram and CLAUDE.md's Repository Structure had drifted ~a dozen commits behind the actual tree. Neither documented four whole top-level areas or the newer home-manager modules:
lib/core-packages.nix— the sharedpkgslist imported by both the flake devShells and home-manager (now has its own note explaining the pattern)tools/— non-Nix tool content (agents overlay, cheat, claude rules, helix), wired in byhome-manager/modules/tools/*secrets/— agenix/ragenix encrypted secretsdocker/+Dockerfile— the x86_64 image for the frozen 2012 MBPmodules/git.nix,ide/vscode-profiles/,profiles/code.nix,darwin/modules/homebrew.nix; dropped the phantomdarwin/profiles/alyssa.nix2. Compound durable lessons mined from closed PRs (
297f844)A pass over all 31 closed PRs (merged and abandoned) — mining each body, review thread, and diff — distilling the reusable rules not already captured. Every claim was verified against the current tree. Highlights:
lib.fakeHash(Add envelope CLI tool to home-manager configuration #19); the full installer-script-under-activation playbook — sanitized PATH,sessionPathover rc exports, guard on the binary path notcommand -v, pin the installer version (Install lazydiff via official script on work profile #32→fix(lazydiff): make installer work under home-manager activation and put binary on PATH #37);linkGenerationvswriteBoundaryordering (feat(claude): manage global outbound-message gate in ~/.claude #38); pin a CLI to a fast-updating input to stay matched to its extension, with the opaque "Interrupted" failure mode (fix: pin claude-code to sadjow/claude-code-nix for version sync with VSCode extension #26)programs.*duplication (Cleanup/darwin #11); enable-the-shell-or-hooks-don't-inject (Enable zsh in home-manager so direnv hook is injected #24); runtime-mutable config stays unmanaged (Add taskbook as an interim CLI task manager #44, Add Claude Code configuration with home-manager and Docker support #10)cleanup="zap"(Add Notion and Slack to Homebrew casks #13); pinned nix-darwin drifts against a newer brew CLI (Fix fresh-machine bootstrap: nix-darwin pin + verified README steps #35)common.nix(feat(agents): mount html-deck skill for Claude #46)just ci/just lint; flagged the deadnix parity gap and floating action refs (Add Nix linting to GitHub workflow #14, Add Nix CI validation workflow #1)3. Fixes surfaced by the pass
justfile'slint-deadnixrandeadnix -- .(report-only) while CI runsdeadnix --fail ., so a greenjust cicould still fail CI. Aligned local to CI.taskbook(a Node closure) sat inlib/core-packages.nix, whichcommon.nix— and therefore the headlessdev/x86 devcontainer — inherits, contradicting the lean-container rule. Moved it to the desktop profiles (home.nix,work.nix) where it's actually used.Testing
Docs + config only; no runtime behavior change beyond the two fixes. CLAUDE.md structure verified (balanced code fences, intact headings). The user runs
darwin-rebuild/home-manager switchthemselves.Follow-ups
Filed as a separate issue: writing the agent-distribution invariants into
tools/agents/README.mdand the Claude-Code-on-web instruction-drift open risk (#40).🤖 Generated with Claude Code
Generated by Claude Code