#+TITLE: JawZ NixOS Configuration
#+AUTHOR: JawZ
#+EMAIL: danilo.reyes.251@proton.me
#+OPTIONS: toc:t num:t
#+STARTUP: content

* Overview

This repository is a NixOS configuration flake with a local MCP server
(`nixos-mcp`) that helps Codex CLI work with the repo’s documentation and
maintenance workflows. The README focuses on how to use the MCP server and
how the repo is structured.

* MCP Server (nixos-mcp)

** What it is
Local-only MCP server that exposes repo documentation helpers over stdio so
Codex CLI can read the constitution, playbooks, and reference map without
manual navigation.

** Tool Catalog
- =show-constitution= :: Open =docs/constitution.md=
- =list-playbooks= :: List =docs/playbooks/=
- =show-reference= :: Open =docs/reference/index.md=
- =search-docs= :: Search the docs set
- =list-mcp-tasks= :: Show MCP tasks from =specs/002-mcp-server/tasks.md=
- =sync-docs= :: Check tool catalog vs. docs anchors

** Quick Start (new users)
#+BEGIN_SRC bash
# Enter the MCP dev shell (includes codex + nixos-mcp)
nix develop .#mcp

# Run the MCP server (stdio mode)
nixos-mcp
#+END_SRC
Configure Codex CLI to use a local stdio MCP endpoint and allowlist
=nixos-mcp= in =.codex/requirements.toml=. The dev shell sets
=CODEX_HOME=.codex= for a repo-local Codex config.

** Reference
Detailed invocation notes live in =docs/reference/mcp-server.md=.

* Repository Structure

** Docs and Guidance
- =docs/constitution.md= :: AI constitution (authoritative rules)
- =docs/reference/index.md= :: Reference map
- =docs/reference/mcp-server.md= :: MCP server reference
- =docs/playbooks/= :: Repeatable workflows
- =specs/002-mcp-server/= :: MCP feature plan + tasks

** MCP Server
- =scripts/mcp-server/= :: Python MCP server implementation, tests, and CLI
- =modules/dev/mcp.nix= :: Dev shell and optional global install

** Flake Parts
- =parts/core.nix= :: Shared library + base composition
- =parts/hosts.nix= :: Host definitions
- =parts/packages.nix= :: Package outputs
- =parts/devshells.nix= :: Dev shells (including MCP)

* Flake Inputs (high level)

** Core Inputs
- =nixpkgs= (25.11) and =nixpkgs-small= (25.11-small)
- =nixpkgs-unstable= (rolling)
- =flake-parts= (structure)
- =home-manager= (user configs)
- =stylix= (theming)
- =sops-nix= (secrets integration)
- =nur=, =nix-gaming=, =hyprland= (extra packages)
- Content inputs: =wallpapers=, =fonts=, =qbit_manage=
- Repo inputs: =jawz-scripts=, =prem2resolve=, =lidarr-mb-gap=
- Check service-specific documentation

* Maintenance

** Regular Tasks
- Update flake inputs weekly
- Review and rotate secrets quarterly
- Update system packages monthly
- Clean old generations: =sudo nix-collect-garbage -d=

** Backup Strategy
- Configuration is version controlled
- Secrets are encrypted and backed up
- BTRFS snapshots for data protection

* Contributing

** Code Style
- Use consistent formatting
- Add comments for complex configurations
- Follow Nix conventions

** Pull Requests
- Test changes on development host first
- Update documentation as needed
- Ensure all secrets are properly managed

* License

This configuration is for personal use. Please respect the licenses of
individual packages and services used.

* Contact

For questions or issues, contact danilo.reyes.251@proton.me

---

*Last updated: 2025*