jared
/
SecondBrain
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

vault: session notes 2026-07-15

This commit is contained in:
Jared Swanson 2026-07-15 09:51:03 -04:00
parent b7abd05ae4
commit 9b57d538b5
6 changed files with 371 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
_templates/user-guide.md Normal file
View File

@ -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

6
cc-os-hub.md
View File

@ -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:

110
howto/herdr-setup-and-config.md Normal file
View File

@ -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.

14
journal/2026-07-15.md
View File

@ -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)

164
user-guide/os-doc-hygiene-user-guide.md Normal file
View File

@ -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.

12
vault-conventions.md
View File

@ -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?"]