lsr-explore · lsr-explore · Jul 10, 2026 · Jul 10, 2026
@@ -18,8 +18,8 @@ backend use.
 If you're an assistant helping set up or improve a project, treat this repo as a
 **source to copy from, not to regenerate**:
 
-1. Start at **[`docs/INDEX.md`](./docs/INDEX.md)** — the routing table of every
-   snippet (purpose, deps, copy-to, when to reach for it).
+1. Start at the **routing table in [`README.md`](./README.md)** — every snippet's
+   purpose, deps, copy-to, and when to reach for it, up front.
 2. Find the row that fits, open that folder's `README.md` (each opens with the same
    purpose / deps / copy-to / use-when header), and copy the file(s) **verbatim**
    along with the README. Don't reinvent a variant — prefer the snippet as written.
@@ -54,8 +54,9 @@ rationale, not the Next-locked reference configs.
 1. Give it its own folder (or place it in the right existing one) with a `README.md`.
 2. Keep it self-contained and zero/minimal-dep; note assumptions at the top of the file.
 3. Give the README the standard **purpose / deps / copy-to / use-when** header block
-   (see any existing snippet), then update the layout map in the top-level
-   `README.md` **and** add a row to [`docs/INDEX.md`](./docs/INDEX.md).
+   (see any existing snippet), then add a row to the routing table in the top-level
+   [`README.md`](./README.md) (the single source — there's no separate index to keep
+   in sync).
 4. If it's a candidate rather than finished work, log it in
    [`docs/backlog.md`](./docs/backlog.md) instead.
 

@@ -6,60 +6,77 @@ piece (a script, a config, a cheatsheet) that you **copy into another project**
 adapt. Snippets avoid cross-dependencies on purpose so a single file can be lifted
 out cleanly.
 
-## Layout
-
-```text
-scripts/
-  keychain/        Retrieve API keys from the macOS Keychain (TS + Python) + security-CLI cheatsheet
-  worktrees/       The `wt` git-worktree helper + install instructions
-  seed-local/      Seed a fresh worktree/clone with gitignored local files (.env, settings, skills, data) via a manifest
-  ai-cache/        Disk-backed response cache to stop re-spending tokens during UI dev (Node + Python)
-  cli-boilerplate/ Starter CLI in TS + Python: arg parsing, --help, leveled logging, exit codes
-  http-fetch/      Zero-dep fetch wrapper: per-attempt timeout + retry/backoff + typed errors (TS + Python)
-  secret-guard/    Pre-commit hook that blocks committing .env files + common secret patterns
-  branch-guard/    Local pre-commit + pre-push hooks that refuse commits/pushes to main
-  kill-port/       Find and kill the process listening on a TCP port (macOS, lsof)
-  a11y-check/      Standalone axe-core accessibility smoke check against a local URL
-  playwright/      Minimal Playwright test (google.com) + axe-core a11y scan + config
-config/
-  claude-code/     Security-focused Claude Code settings.json + notes, and rules/ (.claude/rules/*.md drop-ins)
-  coderabbit/      Example .coderabbit.yaml for the CodeRabbit AI PR reviewer
-  biome/           biome.json + "why Biome over Prettier"
-  node-version/    Pin Node across a team: .nvmrc vs Volta vs Corepack + engines cheatsheet
-  vscode/          VSCode settings + extensions (incl. Vim)
-  iterm2/          iTerm2 setup notes                        — personal env
-  bashmarks/       bashmarks install + usage                — personal env
-templates/
-  docs/            Copyable doc scaffolding: project_log + ADR templates (with instructions)
-  conventions/     Tooling conventions + per-repo verify checklist + reference configs
-  github/          GitHub starters: minimal frontend CI + PR / issue templates + dependabot
-docs/
-  INDEX.md            Structured map of every snippet — start here (the AI entry point)
-  toolchain.md        Inventory of the tools used in the next-template repo
-  references.md       External resources: agent skills, package hygiene, TS reference
-  ai-collaboration.md Personal log of Claude Code friction points + fixes
-  global-packages.md  Global npm CLIs reached for occasionally (ccusage, git-trim, ncu, json-server, http-server, mcp-remote, devlove/devrage)
-  mermaid.md          Mermaid diagram notes — placeholder (dark/light theming is the open problem)
-  backlog.md          Candidate snippet ideas (the first batch has shipped)
-```
+Everything is mapped below — purpose, deps, where it lands, and when to reach for it.
+This routing table is the fastest entry point, and the first thing to point an AI
+assistant at.
+
+**For an AI assistant:** find the row, open that folder's `README.md` (each opens with
+the same **purpose / deps / copy-to / use-when** header), and copy the file(s)
+**verbatim** with their README — don't regenerate from scratch. Prefer a snippet here
+over inventing your own. Skip rows tagged *personal env* when setting up a project.
+
+Legend — **Deps:** `none` = language built-ins / stdlib only.
+
+## scripts/ — runnable utilities
+
+| Snippet | Purpose | Lang | Deps | Copy to | Reach for it when |
+| --- | --- | --- | --- | --- | --- |
+| [keychain](scripts/keychain) | Read API keys from the macOS Keychain at runtime, instead of `.env` | TS + Py | none (macOS `security`) | project (keep filename + README) | You want secrets off-disk on a dev machine. *Not* Linux CI — inject via env there. Pairs with [secret-guard](scripts/secret-guard). |
+| [worktrees (`wt`)](scripts/worktrees) | git-worktree helper (new/open/ls/rm), opens in iTerm2/VSCode | zsh | git (`osascript`/`code` optional) | `~/.local/bin` | You run parallel branches as worktrees. macOS terminal integration. |
+| [seed-local](scripts/seed-local) | Copy gitignored local files (`.env`, settings, skills, data) into a fresh worktree/clone from an existing one | bash | `rsync` (`jq` for a JSON manifest) | `<project>/scripts` | A new worktree/clone needs per-checkout secrets/config git doesn't track. Manifest-driven — won't sweep up branch WIP. Pairs with [worktrees (`wt`)](scripts/worktrees). |
+| [ai-cache](scripts/ai-cache) | Disk-backed response cache keyed on a request hash (don't re-pay for identical calls) | TS + Py | none | project | Iterating on AI/API calls; dedup identical requests. *Not* for mutations or secrets. A general API cache despite the name. |
+| [cli-boilerplate](scripts/cli-boilerplate) | Starter CLI: arg parsing, `--help`, leveled logging, exit codes | TS + Py | none (`tsx` dev-only) | project | Standing up a new Node or Python command-line script. |
+| [http-fetch](scripts/http-fetch) | fetch wrapper: per-attempt timeout + retry/backoff + typed errors | TS (Node 18+) + Py | none | project | A script/backend needs resilient HTTP without `axios`/`requests`. Pairs with [ai-cache](scripts/ai-cache). |
+| [secret-guard](scripts/secret-guard) | Pre-commit hook blocking `.env` + common secret patterns | POSIX sh | git + grep | `.git/hooks` or `core.hooksPath` | Stop secrets leaking into a commit. Pre-commit only — not a history scanner. Companion to [keychain](scripts/keychain). |
+| [branch-guard](scripts/branch-guard) | Local pre-commit + pre-push hooks that refuse commits/pushes to `main` | POSIX sh | git (Husky optional) | `.husky/` or `.githooks/` + `core.hooksPath` | You (or an AI session using your credentials) can bypass the remote ruleset, so only a local hook actually fires. Pairs with [secret-guard](scripts/secret-guard). |
+| [kill-port](scripts/kill-port) | Find and kill the process on a TCP port | POSIX sh | `lsof` + `kill` (macOS) | project / `bin` | A dev server is stuck on a port. Linux: use `fuser`/`ss`. |
+| [a11y-check](scripts/a11y-check) | One-command axe-core accessibility smoke check of a URL | sh | `npx @axe-core/cli` + Chrome/driver | project | Quick a11y pass on a small site with no test setup. *Graduate to* [playwright](scripts/playwright)/vitest-axe when you outgrow it. |
+| [playwright](scripts/playwright) | Minimal Playwright e2e + axe-core a11y example (points at google.com) | TS | `@playwright/test`, `@axe-core/playwright` (ships `package.json`) | project | Starting browser/e2e tests. Shows strict + severity-gated a11y assertions. |
+
+## config/ — editor & tool settings
+
+| Snippet | Purpose | Copy to | Reach for it when |
+| --- | --- | --- | --- |
+| [claude-code](config/claude-code) | Security-focused Claude Code `settings.json` (protect secrets, block destructive shell) | `~/.claude` or `<project>/.claude` | Setting up Claude Code with safe defaults. Pairs with [keychain](scripts/keychain) + [secret-guard](scripts/secret-guard). |
+| [claude-code/rules](config/claude-code/rules) | Drop-in `.claude/rules/*.md`: prompt-injection, coding standards, frontend, testing, workflow | `<project>/.claude/rules` | You want durable per-topic rules the assistant follows without restating them. Generic; `security.md` verbatim, rest adapt per stack. |
+| [coderabbit](config/coderabbit) | Example `.coderabbit.yaml` for the CodeRabbit AI PR reviewer (tone, path rules, a11y/TS instructions) | project root | You want automated PR review with house rules checked in. Needs the CodeRabbit GitHub app — a tool config, not CI. |
+| [biome](config/biome) | `biome.json` + "why Biome over Prettier" | project root | Format + lint for JS/TS/JSON. See [conventions](templates/conventions). |
+| [node-version](config/node-version) | Pin Node across a team: `.nvmrc` vs Volta vs Corepack + `engines` | project root | Pinning Node across dev + CI. The [github](templates/github) CI reads `.nvmrc`. |
+| [vscode](config/vscode) | VSCode settings + extensions (incl. Vim) | `<project>/.vscode` or user | Standardizing the editor for a repo. |
+| [iterm2](config/iterm2) *(personal env)* | iTerm2 setup notes (sync prefs to a folder) | n/a (machine setup) | Setting up your terminal. Backs [`wt`](scripts/worktrees) integration. |
+| [bashmarks](config/bashmarks) *(personal env)* | One-letter directory bookmarks | n/a (machine setup) | Jumping between unrelated project roots. |
+
+## templates/ — copyable scaffolding
+
+| Snippet | Purpose | Copy to | Reach for it when |
+| --- | --- | --- | --- |
+| [docs](templates/docs) | Doc scaffolding: `project_log` + ADR templates with guides | `docs/` | Adopting documentation discipline in a repo. |
+| [conventions](templates/conventions) | Opinionated JS/TS tooling conventions: checklist + rationale + reference configs | point an assistant at `conventions.md` | Standing up or auditing a repo's tooling. See [toolchain.md](docs/toolchain.md). |
+| [github](templates/github) | GitHub repo starters: CI workflow, PR + issue templates, dependabot | `.github/` | New-repo scaffolding. Uses [node-version](config/node-version). |
+
+## docs/ — reference (not snippets)
+
+- [toolchain.md](docs/toolchain.md) — tool inventory from the next-template repo.
+- [references.md](docs/references.md) — external resources (agent skills, package hygiene, TS).
+- [ai-collaboration.md](docs/ai-collaboration.md) — personal log of Claude Code friction points + fixes.
+- [global-packages.md](docs/global-packages.md) — global npm CLIs reached for occasionally (ccusage, git-trim, ncu, json-server, http-server, mcp-remote, devlove/devrage).
+- [mermaid.md](docs/mermaid.md) — working notes on Mermaid diagrams (+ the open dark/light theming problem). *(placeholder)*
+- [backlog.md](docs/backlog.md) — candidate snippet ideas not yet built.
 
 ## Project snippets vs your environment
 
 Most of this is **project** material you copy into a repo. A few folders are
 **personal-environment** setup that follows *you* between machines, not any one
 project — `config/iterm2`, `config/bashmarks` (and, for your own use, the `wt`
-worktree helper). They're tagged *personal env* in the map above; an assistant
+worktree helper). They're tagged *personal env* in the tables above; an assistant
 bootstrapping a project can skip them.
 
 ## How to use
 
 Browse to the folder you want, read its `README.md`, and copy the file(s) you need
 into your target project. Each snippet README opens with a quick **purpose / deps /
-copy-to / use-when** header, and notes any required tweaks.
-
-For a structured, at-a-glance map of every snippet — what it's for, its deps, and
-when to reach for it — see **[`docs/INDEX.md`](./docs/INDEX.md)**. It's the fastest
-entry point, and the first thing to point an AI assistant at.
+copy-to / use-when** header, and notes any required tweaks. The tables above are the
+at-a-glance map — start there.
 
 ## Conventions baked in