roam/azos.org

azos

• Architecture
  • Module registration pattern
  • Option namespace
  • File deployment
• Conventions
• Gotchas
• Key Files
• org-roam Setup

Architecture

azos is a NixOS/home-manager configuration repo with a two-tier feature system:

• azos-core/ — git submodule containing shared, reusable features (base, editor, claude-memory, claude-skills, dev, etc.)
• features/ — machine-specific features (claude, encryption, hyprland, audio, etc.)
• home-manager/home.nix — home-manager entry point; manually lists all modules to import
• _machines/ — per-machine NixOS configs; passes suiteModules as specialArgs

Feature auto-discovery is via import-tree in each flake.nix. Features from both azos-core/features/ and azos/features/ are collected into config.flake.modules.

Module registration pattern

Each feature's default.nix registers itself:

config.flake.modules.homeManager.<name> = { lib, config, pkgs, ... }: {
  options.azos.<name>.enable = lib.mkOption { ... };
  config = lib.mkIf config.azos.<name>.enable { ... };
};

Modules are then imported in home-manager/home.nix via:

imports = [ suiteModules.homeManager.<name> ... ];

Option namespace

azos.<feature-name>.<option-name>

Dependencies between features use lib.mkDefault true to auto-enable:

azos.claude-memory.enable = lib.mkDefault true;
azos.claude-skills.enable = lib.mkDefault true;

File deployment

• Static files: home.file."path".source = ./file;
• Generated text: home.file."path".text = "...";
• Runtime scripts (e.g. merging JSON): home.activation.<name> = lib.hm.dag.entryAfter ["writeBoundary"] ''...'';

Conventions

• azos-core features belong to the submodule; machine-specific features live in the outer repo
• Extensible options follow the pattern established by azos.claude.globalSkills and azos.claude.globalMdSections: attrsets any module can contribute to, deployed by the owning feature
• Emacs config is literate org: azos-core/features/editor/emacs/config.org
• Emacs base config: azos-core/features/base/emacs/config.org
• agent-shell defaults to Claude Code on lauretta via (setq agent-shell-preferred-agent-config 'claude-code) in features/lauretta/emacs/config.org; this symbol skips agent selection entirely (no prompt)

Gotchas

• azos-core is a git submodule — git add must be run inside it separately from the outer repo
• Nix flakes only evaluate git-tracked files; new files must be staged (git add) before nix build will see them
• import-tree auto-discovers features but only sees tracked files — same constraint
• The machine name is lauretta; machine config is at _machines/lauretta.nix

Key Files

File	Purpose
azos-core/features/claude-memory/default.nix	org-roam MCP server integration
azos-core/features/claude-skills/default.nix	global skills + CLAUDE.md deployment
azos-core/features/claude-skills/skills/todo.md	per-project TODO management skill
azos-core/features/claude-skills/skills/project-brain.md	org-roam second brain skill
azos/features/claude/default.nix	installs claude-code, enables claude-memory + claude-skills
azos/home-manager/home.nix	home-manager entry point, imports all modules
azos-core/features/editor/emacs/config.org	literate Emacs config (org-roam at line ~452)
azos/azos-core	git submodule pointing to shared feature library
features/lauretta/emacs/config.org	lauretta-specific Emacs overrides (agent-shell, LLM, beacon, caldav)
~/.claude/settings.json	Claude Code global permissions; read-only org-roam MCP tools are always-allowed here

org-roam Setup

• Directory: ~/roam/
• Database: ~/.emacs.d/org-roam.db (sqlite-builtin connector)
• MCP server: org-roam-mcp registered in ~/.claude.json via home-manager activation
• org-agenda now includes ~/roam/ so TODOs in roam files appear in agenda