chore: rename CLAUDE.md to LLM.md, standardize convention

- LLM.md is now the canonical AI context file (tracked in git) - CLAUDE.md is a local symlink to LLM.md (gitignored)
2026-02-17 18:16:03 -08:00
parent 09e598cb57
commit fdf92efee0
3 changed files with 96 additions and 53 deletions
@@ -80,3 +80,5 @@ mem.prof
 **/.claude/settings.local.json

 host-*.json
+
+CLAUDE.md
@@ -1,53 +0,0 @@
-# Loki Development Guide
-
-## Build & Test Commands
-
-```bash
-make all                      # build all binaries
-make loki                     # build loki only
-make logcli                   # build logcli only
-make test                     # run all unit tests
-make test-integration         # run integration tests
-go test ./...                 # run all tests with Go directly
-go test -v ./pkg/logql/...    # run tests in specific package
-go test -run TestName ./pkg/path  # run a specific test
-make lint  # run all linters (use in CI-like environment)
-make format                   # format code (gofmt and goimports)
-```
-
-### Building the Frontend
-
-The Loki UI/frontend (different from the query-frontend) is located in pkg/ui/frontend and is built with [Vite](https://vitejs.dev/). 
-From pkg/ui/frontend, you can use the following commands.
-
-```bash
-make build          # build the frontend
-make check-deps     # check for vulnerabilities in the frontend dependencies
-make clean          # clean the frontend
-make dev            # start the frontend in development mode
-make lint           # lint the frontend code
-make test           # run the frontend tests
-```
-
-## Code Style Guidelines
- Follow standard Go formatting (gofmt/goimports)
- Import order: standard lib, external packages, then Loki packages
- Error handling: Always check errors with `if err != nil { return ... }`
- Use structured logging with leveled logging (go-kit/log)
- Use CamelCase for exported identifiers, camelCase for non-exported 
- Document all exported functions, types, and variables
- Use table-driven tests when appropriate
- Follow Conventional Commits format: `<change type>: Your change`
- For frontend: use TypeScript, functional components, component composition
- Frontend naming: lowercase with dashes for directories (components/auth-wizard)
-
-## Documentation Standards
- Follow the Grafana [Writers' Toolkit](https://grafana.com/docs/writers-toolkit/) Style Guide
- Use CommonMark flavor of markdown for documentation
- Create LIDs (Loki Improvement Documents) for large functionality changes
- Document upgrading steps in `docs/sources/setup/upgrade/_index.md`
- Preview docs locally with `make docs` from the `/docs` directory
- Include examples and clear descriptions for public APIs
-
-## Using Tools
- When using the `mcp__acp__Write` tool, write to a path within the current worktree to avoid sandboxing/permissions issues. This includes when writing plan files.
@@ -0,0 +1,94 @@
+# Hanzo Logs
+
+Fork of Grafana Loki (upstream: `github.com/grafana/loki`).
+Log aggregation system for Hanzo infrastructure.
+
+**Repo**: `github.com/hanzoai/logs`
+**Go module**: `github.com/grafana/loki/v3` (not yet rebranded)
+**Go version**: 1.25.5
+
+## Binaries
+
+Built from `cmd/`:
+
+| Binary | Purpose |
+|--------|---------|
+| `loki` | Log aggregation server |
+| `logcli` | CLI for querying logs |
+| `loki-canary` | End-to-end logging pipeline test tool |
+| `lokitool` | Operational tooling (migration, inspection) |
+| `querytee` | Query comparison proxy |
+| `chunks-inspect` | Chunk data inspector |
+| `dataobj-inspect` | Data object inspector |
+| `logql-analyzer` | LogQL query analyzer |
+
+## Commands
+
+```bash
+make all              # Build all binaries
+make loki             # Build loki only
+make logcli           # Build logcli only
+make test             # Unit tests
+make test-integration # Integration tests
+make lint             # All linters
+make format           # gofmt + goimports
+go test ./...         # Go tests directly
+go test -v ./pkg/logql/...  # Single package
+```
+
+## Frontend (pkg/ui/frontend)
+
+Vite-based UI, separate from the query-frontend service.
+
+```bash
+cd pkg/ui/frontend
+make build   # Build
+make dev     # Dev server
+make lint    # Lint
+make test    # Tests
+```
+
+## Key Directories
+
+```
+cmd/           # Binary entry points
+pkg/           # All library code
+  logql/       # LogQL query engine
+  ingester/    # Log ingestion
+  distributor/ # Write path distribution
+  compactor/   # Index compaction
+  querier/     # Read path
+  storage/     # Storage backends
+  chunkenc/    # Chunk encoding
+  kafka/       # Kafka integration
+  bloomgateway/ # Bloom filter gateway
+  engine/      # Query engine
+clients/       # Log shipping clients (promtail)
+production/    # Deployment configs (Docker, Helm, Nomad, Ksonnet)
+docs/          # Documentation source
+```
+
+## Architecture
+
+- Write path: distributor -> ingester -> storage
+- Read path: query-frontend -> querier -> storage
+- Storage backends: S3, GCS, Azure Blob, filesystem, Bigtable
+- Index: BoltDB, TSDB
+- Query language: LogQL (Prometheus-inspired)
+
+## Style
+
+- Standard Go formatting (gofmt/goimports)
+- Import order: stdlib, external, then loki packages
+- Structured logging via go-kit/log
+- Table-driven tests preferred
+- Conventional commits: `<type>: message`
+- Frontend: TypeScript, functional components, dash-case dirs
+
+## Deployment
+
+Production configs in `production/`:
+- Docker Compose
+- Helm charts
+- Ksonnet/jsonnet manifests
+- Nomad jobs