110 lines
5.2 KiB
Org Mode
110 lines
5.2 KiB
Org Mode
:PROPERTIES:
|
|
:ID: bf4dde56-0967-4374-94ed-771301e47c66
|
|
:END:
|
|
|
|
#+title: azos
|
|
#+filetags: :project: :knowledge:
|
|
|
|
* 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:
|
|
|
|
#+begin_src nix
|
|
config.flake.modules.homeManager.<name> = { lib, config, pkgs, ... }: {
|
|
options.azos.<name>.enable = lib.mkOption { ... };
|
|
config = lib.mkIf config.azos.<name>.enable { ... };
|
|
};
|
|
#+end_src
|
|
|
|
Modules are then imported in =home-manager/home.nix= via:
|
|
|
|
#+begin_src nix
|
|
imports = [ suiteModules.homeManager.<name> ... ];
|
|
#+end_src
|
|
|
|
** Option namespace
|
|
|
|
=azos.<feature-name>.<option-name>=
|
|
|
|
Dependencies between features use =lib.mkDefault true= to auto-enable:
|
|
|
|
#+begin_src nix
|
|
azos.claude-memory.enable = lib.mkDefault true;
|
|
azos.claude-skills.enable = lib.mkDefault true;
|
|
#+end_src
|
|
|
|
** 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"] ''...'';=
|
|
|
|
** Claude Code integration
|
|
|
|
Three azos-core features wire up Claude Code:
|
|
- =claude-memory= — registers org-roam-mcp as a global MCP server in =~/.claude.json=
|
|
- =claude-skills= — deploys skills to =~/.claude/commands/= and content to =~/.claude/CLAUDE.md=
|
|
- =claude= (=azos/features=) — installs claude-code, auto-enables the above two
|
|
|
|
* 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)
|
|
- Rebuild command: =azos-lauretta-update=
|
|
- Format: =nix fmt=
|
|
- Packages in overlay: =pkgs.<name>= via =config.flake.overlayPkgs.<name>=
|
|
- Unstable packages: =pkgs.unstable.<package>=
|
|
|
|
* 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=
|
|
- org-roam-mcp is forked at =anerisgreat/org-roam-mcp= (not upstream =aserranoni/org-roam-mcp=); fork fixes: =create_node= writes directly to SQLite so new nodes are immediately searchable (no emacsclient needed), and =cli_main= is defined natively (no postPatch needed)
|
|
- emacsql stores all Emacs strings in SQLite with surrounding ="..."= — the Python DB layer strips these with =_clean_path=/_clean_string=
|
|
- org-roam timestamps in SQLite are Emacs =(HIGH LOW USEC PSEC)= tuples: =HIGH = secs >> 16=, =LOW = secs & 0xFFFF=
|
|
- =postPatch= in Nix derivations: alejandra reformats the indentation of multiline strings, which can change the effective shell script content
|
|
|
|
* 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-core/features/claude-skills/README.md= | skills extensibility docs |
|
|
| =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
|
|
|
|
* Subnodes
|
|
|
|
(none yet)
|