diff --git a/_templates/user-guide.md b/_templates/user-guide.md new file mode 100644 index 0000000..aea9492 --- /dev/null +++ b/_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 + + + +## What it is + + +## Mental model + + +## Nuances & gotchas + + +## When NOT to use it / limits + + +## Command reference + + +| Command | Effect | +|---|---| +| `[command]` | [one-line effect] | + +## Pointers + + +- [path/to/repo] — [what's there] + +## Related + + +- [[note-slug]] — why it is relevant diff --git a/cc-os-hub.md b/cc-os-hub.md index b5612ee..bdd2174 100644 --- a/cc-os-hub.md +++ b/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: diff --git a/howto/herdr-setup-and-config.md b/howto/herdr-setup-and-config.md new file mode 100644 index 0000000..c0f4785 --- /dev/null +++ b/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 ` | + +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 ` 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. diff --git a/journal/2026-07-15.md b/journal/2026-07-15.md index de79220..4156afd 100644 --- a/journal/2026-07-15.md +++ b/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) diff --git a/user-guide/os-doc-hygiene-user-guide.md b/user-guide/os-doc-hygiene-user-guide.md new file mode 100644 index 0000000..06da551 --- /dev/null +++ b/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 ] [--category ]` | 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 ] [--category ]` | Apply the latest report's findings; confirm-tier entries gated. | +| `/os-doc-hygiene:sweep [--scope ] [--category ]` | 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. diff --git a/vault-conventions.md b/vault-conventions.md index 170a64e..386b6b5 100644 --- a/vault-conventions.md +++ b/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?"]