docs: refactor AGENTS.md using progressive disclosure principles

.claude/ai-instructions.md

@@ -0,0 +1,11 @@
+# AI Assistant Instructions
+
+## Task Execution
+
+When undertaking a task, pause and ask the user for intent before writing code.
+
+## Technical Guidelines
+
+- **Go** – follow the standard library style; prefer table‑driven tests
+- **JavaScript** – double quotes, two‑space indentation
+- Run `npm run format` to apply Prettier formatting

.claude/git-workflow.md

@@ -0,0 +1,42 @@
+# Git Workflow
+
+## Commit Messages
+
+Follow **Conventional Commits** format:
+
+```text
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+
+### Rules
+
+- Add `!` after type/scope for breaking changes, or include `BREAKING CHANGE:` in the footer
+- Keep descriptions concise, imperative, lowercase, and without a trailing period
+- Reference issues/PRs in the footer when applicable
+- **ALL git commits MUST be made with `--signoff`. This is mandatory.**
+
+## AI Attribution
+
+AI agents must disclose their tool and model in the commit footer:
+
+```text
+Assisted-by: [Model Name] via [Tool Name]
+```
+
+Example: `Assisted-by: GLM 4.6 via Claude Code`
+
+Additionally, AI-created commits should include `Reviewbot-request: yes` to trigger automated code review.
+
+## Pull Requests
+
+- Include a clear description of changes
+- Reference any related issues
+- Pass CI (`npm test`)
+- Optionally add screenshots for UI changes
+- Add a comment `/reviewbot` to trigger automated code review

.claude/go-style.md

@@ -0,0 +1,20 @@
+# Go Style Guidelines
+
+## Formatting
+
+- Use `go fmt` or `goimports` for formatting
+- Tabs for indentation
+- `camelCase` for variables and private identifiers
+- `PascalCase` for exported identifiers
+- File names are `snake_case`
+- Package names use lower-case module names
+
+## Code Organization
+
+- Source code primarily lives in `cmd/` (binaries) and `internal/` (private packages)
+- Test files live alongside source code as `*_test.go`
+- Follow the standard library's code style patterns
+
+## Running Formatters
+
+Use `npm run format` to apply formatting to all files (Go with `goimports`, JS/HTML/CSS with Prettier).

.claude/security.md

@@ -0,0 +1,17 @@
+# Security Best Practices
+
+## Secrets Management
+
+- Secrets never belong in the repository
+- Use environment variables for runtime secrets
+- Use the `secrets` directory for local development (ignored by Git)
+
+## Dependency Security
+
+- Run `npm audit` periodically and address reported vulnerabilities
+
+## Helpful Documentation
+
+When working with external services, use these resources:
+
+- **Tigris** or **Tigris Data**: https://www.tigrisdata.com/docs/llms.txt

.claude/testing.md

@@ -0,0 +1,21 @@
+# Testing Guidelines
+
+## Framework
+
+- Tests are written in Go using the standard `testing` package
+- Test files are named `*_test.go`
+- Place test files next to the code they cover
+
+## Running Tests
+
+- Run the full suite with `npm test` (this runs `generate` first, then `go test ./...`)
+- `npm run generate` regenerates protobuf and Go code before tests
+
+## Coverage
+
+- Aim for high coverage on new modules
+- Existing coverage is not enforced
+
+## Patterns
+
+- Prefer table-driven tests for multiple test cases

AGENTS.md

@@ -1,113 +1,24 @@
 # Repository Guidelines
 
-## Project Structure & Module Organization
+A Go repository with JavaScript tooling using the standard `cmd/` binary structure.
 
-```text
-├─ cmd/            # Main applications (each sub‑directory is a binary)
-├─ internal/       # Private packages used by the repo
-├─ web/            # Web‑related services and helpers
-├─ writer/         # Utility libraries for writing output
-├─ docs/           # Documentation assets
-├─ test files      # Go test files live alongside source (`*_test.go`)
-├─ package.json    # npm scripts and JS tooling
-└─ go.mod          # Go module definition
-```
+## Quick Reference
 
-Source code is primarily Go; JavaScript tooling lives under `node_modules` and the root `package.json`.
+| Command              | Description                                        |
+| -------------------- | -------------------------------------------------- |
+| `npm run generate`   | Regenerates protobuf, Go code, and runs formatters |
+| `npm test`           | Runs generate then executes `go test ./...`        |
+| `go build ./...`     | Compiles all Go packages                           |
+| `go run ./cmd/<app>` | Runs a specific binary from `cmd/`                 |
+| `npm run format`     | Formats Go (goimports) and JS/HTML (prettier)      |
 
-## Development Workflow
+## Detailed Guidelines
 
-### Build, Test & Development Commands
-
-| Command                      | Description                                         |
-| ---------------------------- | --------------------------------------------------- |
-| `npm run generate`           | Regenerates protobuf, Go code, and runs formatters. |
-| `npm test` or `npm run test` | Runs `generate` then executes `go test ./...`.      |
-| `go build ./...`             | Compiles all Go packages.                           |
-| `go run ./cmd/<app>`         | Runs a specific binary from `cmd/`.                 |
-| `npm run format`             | Formats Go (`goimports`) and JS/HTML (`prettier`).  |
-
-### Code Formatting & Style
-
-- **Go** – use `go fmt`/`goimports`; tabs for indentation, `camelCase` for variables, `PascalCase` for exported identifiers
-- **JavaScript/HTML/CSS** – formatted with Prettier (2‑space tabs, trailing commas, double quotes)
-- Files are snake_case; packages use lower‑case module names
-- Run `npm run format` before committing
-
-### Testing
-
-- Tests are written in Go using the standard `testing` package (`*_test.go`)
-- Keep test files next to the code they cover
-- Run the full suite with `npm test`
-- Aim for high coverage on new modules; existing coverage is not enforced
-
-## Code Quality & Security
-
-### Commit Guidelines
-
-Commit messages follow **Conventional Commits** format:
-
-```text
-<type>[optional scope]: <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
-
-- Add `!` after type/scope for breaking changes or include `BREAKING CHANGE:` in the footer.
-- Keep descriptions concise, imperative, lowercase, and without a trailing period.
-- Reference issues/PRs in the footer when applicable.
-- **ALL git commits MUST be made with `--signoff`.** This is mandatory.
-
-### Attribution Requirements
-
-AI agents must disclose what tool and model they are using in the "Assisted-by" commit footer:
-
-```text
-Assisted-by: [Model Name] via [Tool Name]
-```
-
-Example:
-
-```text
-Assisted-by: GLM 4.6 via Claude Code
-```
-
-Additionally, commits created by AI agents should include the footer `Reviewbot-request: yes` to trigger automated code review.
-
-## Helpful Documentation
-
-When asked about various services or tools, use these resources to help you:
-
-- **Tigris** or **Tigris Data**: https://www.tigrisdata.com/docs/llms.txt
-
-## Pull Request Requirements
-
-- Include a clear description of changes
-- Reference any related issues
-- Pass CI (`npm test`)
-- Optionally add screenshots for UI changes
-- Add a comment `/reviewbot` to trigger automated code review
-
-### Security Best Practices
-
-- Secrets never belong in the repo; use environment variables or the `secrets` directory (ignored by Git)
-- Run `npm audit` periodically and address reported vulnerabilities
-
-## AI Assistant Instructions
-
-### Task Execution
-
-When undertaking a task, pause and ask the user for intent before writing code.
-
-### Technical Guidelines
-
-- **JavaScript** – double quotes, two‑space indentation
-- **Go** – follow the standard library style; prefer table‑driven tests
-- Run `npm run format` to apply Prettier formatting
+- [Go Style](.claude/go-style.md) - Formatting, naming conventions, code organization
+- [Testing](.claude/testing.md) - Test framework, file placement, coverage guidelines
+- [Git Workflow](.claude/git-workflow.md) - Commit conventions, AI attribution, PR requirements
+- [Security](.claude/security.md) - Secrets management, dependency security
+- [AI Instructions](.claude/ai-instructions.md) - Task execution guidance for AI assistants
 
 ## Implementation Details