feat(docs): document Dual-Agent Driver/Guardian architecture, new standard tools, streaming/vision support, progress events, and updated API/export docs

readme.hints.md

@@ -1,15 +1,39 @@
 # Project Readme Hints
 
 ## Overview
-`@push.rocks/smartagent` is an agentic framework built on top of `@push.rocks/smartai`. It provides autonomous AI agent capabilities including tool use, multi-step reasoning, and conversation memory.
+`@push.rocks/smartagent` is a dual-agent agentic framework built on top of `@push.rocks/smartai`. It implements a Driver/Guardian architecture where the Driver proposes tool calls and the Guardian evaluates them against security policies.
 
 ## Architecture
-- **SmartAgent**: Main class that wraps SmartAi and adds agentic behaviors
-- **plugins.ts**: Imports and re-exports smartai
-- **index.ts**: Main entry point, exports SmartAgent class and relevant types
+- **DualAgentOrchestrator**: Main entry point, coordinates Driver and Guardian agents
+- **DriverAgent**: Reasons about tasks, plans steps, proposes tool calls
+- **GuardianAgent**: Evaluates tool calls against configured policies
+- **BaseToolWrapper**: Base class for creating custom tools
+- **plugins.ts**: Imports and re-exports smartai and other dependencies
+
+## Standard Tools
+1. **FilesystemTool** - File operations with scoping and exclusion patterns
+2. **HttpTool** - HTTP requests
+3. **ShellTool** - Secure shell commands (no injection possible)
+4. **BrowserTool** - Web page interaction via Puppeteer
+5. **DenoTool** - Sandboxed TypeScript/JavaScript execution
+6. **JsonValidatorTool** - JSON validation and formatting
+
+## Key Features
+- Token streaming support (`onToken` callback)
+- Vision support (pass images as base64)
+- Progress events (`onProgress` callback)
+- Scoped filesystem with exclusion patterns
+- Result truncation with configurable limits
+- History windowing to manage token usage
 
 ## Key Dependencies
-- `@push.rocks/smartai`: Provides the underlying multi-modal AI provider interface
+- `@push.rocks/smartai`: Multi-provider AI interface
+- `@push.rocks/smartfs`: Filesystem operations
+- `@push.rocks/smartshell`: Shell command execution
+- `@push.rocks/smartbrowser`: Browser automation
+- `@push.rocks/smartdeno`: Deno code execution
+- `@push.rocks/smartrequest`: HTTP requests
+- `minimatch`: Glob pattern matching for exclusions
 
 ## Test Structure
 - Tests use `@git.zone/tstest/tapbundle`