chore(agent): rename guidance directory to docs-ai

Move the repository-owned agent guidance from ai/ to docs-ai/ and update Codex, Claude Code, Cursor, README, docs, and area AGENTS pointers. Keep the directory tool-neutral while making its purpose more obvious as documentation.

Author: chicoxyzzy

.cursor/rules/00-core.mdc

@@ -8,7 +8,7 @@ alwaysApply: true
 
 Hecate is an open-source AI gateway and agent-task runtime. The Go gateway embeds the React operator UI, mediates OpenAI- and Anthropic-shaped client traffic, runs queued `agent_loop` tasks with policy and approval gates, and emits OpenTelemetry traces for everything it does. Companion entrypoints such as `hecate-acp` handle protocols that need their own process lifecycle.
 
-The canonical, vendor-neutral instruction layer for this repo lives in [`ai/`](../../ai/README.md). Start there. This file is a thin Cursor adapter listing the top-level non-negotiables.
+The canonical, vendor-neutral instruction layer for this repo lives in [`docs-ai/`](../../docs-ai/README.md). Start there. This file is a thin Cursor adapter listing the top-level non-negotiables.
 
 ## Non-negotiables
 
@@ -25,7 +25,7 @@ The canonical, vendor-neutral instruction layer for this repo lives in [`ai/`](.
 
 ## Pointers
 
-- Full project context: [`ai/core/project-context.md`](../../ai/core/project-context.md).
-- Project-wide conventions: [`ai/core/engineering-standards.md`](../../ai/core/engineering-standards.md).
-- Operating loop: [`ai/core/workflow.md`](../../ai/core/workflow.md).
-- Verification ladders: [`ai/core/verification.md`](../../ai/core/verification.md).
+- Full project context: [`docs-ai/core/project-context.md`](../../docs-ai/core/project-context.md).
+- Project-wide conventions: [`docs-ai/core/engineering-standards.md`](../../docs-ai/core/engineering-standards.md).
+- Operating loop: [`docs-ai/core/workflow.md`](../../docs-ai/core/workflow.md).
+- Verification ladders: [`docs-ai/core/verification.md`](../../docs-ai/core/verification.md).

.cursor/rules/10-planning.mdc

@@ -31,9 +31,9 @@ Substantial changes get a plan before code. Trivial changes (typo fixes, single-
 
 `pkg/types/chat.go` → `internal/api/openai.go` (request struct) → `internal/api/handler_chat.go` (`normalizeChatRequest`) → `internal/providers/openai.go` (lowercase parallel struct) → **both `Chat` and `ChatStream` `wireReq` constructions** in that same file → `internal/providers/anthropic.go` `warnUnsupportedFieldsDropped` → tests at every layer. Forgetting the streaming `wireReq` is the most common bug.
 
-Full chain with file references: [`ai/skills/providers/SKILL.md`](../../ai/skills/providers/SKILL.md).
+Full chain with file references: [`docs-ai/skills/providers/SKILL.md`](../../docs-ai/skills/providers/SKILL.md).
 
 ## Pointers
 
-- Plan format: [`ai/tasks/planning.md`](../../ai/tasks/planning.md).
-- Architect skill (plan template, output shape, anti-patterns): [`ai/skills/architect/SKILL.md`](../../ai/skills/architect/SKILL.md).
+- Plan format: [`docs-ai/tasks/planning.md`](../../docs-ai/tasks/planning.md).
+- Architect skill (plan template, output shape, anti-patterns): [`docs-ai/skills/architect/SKILL.md`](../../docs-ai/skills/architect/SKILL.md).

.cursor/rules/20-testing.mdc

@@ -34,5 +34,5 @@ Race suite is the floor for any change touching `internal/gateway`, `internal/ro
 
 ## Pointers
 
-- Full ladder and done criteria: [`ai/core/verification.md`](../../ai/core/verification.md).
-- Layer-choice matrix and edge cases: [`ai/skills/tester/SKILL.md`](../../ai/skills/tester/SKILL.md).
+- Full ladder and done criteria: [`docs-ai/core/verification.md`](../../docs-ai/core/verification.md).
+- Layer-choice matrix and edge cases: [`docs-ai/skills/tester/SKILL.md`](../../docs-ai/skills/tester/SKILL.md).

.cursor/rules/30-review.mdc

@@ -27,4 +27,4 @@ For each change, run a pass on each axis. Cite `file:line` for every finding.
 
 ## Pointer
 
-Full rubric and discussion: [`ai/tasks/code-review.md`](../../ai/tasks/code-review.md).
+Full rubric and discussion: [`docs-ai/tasks/code-review.md`](../../docs-ai/tasks/code-review.md).

AGENTS.md

@@ -11,20 +11,20 @@ This file is the orientation entry — the codebase map, the runtime
 invariants, and the gotchas that bite often. It is what an agent
 (Claude Code, Codex, Cursor, or human) reaches for when starting work
 on this repo. Conventions, workflow, verification, and longer-form
-guidance live in [`ai/`](ai/README.md).
+guidance live in [`docs-ai/`](docs-ai/README.md).
 
 ## Where guidance lives
 
 | Surface | What it carries |
 |---|---|
-| [`ai/`](ai/README.md) | Canonical agent guidance — project context, conventions, workflow, verification, task shapes, area + posture skills |
+| [`docs-ai/`](docs-ai/README.md) | Canonical agent guidance — project context, conventions, workflow, verification, task shapes, area + posture skills |
 | `AGENTS.md` (this) and `ui/AGENTS.md`, `internal/providers/AGENTS.md` | Codebase map per area |
-| [`CLAUDE.md`](CLAUDE.md) | Thin Claude Code adapter pointing to `ai/` |
-| [`.cursor/rules/`](.cursor/rules/) | Thin Cursor adapter pointing to `ai/` |
+| [`CLAUDE.md`](CLAUDE.md) | Thin Claude Code adapter pointing to `docs-ai/` |
+| [`.cursor/rules/`](.cursor/rules/) | Thin Cursor adapter pointing to `docs-ai/` |
 | [`.claude/commands/`](.claude/commands/) | Slash commands: `/race`, `/typecheck`, `/test-affected` |
 | [`docs/`](docs/) | Long-form references (architecture, runtime API, events, telemetry) |
 
-When in doubt: read [`ai/core/project-context.md`](ai/core/project-context.md) and [`ai/core/workflow.md`](ai/core/workflow.md).
+When in doubt: read [`docs-ai/core/project-context.md`](docs-ai/core/project-context.md) and [`docs-ai/core/workflow.md`](docs-ai/core/workflow.md).
 
 ## Codebase map
 
@@ -44,7 +44,7 @@ scripts/
   stamp-version.ts      stamp Tauri version files to current git tag / TAURI_VERSION
 e2e/                    binary-startup tests; build tag e2e (sub-tags: ollama, docker)
 docs/                   long-form references (architecture, runtime API, events, ...)
-ai/                     canonical agent guidance (this file points there for depth)
+docs-ai/                canonical agent guidance (this file points there for depth)
 
 internal/
   api/                  inbound HTTP shapes + handlers (OpenAIChatMessage, uppercase)
@@ -85,7 +85,7 @@ pkg/types/  ←  internal/api/  ←  internal/providers/
               internal/orchestrator/  (sits above api, drives runs through providers)
 ```
 
-The api↔providers parallel-struct duplication (`OpenAIChatMessage` ↔ `openAIChatMessage`) is intentional — it keeps `internal/providers/` free of `internal/api/` imports. Full rationale: [`ai/skills/providers/SKILL.md`](ai/skills/providers/SKILL.md).
+The api↔providers parallel-struct duplication (`OpenAIChatMessage` ↔ `openAIChatMessage`) is intentional — it keeps `internal/providers/` free of `internal/api/` imports. Full rationale: [`docs-ai/skills/providers/SKILL.md`](docs-ai/skills/providers/SKILL.md).
 
 **Storage tier rule**: every backend-bound concern mirrors two tiers —
 memory (default) and sqlite (`modernc.org/sqlite`, no CGO).
@@ -105,7 +105,7 @@ touches request handling, persistence, or tool execution.
 
 ## Conventions (in brief)
 
-Full standards: [`ai/core/engineering-standards.md`](ai/core/engineering-standards.md).
+Full standards: [`docs-ai/core/engineering-standards.md`](docs-ai/core/engineering-standards.md).
 
 - **Comments explain *why***, not what. State the trade-off.
 - **Pointer vs value for optional fields**: pointer when zero is a valid
@@ -118,7 +118,7 @@ Full standards: [`ai/core/engineering-standards.md`](ai/core/engineering-standar
 
 ## Verification
 
-Full ladder: [`ai/core/verification.md`](ai/core/verification.md).
+Full ladder: [`docs-ai/core/verification.md`](docs-ai/core/verification.md).
 
 - **Race suite is the floor for runtime/backend changes**: `go test -race -timeout 10m ./...` (or `/race`). Race builds are large; if your default `$GOCACHE` is on a small volume, point it at the repo: `GOCACHE="$(pwd)/.gocache" go test -race ...`.
 - **Iteration**: `/test-affected` for narrow runs.
@@ -129,11 +129,11 @@ Full ladder: [`ai/core/verification.md`](ai/core/verification.md).
 
 | Task | Where |
 |---|---|
-| Add a passthrough wire field (the seven-step chain — most-redone task here) | [`ai/skills/providers/SKILL.md`](ai/skills/providers/SKILL.md) |
-| Add an MCP tool / persisted run-event type / test helper cheat-sheet | [`ai/skills/backend/SKILL.md`](ai/skills/backend/SKILL.md) |
-| UI recipes (SSE-driven state field, paired pickers, snapshot refresh) | [`ai/skills/ui/SKILL.md`](ai/skills/ui/SKILL.md) |
-| Native desktop app (sidecar lifecycle, bundling, Tauri commands) | [`ai/skills/tauri/SKILL.md`](ai/skills/tauri/SKILL.md) |
-| Cut a release tag | `bun scripts/release.ts vX.Y.Z` — checks worktree, snapshot dry-run, stamps Tauri versions, tags, pushes. Full procedure: [`ai/tasks/release.md`](ai/tasks/release.md) |
+| Add a passthrough wire field (the seven-step chain — most-redone task here) | [`docs-ai/skills/providers/SKILL.md`](docs-ai/skills/providers/SKILL.md) |
+| Add an MCP tool / persisted run-event type / test helper cheat-sheet | [`docs-ai/skills/backend/SKILL.md`](docs-ai/skills/backend/SKILL.md) |
+| UI recipes (SSE-driven state field, paired pickers, snapshot refresh) | [`docs-ai/skills/ui/SKILL.md`](docs-ai/skills/ui/SKILL.md) |
+| Native desktop app (sidecar lifecycle, bundling, Tauri commands) | [`docs-ai/skills/tauri/SKILL.md`](docs-ai/skills/tauri/SKILL.md) |
+| Cut a release tag | `bun scripts/release.ts vX.Y.Z` — checks worktree, snapshot dry-run, stamps Tauri versions, tags, pushes. Full procedure: [`docs-ai/tasks/release.md`](docs-ai/tasks/release.md) |
 | Stamp Tauri version files | `bun scripts/stamp-version.ts` (or `make tauri-version`) — syncs Cargo.toml, package.json, tauri.conf.json to current git tag |
 
 ## Gotchas
@@ -142,7 +142,7 @@ Full ladder: [`ai/core/verification.md`](ai/core/verification.md).
 - **modernc/sqlite TIME-as-text format**: the driver writes `time.Time` using Go's default `time.Time.String()` format, which doesn't lex-compare with RFC3339Nano cutoffs and silently breaks the retention sweep. Always write timestamps as `t.UTC().Format(time.RFC3339Nano)` when the column is TEXT (see `internal/taskstate/sqlite.go` `AppendRunEvent`).
 - **OpenAI/openAI parallel structs are intentional**: don't unify. Mirror fields when adding on either side.
 - **Streaming `wireReq` plumbing**: when adding a passthrough field, plumb it into BOTH `Chat` and `ChatStream` `wireReq` constructions in `internal/providers/openai.go`. Forgetting one is the most common provider bug — non-stream tests pass; the field silently drops in production for any client using `stream: true`.
-- **Capability-cache seeding** for provider tests: seed `cachedCaps` and `capsExpiry` to skip the discovery path. Snippet in [`ai/skills/providers/SKILL.md`](ai/skills/providers/SKILL.md).
+- **Capability-cache seeding** for provider tests: seed `cachedCaps` and `capsExpiry` to skip the discovery path. Snippet in [`docs-ai/skills/providers/SKILL.md`](docs-ai/skills/providers/SKILL.md).
 - **Pricebook preflight** in tests: `PROVIDER_FAKE_KIND=local` for synthetic models in e2e.
 - **mermaid `loop` is a reserved keyword**: don't use it as a sequence-diagram participant name. Use `Agent` or similar.
 - **CodeQL CWE-190**: don't compute `make([]T, 0, len(x)+N)` with arithmetic — use plain `len(x)` and let `append` grow.

CLAUDE.md

@@ -1,22 +1,22 @@
 # CLAUDE.md
 
-This is the Hecate repo — an open-source AI gateway and agent-task runtime (Go gateway with embedded React UI plus companion integration entrypoints). Shared agent guidance lives in [`ai/`](ai/README.md). This file is a thin Claude-specific adapter; the substance lives there.
+This is the Hecate repo — an open-source AI gateway and agent-task runtime (Go gateway with embedded React UI plus companion integration entrypoints). Shared agent guidance lives in [`docs-ai/`](docs-ai/README.md). This file is a thin Claude-specific adapter; the substance lives there.
 
 ## Start here
 
-[`ai/README.md`](ai/README.md) is the entry point and map.
+[`docs-ai/README.md`](docs-ai/README.md) is the entry point and map.
 
 ## When working on this repo
 
 Pick the right skill for the change:
 
-- **Backend** (anything outside `ui/` and `tauri/`) — [`hecate-backend`](ai/skills/backend/SKILL.md).
-- **UI** (`ui/`) — [`hecate-ui`](ai/skills/ui/SKILL.md).
-- **Native desktop app** (`tauri/`) — [`hecate-tauri`](ai/skills/tauri/SKILL.md). Tauri 2.x Rust layer, sidecar lifecycle, platform bundling, gateway↔webview integration.
-- **Provider adapters** (`internal/providers/`, anything that crosses the api↔providers boundary) — [`hecate-providers`](ai/skills/providers/SKILL.md). Owns the canonical seven-step "add a wire field" chain.
-- **Planning a substantial change** — [`hecate-architect`](ai/skills/architect/SKILL.md). Produces a plan, not code.
-- **Test strategy / coverage audit / verification report** — [`hecate-tester`](ai/skills/tester/SKILL.md).
-- **Delivery review** (env vars, schema migrations, CI/CD, observability surfaces) — [`hecate-devops`](ai/skills/devops/SKILL.md).
+- **Backend** (anything outside `ui/` and `tauri/`) — [`hecate-backend`](docs-ai/skills/backend/SKILL.md).
+- **UI** (`ui/`) — [`hecate-ui`](docs-ai/skills/ui/SKILL.md).
+- **Native desktop app** (`tauri/`) — [`hecate-tauri`](docs-ai/skills/tauri/SKILL.md). Tauri 2.x Rust layer, sidecar lifecycle, platform bundling, gateway↔webview integration.
+- **Provider adapters** (`internal/providers/`, anything that crosses the api↔providers boundary) — [`hecate-providers`](docs-ai/skills/providers/SKILL.md). Owns the canonical seven-step "add a wire field" chain.
+- **Planning a substantial change** — [`hecate-architect`](docs-ai/skills/architect/SKILL.md). Produces a plan, not code.
+- **Test strategy / coverage audit / verification report** — [`hecate-tester`](docs-ai/skills/tester/SKILL.md).
+- **Delivery review** (env vars, schema migrations, CI/CD, observability surfaces) — [`hecate-devops`](docs-ai/skills/devops/SKILL.md).
 
 ## Useful slash commands
 
@@ -28,8 +28,8 @@ Pick the right skill for the change:
 
 ## Repo policy
 
-Shared agent guidance is repository-owned and committed. There is no `.local` override layer and no personal customization tier. If a rule belongs in agent context, it lives in [`ai/`](ai/README.md), in the open, under version control.
+Shared agent guidance is repository-owned and committed. There is no `.local` override layer and no personal customization tier. If a rule belongs in agent context, it lives in [`docs-ai/`](docs-ai/README.md), in the open, under version control.
 
 ## Note on `AGENTS.md`
 
-[`AGENTS.md`](AGENTS.md) at the repo root, [`ui/AGENTS.md`](ui/AGENTS.md), and [`internal/providers/AGENTS.md`](internal/providers/AGENTS.md) are the codebase map and the Codex-discoverable entry points. They stay scoped to map-and-recipes; conventions and longer guidance live in [`ai/`](ai/README.md).
+[`AGENTS.md`](AGENTS.md) at the repo root, [`ui/AGENTS.md`](ui/AGENTS.md), and [`internal/providers/AGENTS.md`](internal/providers/AGENTS.md) are the codebase map and the Codex-discoverable entry points. They stay scoped to map-and-recipes; conventions and longer guidance live in [`docs-ai/`](docs-ai/README.md).

README.md

@@ -219,7 +219,7 @@ First-run environment knobs live in [`.env.example`](.env.example).
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). If you work with an AI assistant, start with [AGENTS.md](AGENTS.md); the vendor-neutral agent instruction layer lives in [ai/](ai/README.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md). If you work with an AI assistant, start with [AGENTS.md](AGENTS.md); the vendor-neutral agent instruction layer lives in [docs-ai/](docs-ai/README.md).
 
 ## License
 

ai/README.md docs-ai/README.mdai/README.md renamed to docs-ai/README.md

@@ -7,7 +7,7 @@ point here — the substance lives in this directory.
 ## Layout
 
 ```
-ai/
+docs-ai/
   README.md                       this file — load order and quick rules
   core/
     project-context.md            what Hecate is, repo layout, rings, storage tiers, toolchain pins, risky areas

ai/core/engineering-standards.md docs-ai/core/engineering-standards.mdai/core/engineering-standards.md renamed to docs-ai/core/engineering-standards.md

@@ -33,7 +33,7 @@ docs/                      long-form references (canonical product/runtime docs)
 
 .claude/                   Claude Code adapter (slash commands, settings)
 .cursor/                   Cursor adapter (.mdc rule files)
-ai/                        canonical, vendor-neutral agent instruction layer (this directory)
+docs-ai/                        canonical, vendor-neutral agent instruction layer (this directory)
 ```
 
 ## Architecture rings