Skip to content

docs/setup: unify agent guidance and harden Pi/server provisioning - #61

Merged
ulises-c merged 39 commits into
mainfrom
docs/agents-md-master
Jul 23, 2026
Merged

docs/setup: unify agent guidance and harden Pi/server provisioning#61
ulises-c merged 39 commits into
mainfrom
docs/agents-md-master

Conversation

@ulises-c

@ulises-c ulises-c commented Jul 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

What & why

Part of #43. This began as the agent-documentation overhaul, then expanded to
resolve the verified findings from the branch-wide reviews rather than leaving
known provisioning and resilience defects behind.

The result has three goals:

  1. Make AGENTS.md the shared instruction source for Claude Code, opencode, and
    Codex, with CLAUDE.md reduced to a Claude-specific overlay.
  2. Move deep package, Railguard, benchmark-review, changelog, and TODO material
    into focused documents instead of loading it into every agent prompt.
  3. Close the confirmed Pi/server reliability, verification, portability, and
    privacy gaps found while reviewing PRs DNS robustness: fix bootstrap deadlock + secondary AdGuard on the Pi #58–docs/setup: unify agent guidance and harden Pi/server provisioning #61.

Changes

Agent documentation

  • Makes AGENTS.md the cross-agent source of truth and imports it from
    CLAUDE.md.
  • Adds docs/PACKAGES.md, the preserved macOS benchmark review, and focused
    Railguard references.
  • Corrects installer/validator drift in agentic-ai/Claude/ and deploys the
    on-demand docs directory.

Pi and server reliability

  • Hardens Pi backup failure handling, timeouts, secret staging, optional-copy
    degradation, AdGuard consistency, and rendered systemd units.
  • Makes NUT configuration actionable from server setup, restarts the UPS driver
    when driver settings change, bounds notifications, prevents repeated NOCOMM
    pushes, and adds server-profile verification.
  • Restores independent LAN access to the Pi Homepage, fixes the AdGuard sync
    route and local widget path, adds the Docker provider config, and documents a
    subnet-scoped CUPS sidecar configuration.
  • Pins Glances, replaces brittle disk-name parsing with refresh-time sysfs label
    resolution, logs patch failures, and covers sdX/NVMe/MMC/late-mount behavior
    with unit tests.

Verification, portability, and privacy

  • Adds Python syntax checks to pre-commit and CI.
  • Renders server backup and Forgejo runner systemd units from the actual checkout
    path instead of committing machine-specific paths.
  • Scrubs tracked hostnames, personal paths, and private network details; repairs
    stale document pointers, rollout state, and migration records.
  • Preserves the full review artifacts in code-review-1-agents.md and
    code-review-2-repo.md.

Verification

  • Root setup.sh --dry-run smoke suite passes on macOS, Ubuntu, Arch, and server.
  • ShellCheck, zsh syntax, JSON validation, package-schema validation, and Python
    syntax CI jobs pass.
  • Pi backup failure/degraded-copy regressions pass with isolated fakes.
  • UPS setup/notification/server-verification regressions pass with isolated fakes.
  • Glances disk alias tests pass for sdX, NVMe, MMC, late arrival, reshuffling,
    successful patching, and visible patch failure.
  • YAML/JSON parsing, diff hygiene, and repository-wide privacy scans pass.

Live verification

Host-specific live checks remain for the main server and Pi. The verification
prompts are being prepared separately so each host agent can deploy and report
without changing repository source or exposing secrets.

Deferred follow-ups

The Quad9 bootstrap policy, timer rescheduling from observed durations, sidecar
deduplication, shared backup implementation, and maintenance-frequency tuning
remain explicit follow-ups. They are operational/design choices rather than
known merge blockers.

Notes

@ulises-c @claude
docs: make AGENTS.md the master agent doc; CLAUDE.md imports it
f9dbe01 
AGENTS.md becomes the single cross-agent instruction set (Claude Code, opencode,
Codex): the former CLAUDE.md content plus a Coding conventions section folded in
from the agent-agnostic global rules (no-comments-by-default, no speculative
design, boundary-only validation, Bash style). Fix the stale "Codex" reference
back to the real "claude-code" custom-install step.

CLAUDE.md slims to `@AGENTS.md` + a Claude-Code-only overlay (/verify and
/security-review triggers for this repo). Per Anthropic's documented pattern,
Claude Code reads only CLAUDE.md and loads AGENTS.md via the import, so there is
no double-load; opencode/Codex read AGENTS.md natively.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Base automatically changed from docs/changelog-todo-unification to main July 12, 2026 09:24
ulises-c and others added 10 commits July 12, 2026 02:28
@ulises-c @claude
docs: preserve macOS benchmark review findings in docs/
824fe28 
The 30 P0-P3 findings were detailed in TODO.md and only summarized in the
CHANGELOG; the detail lived nowhere else. Move the full record to
docs/macos-benchmark-review.md and link it from the changelog entry.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ulises-c @claude
docs: extract packages.json schema to docs/PACKAGES.md; slim AGENTS.md
51d29bf 
Keep AGENTS.md lean: the deep packages.json schema (per-platform scalar-or-object
resolution, environment caveat, tag-filter internals) moves to docs/PACKAGES.md,
leaving a one-paragraph summary + a pointer. Deep reference belongs in docs/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ulises-c
moving MD files to docs/
56a2e17
@ulises-c @claude
docs: fix cross-references after moving TODO/CHANGELOG into docs/
1db2503 
The move (56a2e17) put TODO.md and CHANGELOG.md in docs/ alongside UNIFICATION.md.
Repoint links: root/subdir files now prefix docs/ (AGENTS.md, linux-server
README/HTTPS); docs/-internal cross-links drop the stale docs/ prefix and use
siblings or ../ (CHANGELOG/TODO/UNIFICATION, and TODO's ../linux-server/HTTPS.md).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ulises-c
railguard documentation update
e6c1814
@ulises-c
remove graphify reference
29a2675
@ulises-c @claude
Merge origin/main: port CLAUDE.md Pi-node edits into AGENTS.md
27e79aa 
Main edited the old monolithic CLAUDE.md (linux-pi node description);
this branch made AGENTS.md the master doc with CLAUDE.md as an import
stub. Kept the stub and applied main's two Pi edits to AGENTS.md,
with TODO.md updated to its new docs/TODO.md location.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ulises-c @claude
docs(claude): extract railguard reference into docs/RAILGUARD.md; sli…
d15c3e7 
…m the always-loaded rule

The always-loaded railguard rule and the hand-maintained known-bugs tail
in CLAUDE.md carried full detail into every prompt. Move expected-behavior
detail and the bug-bounty/false-positive log (with upstream issue links)
into an on-demand docs/RAILGUARD.md; the rule shrinks to core semantics
plus a pointer to read the doc when behavior looks wrong.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ulises-c @claude
feat(claude): deploy and validate the docs/ symlink in ~/.claude
472a722 
Rules point at ~/.claude/docs/RAILGUARD.md by path, so install.sh now
links docs/ alongside rules/ and validate.sh checks the link.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ulises-c @claude
docs: add max-effort code-review reports (agents docs + repo-wide PRs…
8e33e80 
… 58-61)

Review 1 covers AGENTS.md/CLAUDE.md/agentic-ai on this branch (15 findings);
Review 2 covers the repo as a whole with emphasis on PRs 58-60 and this PR
(15 top findings + confirmed tail). 30 verified findings total, each with
verdict and concrete failure scenario.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ulises-c ulises-c mentioned this pull request Jul 12, 2026
Open
@ulises-c ulises-c changed the title docs: AGENTS.md as master agent doc; CLAUDE.md imports it docs/setup: unify agent guidance and harden Pi/server provisioning Jul 12, 2026
ulises-c and others added 7 commits July 12, 2026 16:54
@ulises-c
fix(server): persist UPS driver service
ecd2644
@ulises-c
fix(glances): preserve local access during migration
346917b
@ulises-c
fix(pi): enforce backup oneshot timeout
433ed89
@ulises-c
fix(server): verify persistent NUT services
10251bf
@ulises-c
docs: add live host remediation reply chains
3ff8624
@ulises-c @claude
fix(pi): pin cups sidecar subnet for cupsd allow-list
e0f4651 
The cups_default bridge subnet was Docker-assigned, so a network
recreate could hand out a different CIDR and silently break the host
cupsd.conf `Allow <cidr>` rule (and thus the HTTPS front door). Pin it
to 172.21.0.0/16 to match the allow-list in /etc/cups/cupsd.conf.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ulises-c @claude
docs(cups): document + parameterize host CUPS access policy
dd982cf 
The Pi's CUPS is a family-shared USB printer: family devices print over
the LAN via Bonjour (not on the tailnet), while the operator's remote
devices use the Tailscale HTTPS sidecar. Hardening it to tailnet-only
silently blocks the family, so the policy must allow localhost + the
sidecar subnet + the home LAN, and cupsd must answer to the tailnet name
plus the LAN/Bonjour names -- without ever using `ServerAlias *` / `Allow all`.

Add setup.sh, which renders that ServerAlias/<Location /> policy into
/etc/cups/cupsd.conf from a gitignored .env (LAN subnet, hostname, tailnet
name stay out of this public repo). It is idempotent, has --dry-run,
validates with `cupsd -t`, backs up before writing, and refuses to emit
`*`/`all`. .env.example carries placeholders; README.md explains the why.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ulises-c ulises-c mentioned this pull request Jul 13, 2026
Open
4 tasks
@ulises-c
ulises-c marked this pull request as ready for review July 13, 2026 03:43
ulises-c and others added 12 commits July 13, 2026 03:44
@ulises-c @claude
fix(ups): correct UPS model to CyberPower CST135UC2
bed07ee 
The connected unit is a CyberPower CST135UC2 (confirmed via upsc and physical inspection), not the PR1500LCDRT2U the configs and docs claimed. Only the human-readable model label was wrong: the usbhid-ups driver binding (vendorid 0764 / productid 0601) already matched the hardware, so monitoring was unaffected.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ulises-c @claude
docs(pr61): record main server Round 1 verification reply
50ea008 
Add the main server agent's Round 1 reply to the PR #61 reply chain: fast-forward to 3ff8624 with a clean worktree, server verify 38/0, and the NUT permission false-negative resolved. AdGuard credential rotation and UPS notify delivery remain not-attempted/unconfirmed this round.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ulises-c @claude
fix(homepage): parameterize Pi card hostname via env var
bbd935a 
The 'Secondary Server (Pi)' card hard-coded a <pi-hostname> placeholder in its description, which rendered literally on the live dashboard. Move it to HOMEPAGE_VAR_PI_HOSTNAME (real value in the gitignored .env, placeholder in .env.example), matching how the domains are handled. The value is quoted so YAML doesn't misparse the leading {{.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@ulises-c
fix(cups): secure family printing policy deployment
fb199c5
@ulises-c
fix(backup): keep Pi failure status current
a395ce1
@ulises-c
fix(homepage): parameterize main server identity
2a8788c
@ulises-c
test(pi): run policy regressions in CI
eab4a16
@ulises-c
docs(pr61): coordinate final host remediation
b9bcb6e
@ulises-c @claude
driftcheck: honor a repo-root .driftcheckignore
cf23033 
Skips git-tracked paths matching its glob patterns (one per line,
# comments) so intentionally non-executable shebang scripts stop
blocking session stop.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ulises-c @claude
fix(hooks): suppress SC2053 on driftcheck's intentional glob match
63d5162 
CI shellcheck fails on the unquoted RHS, but glob matching is the whole
point of .driftcheckignore patterns.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ulises-c @claude
Merge origin/main into docs/agents-md-master
3f6d9dc 
Resolves the driftcheck.sh conflict in favor of main's version: #64
landed the global ~/.claude/hooks/driftcheck-ignore design for #56, so
this branch's per-repo .driftcheckignore variant (cf23033) is dropped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ulises-c @claude
feat(hooks): make driftcheck ignore lookup repo-root-aware
5a5d485 
Run from git rev-parse --show-toplevel so the check covers the whole
repo and ignore patterns match repo-root-relative paths regardless of
where the session started. Restore per-repo support alongside the
global file: a .driftcheckignore at the repo root is read after
~/.claude/hooks/driftcheck-ignore, same format (#56 follow-up).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ulises-c
ulises-c merged commit 6d65a0c into main Jul 23, 2026
7 checks passed
@ulises-c
ulises-c deleted the docs/agents-md-master branch July 23, 2026 18:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ulises-c