From c37ad6e870b813923bd9badd9adf93526b030b7f Mon Sep 17 00:00:00 2001 From: Frank Date: Wed, 21 Oct 2026 02:16:56 -0700 Subject: [PATCH] docs(indexes): skim layer skimmable, one undescribed entry described MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An index is the skim layer: its entries decide whether a reader opens the page, so an entry that runs 250 characters is a paragraph wearing a bullet. Four entries in `tools/index.md` (`dotfiles-deploy`, `packages`, `pcie-probe`, `remote-job`) now say what the page is for in one line and let the page carry the detail — which is the whole argument for progressive disclosure having an index at all. `engineering/infra/index.md` pointed at `../sdlc.md` with no description at all; it now carries the one from that page's frontmatter, like its four siblings. Refs #64 --- omp-docs/engineering/infra/index.md | 2 +- omp-docs/tools/index.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/omp-docs/engineering/infra/index.md b/omp-docs/engineering/infra/index.md index be7a44a..b74dc93 100644 --- a/omp-docs/engineering/infra/index.md +++ b/omp-docs/engineering/infra/index.md @@ -12,4 +12,4 @@ Current (2025/2026) best practices for infrastructure as code, containers, orche ## See Also * [Engineering](../index.md) - The parent area. -* [SDLC and Tooling](../sdlc.md) +* [SDLC and Tooling](../sdlc.md) - git, CI/CD, testing, review, versioning, and dev environments. diff --git a/omp-docs/tools/index.md b/omp-docs/tools/index.md index 866b884..4e4598d 100644 --- a/omp-docs/tools/index.md +++ b/omp-docs/tools/index.md @@ -9,7 +9,7 @@ Configuration guides and reference material for installed software. Each tool ha * [applications](applications.md) — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming. * [cachyos](cachyos.md) — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on the workstation. * [comfyui](comfyui/index.md) — Node-based AI image generation engine on dankclaw. FLUX.2 klein 4B, CPU backend, systemd managed. -* [dotfiles-deploy](dotfiles-deploy.md) — How `dotfiles/` packages become live config: `deploy.sh` modes, host override packages, and the tier's hard-won laws, from media and generated theme output to systemd enable/start semantics, dconf dumps, and idle-lock watcher triage. +* [dotfiles-deploy](dotfiles-deploy.md) — How `dotfiles/` packages become live config: `deploy.sh` modes, host overrides, and the tier's laws. * [ghostty](ghostty/index.md) — GPU-accelerated terminal emulator with extensive configuration, keybindings, and shaders. * [gitea](gitea/index.md) — Private Git hosting on dankclaw. Quadlet-managed containers: Gitea, PostgreSQL, Caddy. * [handy](handy.md) — Offline speech-to-text transcription with WebKitGTK backend and Tauri v2 UI. @@ -19,9 +19,9 @@ Configuration guides and reference material for installed software. Each tool ha * [neovim](neovim.md) — Two editors in one binary: vanilla `nvim` for quick edits and the `lazyvim` NVIM_APPNAME profile, with the base16 wallpaper-palette hook and fresh-box install. * [niri](niri/index.md) — Scrollable-tiling Wayland compositor — configuration, keybindings, and architecture for the workstation. * [noctalia-shell](noctalia-shell.md) — Native desktop environment for Niri — launcher, control center, settings, lock screen, session menu, hotkey overlay, media controls, and system management. -* [packages](packages.md) — `packages/*.pkgs` desired state and the two tools that keep a machine and its manifest agreeing: `install.sh` installs the delta, `pkg-inventory.sh` reports what the machine has outgrown. -* [pcie-probe](pcie-probe.md) — HIP probes that separate PCIe link bandwidth from the engine's read path at the expert-slab size, and the refuse-by-default guard against benchmarking beside a live service. -* [remote-job](remote-job.md) — Detached job runner for `ssh` work: completion sentinels on the host replace the `tail -f | sed -n /ready/q` pattern that reported success on jobs that never finished. +* [packages](packages.md) — `packages/*.pkgs` desired state, plus `install.sh` (installs the delta) and `pkg-inventory.sh` (reports drift). +* [pcie-probe](pcie-probe.md) — HIP probes separating PCIe link bandwidth from the engine's read path; refuses to run beside a live service. +* [remote-job](remote-job.md) — Detached `ssh` jobs with completion sentinels; replaces the `tail -f | sed` readiness pattern that lied. * [tmux](tmux.md) — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures. ## Adding a New Tool