vault: session notes 2026-07-03

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