docs: rewrite README with first-principles structure

- Lead with what it is and what problem it solves
- Install for all three languages upfront
- Quick Start shows working code immediately
- Tools table replaces bullet list of features
- Safety/permissions/memory/multi-provider each get their own minimal section
- Architecture diagram explains the 4-layer structure
- Remove API reference dump (belongs in docs site)

Author: RoyLin

README.md

@@ -1,194 +1,225 @@
 # A3S Code
 
-**Rust framework for building agentic AI agents** — Embed agents that read, write, and execute code into any application. Native Node.js and Python bindings included.
+**Embed AI coding agents into any application.** A3S Code is a Rust library with native Python and Node.js bindings. Give an LLM a workspace, a set of tools, and a system prompt — it reads files, runs commands, searches code, and acts on results.
 
-## Features
+[![crates.io](https://img.shields.io/crates/v/a3s-code-core)](https://crates.io/crates/a3s-code-core)
+[![PyPI](https://img.shields.io/pypi/v/a3s-code)](https://pypi.org/project/a3s-code/)
+[![npm](https://img.shields.io/npm/v/@a3s-lab/code)](https://www.npmjs.com/package/@a3s-lab/code)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-- **16 Built-in Tools** — File operations (read, write, edit, patch), search (grep, glob, ls), shell (bash), web (web_fetch, web_search), git (git_worktree), delegation (task, parallel_task, run_team, batch, Skill)
-- **Plugin Tools** — Optional tools loaded on demand: `agentic_search` (multi-phase semantic search), `agentic_parse` (LLM-enhanced document parsing). Each plugin automatically registers its companion skill.
-- **8 Built-in Skills** — Code assistance (agentic-search, code-search, code-review, explain-code, find-bugs) + tool documentation (builtin-tools, delegate-task, find-skills)
-- **Plugin System** — Unified `Plugin` trait for mounting optional tool+skill bundles. Plugins register tools into `ToolRegistry` and companion skills into `SkillRegistry` on load.
-- **20 Extension Points** — Trait-based architecture: replace any policy with your own implementation
-- **Safe by Default** — Permission system, HITL confirmation, skill-based tool restrictions, error recovery (parse retries, tool timeout, circuit breaker)
-- **Multi-Provider** — Anthropic, OpenAI, DeepSeek, Kimi, Together AI, Groq, Ollama, vLLM, any OpenAI-compatible API
-- **MCP Integration** — Connect external tool servers via Model Context Protocol
-- **Scalable** — Lane-based priority queue with multi-machine task distribution
+---
 
-## Installation
+## Install
 
 ```bash
+# Python
 pip install a3s-code
+
+# Node.js
+npm install @a3s-lab/code
+
+# Rust
+cargo add a3s-code-core
 ```
 
+---
+
 ## Quick Start
 
+**1. Create an agent config** (`agent.hcl`):
+
+```hcl
+default_model = "anthropic/claude-sonnet-4-20250514"
+
+providers {
+  name    = "anthropic"
+  api_key = env("ANTHROPIC_API_KEY")
+}
+```
+
+**2. Run an agent session:**
+
 ```python
 from a3s_code import Agent
 
 agent = Agent.create("agent.hcl")
 session = agent.session("/my-project")
 
-result = session.send("What files handle authentication?")
+result = session.send("Find all places where we handle authentication errors")
 print(result.text)
 ```
 
-## Plugin Tools
-
-`agentic_search` and `agentic_parse` are opt-in plugins — not loaded by default. Mount them explicitly per session:
-
 ```typescript
-// Node.js
-import { Agent, AgenticSearch, AgenticParse } from '@a3s-lab/code';
+import { Agent } from '@a3s-lab/code';
 
 const agent = await Agent.create('agent.hcl');
-const session = agent.session('.', {
-  plugins: [new AgenticSearch(), new AgenticParse()],
-});
+const session = agent.session('/my-project');
+
+const result = await session.send('Find all places where we handle authentication errors');
+console.log(result.text);
+```
+
+```rust
+use a3s_code_core::Agent;
+
+let agent = Agent::from_file("agent.hcl").await?;
+let session = agent.session("/my-project", Default::default()).await?;
+let result = session.send("Find all places where we handle authentication errors").await?;
+println!("{}", result.text);
 ```
 
+---
+
+## What the LLM Can Do
+
+**16 built-in tools** — always available, no configuration:
+
+| Category | Tools |
+|----------|-------|
+| Files | `read`, `write`, `edit`, `patch` |
+| Search | `grep`, `glob`, `ls` |
+| Shell | `bash` |
+| Web | `web_fetch`, `web_search` |
+| Git | `git_worktree` |
+| Delegation | `task`, `parallel_task`, `run_team`, `batch`, `Skill` |
+
+**Plugin tools** — opt-in, loaded per session:
+
+| Plugin | Tool | What it does |
+|--------|------|--------------|
+| `AgenticSearch` | `agentic_search` | Natural-language code search with IDF-weighted relevance ranking |
+| `AgenticParse` | `agentic_parse` | LLM-enhanced parsing for PDF, Word, CSV, code, and more |
+
 ```python
-# Python
 from a3s_code import Agent, SessionOptions, AgenticSearch, AgenticParse
 
-agent = Agent.create("agent.hcl")
 opts = SessionOptions()
 opts.plugins = [AgenticSearch(), AgenticParse()]
 session = agent.session(".", opts)
 ```
 
-When a plugin is loaded:
-1. Its **tool** is registered into the session's `ToolRegistry` (the LLM can call it)
-2. Its **companion skill** is registered into `SkillRegistry` (appears in the system prompt automatically)
+---
 
-### Available Plugins
+## Safety and Control
 
-| Plugin | Tool | Companion Skill |
-|--------|------|-----------------|
-| `AgenticSearch` | `agentic_search` — multi-phase semantic code search with IDF-weighted relevance | `agentic-search` — guides the LLM on when/how to use the tool |
-| `AgenticParse` | `agentic_parse` — LLM-enhanced document parsing (PDF, Word, CSV, code, etc.) | `agentic-parse` — guides the LLM on parse strategies and extraction |
+Agents run with **explicit permissions**. Nothing executes by default without a policy allowing it:
 
-### Document Parser Support
+```python
+from a3s_code import SessionOptions, PermissionPolicy, PermissionRule
 
-For binary formats (PDF, Excel, Word), pass a `DocumentParserRegistry` through the plugin option:
+opts = SessionOptions()
+opts.permission_policy = PermissionPolicy(
+    allow=[PermissionRule("read(*)"), PermissionRule("grep(*)")],
+    deny=[PermissionRule("bash(*)")],
+    default_decision="deny",
+)
+session = agent.session(".", opts)
+```
 
-```typescript
-import { AgenticParse, DocumentParserRegistry } from '@a3s-lab/code';
+Other safety features:
+- **Human-in-the-loop confirmation** — prompt before any tool call
+- **Skill-based tool restrictions** — `allowed-tools` in skill frontmatter limits what the LLM can call
+- **AHP integration** — plug in an external harness to block or sanitize tool calls at runtime
+- **Auto-compact** — rolls up context before hitting token limits, keeping sessions running
 
-const session = agent.session('.', {
-  plugins: [new AgenticParse({ documentParserRegistry: new DocumentParserRegistry() })],
-});
-```
+---
 
-## Slash Commands
+## Persistence and Memory
 
-Every session includes built-in slash commands dispatched before the LLM:
+Sessions can be saved and resumed. Memory persists across sessions:
 
 ```python
-# List all available commands
-commands = session.list_commands()
-for cmd in commands:
-    print(f"/{cmd['name']:15s} {cmd['description']}")
-
-# Built-in commands
-result = session.send("/help")       # List all commands
-result = session.send("/model")      # Show current model
-result = session.send("/cost")       # Token usage and cost
-result = session.send("/history")    # Conversation stats
-result = session.send("/cron-list")  # List scheduled tasks
+from a3s_code import SessionOptions, FileSessionStore, FileMemoryStore
+
+opts = SessionOptions()
+opts.session_store = FileSessionStore('./sessions')
+opts.memory_store = FileMemoryStore('./memory')
+opts.session_id = 'my-session'
+opts.auto_save = True
+
+session = agent.session(".", opts)
+resumed = agent.resume_session('my-session', opts)
 ```
 
-### Custom Commands
+---
 
-```python
-def my_handler(args: str, ctx: dict) -> str:
-    return f"Model: {ctx['model']}, History: {ctx['history_len']} msgs, args: {args!r}"
+## Multi-Provider
 
-session.register_command("status", "Show session info", my_handler)
-result = session.send("/status hello")
-```
+One config, any LLM:
 
-## Scheduled Tasks
+```hcl
+default_model = "anthropic/claude-sonnet-4-20250514"
+
+providers { name = "anthropic";  api_key = env("ANTHROPIC_API_KEY") }
+providers { name = "openai";     api_key = env("OPENAI_API_KEY") }
+providers { name = "deepseek";   api_key = env("DEEPSEEK_API_KEY") }
+providers { name = "kimi";       api_key = env("MOONSHOT_API_KEY") }
+providers { name = "together";   api_key = env("TOGETHER_API_KEY") }
+providers { name = "groq";       api_key = env("GROQ_API_KEY") }
+```
 
-Schedule recurring prompts that fire after each `send()` call:
+Switch model per session:
 
 ```python
-# Via /loop slash command
-r = session.send("/loop 30s check deployment status")
-print(r.text)  # Scheduled [a1b2c3d4]: "check deployment status" — fires every 30s
+session = agent.session(".", model="openai/gpt-4o")
+```
 
-# Programmatic API
-task_id = session.schedule_task("summarize recent commits", 300)  # every 5 min
+---
 
-# List active tasks
-for t in session.list_scheduled_tasks():
-    print(f"[{t['id']}] every {t['interval_secs']}s — \"{t['prompt']}\"")
+## Skills
 
-# Cancel
-session.cancel_scheduled_task(task_id)
-session.send(f"/cron-cancel {task_id}")
-```
+Skills are markdown files that shape LLM behavior — injected into the system prompt automatically:
 
-**Interval syntax:** `30s`, `5m`, `2h`, `1d`. Leading or trailing with `every` clause.
+```markdown
+---
+name: safe-reviewer
+description: Review code without modifying files
+allowed-tools: "read(*), grep(*), glob(*)"
+---
 
-## Full API
+Review the code in the workspace. You may read and search files,
+but you must not write, edit, or execute anything.
+```
 
 ```python
-from a3s_code import Agent, SessionOptions, DefaultSecurityProvider, FileMemoryStore, FileSessionStore
-from a3s_code import AgenticSearch, AgenticParse
+opts = SessionOptions()
+opts.skill_dirs = ["./skills"]
+session = agent.session(".", opts)
+```
 
-agent = Agent.create("agent.hcl")
-session = agent.session("/my-project",
-    model="openai/gpt-4o",
-    builtin_skills=True,
-    planning=True,
-)
+Built-in skills (enabled via `builtin_skills=True`): `agentic-search`, `code-search`, `code-review`, `explain-code`, `find-bugs`, `builtin-tools`, `delegate-task`, `find-skills`.
 
-# Plugin tools (opt-in)
-opts = SessionOptions()
-opts.plugins = [AgenticSearch(), AgenticParse()]
-session2 = agent.session(".", opts)
-
-# Send / Stream
-result = session.send("Explain the auth module")
-for event in session.stream("Refactor auth"):
-    if event.event_type == "text_delta":
-        print(event.text, end="", flush=True)
-
-# Direct tools (bypass LLM)
-session.read_file("src/main.py")
-session.bash("pytest")
-session.glob("**/*.py")
-session.grep("TODO")
-
-# Slash commands & scheduling
-session.list_commands()
-session.register_command("ping", "Pong!", lambda args, ctx: "pong")
-task_id = session.schedule_task("daily report", 86400)
-session.list_scheduled_tasks()
-session.cancel_scheduled_task(task_id)
-
-# Memory
-session.remember_success("task", ["tool"], "result")
-session.recall_similar("auth", 5)
-
-# Hooks
-session.register_hook("audit", "pre_tool_use", handler_fn)
-
-# MCP
-session.add_mcp_server("github", command="npx", args=["-y", "@modelcontextprotocol/server-github"])
-session.mcp_status()
-session.tool_names()
-session.remove_mcp_server("github")
-
-# Persistence
-opts = SessionOptions()
-opts.session_store = FileSessionStore('./sessions')
-opts.session_id = 'my-session'
-opts.auto_save = True
-session2 = agent.session(".", opts)
-resumed = agent.resume_session('my-session', opts)
+---
+
+## Architecture
+
+```
+Agent (config + provider registry)
+  └── Session (workspace + tools + LLM)
+        └── AgentLoop (turn-based execution)
+              ├── LlmClient      → sends messages, receives tool calls
+              ├── ToolExecutor   → runs tools, enforces permissions
+              ├── SkillRegistry  → injects skills into system prompt
+              └── PluginManager  → loads opt-in tool+skill bundles
 ```
 
+20 trait-based extension points: swap any policy, provider, store, or hook without touching core.
+
+---
+
+## Documentation
+
+Full reference, examples, and guides: **[a3s.dev/docs/code](https://a3s.dev/docs/code)**
+
+- [Sessions & Options](https://a3s.dev/docs/code/sessions)
+- [Tools](https://a3s.dev/docs/code/tools)
+- [Skills](https://a3s.dev/docs/code/skills)
+- [Plugin System](https://a3s.dev/docs/code/plugins)
+- [Security](https://a3s.dev/docs/code/security)
+- [Examples](https://a3s.dev/docs/code/examples)
+
+---
+
 ## License
 
 MIT