vh
1147e14b79
The 3.3.0 deploy exposed a false green. `claude plugin update` matches on the version in plugin.json and declines when it has not moved, so a release that edits hook or script content without a version bump leaves the Claude Code cache stale while every version check in this script reports success. Marketplace and live cache both read 0.1.1, update said "already at the latest version", and pane-route.sh + README differed. That particular delta was documentation-only, so nothing was actually broken — but the script had no way to say so, which is the defect. It now diffs the marketplace tree against the live cache dir on every run and on --check, ignoring orphaned version dirs, and says what to do about drift (bump upstream; never hand-edit Claude Code's bookkeeping). The 2026-09-01 lesson was "compare the hook list, not the version string". This is that lesson one turn deeper: the hook list was identical too. Also documents the cc channel as a deliberately-taken undocumented interface — expected to break on some future Claude Code release, failing to pull-only with a logged reason rather than losing mail — and the herald-before-declare ordering constraint that the script already honours.
docs/
Navigation map for the documentation tree. New session? Read
orientation.md first — it's the narrative overview
of the fleet, backup architecture, governing principles, and gotchas,
and it points at everything else.
Tree
docs/
├── orientation.md # start here — fleet overview + where-to-look guide
├── runbooks/ # ops runbooks (recovery, deployment phases)
│ ├── disaster-recovery.md
│ ├── nh3-prune-ritual.md
│ └── pbs-deployment.md
└── pfi/ # PFI-specific reference (services, models, VMs)
├── docker-stack.md
├── model-list.md
├── proxmox-vms.md
├── recommended-model-settings.md
├── vm-102-matrix-appservice.md
└── vm-102-matrix-synapse.md
What goes where
runbooks/— step-by-step ops procedures. Anything you'd reach for during an incident or while standing up new infrastructure. Examples: disaster recovery (blast-radius tiers + restoration steps), PBS deployment (9-phase rollout). New runbook → new file here.pfi/— PFI-specific reference material that's too narrow for the top-level CLAUDE.md but doesn't change incident response. AI model inventory, recommended inference settings, Matrix bridge config, Proxmox VM map. New stable reference → new file here.- Top-level (
docs/orientation.md,docs/README.md) — narrative guides about the workspace itself, not about specific infra.
Cross-references
- Fleet topology + servers table: top-level
CLAUDE.md. - Open work + recent milestones: top-level
STATUS.md. - Durable cross-session facts:
~/.claude/projects/-home-lkraven-development-eshpfi-management/memory/.
Conventions
- Markdown, GitHub-flavored. CommonMark renders fine in most viewers.
- File names are lowercase-kebab-case, descriptive. No dates in filenames — git history covers that.
- One topic per file. If a file grows past ~500 lines, look for a natural split before adding more.
- No checked-in binaries or checksums. Build/release artifacts belong
in a build pipeline or
tools/, notdocs/.