From cf976ae14afa540670e0bdc55dffdfe47a8e42bc Mon Sep 17 00:00:00 2001
From: Aner Zakobar <aner@zakobar.com>
Date: Sun, 7 Jun 2026 00:48:20 +0300
Subject: [PATCH] Claude memory, second brain, skills

---
 AGENTS.md                   | 186 ++++++++++++++++++++++++------------
 CLAUDE.md                   |   1 +
 azos-core                   |   2 +-
 features/claude/default.nix |   2 +
 home-manager/home.nix       |   2 +
 5 files changed, 131 insertions(+), 62 deletions(-)
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
index 853742a..c53805e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -70,76 +70,111 @@ emacsclient -c -e '(switch-to-buffer (get-buffer-create "test"))'
 emacsclient -e '(message "hello")'
 ```
 
-## Code Style Guidelines
+## Repository Structure
 
-### File Organization
-- **Home-manager modules**: `modules/home-manager/<name>.nix`
-- **NixOS modules**: `modules/nixos/<name>.nix`
-- **Imports**: All modules in `modules/home-manager/default.nix` and `modules/nixos/default.nix` (alphabetical order)
-- **Home config**: `home-manager/home.nix` - main home-manager user config
-- **Custom packages**: `pkgs/` - custom package definitions
-- **Overlays**: `overlays/` - package overlays (addpkgs, modifications, unstable-packages)
+```
+azos/
+├── flake.nix                  # Main flake
+├── home-manager/home.nix      # Home-manager entry point; manually imports all modules
+├── _machines/                 # Per-machine NixOS configs (pass suiteModules as specialArgs)
+├── nixos/                     # NixOS system configs (configuration.nix, configuration-vm.nix, etc.)
+├── features/                  # Machine-specific home-manager features (auto-discovered)
+├── overlays/                  # Package overlays
+├── shells/                    # Dev shells
+└── azos-core/                 # Shared feature library (git submodule)
+    ├── flake.nix
+    ├── features/              # Shared/reusable features (auto-discovered)
+    ├── overlays/              # Core overlays
+    └── _lib/                  # Module schema helpers
+```
+
+Features are auto-discovered by `import-tree` — no central imports file. Each feature's
+`default.nix` registers itself via `config.flake.modules.homeManager.<name>`. Modules are
+then explicitly imported in `home-manager/home.nix` via `suiteModules.homeManager.<name>`.
+
+**Where to put a new feature:**
+- Shared / reusable across machines → `azos-core/features/<name>/default.nix`
+- Machine-specific → `azos/features/<name>/default.nix`
+
+## Code Style Guidelines
 
 ### Nix Module Template
 
-```nix
-{
-  lib,
-  config,
-  pkgs,
-  ...
-}: let
-  isEnabled =
-    config.azos.<module-name>.enable;
-in {
-  options.azos.<module-name>.enable = lib.mkOption {
-    default = true;
-    example = true;
-    type = lib.types.bool;
-  };
+All features follow this flake-parts registration pattern:
 
-  config = lib.mkIf isEnabled {
-    home.packages = with pkgs; [ pkg1 pkg2 ];
+```nix
+{...}: {
+  config.flake.modules.homeManager.<name> = {
+    lib,
+    config,
+    pkgs,
+    ...
+  }: {
+    options.azos.<name>.enable = lib.mkOption {
+      default = false;
+      example = true;
+      type = lib.types.bool;
+    };
+
+    config = lib.mkIf config.azos.<name>.enable {
+      home.packages = with pkgs; [pkg1 pkg2];
+    };
   };
 }
 ```
 
 ### Naming Conventions
-- Option paths: `config.azos.<module-name>.<option>`
-- Enable option: `enable` (bool), default `true`
-- Module names: kebab-case (`libreoffice.nix`, `git-config.nix`)
-- Option names: may differ from filename (e.g., `git.nix` uses `azos.git-config`)
-- Variables: kebab-case (`isEnabled`)
+- Option paths: `azos.<module-name>.<option>`
+- Module names: kebab-case (`git-config`, `claude-memory`)
+- Feature directories: kebab-case, one `default.nix` per feature
+- Variables: kebab-case
 
 ### Formatting
 - Indentation: 2 spaces
-- Let bindings: multi-line with `isEnabled` on its own line
-- Packages: Use `with pkgs; [ ... ]` syntax
+- Packages: `with pkgs; [pkg1 pkg2]` (no trailing semicolon inside list)
 
 ### Imports
-- Always include `{...}` for module args
-- Standard args: `lib, config, pkgs, ...`
-- NixOS config args: `inputs, outputs, lib, config, pkgs, ...`
-- Use `./relative/path.nix` for local imports
+- Always include `{...}` for the outer module args
+- Inner module args: `lib, config, pkgs, ...`
 
 ### Option Patterns
-- Boolean enable: `lib.mkOption { default = true; example = true; type = lib.types.bool; }`
-- Conditional config: `lib.mkIf isEnabled { ... }`
-- User-overridable: `lib.mkDefault`
+- Boolean enable: `lib.mkOption { default = false; example = true; type = lib.types.bool; }`
+- Conditional config: `lib.mkIf config.azos.<name>.enable { ... }`
+- Auto-enable a dependency: `azos.<dep>.enable = lib.mkDefault true;`
 - Force value: `lib.mkForce` (sparingly)
 
+### Extensible Options
+For options that multiple modules should be able to contribute to, use attrset options:
+
+```nix
+options.azos.<name>.things = lib.mkOption {
+  default = {};
+  type = lib.types.attrsOf lib.types.path;  # or lines, str, etc.
+};
+```
+
+Any module can then add entries without modifying the owning feature. Examples in use:
+- `azos.claude.globalSkills` — attrset of skill name → markdown file path
+- `azos.claude.globalMdSections` — attrset of key → markdown string (merged into `~/.claude/CLAUDE.md`)
+
 ### Home-Manager vs NixOS
 - Home-manager: `home.packages`, `home.file`, `programs.<program>`
 - NixOS: `config.services`, `environment.systemPackages`
 
+### Deploying Files
+- Static file: `home.file."dest".source = ./file;`
+- Generated text: `home.file."dest".text = "...";`
+- Runtime script (e.g. merging JSON at activation): `home.activation.<name> = lib.hm.dag.entryAfter ["writeBoundary"] ''...'';`
+
 ### Suites System
-Modules are organized into suites (defined in `azos-core/`):
-- `azos.suites.base` - Base packages and config
-- `azos.suites.editor` - Editor tools
-- `azos.suites.dev` - Development tools
-- `azos.suites.station` - Desktop applications
-- `azos.suites.exwm` - EXWM window manager
-- Enable in `home-manager/home.nix` with `azos.suites.<name>.enable = true;`
+Top-level suites group related features (defined in `azos-core/`):
+- `azos.suites.base` — base packages and config
+- `azos.suites.editor` — editor tools
+- `azos.suites.dev` — development tools
+- `azos.suites.station` — desktop applications
+- `azos.suites.exwm` — EXWM window manager
+
+The machine suite (`azos.suites.lauretta`) enables the relevant suites for this machine.
 
 ### Specializations
 NixOS supports specializations for alternative configurations:
@@ -158,33 +193,62 @@ specialisation = {
 
 ## Adding New Modules
 
-1. Create file in `modules/home-manager/` or `modules/nixos/`
-2. Add import to `modules/<type>/default.nix` (alphabetical)
-3. Use module template above
+1. Create `features/<name>/default.nix` (machine-specific) or `azos-core/features/<name>/default.nix` (shared)
+2. Use the module template above
+3. Add `suiteModules.homeManager.<name>` to the imports list in `home-manager/home.nix`
 4. Run `nix fmt`
 
+> **Submodule gotcha**: New files in `azos-core/` must be `git add`-ed inside the submodule
+> before `nix build` will see them — Nix flakes only evaluate git-tracked files.
+> ```bash
+> cd azos-core && git add features/<name>/
+> ```
+
+## Claude Integration
+
+Claude Code is integrated with this environment via several azos-core features:
+
+| Feature | Option | What it does |
+|---------|--------|--------------|
+| `azos-core/features/claude-memory` | `azos.claude-memory.enable` | Registers org-roam-mcp as a global MCP server in `~/.claude.json` |
+| `azos-core/features/claude-skills` | `azos.claude-skills.enable` | Deploys skills to `~/.claude/commands/` and content to `~/.claude/CLAUDE.md` |
+| `azos/features/claude` | `azos.claude.enable` | Installs claude-code, auto-enables the above two |
+
+### Adding Claude skills or standing instructions
+From any module — no need to touch azos-core:
+```nix
+azos.claude.globalSkills.my-skill = ./skills/my-skill.md;
+azos.claude.globalMdSections.my-rule = ''
+  # My Rule
+  Always do X when Y.
+'';
+```
+See `azos-core/features/claude-skills/README.md` for full documentation.
+
 ## Key Files
 
 | File | Purpose |
 |------|---------|
-| `flake.nix` | Main flake, defines systems, overlays |
-| `modules/home-manager/default.nix` | Home-manager imports |
-| `modules/nixos/default.nix` | NixOS imports |
-| `home-manager/home.nix` | User home-manager config, enables suites |
-| `nixos/configuration.nix` | Lauretta laptop config |
+| `flake.nix` | Main flake, defines systems and overlays |
+| `home-manager/home.nix` | Home-manager entry point, imports all modules |
+| `_machines/lauretta.nix` | Lauretta machine config, passes `suiteModules` as specialArgs |
+| `nixos/configuration.nix` | Lauretta NixOS system config |
 | `nixos/configuration-vm.nix` | Test VM config |
-| `overlays/` | Custom package overlays |
-| `pkgs/` | Custom packages |
-| `azos-core/` | Shared modules (submodule) |
+| `overlays/` | Package overlays |
+| `azos-core/` | Shared feature library (git submodule) |
+| `azos-core/features/` | Shared features (auto-discovered by import-tree) |
+| `features/` | Machine-specific features (auto-discovered by import-tree) |
+| `azos-core/features/editor/emacs/config.org` | Literate Emacs config |
+| `azos-core/features/claude-skills/README.md` | Claude skills extensibility docs |
 
 ## Common Tasks
 
-**Add system package**: Edit NixOS module, add to `environment.systemPackages = with pkgs; [ pkg ]`
+**Add system package**: Edit a NixOS feature, add to `environment.systemPackages = with pkgs; [ pkg ]`
 
-**Add home-manager package**: Edit module, add to `home.packages = with pkgs; [ pkg ]`
+**Add home-manager package**: Edit a feature's config block, add to `home.packages = with pkgs; [ pkg ]`
 
-**Add system service**: Edit NixOS module, add under `services.<service>`
+**Add system service**: Edit a NixOS feature, add under `services.<service>`
 
-**Add custom package**: Create file in `pkgs/`, add to `pkgs/default.nix`, use via overlay
+**Add custom package**: Add to `azos-core/overlays/` via `config.flake.overlayPkgs.<name>`, then use as `pkgs.<name>`
 
 **Access unstable packages**: Use `pkgs.unstable.<package>` (via unstable-packages overlay)
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/azos-core b/azos-core
index 63e7666..4351ff8 160000
--- a/azos-core
+++ b/azos-core
@@ -1 +1 @@
-Subproject commit 63e76667b021f7198195d355ecaf60645a1c98d1
+Subproject commit 4351ff8bd098b459f91a2a7787fa6cedddb3a03a
diff --git a/features/claude/default.nix b/features/claude/default.nix
index 4ac5c5f..a0c74fa 100644
--- a/features/claude/default.nix
+++ b/features/claude/default.nix
@@ -11,6 +11,8 @@
     };
     config = lib.mkIf config.azos.claude.enable {
       home.packages = with pkgs; [claude-code claude-agent-acp];
+      azos.claude-memory.enable = lib.mkDefault true;
+      azos.claude-skills.enable = lib.mkDefault true;
     };
   };
 }
diff --git a/home-manager/home.nix b/home-manager/home.nix
index f397ac9..691bee8 100755
--- a/home-manager/home.nix
+++ b/home-manager/home.nix
@@ -16,6 +16,8 @@
     suiteModules.homeManager.lauretta
     suiteModules.homeManager.audio
     suiteModules.homeManager.claude
+    suiteModules.homeManager.claude-memory
+    suiteModules.homeManager.claude-skills
     suiteModules.homeManager.encryption
     suiteModules.homeManager.git-config
     suiteModules.homeManager.hfsprogs