chore: add agent instruction guidance

.gitignore

@@ -147,11 +147,14 @@ packages/core/docs
 # Create VoltAgent App
 !packages/create-voltagent-app/templates/base/.env
 
-# cursor
-.cursor/*
-!.cursor/rules/
-.cursor/rules/*
-!.cursor/rules/agents.mdc
+# Local coding-agent and IDE config directories/files.
+# Keep shared instruction files such as AGENTS.md and CLAUDE.md tracked instead.
+.agents/
+.claude
+.codex/
+.cursor/
+.windsurf/
+/.mcp.json
 
 # vite and vitest
 vite.config.*.timestamp*
@@ -163,8 +166,6 @@ vitest.config.*.timestamp*
 # vscode
 .vscode
 
-# claude
-.claude
 skills
 !packages/core/src/workspace/skills
 !packages/core/src/workspace/skills/**
@@ -182,6 +183,9 @@ node_modules/
 # serena
 .serena
 
+# joggr
+.joggr
+
 
 # example skills
 !examples/with-workspace/workspace/skills

.husky/pre-commit

@@ -3,4 +3,4 @@
 
 cd "$(git rev-parse --show-toplevel)" || exit 1
 
-npx lint-staged --config package.json
+npx lint-staged

.prettierignore

@@ -2,4 +2,12 @@
 /dist
 /coverage
 /.nx/cache
-/.nx/workspace-data
+/.nx/workspace-data
+
+# Coding-agent instruction files. AGENTS.md is the canonical doc; CLAUDE.md
+# (and any future aliases configured in scripts/sync-agent-instructions.mjs)
+# are symlinks to it. Skipping both avoids two problems:
+#  1. Prettier 3.x errors on symlink paths passed via lint-staged.
+#  2. Mechanical reformatting churn on docs that are hand-curated for agents.
+AGENTS.md
+CLAUDE.md

AGENTS.md

@@ -1,37 +1,134 @@
 # VoltAgent
 
-VoltAgent is an open-source TypeScript framework for building and orchestrating AI agents.
+Open-source TypeScript monorepo for building and orchestrating AI agents with pluggable memory, tools, workflows, and observability.
 
-## What is VoltAgent?
+## Critical Rules
 
-VoltAgent is a comprehensive framework that enables developers to build sophisticated AI agents with memory, tools, observability, and sub-agent capabilities. It provides direct AI SDK integration with comprehensive OpenTelemetry tracing built-in.
+- **Verify before asserting.** Read or grep before claiming a hook signature, span attribute key, workflow step option, registry path, or public export exists in this codebase. Memory and prior context drift; the code is authoritative.
+- **`safeStringify` for production serialization.** Import from `@voltagent/internal` for logs, telemetry attributes, persistence, request/response bodies, and streamed payloads. `JSON.stringify` is acceptable only in tests, mocks, fixtures, or when matching a platform API.
+- **Add a changeset for any published-package change** that affects API, runtime behavior, package contents, dependencies, or migration. See [`contributing/changesets.md`](./contributing/changesets.md).
+- **Generated files are not hand-edited.** Regenerate `packages/core/src/registries/*.generated.ts` via `pnpm --dir packages/core generate:model-registry`. Do not pattern-source from `archive/` — it contains deprecated code.
+- **Validate scoped first, broaden only when crossing package boundaries.** Run `pnpm --dir packages/<pkg> test` before `pnpm test:all`.
+- **Conventional commits, enforced by husky.** Format: `type(scope): subject` (e.g., `fix(core): …`, `feat(server-hono): …`, `chore: …`). The `commit-msg` hook runs commitlint with `@commitlint/config-conventional`. Scope = affected package; omit for repo-wide chores.
 
-## Overview
+## Setup
 
-- View [`docs/structure.md`](./docs/structure.md) for the repository structure and organization
-- View [`docs/tooling.md`](./docs/tooling.md) for development tools and utilities
-- View [`docs/testing.md`](./docs/testing.md) for testing guidelines and commands
-- View [`docs/linting.md`](./docs/linting.md) for code formatting and linting
+Requires Node `>=20` and `pnpm@8.10.5` (pinned via `packageManager`).
 
-## Validating Changes
+```bash
+pnpm install            # Install workspace deps
+pnpm build:all          # Build every package (run before dev for cross-package types)
+pnpm dev                # Watch all packages (excludes example apps)
+```
 
-To validate your changes you can run the following commands:
+## Validation
 
 ```bash
-pnpm test:all        # Run all tests
-pnpm build:all       # Build all packages
-pnpm lint            # Run linting checks
-pnpm lint:fix        # Auto-fix linting issues
+# Root (use only when changes cross package boundaries)
+pnpm lint
+pnpm test:all
+pnpm build:all
+
+# Scoped (preferred — fast, focused)
+pnpm --dir packages/core test
+pnpm --dir packages/core typecheck
+pnpm --dir packages/core build
+pnpm --dir packages/core test:single -- src/path/to/file.spec.ts
+pnpm --dir website build
 ```
 
-## Important Notes for AI Agents
+## Boundaries
+
+**Allowed without asking**
+
+- Read files; run lint, typecheck, test, build commands.
+- Edit code within a single package; add or update tests; add a changeset.
+- Fix typos in `README.md` files and inline comments without changing structure or examples.
+- Add new examples under `examples/with-<integration>/` (copy an existing example as the template).
+
+**Ask first**
+
+- New dependencies (root or any package) or version bumps of `node`, `pnpm`, `tsup`, `vitest`, `biome`, `typescript`.
+- Cross-package public API changes; new public packages; new server runtime adapters.
+- Adding nested `AGENTS.md` files (then run `./scripts/sync-agent-instructions.mjs` to refresh symlinks).
+- Editing `packages/core/src/registries/*.generated.ts`, `archive/`, deprecated packages, `.changeset/config*.json`, CI workflows, husky hooks, `tools/`, root `tsconfig*.json`, `pnpm-workspace.yaml`, `pnpm-lock.yaml`, root `package.json`.
+- Editing `.github/` (issue templates, PR template, workflows, `FUNDING.yml`).
+- Removing tests; deleting docs without setting up redirects; bumping example app dependencies.
+- Bypassing hooks (`--no-verify`) or skipping commitlint scope conventions.
+- Restructuring `packages/`, `examples/`, or top-level `website/` doc trees.
+
+**Never without explicit ask**
+
+- `git push --force` to any shared branch; force-pushing to `main`; amending pushed commits.
+- `pnpm publish` / `lerna publish`; deleting packages or public exports.
+- Modifying or deleting `.changeset/*.md` files that have already been merged or versioned.
+- Committing build outputs (`dist/`, `build/`, `.next/`, `.docusaurus/`) or per-developer IDE config (`.claude.local.md`, `.mcp.json`, `.cursor/`, `.codex/`, `.windsurf/` — see [`contributing/coding-agents.md`](./contributing/coding-agents.md)).
+- Committing secrets, local credentials, or `.env*` files.
+
+## Commit Conventions
+
+- **Husky `pre-commit`** runs `lint-staged`: Biome on TS/JS, Prettier on Markdown/MDX.
+- **Husky `commit-msg`** runs commitlint with `@commitlint/config-conventional`.
+- **Format**: `type(scope): subject`. Scope = the affected package; omit for repo-wide chores. Scopes seen in history: `core`, `server-core`, `server-hono`, `server-elysia`, `serverless-hono`, `internal`, `cli`, `changesets` (CI).
+
+## PR Conventions
+
+- **Fill out the PR template at [`.github/pull_request_template.md`](./.github/pull_request_template.md).** It has the project's canonical checklist (commit-convention link, related issue, tests, docs, changeset link). Do not delete sections.
+- **Title** mirrors the conventional-commit scope/type used in your first commit (`fix(core): …`, `feat(server-hono): …`). Not enforced by a bot, but reviewers expect it.
+- **Changeset rule** (extends the template's "Changesets have been added" checkbox):
+  - Published-package change (API, runtime behavior, package contents, deps, migration) → run `pnpm changeset`, commit the generated `.changeset/*.md`. Patch / minor / major rules in [`contributing/changesets.md`](./contributing/changesets.md).
+  - Internal-only change (CI, repo tooling, contributing docs, examples-only fixes) → no changeset needed; check the "Changesets have been added" box only when one was actually added.
+- **Releases** are automated by Lerna + Changesets via the `ci(changesets): version packages` PR.
+
+## Code Style
 
-1. **Always check existing patterns** before implementing new features
-2. **Use the established registry patterns** for agent and tool management
-3. **Maintain type safety** - this is a TypeScript-first codebase
-4. **Follow the monorepo structure** - changes may impact multiple packages
-5. **Test your changes** - ensure all tests pass before committing
+- **Cross-package imports use `@voltagent/<pkg>` in production code**, not relative paths into another package. Test fixtures may reach across packages relatively when stubbing internal types.
+- **Avoid new `as any` and `as unknown as T` casts.** Existing core source has them; treat as legacy. New code should narrow with type guards, fix the upstream type, or accept a `// biome-ignore` with a one-line justification.
+- **Public APIs preserve inference.** Return types should flow from implementations — over-typing breaks downstream consumers.
+- **Use existing managers, registries, and context keys** (`AgentRegistry`, `WorkspaceManager`, `OperationContext`, etc.) before introducing new global state.
+- **`console.log` is a Biome error under `packages/core/**`** — use the package logger or `@voltagent/logger` instead.
+- Biome handles TS/JS formatting + lint (`pnpm lint:fix`); Prettier handles Markdown/MDX via lint-staged.
 
-## Gotchas
+```ts
+// Good — production serialization
+import { safeStringify } from "@voltagent/internal";
+span.setAttribute("agent.context", safeStringify(contextMap));
+
+// Acceptable — test fixtures only
+const fixture = JSON.stringify({ input: "test" });
+```
+
+See [`contributing/linting.md`](./contributing/linting.md).
+
+## Project Structure
+
+```
+packages/        # Published packages: core runtime, memory adapters, server runtimes,
+                 # telemetry exporters, sandboxes, MCP/A2A servers, SDK, CLI, voice.
+examples/        # Runnable apps; naming `with-<integration>`. Copy-pasteable.
+website/         # Docusaurus docs site (uses npm — NOT in the pnpm workspace).
+contributing/    # Contributor + coding-agent docs.
+scripts/, tools/ # Repo tooling.
+archive/         # Deprecated code; do not pattern-source from it.
+.changeset/      # Pending version bumps. Generated by `pnpm changeset`.
+.github/         # PR template, issue templates, workflows.
+```
+
+Full layout: [`contributing/structure.md`](./contributing/structure.md).
+
+## Documentation Index
+
+Prefer retrieval-led reasoning — open the linked file before answering. The index points at where things live; the files contain the actual contracts and examples.
+
+```
+<docs-index>
+root: ./
+contributing/:{README.md=contributor-docs index,structure.md=full package list (~25) + naming conventions,tooling.md=pnpm/Lerna/Nx/Biome/tsup/Changesets toolchain,testing.md=Vitest patterns + AI SDK mocking via MockLanguageModelV3,linting.md=Biome commands + VS Code setup,changesets.md=patch/minor/major rules + when changeset is/isn't needed,coding-agents.md=supported agent matrix + CLAUDE.md→AGENTS.md symlink convention}
+packages/core/src/:{agent/AGENTS.md=agent runtime, hooks, streaming,workflow/AGENTS.md=workflow steps, suspend/resume, time travel,memory/AGENTS.md=memory contracts, semantic search, working memory,workspace/AGENTS.md=fs, sandbox, search, skills, policy,voltops/AGENTS.md=voltops clients, prompt management, actions,tool/AGENTS.md=tool definition, schema validation, routing,observability/AGENTS.md=otel span names + attribute conventions,mcp/AGENTS.md=MCP bridge (client/server),a2a/AGENTS.md=A2A server registry/protocol}
+packages/:{server-core/AGENTS.md=server handlers, schemas, OpenAPI, WebSocket}
+website/:{AGENTS.md=docs site setup + Docusaurus gotchas,docs/=user-facing framework docs,docs/getting-started/=quickstart,docs/agents/=agent guides,docs/workflows/=workflow guides,docs/integrations/=provider integrations,observability/=otel + VoltOps docs,recipes/=cookbook,blog/=release notes + posts,static/llms.txt=hand-curated 38KB LLM docs index}
+.github/:{pull_request_template.md=canonical PR checklist,workflows/=CI definitions,ISSUE_TEMPLATE/=issue templates}
+</docs-index>
+```
 
-- **JSON.stringify** SHOULD NEVER BE USED, used the `safeStringify` function instead, imported from `@voltagent/internal`
+Memory adapter packages (under `packages/`): `postgres`, `libsql`, `supabase`, `cloudflare-d1`, `voltagent-memory`. Sandboxes: `sandbox-daytona`, `sandbox-e2b`. Exporters: `langfuse-exporter`, `vercel-ai-exporter`. Server runtimes: `server-hono`, `server-elysia`, `serverless-hono`. MCP/A2A: `mcp-server`, `docs-mcp`, `a2a-server`. Read [`contributing/structure.md`](./contributing/structure.md) for the full inventory and naming conventions.

contributing/README.md

@@ -0,0 +1,35 @@
+# Contributing Guide
+
+Start here for repository-level contribution docs and shared reference files.
+
+## Quick Reference
+
+- Read [Contribution policy](../CONTRIBUTING.md) for the public contribution entry point.
+- Use the docs below for repository-specific setup, validation, release, and coding-agent guidance.
+- Use [LLM documentation index](../website/static/llms.txt) when an agent or tool needs a compact docs map.
+
+## Contributor Docs
+
+- [Repository structure](./structure.md)
+- [Development tooling](./tooling.md)
+- [Testing](./testing.md)
+- [Linting and formatting](./linting.md)
+- [Changesets](./changesets.md)
+- [Coding-agent compatibility](./coding-agents.md)
+
+## Repository References
+
+- [Project README](../README.md)
+- [Contribution policy](../CONTRIBUTING.md)
+- [Code of conduct](../CODE_OF_CONDUCT.md)
+- [Security policy](../SECURITY.md)
+- [Changelog](../CHANGELOG.md)
+- [Examples](../examples/README.md)
+- [Website docs app](../website/README.md)
+- [LLM documentation index](../website/static/llms.txt)
+- [Root coding-agent instructions](../AGENTS.md)
+
+## Related Docs
+
+- [Root coding-agent instructions](../AGENTS.md)
+- [Website docs app](../website/README.md)

contributing/changesets.md

@@ -0,0 +1,41 @@
+# Changesets
+
+VoltAgent uses Changesets to version public packages and generate changelog entries.
+
+## Quick Reference
+
+- Run `pnpm changeset` from the repository root.
+- Add a changeset for published package API, runtime behavior, package contents, dependency, or migration changes.
+- Choose the smallest accurate version type: `patch`, `minor`, or `major`.
+
+## Guidelines
+
+Add a changeset when a change affects a published package's public API, runtime behavior, package contents, dependencies, or migration path.
+
+A changeset is usually not needed for tests, internal refactors with no behavior change, examples-only changes, contributor docs, or local tooling that does not affect a published package.
+
+## Version Type
+
+- **patch**: bug fixes, small behavior corrections, dependency updates, or internal changes that affect package output
+- **minor**: backwards-compatible features, new exports, new options, or expanded behavior
+- **major**: breaking API changes, removed exports/options, changed defaults, or required migrations
+
+## Creating One
+
+Run the Changesets CLI from the repository root:
+
+```bash
+pnpm changeset
+```
+
+Select every affected published package and choose the smallest accurate version type. Write the summary for users, not maintainers; explain what changed and any migration needed.
+
+## Config
+
+- Main branch releases use [`.changeset/config.json`](../.changeset/config.json).
+- Prerelease branch releases use [`.changeset/config-next.json`](../.changeset/config-next.json).
+
+## Related Docs
+
+- [Development tooling](./tooling.md)
+- [Root coding-agent instructions](../AGENTS.md)

contributing/coding-agents.md

@@ -0,0 +1,60 @@
+# Coding Agents
+
+VoltAgent supports coding agents through shared repository instructions and ignored local configuration.
+
+## Quick Reference
+
+- Keep `AGENTS.md` as the source of truth for shared coding-agent instructions.
+- Add nested `AGENTS.md` files only for major package areas where local context materially helps.
+- Run `./scripts/sync-agent-instructions.mjs` after adding or moving instruction files.
+
+## Guidelines
+
+`AGENTS.md` is the source of truth for coding-agent instructions. Add shared guidance there, or in nested `AGENTS.md` files for major package areas where local context materially helps.
+
+Some coding agents may require a different instruction filename. Keep those files as symlinks to the nearest `AGENTS.md` file instead of duplicating instruction content.
+
+| Agent/tool                          | Support   | Instruction file         |
+| ----------------------------------- | --------- | ------------------------ |
+| Codex                               | Native    | `AGENTS.md`              |
+| Cursor                              | Native    | `AGENTS.md`              |
+| Other `AGENTS.md`-compatible agents | Native    | `AGENTS.md`              |
+| Claude Code                         | Symlinked | `CLAUDE.md -> AGENTS.md` |
+
+## Useful Links
+
+- [Contributor docs index](./README.md)
+- [Root coding-agent instructions](../AGENTS.md)
+- [LLM documentation index](../website/static/llms.txt)
+- [Website docs app](../website/README.md)
+
+## Local Agent Config
+
+Per-developer agent and IDE config is ignored by git. You can safely create local files for your own setup without committing them:
+
+- `.agents/`
+- `.claude`
+- `.codex/`
+- `.cursor/`
+- `.windsurf/`
+- `.vscode/`
+- `.mcp.json`
+
+Common local MCP config locations include `.cursor/mcp.json`, `.windsurf/mcp.json`, `.vscode/mcp.json`, and root `.mcp.json`. Root `mcp.json` is not ignored; use `.mcp.json` for private root-level MCP config.
+
+Do not commit local credentials, personal MCP server paths, local model settings, or machine-specific tool permissions.
+
+## Syncing Aliases
+
+Run this after adding or moving instruction files:
+
+```bash
+./scripts/sync-agent-instructions.mjs
+```
+
+The sync script creates missing instruction-file aliases for coding agents that do not read `AGENTS.md` directly. It prints the symlinks first and asks for confirmation unless you pass `--yes`.
+
+## Related Docs
+
+- [Contributor docs index](./README.md)
+- [Root coding-agent instructions](../AGENTS.md)