From 7023b420e44bf8f4b5b967e4f2c34232a2a45afb Mon Sep 17 00:00:00 2001 From: Laurie Reynolds Date: Fri, 10 Jul 2026 11:13:32 -0700 Subject: [PATCH] Merge the snippet index into README; drop docs/INDEX.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pull the routing tables (scripts/config/templates + docs list) up front into README.md so the map — purpose, deps, copy-to, when-to-reach-for-it — is the first thing a reader (or an AI assistant) sees. Replaces the thinner Layout tree the README had. Removes docs/INDEX.md and the dual-maintenance it created: adding a snippet now means one routing-table row in README, not a README tree entry AND an INDEX row. Repointed CLAUDE.md's "start here" and "when adding a snippet" steps at the README table. No dangling INDEX.md references remain; all README links resolve; markdownlint clean. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01SKEr4FwR8c3qz2WRDqgLHu --- CLAUDE.md | 9 +++-- README.md | 101 +++++++++++++++++++++++++++++--------------------- docs/INDEX.md | 59 ----------------------------- 3 files changed, 64 insertions(+), 105 deletions(-) delete mode 100644 docs/INDEX.md diff --git a/CLAUDE.md b/CLAUDE.md index 6565ac1..9fa3503 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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. diff --git a/README.md b/README.md index 74241c2..836c41e 100644 --- a/README.md +++ b/README.md @@ -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) | `/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 `/.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 | `/.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) | `/.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 diff --git a/docs/INDEX.md b/docs/INDEX.md deleted file mode 100644 index d7bb1df..0000000 --- a/docs/INDEX.md +++ /dev/null @@ -1,59 +0,0 @@ -# Index - -A structured, at-a-glance map of every snippet — purpose, dependencies, where it -lands, and when to reach for it. This is the fastest entry point to the library. - -**For an AI assistant:** this file is the routing table. To apply something, find the -row, open that folder's `README.md` (each opens with the same header block), 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) | `/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 `/.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 | `/.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) | `/.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](./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](./toolchain.md) — tool inventory from the next-template repo. -- [references.md](./references.md) — external resources (agent skills, package hygiene, TS). -- [ai-collaboration.md](./ai-collaboration.md) — personal log of Claude Code friction points + fixes. -- [global-packages.md](./global-packages.md) — global npm CLIs reached for occasionally (ccusage, git-trim, ncu, json-server, http-server, mcp-remote, devlove/devrage). -- [mermaid.md](./mermaid.md) — working notes on Mermaid diagrams (+ the open dark/light theming problem). *(placeholder)* -- [backlog.md](./backlog.md) — candidate snippet ideas not yet built. -- [INDEX.md](./INDEX.md) — this file.