diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..50034c0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,60 @@
+# AGENTS.md — versioner-cli
+
+Go CLI for tracking build and deployment events in CI/CD. Go 1.24, Cobra, Viper.
+
+## Cross-repo context
+
+This repo is one of the Versioner app repos.
+
+1. Resolve `versioner-workspace` (nested parent **or** sibling — see that repo's `docs/agent/ECOSYSTEM.md` layout discovery).
+2. Read:
+   - `docs/agent/ECOSYSTEM.md` (routing / which repo)
+   - `docs/agent/CONVENTIONS.md` (branches, PRs, commits)
+3. Then follow **this file** for repo-local setup, test, and architecture.
+
+Do **not** use `versioner-dev-docs`, kanban-markdown feature trees, or machine-specific paths like `/Users/phil...`.
+
+
+## Build & test
+
+```bash
+just setup_local_dev    # go mod download + install golangci-lint
+just build              # bin/versioner
+just build_all          # cross-compile linux/mac/windows amd64+arm64
+just run_tests          # go test -v ./...
+just test_unit          # -short
+just test_integration   # integration only
+just test_coverage      # HTML coverage
+just lint               # golangci-lint
+just fmt                # go fmt + gofmt
+just ci                 # fmt -> tests -> lint -> build
+```
+
+## Architecture
+
+### Entry & commands
+
+- `cmd/versioner/main.go` → `cmd.Execute()`
+- `internal/cmd/root.go` — global flags (`--config`, `--verbose`, `--debug`, `--api-url`, `--api-key`)
+- `internal/cmd/track_build.go` — `versioner track build`
+- `internal/cmd/track_deployment.go` — `versioner track deployment`
+
+### Key modules
+
+- `internal/api/` — HTTP client, 3 retries, exponential backoff
+- `internal/cicd/detector.go` — detects 8 CI systems via env
+- `internal/status/validator.go` — status validation/normalization
+- `internal/github/annotations.go` — GHA annotations
+- `internal/version/version.go` — ldflags version
+
+### Config
+
+Order: `--config` flag → `$HOME/.versioner/config.yaml` → `./config.yaml`.  
+Env prefix: `VERSIONER_` (e.g. `VERSIONER_API_KEY`).
+
+## Local conventions
+
+- Follow existing patterns
+- Blank lines must be completely empty
+- Add tests for new behavior; pass before PR
+- Prefer editing existing files over creating new ones
diff --git a/CLAUDE.md b/CLAUDE.md
index ed74120..a80a9cd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,56 +1,10 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Follow **[AGENTS.md](./AGENTS.md)** in this repository (authoritative for Claude Code and other agents).
 
-## What This Is
+Global Versioner rules live in the `versioner-workspace` spine:
 
-Versioner CLI - a Go command-line tool for tracking build and deployment events in CI/CD pipelines. Go 1.24, Cobra, Viper.
+- `docs/agent/ECOSYSTEM.md` — routing
+- `docs/agent/CONVENTIONS.md` — universal process
 
-## Cross-Repo Context
-
-This repo is part of the Versioner ecosystem. Before starting work:
-- Read relevant feature docs from `../docs/specs/`
-- Read relevant architecture docs from `../docs/architecture/`
-- Add entries to `../changelog.md` as you complete tasks
-
-## Build & Test Commands
-
-All commands use `just` (run `just` to list all):
-
-```bash
-just setup_local_dev    # go mod download + install golangci-lint
-just build              # Build binary to bin/versioner
-just build_all          # Cross-compile for Linux, macOS, Windows (amd64 + arm64)
-just run_tests          # go test -v ./...
-just test_unit          # Unit tests only (-short flag)
-just test_integration   # Integration tests only
-just test_coverage      # Generate HTML coverage report
-just lint               # golangci-lint
-just fmt                # go fmt + gofmt
-just ci                 # fmt -> tests -> lint -> build (full check)
-```
-
-## Architecture
-
-### Entry Point & Commands
-- `cmd/versioner/main.go` - Entry point, calls `cmd.Execute()`
-- `internal/cmd/root.go` - Root command with global flags (--config, --verbose, --debug, --api-url, --api-key)
-- `internal/cmd/track_build.go` - `versioner track build` subcommand
-- `internal/cmd/track_deployment.go` - `versioner track deployment` subcommand
-
-### Key Modules
-- `internal/api/` - HTTP client with retry logic (3 retries, exponential backoff)
-- `internal/cicd/detector.go` - Auto-detects 8 CI/CD systems (GitHub Actions, GitLab, Jenkins, CircleCI, Bitbucket, Azure DevOps, Travis CI, Rundeck) via environment variables
-- `internal/status/validator.go` - Status value validation and normalization
-- `internal/github/annotations.go` - GitHub workflow annotations
-- `internal/version/version.go` - Version info injected via ldflags at build time
-
-### Configuration
-Config loaded from (in order): `--config` flag, `$HOME/.versioner/config.yaml`, `./config.yaml`. Environment variable prefix: `VERSIONER_` (e.g., `VERSIONER_API_KEY`).
-
-## Conventions
-
-- Follow existing code patterns and style
-- Blank lines must be completely empty (no whitespace-only lines)
-- Add tests for new features; ensure tests pass before committing
-- Prefer editing existing files over creating new ones
+Resolve the workspace as a **parent** directory (nested Mac layout) or **sibling** directory (Hermes layout).