docs: sync AGENTS guardrails

Author: steipete

AGENTS.md

@@ -17,30 +17,8 @@ Shared guardrails distilled from the various `~/Projects/*/AGENTS.md` files (sta
 - Stick to the package manager and runtime mandated by the repo (pnpm-only, bun-only, swift-only, go-only, etc.). Never swap in alternatives without approval.
 - When editing shared guardrail scripts (runners, committer helpers, browser tools, etc.), mirror the same change back into the `agent-scripts` folder so the canonical copy stays current.
 - Ask the user before adding dependencies, changing build tooling, or altering project-wide configuration.
-- Keep the project’s `AGENTS.md` `<tools>
-# TOOLS
-
-Edit guidance: keep the actual tool list inside the `<tools></tools>` block below so downstream AGENTS syncs can copy the block contents verbatim (without wrapping twice).
-
-<tools>
-- `runner`: Bash shim that routes every command through Bun guardrails (timeouts, git policy, safe deletes).
-- `git` / `bin/git`: Git shim that forces git through the guardrails; use `./git --help` to inspect.
-- `scripts/committer`: Stages the files you list and creates the commit safely.
-- `scripts/docs-list.ts`: Walks `docs/`, enforces front-matter, prints summaries; run `tsx scripts/docs-list.ts`.
-- `scripts/browser-tools.ts`: Chrome helper for remote control/screenshot/eval; run `ts-node scripts/browser-tools.ts --help`.
-- `scripts/runner.ts`: Bun implementation backing `runner`; run `bun scripts/runner.ts --help`.
-- `bin/sleep`: Sleep shim that enforces the 30s ceiling; run `bin/sleep --help`.
-- `xcp`: Xcode project/workspace helper; run `xcp --help`.
-- `oracle`: CLI to bundle prompt + files for another AI; run `npx -y @steipete/oracle --help`.
-- `mcporter`: MCP launcher for any registered MCP server; run `npx mcporter`.
-- `iterm`: Full TTY terminal via MCP; run `npx mcporter iterm`.
-- `firecrawl`: MCP-powered site fetcher to Markdown; run `npx mcporter firecrawl`.
-- `XcodeBuildMCP`: MCP wrapper around Xcode tooling; run `npx mcporter XcodeBuildMCP`.
-- `gh`: GitHub CLI for PRs, CI logs, releases, repo queries; run `gh help`.
-</tools>
-
-</tools>
-` block in sync with the full tool list from `TOOLS.md` so downstream repos get the latest tool descriptions.
+- When discussing dependencies, always provide a GitHub URL.
+- Keep the project’s `AGENTS.md` `<tools></tools>` block in sync with the full tool list from `TOOLS.md` so downstream repos get the latest tool descriptions.
 
 ### tmux & Long Tasks
 - Run any command that could hang (tests, servers, log streams, browser automation) inside tmux using the repository’s preferred entry point.
@@ -51,6 +29,7 @@ Edit guidance: keep the actual tool list inside the `<tools></tools>` block belo
 - Before handing off work, run the full “green gate” for that repo (lint, type-check, tests, doc scripts, etc.). Follow the same command set humans run—no ad-hoc shortcuts.
 - Leave existing watchers running unless the owner tells you to stop them; keep their tmux panes healthy if you started them.
 - Treat every bug fix as a chance to add or extend automated tests that prove the behavior.
+- When someone asks to “fix CI,” use the GitHub CLI (`gh`) to inspect, rerun, and unblock failing workflows on GitHub until they are green.
 
 ### Code Quality & Naming
 - Refactor in place. Never create duplicate files with suffixes such as “V2”, “New”, or “Fixed”; update the canonical file and remove obsolete paths entirely.
@@ -60,11 +39,13 @@ Edit guidance: keep the actual tool list inside the `<tools></tools>` block belo
 
 ### Git, Commits & Releases
 - Invoke git through the provided wrappers, especially for status, diffs, and commits. Only commit or push when the user asks you to do so.
+- To resolve a rebase, `git add`/`git commit` is allowed.
 - Follow the documented release or deployment checklists instead of inventing new steps.
 - Do not delete or rename unfamiliar files without double-checking with the user or the repo instructions.
 
 ### Documentation & Knowledge Capture
 - Update existing docs whenever your change affects them, including front-matter metadata if the repo’s `docs:list` tooling depends on it.
+- Whenever doing a large refactor, track work in `docs/refactor/<title><date>.md`, update it as you go, and delete it when the work is finished.
 - Only create new documentation when the user or local instructions explicitly request it; otherwise, edit the canonical file in place.
 - When you uncover a reproducible tooling or CI issue, record the repro steps and workaround in the designated troubleshooting doc for that repo.
 
@@ -106,7 +87,7 @@ Edit guidance: keep the actual tool list inside the `<tools></tools>` block belo
 - `git` / `bin/git`: Git shim that forces git through the guardrails; use `./git --help` to inspect.
 - `scripts/committer`: Stages the files you list and creates the commit safely.
 - `scripts/docs-list.ts`: Walks `docs/`, enforces front-matter, prints summaries; run `tsx scripts/docs-list.ts`.
-- `scripts/browser-tools.ts`: Chrome helper for remote control/screenshot/eval; run `ts-node scripts/browser-tools.ts --help`.
+- `bin/browser-tools`: Compiled Chrome helper for remote control/screenshot/eval—use the binary (`bin/browser-tools --help`). Source lives in `scripts/browser-tools.ts`; edit there before rebuilding.
 - `scripts/runner.ts`: Bun implementation backing `runner`; run `bun scripts/runner.ts --help`.
 - `bin/sleep`: Sleep shim that enforces the 30s ceiling; run `bin/sleep --help`.
 - `xcp`: Xcode project/workspace helper; run `xcp --help`.
@@ -119,3 +100,5 @@ Edit guidance: keep the actual tool list inside the `<tools></tools>` block belo
 </tools>
 
 </tools>
+
+Guideline: ignore any project folders whose names either contain "copy" or end with a number (e.g., `sweetistics copy`, `sweetistics2`, `VibeMeter3`).