docs: refactor AGENTS.md and CLAUDE.md with progressive disclosure (CopilotKit#3259)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: AlemTuzlak

.claude/docs/architecture.md

@@ -0,0 +1,75 @@
+# Architecture & Packages
+
+## Three-Layer Architecture
+
+```
+Frontend (React/Angular/Vanilla)  →  Runtime (Express/Hono server)  →  Agent (LangGraph/CrewAI/BuiltIn/Custom)
+```
+
+All layers communicate via the **AG-UI protocol** — an event-based standard streamed over SSE.
+
+## V1 vs V2
+
+V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public API that wraps V2 internally. New features always go in V2. If V1 compatibility is needed, create a thin re-export or wrapper in the corresponding V1 package.
+
+## V2 Packages
+
+- **shared**: Common utilities, types, and constants used across all other packages.
+- **core**: The `CopilotKitCore` orchestrator — the central brain on the frontend. Manages the agent registry, tool registry, context store, and event subscriptions. All framework packages (React, Angular, Vanilla) wrap this.
+- **react**: React hooks (`useAgent`, `useFrontendTool`, `useAgentContext`, etc.) and `CopilotKitProvider`. Hooks are thin wrappers that register/unregister with `CopilotKitCore` on mount/unmount.
+- **angular**: Angular DI tokens, services, and signal-based state. Same concepts as React but using Angular patterns (`inject()`, signals, `AgentStore`).
+- **runtime**: The server-side `CopilotRuntime` class that receives HTTP requests and delegates to agents. Provides Express and Hono adapters. Contains the `AgentRunner` abstraction for managing thread/conversation state.
+- **agent**: The `BuiltInAgent` — a default agent implementation powered by the Vercel AI SDK. Used when developers don't bring their own agent framework.
+- **voice**: Voice input and transcription support.
+- **web-inspector**: A debug console (Lit web component) for inspecting agent communication in development.
+- **sqlite-runner**: An `AgentRunner` implementation that persists thread state to SQLite instead of memory.
+
+## V1 Packages
+
+- **react-core**: The public `<CopilotKit>` provider and hooks. Internally delegates to V2 core.
+- **react-ui**: Chat UI components — `CopilotChat`, `CopilotPopup`, `CopilotSidebar`, `CopilotPanel`.
+- **react-textarea**: The `CopilotTextarea` component for AI-assisted text editing.
+- **shared**: Shared types and telemetry utilities.
+- **runtime**: Server-side runtime with GraphQL server and LLM adapters.
+- **runtime-client-gql**: urql-based GraphQL client for frontend-to-runtime communication.
+- **sdk-js**: Helpers for LangGraph/LangChain agent integration.
+
+## Request Lifecycle
+
+1. **Init**: Frontend creates `CopilotKitCore` → fetches agent info from runtime → creates a `ProxiedAgent` instance per remote agent.
+2. **User sends message**: Message is added to the agent, then `runAgent()` is called.
+3. **HTTP request**: A POST is sent to the runtime with a `RunAgentInput` payload containing messages, registered tools, context, threadId, and state.
+4. **Runtime processing**: Request middleware runs → agent is resolved and cloned → `AgentRunner` executes the agent.
+5. **SSE stream back**: Agent emits AG-UI events streamed to the frontend: run lifecycle events, text message chunks (streaming), and optional tool call events.
+6. **Frontend tool execution**: When the agent calls a frontend tool, Core looks up the handler in its registry, executes it locally in the browser, and sends the result back to the agent which continues processing.
+7. **UI update**: Core updates its message store and notifies subscribers → React/Angular re-renders.
+
+## Core Concepts
+
+### AG-UI Protocol
+
+All agent↔UI communication is event-based. Events follow a structured lifecycle: `RUN_STARTED` → `STEP_STARTED` → message/tool events → `STEP_FINISHED` → `RUN_FINISHED`. Events are streamed over SSE and validated with Zod schemas. The `EventType` enum in `@ag-ui/core` defines all event types.
+
+### ProxiedAgent
+
+The frontend representation of a remote agent. Implements the `AbstractAgent` interface but translates calls into HTTP requests to the runtime, streaming SSE events back. Created automatically when the runtime reports available agents.
+
+### AgentRunner
+
+An abstract class on the runtime side responsible for managing thread state (conversation history, agent state). The default `InMemoryAgentRunner` is ephemeral; `SQLiteAgentRunner` provides persistence. Custom runners can be built for any storage backend.
+
+### Tool Registration
+
+Tools can be **frontend tools** (handler runs in the browser, registered via `useFrontendTool`) or **backend tools** (handler runs on the server, defined in the agent config). Tools can be scoped to a specific agent via `agentId`, or available to all agents by omitting it.
+
+### Context
+
+Application data sent alongside messages to give agents awareness of the current UI state. Registered via `useAgentContext(description, data)` where data is any JSON-serializable value. Automatically included in every agent run.
+
+### Multi-Agent
+
+Multiple agents can be registered in a single `CopilotRuntime`. Each agent gets its own endpoint, message thread, state, and optionally scoped tools. The frontend selects which agent to interact with via `useAgent({ agentId })`.
+
+### Middleware
+
+`CopilotRuntime` supports `beforeRequestMiddleware` and `afterRequestMiddleware` for cross-cutting concerns like authentication, logging, and request/response transformation.

.claude/docs/git.md

@@ -0,0 +1,27 @@
+# Git & PRs
+
+## Worktree Workflow
+
+Always use a git worktree for non-trivial work. This keeps the main working tree clean and lets you work in isolation.
+
+1. **Start a worktree** at the beginning of a task. This creates a new branch and a separate working directory.
+2. **Do all work** inside the worktree — commits, builds, tests.
+3. **Push the worktree branch** to the remote with `-u` to set up tracking.
+4. **Create a PR** targeting `main` using `gh pr create --base main`.
+5. **Clean up** the worktree after the PR is merged.
+
+## Creating a PR
+
+When the work is ready:
+
+1. Stage and commit your changes in the worktree.
+2. Push the branch: `git push -u origin <branch-name>`
+3. Create the PR: `gh pr create --base main`
+4. Use a clear title (under 70 chars) and a body summarizing what changed and why.
+
+## Commit Conventions
+
+- Write concise commit messages focused on the "why", not the "what".
+- Stage specific files — avoid `git add -A` or `git add .` to prevent accidentally including unrelated changes.
+- Never amend commits unless explicitly asked. Always create new commits.
+- Never force-push unless explicitly asked.

.claude/docs/hooks.md

@@ -0,0 +1,8 @@
+# Hook Development
+
+When creating a new hook, always complete **all** of the following:
+
+1. **Implementation**: Create the hook in the V2 react package. If V1 compatibility is needed, add a re-export in the V1 react-core package.
+2. **JSDoc**: Add JSDoc on top of the hook implementation, including usage examples.
+3. **Tests**: Write extensive tests covering behavior, edge cases, and lifecycle (mount/unmount/re-render).
+4. **Documentation**: Add a dedicated docs page under `/docs` and update the relevant docs metadata file(s) so the page appears in navigation.

.claude/docs/workflow.md

@@ -0,0 +1,30 @@
+# Workflow & Process
+
+## When to Plan vs. Fix Autonomously
+
+- **Bug fixes** (small/medium, < 5 files): Fix autonomously. No plan mode, no check-in. Just fix it, run tests, done.
+- **Large bugs** (5+ files or architectural impact): Enter plan mode first.
+- **New features and refactors**: Always enter plan mode. Get user sign-off on the approach before implementing.
+
+## Planning
+
+- Enter plan mode for non-trivial features and refactors.
+- Write the plan to `tasks/todo.md` with checkable items.
+- If something goes sideways during implementation, stop and re-plan — don't push through a broken approach.
+
+## Verification
+
+- Never mark a task complete without proving it works.
+- Run tests and check for regressions.
+- Diff behavior between main and your changes when relevant.
+
+## Bug Fixing
+
+- When given a bug report: find the root cause, fix it, verify. No hand-holding needed.
+- Point at logs, errors, failing tests — then resolve them.
+- Go fix failing CI tests without being told how.
+
+## Self-Improvement
+
+- After any correction from the user: update `tasks/lessons.md` with the pattern and a rule to prevent it.
+- Review lessons at session start.

AGENTS.md

@@ -13,11 +13,20 @@
 
 <!-- nx configuration end-->
 
-# Hook Development Requirements
+# CopilotKit
 
-When creating a new hook, always complete all of the following:
+AI agent framework with three layers: **Frontend** (React/Angular/Vanilla) → **Runtime** (Express/Hono) → **Agent** (LangGraph/CrewAI/BuiltIn/Custom), communicating via the AG-UI protocol (event-based SSE).
 
-- Add dedicated documentation for the hook under `/docs`.
-- Update the relevant docs metadata file(s) so the page appears in docs navigation.
-- Add JSDoc on top of the hook implementation, including usage examples.
-- Write extensive tests for the hook (covering behavior, edge cases, and lifecycle where applicable).
+## Essentials
+
+- **Nx monorepo** — always run tasks through `nx` (`nx run`, `nx run-many`, `nx affected`), never the underlying tooling directly.
+- **V1 wraps V2** — V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public compatibility layer that delegates to V2. Build new features in V2 first. Add V1 wrappers only if backward compatibility is needed.
+- **Simplicity** — prefer the simplest correct solution. For non-trivial changes, consider if there's a cleaner approach before committing.
+- **Worktrees** — always work in a git worktree for isolation. See [Git & PRs](.claude/docs/git.md) for the full workflow.
+
+## Reference (read when relevant to your task)
+
+- [Architecture & Packages](.claude/docs/architecture.md) — V2/V1 package roles, request lifecycle, core concepts (AG-UI, ProxiedAgent, AgentRunner, tools, context, multi-agent)
+- [Hook Development](.claude/docs/hooks.md) — checklist for creating new hooks (docs, tests, JSDoc)
+- [Workflow & Process](.claude/docs/workflow.md) — when to plan, when to fix autonomously, verification, self-improvement loop, this should be your default mindset when working on any task
+- [Git & PRs](.claude/docs/git.md) — worktree workflow, branching, creating PRs

CLAUDE.md

@@ -13,11 +13,20 @@
 
 <!-- nx configuration end-->
 
-# Hook Development Requirements
+# CopilotKit
 
-When creating a new hook, always complete all of the following:
+AI agent framework with three layers: **Frontend** (React/Angular/Vanilla) → **Runtime** (Express/Hono) → **Agent** (LangGraph/CrewAI/BuiltIn/Custom), communicating via the AG-UI protocol (event-based SSE).
 
-- Add dedicated documentation for the hook under `/docs`.
-- Update the relevant docs metadata file(s) so the page appears in docs navigation.
-- Add JSDoc on top of the hook implementation, including usage examples.
-- Write extensive tests for the hook (covering behavior, edge cases, and lifecycle where applicable).
+## Essentials
+
+- **Nx monorepo** — always run tasks through `nx` (`nx run`, `nx run-many`, `nx affected`), never the underlying tooling directly.
+- **V1 wraps V2** — V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public compatibility layer that delegates to V2. Build new features in V2 first. Add V1 wrappers only if backward compatibility is needed.
+- **Simplicity** — prefer the simplest correct solution. For non-trivial changes, consider if there's a cleaner approach before committing.
+- **Worktrees** — always work in a git worktree for isolation. See [Git & PRs](.claude/docs/git.md) for the full workflow.
+
+## Reference (read when relevant to your task)
+
+- [Architecture & Packages](.claude/docs/architecture.md) — V2/V1 package roles, request lifecycle, core concepts (AG-UI, ProxiedAgent, AgentRunner, tools, context, multi-agent)
+- [Hook Development](.claude/docs/hooks.md) — checklist for creating new hooks (docs, tests, JSDoc)
+- [Workflow & Process](.claude/docs/workflow.md) — when to plan, when to fix autonomously, verification, self-improvement loop, this should be your default mindset when working on any task
+- [Git & PRs](.claude/docs/git.md) — worktree workflow, branching, creating PRs