Home-manager configuration docs

The main README covers the essentials: installation, activation, bumping pi-coding-agent, and references. This folder holds the deeper technical documentation, split into topics.

Topics

• Security & secrets — SOPS secrets, the age key, Filen and Anytype credentials, path-guard hardening.
• Pi extensions — how extensions are provisioned, the extension inventory, the Anytype integration, and the security-adjacent tools (branch guard, curl, cost tracker).
• Models & providers — the Qwen3.6 local model, Scaleway/Melious/other providers, and cost tracking.
• Harness² — Google Research’s recursive agent-harnessing framework: entry points, benchmark setup, and runtime prerequisites.
• Testing — how the pi-extension test suite is organized and run.
• Vulnerability scanning — vulnix and trivy.
• Tooling — formatter, prek, pinned third-party binaries, the Swift toolchain, rig, uv-managed Python tools, nix-direnv.
• Philosophy — the rationale behind this setup.
• Herdr + firstmate — running a crew of coding agents with herdr as the terminal theater and firstmate as the director.

Repo layout

• flake.nix — flake inputs; evaluates modules/ via import-tree and emits homeConfigurations.
• modules/homes.nix — the Den orchestration: den.homes (philipp, philipp-linux, spectral-cockpit), batteries (define-user, user-shell), sops, and the home-aspect wiring. The darwin home resolves the philipp-darwin aspect, which wraps philipp with the darwin-only darwin-services; philipp-linux wraps philipp with linux-services (Camelid).
• modules/base.nix — the full philipp / philipp-linux profile as den.aspects.home.
• modules/home-spectral.nix — the spectral-cockpit profile as den.aspects.spectral-home.
• modules/ — a single flat Den import-tree; each file is a den.aspects.* with a homeManager class:
  • content aspects — ai.nix, anytype.nix, ub-tools.nix, shell.nix, editors.nix, terminal.nix, git.nix, dev-tools.nix, python.nix, go.nix, zig.nix, elixir.nix, rust.nix, swift.nix, clojure.nix, r-config.nix, r-project-local.nix, arf.nix, omlx.nix, basert.nix, camelid.nix, darwin-services.nix, linux-services.nix, pi-web.nix, opentofu.nix, forgejo.nix, backup.nix, pi-extensions.nix, hardening.nix.
  • package features — pkgs-*.nix (den.aspects.pkgs.*): cli, remote, virtualization, backup, fonts, dev, ai, r, graphics, security, forgejo, console, privacy, microsoft, misc.
  • pkgs.nix — the custom per-system nixpkgs (overlays) + flake packages / formatter.
  • _r-packages.nix — a helper (excluded from import-tree via the /_ filter); imported by r-config.
• pi-extensions/ — pi coding-agent extensions, symlinked into ~/.pi/agent/extensions/. See extensions.mdx.
• pi-agent/ — org-router files (AGENTS.md, per-org overlays).
• pi-models.json — registered providers and models (symlinked to ~/.pi/agent/models.json).
• pkgs/ — locally-vendored Nix derivations (e.g. pi-coding-agent, filen-cli, rig, rv).
• scripts/ — maintenance helpers (e.g. bump-pi-coding-agent.sh, bump-external-extension.sh, bump-tiger-style.sh, bump-ub-mode-skill.sh, bump-ub-tools.sh).
• secrets/ — SOPS-encrypted secrets.
• docs/ — this documentation.
• diagram.svg / diagram.mmd — the module diagram shown in the README.