docs: split AGENTS.md into core policy and on-demand playbooks

2602.12670 and 2602.11988 findings favoring curated, minimal, modular guidance over comprehensive always-on context

docs/agent-playbooks/bug-investigation.md

@@ -0,0 +1,32 @@
+# Bug Investigation Workflow
+
+Use this when a bug is reported in a specific file/line/code block.
+
+## Mandatory First Step
+
+Before editing, check git history for the relevant code. Previous contributors may have introduced behavior for an edge case/workaround.
+
+## Workflow
+
+1. Scan recent commit titles (titles only) for the file/area:
+
+```bash
+# Recent commit titles for a specific file
+git log --oneline -10 -- src/components/post-desktop/post-desktop.tsx
+
+# Recent commit titles for a specific line range
+git blame -L 120,135 src/components/post-desktop/post-desktop.tsx
+```
+
+2. Inspect only relevant commits with scoped diffs:
+
+```bash
+# Show commit message + diff for one file
+git show <commit-hash> -- path/to/file.tsx
+```
+
+3. Continue with reproduction and fix after understanding the history context.
+
+## Troubleshooting Rule
+
+When blocked, search the web for recent fixes/workarounds.

docs/agent-playbooks/commit-issue-format.md

@@ -0,0 +1,26 @@
+# Commit and Issue Format
+
+Use this when proposing or implementing meaningful code changes.
+
+## Commit Suggestion Format
+
+- **Title:** Conventional Commits style, short, wrapped in backticks.
+- Use `perf` (not `fix`) for performance optimizations.
+- **Description:** Optional 2-3 informal sentences describing the solution. Concise, technical, no bullet points.
+
+Example:
+
+> **Commit title:** `fix: correct date formatting in timezone conversion`
+>
+> Updated `formatDate()` in `date-utils.ts` to properly handle timezone offsets.
+
+## GitHub Issue Suggestion Format
+
+- **Title:** As short as possible, wrapped in backticks.
+- **Description:** 2-3 informal sentences describing the problem (not the solution), as if still unresolved.
+
+Example:
+
+> **GitHub issue:**
+> - **Title:** `Date formatting displays incorrect timezone`
+> - **Description:** Comment timestamps show incorrect timezones when users view posts from different regions. The `formatDate()` function doesn't account for user's local timezone settings.

docs/agent-playbooks/hooks-setup.md

@@ -0,0 +1,75 @@
+# Agent Hooks Setup
+
+If your AI coding assistant supports lifecycle hooks, configure these for this repo.
+
+## Recommended Hooks
+
+| Hook | Command | Purpose |
+|---|---|---|
+| `afterFileEdit` | `npx oxfmt <file>` | Auto-format files after AI edits |
+| `afterFileEdit` | `.cursor/hooks/yarn-install.sh` | Run `yarn install` when `package.json` changes |
+| `stop` | `yarn build && yarn lint && yarn type-check && (yarn audit || true)` | Build, lint, type-check, and security audit at end |
+
+## Why
+
+- Consistent formatting
+- Lockfile stays in sync
+- Build/lint/type issues caught early
+- Security visibility via `yarn audit`
+
+## Example Hook Scripts
+
+### Format Hook
+
+```bash
+#!/bin/bash
+# Auto-format JS/TS files after AI edits
+# Hook receives JSON via stdin with file_path
+
+input=$(cat)
+file_path=$(echo "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/')
+
+case "$file_path" in
+  *.js|*.ts|*.tsx|*.mjs) npx oxfmt "$file_path" 2>/dev/null ;;
+esac
+exit 0
+```
+
+### Verify Hook
+
+```bash
+#!/bin/bash
+# Run build, lint, type-check, and security audit when agent finishes
+
+cat > /dev/null  # consume stdin
+echo "=== yarn build ===" && yarn build
+echo "=== yarn lint ===" && yarn lint
+echo "=== yarn type-check ===" && yarn type-check
+echo "=== yarn audit ===" && (yarn audit || true)  # informational
+exit 0
+```
+
+### Yarn Install Hook
+
+```bash
+#!/bin/bash
+# Run yarn install when package.json is changed
+# Hook receives JSON via stdin with file_path
+
+input=$(cat)
+file_path=$(echo "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/')
+
+if [ -z "$file_path" ]; then
+  exit 0
+fi
+
+if [ "$file_path" = "package.json" ]; then
+  cd "$(dirname "$0")/../.." || exit 0
+  echo "package.json changed - running yarn install to update yarn.lock..."
+  yarn install
+fi
+
+exit 0
+```
+
+Configure hook wiring according to your agent tool docs (`hooks.json`, equivalent, etc.).

docs/agent-playbooks/skills-and-tools.md

@@ -0,0 +1,50 @@
+# Skills and Tools
+
+Use this playbook when setting up/adjusting skills and external tooling.
+
+## Recommended Skills
+
+### Context7 (library docs)
+
+For up-to-date docs on libraries like `plebbit-react-hooks` and `plebbit-js`.
+
+```bash
+npx skills add https://github.com/intellectronica/agent-skills --skill context7
+```
+
+### Vercel React Best Practices
+
+For deeper React/Next performance guidance.
+
+```bash
+npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices
+```
+
+### Find Skills
+
+Discover/install skills from the open ecosystem.
+
+```bash
+npx skills add https://github.com/vercel-labs/skills --skill find-skills
+```
+
+### Playwright CLI
+
+Use `playwright-cli` for browser automation (navigation, interaction, screenshots, tests, extraction).
+
+```bash
+npm install -g @playwright/cli@latest
+playwright-cli install --skills
+```
+
+Skill install locations:
+
+- `.cursor/skills/playwright-cli/`
+- `.claude/skills/playwright-cli/`
+
+## MCP Policy Rationale
+
+Avoid GitHub MCP and browser MCP servers for this project because they add significant tool-schema/context overhead.
+
+- GitHub operations: use `gh` CLI.
+- Browser operations: use `playwright-cli`.

docs/agent-playbooks/translations.md

@@ -0,0 +1,43 @@
+# Translations Workflow
+
+This project uses i18next translation files in `public/translations/{lang}/default.json`.
+
+## Rule
+
+Do not manually edit every language file. Use `scripts/update-translations.js`.
+
+## Add or Update a Key
+
+1. Create a temporary dictionary file, e.g. `translations-temp.json`:
+
+```json
+{
+  "en": "English text",
+  "es": "Spanish text",
+  "fr": "French text",
+  "de": "German text"
+}
+```
+
+2. Apply the translation map:
+
+```bash
+node scripts/update-translations.js --key my_new_key --map translations-temp.json --include-en --write
+```
+
+3. Delete the temporary dictionary file.
+
+## Other Useful Commands
+
+```bash
+# Copy a key from English to all languages (dry run then write)
+node scripts/update-translations.js --key some_key --from en --dry
+node scripts/update-translations.js --key some_key --from en --write
+
+# Delete a key from all languages
+node scripts/update-translations.js --key obsolete_key --delete --write
+
+# Audit for unused translation keys
+node scripts/update-translations.js --audit --dry
+node scripts/update-translations.js --audit --write
+```