From b1de91a969290ce3c766ec1bc159c0c4105d432e Mon Sep 17 00:00:00 2001
From: Username <user@mymx.me>
Date: Tue, 17 Feb 2026 23:19:54 +0100
Subject: [PATCH] docs: update CLAUDE.md for playbook-based deployment

Document WireGuard connectivity, playbook architecture, --check
flag, parallel execution, and updated ad-hoc ansible commands
using toolkit inventory.
---
 CLAUDE.md | 49 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 33 insertions(+), 16 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index cd26b9a..160a16b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -37,30 +37,47 @@ All deployment and service management is handled by `tools/`:
 
 ```
 tools/
-  lib/ppf-common.sh     shared library (hosts, wrappers, colors)
-  ppf-deploy            deploy code to nodes
-  ppf-logs              view container logs
-  ppf-service           manage containers (status/start/stop/restart)
+  lib/ppf-common.sh           shared library (hosts, wrappers, colors)
+  ppf-deploy                   deploy wrapper (local validation + playbook)
+  ppf-logs                     view container logs
+  ppf-service                  manage containers (status/start/stop/restart)
+  playbooks/
+    deploy.yml                 ansible playbook (sync, compose, restart)
+    inventory.ini              hosts with WireGuard IPs + SSH key
+    group_vars/
+      all.yml                  shared vars (ppf_base, ppf_owner)
+      master.yml               odin paths + compose file
+      workers.yml              worker paths + compose file
 ```
 
 Symlinked to `~/.local/bin/` for direct use.
 
+### Connectivity
+
+All tools connect over WireGuard (`10.200.1.0/24`) as user `ansible`
+with the SSH key at `/opt/ansible/secrets/ssh/ansible`.
+
 ### Deployment
 
+`ppf-deploy` validates syntax locally, then runs the Ansible playbook.
+Hosts execute in parallel; containers restart only when files change.
+
 ```bash
 ppf-deploy                  # all nodes: validate, sync, restart
 ppf-deploy odin             # master only
 ppf-deploy workers          # cassius, edge, sentinel
 ppf-deploy cassius edge     # specific hosts
 ppf-deploy --no-restart     # sync only, skip restart
+ppf-deploy --check          # dry run (ansible --check --diff)
+ppf-deploy -v               # verbose ansible output
 ```
 
-Steps performed automatically:
-1. Validate Python syntax locally
-2. Rsync `*.py` + `servers.txt` (root for odin, `src/` for workers)
-3. Copy compose file per role (`compose.master.yml` / `compose.worker.yml`)
-4. Fix ownership (`chown -R podman:podman`)
-5. Restart containers and show status
+Playbook steps (per host, in parallel):
+1. Rsync `*.py` + `servers.txt` (role-aware destination via group_vars)
+2. Copy compose file per role (`compose.master.yml` / `compose.worker.yml`)
+3. Fix ownership (`podman:podman`, recursive)
+4. Restart containers via handler (only if files changed)
+5. Show container status
 
 ### Container Logs
 
@@ -83,19 +100,19 @@ ppf-service start workers   # start all workers
 
 ### Direct Ansible (for operations not covered by tools)
 
-Tools use `/opt/ansible` venv and `ANSIBLE_REMOTE_TMP=/tmp/.ansible`
-internally. For ad-hoc operations:
+Use the toolkit inventory for ad-hoc commands over WireGuard:
 
 ```bash
 cd /opt/ansible && source venv/bin/activate
+INV=/home/user/git/ppf/tools/playbooks/inventory.ini
 
 # Check worker config
-ANSIBLE_REMOTE_TMP=/tmp/.ansible ansible cassius,edge,sentinel \
-  -m shell -a "grep -E 'threads|timeout|ssl' /home/podman/ppf/config.ini"
+ansible -i $INV workers -m shell \
+  -a "grep -E 'threads|timeout|ssl' /home/podman/ppf/config.ini"
 
 # Modify config option
-ANSIBLE_REMOTE_TMP=/tmp/.ansible ansible cassius,edge,sentinel \
-  -m lineinfile -a "path=/home/podman/ppf/config.ini line='ssl_only = 1' insertafter='ssl_first'"
+ansible -i $INV workers -m lineinfile \
+  -a "path=/home/podman/ppf/config.ini line='ssl_only = 1' insertafter='ssl_first'"
 ```
 
 ## Podman User IDs