From b86128f593e69ccf5f4b076b75bfe7183df3e4f4 Mon Sep 17 00:00:00 2001 From: jared Date: Fri, 3 Jul 2026 14:38:36 -0400 Subject: [PATCH] vault: session notes 2026-07-03 --- ...roxmox-vm-setup-with-bells-and-whistles.md | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/howto/proxmox-vm-setup-with-bells-and-whistles.md b/howto/proxmox-vm-setup-with-bells-and-whistles.md index 3385f84..1627ef1 100644 --- a/howto/proxmox-vm-setup-with-bells-and-whistles.md +++ b/howto/proxmox-vm-setup-with-bells-and-whistles.md @@ -60,12 +60,27 @@ these steps rather than relying on a review date. 6. **Document host-level facts once, shared across all VM-specific projects — don't duplicate them per project.** Host address, VMID inventory, the token-scoping convention, and the safety rules (never touch protected VMs, no host shell, confirm destructive - actions) belong in one place that every VM-specific project imports/references. Per-project + actions) belong in one place that every VM-specific project can actually see. Per-project duplication drifts — a safety rule updated in one project's docs silently goes stale in - another's. (Concretely: this was extracted from a single project's CLAUDE.md into a - shared host-layer CLAUDE.md referenced by both VM projects, once a second VM project - existed to justify it — don't extract shared docs speculatively before there's a second - real consumer.) + another's. + + **Where "one place" should live, if the VM projects are siblings under an umbrella + directory**: put the shared facts directly in the umbrella's own CLAUDE.md, not in a + separate sibling directory referenced via `@../shared/CLAUDE.md`. Claude Code's `@path` + import resolver does not follow `../` references that escape a file's own directory + tree — only same-directory and subdirectory imports resolve. A shared-facts file one + level up and over from each VM project's CLAUDE.md silently never loads in a session + scoped to that project; the path renders as a dead pointer. Verified empirically by + launching a session with cwd inside a sibling project and checking which CLAUDE.md + *content* (not just referenced paths) was actually present in context. + + The umbrella CLAUDE.md doesn't have this problem — it already auto-loads for any + subdirectory cwd via Claude Code's ancestor-directory walk, so inlining the shared + facts there makes them visible everywhere for free, no import needed. Per-project + CLAUDE.md files then just point to it in prose ("see the umbrella CLAUDE.md's Proxmox + Host section") rather than via `@import`. Subdirectory-descending imports (e.g. the + umbrella file importing `@some-project/docs/foo.md`) are unaffected by this and work + fine — the restriction is specifically on upward (`../`) traversal. 7. **Before defaulting to a Docker/Container install for a self-hosted service, check whether a native/appliance-OS install path exists.** Docker-only installs sometimes lack