feat: agents

.gitignore

@@ -9,3 +9,222 @@ core*
 !core/
 !core.nix
 !coredns*
+
+# =============== Python.gitignore ===========================
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

AGENTS.md

@@ -28,6 +28,7 @@ High-level layout:
 ├── hosts/                       # Host-specific config
 ├── vars/                        # Shared variables
 ├── lib/                         # Helper functions
+├── agents/                      # Reusable cross-project agent files and installer
 └── secrets/                     # Agenix secret definitions
 ```
 
@@ -194,6 +195,7 @@ Before finishing, verify:
 ## References
 
 - [README.md](./README.md)
+- [agents/README.md](./agents/README.md)
 - [Justfile](./Justfile)
 - [outputs/README.md](./outputs/README.md)
 - [hosts/README.md](./hosts/README.md)

README.md

@@ -93,6 +93,10 @@ See [./home/base/tui/editors/neovim/](./home/base/tui/editors/neovim/) for detai
 
 See [./secrets](./secrets) for details.
 
+## Agents
+
+See [./agents](./agents) for my reusable cross-project agent files and installer script.
+
 ## How to Deploy this Flake?
 
 <!-- prettier-ignore -->

agents/AGENTS.md

@@ -0,0 +1,66 @@
+# RULES - Global Agent Baseline
+
+This file defines the cross-project baseline for AI coding agents. It focuses on safety, boundaries,
+and portable behavior.
+
+## 1) Instruction Priority
+
+Apply instructions in this order:
+
+1. Runtime system/developer instructions
+2. User task request
+3. Project-local policy (`AGENTS.md`, `CLAUDE.md`, repo docs)
+4. This global RULES
+
+If rules conflict, follow the higher-priority source and state the conflict briefly.
+
+## 2) Hard Safety Boundaries (MUST NOT)
+
+- MUST NOT read/write outside the approved workspace.
+- MUST NOT perform broad operations on the entire home directory.
+- MUST NOT run remote-mutating commands unless explicitly requested.
+  - Examples: `kubectl apply/delete`, `helm upgrade`, `terraform apply`, remote `ssh` mutation.
+- MUST NOT use destructive/force options unless explicitly requested.
+  - Examples: `--force`, `rm -rf`, `git reset --hard`, `git push --force`.
+- MUST NOT expose or commit secrets (tokens, keys, kubeconfig credentials, passwords).
+
+## 3) Security and Secrets Handling
+
+- Never write secret literals into tracked files.
+- Use environment variables, secret managers, or placeholders.
+- Redact sensitive output in logs and summaries.
+- For infra/IaC changes, prefer plan/eval/check before apply/switch.
+
+## 4) Scope Discipline
+
+- Keep changes strictly within requested scope.
+- Do not refactor unrelated areas unless user asks.
+- Preserve backward compatibility unless a breaking change is explicitly requested.
+
+## 5) Change Hygiene
+
+- Keep diffs minimal and reviewable.
+- Group logically related edits together.
+- Do not revert user/unrelated changes unless explicitly asked.
+- Do not claim verification you did not run.
+
+## 6) Tooling Defaults
+
+- Prefer fast discovery tools (`rg`, `fd`) where available.
+- Prefer project task runners (`just`, `make`, `task`, `npm scripts`, etc.) over ad-hoc commands
+  when equivalent.
+- If a required command is not already available, use only `nix run`, `nix shell`, the project's
+  `flake.nix`, or `shell.nix` to provide it.
+- If that is still insufficient, stop and ask the user to prepare the environment instead of using
+  any other installation method.
+
+## 7) Communication Defaults
+
+- Respond in the language the user is currently using, prefer English & Chinese.
+- Code, commands, identifiers, and code comments: English.
+- Be concise, concrete, and action-oriented.
+
+## 8) Project Overlay
+
+Project-local policy may add stricter constraints (build/test/deploy/style/ownership/environment).
+It must not weaken this baseline.

agents/README.md

@@ -0,0 +1,66 @@
+# agents
+
+This directory is a reusable home for agent-related files that can be shared across projects.
+
+The intended use is to symlink or copy files from here into different agent config directories,
+skill folders, or other agent runtimes. Treat it as a portable source of truth for important agent
+behavior and supporting materials.
+
+It is intended to be a personal collection similar in spirit to
+[`github/awesome-copilot`](https://github.com/github/awesome-copilot), but maintained for my own
+agents, workflows, and preferences.
+
+## Use Cases
+
+- shared agent rules
+- reusable prompts
+- skill definitions
+- agent templates
+- instruction packs
+- workflow notes
+- setup helpers
+- environment preparation docs
+
+## Current Files
+
+- `AGENTS.md`: baseline rules and operating constraints for agents.
+- `install-agents.py`: installs shared agent files into supported agent config directories.
+
+## Guidelines
+
+- Keep files portable across repositories when possible.
+- Prefer plain text and small reviewable files.
+- Document assumptions that downstream agent setups need to know.
+- Keep secrets and machine-specific credentials out of this directory.
+- Prefer reusable materials that can be copied, symlinked, or adapted by multiple agents.
+
+## Distribution
+
+You can:
+
+- symlink files from this directory into an agent's config or skills folder
+- copy selected files into another agent environment
+- treat this directory as the canonical source and sync outward from it
+
+## Installation
+
+Current install targets:
+
+- Codex: `AGENTS.md` -> `~/.codex/AGENTS.md`
+- OpenCode: `AGENTS.md` -> `~/.config/opencode/AGENTS.md`
+- Claude Code: `AGENTS.md` -> `~/.claude/CLAUDE.md`
+- Gemini: `AGENTS.md` -> `~/.gemini/GEMINI.md`
+
+Run:
+
+```bash
+python3 agents/install-agents.py
+```
+
+The installer handles each target independently and skips it if the destination directory does not
+already exist.
+
+## Goal
+
+Build a personal, reusable library of agent resources that is easy to share across environments and
+easy to extend over time.

agents/install-agents.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+from pathlib import Path
+
+
+def install_one(target_dir: Path, source_file: Path, target_name: str) -> None:
+    if not target_dir.exists():
+        print(f"skipped  {target_dir} (not found)")
+        return
+
+    target_file = target_dir / target_name
+
+    if target_file.exists() or target_file.is_symlink():
+        target_file.unlink()
+
+    target_file.symlink_to(source_file)
+    print(f"linked  {target_file} -> {source_file}")
+
+
+def main() -> int:
+    script_dir = Path(__file__).resolve().parent
+    agents_file = script_dir / "AGENTS.md"
+
+    if not agents_file.is_file():
+        print(f"Missing source file: {agents_file}", file=sys.stderr)
+        return 1
+
+    codex_dir = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
+    xdg_config_home = Path(os.environ.get("XDG_CONFIG_HOME", "~/.config")).expanduser()
+    opencode_dir = xdg_config_home / "opencode"
+    claude_dir = Path("~/.claude").expanduser()
+    gemini_dir = Path("~/.gemini").expanduser()
+
+    install_one(codex_dir, agents_file, "AGENTS.md")
+    install_one(opencode_dir, agents_file, "AGENTS.md")
+    install_one(claude_dir, agents_file, "CLAUDE.md")
+    install_one(gemini_dir, agents_file, "GEMINI.md")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hosts/idols-ai/preservation.nix

@@ -143,10 +143,12 @@ in
 
         # ai agents
         ".agents" # skills for all agents
+        ".config/agents"
         ".gemini"
         ".codex"
         ".config/opencode"
         ".local/share/opencode"
+        ".local/state/opencode"
         ".kimi" # kimi-cli
         ".context7" # up-to-date docs and code examples for for LLMs & agents