diff --git a/.agents/skills/epctl-commands/SKILL.md b/.agents/skills/epctl-commands/SKILL.md
new file mode 100644
index 0000000..4e861f3
--- /dev/null
+++ b/.agents/skills/epctl-commands/SKILL.md
@@ -0,0 +1,202 @@
+---
+name: epctl-commands
+description: "Pattern for adding CLI commands to epctl utility. Use when: creating new epctl subcommands, extending CLI functionality, working with cmd/epctl/ files. Covers file structure, urfave/cli v3 patterns, output formatting, and command wiring."
+argument-hint: "Describe the CLI command you want to add"
+---
+
+# epctl CLI Commands — Pattern Guide
+
+You follow this pattern when adding or modifying CLI commands for the `epctl` utility.
+
+## When to Use
+
+- Adding a new subcommand to `epctl`
+- Modifying existing CLI commands
+- Working with files in `cmd/epctl/`
+- Creating new command groups (like `plugins`, `config`)
+
+## Project Structure
+
+```
+cmd/epctl/
+├── main.go                        # Entry point: app.Execute()
+└── internal/
+    ├── output/
+    │   └── printer.go             # Printer (text/JSON dual output)
+    └── app/
+        ├── root.go                # Root command + getPrinter() helper
+        ├── builder.go             # PluginBuilder (business logic)
+        ├── path_filter.go         # PathFilter (business logic)
+        ├── plugins_build.go       # epctl plugins build
+        ├── plugins_register.go    # epctl plugins register
+        ├── plugins_list.go        # epctl plugins list
+        └── config_validate.go     # epctl config validate
+```
+
+### Shared vs CLI-only
+
+| Location | Scope | Example |
+|----------|-------|---------|
+| `internal/config/` | Shared (server + CLI) | Config types, `Validate()` |
+| `cmd/epctl/internal/` | CLI-only | Printer, commands, builder |
+
+**Rule:** if a package is only used by `epctl`, it lives in `cmd/epctl/internal/`. If both server and CLI use it, it stays in `internal/`.
+
+## CLI Framework
+
+**urfave/cli v3** (`github.com/urfave/cli/v3`).
+
+Key patterns:
+- Commands are `*cli.Command` structs
+- Action signature: `func(ctx context.Context, cmd *cli.Command) error`
+- Global flags defined on root command propagate to all subcommands
+- Global `--output` / `-o` flag controls text vs JSON output
+
+## File Naming
+
+Pattern: `<group>_<action>.go`
+
+| File | Command |
+|------|---------|
+| `plugins_build.go` | `epctl plugins build` |
+| `plugins_register.go` | `epctl plugins register` |
+| `plugins_list.go` | `epctl plugins list` |
+| `config_validate.go` | `epctl config validate` |
+
+If a file defines the parent group command (e.g., `newPluginsCmd()`), it goes in the first action file of that group (currently `plugins_build.go`).
+
+## Command Pattern
+
+### Constructor + runner
+
+Every command consists of two functions:
+
+```go
+// Constructor — returns the *cli.Command definition.
+func new<Group><Action>Cmd() *cli.Command {
+    return &cli.Command{
+        Name:      "<action>",
+        Usage:     "Short description",
+        ArgsUsage: "[optional args]",
+        Flags: []cli.Flag{
+            &cli.StringFlag{
+                Name:  "some-flag",
+                Value: "default",
+                Usage: "what it does",
+            },
+        },
+        Action: run<Group><Action>,
+    }
+}
+
+// Runner — implements the command logic.
+func run<Group><Action>(ctx context.Context, cmd *cli.Command) error {
+    printer := getPrinter(cmd)
+
+    // 1. Read flags
+    someFlag := cmd.String("some-flag")
+
+    // 2. Business logic
+    result, err := doSomething(ctx, someFlag)
+    if err != nil {
+        return fmt.Errorf("doSomething: %w", err)
+    }
+
+    // 3. Output via Printer
+    return printer.Table(headers, rows)
+}
+```
+
+### Group command
+
+```go
+func newSomeGroupCmd() *cli.Command {
+    return &cli.Command{
+        Name:  "<group>",
+        Usage: "Group description",
+        Commands: []*cli.Command{
+            newSomeGroupActionCmd(),
+            newSomeGroupOtherCmd(),
+        },
+    }
+}
+```
+
+## Output via Printer
+
+**Every command MUST use `getPrinter(cmd)`** for output. Never use `fmt.Println` directly.
+
+```go
+printer := getPrinter(cmd)
+
+// Simple message
+printer.Message("Done!")              // text: "Done!\n"    json: {"message":"Done!"}
+
+// Table
+printer.Table(
+    []string{"NAME", "STATUS"},       // headers
+    [][]string{{"foo", "ok"}},        // rows
+)
+// text: tabwriter table             json: [{"NAME":"foo","STATUS":"ok"}]
+
+// Error
+printer.Error(err)                    // text: "Error: ...\n"  json: {"error":"..."}
+```
+
+## Wiring a New Command
+
+1. Create `cmd/epctl/internal/app/<group>_<action>.go`
+2. Implement `new<Group><Action>Cmd()` + `run<Group><Action>()`
+3. Add to parent group's `Commands` slice:
+
+```go
+// In the group command constructor:
+Commands: []*cli.Command{
+    newExistingCmd(),
+    newYourNewCmd(),  // ← add here
+},
+```
+
+4. If it's a new group, add to root in `root.go`:
+
+```go
+Commands: []*cli.Command{
+    newPluginsCmd(),
+    newConfigCmd(),
+    newYourGroupCmd(),  // ← add here
+},
+```
+
+## Connecting to EasyP Service
+
+Commands that talk to the service use the SDK:
+
+```go
+client, err := sdk.NewClient(addr, sdk.WithInsecure())
+if err != nil {
+    return fmt.Errorf("cannot connect to %s: %w", addr, err)
+}
+
+defer func() { _ = client.Close() }()
+```
+
+Standard flags for service-connected commands:
+```go
+&cli.StringFlag{
+    Name:  "addr",
+    Value: "localhost:8080",
+    Usage: "gRPC server address",
+},
+```
+
+## Quick Checklist
+
+Before submitting a new CLI command, verify:
+
+- [ ] File named `<group>_<action>.go` in `cmd/epctl/internal/app/`
+- [ ] Uses `getPrinter(cmd)` for all output
+- [ ] Constructor `new<Group><Action>Cmd()` returns `*cli.Command`
+- [ ] Runner `run<Group><Action>(ctx, cmd) error` handles business logic
+- [ ] Wired into parent group's `Commands` slice
+- [ ] Flags have defaults and usage descriptions
+- [ ] Errors wrapped with `fmt.Errorf("<function>: %w", err)`
diff --git a/.agents/skills/go-code-style/SKILL.md b/.agents/skills/go-code-style/SKILL.md
new file mode 100644
index 0000000..17492aa
--- /dev/null
+++ b/.agents/skills/go-code-style/SKILL.md
@@ -0,0 +1,216 @@
+---
+name: go-code-style
+description: "Project-specific Go code style enforcer. Use when: writing Go code, reviewing Go code, refactoring, creating new packages. Covers error wrapping, defer patterns, variable assignment, naming, imports, and other project conventions."
+argument-hint: "Describe the Go code you are writing or reviewing"
+---
+
+# Go Code Style — EasyP Service
+
+You enforce project-specific Go coding conventions for the EasyP Service codebase. These rules are mandatory and take precedence over general Go style guides.
+
+## When to Use
+
+- Writing any Go code in this project
+- Reviewing or refactoring existing Go code
+- Creating new packages, types, or functions
+- Generating code from templates
+
+Every Go code change MUST comply with these rules. Apply them automatically — do not ask the user for permission.
+
+## Anti-Patterns (NEVER DO)
+
+These are the most common mistakes. Memorize and never repeat them.
+
+### 1. Error wrapping with package prefix
+
+```go
+// ❌ WRONG — never add package name prefix
+return fmt.Errorf("goosemigrate: sql.Open: %w", err)
+return fmt.Errorf("registry: c.db.Query: %w", err)
+
+// ✅ CORRECT — only the called function/method name
+return fmt.Errorf("sql.Open: %w", err)
+return fmt.Errorf("c.db.Query: %w", err)
+```
+
+### 2. Assignment inside `if` condition
+
+```go
+// ❌ WRONG — never assign and check in the same line
+if err = db.PingContext(ctx); err != nil {
+    return fmt.Errorf("db.PingContext: %w", err)
+}
+
+if _, err = provider.Up(ctx); err != nil {
+    return fmt.Errorf("provider.Up: %w", err)
+}
+
+// ✅ CORRECT — assignment and check on separate lines
+err = db.PingContext(ctx)
+if err != nil {
+    return fmt.Errorf("db.PingContext: %w", err)
+}
+
+_, err = provider.Up(ctx)
+if err != nil {
+    return fmt.Errorf("provider.Up: %w", err)
+}
+```
+
+**Exception:** short variable declaration with `:=` IS allowed in `if` when the variable is scoped to the block:
+
+```go
+// ✅ OK — new variable scoped to the if block
+if info, err := c.registry.Get(ctx, name); err != nil {
+    ...
+}
+```
+
+### 3. Bare `defer Close()`
+
+```go
+// ❌ WRONG — silently ignores close errors
+defer db.Close()
+defer file.Close()
+defer rows.Close()
+
+// ✅ CORRECT — always log close errors
+defer func() {
+    if err := db.Close(); err != nil {
+        slog.Error("db.Close", "error", err)
+    }
+}()
+```
+
+This applies to ALL resources that return an error from Close: `*sql.DB`, `*os.File`, `*sql.Rows`, `io.Closer`, etc.
+
+### 4. Inline comments on control flow
+
+```go
+// ❌ WRONG — no inline comments on if/for/return
+if err != nil { // check error
+    return err // propagate
+}
+
+// ✅ CORRECT — comment above if needed, or omit entirely
+// Validate connection before proceeding.
+if err != nil {
+    return err
+}
+```
+
+## Error Handling Rules
+
+1. **Wrap at every call site** with `fmt.Errorf("<called_function>: %w", err)`
+2. **Format:** only the function/method name, no package prefix
+3. **Domain errors** are sentinel vars in `core/domain.go`: `core.ErrNotFound`, `core.ErrInvalidPluginName`, etc.
+4. **Never create domain errors** outside `internal/core/domain.go`
+5. **API error mapping:** `ErrorToStatus()` maps domain errors → gRPC status codes
+
+```go
+// Error chain example:
+// adapter → core → api
+return fmt.Errorf("c.registry.Create: %w", err)        // in core
+return fmt.Errorf("c.db.QueryRowContext: %w", err)      // in adapter
+// api layer uses ErrorToStatus() to map, does not wrap
+```
+
+## Import Ordering
+
+Three groups, separated by blank lines. Enforced by `gci`:
+
+```go
+import (
+    // 1. Standard library
+    "context"
+    "fmt"
+    "log/slog"
+
+    // 2. Third-party
+    "github.com/pressly/goose/v3"
+    "google.golang.org/grpc"
+
+    // 3. Project packages
+    "github.com/easyp-tech/service/internal/core"
+)
+```
+
+## Naming Conventions
+
+### Files
+
+| Layer | Pattern | Example |
+|-------|---------|---------|
+| Domain | `domain.go`, `core.go` | `internal/core/domain.go` |
+| Adapters | `<name>.go` | `internal/adapters/registry/registry.go` |
+| API | `api.go`, `mcp.go` | `internal/api/api.go` |
+| Tracing | `tracing_<target>.go` | `internal/telemetry/tracing_core.go` |
+| Tests | `<file>_test.go` | `internal/core/crud_test.go` |
+
+### Types
+
+| Category | Exported? | Example |
+|----------|-----------|---------|
+| Domain entities | Yes | `PluginInfo`, `AuditEntry` |
+| Domain interfaces | Yes | `Registry`, `Plugin`, `FeatureGate` |
+| Config structs | No | `config`, `server`, `ports` |
+| Adapter implementations | Yes | `Store`, `Registry`, `Worker` |
+
+### Enums
+
+```go
+type Feature int
+
+const (
+    _ Feature = iota
+    FeatureCodeGeneration
+    FeaturePluginListing
+)
+```
+
+**Rule:** zero value (`0`) is always reserved with `_` so that uninitialized enum variables are never silently valid.
+
+## Interface Rules
+
+1. **Context first:** `func (r *Registry) Get(ctx context.Context, ...) (Plugin, error)`
+2. **Error always last**
+3. **No `I` prefix:** `Registry`, not `IRegistry`
+4. **Single-method interfaces preferred**
+5. **Interface in consumer package**
+
+## Comments
+
+- **Language:** English only
+- **Godoc:** every exported symbol has a comment starting with its name
+- **No inline comments** on `if`, `for`, `return` lines unless genuinely non-obvious
+- **Package comment:** `// Package <name> provides ...` in one file per package
+
+## Struct Tags
+
+| Layer | Tags | Case |
+|-------|------|------|
+| Domain (`core/`) | None | — |
+| Config (`cmd/`) | `env:""` + `yaml:""` | `snake_case` |
+| Proto (generated) | Don't modify | — |
+
+Tag case: always `snake_case` — enforced by `tagliatelle` linter.
+
+## Concurrency Patterns
+
+- `errgroup` for parallel server startup
+- `WorkerPool` for bounded plugin execution
+- `signal.NotifyContext` + `forceShutdown` goroutine
+- Audit worker: single goroutine, buffered channel
+
+## Quick Checklist
+
+Before submitting any Go code, verify:
+
+- [ ] Error wrapping uses only function name, no package prefix
+- [ ] No assignment inside `if` conditions (except `:=` for new scoped vars)
+- [ ] All `defer Close()` wrapped with error logging
+- [ ] Imports ordered: stdlib → third-party → project
+- [ ] All exported symbols have godoc comments in English
+- [ ] No inline comments on control flow lines
+- [ ] Domain errors defined only in `core/domain.go`
+- [ ] Enum types use `_ = iota` to reserve zero value
diff --git a/.agents/skills/go-testing/SKILL.md b/.agents/skills/go-testing/SKILL.md
new file mode 100644
index 0000000..8ae16a4
--- /dev/null
+++ b/.agents/skills/go-testing/SKILL.md
@@ -0,0 +1,394 @@
+---
+name: go-testing
+description: "Go testing conventions enforcer. Use when: writing tests, reviewing test code, adding test cases, creating test files. Covers table-driven tests, t.Parallel, mocks, assertions, naming conventions."
+argument-hint: "Describe the test you are writing or reviewing"
+---
+
+# Go Testing — EasyP Service
+
+You enforce project-specific Go testing conventions for the EasyP Service codebase. These rules are mandatory and take precedence over general Go testing guides.
+
+## When to Use
+
+- Writing any Go test in this project
+- Reviewing or refactoring existing tests
+- Adding test cases to existing table-driven tests
+- Creating new test files
+- Diagnosing test failures related to shared state or race conditions
+
+Every Go test change MUST comply with these rules. Apply them automatically — do not ask the user for permission.
+
+## Anti-Patterns (NEVER DO)
+
+These are the most common mistakes. Memorize and never repeat them.
+
+### 1. Test case without a name
+
+```go
+// ❌ WRONG — anonymous struct without name field
+tests := []struct {
+    input   string
+    wantErr bool
+}{
+    {"foo", false},
+    {"", true},
+}
+
+// ✅ CORRECT — every case has a descriptive name
+tests := []struct {
+    name    string
+    input   string
+    wantErr bool
+}{
+    {
+        name:  "valid_input",
+        input: "foo",
+    },
+    {
+        name:    "empty_input",
+        input:   "",
+        wantErr: true,
+    },
+}
+```
+
+### 2. Test without t.Parallel()
+
+```go
+// ❌ WRONG — missing t.Parallel() at both levels
+func TestCreatePlugin(t *testing.T) {
+    tests := []struct{ ... }{...}
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            // test body
+        })
+    }
+}
+
+// ✅ CORRECT — t.Parallel() at top-level AND inside each sub-test
+func TestCreatePlugin(t *testing.T) {
+    t.Parallel()
+
+    tests := []struct{ ... }{...}
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel()
+
+            // test body
+        })
+    }
+}
+```
+
+### 3. Shared mutable state between test cases
+
+```go
+// ❌ WRONG — cases share and mutate the same mock
+func TestListPlugins(t *testing.T) {
+    t.Parallel()
+
+    reg := &mockRegistry{} // shared across cases!
+
+    tests := []struct {
+        name  string
+        setup func()
+    }{
+        {
+            name:  "empty",
+            setup: func() { reg.listResult = nil },
+        },
+        {
+            name:  "with_results",
+            setup: func() { reg.listResult = []PluginInfo{{}} }, // mutates shared reg!
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel()
+            tt.setup()       // RACE: parallel sub-tests mutate shared state
+            // ...
+        })
+    }
+}
+
+// ✅ CORRECT — each case creates its own dependencies
+func TestListPlugins(t *testing.T) {
+    t.Parallel()
+
+    tests := []struct {
+        name  string
+        setup func(*mockRegistry)
+        // ...
+    }{
+        {
+            name:  "empty",
+            setup: func(r *mockRegistry) { r.listResult = nil },
+        },
+        {
+            name:  "with_results",
+            setup: func(r *mockRegistry) { r.listResult = []PluginInfo{{}} },
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel()
+
+            reg := &mockRegistry{} // fresh per sub-test
+            tt.setup(reg)
+            // ...
+        })
+    }
+}
+```
+
+> **Red flag:** if one test case can affect another, it means shared mutable state exists. This is a bug in the test (or the code under test). Fix the coupling — do not disable `t.Parallel()`.
+
+### 4. Using assert for fatal preconditions
+
+```go
+// ❌ WRONG — assert does not stop the test; nil dereference follows
+result, err := c.GetPlugin(ctx, req)
+assert.NoError(t, err)
+assert.Equal(t, "grpc", result.Group) // panic if result is nil
+
+// ✅ CORRECT — require stops the test on failure
+result, err := c.GetPlugin(ctx, req)
+require.NoError(t, err)
+assert.Equal(t, "grpc", result.Group)
+```
+
+### 5. Ignoring the error case
+
+```go
+// ❌ WRONG — only checks happy path
+require.NoError(t, err)
+
+// ✅ CORRECT — check specific error with ErrorIs
+if tt.wantErr != nil {
+    require.ErrorIs(t, err, tt.wantErr)
+    return
+}
+require.NoError(t, err)
+```
+
+## Table-Driven Test Template
+
+This is the canonical test structure for the project:
+
+```go
+func TestMethodName(t *testing.T) {
+    t.Parallel()
+
+    tests := []struct {
+        name    string          // REQUIRED, always first field
+        // inputs
+        req     SomeRequest
+        // setup / dependencies
+        setup   func(*mockDep)
+        // expected outputs
+        want    *SomeResult
+        wantErr error
+    }{
+        {
+            name: "success",
+            req:  SomeRequest{Field: "value"},
+            setup: func(m *mockDep) {
+                m.result = &SomeResult{Field: "value"}
+            },
+            want: &SomeResult{Field: "value"},
+        },
+        {
+            name: "not_found",
+            req:  SomeRequest{Field: "missing"},
+            setup: func(m *mockDep) {
+                m.err = ErrNotFound
+            },
+            wantErr: ErrNotFound,
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel()
+
+            // Create fresh dependencies per sub-test
+            dep := &mockDep{}
+            if tt.setup != nil {
+                tt.setup(dep)
+            }
+
+            // Create the system under test
+            sut := New(dep)
+
+            // Execute
+            got, err := sut.Method(context.Background(), tt.req)
+
+            // Assert
+            if tt.wantErr != nil {
+                require.ErrorIs(t, err, tt.wantErr)
+                return
+            }
+            require.NoError(t, err)
+            assert.Equal(t, tt.want, got)
+        })
+    }
+}
+```
+
+### Struct field order
+
+Always follow this order in the test case struct:
+
+1. `name string` — descriptive test case name (always first)
+2. Input fields — request, arguments, parameters
+3. Setup fields — `setup func(...)` for configuring mocks
+4. Expected output fields — `want*`, `wantErr`
+
+## t.Parallel() Rules
+
+### Every table-driven test uses t.Parallel() at two levels
+
+1. **Top-level** — `t.Parallel()` right after `func TestXxx(t *testing.T) {`
+2. **Sub-test** — `t.Parallel()` right after `t.Run(tt.name, func(t *testing.T) {`
+
+### Why two levels?
+
+- **Top-level** `t.Parallel()`: allows this test function to run in parallel with other `Test*` functions in the same package.
+- **Sub-test** `t.Parallel()`: allows table-driven sub-tests to run in parallel with each other within the same `Test*` function.
+
+### When a test cannot be parallel
+
+If a test case cannot run in parallel, it indicates one of these problems:
+
+| Symptom | Root Cause | Fix |
+|---------|-----------|-----|
+| Test modifies package-level variable | Global mutable state | Inject dependency via constructor |
+| Test reads file written by another case | Shared filesystem side effect | Use `t.TempDir()` per case |
+| Test binds to a fixed port | Port conflict | Use port `0` (OS-assigned) |
+| Tests share a mock instance | Shared mutable state | Create mock inside `t.Run` |
+
+**Rule:** never disable `t.Parallel()` to work around coupling. Refactor the code or test instead.
+
+## Mock Patterns
+
+### Inline mocks — no code generation
+
+All mocks are hand-written structs defined in `_test.go` files. No `mockgen`, `moq`, or similar tools.
+
+```go
+type mockRegistry struct {
+    getResult    Plugin
+    getErr       error
+    listResult   []PluginInfo
+    createResult *PluginInfo
+    createErr    error
+}
+
+func (m *mockRegistry) Get(ctx context.Context, group, name, version string) (Plugin, error) {
+    return m.getResult, m.getErr
+}
+
+func (m *mockRegistry) Create(ctx context.Context, info PluginInfo) (*PluginInfo, error) {
+    return m.createResult, m.createErr
+}
+
+func (m *mockRegistry) List(ctx context.Context, filter PluginFilter) ([]PluginInfo, error) {
+    return m.listResult, nil
+}
+```
+
+### Mock struct naming
+
+- Prefix: `mock` (lowercase — unexported)
+- Name: the interface being mocked
+- Example: `mockRegistry` implements `Registry`, `mockFeatureGate` implements `FeatureGate`
+
+### Mock location
+
+Same `_test.go` file that uses them. If multiple test files in a package need the same mock, put it in a shared `helpers_test.go`.
+
+## Assertion Patterns
+
+Uses `testify` (`github.com/stretchr/testify`):
+
+| Function | Package | When to Use |
+|----------|---------|-------------|
+| `require.NoError(t, err)` | `require` | Error must be nil to continue |
+| `require.ErrorIs(t, err, target)` | `require` | Error must match sentinel |
+| `require.ErrorContains(t, err, substr)` | `require` | Error message must contain text |
+| `require.NotNil(t, result)` | `require` | Result must exist before accessing fields |
+| `assert.Equal(t, expected, actual)` | `assert` | Value comparison (test continues on failure) |
+| `assert.Len(t, slice, n)` | `assert` | Collection length check |
+| `assert.Empty(t, slice)` | `assert` | Collection must be empty |
+| `assert.True(t, cond)` | `assert` | Boolean condition |
+
+**Rule of thumb:**
+- `require` — for preconditions: if this fails, the rest of the test is meaningless (stops test)
+- `assert` — for assertions: check values, the test can continue to report multiple failures
+
+## Naming Conventions
+
+### Test files
+
+| Source File | Test File |
+|-------------|-----------|
+| `core.go` | `core_test.go` |
+| `crud.go` | `crud_test.go` |
+| `registry.go` | `registry_test.go` |
+
+### Test functions
+
+| Target | Pattern | Example |
+|--------|---------|---------|
+| Exported method | `Test<Method>` | `TestCreatePlugin` |
+| Unexported function | `Test_<function>` | `Test_validateName` |
+| Multiple scenarios | `Test<Method>_<scenario>` | `TestCreatePlugin_WithTags` |
+
+### Test case names
+
+- Lowercase, descriptive, use underscores for readability
+- Describe the scenario, not the assertion
+
+```go
+// ✅ Good names
+"success"
+"not_found"
+"feature_denied"
+"invalid_plugin_name"
+"empty_version_defaults_to_latest"
+"duplicate_returns_conflict"
+
+// ❌ Bad names
+"test1"
+"case_2"
+"should_work"
+"error"
+"TestCreatePlugin"  // don't repeat the function name
+```
+
+### Test package
+
+Tests use the **same package** (not `_test` suffix). This allows access to unexported symbols:
+
+```go
+// internal/core/crud_test.go
+package core  // same package — NOT core_test
+```
+
+## Quick Checklist
+
+Before submitting any Go test code, verify:
+
+- [ ] Every test case struct has `name string` as the first field
+- [ ] `t.Parallel()` is called at top-level AND inside each `t.Run`
+- [ ] No shared mutable state between test cases
+- [ ] Mocks are created fresh inside each `t.Run` (not shared)
+- [ ] `require` is used for preconditions, `assert` for value checks
+- [ ] Error cases use `require.ErrorIs(t, err, expectedErr)`
+- [ ] Test file uses the same package (no `_test` suffix)
+- [ ] Test case names are lowercase and descriptive
+- [ ] `setup` function (if used) receives mock pointers, does not capture outer scope
diff --git a/.agents/skills/protobuf-expert-skill/SKILL.md b/.agents/skills/protobuf-expert-skill/SKILL.md
new file mode 100644
index 0000000..e03cc55
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/SKILL.md
@@ -0,0 +1,185 @@
+---
+name: protobuf-expert-skill
+description: "Protocol Buffers expert with deep EasyP CLI knowledge. Use when: writing or reviewing .proto files, configuring easyp.yaml, choosing lint rules, setting up code generation plugins, managing proto dependencies, detecting breaking API changes, debugging easyp errors, following protobuf style guide and API design best practices."
+argument-hint: "Describe your protobuf or easyp task (e.g. 'set up linting for my project', 'fix breaking change errors')"
+---
+
+# Protobuf Expert — EasyP CLI Skill
+
+You are an expert in Protocol Buffers design and the EasyP CLI toolkit (drop-in buf.build replacement). Help developers write idiomatic .proto files, configure EasyP correctly, and follow protobuf best practices.
+
+## When to Use
+
+- Writing, reviewing, or refactoring `.proto` files
+- Setting up or modifying `easyp.yaml` configuration
+- Choosing which lint rules to enable
+- Configuring code generation plugins and managed mode
+- Managing proto dependencies (`mod download/update/vendor`)
+- Detecting and resolving breaking API changes
+- Debugging lint errors or generation failures
+- Following protobuf style guide and API design patterns
+- Migrating from buf.build to EasyP
+- Setting up CI/CD for proto linting and breaking checks
+- Installing EasyP
+
+## Decision Flow
+
+```
+User wants to...
+│
+├─ INSTALL EasyP → see [installation.md](./references/installation.md)
+│
+├─ MIGRATE from buf.build → see [migration-from-buf.md](./references/migration-from-buf.md)
+│
+├─ START a new project
+│  ├─ Quick → `easyp init`
+│  └─ Manual → create easyp.yaml, see starter configs in [assets/](./assets/)
+│
+├─ LINT proto files
+│  ├─ Choose rules → § Lint Rule Selection Guide below
+│  ├─ Fix violations → run `easyp lint --debug`, check rule docs
+│  └─ Suppress rules → `lint.except`, `lint.ignore`, or `// easyp:off`
+│
+├─ GENERATE code
+│  ├─ Local plugins → `name` or `path` in `generate.plugins`
+│  ├─ Remote plugins → `remote` in `generate.plugins`
+│  └─ Managed mode → `generate.managed.enabled: true`
+│
+├─ DETECT breaking changes
+│  ├─ Run check → `easyp breaking --against main`
+│  ├─ Resolve → see § Breaking Change Resolution below
+│  └─ Ignore intentional → add to `breaking.ignore`
+│
+├─ SET UP CI/CD → see [ci-cd-integration.md](./references/ci-cd-integration.md)
+│
+└─ DEBUG an error → see [troubleshooting.md](./references/troubleshooting.md)
+```
+
+## Core Knowledge
+
+EasyP is a Go CLI tool (`easyp`) configured via `easyp.yaml`. It provides:
+
+| Command | Purpose |
+|---------|---------|
+| `easyp lint` | Lint .proto files against 42+ rules |
+| `easyp generate` | Generate code via protoc plugins |
+| `easyp breaking` | Detect breaking API changes vs a git ref |
+| `easyp mod download/update/vendor` | Manage proto dependencies |
+| `easyp init` | Interactive config setup |
+| `easyp validate-config` | Validate easyp.yaml |
+| `easyp ls-files` | List proto files with imports |
+| `easyp completion` | Shell completions (bash/zsh) |
+
+Global flags: `--cfg <path>` (default: `easyp.yaml`), `--debug`, `--format text|json`.
+
+## Procedure
+
+### 1. Understand the User's Goal
+
+Identify which workflow applies:
+- **New project setup** → `easyp init` or manual `easyp.yaml` creation
+- **Lint configuration** → Rule selection, groups, ignores
+- **Code generation** → Plugin setup, managed mode, inputs
+- **Dependency management** → `deps` config, mod commands
+- **Breaking change detection** → `breaking` config, git ref comparison
+- **Proto file authoring** → Style guide, naming, structure
+- **Debugging** → Error interpretation, config validation
+
+### 2. Apply the Right Reference
+
+Load the appropriate reference file for detailed information:
+
+| Task | Reference |
+|------|-----------|
+| CLI commands, flags, exit codes | [cli-commands.md](./references/cli-commands.md) |
+| Lint rules (42 rules, 5 groups) | [lint-rules.md](./references/lint-rules.md) |
+| Breaking change checks | [breaking-checks.md](./references/breaking-checks.md) |
+| easyp.yaml full format | [config-reference.md](./references/config-reference.md) |
+| Proto file style and API design | [protobuf-best-practices.md](./references/protobuf-best-practices.md) |
+| Migrating from buf.build | [migration-from-buf.md](./references/migration-from-buf.md) |
+| Troubleshooting & debugging | [troubleshooting.md](./references/troubleshooting.md) |
+| CI/CD integration | [ci-cd-integration.md](./references/ci-cd-integration.md) |
+| Installation methods | [installation.md](./references/installation.md) |
+| Starter configs (Go+gRPC, minimal, strict) | [assets/](./assets/) |
+
+### 3. Lint Rule Selection Guide
+
+When helping users choose rules, recommend by project maturity:
+
+- **Starting out**: Use the `DEFAULT` group (32 rules — covers MINIMAL + BASIC + DEFAULT)
+- **Strict API projects**: `DEFAULT` + `COMMENTS` + `UNARY_RPC` (all 42 rules)
+- **Internal/rapid prototyping**: `BASIC` group (24 rules — less opinionated)
+- **Minimal enforcement**: `MINIMAL` group (4 rules — package consistency only)
+
+Always suggest `allow_comment_ignores: true` for gradual adoption.
+
+### 4. Config Authoring
+
+When creating or modifying `easyp.yaml`:
+1. Start with required section (`lint.use` at minimum)
+2. Add `deps` for any external proto imports
+3. Add `generate` section with plugins, `out`, and `opts`
+4. Add `breaking` section if API stability matters
+5. Validate with `easyp validate-config`
+
+### 5. Proto File Review
+
+When reviewing `.proto` files, check against easyp rules:
+- File name: `lower_snake_case.proto`
+- Package: matches directory, has version suffix (`v1`, `v2`)
+- Naming: Messages/Services/Enums PascalCase, fields lower_snake_case, enum values UPPER_SNAKE_CASE
+- Enum zero value: has `_UNSPECIFIED` suffix (or configured suffix)
+- RPC: request/response types are unique, named `<Method>Request`/`<Method>Response`
+- Comments: all public entities documented
+- Imports: no unused, no public/weak imports
+
+### 6. Breaking Change Resolution
+
+When users encounter breaking changes:
+1. Identify the change type (field deleted, type changed, service removed, etc.)
+2. Explain WHY it's breaking for consumers
+3. Suggest backward-compatible alternatives:
+   - Don't remove fields — deprecate and reserve the number
+   - Don't change field types — add a new field
+   - Don't rename enum values — add new value, deprecate old
+   - Don't remove RPCs — deprecate first
+4. If the break is intentional, suggest adding to `breaking.ignore`
+
+### 7. New Project Setup
+
+When helping users start a new project:
+1. Recommend installation method from [installation.md](./references/installation.md)
+2. Run `easyp init` for interactive setup, OR
+3. Copy a starter config from [assets/](./assets/):
+   - `easyp-minimal.yaml` — linting only (DEFAULT group)
+   - `easyp-go-grpc.yaml` — Go + gRPC with generation
+   - `easyp-strict.yaml` — all 42 rules, Go + gRPC
+4. Run `easyp mod download` if deps are configured
+5. Validate with `easyp validate-config`
+
+### 8. Migration from buf.build
+
+When users are migrating from buf:
+1. Load [migration-from-buf.md](./references/migration-from-buf.md) for the full mapping
+2. Convert `buf.yaml` + `buf.gen.yaml` → single `easyp.yaml`
+3. Replace BSR deps with Git repository URLs
+4. Test: `easyp lint`, `easyp generate`, `easyp breaking`
+5. Update CI with [easyp-tech/actions](https://github.com/easyp-tech/actions)
+
+### 9. CI/CD Setup
+
+When setting up CI/CD:
+1. Load [ci-cd-integration.md](./references/ci-cd-integration.md)
+2. For GitHub → use official `easyp-tech/actions/lint@v1` and `easyp-tech/actions/breaking@v1`
+3. For GitLab/other → use Docker image `ghcr.io/easyp-tech/easyp:<version>`
+4. Always pin EasyP version for reproducibility
+5. Breaking checks need full git history (`fetch-depth: 0`)
+
+## Important Constraints
+
+- EasyP uses `easyp.yaml` (not `buf.yaml`) but is a drop-in buf.build replacement
+- Rule names are UPPER_SNAKE_CASE (e.g., `FIELD_LOWER_SNAKE_CASE`)
+- Groups can be used in `lint.use`: `MINIMAL`, `BASIC`, `DEFAULT`, `COMMENTS`, `UNARY_RPC`
+- Exit codes: 0 = success, 1 = issues found, 2 = critical error
+- `--format json` is available for `lint`, `breaking`, `validate-config`, and `ls-files`
+- Dependencies support `@version` or `@commit-hash` suffixes
diff --git a/.agents/skills/protobuf-expert-skill/assets/easyp-go-grpc.yaml b/.agents/skills/protobuf-expert-skill/assets/easyp-go-grpc.yaml
new file mode 100644
index 0000000..dd0e13b
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/assets/easyp-go-grpc.yaml
@@ -0,0 +1,29 @@
+# EasyP starter config: Go + gRPC project
+# Usage: copy to your project root as easyp.yaml
+
+deps:
+  - github.com/googleapis/googleapis
+  - github.com/protocolbuffers/protobuf
+
+lint:
+  use:
+    - DEFAULT
+    - COMMENTS
+  allow_comment_ignores: true
+
+generate:
+  inputs:
+    - directory: proto
+  plugins:
+    - name: go
+      out: gen/go
+      opts:
+        paths: source_relative
+    - name: go-grpc
+      out: gen/go
+      opts:
+        paths: source_relative
+        require_unimplemented_servers: false
+
+breaking:
+  against_git_ref: main
diff --git a/.agents/skills/protobuf-expert-skill/assets/easyp-minimal.yaml b/.agents/skills/protobuf-expert-skill/assets/easyp-minimal.yaml
new file mode 100644
index 0000000..6208cdb
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/assets/easyp-minimal.yaml
@@ -0,0 +1,7 @@
+# EasyP starter config: minimal linting only
+# Usage: copy to your project root as easyp.yaml
+
+lint:
+  use:
+    - DEFAULT
+  allow_comment_ignores: true
diff --git a/.agents/skills/protobuf-expert-skill/assets/easyp-strict.yaml b/.agents/skills/protobuf-expert-skill/assets/easyp-strict.yaml
new file mode 100644
index 0000000..7cd4cb5
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/assets/easyp-strict.yaml
@@ -0,0 +1,31 @@
+# EasyP starter config: strict API project (all 42 rules)
+# Usage: copy to your project root as easyp.yaml
+
+deps:
+  - github.com/googleapis/googleapis
+  - github.com/protocolbuffers/protobuf
+
+lint:
+  use:
+    - DEFAULT
+    - COMMENTS
+    - UNARY_RPC
+    - PACKAGE_NO_IMPORT_CYCLE
+  allow_comment_ignores: true
+
+generate:
+  inputs:
+    - directory: proto
+  plugins:
+    - name: go
+      out: gen/go
+      opts:
+        paths: source_relative
+    - name: go-grpc
+      out: gen/go
+      opts:
+        paths: source_relative
+        require_unimplemented_servers: false
+
+breaking:
+  against_git_ref: main
diff --git a/.agents/skills/protobuf-expert-skill/references/breaking-checks.md b/.agents/skills/protobuf-expert-skill/references/breaking-checks.md
new file mode 100644
index 0000000..5870050
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/breaking-checks.md
@@ -0,0 +1,92 @@
+# EasyP Breaking Change Checks Reference
+
+EasyP detects breaking API changes by comparing the current proto files against a previous git ref (branch, tag, or commit).
+
+## Usage
+
+```sh
+easyp breaking --path proto --against main
+```
+
+## Configuration
+
+```yaml
+breaking:
+  ignore:
+    - proto/internal          # Paths to exclude from checks
+  against_git_ref: main       # Default ref (overridden by --against flag)
+```
+
+## Check Categories
+
+### Import Changes
+
+| Check | Description |
+|-------|-------------|
+| Import deleted | A previously existing import was removed |
+
+### Service Changes
+
+| Check | Description |
+|-------|-------------|
+| Service deleted | An entire service definition was removed |
+| RPC deleted | An RPC method was removed from a service |
+| RPC request type changed | The request message type of an RPC was changed |
+| RPC response type changed | The response message type of an RPC was changed |
+
+### Message Changes
+
+| Check | Description |
+|-------|-------------|
+| Message deleted | A message definition was removed |
+| Field deleted | A field was removed (reports field number and name) |
+| Field type changed | A field's type was changed |
+| Field became optional | A required/default field was changed to optional |
+| Field became not optional | An optional field was changed to required |
+
+### OneOf Changes
+
+| Check | Description |
+|-------|-------------|
+| OneOf deleted | A oneof group was removed |
+| OneOf field deleted | A field within a oneof was removed |
+| OneOf field type changed | A field type within a oneof was changed |
+
+### Enum Changes
+
+| Check | Description |
+|-------|-------------|
+| Enum deleted | An enum definition was removed |
+| Enum value deleted | An enum value was removed |
+| Enum value name changed | An enum value was renamed |
+
+## Backward-Compatible Alternatives
+
+Instead of making a breaking change, use these patterns:
+
+| Breaking Change | Safe Alternative |
+|----------------|-----------------|
+| Remove a field | Mark as `reserved` and deprecate: `reserved 3; reserved "old_field";` |
+| Change field type | Add a new field with the new type, deprecate the old one |
+| Remove an enum value | Reserve the number and name, add replacement value |
+| Rename an enum value | Add new value, deprecate old (both keep same number) |
+| Remove an RPC | Deprecate with `option deprecated = true;` first |
+| Remove a service | Deprecate first, remove in next major version |
+| Change RPC request/response | Create a new RPC with new types |
+
+## Ignoring Breaking Changes
+
+For intentional breaks, add paths to `breaking.ignore`:
+
+```yaml
+breaking:
+  ignore:
+    - proto/internal/experimental
+```
+
+Or change the comparison ref to start fresh:
+
+```yaml
+breaking:
+  against_git_ref: v2.0.0    # Compare against a specific release tag
+```
diff --git a/.agents/skills/protobuf-expert-skill/references/ci-cd-integration.md b/.agents/skills/protobuf-expert-skill/references/ci-cd-integration.md
new file mode 100644
index 0000000..0138dfd
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/ci-cd-integration.md
@@ -0,0 +1,171 @@
+# EasyP CI/CD Integration
+
+## GitHub Actions (Official)
+
+EasyP provides official GitHub Actions at [easyp-tech/actions](https://github.com/easyp-tech/actions).
+
+### Lint on push and PR
+
+```yaml
+name: easyp-lint
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: easyp-tech/actions/lint@v1
+        with:
+          version: v0.12.2
+```
+
+### Breaking change detection on PR
+
+```yaml
+name: easyp-breaking
+on: [pull_request]
+
+jobs:
+  breaking:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0    # Required — needs full git history
+      - uses: easyp-tech/actions/breaking@v1
+        with:
+          version: v0.12.2
+          against: origin/main
+```
+
+### Combined workflow (lint + breaking)
+
+```yaml
+name: easyp
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: easyp-tech/actions/lint@v1
+        with:
+          version: v0.12.2
+
+  breaking:
+    name: Breaking Changes
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: easyp-tech/actions/breaking@v1
+        with:
+          version: v0.12.2
+          against: origin/main
+```
+
+Features of official actions:
+- Pre-built Docker images (fast, no compilation)
+- GitHub Annotations (errors appear on PR diff lines)
+- Version pinning via `version` input
+
+## GitLab CI
+
+```yaml
+stages:
+  - proto
+
+easyp-lint:
+  stage: proto
+  image: ghcr.io/easyp-tech/easyp:v0.12.2
+  script:
+    - easyp lint
+  rules:
+    - changes:
+        - "**/*.proto"
+        - easyp.yaml
+
+easyp-breaking:
+  stage: proto
+  image: ghcr.io/easyp-tech/easyp:v0.12.2
+  script:
+    - easyp breaking --against origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+  variables:
+    GIT_DEPTH: 0
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+      changes:
+        - "**/*.proto"
+        - easyp.yaml
+```
+
+## Makefile
+
+```makefile
+EASYP_VERSION ?= latest
+
+.PHONY: proto-lint proto-breaking proto-generate proto-download proto-validate
+
+proto-lint:
+	easyp lint
+
+proto-breaking:
+	easyp breaking --against main
+
+proto-generate:
+	easyp generate
+
+proto-download:
+	easyp mod download
+
+proto-validate:
+	easyp validate-config
+
+proto-all: proto-download proto-lint proto-generate
+```
+
+## Pre-commit Hook
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+
+# Lint only changed proto files
+if git diff --cached --name-only | grep -q '\.proto$'; then
+  easyp lint
+  if [ $? -ne 0 ]; then
+    echo "Proto lint failed. Fix issues before committing."
+    exit 1
+  fi
+fi
+```
+
+## Docker-based CI (generic)
+
+For any CI system that supports Docker:
+
+```bash
+docker run --rm \
+  -v $(pwd):/workspace \
+  -w /workspace \
+  ghcr.io/easyp-tech/easyp:v0.12.2 \
+  lint
+```
+
+## Important CI Notes
+
+- **Breaking checks need full git history** — use `fetch-depth: 0` or `GIT_DEPTH: 0`
+- **Pin the EasyP version** — avoid `latest` in CI for reproducibility
+- **Run `validate-config` first** — catches config issues before lint/generate
+- **Cache dependencies** — `easyp mod download` results are cached in `~/.cache/easyp`
diff --git a/.agents/skills/protobuf-expert-skill/references/cli-commands.md b/.agents/skills/protobuf-expert-skill/references/cli-commands.md
new file mode 100644
index 0000000..f35b334
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/cli-commands.md
@@ -0,0 +1,153 @@
+# EasyP CLI Commands Reference
+
+## Global Flags
+
+| Flag | Short | Type | Default | Env Var | Description |
+|------|-------|------|---------|---------|-------------|
+| `--cfg` / `--config` | — | string | `easyp.yaml` | `EASYP_CFG` | Path to config file |
+| `--debug` | `-d` | bool | `false` | `EASYP_DEBUG` | Enable debug logging |
+| `--format` | `-f` | enum | `text` | `EASYP_FORMAT` | Output format: `text` or `json` |
+
+---
+
+## lint (alias: l)
+
+Lint `.proto` files against configured rules.
+
+**Flags:**
+
+| Flag | Short | Type | Default | Description |
+|------|-------|------|---------|-------------|
+| `--path` | `-p` | string | `.` | Relative path to proto directory |
+| `--root` | `-r` | string | project root | Root directory for file search |
+
+**Output formats:**
+- Text: `path:line:column:source message (rule_name)`
+- JSON: Structured issue objects
+
+**Exit codes:** 0 = no issues, 1 = lint issues found, 2 = critical error (e.g., import failure)
+
+---
+
+## generate (alias: g)
+
+Generate code from proto files using configured plugins.
+
+**Flags:**
+
+| Flag | Short | Type | Default | Description |
+|------|-------|------|---------|-------------|
+| `--path` | `-p` | string | `.` | Relative path to proto directory |
+| `--root` | `-r` | string | project root | Root directory for file search |
+| `--descriptor_set_out` | — | string | — | Output path for binary FileDescriptorSet |
+| `--include_imports` | — | bool | `false` | Include transitive deps in FileDescriptorSet |
+
+**Env:** `EASYP_ROOT_GENERATE_PATH` overrides `--path`.
+
+---
+
+## breaking
+
+Detect breaking API changes by comparing against a git ref.
+
+**Flags:**
+
+| Flag | Short | Type | Default | Description |
+|------|-------|------|---------|-------------|
+| `--path` | `-p` | string | `.` | Relative path to proto directory |
+| `--against` | — | string | `master` | Git branch/ref to compare against |
+
+**Exit codes:** 0 = no breaking changes, 1 = breaking changes found, 2 = critical error
+
+---
+
+## mod (alias: m)
+
+Package manager for proto dependencies.
+
+### mod download
+
+Download all dependencies from `deps` and `generate.inputs[].git_repo` to local cache.
+
+No additional flags. Exit code 1 if version not found.
+
+### mod update
+
+Update cached modules to versions specified in config.
+
+No additional flags. Exit code 1 if version not found.
+
+### mod vendor
+
+Copy proto files from cached dependencies into `vendor/` directory.
+
+No additional flags. Exit code 1 if version not found.
+
+---
+
+## init (alias: i)
+
+Interactive configuration setup — creates `easyp.yaml`.
+
+**Flags:**
+
+| Flag | Short | Type | Default | Description |
+|------|-------|------|---------|-------------|
+| `--dir` | `-d` | string | `.` | Directory to initialize |
+
+**Env:** `EASYP_INIT_DIR` overrides `--dir`.
+
+Prompts for: lint rule groups, enum zero value suffix, service suffix, breaking check ref, generate plugins, dependencies.
+
+---
+
+## validate-config (alias: validate)
+
+Validate `easyp.yaml` syntax and structure.
+
+**Output:**
+- JSON: `{"valid": bool, "errors": [...], "warnings": [...]}`
+- Text: tabular format with counts
+
+**Exit codes:** 0 = valid, 1 = validation errors
+
+---
+
+## ls-files (alias: ls)
+
+List `.proto` files considering inputs and imports.
+
+**Flags:**
+
+| Flag | Short | Type | Default | Description |
+|------|-------|------|---------|-------------|
+| `--include-imports` | `-I` | bool | `true` | Include transitive import dependencies |
+
+**Output:** JSON or text with roots, files (source, import path, absolute path), and errors.
+
+---
+
+## schema-gen
+
+Generate JSON Schema artifacts for `easyp.yaml` (for IDE autocompletion).
+
+**Flags:**
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--out-versioned` | string | `schemas/easyp-config-v1.schema.json` | Versioned schema output |
+| `--out-latest` | string | `schemas/easyp-config.schema.json` | Latest schema alias output |
+
+---
+
+## completion
+
+Generate shell completion scripts.
+
+### completion bash
+
+Outputs bash completion function for the `easyp` command.
+
+### completion zsh
+
+Outputs zsh completion function for the `easyp` command.
diff --git a/.agents/skills/protobuf-expert-skill/references/config-reference.md b/.agents/skills/protobuf-expert-skill/references/config-reference.md
new file mode 100644
index 0000000..ee6c350
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/config-reference.md
@@ -0,0 +1,150 @@
+# EasyP Configuration Reference (easyp.yaml)
+
+Complete reference for all configuration sections and options.
+
+## Minimal Example
+
+```yaml
+lint:
+  use:
+    - DEFAULT
+```
+
+## Full Structure
+
+```yaml
+# ─── Lint ───────────────────────────────────────────────
+lint:
+  use:                              # Required. Rule names or group names.
+    - DEFAULT                       # Groups: MINIMAL, BASIC, DEFAULT, COMMENTS, UNARY_RPC
+    - COMMENTS
+    - PACKAGE_NO_IMPORT_CYCLE       # Individual rule names also accepted
+
+  except:                           # Rules to exclude (even if included by group)
+    - SERVICE_SUFFIX
+    - PACKAGE_VERSION_SUFFIX
+
+  enum_zero_value_suffix: _UNSPECIFIED  # Suffix for ENUM_ZERO_VALUE_SUFFIX rule (default: _UNSPECIFIED)
+  service_suffix: Service               # Suffix for SERVICE_SUFFIX rule (default: Service)
+
+  allow_comment_ignores: true       # Allow // easyp:off / // easyp:on in proto files
+
+  ignore:                           # Directories to skip entirely
+    - proto/vendor
+    - proto/third_party
+
+  ignore_only:                      # Per-rule path ignores
+    FIELD_LOWER_SNAKE_CASE:
+      - proto/legacy
+    COMMENT_FIELD:
+      - proto/internal
+
+# ─── Dependencies ──────────────────────────────────────
+deps:
+  - github.com/googleapis/googleapis              # Latest default branch
+  - github.com/grpc-ecosystem/grpc-gateway@v2.0.0 # Specific tag/version
+  - github.com/user/repo@abc123def                # Specific commit hash
+
+# ─── Code Generation ──────────────────────────────────
+generate:
+  inputs:                           # Proto file sources
+    - directory: proto              # Local directory (shorthand)
+    - directory:                    # Full form with all fields
+        path: proto                 #   Path to proto files
+        root: .                     #   Root directory (default: ".")
+
+    - git_repo:                     # Remote git repository
+        url: github.com/user/repo@v1.0.0
+        sub_directory: proto        # Optional: subdirectory within repo
+        root: .                     # Optional: root within subdirectory
+
+  plugins:
+    - name: go                      # Plugin source (one of: name, remote, path, command)
+      out: gen/go                   # Output directory
+      opts:                         # Plugin-specific options (key-value)
+        paths: source_relative
+      with_imports: false           # Generate code for imported files too
+
+    - remote: buf.build/grpc/go     # Remote plugin from registry
+      out: gen/go
+      opts:
+        paths: source_relative
+
+    - path: /usr/local/bin/protoc-gen-custom  # Local binary path
+      out: gen/custom
+
+    - command:                      # Command array to execute
+        - docker
+        - run
+        - --rm
+        - protoc-gen-custom
+      out: gen/custom
+
+  managed:                          # Managed mode — auto-set file/field options
+    enabled: true
+
+    disable:                        # Disable managed mode for specific targets
+      - module: google.protobuf     # By module name
+      - package: com.example        # By proto package
+      - path: proto/internal        # By file path
+      - file_option: go_package     # By file option name
+      - field_option: "(custom)"    # By field option name
+      - field: pkg.Message.field    # By fully qualified field name
+
+    override:                       # Override specific options
+      - file_option: go_package     # Override a file option
+        value: github.com/myorg/pkg
+        module: myapp               # Optional: limit to module
+        package: com.example        # Optional: limit to proto package
+        path: proto/api             # Optional: limit to path
+
+      - field_option: "(validate.rules)"  # Override a field option
+        value: true
+        field: pkg.Message.field    # Optional: limit to specific field
+
+      - file_option: java_package
+        value: com.myorg.proto
+
+# ─── Breaking Change Detection ────────────────────────
+breaking:
+  ignore:                           # Paths to exclude from breaking checks
+    - proto/internal
+    - proto/experimental
+
+  against_git_ref: main             # Default git ref to compare against
+```
+
+## Plugin Source Priority
+
+Each plugin must specify exactly ONE source:
+
+| Source | Description | Example |
+|--------|-------------|---------|
+| `name` | Built-in plugin name | `go`, `go-grpc`, `grpc-gateway`, `openapiv2`, `validate-go` |
+| `remote` | Registry URL | `buf.build/grpc/go` |
+| `path` | Local binary path | `/usr/local/bin/protoc-gen-foo` |
+| `command` | Command array | `["docker", "run", "gen-image"]` |
+
+Plugin `opts` values can be scalars or arrays:
+
+```yaml
+opts:
+  paths: source_relative                    # Scalar value
+  require_unimplemented_servers: false       # Boolean value
+```
+
+## Managed Mode
+
+When `managed.enabled: true`, EasyP automatically sets file options (like `go_package`, `java_package`) based on the proto file's package and path, reducing boilerplate.
+
+Use `managed.disable` to exclude specific modules, packages, or paths from managed mode.
+Use `managed.override` to set specific option values for specific modules.
+
+## Validation
+
+Always validate config after editing:
+
+```sh
+easyp validate-config
+easyp validate-config --format json
+```
diff --git a/.agents/skills/protobuf-expert-skill/references/installation.md b/.agents/skills/protobuf-expert-skill/references/installation.md
new file mode 100644
index 0000000..0005a77
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/installation.md
@@ -0,0 +1,58 @@
+# EasyP Installation Guide
+
+## Homebrew (macOS / Linux)
+
+```bash
+brew install easyp-tech/tap/easyp
+```
+
+## Go Install
+
+Requires Go 1.21+:
+
+```bash
+go install github.com/easyp-tech/easyp/cmd/easyp@latest
+```
+
+## npm
+
+```bash
+npx easyp@latest --help
+```
+
+## Docker
+
+```bash
+docker run --rm -v $(pwd):/workspace ghcr.io/easyp-tech/easyp:latest lint
+```
+
+## Binary from GitHub Releases
+
+Download the appropriate binary from [GitHub Releases](https://github.com/easyp-tech/easyp/releases):
+
+```bash
+# Example for Linux amd64
+curl -Lo easyp https://github.com/easyp-tech/easyp/releases/latest/download/easyp_linux_amd64
+chmod +x easyp
+sudo mv easyp /usr/local/bin/
+```
+
+## Verify Installation
+
+```bash
+easyp --help
+```
+
+## Shell Completions
+
+```bash
+# Bash
+easyp completion bash >> ~/.bashrc
+
+# Zsh
+easyp completion zsh >> ~/.zshrc
+```
+
+## Official Documentation
+
+For the most up-to-date installation methods, see [easyp.tech/docs/guide/introduction/install](https://easyp.tech/docs/guide/introduction/install).
diff --git a/.agents/skills/protobuf-expert-skill/references/lint-rules.md b/.agents/skills/protobuf-expert-skill/references/lint-rules.md
new file mode 100644
index 0000000..c3b593a
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/lint-rules.md
@@ -0,0 +1,154 @@
+# EasyP Lint Rules Reference
+
+EasyP provides 42 lint rules organized into 5 groups. Groups are cumulative — `BASIC` includes `MINIMAL`, `DEFAULT` includes `BASIC`.
+
+## Rule Groups
+
+| Group | Rules | Description |
+|-------|-------|-------------|
+| `MINIMAL` | 4 | Package consistency only |
+| `BASIC` | 24 | MINIMAL + naming conventions and import hygiene |
+| `DEFAULT` | 32 | BASIC + enum/RPC/service/file standards |
+| `COMMENTS` | 7 | Documentation requirements for all entities |
+| `UNARY_RPC` | 2 | Disallow streaming RPCs |
+
+Use a group name directly in `lint.use` to enable all its rules.
+
+---
+
+## MINIMAL Group (4 rules)
+
+| Rule | What it checks |
+|------|----------------|
+| `DIRECTORY_SAME_PACKAGE` | All `.proto` files in the same directory must declare the same package |
+| `PACKAGE_DEFINED` | Every file must have a `package` declaration |
+| `PACKAGE_DIRECTORY_MATCH` | Package name must match the directory path |
+| `PACKAGE_SAME_DIRECTORY` | All files declaring the same package must be in the same directory |
+
+---
+
+## BASIC Group (adds 20 rules)
+
+### Naming
+
+| Rule | What it checks |
+|------|----------------|
+| `ENUM_PASCAL_CASE` | Enum type names must be PascalCase |
+| `ENUM_VALUE_UPPER_SNAKE_CASE` | Enum values must be UPPER_SNAKE_CASE |
+| `FIELD_LOWER_SNAKE_CASE` | Message field names must be lower_snake_case |
+| `MESSAGE_PASCAL_CASE` | Message type names must be PascalCase |
+| `ONEOF_LOWER_SNAKE_CASE` | Oneof field names must be lower_snake_case |
+| `PACKAGE_LOWER_SNAKE_CASE` | Package names must be lower_snake_case |
+| `RPC_PASCAL_CASE` | RPC method names must be PascalCase |
+| `SERVICE_PASCAL_CASE` | Service names must be PascalCase |
+
+### Enums
+
+| Rule | What it checks |
+|------|----------------|
+| `ENUM_FIRST_VALUE_ZERO` | First enum value must have number 0 |
+| `ENUM_NO_ALLOW_ALIAS` | Enums must not use `allow_alias = true` |
+
+### Imports
+
+| Rule | What it checks |
+|------|----------------|
+| `IMPORT_NO_PUBLIC` | No `import public` statements |
+| `IMPORT_NO_WEAK` | No `import weak` statements |
+| `IMPORT_USED` | All imports must be referenced |
+
+### Cross-file Package Consistency
+
+| Rule | What it checks |
+|------|----------------|
+| `PACKAGE_SAME_CSHARP_NAMESPACE` | Files in same package must have same `csharp_namespace` |
+| `PACKAGE_SAME_GO_PACKAGE` | Files in same package must have same `go_package` |
+| `PACKAGE_SAME_JAVA_MULTIPLE_FILES` | Files in same package must have same `java_multiple_files` |
+| `PACKAGE_SAME_JAVA_PACKAGE` | Files in same package must have same `java_package` |
+| `PACKAGE_SAME_PHP_NAMESPACE` | Files in same package must have same `php_namespace` |
+| `PACKAGE_SAME_RUBY_PACKAGE` | Files in same package must have same `ruby_package` |
+| `PACKAGE_SAME_SWIFT_PREFIX` | Files in same package must have same `swift_prefix` |
+
+---
+
+## DEFAULT Group (adds 8 rules)
+
+| Rule | What it checks | Config |
+|------|----------------|--------|
+| `ENUM_VALUE_PREFIX` | Enum values must be prefixed with the enum type name in UPPER_SNAKE_CASE | — |
+| `ENUM_ZERO_VALUE_SUFFIX` | Zero-value enum entry must end with a specific suffix | `lint.enum_zero_value_suffix` (default: `_UNSPECIFIED`) |
+| `FILE_LOWER_SNAKE_CASE` | `.proto` file names must be lower_snake_case | — |
+| `RPC_REQUEST_RESPONSE_UNIQUE` | Each RPC request/response type must be used by only one RPC | — |
+| `RPC_REQUEST_STANDARD_NAME` | RPC request type must be named `<MethodName>Request` | — |
+| `RPC_RESPONSE_STANDARD_NAME` | RPC response type must be named `<MethodName>Response` | — |
+| `PACKAGE_VERSION_SUFFIX` | Package must end with a version (e.g., `.v1`, `.v2beta1`) | — |
+| `SERVICE_SUFFIX` | Service names must end with a configurable suffix | `lint.service_suffix` (default: `Service`) |
+
+---
+
+## COMMENTS Group (7 rules)
+
+| Rule | What it checks |
+|------|----------------|
+| `COMMENT_ENUM` | Enum types must have a non-empty leading comment |
+| `COMMENT_ENUM_VALUE` | Enum values must have a non-empty leading comment |
+| `COMMENT_FIELD` | Message fields must have a non-empty leading comment |
+| `COMMENT_MESSAGE` | Message types must have a non-empty leading comment |
+| `COMMENT_ONEOF` | Oneof fields must have a non-empty leading comment |
+| `COMMENT_RPC` | RPC methods must have a non-empty leading comment |
+| `COMMENT_SERVICE` | Services must have a non-empty leading comment |
+
+---
+
+## UNARY_RPC Group (2 rules)
+
+| Rule | What it checks |
+|------|----------------|
+| `RPC_NO_CLIENT_STREAMING` | RPCs must not use client streaming |
+| `RPC_NO_SERVER_STREAMING` | RPCs must not use server streaming |
+
+---
+
+## Uncategorized (1 rule)
+
+| Rule | What it checks |
+|------|----------------|
+| `PACKAGE_NO_IMPORT_CYCLE` | Packages must not have circular import dependencies |
+
+---
+
+## Suppression
+
+### Ignoring paths
+
+```yaml
+lint:
+  ignore:
+    - proto/vendor        # Ignore entire directories
+  ignore_only:
+    FIELD_LOWER_SNAKE_CASE:
+      - proto/legacy      # Ignore specific rule for specific paths
+```
+
+### Inline comment ignores
+
+Enable with `lint.allow_comment_ignores: true`, then use in `.proto` files:
+
+```protobuf
+// easyp:off
+message legacy_message {  // This won't trigger MESSAGE_PASCAL_CASE
+  string BadField = 1;    // This won't trigger FIELD_LOWER_SNAKE_CASE
+}
+// easyp:on
+```
+
+### Excluding rules
+
+```yaml
+lint:
+  use:
+    - DEFAULT
+  except:
+    - SERVICE_SUFFIX          # Disable individual rules from a group
+    - PACKAGE_VERSION_SUFFIX
+```
diff --git a/.agents/skills/protobuf-expert-skill/references/migration-from-buf.md b/.agents/skills/protobuf-expert-skill/references/migration-from-buf.md
new file mode 100644
index 0000000..110908a
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/migration-from-buf.md
@@ -0,0 +1,124 @@
+# Migration from buf.build to EasyP
+
+EasyP is a drop-in replacement for buf.build. This guide maps buf concepts to EasyP equivalents.
+
+## Command Mapping
+
+| buf command | EasyP equivalent | Notes |
+|-------------|-----------------|-------|
+| `buf lint` | `easyp lint` | Same rule names and groups |
+| `buf breaking` | `easyp breaking` | Same detection categories |
+| `buf generate` | `easyp generate` | Supports local + remote plugins |
+| `buf mod update` | `easyp mod update` | Git-native dependencies |
+| `buf mod init` | `easyp init` | Interactive setup wizard |
+| `buf build` | `easyp generate --descriptor_set_out` | FileDescriptorSet output |
+| `buf format` | — | Not yet supported |
+| `buf push` | — | Not needed (uses Git repos directly) |
+| `buf registry` | — | Not needed (uses Git repos directly) |
+
+## Config File Mapping
+
+| buf file | EasyP file | Notes |
+|----------|-----------|-------|
+| `buf.yaml` | `easyp.yaml` | Single config for all features |
+| `buf.gen.yaml` | `easyp.yaml` (`generate` section) | Merged into main config |
+| `buf.lock` | — | Uses Git refs for pinning |
+
+## Config Structure Migration
+
+### buf.yaml → easyp.yaml: Lint
+
+```yaml
+# buf.yaml                          # easyp.yaml
+version: v1                         # (no version field)
+lint:                                lint:
+  use:                                 use:
+    - DEFAULT                            - DEFAULT
+  except:                              except:
+    - SERVICE_SUFFIX                     - SERVICE_SUFFIX
+  ignore:                              ignore:
+    - proto/vendor                       - proto/vendor
+  allow_comment_ignores: true          allow_comment_ignores: true
+  enum_zero_value_suffix: _UNSPECIFIED enum_zero_value_suffix: _UNSPECIFIED
+  service_suffix: Service              service_suffix: Service
+```
+
+### buf.yaml → easyp.yaml: Breaking
+
+```yaml
+# buf.yaml                          # easyp.yaml
+breaking:                            breaking:
+  use:                                 # (no `use` — all checks enabled)
+    - FILE                             ignore:
+  ignore:                                - proto/internal
+    - proto/internal                   against_git_ref: main
+```
+
+### buf.yaml → easyp.yaml: Dependencies
+
+```yaml
+# buf.yaml                          # easyp.yaml
+deps:                                deps:
+  - buf.build/googleapis/googleapis    - github.com/googleapis/googleapis
+  - buf.build/grpc/grpc               - github.com/grpc/grpc@v1.60.0
+```
+
+Key difference: buf uses BSR module references, EasyP uses **Git repository URLs** with optional `@version` or `@commit` suffixes.
+
+### buf.gen.yaml → easyp.yaml: Code Generation
+
+```yaml
+# buf.gen.yaml                      # easyp.yaml
+version: v1                         generate:
+plugins:                               inputs:
+  - plugin: go                           - directory: proto
+    out: gen/go                        plugins:
+    opt: paths=source_relative           - name: go
+  - plugin: buf.build/grpc/go              out: gen/go
+    out: gen/go                            opts:
+    opt: paths=source_relative               paths: source_relative
+                                         - remote: buf.build/grpc/go
+                                             out: gen/go
+                                             opts:
+                                               paths: source_relative
+```
+
+Key differences:
+- `opt` (string) → `opts` (key-value map)
+- `plugin` → `name`, `remote`, `path`, or `command`
+- Inputs are declared explicitly in `generate.inputs`
+
+## Lint Rule Compatibility
+
+EasyP supports the **same rule names and groups** as buf:
+
+| Group | Rules | Equivalent |
+|-------|-------|-----------|
+| `MINIMAL` | 4 rules | Identical |
+| `BASIC` | 24 rules | Identical |
+| `DEFAULT` | 32 rules | Identical |
+| `COMMENTS` | 7 rules | Identical |
+| `UNARY_RPC` | 2 rules | Identical |
+
+Inline suppression uses `// easyp:off` / `// easyp:on` (instead of `// buf:lint:ignore`).
+
+## Dependency Management Differences
+
+| Concept | buf | EasyP |
+|---------|-----|-------|
+| Registry | BSR (buf.build) | Git repositories |
+| Pinning | `buf.lock` | `@version` or `@commit` in deps URL |
+| Download | `buf mod update` | `easyp mod download` |
+| Vendoring | — | `easyp mod vendor` |
+
+## Migration Steps
+
+1. **Rename config**: Create `easyp.yaml` based on your `buf.yaml` + `buf.gen.yaml`
+2. **Convert deps**: Replace BSR module refs with Git repository URLs
+3. **Convert plugins**: Map `plugin` + `opt` to `name`/`remote` + `opts`
+4. **Download deps**: `easyp mod download`
+5. **Test lint**: `easyp lint` — should produce same results
+6. **Test generate**: `easyp generate` — verify output matches
+7. **Test breaking**: `easyp breaking --against main`
+8. **Update CI**: Replace buf actions with [easyp-tech/actions](https://github.com/easyp-tech/actions)
+9. **Remove buf files**: Delete `buf.yaml`, `buf.gen.yaml`, `buf.lock`
diff --git a/.agents/skills/protobuf-expert-skill/references/protobuf-best-practices.md b/.agents/skills/protobuf-expert-skill/references/protobuf-best-practices.md
new file mode 100644
index 0000000..23d7aff
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/protobuf-best-practices.md
@@ -0,0 +1,237 @@
+# Protobuf Best Practices (EasyP-aligned)
+
+Best practices for writing `.proto` files that are idiomatic, maintainable, and pass EasyP lint rules.
+
+## File Organization
+
+### File naming
+- Use `lower_snake_case.proto` for all file names → enforced by `FILE_LOWER_SNAKE_CASE`
+- One service per file (or group tightly related messages)
+- Name the file after the primary entity: `user_service.proto`, `order.proto`
+
+### Package structure
+- Use dot-separated, lower_snake_case packages → enforced by `PACKAGE_LOWER_SNAKE_CASE`
+- End with a version suffix → enforced by `PACKAGE_VERSION_SUFFIX`
+- Match directory layout → enforced by `PACKAGE_DIRECTORY_MATCH`
+
+```
+proto/
+  myapp/
+    user/
+      v1/
+        user_service.proto    → package myapp.user.v1;
+        user.proto            → package myapp.user.v1;
+    order/
+      v1/
+        order_service.proto   → package myapp.order.v1;
+```
+
+### File options
+- Set `go_package`, `java_package`, etc. consistently within each package
+- Enforced by `PACKAGE_SAME_GO_PACKAGE`, `PACKAGE_SAME_JAVA_PACKAGE`, etc.
+- Consider using EasyP's managed mode to auto-set these
+
+---
+
+## Naming Conventions
+
+| Entity | Convention | Example | EasyP Rule |
+|--------|-----------|---------|------------|
+| Message | PascalCase | `UserProfile` | `MESSAGE_PASCAL_CASE` |
+| Field | lower_snake_case | `first_name` | `FIELD_LOWER_SNAKE_CASE` |
+| Service | PascalCase + suffix | `UserService` | `SERVICE_PASCAL_CASE`, `SERVICE_SUFFIX` |
+| RPC | PascalCase | `GetUser` | `RPC_PASCAL_CASE` |
+| Enum type | PascalCase | `UserStatus` | `ENUM_PASCAL_CASE` |
+| Enum value | UPPER_SNAKE_CASE | `USER_STATUS_ACTIVE` | `ENUM_VALUE_UPPER_SNAKE_CASE` |
+| Oneof | lower_snake_case | `auth_method` | `ONEOF_LOWER_SNAKE_CASE` |
+| Package | lower_snake_case | `myapp.user.v1` | `PACKAGE_LOWER_SNAKE_CASE` |
+| File | lower_snake_case | `user_service.proto` | `FILE_LOWER_SNAKE_CASE` |
+
+---
+
+## Enums
+
+### Zero value
+Every enum must have a zero value with a suffix like `_UNSPECIFIED`:
+
+```protobuf
+enum UserStatus {
+  USER_STATUS_UNSPECIFIED = 0;  // Default/unknown
+  USER_STATUS_ACTIVE = 1;
+  USER_STATUS_INACTIVE = 2;
+}
+```
+
+- Zero value rule → `ENUM_ZERO_VALUE_SUFFIX` (configurable suffix)
+- First value must be 0 → `ENUM_FIRST_VALUE_ZERO`
+
+### Value prefixing
+Prefix all values with the enum type in UPPER_SNAKE_CASE → `ENUM_VALUE_PREFIX`:
+
+```protobuf
+// Good
+enum Color {
+  COLOR_UNSPECIFIED = 0;
+  COLOR_RED = 1;
+}
+
+// Bad — values lack prefix
+enum Color {
+  UNSPECIFIED = 0;
+  RED = 1;
+}
+```
+
+### No aliases
+Avoid `allow_alias = true` → `ENUM_NO_ALLOW_ALIAS`. Use separate values instead.
+
+---
+
+## Services and RPCs
+
+### Request/Response pattern
+Each RPC should have unique, method-named request and response types:
+
+```protobuf
+service UserService {
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
+}
+```
+
+- Unique types → `RPC_REQUEST_RESPONSE_UNIQUE`
+- Naming convention → `RPC_REQUEST_STANDARD_NAME`, `RPC_RESPONSE_STANDARD_NAME`
+
+### Service suffix
+Use a consistent suffix (default: `Service`) → `SERVICE_SUFFIX`
+
+### Streaming considerations
+If using `UNARY_RPC` rules, streaming is disallowed. Design APIs as unary where possible. Use streaming only when truly needed (large data transfers, real-time updates).
+
+---
+
+## Comments and Documentation
+
+Document all public entities with leading comments:
+
+```protobuf
+// UserService handles user account operations.
+service UserService {
+  // GetUser retrieves a user by their unique identifier.
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+}
+
+// UserStatus represents the current state of a user account.
+enum UserStatus {
+  // USER_STATUS_UNSPECIFIED is the default value.
+  USER_STATUS_UNSPECIFIED = 0;
+  // USER_STATUS_ACTIVE means the user can log in.
+  USER_STATUS_ACTIVE = 1;
+}
+
+// GetUserRequest contains the parameters for retrieving a user.
+message GetUserRequest {
+  // user_id is the unique identifier of the user.
+  string user_id = 1;
+}
+```
+
+Enforced by `COMMENT_SERVICE`, `COMMENT_RPC`, `COMMENT_ENUM`, `COMMENT_ENUM_VALUE`, `COMMENT_MESSAGE`, `COMMENT_FIELD`, `COMMENT_ONEOF`.
+
+---
+
+## Imports
+
+- Remove unused imports → `IMPORT_USED`
+- Never use `import public` → `IMPORT_NO_PUBLIC`
+- Never use `import weak` → `IMPORT_NO_WEAK`
+- Avoid circular package imports → `PACKAGE_NO_IMPORT_CYCLE`
+
+---
+
+## Backward Compatibility
+
+### Never do
+
+- Remove or rename fields (reserve instead)
+- Change field types or numbers
+- Remove enum values (reserve instead)
+- Remove or rename RPCs
+- Change RPC request/response types
+
+### Safe changes
+
+- Add new fields (with new field numbers)
+- Add new enum values
+- Add new RPCs to existing services
+- Add new services
+- Add new messages
+- Deprecate fields with `[deprecated = true]`
+
+### Reservations
+
+When removing a field or enum value, reserve both the number and the name:
+
+```protobuf
+message User {
+  reserved 3, 7;
+  reserved "old_field", "legacy_field";
+
+  string name = 1;
+  string email = 2;
+  // field 3 was old_field (removed in v1.2)
+}
+```
+
+---
+
+## API Design Patterns
+
+### Use wrapper messages
+Always wrap request and response in dedicated messages (never use primitives directly):
+
+```protobuf
+// Good
+rpc GetUser(GetUserRequest) returns (GetUserResponse);
+
+// Bad — cannot evolve without breaking
+rpc GetUser(google.protobuf.StringValue) returns (User);
+```
+
+### Pagination
+For list endpoints, use cursor-based or offset pagination:
+
+```protobuf
+message ListUsersRequest {
+  int32 page_size = 1;
+  string page_token = 2;
+}
+
+message ListUsersResponse {
+  repeated User users = 1;
+  string next_page_token = 2;
+}
+```
+
+### Field masks
+Use `google.protobuf.FieldMask` for partial updates:
+
+```protobuf
+message UpdateUserRequest {
+  User user = 1;
+  google.protobuf.FieldMask update_mask = 2;
+}
+```
+
+### Standard method names
+Follow consistent verb patterns: `Get`, `List`, `Create`, `Update`, `Delete`, `BatchGet`, `BatchCreate`.
+
+---
+
+## Versioning
+
+- Use package version suffixes: `myapp.user.v1`, `myapp.user.v2`
+- Never make breaking changes within a version — create `v2` instead
+- Keep old versions running until all clients migrate
+- Enforced by `PACKAGE_VERSION_SUFFIX`
diff --git a/.agents/skills/protobuf-expert-skill/references/troubleshooting.md b/.agents/skills/protobuf-expert-skill/references/troubleshooting.md
new file mode 100644
index 0000000..e97f85f
--- /dev/null
+++ b/.agents/skills/protobuf-expert-skill/references/troubleshooting.md
@@ -0,0 +1,134 @@
+# EasyP Troubleshooting Guide
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (no issues) |
+| 1 | Issues found (lint violations, breaking changes, validation errors) |
+| 2 | Critical error (import failure, config error, runtime crash) |
+
+## Common Errors
+
+### Import not found
+
+**Symptom:** `exit code 2` with message like `import "google/protobuf/timestamp.proto" not found`
+
+**Causes & fixes:**
+1. Missing dependency — add to `deps` in `easyp.yaml`:
+   ```yaml
+   deps:
+     - github.com/protocolbuffers/protobuf@v25.0
+   ```
+2. Dependencies not downloaded — run `easyp mod download`
+3. Wrong `--path` flag — ensure it points to the correct proto directory
+
+### Config validation errors
+
+**Symptom:** `easyp validate-config` returns errors
+
+**Debug:**
+```bash
+easyp validate-config --format json
+```
+
+**Common causes:**
+- Unknown keys (typos in field names)
+- Missing required fields (`lint.use` is required)
+- Invalid rule names in `lint.use` or `lint.except`
+- Plugin missing exactly one source (`name`, `remote`, `path`, or `command`)
+
+### Lint rule not working
+
+**Symptom:** Expected lint violation not reported
+
+**Check:**
+1. Rule is in `lint.use` (either directly or via group)
+2. Rule is NOT in `lint.except`
+3. File path is NOT in `lint.ignore`
+4. Rule is NOT suppressed by `// easyp:off` in the proto file
+5. Run with `--debug` for verbose output: `easyp lint --debug`
+
+### Breaking check fails with "could not get git ref"
+
+**Symptom:** `easyp breaking --against main` fails
+
+**Causes:**
+- Shallow clone — need full history: `git fetch --unshallow` or `fetch-depth: 0` in CI
+- Wrong ref name — verify with `git branch -a` or `git tag -l`
+- Detached HEAD — specify explicit branch: `--against origin/main`
+
+### Generate produces no output
+
+**Symptom:** `easyp generate` runs but no files are created
+
+**Check:**
+1. `generate.inputs` points to directory with `.proto` files
+2. Plugin binary is installed and in `$PATH` (for `name` source)
+3. `out` directory exists or plugin can create it
+4. Run with `--debug`: `easyp generate --debug`
+5. For remote plugins, check network connectivity
+
+### Dependency version not found
+
+**Symptom:** `easyp mod download` fails with exit code 1
+
+**Causes:**
+- Tag doesn't exist — verify tag on the repository: `git ls-remote --tags <url>`
+- Commit hash is wrong or abbreviated — use full hash
+- Repository is private — ensure Git credentials are configured
+
+### Circular import detected
+
+**Symptom:** `PACKAGE_NO_IMPORT_CYCLE` violation
+
+**Debug with:**
+```bash
+easyp ls-files --format json
+```
+
+This shows the full import graph. Refactor packages to break the cycle:
+- Move shared types to a common package
+- Use message wrappers instead of direct cross-package imports
+
+## Debugging Techniques
+
+### Verbose output
+
+```bash
+easyp lint --debug
+easyp generate --debug
+```
+
+### JSON output for parsing
+
+```bash
+easyp lint --format json
+easyp breaking --format json
+easyp validate-config --format json
+easyp ls-files --format json
+```
+
+### List resolved files
+
+```bash
+easyp ls-files                    # With imports
+easyp ls-files --include-imports=false  # Without imports
+```
+
+### Validate config first
+
+Always validate before running other commands:
+```bash
+easyp validate-config
+```
+
+## Environment Variables
+
+| Variable | Overrides | Description |
+|----------|----------|-------------|
+| `EASYP_CFG` | `--cfg` | Path to config file |
+| `EASYP_DEBUG` | `--debug` | Enable debug logging |
+| `EASYP_FORMAT` | `--format` | Output format (text/json) |
+| `EASYP_INIT_DIR` | `init --dir` | Init directory |
+| `EASYP_ROOT_GENERATE_PATH` | `generate --path` | Generate path |
diff --git a/.agents/skills/protoc-gen-mcp-skill/SKILL.md b/.agents/skills/protoc-gen-mcp-skill/SKILL.md
new file mode 100644
index 0000000..2ec79d4
--- /dev/null
+++ b/.agents/skills/protoc-gen-mcp-skill/SKILL.md
@@ -0,0 +1,367 @@
+---
+name: protoc-gen-mcp-skill
+description: "Build MCP servers from protobuf definitions using protoc-gen-mcp and easyp. Use when: creating an MCP server, generating MCP tools from proto files, building a proto-first MCP server in Go, configuring easyp for MCP generation, adding MCP tool annotations to protobuf services, implementing MCP tool handlers, setting up ProtoJSON-based MCP tools, or any task involving protobuf-to-MCP code generation. Also use when the user mentions protoc-gen-mcp, mcp proto, proto mcp server, easyp mcp, or wants type-safe MCP bindings from .proto files."
+---
+
+# protoc-gen-mcp — Proto-First MCP Server Generator
+
+Generate type-safe Go MCP tool bindings from annotated protobuf services.
+Protobuf is the source of truth: define your service once in `.proto`, generate
+both `*.pb.go` and `*.mcp.go`, implement the handler interface, and serve.
+
+## When to Use
+
+- Building a new MCP server and want type-safe, schema-validated tools
+- Already have protobuf services and want to expose them as MCP tools
+- Need JSON Schema validation on MCP tool inputs derived from proto definitions
+- Want ProtoJSON as the wire format for MCP tool requests and responses
+
+## Prerequisites
+
+Install [easyp](https://easyp.tech) — the recommended way to lint and generate:
+
+```bash
+brew install easyp-tech/tap/easyp
+```
+
+Or install from source:
+
+```bash
+go install github.com/easyp-tech/easyp/cmd/easyp@latest
+```
+
+See https://easyp.tech/docs for full documentation.
+
+## Step-by-Step Workflow
+
+### Step 1: Define Your Proto Service
+
+Create a `.proto` file with service, methods, and MCP annotations:
+
+```proto
+syntax = "proto3";
+
+package myapi.v1;
+
+option go_package = "github.com/you/myproject/myapi/v1;myapiv1";
+
+import "mcp/options/v1/options.proto";
+import "google/protobuf/empty.proto";
+
+service MyServiceAPI {
+  option (mcp.options.v1.service) = {
+    namespace: "myapi"
+    description: "My tools exposed as MCP tools."
+  };
+
+  // CreateItem creates a new item.
+  rpc CreateItem(CreateItemRequest) returns (CreateItemResponse) {
+    option (mcp.options.v1.method) = {
+      title: "Create item"
+      description: "Create a new item with validation."
+      annotations: { read_only_hint: false }
+    };
+  }
+
+  // Health returns server status.
+  rpc Health(google.protobuf.Empty) returns (HealthResponse) {
+    option (mcp.options.v1.method) = {
+      title: "Health check"
+      description: "Verify the server is alive."
+      annotations: { read_only_hint: true }
+    };
+  }
+}
+
+message CreateItemRequest {
+  // name is required (singular, non-optional in proto3).
+  string name = 1 [(mcp.options.v1.field) = {
+    description: "Item name."
+    examples: [{ string_value: "Widget" }]
+    min_length: 1
+    max_length: 200
+  }];
+
+  // count has a default and numeric bounds.
+  int32 count = 2 [(mcp.options.v1.field) = {
+    default_value: { number_value: 1 }
+    minimum: 1
+    maximum: 1000
+  }];
+
+  // tags is optional because it is repeated.
+  repeated string tags = 3 [(mcp.options.v1.field) = {
+    max_items: 20
+    unique_items: true
+  }];
+
+  // note is optional because of the `optional` keyword.
+  optional string note = 4;
+}
+
+message CreateItemResponse {
+  string id = 1;
+}
+
+message HealthResponse {
+  string status = 1;
+}
+```
+
+### Step 2: Configure easyp
+
+Create `easyp.yaml` in your project root. This single file drives both
+`protoc-gen-go` (standard Go protobuf) and `protoc-gen-mcp` (MCP bindings):
+
+```yaml
+deps:
+  - github.com/easyp-tech/protoc-gen-mcp@v0.3.1
+
+lint:
+  use:
+    - PACKAGE_DEFINED
+    - PACKAGE_VERSION_SUFFIX
+    - RPC_NO_CLIENT_STREAMING
+    - RPC_NO_SERVER_STREAMING
+
+generate:
+  inputs:
+    - directory:
+        path: proto          # directory containing your .proto files
+        root: "."
+  plugins:
+    - name: go
+      out: .
+      opts:
+        paths: source_relative
+    - command: ["go", "run", "github.com/easyp-tech/protoc-gen-mcp/cmd/protoc-gen-mcp@latest"]
+      out: .
+      opts:
+        paths: source_relative
+```
+
+For reproducible builds, pin a specific version tag instead of `@latest`:
+
+```yaml
+    - command: ["go", "run", "github.com/easyp-tech/protoc-gen-mcp/cmd/protoc-gen-mcp@v0.3.1"]
+```
+
+Why easyp over raw protoc:
+- Single `easyp.yaml` config manages all plugins, lint rules, and dependencies
+- Both `*.pb.go` and `*.mcp.go` are generated in one command
+- Built-in linting catches streaming RPCs and other unsupported patterns early
+- Git-native dependency management with lock files for reproducibility
+- No need to install `protoc` or manage plugin binaries manually
+
+### Step 3: Generate Code
+
+```bash
+# Validate config
+easyp validate-config
+
+# Download dependencies
+easyp mod download
+
+# Lint proto files
+easyp lint -p proto -r .
+
+# Generate *.pb.go and *.mcp.go
+easyp generate -p proto -r .
+```
+
+This produces two files next to your `.proto`:
+- `myapi.pb.go` — standard protobuf Go types
+- `myapi.mcp.go` — MCP tool handler interface + registration
+
+### Step 4: Implement the Handler
+
+The generated code exposes a `<Service>ToolHandler` interface. Implement it:
+
+```go
+package main
+
+import (
+    "context"
+    "log"
+
+    myapiv1 "github.com/you/myproject/myapi/v1"
+    "github.com/modelcontextprotocol/go-sdk/mcp"
+    emptypb "google.golang.org/protobuf/types/known/emptypb"
+)
+
+type handler struct{}
+
+func (handler) CreateItem(
+    _ context.Context,
+    req *myapiv1.CreateItemRequest,
+) (*myapiv1.CreateItemResponse, error) {
+    return &myapiv1.CreateItemResponse{Id: "item-1"}, nil
+}
+
+func (handler) Health(
+    _ context.Context,
+    _ *emptypb.Empty,
+) (*myapiv1.HealthResponse, error) {
+    return &myapiv1.HealthResponse{Status: "ok"}, nil
+}
+
+func main() {
+    server := mcp.NewServer(&mcp.Implementation{
+        Name:    "myapi-mcp",
+        Version: "v0.1.0",
+    }, nil)
+
+    if err := myapiv1.RegisterMyServiceAPITools(server, handler{}); err != nil {
+        log.Fatal(err)
+    }
+
+    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+### Step 5: Run
+
+```bash
+go run ./cmd/myserver
+```
+
+The server communicates over stdio. Connect any MCP client to it. The generated
+tools are `myapi_CreateItem` and `myapi_Health`.
+
+## Key Concepts
+
+### Tool Naming
+
+Generated tool names follow the pattern `{namespace}_{MethodName}`. Dots in
+the namespace are normalized to underscores. Override the method segment with
+`mcp.options.v1.method.name`.
+
+### Requiredness Policy
+
+Requiredness in generated MCP JSON Schema is determined by proto3 syntax:
+
+| Proto Pattern | Required? |
+|---|---|
+| `string name = 1` (singular, no `optional`) | YES |
+| `optional string name = 1` | NO |
+| `repeated string names = 1` | NO |
+| `map<string, string> m = 1` | NO |
+| `oneof choice { ... }` | NO (unless `mcp.options.v1.oneof.required = true`) |
+
+Fields that are not required accept explicit JSON `null`.
+
+### ProtoJSON Contract
+
+MCP tool I/O uses ProtoJSON encoding. Key differences from plain JSON:
+
+- `int64`/`uint64` are JSON **strings**, not numbers
+- `float`/`double` accept `"NaN"`, `"Infinity"`, `"-Infinity"` as strings
+- `bytes` use base64 encoding
+- Enums use string names (e.g., `"FORECAST_MODE_DAILY"`)
+- `Timestamp` → RFC 3339 string, `Duration` → `"3.5s"`, `FieldMask` → `"field1,field2"`
+
+### Supported Protobuf Features
+
+- Scalars, enums, nested messages, repeated, maps, `oneof`, `optional`
+- Recursive messages via `$defs`/`$ref`
+- Well-known types: `Any`, `Empty`, `Timestamp`, `Duration`, `FieldMask`,
+  `Struct`, `Value`, `ListValue`, and all scalar wrapper types
+
+### Fail-Fast Rules
+
+The generator rejects at generation time (not runtime):
+- Proto2 syntax
+- Streaming RPCs (client, server, or bidirectional)
+- Unsupported `google.protobuf.*` types
+
+## Quick Proto Options Reference
+
+```proto
+import "mcp/options/v1/options.proto";
+
+// Service: namespace prefix, description, icons
+option (mcp.options.v1.service) = {
+  namespace: "myapi"
+  description: "My API tools."
+};
+
+// Method: tool name, title, description, visibility, agent hints
+option (mcp.options.v1.method) = {
+  name: "CustomName"
+  title: "Human Title"
+  description: "What this tool does."
+  hidden: true
+  annotations: {
+    read_only_hint: true
+    destructive_hint: false
+    idempotent_hint: true
+  }
+};
+
+// Field: description, examples, defaults, validation constraints
+[(mcp.options.v1.field) = {
+  description: "Field purpose."
+  examples: [{ string_value: "example" }]
+  default_value: { number_value: 42 }
+  pattern: "^[A-Z]"
+  min_length: 1
+  max_length: 255
+  minimum: 0
+  maximum: 100
+  min_items: 1
+  max_items: 50
+  unique_items: true
+}];
+
+// Oneof: make a oneof group required in the MCP schema
+option (mcp.options.v1.oneof) = { required: true };
+
+// Enum: title and description for the enum type
+option (mcp.options.v1.enum) = { title: "Status" };
+
+// Enum value: hide sentinel zero-value from the schema
+UNSPECIFIED = 0 [(mcp.options.v1.enum_value) = { hidden: true }];
+```
+
+For full options details, read `references/options-reference.md` in this skill.
+
+## Common Patterns
+
+### Hide Internal RPCs
+
+```proto
+rpc InternalDebug(DebugRequest) returns (DebugResponse) {
+  option (mcp.options.v1.method) = { hidden: true };
+};
+```
+
+### Read-Only vs Destructive Tools
+
+```proto
+// Read-only query
+option (mcp.options.v1.method) = {
+  annotations: { read_only_hint: true }
+};
+
+// Destructive mutation
+option (mcp.options.v1.method) = {
+  annotations: { destructive_hint: true }
+};
+```
+
+### Namespace Override at Registration
+
+```go
+myapiv1.RegisterMyServiceAPITools(server, handler{},
+    mcpruntime.WithNamespace("custom_prefix"),
+)
+```
+
+## Reference Files
+
+For detailed lookup tables, read these files from this skill directory:
+
+- `references/options-reference.md` — full MCP proto options with all fields and examples
+- `references/schema-mapping.md` — proto type → JSON Schema mapping, well-known types, nullability rules
diff --git a/.agents/skills/protoc-gen-mcp-skill/references/options-reference.md b/.agents/skills/protoc-gen-mcp-skill/references/options-reference.md
new file mode 100644
index 0000000..c05f0ac
--- /dev/null
+++ b/.agents/skills/protoc-gen-mcp-skill/references/options-reference.md
@@ -0,0 +1,212 @@
+# MCP Proto Options Reference
+
+Complete reference for all `mcp.options.v1` protobuf extension options.
+
+Import in your `.proto` files:
+```proto
+import "mcp/options/v1/options.proto";
+```
+
+## ServiceOptions
+
+Applied via `option (mcp.options.v1.service) = { ... };` inside a `service` block.
+
+| Field | Type | Description |
+|---|---|---|
+| `namespace` | `string` | Prefix for all generated tool names (e.g., `weather` → `weather_GetForecast`) |
+| `description` | `string` | Overrides the service description inferred from proto comments |
+| `icons` | `repeated Icon` | Default icon metadata for all tools in this service |
+
+```proto
+service WeatherAPI {
+  option (mcp.options.v1.service) = {
+    namespace: "weather"
+    description: "Weather tools exposed as MCP tools."
+    icons: [{
+      src: "https://example.com/weather.png"
+      mime_type: "image/png"
+    }]
+  };
+}
+```
+
+## MethodOptions
+
+Applied via `option (mcp.options.v1.method) = { ... };` inside an `rpc` block.
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Override the RPC segment of the tool name |
+| `title` | `string` | Human-readable tool title |
+| `description` | `string` | Override description from proto comments |
+| `hidden` | `bool` | Suppress tool generation for this RPC entirely |
+| `annotations` | `ToolAnnotations` | Agent hints (see below) |
+| `icons` | `repeated Icon` | Per-tool icons, overrides service default |
+| `execution` | `ExecutionOptions` | Execution behavior (e.g., `task_support`) |
+
+```proto
+rpc Forecast(GetForecastRequest) returns (GetForecastResponse) {
+  option (mcp.options.v1.method) = {
+    name: "GetForecast"
+    title: "Get forecast"
+    description: "Fetch the forecast for a city."
+    annotations: {
+      read_only_hint: true
+      idempotent_hint: true
+    }
+  };
+}
+```
+
+### ToolAnnotations
+
+| Field | Type | Description |
+|---|---|---|
+| `read_only_hint` | `bool` | Tool only reads data, no side effects |
+| `destructive_hint` | `bool` | Tool may delete or irreversibly modify data |
+| `idempotent_hint` | `bool` | Repeated calls with same input produce same result |
+| `open_world_hint` | `bool` | Tool interacts with external systems |
+
+### Icon
+
+| Field | Type | Description |
+|---|---|---|
+| `src` | `string` | URI to the icon resource |
+| `mime_type` | `string` | MIME type (e.g., `image/png`, `image/svg+xml`) |
+
+### ExecutionOptions
+
+| Field | Type | Description |
+|---|---|---|
+| `task_support` | `TaskSupport` | `TASK_SUPPORT_UNSPECIFIED` or `TASK_SUPPORT_OPTIONAL` |
+
+## FieldOptions
+
+Applied via `[(mcp.options.v1.field) = { ... }]` on a message field.
+
+| Field | Type | Description |
+|---|---|---|
+| `description` | `string` | Override description from proto comments |
+| `examples` | `repeated ExampleValue` | Typed example values for the schema |
+| `default_value` | `ExampleValue` | Explicit default value |
+| `pattern` | `string` | Regex pattern for string fields |
+| `format` | `string` | JSON Schema format (e.g., `email`, `date-time`, `uri`) |
+| `min_length` | `uint32` | Minimum string length |
+| `max_length` | `uint32` | Maximum string length |
+| `minimum` | `float` | Minimum numeric value (inclusive) |
+| `maximum` | `float` | Maximum numeric value (inclusive) |
+| `exclusive_minimum` | `float` | Minimum numeric value (exclusive) |
+| `exclusive_maximum` | `float` | Maximum numeric value (exclusive) |
+| `multiple_of` | `float` | Number must be a multiple of this value |
+| `min_items` | `uint32` | Minimum array length |
+| `max_items` | `uint32` | Maximum array length |
+| `unique_items` | `bool` | Array items must be unique |
+| `read_only` | `bool` | Mark field as read-only |
+
+```proto
+string city = 1 [(mcp.options.v1.field) = {
+  description: "City name."
+  examples: [{ string_value: "Paris" }, { string_value: "London" }]
+  min_length: 1
+  max_length: 100
+  pattern: "^[A-Z]"
+}];
+
+int32 count = 2 [(mcp.options.v1.field) = {
+  default_value: { number_value: 10 }
+  minimum: 1
+  maximum: 1000
+}];
+
+repeated string labels = 5 [(mcp.options.v1.field) = {
+  min_items: 1
+  max_items: 50
+  unique_items: true
+}];
+```
+
+### ExampleValue
+
+Typed example values used in `examples` and `default_value`:
+
+| Oneof Field | Type | Usage |
+|---|---|---|
+| `string_value` | `string` | `{ string_value: "Paris" }` |
+| `number_value` | `double` | `{ number_value: 42.5 }` |
+| `integer_value` | `int64` | `{ integer_value: 10 }` |
+| `bool_value` | `bool` | `{ bool_value: true }` |
+| `array_value` | `ArrayValue` | `{ array_value: { items: [{ string_value: "a" }] } }` |
+| `object_value` | `ObjectValue` | `{ object_value: { fields: [{ key: "k" value: { string_value: "v" } }] } }` |
+| `null_value` | `NullValue` | `{ null_value: NULL_VALUE }` |
+
+## MessageOptions
+
+Applied via `option (mcp.options.v1.message) = { ... };` inside a `message` block.
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `string` | Human-readable message title |
+| `description` | `string` | Message description |
+| `examples` | `repeated ExampleValue` | Example message payloads |
+
+## OneofOptions
+
+Applied via `option (mcp.options.v1.oneof) = { ... };` inside a `oneof` block.
+
+| Field | Type | Description |
+|---|---|---|
+| `description` | `string` | Description of the oneof group |
+| `required` | `bool` | If true, exactly one variant must be set |
+
+```proto
+oneof selector {
+  option (mcp.options.v1.oneof) = {
+    description: "Select how to find the city."
+    required: true
+  };
+  string city_alias = 41;
+  int64 city_id = 42;
+}
+```
+
+## EnumOptions
+
+Applied via `option (mcp.options.v1.enum) = { ... };` inside an `enum` block.
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | `string` | Human-readable enum title |
+| `description` | `string` | Enum description |
+
+## EnumValueOptions
+
+Applied via `[(mcp.options.v1.enum_value) = { ... }]` on an enum value.
+
+| Field | Type | Description |
+|---|---|---|
+| `description` | `string` | Description for this enum value |
+| `hidden` | `bool` | Hide this value from the schema (commonly used for sentinel zero-values) |
+
+```proto
+enum ForecastMode {
+  option (mcp.options.v1.enum) = {
+    title: "Forecast Mode"
+    description: "Scope of the forecast."
+  };
+
+  FORECAST_MODE_NONE = 0 [(mcp.options.v1.enum_value) = { hidden: true }];
+  FORECAST_MODE_DAILY = 1;
+  FORECAST_MODE_HOURLY = 2;
+}
+```
+
+## Comment-Based Metadata
+
+Proto comments also contribute to generated metadata:
+
+- Plain comment lines become descriptions
+- `Example: ...` adds a single schema example
+- `Examples: ... | ...` adds multiple schema examples (pipe-separated)
+
+Field options (`mcp.options.v1.field`) take precedence when both comments and
+options define the same metadata.
diff --git a/.agents/skills/protoc-gen-mcp-skill/references/schema-mapping.md b/.agents/skills/protoc-gen-mcp-skill/references/schema-mapping.md
new file mode 100644
index 0000000..60ae9bb
--- /dev/null
+++ b/.agents/skills/protoc-gen-mcp-skill/references/schema-mapping.md
@@ -0,0 +1,91 @@
+# Proto Type → JSON Schema Mapping
+
+## Scalar Types
+
+| Proto Type | JSON Schema Type | Notes |
+|---|---|---|
+| `int32`, `sint32`, `sfixed32` | `integer` | — |
+| `uint32`, `fixed32` | `integer`, `minimum: 0` | — |
+| `int64`, `sint64`, `sfixed64` | `string` | ProtoJSON encodes as string |
+| `uint64`, `fixed64` | `string` | ProtoJSON encodes as string |
+| `float`, `double` | `number` | Also accepts `"NaN"`, `"Infinity"`, `"-Infinity"` strings |
+| `bool` | `boolean` | — |
+| `string` | `string` | — |
+| `bytes` | `string` | base64 encoding |
+| `enum` | `string` | ProtoJSON enum name strings; hidden zero-values excluded |
+
+## Compound Types
+
+| Proto Type | JSON Schema Type | Notes |
+|---|---|---|
+| `message` | `object` | Nested schema; recursive via `$defs`/`$ref` |
+| `repeated T` | `array` of T | — |
+| `map<K, V>` | `object` with `additionalProperties` | Key type determines `propertyNames.pattern` |
+| `oneof` | `oneOf` array | Discriminated union of variants |
+
+## Well-Known Types
+
+| Proto Type | JSON Schema | ProtoJSON Shape |
+|---|---|---|
+| `google.protobuf.Timestamp` | `string` (format: `date-time`) | `"2024-01-01T00:00:00Z"` |
+| `google.protobuf.Duration` | `string` | `"3.5s"` |
+| `google.protobuf.FieldMask` | `string` | `"field1,field2"` |
+| `google.protobuf.Struct` | `object` (free-form) | `{ "key": value }` |
+| `google.protobuf.Value` | any JSON value | `true`, `1.0`, `"str"`, `null`, `[]`, `{}` |
+| `google.protobuf.ListValue` | `array` | `[value, ...]` |
+| `google.protobuf.Any` | `object` with `@type` | `{"@type": "type.googleapis.com/...", ...}` |
+| `google.protobuf.Empty` | `object` (empty) | `{}` |
+| `google.protobuf.*Value` wrappers | unwrapped scalar type | `42`, `"str"`, `true` |
+
+Supported wrapper types: `BoolValue`, `StringValue`, `BytesValue`,
+`Int32Value`, `UInt32Value`, `Int64Value`, `UInt64Value`, `FloatValue`, `DoubleValue`.
+
+## Map Key Patterns
+
+| Key Type | `propertyNames.pattern` |
+|---|---|
+| `string` | (no constraint) |
+| `int32`, `sint32`, `sfixed32` | `^-?[0-9]+$` |
+| `uint32`, `fixed32`, `uint64`, `fixed64` | `^[0-9]+$` |
+| `int64`, `sint64`, `sfixed64` | `^-?[0-9]+$` |
+| `bool` | `^(true\|false)$` |
+
+## Requiredness Decision Tree
+
+```
+Is the field...
+├── proto3 `optional`?           → NOT required, nullable
+├── `repeated`?                  → NOT required, nullable
+├── `map`?                       → NOT required, nullable
+├── Inside a `oneof`?            → NOT required (unless oneof has required=true)
+├── Has FieldOptions.optional?   → NOT required, nullable
+└── Singular (none of above)?    → REQUIRED
+```
+
+## Nullability Rules
+
+For any field NOT in the `required` array:
+- Schema wraps type with null: `"type": ["string", "null"]`
+- Or uses `"oneOf": [<schema>, {"type": "null"}]` for complex types
+- Runtime accepts explicit JSON `null` → treated as unset in ProtoJSON
+
+This ensures MCP clients that validate cached `inputSchema` do not reject
+otherwise valid tool calls.
+
+## Recursive Messages
+
+- First occurrence generates full schema in `$defs`
+- Subsequent references use `$ref: "#/$defs/MessageName"`
+- Prevents infinite schema expansion
+
+## ProtoJSON Special Encodings
+
+| Type | Encoding | Example |
+|---|---|---|
+| `int64`/`uint64` | JSON string | `"123456789"` |
+| `float`/`double` special | Strings for non-finite | `"NaN"`, `"Infinity"`, `"-Infinity"` |
+| `bytes` | base64 string | `"SGVsbG8="` |
+| `enum` | string name | `"REPORT_STATUS_OK"` |
+| `Timestamp` | RFC 3339 | `"2024-01-01T00:00:00Z"` |
+| `Duration` | seconds with `s` | `"3.5s"` |
+| `FieldMask` | comma-separated | `"field1,field2"` |
diff --git a/.agents/skills/sdd/SKILL.md b/.agents/skills/sdd/SKILL.md
new file mode 100644
index 0000000..1f3ebe9
--- /dev/null
+++ b/.agents/skills/sdd/SKILL.md
@@ -0,0 +1,293 @@
+---
+name: sdd
+version: 1.5.0
+description: >
+  Spec-driven development pipeline with 6 phases: Explore, Requirements,
+  Design, Task Plan, Implementation, Review. Enforces human approval gates
+  between phases. Also provides a standalone documentation workflow for
+  generating or updating project docs without starting a feature pipeline.
+  Use when user wants structured feature development, spec-first approach,
+  or says "I want to add feature X", "new feature", "implement", "build",
+  "generate documentation", "update docs", "actualize the documentation".
+  Keywords: spec, requirements, design document, TDD plan, task plan,
+  implementation, code review, pipeline, approval gates, WHEN/SHALL,
+  generate docs, update docs, documentation queue.
+---
+
+# Spec-Driven Development
+
+You are operating in **spec-driven development mode**.
+This project uses a 6-phase pipeline with human approval gates between each phase.
+
+## Pipeline
+
+```
+Explore → [APPROVE] → Requirements → [APPROVE] → Design → [APPROVE] → Task Plan → [APPROVE] → Implementation → [APPROVE] → Review → [APPROVE] → Done
+```
+
+Each phase has a dedicated prompt template. Read the template for the **current** phase before generating any output.
+
+## Quick Reference
+
+### Core Commands
+
+| Action | Command |
+|--------|---------|
+| Check state | `sh ./scripts/pipeline.sh status` |
+| Start feature | `sh ./scripts/pipeline.sh init <name>` |
+| Register output | `sh ./scripts/pipeline.sh artifact [path]` |
+| Advance phase | `sh ./scripts/pipeline.sh approve` (only after user says "approve") |
+| Mark task done | `sh ./scripts/pipeline.sh task T-N` (implementation phase only) |
+| Multi-feature | Add `--feature <name>` before any command |
+
+### Decision Points
+
+At these moments, **ask the user** before running a command:
+
+#### Starting a feature (`init`)
+
+If config has `auto_branch: true` or `auto_worktree: true` → use the config default silently.
+Otherwise, ASK: *"Create a separate branch for this feature? (branch / worktree / no)"*
+
+| User answer | Command |
+|------------|--------|
+| "branch" | `pipeline.sh init --branch <name>` |
+| "worktree" | `pipeline.sh init --worktree <name>` |
+| "no" / "нет" | `pipeline.sh init <name>` |
+
+#### Finishing a feature (`finish`)
+
+After pipeline reaches `done` and docs maintenance is handled, ASK: *"What to do with the branch? (merge / PR / keep / discard)"*
+
+| User answer | Command |
+|------------|--------|
+| "merge" | `pipeline.sh finish merge` |
+| "PR" / "pull request" | `pipeline.sh finish pr` |
+| "keep" / "оставить" | `pipeline.sh finish keep` |
+| "discard" / "удалить" | `pipeline.sh finish discard --confirm` |
+| On default branch / no git | `pipeline.sh finish keep` (auto, no question) |
+
+#### Documentation updates
+
+When `docs-check` reports issues, ASK the user (already described in Pre-flight Checklist step 3).
+
+| User answer | Command |
+|------------|--------|
+| "generate docs" | `pipeline.sh docs-init --all` |
+| "update docs" | `pipeline.sh docs-init --update` |
+| "skip" / "пропустить" | (no command) |
+
+**Hard rules:** check status first · never skip phases · never auto-approve · save artifacts to `.spec/features/<feature>/` · max 3 revisions then ask user
+
+**Config:** `.spec/config.yaml` → `context`, `rules.<phase>`, `test_skill`, `test_reference`, `docs_dir`, `auto_branch`, `branch_prefix`, `auto_worktree`, `worktree_dir`
+
+**Phase flow:** read template → generate artifact → save → `artifact` → present → wait for "approve" → `approve`
+
+## Phases
+
+| # | Phase          | Template                        | Produces                        |
+|---|----------------|---------------------------------|---------------------------------|
+| 1 | Explore        | `./templates/explore.md`        | Exploration & research document |
+| 2 | Requirements   | `./templates/requirements.md`   | Formal requirements document    |
+| 3 | Design         | `./templates/design.md`         | Architecture & design document  |
+| 4 | Task Plan      | `./templates/task-plan.md`      | TDD implementation plan         |
+| 5 | Implementation | `./templates/implementation.md` | Implementation report           |
+| 6 | Review         | `./templates/review.md`         | Code review document            |
+
+## State Machine
+
+The pipeline state is managed via a shell script:
+
+```sh
+# Check current phase and progress
+sh ./scripts/pipeline.sh status
+
+# Start a new feature pipeline (see Decision Points for branching options)
+sh ./scripts/pipeline.sh init <feature-name>
+
+# Register the artifact you generated for the current phase
+sh ./scripts/pipeline.sh artifact [path]
+
+# Advance to the next phase (only after user says "approve")
+sh ./scripts/pipeline.sh approve
+
+# View revision history
+sh ./scripts/pipeline.sh revisions [phase]
+
+# View all features and their status
+sh ./scripts/pipeline.sh history
+
+# Mark an implementation task as completed (enables resume)
+sh ./scripts/pipeline.sh task <T-N>
+
+# Validate config file
+sh ./scripts/pipeline.sh config-check
+
+# Inject a pre-written artifact and skip to that phase
+sh ./scripts/pipeline.sh inject <phase> <path>
+
+# Abandon an active pipeline
+sh ./scripts/pipeline.sh abandon [feature]
+```
+
+For standalone documentation workflow commands (`docs-init`, `docs-next`, `docs-done`, `docs-status`, `docs-reset`), see `./templates/docs-maintenance.md`.
+
+For all available flags and options: `sh ./scripts/pipeline.sh help`
+
+### Parallel Pipelines
+
+When multiple features are active simultaneously, add `--feature <name>` before the command:
+
+```sh
+sh ./scripts/pipeline.sh --feature auth-flow status
+sh ./scripts/pipeline.sh --feature payment approve
+```
+
+Without the flag, the pipeline auto-detects the active feature. If more than one is active, it will error and prompt you to use `--feature`.
+
+## Project Configuration
+
+If the file `.spec/config.yaml` exists in the project root, read it before starting any phase. See `.spec/config.yaml.example` for a template with all supported keys.
+
+> **Format limitation:** the pipeline parser reads flat `key: value` pairs only. Nested YAML structures, multi-line values, and quoted strings are not supported.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `context` | string | — | Project-wide background for ALL phases |
+| `rules.<phase>` | string | — | Phase-specific rules (supplement template) |
+| `rules.docs` | string | — | Rules for documentation generation |
+| `test_skill` | string | — | Skill name for delegated test generation |
+| `test_reference` | string | — | Glob/paths to representative test files |
+| `docs_dir` | string | `.spec` | Directory for project documentation |
+| `doc_freshness_days` | integer | `30` | Days before a generated doc is stale |
+| `auto_branch` | boolean | `false` | Auto-create git branch on `init` |
+| `branch_prefix` | string | `feature/` | Prefix for auto-created branches |
+| `auto_worktree` | boolean | `false` | Auto-create git worktree on `init` (mutually exclusive with `auto_branch`) |
+| `worktree_dir` | string | `.worktrees` | Directory for worktrees (add to `.gitignore`) |
+
+Phase-specific rule keys: `rules.explore`, `rules.requirements`, `rules.design`, `rules.task-plan`, `rules.implementation`, `rules.review`, `rules.docs`.
+
+Injection order: **context → phase rules → template instructions.**
+
+If the file does not exist, skip this step.
+
+## Standalone Documentation Workflow
+
+If the user requests documentation generation or update **without referring to a feature** (e.g. *"generate docs"*, *"update documentation"*, *"actualize the docs"*, *"refresh AUTH.md"*) — **do NOT run `pipeline.sh init`**. This is a standalone workflow with its own state machine.
+
+1. Read `./templates/docs-maintenance.md` § Standalone Documentation Workflow.
+2. Run `pipeline.sh docs-init [--all|--update|<template>...]` based on user intent.
+3. Choose execution strategy (subagent recommended when available, sequential as fallback).
+4. Drive the queue: `docs-next` → generate → `docs-done` (sequential), or dispatch up to 3 subagents in parallel (subagent mode).
+
+The standalone workflow is independent from feature pipelines — it does not create `.spec/features/<feature>/`, does not require approvals, and runs purely from `.spec/.docs-queue.kv` state.
+
+## Pre-flight Checklist
+
+Before starting any pipeline work, follow these steps in order:
+
+1. **Check pipeline state**: run `pipeline.sh status`.
+   - If exactly one active pipeline exists → resume from the current phase. Do NOT run `init` again.
+   - If no active pipeline → proceed to step 2.
+   - If multiple active pipelines → ask the user which feature to work on, then use `--feature <name>` with all subsequent commands.
+2. **Read project config**: check if `.spec/config.yaml` exists.
+   - If yes → read it, apply `context` to all phases, note `rules.*` for each phase.
+   - If no → proceed without config (defaults apply).
+3. **Check documentation** (MUST — do not skip this step): run `pipeline.sh docs-check`.
+   - **Docs directory missing** → suggest: *"Project documentation (<docs_dir>/) not found. I can generate it to better understand your codebase. Say 'generate docs' or 'skip'."* **Wait for the user's response** before proceeding. This is a soft gate — the pipeline works without documentation, but the user must explicitly acknowledge (say 'generate docs' or 'skip').
+   - **Docs exist, stale files found** → suggest: *"Some docs are outdated (<file>: <N> days old). Regenerate before starting? Say 'update docs' or 'skip'."* **Wait for the user's response.** If user agrees, read `./templates/docs-maintenance.md` for the Stale doc regeneration workflow.
+   - **Docs exist, all fresh** → use as supplementary context for ALL phases. Read `<docs_dir>/README.md` for the documentation map.
+   - If user says **"generate docs"** or **"update docs"**: read `./templates/docs-maintenance.md`, follow the workflow. Generated documentation files go to `<docs_dir>/` (default: `.spec/`), **NOT** to `.spec/features/<feature>/`.
+   - **Do NOT proceed to step 4 until the user responds** to the documentation suggestion.
+4. **Start pipeline**: run `pipeline.sh init <feature-name>`.
+
+For documentation generation, staleness checks, and regeneration workflows, read `./templates/docs-maintenance.md`.
+
+## When to Use This Pipeline
+
+**Use the pipeline for:**
+- New features ("add user authentication", "implement search")
+- Significant changes to existing features (new behavior, API changes, schema migrations)
+- Bug fixes that require investigation and design (root cause unknown, multiple components affected)
+
+**Do NOT use the pipeline for:**
+- Trivial changes: typo fixes, config tweaks, single-field additions, comment updates
+- Dependency updates with no code changes
+- Pure refactors with no behavioral change (unless they are large and risky)
+
+For trivial changes, just make the change directly — no pipeline needed. The skill is designed for work that **benefits from structured thinking before coding**.
+
+### Fast-track mode
+
+For **bug fixes with a known reproduction** or other small, well-understood changes:
+
+- All 6 phases still apply — do not skip phases.
+- Each phase produces a **minimal artifact**: 1-paragraph exploration, 1–2 requirements, focused design (CPs only for the bug scenario), 4–5 tasks (RED→GREEN→CODE→VERIFY→GATE), brief implementation report, short review.
+- Each template contains a "Fast-track mode" section with phase-specific minimums. Follow those rules when fast-track applies.
+
+**When to activate:** The agent activates fast-track when the user describes a bug with a known reproduction step, or a small, scoped change where investigation is unnecessary. At the start, announce: *"Using fast-track mode — all 6 phases, minimal artifacts."* If the user says "full pipeline", switch to the standard (non-abbreviated) flow.
+
+**Scope:** This pipeline is designed for a **single project or monorepo**. It is not intended for features that span multiple independent repositories. Within a monorepo, use one `.spec/` directory at the repository root.
+
+## Rules
+
+1. **MUST check status first.** Run `pipeline.sh status` before doing anything. Never generate phase output without checking status. If multiple active pipelines exist, use `--feature <name>` with all commands.
+2. **Never skip phases.** Follow the order: explore → requirements → design → task-plan → implementation → review.
+3. **Never auto-approve.** Wait for the user to explicitly say "approve" or equivalent.
+4. **Read the template.** Before generating output for a phase, read the corresponding template file.
+5. **Save artifacts.** Save phase artifacts (explore, requirements, design, task-plan, implementation, review) to `.spec/features/<feature>/` and register them with `pipeline.sh artifact`. **Project documentation** (README.md, ARCHITECTURE.md, DOMAIN.md, etc.) goes to `<docs_dir>/` (default: `.spec/`), NOT to `.spec/features/<feature>/` — these are separate directories with separate purposes.
+6. **Each phase produces one artifact** that becomes input for the next phase.
+7. **Artifacts are cumulative.** Each phase reads all prior artifacts.
+8. **Revision limit.** If the user rejects the same artifact 3 times in a row, stop generating and ask: "We've gone through 3 revisions — could you clarify what's missing or what direction you'd prefer?" Do not continue revising without explicit guidance.
+9. **Surface uncertainty.** If you are unsure about intent, scope, or technical approach — say so explicitly. State the assumption you would make and ask the user to confirm or correct it. Never silently assume.
+10. **Write in the user's language.** Detect the user's language from their first message and use it for ALL pipeline artifacts and conversational replies. What stays in English:
+    - Formal grammar keywords: `WHEN`, `SHALL`, `the system`
+    - Requirement IDs: `REQ-X.Y`
+    - Task IDs: `T-N`
+    - Instruction keywords: `CRITICAL`, `IMPORTANT`, `NOTE`, `DO NOT`, `GOAL`
+    - Correctness Property format: `Property N`, `Category`, `For all`, `Validates`
+    - Code identifiers, file paths, shell commands, Mermaid node labels
+    - Documentation in `<docs_dir>/` (`.spec/`) — always English (see `templates/docs/README.md`)
+
+    Everything else — prose, section headers, descriptions, interview questions, explanations — is written in the user's language.
+
+## Error Recovery
+
+- **Revising an artifact:** Overwrite the file, re-register with `pipeline.sh artifact`, and present the updated version to the user. The previous version is automatically saved as a revision in the feature’s `revisions/` directory. Use `pipeline.sh revisions` to view past revisions.
+
+
+## Documentation Maintenance
+
+After the pipeline reaches `phase=done`, read `./templates/docs-maintenance.md` § Documentation Maintenance to check if project documentation needs updating.
+
+## Branch Finishing
+
+After documentation maintenance is complete (or skipped), follow the **Finishing a feature** Decision Point in Quick Reference above.
+
+If on the default branch (main/master) or git is unavailable, run `pipeline.sh finish keep` automatically — no question needed.
+
+This is a soft suggestion, not a blocker. If the user ignores it, the pipeline is still complete.
+
+## Quick Start (for the agent)
+
+When the user says something like "I want to add feature X":
+
+1. Follow the **Pre-flight Checklist** (status → config → docs-check → init)
+2. Read `./templates/explore.md` — investigate the problem space (use `.spec/` docs as context if available)
+3. Generate the exploration document → save to `.spec/features/<feature>/explore.md`
+4. Run `pipeline.sh artifact`
+5. Present to user → wait for "approve"
+6. Run `pipeline.sh approve` → phase advances to requirements
+7. Read `./templates/requirements.md` → follow its interview process
+8. Generate the requirements document → save, register artifact, present, wait for approve
+9. Repeat for design phase
+10. Read `./templates/task-plan.md` → generate TDD implementation plan (no code yet)
+11. Save, register artifact, present, wait for approve
+12. Read `./templates/implementation.md` → execute the task plan (write tests, write code, mark tasks done)
+13. Save implementation report, register artifact, present, wait for approve
+14. Read `./templates/review.md` → review the written code against all prior artifacts
+15. Present review document with findings and verdict → wait for user instructions
+16. If user asks to fix findings → fix → generate new review → present again → wait for approve
+17. After review is approved → `pipeline.sh approve` → pipeline complete
+18. Check if documentation needs updating (see Documentation Maintenance)
+19. Check if the feature branch needs finalizing (see Branch Finishing) → present options → `pipeline.sh finish`
diff --git a/.agents/skills/sdd/scripts/pipeline.sh b/.agents/skills/sdd/scripts/pipeline.sh
new file mode 100755
index 0000000..3cecf09
--- /dev/null
+++ b/.agents/skills/sdd/scripts/pipeline.sh
@@ -0,0 +1,1723 @@
+#!/usr/bin/env sh
+# Spec-Driven Dev Pipeline — state machine (POSIX sh, zero dependencies)
+# Usage: sh pipeline.sh [--feature <name>] <command> [args]
+#
+# Shell compatibility: requires sh with `local` support (bash, dash, ash, zsh).
+#
+# Global flags:
+#   --feature <name>      Specify which feature to operate on (required when
+#                         multiple pipelines are active simultaneously)
+#
+# Commands:
+#   init [--branch|--no-branch] <feature-name>
+#                         Start a new pipeline for a feature
+#                         --branch: create git branch <prefix><name> (prefix from config, default: feature/)
+#                         --no-branch: skip branch creation even if auto_branch is set in config
+#   status                Show current phase, feature, and artifacts
+#   approve               Advance to next phase (requires artifact)
+#   artifact [path]       Register artifact for current phase
+#   history               Show all features and their status
+#   revisions [phase]     Show revision history for current or specified phase
+#   docs-check            Check project documentation status
+#   task <T-N>            Mark implementation task as completed (resume tracking)
+#   version               Show version
+#   help                  Show this help message
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+FEATURES_DIR="$PROJECT_ROOT/.spec/features"
+CONFIG_FILE="$PROJECT_ROOT/.spec/config.yaml"
+
+# --- helpers ---
+
+VERSION="1.5.0"
+EXPLICIT_FEATURE=""
+
+die() { echo "ERROR: $*" >&2; exit 1; }
+info() { echo "→ $*"; }
+warn() { echo "⚠ $*" >&2; }
+
+iso_now() {
+  date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+iso_now_compact() {
+  date -u +"%Y-%m-%dT%H-%M-%SZ" 2>/dev/null || date +"%Y-%m-%dT%H-%M-%SZ"
+}
+
+# Escape a string for safe embedding in JSON values (RFC 8259)
+json_escape() {
+  printf '%s' "$1" | awk '
+    BEGIN { ORS="" }
+    {
+      gsub(/\\/, "\\\\")
+      gsub(/"/, "\\\"")
+      gsub(/\t/, "\\t")
+      gsub(/\r/, "\\r")
+      if (NR > 1) printf "\\n"
+      printf "%s", $0
+    }'
+}
+
+# Read a value from .spec/config.yaml (simple grep-based, no YAML parser)
+# Usage: read_config <key> [default]
+# Returns the value or default (empty string if no default)
+read_config() {
+  local key="$1" default="${2:-}"
+  if [ -f "$CONFIG_FILE" ]; then
+    local val
+    val="$(grep "^${key}:" "$CONFIG_FILE" 2>/dev/null | head -1 | sed "s/^${key}:[[:space:]]*//" | sed 's/[[:space:]]*$//')"
+    if [ -n "$val" ]; then
+      printf '%s' "$val"
+      return
+    fi
+  fi
+  printf '%s' "$default"
+}
+
+# --- per-feature state ---
+
+# Current feature paths (set by set_feature_context / resolve_feature)
+FEATURE_DIR=""
+STATE_FILE=""
+KV_FILE=""
+REVISIONS_DIR=""
+APPROVED_DIR=""
+
+set_feature_context() {
+  # set_feature_context <feature-name> — sets global paths for the feature
+  FEATURE_DIR="$FEATURES_DIR/$1"
+  KV_FILE="$FEATURE_DIR/pipeline.kv"
+  STATE_FILE="$FEATURE_DIR/pipeline.json"
+  REVISIONS_DIR="$FEATURE_DIR/revisions"
+  APPROVED_DIR="$FEATURE_DIR/approved"
+}
+
+ensure_feature_dir() {
+  # ensure_feature_dir <feature-name> — creates feature directory structure
+  local fdir="$FEATURES_DIR/$1"
+  mkdir -p "$fdir" "$fdir/revisions" "$fdir/approved"
+}
+
+read_field() {
+  [ -f "$KV_FILE" ] || return 1
+  local _line
+  _line="$(grep "^$1=" "$KV_FILE" 2>/dev/null | head -1)" || return 1
+  [ -n "$_line" ] || return 1
+  printf '%s' "$_line" | cut -d'=' -f2-
+}
+
+validate_kv() {
+  # Verify required fields exist in KV store; die with diagnostic on failure
+  [ -f "$KV_FILE" ] || die "Pipeline state file missing: $KV_FILE"
+  local missing=""
+  for field in feature phase created_at; do
+    grep -q "^${field}=" "$KV_FILE" 2>/dev/null || missing="$missing $field"
+  done
+  if [ -n "$missing" ]; then
+    die "Corrupted pipeline state ($KV_FILE): missing fields:$missing. Fix the file manually or remove and re-init."
+  fi
+  # Verify every line matches key=value format (key: lowercase + digits + underscore)
+  local line_num=0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line_num=$((line_num + 1))
+    case "$line" in
+      "") continue ;;  # skip blank lines
+      [a-z_]*=*) ;;    # valid key=value
+      *) die "Corrupted pipeline state ($KV_FILE): invalid line $line_num: $line" ;;
+    esac
+  done < "$KV_FILE"
+}
+
+# Escape a value for safe use in sed replacement string
+kv_escape_sed() {
+  printf '%s' "$1" | sed -e 's/[&\\/|]/\\&/g'
+}
+
+# Validate that a value is safe for the KV store (no =, |, or newlines)
+kv_validate_value() {
+  case "$1" in
+    *'='*) die "KV value must not contain '=': $1" ;;
+    *'|'*) die "KV value must not contain '|': $1" ;;
+  esac
+  # Check for newlines by comparing line count (portable across POSIX shells)
+  local line_count
+  line_count="$(printf '%s' "$1" | wc -l)"
+  if [ "$line_count" -ne 0 ]; then
+    die "KV value must not contain newlines: $1"
+  fi
+}
+
+# Validate artifact path: reject directory traversal and control characters
+validate_artifact_path() {
+  case "$1" in
+    */../*|*/..) die "Artifact path must not contain '..' traversal" ;;
+    ../*|..)     die "Artifact path must not contain '..' traversal" ;;
+  esac
+  if printf '%s' "$1" | grep -q '[[:cntrl:]]' 2>/dev/null; then
+    die "Artifact path must not contain control characters"
+  fi
+}
+
+write_field() {
+  kv_validate_value "$2"
+  if [ -f "$KV_FILE" ] && grep -q "^$1=" "$KV_FILE" 2>/dev/null; then
+    local tmp="$KV_FILE.tmp"
+    local escaped
+    escaped="$(kv_escape_sed "$2")"
+    sed "s|^$1=.*|$1=$escaped|" "$KV_FILE" > "$tmp" && mv "$tmp" "$KV_FILE"
+  else
+    echo "$1=$2" >> "$KV_FILE"
+  fi
+}
+
+detect_active_feature() {
+  # Scan all features, return the one with phase != done
+  [ -d "$FEATURES_DIR" ] || return 0
+  local active=""
+  local count=0
+  for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+    [ -f "$kv" ] || continue
+    local phase
+    phase="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+    if [ -n "$phase" ] && [ "$phase" != "done" ]; then
+      local fname
+      fname="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+      active="$fname"
+      count=$((count + 1))
+    fi
+  done
+  if [ "$count" -gt 1 ]; then
+    warn "Multiple active pipelines found:"
+    for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+      [ -f "$kv" ] || continue
+      local phase fname
+      phase="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+      fname="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+      if [ -n "$phase" ] && [ "$phase" != "done" ]; then
+        echo "  - $fname (phase: $phase)" >&2
+      fi
+    done
+    return 1
+  fi
+  [ -n "$active" ] && echo "$active"
+}
+
+resolve_feature() {
+  if [ -n "$EXPLICIT_FEATURE" ]; then
+    # Validate that the explicitly specified feature exists
+    if [ ! -f "$FEATURES_DIR/$EXPLICIT_FEATURE/pipeline.kv" ]; then
+      die "Feature '$EXPLICIT_FEATURE' not found. Run 'pipeline.sh history' to list features."
+    fi
+    set_feature_context "$EXPLICIT_FEATURE"
+    validate_kv
+    return 0
+  fi
+  local feat
+  feat="$(detect_active_feature)" || { warn "Hint: use --feature <name> to select one."; return 1; }
+  if [ -z "$feat" ]; then
+    return 1
+  fi
+  set_feature_context "$feat"
+  validate_kv
+  return 0
+}
+
+next_phase() {
+  case "$1" in
+    explore)        echo "requirements" ;;
+    requirements)   echo "design" ;;
+    design)         echo "task-plan" ;;
+    task-plan)      echo "implementation" ;;
+    implementation) echo "review" ;;
+    review)         echo "done" ;;
+    done)           echo "" ;;
+    *)              echo "" ;;
+  esac
+}
+
+phase_number() {
+  case "$1" in
+    explore)        echo "1" ;;
+    requirements)   echo "2" ;;
+    design)         echo "3" ;;
+    task-plan)      echo "4" ;;
+    implementation) echo "5" ;;
+    review)         echo "6" ;;
+    done)           echo "✓" ;;
+    *)              echo "?" ;;
+  esac
+}
+
+# Numeric ordering for comparisons (phase_number is for display)
+phase_order() {
+  case "$1" in
+    explore)        echo 1 ;;
+    requirements)   echo 2 ;;
+    design)         echo 3 ;;
+    task-plan)      echo 4 ;;
+    implementation) echo 5 ;;
+    review)         echo 6 ;;
+    done)           echo 7 ;;
+    *)              echo 0 ;;
+  esac
+}
+
+# Rebuild the JSON file from KV store (for agents to read)
+# Uses atomic write (tmp + mv) to prevent corruption on interruption
+rebuild_json() {
+  validate_kv
+  local feature phase created artifact
+  feature="$(json_escape "$(read_field feature)")"
+  phase="$(read_field phase)"
+  created="$(read_field created_at)"
+  artifact="$(read_field current_artifact)"
+  local history_count
+  history_count="$(read_field history_count)"
+  [ -z "$history_count" ] && history_count=0
+
+  local tmp_file="$STATE_FILE.tmp"
+  {
+    printf '{\n'
+    printf '  "feature": "%s",\n' "$feature"
+    printf '  "phase": "%s",\n' "$phase"
+    printf '  "created_at": "%s",\n' "$created"
+    if [ -n "$artifact" ]; then
+      printf '  "current_artifact": "%s",\n' "$(json_escape "$artifact")"
+    else
+      printf '  "current_artifact": null,\n'
+    fi
+    printf '  "history": [\n'
+
+    local i=0
+    while [ "$i" -lt "$history_count" ]; do
+      local h_phase h_artifact h_approved
+      h_phase="$(read_field "history_${i}_phase")"
+      h_artifact="$(json_escape "$(read_field "history_${i}_artifact")")"
+      h_approved="$(read_field "history_${i}_approved_at")"
+      [ "$i" -gt 0 ] && printf ',\n'
+      printf '    {"phase": "%s", "artifact": "%s", "approved_at": "%s"}' \
+        "$h_phase" "$h_artifact" "$h_approved"
+      i=$((i + 1))
+    done
+
+    printf '\n  ],\n'
+
+    # Include review_base_commit if set
+    local rbc
+    rbc="$(read_field review_base_commit 2>/dev/null || echo "")"
+    if [ -n "$rbc" ]; then
+      printf '  "review_base_commit": "%s",\n' "$(json_escape "$rbc")"
+    else
+      printf '  "review_base_commit": null,\n'
+    fi
+
+    # Include branch if set
+    local br
+    br="$(read_field branch 2>/dev/null || echo "")"
+    if [ -n "$br" ]; then
+      printf '  "branch": "%s",\n' "$(json_escape "$br")"
+    else
+      printf '  "branch": null,\n'
+    fi
+
+    # Include worktree if set
+    local wt
+    wt="$(read_field worktree 2>/dev/null || echo "")"
+    if [ -n "$wt" ]; then
+      printf '  "worktree": "%s",\n' "$(json_escape "$wt")"
+    else
+      printf '  "worktree": null,\n'
+    fi
+
+    # Include last_completed_task if set
+    local lct
+    lct="$(read_field last_completed_task 2>/dev/null || echo "")"
+    if [ -n "$lct" ]; then
+      printf '  "last_completed_task": "%s",\n' "$(json_escape "$lct")"
+    else
+      printf '  "last_completed_task": null,\n'
+    fi
+
+    # Include finish fields if set
+    local fa ft fb
+    fa="$(read_field finish_action 2>/dev/null || echo "")"
+    ft="$(read_field finished_at 2>/dev/null || echo "")"
+    fb="$(read_field finish_base 2>/dev/null || echo "")"
+    if [ -n "$fa" ]; then
+      printf '  "finish_action": "%s",\n' "$(json_escape "$fa")"
+      printf '  "finished_at": "%s",\n' "$(json_escape "$ft")"
+      if [ -n "$fb" ]; then
+        printf '  "finish_base": "%s"\n' "$(json_escape "$fb")"
+      else
+        printf '  "finish_base": null\n'
+      fi
+    else
+      printf '  "finish_action": null,\n'
+      printf '  "finished_at": null,\n'
+      printf '  "finish_base": null\n'
+    fi
+
+    printf '}\n'
+  } > "$tmp_file"
+  mv -f "$tmp_file" "$STATE_FILE"
+}
+
+# --- commands ---
+
+cmd_init() {
+  # Parse init-specific flags
+  local do_branch=""
+  local do_worktree=""
+  local feature=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --branch)      do_branch="yes"; shift ;;
+      --worktree)    do_worktree="yes"; shift ;;
+      --no-branch)   do_branch="no"; do_worktree="no"; shift ;;
+      -*)            die "Unknown flag for init: $1" ;;
+      *)
+        [ -n "$feature" ] && die "Unexpected argument: $1"
+        feature="$1"; shift
+        ;;
+    esac
+  done
+
+  [ -z "$feature" ] && die "Usage: pipeline.sh init [--branch|--worktree|--no-branch] <feature-name>"
+
+  # Mutual exclusion
+  if [ "$do_branch" = "yes" ] && [ "$do_worktree" = "yes" ]; then
+    die "--branch and --worktree are mutually exclusive."
+  fi
+
+  # Validate feature name (kebab-case)
+  case "$feature" in
+    *[!a-z0-9-]*) die "Feature name must be kebab-case (e.g. grpc-streaming-support)" ;;
+    -*|*-)        die "Feature name must be kebab-case (e.g. grpc-streaming-support)" ;;
+    *--*)         die "Feature name must be kebab-case (e.g. grpc-streaming-support)" ;;
+    [!a-z]*)      die "Feature name must be kebab-case (e.g. grpc-streaming-support)" ;;
+  esac
+
+  if [ ${#feature} -gt 64 ]; then
+    die "Feature name too long (max 64 chars): $feature"
+  fi
+
+  # Resolve branch/worktree creation: flag > config > default (neither)
+  if [ -z "$do_branch" ] && [ -z "$do_worktree" ]; then
+    local auto_branch auto_worktree
+    auto_worktree="$(read_config auto_worktree "false")"
+    case "$auto_worktree" in
+      true|yes|1) do_worktree="yes" ;;
+    esac
+    if [ "$do_worktree" != "yes" ]; then
+      auto_branch="$(read_config auto_branch "false")"
+      case "$auto_branch" in
+        true|yes|1) do_branch="yes" ;;
+        *)          do_branch="no" ;;
+      esac
+    fi
+  fi
+
+  local branch_name=""
+  local worktree_path=""
+
+  if [ "$do_worktree" = "yes" ]; then
+    # --- Worktree mode ---
+    if ! command -v git >/dev/null 2>&1; then
+      die "Git not found. Cannot create worktree."
+    fi
+    if ! git rev-parse --git-dir >/dev/null 2>&1; then
+      die "Not a git repository. Cannot create worktree."
+    fi
+
+    local prefix wt_dir
+    prefix="$(read_config branch_prefix "feature/")"
+    wt_dir="$(read_config worktree_dir ".worktrees")"
+    branch_name="${prefix}${feature}"
+    worktree_path="${wt_dir}/${feature}"
+
+    # Check if branch already exists
+    if git rev-parse --verify "$branch_name" >/dev/null 2>&1; then
+      die "Branch '$branch_name' already exists."
+    fi
+
+    # Warn if worktree_dir is not in .gitignore
+    if [ -f ".gitignore" ]; then
+      if ! grep -qx "$wt_dir" .gitignore 2>/dev/null && ! grep -qx "$wt_dir/" .gitignore 2>/dev/null; then
+        warn "Worktree directory '$wt_dir' is not in .gitignore. Consider adding it."
+      fi
+    else
+      warn "No .gitignore found. Consider adding '$wt_dir' to .gitignore."
+    fi
+
+    git worktree add "$worktree_path" -b "$branch_name" || die "Failed to create worktree at '$worktree_path'."
+    info "Created worktree: $worktree_path (branch: $branch_name)"
+
+  elif [ "$do_branch" = "yes" ]; then
+    # Verify git is available
+    if ! command -v git >/dev/null 2>&1; then
+      die "Git not found. Cannot create branch."
+    fi
+    if ! git rev-parse --git-dir >/dev/null 2>&1; then
+      die "Not a git repository. Cannot create branch."
+    fi
+
+    local prefix
+    prefix="$(read_config branch_prefix "feature/")"
+    branch_name="${prefix}${feature}"
+
+    # Check if branch already exists
+    if git rev-parse --verify "$branch_name" >/dev/null 2>&1; then
+      die "Branch '$branch_name' already exists."
+    fi
+
+    # Warn about dirty working tree
+    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+      warn "Working tree has uncommitted changes."
+    fi
+
+    git checkout -b "$branch_name" || die "Failed to create branch '$branch_name'."
+    info "Created branch: $branch_name"
+  fi
+
+  local fdir="$FEATURES_DIR/$feature"
+
+  # Check if feature already exists
+  if [ -f "$fdir/pipeline.kv" ]; then
+    local existing_phase
+    existing_phase="$(grep "^phase=" "$fdir/pipeline.kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+    if [ "$existing_phase" = "done" ]; then
+      die "Feature '$feature' already completed. Choose a different name."
+    else
+      warn "Active pipeline for '$feature' exists (phase: $existing_phase)"
+      die "Complete or choose a different feature name."
+    fi
+  fi
+
+  ensure_feature_dir "$feature"
+  set_feature_context "$feature"
+
+  # Initialize KV store
+  {
+    echo "feature=$feature"
+    echo "phase=explore"
+    echo "created_at=$(iso_now)"
+    echo "current_artifact="
+    echo "history_count=0"
+    if [ -n "$branch_name" ]; then
+      echo "branch=$branch_name"
+    fi
+    if [ -n "$worktree_path" ]; then
+      echo "worktree=$worktree_path"
+    fi
+  } > "$KV_FILE"
+
+  rebuild_json
+  info "Pipeline initialized for '$feature'"
+  if [ -n "$worktree_path" ]; then
+    info "Worktree: $worktree_path (branch: $branch_name)"
+  elif [ -n "$branch_name" ]; then
+    info "Branch: $branch_name"
+  fi
+  info "Phase: [1/6] explore"
+  info "Artifacts: .spec/features/$feature/"
+  info "Read template: ./templates/explore.md"
+}
+
+cmd_status() {
+  if ! resolve_feature; then
+    info "No active pipeline."
+    # Show completed features if any
+    if [ -d "$FEATURES_DIR" ]; then
+      local has_completed=0
+      for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+        [ -f "$kv" ] || continue
+        local phase
+        phase="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        if [ "$phase" = "done" ]; then
+          if [ "$has_completed" -eq 0 ]; then
+            echo ""
+            echo "Completed features:"
+            has_completed=1
+          fi
+          local fname
+          fname="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+          printf "  ✓ %s\n" "$fname"
+        fi
+      done
+    fi
+    echo ""
+    info "Run: pipeline.sh init <feature-name>"
+    return 0
+  fi
+
+  local feature phase artifact history_count
+  feature="$(read_field feature)"
+  phase="$(read_field phase)"
+  artifact="$(read_field current_artifact)"
+  history_count="$(read_field history_count)"
+  [ -z "$history_count" ] && history_count=0
+
+  echo ""
+  echo "┌─────────────────────────────────────────────┐"
+  printf "│ Feature: %-35s│\n" "$feature"
+  printf "│ Phase:   [%s/6] %-30s│\n" "$(phase_number "$phase")" "$phase"
+  # Show branch/worktree info
+  local br_info wt_info
+  br_info="$(read_field branch 2>/dev/null || echo "")"
+  wt_info="$(read_field worktree 2>/dev/null || echo "")"
+  if [ -n "$wt_info" ]; then
+    printf "│ Worktree: %-34s│\n" "$wt_info"
+  elif [ -n "$br_info" ]; then
+    printf "│ Branch:  %-35s│\n" "$br_info"
+  fi
+  if [ -n "$artifact" ]; then
+    printf "│ Artifact: %-34s│\n" "$artifact"
+  else
+    printf "│ Artifact: %-34s│\n" "(none — register before approve)"
+  fi
+  # Show last completed task during implementation phase
+  if [ "$phase" = "implementation" ]; then
+    local lct
+    lct="$(read_field last_completed_task 2>/dev/null || echo "")"
+    if [ -n "$lct" ]; then
+      printf "│ Last task: %-33s│\n" "$lct"
+    fi
+  fi
+  echo "├─────────────────────────────────────────────┤"
+
+  # Show pipeline progress
+  local e_mark="○" r_mark="○" d_mark="○" t_mark="○" i_mark="○" rev_mark="○"
+  case "$phase" in
+    explore)        e_mark="●" ;;
+    requirements)   e_mark="✓"; r_mark="●" ;;
+    design)         e_mark="✓"; r_mark="✓"; d_mark="●" ;;
+    task-plan)      e_mark="✓"; r_mark="✓"; d_mark="✓"; t_mark="●" ;;
+    implementation) e_mark="✓"; r_mark="✓"; d_mark="✓"; t_mark="✓"; i_mark="●" ;;
+    review)         e_mark="✓"; r_mark="✓"; d_mark="✓"; t_mark="✓"; i_mark="✓"; rev_mark="●" ;;
+    done)           e_mark="✓"; r_mark="✓"; d_mark="✓"; t_mark="✓"; i_mark="✓"; rev_mark="✓" ;;
+  esac
+  printf "│ %s Ex → %s Rq → %s Ds → %s Tp → %s Im → %s Rv │\n" "$e_mark" "$r_mark" "$d_mark" "$t_mark" "$i_mark" "$rev_mark"
+  echo "└─────────────────────────────────────────────┘"
+
+  # Show history
+  if [ "$history_count" -gt 0 ]; then
+    echo ""
+    echo "Completed phases:"
+    local i=0
+    while [ "$i" -lt "$history_count" ]; do
+      local h_phase h_artifact h_approved
+      h_phase="$(read_field "history_${i}_phase")"
+      h_artifact="$(read_field "history_${i}_artifact")"
+      h_approved="$(read_field "history_${i}_approved_at")"
+      printf "  [%s] %-15s → %s (approved: %s)\n" "$((i+1))" "$h_phase" "$h_artifact" "$h_approved"
+      i=$((i + 1))
+    done
+  fi
+
+  # Hint for next action
+  echo ""
+  if [ "$phase" = "done" ]; then
+    info "Pipeline complete."
+  elif [ -z "$artifact" ]; then
+    info "Next: register artifact with 'pipeline.sh artifact <path>'"
+    info "Then: 'pipeline.sh approve' after user approval"
+  else
+    info "Artifact registered. Ask user to approve, then run 'pipeline.sh approve'"
+  fi
+  echo ""
+}
+
+cmd_artifact() {
+  resolve_feature || die "No active pipeline. Run 'pipeline.sh init <feature>' first."
+
+  local phase
+  phase="$(read_field phase)"
+  [ "$phase" = "done" ] && die "Pipeline is complete. Nothing to register."
+
+  local path="$1"
+
+  # If no path given, use the default: .spec/features/<feature>/<phase>.md
+  if [ -z "$path" ]; then
+    path="$FEATURE_DIR/${phase}.md"
+  fi
+
+  validate_artifact_path "$path"
+  [ -f "$path" ] || die "Artifact file does not exist: $path"
+
+  # Save a snapshot of the artifact being registered (revision tracking)
+  local rev_count
+  rev_count="$(read_field "revision_count_${phase}")"
+  [ -z "$rev_count" ] && rev_count=0
+  rev_count=$((rev_count + 1))
+  local rev_name
+  rev_name="${phase}-rev-${rev_count}-$(iso_now_compact).md"
+  cp "$path" "$REVISIONS_DIR/$rev_name"
+  write_field "revision_count_${phase}" "$rev_count"
+  if [ "$rev_count" -gt 1 ]; then
+    info "Revision $rev_count saved: $rev_name"
+  fi
+
+  write_field current_artifact "$path"
+  rebuild_json
+  info "Artifact registered for phase '$phase': $path"
+}
+
+cmd_approve() {
+  resolve_feature || die "No active pipeline."
+
+  local phase artifact history_count
+  phase="$(read_field phase)"
+  artifact="$(read_field current_artifact)"
+  history_count="$(read_field history_count)"
+  [ -z "$history_count" ] && history_count=0
+
+  [ "$phase" = "done" ] && die "Pipeline already complete."
+  [ -z "$artifact" ] && die "No artifact registered for phase '$phase'. Run 'pipeline.sh artifact <path>' first."
+  [ -f "$artifact" ] || die "Artifact file no longer exists: $artifact. Re-register with 'pipeline.sh artifact <path>'."
+
+  # Snapshot artifact contents
+  cp "$artifact" "$APPROVED_DIR/${phase}.md"
+
+  # Record base commit for review phase (git diff source)
+  if [ "$phase" = "task-plan" ]; then
+    local base_commit
+    base_commit="$(git rev-parse HEAD 2>/dev/null || echo "")"
+    write_field review_base_commit "$base_commit"
+  fi
+
+  # Record in history
+  write_field "history_${history_count}_phase" "$phase"
+  write_field "history_${history_count}_artifact" "$artifact"
+  write_field "history_${history_count}_approved_at" "$(iso_now)"
+  history_count=$((history_count + 1))
+  write_field history_count "$history_count"
+
+  # Advance phase
+  local next
+  next="$(next_phase "$phase")"
+  write_field phase "$next"
+  write_field current_artifact ""
+
+  # Clear task tracking when leaving implementation
+  if [ "$phase" = "implementation" ]; then
+    write_field last_completed_task ""
+  fi
+
+  rebuild_json
+
+  if [ "$next" = "done" ]; then
+    echo ""
+    echo "✅ Pipeline complete!"
+    echo ""
+    echo "All artifacts:"
+    local i=0
+    while [ "$i" -lt "$history_count" ]; do
+      printf "  [%s] %s → %s\n" "$((i+1))" \
+        "$(read_field "history_${i}_phase")" \
+        "$(read_field "history_${i}_artifact")"
+      i=$((i + 1))
+    done
+    echo ""
+    local feat
+    feat="$(read_field feature)"
+    info "Artifacts saved in: .spec/features/$feat/"
+    info "Next: check documentation (docs-check), then finish branch (pipeline.sh finish)"
+  else
+    info "Phase '$phase' approved."
+    info "Advanced to: [$(phase_number "$next")/6] $next"
+    info "Read template: ./templates/${next}.md"
+  fi
+}
+
+cmd_task() {
+  local task_id="$1"
+  [ -z "$task_id" ] && die "Usage: pipeline.sh task <T-N>"
+
+  resolve_feature || die "No active pipeline."
+
+  local phase
+  phase="$(read_field phase)"
+  [ "$phase" = "implementation" ] || die "Task tracking is only available during implementation phase (current: $phase)."
+
+  write_field last_completed_task "$task_id"
+  rebuild_json
+  info "Task $task_id marked complete"
+}
+
+cmd_history() {
+  if [ ! -d "$FEATURES_DIR" ]; then
+    info "No features found."
+    return 0
+  fi
+
+  local found=0
+  for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+    [ -f "$kv" ] || continue
+    found=1
+    local fname phase created
+    fname="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+    phase="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+    created="$(grep "^created_at=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+
+    local status_icon
+    if [ "$phase" = "done" ]; then
+      status_icon="✓"
+    else
+      status_icon="●"
+    fi
+
+    printf "  %s %-25s [%s/6] %-15s (created: %s)\n" \
+      "$status_icon" "$fname" "$(phase_number "$phase")" "$phase" "$created"
+  done
+
+  if [ "$found" -eq 0 ]; then
+    info "No features found."
+  fi
+}
+
+cmd_revisions() {
+  resolve_feature || die "No active pipeline."
+
+  local phase
+  phase="$(read_field phase)"
+
+  local target_phase="${1:-$phase}"
+  # Validate target phase
+  case "$target_phase" in
+    explore|requirements|design|task-plan|implementation|review|all) ;;
+    *) die "Unknown phase: $target_phase. Use: explore, requirements, design, task-plan, implementation, review, or all." ;;
+  esac
+
+  local found=0
+  local tmp
+  tmp="$(mktemp)"
+  if [ "$target_phase" = "all" ]; then
+    echo "All revisions:"
+    for p in explore requirements design task-plan implementation review; do
+      find "$REVISIONS_DIR" -name "${p}-rev-*" 2>/dev/null | sort > "$tmp"
+      while IFS= read -r f; do
+        printf "  [%s] %s\n" "$p" "$(basename "$f")"
+        found=1
+      done < "$tmp"
+    done
+  else
+    echo "Revisions for phase '$target_phase':"
+    find "$REVISIONS_DIR" -name "${target_phase}-rev-*" 2>/dev/null | sort > "$tmp"
+    while IFS= read -r f; do
+      printf "  %s\n" "$(basename "$f")"
+      found=1
+    done < "$tmp"
+  fi
+  rm -f "$tmp"
+
+  if [ "$found" -eq 0 ]; then
+    info "No revisions recorded yet."
+  fi
+}
+
+cmd_version() {
+  echo "Spec-Driven Dev Pipeline v${VERSION}"
+}
+
+# check_file_staleness <file> <templates_dir> <freshness_days> <now_epoch>
+# Outputs tab-separated: generated template age_days stale scope_changed
+check_file_staleness() {
+  local f="$1" templates_dir="$2" freshness_days="$3" now_epoch="$4"
+  local generated="null" template="null" age_days="null" stale="false" scope_changed="null"
+
+  local first_line
+  first_line="$(head -1 "$f" 2>/dev/null)"
+  case "$first_line" in
+    *"<!-- generated:"*"template:"*"-->"*)
+      local gen_date gen_tmpl
+      gen_date="$(echo "$first_line" | sed 's/.*<!-- generated: \([0-9-]*\),.*/\1/')"
+      gen_tmpl="$(echo "$first_line" | sed 's/.*template: \([^ ]*\) -->.*/\1/')"
+      if [ -n "$gen_date" ]; then
+        generated="\"$gen_date\""
+        template="\"$gen_tmpl\""
+        local gen_epoch
+        gen_epoch="$(date -j -f '%Y-%m-%d' "$gen_date" '+%s' 2>/dev/null || date -d "$gen_date" '+%s' 2>/dev/null || echo 0)"
+        if [ "$gen_epoch" -gt 0 ] && [ "$now_epoch" -gt 0 ]; then
+          age_days=$(( (now_epoch - gen_epoch) / 86400 ))
+
+          local tmpl_file="$templates_dir/$gen_tmpl"
+          if [ -f "$tmpl_file" ]; then
+            local scope_line
+            scope_line="$(head -1 "$tmpl_file" 2>/dev/null)"
+            case "$scope_line" in
+              "<!-- scope:"*"-->")
+                local patterns
+                patterns="$(echo "$scope_line" | sed 's/<!-- scope: //' | sed 's/ -->//' | sed 's/,[[:space:]]*/\n/g' | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
+                if [ -n "$patterns" ]; then
+                  local git_hits
+                  # shellcheck disable=SC2086
+                  git_hits="$(cd "$PROJECT_ROOT" && set -f && git log --oneline --since="$gen_date" -- $patterns 2>/dev/null | head -1)"
+                  if [ -n "$git_hits" ]; then
+                    scope_changed="true"
+                    if [ "$age_days" -gt "$freshness_days" ]; then
+                      stale="true"
+                    fi
+                  else
+                    scope_changed="false"
+                  fi
+                fi
+                ;;
+              *)
+                if [ "$age_days" -gt "$freshness_days" ]; then
+                  stale="true"
+                fi
+                ;;
+            esac
+          else
+            if [ "$age_days" -gt "$freshness_days" ]; then
+              stale="true"
+            fi
+          fi
+        fi
+      fi
+      ;;
+  esac
+  printf '%s\t%s\t%s\t%s\t%s' "$generated" "$template" "$age_days" "$stale" "$scope_changed"
+}
+
+cmd_docs_check() {
+  local config_file="$CONFIG_FILE"
+  local docs_dir=".spec"
+  local freshness_days=30
+
+  # Read docs_dir and doc_freshness_days from config.yaml if it exists
+  if [ -f "$config_file" ]; then
+    local configured_dir
+    configured_dir="$(grep '^docs_dir:' "$config_file" 2>/dev/null | head -1 | sed 's/^docs_dir:[[:space:]]*//' | sed 's/[[:space:]]*$//')"
+    if [ -n "$configured_dir" ]; then
+      docs_dir="$configured_dir"
+    fi
+    local configured_days
+    configured_days="$(grep '^doc_freshness_days:' "$config_file" 2>/dev/null | head -1 | sed 's/^doc_freshness_days:[[:space:]]*//' | sed 's/[[:space:]]*$//')"
+    if [ -n "$configured_days" ]; then
+      freshness_days="$configured_days"
+    fi
+  fi
+
+  local full_path="$PROJECT_ROOT/$docs_dir"
+  local templates_dir="$SKILL_DIR/templates/docs"
+  local now_epoch
+  now_epoch="$(date +%s 2>/dev/null || echo 0)"
+
+  if [ -d "$full_path" ]; then
+    printf '{"exists": true, "dir": "%s", "freshness_days": %d, "files": [' "$(json_escape "$docs_dir")" "$freshness_days"
+
+    # Single scan: find files into tmpfile, iterate once, capture stale names
+    local tmp_files tmp_stale
+    tmp_files="$(mktemp)"
+    tmp_stale="$(mktemp)"
+    find "$full_path" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort > "$tmp_files"
+
+    local first=1
+    while IFS= read -r f; do
+      local fname result generated template age_days stale scope_changed
+      fname="$(basename "$f")"
+      result="$(check_file_staleness "$f" "$templates_dir" "$freshness_days" "$now_epoch")"
+
+      generated="$(printf '%s' "$result" | cut -f1)"
+      template="$(printf '%s' "$result" | cut -f2)"
+      age_days="$(printf '%s' "$result" | cut -f3)"
+      stale="$(printf '%s' "$result" | cut -f4)"
+      scope_changed="$(printf '%s' "$result" | cut -f5)"
+
+      if [ "$first" -eq 1 ]; then
+        first=0
+      else
+        printf ', '
+      fi
+      printf '{"name": "%s", "generated": %s, "template": %s, "age_days": %s, "stale": %s, "scope_changed": %s}' \
+        "$(json_escape "$fname")" "$generated" "$template" "$age_days" "$stale" "$scope_changed"
+
+      if [ "$stale" = "true" ]; then
+        echo "$fname" >> "$tmp_stale"
+      fi
+    done < "$tmp_files"
+
+    printf '], "stale": ['
+    # Read stale names from tmpfile (no re-scan needed)
+    local sfirst=1
+    if [ -s "$tmp_stale" ]; then
+      while IFS= read -r sname; do
+        if [ "$sfirst" -eq 1 ]; then
+          sfirst=0
+        else
+          printf ', '
+        fi
+        printf '"%s"' "$(json_escape "$sname")"
+      done < "$tmp_stale"
+    fi
+    printf ']}\n'
+
+    rm -f "$tmp_files" "$tmp_stale"
+  else
+    printf '{"exists": false, "dir": "%s", "freshness_days": %d, "files": [], "stale": []}\n' "$(json_escape "$docs_dir")" "$freshness_days"
+  fi
+}
+
+# --- standalone docs queue ---
+
+DOCS_QUEUE_FILE="$PROJECT_ROOT/.spec/.docs-queue.kv"
+
+docs_queue_read() {
+  # docs_queue_read <key> — read value from queue file
+  [ -f "$DOCS_QUEUE_FILE" ] || return 1
+  local _line
+  _line="$(grep "^$1=" "$DOCS_QUEUE_FILE" 2>/dev/null | head -1)" || return 1
+  [ -n "$_line" ] || return 1
+  printf '%s' "$_line" | sed "s/^$1=//"
+}
+
+docs_queue_write_status() {
+  # docs_queue_write_status <index> <status>
+  local idx="$1" status="$2"
+  local tmp="$DOCS_QUEUE_FILE.tmp"
+  grep -v "^template_${idx}_status=" "$DOCS_QUEUE_FILE" > "$tmp" 2>/dev/null || true
+  echo "template_${idx}_status=$status" >> "$tmp"
+  mv -f "$tmp" "$DOCS_QUEUE_FILE"
+}
+
+docs_template_name() {
+  # Extract template name from generated file metadata (line 1)
+  local f="$1"
+  local first_line
+  first_line="$(head -1 "$f" 2>/dev/null)"
+  case "$first_line" in
+    "<!-- generated:"*"-->")
+      printf '%s' "$first_line" | sed -n 's/.*template:[[:space:]]*\([^[:space:]]*\)\.md[[:space:]]*-->/\1/p'
+      ;;
+  esac
+}
+
+cmd_docs_init() {
+  local mode="all"
+  local explicit_templates=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --all)    mode="all"; shift ;;
+      --update) mode="update"; shift ;;
+      -*)       die "Unknown flag for docs-init: $1" ;;
+      *)
+        explicit_templates="$explicit_templates $1"
+        mode="explicit"
+        shift
+        ;;
+    esac
+  done
+
+  [ -f "$DOCS_QUEUE_FILE" ] && die "Docs queue already exists at $DOCS_QUEUE_FILE. Run 'pipeline.sh docs-reset' first."
+
+  local templates_dir="$SKILL_DIR/templates/docs"
+  local docs_dir
+  docs_dir="$(read_config docs_dir ".spec")"
+  local full_path="$PROJECT_ROOT/$docs_dir"
+
+  local templates=""
+  case "$mode" in
+    all)
+      for f in "$templates_dir"/*.md; do
+        local name
+        name="$(basename "$f" .md)"
+        [ "$name" = "README" ] && continue
+        templates="$templates $name"
+      done
+      ;;
+    update)
+      [ -d "$full_path" ] || die "Docs directory '$docs_dir' does not exist. Use --all to bootstrap."
+      local freshness_days
+      freshness_days="$(read_config doc_freshness_days "30")"
+      local now_epoch
+      now_epoch="$(date +%s 2>/dev/null || echo 0)"
+      # Iterate stale files, extract template names
+      local tmp_list
+      tmp_list="$(mktemp)"
+      find "$full_path" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort > "$tmp_list"
+      while IFS= read -r f; do
+        local result stale tmpl
+        result="$(check_file_staleness "$f" "$templates_dir" "$freshness_days" "$now_epoch")"
+        stale="$(printf '%s' "$result" | cut -f4)"
+        if [ "$stale" = "true" ]; then
+          tmpl="$(docs_template_name "$f")"
+          if [ -n "$tmpl" ]; then
+            case " $templates " in
+              *" $tmpl "*) ;;
+              *) templates="$templates $tmpl" ;;
+            esac
+          fi
+        fi
+      done < "$tmp_list"
+      rm -f "$tmp_list"
+      ;;
+    explicit)
+      templates="$explicit_templates"
+      ;;
+  esac
+
+  mkdir -p "$(dirname "$DOCS_QUEUE_FILE")"
+
+  # Build queue file
+  local count=0
+  local tmp_queue="$DOCS_QUEUE_FILE.tmp"
+  {
+    echo "created_at=$(iso_now)"
+    echo "docs_dir=$docs_dir"
+    echo "mode=$mode"
+  } > "$tmp_queue"
+
+  for t in $templates; do
+    if [ ! -f "$templates_dir/$t.md" ]; then
+      warn "Template not found, skipping: $t"
+      continue
+    fi
+    echo "template_${count}=$t" >> "$tmp_queue"
+    echo "template_${count}_status=pending" >> "$tmp_queue"
+    count=$((count + 1))
+  done
+  echo "total=$count" >> "$tmp_queue"
+
+  if [ "$count" -eq 0 ]; then
+    rm -f "$tmp_queue"
+    info "No templates to queue (nothing stale or none selected)."
+    return 0
+  fi
+
+  mv -f "$tmp_queue" "$DOCS_QUEUE_FILE"
+
+  info "Docs queue created: $count template(s), mode=$mode."
+  info "Next: pipeline.sh docs-next"
+  info ""
+  info "Execution strategy:"
+  info "  - If your toolset supports subagent dispatch (Task/Composer/etc):"
+  info "    use SUBAGENT mode — dispatch up to 3 templates in parallel."
+  info "  - Otherwise: SEQUENTIAL mode — one template per iteration."
+  info "  See ./templates/docs-maintenance.md § Standalone Documentation Workflow."
+}
+
+cmd_docs_next() {
+  [ -f "$DOCS_QUEUE_FILE" ] || die "No docs queue. Run 'pipeline.sh docs-init' first."
+
+  local total
+  total="$(docs_queue_read total)"
+  [ -z "$total" ] && total=0
+
+  local i=0
+  local templates_dir="$SKILL_DIR/templates/docs"
+  local docs_dir
+  docs_dir="$(docs_queue_read docs_dir)"
+
+  while [ "$i" -lt "$total" ]; do
+    local status
+    status="$(docs_queue_read "template_${i}_status")"
+    if [ "$status" = "pending" ]; then
+      local name
+      name="$(docs_queue_read "template_${i}")"
+      printf '%s\t%s\n' "$name" "$templates_dir/$name.md"
+      # Sequential mode hint after position 3
+      if [ "$i" -ge 3 ]; then
+        info "" >&2
+        info "Tip: if context feels heavy, start a fresh chat and resume" >&2
+        info "     with 'pipeline.sh docs-status' (sequential mode)." >&2
+      fi
+      return 0
+    fi
+    i=$((i + 1))
+  done
+
+  info "Docs queue complete: all $total template(s) processed."
+  info "Run 'pipeline.sh docs-reset' to clear the queue."
+  return 0
+}
+
+cmd_docs_done() {
+  local name="${1:-}"
+  [ -z "$name" ] && die "Usage: pipeline.sh docs-done <template>"
+  [ -f "$DOCS_QUEUE_FILE" ] || die "No docs queue. Run 'pipeline.sh docs-init' first."
+
+  local total
+  total="$(docs_queue_read total)"
+  [ -z "$total" ] && total=0
+
+  local i=0
+  while [ "$i" -lt "$total" ]; do
+    local entry
+    entry="$(docs_queue_read "template_${i}")"
+    if [ "$entry" = "$name" ]; then
+      local status
+      status="$(docs_queue_read "template_${i}_status")"
+      if [ "$status" = "done" ]; then
+        warn "Template '$name' already marked done."
+        return 0
+      fi
+      docs_queue_write_status "$i" "done"
+      info "Marked done: $name ($((i + 1))/$total)"
+      # Check if queue is now complete
+      local remaining=0
+      local j=0
+      while [ "$j" -lt "$total" ]; do
+        local s
+        s="$(docs_queue_read "template_${j}_status")"
+        [ "$s" = "pending" ] && remaining=$((remaining + 1))
+        j=$((j + 1))
+      done
+      if [ "$remaining" -eq 0 ]; then
+        info "Docs queue complete. Run 'pipeline.sh docs-reset' to clear it."
+      fi
+      return 0
+    fi
+    i=$((i + 1))
+  done
+
+  die "Template '$name' not found in queue."
+}
+
+cmd_docs_status() {
+  if [ ! -f "$DOCS_QUEUE_FILE" ]; then
+    printf '{"exists": false}\n'
+    return 0
+  fi
+
+  local total docs_dir mode created_at
+  total="$(docs_queue_read total)"
+  docs_dir="$(docs_queue_read docs_dir)"
+  mode="$(docs_queue_read mode)"
+  created_at="$(docs_queue_read created_at)"
+  [ -z "$total" ] && total=0
+
+  local completed=0
+  local pending_list=""
+  local current=""
+  local first_pending_set=0
+  local i=0
+  while [ "$i" -lt "$total" ]; do
+    local name status
+    name="$(docs_queue_read "template_${i}")"
+    status="$(docs_queue_read "template_${i}_status")"
+    if [ "$status" = "done" ]; then
+      completed=$((completed + 1))
+    else
+      if [ "$first_pending_set" -eq 0 ]; then
+        current="$name"
+        first_pending_set=1
+      fi
+      if [ -z "$pending_list" ]; then
+        pending_list="\"$(json_escape "$name")\""
+      else
+        pending_list="$pending_list, \"$(json_escape "$name")\""
+      fi
+    fi
+    i=$((i + 1))
+  done
+
+  printf '{"exists": true, "total": %d, "completed": %d, "current": %s, "pending": [%s], "mode": "%s", "docs_dir": "%s", "created_at": "%s"}\n' \
+    "$total" \
+    "$completed" \
+    "$([ -n "$current" ] && printf '"%s"' "$(json_escape "$current")" || printf 'null')" \
+    "$pending_list" \
+    "$(json_escape "$mode")" \
+    "$(json_escape "$docs_dir")" \
+    "$(json_escape "$created_at")"
+}
+
+cmd_docs_reset() {
+  if [ ! -f "$DOCS_QUEUE_FILE" ]; then
+    info "No docs queue to reset."
+    return 0
+  fi
+
+  local total completed=0
+  total="$(docs_queue_read total)"
+  [ -z "$total" ] && total=0
+  local i=0
+  while [ "$i" -lt "$total" ]; do
+    local s
+    s="$(docs_queue_read "template_${i}_status")"
+    [ "$s" = "done" ] && completed=$((completed + 1))
+    i=$((i + 1))
+  done
+
+  rm -f "$DOCS_QUEUE_FILE"
+  info "Docs queue reset (was: $completed/$total completed)."
+}
+
+cmd_config_check() {
+  [ -f "$CONFIG_FILE" ] || { info "No config file found: $CONFIG_FILE"; return 0; }
+
+  local valid_keys=" context rules.explore rules.requirements rules.design rules.task-plan rules.implementation rules.review rules.docs test_skill test_reference docs_dir doc_freshness_days auto_branch branch_prefix auto_worktree worktree_dir "
+  local errors=0
+
+  info "Checking $CONFIG_FILE ..."
+
+  # Extract keys and validate against whitelist
+  local tmp
+  tmp="$(mktemp)"
+  grep '^[a-z]' "$CONFIG_FILE" 2>/dev/null > "$tmp" || true
+  while IFS= read -r line; do
+    local key
+    key="$(printf '%s' "$line" | sed 's/:.*//')"
+    case "$valid_keys" in
+      *" $key "*) ;;
+      *) warn "Unknown key: '$key'"; errors=$((errors + 1)) ;;
+    esac
+  done < "$tmp"
+  rm -f "$tmp"
+
+  # Type checks
+  local val
+  val="$(read_config doc_freshness_days "")"
+  if [ -n "$val" ]; then
+    case "$val" in
+      *[!0-9]*) warn "doc_freshness_days must be numeric, got: '$val'"; errors=$((errors + 1)) ;;
+    esac
+  fi
+
+  val="$(read_config auto_branch "")"
+  if [ -n "$val" ]; then
+    case "$val" in
+      true|false|yes|no|1|0) ;;
+      *) warn "auto_branch must be boolean (true/false/yes/no/1/0), got: '$val'"; errors=$((errors + 1)) ;;
+    esac
+  fi
+
+  val="$(read_config auto_worktree "")"
+  if [ -n "$val" ]; then
+    case "$val" in
+      true|false|yes|no|1|0) ;;
+      *) warn "auto_worktree must be boolean (true/false/yes/no/1/0), got: '$val'"; errors=$((errors + 1)) ;;
+    esac
+  fi
+
+  if [ "$errors" -eq 0 ]; then
+    info "Config OK — all keys valid."
+  else
+    warn "$errors problem(s) found."
+    return 1
+  fi
+}
+
+cmd_inject() {
+  local target_phase="${1:-}"
+  local artifact_path="${2:-}"
+
+  if [ -z "$target_phase" ] || [ -z "$artifact_path" ]; then
+    die "Usage: pipeline.sh inject <phase> <path>"
+  fi
+
+  # Validate target phase
+  case "$target_phase" in
+    explore|requirements|design|task-plan|implementation|review) ;;
+    *) die "Unknown phase: $target_phase. Use: explore, requirements, design, task-plan, implementation, review." ;;
+  esac
+
+  resolve_feature || die "No active pipeline. Run 'pipeline.sh init <feature>' first."
+
+  local current_phase
+  current_phase="$(read_field phase)"
+  [ "$current_phase" = "done" ] && die "Pipeline already complete."
+
+  # Validate current phase <= target phase
+  local current_num target_num
+  current_num="$(phase_order "$current_phase")"
+  target_num="$(phase_order "$target_phase")"
+  if [ "$current_num" -gt "$target_num" ]; then
+    die "Cannot inject backward: current phase is '$current_phase' ($current_num), target is '$target_phase' ($target_num)."
+  fi
+
+  validate_artifact_path "$artifact_path"
+  [ -f "$artifact_path" ] || die "Artifact file does not exist: $artifact_path"
+
+  # Lightweight content validation
+  case "$target_phase" in
+    requirements)
+      if ! grep -q 'WHEN\|SHALL' "$artifact_path" 2>/dev/null; then
+        warn "Requirements artifact should contain WHEN/SHALL keywords."
+      fi
+      ;;
+    design)
+      if ! grep -q 'Correctness\|Property' "$artifact_path" 2>/dev/null; then
+        warn "Design artifact should contain Correctness Properties."
+      fi
+      ;;
+  esac
+
+  # Skip intermediate phases (record as injected in history)
+  local p="$current_phase"
+  local history_count
+  history_count="$(read_field history_count)"
+  [ -z "$history_count" ] && history_count=0
+
+  while [ "$p" != "$target_phase" ]; do
+    write_field "history_${history_count}_phase" "$p"
+    write_field "history_${history_count}_artifact" "(injected)"
+    write_field "history_${history_count}_approved_at" "$(iso_now)"
+    history_count=$((history_count + 1))
+    p="$(next_phase "$p")"
+  done
+
+  # Set to target phase and register artifact
+  write_field phase "$target_phase"
+  write_field current_artifact "$artifact_path"
+  write_field history_count "$history_count"
+
+  # Save revision snapshot
+  local rev_count
+  rev_count="$(read_field "revision_count_${target_phase}")"
+  [ -z "$rev_count" ] && rev_count=0
+  rev_count=$((rev_count + 1))
+  local rev_name
+  rev_name="${target_phase}-rev-${rev_count}-$(iso_now_compact).md"
+  cp "$artifact_path" "$REVISIONS_DIR/$rev_name"
+  write_field "revision_count_${target_phase}" "$rev_count"
+
+  # Capture review_base_commit if injecting into implementation/review and not already set
+  case "$target_phase" in
+    implementation|review)
+      local rbc
+      rbc="$(read_field review_base_commit 2>/dev/null || echo "")"
+      if [ -z "$rbc" ]; then
+        local head_commit
+        head_commit="$(git rev-parse HEAD 2>/dev/null || echo "")"
+        if [ -n "$head_commit" ]; then
+          write_field review_base_commit "$head_commit"
+          info "Captured review_base_commit: $(printf '%.8s' "$head_commit")"
+        fi
+      fi
+      ;;
+  esac
+
+  rebuild_json
+
+  local skipped=$((target_num - current_num))
+  if [ "$skipped" -gt 0 ]; then
+    info "$skipped phase(s) skipped to reach '$target_phase'."
+  fi
+  info "Artifact injected for phase '$target_phase': $artifact_path"
+  info "Ask user to approve, then run 'pipeline.sh approve'"
+}
+
+cmd_finish() {
+  # Parse finish-specific flags and action
+  local action=""
+  local confirm=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --confirm) confirm="yes"; shift ;;
+      -*)        die "Unknown flag for finish: $1" ;;
+      *)
+        [ -n "$action" ] && die "Unexpected argument: $1"
+        action="$1"; shift
+        ;;
+    esac
+  done
+
+  [ -z "$action" ] && die "Usage: pipeline.sh finish <merge|pr|keep|discard> [--confirm]"
+
+  # Validate action
+  case "$action" in
+    merge|pr|keep|discard) ;;
+    *) die "Unknown finish action: $action. Use: merge, pr, keep, discard." ;;
+  esac
+
+  # Resolve feature (supports completed pipelines)
+  if [ -n "$EXPLICIT_FEATURE" ]; then
+    if [ ! -f "$FEATURES_DIR/$EXPLICIT_FEATURE/pipeline.kv" ]; then
+      die "Feature '$EXPLICIT_FEATURE' not found."
+    fi
+    set_feature_context "$EXPLICIT_FEATURE"
+    validate_kv
+  else
+    # For finish, we need to find a done-but-not-finished feature
+    local found=""
+    local count=0
+    if [ -d "$FEATURES_DIR" ]; then
+      for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+        [ -f "$kv" ] || continue
+        local p fa
+        p="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        fa="$(grep "^finish_action=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        if [ "$p" = "done" ] && [ -z "$fa" ]; then
+          local fn
+          fn="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+          found="$fn"
+          count=$((count + 1))
+        fi
+      done
+    fi
+    if [ "$count" -gt 1 ]; then
+      warn "Multiple completed pipelines awaiting finish:"
+      for kv in "$FEATURES_DIR"/*/pipeline.kv; do
+        [ -f "$kv" ] || continue
+        local p fa fn
+        p="$(grep "^phase=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        fa="$(grep "^finish_action=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        fn="$(grep "^feature=" "$kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+        if [ "$p" = "done" ] && [ -z "$fa" ]; then
+          echo "  - $fn" >&2
+        fi
+      done
+      die "Use --feature <name> to select one."
+    fi
+    if [ -z "$found" ]; then
+      die "No completed pipeline awaiting finish. Run 'pipeline.sh history' to list features."
+    fi
+    set_feature_context "$found"
+    validate_kv
+  fi
+
+  local phase
+  phase="$(read_field phase)"
+  [ "$phase" != "done" ] && die "Pipeline not complete (current phase: $phase). Finish is only available after all phases are done."
+
+  # Check idempotency
+  local existing_action
+  existing_action="$(read_field finish_action 2>/dev/null || echo "")"
+  if [ -n "$existing_action" ]; then
+    die "Already finished (action: $existing_action). Nothing to do."
+  fi
+
+  # Git availability check
+  if [ "$action" != "keep" ]; then
+    if ! command -v git >/dev/null 2>&1; then
+      die "Git not found. Use 'finish keep' to skip git operations."
+    fi
+    if ! git rev-parse --git-dir >/dev/null 2>&1; then
+      die "Not a git repository. Use 'finish keep' to skip git operations."
+    fi
+  fi
+
+  local feat branch current_branch worktree
+  feat="$(read_field feature)"
+  branch="$(read_field branch 2>/dev/null || echo "")"
+  worktree="$(read_field worktree 2>/dev/null || echo "")"
+  current_branch="$(git branch --show-current 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+
+  # Determine base branch for merge/discard
+  local base_branch=""
+  if [ "$action" = "merge" ] || [ "$action" = "discard" ]; then
+    # Try to find default branch
+    if git rev-parse --verify main >/dev/null 2>&1; then
+      base_branch="main"
+    elif git rev-parse --verify master >/dev/null 2>&1; then
+      base_branch="master"
+    else
+      die "Cannot determine base branch (no main or master). Merge/discard manually."
+    fi
+
+    # Check for uncommitted changes
+    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+      die "Working tree has uncommitted changes. Commit or stash before '$action'."
+    fi
+  fi
+
+  # Determine which branch to operate on
+  local target_branch="${branch:-$current_branch}"
+
+  case "$action" in
+    merge)
+      [ -z "$target_branch" ] && die "No branch to merge (not on a feature branch and no branch recorded)."
+      [ "$target_branch" = "$base_branch" ] && die "Already on $base_branch. Nothing to merge."
+      # If worktree, remove it first (must not be in worktree dir when removing)
+      if [ -n "$worktree" ] && git worktree list 2>/dev/null | grep -q "$worktree"; then
+        git worktree remove "$worktree" || die "Failed to remove worktree '$worktree'."
+        info "Removed worktree: $worktree"
+      fi
+      git checkout "$base_branch" || die "Failed to checkout $base_branch."
+      git merge "$target_branch" || die "Merge failed. Resolve conflicts and retry."
+      write_field finish_action "merge"
+      write_field finished_at "$(iso_now)"
+      write_field finish_base "$base_branch"
+      rebuild_json
+      info "Merged '$target_branch' into '$base_branch'."
+      info "Tip: run tests to verify, then 'git branch -d $target_branch' to clean up."
+      ;;
+
+    pr)
+      [ -z "$target_branch" ] && die "No branch to push (not on a feature branch and no branch recorded)."
+      [ "$target_branch" = "$base_branch" ] && die "Already on $base_branch. Nothing to push."
+      git push -u origin "$target_branch" || die "Failed to push '$target_branch'."
+      write_field finish_action "pr"
+      write_field finished_at "$(iso_now)"
+      write_field finish_base "${base_branch:-}"
+      rebuild_json
+      info "Branch '$target_branch' pushed to origin."
+      info "Create a pull request: gh pr create --fill"
+      ;;
+
+    keep)
+      write_field finish_action "keep"
+      write_field finished_at "$(iso_now)"
+      rebuild_json
+      info "Branch kept as-is. Handle manually when ready."
+      ;;
+
+    discard)
+      [ "$confirm" != "yes" ] && die "Discard deletes the branch and all unmerged commits. Re-run with --confirm to proceed: pipeline.sh finish discard --confirm"
+      [ -z "$target_branch" ] && die "No branch to discard (not on a feature branch and no branch recorded)."
+      [ "$target_branch" = "$base_branch" ] && die "Cannot discard $base_branch."
+      # If worktree, force-remove it first
+      if [ -n "$worktree" ] && git worktree list 2>/dev/null | grep -q "$worktree"; then
+        git worktree remove --force "$worktree" || die "Failed to remove worktree '$worktree'."
+        info "Removed worktree: $worktree"
+      fi
+      git checkout "$base_branch" || die "Failed to checkout $base_branch."
+      git branch -D "$target_branch" || die "Failed to delete branch '$target_branch'."
+      write_field finish_action "discard"
+      write_field finished_at "$(iso_now)"
+      write_field finish_base "$base_branch"
+      rebuild_json
+      info "Branch '$target_branch' discarded."
+      ;;
+  esac
+}
+
+cmd_abandon() {
+  local feature="${1:-}"
+
+  # If --feature was specified globally, use it
+  if [ -z "$feature" ] && [ -n "$EXPLICIT_FEATURE" ]; then
+    feature="$EXPLICIT_FEATURE"
+  fi
+
+  # If still empty, try to resolve active feature
+  if [ -z "$feature" ]; then
+    feature="$(detect_active_feature)" || die "Multiple active pipelines. Use: pipeline.sh abandon <feature-name>"
+    [ -z "$feature" ] && die "No active pipeline to abandon."
+  fi
+
+  local fdir="$FEATURES_DIR/$feature"
+  [ -f "$fdir/pipeline.kv" ] || die "Feature '$feature' not found."
+
+  local phase
+  phase="$(grep "^phase=" "$fdir/pipeline.kv" 2>/dev/null | head -1 | cut -d'=' -f2-)"
+  [ "$phase" = "done" ] && die "Feature '$feature' is already completed."
+
+  set_feature_context "$feature"
+  write_field phase "done"
+  write_field abandoned_at "$(iso_now)"
+  write_field finish_action "abandoned"
+  write_field finished_at "$(iso_now)"
+
+  # Clean up worktree if present
+  local wt
+  wt="$(read_field worktree 2>/dev/null || echo "")"
+  if [ -n "$wt" ] && command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+    if git worktree list 2>/dev/null | grep -q "$wt"; then
+      git worktree remove --force "$wt" 2>/dev/null && info "Removed worktree: $wt"
+    fi
+  fi
+
+  rebuild_json
+
+  info "Feature '$feature' abandoned (was in phase: $phase)."
+  info "Artifacts remain in: .spec/features/$feature/"
+}
+
+cmd_help() {
+  echo "Spec-Driven Dev Pipeline v${VERSION}"
+  echo ""
+  echo "Usage: sh pipeline.sh [--feature <name>] <command> [args]"
+  echo ""
+  echo "Global flags:"
+  echo "  --feature <name>  Select feature (needed when multiple are active)"
+  echo ""
+  echo "Commands:"
+  echo "  init [--branch|--worktree|--no-branch] <feature>"
+  echo "                    Start a new pipeline (kebab-case name)"
+  echo "                    --branch: create git branch <prefix><name>"
+  echo "                    --worktree: create git worktree in <worktree_dir>/<name>"
+  echo "                    --no-branch: skip auto-branch/worktree from config"
+  echo "  status            Show current phase, artifacts, progress"
+  echo "  artifact [path]   Register output artifact for current phase"
+  echo "  approve           Advance to next phase (needs artifact)"
+  echo "  revisions [phase] Show revision history (current phase or specify: explore, all)"
+  echo "  history           Show all features and their status"
+  echo "  docs-check        Check project documentation status (JSON)"
+  echo "  docs-init [--all|--update|<template>...]"
+  echo "                    Create standalone docs generation queue"
+  echo "                    --all: queue all available templates"
+  echo "                    --update: queue only stale templates"
+  echo "                    <template>...: queue explicit templates by name"
+  echo "  docs-next         Print next pending template (name + path)"
+  echo "  docs-done <name>  Mark template as completed in queue"
+  echo "  docs-status       Show docs queue progress (JSON)"
+  echo "  docs-reset        Clear the docs queue"
+  echo "  task <T-N>        Mark implementation task as completed (resume tracking)"
+  echo "  config-check      Validate .spec/config.yaml keys and types"
+  echo "  inject <phase> <path>"
+  echo "                    Inject pre-written artifact and skip to that phase"
+  echo "  finish <action>   Finalize branch after pipeline completes"
+  echo "                    Actions: merge, pr, keep, discard (--confirm)"
+  echo "  abandon [feature] Abandon an active pipeline (marks as done)"
+  echo "  version           Show version"
+  echo "  help              Show this message"
+  echo ""
+  echo "Workflow (6 phases):"
+  echo "  1. init my-feature"
+  echo "  2. (agent reads templates/explore.md, investigates)"
+  echo "  3. artifact  ← writes .spec/features/my-feature/explore.md"
+  echo "  4. approve   ← user confirms"
+  echo "  5. (agent reads templates/requirements.md, generates doc)"
+  echo "  6. artifact  ← writes .spec/features/my-feature/requirements.md"
+  echo "  7. approve   ← user confirms"
+  echo "  8. (agent reads templates/design.md, generates doc)"
+  echo "  9. artifact  ← writes .spec/features/my-feature/design.md"
+  echo " 10. approve   ← user confirms"
+  echo " 11. (agent reads templates/task-plan.md, creates TDD plan)"
+  echo " 12. artifact  ← writes .spec/features/my-feature/task-plan.md"
+  echo " 13. approve   ← user confirms"
+  echo " 14. (agent reads templates/implementation.md, executes TDD plan)"
+  echo " 15. artifact  ← writes .spec/features/my-feature/implementation.md"
+  echo " 16. approve   ← user confirms"
+  echo " 17. (agent reads templates/review.md, reviews code)"
+  echo " 18. artifact  ← writes .spec/features/my-feature/review.md"
+  echo " 19. approve   ← user confirms → done!"
+  echo " 20. docs-check ← update project documentation if needed"
+  echo " 21. finish     ← merge, push PR, keep, or discard branch"
+  echo ""
+  echo "All artifacts are saved permanently in .spec/features/<feature>/ and tracked by git."
+  echo "Tip: use 'revisions' to see previous versions of an artifact within a phase."
+}
+
+# --- main ---
+
+# Parse global flags before command dispatch
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --feature)
+      [ -n "$2" ] || die "--feature requires a value"
+      EXPLICIT_FEATURE="$2"
+      shift 2
+      ;;
+    *) break ;;
+  esac
+done
+
+case "${1:-help}" in
+  init)     shift; cmd_init "$@" ;;
+  status)   cmd_status ;;
+  artifact) shift; cmd_artifact "$@" ;;
+  approve)  cmd_approve ;;
+  revisions) shift; cmd_revisions "$@" ;;
+  history)  cmd_history ;;
+  docs-check) cmd_docs_check ;;
+  task)     shift; cmd_task "$@" ;;
+  config-check) cmd_config_check ;;
+  inject)   shift; cmd_inject "$@" ;;
+  finish)   shift; cmd_finish "$@" ;;
+  abandon)  shift; cmd_abandon "$@" ;;
+  docs-init)   shift; cmd_docs_init "$@" ;;
+  docs-next)   cmd_docs_next ;;
+  docs-done)   shift; cmd_docs_done "$@" ;;
+  docs-status) cmd_docs_status ;;
+  docs-reset)  cmd_docs_reset ;;
+  version|--version|-v) cmd_version ;;
+  help|--help|-h) cmd_help ;;
+  *)        die "Unknown command: $1. Run 'pipeline.sh help' for usage." ;;
+esac
diff --git a/.agents/skills/sdd/templates/_preamble.md b/.agents/skills/sdd/templates/_preamble.md
new file mode 100644
index 0000000..37ae049
--- /dev/null
+++ b/.agents/skills/sdd/templates/_preamble.md
@@ -0,0 +1,37 @@
+# Phase Preamble — Shared Instructions
+
+This file contains pipeline integration and project context instructions shared by all phase templates.
+
+Each phase template references this file instead of repeating these sections.
+
+---
+
+## Pipeline Integration
+
+Before starting any phase work:
+
+1. **Check pipeline state:**
+   ```
+   sh ./scripts/pipeline.sh status
+   ```
+2. **Read input artifacts:** read all completed phase artifacts listed in the status output (`history[N].artifact`). Later phases build on earlier ones — read them all for context.
+3. **After the user approves your output:**
+   a. Save the document to `.spec/features/<feature-name>/<phase-name>.md`
+   b. Register: `sh ./scripts/pipeline.sh artifact` (defaults to `.spec/features/<feature-name>/<phase-name>.md`)
+   c. Wait for user to confirm, then: `sh ./scripts/pipeline.sh approve`
+
+> **Directory separation — DO NOT mix these:**
+> - **Phase artifacts** (explore.md, requirements.md, design.md, …) → `.spec/features/<feature>/`
+> - **Project documentation** (README.md, ARCHITECTURE.md, DOMAIN.md, …) → `<docs_dir>/` (default: `.spec/`)
+>
+> Phase artifact instructions above apply ONLY to pipeline phase outputs. Project documentation is a separate workflow — see `./templates/docs-maintenance.md`.
+
+---
+
+## Project Context
+
+If `.spec/config.yaml` exists, read it now and apply:
+- **`context`** → treat as background knowledge about this project.
+- **`rules.<phase>`** → treat as additional rules for THIS phase (appended to the rules below, not replacing them). The phase-specific rule key is specified in each template.
+
+If the file does not exist, skip this step.
diff --git a/.agents/skills/sdd/templates/design.md b/.agents/skills/sdd/templates/design.md
new file mode 100644
index 0000000..432c64d
--- /dev/null
+++ b/.agents/skills/sdd/templates/design.md
@@ -0,0 +1,302 @@
+# Phase 3: Design
+
+You are a Software Architect. Your task: accept the approved requirements document and transform it into a detailed design document that fully describes **HOW** to implement the requirements.
+
+You do **NOT** write implementation code.
+You do **NOT** create task lists.
+You **design** the solution: architecture, interfaces, data models, correctness properties, and verification strategy.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.design`
+- **Input artifacts:** read `history[0..1].artifact` (exploration, requirements documents)
+- **Output:** `.spec/features/<feature-name>/design.md`
+
+---
+
+### Fast-track mode
+
+When the requirements artifact contains 1–2 REQs for a small bug fix:
+
+- **§2.1 Overview:** 1 paragraph.
+- **§2.2 Architecture:** simplified diagram — only the modified component(s). Omit unchanged context unless needed for understanding.
+- **§2.3 Components:** only files requiring changes + 1–2 unchanged files for context. Skip exhaustive "NOT Requiring Changes" list.
+- **§2.4 Key Decisions:** 1 ADR max. Omit if the fix is straightforward with no meaningful alternatives.
+- **§2.5 Data Models:** omit entirely if no new types or schema changes.
+- **§2.6 Correctness Properties:** 2–3 properties focused on the bug scenario. Skip categories that don't apply.
+- **§2.7 Error Handling:** 1–2 rows (main error path + fallback if applicable).
+- **§2.8 Testing Strategy:** reference existing test infrastructure. No new test patterns needed unless the bug exposed a gap.
+
+Target artifact size: **≤ 1.5 pages**.
+
+---
+
+## Language
+
+Write the design document in the **user's language** (detected from their first message). This includes:
+- Section headers (translate "Overview", "Architecture", "Key Decisions", "Error Handling", etc.)
+- All prose: overviews, ADR context/rationale/consequences, error scenario descriptions, test descriptions
+- File change descriptions in §2.3 tables (the "Description" column)
+- Correctness Property statements: write in the user's language, but keep the formal frame in English — `Property N`, `Category`, the quantifier `For all`, and `Validates: Requirements X.Y`
+
+Keep in English (do not translate):
+- Code signatures, type definitions, field names, import paths
+- Mermaid diagram node labels (they reference code constructs)
+- File paths in §2.3 tables
+- Project Commands table values (commands must be verbatim)
+- Tag names in test tables: `Feature/<name>`, `Property/<N>`
+
+---
+
+## Step 1: Context Clarification (optional)
+
+Ask clarifying questions when:
+- The requirements admit multiple substantially different architectural solutions
+- You need information about the existing codebase to make sound design decisions
+- There are contradictions or ambiguities in the requirements
+
+Group 2–4 questions in a single message. If the requirements are self-contained and unambiguous, you may skip this step — but then label every design assumption with `[ASSUMPTION: ...]` inline where it appears, so the user can spot and correct unstated beliefs during review.
+
+---
+
+## Step 2: Design Document Generation
+
+Produce a design document with the following sections. All marked **[REQUIRED]** must appear in every design document. Sections marked **[IF APPLICABLE]** should be included when relevant.
+
+---
+
+### 2.1 Overview [REQUIRED]
+
+Provide a brief description of the feature or change being designed. If the task divides into distinct logical parts, list them explicitly.
+
+---
+
+### 2.2 Architecture [REQUIRED]
+
+Describe the overall architecture using one or more **Mermaid diagrams**. Diagrams must visually distinguish:
+
+- **New** components: `fill:#90EE90` (green)
+- **Modified** components: `fill:#FFD700` (yellow)
+- **Existing/unchanged** components: default styling
+
+Also specify the **implementation order** — which parts should be built first and why.
+
+---
+
+### 2.3 Components and Interfaces [REQUIRED]
+
+#### Files Requiring Changes
+
+Provide a table of all files that must be created or modified:
+
+| File | Change Type | Description |
+|------|-------------|-------------|
+| `path/to/file` | `[NEW]` / `[MODIFIED]` / `[DELETED]` | What specifically is added, changed, or removed |
+
+For `[MODIFIED]` files — state **what exactly changes** (not "various changes"). Example:
+- ✓ `[MODIFIED]` — adds `refreshToken()` method, modifies `authenticate()` return type
+- ✗ `[MODIFIED]` — various authentication changes
+
+#### Files NOT Requiring Changes
+
+Explicitly list files that are in scope or might be expected to change, but will **not** be modified:
+
+| File | Reason Unchanged |
+|------|-----------------|
+| `path/to/file` | Explanation of why this file is unaffected |
+
+> Do not leave this table empty or skip it. Explicitly stating what is not changing is part of the design.
+
+For each interface, provide:
+- **Signature only** — no function bodies or implementation details
+- Input and output types
+- Any preconditions or postconditions in prose
+
+---
+
+### 2.4 Key Decisions (ADR) [REQUIRED]
+
+For each significant design decision, document an Architecture Decision Record (ADR):
+
+**Decision: [short title]**
+- **Context:** What problem or trade-off necessitates this decision
+- **Options considered:** List 2–3 alternatives
+- **Decision:** Which option was chosen
+- **Rationale:** Why this option was selected over the others
+- **Consequences:** Any trade-offs or implications of this choice
+
+Include at least one ADR per non-trivial design choice. Every ADR must capture a **choice between alternatives** — not a restatement of the requirements.
+
+If the feature changes a public API, wire protocol, database schema, or configuration contract, include a **Versioning & Backward Compatibility ADR**:
+- **Versioning strategy** — how old clients/schemas coexist with new (e.g., URL versioning, header negotiation, schema migration with rollback)
+- **Breaking change assessment** — what breaks if deployed without coordination
+- **Migration path** — steps for consumers to adopt the new version
+
+---
+
+### 2.5 Data Models [IF APPLICABLE]
+
+Show full type definitions (struct/class/interface/type alias) for all data structures involved in the feature. Include:
+
+- All fields with their types and a brief comment
+- Mark new types as `[NEW]`
+- Mark types that replace or supersede existing types as `[REMOVED: <OldTypeName>]`
+- Mark modified types explicitly
+
+Example format:
+
+```
+// [NEW] Represents a scheduled job entry
+JobEntry {
+  id:         string   // Unique identifier
+  name:       string   // Human-readable label
+  schedule:   string   // Cron expression
+  enabled:    boolean  // Whether the job is active
+  lastRunAt:  datetime // Timestamp of most recent execution, nullable
+}
+```
+
+Use the syntax natural to your project's language. The goal is precision and completeness, not adherence to any specific language.
+
+---
+
+### 2.6 Correctness Properties [REQUIRED]
+
+Define formal, verifiable properties that the implementation must satisfy. These serve as the specification for testing.
+
+**Format for each property:**
+
+```
+Property <N>: <Name>
+Category: <Equivalence | Absence | Round-trip | Propagation | Exclusion>
+Statement: For all <inputs/states>, <condition that must hold>
+Validates: Requirements <X.Y>
+```
+
+**Category definitions:**
+- **Equivalence** — Two computations that should produce the same result always do
+- **Absence** — A specific error, state, or condition never occurs
+- **Round-trip** — An operation followed by its inverse returns the original value
+- **Propagation** — A change in one place correctly flows through to dependent locations
+- **Exclusion** — Two conditions or states that must never both be true simultaneously
+
+**Rules:**
+- Every property must use the "For all" quantifier — no existential claims
+- Every property must include a `Validates: Requirements X.Y` reference
+- Every requirement from the requirements document must be covered by at least one property
+- Properties must be verifiable — not vague assertions
+- When referenced in tables (Coverage Matrix, Traceability Matrix), use the abbreviated form `CP-N` (e.g., `CP-1`, `CP-2`). The full form `Property N` is used only in definitions above.
+
+**Worked examples** of each category (Equivalence, Absence, Round-trip, Propagation, Exclusion) with §2.6 definitions and §2.8 test table entries: read `./templates/reference/correctness-properties-examples.md`.
+
+---
+
+### 2.7 Error Handling [REQUIRED]
+
+Enumerate all error scenarios and specify how each is detected and handled:
+
+| Scenario | Detection | Action |
+|----------|-----------|--------|
+| Description of what can go wrong | How the system detects this condition | What the system does in response |
+
+Cover edge cases, not just happy-path failures. Include:
+- Invalid or malformed inputs
+- Missing or unavailable dependencies (files, services, connections)
+- Concurrent or race conditions (if applicable)
+- Partial failure states
+
+---
+
+### 2.8 Testing Strategy [REQUIRED]
+
+#### Test Style Source
+
+Before specifying any tests, determine the test style source using the priority cascade defined in `./templates/task-plan.md` § Test Infrastructure Discovery. If `test_skill` is configured, delegate test specification to that skill and skip the rest of §2.8.
+
+**Output:** Include a `Test Style Source` block at the top of §2.8:
+
+```markdown
+**Test Style Source:** Tier <1|2|3>
+- <Evidence: skill name / reference test file paths / "no adjacent tests found">
+- <Key patterns to follow, if Tier 2>
+```
+
+All tests specified below MUST follow the patterns identified in the Test Style Source.
+
+#### Project Commands
+
+Copy the Verification Commands table from the requirements document (§2.8) into the design document. These exact commands will be used in the implementation plan for all test/build/lint/generate steps. If the requirements document lacks this table, read the exploration document's Build Tooling section or discover commands directly from `Makefile`, `Taskfile.yml`, or `package.json` scripts.
+
+```markdown
+**Project Commands:**
+| Action   | Command     |
+|----------|-------------|
+| Test     | `<command>` |
+| Build    | `<command>` |
+| Lint     | `<command>` |
+| Generate | `<command>` |
+```
+
+> The **Generate** row is required only if the project uses code generation. These commands are passed verbatim to the implementation phase.
+
+---
+
+#### Unit Tests
+
+Define the tests required to verify the design. Tag each test with the feature or property it validates.
+
+| Test | Description | Tags |
+|------|-------------|------|
+| `test_<name>` | What is being tested and what the expected outcome is | `Feature/<name>` |
+
+#### Property-Based Tests
+
+Use a property-based testing library appropriate for the project's language. For each correctness property defined in section 2.6, provide a corresponding property-based test:
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_<name>` | Property N from section 2.6 | What inputs are randomly generated | `Property/<N>` |
+
+**Rules:**
+- Every correctness property from section 2.6 must have a corresponding property-based test
+- If no property-based testing library is available for the project's language, substitute targeted unit tests covering representative inputs for each correctness property. Mark them `prop_<name>` and tag with `Property/<N>` as usual. In the Test Style Source block, note: "PBT unavailable — using targeted unit tests as substitute."
+- Every unit test must reference at least one `Feature/` or `Property/` tag
+- Tests are specified by **what they verify** — not by implementation
+
+---
+
+## Quality Control Checklist
+
+Before presenting the design document, verify:
+
+- [ ] Every requirement from the requirements document is covered by at least one correctness property
+- [ ] Every correctness property includes a `Validates: Requirements X.Y` reference
+- [ ] Every correctness property has a corresponding property-based test in section 2.8
+- [ ] Mermaid diagrams use correct colors: green for new, yellow for modified, default for unchanged
+- [ ] The "Files NOT Requiring Changes" table in section 2.3 is filled out
+- [ ] All data types referenced in interfaces are fully defined in section 2.5 (if applicable)
+- [ ] Error handling covers edge cases and partial failure states
+- [ ] Test Style Source (§2.8) is documented with tier and evidence
+- [ ] If the feature changes public APIs, database schemas, or protocols, a versioning/backward-compatibility ADR is present in §2.4
+- [ ] The document is self-contained: a reader unfamiliar with prior context can understand the design
+
+---
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Every requirement from the requirements document is traced to at least one correctness property.
+2. Every correctness property has a corresponding property-based test in §2.8.
+3. The "Files NOT Requiring Changes" table in §2.3 is non-empty.
+4. Mermaid diagrams use correct color coding: green (`#90EE90`) = new, yellow (`#FFD700`) = modified, default = unchanged.
+5. At least one ADR is present in §2.4. If changing API/schema/protocol contracts, a versioning ADR is included.
+6. Test Style Source is documented in §2.8 with tier selection and evidence.
+7. Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Antipatterns to Avoid
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Design.
diff --git a/.agents/skills/sdd/templates/docs-maintenance.md b/.agents/skills/sdd/templates/docs-maintenance.md
new file mode 100644
index 0000000..dedf4da
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs-maintenance.md
@@ -0,0 +1,209 @@
+# Documentation Workflows
+
+This file contains all documentation generation, staleness checking, and post-pipeline maintenance workflows. Referenced from `SKILL.md`.
+
+---
+
+## Standalone Documentation Workflow
+
+**Trigger:** the user requests documentation generation or update **without referring to a feature**. Examples:
+- *"Generate the project documentation"* / *"сгенерируй документацию"*
+- *"Update the docs"* / *"обнови документацию"*
+- *"Refresh AUTH.md"* / *"actualize the architecture doc"*
+
+**DO NOT** run `pipeline.sh init <feature>` for these requests. Documentation generation is a **standalone workflow** with its own state machine — `.spec/.docs-queue.kv` — driven by `pipeline.sh docs-*` commands.
+
+### Step 1: Detect intent
+
+| User intent | Command |
+|-------------|---------|
+| Bootstrap docs from scratch (no `<docs_dir>/` yet) | `pipeline.sh docs-init --all` |
+| Update stale docs only | `pipeline.sh docs-init --update` |
+| Regenerate specific docs (user named them, e.g. "regenerate AUTH and API") | `pipeline.sh docs-init auth api` |
+| User unsure | Run `pipeline.sh docs-check`. If `exists: false` → propose `--all`. If `stale: []` → propose `--update`. Wait for user confirmation. |
+
+### Step 2: Initialize the queue
+
+Run the chosen `docs-init` command. It writes `.spec/.docs-queue.kv` with the list of templates to process. If a queue already exists, the command errors — run `pipeline.sh docs-reset` first if you intend to start over.
+
+Then verify with `pipeline.sh docs-status` (returns JSON with `total`, `completed`, `pending`, `current`, `mode`).
+
+### Step 2.5: Evaluate Execution Strategy
+
+Documentation templates are **independent** (no shared state) and **heavy** (each requires reading dozens of source files). This makes parallelization safe and beneficial.
+
+**Default: SUBAGENT mode** — recommended whenever your toolset supports subagent dispatch (e.g. Claude Code `Task` tool, Cursor Composer, GitHub Copilot subagents, or equivalent).
+
+**Fallback: SEQUENTIAL mode** — used only when subagent dispatch is unavailable.
+
+**Skip mode selection if `total = 1`** — sequential always (overhead of dispatch not justified).
+
+#### Subagent mode (recommended default)
+
+You become the **controller**. Loop:
+
+1. Read `pipeline.sh docs-status` to see pending templates.
+2. **Dispatch up to 3 subagents in parallel** (rate-limit + controller context safety). Each subagent gets one template via this **context package**:
+   - Path to template file (e.g. `./templates/docs/auth.md`)
+   - `docs_dir` value (where to save output)
+   - `rules.docs` from `.spec/config.yaml` (if set)
+   - `context` from `.spec/config.yaml` (if set)
+   - One- or two-sentence summary of project stack (language, framework, key patterns)
+3. **Receive each subagent's report** — it should report which file(s) were created and where.
+4. **Verify** each generated file (controller, never delegated):
+   - File exists at the expected path
+   - **Line 1** matches `<!-- generated: YYYY-MM-DD, template: <name>.md -->`
+   - File is non-trivial (≥ 50 lines)
+5. **If verification fails**: re-dispatch with the verification error in the context package. Maximum **2 retries per template**, then escalate to the user.
+6. **If verification passes**: call `pipeline.sh docs-done <template>`.
+7. Repeat from step 1 until `docs-next` reports the queue is complete.
+8. Run `pipeline.sh docs-reset` to clear the queue.
+
+**Subagent rules:**
+- One subagent per template — never bundle multiple templates into one dispatch.
+- Subagents do NOT interact with `pipeline.sh` — only the controller does.
+- Up to 3 in parallel (no more — controller context fills up receiving multiple large outputs at once).
+- Verification is always performed by the controller.
+
+#### Sequential mode (fallback)
+
+Loop:
+
+1. Run `pipeline.sh docs-next` — it prints the next pending template name and path (tab-separated).
+2. Read the template file from the printed path.
+3. Read `rules.docs` and `context` from `.spec/config.yaml` (if set).
+4. Generate the documentation file(s) following the template's instructions. Save to `<docs_dir>/`. Verify line 1 has the `<!-- generated: ... -->` metadata.
+5. Run `pipeline.sh docs-done <template-name>`.
+6. Repeat until `docs-next` reports the queue is complete.
+
+**Fresh-chat hint:** after position 3, `docs-next` automatically prints a hint suggesting you start a fresh chat to avoid context exhaustion. The queue persists in `.spec/.docs-queue.kv` — in a new chat, run `pipeline.sh docs-status` to see your position and continue with `docs-next`.
+
+### Step 3: Auto-trigger from `docs-check`
+
+When `pipeline.sh docs-check` reports `stale: [...]` non-empty (during pre-pipeline check or on-demand), the workflow is:
+
+1. Inform the user: *"Found N stale doc(s): X, Y, Z. Initialize update queue? Say 'update docs' or 'skip'."*
+2. If user agrees → `pipeline.sh docs-init --update` → proceed to Step 2.5 (execution strategy).
+3. If user declines → no action. The user can run `pipeline.sh docs-init --update` later.
+
+The script does not auto-create the queue — explicit user consent is always required to begin a regeneration cycle.
+
+---
+
+## Documentation Context
+
+The skill supports a self-documenting mechanic via a project documentation directory (default: `.spec/`, configurable via `docs_dir` in `config.yaml`).
+
+> **Directory separation:** Project documentation files (README.md, ARCHITECTURE.md, DOMAIN.md, etc.) live in `<docs_dir>/` (default: `.spec/`). Pipeline phase artifacts (explore.md, requirements.md, design.md, etc.) live in `.spec/features/<feature>/`. **Never place project documentation into the feature directory or vice versa.**
+
+### Pre-pipeline check
+
+When running `pipeline.sh init <feature-name>`, before starting the Explore phase:
+
+1. Determine the docs directory: read `docs_dir` from `.spec/config.yaml`. If not set, default to `.spec`.
+2. Run `pipeline.sh docs-check` to determine if documentation exists and check freshness.
+3. If the docs directory **exists and contains `README.md`**:
+   - Read `README.md` for the documentation map
+   - Use available docs (`ARCHITECTURE.md`, `PACKAGES.md`, etc.) as supplementary context for ALL phases
+   - This is richer than `config.yaml` context and reduces the file-read budget in Explore phase
+   - Check the `stale` array in docs-check output. If stale files exist, suggest: *"Some docs are outdated (<file>: <N> days old). Regenerate before starting? Say 'update docs' or 'skip'."* If user agrees, follow the **Standalone Documentation Workflow** above (`pipeline.sh docs-init --update`).
+4. If the docs directory **does not exist**:
+   - Suggest to the user: *"Project documentation (<docs_dir>/) not found. I can generate it to better understand your codebase. Say 'generate docs' or 'skip'."*
+   - If user says **"generate docs"**: follow the **Standalone Documentation Workflow** above (`pipeline.sh docs-init --all`).
+   - If user says **"skip"**: proceed with the pipeline normally — documentation is NOT required
+   - **This is a soft suggestion, not a blocker.** The pipeline works without documentation.
+
+### Stale doc regeneration workflow (legacy ad-hoc)
+
+> **Prefer the Standalone Documentation Workflow** (top of this file) which uses the `docs-init --update` queue. The ad-hoc steps below remain as a reference for manual single-file regeneration.
+
+When `pipeline.sh docs-check` reports stale files (or the user requests a doc update), follow these steps:
+
+1. Parse the `docs-check` JSON output — read the `stale` array.
+2. For each stale file, extract the `template` field from its freshness metadata.
+3. Group stale files by template (one template may generate multiple files).
+4. For each affected template:
+   a. Read the template from `./templates/docs/<template>.md`.
+   b. Read the existing generated file(s) as baseline — preserve project-specific content where possible.
+   c. Regenerate following the template instructions.
+   d. Update the freshness metadata: `<!-- generated: YYYY-MM-DD, template: <name>.md -->`.
+5. Present updated files to the user for review before saving.
+6. **Never auto-overwrite.** Always confirm with the user.
+
+Use this lookup table to find the owner template for any generated file:
+
+| Generated file | Owner template |
+|----------------|----------------|
+| `README.md`, `agent-rules.md` | `bootstrap.md` |
+| `AGENTS.md` | `agents-index.md` |
+| `ARCHITECTURE.md`, `PACKAGES.md`, `DOMAIN.md`, `CODE_STYLE.md` | `core.md` |
+| `TOOLS.md`, `TESTING.md`, `FILES.md` | `development.md` |
+| `ERRORS.md` | `errors.md` |
+| `AUTH.md`, `OAUTH.md` | `auth.md` |
+| `DATABASE.md` | `database.md` |
+| `API.md` | `api.md` |
+| `DEPLOYMENT.md` | `deployment.md` |
+| `SECURITY.md` | `security.md` |
+| `CLIENTS.md` + per-client docs | `clients.md` |
+| `FEATURE_FLAGS.md` | `feature-flags.md` |
+| `BACKGROUND_JOBS.md` | `background-jobs.md` |
+| `<COMPONENT>.md` (infra) | `infrastructure.md` |
+| `CLI.md` | `cli.md` |
+| `STATE.md` | `state-management.md` |
+| `EVENTS.md` | `events.md` |
+| `COMPONENTS.md` | `components.md` |
+| `ROUTING.md` | `routing.md` |
+
+### Documentation generation templates
+
+Templates for generating project documentation are in `./templates/docs/`. Read the manifest (`./templates/docs/README.md`) to discover available templates. When generating docs:
+- Apply `rules.docs` from `config.yaml` (if present) as additional rules
+- Apply `context` from `config.yaml` as background knowledge
+- Each template is self-contained and generates one or more files in `<docs_dir>/`
+- **Freshness metadata**: when generating or updating any file in `<docs_dir>/`, MUST add `<!-- generated: YYYY-MM-DD, template: <template-name>.md -->` as the **first line** of the file (before the title). This enables `pipeline.sh docs-check` to track documentation age and detect stale files.
+- **Freshness metadata validation**: after saving a generated doc, verify that line 1 matches the pattern `<!-- generated: YYYY-MM-DD, template: <name>.md -->`. If the metadata is missing or malformed, fix it immediately — `docs-check` will silently skip files without valid metadata.
+- **Content-aware staleness**: `pipeline.sh docs-check` uses scope metadata from templates (`<!-- scope: ... -->` first line) combined with `git log --since=<generated_date>` to determine staleness. A doc is marked stale only if (a) files matching its template's scope patterns were changed since generation **and** (b) the doc exceeds the freshness threshold. Docs whose scope shows no changes remain fresh regardless of age. If a template has no scope line, the check falls back to pure age-based staleness. The JSON output includes a `scope_changed` field (`true`/`false`/`null`) per file.
+
+---
+
+## Documentation Maintenance
+
+After the pipeline reaches `phase=done` and artifacts are published, check if project documentation needs updating.
+
+### Step 1: Identify affected docs
+
+Read the design document §2.3 ("Files Requiring Changes" table). Match changed file paths against this pattern table:
+
+| Changed file pattern | Affected doc | Owner template |
+|----------------------|-------------|----------------|
+| `*domain*`, `models/*`, `types/*`, `*entity*` | `DOMAIN.md` | `core.md` |
+| new directory under `internal/`, `pkg/` | `PACKAGES.md` | `core.md` |
+| `cmd/*`, new service, layer changes | `ARCHITECTURE.md` | `core.md` |
+| `*_test*`, `__tests__/`, test config files | `TESTING.md` | `development.md` |
+| `Makefile`, `Taskfile`, `scripts/*`, CI tool changes | `TOOLS.md` | `development.md` |
+| `*error*`, `*errs*`, error codes, error types | `ERRORS.md` | `errors.md` |
+| `*auth*`, `*oauth*`, `*login*`, `*session*` | `AUTH.md` / `OAUTH.md` | `auth.md` |
+| `migrations/*`, `schema*`, `*_repo*`, `*_store*` | `DATABASE.md` | `database.md` |
+| `*handler*`, `*route*`, `*endpoint*`, `*.proto`, `openapi*` | `API.md` | `api.md` |
+| `Dockerfile`, `.github/workflows/*`, `k8s/*`, `docker-compose*` | `DEPLOYMENT.md` | `deployment.md` |
+| `*redis*`, `*kafka*`, `*traefik*`, `*prometheus*`, `*nats*` | `<COMPONENT>.md` | `infrastructure.md` |
+| `*client*`, `*frontend*`, `*mobile*` | `CLIENTS.md` | `clients.md` |
+| `*cors*`, `*csrf*`, `*rate_limit*`, `*security*`, `*helmet*` | `SECURITY.md` | `security.md` |
+| `*feature_flag*`, `*toggle*`, `*experiment*` | `FEATURE_FLAGS.md` | `feature-flags.md` |
+| `*worker*`, `*job*`, `*queue*`, `*cron*`, `*scheduler*` | `BACKGROUND_JOBS.md` | `background-jobs.md` |
+| new code style rule, naming convention change | `CODE_STYLE.md` | `core.md` |
+| `cmd/*`, `cli/*`, `commands/*`, `*cobra*`, `*clap*`, `*click*` | `CLI.md` | `cli.md` |
+| `*store*`, `*redux*`, `*bloc*`, `*provider*`, `*zustand*`, `*pinia*` | `STATE.md` | `state-management.md` |
+| `*event*`, `*messaging*`, `*pubsub*`, `*subscriber*`, `*producer*`, `*consumer*` | `EVENTS.md` | `events.md` |
+| `components/*`, `ui/*`, `design-system/*`, `*widget*`, `atoms/*`, `molecules/*` | `COMPONENTS.md` | `components.md` |
+| `routes/*`, `router/*`, `pages/*`, `screens/*`, `navigation/*` | `ROUTING.md` | `routing.md` |
+
+### Step 2: Filter and suggest
+
+1. Collect unique affected docs from the pattern matches.
+2. **Filter**: only suggest docs that already exist in `<docs_dir>/`. Do not suggest creating new docs post-pipeline.
+3. Present to user: *"This feature touched auth and database files. Update AUTH.md and DATABASE.md? Say 'update docs' or 'skip'."*
+4. If user says **"update docs"**: for each affected doc, read its owner template from `./templates/docs/`, regenerate the doc, update freshness metadata.
+5. If user says **"skip"**: done, no action.
+6. If the docs directory does not exist at all, suggest full generation (same as Pre-flight Checklist step 3).
+7. **Never auto-update documentation.** Always ask the user first.
diff --git a/.agents/skills/sdd/templates/docs/README.md b/.agents/skills/sdd/templates/docs/README.md
new file mode 100644
index 0000000..6239849
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/README.md
@@ -0,0 +1,91 @@
+# Documentation Templates — Manifest
+
+This directory contains prompt templates for generating project documentation in the `.spec/` directory (configurable via `docs_dir` in `config.yaml`).
+
+> **IMPORTANT — Output directory:** All files generated by these templates go to `<docs_dir>/` (default: `.spec/`), **NOT** to `.spec/features/<feature>/`. The features directory is for pipeline phase artifacts only. These are separate directories with separate purposes.
+
+Each template is a self-contained prompt that instructs the AI agent to analyze the project and generate specific documentation files.
+
+## Available Templates
+
+Execution order: **Bootstrap → Core → Domain-Specific**. Run Bootstrap templates first to create the index, then Core for fundamental docs, then Domain-Specific as needed.
+
+| Template | Stage | Generates | When to Use |
+|----------|-------|-----------|-------------|
+| `bootstrap.md` | Bootstrap | `README.md`, `agent-rules.md` | **Run first** — creates the root index and agent rules |
+| `agents-index.md` | Bootstrap | `AGENTS.md` (root) | First-time setup — creates the entry point that explains `.spec/` to agents |
+| `core.md` | Core | `ARCHITECTURE.md`, `PACKAGES.md`, `DOMAIN.md`, `CODE_STYLE.md` | First-time setup or after significant architectural changes |
+| `development.md` | Core | `TOOLS.md`, `TESTING.md`, `FILES.md` | First-time setup or after tooling/testing convention changes |
+| `errors.md` | Core | `ERRORS.md` | If the project defines custom error types, error codes, or error mapping |
+| `auth.md` | Domain | `AUTH.md` or `OAUTH.md` | If the project has authentication (OAuth, email+password, API keys, etc.) |
+| `database.md` | Domain | `DATABASE.md` | If the project uses SQL/NoSQL databases |
+| `api.md` | Domain | `API.md` | If the project exposes REST/gRPC/GraphQL API |
+| `deployment.md` | Domain | `DEPLOYMENT.md` | If the project has Dockerfile, CI/CD, k8s, or PaaS config |
+| `infrastructure.md` | Domain | One `<COMPONENT>.md` per infra component | If the project has Redis, Kafka, Traefik, observability, etc. |
+| `clients.md` | Domain | `CLIENTS.md` + per-client docs | If the project has frontend, mobile, Telegram, CLI clients |
+| `security.md` | Domain | `SECURITY.md` | If the project needs a security audit (input validation, CORS, secrets, OWASP) |
+| `feature-flags.md` | Domain | `FEATURE_FLAGS.md` | If the project uses feature flags, A/B testing, or gradual rollouts |
+| `background-jobs.md` | Domain | `BACKGROUND_JOBS.md` | If the project has background workers, cron jobs, task queues, or async processing |
+| `cli.md` | Domain | `CLI.md` | If the project is a CLI application (commands, flags, config, exit codes) |
+| `state-management.md` | Domain | `STATE.md` | If the project uses state management (Redux, Zustand, BLoC, Pinia, MobX, etc.) |
+| `events.md` | Domain | `EVENTS.md` | If the project uses event-driven patterns (Kafka, NATS, domain events, pub/sub) |
+| `components.md` | Domain | `COMPONENTS.md` | If the project has a UI component library or design system |
+| `routing.md` | Domain | `ROUTING.md` | If the project has client-side routing, navigation guards, or page-based structure |
+
+## Usage
+
+The agent reads this manifest to discover available templates when:
+1. **Pre-pipeline check**: `.spec/` directory is missing — agent offers to generate it
+2. **Post-pipeline update**: feature touched files that affect documentation — agent offers targeted regeneration
+
+The agent selects the relevant template(s), reads them, and follows the instructions to generate documentation.
+
+### Multi-Service / Monorepo Projects
+
+When the project contains multiple services, languages, or independently deployable components:
+- **One `.spec/` per repository, not per service.** Documentation is scoped to the repository level.
+- **Core templates** (`core.md`, `development.md`) cover the overall architecture. Use sections within generated files to describe per-service specifics (e.g., `ARCHITECTURE.md` has a section per service).
+- **Domain templates** (`api.md`, `database.md`, etc.) may be run multiple times — once per service that has the relevant concern. Name generated files with a service prefix if needed (e.g., `API-gateway.md`, `API-users.md`).
+- **Template selection is per-concern, not per-service.** Don't generate `DEPLOYMENT.md` for a service with no deployment config.
+
+## Adding a New Template
+
+To add documentation for a new topic (e.g., AUTH.md, OBSERVABILITY.md, CACHING.md):
+
+1. Create a new file `<topic>.md` in this directory
+2. Follow the structure convention below
+3. Add an entry to the "Available Templates" table above
+
+### Structure Convention
+
+Every template file must follow this structure:
+
+```markdown
+# <Topic> Documentation Template
+
+## What This Generates
+<List of files this template creates, with brief descriptions>
+
+## Instructions
+<Detailed prompt for the AI agent>
+
+### File 1: .spec/<FILENAME>.md
+<Structure and content requirements for this file>
+
+### File 2: .spec/<FILENAME>.md (if multiple)
+<Structure and content requirements for this file>
+
+## General Rules
+<Shared rules for all files generated by this template>
+```
+
+### Rules for template authors:
+- **Language**: English only
+- **Language-neutral examples**: Templates use generic or Go-like examples for illustration, but generated documentation MUST use actual code from the project in its real language/framework. Agents should adapt patterns, naming conventions, and idioms to match the project's tech stack.
+- **Examples**: Use generic placeholders, not project-specific code
+- **Self-contained**: Each template must be usable independently
+- **Real code only**: Templates must instruct the agent to use examples from actual project source, not invented ones
+- **Skip if absent**: If a topic doesn't apply to the project, the agent should skip it (not generate empty docs)
+- **Freshness metadata**: Instruct the agent to add `<!-- generated: YYYY-MM-DD, template: <name>.md -->` as the first line of every generated file. This is parsed by `pipeline.sh docs-check` for staleness detection.
+- **Single owner**: Each piece of data must live in exactly one `.spec/` file. If another template already owns a topic, add a one-line pointer (e.g., "See `ERRORS.md`") instead of duplicating content.
+- **Scope metadata**: Every template must include `<!-- scope: pattern1, pattern2, ... -->` as the **first line** (before the title). Patterns are glob expressions matching source files relevant to the template's topic. `pipeline.sh docs-check` reads these patterns to perform content-aware staleness detection — a doc is only marked stale if files matching its scope were actually changed since the last generation. Example: `<!-- scope: **/migrations/*, **/schema*, **/*repo*, **/*store* -->`.
diff --git a/.agents/skills/sdd/templates/docs/agents-index.md b/.agents/skills/sdd/templates/docs/agents-index.md
new file mode 100644
index 0000000..cb63aec
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/agents-index.md
@@ -0,0 +1,74 @@
+<!-- scope: .copilot/*, .cursor/*, .github/copilot* -->
+# Agents Index Documentation Template
+
+## What This Generates
+
+- `AGENTS.md` in the project root — an instruction file for AI agents (Copilot, Cursor, Windsurf, Claude, etc.) explaining how to use the `.spec/` documentation directory.
+
+## Instructions
+
+Create `AGENTS.md` in the project root. This file instructs AI agents on how to work with the `.spec/` directory in this repository.
+
+The file must contain the following sections:
+
+### Section 1: What is `.spec/`
+
+Explain that `.spec/` is a project documentation directory optimized for AI agent (LLM) consumption. It contains:
+- Structured descriptions of architecture, packages, and domain
+- Code and testing conventions
+- Infrastructure and tooling descriptions
+- Agent rules (`agent-rules.md`)
+
+Purpose: give the agent full project context without having to read the entire source code.
+
+### Section 2: How to Use (for agents)
+
+Instructions for the AI agent:
+- When starting work on a project — read `.spec/README.md` for the documentation map
+- Before modifying code — read the relevant document from `.spec/` (e.g., before modifying API — read `ARCHITECTURE.md` and `CODE_STYLE.md`)
+- Always follow rules from `agent-rules.md`
+- If a document appears outdated — suggest an update
+
+### Section 3: File Structure Convention
+
+Describe file naming conventions in `.spec/`:
+- `README.md` — index of all documents, Quick Facts, project structure, ports, commands
+- `agent-rules.md` — mandatory rules for the agent (code style, naming, error handling)
+- `UPPER_CASE.md` — topical documents (`ARCHITECTURE.md`, `TESTING.md`, etc.)
+- `skills/` — directory for agent skills (custom scripts)
+- `workflows/` — directory for agent workflows
+- `prompts/` — prompts for (re)generating documentation
+
+### Section 4: Document Categories
+
+List the recommended document categories:
+- **Core**: Architecture, Packages, Domain, Code Style
+- **Development**: Tools, Testing, Files/Storage
+- **Auth & Security**: OAuth, API Keys, Permissions
+- **Infrastructure**: Observability, Caching, Proxy, Queues, Leader Election
+- **Clients**: Frontend apps, Mobile, Bots
+
+### Section 5: How to Maintain
+
+Rules for keeping documentation current:
+- When adding a new component — update or create the corresponding document
+- When changing architecture — update `ARCHITECTURE.md`
+- When adding a dependency — update `PACKAGES.md`
+- `README.md` must always reflect the current list of documents
+- Documents must contain code examples from the actual project, not abstract ones
+
+### Section 6: How to Add New Document
+
+Steps for adding a new document:
+1. Create a file `TOPIC_NAME.md` in `.spec/`
+2. Use this structure: title → overview → architectural diagram (ASCII) → details → code examples → configuration → testing → key files
+3. Add a link in `README.md` under the appropriate category
+4. If the topic is project-specific — use real code examples
+
+## General Rules
+
+- Format: Markdown with ASCII diagrams, tables, fenced code blocks with language tags
+- Style: concise, structured, no filler. Optimized for quick scanning.
+- Language: English
+- All code examples must come from the actual project source, not invented
+- If a section does not apply to the project, omit it
diff --git a/.agents/skills/sdd/templates/docs/api.md b/.agents/skills/sdd/templates/docs/api.md
new file mode 100644
index 0000000..61d7f12
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/api.md
@@ -0,0 +1,156 @@
+<!-- scope: **/routes/*, **/handlers/*, **/api/*, *.proto, **/openapi* -->
+# API Documentation Template
+
+## What This Generates
+
+- `.spec/API.md` — API endpoint reference, conventions, middleware, and error format
+
+## Instructions
+
+You are a technical documentarian. Create API documentation for the project in the `.spec/` directory.
+Analyze: route definitions, handler files, middleware chain, proto/OpenAPI specs, request/response types, error handling.
+
+### Step 1: Identify API Surface
+
+Determine the API type(s):
+- **REST**: route files, handler functions, HTTP methods
+- **gRPC**: `.proto` files, generated code, service definitions
+- **GraphQL**: schema files, resolvers
+- **WebSocket**: upgrade handlers, event definitions
+
+For each API surface, identify:
+- Router / framework (e.g., `chi`, `gin`, `echo`, `Express`, `FastAPI`, `net/http`)
+- Base path / port
+- Authentication method (Bearer token, API key, cookie)
+
+### Step 2: Create .spec/API.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: API type + framework
+- Base URL pattern (e.g., `http://localhost:8080/api/v1`)
+- Authentication method summary
+
+##### 2. Middleware Stack
+
+Ordered list of middleware in the request processing pipeline:
+| Order | Middleware | Purpose |
+|-------|-----------|---------|
+| 1 | Request ID | Assigns unique ID to each request |
+| 2 | Logger | Structured request logging |
+| 3 | Recovery | Panic recovery |
+| 4 | Auth | Token validation |
+| 5 | ... | ... |
+
+Determine order from the actual router setup code.
+Note which middleware is global vs route-specific.
+
+##### 3. Endpoint Reference
+
+Group endpoints by resource/domain:
+
+**Users**
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/api/v1/users` | No | Create user |
+| GET | `/api/v1/users/:id` | Yes | Get user by ID |
+
+For each group, include:
+- All endpoints with method, path, auth requirement, description
+- Source file reference (handler file path)
+
+If there are many endpoints (>20), create a summary table first, then detail sections per resource.
+
+##### 4. Request / Response Conventions
+
+Describe the standard patterns:
+- **Request envelope**: is there a wrapper? (`{"data": ...}` vs flat)
+- **Response envelope**: standard response format
+  ```json
+  {
+    "data": { ... },
+    "error": null
+  }
+  ```
+- **Pagination**: pattern used (offset/limit, cursor, page/per_page)
+  - Request parameters
+  - Response metadata (`total`, `next_cursor`, `has_more`)
+- **Sorting**: parameter name and format (e.g., `?sort=name,-created_at`)
+- **Filtering**: parameter patterns (e.g., `?status=active&role=admin`)
+
+Code examples from the actual project.
+
+##### 5. Status Codes & Error Format
+
+**Standard status codes used:**
+| Status | When Used |
+|--------|-----------|
+| 200 | Successful response |
+| 201 | Resource created |
+| 400 | Validation error |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+| 500 | Internal error |
+
+**Error response format:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "email is required",
+    "details": [...]
+  }
+}
+```
+
+Show the actual error response structure from the project.
+Reference the error mapping code (where domain errors become HTTP errors).
+
+##### 6. Versioning Strategy (if applicable)
+- How API versions are specified: URL prefix (`/v1/`), header (`Accept-Version`), content type
+- Current version(s)
+- Deprecation policy
+
+##### 7. Rate Limiting (if applicable)
+- Rate limit values (requests per second/minute)
+- Rate limit headers returned (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)
+- Per-user vs per-IP vs per-API-key
+- Configuration reference
+
+##### 8. Proto / OpenAPI / GraphQL Schema (if applicable)
+
+For **gRPC**:
+- `.proto` file locations
+- Service definitions (list of RPCs per service)
+- Code generation command
+- Client stub usage example
+
+For **OpenAPI**:
+- Spec file location (e.g., `api/openapi.yaml`)
+- How spec is generated (manual vs auto-generated)
+- Swagger UI URL (if served)
+- Code generation command (if applicable)
+
+For **GraphQL**:
+- Schema file location
+- Key queries and mutations
+- Resolver structure
+
+##### 9. Validation
+- Validation library / approach (struct tags, middleware, manual)
+- Where validation happens (handler, middleware, domain layer)
+- Common validation rules used
+- Custom validators (if any)
+
+Code example of a validated request from the project.
+
+## General Rules
+
+- Language: English
+- All endpoints must come from actual route definitions, not assumed
+- Request/response examples must use realistic but non-sensitive data
+- If the project has no API (library, CLI-only), do not generate this file
+- Group endpoints logically by resource, not by HTTP method
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/auth.md b/.agents/skills/sdd/templates/docs/auth.md
new file mode 100644
index 0000000..afd5d8c
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/auth.md
@@ -0,0 +1,142 @@
+<!-- scope: **/*auth*, **/*oauth*, **/*login*, **/*session* -->
+# Auth Documentation Template
+
+## What This Generates
+
+- `.spec/AUTH.md` (or `.spec/OAUTH.md` if the project primarily uses OAuth) — authentication and authorization documentation
+
+## Instructions
+
+You are a technical documentarian. Create auth/authorization documentation for the project in the `.spec/` directory.
+Analyze: OAuth adapters, JWT/PASETO/session middleware, login handlers, DB migrations with auth fields.
+
+### Step 1: Identify Authentication Mechanisms
+
+Determine which authentication mechanisms exist in the project:
+- OAuth2 providers (Google, GitHub, Apple, Yandex, Facebook, Twitter, etc.)
+- Email + Password (classic registration)
+- Telegram Login / Mini App initData
+- API Keys
+- SSO (SAML, OIDC)
+- Magic Links
+- 2FA / MFA
+
+### Step 2: Create the Document
+
+Create `.spec/OAUTH.md` if OAuth is the primary mechanism, or `.spec/AUTH.md` otherwise.
+
+#### Structure:
+
+##### 1. Supported Providers / Methods
+
+Table:
+| Provider/Method | Status | Validation Method |
+|-----------------|--------|-------------------|
+| Google | Ready / TODO | ID Token / API call / ... |
+
+Statuses: Ready, TODO, In Progress
+
+##### 2. Architecture (Flow)
+
+ASCII diagram of the authentication flow:
+```
+Frontend → obtains token → sends to backend → validation → session creation → response
+```
+
+Show the full flow from user click to session receipt.
+If multiple flows exist (OAuth, email+password, Telegram) — show a unified diagram.
+
+##### 3. User Lookup / Creation Logic
+
+Flowchart (Mermaid or ASCII):
+- Token received → validation
+- Search by provider_id → found? → login
+- Search by email → found? → account linking
+- Not found → create new user
+- Create session → return token
+
+##### 4. Account Linking (if applicable)
+Description of the mechanism for linking OAuth accounts to an existing user.
+
+##### 5. Authorization (if applicable)
+
+Permission and access control model:
+- Authorization model type: RBAC / ABAC / scope-based / custom
+- Permission matrix table:
+
+| Role | Action | Resource | Allowed |
+|------|--------|----------|---------|
+| admin | * | * | Yes |
+| user | read | own profile | Yes |
+
+- Where authorization checks happen (middleware, guard, decorator, in-handler)
+- Code reference: file path and key function/method for permission checking
+- How roles/permissions are stored (DB table, JWT claims, config)
+
+##### 6. Session Management (if applicable)
+
+Session storage and lifecycle:
+- Storage mechanism: database / Redis / JWT (stateless) / cookie-based
+- Session model (fields: id, user_id, token, expires_at, etc.)
+- Session lifecycle:
+  1. Creation (on login / OAuth callback)
+  2. Validation (on each request)
+  3. Refresh (token rotation)
+  4. Revocation (logout, password change)
+- Concurrent session policy: allow multiple / single session / limit per device
+- Session cleanup: TTL, cron job, on-demand
+
+##### 7. Token Lifecycle (if applicable)
+
+Token flow and management:
+- Token types used: access token, refresh token, ID token, API key
+- Token format: JWT / PASETO / opaque / custom
+- Token claims / payload structure
+- Issuance flow: what triggers token creation
+- Rotation strategy: how refresh tokens are rotated
+- Revocation mechanism: blocklist, DB flag, Redis TTL
+- Token storage on client side (see also CLIENTS.md if applicable)
+
+##### 8. Account Operations (if applicable)
+
+User account management flows:
+- **Password reset**: flow diagram (request → email → token → new password), token TTL, rate limiting
+- **Email change**: verification flow, old email notification
+- **Account deletion / deactivation**: soft delete vs hard delete, data retention, cascade rules
+- **Profile update**: which fields are mutable, validation rules
+
+For each flow: endpoint reference, code path, edge cases.
+
+##### 9. Configuration
+Configuration example (config.yml, .env, environment variables).
+Do not include real secrets — use placeholders.
+
+##### 10. Per-Provider / Per-Method Implementation
+
+For each provider/method:
+- **File**: path to implementation file
+- **Code**: key fragment (token validation, API call)
+- **Specifics**: what distinguishes this provider
+
+##### 11. Tracing (if applicable)
+Table of tracing spans for auth operations:
+| Span | Description |
+|------|-------------|
+
+##### 12. Adding a New Provider / Method
+Step-by-step guide (numbered list):
+1. Create adapter (code example)
+2. Add configuration
+3. Register in main
+4. DB migration (if needed)
+5. Update handler
+6. Update API validation
+
+## General Rules
+
+- Language: English
+- Do not create sections for providers/methods that do not exist in the project
+- Replace real secrets with placeholders
+- If the project only has email+password without OAuth — name the file `AUTH.md` and adapt the structure
+- All code examples must come from the actual project
+- After creating, update `.spec/README.md`: add a link under Auth & Security
diff --git a/.agents/skills/sdd/templates/docs/background-jobs.md b/.agents/skills/sdd/templates/docs/background-jobs.md
new file mode 100644
index 0000000..2d37e3e
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/background-jobs.md
@@ -0,0 +1,107 @@
+<!-- scope: **/*worker*, **/*job*, **/*queue*, **/*cron* -->
+# Background Jobs Documentation Template
+
+## What This Generates
+
+- `.spec/BACKGROUND_JOBS.md` — documents the background job system, job inventory, retry strategy, and scaling approach
+
+## Instructions
+
+Analyze the project to identify any background job or async task processing. Look for:
+- Job frameworks (Sidekiq, Celery, Temporal, Asynq, Bull, Hangfire, Faktory)
+- Custom worker implementations (goroutines + channels, threads + queues)
+- Cron/scheduler configurations (crontab, systemd timers, Kubernetes CronJobs, `robfig/cron`)
+- Message queue consumers (Kafka consumers, RabbitMQ subscribers, NATS workers, SQS listeners)
+
+If no background job system is found, **skip this template entirely** — do not generate an empty document.
+
+### File: .spec/BACKGROUND_JOBS.md
+
+#### Structure:
+
+##### 1. Overview
+- **System**: which job framework or custom implementation is used
+- **Transport**: underlying queue/broker (Redis, RabbitMQ, Kafka, PostgreSQL, in-memory)
+- **Architecture pattern**: pull-based (workers poll queue) or push-based (broker dispatches)
+- **Entry point**: where workers are started (separate binary, same process, sidecar)
+
+##### 2. Job Inventory
+
+Table of all registered jobs:
+
+| Job Name | Trigger | Frequency / Event | Timeout | Retry | DLQ | Priority |
+|----------|---------|-------------------|---------|-------|-----|----------|
+| `SendWelcomeEmail` | Event: user.created | On event | 30s | 3× | ✅ | normal |
+| `CleanupExpiredSessions` | Cron | Every hour | 5m | 1× | ❌ | low |
+| `ProcessPayment` | Event: order.placed | On event | 60s | 5× exponential | ✅ | high |
+
+Trigger types: `Cron` (scheduled), `Event` (message/webhook), `Manual` (API/CLI), `Cascade` (triggered by another job).
+
+##### 3. Architecture
+
+ASCII diagram showing the job processing flow:
+
+```
+Producer → Queue/Broker → Worker Pool → Result Store
+                ↓ (on failure)
+           Dead Letter Queue → Alert
+```
+
+For each component:
+- **Producer**: which services enqueue jobs, how (SDK call, publish message, HTTP endpoint)
+- **Queue**: queue names, partitioning, priority levels
+- **Worker**: concurrency model (process per job, thread pool, goroutine pool), startup configuration
+- **Result**: where job results are stored (database, cache, nowhere), how callers check completion
+
+##### 4. Retry & Error Handling
+- **Retry policy**: max retries per job, backoff strategy (fixed, exponential, custom)
+- **Backoff configuration**: initial delay, multiplier, max delay, jitter
+- **Dead letter queue (DLQ)**: which jobs have DLQ, how DLQ is monitored, manual replay procedure
+- **Idempotency**: which jobs MUST be idempotent, how idempotency is enforced (unique keys, deduplication)
+- **Error classification**: transient errors (retry) vs permanent errors (DLQ), how the system distinguishes them
+- **Poison messages**: how malformed/unprocessable messages are handled
+
+##### 5. Concurrency & Ordering
+- **Worker count**: how many workers per queue, how it's configured
+- **Parallelism**: can the same job type run in parallel? Are there mutex/lock constraints?
+- **Ordering guarantees**: FIFO per queue? Per partition key? No guarantees?
+- **Rate limiting**: are any jobs rate-limited (e.g., email sending, API calls)?
+- **Distributed locking**: if jobs use locks, which lock mechanism (Redis, DB advisory locks, etcd)
+
+##### 6. Monitoring
+- **Metrics**: which job metrics are collected
+  - Queue depth (pending jobs)
+  - Processing duration (p50, p95, p99)
+  - Success/failure rate
+  - DLQ size
+- **Dashboards**: Grafana/Datadog dashboard links or query examples
+- **Alerting**: alert rules (e.g., "DLQ > 100", "queue depth > 1000 for 5min", "job duration > 2× p99")
+- **Logging**: what is logged per job execution (start, end, duration, error, retry count)
+
+##### 7. Scaling
+- **Horizontal scaling**: how to add more workers (replicas, autoscaling, manual)
+- **Queue partitioning**: are queues partitioned? By what key?
+- **Priority queues**: which priority levels exist, how workers consume them (weighted, strict)
+- **Backpressure**: what happens when the queue is full (block producer, drop, overflow queue)
+- **Resource limits**: CPU/memory per worker, connection pool sizing
+
+##### 8. Development
+Step-by-step guide to add a new background job:
+1. Define job payload struct/schema
+2. Implement handler function
+3. Register handler with the worker
+4. Create producer (enqueue function)
+5. Add retry/DLQ configuration
+6. Write tests (unit + integration)
+7. Add monitoring (metrics, alerts)
+8. Deploy (worker restart required?)
+
+- **Local testing**: how to run workers locally, how to enqueue test jobs
+- **Job simulation**: how to trigger a job manually for debugging (CLI, admin API, console)
+
+## General Rules
+
+- Language: English
+- Use actual job names, queue names, and code references from the project — do not invent examples
+- If no background job system exists, do not generate this file
+- For message queue consumers that are part of the infrastructure layer, defer to `infrastructure.md` for broker-level docs (connection, topology). This template owns the job-level details (handler, retry, monitoring).
diff --git a/.agents/skills/sdd/templates/docs/bootstrap.md b/.agents/skills/sdd/templates/docs/bootstrap.md
new file mode 100644
index 0000000..1d43fdf
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/bootstrap.md
@@ -0,0 +1,126 @@
+<!-- scope: * -->
+# Bootstrap Documentation Template
+
+## What This Generates
+
+- `.spec/README.md` — project documentation index (Quick Facts, Project Structure, Running, Ports, Key Interfaces, Adding Features)
+- `.spec/agent-rules.md` — mandatory rules for AI agents working on this project (Code Style, Naming, Error Handling, Testing, Dependencies, Formatting)
+
+**Run this template first** — it creates the root index that all other templates reference and update.
+
+## Instructions
+
+You are a technical documentarian. Your task is to analyze the current project and create the foundational documentation in the `.spec/` directory for use by AI agents.
+
+### Step 1: Project Analysis
+
+Study the project structure. Pay attention to:
+- Root files: `go.mod`, `package.json`, `requirements.txt`, `Cargo.toml`, `pom.xml`, etc. → determine language and framework
+- Directory structure: `cmd/`, `src/`, `internal/`, `pkg/`, `app/`, `lib/`, etc.
+- Configuration: `docker-compose.yml`, `Makefile`, `Taskfile.yml`, `.github/`, CI/CD
+- API: proto files, OpenAPI/Swagger, GraphQL schemas
+- Tests: `*_test.go`, `*.test.ts`, `test/`, `tests/`, `spec/`
+- Infrastructure: `Dockerfile`, `kubernetes/`, `terraform/`, `configs/`
+- Client applications: `clients/`, `frontend/`, `web/`, `mobile/`
+- Dependencies: `go.sum`, `package-lock.json`, `poetry.lock`, etc.
+
+### Step 2: Create .spec/README.md
+
+Create `.spec/README.md` with the following structure:
+
+#### Header
+```markdown
+# {Project Name} Documentation
+This folder contains documentation to help LLMs and developers quickly understand the project context.
+```
+
+#### Documentation Index
+Group documents by category. Use only categories relevant to the project:
+
+- **Core** — Architecture, Packages, Domain, Code Style (always needed)
+- **Development** — Tools, Testing, Files/Storage (always needed)
+- **Auth & Security** — if the project has OAuth, JWT, API keys
+- **Infrastructure** — if the project has Docker, monitoring, caching, queues
+- **Clients** — if the project has frontend, mobile apps, bots
+
+For each document, add a link: `- [DOC_NAME.md](./DOC_NAME.md) — brief description`
+
+IMPORTANT: If documents have not been created yet, mark them as "TODO" or add a note that they will be created later.
+
+#### Quick Facts
+Table of key project technologies:
+
+```markdown
+| Aspect | Technology |
+|--------|------------|
+| **Language** | ... |
+| **Architecture** | ... |
+| **API** | ... |
+| **Database** | ... |
+| ...    | ...        |
+```
+
+Fill in only what actually exists in the project. Do not guess.
+
+#### Project Structure
+ASCII tree of main directories (1-2 levels deep) with comments:
+
+```
+project/
+├── cmd/           # Entry points
+├── internal/      # Private packages
+├── ...
+```
+
+#### Running
+Key commands for running, testing, and building. Source from Makefile/Taskfile/package.json.
+
+#### Ports
+Port table (if server components exist). Determine from docker-compose.yml, configs, code.
+
+#### Key Interfaces / Entry Points
+Main interfaces or application entry points.
+
+#### Adding New Features
+Brief guide: how to add a new endpoint / page / module.
+
+### Step 3: Create .spec/agent-rules.md
+
+Create `.spec/agent-rules.md` with rules for AI agents specific to this project.
+
+Determine rules based on:
+- Programming language (Go → Effective Go, Python → PEP8, TypeScript → project standards)
+- Linter config (`.golangci.yml`, `.eslintrc`, `.prettierrc`, `pyproject.toml`)
+- Existing code (naming patterns, error handling, file structure)
+
+Required sections:
+- **Code Style** — main style rules
+- **Naming Conventions** — variable, function, and file naming
+- **Error Handling** — project's error handling pattern
+- **Testing** — testing conventions (framework, coverage, patterns)
+- **Dependencies** — how to manage dependencies
+- **Formatting** — formatting and linting
+
+Each rule: 1-2 lines. No filler.
+
+### Step 4: Output Recommendations
+
+After creating files, output a list of recommended documents to generate:
+
+```
+Recommended documents for generation:
+1. ARCHITECTURE.md — [reason: detected Clean Architecture / MVC / ... pattern]
+2. PACKAGES.md — [reason: X packages in the project]
+3. ...
+```
+
+Include only documents for which there is real content in the project.
+
+## General Rules
+
+- Language: English
+- Use only facts from actual code — do not invent
+- If something is unclear — mark as "TODO: requires clarification"
+- Format: Markdown, ASCII diagrams, tables
+- Style: concise, no filler
+- After creating files, the README.md should serve as the map for all future documentation
diff --git a/.agents/skills/sdd/templates/docs/cli.md b/.agents/skills/sdd/templates/docs/cli.md
new file mode 100644
index 0000000..2e9f5ac
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/cli.md
@@ -0,0 +1,146 @@
+<!-- scope: **/cmd/*, **/cli/*, **/commands/*, **/flags/* -->
+# CLI Documentation Template
+
+## What This Generates
+
+- `.spec/CLI.md` — command tree, flags, arguments, configuration, exit codes, I/O contracts
+
+## Instructions
+
+You are a technical documentarian. Create CLI application documentation for the project in the `.spec/` directory.
+Analyze: entry point files, command definitions, flag/argument parsers, configuration loaders, and shell completion scripts.
+
+### Step 1: Identify CLI Framework
+
+Check for the presence of:
+- **Go**: cobra, urfave/cli, kong, pflag, flag (stdlib)
+- **Rust**: clap, structopt, argh
+- **Python**: click, typer, argparse, fire
+- **Node.js**: commander, yargs, oclif, meow, citty
+- **Ruby**: thor, optparse, gli
+- **Dart**: args, dcli
+
+Determine from imports, `go.mod`, `Cargo.toml`, `package.json`, `requirements.txt`, `pubspec.yaml`, etc.
+
+### Step 2: Create .spec/CLI.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: what the CLI does and who uses it
+- Installation command (if applicable)
+- Quick start example (the most common invocation)
+
+##### 2. Command Tree
+
+ASCII tree of all commands and subcommands:
+```
+myapp
+├── init              # Initialize a new project
+├── run               # Run the application
+│   ├── --watch       # Watch mode
+│   └── --port N      # Port number
+├── config
+│   ├── get <key>     # Read config value
+│   ├── set <key> <v> # Write config value
+│   └── list          # List all config values
+└── version           # Print version
+```
+
+Build from actual command registration code (e.g., `rootCmd.AddCommand()`, `@app.command()`, `.command()`).
+
+##### 3. Commands Reference
+
+For each command (or command group):
+
+```markdown
+### `myapp <command> [flags]`
+
+**Description:** One sentence.
+
+| Flag / Argument | Type | Required | Default | Description |
+|----------------|------|----------|---------|-------------|
+| `<positional>` | string | yes | — | What it is |
+| `--flag` / `-f` | bool | no | `false` | What it does |
+| `--output` / `-o` | string | no | `stdout` | Output destination |
+
+**Examples:**
+\```bash
+myapp run --port 8080
+myapp config set key value
+\```
+```
+
+Extract flags from actual struct tags, decorators, or builder calls — do not invent.
+
+##### 4. Configuration
+
+- Config file locations (precedence order): CLI flags → env vars → config file → defaults
+- Config file format (YAML, TOML, JSON, INI)
+- Config file path resolution (XDG, `$HOME/.config/`, project-local)
+- Environment variable naming convention (e.g., `MYAPP_PORT`, `MYAPP_LOG_LEVEL`)
+
+Table:
+| Setting | Flag | Env Var | Config Key | Default |
+|---------|------|---------|------------|---------|
+
+##### 5. Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | General error |
+| `2` | Usage error (invalid flags/arguments) |
+| ... | Project-specific codes |
+
+Extract from actual code if defined (e.g., `os.Exit()`, `process.exit()`, `std::process::exit()`).
+
+##### 6. I/O Contracts
+
+- **stdin**: Does the CLI read from stdin? What format? (e.g., piped JSON, line-delimited)
+- **stdout**: What is printed on success? (data output, structured JSON, human-readable text)
+- **stderr**: What goes to stderr? (logs, progress, errors)
+- **Files**: Does the CLI create/modify files? Where?
+
+Piping and composition examples:
+```bash
+cat input.json | myapp process --format json > output.json
+myapp list --json | jq '.[] | .name'
+```
+
+##### 7. Shell Completion
+
+- Supported shells (bash, zsh, fish, PowerShell)
+- Installation commands for each shell
+- How completions are generated (static file, dynamic `completion` subcommand)
+
+If no completion support exists, note it explicitly.
+
+##### 8. Global Flags
+
+Flags available on all commands:
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--verbose` / `-v` | bool | `false` | Verbose output |
+| `--config` / `-c` | string | `~/.config/myapp/config.yaml` | Config file path |
+| `--quiet` / `-q` | bool | `false` | Suppress non-error output |
+
+##### 9. Error Messages & Troubleshooting
+
+Common error messages and their resolutions:
+| Error | Cause | Fix |
+|-------|-------|-----|
+
+##### 10. Development
+
+- How to run the CLI locally during development
+- How to build a release binary
+- How to add a new command (step-by-step referencing the framework)
+
+## General Rules
+
+- Language: English
+- All commands, flags, and examples must come from actual source code — do not invent
+- If the CLI has no subcommands (single-command tool), adapt the structure: skip the command tree, expand the flags section
+- If the project is not a CLI application, do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/clients.md b/.agents/skills/sdd/templates/docs/clients.md
new file mode 100644
index 0000000..6f21ac2
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/clients.md
@@ -0,0 +1,175 @@
+<!-- scope: **/client*, **/sdk/* -->
+# Clients Documentation Template
+
+## What This Generates
+
+- `.spec/CLIENTS.md` — overview of all client applications
+- `.spec/<CLIENT_NAME>.md` — one file per significant client (e.g., `FRONTEND.md`, `TELEGRAM.md`, `MOBILE.md`, `CLI.md`)
+
+## Instructions
+
+You are a technical documentarian. Create client application documentation for the project in the `.spec/` directory.
+Analyze directories: `clients/`, `frontend/`, `web/`, `mobile/`, `app/`, `bot/`, `cli/`, etc.
+
+### Step 1: Identify Client Applications
+
+Check for the presence of:
+- **Web SPA**: React, Vue, Angular, Svelte, Next.js, Nuxt
+- **Mobile**: React Native, Flutter, Swift, Kotlin
+- **Telegram**: Mini App, Bot
+- **Desktop**: Electron, Tauri
+- **CLI**: cobra, click, argparse
+- **Browser Extension**: Chrome, Firefox
+
+For each found client, analyze: `package.json`, `pubspec.yaml`, `build.gradle`, etc.
+
+### Step 2: Create .spec/CLIENTS.md (overview)
+
+#### Structure:
+
+##### 1. Available Clients
+Table:
+| Client | Location | Technology | Purpose |
+|--------|----------|------------|---------|
+
+##### 2. Shared Code
+What clients share:
+- API types (TypeScript interfaces, Dart models)
+- API client (Axios, Dio, fetch wrapper)
+- Commands for syncing shared code
+
+**Code Generation** (if applicable):
+- Source of truth: proto files, OpenAPI spec, GraphQL schema
+- Generation command (e.g., `make gen-client`, `npm run codegen`)
+- Output directory (e.g., `clients/shared/api/`)
+- Sync workflow: when to regenerate, how to verify freshness
+
+**API Version Management** (if applicable):
+- How clients handle API versioning (URL prefix, header, content-type)
+- Backward compatibility strategy (deprecation notices, feature flags)
+- How multiple API versions coexist on the client side
+
+##### 3. API Communication
+ASCII diagram: how clients communicate with the backend:
+```
+┌──────────┐     ┌──────────┐
+│  Client  │────>│ Backend  │
+│  (React) │ REST│ (API)    │
+└──────────┘     └──────────┘
+```
+Protocol (REST, gRPC, WebSocket, GraphQL), ports.
+
+##### 4. Authentication Flow
+Authentication steps from the client perspective:
+1. Registration → endpoint
+2. Login → endpoint → token receipt
+3. Token storage (localStorage, SecureStorage, cookies)
+4. Sending in header
+
+##### 5. Adding a New Client
+Options (React-based, native mobile, PWA, etc.) with step-by-step instructions.
+
+##### 6. Development Workflow
+Commands for running the full stack (backend + clients).
+
+### Step 3: Create Per-Client Documents
+
+Create a separate document if the client:
+- Has its own technology stack
+- Contains > 10 files
+- Has specific logic (Telegram SDK, TON Connect, etc.)
+
+#### Per-Client Template: .spec/{CLIENT_NAME}.md
+
+Example names: `FRONTEND.md`, `TELEGRAM.md`, `MOBILE.md`, `CLI.md`
+
+##### 1. Overview
+One sentence + link to base template (if applicable).
+Path: `clients/web/` or equivalent.
+
+##### 2. Tech Stack
+Table:
+| Technology | Purpose |
+|------------|---------|
+
+Determine from `package.json` / `pubspec.yaml` / `build.gradle`.
+
+##### 3. Directory Structure
+ASCII tree (2 levels):
+```
+clients/web/
+├── src/
+│   ├── api/         # API client and types
+│   ├── components/  # Reusable components
+│   ├── pages/       # Page components
+│   └── ...
+└── package.json
+```
+
+##### 4. Commands
+```bash
+npm install          # Install dependencies
+npm run dev          # Start dev server
+npm run build        # Production build
+...
+```
+
+##### 5. Routes / Navigation
+Route table:
+| Path | Component | Auth Required |
+|------|-----------|---------------|
+
+##### 6. API Client
+- Configuration (base URL, interceptors)
+- Authentication (how the token is stored and sent)
+- Available methods (table: Method | Endpoint | Auth)
+
+##### 7. UI Framework / Theme (if applicable)
+- Which UI kit is used
+- Colors, fonts, styling approach
+
+##### 8. Platform-Specific Features
+
+**For Telegram Mini App:**
+- SDK initialization
+- initData authentication
+- Mock environment for local development
+- Native UI components (@telegram-apps/telegram-ui)
+- TON Connect (if applicable)
+- Auto-login flow
+
+**For Mobile (React Native / Flutter):**
+- Platform-specific code (iOS/Android)
+- Push notifications
+- Deep linking
+- Native modules
+
+**For CLI:**
+- Commands and subcommands
+- Flags and arguments
+- Configuration files
+
+##### 9. Environment Variables
+```bash
+VITE_API_URL=http://localhost:10002
+# or
+NEXT_PUBLIC_API_URL=...
+```
+
+##### 10. Development vs Production
+Differences between dev and prod modes.
+
+##### 11. Deployment
+How to deploy the client (GitHub Pages, Vercel, App Store, npm publish).
+
+##### 12. Adding New Pages / Features
+Step-by-step instructions for adding a new page/feature.
+
+## General Rules
+
+- If a client is trivial (< 5 files) — do not create a separate document, describe it in `CLIENTS.md`
+- Determine technologies from actual `package.json` / dependencies, do not guess
+- Routes must come from the actual router code (`App.tsx`, `routes.tsx`, `router.ts`)
+- API methods must come from the actual API client
+- After creating files, update `.spec/README.md`: add links under the Clients section
+- If there are no client applications in the project, do not generate any files — skip this template entirely
diff --git a/.agents/skills/sdd/templates/docs/components.md b/.agents/skills/sdd/templates/docs/components.md
new file mode 100644
index 0000000..113afa6
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/components.md
@@ -0,0 +1,176 @@
+<!-- scope: **/components/*, **/ui/*, **/design-system/*, **/atoms/*, **/molecules/*, **/widgets/* -->
+# Components Documentation Template
+
+## What This Generates
+
+- `.spec/COMPONENTS.md` — design system, component library, composition patterns, theming
+
+## Instructions
+
+You are a technical documentarian. Create UI component documentation for the project in the `.spec/` directory.
+Analyze: component directories, shared UI libraries, theme/token files, Storybook config, and style systems.
+
+### Step 1: Identify Component Architecture
+
+Check for the presence of:
+- **React**: `components/`, JSX/TSX files, Storybook, Radix, shadcn/ui, MUI, Ant Design, Chakra
+- **Vue**: `components/`, SFC (`.vue` files), Vuetify, PrimeVue, Quasar, Headless UI
+- **Angular**: `components/`, Angular Material, PrimeNG, standalone components
+- **Svelte**: `lib/components/`, SvelteKit components, Skeleton UI, Flowbite
+- **Flutter/Dart**: `widgets/`, `lib/ui/`, custom Widget classes, Material/Cupertino
+- **Web Components**: Custom Elements, Lit, Stencil
+
+Determine from framework files, imports, and component registration patterns.
+
+### Step 2: Create .spec/COMPONENTS.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: component architecture approach
+- UI library / framework used (if any)
+- Design methodology: Atomic Design, BEM, component composition, compound components
+- Styling approach: CSS Modules, styled-components, Tailwind, CSS-in-JS, vanilla CSS, SCSS
+
+##### 2. Component Inventory
+
+Master table of all shared/reusable components:
+
+| Component | Location | Category | Props / Inputs | Used By |
+|-----------|----------|----------|----------------|---------|
+| `Button` | `src/components/Button.tsx` | Atom | `variant`, `size`, `disabled`, `onClick` | Throughout |
+| `Modal` | `src/components/Modal.tsx` | Molecule | `isOpen`, `onClose`, `title`, `children` | `Settings`, `Confirm` |
+| `DataTable` | `src/components/DataTable.tsx` | Organism | `columns`, `data`, `onSort`, `pagination` | `Users`, `Orders` |
+
+Categorize by complexity level (Atom / Molecule / Organism / Template) or by domain (Layout / Form / Feedback / Navigation / Data Display) — whichever the project uses.
+
+##### 3. Component API Patterns
+
+Document the conventions used across all components:
+
+**Props / Inputs:**
+- Naming conventions (e.g., `onX` for callbacks, `isX` for booleans, `xRef` for refs)
+- Required vs optional patterns
+- Default values strategy
+- Children / slots / content projection patterns
+
+**Composition patterns used:**
+- Compound components (e.g., `<Select><Select.Option>`)
+- Render props / scoped slots
+- Higher-order components / mixins
+- Headless / renderless components
+- Forward ref / template ref
+
+Code example of a well-structured component from the project.
+
+##### 4. Design Tokens / Theme
+
+**Colors:**
+| Token | Light Value | Dark Value | Usage |
+|-------|-------------|------------|-------|
+| `--color-primary` | `#3B82F6` | `#60A5FA` | Buttons, links, active states |
+| `--color-surface` | `#FFFFFF` | `#1E1E1E` | Cards, modals, backgrounds |
+
+**Typography:**
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--font-family-base` | `Inter, sans-serif` | Body text |
+| `--font-size-sm` | `0.875rem` | Secondary text, captions |
+
+**Spacing:**
+| Token | Value |
+|-------|-------|
+| `--space-1` | `4px` |
+| `--space-2` | `8px` |
+
+Extract from actual theme files, CSS custom properties, Tailwind config, `ThemeData`, or token files.
+
+**Dark mode / Theming:**
+- How themes are defined and switched
+- CSS custom properties, `ThemeProvider`, `prefers-color-scheme`
+- Where theme tokens live (file path)
+
+##### 5. Layout System
+
+- Grid system: CSS Grid, Flexbox, framework grid (e.g., MUI Grid, Bootstrap Grid)
+- Breakpoints:
+
+| Name | Min Width | Typical Usage |
+|------|-----------|---------------|
+| `sm` | `640px` | Mobile landscape |
+| `md` | `768px` | Tablet |
+| `lg` | `1024px` | Desktop |
+
+- Container / wrapper components
+- Responsive patterns used (fluid, adaptive, mobile-first)
+
+##### 6. Form Components
+
+- Form library (React Hook Form, Formik, VeeValidate, Angular Reactive Forms)
+- Validation approach (schema-based with Zod/Yup, inline, server-side)
+- Error display pattern (inline, toast, summary)
+- Standard form controls:
+
+| Component | Type | Validation | Accessibility |
+|-----------|------|------------|---------------|
+| `TextInput` | text, email, password | required, pattern | `aria-label`, error announcement |
+| `Select` | dropdown | required | keyboard navigation |
+| `Checkbox` | boolean | — | `role="checkbox"` |
+
+##### 7. Icon System
+
+- Icon source: icon library (Lucide, Heroicons, Material Icons), custom SVGs, icon font
+- How icons are used in components (component import, sprite, CSS class)
+- Sizing conventions
+- Where custom icons are stored
+
+##### 8. Animation & Transitions
+
+- Animation library (Framer Motion, GSAP, Vue Transition, CSS animations)
+- Standard transitions:
+
+| Transition | Duration | Easing | Used For |
+|-----------|----------|--------|----------|
+| Fade in/out | `200ms` | `ease-in-out` | Modal, tooltip |
+| Slide | `300ms` | `ease-out` | Drawer, sidebar |
+| Scale | `150ms` | `ease-in` | Button press, card hover |
+
+- Reduced motion: how `prefers-reduced-motion` is respected
+
+##### 9. Accessibility (a11y)
+
+- WCAG target level (A, AA, AAA)
+- Keyboard navigation patterns (tab order, focus trap in modals, arrow keys in lists)
+- ARIA attributes used by components
+- Screen reader testing approach
+- Color contrast compliance
+
+##### 10. Storybook / Component Playground
+
+- Storybook version and config location (if applicable)
+- How to run: command
+- Story file naming convention (`.stories.tsx`, `.stories.vue`)
+- Addons used (a11y, viewport, controls)
+- How to add a new story
+
+If no Storybook or equivalent exists, note it.
+
+##### 11. Adding a New Component
+
+Step-by-step guide:
+1. Create component file in the correct directory
+2. Define props/inputs interface
+3. Implement with project conventions (styling, composition)
+4. Add to exports / barrel file
+5. Write story (if Storybook)
+6. Write tests (unit + visual regression if applicable)
+7. Document usage
+
+## General Rules
+
+- Language: English
+- All components, props, and tokens must come from actual source code — do not invent
+- If the project uses a pre-built UI library with no customization (e.g., just MUI out-of-box), document the usage patterns rather than the library internals
+- For Flutter/Dart projects, adapt terminology: Widget instead of Component, `ThemeData` instead of CSS tokens
+- If the project has no shared UI components (e.g., pure backend, CLI), do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/core.md b/.agents/skills/sdd/templates/docs/core.md
new file mode 100644
index 0000000..22a591f
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/core.md
@@ -0,0 +1,232 @@
+<!-- scope: cmd/*, internal/*, pkg/*, src/*, app/*, domain/* -->
+# Core Documentation Template
+
+## What This Generates
+
+- `.spec/ARCHITECTURE.md` — project architecture overview
+- `.spec/PACKAGES.md` — reference of all packages/modules
+- `.spec/DOMAIN.md` — domain model description
+- `.spec/CODE_STYLE.md` — project-specific code conventions
+
+## Instructions
+
+You are a technical documentarian. Create the core project documentation in the `.spec/` directory.
+Analyze the source code, directory structure, dependencies, and configuration files.
+
+Create the following files:
+
+---
+
+### File 1: .spec/ARCHITECTURE.md
+
+A document describing the project's architecture.
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: application type + architectural pattern
+- ASCII diagram of application layers (top-down: Transport → Application → Adapters → Infrastructure)
+- Show connections between layers with arrows
+
+##### 2. Component Deep Dive
+For each architectural layer:
+- Name and package path
+- Key files with descriptions (table: File | Description)
+- Role in the system
+- Which interfaces it implements / uses
+
+Analyze the actual code:
+- Entry point (`main.go` / `main.ts` / `app.py` etc.)
+- Business logic (`app/`, `domain/`, `services/`, `use_cases/`)
+- Adapters (`adapters/`, `repositories/`, `infrastructure/`)
+- API layer (`api/`, `handlers/`, `controllers/`, `routes/`)
+
+##### 3. Directory Structure
+ASCII tree with comments (2-3 levels deep):
+```
+project/
+├── cmd/                    # Entry points
+│   └── app/
+│       └── internal/
+│           ├── app/        # Business logic
+│           ├── adapters/   # Infrastructure adapters
+│           └── api/        # API handlers
+├── internal/               # Shared packages
+└── configs/                # Configuration files
+```
+
+##### 4. Key Design Decisions
+Numbered list of key architectural decisions (3-7 items):
+- Architectural pattern and why
+- API strategy (REST/gRPC/GraphQL)
+- Dependency injection approach
+- Testing strategy
+- Observability approach (if present)
+- Context propagation (if present)
+
+For each decision: title, 2-3 bullet points, code example if appropriate.
+
+##### 5. Data Flow
+Trace the lifecycle of a typical request from entry point to response:
+- ASCII sequence diagram showing how a request passes through layers
+- Name the concrete types/functions involved at each step
+- Show where validation, authorization, business logic, and persistence happen
+
+Example format:
+```
+HTTP Request
+  → Router (api/router.go)
+    → Middleware (auth, logging, tracing)
+      → Handler (api/handler.go)
+        → App method (app/service.go)
+          → Adapter (adapters/repo.go)
+            → Database
+          ← Return domain object
+        ← Convert to response
+      ← Send HTTP response
+```
+
+If the project has multiple entry points (HTTP + gRPC, CLI + API), show the primary one and note differences for others.
+
+---
+
+### File 2: .spec/PACKAGES.md
+
+Reference of all project packages/modules.
+
+#### Structure:
+
+For each package/module:
+
+```markdown
+### `path/to/package`
+**Brief description** — one sentence.
+
+| File | Description |
+|------|-------------|
+| `file1.go` | Description |
+| `file2.go` | Description |
+
+Key details (if applicable):
+- Which interfaces it implements
+- Which libraries it uses
+- Specifics (tracing, caching, etc.)
+```
+
+Group packages by layer:
+1. **Application Layer** — business logic
+2. **Adapters Layer** — infrastructure adapters
+3. **API Layer** — transport
+4. **Shared/Internal** — common utilities
+5. **Generated** — generated code (proto, OpenAPI, etc.)
+
+---
+
+### File 3: .spec/DOMAIN.md
+
+Description of the project's domain model.
+
+#### Structure:
+
+##### 1. Core Entities
+For each entity:
+- Name
+- Structure definition (in the project's language)
+- Field comments (if non-obvious)
+
+##### 2. Enums / Value Objects
+All enumerations and value objects with their values.
+
+##### 3. Business Errors
+> Owned by `errors.md` → `ERRORS.md`. Do **not** duplicate the catalog here.
+
+One-line summary: "For the full business error catalog (codes, HTTP/gRPC mapping, retry policy) see `ERRORS.md`."
+If `ERRORS.md` does not exist yet, list errors inline and note that they should be migrated when `errors.md` is run.
+
+##### 4. Search/Filter Parameters
+Search/filter structures (if present).
+
+Important:
+- Take definitions from actual code (`domain.go`, `models.py`, `types.ts`, etc.)
+- Do not invent fields — only what exists in the code
+- For large structures, show all fields
+
+---
+
+### File 4: .spec/CODE_STYLE.md
+
+Project-specific code conventions.
+
+#### Structure:
+
+##### 1. Layer Structure
+ASCII diagram of layers with rules for each:
+- Which structures are used (public/private, with/without tags)
+- How conversion between layers works
+
+##### 2. Struct Tags by Layer (if applicable)
+For each layer:
+- Rule
+- Code example (Correct)
+- Explanation (Why)
+
+##### 3. Conversion Pattern
+How data is converted between layers:
+- Adapters ↔ App (convert methods)
+- API ↔ App (toX functions)
+
+##### 4. Naming Conventions
+Tables:
+- Files: file naming patterns by layer
+- Structs: visibility (public/private) by layer
+- Enums: definition pattern
+
+##### 5. Interface Conventions
+Rules for interfaces:
+- Argument order (context first, etc.)
+- Error documentation
+- Interface composition
+
+##### 6. Import Ordering
+Import order with example.
+
+##### 7. Test File Organization
+Table of test file patterns.
+
+##### 8. Quick Reference
+Summary table: Aspect | App Layer | Adapters Layer | API Layer
+
+##### 9. Error Propagation
+Rules for error handling across layers:
+- How errors are wrapped when crossing layer boundaries
+- Sentinel errors vs typed errors: when to use each
+- Error types by layer (domain errors, adapter errors, API errors)
+- Code example showing error wrapping chain from adapter → app → API
+
+##### 10. Logging Conventions
+Structured logging rules:
+- Logger type and initialization pattern
+- What to log at each layer (table: Layer | Log Level | What to Log)
+- Sensitive data handling (what must never be logged)
+- Correlation IDs / request IDs (how passed through context)
+- Code example of a properly logged operation
+
+##### 11. Concurrency Patterns (if applicable)
+Concurrency rules used in the project:
+- Goroutine / async task management (how spawned, how tracked)
+- Context cancellation propagation
+- Channel / queue usage patterns
+- Mutex / synchronization patterns
+- Graceful shutdown sequence
+
+If the project is single-threaded or has no concurrency patterns, skip this section.
+
+## General Rules
+
+- Language: English
+- Format: Markdown with ASCII diagrams, tables, fenced code blocks with language tags
+- Code examples: ONLY from the actual project, not abstract
+- If something is not found in the project — do not create the corresponding section
+- Each document must be self-contained (can be read independently)
+- Do not duplicate information between documents — cross-reference instead
+- After creating files, update `.spec/README.md`: add links to created documents in the Documentation Index section
diff --git a/.agents/skills/sdd/templates/docs/database.md b/.agents/skills/sdd/templates/docs/database.md
new file mode 100644
index 0000000..04b986b
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/database.md
@@ -0,0 +1,114 @@
+<!-- scope: **/migrations/*, **/schema*, **/*repo*, **/*store* -->
+# Database Documentation Template
+
+## What This Generates
+
+- `.spec/DATABASE.md` — database schema, migrations, connection management, and query patterns
+
+## Instructions
+
+You are a technical documentarian. Create database documentation for the project in the `.spec/` directory.
+Analyze: migration files, ORM config, repository/DAO layer, database drivers, connection setup, seed scripts.
+
+### Step 1: Identify Database Usage
+
+Determine which databases the project uses:
+- **SQL**: PostgreSQL, MySQL, SQLite, CockroachDB
+- **NoSQL**: MongoDB, DynamoDB, Cassandra, Redis (if used as primary store)
+- **Search**: Elasticsearch, Meilisearch, Typesense
+
+For each database, identify:
+- Driver / ORM / query builder (e.g., `pgx`, `sqlx`, `GORM`, `Prisma`, `TypeORM`, `sqlc`)
+- Migration tool (e.g., `goose`, `migrate`, `knex`, `Flyway`, `Alembic`)
+- Connection configuration (env vars, config files)
+
+### Step 2: Create .spec/DATABASE.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: which database(s) and why
+- Driver / ORM used
+- Connection string format (with placeholders, no real credentials)
+
+##### 2. Schema Overview
+
+**Entity-Relationship Diagram:**
+ASCII or Mermaid ER diagram showing tables and relationships:
+```
+┌──────────┐     ┌──────────────┐     ┌──────────┐
+│  users   │────<│ user_tokens  │     │  posts   │
+│──────────│     │──────────────│     │──────────│
+│ id (PK)  │     │ id (PK)      │     │ id (PK)  │
+│ email    │     │ user_id (FK) │  ┌──│ user_id  │
+│ name     │     │ token        │  │  │ title    │
+└──────────┘     └──────────────┘  │  └──────────┘
+      │                            │
+      └────────────────────────────┘
+```
+
+**Table Reference:**
+| Table | Purpose | Key Columns |
+|-------|---------|-------------|
+| `users` | User accounts | `id`, `email`, `name`, `created_at` |
+
+For each table: name, purpose, key columns. Group by domain area if many tables.
+
+##### 3. Migration Strategy
+- Migration tool and version
+- Migration directory path
+- Naming convention (e.g., `YYYYMMDDHHMMSS_description.sql`, sequential numbers)
+- Up / down convention: are down migrations required?
+- How to create a new migration (command)
+- How to run migrations (command)
+- How to rollback (command)
+- CI integration: are migrations run automatically in CI/CD?
+
+##### 4. Connection Management
+- Connection pool configuration (min/max connections, idle timeout)
+- Read replicas (if applicable): how reads are routed
+- Connection lifecycle: where the connection is created, how it's passed (context, DI, global)
+- Health check / ping mechanism
+- Reconnection strategy
+
+Code reference: file path where connection is initialized.
+
+##### 5. Query Patterns
+- Repository / DAO pattern: interface definition and implementation structure
+- Query builder vs raw SQL vs ORM: which approach is used and when
+- Transaction management: how transactions are started, committed, rolled back
+- Prepared statements / named queries (if applicable)
+- Pagination pattern (offset vs cursor)
+
+Code example of a typical repository method from the project.
+
+##### 6. Seed / Fixtures
+- Dev seed data: how to populate the database for local development (command)
+- Test fixtures: how test data is set up (helpers, factories, SQL files)
+- Reset command: how to wipe and re-seed the database
+- Sample data location (if seed files exist)
+
+##### 7. Indexes & Performance (if discoverable)
+Notable indexes beyond primary keys:
+| Table | Index | Columns | Type |
+|-------|-------|---------|------|
+
+Only include if indexes are defined in migration files or ORM annotations.
+
+##### 8. Backup & Recovery (if applicable)
+- Backup strategy (pg_dump, cloud snapshots, scheduled jobs)
+- Backup commands or scripts
+- Point-in-time recovery (WAL archiving, binlog)
+- Data retention policy
+
+Only include if backup tooling or scripts exist in the project.
+
+## General Rules
+
+- Language: English
+- All SQL examples must come from actual migration files or repository code
+- Do not invent tables or columns — only document what exists
+- If the project uses multiple databases, create sections for each
+- Connection strings and credentials must use placeholders, never real values
+- If the project has no database, do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/deployment.md b/.agents/skills/sdd/templates/docs/deployment.md
new file mode 100644
index 0000000..72e88e9
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/deployment.md
@@ -0,0 +1,138 @@
+<!-- scope: Dockerfile*, docker-compose*, **/deploy/*, **/k8s/* -->
+# Deployment Documentation Template
+
+## What This Generates
+
+- `.spec/DEPLOYMENT.md` — environments, deployment pipeline, rollout strategy, health checks, and infrastructure
+
+## Instructions
+
+You are a technical documentarian. Create deployment documentation for the project in the `.spec/` directory.
+Analyze: Dockerfile, docker-compose files, CI/CD configs, Kubernetes manifests, Helm charts, Terraform files, deployment scripts, health check endpoints.
+
+### Step 1: Identify Deployment Infrastructure
+
+Check for the presence of:
+- **Containers**: `Dockerfile`, `docker-compose.yml`, `.dockerignore`
+- **CI/CD**: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `bitbucket-pipelines.yml`
+- **Orchestration**: `k8s/`, `helm/`, `kustomize/`, `nomad/`
+- **IaC**: `terraform/`, `pulumi/`, `cloudformation/`
+- **PaaS**: `fly.toml`, `render.yaml`, `railway.json`, `vercel.json`, `netlify.toml`
+
+### Step 2: Create .spec/DEPLOYMENT.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: deployment target + strategy
+- ASCII diagram of the deployment pipeline:
+```
+push → CI (lint + test) → build image → push registry → deploy → health check
+```
+
+##### 2. Environments
+
+| Environment | URL / Host | Purpose | Branch | Auto-deploy |
+|-------------|-----------|---------|--------|-------------|
+| Local | `localhost:8080` | Development | — | — |
+| Staging | `staging.example.com` | Pre-production testing | `develop` | Yes |
+| Production | `example.com` | Live | `main` | No (manual) |
+
+For each environment: how to access, what branch triggers deployment, any special config.
+
+##### 3. Docker
+
+**Dockerfile analysis:**
+- Base image and build stages (multi-stage?)
+- Build arguments and their purpose
+- Exposed ports
+- Entry point / command
+- Image size optimization notes
+
+**Docker Compose (dev):**
+- Services defined and their roles
+- Volume mounts
+- Network configuration
+- Useful commands:
+```bash
+docker-compose up -d        # Start all services
+docker-compose logs -f app  # Follow app logs
+docker-compose down -v      # Stop and remove volumes
+```
+
+##### 4. CI/CD Pipeline
+
+For each CI/CD workflow file:
+- **File**: path to workflow
+- **Trigger**: on push, PR, tag, manual
+- **Steps**: ordered list of what happens
+- **Secrets required**: list of secret names (not values)
+
+Example:
+```
+.github/workflows/ci.yml
+  Trigger: push to main, PR
+  Steps: checkout → setup → lint → test → build → push image
+  Secrets: DOCKER_USERNAME, DOCKER_PASSWORD, DEPLOY_KEY
+```
+
+##### 5. Rollout Strategy
+- Strategy type: rolling update / blue-green / canary / recreate
+- Configuration (max surge, max unavailable, canary percentage)
+- Where configured (k8s deployment spec, PaaS config, script)
+- Zero-downtime deployment: yes/no, how achieved
+
+##### 6. Health Checks
+
+| Endpoint | Type | Expected Response | Timeout |
+|----------|------|-------------------|---------|
+| `/health` | Liveness | `200 OK` | 5s |
+| `/ready` | Readiness | `200 OK` | 10s |
+
+- What each check verifies (DB connection, cache, external services)
+- Startup probe (if applicable)
+- Code reference: where health check handlers are defined
+
+##### 7. Rollback Procedure
+Step-by-step rollback instructions:
+1. Identify the issue (logs, metrics, alerts)
+2. Rollback command (e.g., `kubectl rollout undo`, `git revert` + redeploy, PaaS rollback)
+3. Verify rollback (health check, smoke test)
+4. Post-mortem actions
+
+Include actual commands for the project's deployment target.
+
+##### 8. Secrets Management
+- Where secrets are stored: environment variables, vault, cloud secret manager, CI/CD variables
+- How secrets are injected: env files, k8s secrets, mounted volumes
+- Rotation policy (if documented)
+- Required secrets list:
+
+| Secret | Purpose | Where Set |
+|--------|---------|-----------|
+| `DATABASE_URL` | DB connection | CI/CD vars |
+| `JWT_SECRET` | Token signing | Vault |
+
+Do not include actual secret values.
+
+##### 9. Infrastructure Requirements (if applicable)
+Resource requirements per service:
+| Service | CPU | Memory | Storage | Replicas |
+|---------|-----|--------|---------|----------|
+
+Determine from k8s resource limits, PaaS config, or documentation.
+
+##### 10. Monitoring & Alerts (if applicable)
+- Where to view logs (log aggregator URL, command)
+- Metrics dashboard (Grafana URL, Datadog, etc.)
+- Alert rules (what triggers alerts)
+- On-call / escalation process (if documented)
+
+## General Rules
+
+- Language: English
+- All commands and paths must come from actual project files
+- Never include real secrets, tokens, or internal URLs — use placeholders
+- If the project has no deployment config (pure library), do not generate this file
+- Focus on what exists, not what should exist — document current state
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/development.md b/.agents/skills/sdd/templates/docs/development.md
new file mode 100644
index 0000000..9aa772e
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/development.md
@@ -0,0 +1,202 @@
+<!-- scope: Makefile, Taskfile*, scripts/*, **/ci/* -->
+# Development Documentation Template
+
+## What This Generates
+
+- `.spec/TOOLS.md` — reference of commands and project tools
+- `.spec/TESTING.md` — project testing conventions
+- `.spec/FILES.md` — file storage system description (only if applicable)
+
+## Instructions
+
+You are a technical documentarian. Create the development documentation in the `.spec/` directory.
+Analyze the Makefile, Taskfile.yml, package.json scripts, CI/CD configs, test files, and file adapters.
+
+Create the following files:
+
+---
+
+### File 1: .spec/TOOLS.md
+
+Reference of commands and project tools.
+
+#### Structure:
+
+##### 0. Dev Environment Setup
+
+Prerequisites and first-run instructions for new developers:
+
+**Prerequisites:**
+| Tool | Version | Install |
+|------|---------|---------|
+| Go / Node / Python | x.y | `brew install ...` / link |
+
+Determine from: `go.mod`, `package.json` engines, `.tool-versions`, `Dockerfile` base image, README.
+
+**First Run:**
+Numbered steps to go from a fresh clone to a running dev environment:
+1. Clone the repository
+2. Copy env file (`cp .env.example .env`) — list required variables
+3. Install dependencies (`go mod download` / `npm install`)
+4. Start infrastructure (`docker-compose up -d`)
+5. Run migrations (command)
+6. Start the application (command)
+7. Verify (health check URL or test command)
+
+If a `Makefile` / `Taskfile` has an `init` or `setup` target, reference it.
+
+##### 1. Overview
+One sentence + important note about how to run commands (e.g., "All commands must be run via `task`" or "Use `make`" or "Use `npm run`").
+
+##### 2. Quick Reference
+Table of key commands:
+| Action | Command |
+|--------|---------|
+| Unit tests | `...` |
+| Build | `...` |
+| Lint | `...` |
+| Start | `...` |
+| Stop | `...` |
+
+Source commands from:
+- Makefile / Taskfile.yml / package.json scripts
+- CI/CD configs (`.github/workflows/`, `.gitlab-ci.yml`)
+- Project README.md
+
+##### 3. Detailed Command Groups
+
+For each group (Testing, Building, Docker, Linting, Init, etc.):
+- Command with usage example (bash code block)
+- What it does (1-2 lines)
+- Dependencies (what must be run before)
+- Tools used
+
+##### 4. Code Generation (if applicable)
+Code generation commands:
+- Proto/OpenAPI generation
+- Test mocks
+- Stringer/enum generators
+- ORM generators (sqlc, ent, etc.)
+
+For each: command + what it generates + configuration file.
+
+##### 5. CI/CD Cheatsheet
+Quick commands for simulating the CI pipeline locally.
+
+##### 6. Tool Installation
+Table of tools with installation commands:
+| Tool | Install Command |
+|------|-----------------|
+
+Determine from go.mod tools, package.json devDependencies, Brewfile, etc.
+
+---
+
+### File 2: .spec/TESTING.md
+
+Project testing conventions.
+
+#### Structure:
+
+Analyze existing test files in the project and identify patterns.
+
+##### 1. Test Package Naming
+Which convention: internal test package or external test package?
+Example from actual code.
+
+##### 2. Test File Structure
+Full example of a typical test from the project:
+- Imports
+- Test case structure
+- Setup / teardown
+- Assertions
+
+##### 3. Key Patterns
+Identify and describe patterns (only those actually used):
+- Table-driven tests (map vs slice)
+- Parallel execution
+- Variable capture in range loops
+- Common test helpers (`start()`, `setup()` functions)
+- Builder pattern for test data
+- Golden files
+- Snapshot testing
+
+For each pattern: name + code example from the project.
+
+##### 4. Mock Generation
+How mocks are generated:
+- Tool (mockgen, testify/mock, etc.)
+- Generation command
+- Where stored (alongside tests / separate directory)
+- `go:generate` directive (if applicable)
+
+##### 5. Integration Tests
+- How separated from unit tests (build tags, directory, naming)
+- Run command
+- Test containers / test helpers for Docker
+- Examples of test resource initialization
+
+##### 6. Export Pattern (if applicable)
+How private functions are tested from external test packages.
+Example of `export_test.go` or equivalent.
+
+##### 7. Commands
+All testing commands:
+```bash
+# Unit tests
+...
+# Integration tests
+...
+# Coverage
+...
+# Race detector
+...
+```
+
+---
+
+### File 3: .spec/FILES.md (only if the project has file storage)
+
+Description of the file handling system.
+
+#### When to create:
+- S3/MinIO/file adapter exists
+- File upload/download functionality exists
+- Avatars, media, or documents are handled
+
+#### Structure:
+
+##### 1. Overview
+ASCII diagram of file flow: API → Application → FileStore → Storage
+
+##### 2. FileStore Interface
+Interface definition from the code.
+
+##### 3. File Model
+File structure from the domain layer.
+
+##### 4. Storage Adapter
+- Which storage (S3, MinIO, local FS, Cloudflare R2)
+- Configuration
+- Bucket / directory structure
+- File metadata
+
+##### 5. Specific Features
+Project-specific features (avatars, limits, formats, etc.)
+
+##### 6. Limitations & Recommendations
+Current limitations and improvement recommendations.
+
+##### 7. Environment Variables
+Storage configuration from docker-compose / env files.
+
+##### 8. Test Coverage
+How the file system is tested.
+
+## General Rules
+
+- All code examples — from the actual project
+- If a tool/pattern is not found — do not describe it
+- Format: Markdown, tables, fenced code blocks with language tags
+- After creating files, update `.spec/README.md`: add links under the Development section
+- If `.spec/FILES.md` does not apply (no file storage in the project), skip it entirely
diff --git a/.agents/skills/sdd/templates/docs/errors.md b/.agents/skills/sdd/templates/docs/errors.md
new file mode 100644
index 0000000..384040c
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/errors.md
@@ -0,0 +1,172 @@
+<!-- scope: **/*error*, **/*errs* -->
+# Errors Documentation Template
+
+## What This Generates
+
+- `.spec/ERRORS.md` — error architecture, business error catalog, wrapping conventions, and API error format
+
+## Instructions
+
+You are a technical documentarian. Create error handling documentation for the project in the `.spec/` directory.
+Analyze: error type definitions, error packages, HTTP/gRPC error mapping, middleware error handlers, domain error constants.
+
+### Step 1: Identify Error Patterns
+
+Determine how the project handles errors:
+- **Custom error types**: struct-based errors with codes, domain error packages
+- **Sentinel errors**: `var ErrNotFound = errors.New(...)` / constants
+- **Error wrapping**: `fmt.Errorf("...: %w", err)` / custom wrap functions
+- **Error mapping**: domain → HTTP status, domain → gRPC code
+- **Error response format**: JSON structure returned to API consumers
+
+### Step 2: Create .spec/ERRORS.md
+
+#### Structure:
+
+##### 1. Error Architecture
+
+Layered error model showing how errors flow through the application:
+```
+┌─────────────────────────────────────────────────┐
+│  API Layer                                       │
+│  Maps domain errors → HTTP status / gRPC code   │
+│  Formats error response JSON                     │
+├─────────────────────────────────────────────────┤
+│  Application Layer                               │
+│  Returns domain errors (ErrNotFound, etc.)       │
+│  Wraps adapter errors with context               │
+├─────────────────────────────────────────────────┤
+│  Adapter Layer                                   │
+│  Wraps infrastructure errors (DB, network)       │
+│  Converts to domain errors where appropriate     │
+├─────────────────────────────────────────────────┤
+│  Infrastructure                                  │
+│  Raw errors (sql.ErrNoRows, net.Error, etc.)     │
+└─────────────────────────────────────────────────┘
+```
+
+Describe the error propagation direction and rules:
+- Which layer creates errors
+- Which layer wraps errors
+- Which layer maps/translates errors
+- Where errors are logged vs returned
+
+##### 2. Business Error Catalog
+
+Table of all defined business/domain errors:
+
+| Code | Name | HTTP Status | gRPC Code | Description |
+|------|------|-------------|-----------|-------------|
+| `NOT_FOUND` | `ErrNotFound` | 404 | `NotFound` | Resource does not exist |
+| `ALREADY_EXISTS` | `ErrAlreadyExists` | 409 | `AlreadyExists` | Resource already exists |
+| `VALIDATION` | `ErrValidation` | 400 | `InvalidArgument` | Input validation failed |
+| `UNAUTHORIZED` | `ErrUnauthorized` | 401 | `Unauthenticated` | Authentication required |
+| `FORBIDDEN` | `ErrForbidden` | 403 | `PermissionDenied` | Insufficient permissions |
+
+Group by domain area if many errors exist. Include the file path where each error is defined.
+
+##### 3. Error Wrapping Convention
+
+Rules for wrapping errors at each layer boundary:
+
+**Adapter → Application:**
+```
+// Example pattern (use actual code from the project)
+func (r *repo) GetUser(ctx context.Context, id UserID) (*User, error) {
+    row := r.db.QueryRow(ctx, query, id)
+    if err := row.Scan(...); err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, ErrNotFound
+        }
+        return nil, fmt.Errorf("get user %s: %w", id, err)
+    }
+    ...
+}
+```
+
+**Application → API:**
+```
+// Example pattern (use actual code from the project)
+func handleError(err error) (int, ErrorResponse) {
+    switch {
+    case errors.Is(err, app.ErrNotFound):
+        return 404, ErrorResponse{Code: "NOT_FOUND", ...}
+    ...
+    }
+}
+```
+
+Show the actual wrapping pattern used in the project. Include file references.
+
+##### 4. Error Response Format
+
+The standard error response structure returned by the API:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable description",
+    "details": [
+      {
+        "field": "email",
+        "message": "must be a valid email address"
+      }
+    ]
+  }
+}
+```
+
+Document:
+- Envelope structure
+- Required vs optional fields
+- How validation errors include field-level details
+- How the code maps to the Business Error Catalog
+- Content-Type header
+
+##### 5. Sentinel Errors vs Error Types
+
+When to use each approach in this project:
+
+**Sentinel errors** (simple, comparable with `errors.Is`):
+- When to use: identity-only errors without extra data
+- Examples from the project
+
+**Typed errors** (struct implementing `error` interface):
+- When to use: errors carrying extra context (field name, entity ID, etc.)
+- Examples from the project
+
+**Error interfaces** (if applicable):
+- Custom error interfaces for behavior-based checking (`errors.As`)
+- Examples from the project
+
+##### 6. Retry Policy (if applicable)
+
+Which errors are retryable and how:
+
+| Error Category | Retryable | Strategy |
+|----------------|-----------|----------|
+| Network timeout | Yes | Exponential backoff, max 3 |
+| DB connection lost | Yes | Reconnect + retry once |
+| Validation error | No | — |
+| Not found | No | — |
+| Rate limited | Yes | Respect Retry-After header |
+
+Include retry logic implementation reference if it exists in the project.
+
+##### 7. Error Logging
+
+Rules for error logging:
+- Which errors are logged and at which level (error, warn, info)
+- What context is included (request ID, user ID, stack trace)
+- Where errors are logged (handler layer, middleware, or both)
+- How to avoid double-logging (log at the top, wrap at the bottom)
+
+## General Rules
+
+- Language: English
+- All error types and codes must come from actual code — do not invent errors
+- Code examples must be from the project, showing real wrapping and mapping patterns
+- If the project has no custom error handling (uses raw errors only), document that and keep the file minimal
+- Do not duplicate the full error catalog if it already exists in `DOMAIN.md` §3 — cross-reference instead, but add HTTP/gRPC mapping columns
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/events.md b/.agents/skills/sdd/templates/docs/events.md
new file mode 100644
index 0000000..99627f4
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/events.md
@@ -0,0 +1,159 @@
+<!-- scope: **/events/*, **/messaging/*, **/pubsub/*, **/subscribers/*, **/producers/*, **/consumers/* -->
+# Events Documentation Template
+
+## What This Generates
+
+- `.spec/EVENTS.md` — event catalog, schemas, producers/consumers, delivery guarantees, error handling
+
+## Instructions
+
+You are a technical documentarian. Create event-driven architecture documentation for the project in the `.spec/` directory.
+Analyze: event definitions, message schemas, producer/publisher implementations, consumer/subscriber handlers, queue/topic configuration, and retry/DLQ logic.
+
+### Step 1: Identify Event System
+
+Check for the presence of:
+- **Message Brokers**: Kafka, RabbitMQ, NATS, Redis Pub/Sub, AWS SQS/SNS, Google Pub/Sub, Azure Service Bus
+- **In-Process Event Bus**: EventEmitter (Node.js), mediator pattern, domain events (DDD), Spring Events
+- **Streaming**: Kafka Streams, NATS JetStream, Redis Streams, Flink
+- **Browser/Frontend**: CustomEvent, EventTarget, RxJS Subject, Vue EventBus, React event callbacks
+- **Mobile**: Flutter Streams, BroadcastChannel, NotificationCenter (iOS), LocalBroadcastManager (Android)
+- **Webhooks**: outbound event delivery over HTTP (see also `webhooks.md` if you create a separate template)
+
+For each system found, identify: client library, connection config, serialization format (JSON, Protobuf, Avro, MessagePack).
+
+### Step 2: Create .spec/EVENTS.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: which event system(s) and why
+- Architecture pattern: event-driven, CQRS, event sourcing, pub/sub, saga/choreography
+- ASCII diagram of the event flow:
+
+```
+Producer A ──→ [Topic/Queue] ──→ Consumer X
+Producer B ──→ [Topic/Queue] ──→ Consumer Y
+                    ↓
+              [Dead Letter Queue]
+```
+
+##### 2. Event Catalog
+
+Master table of all events in the system:
+
+| Event Name | Topic / Channel | Producer | Consumer(s) | Schema | Idempotent |
+|------------|----------------|----------|-------------|--------|------------|
+| `user.created` | `users` | `UserService` | `EmailService`, `AnalyticsService` | `UserCreatedEvent` | Yes (by user_id) |
+| `order.paid` | `orders` | `PaymentGateway` | `FulfillmentService` | `OrderPaidEvent` | Yes (by order_id) |
+| `cart.updated` | in-process | `CartStore` | `CartBadge`, `CartSummary` | `CartState` | N/A |
+
+Extract from actual event publishing and subscription code — do not invent events.
+
+##### 3. Event Schemas
+
+For each event (or event group), document the payload:
+
+```typescript
+// user.created
+interface UserCreatedEvent {
+  event_id: string;        // Unique event identifier (UUID)
+  event_type: "user.created";
+  timestamp: string;       // ISO 8601
+  data: {
+    user_id: string;
+    email: string;
+    registered_via: "email" | "oauth";
+  };
+  metadata: {
+    correlation_id: string;  // Request trace ID
+    source: string;          // Producing service name
+  };
+}
+```
+
+Use the project's actual language and types. Note which fields are required vs optional.
+
+##### 4. Topics / Channels / Queues
+
+| Topic / Queue | Partitions | Retention | Consumer Group(s) | Purpose |
+|--------------|------------|-----------|-------------------|---------|
+| `users` | 3 | 7 days | `email-svc`, `analytics-svc` | User lifecycle events |
+| `orders` | 6 | 30 days | `fulfillment-svc` | Order processing |
+
+Include configuration source (env vars, config files, IaC definitions).
+
+##### 5. Producers
+
+For each producer:
+- **Location**: file path and function/method
+- **Trigger**: what causes the event to be published
+- **Serialization**: how the event is serialized before sending
+- **Error handling**: what happens if publishing fails (retry, circuit breaker, outbox pattern)
+- **Transactional outbox**: if used, describe the pattern (DB transaction + outbox table + poller)
+
+Code example of a typical producer from the project.
+
+##### 6. Consumers
+
+For each consumer:
+- **Location**: file path and function/method
+- **Concurrency**: how many concurrent consumers (worker count, partition assignment)
+- **Processing guarantee**: at-least-once, at-most-once, exactly-once
+- **Idempotency strategy**: how duplicate events are handled (idempotency key, deduplication window, upsert)
+- **Error handling**: what happens on processing failure
+- **Ordering**: does processing depend on event order? How is it guaranteed?
+
+Code example of a typical consumer from the project.
+
+##### 7. Delivery Guarantees
+
+| Guarantee | Strategy | Implementation |
+|-----------|----------|----------------|
+| At-least-once | Manual ack after processing | Consumer commits offset after handler returns |
+| Ordering | Per-key ordering | Partition key = entity ID |
+| Idempotency | Dedup by event_id | Check processed_events table before handling |
+| Exactly-once | Transactional outbox | DB transaction + outbox poller |
+
+##### 8. Dead Letter Queue (DLQ)
+
+- DLQ topic/queue name and configuration
+- When events are sent to DLQ (max retries exceeded, deserialization failure, handler exception)
+- Retry policy before DLQ: count, backoff strategy (fixed, exponential, jitter)
+- How DLQ events are monitored and reprocessed
+- Manual replay mechanism (if available)
+
+If no DLQ exists, note it explicitly and flag as a risk.
+
+##### 9. Event Versioning & Evolution
+
+- How event schemas evolve (backward-compatible additions, schema registry, version field)
+- Breaking change process: how old consumers handle new event versions
+- Schema validation: compile-time (Protobuf, Avro) or runtime (JSON Schema)
+- If no versioning strategy exists, note it and flag as a risk.
+
+##### 10. Monitoring & Observability
+
+- Consumer lag monitoring (Kafka consumer group lag, queue depth)
+- Event throughput metrics
+- Failed event alerting
+- Correlation ID / trace propagation through events
+- Dashboard links (if applicable)
+
+##### 11. Testing Events
+
+- How to test producers (unit test: event published with correct payload)
+- How to test consumers (unit test: handler processes event correctly)
+- Integration testing: in-memory broker, test containers, embedded broker
+- How to publish test events manually (CLI tool, admin endpoint, script)
+
+Code example of an event test from the project.
+
+## General Rules
+
+- Language: English
+- All events, topics, and schemas must come from actual source code — do not invent
+- If the project uses multiple event systems (e.g., Kafka for inter-service + in-process for domain events), document all and explain boundaries
+- For frontend-only event systems (CustomEvent, RxJS), adapt the template: skip DLQ, delivery guarantees, and monitoring sections
+- If the project has no event-driven patterns, do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/feature-flags.md b/.agents/skills/sdd/templates/docs/feature-flags.md
new file mode 100644
index 0000000..45c2245
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/feature-flags.md
@@ -0,0 +1,91 @@
+<!-- scope: **/*flag*, **/*toggle*, **/*feature* -->
+# Feature Flags Documentation Template
+
+## What This Generates
+
+- `.spec/FEATURE_FLAGS.md` — documents the feature flag system, flag inventory, lifecycle, and rollout strategy
+
+## Instructions
+
+Analyze the project to identify any feature flag or feature toggle system. Look for:
+- SDK imports (LaunchDarkly, Unleash, Flagsmith, Split.io)
+- Custom flag implementations (config-based, env var-based, database-based)
+- Flag evaluation calls in application code
+- A/B testing or experimentation frameworks
+
+If no feature flag system is found, **skip this template entirely** — do not generate an empty document.
+
+### File: .spec/FEATURE_FLAGS.md
+
+#### Structure:
+
+##### 1. Overview
+- **System**: which flag provider or custom implementation is used
+- **Architecture**: how flags are loaded (SDK init, config file, env vars, database table)
+- **Evaluation flow**: where in the request lifecycle flags are checked (middleware, service layer, per-handler)
+- **Default behavior**: what happens when the flag service is unavailable (fail open / fail closed)
+
+##### 2. Flag Inventory
+
+Table of all active feature flags:
+
+| Flag Name | Type | Description | Owner | Created | Expiry | Default |
+|-----------|------|-------------|-------|---------|--------|---------|
+| `enable_new_checkout` | boolean | New checkout flow | @payments | 2025-01-15 | 2025-04-15 | false |
+| `search_algorithm` | multivariate | A/B test for search | @search | 2025-02-01 | — | `v1` |
+
+Types: `boolean`, `multivariate` (string/number variants), `percentage` (0–100).
+
+Mark flags as: 🟢 Active, 🟡 Rolling out, 🔴 Scheduled for removal.
+
+##### 3. Lifecycle
+Document the flag lifecycle in this project:
+1. **Creation** — who can create flags, where they are defined, naming conventions
+2. **Rollout** — gradual rollout strategy (percentage, user segments, regions)
+3. **Stabilization** — when a flag is considered stable (metrics period, error rate threshold)
+4. **Permanent or removal** — decision criteria: does the flag become permanent config or get removed?
+5. **Removal process** — code cleanup steps, how to find all evaluation points
+
+##### 4. Implementation Pattern
+Show the code pattern used to evaluate flags in this project:
+- **Evaluation call**: actual code example from the project (e.g., `flags.IsEnabled("feature_x", user)`)
+- **Context passing**: how user/request context reaches the flag evaluation
+- **Type safety**: is there a typed wrapper or raw string keys?
+- **Fallback**: what value is returned if evaluation fails
+
+##### 5. Testing with Flags
+- **Unit tests**: how to override flag values in tests (mock, test config, env var)
+- **Integration tests**: how to test both sides of a flag (enabled and disabled)
+- **Test matrix**: which flag combinations are tested together
+- **CI behavior**: are flags forced to a specific value in CI?
+
+##### 6. Rollout Strategy
+- **Percentage rollout**: how to do gradual rollout (1% → 10% → 50% → 100%)
+- **User targeting**: can flags be enabled per user, per org, per region?
+- **Kill switch**: how to instantly disable a flag in production
+- **Monitoring**: what metrics to watch during rollout (error rate, latency, conversion)
+- **Rollback**: how to roll back a flag without a code deploy
+
+##### 7. Cleanup Policy
+- **Stale flag detection**: how to find flags that are 100% rolled out but not removed from code
+- **Linting / static analysis**: any tooling to detect dead flag references
+- **Cleanup cadence**: how often the team reviews and removes old flags
+- **Technical debt tracking**: how stale flags are tracked (issues, labels, dashboards)
+
+##### 8. Configuration
+How flags are configured per environment:
+
+| Environment | Source | Sync | Notes |
+|-------------|--------|------|-------|
+| Development | `.env` / config file | Manual | All flags enabled by default |
+| Staging | Flag service | Real-time | Mirrors production targeting |
+| Production | Flag service | Real-time | Gradual rollout rules apply |
+
+- **Local override**: how developers enable/disable flags locally
+
+## General Rules
+
+- Language: English
+- Use actual flag names and code from the project — do not invent examples
+- If no feature flag system exists, do not generate this file
+- Mark flags scheduled for removal — this document should help cleanup efforts
diff --git a/.agents/skills/sdd/templates/docs/infrastructure.md b/.agents/skills/sdd/templates/docs/infrastructure.md
new file mode 100644
index 0000000..8597407
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/infrastructure.md
@@ -0,0 +1,157 @@
+<!-- scope: **/infra/*, **/redis*, **/kafka*, **/nats* -->
+# Infrastructure Documentation Template
+
+## What This Generates
+
+One `.spec/<COMPONENT>.md` file per significant infrastructure component discovered in the project. Examples:
+- `.spec/OBSERVABILITY.md` — OpenTelemetry, Prometheus, Grafana, Jaeger, etc.
+- `.spec/REDIS.md` — Redis caching, sessions, leader election
+- `.spec/TRAEFIK.md` / `.spec/NGINX.md` — reverse proxy
+- `.spec/QUEUES.md` / `.spec/KAFKA.md` — message queues
+- `.spec/LEADER_ELECTION.md` — distributed coordination
+- `.spec/SEARCH.md` — Elasticsearch, Meilisearch, etc.
+
+## Instructions
+
+You are a technical documentarian. Create infrastructure documentation for the project in the `.spec/` directory.
+Analyze: `docker-compose.yml`, `configs/`, caching adapters, monitoring setup, proxy config, and other infrastructure components.
+
+### Step 1: Identify Infrastructure Components
+
+Check for the presence of:
+- **Observability**: OpenTelemetry, Prometheus, Grafana, Jaeger, Tempo, Loki, Datadog, New Relic, Sentry, Pyroscope
+- **Caching**: Redis, Memcached, in-memory cache
+- **Message Queues**: Kafka, RabbitMQ, NATS, Redis Pub/Sub
+- **Reverse Proxy**: Traefik, Nginx, Caddy, Envoy
+- **Search**: Elasticsearch, Meilisearch, Typesense
+- **Distributed Coordination**: Leader election, distributed locks, service discovery
+- **CDN / Object Storage**: CloudFront, Cloudflare, S3
+
+For each discovered component, create a separate `.spec/COMPONENT_NAME.md` file.
+
+### Step 2: Create Documents
+
+For each infrastructure component, use the following template:
+
+---
+
+#### Section 1: Overview
+- One sentence: what it is and why it's used
+- ASCII diagram: how the component connects to the rest of the system
+
+#### Section 2: Architecture / Components
+If the component has multiple parts (e.g., Grafana stack = Tempo + Loki + Mimir + Alloy):
+- For each part: role, configuration file, endpoints (ports)
+
+If the component is standalone (e.g., Redis):
+- Usage diagram (which services connect, what data they store)
+
+#### Section 3: Use Cases (for general-purpose components like Redis)
+Table:
+| Use Case | Key Pattern | TTL | Purpose |
+|----------|-------------|-----|---------|
+
+#### Section 4: File Structure
+```
+path/to/adapter/
+├── file1.go    # Description
+├── file2.go    # Description
+└── ...
+```
+
+#### Section 5: Interfaces
+Interface definitions from the code (contracts.go, interfaces, etc.).
+Show the full interface code.
+
+#### Section 6: Implementation Details
+
+For each use case / method:
+- Name
+- Usage example (code)
+- Configuration
+- Key parameters (TTL, retry policy, etc.)
+
+**Type-specific sections:**
+
+**For Observability (OBSERVABILITY.md):**
+- Backend Integration: how tracing/metrics are initialized in code
+- Instrumentation Layers: table (Layer | Package | Technology | Span Names)
+- Trace-Log Correlation: how trace_id gets into logs
+- Span Hierarchy Example: span tree for a typical request
+- Grafana / Dashboard access and key queries
+
+**For Cache/Redis (REDIS.md):**
+- Generic Cache API (Set/Get/Del)
+- Session Storage: keys, TTL, format
+- Cache-Aside / Read-Through pattern
+- Invalidation strategy
+- Algorithm (for leader election and similar): steps + Lua scripts
+
+**For Reverse Proxy (TRAEFIK.md / NGINX.md):**
+- Service URLs table
+- How to customize (prefixes, domains)
+- Configuration (labels, config files)
+- Ports exposed to host
+- Troubleshooting
+
+**For Message Queues (QUEUES.md / KAFKA.md):**
+- Topics / Exchanges / Subjects
+- Producer / Consumer pattern
+- Retry / DLQ policy
+- Serialization format
+
+**For Leader Election (LEADER_ELECTION.md):**
+- Algorithm (SETNX, Consul, etcd)
+- Failover scenarios
+- Heartbeat mechanism
+- Parameters table (TTL, heartbeat interval, namespace)
+
+#### Section 7: Configuration
+
+Docker Compose fragment:
+```yaml
+service_name:
+  image: ...
+  ports: ...
+  environment: ...
+  volumes: ...
+```
+
+Application config (config.yml / .env):
+```yaml
+component:
+  url: "..."
+  option: "..."
+```
+
+#### Section 8: Testing
+- How the component is tested (integration tests, test containers)
+- Test example
+
+#### Section 9: Observability (for non-tracing components)
+- How the component is traced (redisotel, otelhttp, etc.)
+- Health check
+
+#### Section 10: Verification Commands
+```bash
+# Check connection
+docker exec container_name ...
+# View data
+...
+# Monitoring
+...
+```
+
+#### Section 11: Key Files
+Table:
+| File | Description |
+|------|-------------|
+
+## General Rules
+
+- Create a separate file for each significant infrastructure component
+- If a component is trivial (1 config, no code) — do not create a separate file, mention it in `ARCHITECTURE.md`
+- All code examples and configs — from the actual project
+- Docker Compose fragments — from the actual `docker-compose.yml`
+- After creating files, update `.spec/README.md`: add links under the Infrastructure section
+- If no infrastructure components are found, do not generate any files — skip this template entirely
diff --git a/.agents/skills/sdd/templates/docs/routing.md b/.agents/skills/sdd/templates/docs/routing.md
new file mode 100644
index 0000000..614214c
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/routing.md
@@ -0,0 +1,198 @@
+<!-- scope: **/routes/*, **/router/*, **/pages/*, **/screens/*, **/navigation/* -->
+# Routing Documentation Template
+
+## What This Generates
+
+- `.spec/ROUTING.md` — route definitions, guards, layouts, navigation patterns, SSR/SSG strategy
+
+## Instructions
+
+You are a technical documentarian. Create routing and navigation documentation for the project in the `.spec/` directory.
+Analyze: router configuration, route definitions, page/screen components, navigation guards/middleware, layout wrappers, and deep link configuration.
+
+### Step 1: Identify Routing Framework
+
+Check for the presence of:
+- **React**: React Router, TanStack Router, Next.js App Router / Pages Router, Remix, Wouter
+- **Vue**: Vue Router, Nuxt routing (file-based)
+- **Angular**: Angular Router (@angular/router)
+- **Svelte**: SvelteKit file-based routing
+- **Flutter/Dart**: GoRouter, Navigator 2.0, auto_route, Beamer
+- **React Native**: React Navigation, Expo Router
+- **Solid**: Solid Router, SolidStart file-based routing
+
+Determine from imports, configuration files, and directory structure (file-based routing uses `pages/`, `app/`, `routes/`).
+
+### Step 2: Create .spec/ROUTING.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: routing framework and approach
+- Routing type: code-based, file-based, or hybrid
+- Rendering strategy: CSR, SSR, SSG, ISR, or mixed
+- ASCII diagram of the route tree (high-level):
+
+```
+/
+├── / (home)                    [public]
+├── /auth
+│   ├── /login                  [public]
+│   └── /register               [public]
+├── /dashboard                  [auth required]
+│   ├── /settings               [auth required]
+│   └── /profile                [auth required]
+├── /admin/*                    [admin role]
+└── /api/* (API routes)         [server only]
+```
+
+##### 2. Route Table
+
+Complete table of all routes:
+
+| Path | Component / Page | Auth | Roles | Layout | Method | Notes |
+|------|-----------------|------|-------|--------|--------|-------|
+| `/` | `HomePage` | No | — | `MainLayout` | GET | Landing page |
+| `/login` | `LoginPage` | No | — | `AuthLayout` | GET | Redirects if authenticated |
+| `/dashboard` | `DashboardPage` | Yes | `user` | `DashboardLayout` | GET | — |
+| `/admin/users` | `AdminUsersPage` | Yes | `admin` | `AdminLayout` | GET | — |
+| `/api/users` | — | Yes | — | — | GET, POST | API route (server only) |
+
+Extract from actual router configuration, file-based route directories, or route decorators.
+
+##### 3. Route Parameters & Query Strings
+
+| Route Pattern | Param | Type | Validation | Example |
+|--------------|-------|------|------------|---------|
+| `/users/:id` | `id` | UUID | Regex / Zod | `/users/abc-123` |
+| `/posts/:slug` | `slug` | string | — | `/posts/hello-world` |
+| `/search?q=` | `q` | string | URL encoded | `/search?q=hello` |
+
+Document how params are parsed and validated (middleware, loader, schema).
+
+##### 4. Guards / Middleware / Interceptors
+
+Navigation guards that run before route access:
+
+| Guard | Applied To | Check | On Failure |
+|-------|-----------|-------|------------|
+| `authGuard` | `/dashboard/*`, `/admin/*` | Token exists and valid | Redirect to `/login` |
+| `roleGuard` | `/admin/*` | User has `admin` role | Redirect to `/403` |
+| `onboardingGuard` | `/dashboard/*` | Profile is complete | Redirect to `/onboarding` |
+
+For each guard:
+- **Location**: file path
+- **Execution order**: in what order do guards run
+- **How applied**: route meta, middleware chain, HOC wrapper, per-route config
+
+Code example of a typical guard from the project.
+
+##### 5. Layouts & Nesting
+
+Layout hierarchy:
+
+```
+RootLayout (html, body, providers)
+├── MainLayout (header, footer, nav)
+│   ├── HomePage
+│   └── AboutPage
+├── AuthLayout (centered card, no nav)
+│   ├── LoginPage
+│   └── RegisterPage
+├── DashboardLayout (sidebar, topbar)
+│   ├── DashboardPage
+│   └── SettingsPage
+└── AdminLayout (admin sidebar)
+    └── AdminPages
+```
+
+For each layout:
+- **Location**: file path
+- **Provides**: what UI chrome it adds (header, sidebar, footer)
+- **Context / Providers**: what data it fetches or provides to children (user, theme, permissions)
+
+##### 6. Data Loading
+
+How data is loaded for routes:
+
+| Pattern | Framework Feature | When |
+|---------|-------------------|------|
+| Server loader | `loader()` (Remix), `getServerSideProps` (Next), `load()` (SvelteKit) | Before render, server-side |
+| Client fetch | `useEffect`, `onMounted`, `initState` | After mount, client-side |
+| Suspense / streaming | React Suspense, deferred data | Progressive loading |
+| Static generation | `getStaticProps`, `prerender` | Build time |
+
+For each significant route, document:
+- What data is loaded and from where (API endpoint, database, cache)
+- Loading state handling (skeleton, spinner, placeholder)
+- Error state handling (error boundary, fallback component)
+
+##### 7. Navigation Patterns
+
+How navigation is triggered:
+
+| Pattern | Implementation | Example |
+|---------|---------------|---------|
+| Declarative link | `<Link to="/about">` | Menu items, breadcrumbs |
+| Programmatic | `router.push("/dashboard")` | After form submit, auth redirect |
+| Back / history | `router.back()`, `history.back()` | Cancel buttons |
+| Replace (no history entry) | `router.replace("/login")` | Auth redirects |
+| External | `window.open(url)` | Third-party links |
+
+##### 8. Deep Links & Universal Links (Mobile / PWA)
+
+If the project supports deep linking:
+- URL scheme: `myapp://path` or `https://myapp.com/path`
+- Configuration file: `AndroidManifest.xml`, `Info.plist`, `apple-app-site-association`, `assetlinks.json`
+- Route-to-screen mapping
+- Deferred deep links (install → open at correct screen)
+- Testing: how to test deep links locally
+
+If not applicable, skip this section.
+
+##### 9. Error & Special Routes
+
+| Route | Purpose | Component |
+|-------|---------|-----------|
+| `404` / `*` | Not found | `NotFoundPage` |
+| `403` | Forbidden | `ForbiddenPage` |
+| `500` | Server error | `ErrorPage` |
+| `/maintenance` | Maintenance mode | `MaintenancePage` |
+
+How errors are caught: error boundaries, `errorElement` (React Router), `+error.svelte`, `error.tsx`.
+
+##### 10. SEO & Metadata
+
+- How page titles and meta descriptions are set per route (Head component, `generateMetadata`, `useMeta`)
+- Open Graph / social sharing meta tags
+- Canonical URLs
+- Sitemap generation (static, dynamic, `sitemap.xml`)
+- `robots.txt` configuration
+
+##### 11. Route Testing
+
+- How routes are tested (navigation tests, guard tests, loader tests)
+- Testing framework and utilities (Testing Library, Playwright, Cypress)
+- How to test protected routes (mock auth, test tokens)
+- Code example from the project
+
+##### 12. Adding a New Route
+
+Step-by-step guide:
+1. Create page/screen component
+2. Add route definition (config entry or file in `pages/`)
+3. Apply guard/middleware if needed
+4. Assign layout
+5. Add data loader (if SSR/SSG)
+6. Set page metadata (title, description)
+7. Add to navigation (menu, breadcrumbs)
+8. Write tests
+
+## General Rules
+
+- Language: English
+- All routes, guards, and layouts must come from actual source code — do not invent
+- If the project uses file-based routing, document the directory structure as the primary route definition source
+- For API-only projects (no pages/screens), do not generate this file — skip entirely
+- For Flutter/Dart, adapt terminology: Screen instead of Page, Navigator/GoRouter instead of React Router
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/docs/security.md b/.agents/skills/sdd/templates/docs/security.md
new file mode 100644
index 0000000..6b93b0d
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/security.md
@@ -0,0 +1,209 @@
+<!-- scope: **/*security*, **/*crypto*, **/*cert* -->
+# Security Documentation Template
+
+## What This Generates
+
+- `.spec/SECURITY.md` — security model, threat boundaries, input validation, secrets management, and OWASP Top 10 mapping
+
+## Instructions
+
+You are a technical documentarian with a security focus. Create security documentation for the project in the `.spec/` directory.
+Analyze: input validation logic, authentication/authorization middleware, CORS/CSP config, rate limiting, TLS setup, secrets handling, dependency manifests, security headers.
+
+**Important**: This template focuses on the **security perspective** of the project. It cross-references `AUTH.md` (if it exists) for detailed auth flows and `DEPLOYMENT.md` for infrastructure security, but does not duplicate them. Instead, it audits and evaluates security posture.
+
+### Step 1: Identify Security Surface
+
+Map the project's security surface:
+- **Entry points**: HTTP endpoints, gRPC services, WebSocket handlers, CLI commands, message consumers
+- **Trust boundaries**: external → API gateway → backend → database, user input → validation → business logic
+- **Sensitive data**: PII fields, credentials, tokens, financial data
+- **Third-party integrations**: OAuth providers, payment systems, external APIs
+
+### Step 2: Create .spec/SECURITY.md
+
+#### Structure:
+
+##### 1. Security Overview
+
+High-level security posture:
+- One sentence: security model summary (e.g., "Token-based auth with RBAC, TLS everywhere, secrets in Vault")
+- Trust boundary diagram (ASCII):
+```
+┌─────────────────────────────────────────────┐
+│  External (untrusted)                        │
+│  ┌─────────┐    ┌──────────┐                │
+│  │ Browser │    │ Mobile   │                │
+│  └────┬────┘    └────┬─────┘                │
+│       └──────┬───────┘                       │
+├──────────────┼───────────────────────────────┤
+│  DMZ         │                               │
+│  ┌───────────▼──────────┐                   │
+│  │  Reverse Proxy / LB  │                   │
+│  └───────────┬──────────┘                   │
+├──────────────┼───────────────────────────────┤
+│  Internal (trusted)                          │
+│  ┌───────────▼──────────┐  ┌─────────────┐ │
+│  │  Application Server  │──│  Database    │ │
+│  └──────────────────────┘  └─────────────┘ │
+└─────────────────────────────────────────────┘
+```
+- List of security-critical components with file references
+
+##### 2. Input Validation
+
+Input sanitization strategy:
+- **Validation layer**: where validation happens (handler, middleware, domain, or all)
+- **Validation approach**: struct tags, validation library, manual checks
+- **Injection prevention**:
+  - SQL injection: parameterized queries? ORM? raw SQL audit
+  - XSS: output encoding, template escaping, CSP
+  - Command injection: any `exec` / `os.Command` usage? input sanitization
+  - Path traversal: file path validation
+- **Validation rules**: table of key validated inputs:
+
+| Input | Location | Validation | Sanitization |
+|-------|----------|------------|--------------|
+| email | POST /users | format, length | lowercase, trim |
+| file upload | POST /files | size, mime type | rename, virus scan |
+
+Code reference: file path where validation is implemented.
+
+##### 3. Authentication & Authorization Audit
+
+Security-focused review of auth (cross-references `AUTH.md` if it exists):
+- **Authentication strength**: password policy (min length, complexity), brute force protection (rate limit, lockout)
+- **Token security**: token type, signing algorithm, expiry times, rotation policy
+- **Session security**: HttpOnly cookies, Secure flag, SameSite, session fixation prevention
+- **Privilege escalation prevention**: horizontal (user A accessing user B's data) and vertical (user → admin)
+- **Known weaknesses or TODOs**: any `// TODO: security` comments, missing auth checks
+
+If `AUTH.md` exists, reference it for flow details and focus here on security audit findings.
+
+##### 4. Transport Security
+
+TLS and network security:
+- **TLS configuration**: version (1.2/1.3), cipher suites, certificate source (Let's Encrypt, self-signed, CA)
+- **Internal communication**: mTLS between services? plain HTTP internally?
+- **Certificate management**: how certificates are provisioned and rotated
+- **Redirect policy**: HTTP → HTTPS redirect enforced?
+
+Code/config reference for TLS setup.
+
+##### 5. CORS & CSP
+
+Cross-origin and content security policies:
+- **CORS configuration**:
+  - Allowed origins (exact list or pattern)
+  - Allowed methods and headers
+  - Credentials policy
+  - Preflight cache duration
+  - Code reference: where CORS is configured
+- **Content Security Policy** (if applicable):
+  - CSP directives (script-src, style-src, connect-src, etc.)
+  - Report-only vs enforced
+  - Where CSP header is set
+
+##### 6. Rate Limiting & Abuse Prevention
+
+- **Rate limits**: table of limits per endpoint or operation:
+
+| Scope | Limit | Window | Action |
+|-------|-------|--------|--------|
+| Login | 5 req | 1 min | 429 + lockout |
+| API global | 100 req | 1 min | 429 |
+| File upload | 10 req | 1 hour | 429 |
+
+- **Rate limit implementation**: middleware, reverse proxy, cloud WAF
+- **Headers returned**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`
+- **DDoS mitigation**: Cloudflare, AWS Shield, or application-level measures
+- **Bot protection**: CAPTCHA, proof-of-work, behavioral analysis
+
+##### 7. Secrets Management (audit only)
+
+> Operational details (inventory, storage, rotation, local dev) are owned by `deployment.md` → `DEPLOYMENT.md §8 Secrets`.
+> This section focuses on **security audit**: anti-patterns, gaps, and recommendations.
+
+- **Anti-patterns to flag**: secrets in code, secrets in git history, secrets in logs, unencrypted config files
+- **Gaps**: any secrets without rotation, any secrets accessible beyond need-to-know
+- **Recommendations**: concrete next steps to improve secrets hygiene
+
+##### 8. Data Protection
+
+Data handling and privacy:
+- **Encryption at rest**: database encryption, file storage encryption
+- **Encryption in transit**: TLS (see §4)
+- **PII handling**: which fields are PII, how they are stored, access controls
+- **Data retention**: retention periods, deletion policy, right to erasure
+- **Backup encryption**: are backups encrypted?
+- **Compliance**: GDPR, HIPAA, SOC2, PCI-DSS — which apply and how addressed
+
+If no compliance requirements exist, note that and skip the compliance subsection.
+
+##### 9. Security Headers
+
+HTTP security headers:
+
+| Header | Value | Purpose |
+|--------|-------|---------|
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` | Force HTTPS |
+| `X-Content-Type-Options` | `nosniff` | Prevent MIME sniffing |
+| `X-Frame-Options` | `DENY` | Prevent clickjacking |
+| `X-XSS-Protection` | `0` | Disable legacy XSS filter |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` | Control referrer |
+| `Permissions-Policy` | `camera=(), microphone=()` | Restrict browser features |
+
+Identify which headers are set and which are missing. Note where they are configured.
+
+##### 10. Dependency Security
+
+Third-party dependency audit:
+- **Audit tool**: `npm audit`, `govulncheck`, `pip-audit`, `cargo audit`, Snyk, Dependabot
+- **Audit command**: how to run a vulnerability scan
+- **Update policy**: how often dependencies are updated, who reviews
+- **Known vulnerabilities**: any current advisories (from the latest audit)
+- **Lock file**: is a lock file committed (`go.sum`, `package-lock.json`, `poetry.lock`)?
+- **Supply chain**: pinned versions, integrity hashes, trusted registries
+
+##### 11. OWASP Top 10 Mapping
+
+Map each OWASP Top 10 (2021) category to the project's mitigations:
+
+| # | OWASP Category | Project Mitigation | Status |
+|---|----------------|-------------------|--------|
+| A01 | Broken Access Control | RBAC middleware, ownership checks | ✅ Mitigated |
+| A02 | Cryptographic Failures | TLS 1.3, bcrypt passwords, JWT RS256 | ✅ Mitigated |
+| A03 | Injection | Parameterized queries, input validation | ✅ Mitigated |
+| A04 | Insecure Design | Threat modeling, code review | ⚠️ Partial |
+| A05 | Security Misconfiguration | Hardened defaults, no debug in prod | ✅ Mitigated |
+| A06 | Vulnerable Components | Dependabot, weekly audit | ✅ Mitigated |
+| A07 | Auth Failures | Rate limiting, MFA, strong passwords | ⚠️ Partial |
+| A08 | Data Integrity Failures | Signed deployments, CI/CD gates | ✅ Mitigated |
+| A09 | Logging & Monitoring | Structured logging, alerting | ⚠️ Partial |
+| A10 | SSRF | No user-controlled URLs / URL allowlist | ✅ Mitigated |
+
+Statuses: ✅ Mitigated, ⚠️ Partial, ❌ Not Addressed, N/A
+
+For each "Partial" or "Not Addressed": note what's missing and recommend next steps.
+
+##### 12. Incident Response (if applicable)
+
+If the project has incident response procedures or documentation:
+- **Detection**: how security incidents are detected (alerts, logs, user reports)
+- **Containment**: immediate steps (revoke tokens, block IPs, disable accounts)
+- **Communication**: who to notify, disclosure timeline
+- **Recovery**: restore from backup, re-deploy, rotate secrets
+- **Post-mortem**: how lessons learned are documented
+
+If no incident response exists, note this as a gap and suggest creating one.
+
+## General Rules
+
+- Language: English
+- This is a **security audit** template — focus on findings, gaps, and recommendations
+- Cross-reference `AUTH.md` for detailed auth flows, `DEPLOYMENT.md` for infra security — do not duplicate
+- All code references must point to actual project files
+- Never include real secrets, tokens, keys, or internal URLs — use placeholders
+- Flag security anti-patterns explicitly (e.g., "⚠️ JWT secret is hardcoded in config file")
+- If a section is not applicable (e.g., no CORS because no browser clients), state "N/A — [reason]" and skip
+- After creating, update `.spec/README.md`: add a link under the Security section
diff --git a/.agents/skills/sdd/templates/docs/state-management.md b/.agents/skills/sdd/templates/docs/state-management.md
new file mode 100644
index 0000000..4b3be82
--- /dev/null
+++ b/.agents/skills/sdd/templates/docs/state-management.md
@@ -0,0 +1,151 @@
+<!-- scope: **/store/*, **/stores/*, **/state/*, **/redux/*, **/bloc/*, **/providers/* -->
+# State Management Documentation Template
+
+## What This Generates
+
+- `.spec/STATE.md` — state management architecture, store structure, data flow, side effects
+
+## Instructions
+
+You are a technical documentarian. Create state management documentation for the project in the `.spec/` directory.
+Analyze: store definitions, reducers, actions, selectors, providers, BLoC classes, signals, and reactive state primitives.
+
+### Step 1: Identify State Management Approach
+
+Check for the presence of:
+- **React**: Redux (Toolkit), Zustand, MobX, Jotai, Recoil, Valtio, XState, React Context + useReducer
+- **Vue**: Pinia, Vuex
+- **Angular**: NgRx, Akita, Elf, simple services with RxJS
+- **Svelte**: Svelte stores (writable, readable, derived)
+- **Solid**: Solid signals, createStore
+- **Flutter/Dart**: BLoC, Provider, Riverpod, GetX, MobX
+- **Mobile (RN)**: Redux, Zustand, MobX-State-Tree
+
+Determine from `package.json`, `pubspec.yaml`, imports in source files.
+
+### Step 2: Create .spec/STATE.md
+
+#### Structure:
+
+##### 1. Overview
+- One sentence: which state management solution and why
+- Architecture pattern name (Flux, CQRS, reactive, signal-based)
+- ASCII diagram of the data flow:
+
+```
+User Action → Dispatch → Store/Reducer → New State → UI Re-render
+                           ↓
+                      Side Effects (API calls, persistence)
+```
+
+Adapt the diagram to the actual pattern used (BLoC: Event → Bloc → State → Widget; Signals: Signal → Effect → Derived).
+
+##### 2. Store Structure
+
+Map of all stores / slices / blocs / atoms:
+
+| Store / Slice | Location | Purpose | Persistence |
+|---------------|----------|---------|-------------|
+| `authStore` | `src/stores/auth.ts` | User session, tokens | localStorage |
+| `cartSlice` | `src/store/cart.ts` | Shopping cart items | None (memory) |
+
+For each store, note whether it is:
+- **Global** (app-wide singleton)
+- **Scoped** (per-route, per-component tree, per-feature)
+- **Local** (component-level, not shared)
+
+##### 3. State Shape
+
+For each significant store, document the state type/interface:
+
+```typescript
+// authStore state
+interface AuthState {
+  user: User | null;       // Current authenticated user
+  token: string | null;    // JWT access token
+  isLoading: boolean;      // Auth operation in progress
+  error: string | null;    // Last auth error message
+}
+```
+
+Use the project's actual language and type definitions. Include initial/default values.
+
+##### 4. Actions / Events / Mutations
+
+For each store, list the actions that modify state:
+
+| Action / Event | Payload | Effect on State | Side Effects |
+|----------------|---------|-----------------|--------------|
+| `login` | `{email, password}` | Sets `isLoading: true` | API call to `/auth/login` |
+| `loginSuccess` | `{user, token}` | Sets `user`, `token`, `isLoading: false` | Persists token |
+| `logout` | — | Clears `user`, `token` | Removes token from storage |
+
+##### 5. Selectors / Derived State / Computed
+
+| Selector / Computed | Source | Returns | Used By |
+|---------------------|--------|---------|---------|
+| `isAuthenticated` | `authStore` | `boolean` | `ProtectedRoute`, `Header` |
+| `cartTotal` | `cartStore` | `number` | `CartSummary`, `Checkout` |
+
+##### 6. Side Effects
+
+How async operations and side effects are handled:
+- **Pattern**: thunks, sagas, epics, effects, listeners, BLoC events, async actions
+- **API integration**: how API calls are dispatched and results handled
+- **Error handling**: how API errors flow back to state
+- **Optimistic updates**: are they used? Where?
+- **Cancellation**: how in-flight requests are cancelled (e.g., route change, unmount)
+
+Code example of a typical side effect from the project.
+
+##### 7. Persistence
+
+Which parts of state are persisted and how:
+
+| Store | Medium | Key | Serialization | Hydration |
+|-------|--------|-----|---------------|-----------|
+| `auth` | localStorage | `auth_token` | JSON | On app init |
+| `settings` | AsyncStorage | `user_prefs` | JSON | On app init |
+| `cart` | sessionStorage | `cart_items` | JSON | On tab restore |
+
+If no persistence is used, state it explicitly.
+
+##### 8. Subscriptions / Reactivity
+
+How components subscribe to state changes:
+- **React**: `useSelector`, `useStore`, `useSnapshot`, custom hooks
+- **Vue**: `storeToRefs`, computed properties
+- **Flutter**: `BlocBuilder`, `Consumer`, `Watch`
+- **Svelte**: `$store` auto-subscription
+
+Performance considerations:
+- Selector memoization
+- Render optimization (shallow compare, structural sharing)
+- Common pitfalls in the project
+
+##### 9. Testing State
+
+- How stores/slices/blocs are unit tested
+- How to create test state (factories, fixtures, initial state overrides)
+- How to mock stores in component tests
+- Code example of a store test from the project
+
+##### 10. Adding a New Store
+
+Step-by-step guide for adding a new store/slice/bloc:
+1. Create the state type
+2. Define actions/events
+3. Implement reducer/handler
+4. Add selectors
+5. Connect to components
+6. Add tests
+
+Reference existing stores as examples.
+
+## General Rules
+
+- Language: English
+- All state shapes, actions, and selectors must come from actual source code
+- If the project uses multiple state management solutions (e.g., Redux for global + useState for local), document all of them and explain the boundary
+- If the project has no state management beyond component-local state, do not generate this file — skip entirely
+- After creating, update `.spec/README.md`: add a link under the appropriate section
diff --git a/.agents/skills/sdd/templates/explore.md b/.agents/skills/sdd/templates/explore.md
new file mode 100644
index 0000000..97ac82d
--- /dev/null
+++ b/.agents/skills/sdd/templates/explore.md
@@ -0,0 +1,212 @@
+# Phase 1: Exploration
+
+## Role
+
+You are a **Research Partner**. Your task: investigate the problem space, analyze the existing codebase, compare approaches, and help the user clarify what they actually need before committing to formal requirements.
+
+You do **NOT** write requirements documents.
+You do **NOT** design solutions or write code.
+You **explore**: ask questions, read code, compare options, surface constraints and risks.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.explore`
+- **Input artifacts:** none (this is the first phase)
+- **Output:** `.spec/features/<feature-name>/explore.md`
+
+---
+
+### Fast-track mode
+
+When the user describes a bug with a known reproduction or a small scoped change:
+
+- **Intent:** 1 paragraph (not 3–5). State the problem and the expected fix direction.
+- **Investigation (Root Cause):** confirm the bug exists AND identify root cause. Follow these steps:
+  1. **Read errors** — read the full stack trace / error log, not just the last line. Note the originating call site.
+  2. **Reproduce** — run the failing test or command yourself. Capture actual output.
+  3. **Check recent changes** — `git log --oneline -10 <affected-files>` (if git is available). Look for the commit that introduced the regression.
+  4. **Trace data flow** — follow the data path from input → processing → failure point. Cite each file and line in the chain.
+  
+  If root cause remains unclear after these steps, mark it as `[ROOT CAUSE: unknown]` and include it in Open Questions. Do NOT skip to a fix direction based on symptoms alone.
+- **Options:** single recommended approach. Skip multi-option comparison unless two genuinely different strategies exist.
+- **Scope boundaries:** list only must-have (v1). Omit deferred/spike unless the user raised them.
+- **Assumptions:** 2–3 critical assumptions max.
+- **Open questions:** omit if none. Do not fabricate questions.
+- **Build Tooling:** still required (later phases depend on it).
+
+Target artifact size: **≤ 1 page**.
+
+IMPORTANT: For bug fixes, DO NOT propose a fix direction in "Recommended Direction" until root cause is identified. A symptom-level recommendation ("the error is on line 42, let's fix it") without understanding WHY it fails leads to patches that mask the real problem.
+
+---
+
+## Language
+
+Write the entire exploration document in the **user's language** (detected from their first message). This includes:
+- Section headers (e.g., translate "Intent", "Investigation", "Options Considered", etc.)
+- All prose: problem descriptions, findings, trade-off analysis, recommendations
+- Scope boundary labels (translate "Must-have (v1)", "Deferred (v2)", "Needs spike")
+- Assumption tags: keep the marker format `[ASSUMPTION: ...]` but write the assumption text in the user's language
+
+Keep in English (do not translate):
+- Code identifiers, file paths, import paths
+- Shell commands and their output
+- Build Tooling commands (the command values — labels like "Orchestrator", "Test", "Build" may be translated)
+
+---
+
+## What To Do
+
+### Step 1: Understand Intent
+
+Ask the user:
+- What problem are they trying to solve?
+- What triggered this — a bug report, user feedback, tech debt, new feature request?
+- Is this new functionality (greenfield) or modifying existing behavior (brownfield)?
+- Is there prior art or inspiration (other tools, competitors, RFCs)?
+
+### Step 2: Investigate the Codebase
+
+Without waiting for all answers:
+
+**Project documentation shortcut:** If the project documentation directory exists (default: `.spec/`, configurable via `docs_dir` in `config.yaml`), read `README.md` first for the documentation map, then read relevant docs (`ARCHITECTURE.md`, `PACKAGES.md`, `DOMAIN.md`) before scanning source code. This provides pre-verified context and significantly reduces file-read budget consumption. If docs exist, you may need fewer than 20 raw file reads.
+
+> **Directory reminder:** You READ project documentation from `<docs_dir>/` (default: `.spec/`). You WRITE phase artifacts to `.spec/features/<feature>/`. These are separate directories — do not mix them.
+
+- Read relevant source code, configs, and tests
+- Identify existing patterns, conventions, and constraints
+
+**Budget:** Limit initial investigation to ~20 file reads. If the codebase is large and you haven't found enough context, summarize what you've learned so far and ask the user which areas to investigate deeper. This prevents context window exhaustion.
+- Find related functionality that might be affected
+- Note technical debt or risks in the affected area
+
+**If modifying existing code (brownfield):**
+- What behavior must NOT change? Identify preservation constraints.
+- What tests cover current behavior? These must keep passing.
+- What's the migration path if data structures change?
+
+**If building new (greenfield):**
+- What similar patterns already exist in the codebase? Follow them.
+- Are there shared abstractions (interfaces, base classes) to reuse?
+
+**Testing patterns (brownfield and greenfield):**
+- Identify the project's testing framework and assertion library.
+- Where do test files live? What naming convention is used?
+- Note representative test files for later phases to follow as style references.
+
+**Build tooling discovery (brownfield and greenfield):**
+- Identify the project's command orchestrator: check for `Makefile`, `Taskfile.yml` (`taskfile.yml`), `package.json` scripts section, `Justfile`, or similar.
+- Extract key commands for: **test**, **build**, **lint**, **generate** (code generation), **start**, **stop**.
+- If a `Makefile` or `Taskfile` exists, read it and list the relevant targets.
+- If `package.json` exists, read the `scripts` section.
+- Note code generation commands (proto, OpenAPI, mocks, ORM generators) — these must run before tests.
+- Document the orchestrator and commands in the exploration output (see Build Tooling section in Output Format).
+
+### Step 3: Compare Approaches
+
+If multiple solutions exist:
+- List 2–4 realistic options
+- For each: brief description, pros, cons, estimated complexity
+- Highlight trade-offs explicitly (e.g., "simpler but less extensible")
+
+### Step 4: Surface Constraints
+
+Proactively identify:
+- Breaking changes or backward compatibility concerns
+- Performance implications
+- Security considerations
+- Dependencies that would be added or affected
+- Edge cases that aren't obvious
+
+### Step 5: Recommend Direction
+
+Based on investigation, suggest:
+- Which approach seems best and why
+- What questions remain unanswered
+- **What assumptions your recommendation depends on** — list them explicitly and ask the user to confirm or correct before proceeding
+
+**Scope Boundaries** — explicitly categorize:
+- **Must-have (v1):** essential for the feature to be useful
+- **Deferred (v2):** valuable but not required for initial delivery
+- **Needs spike:** risky or unknown, requires investigation before committing
+
+---
+
+## Output Format
+
+Generate an exploration document with this structure:
+
+```markdown
+# Exploration: <Feature Name>
+
+## Intent
+What problem we're solving and why.
+
+## Investigation
+What was examined in the codebase. Key findings about existing code, patterns, constraints.
+
+## Root Cause
+<!-- Bug fixes only. Omit for pure features. -->
+Identified root cause of the defect: what is broken and why. Cite the originating file, line, and commit (if found).
+If unknown: `[ROOT CAUSE: unknown]` — explain what was investigated and why cause remains unclear.
+
+## Build Tooling
+- **Orchestrator:** make / task / npm scripts / custom scripts / none
+- **Test:** `<command>`
+- **Build:** `<command>`
+- **Lint:** `<command>`
+- **Generate:** `<command>` (if applicable — proto, mocks, ORM, etc.)
+- **Source:** Makefile / Taskfile.yml / package.json / CI config / ...
+
+## Options Considered
+### Option A: ...
+- Description, pros, cons, complexity.
+### Option B: ...
+- Description, pros, cons, complexity.
+
+## Constraints & Risks
+- Breaking changes, security, performance, dependencies.
+
+## Recommended Direction
+Which option and why.
+
+## Scope Boundaries
+- **Must-have (v1):** ...
+- **Deferred (v2):** ...
+- **Needs spike:** ...
+
+## Assumptions & Open Questions
+Explicit assumptions behind the recommendation. Open questions that need clarification before requirements.
+```
+
+---
+
+## Quality Checklist
+
+Before presenting to the user:
+- [ ] Codebase was actually read (not just guessed about)
+- [ ] At least 2 options were considered (unless truly only one path exists)
+- [ ] Trade-offs are explicit, not hidden
+- [ ] Scope boundaries are suggested
+- [ ] Assumptions behind the recommendation are stated explicitly
+- [ ] Open questions are listed (if any)
+- [ ] For bug fixes: root cause is identified and cited, or explicitly marked `[ROOT CAUSE: unknown]`
+- [ ] Build Tooling section is present with orchestrator and key commands (test, build, lint; generate if applicable)
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Codebase was actually read — file paths and findings are cited, not guessed.
+2. At least 2 options were compared (or a single-path justification is documented).
+3. Scope boundaries are explicitly categorized: **Must-have (v1)**, **Deferred (v2)**, **Needs spike**.
+4. Every assumption behind the recommendation is tagged with `[ASSUMPTION: ...]`.
+5. Open questions section is present (even if the answer is "None identified").
+6. For bug fixes: root cause is documented — either identified with file/line citation, or explicitly marked `[ROOT CAUSE: unknown]` with investigation summary.
+7. Build Tooling section is present — orchestrator identified, key commands (test, build, lint) documented.
+8. Artifact is registered via `pipeline.sh artifact <path>`.
+
+## Antipatterns
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Explore.
diff --git a/.agents/skills/sdd/templates/implementation.md b/.agents/skills/sdd/templates/implementation.md
new file mode 100644
index 0000000..078e19a
--- /dev/null
+++ b/.agents/skills/sdd/templates/implementation.md
@@ -0,0 +1,280 @@
+# Phase 5: Implementation
+
+> **For AI agents (Cursor, Claude Code, Windsurf, etc.):**
+> Read this file in full before starting. Follow every instruction exactly.
+> Your role is to execute the approved task plan — write tests, write code, run, iterate.
+
+---
+
+## Role
+
+You are a **TDD Implementation Executor**. Your task: take the approved task plan and execute it — write real tests, write real production code, run the suite, and iterate until everything is green.
+
+You do **NOT** create new tasks or modify the plan. You **execute** the tasks exactly as specified.
+You do **NOT** skip tasks. You do **NOT** reorder tasks (unless a dependency requires it and you document why).
+You **write code** and **run tests** for every task.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.implementation`
+- **Input artifacts:** read `history[0..3].artifact` (exploration, requirements, design, task plan). Read the **task plan** (`history[3]`) carefully — it defines the exact sequence of tasks to execute.
+- **Output:** `.spec/features/<feature-name>/implementation.md`
+
+---
+
+### Fast-track mode
+
+When the task plan contains 4–5 tasks for a small bug fix:
+
+- **Summary:** 1 paragraph (bug description + fix approach).
+- **Task Execution:** 1–2 lines per task — status and brief note only. Skip detailed iteration logs unless a task required retry.
+- **Final Verification:** still required — actual stdout from test, build, lint commands. No shortcuts here.
+- **Files Changed:** list of modified/created files (typically 1–3).
+
+Target artifact size: **≤ 0.5 page** (excluding stdout).
+
+---
+
+## Language
+
+Write the implementation report in the **user's language** (detected from their first message). This includes:
+- Section headers, task status descriptions, notes on issues found
+- Summary of what was done
+
+Keep in English (do not translate):
+- Code identifiers, file paths, shell commands
+- Test names, assertion messages
+- Task IDs: `T-N`
+- Instruction keywords: `CRITICAL`, `IMPORTANT`, `NOTE`, `DO NOT`, `GOAL`
+
+---
+
+## What To Do
+
+### Step 1: Read the Task Plan
+
+Read the approved task plan artifact. Extract:
+- **Commands** block — the exact commands for test, build, lint, generate
+- **Test Style Source** — the test style reference files
+- **Task list** — the ordered sequence of tasks (`T-1`, `T-2`, etc.)
+
+**Resume check:** Run `pipeline.sh status`. If `Last task` is shown (e.g., `T-4`), skip all tasks up to and including that task — they were completed in a previous session. Resume from the next task.
+
+### Step 1.5: Evaluate Execution Strategy
+
+After reading the task plan, decide whether to use **sequential mode** (default) or **subagent mode**.
+
+**Consider subagent mode when ALL three conditions are true:**
+1. The plan contains **6+ top-level tasks**
+2. At least one task has `Complexity: complex`
+3. Your platform supports **dispatching isolated subagents** (e.g., Claude Code `Task` tool, Cursor Composer, or equivalent)
+
+If any condition is not met — use sequential mode (Step 2 as-is). Sequential is always safe.
+
+**Subagent mode architecture:**
+
+You become a **controller**. For each task `T-N` in order:
+1. **Build a context package** — extract from the task plan:
+   - The single task `T-N` with all subtasks, `_Requirements_`, `_Preservation_`, `_Complexity_`
+   - Commands block and Test Style Source (copied verbatim)
+   - File paths referenced in subtasks
+   - One-line summary of each previously completed task (not full reports)
+2. **Dispatch a subagent** with this context package as input
+3. **Receive the subagent's report** — changed files, test stdout, any issues
+4. **Verify** — run the full test suite yourself. If tests fail, fix or escalate (same rules as Step 4)
+5. **Mark done** — `pipeline.sh task T-N`, update the implementation report
+
+**Subagent rules:**
+- One subagent per task — never bundle multiple `T-N` into one dispatch
+- Subagent does NOT interact with `pipeline.sh` — only the controller does
+- Task order remains strict (RED → GREEN → CODE → VERIFY → GATE) — parallelize only if tasks have zero shared files and no `_Preservation_` overlap
+- GATE task is always executed by the controller, never delegated
+- If a subagent fails after 3 attempts, apply the same rollback rules as Step 4
+
+NOTE: If you are unsure whether your platform supports subagents, use sequential mode. The output is identical — only the execution strategy differs.
+
+### Step 2: Execute Each Task
+
+For each task in order:
+
+#### 2.1 Exploration Tests (RED)
+
+If the task is an exploration test:
+1. Write the test exactly as described in the task
+2. Run the test command — confirm it **fails** (RED)
+3. If it passes instead of failing, the problem may already be fixed — note this and proceed
+4. Mark the task as done in the artifact (see Step 3)
+
+#### 2.2 Preservation Tests (GREEN)
+
+If the task is a preservation test:
+1. Write the test exactly as described in the task
+2. Run the test command — confirm it **passes** (GREEN)
+3. If it fails, there's a pre-existing bug — note this and ask the user before proceeding
+4. Mark the task as done in the artifact
+
+#### 2.3 Implementation Tasks (Code Changes)
+
+If the task is an implementation task:
+1. Read the task's `GOAL`, instructions, and `_Preservation_` list
+2. Make the minimal atomic change described
+3. Run the full test suite — confirm:
+   - The exploration test now **passes** (GREEN)
+   - All preservation tests still **pass** (GREEN)
+   - No other tests broke
+4. If tests fail, iterate:
+   - Diagnose the failure
+   - Adjust the implementation (not the tests, unless the test is wrong)
+   - Re-run until green
+5. Mark the task as done in the artifact
+
+#### 2.4 Re-test / Checkpoint Tasks
+
+If the task is a re-test or checkpoint:
+1. Run the specified commands
+2. Verify the expected outcome
+3. Mark the task as done in the artifact
+
+### Step 3: Mark Tasks Done
+
+After completing each task, update the implementation report artifact by marking the task as completed:
+
+```markdown
+- [x] **T-1** Exploration test: verify current behavior — RED confirmed
+- [x] **T-2** Preservation test: lock auth flow — GREEN confirmed
+- [x] **T-3** Implement token refresh — GREEN (all tests pass)
+- [ ] **T-4** Re-test full suite — (next)
+```
+
+**Rules for marking:**
+- Use `[x]` for completed tasks, `[ ]` for pending
+- Add a brief status note after the task title (e.g., "RED confirmed", "GREEN (3 tests pass)", "needed adjustment — see notes")
+- If a task required iteration (fix → re-run), note what was adjusted
+- After writing `[x]`, register in this order:
+  1. `sh ./scripts/pipeline.sh artifact` — saves the updated report
+  2. `sh ./scripts/pipeline.sh task T-N` — records last completed task for resume
+
+### Step 4: Handle Failures
+
+If a task cannot be completed:
+- **Test won't compile** — check imports, dependencies, code generation. Run `generate` command if available.
+- **Exploration test passes when it should fail** — the behavior may already be correct. Note it and proceed.
+- **Preservation test fails** — pre-existing bug. Note it and ask the user: "Preservation test T-N fails on existing code. This is a pre-existing issue. Proceed or fix first?"
+- **Implementation breaks other tests** — iterate on the implementation. Do NOT modify preservation tests.
+- **Blocked by dependency** — note the blocker, skip the task, continue with independent tasks. Return to blocked task when unblocked.
+
+#### Task rollback on repeated failure
+
+If an implementation task fails after **3 attempts** (3 iterations of adjust → re-run without reaching green):
+
+1. **Stop** — do not continue iterating.
+2. **Document** the situation in the implementation report:
+   - Task ID and title
+   - What was attempted (3 approaches tried)
+   - Which files were modified during attempts
+   - Current state: which tests pass, which fail
+3. **Present the user** with options:
+   - **(a) Revert this task's files** — `git checkout HEAD -- <file1> <file2> ...` to undo changes from the failed task only. Then continue with the next independent task.
+   - **(b) Debug together** — the user helps investigate the issue. Provide the failing test output and relevant code context.
+   - **(c) Full rollback** — `git checkout <review_base_commit> -- .` to restore the entire working tree to the state before implementation started. This undoes ALL tasks, not just the failed one.
+4. **Wait** for the user's decision before proceeding.
+
+CRITICAL: Do NOT silently leave the project in a broken state. If tests are failing after implementation attempts, the user must be informed and given control.
+
+### Step 5: Final Verification
+
+After all tasks are complete:
+1. Run the **full test suite** — all tests must pass
+2. Run the **build** command — must succeed
+3. Run the **lint** command — must pass (or only pre-existing warnings)
+4. Run **generate** command if applicable — ensure generated code is up to date
+5. Update the implementation report with final results
+
+---
+
+## Output Format
+
+Generate an implementation report with this structure:
+
+```markdown
+# Implementation Report: <Feature Name>
+
+## Summary
+Brief description of what was implemented. Number of tasks completed.
+
+## Commands Used
+- **Test:** `<command>`
+- **Build:** `<command>`
+- **Lint:** `<command>`
+- **Generate:** `<command>` (if applicable)
+
+## Task Execution
+
+- [x] **T-1** <task title> — <status>
+- [x] **T-2** <task title> — <status>
+- [x] **T-3** <task title> — <status>
+  - Note: <any adjustments or iteration notes>
+- [x] **T-4** <task title> — <status>
+...
+
+## Final Verification
+
+Include the actual (possibly truncated) stdout of each command below. Do NOT replace real output with status assertions like "All pass".
+
+```
+- **Tests:**
+\`\`\`
+<paste last 20 lines of test command output>
+\`\`\`
+- **Build:**
+\`\`\`
+<paste last 10 lines of build command output>
+\`\`\`
+- **Lint:**
+\`\`\`
+<paste last 10 lines of lint command output>
+\`\`\`
+- **Generate:** (if applicable)
+\`\`\`
+<paste last 10 lines of generate command output>
+\`\`\`
+```
+
+## Files Changed
+List of files created or modified during implementation.
+
+## Notes
+Any observations, pre-existing issues found, or deviations from the plan.
+```
+
+---
+
+## Quality Checklist
+
+Before presenting to the user:
+- [ ] Every task from the plan is marked (completed or explicitly skipped with reason)
+- [ ] All exploration tests confirmed RED before implementation
+- [ ] All preservation tests confirmed GREEN before and after implementation
+- [ ] Full test suite passes after all tasks
+- [ ] Build succeeds
+- [ ] Lint passes (or only pre-existing warnings)
+- [ ] Implementation report artifact is registered via `pipeline.sh artifact`
+- [ ] No tasks were silently skipped
+- [ ] Final Verification section contains actual command output (stdout), not just status assertions
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Every task from the approved plan is executed and marked in the artifact.
+2. Full test suite passes — zero new failures.
+3. Build command succeeds.
+4. Lint command passes (pre-existing warnings are acceptable, new ones are not).
+5. Implementation report lists all files changed.
+6. Artifact is registered via `pipeline.sh artifact`.
+7. Final Verification section contains real command output (stdout) for test, build, and lint.
+
+## Antipatterns
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Implementation.
diff --git a/.agents/skills/sdd/templates/reference/antipatterns.md b/.agents/skills/sdd/templates/reference/antipatterns.md
new file mode 100644
index 0000000..09f89cd
--- /dev/null
+++ b/.agents/skills/sdd/templates/reference/antipatterns.md
@@ -0,0 +1,103 @@
+# Antipatterns Reference
+
+Antipattern tables for each pipeline phase. Referenced from the corresponding phase template.
+
+---
+
+## Explore
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| Premature requirements | "WHEN token expires, system SHALL refresh" | "One option is to auto-refresh tokens" | WHEN/SHALL belongs in requirements phase |
+| Solution attachment | "We should use Redis" | "Option A: Redis, Option B: in-memory — trade-offs:..." | Must show alternatives before committing |
+| Ignoring existing code | "I suggest adding a new auth module" | "Existing `src/auth` uses X pattern; we can extend it" | Always read codebase first |
+| Scope creep | "We should also add rate limiting and logging" | "Rate limiting could be v2; focus on core auth first" | Help user narrow, not expand |
+| Analysis paralysis | 5 options with no recommendation | "Option B is best because...; A is fallback if..." | Recommend clearly when path is evident |
+| Symptom-level fix | "Bug confirmed at line 42, let's fix it" | "Root cause: `validate()` skips nil check added in commit abc123; line 42 fails because input is nil" | Without root cause, fix may mask the real problem |
+
+---
+
+## Requirements
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| Architectural solution | "Use a Redis cache for token storage" | "WHEN cache miss occurs, SHALL return fresh data within 100ms" | Prescribes HOW, not WHAT |
+| Code or pseudocode | `if token.expired { refresh() }` | "WHEN token is expired, SHALL attempt refresh" | Implementation detail |
+| Diagram | Mermaid sequence diagram | Prose description of the flow | Belongs in design phase |
+| Vague wording | "The system should handle errors gracefully" | "WHEN refresh fails, SHALL return 401 with error code" | Not verifiable |
+| Combined SHALLs | "…SHALL refresh the token and log the event" | Two REQs: one for refresh, one for logging | Must be one SHALL per REQ |
+| Unconfirmed requirement | Agent adds REQ-3.1 user never mentioned | Only requirements confirmed by user in interview | Hallucinated scope |
+| Technology lock-in | "Use JWT with RS256 signing" | "WHEN issuing tokens, SHALL use cryptographic signing" | Constrains design without user mandate |
+
+---
+
+## Design
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| Function bodies | `func refresh() { cache.Get(key)... }` | `func refresh(token Token) (Token, error)` | Interfaces show signatures only |
+| Task lists | "Step 1: create file, Step 2: add tests" | Architecture + interfaces + properties | This is design, not work breakdown |
+| Skipping unchanged files | "Files NOT Requiring Changes" table is empty | Explicitly list files in scope that won't change | Omission suggests scope not fully considered |
+| Existential properties | "There exists a case where refresh works" | "For all expired tokens, refresh returns valid token" | Properties must use universal quantifier |
+| Unlinked properties | "Property 3: tokens are secure" | "Property 3: ... Validates: REQ-1.2" | Every property must trace to a requirement |
+| Vague modification scope | `[MODIFIED]` — "various authentication changes" | `[MODIFIED]` — "adds refreshToken(), modifies authenticate() return type" | Must state what exactly changes |
+| Scope creep | Designing rate limiting not in requirements | Only design what requirements specify | Stay within approved requirements |
+| Silent assumption | Choosing a caching strategy without stating why | `[ASSUMPTION: write-through preferred]` — ask user or mark explicitly | Unstated beliefs cause surprises during implementation |
+| Ignoring existing test patterns | Agent invents new test structure (e.g., flat assertions) | Agent follows existing pattern: `auth/token_test.go:TestRefresh` uses table-driven subtests | Tests must be consistent with the project's existing style |
+
+---
+
+## Task Plan
+
+| Antipattern | Why it's harmful |
+|---|---|
+| Writing code in the plan | The plan is instructions for an agent, not the implementation itself |
+| Designing architecture in the plan | Architecture is fixed in the approved design document — do not revise it here |
+| Skipping exploration tests for bug fixes | Without a failing test, you cannot prove the bug existed or was fixed |
+| Tasks without `*_Requirements:_*` | Untraced tasks cannot be reviewed or rejected with precision |
+| Multi-file subtasks | Atomic subtasks are the unit of change — mixing files makes review and fixing harder |
+| Forgetting re-test tasks | A fix without a passing re-test is unverified |
+| Placing the checkpoint before all tasks complete | The checkpoint is a gate, not a milestone |
+| Vague task descriptions | "Update the code" is not a task. "Add null check to `parseToken` in auth module" is a task |
+| Inventing test style | When adjacent tests use table-driven subtests, do not write flat assertions. Follow existing project test patterns discovered in Test Infrastructure Discovery |
+
+---
+
+## Implementation
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| Skipping exploration test | Write code first, then test | Write test first (RED), then code (GREEN) | TDD requires RED→GREEN cycle |
+| Modifying preservation tests | Change test to match new code | Change code to satisfy both old and new tests | Preservation tests lock correct behavior |
+| Bulk implementation | Implement all tasks at once, test at the end | Implement one task, test, mark done, repeat | Atomic execution finds issues early |
+| Silent skip | Skip a failing task without noting it | Note the issue, ask user, document decision | Transparency over speed |
+| Plan modification | "This task doesn't make sense, I'll do it differently" | Execute as planned; note concerns for review phase | The plan was approved — execute it faithfully |
+| Silently leaving broken state | Continue to next task while tests are failing | Stop after 3 failed attempts, document state, ask user to decide | User must stay in control when implementation is stuck |
+| Unsupervised subagent | Dispatch subagent, accept its output without running tests | Dispatch subagent, then run full test suite yourself before marking task done | Subagent output must be verified — trust but verify |
+
+---
+
+## Review
+
+| Antipattern | Why it's harmful |
+|---|---|
+| Skipping the implementation report | The implementation report (history[4]) shows which tasks were completed — always verify against it |
+| Reviewing the entire codebase | Scope is limited to files changed since `review_base_commit` |
+| Approving with `major` findings open | Major findings must be resolved before `PASS` verdict |
+| Changing the design in the review | Design is locked in the approved design document — open a new pipeline for design changes |
+| Skipping the traceability matrix | Without it, requirements coverage cannot be verified |
+| Inventing requirements during review | Review checks against approved requirements only — new requirements need a new pipeline |
+| Flagging style preferences as `major` | Style preferences are `nit` at most; reserve `major` for real issues |
+| Auto-fixing without user direction | Review is for presenting findings to the user, not for autonomous code changes. Wait for explicit user instructions before modifying code |
+
+---
+
+## Documentation (Standalone Workflow)
+
+| Antipattern | WRONG ❌ | RIGHT ✓ | Why |
+|---|---|---|---|
+| All templates in one window | Generate `core.md` + `development.md` + `auth.md` + ... back-to-back in a single chat | Use `pipeline.sh docs-init` + queue; one template per iteration (sequential) or up to 3 parallel subagents | Single-chat batch generation exhausts context; agent starts hallucinating, dropping rules, and truncating output |
+| Sequential when subagent available | Loop `docs-next` / `docs-done` in one chat when your toolset has Task/Composer/dispatch tool | Use SUBAGENT mode — dispatch up to 3 templates in parallel; controller verifies metadata after each | Subagent dispatch isolates per-template context, prevents controller bloat, and parallelizes independent work |
+| Bundled subagent dispatch | "Subagent, generate `core.md`, `development.md`, and `auth.md`" | One subagent = one template; dispatch 3 separate subagents in parallel | Bundling defeats isolation; subagent context fills up the same way single-chat batch does |
+| Skipping metadata verification | Call `docs-done <template>` immediately after subagent reports success | After subagent finishes, controller verifies file exists, line 1 matches `<!-- generated: YYYY-MM-DD, template: <name>.md -->`, and file is non-trivial (≥ 50 lines) — only then `docs-done` | `docs-check` silently skips files with malformed metadata; missed verification = stale detection broken forever |
+| Running `init <feature>` for docs request | User says "обнови документацию" → agent runs `pipeline.sh init update-docs` | Run `pipeline.sh docs-init --update` (or `--all` for bootstrap) — the standalone workflow is independent from feature pipelines | Documentation generation does not need 6 phases, approval gates, or `.spec/features/<feature>/` — it is a separate state machine |
diff --git a/.agents/skills/sdd/templates/reference/correctness-properties-examples.md b/.agents/skills/sdd/templates/reference/correctness-properties-examples.md
new file mode 100644
index 0000000..421df84
--- /dev/null
+++ b/.agents/skills/sdd/templates/reference/correctness-properties-examples.md
@@ -0,0 +1,120 @@
+# Correctness Properties — Worked Examples
+
+Worked examples for each Correctness Property category. Referenced from `design.md` §2.6.
+
+Each example shows (1) a requirement, (2) the §2.6 property definition, (3) the §2.8 property-based test table entry, and (4) what the generator does.
+
+---
+
+## Equivalence
+
+Suppose REQ-1.1 says: *WHEN the system receives a valid token, it SHALL return the corresponding user profile.*
+
+**§2.6 definition:**
+
+```
+Property 1: Token-to-profile resolution
+Category: Equivalence
+Statement: For all valid tokens T issued for user U, resolveProfile(T) = profile(U)
+Validates: Requirements 1.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_token_resolves_to_owner_profile` | Property 1 | Generate random valid User, issue a token for that user, resolve profile via token | `Property/1` |
+
+The generator creates a random user, issues a token, and asserts that resolving the token returns the same user's profile. This verifies the equivalence property across many random inputs.
+
+---
+
+## Absence
+
+Suppose REQ-2.1 says: *WHEN processing a payment, the system SHALL never charge the user twice for the same order.*
+
+**§2.6 definition:**
+
+```
+Property 2: No duplicate charges
+Category: Absence
+Statement: For all orders O processed concurrently, chargeCount(O) = 1
+Validates: Requirements 2.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_no_duplicate_charges` | Property 2 | Generate random Order, simulate N concurrent payment attempts for that order, count successful charges | `Property/2` |
+
+The generator creates a random order, fires multiple concurrent payment requests, and asserts the total charge count is exactly 1. This verifies the absence of duplicate charges under concurrency.
+
+---
+
+## Round-trip
+
+Suppose REQ-3.1 says: *WHEN the system serializes a configuration, it SHALL be able to deserialize it back to an identical value.*
+
+**§2.6 definition:**
+
+```
+Property 3: Config serialization round-trip
+Category: Round-trip
+Statement: For all valid configurations C, deserialize(serialize(C)) = C
+Validates: Requirements 3.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_config_roundtrip` | Property 3 | Generate random valid Config with varied field types, serialize to storage format, deserialize back | `Property/3` |
+
+The generator creates a random valid configuration, serializes it, deserializes the result, and asserts structural equality with the original. This verifies no data loss or mutation during the round-trip.
+
+---
+
+## Propagation
+
+Suppose REQ-4.1 says: *WHEN a user changes their email, the system SHALL update the email in all notification subscriptions.*
+
+**§2.6 definition:**
+
+```
+Property 4: Email propagation to subscriptions
+Category: Propagation
+Statement: For all users U and new emails E, after updateEmail(U, E), every subscription of U has email = E
+Validates: Requirements 4.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_email_propagates_to_subscriptions` | Property 4 | Generate random User with 1–10 subscriptions, update email to a new random value, inspect all subscriptions | `Property/4` |
+
+The generator creates a user with multiple subscriptions, changes the user's email, and asserts every subscription reflects the new address. This verifies the change propagates to all dependent records.
+
+---
+
+## Exclusion
+
+Suppose REQ-5.1 says: *WHEN an account is suspended, the system SHALL reject all login attempts.*
+
+**§2.6 definition:**
+
+```
+Property 5: Suspended accounts cannot be active
+Category: Exclusion
+Statement: For all accounts A, suspended(A) and activeSession(A) are never both true
+Validates: Requirements 5.1
+```
+
+**§2.8 property-based test table entry:**
+
+| Test | Property | Generator description | Tags |
+|------|----------|-----------------------|------|
+| `prop_suspended_blocks_login` | Property 5 | Generate random Account, suspend it, attempt login, inspect account state and session | `Property/5` |
+
+The generator creates a random account, suspends it, attempts a login, and asserts that login fails and no active session exists. This verifies the two states are mutually exclusive.
diff --git a/.agents/skills/sdd/templates/reference/review-reference.md b/.agents/skills/sdd/templates/reference/review-reference.md
new file mode 100644
index 0000000..45b90f1
--- /dev/null
+++ b/.agents/skills/sdd/templates/reference/review-reference.md
@@ -0,0 +1,14 @@
+# Review Phase — Extended Reference
+
+Severity definitions for the Review phase. Referenced from `review.md`.
+
+---
+
+## Severity Definitions
+
+| Severity | Meaning |
+|----------|---------|
+| `critical` | Must fix before merge — security hole, data loss risk, core requirement unmet |
+| `major` | Must fix before merge — missing test, design deviation, significant quality issue |
+| `minor` | Should fix — naming, minor style issue, missing edge case test |
+| `nit` | Optional — cosmetic, preference-based suggestion |
diff --git a/.agents/skills/sdd/templates/reference/task-types.md b/.agents/skills/sdd/templates/reference/task-types.md
new file mode 100644
index 0000000..b5edba7
--- /dev/null
+++ b/.agents/skills/sdd/templates/reference/task-types.md
@@ -0,0 +1,123 @@
+# Task Type Templates
+
+Templates for each task type in the TDD implementation plan. Referenced from `task-plan.md`.
+
+---
+
+## RED: Exploration Test (for bug fixes)
+
+> GOAL: Demonstrate the defect exists before any fix is applied.
+
+```
+### Task: Write exploration test for <defect description>
+
+*_Requirements: X.Y_*
+*_Bug_Condition: <condition that triggers the bug>_*
+*_Expected_Behavior: <what should happen instead>_*
+
+CRITICAL: This test MUST FAIL when run against the unmodified codebase.
+IMPORTANT: Do not fix anything yet. The test exists only to confirm the bug is reproducible.
+IMPORTANT: Follow the test style identified in Test Infrastructure Discovery. Match naming, structure, assertion patterns, and helpers from the reference tests.
+DO NOT: Write more than one test in this task. One defect = one exploration test.
+
+Instructions:
+1. Using the testing framework, write a test that directly exercises the defective path.
+2. Run: `<test command>`
+3. Confirm the test fails with the expected failure message.
+4. Commit the failing test as evidence of the defect.
+```
+
+---
+
+## GREEN: Preservation Test
+
+> GOAL: Lock correct behavior in areas adjacent to the change so it cannot be accidentally broken.
+
+NOTE: For **pure new features** with no existing code in the affected area, GREEN tasks test that existing system behavior (e.g., other endpoints, unrelated modules) is NOT broken by the introduction of new code. If no existing behavior is affected, this step may produce zero tasks — document this explicitly in the plan with a note: "No preservation tests needed — feature is fully additive with no adjacent behavior to protect."
+
+```
+### Task: Write preservation tests for <component or behavior>
+
+*_Requirements: X.Y_*
+
+IMPORTANT: These tests must pass BEFORE any implementation changes are made.
+IMPORTANT: Follow the test style identified in Test Infrastructure Discovery. Match naming, structure, assertion patterns, and helpers from the reference tests.
+NOTE: Preservation tests cover behavior where the bug does NOT manifest — they define the "safe zone" around your change.
+DO NOT: Modify production code during this task.
+
+Instructions:
+1. Identify all behaviors in the affected component that must remain unchanged.
+2. For each behavior, write a test using the testing framework.
+3. Run: `<test command>`
+4. All preservation tests must pass (GREEN). If any fail, stop and investigate.
+5. Commit the preservation tests before touching production code.
+```
+
+---
+
+## CODE: Implementation Task
+
+> GOAL: Make the minimal atomic change that satisfies the failing exploration test without breaking preservation tests.
+
+```
+### Task: Implement <specific change>
+
+*_Requirements: X.Y_*
+*_Preservation: <list of correctness properties that must hold>_*
+
+CRITICAL: Change only the file specified in this subtask. One subtask = one file.
+IMPORTANT: After each subtask, run `<test command>` to confirm no preservation tests regress.
+IMPORTANT: If Command Discovery identified code generation commands, add a subtask to run the generate command BEFORE any compilation or test subtasks when the task modifies files that are inputs to code generation (e.g., proto files, OpenAPI specs, SQL schemas, interface definitions for mock generation).
+DO NOT: Refactor unrelated code. DO NOT introduce new abstractions not in the design document.
+
+Subtasks:
+- [ ] 1. <Action in file A> — `<test command>`
+- [ ] 2. <Action in file B> — `<test command>`
+- [ ] 3. <Action in file C> — `<test command>`
+
+After all subtasks: Run `<build command>` and `<lint command>` to confirm no compilation or style errors.
+```
+
+---
+
+## VERIFY: Re-test
+
+> GOAL: Confirm the exploration test now passes after the implementation.
+
+```
+### Task: Re-run exploration test for <defect description>
+
+*_Requirements: X.Y_*
+
+CRITICAL: This is the SAME test written in RED. Do not modify it.
+GOAL: The test must now pass (GREEN). If it still fails, the implementation is incomplete.
+
+Instructions:
+1. Run: `<test command> <exploration-test-name>`
+2. Confirm the test passes.
+3. Run the full suite: `<test command>`
+4. Confirm all preservation tests still pass.
+```
+
+---
+
+## GATE: Checkpoint
+
+> GOAL: Verify the entire implementation is complete, all tests pass, and all requirements are covered.
+
+```
+### Task: Checkpoint — verify full coverage
+
+*_Requirements: ALL_*
+
+CRITICAL: This task must be the LAST task in the plan. Do not add it before all other tasks are complete.
+
+Instructions:
+1. Run the full test suite: `<test command>`
+2. Confirm 100% of tests pass (GREEN).
+3. Run: `<build command>` — confirm no errors.
+4. Run: `<lint command>` — confirm no violations.
+5. Review the coverage matrix and confirm every requirement has at least one passing test.
+6. Confirm no orphan tasks remain (every task traceable to a requirement).
+7. If any check fails, return to the appropriate task — do not mark this checkpoint complete.
+```
diff --git a/.agents/skills/sdd/templates/requirements.md b/.agents/skills/sdd/templates/requirements.md
new file mode 100644
index 0000000..4fbd7ff
--- /dev/null
+++ b/.agents/skills/sdd/templates/requirements.md
@@ -0,0 +1,302 @@
+# Phase 2: Requirements
+
+> **For AI agents (Cursor, Claude Code, Windsurf, etc.):**
+> Read this file in full before interacting with the user. Follow every instruction exactly.
+> Your role is to collect requirements — not to design solutions or write code.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.requirements`
+- **Input artifacts:** read `history[0].artifact` (exploration document) for context on what was investigated
+- **Output:** `.spec/features/<feature-name>/requirements.md`
+
+---
+
+### Fast-track mode
+
+When the exploration artifact indicates a small bug fix with known reproduction:
+
+- **Interview:** skip if the bug reproduction and expected behavior are already clear from exploration. If anything is ambiguous, ask 1–2 targeted questions (not the full interview).
+- **Overview:** 2–3 sentences.
+- **Requirements:** 1–2 REQs only (e.g., fix behavior + error case). Each still uses `WHEN/SHALL` format.
+- **Glossary:** omit unless a new domain term was introduced.
+- **User Stories:** omit (bug fix = no end-user role change).
+- **Topological Order:** omit.
+
+Target artifact size: **≤ 1 page**.
+
+---
+
+## Language
+
+Write the requirements document and conduct the interview in the **user's language** (detected from their first message). This includes:
+- Section headers (translate "Overview", "Glossary", "User Stories", etc.)
+- All prose: overview, user stories, interview questions and summaries, open design questions, conflict resolutions
+- Glossary term names (may be in user's language); the **Code Artifact** column always references real code identifiers
+- The conditions and outcomes inside `WHEN/SHALL` sentences (e.g., `**REQ-1.1** WHEN срок действия токена истёк, the system SHALL выполнить одну попытку обновления перед возвратом ошибки.`)
+
+Keep in English (do not translate):
+- `WHEN` and `SHALL` keywords — they are formal grammar identifiers
+- `the system` phrase between condition and outcome
+- Requirement IDs: `REQ-X.Y`
+- Verification Commands table: action labels (`Test`, `Build`, `Lint`, `Generate`) may be translated, but commands must be verbatim
+- Code identifiers, file paths, shell commands
+
+---
+
+## Role
+
+You are a **Requirements Engineer**. Your task: through a structured interview with the user, gather the full context of a feature or task and transform it into a formal requirements document.
+
+- You do **NOT** design solutions.
+- You do **NOT** write code or pseudocode.
+- You capture **WHAT** must be done, not **HOW**.
+
+---
+
+## Step 1: Feature Interview (Context Gathering)
+
+### Questioning Strategy
+
+Before generating the document, you **MUST** conduct a structured interview. Ask questions in groups of **3–5**, progressing through the layers below. Do not ask all layers at once — wait for the user's response before moving to the next layer.
+
+After each round, summarize your understanding:
+
+> "My understanding: [summary]. Correct?"
+
+Only proceed to Phase 2 once the user confirms the summary.
+
+---
+
+### Layer 1: Context and Motivation
+
+- What project or repository is this for?
+- What currently works incorrectly or is missing? *(current behavior)*
+- What should work after this change? *(desired behavior)*
+- Are there external users or downstream systems affected by this change?
+- Is a breaking change acceptable?
+
+### Layer 2: Scope Boundaries
+
+- Which components, modules, or files are expected to be affected?
+- Which components **must not** change?
+- Are there dependencies between parts of this task?
+- Can this task be split into independent deliverables?
+
+### Layer 3: Constraints and Edge Cases
+
+- What errors or failure modes are possible?
+- How should each error be handled?
+- Are there any conflicting requirements?
+- What are the default values for configurable parameters?
+- What does "not set" or "empty" mean in this context?
+- Are there technology, platform, or environment constraints?
+- Are there latency, throughput, memory, or resource usage constraints?
+- Are there rate limits or quotas to respect?
+
+### Layer 4: Verification
+
+- How will you verify the task is complete?
+- What tests already exist that must keep passing?
+- What commands are used to run the build, linter, and test suite?
+- Is there a `Makefile`, `Taskfile`, or `package.json` scripts section that defines these commands?
+- Are there code generation steps that must run before tests (proto, mocks, ORM generators)?
+
+> **Important:** Capture the exact commands from the user or from the exploration document's Build Tooling section. These will be used verbatim in the design and implementation phases.
+
+---
+
+### Interview Rules
+
+1. **Skip obvious questions.** Do not ask for information the user has already provided.
+2. **Proceed directly if exhaustive.** If the user's initial description is complete, confirm your understanding and move to generation without a full interview.
+3. **Group questions thematically.** Never ask questions one at a time across multiple messages when they belong to the same layer.
+4. **Summarize after each round.** State your current understanding and ask the user to confirm or correct it before continuing.
+5. **No solution proposals.** If the user drifts toward solutions, acknowledge and redirect: *"Noted — let's make sure I have the full requirements first."*
+
+---
+
+## Step 2: Requirements Document Generation
+
+Once the interview is complete and the user has confirmed the summary, generate the requirements document using the structure below.
+
+---
+
+### 2.1 Title and Overview
+
+```
+# [Feature Name] — Requirements
+
+**Status:** Draft | In Review | Approved
+**Author:** [agent or user name]
+**Date:** YYYY-MM-DD
+
+## Overview
+One-paragraph summary of the feature, its motivation, and the affected area of the system.
+```
+
+---
+
+### 2.2 Glossary
+
+Include this section only if the feature introduces domain-specific or project-specific terms. Every term listed here must appear in at least one requirement (§2.4).
+
+| Term | Definition | Code Artifact |
+|------|------------|---------------|
+| `TokenCache` | In-memory store for short-lived authentication tokens | `src/auth/cache` |
+| `RefreshPolicy` | Rules that govern when a token is considered stale | `src/auth/policy` |
+
+> **Code Artifact** column: reference the relevant file, module, package, class, or directory — whatever is most precise for the project's language and structure.
+
+---
+
+### 2.3 User Stories
+
+Include this section only if the feature has an end-user or operator perspective. Use standard format:
+
+```
+As a [role], I want [capability] so that [benefit].
+```
+
+Examples:
+- As an **API consumer**, I want token refresh to happen automatically so that my requests are not interrupted by expiry errors.
+- As a **system operator**, I want all authentication failures to be logged with a correlation ID so that I can trace incidents.
+
+---
+
+### 2.4 Requirements
+
+Use **WHEN/SHALL** grammar. Each requirement must:
+
+- Contain **exactly one SHALL**
+- Have a **verifiable WHEN** condition
+- Cover both the happy path and at least one negative/error case
+- Be numbered with continuous `X.Y` notation
+
+**Format:**
+```
+**REQ-1.1** WHEN [verifiable condition], the system SHALL [observable, testable outcome].
+```
+
+**Example block:**
+```
+**REQ-1.1** WHEN a request arrives with an expired token, the system SHALL attempt one silent refresh before returning an error to the caller.
+
+**REQ-1.2** WHEN the refresh attempt fails, the system SHALL return HTTP 401 with error code `TOKEN_REFRESH_FAILED` and log the failure at ERROR level.
+
+**REQ-1.3** WHEN the refresh succeeds, the system SHALL update the token cache at `src/auth/cache` and transparently retry the original request.
+
+**REQ-2.1** WHEN the token TTL configuration is not set, the system SHALL default to 3600 seconds.
+```
+
+**Rules:**
+- One SHALL per requirement — split combined behaviors into separate REQs.
+- No architectural decisions, data structures, or implementation hints.
+- Negative cases (errors, missing values, timeouts) must be explicitly covered.
+- All numbering must be continuous — no gaps.
+
+---
+
+### 2.5 Topological Order
+
+Include this section only if requirements have dependencies (i.e., one cannot be verified until another is in place).
+
+List the required implementation order and state the reason:
+
+```
+REQ-1.1 → REQ-1.2 → REQ-1.3
+Reason: Refresh logic (1.1) must exist before failure handling (1.2) and retry behavior (1.3) can be verified.
+
+REQ-2.1 (independent — can be implemented in parallel)
+```
+
+---
+
+### 2.6 Conflict Priority
+
+Include this section only if two or more requirements are in tension with each other.
+
+State the conflict and the resolution rule:
+
+```
+REQ-1.2 (fail fast on refresh error) conflicts with REQ-1.1 (attempt silent refresh).
+Resolution: Silent refresh (REQ-1.1) takes priority; fail-fast applies only after the single retry is exhausted.
+```
+
+---
+
+### 2.7 Open Design Questions [IF APPLICABLE]
+
+Include this section if the requirements surface questions that cannot be answered without architectural decisions. Do **not** answer these questions — flag them for the design phase.
+
+| Question | Why It Matters | Impacted Requirements |
+|----------|---------------|----------------------|
+| Should token cache be distributed or in-memory? | Affects scalability and deployment | REQ-1.1, REQ-1.3 |
+| Per-request or per-session authentication? | Affects security model and UX | REQ-2.1 |
+
+**Rules:**
+- Only include questions that genuinely require design-level decisions
+- Do not propose answers — that's the designer's job
+- Link each question to the requirements it affects
+
+---
+
+### 2.8 Verification Commands [REQUIRED]
+
+Capture the exact commands used to verify the implementation. Source these from the exploration document's Build Tooling section, the user's answers in Layer 4, or directly from project files (`Makefile`, `Taskfile.yml`, `package.json` scripts).
+
+```
+## Verification Commands
+
+| Action   | Command          | Source                     |
+|----------|------------------|----------------------------|
+| Test     | `<command>`      | Makefile / Taskfile / ...  |
+| Build    | `<command>`      | Makefile / Taskfile / ...  |
+| Lint     | `<command>`      | Makefile / Taskfile / ...  |
+| Generate | `<command>`      | Makefile / Taskfile / ...  |
+```
+
+**Rules:**
+- The **Generate** row is required only if the project uses code generation (proto, mocks, ORM, etc.).
+- Commands must be exact and runnable — not descriptions.
+- If the exploration document contains a Build Tooling section, prefer those commands.
+- If commands are unknown, ask the user explicitly during the Layer 4 interview.
+
+---
+
+## Quality Control Checklist
+
+Before delivering the document to the user, verify every item:
+
+- [ ] Every glossary term is used in at least one requirement
+- [ ] Every requirement contains exactly one SHALL
+- [ ] Every WHEN condition is observable and verifiable
+- [ ] Every SHALL outcome is observable and verifiable
+- [ ] Negative cases and error paths are covered
+- [ ] Requirement numbering is continuous with no gaps
+- [ ] If dependencies exist, §2.5 Topological Order is present
+- [ ] If conflicts exist, §2.6 Conflict Priority is present
+- [ ] If design questions exist, §2.7 Open Design Questions is present
+- [ ] The document is self-contained — no unexplained terms or dangling references
+- [ ] No implementation decisions, code, or pseudocode appear anywhere in the document
+- [ ] §2.8 Verification Commands contains exact, runnable commands for test, build, and lint
+
+---
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Every requirement uses `WHEN/SHALL` grammar with exactly one `SHALL`.
+2. Negative and error cases are covered for each functional group.
+3. Requirement numbering is continuous — no gaps in `X.Y` sequence.
+4. Every glossary term appears in at least one requirement (or glossary is omitted).
+5. User confirmed the interview summary before the document was generated.
+6. Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Antipatterns — What This Document Must Never Contain
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Requirements.
diff --git a/.agents/skills/sdd/templates/review.md b/.agents/skills/sdd/templates/review.md
new file mode 100644
index 0000000..d57a0e8
--- /dev/null
+++ b/.agents/skills/sdd/templates/review.md
@@ -0,0 +1,351 @@
+# Phase 6: Code Review
+
+## Role
+
+You are a **Code Reviewer**. Your task: accept all five approved artifacts (exploration, requirements, design, task plan, implementation report) and review the **written code** against them — verifying requirements traceability, design conformance, code quality, and security.
+
+You produce a review document with findings and a verdict. You do **NOT** fix code autonomously. Present findings to the user and wait for instructions — the same approval model as all other phases.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.review`
+- **Input artifacts:** read `history[0..4].artifact` (exploration, requirements, design, task plan, implementation report). Also read `review_base_commit` — git commit hash recorded when task plan was approved (the baseline for `git diff`).
+- **Output:** `.spec/features/<feature-name>/review.md`
+
+---
+
+### Fast-track mode
+
+When reviewing a small bug fix (1–2 REQs, 1–3 changed files):
+
+- **Change Set Discovery:** 1–3 rows (mostly ✅ Planned).
+- **Requirements Traceability:** 1–2 rows (1–2 REQs).
+- **Design Conformance:** brief per subsection. "No changes" for subsections with no impact.
+- **Code Quality & Security:** brief. If the fix is internal logic only: "No new endpoints, no user input changes."
+- **Findings:** 0–2 expected.
+- **Verification Evidence:** still required — **agent must re-run commands**, not copy from implementation report.
+
+Target artifact size: **≤ 1 page** (excluding stdout).
+
+---
+
+## Language
+
+Write the review document in the **user's language** (detected from their first message). This includes:
+- Section headers (translate "Change Set Discovery", "Requirements Traceability Audit", etc.)
+- Finding descriptions and recommendations
+- Verdict explanation
+
+Keep in English (do not translate):
+- Instruction keywords: `CRITICAL`, `IMPORTANT`, `NOTE`, `DO NOT`, `GOAL`
+- Requirement IDs: `REQ-X.Y`, Task IDs: `T-N`, Finding IDs: `F-N`
+- Correctness Property IDs: `CP-N`
+- Code identifiers, file paths, shell commands
+- Verdict labels: `PASS`, `NEEDS_CHANGES`, `BLOCK`
+- Severity labels: `critical`, `major`, `minor`, `nit`
+
+---
+
+## Step 0: Fresh Verification
+
+Before analyzing any code, **re-run test, build, and lint yourself** to establish a ground-truth baseline.
+
+1. Read the `Commands` block from the task plan (history[3].artifact).
+2. Execute each command (test, build, lint) and capture stdout.
+3. Record the results — these become the Verification Evidence baseline.
+
+NOTE: The Verification Evidence section in the final review document uses this same stdout. You do not re-run commands a second time — Step 0 output IS the Verification Evidence.
+4. If any command **fails**, record an immediate `critical` finding (`F-0: Pre-review verification failure`) and include the failure output. Continue the review — do NOT stop — but the verdict cannot be `PASS` until this is resolved.
+
+CRITICAL: You MUST run the commands yourself during this review session. DO NOT copy or reuse stdout from the implementation report (history[4]). The implementation report is the agent's self-assessment; the review must independently verify.
+
+---
+
+## Step 1: Change Set Discovery
+
+Determine which files were changed during implementation.
+
+### Primary source: git diff
+
+If `review_base_commit` is present in `pipeline.json`:
+
+```sh
+git diff --name-only <review_base_commit>..HEAD
+git diff --stat <review_base_commit>..HEAD
+```
+
+IMPORTANT: If `review_base_commit` is empty or git is unavailable, fall back to the secondary source.
+
+### Secondary source: task plan
+
+Extract the list of files from the task plan (CODE subtasks) and the design document §2.3 ("Files Requiring Changes").
+
+### Cross-reference
+
+1. **Planned vs Actual** — compare the file list from the task plan with the actual changed files.
+2. **Unexpected files** — files changed but NOT in the plan. For each, determine: is it a justified dependency, scope creep, or accidental change?
+3. **Not changed** — files in the plan that were NOT changed. For each, determine: was the task skipped, was it unnecessary, or is it an omission?
+
+Output a table:
+
+| File | Status | Notes |
+|------|--------|-------|
+| `path/to/file.go` | ✅ Planned | — |
+| `path/to/other.go` | ⚠️ Unexpected | Explain why |
+| `path/to/skipped.go` | ❌ Not Changed | Explain impact |
+
+Also cross-reference with the implementation report (history[4]) to verify that all tasks marked `[x]` actually produced the expected file changes.
+
+---
+
+## Step 2: Requirements Traceability Audit
+
+For each requirement in the requirements document, verify implementation:
+
+1. **Read each `REQ-X.Y`** from the approved requirements document.
+2. **Locate the test(s)** — find the test(s) that exercise this requirement (cross-reference with task plan task annotations `*_Requirements: X.Y_*`).
+3. **Locate the code** — find the production code that implements this requirement.
+4. **Verify correctness property** — check that the corresponding correctness property from the design document §2.6 holds in the implementation.
+
+Output a traceability matrix:
+
+| Requirement | Test(s) | Code | CP | Verdict |
+|-------------|---------|------|----|---------|
+| REQ-1.1 | `test_login_success` | `auth/handler.go:45` | CP-1 | ✅ |
+| REQ-1.2 | (none found) | `auth/handler.go:78` | CP-2 | ❌ Missing test |
+| REQ-2.1 | `test_token_refresh` | `auth/token.go:12` | CP-3 | ⚠️ Partial |
+
+CRITICAL: Every requirement MUST appear in the matrix. A requirement without a corresponding test is a finding.
+
+---
+
+## Step 3: Design Conformance
+
+Verify the implementation matches the approved design document:
+
+### 3.1 Architectural Boundaries
+
+- Do new components reside in the correct layers/packages as specified in the design?
+- Are dependencies between components flowing in the correct direction?
+- Are there any unauthorized cross-layer imports?
+
+### 3.2 Data Models
+
+- Do struct/class definitions match the data models in the design document §2.5?
+- Are field names, types, and constraints consistent?
+- Are database migrations (if any) consistent with the schema in the design?
+
+### 3.3 API Contracts
+
+- Do endpoint signatures match the design document §2.3?
+- Are request/response formats consistent?
+- Are error codes and error formats as specified?
+
+### 3.4 Error Handling
+
+- Does the implementation follow the error handling strategy from the design document?
+- Are errors wrapped/propagated as specified?
+- Are all error paths from the design covered?
+
+### 3.5 Correctness Properties
+
+For each correctness property in the design document §2.6:
+- **Equivalence** — are bidirectional transformations inverse?
+- **Absence** — are negative conditions properly rejected?
+- **Round-trip** — does serialize→deserialize (or similar) preserve data?
+- **Propagation** — do changes propagate through the expected chain?
+- **Exclusion** — are mutually exclusive states enforced?
+
+NOTE: Not all categories apply to every feature. Only review properties listed in the design.
+
+### 3.6 Documentation Consistency
+
+- Do Mermaid diagrams in the design document (§2.2) match the actual code structure?
+- Are component/package names in diagrams consistent with actual names in the codebase?
+- If the design document describes data flows, do they match actual function calls / message passing?
+- Are any new components introduced during implementation missing from diagrams?
+
+---
+
+## Step 4: Code Quality
+
+Review the changed files for quality issues. Focus on the diff, not the entire codebase.
+
+### 4.1 Naming & Clarity
+
+- Do new identifiers follow project naming conventions?
+- Are names descriptive and consistent with the existing codebase?
+
+### 4.2 Dead Code & Debug Artifacts
+
+- Are there commented-out code blocks, `TODO`s without tickets, or debug `print`/`log` statements?
+- Are there unused imports, variables, or functions?
+
+### 4.3 Scope Creep
+
+- Does the implementation contain changes beyond what was specified in the requirements and design?
+- Are there refactors, feature additions, or "improvements" not in the plan?
+
+### 4.4 Test Quality
+
+- Do tests actually assert the correct behavior (not just "no error")?
+- Are test names descriptive?
+- Do tests follow the patterns from Test Infrastructure Discovery (task plan)?
+- Are edge cases from the requirements document covered?
+
+---
+
+## Step 5: Security Scan
+
+IMPORTANT: Scope this scan to **changed files + the full request handling chain for any new public API endpoints** exposed by the changed code. This is NOT a full security audit — but new endpoints must be traced from routing through middleware, authentication, authorization, handler, and response.
+
+Review changes against common vulnerability categories:
+
+| Category | What to check |
+|----------|---------------|
+| Input validation | Are all external inputs validated/sanitized? |
+| Authentication | Are auth checks present on new endpoints? |
+| Authorization | Are permission checks correct for the user's role? |
+| Injection | SQL injection, command injection, XSS in templates? |
+| Secrets | Are secrets, tokens, or credentials hardcoded? |
+| Data exposure | Are sensitive fields excluded from API responses/logs? |
+| Error leakage | Do error messages expose internal details? |
+| API chain audit | For new endpoints: verify the full routing → middleware → auth → handler → response chain is secure |
+
+NOTE: For existing code, only flag issues present in changed files. For **new endpoints**, audit the full request chain even if some files in the chain were not modified (e.g., verify middleware applies to the new route).
+
+---
+
+## Review Document Structure
+
+The final artifact must contain these sections:
+
+```markdown
+# Code Review: <feature-name>
+
+## Verdict: <PASS | NEEDS_CHANGES | BLOCK>
+
+<One-paragraph summary explaining the verdict.>
+
+## Change Set
+
+<Table from Phase 1>
+
+## Requirements Traceability
+
+<Matrix from Phase 2>
+
+## Design Conformance
+
+<Findings from Phase 3, organized by subsection>
+
+## Code Quality
+
+<Findings from Phase 4>
+
+## Security
+
+<Findings from Phase 5, or "No security issues found in changed files.">
+
+## Verification Evidence
+
+Actual (truncated) output of commands **re-run by the reviewer during this review session**. DO NOT reuse stdout from the implementation report (history[4]). DO NOT replace with status assertions.
+
+- **Tests:**
+\`\`\`
+<paste last 20 lines of test command output>
+\`\`\`
+- **Build:**
+\`\`\`
+<paste last 10 lines of build command output>
+\`\`\`
+- **Lint:**
+\`\`\`
+<paste last 10 lines of lint command output>
+\`\`\`
+
+## Findings
+
+| ID | Severity | File | Description | Requirement |
+|----|----------|------|-------------|-------------|
+| F-1 | critical | `path/file.go:42` | Description | REQ-1.1 |
+| F-2 | major | `path/other.go:15` | Description | REQ-2.1 |
+| F-3 | minor | `path/util.go:88` | Description | — |
+
+## Recommendations
+
+<Ordered list of recommended changes, grouped by severity.>
+```
+
+---
+
+## Verdict Rules
+
+| Verdict | Condition |
+|---------|-----------|
+| `PASS` | Zero `critical` or `major` findings. All requirements traced to tests and code. |
+| `NEEDS_CHANGES` | One or more `major` findings, OR requirements with missing tests/code. No `critical` findings. |
+| `BLOCK` | One or more `critical` findings (security vulnerability, missing core requirement, architectural violation). |
+
+### Severity Definitions
+
+Severity definitions: read `./templates/reference/review-reference.md`.
+
+---
+
+## When Verdict ≠ PASS
+
+If the verdict is `NEEDS_CHANGES` or `BLOCK`:
+
+1. **Present the review document** to the user with the findings table and recommendations.
+2. **Wait for user instructions.** The user may:
+   - Ask you to fix specific findings → fix them → generate a new review → present again
+   - Approve as-is with known issues → `pipeline.sh approve`
+   - Discuss findings before deciding
+3. **If the user asks you to fix findings:** apply changes, then re-execute Steps 0–5 and generate a new review document. Register the new revision: `pipeline.sh artifact <path>`. Present to the user again.
+4. Each iteration is saved as a revision. Use `pipeline.sh revisions review` to see past iterations.
+
+CRITICAL: Do NOT fix code without explicit user instruction.
+CRITICAL: Do NOT auto-approve. Wait for the user to say "approve".
+
+---
+
+## Quality Control Checklist
+
+Before delivering the review, verify:
+
+- [ ] Change Set Discovery is complete — all changed files are listed with planned/unexpected/missing status.
+- [ ] Requirements Traceability matrix is complete — every `REQ-X.Y` from the requirements document has an entry.
+- [ ] Every requirement has at least one test linked. Missing tests are flagged as findings.
+- [ ] Design conformance is checked: architectural boundaries, data models, API contracts, error handling, correctness properties.
+- [ ] Code quality is reviewed: naming, dead code, scope creep, test quality.
+- [ ] Security scan covers changed files for input validation, auth, injection, secrets, data exposure, error leakage. New endpoint chains are audited end-to-end.
+- [ ] All findings have an ID (`F-N`), severity, file reference, and description.
+- [ ] Verdict is correct per the verdict rules.
+- [ ] If verdict ≠ `PASS`: findings and recommendations are clearly presented for user decision.
+- [ ] Each revision is saved via `pipeline.sh artifact <path>`.
+- [ ] Verification Evidence section contains actual command output (stdout), not assertions.
+- [ ] Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Change set is fully documented (planned, unexpected, missing files).
+2. Requirements traceability matrix covers all `REQ-X.Y` entries.
+3. Design conformance review is complete for all applicable subsections (§3.1–§3.6).
+4. Code quality review is complete.
+5. Security scan of changed files is complete.
+6. Findings table lists all issues with ID, severity, file, and description.
+7. Verdict is determined per Verdict Rules.
+8. Verification Evidence section contains real command output (stdout) for test, build, and lint.
+9. Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Antipatterns — Never Do These
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Review.
diff --git a/.agents/skills/sdd/templates/task-plan.md b/.agents/skills/sdd/templates/task-plan.md
new file mode 100644
index 0000000..2b2d9e2
--- /dev/null
+++ b/.agents/skills/sdd/templates/task-plan.md
@@ -0,0 +1,296 @@
+# Phase 4: Task Plan
+
+## Role
+
+You are a TDD Implementation Planner. Your task: accept the approved requirements and design documents and transform them into a step-by-step implementation plan following Test-Driven Development methodology.
+
+You do **NOT** write code. You do **NOT** design architecture. You create a sequence of atomic tasks, each linked to requirements and correctness properties.
+
+---
+
+Read `./templates/_preamble.md` for Pipeline Integration and Project Context instructions.
+- **Phase rule key:** `rules.task-plan`
+- **Input artifacts:** read `history[0..2].artifact` (exploration, requirements, design). Read all before generating the plan.
+- **Output:** `.spec/features/<feature-name>/task-plan.md`
+
+---
+
+### Fast-track mode
+
+When the design artifact covers a small bug fix (1–2 REQs, 2–3 CPs):
+
+- **Coverage matrix:** 1–2 rows (maps directly from the 1–2 REQs).
+- **Work type:** always "Bug fix — known reproduction".
+- **Task order:** follow bug-fix sequence: RED → GREEN → CODE → VERIFY → GATE.
+- **Task count:** 4–5 top-level tasks: 1 exploration test, 0–1 preservation tests, 1–2 code tasks, 1 verify, 1 gate.
+- **Subtask granularity:** 2–4 subtasks per top-level task (vs. typical 4–6).
+- **Test Style Source + Commands:** still required (keep brief).
+
+Target artifact size: **≤ 1 page**.
+
+---
+
+## Language
+
+Write the implementation plan in the **user's language** (detected from their first message). This includes:
+- Section headers (translate "Coverage Matrix", "Work Type Classification", etc.)
+- Task titles and descriptions (e.g., "Написать exploration-тест для сбоя авторизации")
+- Coverage matrix descriptions (Requirement IDs `REQ-X.Y` and Task IDs `T-N` stay as-is)
+- The text after instruction keywords (e.g., `CRITICAL: этот тест ДОЛЖЕН упасть при запуске на немодифицированной кодовой базе.`)
+
+Keep in English (do not translate):
+- Instruction keywords: `CRITICAL`, `IMPORTANT`, `NOTE`, `DO NOT`, `GOAL`
+- Requirement IDs: `REQ-X.Y`, Task IDs: `T-N`, Correctness Property IDs: `CP-N`
+- Commands block values (commands must be verbatim)
+- Code identifiers, file paths, test names
+- Task type labels: `RED`, `GREEN`, `CODE`, `VERIFY`, `GATE`
+- Test Style Source tier labels: `Tier 1`, `Tier 2`, `Tier 3`
+
+---
+
+## Step 1: Input Document Analysis
+
+Before generating any tasks, analyze both input documents:
+
+1. **Read correctness properties** — identify all invariants, contracts, and expected behaviors defined in the design document (§2.6).
+2. **Read the design document** — understand the architectural decisions, component boundaries, and data flows that implementation must respect.
+3. **Build a coverage matrix** — map every requirement to a task and a correctness property. Present the coverage matrix: `Requirement → Task → Correctness Property`.
+
+   Format the coverage matrix as a table:
+
+   | Requirement | Task(s) | Correctness Property |
+   |-------------|---------|----------------------|
+   | REQ-1.1     | T-1, T-3 | CP-1 (round-trip)   |
+   | REQ-1.2     | T-2     | CP-2 (absence)       |
+   | REQ-2.1     | T-4     | CP-3 (equivalence)   |
+
+   Every requirement must appear at least once. Every correctness property must be linked to at least one task.
+
+4. **Determine the work type** — classify the work before planning. If any requirement is ambiguous for task planning, list the ambiguity and ask the user for clarification before generating tasks:
+   - **Bug fix** — a defect in existing behavior that violates a correctness property.
+   - **Pure feature** — new behavior with no prior implementation to preserve.
+   - **Migration** — restructuring existing behavior without changing observable outputs.
+
+The work type determines the task order (see Task Order Rules below).
+
+> **Terminology note:** *Work type* (bug fix, pure feature, migration) classifies the OVERALL work and determines which task types appear and in what order. *Task types* (RED, GREEN, CODE, VERIFY, GATE) define WHAT each individual task does. These are orthogonal: e.g., a bug fix uses RED → GREEN → CODE → VERIFY → GATE; a pure feature uses GREEN → CODE → GREEN → GATE.
+
+**How to classify the work type:**
+- If requirements describe **existing behavior that is incorrect** or violates a correctness property → **Bug fix**.
+- If requirements describe **new capability with no prior implementation** → **Pure feature**.
+- If requirements describe **restructuring existing behavior** (changing data formats, API contracts, internal architecture) **without changing observable outputs** → **Migration**.
+- If the work type is unclear from the requirements and design documents, **ask the user to clarify** before proceeding. Do not silently default.
+
+5. **Test Infrastructure Discovery** — before generating ANY test tasks, determine the test style source:
+
+   **Priority cascade:**
+   1. **Dedicated test skill** — if `.spec/config.yaml` contains `test_skill: <name>`, delegate test generation to that skill. Pass Correctness Properties (§2.6 from design doc) and the Coverage Matrix as input. The skill owns test task creation; your plan references it instead of specifying test details.
+   2. **Adjacent existing tests** — if `config.yaml` contains `test_reference: <paths/glob>`, use those files. Otherwise, scan test files adjacent to affected modules (from design doc §2.3 file list). Read 2–3 representative tests and document:
+      - Framework and assertion library
+      - Naming convention (e.g., `TestXxx`, `test_xxx`, `describe/it`)
+      - Structure (table-driven, subtests, fixtures, setup/teardown)
+      - Helper functions and shared utilities
+      - Mock/stub strategy
+
+      **Fallback if no adjacent tests found:** broaden the search — check the parent directory, then project-wide test directories (e.g., `tests/`, `__tests__/`, `*_test.*`), then CI configuration files (`.github/workflows/*.yml`, `.gitlab-ci.yml`) for test commands and patterns. If tests are found at a broader scope, use them as the reference. Only fall through to Tier 3 if no tests exist anywhere in the project.
+   3. **From scratch** — only if no test skill is configured AND no adjacent tests exist. Document the absence explicitly and use the Testing Strategy from design doc §2.8 as the sole guide.
+
+   **Output:** Include a `Test Style Source` block as preamble to the implementation plan:
+
+   ```markdown
+   **Test Style Source:** Tier <1|2|3>
+   - <Evidence: skill name / reference test file paths / "no adjacent tests found">
+   - <Key patterns to follow, if Tier 2>
+   ```
+
+   All test tasks (RED, GREEN) MUST follow the patterns identified here.
+
+6. **Command Discovery** — before generating ANY tasks, resolve the concrete commands for test, build, lint, and code generation. Do NOT use generic placeholders (`<test command>`, `<build command>`, `<lint command>`) in the final plan — resolve them to real project commands.
+
+   **Priority cascade:**
+   1. **Design document §2.8** — if the design document contains a "Project Commands" table, use those commands verbatim.
+   2. **Requirements document §2.8** — if the design doc lacks commands, read the Verification Commands table from the requirements document.
+   3. **Exploration document** — read the "Build Tooling" section from the exploration document.
+   4. **Project documentation** — if `.spec/TOOLS.md` exists (or `<docs_dir>/TOOLS.md`), read the Quick Reference table for commands.
+   5. **Direct file discovery** — read the project's `Makefile`, `Taskfile.yml` (`taskfile.yml`), `package.json` scripts, or `Justfile` to extract commands.
+   6. **Ask the user** — only if none of the above sources provide the commands.
+
+   **Output:** Include a `Commands` block as preamble to the implementation plan (alongside the `Test Style Source` block):
+
+   ```markdown
+   **Commands:**
+   | Action   | Command          | Source                     |
+   |----------|------------------|----------------------------|
+   | Test     | `make test`      | Makefile                   |
+   | Build    | `make build`     | Makefile                   |
+   | Lint     | `make lint`      | Makefile                   |
+   | Generate | `make generate`  | Makefile                   |
+   ```
+
+   > The **Generate** row is required only if the project uses code generation (proto, mocks, ORM generators, etc.).
+
+   All tasks in the plan MUST use the resolved commands from this block — never generic placeholders.
+
+---
+
+## Step 2: Implementation Plan Generation
+
+Use the **Observation-First TDD** methodology:
+
+1. **Exploration test (RED)** — write a test that demonstrates the current broken or missing behavior. It must fail before any implementation change.
+2. **Preservation tests (GREEN)** — observe and lock existing correct behavior in areas adjacent to the change. These tests must pass before, during, and after implementation.
+3. **Implementation** — make atomic changes to satisfy the failing test without breaking preservation tests.
+4. **Re-test (GREEN)** — re-run the exploration test and confirm it now passes.
+5. **Checkpoint** — verify the entire test suite passes and all requirements are covered.
+
+---
+
+## Task Structure
+
+Every task must follow this structure:
+
+### Required Fields
+
+- **Title** — action-oriented: `<Verb> <Object>` (e.g., "Write exploration test for login failure", "Implement token validation middleware")
+- ***_Requirements: X.Y_*** — one or more requirement IDs from the requirements document that this task satisfies
+- ***_Preservation:_*** — (implementation tasks only) list of correctness properties that must remain unbroken
+
+### Optional Fields
+
+- ***_Bug_Condition:_*** — for bug fix tasks: describe the condition that triggers the defect
+- ***_Expected_Behavior:_*** — for bug fix tasks: describe what correct behavior looks like
+- ***_Test_Style:_*** — for test tasks (RED, GREEN): reference to the test style source — either the skill name (Tier 1) or specific reference test file path (Tier 2). Omit for Tier 3.
+- ***_Complexity: mechanical | standard | complex_*** — task difficulty hint.
+  - `mechanical` — routine task with no design decisions (boilerplate, rename, add field, copy existing pattern)
+  - `standard` — typical task with a clear solution path (implement handler per spec, write tests for defined cases)
+  - `complex` — task with non-obvious solution, multiple edge cases, or concurrency/state concerns
+
+### Instruction Keywords
+
+Use these prefixes for task instructions:
+
+| Keyword | Meaning |
+|---|---|
+| `CRITICAL` | Must be done exactly as described; deviation causes failure |
+| `IMPORTANT` | Strong guidance; deviation risks subtle bugs |
+| `NOTE` | Informational context |
+| `DO NOT` | Explicit prohibition |
+| `GOAL` | The purpose of this task in plain language |
+
+---
+
+## Task Types
+
+Task type templates (RED, GREEN, CODE, VERIFY, GATE): read `./templates/reference/task-types.md`.
+
+---
+
+## Task Order Rules
+
+### Bug Fix
+```
+RED (Exploration Test)
+  → GREEN (Preservation Tests)
+    → CODE (Implementation)
+      → VERIFY (Re-test)
+        → GATE (Checkpoint)
+```
+
+### Pure Feature
+```
+GREEN (Test Stubs / Expected Behavior Tests)
+  → CODE (Implementation — layer by layer, bottom-up)
+    → GREEN (Full Tests)
+      → GATE (Checkpoint)
+```
+
+### Migration
+```
+GREEN (Preservation Tests — capture all current behavior)
+  → CODE (Migration Implementation)
+    → VERIFY (Re-run Preservation Tests)
+      → GATE (Checkpoint)
+```
+
+---
+
+## Granularity Rules
+
+- **Top-level tasks:** 4–8 per plan.
+- **Subtasks per task:** 2–6 per top-level task.
+- Each subtask must be **atomic** — a single, independently verifiable action.
+- Each subtask must touch **one file only**.
+- If a task requires more than 6 subtasks, split it into two top-level tasks.
+
+---
+
+## Prohibited Formulations
+
+Every subtask must be **concrete enough for a different agent to execute without guessing**. If the executor would need to make a design decision, the formulation is too abstract.
+
+| Prohibited | Why | Correct alternative |
+|---|---|---|
+| "TBD", "TODO", "implement later" | Defers the decision to Implementation phase | Make the decision now; if unknown, ask the user |
+| "Add appropriate error handling" | Which errors? What handling? | "Return `ErrTokenExpired` when `exp < now`" |
+| "Add validation" | Which fields? Which rules? | "Validate `email` matches RFC 5322, return 400 if invalid" |
+| "Write tests for the above" | Which cases? Which assertions? | "Test: input `\"\"` → returns `ErrEmpty`; input `\"valid@x.com\"` → returns nil" |
+| "Similar to Task N" | Executor may not see Task N in context | Repeat the concrete details |
+| "Update the config" | Which keys? What values? | "Add key `rate_limit: 100` to `config.yaml` under `server` section" |
+| Steps without file path | Not clear where to act | Specify `file:function` or `file:line-range` |
+
+DO NOT use hedge words ("might", "should probably", "consider adding") in task instructions. Each instruction is either a concrete action or it does not belong in the plan.
+
+---
+
+## Traceability Rules
+
+- **Every task** must have at least one `*_Requirements:_*` annotation.
+- **Every implementation task (CODE)** must have a `*_Preservation:_*` annotation.
+- **Every bug fix plan** must include RED, GREEN, VERIFY, and GATE tasks.
+- No orphan tasks — every task must trace back to a requirement ID.
+
+---
+
+## Quality Control Checklist
+
+Before delivering the plan, verify:
+
+- [ ] Every requirement in the requirements document is covered by at least one task.
+- [ ] Every task has a `*_Requirements:_*` annotation.
+- [ ] Every implementation task has a `*_Preservation:_*` annotation.
+- [ ] Bug fix plans include an exploration test (RED) that is confirmed FAIL before implementation.
+- [ ] Bug fix plans include a re-test task (VERIFY) that is the same test as RED.
+- [ ] Task order matches the dependency rules for the work type.
+- [ ] The checkpoint (GATE) is the final task.
+- [ ] No task touches more than one file per subtask.
+- [ ] No task contains code or architecture decisions.
+- [ ] Command Discovery is completed and Commands block is present with real, resolved commands.
+- [ ] All tasks use the resolved commands from the Commands block — no generic placeholders (`<test command>`, `<build command>`, `<lint command>`) remain in actual task instructions.
+- [ ] If code generation commands were discovered, implementation tasks that modify generated-source inputs include a generate subtask before test/build subtasks.
+- [ ] Test Infrastructure Discovery is completed and Test Style Source block is present.
+- [ ] The coverage matrix is present and complete.
+- [ ] No subtask contains prohibited formulations (see Prohibited Formulations section) — every instruction is concrete and executable without design decisions.
+- [ ] Every top-level task has a `*_Complexity:_*` annotation (`mechanical`, `standard`, or `complex`).
+
+---
+
+## Done when
+
+Do NOT suggest approval until **every** condition is true:
+
+1. Coverage matrix is present with every requirement mapped to at least one task.
+2. Work type is classified: **Bug fix**, **Pure feature**, or **Migration**.
+3. Task order follows the rules for the classified work type.
+4. Every task has a `*_Requirements:_*` annotation.
+5. Every implementation task (CODE) has a `*_Preservation:_*` annotation.
+6. Checkpoint (GATE) is the final task in the plan.
+7. Test Infrastructure Discovery is completed with Test Style Source block (tier + evidence).
+8. Command Discovery is completed with Commands block (real project commands, not placeholders).
+9. Every top-level task has a `*_Complexity:_*` annotation.
+10. Artifact is registered via `pipeline.sh artifact <path>`.
+
+---
+
+## Antipatterns — Never Do These
+
+Antipatterns for this phase: read `./templates/reference/antipatterns.md` § Task Plan.
diff --git a/.spec/ARCHITECTURE.md b/.spec/ARCHITECTURE.md
new file mode 100644
index 0000000..7076481
--- /dev/null
+++ b/.spec/ARCHITECTURE.md
@@ -0,0 +1,175 @@
+<!-- generated: 2026-07-27, template: core.md -->
+# EasyP Architecture
+
+## Overview
+
+EasyP is a Go command-line application that uses handlers in `internal/api` to assemble a `core.Core` service from configuration, rules, and infrastructure adapters.
+
+```text
+CLI transport
+cmd/easyp/main.go + urfave/cli
+          |
+          v
+Application wiring
+internal/api handlers and buildCore
+          |
+          v
+Domain operations
+internal/core + internal/rules
+          |
+          v
+Adapters and infrastructure
+internal/adapters + filesystem, Git, local cache, plugins
+```
+
+The primary executable is `cmd/easyp`. It registers command handlers for linting, modules, completion, initialization, generation, schema generation, file listing, configuration validation, and breaking-change checks.
+
+## CLI Transport
+
+Package: `cmd/easyp` and `internal/api`.
+
+| File | Responsibility |
+|------|----------------|
+| `cmd/easyp/main.go` | Creates the `urfave/cli/v2` app, global flags, logger, and handler command list. |
+| `internal/api/interface.go` | Defines the `Handler` interface used to supply `*cli.Command` values. |
+| `internal/api/lint.go` | Resolves paths, loads config, invokes `Core.Lint`, and prints text or JSON issues. |
+| `internal/api/generate.go` | Resolves generation roots and invokes `Core.Generate`. |
+| `internal/api/mod.go` | Defines `mod download`, `mod update`, and `mod vendor`. |
+| `internal/api/breaking_check.go` | Configures the comparison Git ref and invokes `Core.BreakingCheck`. |
+| `internal/api/temporaly_helper.go` | Builds `core.Core` and converts config types into core types. |
+
+Handlers own CLI flags, command-specific exit handling, configuration loading, and output presentation. They use `core.Core` for operations rather than implementing linting, generation, or dependency resolution directly.
+
+## Application Wiring
+
+`buildCore` in `internal/api/temporaly_helper.go` is the composition root for the main commands. It:
+
+1. Builds selected lint rules with `rules.New`.
+2. Opens the project lock file through `adapters/lock_file`.
+3. Resolves `EASYPPATH`, defaulting to `$HOME/.easyp`.
+4. Instantiates storage, module-config, console, and Git-walker adapters.
+5. Combines `deps` with Git repository generation inputs.
+6. Converts configured plugins, inputs, managed-mode rules, and breaking-check settings.
+7. Constructs `core.Core`.
+
+The hard-coded vendor directory passed to the core is `easyp_vendor`. Package-manager behavior is documented in depth in [config/dependency.md](./config/dependency.md).
+
+## Domain Operations
+
+Package: `internal/core`.
+
+| File | Responsibility |
+|------|----------------|
+| `core.go` | Defines `Core`, its injected dependencies, and shared sentinels. |
+| `lint.go` | Downloads dependencies, walks `.proto` files, applies configured rules, and returns issues. |
+| `generate.go` | Resolves imports and inputs, compiles descriptors, applies managed mode, executes plugins, and writes output. |
+| `breaking_check.go` | Reads current and Git-ref proto states, collects entities by package, and compares them. |
+| `download.go`, `update.go`, `get.go`, `vendor.go` | Implement module acquisition, lock updates, cached installation, and vendoring. |
+| `dom.go` | Defines proto-domain representations such as `ProtoInfo`, `Issue`, and `ProtoData`. |
+| `managed_mode.go` | Applies configured file and field option changes to descriptors. |
+
+`Core` depends on consumer-facing interfaces such as `Rule`, `Storage`, `LockFile`, `ModuleConfig`, `CurrentProjectGitWalker`, and `DirWalker`. Concrete adapters are injected by the API layer.
+
+## Adapters and Infrastructure
+
+Package: `internal/adapters`.
+
+| Package | Responsibility |
+|---------|----------------|
+| `adapters/storage` | Manages the cache and installed module trees under `EASYPPATH`. |
+| `adapters/lock_file` | Reads, writes, iterates, and checks `easyp.lock`. |
+| `adapters/repository/git` | Resolves revisions, fetches Git objects, reads repository files, and archives proto sources. |
+| `adapters/go_git` | Provides directory walkers for project Git references. |
+| `adapters/module_config` | Reads supported module layouts from a repository. |
+| `adapters/plugin` | Supplies local, remote, built-in, and command plugin executors. |
+| `adapters/console` | Runs local commands through platform-specific console implementations. |
+| `adapters/prompter` | Provides interactive prompting. |
+
+The `mcp/easypconfig` package is separate from command execution: it registers an MCP tool that describes the `easyp.yaml` schema and generates the schema metadata used by `schema-gen`.
+
+## Directory Structure
+
+```text
+easyp/
+├── cmd/easyp/                 # CLI executable
+├── internal/
+│   ├── api/                   # urfave/cli command handlers and composition root
+│   ├── core/                  # lint, breaking, generation, and module workflows
+│   │   ├── models/            # module, revision, lock, and error value types
+│   │   └── path_helpers/      # path predicates used by core
+│   ├── adapters/              # Git, storage, lockfile, plugin, and console adapters
+│   ├── config/                # easyp.yaml parsing and validation
+│   ├── rules/                 # concrete protobuf lint rules and registry
+│   ├── fs/                    # filesystem walker implementation
+│   ├── logger/                # logger abstraction and implementations
+│   └── flags/                 # shared CLI flags
+├── mcp/easypconfig/           # MCP config-description tool and schema model
+├── schemas/                   # generated JSON Schema artifacts
+├── docs/                      # Vite documentation site
+└── Taskfile.yml               # build, test, lint, schema, and mock tasks
+```
+
+## Key Design Decisions
+
+1. **CLI handlers are thin adapters.**
+   - Each command implements `api.Handler` and returns a `*cli.Command`.
+   - Handlers load configuration and map known errors to process behavior.
+
+2. **Core logic uses injected interfaces.**
+   - `Core.New` accepts storage, lock-file, module-config, console, Git-walker, and rule dependencies.
+   - This supports mocks under `internal/core/mocks` in tests.
+
+3. **Dependency resolution is Git-based.**
+   - `Core.Download` is used before linting, generation, and breaking checks.
+   - Resolved versions and hashes are persisted in `easyp.lock`; installed sources are cached outside the project.
+
+4. **Generation uses protobuf descriptors and plugin executors.**
+   - `Core.Generate` compiles files with `protocompile`.
+   - Plugin choice is selected from command, remote, built-in, or local sources.
+
+5. **Schema metadata has a code source of truth.**
+   - `mcp/easypconfig` reflects a schema model and exposes it through MCP.
+   - Generated files in `schemas/` are refreshed through `task schema:generate`.
+
+## Primary Data Flows
+
+### Lint
+
+```text
+easyp lint
+  -> api.Lint.Action
+  -> config.New(easyp.yaml)
+  -> api.buildCore
+  -> Core.Lint
+  -> Core.Download
+  -> DirWalker.WalkDir(.proto files)
+  -> Core.protoInfoRead + configured Rule.Validate
+  -> []core.IssueInfo
+  -> text or JSON output
+```
+
+### Generation
+
+```text
+easyp generate
+  -> api.Generate.Action
+  -> config.New + api.buildCore
+  -> Core.Generate
+  -> dependency and input resolution
+  -> protocompile.Compiler.Compile
+  -> optional ApplyManagedMode
+  -> plugin.Executor.Execute
+  -> GenerateBucket.DumpToFs
+```
+
+### Breaking Change Check
+
+```text
+easyp breaking --against <ref>
+  -> api.BreakingCheck.Action
+  -> Core.BreakingCheck
+  -> current filesystem walker + Git-ref directory walker
+  -> readProtoFiles and collect
+  -> BreakingChecker.Check
+  -> []core.IssueInfo
+```
diff --git a/.spec/CLI.md b/.spec/CLI.md
new file mode 100644
index 0000000..4804a49
--- /dev/null
+++ b/.spec/CLI.md
@@ -0,0 +1,252 @@
+<!-- generated: 2026-07-27, template: cli.md -->
+# EasyP CLI
+
+## Overview
+
+EasyP is a Protocol Buffers command-line toolkit for projects that lint schemas, generate code, check API compatibility, and manage Git-based dependencies.
+
+Build a local binary:
+
+```bash
+go build -o easyp ./cmd/easyp
+```
+
+Typical project workflow:
+
+```bash
+easyp lint --path .
+easyp generate --path .
+```
+
+The CLI is implemented with `urfave/cli/v2`. Its version is available through the framework-provided `--version` flag; the code does not register a standalone `version` command.
+
+## Command Tree
+
+```text
+easyp
+├── lint (l)                         Lint Protocol Buffer files
+├── generate (g)                     Generate code from Protocol Buffer files
+├── breaking                         Check for API breaking changes
+├── mod (m)                          Manage dependencies
+│   ├── download                     Download modules into the local cache
+│   ├── update                       Update module versions from configuration
+│   └── vendor                       Copy dependency protos into easyp_vendor
+├── init (i)                         Interactively initialize configuration
+├── ls-files (ls)                    List resolved .proto files
+├── validate-config (validate)       Validate an easyp configuration file
+├── schema-gen                       Generate configuration JSON Schema artifacts
+└── completion
+    ├── bash                         Print Bash completion script
+    └── zsh                          Print Zsh completion script
+```
+
+## Commands Reference
+
+### `easyp lint [flags]`
+
+Lints `.proto` files using the project configuration.
+
+| Flag | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--path`, `-p` | string | yes | `.` | Relative path to the directory containing `.proto` files. |
+| `--root`, `-r` | string | no | config-file directory | Root directory used to search for files. |
+
+```bash
+easyp lint --path proto
+easyp lint --path api --format json
+```
+
+Lint issues are written to standard output. Text output has the form `path:line:column:source message (rule)`; JSON output is one JSON object per issue.
+
+### `easyp generate [flags]`
+
+Generates code from `.proto` files according to `easyp.yaml`.
+
+| Flag | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--path`, `-p` | string | yes | `.` | Directory containing `.proto` files. |
+| `--root`, `-r` | string | no | config-file directory | Root directory used to search for files. |
+| `--descriptor_set_out` | string | no | — | Destination for a binary `FileDescriptorSet`. |
+| `--include_imports` | bool | no | `false` | Include transitive dependencies in the descriptor set. |
+
+`--path` can also be supplied through `EASYP_ROOT_GENERATE_PATH`.
+
+```bash
+easyp generate --path proto
+easyp generate --path proto --descriptor_set_out descriptors.pb --include_imports
+```
+
+### `easyp breaking [flags]`
+
+Checks the current Protocol Buffer API for breaking changes relative to a Git ref.
+
+| Flag | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--path`, `-p` | string | yes | `.` | Relative path to the directory containing `.proto` files. |
+| `--against` | string | yes | `master` | Branch or Git ref to compare against. |
+| `--root`, `-r` | string | no | config-file directory | Root directory used to search for files. |
+
+```bash
+easyp breaking --path proto --against main
+```
+
+When the configuration does not set `breaking_check.against_git_ref`, the value of `--against` is used. Findings use the same text and JSON formats as `lint`.
+
+### `easyp mod <subcommand>`
+
+Manages the dependencies defined by the configuration. All subcommands use the current working directory as the project root and take no command-specific flags.
+
+| Subcommand | Description |
+|---|---|
+| `download` | Downloads modules to EasyP's local cache. |
+| `update` | Updates module versions using configured versions. |
+| `vendor` | Copies dependency `.proto` files to `easyp_vendor`. |
+
+```bash
+easyp mod download
+easyp mod update
+easyp mod vendor
+```
+
+For dependency configuration, cache behavior, lockfiles, and vendoring, see [Dependency Management](config/dependency.md).
+
+### `easyp init [flags]`
+
+Interactively creates an EasyP configuration using the available lint rule groups.
+
+| Flag | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--dir`, `-d` | string | yes | `.` | Directory to initialize. |
+
+`--dir` can also be supplied through `EASYP_INIT_DIR`.
+
+```bash
+easyp init --dir .
+```
+
+### `easyp ls-files [flags]`
+
+Lists resolved `.proto` files, including configured inputs and optionally transitive imports.
+
+| Flag | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--include-imports`, `-I` | bool | no | `true` | Include transitive imports. |
+
+```bash
+easyp ls-files
+easyp ls-files --format text
+```
+
+The default output is indented JSON. Text output lists roots, files, and resolution errors.
+
+### `easyp validate-config [flags]`
+
+Validates the configuration file for syntax and required fields.
+
+This command aliases the global configuration flag as a command flag.
+
+```bash
+easyp validate-config --config easyp.yaml
+easyp validate-config --format text
+```
+
+The default output is JSON with `valid`, and when applicable `errors` and `warnings`. Text output begins with `VALID: true` or `VALID: false`.
+
+### `easyp schema-gen [flags]`
+
+Generates versioned and latest JSON Schema artifacts for EasyP configuration.
+
+| Flag | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--out-versioned` | string | no | schemagen default | Path for the versioned schema file. |
+| `--out-latest` | string | no | schemagen default | Path for the latest-schema alias file. |
+
+```bash
+easyp schema-gen
+easyp schema-gen --out-versioned schemas/easyp-config-v1.schema.json --out-latest schemas/easyp-config.schema.json
+```
+
+### `easyp completion <shell>`
+
+Prints a shell completion script to standard output.
+
+| Argument | Allowed values | Description |
+|---|---|---|
+| `<shell>` | `bash`, `zsh` | Select the completion script to print. |
+
+```bash
+easyp completion bash > "$(brew --prefix)/etc/bash_completion.d/easyp"
+easyp completion zsh > "${fpath[1]}/_easyp"
+```
+
+Only Bash and Zsh completion subcommands are registered. The generated scripts use the CLI's Bash-completion support for dynamic suggestions.
+
+## Global Flags
+
+The application registers these global flags:
+
+| Flag | Type | Default | Environment variable | Description |
+|---|---|---|---|---|
+| `--cfg`, `--config` | string | `easyp.yaml` | `EASYP_CFG` | Absolute or relative configuration file path. |
+| `--debug`, `-d` | bool | `false` | `EASYP_DEBUG` | Enables debug-level logs. |
+| `--format`, `-f` | enum | `text` | `EASYP_FORMAT` | Output format: `text` or `json`. Commands can select a different default when the flag is unset. |
+| `--version` | bool | `false` | — | Prints the application version provided by `internal/version`. |
+
+The configuration flag is marked required by the CLI definition while its configured value defaults to `easyp.yaml`. For relative paths, EasyP resolves the configuration file from the current working directory. For `lint`, `generate`, `breaking`, and `ls-files`, the configuration file's directory is the project root unless `--root` is provided.
+
+## Configuration
+
+EasyP reads YAML configuration. The effective configuration path is selected in this order: `--cfg` or `--config`, `EASYP_CFG`, then the default `easyp.yaml`.
+
+| Setting | Flag | Environment variable | Config key | Default |
+|---|---|---|---|---|
+| Configuration path | `--cfg`, `--config` | `EASYP_CFG` | — | `easyp.yaml` |
+| Debug logging | `--debug`, `-d` | `EASYP_DEBUG` | — | `false` |
+| Output format | `--format`, `-f` | `EASYP_FORMAT` | — | `text` |
+| Generate input path | `generate --path`, `-p` | `EASYP_ROOT_GENERATE_PATH` | — | `.` |
+| Init target directory | `init --dir`, `-d` | `EASYP_INIT_DIR` | — | `.` |
+| Module cache path | — | `EASYPPATH` | — | `$HOME/.easyp` |
+
+EasyP uses `easyp_vendor` as its vendor directory.
+
+## Exit Codes
+
+| Code | Meaning |
+|---:|---|
+| `0` | Successful command completion. |
+| `1` | Lint or breaking-change findings; or a module version was not found during `mod download`, `mod update`, or `mod vendor`. |
+| `2` | An imported file cannot be opened, a requested Git ref cannot be found, or the current directory is not a Git repository for `breaking`. |
+| non-zero, implementation/runtime dependent | Other returned errors are passed to `log.Fatal`, which terminates the process after printing the error. |
+
+Invalid flags and arguments are handled by `urfave/cli`; this repository does not define a separate explicit `os.Exit` code for those usage errors.
+
+## I/O Contracts
+
+- **stdin:** No command reads standard input directly.
+- **stdout:** `lint` and `breaking` print findings; `ls-files` and `validate-config` print JSON by default; `completion` prints a script; `schema-gen` writes schema files.
+- **stderr:** The logger writes text logs and errors to standard error. `--debug` includes debug-level log records.
+- **files:** `init` creates configuration through an interactive prompt; `generate` writes configured generator outputs and may write a descriptor set; `mod vendor` writes `easyp_vendor`; `schema-gen` writes its two schema artifacts.
+
+Examples for composition:
+
+```bash
+easyp lint --path proto --format json > lint-issues.json
+easyp ls-files --format json | jq '.files[]'
+easyp completion zsh > "${fpath[1]}/_easyp"
+```
+
+## Development
+
+Run without creating a persistent binary:
+
+```bash
+go run ./cmd/easyp lint --path .
+```
+
+Build the local CLI:
+
+```bash
+go build -o easyp ./cmd/easyp
+```
+
+New commands are added by implementing `api.Handler`, returning a `*cli.Command`, and registering the handler in `cmd/easyp/main.go`.
diff --git a/.spec/CODE_STYLE.md b/.spec/CODE_STYLE.md
new file mode 100644
index 0000000..617eda5
--- /dev/null
+++ b/.spec/CODE_STYLE.md
@@ -0,0 +1,216 @@
+<!-- generated: 2026-07-27, template: core.md -->
+# EasyP Code Style
+
+This document records repository conventions from `AGENTS.md`, `.spec/agent-rules.md`, and existing source. Project rules take precedence over generic Go guidance.
+
+## Layer Structure
+
+```text
+cmd/easyp
+  -> internal/api       CLI handlers and composition
+    -> internal/core    domain workflows and ports
+      -> internal/adapters
+           Git, storage, lock file, plugins, console
+
+internal/config         external easyp.yaml model and validation
+internal/rules          core.Rule implementations
+mcp/easypconfig         config schema metadata and MCP exposure
+```
+
+| Layer | Convention |
+|-------|------------|
+| CLI | Implement `api.Handler`, build a `*cli.Command`, parse flags, call core, and map known CLI outcomes. |
+| API | Construct concrete adapters and convert `config` values into core values in `buildCore`. |
+| Core | Define consumer-side interfaces and operate through them; avoid importing concrete adapter packages where a port exists. |
+| Adapters | Implement filesystem, Git, storage, lockfile, plugin, console, and prompt mechanics. |
+| Rules | Implement `core.Rule` in a dedicated source file with a colocated test file. |
+| Config/schema | Keep user-facing configuration validation in `internal/config` and schema metadata in `mcp/easypconfig`. |
+
+## Public Types and Tags
+
+Exported types have Go doc comments that begin with the type name. Configuration structs use `json` and `yaml` tags:
+
+```go
+type Plugin struct {
+	Name    string   `json:"name,omitempty" yaml:"name,omitempty"`
+	Remote  string   `json:"remote,omitempty" yaml:"remote,omitempty"`
+	Path    string   `json:"path,omitempty" yaml:"path,omitempty"`
+	Command []string `json:"command,omitempty" yaml:"command,omitempty"`
+
+	Out         string     `json:"out" yaml:"out"`
+	Opts        PluginOpts `json:"opts,omitempty" yaml:"opts,omitempty"`
+	WithImports bool       `json:"with_imports,omitempty" yaml:"with_imports,omitempty"`
+}
+```
+
+Use snake_case YAML and JSON field names where tags are required. Keep configuration types unexported when their scope is local; exported domain entities and adapter implementations use exported names.
+
+## Conversion Boundaries
+
+The API layer is the explicit conversion boundary from configuration to core:
+
+```go
+core.Plugin{
+	Source: core.PluginSource{
+		Name:    p.Name,
+		Remote:  p.Remote,
+		Path:    p.Path,
+		Command: p.Command,
+	},
+	Out:         p.Out,
+	Options:     p.Opts,
+	WithImports: p.WithImports,
+}
+```
+
+`buildCore` also converts managed-mode rules and divides generation inputs into local directory and Git-repository collections. Core types therefore do not use YAML or JSON tags for the configuration representation.
+
+## Naming Conventions
+
+| Subject | Convention |
+|---------|------------|
+| Go source | Use lowercase, underscore-separated file names. |
+| Tests | Place tests beside the implementation as `<file>_test.go`. |
+| Lint rules | Use `internal/rules/<rule>.go` plus `<rule>_test.go`. |
+| Packages | Use short lower-case package names; adapter subpackages describe a capability. |
+| Interfaces | Use descriptive names without an `I` prefix. |
+| Enums | Reserve the zero value with `_ = iota` when defining enums. |
+| Rule names | `core.GetRuleName` converts concrete rule type names to upper snake case. |
+| Struct tags | Use snake_case field names for YAML and environment-facing data. |
+
+Examples of rule-file naming include `rpc_pascal_case.go`, `package_defined.go`, and `enum_first_value_zero.go`.
+
+## Interface Conventions
+
+Interfaces are generally defined by the package that consumes them. `internal/core` owns ports such as `Rule`, `Storage`, `LockFile`, `ModuleConfig`, `CurrentProjectGitWalker`, and `Repo`.
+
+```go
+type Rule interface {
+	Message() string
+	Validate(ProtoInfo) ([]Issue, error)
+}
+
+type Executor interface {
+	Execute(ctx context.Context, plugin Info, request *pluginpb.CodeGeneratorRequest) (*pluginpb.CodeGeneratorResponse, error)
+	GetName() string
+}
+```
+
+Rules:
+
+- Put `context.Context` first in interface and function signatures.
+- Put `error` last in results.
+- Do not prefix interface names with `I`.
+- Prefer passing a small consumer-owned interface over a concrete adapter.
+- Regenerate mocks with `task mocks` when core or storage interfaces change.
+
+## Error Propagation
+
+Wrap returned errors at each failing call site using the called function or method name only:
+
+```go
+cfg, err := config.New(ctx.Context, configPath)
+if err != nil {
+	return fmt.Errorf("config.New: %w", err)
+}
+```
+
+```go
+if err := c.Download(ctx); err != nil {
+	return nil, fmt.Errorf("c.Download: %w", err)
+}
+```
+
+Use `errors.Is` for sentinels and `errors.As` for typed errors. Examples in API handlers include `core.ErrEmptyInputFiles`, `models.ErrVersionNotFound`, `*core.OpenImportFileError`, and `*core.GitRefNotFoundError`.
+
+Domain and package-manager sentinels belong in `internal/core` or `internal/core/models`; do not add duplicate sentinels in adapters or API handlers. Detailed error catalog documentation belongs in [ERRORS.md](./ERRORS.md).
+
+## Resource Closing
+
+Do not use a bare `defer x.Close()`. Wrap close calls and explicitly handle or intentionally discard the returned error:
+
+```go
+defer func() {
+	_ = cfgFile.Close()
+}()
+```
+
+When the close failure is operationally useful, `Core.close` logs the path and error with the repository logger.
+
+## Imports
+
+Order imports as standard library, third-party packages, then project packages. Separate groups with blank lines:
+
+```go
+import (
+	"context"
+	"fmt"
+
+	"github.com/urfave/cli/v2"
+
+	"github.com/easyp-tech/easyp/internal/config"
+	"github.com/easyp-tech/easyp/internal/core"
+)
+```
+
+Use project formatting and `gci`/`golangci-lint` rather than manually preserving an invalid import order.
+
+## Comments and Documentation
+
+- Write Go comments and Godoc in English.
+- Begin exported-symbol documentation with that symbol's name.
+- Put explanatory comments above `if`, `for`, and `return` lines rather than inline.
+- Keep generated schema JSON out of manual edits.
+
+## Testing Organization
+
+| Test target | Location and pattern |
+|-------------|----------------------|
+| A core behavior | `internal/core/<file>_test.go` |
+| A lint rule | `internal/rules/<rule>_test.go` |
+| An adapter | Its adapter package with `<file>_test.go` |
+| A mocked core port | `internal/core/mocks/` |
+| A mocked storage port | `internal/adapters/storage/mocks/` |
+
+Tests use `testify`. Use `require` for fatal preconditions and `assert` for non-fatal assertions. Table-driven tests require a `name` field. Call `t.Parallel()` at the top level and inside each `t.Run`, and create dependencies per case instead of sharing mutable mocks.
+
+Run relevant tests after behavior changes. The repository's comprehensive task uses race detection:
+
+```sh
+task test
+```
+
+## Logging
+
+The CLI initializes an `slog` text handler and stores the project logger in `cli.App.Metadata`. API handlers retrieve it with `getLogger`; core and adapters receive it as a dependency.
+
+| Layer | Typical use |
+|-------|-------------|
+| CLI/API | Log terminal failures before calling `os.Exit` for recognized conditions. |
+| Core | Log operation start/completion, debug resolution data, and warnings for recoverable conditions. |
+| Adapters | Log infrastructure-relevant actions through the injected logger. |
+
+Use structured attributes such as `slog.String`, `slog.Int`, and `slog.Any`. Existing generation and breaking flows pass `context.Context` to logging methods. No project-wide correlation-ID convention is defined in the inspected code.
+
+## Concurrency
+
+No project-wide goroutine, worker-pool, channel, or synchronization pattern is established in the inspected core workflows. Methods accept and check `context.Context` during filesystem walks, compilation, and executor calls; preserve that cancellation propagation when extending these paths.
+
+## Quick Reference
+
+| Aspect | API | Core | Adapters |
+|--------|-----|------|----------|
+| Main responsibility | CLI translation and composition | Domain workflows and ports | Concrete infrastructure |
+| Config representation | `internal/config` values | Converted core values | Adapter-specific values |
+| Error handling | Map known outcomes; wrap unknown failures | Wrap port failures; expose core sentinels | Wrap OS/Git/plugin failures |
+| Dependency direction | Imports core and adapters | Depends on interfaces | Implements core-facing behavior |
+| Tests | Handler-focused | Workflow and model tests | Adapter behavior tests |
+
+## Tooling Rules
+
+- Format Go code with `gofmt` and run `task lint` when appropriate.
+- Use `task build`, `task test`, `task quality`, and `task schema:check` as defined in `Taskfile.yml`.
+- Update `mcp/easypconfig` and/or `internal/config` before regenerating schema files with `task schema:generate`.
+- Do not hand-edit `schemas/easyp-config-v1.schema.json` or `schemas/easyp-config.schema.json`.
+- Do not commit generated local binaries, `coverage.out`, `docs/node_modules`, secrets, or credentials.
+- Dependency and vendoring conventions are documented in [config/dependency.md](./config/dependency.md); the vendor directory is `easyp_vendor`.
diff --git a/.spec/DEPLOYMENT.md b/.spec/DEPLOYMENT.md
new file mode 100644
index 0000000..fa524bd
--- /dev/null
+++ b/.spec/DEPLOYMENT.md
@@ -0,0 +1,154 @@
+<!-- generated: 2026-07-27, template: deployment.md -->
+# Deployment
+
+## Overview
+
+EasyP is a Go command-line toolkit distributed through release automation and
+documented installation channels, rather than deployed as a long-running web
+service.
+
+```text
+pull request / push to main
+  → GitHub Actions tests
+  → release tag vX.Y.Z
+  → GitHub Actions release + documentation build
+  → published release artifacts and container images
+```
+
+The release workflow accepts stable semantic-version tags in the form
+`v<major>.<minor>.<patch>` only. Pre-release suffixes are explicitly rejected.
+
+## Environments
+
+| Environment | URL / Host | Purpose | Branch / Tag | Auto-deploy |
+|---|---|---|---|---|
+| Local CLI | N/A | Build, test, and install the command-line tool | Local checkout | N/A |
+| Staging | N/A | No staging deployment is configured | N/A | N/A |
+| Production service | N/A | No long-running production service is configured | N/A | N/A |
+| Release distribution | GitHub Releases, Homebrew, Docker, npm | Install EasyP artifacts | `vX.Y.Z` tag | Yes |
+
+The repository README documents Homebrew installation, `go install`, Docker
+image use, npm installation, and binary installation from GitHub Releases.
+It does not define a service host, a staging URL, or runtime environment
+configuration.
+
+## Docker
+
+The checked-in `Taskfile.yml` includes container targets for `easyp/base` and
+`easyp/lint`:
+
+```sh
+task docker_base
+task docker_lint
+task docker_push
+task docker
+```
+
+`task docker` obtains `GIT_TAG` from the latest Git tag, builds both images,
+tags them as `latest` and with that tag, then pushes them.
+
+The Taskfile expects Dockerfiles at `Docker/base/Dockerfile` and
+`Docker/lint/Dockerfile`. Those paths are not present in this checkout, so
+their base images, build stages, build arguments beyond
+`EASYP_BASE_VERSION=latest`, exposed ports, entrypoints, and image-size
+optimizations cannot be documented from the allowed source files.
+
+No Docker Compose configuration is present. Service definitions, volume
+mounts, and network configuration are therefore N/A.
+
+## CI/CD Pipeline
+
+### `.github/workflows/tests.yml`
+
+- **Trigger:** pushes to `main` and pull requests targeting any branch.
+- **Runner:** `ubuntu-latest`.
+- **Steps:** check out the repository; install Go 1.24; install Task 3.x;
+  run `task init`; run `task test`.
+- **Secrets required:** `GITHUB_TOKEN`, supplied to the Task setup action.
+
+`task init` installs the local Go development tools and resolves Go
+dependencies. `task test` runs the test suite through `gotestsum` with race
+detection and writes `coverage.out`.
+
+### `.github/workflows/release.yml`
+
+- **Trigger:** push of a stable `vX.Y.Z` tag.
+- **Runner:** `ubuntu-latest` with Go 1.24.
+- **Permissions:** write access to repository contents and packages.
+- **Steps:** full-history checkout; QEMU setup; Docker Buildx setup; login to
+  GitHub Container Registry; login to Docker Hub; install Go; validate the
+  tag; run GoReleaser with `release --clean --timeout=90m`.
+- **Secrets required:** `GITHUB_TOKEN`, `DOCKERHUB_USERNAME`,
+  `DOCKERHUB_TOKEN`, and `GORELEASER_AUTH_TOKEN`.
+- **Variable used:** `DOCKERHUB_IMAGE`, with `easyp/easyp` as the workflow
+  fallback value.
+
+The workflow's QEMU and Buildx setup supports the GoReleaser release process;
+the exact artifact list and image platforms are not specified by the allowed
+sources.
+
+### `.github/workflows/docs.yml`
+
+- **Trigger:** push of a stable `vX.Y.Z` tag.
+- **Runner:** `ubuntu-latest`.
+- **Steps:** full-history checkout; install Node.js 20; install dependencies
+  in `docs`; build VitePress; verify English and Russian search indexes;
+  detect generated documentation changes; commit and push changed `docs/dist/`
+  files to the repository default branch.
+- **Secrets required:** `GITHUB_TOKEN`.
+
+The workflow reports that an external service pulls the changes for
+`easyp.tech`; that external deployment is not configured in this repository.
+
+### `.github/workflows/relator.yml`
+
+This workflow is not a deployment pipeline. It sends Telegram notifications
+when issues or pull requests are opened or reopened. It requires
+`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, and `GITHUB_TOKEN`.
+
+## Rollout Strategy
+
+N/A. EasyP has no configured application-service rollout, Kubernetes
+deployment, blue-green deployment, canary deployment, or zero-downtime
+strategy in the allowed sources. Distribution occurs by publishing a stable
+release tag through the release workflow.
+
+## Health Checks
+
+N/A. EasyP is a CLI, and no HTTP health, readiness, liveness, or startup probe
+is defined in the allowed sources.
+
+## Rollback Procedure
+
+No automated rollback procedure is defined. For a faulty published CLI
+release, the repository documentation and workflow sources do not specify an
+artifact withdrawal or rollback command. The actionable repository-level
+procedure is to correct the issue and publish a new stable `vX.Y.Z` tag through
+the release workflow.
+
+## Secrets Management
+
+| Secret / Variable | Purpose | Where Set |
+|---|---|---|
+| `GITHUB_TOKEN` | GitHub API, package-registry, checkout, and documentation workflow authentication | GitHub Actions |
+| `GORELEASER_AUTH_TOKEN` | GoReleaser release authentication | GitHub Actions secret |
+| `DOCKERHUB_USERNAME` | Docker Hub login username | GitHub Actions secret |
+| `DOCKERHUB_TOKEN` | Docker Hub login token | GitHub Actions secret |
+| `DOCKERHUB_IMAGE` | Docker Hub image name override | GitHub Actions variable |
+| `TELEGRAM_BOT_TOKEN` | Relator notification authentication | GitHub Actions secret |
+| `TELEGRAM_CHAT_ID` | Relator notification destination | GitHub Actions variable |
+
+Secret rotation, vault integration, and runtime secret injection are not
+documented in the allowed sources.
+
+## Infrastructure Requirements
+
+N/A. No infrastructure resource requirements, replicas, storage allocations,
+or orchestration manifests are configured for EasyP in the allowed sources.
+
+## Monitoring and Alerts
+
+N/A for runtime monitoring because EasyP has no deployed service in this
+repository. GitHub Actions workflow results are the available build and release
+execution record. The Relator workflow provides issue and pull-request
+notifications, but no monitoring dashboard or alert policy is configured.
diff --git a/.spec/DOMAIN.md b/.spec/DOMAIN.md
new file mode 100644
index 0000000..e765d5d
--- /dev/null
+++ b/.spec/DOMAIN.md
@@ -0,0 +1,264 @@
+<!-- generated: 2026-07-27, template: core.md -->
+# EasyP Domain Model
+
+EasyP operates on Protocol Buffers source trees, lint findings, generation inputs and plugins, and Git-backed dependency modules. The core domain types are defined primarily in `internal/core`, `internal/core/models`, and `internal/config`.
+
+## Core Proto Entities
+
+### `ProtoInfo`
+
+Defined in `internal/core/dom.go`. It is the parsed view of one protobuf source file and the imported files available to it.
+
+```go
+type ProtoInfo struct {
+	Path                 string
+	Info                 *unordered.Proto
+	ProtoFilesFromImport map[ImportPath]*unordered.Proto
+}
+```
+
+- `Path` is the source file path.
+- `Info` is the parsed protobuf syntax tree.
+- `ProtoFilesFromImport` maps import paths to parsed imported files.
+
+### `Issue` and `IssueInfo`
+
+Defined in `internal/core/dom.go`. Linting and breaking checks emit these values.
+
+```go
+type Issue struct {
+	Position   meta.Position
+	SourceName string
+	Message    string
+	RuleName   string
+}
+
+type IssueInfo struct {
+	Issue
+	Path string
+}
+```
+
+- `Position` identifies the protobuf source location.
+- `SourceName` records the checked source.
+- `Message` is supplied by the rule or checker.
+- `RuleName` is the upper-snake-case rule identity.
+- `Path` is added when the issue is associated with a walked file.
+
+### `ProtoData` and `Collection`
+
+Breaking checks collect parsed files into a package-keyed representation.
+
+```go
+type Collection struct {
+	Imports  map[ImportPath]Import
+	Services map[string]Service
+	Messages map[string]Message
+	OneOfs   map[string]OneOf
+	Enums    map[string]Enum
+}
+
+type ProtoData map[PackageName]*Collection
+```
+
+Each collection groups proto declarations for one `PackageName`. Nested messages, oneofs, and enums retain a dotted parent path such as `MainMessage.NestedMessage`.
+
+### Declaration Wrappers
+
+`internal/core/dom.go` wraps parser nodes with their source context:
+
+| Type | Context retained |
+|------|------------------|
+| `Import` | Proto file path, package name, and parsed import. |
+| `Service` | Proto file path, package name, and parsed service. |
+| `Message` | Message path, proto file path, package name, and parsed message. |
+| `OneOf` | Oneof path, proto file path, package name, and parsed oneof. |
+| `Enum` | Enum path, proto file path, package name, and parsed enum. |
+
+## Rule Model
+
+### `Rule`
+
+Every lint rule implements the core interface:
+
+```go
+type Rule interface {
+	Message() string
+	Validate(ProtoInfo) ([]Issue, error)
+}
+```
+
+`internal/rules/builder.go` creates selected rules using the configured `lint.use`, `lint.except`, and `lint.ignore_only` values. The named groups are `MINIMAL`, `BASIC`, `DEFAULT`, `COMMENTS`, and `UNARY_RPC`.
+
+### Ignore Model
+
+The core accepts:
+
+- `ignore []string` for paths skipped while walking.
+- `ignoreOnly map[string][]string` for paths skipped for a specific rule.
+- Comment directives when `allow_comment_ignores` is enabled.
+
+`Core.CheckIsIgnored` recognizes both `nolint:<RULE_NAME>` and the backward-compatible `buf:lint:ignore <RULE_NAME>` form.
+
+## Module and Dependency Entities
+
+### `Module`
+
+Defined in `internal/core/models/module.go`.
+
+```go
+type Module struct {
+	Name    string
+	Version RequestedVersion
+}
+```
+
+`Name` is a remote repository path. `Version` comes from a `repo[@version]` dependency declaration. When omitted, it is `RequestedVersion("")`, exposed as the `Omitted` constant.
+
+### Version Values
+
+```go
+type ModuleHash string
+type RequestedVersion string
+
+type GeneratedVersionParts struct {
+	Datetime   string
+	CommitHash string
+}
+```
+
+`RequestedVersion` can identify an explicit request or parse a generated version in the `v0.0.0-<datetime>-<commit>` form. Its methods are `GetParts`, `IsGenerated`, and `IsOmitted`.
+
+### Resolved Module State
+
+```go
+type Revision struct {
+	CommitHash string
+	Version    string
+}
+
+type LockFileInfo struct {
+	Name    string
+	Version string
+	Hash    ModuleHash
+}
+
+type InstalledModuleInfo struct {
+	ModuleName      string
+	Hash            ModuleHash
+	RevisionVersion string
+}
+```
+
+- `Revision` represents the commit and resulting version selected from Git.
+- `LockFileInfo` is the persisted dependency lock entry.
+- `InstalledModuleInfo` describes a cached installed module and its directory hash.
+
+### Module Configuration
+
+```go
+type ModuleConfig struct {
+	Directories  []string
+	Dependencies []Module
+}
+```
+
+It describes directories containing protobuf files and dependencies discovered in a remote module configuration. See [config/dependency.md](./config/dependency.md) for the full dependency resolution and installation flow.
+
+## Generation Model
+
+### Plugin and Input
+
+Core generation receives already-converted values:
+
+```go
+type PluginSource struct {
+	Name    string
+	Remote  string
+	Path    string
+	Command []string
+}
+
+type Plugin struct {
+	Source      PluginSource
+	Out         string
+	Options     map[string][]string
+	WithImports bool
+}
+```
+
+Plugin execution source selection is command first, then remote, then a built-in plugin absent from `PATH`, and otherwise local execution.
+
+```go
+type InputGitRepo struct {
+	URL          string
+	SubDirectory string
+	Root         string
+}
+
+type InputFilesDir struct {
+	Path string
+	Root string
+}
+
+type Inputs struct {
+	InputFilesDir []InputFilesDir
+	InputGitRepos []InputGitRepo
+}
+```
+
+`Query` holds resolved import directories, plugins, and protobuf files used to create a `CodeGeneratorRequest`.
+
+### Managed Mode
+
+The configuration model contains:
+
+```go
+type ManagedMode struct {
+	Enabled bool
+	Disable []ManagedDisableRule
+	Override []ManagedOverrideRule
+}
+```
+
+Disable rules can match a module, protobuf package, path, file option, field option, or field. Override rules set a file or field option value and can be scoped by module, package, path, or field.
+
+The configuration validator requires valid option combinations: a rule cannot use both file and field options, and a field scope requires a field option.
+
+## Configuration Model
+
+The top-level `internal/config.Config` has four sections:
+
+```go
+type Config struct {
+	Lint          LintConfig
+	Deps          []string
+	Generate      Generate
+	BreakingCheck BreakingCheck
+}
+```
+
+Configuration parsing expands environment variables before YAML unmarshalling and calls `Config.Validate`. A generation plugin must have exactly one source among `name`, `remote`, `path`, and `command`.
+
+The MCP schema model and generated schema files describe the same user-facing configuration domain. Schema changes originate in `mcp/easypconfig` and/or `internal/config`, not directly in `schemas/`.
+
+## Business Errors
+
+For the full business error catalog (codes, mappings, and retry guidance) see [ERRORS.md](./ERRORS.md). That document is generated separately.
+
+Key sentinels currently include:
+
+| Sentinel | Defined in | Meaning |
+|----------|------------|---------|
+| `core.ErrInvalidRule` | `internal/core` | Configured lint rule is not known. |
+| `core.ErrRepositoryDoesNotExist` | `internal/core` | A required project repository is absent. |
+| `core.ErrEmptyInputFiles` | `internal/core` | Generation selected no protobuf input files. |
+| `models.ErrVersionNotFound` | `internal/core/models` | A requested module version cannot be resolved. |
+| `models.ErrFileNotFound` | `internal/core/models` | A module configuration file was not found. |
+| `models.ErrModuleNotInstalled` | `internal/core/models` | An installed module directory is absent. |
+| `models.ErrModuleInfoFileNotFound` | `internal/core/models` | Cached install metadata is absent. |
+| `models.ErrHashDependencyMismatch` | `internal/core/models` | Cached module contents do not match the expected hash. |
+| `models.ErrModuleNotFoundInLockFile` | `internal/core/models` | A module has no lock-file entry. |
+| `models.ErrRequestedVersionNotGenerated` | `internal/core/models` | A version cannot be parsed as a generated version. |
+
+The CLI additionally uses command-level sentinels such as `api.ErrHasLintIssue` and `api.ErrBreakingCheckIssue` to produce exit code 1 for findings.
diff --git a/.spec/ERRORS.md b/.spec/ERRORS.md
new file mode 100644
index 0000000..cbe780f
--- /dev/null
+++ b/.spec/ERRORS.md
@@ -0,0 +1,168 @@
+<!-- generated: 2026-07-27, template: errors.md -->
+# Error Handling
+
+EasyP is a command-line application. It does not expose an HTTP or gRPC
+server API, so it has no HTTP status mapping, gRPC status mapping, or
+server-side JSON error envelope. In this document, the API layer means the
+command handlers in `internal/api`.
+
+## Error Architecture
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│ CLI command layer: internal/api                              │
+│ Prints lint, breaking, or config-validation results.         │
+│ Maps selected errors to process exit code 1 or 2.             │
+├─────────────────────────────────────────────────────────────┤
+│ Application layer: internal/core                             │
+│ Returns sentinel and typed domain errors.                    │
+│ Adds operation context using fmt.Errorf("operation: %w").    │
+├─────────────────────────────────────────────────────────────┤
+│ Adapter layer: internal/adapters                             │
+│ Converts selected filesystem and Git conditions to sentinels.│
+│ Wraps other infrastructure errors with operation context.    │
+├─────────────────────────────────────────────────────────────┤
+│ Infrastructure                                               │
+│ Filesystem, Git, subprocess, plugin, parser, and YAML errors│
+└─────────────────────────────────────────────────────────────┘
+```
+
+Errors normally propagate upward as Go `error` values. Core and adapters use
+`errors.Is` to identify sentinels without discarding wrapped context; CLI
+handlers use `errors.Is` and `errors.As` where they provide specific behavior.
+Unhandled errors are returned to `main`, where `app.Run` failures are passed to
+`log.Fatal` (`cmd/easyp/main.go`), terminating the process with exit code 1.
+
+`errExit` in `internal/api/temporaly_helper.go` is the explicit user-error
+path: it logs at error level and calls `os.Exit` with the supplied code. It is
+currently used by the `lint` and `breaking` command handlers.
+
+## Core and Model Sentinel Catalog
+
+The following sentinels are defined by `internal/core` and
+`internal/core/models`. They have no machine-readable error codes beyond their
+Go identifiers and message text.
+
+| Name | Defined in | Meaning | CLI-specific mapping |
+|---|---|---|---|
+| `ErrInvalidRule` | `internal/core/core.go` | A configured lint rule is not recognized. | No dedicated mapping; returned error ultimately exits 1. |
+| `ErrRepositoryDoesNotExist` | `internal/core/core.go` | A required Git repository cannot be opened. | `breaking` logs “Repository does not exist in current directory” and exits 2. |
+| `ErrEmptyInputFiles` | `internal/core/core.go` | Generation resolved no input `.proto` files. | `generate` logs a warning and returns success (0). |
+| `ErrRootOutsideProject` | `internal/core/breaking_check.go` | The breaking-check working root lies outside its Git repository. | No dedicated mapping; returned error ultimately exits 1. |
+| `ErrVersionNotFound` | `internal/core/models/errors.go` | A requested dependency version or revision cannot be found. | `mod download`, `mod update`, and `mod vendor` exit 1 directly. |
+| `ErrFileNotFound` | `internal/core/models/errors.go` | A Git-backed file cannot be read. | Used internally as an expected absence by module-config reading; otherwise propagates. |
+| `ErrModuleNotInstalled` | `internal/core/models/errors.go` | An installed module directory is absent while calculating its hash. | No dedicated mapping; returned error ultimately exits 1. |
+| `ErrModuleInfoFileNotFound` | `internal/core/models/errors.go` | Cached installed-module metadata is absent. | `Core.Get` treats it as a cache miss and installs the module. |
+| `ErrHashDependencyMismatch` | `internal/core/models/errors.go` | Cached module contents do not match the lock-file hash. | No dedicated mapping; returned error ultimately exits 1. |
+| `ErrRequestedVersionNotGenerated` | `internal/core/models/module.go` | A version is not in EasyP’s generated-version form. | Returned by `RequestedVersion.GetParts`; no CLI-specific mapping. |
+| `ErrModuleNotFoundInLockFile` | `internal/core/models/lock_file_info.go` | A module has no lock-file entry. | `Core.Get` accepts it when checking an installed module; `Core.Download` also handles it as expected absence. |
+
+## CLI Outcome Sentinels and Typed Errors
+
+`internal/api` also defines command-control sentinels. They represent expected
+command outcomes rather than reusable core-domain failures.
+
+| Name or type | Defined in | Exit code / user-facing behavior |
+|---|---|---|
+| `ErrHasLintIssue` | `internal/api/lint.go` | Lint issues are printed to stdout, then `lint` exits 1. |
+| `ErrHasValidateIssue` | `internal/api/lint.go` | `validate-config` returns it after outputting an invalid result; `main` logs it and exits 1. |
+| `ErrBreakingCheckIssue` | `internal/api/breaking_check.go` | Breaking issues are printed to stdout, then `breaking` exits 1. |
+| `ErrPathNotAbsolute` | `internal/api/temporaly_helper.go` | Returned if the EasyP cache path cannot be made absolute; no dedicated output mapping. |
+| `*core.OpenImportFileError` | `internal/core/dom.go` | `lint` and `breaking` log “Cannot import file” with `file name`, then exit 2. |
+| `*core.GitRefNotFoundError` | `internal/core/dom.go` | `breaking` logs “Cannot find git ref” with `ref`, then exits 2. |
+
+The typed errors carry the field needed for user-facing logging:
+`OpenImportFileError.FileName` and `GitRefNotFoundError.GitRef`. They are
+matched with `errors.As`, not a sentinel identity check.
+
+## Exit Code Behavior
+
+| Exit code | When it is used | Observable behavior |
+|---|---|---|
+| `0` | Successful command execution; also `generate` with `ErrEmptyInputFiles`. | Normal output, or a warning for empty generation input. |
+| `1` | Lint findings, breaking-change findings, dependency version not found, and unhandled returned errors. | Findings are printed for lint/breaking; other errors follow their handler or `log.Fatal` path. |
+| `2` | Selected invalid runtime conditions in `lint` and `breaking`. | `errExit` writes a structured `slog` error to stderr with an actionable message and attributes. |
+
+There is no central exit-code mapper. Each command handler decides whether to
+return an error, call `os.Exit(1)`, or call `errExit(..., 2, ...)`. Therefore,
+new commands should document any explicit exit behavior they introduce.
+
+## Wrapping Convention
+
+The project convention is to add the failing operation as a prefix and retain
+the original error with `%w`. `Core.Get` provides the representative pattern:
+
+```go
+installedModuleInfo, err = c.storage.ReadInstalledModuleInfo(cacheDownloadPaths)
+if err != nil {
+    if !errors.Is(err, models.ErrModuleInfoFileNotFound) {
+        return fmt.Errorf("c.storage.ReadInstalledModuleInfo: %w", err)
+    }
+    needToInstall = true
+}
+```
+
+This pattern is in `internal/core/get.go`. It first identifies an expected
+sentinel, then wraps every other adapter failure with the core operation that
+failed. The `breaking` core implementation applies the same rule at method
+boundaries, for example `fmt.Errorf("c.Download: %w", err)` in
+`internal/core/breaking_check.go`.
+
+At the CLI boundary, commands add their own context before returning errors,
+such as `fmt.Errorf("config.New: %w", err)` and
+`fmt.Errorf("generator.Generate: %w", err)`. Commands must preserve `%w` when
+the caller needs to inspect a sentinel or typed error using `errors.Is` or
+`errors.As`.
+
+## User-Facing Output Formats
+
+EasyP does not serialize a general error response object. Output is
+command-specific:
+
+- `lint` and `breaking` print each `core.IssueInfo` to stdout. Text output is
+  `path:line:column:source message (rule)`; JSON output encodes one issue per
+  line in `internal/api/lint.go`.
+- `validate-config` prints a result, not an error envelope. JSON output has
+  `valid`, optional `errors`, and optional `warnings`; every validation issue
+  contains `code`, `message`, optional `line`, `column`, and `severity`.
+- In text mode, `validate-config` prints `VALID: true|false`, followed by
+  `ERRORS` and/or `WARNINGS` rows when present.
+- Explicit `errExit` cases are logged to stderr through the configured
+  text-format `slog` handler.
+
+`config.ValidationIssue` is a typed diagnostic record, not an `error`
+implementation. `ValidateRaw` assigns `envsubst_error` when environment
+variable expansion fails and `yaml_validation` for schema-collector findings.
+Warnings alone leave `valid` true; only `SeverityError` makes validation fail.
+
+## Sentinel Errors Versus Error Types
+
+Use a sentinel when identity alone controls behavior. The core model errors
+are compared with `errors.Is`, including `ErrVersionNotFound` in `mod` commands
+and `ErrModuleInfoFileNotFound` in the cache-miss path.
+
+Use a typed error when the caller needs structured context to present an
+actionable diagnostic. `OpenImportFileError` and `GitRefNotFoundError` are the
+current examples and are inspected with `errors.As`.
+
+No project-defined error interface was found. The code relies on Go’s standard
+`error` interface plus `errors.Is` and `errors.As`.
+
+## Retry Policy
+
+No generic retry, backoff, or retryability classification is implemented in
+`internal/`. Git, filesystem, plugin, and remote-executor failures propagate to
+their callers. Callers should not assume retry behavior from a sentinel unless
+they add and document it explicitly.
+
+## Error Logging
+
+The application initializes a text `slog` logger that writes to stderr in
+`cmd/easyp/main.go`; debug logging is enabled only with the debug flag. Core
+operations log useful operational context, for example dependency `module` and
+`version` in `Core.Get`.
+
+Log a failure at the boundary that terminates or meaningfully handles it.
+`errExit` is the current terminal error logger. Core and adapter layers should
+generally wrap errors with context rather than log the same failure again,
+which avoids duplicate user-visible error records.
diff --git a/.spec/PACKAGES.md b/.spec/PACKAGES.md
new file mode 100644
index 0000000..399f934
--- /dev/null
+++ b/.spec/PACKAGES.md
@@ -0,0 +1,197 @@
+<!-- generated: 2026-07-27, template: core.md -->
+# EasyP Package Reference
+
+This reference groups source packages by their role. Generated mocks are omitted except where they establish a test seam.
+
+## Executable
+
+### `cmd/easyp`
+**CLI entry point** — creates the EasyP `urfave/cli/v2` application and installs its commands.
+
+| File | Description |
+|------|-------------|
+| `main.go` | Initializes `slog`-backed logging, sets global flags, registers API handlers, and runs the app. |
+
+The command list is created from values implementing `internal/api.Handler`.
+
+## API Layer
+
+### `internal/api`
+**Command wiring** — maps CLI commands and flags to configuration parsing, `core.Core` construction, execution, and CLI output.
+
+| File | Description |
+|------|-------------|
+| `interface.go` | Declares the `Handler` command-provider interface. |
+| `lint.go` | Implements `lint`, issue output formats, and lint exit behavior. |
+| `generate.go` | Implements `generate` and root resolution. |
+| `breaking_check.go` | Implements `breaking` and its Git reference handling. |
+| `mod.go` | Implements the `mod` command and module subcommands. |
+| `init.go` | Implements project initialization. |
+| `validate.go` | Implements configuration validation. |
+| `ls_files.go` | Implements listing installed dependency files. |
+| `schema_gen.go` | Implements config schema generation. |
+| `completion.go` | Implements shell completion support. |
+| `temporaly_helper.go` | Provides logger access, `buildCore`, managed-mode conversion, and cache-path resolution. |
+
+The package instantiates adapters and translates `config.Config` into the core's dependency types.
+
+## Application and Domain Layer
+
+### `internal/core`
+**Business workflows** — performs linting, protobuf compilation and generation, dependency management, and breaking-change analysis.
+
+| File group | Description |
+|------------|-------------|
+| `core.go`, `dom.go` | Defines `Core`, its ports, proto representations, rules, issues, and plugin/input values. |
+| `lint.go`, `check_lint_ignore.go` | Walks local proto files, reads imports, and applies rules and ignore behavior. |
+| `breaking_check.go`, `breaking_checker.go` | Loads current and historical proto models and checks compatibility. |
+| `generate.go`, `generate_bucket.go`, `generate_insertion_point.go` | Builds descriptors, invokes plugins, stages generated files, and supports insertion points. |
+| `managed_mode.go` | Applies configured descriptor option changes. |
+| `download.go`, `update.go`, `get.go`, `vendor.go` | Resolve, install, lock, update, and vendor modules. |
+| `module_path.go`, `proto_info_read.go`, `fs.go` | Resolve module paths, parse proto imports, and define filesystem ports. |
+| `init.go`, `init_template.go` | Provide project initialization behavior. |
+| `instruction_parser.go` | Parses protobuf option/instruction names. |
+
+The package owns consumer-side interfaces including `Storage`, `LockFile`, `ModuleConfig`, `Rule`, `Repo`, and `CurrentProjectGitWalker`.
+
+### `internal/core/models`
+**Module value objects and sentinels** — represents dependencies, resolved revisions, cached-install metadata, lock entries, and module errors.
+
+| File | Description |
+|------|-------------|
+| `module.go` | Defines `Module`, `RequestedVersion`, `ModuleHash`, install metadata, and pseudo-version parsing. |
+| `revision.go` | Defines resolved Git commit and version data. |
+| `lock_file_info.go` | Defines a lock-file entry. |
+| `module_config.go` | Defines module directories and transitive dependencies. |
+| `cache_download_paths.go` | Defines cache archive and info paths. |
+| `errors.go` | Defines dependency-management sentinel errors. |
+
+### `internal/core/path_helpers`
+**Path predicates** — contains helpers used when walking selected or ignored paths.
+
+| File | Description |
+|------|-------------|
+| `is_target_path.go` | Tests whether a path matches the targeted path set. |
+
+## Rule Layer
+
+### `internal/rules`
+**Concrete protobuf lint rules** — builds the selected rule set from lint configuration and implements buf-compatible naming, package, import, comment, enum, service, and RPC checks.
+
+| File group | Description |
+|------------|-------------|
+| `builder.go` | Defines named rule groups and creates `[]core.Rule` from configuration. |
+| `package_*.go`, `directory_*.go` | Validate package declarations, directories, and language package options. |
+| `message_*.go`, `oneof_*.go`, `enum_*.go` | Validate message, oneof, and enum names and values. |
+| `service_*.go`, `rpc_*.go` | Validate service and RPC naming, request/response forms, and streaming policy. |
+| `import_*.go` | Validate import use and forbid weak or public imports. |
+| `comment_*.go` | Validate comments for protobuf declarations. |
+| `protovalidate.go` | Supports protovalidate-aware rule behavior. |
+
+Each rule follows the `core.Rule` interface: it provides a message and validates a `core.ProtoInfo`.
+
+## Configuration and Schema
+
+### `internal/config`
+**`easyp.yaml` parser and validator** — loads YAML after environment substitution and validates configuration objects.
+
+| File | Description |
+|------|-------------|
+| `config.go` | Defines configuration, generation inputs/plugins, managed mode, parsing, and validation. |
+| `lint.go` | Defines lint configuration. |
+| `breaking_check.go` | Defines breaking-check configuration. |
+| `default.go` | Provides default configuration values. |
+| `yaml_validators.go`, `validate_raw.go` | Validate YAML nodes and raw configuration. |
+| `plugin_opts.go` | Supports plugin option values expressed as scalars or sequences. |
+
+### `mcp/easypconfig`
+**Configuration schema metadata and MCP tool** — defines the config-schema model, generates JSON Schema, indexes schema paths, and serves schema descriptions.
+
+| File | Description |
+|------|-------------|
+| `tool.go` | Registers the MCP config-description tool. |
+| `describe.go` | Describes the complete schema or a requested schema path. |
+| `schema.go`, `schema_model.go` | Reflects and models the JSON Schema source. |
+| `tool_schemas.go` | Defines MCP tool input and output schemas. |
+| `generate.go` | Generates schema content used by the CLI. |
+| `spec_docs.go` | Holds schema documentation metadata. |
+
+`schemas/` contains generated JSON Schema artifacts. Do not hand-edit them; regenerate through `task schema:generate`.
+
+## Adapter Layer
+
+### `internal/adapters/storage`
+**Dependency cache and installation adapter** — manages archives, installed module directories, metadata, hashes, and lock-aware path lookup under `EASYPPATH`.
+
+| File group | Description |
+|------------|-------------|
+| `storage.go`, `install.go` | Define storage and install downloaded module archives. |
+| `cache_download.go`, `get_cache_download_paths.go` | Compute cached archive and metadata paths. |
+| `get_install_dir.go`, `get_installed_module_hash.go` | Locate installed modules and verify their hash. |
+| `read_installed_module_info.go`, `write_installed_module_info.go` | Persist install metadata. |
+| `create_cache_repository_dir.go`, `sanitize.go` | Create Git-cache paths and sanitize version components. |
+
+### `internal/adapters/lock_file`
+**Lock-file adapter** — reads, writes, iterates, and checks the project `easyp.lock`.
+
+| File | Description |
+|------|-------------|
+| `lock_file.go` | Defines the lock-file adapter. |
+| `read.go`, `write.go` | Parse and serialize lock entries. |
+| `deps_iter.go`, `is_empty.go` | Iterate entries and detect an empty lock file. |
+
+### `internal/adapters/repository` and `internal/adapters/repository/git`
+**Git repository adapter** — supplies repository operations required for dependency resolution.
+
+| File group | Description |
+|------------|-------------|
+| `repository.go` | Declares the repository port. |
+| `git/git.go` | Constructs the Git implementation. |
+| `git/read_revision.go` | Resolves a requested version to a revision. |
+| `git/fetch.go`, `git/archive.go` | Fetches Git objects and archives proto content. |
+| `git/read_file.go`, `git/get_files.go` | Reads repository files and lists paths. |
+
+### `internal/adapters/module_config`
+**Remote module-layout reader** — reads module directories and dependencies from supported repository configuration.
+
+| File | Description |
+|------|-------------|
+| `module_config.go` | Defines the adapter. |
+| `read_from_repo.go` | Selects and reads supported module configuration. |
+| `read_buf_work.go`, `read_easyp.go` | Read Buf and EasyP layouts. |
+
+### `internal/adapters/plugin`
+**Code-generation plugin executors** — executes local, remote, built-in, and command-based plugins.
+
+| File group | Description |
+|------------|-------------|
+| `interface.go`, `options.go` | Define executor contracts and plugin invocation metadata. |
+| `local.go`, `remote.go`, `command.go` | Implement execution sources. |
+| `builtin.go`, `builtin_impl.go`, `wasm_embed.go` | Provide built-in plugin support. |
+
+### `internal/adapters/go_git`
+**Historical-tree adapter** — returns directory walkers for the current project's Git references.
+
+### `internal/adapters/console`
+**Local command adapter** — selects shell behavior and represents console errors.
+
+### `internal/adapters/prompter`
+**Interactive input adapter** — provides prompt behavior used by interactive operations.
+
+## Shared Internal Packages
+
+### `internal/fs`
+**Filesystem access** — supplies directory walkers used by core operations.
+
+### `internal/logger`
+**Logging abstraction** — wraps the logger used by CLI setup, core workflows, and adapters.
+
+### `internal/flags`
+**Global command flags** — defines shared config, debug, and output-format flags.
+
+### `internal/version`
+**Build and compiler version information** — supplies the CLI and protobuf compiler version values.
+
+## Package-Manager Reference
+
+For dependency declaration, cache layout, lockfile format, Git resolution, transitive dependencies, and `easyp_vendor`, see [config/dependency.md](./config/dependency.md).
diff --git a/.spec/README.md b/.spec/README.md
new file mode 100644
index 0000000..a0f1d1b
--- /dev/null
+++ b/.spec/README.md
@@ -0,0 +1,106 @@
+<!-- generated: 2026-07-27, template: bootstrap.md -->
+# EasyP Documentation
+
+This folder contains documentation to help LLMs and developers quickly understand the project context.
+
+## Documentation Index
+
+### Core
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Layered architecture (cmd → api → core → adapters)
+- [PACKAGES.md](./PACKAGES.md) — Package reference for `internal/*`, `mcp/`, `cmd/`
+- [DOMAIN.md](./DOMAIN.md) — Domain model (modules, lockfile, lint rules, plugins)
+- [CODE_STYLE.md](./CODE_STYLE.md) — Go conventions expanded from agent-rules
+
+### Development
+
+- [TOOLS.md](./TOOLS.md) — Taskfile, golangci-lint, mockery, gotestsum
+- [TESTING.md](./TESTING.md) — testify patterns, mocks, race tests
+
+### Config & Dependencies
+
+- [config/dependency.md](./config/dependency.md) — Git-native package manager (`easyp mod`, lockfile, cache)
+- [agent-rules.md](./agent-rules.md) — Mandatory rules for AI agents
+
+### Domain (CLI toolkit)
+
+- [CLI.md](./CLI.md) — Commands, flags, exit codes
+- [ERRORS.md](./ERRORS.md) — Domain / models sentinel errors and CLI mapping
+- [DEPLOYMENT.md](./DEPLOYMENT.md) — Docker, CI/CD, releases
+
+## Quick Facts
+
+| Aspect | Technology |
+|--------|------------|
+| **Language** | Go 1.24 (`github.com/easyp-tech/easyp`) |
+| **Product** | Protocol Buffers CLI toolkit |
+| **CLI** | urfave/cli (`cmd/easyp`) |
+| **Capabilities** | lint, breaking, generate, `easyp mod` |
+| **Config** | `easyp.yaml` (+ envsubst); schema via `mcp/easypconfig` → `schemas/` |
+| **Deps** | Git repositories; lockfile `easyp.lock`; cache `EASYPPATH` |
+| **Build** | Task (`Taskfile.yml`) |
+| **Lint** | golangci-lint (`.golangci.yml`) |
+| **Tests** | gotestsum, `-race`, testify |
+| **Human docs** | `docs/` (Vite site), https://easyp.tech |
+
+## Project Structure
+
+```
+easyp/
+├── cmd/easyp/              # CLI entrypoint
+├── internal/
+│   ├── api/                # CLI command wiring
+│   ├── core/               # Business logic (lint, generate, mod, breaking)
+│   ├── rules/              # Lint rules (+ colocated tests)
+│   ├── config/             # easyp.yaml parse/validate
+│   └── adapters/           # Git, storage, lockfile, plugins, console
+├── mcp/easypconfig/        # Config schema metadata (source of truth)
+├── schemas/                # Generated JSON Schema artifacts
+├── docs/                   # Documentation site
+├── .spec/                  # Agent-oriented project docs (this tree)
+└── Taskfile.yml
+```
+
+## Running
+
+```sh
+task init              # install local tools (golangci-lint, gotestsum, mockery)
+task build             # go build -o easyp ./cmd/easyp
+task test              # gotestsum with -race and coverage
+task lint              # golangci-lint (+ hadolint where applicable)
+task quality           # test + lint
+task schema:generate   # regenerate schemas/*.json
+task schema:check      # fail if schemas drift
+task mocks             # regenerate mockery mocks
+```
+
+Without Task:
+
+```sh
+go build -o easyp ./cmd/easyp
+go test -race -count=1 ./...
+go run ./cmd/easyp schema-gen
+```
+
+## Ports
+
+N/A — EasyP is a CLI tool, not a long-running server. Remote plugin execution uses gRPC to an external EasyP plugin API when configured; there is no default listen port in-repo.
+
+## Key Interfaces / Entry Points
+
+| Entry | Role |
+|-------|------|
+| `cmd/easyp` | Process entry; registers CLI handlers |
+| `internal/api` | Commands: lint, generate, breaking, mod, init, ls-files, schema-gen |
+| `internal/core.Core` | Business logic facade |
+| `internal/core` Storage / LockFile / ModuleConfig | Package-manager ports |
+| `easyp.yaml` `deps` + `easyp.lock` | Declared and locked proto dependencies |
+| `mcp/easypconfig` | Config schema / MCP metadata |
+
+## Adding New Features
+
+1. **Lint rule** — add `internal/rules/<rule>.go` + `_test.go`; register via existing rule builder; mirror neighboring rules.
+2. **`easyp.yaml` schema** — change `mcp/easypconfig` and/or `internal/config`, then `task schema:generate` (never hand-edit `schemas/*.json`).
+3. **CLI command** — wire in `internal/api`, register from `cmd/easyp`; follow existing handler patterns.
+4. **Core/storage interfaces** — update interfaces, `task mocks`, add/adjust tests with `-race`.
+5. Before finishing behavior changes: run tests for touched packages; for schema changes run `task schema:check`.
diff --git a/.spec/TESTING.md b/.spec/TESTING.md
new file mode 100644
index 0000000..07b0b8a
--- /dev/null
+++ b/.spec/TESTING.md
@@ -0,0 +1,282 @@
+<!-- generated: 2026-07-27, template: development.md -->
+# Testing
+
+## Overview
+
+EasyP tests are Go `*_test.go` files distributed beside the packages they
+exercise. The test task runs every package with coverage, the race detector,
+and test caching disabled:
+
+```bash
+task test
+```
+
+The command expands to:
+
+```bash
+bin/gotestsum --format pkgname -- -coverprofile=coverage.out -race -count=1 ./...
+```
+
+Tests use the standard `testing` package and `github.com/stretchr/testify`.
+Testify's `require` package is the most common assertion style in the lint
+rule tests, while some smaller package tests use `t.Fatalf` or `t.Errorf`.
+
+## Test Package Naming
+
+Both external and internal test packages are present; select the package style
+that matches the code being tested and neighboring tests.
+
+Lint rule tests use an external package:
+
+```go
+package rules_test
+
+import (
+    "testing"
+
+    "github.com/easyp-tech/easyp/internal/rules"
+)
+```
+
+For example, `internal/rules/file_lower_snake_case_test.go` imports
+`internal/rules` explicitly and tests its exported rule type. Tests in
+`internal/core` commonly use the internal package instead:
+
+```go
+package core
+```
+
+`internal/core/generate_path_test.go` calls the unexported `stripPrefix`
+function directly, which requires the internal `core` package. There are no
+`export_test.go` files in the repository, so private behavior is tested from
+same-package tests rather than exposed through test-only exports.
+
+## Test File Structure
+
+Rule validation tests commonly use a table keyed by scenario name, make
+parallelism explicit, create test data through a shared helper, and use
+Testify assertions:
+
+```go
+func TestFileLowerSnakeCase_Validate(t *testing.T) {
+    t.Parallel()
+
+    tests := map[string]struct {
+        fileName   string
+        wantIssues *core.Issue
+        wantErr    error
+    }{
+        "invalid": {fileName: invalidAuthProto3},
+        "valid":   {fileName: validAuthProto},
+    }
+
+    for name, tc := range tests {
+        name, tc := name, tc
+        t.Run(name, func(t *testing.T) {
+            t.Parallel()
+
+            r, protos := start(t)
+            rule := rules.FileLowerSnakeCase{}
+            issues, err := rule.Validate(protos[tc.fileName])
+            r.ErrorIs(err, tc.wantErr)
+            if tc.wantIssues != nil {
+                r.Contains(issues, *tc.wantIssues)
+            }
+        })
+    }
+}
+```
+
+The actual test additionally verifies rule issue fields. The abbreviated
+example shows the recurring structure without duplicating all fixture data.
+
+## Table-Driven Tests
+
+The repository uses both map- and slice-based table tests.
+
+Rule tests typically use `map[string]struct` where each map key is the
+subtest name. They rebind the range values before the closure:
+
+```go
+for name, tc := range tests {
+    name, tc := name, tc
+    t.Run(name, func(t *testing.T) {
+        // use name and tc
+    })
+}
+```
+
+This protects closure code from range-variable capture and is especially
+important when subtests run in parallel.
+
+Other tests use a slice with an explicit `name` field. For example,
+`internal/adapters/plugin/options_test.go` defines:
+
+```go
+tests := []struct {
+    name      string
+    options   map[string][]string
+    expected  string
+    hasResult bool
+}{
+    {
+        name:      "single scalar value",
+        options:   map[string][]string{"env": {"node"}},
+        expected:  "env=node",
+        hasResult: true,
+    },
+}
+```
+
+Prefer descriptive scenario names. The project testing skill calls for
+`name string` as the first table field, input fields next, setup fields after
+that, and expected values last. Existing legacy tests do not all follow every
+new convention, so use nearby tests and the testing skill when adding code.
+
+## Parallel Execution
+
+Many rule tests call `t.Parallel()` at the top level and in every subtest:
+
+```go
+func TestRule_Validate(t *testing.T) {
+    t.Parallel()
+
+    for name, tc := range tests {
+        name, tc := name, tc
+        t.Run(name, func(t *testing.T) {
+            t.Parallel()
+            // isolated test body
+        })
+    }
+}
+```
+
+The project testing skill treats this as the standard for table-driven tests.
+Keep each parallel subtest isolated: create mutable dependencies inside the
+subtest and use `t.TempDir()` for filesystem state. Do not remove
+parallelism merely to work around coupled test state.
+
+Not every existing test is parallel. For example,
+`internal/core/generate_path_test.go` uses sequential subtests, and
+`internal/config/config_test.go` sets and unsets process environment
+variables. When modifying a test, preserve its safety requirements rather
+than adding parallelism to code with shared global state.
+
+## Helpers, Fixtures, and Cleanup
+
+`internal/rules/init_test.go` supplies the shared `start(t testing.TB)`
+helper for rule tests. It parses `.proto` files from `testdata/` and returns
+both `*require.Assertions` and a map of `core.ProtoInfo`.
+
+The helper marks itself as a helper and registers file cleanup:
+
+```go
+func parseFile(t testing.TB, assert *require.Assertions, path string) core.ProtoInfo {
+    t.Helper()
+
+    f, err := os.Open(path)
+    assert.NoError(err)
+    t.Cleanup(func() { assert.NoError(f.Close()) })
+
+    got, err := protoparser.Parse(f)
+    assert.NoError(err)
+    // interpret the parsed proto and its imports
+}
+```
+
+Use `t.Helper()` for reusable helpers so failure locations point to the test
+call site. Use `t.Cleanup()` for resources opened by the test. The repository
+does not contain golden-file or snapshot-test infrastructure.
+
+## Assertions and Errors
+
+Testify is a direct module dependency. Rule tests frequently construct
+`require.New(t)` and use the returned assertion object:
+
+```go
+assert := require.New(t)
+assert.Equal(expMessage, message)
+assert.NoError(err)
+```
+
+For new tests, use `require` for a condition that must hold before later
+assertions can be meaningful, such as an error-free operation or a non-nil
+value. Use `assert` for independent value checks when continued reporting is
+useful. For expected sentinel errors, the project testing skill specifies
+`require.ErrorIs(t, err, wantErr)`.
+
+Some existing compact tests use direct fatal failures:
+
+```go
+if result != tt.expected {
+    t.Fatalf("flattenOptions() result = %q, want %q", result, tt.expected)
+}
+```
+
+Follow the surrounding test's established assertion style when making a
+small extension, while using the project testing conventions for new suites.
+
+## Mock Generation
+
+Mockery is the generated-mock tool. `Taskfile.yml` pins Mockery v2.41.0 and
+installs it into `bin/` through `task init`.
+
+```bash
+task mocks
+```
+
+The task generates mocks for storage and core interfaces. Generated files
+include `internal/adapters/storage/mocks/LockFile.go` and types under
+`internal/core/mocks/`. They begin with `Code generated by mockery. DO NOT
+EDIT.` and use `testify/mock`.
+
+Two core test-only mocks are generated in place by directives in
+`internal/core/mod.go`:
+
+```go
+//go:generate mockery --name Storage --dir . --output . --outpkg core --filename storage_mock_test.go --structname StorageMock --inpackage --testonly
+//go:generate mockery --name LockFile --dir . --output . --outpkg core --filename lockfile_mock_test.go --structname LockFileMock --inpackage --testonly
+```
+
+Run `task mocks` after changing core or storage interfaces covered by the
+Taskfile. Run `go generate ./internal/core` when the in-package test-only
+directives must be refreshed. Do not hand-edit generated mock files.
+
+## Integration Tests
+
+There is no separate integration-test directory, test build tag, `TestMain`,
+or test-container configuration in the current test tree. `task test` runs
+all Go tests in `./...`; it is therefore the single repository test command
+rather than a unit/integration split.
+
+Tests that parse Protocol Buffers use checked-in files under `testdata/`.
+They do not start an external database, Docker Compose stack, or other
+service. EasyP's Git-backed module cache and `easyp_vendor` output belong to
+the dependency-management flow; see
+[config/dependency.md](config/dependency.md), not a file-upload test suite.
+
+## Commands
+
+```bash
+# Full suite: coverage, race detector, and no cache
+task test
+
+# Direct Go equivalent without gotestsum's package formatter
+go test -race -count=1 ./...
+
+# Run one package
+go test -race -count=1 ./internal/rules
+
+# Run one test or subtest pattern
+go test -race -count=1 ./internal/rules -run 'TestFileLowerSnakeCase_Validate'
+
+# Open the coverage profile produced by task test
+task coverage
+
+# Regenerate Mockery outputs after interface changes
+task mocks
+```
+
+Run at least the package tests you touched after a behavior change. Run
+`task test` before handing off broader changes; it is also the command used
+by the GitHub Actions test workflow after `task init`.
diff --git a/.spec/TOOLS.md b/.spec/TOOLS.md
new file mode 100644
index 0000000..3948539
--- /dev/null
+++ b/.spec/TOOLS.md
@@ -0,0 +1,200 @@
+<!-- generated: 2026-07-27, template: development.md -->
+# Development Tools
+
+## Dev Environment Setup
+
+EasyP is a Go Protocol Buffers CLI toolkit. The module declares Go 1.24.0,
+and the test workflow in GitHub Actions installs Go 1.24 and Task 3.x.
+
+| Tool | Version / source | Purpose |
+|---|---|---|
+| Go | 1.24.0 (`go.mod`) | Build and test the CLI |
+| Task | 3.x in CI | Run the repository task targets |
+| Docker | Required by lint and image tasks | Run Hadolint and build images |
+| Git | Required by EasyP module operations and releases | Work with Git-backed proto dependencies |
+
+`Taskfile.yml` installs project-local helpers into `bin/`:
+`golangci-lint` 2.1.6, `gotestsum` 1.11.0, and `mockery` 2.41.0.
+Hadolint v2.12.1-beta is pulled as a Docker image instead of installed
+locally.
+
+### First Run
+
+1. Clone the repository and enter its root.
+2. Install Go 1.24 and Task.
+3. Ensure Docker is available if you will run `task lint`, Docker image
+   tasks, or release snapshots.
+4. Run `task init`. It installs the local Go tools into `bin/` and runs
+   `go get -v ./...`.
+5. Run `task test` to verify the checkout.
+6. Run `task build` to create the root-level `easyp` executable.
+
+The repository has no `docker-compose` file or service startup target. EasyP
+is a CLI, so development verification is normally a build or test command.
+
+## Overview
+
+Prefer `task` targets from `Taskfile.yml`; they encode the local tool paths,
+coverage settings, race detection, and Docker-based lint checks used by the
+project.
+
+## Quick Reference
+
+| Action | Command |
+|---|---|
+| Install development helpers | `task init` |
+| Build the CLI | `task build` |
+| Run the full test suite | `task test` |
+| Run lint checks | `task lint` |
+| Run tests and lint | `task quality` |
+| Open HTML coverage | `task coverage` |
+| Install the CLI into `GOBIN` | `task install` |
+| Remove local build/tool artifacts | `task clean` |
+| Regenerate config schemas | `task schema:generate` |
+| Check config schema drift | `task schema:check` |
+| Regenerate mocks | `task mocks` |
+
+## Build and Install
+
+```bash
+task build
+task install
+```
+
+`task build` runs `go build -o easyp ./cmd/easyp`, placing a local executable
+at `./easyp`. `task install` instead runs `go install ./cmd/easyp` and uses
+the Go installation destination. Neither task needs generated schemas or
+mocks as a prerequisite.
+
+The direct build equivalent is:
+
+```bash
+go build -o easyp ./cmd/easyp
+```
+
+The root `Dockerfile` is a separate production build path. It compiles with
+`CGO_ENABLED=0` using `golang:1.25-alpine` and packages the binary in
+`alpine:3.22` with CA certificates, timezone data, Git, and Bash.
+
+## Testing and Coverage
+
+```bash
+task test
+task coverage
+```
+
+`task test` invokes the project-local `bin/gotestsum` with:
+
+```bash
+bin/gotestsum --format pkgname -- -coverprofile=coverage.out -race -count=1 ./...
+```
+
+This is the repository-wide test command: it records coverage in
+`coverage.out`, enables the race detector, and disables Go test caching.
+`task coverage` opens that existing profile with `go tool cover -html`; run
+`task test` first. See [TESTING.md](TESTING.md) for conventions and narrower
+Go commands.
+
+## Linting and Quality
+
+```bash
+task lint
+task quality
+```
+
+`task lint` first depends on `task build`. It runs Hadolint in Docker against
+`Docker/base/Dockerfile` and `Docker/lint/Dockerfile`, then runs
+`bin/golangci-lint run ./...`. The checked-in `.golangci.yml` enables
+`staticcheck`; the installed linter version is pinned by the Taskfile.
+
+`task quality` depends on both `task test` and `task lint`. It is the closest
+local approximation of the test and lint checks. CI's `tests.yml` workflow
+currently performs `task init` followed by `task test`; it does not invoke
+the lint target in that workflow.
+
+## Generated Artifacts
+
+### Configuration JSON Schema
+
+```bash
+task schema:generate
+task schema:check
+```
+
+`task schema:generate` runs `go run ./cmd/easyp schema-gen`, producing the
+versioned and latest schema artifacts under `schemas/`. The `go:generate`
+directive in `mcp/easypconfig/generate.go` can also run schema generation with
+explicit output paths.
+
+Use `task schema:check` after changing config schema metadata or validation.
+It regenerates the artifacts and fails if
+`schemas/easyp-config-v1.schema.json` or `schemas/easyp-config.schema.json`
+would differ. Do not hand-edit those generated JSON files.
+
+### Test Mocks
+
+```bash
+task mocks
+go generate ./internal/core ./mcp/easypconfig
+```
+
+`task mocks` uses local Mockery to regenerate mocks for `LockFile` in storage
+and several `internal/core` interfaces, including `Rule`, `Console`,
+`CurrentProjectGitWalker`, `Storage`, and `ModuleConfig`. It writes mocks to
+the package `mocks/` directories.
+
+`internal/core/mod.go` also declares test-only `go:generate mockery`
+directives that generate `storage_mock_test.go` and `lockfile_mock_test.go`
+in the `core` package. Regenerate mocks after changing an interface they
+implement.
+
+## Docker and Release Checks
+
+```bash
+task docker_base GIT_TAG=v0.0.0
+task docker_lint GIT_TAG=v0.0.0
+task goreleaser:check
+task goreleaser:test
+task goreleaser:test-docker
+```
+
+`docker_base` and `docker_lint` build and tag the base and lint images.
+`task docker` obtains the current Git tag, builds both images, and pushes
+them, so it is a publishing command rather than a local smoke test.
+
+`task goreleaser:check` validates GoReleaser configuration. The snapshot
+tasks create or select a `multiarch` Docker Buildx builder and run
+`goreleaser release --snapshot --clean`; they do not publish a release.
+The release workflow runs for stable `vMAJOR.MINOR.PATCH` tags and authenticates
+to GitHub Container Registry and Docker Hub.
+
+## Dependency and Vendor Tools
+
+EasyP module dependencies are Git repositories, cached under `EASYPPATH`
+(default `$HOME/.easyp`) and locked in `easyp.lock`. The vendoring command is:
+
+```bash
+./easyp mod vendor
+```
+
+It copies installed proto dependencies to `easyp_vendor`, not Go's usual
+`vendor/` directory. This is EasyP dependency cache and package-management
+behavior, not application file storage. See
+[config/dependency.md](config/dependency.md) for the authoritative dependency
+flow and available `easyp mod` subcommands.
+
+## Tool Installation
+
+| Tool | Installation used by this repository |
+|---|---|
+| Go | Install Go 1.24, then verify with `go version` |
+| Task | Install Task 3.x; CI uses `arduino/setup-task@v1` |
+| GolangCI-Lint | `task init` installs it into `./bin` |
+| Gotestsum | `task init` installs it into `./bin` |
+| Mockery | `task init` installs it into `./bin` |
+| Hadolint | `task lint` pulls `ghcr.io/hadolint/hadolint:v2.12.1-beta` |
+| GoReleaser | Provide `goreleaser` on `PATH` for its Task targets |
+
+`task clean` removes `bin/` and `coverage.out`, then clears the Go build
+cache. It does not remove module caches, EasyP's dependency cache, schemas,
+or the root-level `easyp` binary.
diff --git a/.spec/agent-rules.md b/.spec/agent-rules.md
new file mode 100644
index 0000000..63593d3
--- /dev/null
+++ b/.spec/agent-rules.md
@@ -0,0 +1,55 @@
+<!-- generated: 2026-07-27, template: bootstrap.md -->
+# Agent Rules — EasyP
+
+Mandatory rules for AI agents. Prefer these over generic Go guides when they conflict. Expanded skills: `.agents/skills/go-code-style`, `.agents/skills/go-testing`. Dependency details: [config/dependency.md](./config/dependency.md).
+
+## Code Style
+
+- Wrap errors as `fmt.Errorf("<called_function>: %w", err)` — function/method name only, **no package prefix**.
+- Do not assign inside `if` conditions except `:=` for block-scoped vars; assign then check on separate lines.
+- Never bare `defer x.Close()` — always wrap Close and log/handle the error.
+- No inline comments on `if` / `for` / `return` lines; comments go above if needed.
+- Imports: stdlib → third-party → project (`gci`); comments and godoc in English; exported symbols need godoc starting with the name.
+- Interfaces: context first, error last, no `I` prefix; prefer defining interfaces in the consumer package.
+- Enums: reserve zero with `_ = iota` so unset values are never silently valid.
+
+## Naming Conventions
+
+- Files: colocated tests as `<file>_test.go`; lint rules as `internal/rules/<rule>.go`.
+- Types: exported domain/entities and adapter implementations; keep config structs unexported when local.
+- Struct tags: `snake_case` (`yaml`, env) — follow `tagliatelle` / existing config patterns.
+- Do not invent parallel agent instruction files (`.cursor/rules/`, `CLAUDE.md`); root `AGENTS.md` + `.spec/` are the source of truth.
+
+## Error Handling
+
+- Wrap at every call site with `%w`; use `errors.Is` / `errors.As` for sentinels.
+- Domain/package-manager sentinels live under `internal/core` / `internal/core/models` (e.g. `ErrVersionNotFound`); do not invent duplicate sentinels elsewhere.
+- CLI: map known failures to documented exit codes (e.g. `ErrVersionNotFound` → exit 1 for `mod`).
+
+## Testing
+
+- Use `testify` (`require` for fatal preconditions, `assert` for non-fatal checks).
+- Table-driven tests with a required `name` field; call `t.Parallel()` at top level and inside each `t.Run`.
+- No shared mutable mocks/state across parallel sub-tests — construct deps per case.
+- Prefer `require.ErrorIs` for expected errors; run with `-race` (`task test`).
+- When core/storage interfaces change, regenerate mocks with `task mocks`.
+
+## Dependencies
+
+- Proto deps: declare in `easyp.yaml` `deps` (and/or `generate.inputs[].git_repo.url`); lock with `easyp.lock`; cache under `EASYPPATH` (default `~/.easyp`).
+- Vendor directory is `easyp_vendor`, not `vendor/`.
+- Use `easyp mod download` (lock-first) vs `easyp mod update` (refresh from config); commit `easyp.lock` for CI reproducibility.
+- No remotes/mirrors/auth fields in `easyp.yaml` — auth via system git.
+- Do not hand-edit `schemas/easyp-config*.schema.json`; regenerate via `task schema:generate`.
+
+## Formatting
+
+- Format with `gofmt` / project tooling; lint with `task lint` (golangci-lint + hadolint where applicable).
+- Do not commit secrets, `docs/node_modules`, `coverage.out`, or the local `easyp` binary in the repo root.
+- After behavior changes, run tests for touched packages; after schema changes, run `task schema:check`.
+
+## Quick Checklist
+
+- [ ] Error wrap = callee name only; no bare `defer Close()`
+- [ ] Tests: named cases, `t.Parallel`, no shared mutable mocks
+- [ ] Schema JSON regenerated, not hand-edited; vendor = `easyp_vendor`
diff --git a/.spec/config.yaml b/.spec/config.yaml
new file mode 100644
index 0000000..de6c087
--- /dev/null
+++ b/.spec/config.yaml
@@ -0,0 +1,7 @@
+context: EasyP is a Protocol Buffers CLI toolkit (Go) — lint, breaking, generate, easyp mod.
+docs_dir: .spec
+doc_freshness_days: 30
+auto_branch: false
+auto_worktree: false
+test_skill: go-testing
+rules.docs: Prefer code under internal/ and AGENTS.md over marketing docs. Vendor dir is easyp_vendor. Link .spec/config/dependency.md for package manager details.
diff --git a/.spec/config/dependency.md b/.spec/config/dependency.md
new file mode 100644
index 0000000..4c3e8b0
--- /dev/null
+++ b/.spec/config/dependency.md
@@ -0,0 +1,291 @@
+# EasyP Dependency Management
+
+Agent-oriented specification of how EasyP declares, downloads, locks, and resolves protobuf dependencies.
+
+Source of truth: Go code under `internal/core`, `internal/api`, and `internal/adapters`. Do not treat human docs or skill references as authoritative when they disagree with this file or the code.
+
+---
+
+## 1. Overview
+
+EasyP’s package manager is **Git-native** and shaped like Go modules:
+
+- Any Git repository path can be a dependency (no Buf Schema Registry).
+- Versions are Git tags, branch names, commit hashes, omitted (`HEAD`), or Go-style pseudo-versions.
+- Installs are cached under `EASYPPATH` (default `$HOME/.easyp`).
+- Reproducibility is provided by project-root `easyp.lock`.
+- Auth, proxies, and SSH are delegated to the system `git` CLI (no remotes/mirrors/tokens in `easyp.yaml`).
+
+Vendor output directory is hardcoded as `easyp_vendor` (not `vendor/`).
+
+---
+
+## 2. Declaration (`easyp.yaml`)
+
+### `deps`
+
+```yaml
+deps:
+  - github.com/googleapis/googleapis@common-protos-1_3_1
+  - github.com/bufbuild/protoc-gen-validate          # version omitted → latest
+```
+
+| Field | Go type | Notes |
+|-------|---------|--------|
+| `deps` | `[]string` | `Config.Deps` in `internal/config/config.go` |
+| Entry format | `repo[@version]` | Split on first `@` via `models.NewModule` |
+| Omitted version | `RequestedVersion("")` | Treated as latest (`HEAD`) |
+
+Entire config content (including deps) is expanded with `envsubst` (`${VAR}`) before YAML parse.
+
+### Union with generate inputs
+
+`buildCore` builds the effective deps list as:
+
+```
+uniq(cfg.Deps + generate.inputs[].git_repo.url)
+```
+
+See `getDepsFromGenerateDeps` in `internal/api/mod.go` and `buildCore` in `internal/api/temporaly_helper.go`.
+
+```yaml
+generate:
+  inputs:
+    - git_repo:
+        url: github.com/acme/contracts@v1.2.3   # also becomes a Core.deps entry
+        sub_directory: proto
+```
+
+There are **no** YAML fields for remotes, mirrors, auth, cache path, lockfile path, or vendor dir.
+
+---
+
+## 3. CLI
+
+Parent command: `easyp mod` (alias `m`) — `internal/api/mod.go`.
+
+| Subcommand | Core method | Behavior |
+|------------|-------------|----------|
+| `mod download` | `Core.Download` | Lock-first install; empty lock → `Update` |
+| `mod update` | `Core.Update` | Install every config dep; refresh lock |
+| `mod vendor` | `Core.Vendor` | `Download`, then copy install trees → `easyp_vendor` |
+
+No subcommand-specific flags.
+
+### Global flags (all commands)
+
+| Flag | Env | Default |
+|------|-----|---------|
+| `--cfg` / `--config` | `EASYP_CFG` | `easyp.yaml` |
+| `--debug` / `-d` | `EASYP_DEBUG` | `false` |
+| `--format` / `-f` | `EASYP_FORMAT` | `text` |
+
+### Exit codes
+
+On `models.ErrVersionNotFound`, mod handlers call `os.Exit(1)`.
+
+---
+
+## 4. Flows
+
+```mermaid
+flowchart TD
+  cfg["easyp.yaml deps + generate.inputs.git_repo"] --> buildCore["buildCore → Core.deps"]
+  buildCore --> download["Core.Download / Update"]
+  download --> get["Core.Get"]
+  get --> git["bare git cache + fetch"]
+  git --> modcfg["Read buf/easyp ModuleConfig"]
+  modcfg --> indirect["Recursive Get for transitive deps"]
+  indirect --> archive["git archive *.proto → zip"]
+  archive --> install["storage.Install → mod/ + dirhash"]
+  install --> lock["easyp.lock Write"]
+  lock --> consumers["lint / generate / breaking / vendor"]
+```
+
+### `Download` (`internal/core/download.go`)
+
+1. If lockfile is empty / missing → delegate to `Update`.
+2. Else install each lockfile entry via `Get`.
+3. Then install any `c.deps` entries not already in the lockfile.
+
+### `Update` (`internal/core/update.go`)
+
+For each string in `c.deps`, parse `Module` and call `Get` (overwrites lock entries with resolved revision + hash).
+
+### `Get` / `get` (`internal/core/get.go`)
+
+**Fast path:** if `.info` exists for the requested module/version and hash checks pass → skip network; still rewrite lock entry.
+
+**Install path (`get`):**
+
+1. `storage.CreateCacheRepositoryDir(name)` — bare clone under `cache/<sha256(name)>`
+2. `git.New` — `origin` = `https://` + module name
+3. `repo.ReadRevision` — resolve tag / branch / commit / HEAD / pseudo-version
+4. `repo.Fetch` — shallow fetch
+5. `moduleConfig.ReadFromRepo` — buf or easyp module layout + transitive deps
+6. Recursive `Get` for each `moduleConfig.Dependencies`
+7. `repo.Archive` — `git archive --format=zip <commit> -o … "*.proto"` only
+8. `storage.Install` — extract, strip module dirs, `dirhash.HashDir`, atomic rename into `mod/`
+9. Write `.info` + `lockFile.Write`
+
+### `Vendor` (`internal/core/vendor.go`)
+
+1. `Download`
+2. For each lock entry, `cp.Copy(installDir, vendorDir)` where `vendorDir` is `easyp_vendor`
+
+---
+
+## 5. Lockfile (`easyp.lock`)
+
+| Property | Value |
+|----------|--------|
+| Filename | `easyp.lock` (constant `lockFileName`) |
+| Location | Project working directory (via `DirWalker`) |
+| Line format | `moduleName version hash` (exactly 3 space-separated fields) |
+| Hash | Go `dirhash` style (`h1:…`) of installed tree |
+| Write behavior | Full rewrite; keys sorted alphabetically |
+
+Example:
+
+```
+github.com/googleapis/googleapis v0.0.0-20250909114430-8727b5baabcdef h1:eI+…
+github.com/grpc-ecosystem/grpc-gateway v2.19.1 h1:01NNlC…
+```
+
+Malformed lines (≠ 3 fields) are skipped on read.
+
+Key types: `models.LockFileInfo`, `models.ErrModuleNotFoundInLockFile` (`internal/core/models/lock_file_info.go`).
+
+Adapter: `internal/adapters/lock_file/`.
+
+---
+
+## 6. Storage layout (`EASYPPATH`)
+
+| Env | Default |
+|-----|---------|
+| `EASYPPATH` | `$HOME/.easyp` |
+
+```
+$EASYPPATH/
+├── cache/
+│   ├── download/<moduleName>/<sanitizedVersion>.zip
+│   ├── download/<moduleName>/<sanitizedVersion>.info   # JSON InstalledModuleInfo
+│   └── <sha256(moduleName)>/                          # bare git repository
+└── mod/<moduleName>/<sanitizedVersion>/               # extracted *.proto tree
+```
+
+- `sanitizePath`: replaces `/` with `-` in version strings.
+- Install example: `~/.easyp/mod/github.com/googleapis/googleapis/v1.2.3`
+- Archive contains only `*.proto` files.
+- If remote has `buf.work.yaml` / `buf.yaml` / `easyp.yaml` directories, install strips those prefixes so import paths match.
+
+Adapter: `internal/adapters/storage/`.
+
+---
+
+## 7. Version resolution
+
+`repo.ReadRevision` (`internal/adapters/repository/git/read_revision.go`):
+
+| Requested version | Resolution |
+|-------------------|------------|
+| Pseudo-version `v0.0.0-<datetime>-<commit>` | Fetch that commit |
+| Omitted | `HEAD` → tag if present, else generate pseudo-version |
+| Explicit | tag → branch → commit hash (in that order) |
+
+Pseudo-version format mirrors Go modules: `v0.0.0-20240222234643-814bf88cf225`.
+
+Helpers: `RequestedVersion.IsGenerated()`, `IsOmitted()`, `GetParts()` in `internal/core/models/module.go`.
+
+Remote URL construction: always `https://` + module path (`getRemote` in `internal/adapters/repository/git/git.go`). No SSH URLs in deps strings.
+
+---
+
+## 8. Transitive / module config
+
+`ModuleConfig.ReadFromRepo` (`internal/adapters/module_config/read_from_repo.go`) tries, in order:
+
+1. **Buf** (`buf.work.yaml` v1 or `buf.yaml` v2) → **directories only** (no dependency list)
+2. **EasyP** (`easyp.yaml`) → `deps` become transitive `Dependencies`; `generate.inputs[].input_files_dir.root` become `Directories`
+3. Else empty config
+
+Indirect deps are installed only when the remote module ships an `easyp.yaml` with `deps`. Buf-only modules do not pull transitive packages via EasyP.
+
+---
+
+## 9. Consumers (auto-download)
+
+| Command | Calls `Download`? | Dep usage |
+|---------|-------------------|-----------|
+| `lint` | yes (`internal/core/lint.go`) | Import resolution via install dirs |
+| `generate` | yes (`internal/core/generate.go`) | Install dirs on import path; walks `git_repo` inputs |
+| `breaking` | yes (`internal/core/breaking_check.go`) | Same import resolution path |
+| `mod vendor` | via `Download` | Copies install trees |
+| `ls-files` | **no** | Uses lock + install dirs if present |
+
+### Import resolution order (`readFileFromImport`)
+
+1. Local project file
+2. Each `c.deps` module’s `GetInstallDir` (via lock version)
+3. Embedded well-known types (`wellknownimports`)
+
+---
+
+## 10. Auth and private repos
+
+No auth fields in `easyp.yaml`. Fetch always uses HTTPS + system `git`.
+
+Documented operational patterns (outside code):
+
+- SSH: `git config url."git@host:.insteadOf" "https://host/"`
+- Tokens: credential helper / URL rewrite
+- Corporate CA / proxy: standard git / HTTP env
+
+`generate.plugins[].remote` is **remote plugin execution** (gRPC), not proto dependency remotes.
+
+---
+
+## 11. Key packages and types
+
+| Package / type | Role |
+|----------------|------|
+| `internal/api.Mod` | CLI wiring for `mod` |
+| `internal/api.buildCore` | Assembles deps, storage, lock, vendor dir |
+| `core.Core` | `Download`, `Update`, `Get`, `Vendor` |
+| `core.Storage` | Cache dirs, install, hashes, install paths |
+| `core.LockFile` | Read / Write / IsEmpty / DepsIter |
+| `core.ModuleConfig` | Read buf/easyp layout from cloned repo |
+| `models.Module` | Name + `RequestedVersion` |
+| `models.LockFileInfo` | Name, version, hash |
+| `models.InstalledModuleInfo` | Name, hash, revision version (`.info` file) |
+| `models.Revision` | CommitHash + Version |
+| `models.ModuleConfig` | `Dependencies` + `Directories` |
+| `adapters/repository/git` | Bare clone, fetch, archive, revision resolve |
+| `adapters/lock_file` | `easyp.lock` I/O |
+| `adapters/storage` | `$EASYPPATH` layout |
+| `adapters/module_config` | Buf / EasyP module config readers |
+
+### Domain errors (`internal/core/models`)
+
+| Error | Meaning |
+|-------|---------|
+| `ErrVersionNotFound` | Tag/branch/commit could not be resolved |
+| `ErrHashDependencyMismatch` | Lock hash ≠ installed tree hash |
+| `ErrModuleNotFoundInLockFile` | Module missing from lock |
+| `ErrModuleInfoFileNotFound` | No `.info` → need install |
+| `ErrModuleNotInstalled` | Install dir missing |
+| `ErrFileNotFound` | Module config file missing in repo |
+
+---
+
+## 12. Agent rules
+
+- Prefer this spec + code over outdated docs/skills that say vendor → `vendor/` (actual: `easyp_vendor`).
+- Do not invent remotes, mirrors, or auth YAML fields; they do not exist.
+- Do not hand-edit generated `schemas/*.json` for deps schema changes — update `mcp/easypconfig` / `internal/config`, then `task schema:generate`.
+- Commit `easyp.lock` for reproducible CI; cache lives outside the repo (`EASYPPATH`).
+- `mod download` is lock-first; use `mod update` to refresh versions from config.
+- Archives contain only `*.proto`; non-proto files from deps are never installed.
+- Transitive deps require the dependency’s own `easyp.yaml`; buf configs alone do not declare them.
+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..aadfa9c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,77 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in this repository.
+
+## Project overview
+
+EasyP is a Protocol Buffers CLI toolkit (`github.com/easyp-tech/easyp`, Go 1.24) that provides:
+
+- linting (buf-compatible rules)
+- breaking change detection
+- code generation (local and remote plugins)
+- Git-based dependency / package management (`easyp mod`)
+
+Human-facing docs: [README.md](README.md) and https://easyp.tech.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `cmd/easyp` | CLI entrypoint |
+| `internal/api` | CLI command wiring |
+| `internal/core` | Business logic (lint, generate, mod, breaking) |
+| `internal/rules` | Lint rules (each rule + colocated `_test.go`) |
+| `internal/config` | `easyp.yaml` parsing and validation |
+| `internal/adapters` | Git, storage, lockfile, plugins |
+| `mcp/easypconfig` | MCP tool + config schema metadata (source of truth) |
+| `schemas/` | Generated JSON Schema artifacts |
+| `docs/` | Documentation site (Vite) |
+
+## What is .spec/
+.spec/ is a project documentation directory optimized for AI agent (LLM) consumption. It contains:
+
+* Structured descriptions of architecture, packages, and domain model
+* Code conventions and testing patterns
+* Infrastructure and tooling descriptions
+* Agent rules (agent-rules.md) with mandatory coding standards
+* Purpose: give the agent full project context without reading the entire source code.
+
+
+## Build, test, lint
+
+Prefer Task targets from [`Taskfile.yml`](Taskfile.yml):
+
+```sh
+task init              # install local tools (golangci-lint, gotestsum, mockery)
+task build             # go build -o easyp ./cmd/easyp
+task test              # gotestsum with -race and coverage
+task lint              # golangci-lint (+ hadolint where applicable)
+task quality           # test + lint
+task schema:generate   # regenerate schemas/*.json
+task schema:check      # generate and fail if schemas drift
+task mocks             # regenerate mockery mocks for core/storage interfaces
+```
+
+Equivalents without Task:
+
+```sh
+go build -o easyp ./cmd/easyp
+go test -race -count=1 ./...
+go run ./cmd/easyp schema-gen
+```
+
+After behavior changes, run the relevant tests (at least the packages you touched). For config schema changes, run `task schema:check` before finishing.
+
+## Conventions
+
+- **New lint rules**: add `internal/rules/<rule>.go` + `_test.go`, register via the existing rule builder; mirror patterns in neighboring rules.
+- **`easyp.yaml` schema**: change metadata/validation in `mcp/easypconfig` and/or `internal/config`, then regenerate `schemas/` with `task schema:generate`. Do not hand-edit generated schema JSON.
+- **Tests**: use `testify`; regenerate mocks with `task mocks` when core/storage interfaces change.
+- Prefer pointing agents/humans at README and docs over copying long usage text into this file.
+
+## Do not
+
+- Commit secrets, credentials, or unrelated local artifacts.
+- Hand-edit `schemas/easyp-config-v1.schema.json` or `schemas/easyp-config.schema.json` without regenerating.
+- Commit or “fix” noise under `docs/node_modules`, `coverage.out`, or the local `easyp` binary in the repo root.
+- Add parallel agent instruction files (`.cursor/rules/`, `CLAUDE.md`) unless explicitly requested; keep this file the source of truth.