114 lines
3.2 KiB
Org Mode
114 lines
3.2 KiB
Org Mode
#+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*
|