docs: add coding rules to CLAUDE.md

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+- Build: `go build -o managerd ./cmd/managerd`
+- Run: `./managerd` (uses `managerd.json` config) or `./managerd <config-path>`
+- Test all: `go test ./...`
+- Test single package: `go test ./internal/service/...`
+- Test single test: `go test ./internal/storage/... -run TestAssetsRepo_SaveTemplate`
+- Verbose test: `go test ./internal/web/... -v -run TestUI_ActionDevicesBatchAction`
+
+## Codebase Architecture
+
+### Layered Structure (no DI framework — manual wiring in main.go)
+
+```
+cmd/managerd/main.go     — Composition root: builds config, services, storage, router
+internal/api/            — Thin HTTP handlers that delegate to services (chi router, no framework)
+internal/web/            — Embedded HTML UI (Go html/template + layout.html pattern)
+internal/service/        — Business logic (discovery, registry, tasks, config assets, preview rendering, template slots)
+internal/storage/        — SQLite persistence (raw SQL via database/sql, pure-Go modernc.org/sqlite driver)
+internal/config/         — JSON config file loading (managerd.json)
+internal/models/         — Core domain types (Device, Task, DeviceTaskStatus, etc.)
+templates/               — Local JSON template files loaded at runtime
+templates/standard_templates/ — "Standard" templates (std_ prefix) imported into SQLite on startup
+```
+
+### Dependency Flow (all wired in main.go)
+
+```
+config → service (agent client, registry, discovery)
+config + service → storage (opens SQLite, creates repos)
+storage → service (task service, config preview, etc.)
+service + storage → api + web (HTTP handlers)
+chi.Router → mounts api routes + UI
+```
+
+### Device Communication
+
+- `AgentClient` proxies HTTP requests to device-side `rk3588-agent` via the device's IP/port.
+- Two timeout tiers: 3s for normal requests, 120s for long operations (config apply, media server, model uploads).
+- All proxied requests carry `X-RK-Token` header from config.
+- Generic passthrough: `r.Handle("/devices/{id}/v1/*", proxyAgentV1)` covers agent sub-routes.
+
+### Config Asset Management
+
+The system manages four asset types stored as JSON blobs in SQLite:
+
+| Asset | Table | Key Concept |
+|---|---|---|
+| Templates | `templates` | Base config template with bindings/variables |
+| Profiles | `profiles` | Template-specific configuration (references `primary_template_name`) |
+| Overlays | `overlays` | Named config overrides that can be appended to any profile |
+| Integration Services | `integration_services` | Third-party service definitions (e.g., RTMP, HTTP push) |
+| Video Sources | `video_sources` | Camera/stream source definitions |
+
+Naming convention: names starting with `std_` are read-only standard templates, imported on startup from `templates/standard_templates/`.
+
+The config preview rendering pipeline: merge template + profile + overlays → resolve binding references (video sources, integration services) → expand slot tokens (`${slot:name.field}`) → compute SHA256 hash.
+
+### Background Goroutines
+
+- RegistryService: 2s tick for offline pruning, 30s tick for graph polling
+- DiscoveryService: UDP broadcast listener (blocking goroutine per discovery request)
+- TaskService: concurrent task execution gated by a semaphore channel
+
+### Key Database Tables (SQLite, migrations in storage/migrate.go)
+
+- `devices` — device registry (device_id PK, ip, port, online status, last_seen)
+- `templates`, `profiles`, `overlays` — config assets
+- `integration_services`, `video_sources` — third-party service and video source definitions
+- `tasks` + `task_devices` — batch task execution (type, status, per-device status)
+- `device_config_state` — per-device applied config state
+- `audit_logs` — action audit trail (actor, action, target, details)
+
+### Test Patterns
+
+- Test files co-located with source: `*_test.go`
+- Services constructed with nil/real dependencies (no mocking framework)
+- HTTP tests use `httptest.NewRequest` + `httptest.NewRecorder`
+- Storage tests use in-memory SQLite (tests seed their own data via repo methods)
+- Tests assert on status codes, redirect URLs, and response body content
+
+## Coding Rules
+
+- **Never use `sed`** on Windows (Git Bash). It produces stray `t` characters, broken indentation, and corrupted files.
+- **Use `rg` and `fd`** for searching (not `grep`/`find`). Both are installed.
+- **File editing**: use the `write` tool for new/rewritten files and `edit` tool for precise changes. For complex find-and-replace, write a small temporary Go program.
+- **No tabs**: use spaces for indentation in all source files.
+- **No `fetch()` in templates** for page data — all API calls must go through Go server-side handlers. JS is only for UI interactivity (modals, carousels, confirm dialogs).
+- **No inline `onclick` with complex quoting** — use `data-*` attributes + event delegation instead.