vault: session notes 2026-07-15

_templates/user-guide.md

@@ -0,0 +1,67 @@
+---
+type: user-guide
+title: [Human-readable title]
+summary: [1-2 sentences answering "what mental model + gotchas does using [tool] well require?" — NOT what the tool does or a feature list]
+tags:
+  - type/user-guide
+  - tool/[tool]
+  - domain/[field]     # if applicable
+  - client/[client]    # if client-specific
+  - project/[project]  # if project-specific
+scope: [global|project|client]
+last_updated: YYYY-MM-DD
+date: YYYY-MM-DD          # creation date — set once, never updated
+update_note: experience-driven  # keep — user guides update when a session finds a new gotcha or a discrepancy
+related:
+  - [note-slug]  # cross-links to companion notes; omit if none
+source: [project name]  # project that spawned the note
+---
+
+# [Tool Name] — User Guide
+
+<!-- REMINDER before you fill this: this is NOT a how-to. No numbered steps. Command
+     syntax gets the compact table in "Command Reference" at most — everything else
+     is nuance: semantics, distinctions, gotchas, judgment calls a competent user has
+     internalized. If a section would just restate --help output, cut it. -->
+
+## What it is
+<!-- One paragraph. What the tool does and the one-sentence mental model of its purpose —
+     enough for the reader to recognize "this is/isn't the tool for my situation." Do NOT
+     restate the summary; do NOT give a feature list. -->
+
+## Mental model
+<!-- The key concepts and distinctions the reader must hold to reason about the tool
+     correctly — the vocabulary and the boundaries between modes/concepts that command
+     syntax alone does not convey (e.g. "X vs Y look similar but differ in Z"). This is
+     what makes the rest of the guide (and the tool's own docs) parseable. -->
+
+## Nuances & gotchas
+<!-- The meat of the guide — the heaviest section. Each item: the surprising behavior,
+     why it exists (if known), and how to recognize/avoid/recover from it. Prioritize
+     things that look safe but aren't, defaults that surprise, or state that silently
+     changes behavior. One sub-heading or bullet per nuance; don't pad with obvious facts. -->
+
+## When NOT to use it / limits
+<!-- The boundary: situations where this tool is the wrong choice, or where it stops
+     working as expected. Prevents the reader from forcing a bad fit. Omit only if the
+     tool genuinely has no such boundary (rare — justify the omission to yourself first). -->
+
+## Command reference
+<!-- Compact table ONLY — command/flag → one-line effect. No walkthroughs, no examples
+     of full sessions. If there's nothing beyond what --help already says clearly, cut
+     this section entirely rather than restate --help. -->
+
+| Command | Effect |
+|---|---|
+| `[command]` | [one-line effect] |
+
+## Pointers
+<!-- Where to go deeper: repo paths, ADRs, specs, upstream docs. One line each — what
+     the reader finds there, not a restatement of its content. -->
+
+- [path/to/repo] — [what's there]
+
+## Related
+<!-- Wikilinks to companion notes, one line each on why it is relevant. -->
+
+- [[note-slug]] — why it is relevant

cc-os-hub.md

@@ -38,6 +38,12 @@ operationalize conventions across every project, not just cc-os itself.
 - [[vault-backlog-pilot-plan]] / [[backlog-system-options-research]] — the cross-project backlog
   decision (Planka CE + thin Ruby CLI) adjacent to the vault's knowledge-layer role.
 
+## User guides
+
+- [[os-doc-hygiene-user-guide]] — mental model, gotchas, and rule semantics for using
+  os-doc-hygiene well (not a how-to — command syntax is a compact table, the body is
+  nuance).
+
 ## Graphify handbook
 
 The verified reference handbook behind cc-os's chosen knowledge-graph engine:

howto/herdr-setup-and-config.md

@@ -0,0 +1,110 @@
+---
+type: howto
+title: Herdr Setup, Concepts, and My Config Customizations
+summary: How to install, drive, and configure Herdr (the mouse-first, agent-aware terminal multiplexer) — core concepts, essential commands, and the specific config.toml customizations I chose with the reasoning behind each.
+tags:
+  - type/howto
+  - tool/herdr
+  - domain/dev-tooling
+scope: global
+last_updated: 2026-07-15
+date: 2026-07-15
+update_note: experience-driven
+source: servers
+---
+
+# Herdr Setup, Concepts, and My Config Customizations
+
+Herdr (herdr.dev) is a **terminal workspace manager for AI coding agents** — a tmux-like
+multiplexer, but **mouse-first** and **agent-aware**: it detects agents like `claude`/`codex`
+running in panes and shows their live state (working / blocked / done). Agent guide:
+https://herdr.dev/agent-guide.md · Docs: https://herdr.dev/docs/
+
+## Core Concepts
+
+- **Session** — persistent background server namespace (survives closing the window).
+- **Workspace** — one per project directory; owns its tabs/panes.
+- **Tab** — a layout inside a workspace.
+- **Pane** — a real terminal that survives detach.
+- **Agent** — a recognized process shown with a live status in the sidebar.
+- **Modes** — terminal mode, prefix mode (`ctrl+b` then a key), navigate mode.
+
+## Install
+
+```bash
+# Linux/macOS
+curl -fsSL https://herdr.dev/install.sh | sh
+# Windows (preview beta)
+powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
+```
+Installs to `~/.local/bin/herdr`. Also available via Homebrew / mise / Nix (see docs).
+
+## Essential Commands
+
+| Do this | Command / keys |
+|---|---|
+| Launch / attach session (from a project dir) | `herdr` |
+| Start an agent in a pane | `claude` (or `codex`, …) — auto-detected |
+| Split right / down | `prefix+v` / `prefix+minus`, or right-click menu |
+| New tab | `prefix+c` |
+| See all keybindings | `prefix+?` |
+| Open settings (live theme browser!) | `prefix+s` |
+| Detach (leaves agents running) | `prefix+q`, or close the window |
+| List detected agents | `herdr agent list` |
+| Local/server status | `herdr status` |
+| Reload config in running server | `herdr server reload-config` |
+| Stop background server | `herdr server stop` |
+| Print default config | `herdr --default-config` |
+| Attach a workspace to a remote host | `herdr --remote <ssh-target>` |
+
+Config lives at `~/.config/herdr/config.toml` (override via `HERDR_CONFIG_PATH`).
+Logs: `~/.config/herdr/herdr.log` (+ `herdr-client.log`, `herdr-server.log`).
+
+**Adoption note:** don't force keybindings before you're used to the tool — it makes adoption
+harder. Learn via mouse + right-click menu first, pick up a few bindings organically.
+Don't carry tmux muscle memory in — it's a different tool despite the shared `ctrl+b` prefix.
+
+## Themes
+
+There is **no CLI theme preview**. To browse: open Herdr and press **`prefix+s`** (settings) —
+built-in themes apply **live and instantly**, no reload. Built-ins: `catppuccin`, `terminal`,
+`tokyo-night`, `dracula`, `nord`, `gruvbox`, `one-dark`, `solarized`, `kanagawa`, `rose-pine`,
+`vesper`. Persist a choice via `[theme] name = "..."` + `herdr server reload-config`.
+
+My kitty theme (DMS "dank" generator) is **Catppuccin-Macchiato-derived** (`background #24273a` /
+`foreground #cad3f5` = Macchiato base/text, warm Material-You peach accent `#f5a97f`). So I set
+Herdr's built-in `catppuccin` + a `[ui] accent` override of the peach to echo the terminal look.
+`[theme] auto_switch` + `dark_name`/`light_name` can follow the host terminal's light/dark mode.
+`[theme.custom]` overrides individual color tokens (hex / named / rgb) on top of a base theme.
+
+## My config.toml Customizations (2026-07-15) — and why
+
+Only behavior/notification settings were changed; keybindings left at defaults on purpose.
+
+| Setting | Value | Why |
+|---|---|---|
+| `[theme] name` | `"catppuccin"` | Closest built-in to my Catppuccin-Macchiato kitty theme. Browse alternatives live via `prefix+s`. |
+| `[ui] accent` | `"#f5a97f"` | My kitty/dank palette's warm peach accent, replacing Herdr's default cyan on borders/nav. Delete to use the theme's own accent. |
+| `[ui] show_agent_labels_on_pane_borders` | `true` | I run `claude` AND `codex`, often side by side — labels tell me which agent is in which pane at a glance. |
+| `[ui] agent_panel_sort` | `"priority"` | I run several agents across projects; "priority" is an attention queue (blocked/done float to top) — answers "who needs me now?" vs. "spaces" grouping. |
+| `[ui.toast] delivery` | `"herdr"` | Long agent runs + I step away. In-app toasts always work, zero deps. `"system"` (real desktop popups) needs a notification daemon (mako/dunst/swaync) — my Hyprland/DMS setup is mid-migration, so avoid until a daemon is confirmed. |
+| `[ui.sound] enabled` | `true` | Reliable audible "agent done / needs input" cue while I'm in another window — works regardless of the desktop-notification-daemon situation. |
+| `[session] resume_agents_on_restore` | `true` (pinned) | Both my agents support it; after a server restart/reboot their conversations reload instead of starting cold. Default, pinned for clarity. |
+| `[remote] manage_ssh_config` | `true` (pinned) | I manage a fleet over SSH; layers keepalives over my `~/.ssh/config` aliases so long remote agent sessions survive NAT/idle drops. `herdr --remote <host>` gives remote panes that survive detach. |
+
+Apply live after editing: `herdr server reload-config` (returns `status: applied` with a
+`diagnostics` array — empty means the config is valid).
+
+## Gotchas / notes
+
+- **Notification popups need a daemon on Wayland/Hyprland.** `delivery = "system"` (and often
+  `"terminal"`) depend on a running notification daemon. Start with `"herdr"` + sound; only move
+  to `"system"` after confirming mako/dunst/swaync is up.
+- **Config edits vs dotfiles:** `~/.config/herdr/config.toml` is a real file (NOT a stow symlink
+  into `~/.dotfiles`), so it's directly editable — unlike kitty/hypr configs which are dotfile-managed.
+- `herdr config reset-keys` backs up config.toml and strips custom keybindings if bindings get tangled.
+
+## Related
+
+- Terminal/desktop context: my Hyprland migration (Fedora 43) and kitty use the DMS "dank"
+  Catppuccin-Macchiato palette — the source of the accent color reused above.

journal/2026-07-15.md

@@ -121,3 +121,17 @@ tags: [scope/global, type/log]
 **Reason:** other
 **Vault notes touched:**
 (none)
+
+## Session — 2026-07-15T13:11:45Z
+
+**Project:** /home/jared/dev/cc-os
+**Reason:** prompt_input_exit
+**Vault notes touched:**
+(none)
+
+## Session — 2026-07-15T13:51:03Z
+
+**Project:** /home/jared/dev/cc-os
+**Reason:** other
+**Vault notes touched:**
+(none)

user-guide/os-doc-hygiene-user-guide.md

@@ -0,0 +1,164 @@
+---
+type: user-guide
+title: os-doc-hygiene — User Guide
+summary: Mental model and gotchas for using the os-doc-hygiene Claude Code plugin well — the stale-vs-bloat distinction, check/calibrate/clean/sweep semantics, the two rule files, rule-activation pitfalls, safety tiers, and report-reading traps.
+tags:
+  - type/user-guide
+  - tool/os-doc-hygiene
+  - tool/claude-code
+  - project/cc-os
+  - domain/documentation
+scope: global
+last_updated: 2026-07-15
+date: 2026-07-15
+related:
+  - cc-os-hub
+source: cc-os
+---
+
+# os-doc-hygiene — User Guide
+
+## What it is
+
+`os-doc-hygiene` is a globally-installed Claude Code plugin that monitors and manages
+project documentation across two independent failure modes: docs that are *wrong* and
+docs that are *true but bloated*. It reminds passively every session (zero tokens, no
+mutation) and does its actual work — scanning, classifying, and cleaning — only on
+demand via skills. It is not a linter for prose quality; it is a lifecycle manager for
+`.md` files, extended (2026-07-15) with a rulebook that can also delete or archive
+files on a schedule or trigger.
+
+## Mental model
+
+- **Stale vs bloat is the core axis, and they are not the same failure.** *Stale* means
+  the doc is *wrong* — contradicted, orphaned, superseded, provisional-but-abandoned,
+  completed-in-place, or duplicated; the remedy is fix or remove. *Bloat* means the doc
+  is *true but mostly irrelevant at its current altitude* — the remedy is to distill,
+  split, or freeze it, almost never to delete history. Conflating the two leads to
+  either deleting a correct-but-long doc or leaving a wrong-but-short one in place.
+- **Severity scales with injection frequency, not file size.** A stale line in a file
+  that gets auto-injected every session (e.g. a `CLAUDE.md`) is worse than the same
+  line in a doc nobody opens, even if the second doc is larger.
+- **The skill quartet has distinct jobs, not a redundant surface:**
+  - `:check` — scan + classify against the *existing* rules, writes a report. Does not
+    learn anything new.
+  - `:calibrate` — the *learn-new-rules* loop. It clusters the pool of files no
+    existing rule governs, proposes candidate globs, and gets them judged and
+    persisted. It is recurring and self-narrowing: each pass only looks at what's
+    still unmatched, and it hard-caps at 3 rounds per invocation (stops early at
+    <2 new rules or <10% unmatched shrink).
+  - `:clean` — applies the *most recent* report's findings (deterministic ops
+    mechanically, generative ops via a subagent, confirm-tier gated).
+  - `:sweep` — check-then-clean back to back; it does not skip clean's confirm gate,
+    it just chains the two.
+- **Rules live in two places with different trust levels.** A committed,
+  per-project `.dochygiene-rules.json` at the repo root (reviewable, versioned,
+  travels with the repo — ADR-0038) holds the project's actual lifecycle rules. A
+  gitignored `.cc-os/dochygiene/` directory (legacy fallback path: `.dochygiene/`)
+  holds only local state and reports — never rules. The plugin also ships a global
+  `plugins/os-doc-hygiene/rulebook.json`, but that ships **only IGNORE seeds**
+  (`graphify-out/**`, `.dochygiene/**` as of 2026-07-15) — it is not a source of
+  general-purpose lifecycle rules for your project.
+- **A rule with no `lifetime` field is not "keep" — it's an IGNORE sentinel.** IGNORE
+  paths are pruned from the scan walk entirely; they never appear in a report, not
+  even as "kept." This is distinct from `lifetime: keep`, which *is* walked and
+  reported, just never deleted. If you expect a file to show up as "kept" in a
+  report and it never does, check whether an IGNORE rule (no `lifetime`) is silently
+  swallowing it.
+
+## Nuances & gotchas
+
+- **`temporary` deletion needs BOTH conditions, not either.** A file is only deleted
+  under a `temporary`-lifetime rule once it is *both* ranked past `retain_recent`
+  (i.e. not one of the N newest matches) *and* older than `max_age_days`. A file that
+  is old but still in the top-N-newest survives; a file that's low-ranked but too
+  young also survives. Don't reason about temporary rules with just one of the two
+  numbers.
+- **`served_when` vs `served_when_path` is a trust boundary, not a style choice.**
+  `served_when` is free text judged by the LLM classifier — it is *always* confirm-tier,
+  never auto, regardless of git state. `served_when_path` is a path pattern the scanner
+  can prove deterministically (e.g. "moved into `archive/{id}/`") — it *can* be
+  auto-tier. If you want a rule to eventually run silently, the path is to graduate it
+  from `served_when` to `served_when_path` by adopting a structural completion
+  convention (see conventions.json below) — not to just mark it `confirm: true` and
+  move on.
+- **A rule missing `confirmed_by` is silently inactive.** It doesn't error, doesn't
+  warn loudly — it just never acts. If a rule you added doesn't seem to be doing
+  anything, check for a missing or malformed `confirmed_by`/`confirmed_on` before
+  assuming the glob is wrong.
+- **Safety tiers are about evidence quality and recoverability, not file type.** `auto`
+  requires deterministic + reversible + objective; `confirm` covers anything
+  destructive, subjective, or generative. Critically: a dirty or untracked file
+  *always* escalates to confirm even if a rule would otherwise make it auto — there's
+  no git history to recover from. And git state is **re-verified at apply time**, not
+  trusted from when the report was generated — a file that was tracked+clean at
+  `:check` time but got dirtied before `:clean` runs will be downgraded to confirm (or
+  skipped as `git-state-changed-since-check`).
+- **The report's "cleared" count is not what it sounds like.** `cleared` = shortlist
+  entries minus findings — i.e. candidates the deterministic scanner surfaced but the
+  classifier decided need no action. It can coincidentally equal (or come close to)
+  the total files-scanned count, which misleads you into thinking "cleared" means
+  "scanned." The AI classifier only ever sees the signal-bearing subset the scanner
+  flagged — in the first cc-os run, that was 44 of 384 files scanned; the rest were
+  cleared deterministically and never reached the model at all.
+- **There is deliberately no calendar-date staleness signal.** The scanner does not
+  flag "this file hasn't been touched in N days" as a signal by itself. Staleness
+  comes from broken references, file length (bloat), edit-recency-vs-churn patterns,
+  and lifecycle rules — not raw age. A quiet-but-correct doc is not stale just because
+  it's old.
+- **The scanner is a pure script — no tokens, full re-walk every run, `.md` files
+  only.** It doesn't cache or incrementally diff; every `:check` re-walks the whole
+  tree (minus exclusions). Don't expect it to pick up non-Markdown docs (READMEs in
+  other formats, code comments) as scan targets.
+- **The `SessionStart` hook only reminds — never analyzes or mutates.** It fires at
+  most once per calendar day while docs are stale (keyed off `last_reminded`), and
+  spends zero AI tokens. If you see the reminder banner, no scan has happened yet —
+  you still have to run `:check` to get real findings.
+- **New-project onboarding is not automatic.** A fresh project has no
+  `.dochygiene-rules.json`. Until you run `:calibrate` once to generate it, only the
+  global IGNORE seeds apply and *no* lifecycle deletions happen — `:check`/`:clean`
+  still work for stale/bloat findings, but the lifecycle layer is inert.
+
+## When NOT to use it / limits
+
+- Not a prose/style linter — it does not check grammar, tone, or writing quality.
+- Not a general file manager — the lifecycle/delete features only ever act on paths
+  matched by an explicitly confirmed rule; unmatched files are left alone
+  ("unmatched = unmanaged").
+- Not a substitute for `:calibrate` when a project has structurally unusual doc
+  conventions (e.g. specs/plans as the shipped product) — the global rulebook alone
+  will under- or over-match.
+- Don't expect deletions to be silently recoverable outside git — deletion is a real
+  `git rm` in a dedicated commit; git history is the only archive. There is no
+  graveyard directory.
+- Not designed to run unattended in CI as a destructive step without review — confirm-
+  tier gates exist precisely because classifier judgment and dirty/untracked state
+  need a human.
+
+## Command reference
+
+| Command | Effect |
+|---|---|
+| `/os-doc-hygiene:status` | Read-only timestamps (last check/clean/reminded) + report presence. No model, no scan. |
+| `/os-doc-hygiene:check [--scope <glob-or-path>] [--category <class\|subtype>]` | Scan + classify against existing rules, write a report. |
+| `/os-doc-hygiene:calibrate` | Learn-new-rules loop over the unmatched pool; hard cap 3 rounds; nothing persists without the human seeing the rule report first. |
+| `/os-doc-hygiene:clean [--scope <glob-or-path>] [--category <class\|subtype>]` | Apply the latest report's findings; confirm-tier entries gated. |
+| `/os-doc-hygiene:sweep [--scope <glob-or-path>] [--category <class\|subtype>]` | check then clean, same confirm gate as standalone clean. |
+
+## Pointers
+
+- `plugins/os-doc-hygiene/CLAUDE.md` (cc-os repo) — build map + the stale-vs-bloat
+  invariant summary.
+- `plugins/os-doc-hygiene/lifecycle-spec.md` (cc-os repo) — the full lifecycle-rules
+  design: taxonomy, rulebook schema, deletion semantics, `:calibrate` protocol.
+- `plugins/os-doc-hygiene/invariants.md` (cc-os repo) — the reversion-protection
+  contract; read before changing any behavioral invariant.
+- `plugins/os-doc-hygiene/conventions.json` (cc-os repo) — the determinism-promotion
+  catalog (`archive-bucket`, `status-frontmatter`) that graduates `served_when` rules
+  to auto-tier `served_when_path`.
+- `docs/adr/0038-*.md` through `0041-*.md` (cc-os repo) — rulebook location, deletion
+  autonomy tiers, no-ignore-propagation, and determinism-promotion decisions.
+
+## Related
+
+- [[cc-os-hub]] — the cc-os plugin family this tool belongs to.

vault-conventions.md

@@ -59,6 +59,7 @@ Use exactly one `type/` tag per note.
 | `type/clip` | Web clips, saved articles |
 | `type/project-config` | Per-project tag inference rules and conventions |
 | `type/meta` | Vault governance (this file, CLAUDE.md) |
+| `type/user-guide` | Nuance/mental-model guide for using a tool well (NOT a how-to — see Note Types (Authoring Guide) below) |
 
 ## Tag Taxonomy
 
@@ -138,7 +139,14 @@ This section defines the three primary note types used for durable, evergreen kn
 **Template:** eval-results.md
 **Sub-templates:** none
 
-**Note on directories:** The standard directories for these types are `convention/`, `reference/`, and `howto/` at the vault root. These directories do not yet exist; notes of these types currently live at the vault root until directory structure is established.
+### user-guide
+**Question this answers:** "What's the mental model, and what will bite me, when using [tool X] well?" A user-guide is NOT a how-to: it carries no numbered steps and only a compact command-syntax table at most. Its body is nuance — the semantics, distinctions, and gotchas a competent user needs internalized to use the tool correctly, that command syntax alone does not convey. Boundary against `howto`: reach for `howto` when the reader wants to DO a specific repeatable procedure end-to-end; reach for `user-guide` when the reader already knows roughly what command to run and needs the judgment to use it correctly (which mode applies, what silently changes behavior, what looks safe but isn't).
+**Value gate:** Longevity (still relevant in 6-12 months?) + Reusability (applies beyond the project that produced it?)
+**Mutability:** stable knowledge, but experience-driven updates apply — when a session uses the tool and finds a discrepancy or a new gotcha, update the note rather than relying on a review date.
+**Template:** user-guide.md
+**Sub-templates:** none
+
+**Note on directories:** The standard directories for these types are `convention/`, `reference/`, `howto/`, and `user-guide/` at the vault root. `convention/`, `reference/`, and `howto/` already exist; `user-guide/` is created with the first note of that type.
 
 ## Standard Frontmatter Schema
 
@@ -146,7 +154,7 @@ All notes use this frontmatter block. Type-specific additions are noted inline.
 
 ```yaml
 ---
-type: [convention|reference|howto|eval-results]
+type: [convention|reference|howto|eval-results|user-guide]
 subtype: [pattern/framework|api-integration|role-definitions|design-rules]  # reference only
 title: [Human-readable title]
 summary: [1-2 sentences answering "what question does this note answer?"]