docs: update claude setup

refactor: Move some things to roles
refactor: fix some linting

CLAUDE.md

@@ -2,41 +2,62 @@
 
 ## Session Start
 
-Read the latest handoff in docs/summaries/ if one exists. Load only the files that handoff references — not all summaries. If no handoff exists, ask: what is the project, what type of work, what is the target deliverable.
+Check `docs/summaries/` for a handoff file. If one exists, read it and the files it references — not all summaries. State: what you understand the project state to be, what you plan to do, and open questions.
 
-Before starting work, state: what you understand the project state to be, what you plan to do this session, and any open questions.
+If no handoff exists, determine session type before proceeding:
+- **Quick task**: single-session, self-contained work (adding a playbook, fixing a role, configuring a service) → proceed without setup overhead
+- **Sustained work**: multi-session project or significant design work → ask: what is the goal and what is the target deliverable
 
 ## Identity
 
-You work with Pat, a Senior Solutions Architect at Red Hat building automation for a HomeLab.
+You work with Pat, a Senior Solutions Architect at Red Hat building automation for a HomeLab. Expert-level Ansible knowledge — do not explain Ansible basics.
+
+## Project
+
+**Repo:** Ansible playbooks and roles managing a full HomeLab — Proxmox, OPNsense, OpenShift (SNO), AAP, Satellite, Gitea, and services.
+**Inventory:** `/home/ptoal/Dev/inventories/toallab-inventory/static.yml`
+**Run locally:** `ansible-navigator run playbooks/<name>.yml --mode stdout`
+**Run with extra vars:** `ansible-navigator run playbooks/<name>.yml --mode stdout -e key=value`
+**Lint:** `ansible-navigator lint playbooks/ --mode stdout`
+**Collections:** `ansible-galaxy collection install -r collections/requirements.yml`
+**Production:** playbooks run via AAP — do not refer to AWX
+
+Load `docs/context/project-structure.md` when working on playbooks or roles.
 
 ## Rules
 
 1. Do not mix unrelated project contexts in one session.
-2. Write state to disk, not conversation. After completing meaningful work, write a summary to docs/summaries/ using templates from templates/claude-templates.md. Include: decisions with rationale, exact numbers, file paths, open items.
-3. Before compaction or session end, write to disk: every number, every decision with rationale, every open question, every file path, exact next action.
-4. When switching work types (research → writing → review), write a handoff to docs/summaries/handoff-[date]-[topic].md and suggest a new session.
+2. For sustained work: write state to disk after completing meaningful work. Use templates from `templates/claude-templates.md`. Include: decisions with rationale, exact numbers, file paths, open items.
+3. For sustained work: before compaction or session end, write to disk — every number, every decision with rationale, every open question, every file path, exact next action.
+4. For sustained work: when switching work types (development → documentation → review), write a handoff to `docs/summaries/handoff-[date]-[topic].md` and suggest a new session.
 5. Do not silently resolve open questions. Mark them OPEN or ASSUMED.
-6. Do not bulk-read documents. Process one at a time: read, summarize to disk, release from context before reading next. For the detailed protocol, read docs/context/processing-protocol.md.
-7. Sub-agent returns must be structured, not free-form prose. Use output contracts from templates/claude-templates.md.
+6. Do not bulk-read documents. Process one at a time: read, summarize to disk, release from context before reading next. For the detailed protocol, read `docs/context/processing-protocol.md`.
+7. Sub-agent returns must be structured, not free-form prose. Use output contracts from `templates/claude-templates.md`.
 
 ## Where Things Live
 
-- templates/claude-templates.md — summary, handoff, decision, analysis, task, output contract templates (read on demand)
-- docs/summaries/ — active session state (latest handoff + project brief + decision records + source summaries)
-- docs/context/ — reusable domain knowledge, loaded only when relevant to the current task
-  - processing-protocol.md — full document processing steps
-  - archive-rules.md — summary lifecycle and file archival rules
-- playbooks/ -- Main ansible playbooks
-- roles/ -- Both custom, and external Ansible roles
-- collections/ -- should only contain requirements.yml
-- docs/archive/ — processed raw files. Do not read unless explicitly told.
-- output/deliverables/ — final outputs
+- `templates/claude-templates.md` — summary, handoff, decision, analysis, task, output contract templates (read on demand)
+- `docs/summaries/` — active session state (latest handoff + decision records + source summaries)
+- `docs/context/` — reusable domain knowledge, loaded only when relevant
+  - `project-structure.md` — playbook inventory, roles, collections, infrastructure map
+  - `processing-protocol.md` — full document processing steps
+  - `archive-rules.md` — summary lifecycle and file archival rules
+  - `subagent-rules.md` — when to use subagents vs. main agent
+- `.claude/agents/` — specialized subagents (ansible-idempotency-reviewer — use before adding tasks or before production runs)
+- `playbooks/` — main Ansible playbooks
+- `roles/` — custom and external Ansible roles
+- `collections/` — `requirements.yml` only; installed collections in `collections/ansible_collections/`
+- `docs/archive/` — processed raw files. Do not read unless explicitly told.
+- `output/deliverables/` — final outputs
+
+For cross-project user preferences, recurring constraints, or tool preferences: use Claude Code's native memory system, not `docs/summaries/`.
 
 ## Error Recovery
 
-If context degrades or auto-compact fires unexpectedly: write current state to docs/summaries/recovery-[date].md, tell the user what may have been lost, suggest a fresh session.
+If context degrades or auto-compact fires unexpectedly: write current state to `docs/summaries/recovery-[date].md`, tell the user what may have been lost, suggest a fresh session.
 
 ## Before Delivering Output
 
-Verify: exact numbers preserved, open questions marked OPEN, output matches what was requested (not assumed), claims backed by specific data, output consistent with stored decisions in docs/context/, summary written to disk for this session's work.
+Verify: exact numbers preserved, open questions marked OPEN, output matches what was requested (not assumed), no Ansible idempotency regressions introduced.
+
+All Ansible files (playbooks, task files, templates, vars) must end with a trailing newline.