noumen 0.5.0 → 0.8.0

package/README.md

@@ -14,28 +14,37 @@ Any provider. Any sandbox. One package.
 pnpm add noumen
 ```
 
-Then install the provider SDK you need:
+Then install the Vercel AI SDK package for the provider you want:
 
 ```bash
-pnpm add openai           # for OpenAI / OpenRouter / Ollama
-pnpm add @anthropic-ai/sdk  # for Anthropic
-pnpm add @google/genai      # for Gemini
-# Ollama requires no SDK — just install https://ollama.com
+pnpm add @ai-sdk/openai              # OpenAI
+pnpm add @ai-sdk/anthropic           # Anthropic
+pnpm add @ai-sdk/google              # Google Gemini
+pnpm add @openrouter/ai-sdk-provider # OpenRouter
+pnpm add @ai-sdk/amazon-bedrock      # AWS Bedrock
+pnpm add @ai-sdk/google-vertex       # Google Vertex AI
+pnpm add ollama-ai-provider-v2       # Ollama (local)
 ```
 
+noumen wraps any Vercel AI SDK `LanguageModel` via a single `AiSdkProvider` adapter — install only the packages for the providers you actually use.
+
 ## Quick Start
 
 ```typescript
-import { Agent } from "noumen";
+import { LocalAgent } from "noumen/local";
 
-const agent = new Agent({ provider: "anthropic", cwd: "." });
+const agent = LocalAgent({ provider: "anthropic", cwd: "." });
 
 for await (const event of agent.run("Add a health-check endpoint to server.ts")) {
   if (event.type === "text_delta") process.stdout.write(event.text);
 }
 ```
 
-Three lines to a working agent. The string provider auto-detects your `ANTHROPIC_API_KEY` from the environment, and `cwd` defaults to a local sandbox.
+A working agent in three lines. `LocalAgent` is a convenience factory that constructs an [`Agent`](#embedding) wired to a `LocalSandbox` (OS-level sandboxing via `@anthropic-ai/sandbox-runtime`) — use it whenever you want the host's filesystem and shell, isolated. The string provider auto-detects your `ANTHROPIC_API_KEY` from the environment.
+
+Want raw host access with no isolation? Swap `noumen/local` → `noumen/unsandboxed` and `LocalAgent` → `UnsandboxedAgent`. Want a remote sandbox? Use `new Agent({ provider, sandbox })` directly — see [Sandboxes](#sandboxes) for every backend.
+
+> **Why the subpath import?** The root barrel (`import { Agent } from "noumen"`) deliberately never pulls a default sandbox into the module graph — that keeps `noumen` lightweight for apps that bundle with Next.js NFT or serverless-webpack and only use a remote sandbox. Opting into a local sandbox is an explicit import line. See [Sandboxes](#sandboxes).
 
 ### Execute (run to completion)
 
@@ -52,11 +61,14 @@ console.log(`Done — ${result.toolCalls} tool calls`);
 ### Full control
 
 ```typescript
-import { Agent, LocalSandbox } from "noumen";
-import { OpenAIProvider } from "noumen/openai";
+import { Agent, AiSdkProvider } from "noumen";
+import { LocalSandbox } from "noumen/local";
+import { createOpenAI } from "@ai-sdk/openai";
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
 const agent = new Agent({
-  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  provider: new AiSdkProvider({ model: openai.chat("gpt-5") }),
   sandbox: LocalSandbox({ cwd: "/my/project" }),
 });
 
@@ -82,12 +94,16 @@ for await (const event of thread.run("Refactor the auth module")) {
 For zero-config setup, use a preset that configures everything for you:
 
 ```typescript
-import { codingAgent } from "noumen";
-import { OpenAIProvider } from "noumen/openai";
+import { codingAgent, AiSdkProvider } from "noumen";
+import { LocalSandbox } from "noumen/local";
+import { createOpenAI } from "@ai-sdk/openai";
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });
 
 const agent = codingAgent({
-  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
+  provider: new AiSdkProvider({ model: openai.chat("gpt-5") }),
   cwd: "/my/project",
+  sandbox: LocalSandbox({ cwd: "/my/project" }),
 });
 
 await agent.init();
@@ -100,6 +116,8 @@ for await (const event of thread.run("Refactor the auth module")) {
 await agent.close();
 ```
 
+Presets require an explicit `sandbox` for the same bundler-hygiene reason — pick a backend from its subpath (`noumen/local`, `noumen/unsandboxed`, `noumen/docker`, …).
+
 Three presets are available:
 
 | Preset | Mode | Includes |
@@ -249,143 +267,234 @@ npx noumen doctor
 
 ## Providers
 
+noumen wraps any [Vercel AI SDK](https://sdk.vercel.ai) `LanguageModel` via a single `AiSdkProvider` adapter. Install the `@ai-sdk/*` package for the vendor you want, hand its model instance to `AiSdkProvider`, and pass the result to `Agent`. Every provider follows the same three-line pattern:
+
+```typescript
+import { AiSdkProvider } from "noumen";
+import { createOpenAI } from "@ai-sdk/openai";
+
+const provider = new AiSdkProvider({
+  model: createOpenAI({ apiKey: process.env.OPENAI_API_KEY })("gpt-5"),
+});
+```
+
+| Option on `AiSdkProvider` | Description |
+| --- | --- |
+| `model` | Any AI SDK `LanguageModelV2` / `V3` instance. Required. |
+| `defaultModel` | Override the model id reported by `provider.defaultModel`. |
+| `providerFamily` | `"openai" \| "anthropic" \| "google"` — controls how noumen maps thinking / reasoning / cache options. Inferred from the model by default; set explicitly when going through a custom proxy. |
+| `cacheConfig` | `{ enabled: true }` inserts an Anthropic `cache_control` breakpoint and honors `ChatParams.skipCacheWrite`. No-op for non-Anthropic families. |
+
+Per-call options (`thinking`, `reasoningEffort`, `outputFormat`, `skipCacheWrite`, etc.) continue to flow through `ChatParams` / `AgentOptions` exactly like before — the adapter routes them to the right `providerOptions.*` entry for the detected family.
+
 ### OpenAI
 
+```bash
+pnpm add @ai-sdk/openai
+```
+
 ```typescript
-import { OpenAIProvider } from "noumen/openai";
+import { AiSdkProvider } from "noumen";
+import { createOpenAI } from "@ai-sdk/openai";
 
-const provider = new OpenAIProvider({
-  apiKey: "sk-...",
-  model: "gpt-4o",      // default
-  baseURL: "https://...", // optional, for compatible APIs
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: "https://...",  // optional, for Azure / proxies / compatible APIs
 });
+
+// `.chat(id)` pins to chat/completions. Drop it to use the Responses API.
+const provider = new AiSdkProvider({ model: openai.chat("gpt-5") });
 ```
 
 ### Anthropic
 
+```bash
+pnpm add @ai-sdk/anthropic
+```
+
 ```typescript
-import { AnthropicProvider } from "noumen/anthropic";
+import { AiSdkProvider } from "noumen";
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
-const provider = new AnthropicProvider({
-  apiKey: "sk-ant-...",
-  model: "claude-sonnet-4", // default
+const provider = new AiSdkProvider({
+  model: anthropic("claude-opus-4.6"),
+  providerFamily: "anthropic",
+  cacheConfig: { enabled: true }, // prompt caching
 });
 ```
 
 ### Google Gemini
 
+```bash
+pnpm add @ai-sdk/google
+```
+
 ```typescript
-import { GeminiProvider } from "noumen/gemini";
+import { AiSdkProvider } from "noumen";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+
+const google = createGoogleGenerativeAI({ apiKey: process.env.GEMINI_API_KEY });
 
-const provider = new GeminiProvider({
-  apiKey: "...",                   // Google AI Studio API key
-  model: "gemini-2.5-flash",      // default
+const provider = new AiSdkProvider({
+  model: google("gemini-2.5-flash"),
+  providerFamily: "google",
 });
 ```
 
 ### OpenRouter
 
+```bash
+pnpm add @openrouter/ai-sdk-provider
+```
+
 ```typescript
-import { OpenRouterProvider } from "noumen/openrouter";
+import { AiSdkProvider } from "noumen";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+  headers: {
+    "HTTP-Referer": "https://myapp.com",  // optional, for openrouter.ai rankings
+    "X-Title": "My Agent",                 // optional
+  },
+});
 
-const provider = new OpenRouterProvider({
-  apiKey: "sk-or-...",
-  model: "anthropic/claude-sonnet-4",  // default
-  appName: "My Agent",                 // optional, for openrouter.ai rankings
-  appUrl: "https://myapp.com",         // optional
+const provider = new AiSdkProvider({
+  model: openrouter.chat("anthropic/claude-opus-4.6"),
 });
 ```
 
-### AWS Bedrock (Anthropic)
+### AWS Bedrock
 
-Route Anthropic models through AWS Bedrock. Requires `@anthropic-ai/bedrock-sdk`:
+Route Claude (and any other Bedrock-hosted model) through AWS Bedrock.
 
 ```bash
-pnpm add @anthropic-ai/bedrock-sdk
+pnpm add @ai-sdk/amazon-bedrock
 ```
 
 ```typescript
-import { BedrockAnthropicProvider } from "noumen/bedrock";
-
-const provider = new BedrockAnthropicProvider({
-  region: "us-west-2",                                     // default: us-east-1
-  model: "us.anthropic.claude-sonnet-4-v1:0",               // default
-  credentials: {                                            // optional, falls back to default chain
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    sessionToken: process.env.AWS_SESSION_TOKEN,
-  },
-  cacheControl: { enabled: true },                          // optional prompt caching
+import { AiSdkProvider } from "noumen";
+import { createAmazonBedrock } from "@ai-sdk/amazon-bedrock";
+
+const bedrock = createAmazonBedrock({
+  region: process.env.AWS_REGION ?? "us-east-1",
+  // Credentials resolved from the standard AWS credential chain
+  // (env vars, ~/.aws/credentials, IAM roles) unless you pass
+  // explicit accessKeyId / secretAccessKey / sessionToken.
 });
-```
 
-When `credentials` is omitted, the SDK uses the standard AWS credential chain (env vars, `~/.aws/credentials`, IAM roles, etc.).
+const provider = new AiSdkProvider({
+  model: bedrock("us.anthropic.claude-opus-4.6-v1:0"),
+  providerFamily: "anthropic",
+  cacheConfig: { enabled: true },
+});
+```
 
-### Google Vertex AI (Anthropic)
+### Google Vertex AI
 
-Route Anthropic models through Google Cloud Vertex AI. Requires `@anthropic-ai/vertex-sdk` and `google-auth-library`:
+Route Claude or native Gemini through Google Cloud Vertex AI.
 
 ```bash
-pnpm add @anthropic-ai/vertex-sdk google-auth-library
+pnpm add @ai-sdk/google-vertex
 ```
 
 ```typescript
-import { VertexAnthropicProvider } from "noumen/vertex";
+import { AiSdkProvider } from "noumen";
+import { createVertex } from "@ai-sdk/google-vertex";
 
-const provider = new VertexAnthropicProvider({
-  projectId: "my-gcp-project",
-  region: "us-east5",                     // default
-  model: "claude-sonnet-4",               // default
-  cacheControl: { enabled: true },        // optional prompt caching
+const vertex = createVertex({
+  project: process.env.GOOGLE_CLOUD_PROJECT,
+  location: "us-east5",
+  // googleAuthOptions: { keyFile: "/path/to/service-account.json" },
 });
-```
-
-When `googleAuth` is omitted, the provider creates a `GoogleAuth` instance using application default credentials. You can pass your own `googleAuth` instance for custom authentication:
 
-```typescript
-import { GoogleAuth } from "google-auth-library";
+// Claude on Vertex
+const claudeProvider = new AiSdkProvider({
+  model: vertex.anthropic("claude-opus-4.6"),
+  providerFamily: "anthropic",
+  cacheConfig: { enabled: true },
+});
 
-const provider = new VertexAnthropicProvider({
-  projectId: "my-project",
-  googleAuth: new GoogleAuth({ keyFile: "/path/to/service-account.json" }),
+// Native Gemini on Vertex
+const geminiProvider = new AiSdkProvider({
+  model: vertex("gemini-2.5-pro"),
+  providerFamily: "google",
 });
 ```
 
 ### Ollama (Local)
 
-Run models locally with [Ollama](https://ollama.com). No API key needed — just install Ollama and pull a model:
+Run models locally with [Ollama](https://ollama.com). No API key needed — just install Ollama, pull a model, and add the Vercel AI SDK provider:
 
 ```bash
 ollama pull qwen2.5-coder:32b
 ollama serve
+pnpm add ollama-ai-provider-v2
 ```
 
 ```typescript
-import { OllamaProvider } from "noumen/ollama";
+import { AiSdkProvider } from "noumen";
+import { createOllama } from "ollama-ai-provider-v2";
 
-const provider = new OllamaProvider({
-  model: "qwen2.5-coder:32b",   // default
-  baseURL: "http://localhost:11434/v1",  // default
+const ollama = createOllama({
+  // baseURL: "http://192.168.1.10:11434/api", // override for remote Ollama
 });
+
+const provider = new AiSdkProvider({ model: ollama("qwen2.5-coder:32b") });
 ```
 
 The CLI auto-detects a running Ollama server when no cloud API keys are set, so you can simply run `noumen` with Ollama serving in the background.
 
+### String shorthand
+
+For quick setup and the CLI, pass a provider name string — noumen dynamically imports the right `@ai-sdk/*` package and wraps it in `AiSdkProvider` for you:
+
+```typescript
+const agent = LocalAgent({ provider: "anthropic", cwd: "." });
+// Equivalent to manually constructing AiSdkProvider with @ai-sdk/anthropic.
+```
+
+Supported names: `openai`, `anthropic`, `gemini`, `openrouter`, `bedrock`, `vertex`, `ollama`.
+
+### Custom / metered proxies
+
+Any AI SDK factory accepts a `baseURL` and custom headers, so routing through your own metered gateway is a one-liner:
+
+```typescript
+const gateway = createOpenAI({
+  baseURL: "https://my-proxy.example.com/openai",
+  apiKey: userJwt, // forwarded as Authorization: Bearer <jwt>
+});
+const provider = new AiSdkProvider({ model: gateway.chat("gpt-5") });
+```
+
 ## Sandboxes
 
 A `Sandbox` bundles a `VirtualFs` (filesystem) and `VirtualComputer` (shell execution) into one object. Every file read/write and shell command the agent executes goes through these interfaces — swap the sandbox to control what the agent can access.
 
-Local factories live on the root barrel; each remote backend ships on its own subpath so its optional peer dep only enters the module graph when you opt in:
+`sandbox` is **required** on `Agent` and every preset. The root barrel (`import { Agent } from "noumen"`) never imports a sandbox factory, so callers pick a backend explicitly from its subpath. That keeps `node:child_process` and `node:fs/promises` out of the static module graph for consumers that only use a remote sandbox — critical for bundlers like Next.js NFT and serverless-webpack that trace dependencies.
 
 | Factory | Import | Peer dep |
 | --- | --- | --- |
-| `LocalSandbox`, `UnsandboxedLocal` | `noumen` | `@anthropic-ai/sandbox-runtime` (bundled) |
+| `LocalSandbox` | `noumen/local` | `@anthropic-ai/sandbox-runtime` (bundled) |
+| `UnsandboxedLocal` | `noumen/unsandboxed` | — |
 | `SpritesSandbox` | `noumen/sprites` | — |
 | `DockerSandbox` | `noumen/docker` | `dockerode` |
 | `E2BSandbox` | `noumen/e2b` | `e2b` |
 | `FreestyleSandbox` | `noumen/freestyle` | `freestyle-sandboxes` |
 | `SshSandbox` | `noumen/ssh` | `ssh2` |
 
+For the two local backends, shortcut factories bundle `Agent` + sandbox together:
+
+| Shortcut | Import | Equivalent to |
+| --- | --- | --- |
+| `LocalAgent` | `noumen/local` | `new Agent({ ..., sandbox: LocalSandbox({ cwd }) })` |
+| `UnsandboxedAgent` | `noumen/unsandboxed` | `new Agent({ ..., sandbox: UnsandboxedLocal({ cwd }) })` |
+
+Remote sandboxes stay on the `new Agent({ provider, sandbox })` path — there's no `DockerAgent` shortcut because remote backends carry config (tokens, templates, connection state) that's clearer at the call site.
+
 ### Local — OS-level sandboxing
 
 Backed by `@anthropic-ai/sandbox-runtime`. Uses macOS Seatbelt or Linux bubblewrap to restrict filesystem and network access at the OS level — no containers needed:
@@ -395,20 +504,34 @@ pnpm add @anthropic-ai/sandbox-runtime
 ```
 
 ```typescript
-import { LocalSandbox } from "noumen";
+import { LocalAgent } from "noumen/local";
 
-const sandbox = LocalSandbox({ cwd: "/my/project" });
+// Shortcut — Agent + LocalSandbox in one call:
+const agent = LocalAgent({ provider: "anthropic", cwd: "/my/project" });
 
-// Customize restrictions:
-const restricted = LocalSandbox({
+// Customize sandbox restrictions via `localSandbox`:
+const restricted = LocalAgent({
+  provider: "anthropic",
   cwd: "/my/project",
-  sandbox: {
-    filesystem: { denyRead: ["/etc/shadow"] },
-    network: { allowedDomains: ["api.openai.com"] },
+  localSandbox: {
+    sandbox: {
+      filesystem: { denyRead: ["/etc/shadow"] },
+      network: { allowedDomains: ["api.openai.com"] },
+    },
   },
 });
 ```
 
+Or drop down to the sandbox factory directly when you need to share the sandbox across multiple agents / presets:
+
+```typescript
+import { Agent } from "noumen";
+import { LocalSandbox } from "noumen/local";
+
+const sandbox = LocalSandbox({ cwd: "/my/project" });
+const agent = new Agent({ provider: "anthropic", sandbox });
+```
+
 Defaults: writes allowed only in `cwd`, reads allowed everywhere, network unrestricted.
 
 ### UnsandboxedLocal — no isolation
@@ -416,9 +539,17 @@ Defaults: writes allowed only in `cwd`, reads allowed everywhere, network unrest
 Backed by `fs/promises` and `child_process` with no OS-level restrictions. Use for development or trusted environments:
 
 ```typescript
-import { UnsandboxedLocal } from "noumen";
+import { UnsandboxedAgent } from "noumen/unsandboxed";
+
+// Shortcut — Agent + UnsandboxedLocal in one call:
+const agent = UnsandboxedAgent({ provider: "anthropic", cwd: "/my/project" });
+
+// Or compose manually:
+import { Agent } from "noumen";
+import { UnsandboxedLocal } from "noumen/unsandboxed";
 
 const sandbox = UnsandboxedLocal({ cwd: "/my/project" });
+const plain = new Agent({ provider: "anthropic", sandbox });
 ```
 
 ### sprites.dev — full sandbox
@@ -636,8 +767,10 @@ The interfaces are intentionally minimal (one method for shell, eight for filesy
 
 ## Options
 
+Snippets below use `LocalAgent` (`import { LocalAgent } from "noumen/local"`) for brevity. Every option is also valid on `new Agent({ ..., sandbox })` and on the presets (`codingAgent`, `planningAgent`, `reviewAgent`) — the shape is identical, only the sandbox plumbing differs.
+
 ```typescript
-const agent = new Agent({
+const agent = LocalAgent({
   provider: "anthropic",
   cwd: "/my/project",
   options: {
@@ -648,9 +781,15 @@ const agent = new Agent({
     autoCompactThreshold: 100_000,  // token threshold for auto-compact
     systemPrompt: "...",            // override the built-in system prompt
     skills: [{ name: "...", content: "..." }],
-    skillsPaths: [".claude/skills"],   // paths to SKILL.md files on the sandbox filesystem
+    skillsPaths: [".claude/skills"],   // extra paths to SKILL.md files (adds to auto-discovered .noumen/skills + .claude/skills)
     projectContext: true,              // load NOUMEN.md / CLAUDE.md from project
 
+    // Dot-directory layout (controls where .noumen / .claude state lives).
+    // Default: [".noumen", ".claude"]. First name wins for writes; all names
+    // are scanned for reads, and every name is protected by the dangerous-path
+    // permission check.
+    dotDirs: { names: [".noumen", ".claude"] },
+
     // Extended thinking / reasoning (see below)
     thinking: { type: "enabled", budgetTokens: 10000 },
 
@@ -770,7 +909,7 @@ Enable model reasoning/thinking for supported providers. Each provider maps the
 - **Gemini**: Sets `thinkingConfig.thinkingBudget`
 
 ```typescript
-const agent = new Agent({
+const agent = LocalAgent({
   provider: "anthropic",
   cwd: ".",
   options: {
@@ -795,7 +934,7 @@ Disable explicitly with `{ type: "disabled" }`, or omit the option entirely for
 Automatic retries with exponential backoff, Retry-After header support, context overflow recovery, and model fallback. Handles 429 (rate limit), 529 (overloaded), 500/502/503 (server errors), and connection failures.
 
 ```typescript
-const agent = new Agent({
+const agent = LocalAgent({
   provider: "anthropic",
   cwd: ".",
   options: {
@@ -804,7 +943,7 @@ const agent = new Agent({
 });
 
 // Or customize:
-const agent2 = new Agent({
+const agent2 = LocalAgent({
   provider: "anthropic",
   cwd: ".",
   options: {
@@ -830,7 +969,7 @@ On context overflow (input + max_tokens > context limit), the engine automatical
 Track token usage and estimate USD costs across all model calls. Includes built-in pricing for Claude, GPT-4o, Gemini, and o-series models.
 
 ```typescript
-const agent = new Agent({
+const agent = LocalAgent({
   provider: "anthropic",
   cwd: ".",
   options: {
@@ -856,7 +995,7 @@ console.log(`Output tokens: ${summary.totalOutputTokens}`);
 Supply custom pricing for unlisted models:
 
 ```typescript
-const agent = new Agent({
+const agent = LocalAgent({
   provider: "anthropic",
   cwd: ".",
   options: {
@@ -875,17 +1014,17 @@ const agent = new Agent({
 
 ## Skills
 
-Skills are markdown instructions injected into the system prompt. Provide them inline or load from `SKILL.md` files on the virtual filesystem:
+Skills are markdown instructions injected into the system prompt. They are auto-discovered from `<cwd>/.noumen/skills/` and `<cwd>/.claude/skills/` (and the same paths under `$HOME`), and can also be provided inline or loaded from explicit paths:
 
 ```typescript
-const agent = new Agent({
+const agent = LocalAgent({
   provider: "anthropic",
   cwd: ".",
   options: {
     skills: [
       { name: "Testing", content: "Always write vitest tests for new code." },
     ],
-    skillsPaths: [".claude/skills", "~/.config/skills"],
+    skillsPaths: ["~/.config/skills"], // additive to auto-discovery
   },
 });
 
@@ -893,6 +1032,8 @@ const agent = new Agent({
 await agent.init();
 ```
 
+Auto-discovery follows the configured `dotDirs` list (default `[".noumen", ".claude"]`). On name collisions, project skills win over home skills, and the **first** dot-dir in the list wins within a scope — so `.noumen/skills/foo` overrides `.claude/skills/foo`. Only `<dot-dir>/skills/<name>/SKILL.md` is discovered; loose `SKILL.md` files at the dot-dir root are ignored.
+
 ## Project Context (NOUMEN.md / CLAUDE.md)
 
 Drop a `NOUMEN.md` or `CLAUDE.md` in your project root to give the agent persistent instructions:
@@ -907,6 +1048,8 @@ Enable it with `projectContext: true` in your `Agent` options. The loader discov
 
 This is fully compatible with `CLAUDE.md`. If your project already has one, noumen picks it up automatically. Both `NOUMEN.md` and `CLAUDE.md` can coexist in the same directory. The format supports `@path` includes, conditional rules via `paths:` frontmatter in `.noumen/rules/` directories, and hierarchical overriding.
 
+The set of dot-directory names is configurable via `dotDirs` (default `[".noumen", ".claude"]`). The same list drives `NOUMEN.md`/`CLAUDE.md` discovery, auto-discovered skills (under `<dot-dir>/skills/`), CLI config lookup (`<dot-dir>/config.json`), and agent-managed state (sessions, checkpoints, worktrees, OAuth tokens). Writes always go to the **first** name in the list; reads fall back through the rest in order.
+
 See **[noumen.dev/docs/context](https://noumen.dev/docs/context)** for full configuration options.
 
 ## Sessions
@@ -924,7 +1067,7 @@ const sessions = await agent.listSessions();
 18 hook events across six categories — intercept tool calls, session lifecycle, permissions, file writes, model switches, compaction, retry, memory, and errors:
 
 ```typescript
-const agent = new Agent({
+const agent = LocalAgent({
   provider: "anthropic", cwd: ".",
   options: {
     hooks: [
@@ -1007,7 +1150,8 @@ await swarm.waitForAll();
 Persist knowledge across sessions:
 
 ```typescript
-import { FileMemoryProvider, LocalFs } from "noumen";
+import { FileMemoryProvider } from "noumen";
+import { LocalFs } from "noumen/local";
 
 options: {
   memory: {

package/dist/a2a/index.d.ts

@@ -1,12 +1,10 @@
-import { A as Agent } from '../agent-C3eDRsxs.js';
+import { a as Agent } from '../agent-D0gl-qYi.js';
 import { A as AgentSkill, a as AgentCard, T as TaskSendParams, b as Task, c as TaskStreamEvent } from '../types-NIyVwQ4h.js';
 export { d as A2A_METHODS, e as Artifact, D as DataPart, F as FilePart, M as Message, P as Part, f as TaskState, g as TaskStatus, h as TextPart } from '../types-NIyVwQ4h.js';
-import '../types-LrU4LRmX.js';
-import '../sandbox-9qeMTNrD.js';
-import '../computer-BPdxSo6X.js';
-import '../types-BA87bHPV.js';
-import '../types-CD0rUKKT.js';
-import '../cache-DsRqxx6v.js';
+import '../types-DLZNyF5t.js';
+import '../sandbox-DAqQo0Tj.js';
+import '../computer-DzMR92tK.js';
+import '../types-BX4ALqoN.js';
 import '../types-2kTLUCnD.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 import '@modelcontextprotocol/sdk/client/auth.js';

package/dist/a2a/index.js

@@ -1,6 +1,3 @@
-import {
-  generateUUID
-} from "../chunk-3HEYCV26.js";
 import {
   INTERNAL_ERROR,
   INVALID_PARAMS,
@@ -12,8 +9,10 @@ import {
   isRequest,
   parseMessage
 } from "../chunk-AMYIJSAZ.js";
+import {
+  generateUUID
+} from "../chunk-3HEYCV26.js";
 import "../chunk-JACGEMTF.js";
-import "../chunk-DGUM43GV.js";
 
 // src/a2a/server.ts
 import { createServer } from "http";