backup: 2026-06-17 07:36

azos.org

@@ -7,56 +7,9 @@
 
 * Architecture
 
-azos is a NixOS/home-manager configuration repo with a two-tier feature system:
+Two-tier NixOS/home-manager feature system: =azos-core/= (shared submodule) + =features/= (machine-specific). Features auto-discovered via =import-tree=, collected into =config.flake.modules=.
 
-- =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
+See [[id:36fe6a01-ea1f-4785-8516-f6dcfecf05bb][azos/architecture]] for module registration, option namespace, file deployment, and Claude Code wiring.
 
 * Conventions
 
@@ -70,16 +23,21 @@ Three azos-core features wire up Claude Code:
 - Packages in overlay: =pkgs.<name>= via =config.flake.overlayPkgs.<name>=
 - Unstable packages: =pkgs.unstable.<package>=
 
+** Writing Claude Skills
+
+Skill descriptions are routing keys — they determine whether a skill activates. Guidelines (ref: https://stevekinney.com/writing/agent-skills):
+- Open with =TRIGGER on:= and numbered conditions so activation is unambiguous
+- One specific job per skill; overlapping descriptions cause routing competition
+- Scope exclusions: state what the skill does NOT replace to prevent false positives
+- Domain-specific language; no generic phrases like "helps with X"
+
 * 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
+- =postPatch= in Nix derivations: alejandra reformats indentation of multiline strings, which can change effective shell script content
 
 * Key Files
 
@@ -89,21 +47,11 @@ Three azos-core features wire up Claude Code:
 | =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
+| =~/.claude/settings.json= | Claude Code global permissions; always-allowed org-roam MCP tools listed here |
 
 * Subnodes
 
-(none yet)
+- [[id:36fe6a01-ea1f-4785-8516-f6dcfecf05bb][azos/architecture]] — module registration, option namespace, file deployment, Claude Code wiring
+- [[id:c945da4f-de5c-4eb8-bd99-810576a2545a][azos/org-roam]] — setup, MCP server, SQLite internals, fork details