chore: set up codex cli agent and add documentation

.codex/requirements.md

@@ -0,0 +1,35 @@
+# Codex Agent Requirements
+
+This document provides the Codex CLI agent with authoritative project context,
+ensuring that generated plans and changes align with the mission,
+conventions, and constraints of this Nix configuration repository.
+
+## 1. Project Goals
+- Maintain and improve the Nix flake-based Home Manager and NixOS configuration
+  for Mohammed’s machines.
+- Enhance automation, readability, and maintainability of repository conventions.
+
+## 2. Scope & Constraints
+- Only modify files under version control (flake.nix, home.nix,
+  configuration.nix, docs/, dotfiles/, bin/).
+- The `.codex/` directory is git-ignored and reserved for agent workspace and
+  dynamic planning files (plans, logs, etc.).
+- Follow existing style guidelines and do not introduce external dependencies.
+- Use flakes, support multi-system outputs, and preserve backward compatibility.
+
+## 3. Coding & Commit Conventions
+- Indentation: 2 spaces, no tabs, max 80 chars per line.
+- Nix formatting: run `nix fmt` before committing.
+- Shell scripts: `set -euo pipefail`, proper shebangs, lint with `shellcheck`.
+- Commits: Conventional Commits with lower-case header ≤ 50 chars, body ≤ 72.
+
+## 4. Deliverables & Milestones
+- Add README.md with project overview and bootstrap instructions.
+- Configure CI (flake checks, formatting) and update CI workflows.
+- Modularize `home.nix` and `configuration.nix` into smaller modules.
+- Create `.codex/` workspace and dynamic planning files.
+- Add CHANGELOG.md and integrate dotfiles into Home Manager modules.
+
+## 5. Additional Context
+- See docs/CODE_REVIEW.md for a prioritized action plan and code review.
+- Use docs/ai-tasks.md for the AI backlog of future tasks.

.gitignore

@@ -9,3 +9,8 @@
 # devcontainer
 *.devcontainer
 
+# Codex session state (keep private)
+# Codex CLI agent workspace and sessions (keep private)
+sessions/*.json
+.codex/
+

CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+- 

codex.md

@@ -0,0 +1,161 @@
+# 🦜🔗 Codex Instructions for Mohammed’s Nix Configuration
+
+> **Note:** Using model `codex-mini-latest`, provider `openai`, approval mode `suggest`
+>
+> **Recommended:** add `alias codex='op run --no-masking -- codex'` to your
+> shell profile for automatic API‑key lookup.
+
+## 🤖 Agent Behavior
+
+- You are an agent—keep going until the user’s query is completely resolved.
+  Only end your turn when you are sure that the problem has been solved.
+- If you are not sure about file content or codebase structure pertaining to
+  the user’s request, use your tools to read files and gather the relevant
+  information; do NOT guess or make up an answer.
+- You MUST plan extensively before each function call and reflect on the
+  outcomes of previous calls. DO NOT perform the entire process by making
+  function calls only, as this may impair your ability to solve the problem
+  and think insightfully.
+
+## 🏗️ Agentic Workflow
+
+Introduce a top-level `.codex/` workspace for agent state, including:
+- A high-level `requirements.md` file outlining goals, conventions, and scope.
+- Dated planning files (e.g., `.codex/plan_YYYY-MM-DD.md`) to track milestones.
+- Changelog entries in `CHANGELOG.md` for significant completed work.
+
+## ⚙️ Modes of interaction
+
+- **Interactive mode:** propose each milestone or change and await your
+  approval before proceeding.
+- **Full-auto mode:** execute the whole plan without pausing, then summarize
+  all work for your review.
+
+## 📚 Project Overview
+
+This repository contains Nix flakes for configuring:
+
+- **Home Manager**: user-level dotfiles, packages, and environment.
+- **NixOS system**: machine-level configuration.
+
+We use a single `flake.nix` to generate Home Manager configurations for
+Mohammed’s machines and a NixOS system configuration under
+`nixosConfigurations`.
+
+## 🛠️ Setup & Development Shell
+
+Prerequisites: Nix with flakes support, `nix-direnv`, and `direnv`.
+
+```bash
+# Enable nix-direnv integration
+# Install nix-direnv and direnv if needed, then add to .envrc:
+use flake .
+direnv allow
+```
+
+To apply your Home Manager configuration:
+
+```bash
+home-manager switch --flake .#mohammed
+```
+
+To build and deploy the NixOS system:
+
+```bash
+sudo nixos-rebuild switch --flake .#nixos
+```
+
+## 🌲 Repository Structure
+
+```
+.
+├── bin/
+├── configuration.nix
+├── docs/
+│   ├── CODE_REVIEW.md
+│   └── ai-tasks.md
+├── dotfiles/
+├── sessions/
+├── flake.nix
+├── flake.lock
+├── home.nix
+├── setup.sh
+├── treefmt.nix
+└── .editorconfig
+```
+
+## 🎯 Style & Conventions
+
+- **Indentation:** 2 spaces, no tabs, max 80 chars per line.
+- **Nix Formatting:** run `nix fmt`.
+- **Shell scripts:** `set -euo pipefail`, proper shebangs, linted by `shellcheck`.
+- **Commits:** Conventional Commits (header ≤ 50 chars in lower-case,
+  body ≤ 72 chars).
+- **Code blocks:** annotate with language comments for syntax highlighting.
+
+## 🔨 Common Tasks
+
+| Task                            | Command                                  |
+|---------------------------------|------------------------------------------|
+| Format Nix code                 | `nix fmt`                                |
+| Run flake checks                | `nix flake check`                        |
+| Apply Home Manager config       | `home-manager switch --flake .#mohammed` |
+| Build NixOS system              | `sudo nixos-rebuild switch --flake .#nixos` |
+
+## ⚓ PR Merge Strategy
+
+See `docs/pr-merge-strategy.md` for details on GitHub pull-request merge
+strategies. We recommend using **squash and merge** for this repository to
+produce a clean, linear history.
+
+## 📋 Outstanding AI‑Backlog
+
+Use Codex to work on these tasks. Example:
+
+```bash
+codex --project-doc docs/ai-tasks.md "Implement README.md and bootstrap docs"
+```
+
+- [ ] Add README.md with project purpose, prerequisites, and instructions.
+- [ ] Add CI workflows for flake checks and formatting.
+- [ ] Improve `setup.sh` for automated bootstrap.
+- [ ] Modularize `home.nix` and `configuration.nix` into smaller modules.
+- [ ] Automate flake updates with a helper script.
+- [ ] Integrate dotfiles into Home Manager modules.
+- [ ] Lint and document scripts in `bin/`.
+- [ ] Audit repository for any sensitive data.
+- [ ] Review and refine `treefmt.nix` excludes.
+
+## 🗒️ AI Session Workflow
+
+At the end of each AI session, summarize completed tasks and outstanding todos:
+
+```bash
+codex -q "Summarize this session's completed tasks and outstanding todos" \
+  > docs/ai-tasks.md
+```
+
+At the start of a new session, recap last session:
+
+```bash
+codex -q "Summarize the last session's completed tasks and next steps"
+```
+
+## 🔄 Resume last AI session
+
+```bash
+codex --view sessions/last.json
+```
+
+## 🤖 How to invoke Codex
+
+```bash
+# Interactive (auto-loads codex.md):
+codex "Refactor Nix flakes configuration"
+
+# Full-context batch refactor:
+codex --full-context "Update style conventions in codex.md"
+```
+
+*This file is maintained by the Codex CLI agent. Do not edit manually unless
+updating agent configuration.*