AGENTS.md (Project)

This is fmind/dot — chezmoi + mise dotfiles for AI-CLI-first, Python-first development on Linux and macOS. Setup, usage, and common tasks live in README.md.

House rules

• Edit chezmoi sources, never deployed copies: change this repository, not files under $HOME; automation runs chezmoi apply --force. Naming, templates, and secrets: chezmoi skill.
• Treat this repository as public — never leak information: Never put customer or employer names, domains, emails, project or account IDs, repo or service names, hostnames, local paths, or details from untracked configs (~/.config/dot.yaml, ~/.config/git/config.*). Use only synthetic fixtures on fmind.dev, fmind.ai, or RFC 2606 domains (@example.com, @example.test).
• Never commit decrypted secrets: *.age files stay encrypted; never write plaintext secrets to the source tree, diffs, logs, or command arguments. Native credentials are create-only seeds; scoped keys use dot secret run and preserve account overrides (Secret Management).
• Match validation to the task: read-only reviews need only evidence checks; doc and instruction edits need formatting, link, and contract checks (mise run check:skills); behavior changes need focused pytest runs and affected static checks. mise run doctor checks local workstation health (dot, chezmoi, and mise); mise run check, test, and all validate the repository (all runs whole-tree gates without rewriting files, while mise run format writes the tree — isolate formatting when unrelated edits are present; run all for cross-cutting changes, dependencies, packaging, releases, or full qualification). Reuse passing results while inputs remain unchanged.
• Parallelize independent CLI probes: use run_parallel (fmind_dot.process) for independent subprocess, repository, and tool checks so dot stays synchronous while bounding concurrent I/O and preserving deterministic output order.
• Never use sudo: stay user-space; install via mise.
• Choose global tools for agent coding: dot_config/mise/config.toml serves AI-agent coding (harnesses, service connectors, and cross-project CLIs agents run), plus a few human review/shell tools (LazyVim, lazygit, lazydocker, the macOS Docker stack, Fish, Zellij). Pin project tools in their project; keep one global only when it must work outside projects (such as formatters and linters LazyVim runs on any file) and state why in its comment; a global copy never replaces a project pin.
• Lock tools with mise, never edit generated locks: use mise lockfile revision 4 and keep dot_config/mise/mise.lock with its referenced locks/ dependency graphs; never hand-edit or format generated locks. mise run lock resolves the portable baseline in isolation, and mise run lock:tool TOOL... bumps only the named global tools (clear a stale mise latest TOOL with mise cache clear first); mise run full installs with --locked; Python dependencies lock in dot/uv.lock.
• Keep README for users; workflows go in skills: keep setup, auth, everyday usage, and the short task table in README.md; put contributor workflows in skills and sync docs via repository-docs.
• Pin themes and terminal defaults: fmind/theme owns the palette, native app files, and ~/.agents/DESIGN.md. Fetch standalone themes via .chezmoiexternal.toml.tmpl pinned to one commit with SHA-256 checksums (mise run upgrade advances the pin); when tools require merged styles, copy only the native theme block with an upstream source comment. Terminal tools follow the Ghostty ANSI palette, inherit GoogleSansCode Nerd Font Mono from Ghostty, and enable Vim mode in every TUI that supports it.

Workflows

See common tasks; mise tasks lists all tasks and aliases (mise run <task>, or ~/.local/bin/mise if not in $PATH; running from dot/ resolves to the root tasks).

• Iterate: edit source → run focused checks → mise run diff → mise run apply when deployment is in scope (runs eligible hooks and writes managed files). Lefthook runs commit/push checks; CI runs the full gate.
• Add or upgrade tools: for project pins see mise; for global tools insert into [tools] in dot_config/mise/config.toml alphabetically within its group (backend-prefixed entries, registry names, then per-platform tables) → mise run lock → mise run full. mise run upgrade upgrades this workstation's dependencies, tools, theme pin, and plugins only; upgrade other repos separately per upgrade-tools.
• CLI (dot) & workstation: follow dot-development for implementation, tests, and installation proof, dot-cli for dot login, setup, cache, prune, and workspace commands (explicit commands, never apply hooks), and agent usage for usage reports.
• Completions: mise run completions installs Fish completions from the deployed CLI; mise run check:completions runs outside all and gates releases.
• Skills: dot-skills owns catalog changes, links, and check:skills; skillify owns authoring and admission.
• Verify & release: dot-verify qualifies the checkout without committing; /dot-release runs dot-verify, commits, pushes, and follows dot-release for mise run release and publication checks.

Layout

• dot/: Python CLI package (fmind_dot), repo-only dot_tasks/, uv.lock, and pytest suite.
• dot_agents/AGENTS.md: global persona deployed to ~/.agents/AGENTS.md for all harnesses; dot_gemini/ (agy, primary), dot_claude/, dot_copilot/, and dot_config/opencode/ adapt it per host (other host state is gitignored). No custom subagent roles are deployed; see cross-harness agents.
• skills/ & .agents/skills/: global catalog (linked into ~/.agents/skills/) and repo-local skills (.claude/skills links to .agents/skills).
• .chezmoitemplates/ & .chezmoiignore: JSON/TOML merge, shell block, skill-catalog, and dot-path helpers; .chezmoiignore gates repo-only, OS/Crostini-specific (including darwin-only .docker and .zprofile), and age-key-dependent targets.
• .github/: CI, release, security, and dependency automation; .github/assets/ holds the README's SVG diagrams.
• Mise trust stays machine-local (mise trust or unmanaged ~/.config/mise/conf.d/trust.toml); apply's run_after_dot-trust hook pre-trusts configured workspaces and this checkout in the coding harnesses, not in mise.