📝 Refactor AGENTS.md into hierarchical index structure

Author: OpenWaygate

AGENTS.md

@@ -1,43 +1,35 @@
-# Agent Guidelines
+# Yutu
 
-## OVERVIEW
+Go CLI + MCP server + Agent for YouTube.
 
-Go CLI + MCP server for YouTube.
+## Quick Reference
 
-## STRUCTURE
-
-```text
-.
-├── assets/     # Static assets (logos, etc.)
-├── cmd/        # CLI command definitions (Cobra)
-├── dist/       # Build artifacts
-├── internal/   # Internal tools and private packages
-├── pkg/        # Core domain logic and infrastructure
-└── scripts/    # Utility scripts and smoke tests
-```
-
-## WHERE TO LOOK
-
-- **CLI Entry**: `main.go` -> `cmd/`
-- **Domain Logic**: `pkg/<resource>/` (e.g., `pkg/video/`)
-- **Infrastructure**: `pkg/auth`, `pkg/utils`
-- **Tests**: Co-located `*_test.go` files within `pkg/`
+- **Build**: `go build -o yutu .` or `bazel build //...`
+- **Test**: `go test ./...` or `bazel test //...`
+- **Smoke Tests**: `./scripts/command-test.sh`
+- **Entry Point**: `main.go`
 
-## CODE MAP
+## Directory Index
 
-- `main.go`: Application entry point.
-- `cmd/root.go`: Cobra root command and global flag definitions.
-- `pkg/video/video.go`: Example of domain logic implementation.
+| Directory | Description |
+|-----------|-------------|
+| [cmd/](cmd/AGENTS.md) | CLI command definitions and MCP tool bindings |
+| [pkg/](pkg/AGENTS.md) | Core domain logic and shared infrastructure |
+| [internal/](internal/AGENTS.md) | Internal tools (docgen, skillgen) |
+| [scripts/](scripts/AGENTS.md) | Utility scripts and smoke tests |
+| [docs/](docs/) | Project documentation |
 
-## CONVENTIONS
+## Documentation
 
-- **Build System**: Bazel is used for build/test, though standard Go tools (`go build`, `go test`) also work.
-- **Testing**: Table-driven tests are preferred for consistency and coverage.
-- **Secrets**: `client_secret.json` and `youtube.token.json` are typically stored in the root directory (standard for
-  this project).
+- [docs/FEATURES.md](docs/FEATURES.md) — Feature overview
+- [docs/HOW_TO_TEST.md](docs/HOW_TO_TEST.md) — Testing guide
+- [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) — Contribution guidelines
+- [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md) — Code of conduct
 
-## COMMANDS
+## Conventions
 
-- **Build**: `go build -o yutu .` or `bazel build //...`
-- **Test**: `go test ./...` or `bazel test //...`
-- **Smoke Tests**: `./scripts/command-test.sh`
+- **Secrets**: `client_secret.json` and `youtube.token.json` in root (standard for this project).
+- **Build System**: Bazel is primary, standard Go tools also work.
+- **BUILD.bazel files are auto-generated** — do NOT create or edit them manually. Run `bazel run //:gazelle` to regenerate.
+- After changing dependencies: `bazel run @rules_go//go -- mod tidy -v && bazel mod tidy`.
+- See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the full list of useful build/test/release commands.

cmd/AGENTS.md

@@ -1,20 +1,24 @@
-# OVERVIEW
+# cmd/
 
 CLI command definitions and MCP tool bindings.
 
-# STRUCTURE
+## Wiring
 
-- `root.go`: Root command entry point.
-- `<resource>/`: Subcommands (e.g., `video/`, `channel/`).
+- `main.go` → `cmd.Execute()` → `root.go`
+- Each `<resource>/` dir registers a subcommand + MCP tool
+- `Run` function: binds flags → calls `pkg/<resource>` method
 
-# WIRING PATTERN
+## Conventions
 
-- `main.go` -> `cmd.Execute()` -> `root.go`.
-- `<resource>.go`: Registers subcommand + MCP tool.
-- `Run`: Binds flags -> Calls `pkg/<resource>` method.
-
-# CONVENTIONS
-
-- `resetFlags` in `PersistentPreRun`: Ensures clean state for MCP.
+- `resetFlags` in `PersistentPreRun`: ensures clean state for MCP.
 - MCP tools registered via `mcp.AddTool`.
 - Flags bound to package-level variables.
+- `BUILD.bazel` files are auto-generated — do NOT create or edit them manually.
+
+## Subcommands
+
+Each subdirectory is a 1:1 mapping to a YouTube API resource:
+
+`activity/`, `agent/`, `caption/`, `channel/`, `channelBanner/`, `channelSection/`, `comment/`, `commentThread/`, `i18nLanguage/`, `i18nRegion/`, `member/`, `membershipsLevel/`, `playlist/`, `playlistImage/`, `playlistItem/`, `search/`, `subscription/`, `superChatEvent/`, `thumbnail/`, `video/`, `videoAbuseReportReason/`, `videoCategory/`, `watermark/`
+
+All follow the same pattern — see [Wiring](#wiring) above.

internal/AGENTS.md

@@ -0,0 +1,12 @@
+# internal/
+
+Internal tools and private packages. Not importable by external code.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `tools/docgen/` | Documentation generator |
+| `tools/skillgen/` | Skill file generator |
+
+Each tool is a standalone `main.go` with its own `BUILD.bazel` (auto-generated — do NOT edit manually).

pkg/AGENTS.md

@@ -1,24 +1,30 @@
-# Package Guidelines
-
-## OVERVIEW
+# pkg/
 
 Core domain logic and shared infrastructure.
 
-## STRUCTURE
-
-- `<resource>/`: Domain logic (video, channel, etc.).
-- `auth/`: Authentication service.
-- `utils/`: Generic helpers.
-- `common/`: Shared types.
-
-## PATTERNS
+## Patterns
 
 - 1:1 mapping with YouTube API resources.
-- Structure: `<resource>.go` + `<resource>_test.go` + `BUILD.bazel`.
-- Domain packages depend on `auth` and `common`.
+- Structure: `<resource>.go` + `<resource>_test.go` + `BUILD.bazel` (auto-generated by `bazel run //:gazelle` — do NOT edit manually).
+- Domain packages depend on `auth/` and `common/`.
 
-## TESTING
+## Testing
 
 - Table-driven tests.
 - Real `youtube.Service` with `httptest.NewServer`.
 - Global state (envs) carefully managed/restored.
+- See [docs/HOW_TO_TEST.md](../docs/HOW_TO_TEST.md) for details.
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| `auth/` | Authentication service |
+| `common/` | Shared types |
+| `utils/` | Generic helpers |
+
+### Resource Packages
+
+Each maps 1:1 to a YouTube API resource:
+
+`activity/`, `caption/`, `channel/`, `channelBanner/`, `channelSection/`, `comment/`, `commentThread/`, `i18nLanguage/`, `i18nRegion/`, `member/`, `membershipsLevel/`, `playlist/`, `playlistImage/`, `playlistItem/`, `search/`, `subscription/`, `superChatEvent/`, `thumbnail/`, `video/`, `videoAbuseReportReason/`, `videoCategory/`, `watermark/`

scripts/AGENTS.md

@@ -0,0 +1,12 @@
+# scripts/
+
+Utility scripts for build, test, and release.
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `command-test.sh` | Smoke tests for CLI commands |
+| `bazel-status.sh` | Bazel build status helper |
+| `install.sh` | Installation script |
+| `npm-publish.sh` | NPM package publishing |