@j-o-r/hello-dave 0.0.5 → 0.0.7

package/README.md

@@ -1,601 +1,240 @@
-# Updated README.md: v0.0.5 Released; createAgent Bin & Spawn Enhancements
+# hello-dave
 
-# @j-o-r/hello-dave
-
-[![npm version](https://badge.fury.io/js/%40j-o-r%2Fhello-dave.svg)](https://www.npmjs.com/package/%40j-o-r%2Fhello-dave)
-[![Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Node.js >=20](https://img.shields.io/badge/Node.js-%3E=20-green.svg)](https://nodejs.org/)
+[![Version: v0.0.8](https://img.shields.io/badge/Version-v0.0.8-green.svg)](https://codeberg.org/duin/hello-dave)
+[![PM2 Compatible](https://img.shields.io/badge/PM2-Compatible-orange.svg)](https://pm2.keymetrics.io/)
 
 ## Table of Contents
 
 - [Description](#description)
 - [Features](#features)
+- [Folder Structure](#folder-structure)
 - [Installation](#installation)
-- [Quick Start](#quick-start)
 - [Usage](#usage)
-- [Startup Modes](#startup-modes)
-- [Examples](#examples)
+- [Usage Examples](#usage-examples)
 - [Development](#development)
-- [Changelog](#changelog)
 - [Contributing](#contributing)
 - [License](#license)
-- [TODO Alignment](#todo-alignment)
 
 ## Description
 
-**@j-o-r/hello-dave** is a lightweight, ESM-only Node.js framework for building intelligent AI agents powered by large language models (LLMs) such as xAI Grok, Anthropic Claude, or OpenAI GPT. It simplifies the creation of custom agents with features like the central `AgentManager` class, WebSocket-based client/server support for networked agents, seamless tool integration (e.g., bash execution, web search), customizable system prompts, and robust session management supporting large context windows (up to millions of tokens).
-
-The framework emphasizes ease of use, allowing developers and non-experts alike to rapidly prototype and deploy specialized agents. Core integrations include unified xAI Grok API access, WebSocket (WS) networking with secret-based authentication, and direct CLI/cron messaging (no heartbeat/ping mechanism required). Example scripts like `readmeDave`, `todoDave`, and others have been reorganized into the `examples/` folder for clarity.
+**hello-dave** is an ESM (ECMAScript Modules) toolkit for building AI agents with unified access to endpoints from Grok (xAI), OpenAI, and Anthropic. It provides CLI tools for interacting with agents locally or via WebSocket servers, along with pre-built agent scripts for various tasks like code generation, documentation, testing, and more.
 
-Whether youre building a code reviewer, a research assistant, or a creative collaborator, `@j-o-r/hello-dave` abstracts away API complexities, providing a unified interface across providers. Its alpha-stage but production-ready for personal projects, with persistence for sessions and logs in NDJSON format.
+The project emphasizes modular agent management, tool integration (e.g., web search, file operations), and session handling with memory and caching. With v0.0.8, enhanced portability allows spawning agents in isolated environments like `/tmp` while maintaining tool functionality relative to the current working directory (CWD).
 
 ## Features
 
-- **Unified LLM Access**: Seamless integration with xAI Grok API, Anthropic Claude, and OpenAI GPT via a single API.
-- **AgentManager Class**: Core orchestrator for prompts, tools, sessions, and interactions (CLI, direct calls, WebSocket).
-- **Tool Integration**: Built-in tools for bash scripting, web search, JavaScript execution, and more; easily extensible.
-- **WebSocket Networking with Secrets**: Agents can act as servers or clients with optional secret authentication, enabling secure distributed agent networks across machines.
-- **Direct CLI/Cron Messaging**: Simplified interactions without needing heartbeat mechanisms—ideal for scheduled tasks.
-- **Customizable Prompts**: Tailor agent behavior with system prompts for specialized tasks (e.g., music production, code analysis).
-- **Session Management**: Persistent conversations with large context windows; automatic truncation and history search.
-- **CLI Utilities**: Core tool at `bin/dave.js` for cache management, WS connections, interactive queries, spawning agents, and CodeServer launches; plus agent generator via `createAgent`.
-- **Lightweight & TypeScript-Friendly**: ESM-only, no heavy deps; full types included.
-- **Memory Tools**: Generic tools `memory_recall` and `memory_write` for persisting and recalling tasks, errors, and preferences in `.cache/memory.ndjson`, optimizing loops and long-running agent sessions (available in `toolsetMode: auto`).
+- **Unified API Access**: Seamless integration with xAI (Grok), OpenAI, and Anthropic models.
+- **CLI Tools**: `dave` for querying agents, `agentDave` for spawning servers, `codeDave` for code servers.
+- **Agent Scripts**: Specialized agents for code, docs, npm, todo, readme, memory, and more.
+- **WebSocket Support**: Connect to remote agent servers for interactive or one-shot interactions.
+- **Toolsets**: Built-in tools for search, file I/O, email, and custom toolcalls.
+- **Session Management**: Cache history, search sessions, reset, and inspect logs.
+- **ESM-First**: Modern Node.js modules with TypeScript definitions.
+- **Portable Agent Spawning**: `spawn_agent.js` enables creating and deploying agents anywhere (project dirs or fresh `/tmp`). Supports auto-deploy in existing projects (detects `./agents/*.js`), manual code+bash in isolated setups. Tools adapt to CWD for portability. Hybrid modes combine server/client for chaining. See [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) for blueprint and validation.
+- **Multi-Agent Clusters**: PM2-powered CodeServer for scalable, clustered agent deployments (e.g., code_agent + todo_agent). Defaults to port 9000/secret '123'. See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md) for configuration.
+
+## Folder Structure
+
+- **bin/**: Executables for CLI tools.
+  - `dave.js`: Main CLI for asking agents or connecting to WebSocket servers.
+  - `spawn_agent.js`: Spawns agent instances (binary: `agentDave`).
+  - `codeDave`: Launches code servers (via PM2 clusters). References [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md) for setup and scaling.
+
+- **agents/**: Agent scripts (`*_agent.js`) for specific tasks. These can be run directly with `node agents/<script>.js`.
+  - `ask_agent.js`: General query agent.
+  - `code_agent.js`: Code generation and execution agent (serves as main server in code clusters).
+  - `daisy_agent.js`: Specialized agent (details in script).
+  - `docs_agent.js`: Documentation-focused agent.
+  - `gpt_agent.js`: OpenAI GPT integration agent.
+  - `grok_agent.js`: xAI Grok-specific agent.
+  - `memory_agent.js`: Agent with enhanced memory and context handling.
+  - `npm_agent.js`: NPM package management agent.
+  - `prompt_agent.js`: Prompt engineering and testing agent.
+  - `readme_agent.js`: README.md management agent.
+  - `spawn_agent.js`: Agent spawner (also in bin/). Creates portable CLI/WS agents + PM2 launchers. Validates/tests/deploys to `./agents/<name>.js`. Supports hybrid server/client modes. Portable to `/tmp` (tools follow CWD). Blueprint: [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md).
+  - `test_agent.js`: Testing and validation agent.
+  - `todo_agent.js`: TODO list and task management agent.
+  - `codeserver.sh`: Shell script for launching PM2-based code server clusters (uses agents above). See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
+
+- **lib/**: Core library modules (e.g., `index.js`, `wsCli.js`, `wsIO.js`, API integrations).
+- **scenarios/**: Test and example scenarios (e.g., toolset tests, integration scripts).
+- **types/**: TypeScript definitions.
+- **utils/**: Utility scripts (e.g., session management, testing).
+- **docs/**: Additional documentation, including agent blueprints (e.g., [prompt/spawn_agent.md](docs/prompt/spawn_agent.md)) and multi-agent guides (e.g., [multi-agent-clusters.md](docs/multi-agent-clusters.md)).
+- **release/**: Build artifacts.
+
+Other files: `package.json`, `CHANGELOG.md`, `TODO.md`, `LICENSE`.
 
 ## Installation
 
-Install as a dependency in your Node.js project (requires Node.js >= 20 with `"type": "module"` in `package.json`):
-
-```bash
-npm install @j-o-r/hello-dave
-```
-
-For global access to CLI tools (including `dave` from `bin/dave.js` and `createAgent`):
-
-```bash
-npm install -g @j-o-r/hello-dave
-```
-
-Set your API keys via environment variables (only set what you need):
-- `XAIKEY` for xAI Grok
-- `ANTHKEY` for Anthropic Claude
-- `OPENAIKEY` for OpenAI GPT
-- `BRAVESEARCHKEY` for web search (optional)
+1. **Prerequisites**: Node.js >= 20. PM2 for multi-agent clusters: `npm install -g pm2`.
 
-Create a cache directory for sessions:
-```bash
-mkdir .cache
-```
-
-## Quick Start
-
-1. Set an API key (e.g., for Grok):
-   ```bash
-   export XAIKEY=your_xai_api_key
-   ```
-
-2. Use the core CLI utility `bin/dave.js` (not a full agent) for interactive queries or management:
+2. **Local Development**:
    ```bash
-   npx @j-o-r/hello-dave dave --ask
+   git clone https://codeberg.org/duin/hello-dave.git
+   cd hello-dave
+   npm install
    ```
-   - Launches an interactive agent session using default Grok tools. Use `Alt+d` to exit, `Alt+r` to reset.
-   - Example: Ask questions about anything; it uses xAI Grok by default with web search and X search tools.
 
-3. For one-shot queries via piped input:
+3. **Global CLI Installation** (for `dave`, `agentDave`, `codeDave`):
    ```bash
-   echo "Explain quantum computing" | npx @j-o-r/hello-dave dave --ask --model grok-4
+   npm install -g .
+   # Or link for dev: npm run link-self
    ```
-   - Provides a direct response using the specified model (e.g., `--model grok-4`).
 
-4. Connect to a WebSocket server using the CLI utility (for UI access to servers):
-   ```bash
-   npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret your_secret
-   ```
-
-5. Generate a custom agent using the portable `createAgent` CLI tool (CLI/WS agents + CodeServer launchers; equivalent to `dave --spawn`):
-   ```bash
-   npx @j-o-r/hello-dave createAgent
-   ```
-   - Interactive: Follow prompts to create a new agent script in `bin/` (e.g., `bin/myagent.js`).
-   - Portable to any project (auto-installs deps like `@j-o-r/hello-dave`; runs via npx anywhere—no local install needed):
-     ```bash
-     npx @j-o-r/hello-dave createAgent --cwd ~/my-project
-     ```
-   - Supports one-shot: `echo "Create code-review agent" | npx @j-o-r/hello-dave createAgent --cwd ~/proj`.
-   - Aligns with CodeServer pattern for multi-agent setups (see Usage/Examples). Use `dave --spawn` as a convenience alias within this package.
-
-`bin/dave.js` also supports cache operations like `--list` (list sessions), `--search "query"`, `--clear`, and `--inspect path/to/log.ndjson`. For multi-agent clusters, use `--code` (see Usage).
+4. **API Keys**: Set environment variables (e.g., `XAIKEY` for xAI, `OPENAI_API_KEY` for OpenAI).
 
 ## Usage
 
-### Core CLI Utility via `bin/dave.js` (Not a Full Agent)
-
-`bin/dave.js` is a CLI utility for session maintenance, WS client connections (UI for servers), spawning agents (via `--spawn`, alias for `createAgent`), and launching CodeServer clusters. It does NOT support custom prompts/tools or server mode (--serve). For full agents with customization, use examples like `npm_agent.js` or programmatic `AgentManager`. Key functions:
-
-- **Ask Mode** (Interactive or Piped One-Shot, using default Grok agent):
-  ```bash
-  # Interactive
-  npx @j-o-r/hello-dave dave --ask --model grok-4 --temperature 0.2
-
-  # Piped one-shot
-  echo "What is quantum computing?" | npx @j-o-r/hello-dave dave --ask --model grok-4
-  ```
-  - Note: Piped input triggers a direct response via `directCall`; without pipe, it launches an interactive CLI session.
-  - `--model` option works for both modes (e.g., `grok-4`, `grok-4-1-fast-reasoning`).
-  - Uses default `AgentManager` with xAI Grok API integration, adds tools like `web_search`, `x_search`, `open_link`, `send_email`, `history_search`.
-  - System prompt emphasizes brief, direct responses with step-by-step reasoning.
-
-- **SpawnDave Mode** (Portable Agent Creator with --cwd Support; Convenience Alias for `createAgent`):
-  ```bash
-  # Interactive in current project
-  npx @j-o-r/hello-dave dave --spawn --model grok-4-fast-reasoning --temperature 0.7
-
-  # Portable to another project (switches cwd, auto-deps)
-  npx @j-o-r/hello-dave dave --spawn --cwd ../other-proj
-
-  # One-shot for quick generation
-  echo "name=coderev desc=Git diff analyzer tools=read_file execute_bash_script web_search" | npx @j-o-r/hello-dave dave --spawn --cwd ~/my-proj
-  ```
-  - Creates production-ready CLI/WS agents (`bin/<name>.js`) supporting CLI, server (`--serve`), client (`--connect`), and hybrid modes.
-  - Generates multi-agent CodeServer launchers (`examples/<Name>Server`) using PM2 for persistent networked setups (main server + sub-agents).
-  - **Portable**: Runs via `npx` anywhere—no local install needed. Auto-inspects project, installs `@j-o-r/hello-dave @j-o-r/sh` if missing, validates ESM code (`node --check`), tests deployment.
-  - Aligns with CodeServer pattern: Self-contained Bash launchers for PM2-managed multi-agents (e.g., code review + TODO + NPM agents).
-  - Requires `XAIKEY`; uses online repo docs (https://codeberg.org/duin/hello-dave) for portability.
-  - Example output: Deploys `bin/coderev_agent.js`, tests it, provides server/client usage guide.
-  - **Note**: `dave --spawn` is a convenience wrapper around the full `createAgent` tool (see below). Use `createAgent` directly for standalone/portable access without the dave utility.
-
-- **WebSocket Client Mode** (Utility UI for connecting to servers, with secrets for secure networking):
-  ```bash
-  # Interactive connection
-  npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
-
-  # Piped one-shot (direct CLI/cron messaging, no heartbeat needed)
-  echo "Predict the weather" | npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
-  echo "user_reset" | npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
-  ```
-
-- **CodeServer Launch Mode** (One-Command Multi-Agent Cluster via PM2; Utility Only, No --serve):
-  ```bash
-  # Global (requires global install)
-  dave --code 8080 --secret mysecret
-
-  # Portable via npx (no local install needed)
-  npx @j-o-r/hello-dave dave --code 8080 --secret mysecret
-  ```
-  - Launches `examples/codeserver.sh` with the provided port (1024-65535) and secret (min 3 chars), starting a PM2-managed CodeServer cluster.
-  - Cluster setup: Main `code_agent.js` as WS server on the port (exposes code tools); client agents (`todo_agent.js`, `readme_agent.js`, `npm_agent.js`, `docs_agent.js`, `test_agent.js`, `memory_agent.js`) connect as clients, gaining access to the servers tools.
-  - Requires PM2 installed globally: `npm i -g pm2`.
-  - **Portability Preference**: For maximum shell portability across environments, run the script directly: `./examples/codeserver.sh 8080 mysecret`. The `--code` flag is a Node.js wrapper for convenience in global/npx usage, auto-resolving paths.
-  - Monitors processes with PM2 prefix (e.g., `project_code_agent_8080`). Stop via `pm2 delete project_*_8080`.
-  - Aligns with Startup Modes (utility launch only; no direct --serve in dave.js—use full agents for servers).
-  - Connect to the cluster: `npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:8080 --secret mysecret` (interactive or piped).
-  - **Enhanced Documentation**: The `--code` flag provides a convenient wrapper around `examples/codeserver.sh`, which is the preferred method for direct shell execution in scripts or CI/CD pipelines due to its self-contained nature (no Node.js dependency). The script handles PM2 process management, cleanup, and absolute path resolution for portability.
-
-- **Cache Management** (Session maintenance in .cache):
-  ```bash
-  npx @j-o-r/hello-dave dave --list  # List sessions
-  npx @j-o-r/hello-dave dave --search "AI agents"  # Search history
-  npx @j-o-r/hello-dave dave --clear  # Clear cache
-  npx @j-o-r/hello-dave dave --inspect path/to/log.ndjson  # Inspect log
-  ```
-
-For custom full agents (with prompts/tools/server support), use `AgentManager` programmatically (see Examples) or scripts like `examples/npm_agent.js`.
-
-### createAgent CLI Tool (Portable Agent Generator; Full Agent Script)
-
-The `createAgent` command (mapped to `examples/spawn_agent.js` in package.json) is a full-featured agent for generating custom agents. It supports all Startup Modes (Direct Call, Interactive CLI, WS Server, WS Client, Hybrid) and is highly portable—run via `npx @j-o-r/hello-dave createAgent` anywhere without local installation. It auto-installs dependencies (`@j-o-r/hello-dave @j-o-r/sh`) in the target project, validates generated code, and tests deployments. Use `dave --spawn` as a convenience alias within this package.
-
-**Full Modes (Aligned with Startup Modes)**:
-- **Direct Call (One-Shot, Positional Arg Only)**: For single generations via positional prompt. Ideal for scripts/cron.
-  ```bash
-  # Portable one-shot (no local install)
-  npx @j-o-r/hello-dave createAgent "Create a code-review agent with git diff tools"
-  # With options
-  npx @j-o-r/hello-dave createAgent "Generate music agent" --model grok-4-fast-reasoning --temperature 0.7 --cwd ~/my-proj
-  ```
-  - Input: Positional string (trimmed). Triggers `directCall` for quick agent creation. Outputs generated script (e.g., `bin/coderev_agent.js`), validates with `node --check`, and tests via execution.
-
-- **Interactive CLI (No Positional Arg)**: Launches ongoing conversation for guided agent creation.
-  ```bash
-  # Interactive (current dir)
-  npx @j-o-r/hello-dave createAgent
-  # Portable to another project
-  npx @j-o-r/hello-dave createAgent --cwd ../other-proj --model grok-4
-  ```
-  - Follows conversational prompts: name (lowercase /^[a-z_0-9_]{2,}$/), description, tools, prompt, etc. Generates, deploys, and tests the agent.
+### CLI Tools
 
-- **WS Server (--serve [port])**: Exposes `createAgent` as a remote tool for other agents to call (e.g., generate agents programmatically).
-  ```bash
-  npx @j-o-r/hello-dave createAgent --serve 8081 --secret mysecret
-  ```
-  - Runs indefinitely; clients connect to use `spawn_agent` tool (tool_call_name: 'spawn_agent'). See Startup Modes for exposure details.
+- **dave**: Interact with agents locally or remotely.
+  - Local query: `dave --ask "Predict the weather"`
+  - One-shot remote: `echo "Hello" | dave --connect 'ws://127.0.0.1:8080' --secret '123'`
+  - Interactive remote: `dave --connect 'ws://127.0.0.1:8080' --secret '123'`
+  - Other: `dave --list` (sessions), `dave --clear` (cache), `dave --help`.
 
-- **WS Client (--connect [ws_url])**: Connects to a remote server (gains remote tools), then launches interactive CLI for agent generation.
+- **agentDave**: Spawn an agent server (powered by `spawn_agent.js`).
   ```bash
-  npx @j-o-r/hello-dave createAgent --connect ws://127.0.0.1:8080/ws --secret mysecret
+  agentDave --serve 8080 --secret '123'  # Starts WebSocket server
   ```
-  - Uses remote tools (e.g., from CodeServer) during generation. Portable via npx.
 
-- **Hybrid (--serve [port] + --connect [ws_url])**: Serves as a generator tool locally while using remote tools.
+- **codeDave**: Launch a PM2 code server cluster.
   ```bash
-  npx @j-o-r/hello-dave createAgent --serve 8082 --connect ws://localhost:8080/ws --secret mysecret
+  codeDave 8080 --secret '123'  # Or: dave --code 8080 --secret '123'
   ```
-  - Ideal for networked setups; generates agents with access to remote capabilities.
-
-**Shared Options** (Apply to All Modes):
-- `--model [grok-4-fast-reasoning|...]`: LLM model (default: grok-4-fast-reasoning).
-- `--temperature [float] (-2 to +2)`: Creativity level.
-- `--tokens [number]`: Max output tokens.
-- `--top_p [float]`: Nucleus sampling.
-- `--context [number] (default: 250000)`: Context window size.
-- `--cwd [path]`: Target directory for generation (auto-switches, installs deps if needed; portable).
-- `--secret [string] (min 3 chars)`: For WS modes (shared auth token).
 
-**Portability Emphasis**: `createAgent` is designed for use anywhere via `npx`—no cloning or local deps required. It inspects the target project (`--cwd`), auto-installs `@j-o-r/hello-dave @j-o-r/sh`, uses online repo docs (https://codeberg.org/duin/hello-dave), and ensures generated agents are self-contained (absolute imports, ESM validation). Requires `XAIKEY`. For piped one-shot: `echo "prompt" | npx @j-o-r/hello-dave createAgent --cwd ~/proj`.
-
-**Integration with dave --spawn**: Within this package, `dave --spawn` provides a simple wrapper (e.g., handles input parsing), but `createAgent` is the primary, standalone tool for broader use.
-
-### Programmatic Usage with AgentManager (For Full Agents)
-
-```javascript
-import AgentManager from '@j-o-r/hello-dave';
-
-const agent = new AgentManager({ name: 'MyAgent', secret: 'optional_secret' });
-agent.setup({
-  prompt: 'You are a helpful assistant...',
-  api: 'xai',  // Uses unified xAI Grok API access
-  options: { model: 'grok-4', temperature: 0.7, tools: [{ type: 'web_search' }] },
-  toolsetMode: 'auto',
-  contextWindow: 500000
-});
-
-agent.addGenericToolcall('execute_bash_script');  // Post-setup generics
-agent.addGenericToolcall('read_file');
-agent.addGenericToolcall('write_file');
-agent.addGenericToolcall('memory_recall');  // Persist/recall tasks, errors, prefs in .cache/memory.ndjson
-agent.addGenericToolcall('memory_write');   // Optimizes loops and long-running sessions
-
-await agent.start();  // Interactive CLI
-// Or: await agent.start(undefined, 8000, undefined, 'Intro', 'toolName', 'desc');  // WS server
-// Or: const response = await agent.directCall('Query');  // One-shot
-```
+### Running Agents
 
-Direct CLI/cron: Pipe inputs to custom scripts for non-interactive use. WS supports secrets for authentication; no heartbeat required due to event-driven messaging.
-
-The `memory_recall` and `memory_write` tools, available when `toolsetMode: 'auto'`, enable agents to persist and recall tasks, errors, and preferences in `.cache/memory.ndjson`. This optimizes iterative loops and long-running sessions by maintaining state across interactions without relying solely on session history.
-
-## Startup Modes
-
-This section unifies the startup modes for full agents (e.g., `examples/npm_agent.js`, `createAgent`) and the programmatic `AgentManager.start(serve, connect, cliIntro, tool_call_name, tool_call_description)`. These modes are standardized across agents generated by `createAgent` and align with the [AgentManager docs](docs/agent-manager.md). The CLI utility `bin/dave.js` supports only interactive ask, WS client connect, spawn_agent (via --spawn), cache management, and CodeServer launch via --code (no custom prompts/tools or --serve; utility-only). 
-
-All modes are cron-friendly with no heartbeat/ping required—agents respond directly to event-driven inputs. In WS modes (--serve, --connect, hybrid), positional arguments are ignored; use interactive CLI or piped inputs for messaging. Agent names and tool names must follow the strict lowercase naming rules: `/^[a-z_0-9_]{2,}$/` (no uppercase, hyphens, or specials) for filesystem/tool safety—see [AgentManager docs](docs/agent-manager.md).
-
-**Note on dave.js --code**: This utility flag launches a multi-agent CodeServer cluster via PM2 (shell portability preferred via direct `examples/codeserver.sh`), aligning with hybrid WS patterns but without direct --serve support in the utility itself. Use full agents for standalone servers.
-
-**Note on createAgent**: As a full agent, it supports all modes below. Use for portable generation in any project.
-
-### AgentManager.start() Options Explained
-The `start()` method is the smart launcher for all modes. It accepts up to 5 arguments in order:
-- `serve` (number | undefined): Port for WS **server** mode (e.g., 8080). Exposes the agent as a remote tool via `ws://127.0.0.1:[port]/ws`. Requires `--secret` for client authentication. Runs indefinitely until Ctrl+C. See [AgentManager docs](docs/agent-manager.md) for server config.
-- `connect` (string | undefined): WS URL for **client** mode (e.g., `ws://127.0.0.1:8080/ws`). Connects to a remote server to gain access to its tools. Launches interactive CLI after connection.
-- `cliIntro` (string | undefined): Custom welcome message for interactive CLI mode (e.g., "NPM Agent ready. Ask about modules.").
-- `tool_call_name` (string | undefined): **Required for server mode**. The tool name this agent exposes (must match naming regex `/^[a-z_0-9_]{2,}$/`). E.g., `npm_module_inspector`. Used when clients attach.
-- `tool_call_description` (string | undefined): **Required for server mode**. Detailed description of the exposed tool (e.g., "Inspects NPM modules in node_modules/ using bash and cache.").
-
-**Mode Determination**:
-- If `serve` provided: Starts WS server (exposes tools).
-- If `connect` provided: Starts WS client (attaches to remote, gains tools).
-- If both: Hybrid mode (serves locally while using remote tools).
-- If neither: Interactive CLI mode.
-- For one-shot (non-start): Use `directCall(input)` directly (positional arg in scripts).
-
-**Shared Notes**:
-- `--secret [string]` (min 3 chars): Shared auth token. Servers reject mismatched clients; use the same for chains/networks.
-- Other options: `--model [grok-4-fast-reasoning|...]`, `--temperature [-2 to +2]`, `--tokens`, `--top_p`, `--context [250000]`.
-- Positional args ignored in WS modes (use CLI/pipes instead).
-- No heartbeat: Event-driven responses.
-- For multi-agent chaining, see [CodeServer pattern](docs/codeserver-pattern.md).
-
-### 1. Direct Call (One-Shot, Positional Arg Only)
-For single responses via positional query. Ideal for scripts/cron jobs. Bypasses CLI/WS; uses `agent.directCall(input)`. (Not available in `dave` utility for custom agents; use full agents or `--ask` for defaults.)
-
-**CLI Example (Full Agent, e.g., npm_agent.js or createAgent)**:
+Run agent scripts directly:
 ```bash
-npx @j-o-r/hello-dave createAgent "What modules are installed?" [--model grok-4]
-./examples/npm_agent.js "What modules are installed?" [--model grok-4]
+node agents/spawn_agent.js --serve 8080 --secret '123'  # Spawn server
+node agents/code_agent.js --connect 'ws://127.0.0.1:8080' --secret '123'  # Client mode
 ```
-- Input: Positional string (trimmed). If empty/missing, falls to interactive CLI or help.
 
-**Programmatic (AgentManager)**:
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave' ;
-const agent = new AgentManager({ name: 'npm_agent' });
-await agent.setup({ /* prompt, api, options, toolsetMode, contextWindow */ });
-const response = await agent.directCall('What modules are installed?' );
-console.log(response);
-```
-- Pair with `readIn()` from `@j-o-r/sh` for piped stdin detection in scripts (e.g., `echo "query" | script.js`).
+For full options, see script headers or run with `--help`.
 
-**Utility (dave.js for Default Queries)**:
-```bash
-echo "Explain quantum computing" | npx @j-o-r/hello-dave dave --ask [--model grok-4]
-```
-- Triggers `directCall` on piped input.
-
-### 2. Interactive CLI (No Positional Arg)
-Launches ongoing conversation session with REPL-like input (multi-turn, until Ctrl+C or `Alt+d`).
-
-**CLI Example (Full Agent)**:
-```bash
-npx @j-o-r/hello-dave createAgent [--model grok-4]
-./examples/npm_agent.js [--model grok-4]
-```
-- No positional: Starts `agent.start()` with CLI intro.
+### Programmatic Usage
 
-**Programmatic**:
+Import and use in your Node.js app:
 ```javascript
-await agent.start(undefined, undefined, 'NPM Agent ready. Ask about modules or tools.' );  // Interactive CLI with custom intro
+import { AgentManager } from '@j-o-r/hello-dave';
+// Setup and run agent...
 ```
-- Uses `cliIntro` for welcome message. Supports history, reset (`Alt+r`).
 
-**Utility (dave.js)**:
-```bash
-npx @j-o-r/hello-dave dave --ask
-```
-- Default agent; no custom tools/prompts.
-
-### 3. WS Server (--serve [port])
-Starts a WebSocket server at `ws://127.0.0.1:[port]/ws` to expose the agent as a remote tool for clients. Runs indefinitely. (Not supported in `dave` utility.)
-
-**CLI Example (Full Agent)**:
-```bash
-npx @j-o-r/hello-dave createAgent --serve 8080 [--secret mysecret] [--model grok-4]
-./examples/npm_agent.js --serve 8080 [--secret mysecret] [--model grok-4]
-```
-- Exposes `tool_call_name` (e.g., `npm_module_inspector` or `spawn_agent` for createAgent) for remote calls.
+### spawn_agent.js Specifics (v0.0.8 Portability Ready)
 
-**Programmatic**:
-```javascript
-await agent.start(8080, undefined, undefined, 'npm_module_inspector' , 'NPM modules expert using bash and cache in node_modules/.' );  // Server on 8080; secret optional but recommended
-```
-- `tool_call_name` and `tool_call_description` required for exposure. See [AgentManager docs](docs/agent-manager.md) for full server config, including reset propagation.
-
-**Client Usage** (Connect to this server):
-```bash
-# Interactive
-npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:8080 --secret mysecret
-# Or full agent: ./examples/other_agent.js --connect ws://127.0.0.1:8080 --secret mysecret
-```
-- Clients gain the servers tools (e.g., call `npm_module_inspector` in their prompts).
+`spawn_agent.js` (executable as `agentDave`) creates and deploys portable agents in CLI, WebSocket server, client, or **hybrid** modes (server + client for tool chaining). It fetches live prompts from [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) and validates new agents via blueprint (temp files, syntax checks, grep for modes/tools).
 
-### 4. WS Client (--connect [ws_url])
-Connects to a remote WS server as a client, gaining access to its tools, then launches interactive CLI.
+- **Modes**:
+  - **Direct (One-Shot)**: Positional input, e.g., `node agents/spawn_agent.js "Create a tester"`.
+  - **Interactive CLI**: No input; runs REPL-like session.
+  - **Server**: `--serve <port>` – Exposes as remote tool (e.g., for other agents to call `spawn_agent`).
+  - **Client**: `--connect <ws_url>` – Connects to remote server for tool access.
+  - **Hybrid**: `--serve <port> --connect <ws_url>` – Serves locally while using remote tools.
 
-**CLI Example (Full Agent)**:
-```bash
-npx @j-o-r/hello-dave createAgent --connect ws://127.0.0.1:8080/ws --secret mysecret [--model grok-4]
-./examples/npm_agent.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--model grok-4]
-```
-- Attaches to server; uses remote tools in local sessions.
+- **Portability**:
+  - **In Project**: Auto-deploys to `./agents/<name>.js` if `./agents/*.js` exist (uses existing structure).
+  - **Fresh /tmp**: Manual code generation + bash setup (e.g., `mkdir /tmp/myproj/agents; cd /tmp/myproj; node spawn_agent.js ...`). Tools (e.g., `read_file`) follow CWD, ensuring isolation without fixed paths.
+  - Works in any dir; no repo deps beyond Node.js + npm installs.
 
-**Programmatic**:
-```javascript
-await agent.start(undefined, 'ws://127.0.0.1:8080/ws' , undefined, undefined, undefined );  // Client mode; secret required if server uses one
-```
-- After connection, interactive CLI starts. For one-shot: Pipe to script (uses `directCall` with remote tools).
+- **Custom Tools**: Specify in prompt, e.g., "name=coderev, tools=read_file,web_search,execute_bash_script".
 
-**Utility (dave.js)**:
-```bash
-# Interactive
-npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
-# Piped one-shot (cron-friendly)
-echo "Use remote NPM tool to list modules" | npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
-```
+For validation/testing: See blueprint in [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) (includes bash examples like `node agents/NEW_AGENT.js --help` or server connect tests).
 
-### 5. Hybrid (--serve [port] + --connect [ws_url])
-Serves tools locally (on local port) while connecting as a client to a remote server (gains remote tools). No positional arg; launches interactive CLI. Ideal for agent chains/networks. (Not supported in `dave` utility.)
+### CodeServer & PM2 Multi-Agent (v0.0.8)
 
-**CLI Example (Full Agent)**:
-```bash
-npx @j-o-r/hello-dave createAgent --serve 8081 --connect ws://otherhost:8080/ws [--secret mysecret]
-./examples/npm_agent.js --serve 8081 --connect ws://otherhost:8080/ws [--secret mysecret]
-```
-- Local server on 8081 (exposes local tools); client to remote (uses remote tools).
+CodeServer (via `bin/codeDave` or `agents/codeserver.sh`) launches scalable, PM2-clustered multi-agent environments for collaborative tasks (e.g., code generation + task management). It deploys agents like `code_agent`, `todo_agent`, and `readme_agent` on a WebSocket server, enabling chaining and load balancing.
 
-**Programmatic**:
-```javascript
-await agent.start(8081, 'ws://otherhost:8080/ws' , 'Hybrid NPM Agent ready.' , 'npm_module_inspector' , 'Hybrid NPM inspector with remote access.' );  // Hybrid; secret for both if needed
-```
-- Custom handling for secrets (use same or per-mode). See [AgentManager docs](docs/agent-manager.md) for hybrid details and error handling.
-
-**Notes**: Positional args ignored. Use for distributed setups (e.g., NPM agent serves locally but uses a code agents tools remotely). Monitor with tools like `netstat` or PM2 in CodeServer.
-
-This section completes the unified documentation for startup modes, aligned with `npm_agent.js` help output, `createAgent`, and `AgentManager` API. For more, see [docs/agent-manager.md](docs/agent-manager.md) and [examples/](examples/).
-
-## Examples
-
-Example scripts (e.g., `readme_agent.js` for README management, `todo_agent.js` for task handling, `spawn_agent.js` for agent creation via `createAgent`) are now organized in the `examples/` folder. These demonstrate specialized full agents using `AgentManager`, xAI Grok API integration, and tools. **Note**: Agent names and filenames follow lowercase naming rules per [docs/agent-manager.md](docs/agent-manager.md) (regex `/^[a-z_0-9_]{2,}$/` for safety in folders, tools, and filesystems—no uppercase, hyphens, or specials).
-
-- **Link to Examples Folder**: Explore [examples/](examples/) for full scripts like `daisy_agent.js` (music agent), `code_agent.js` (code review), `npm_agent.js` (NPM inspector).
-
-In custom agents, consider adding `memory_recall` and `memory_write` tools to enable state persistence for complex workflows, such as tracking progress in multi-step tasks or storing user preferences across sessions.
-
-### Persistent Multi-Agent CodeServer Pattern
-
-The `examples/codeserver.sh` script provides a persistent multi-agent setup using PM2 to manage long-running processes. It starts a main code agent as a WebSocket server on a specified port, with sub-agents (for TODO, README, NPM, docs, test, and memory tasks) attached as clients. This pattern enables a networked ecosystem of specialized agents that maintain state across sessions, ideal for extended development workflows where context persistence and task delegation are key.
-
-Benefits include seamless integration for dev sessions—agents stay online, handling queries via WS without restarts, supporting large context windows and tool calls. For full details, see [docs/codeserver-pattern.md](docs/codeserver-pattern.md).
-
-**Usage (Prefer Shell Portability):**
-
-```bash
-# Direct shell launch (portable, no Node.js wrapper needed; requires PM2: npm i -g pm2)
-./examples/codeserver.sh 8080 mysecret
-
-# Convenience via dave.js utility (global or npx)
-dave --code 8080 --secret mysecret
-npx @j-o-r/hello-dave dave --code 8080 --secret mysecret
-```
-
-Monitor with `pm2 list` and stop via `pm2 delete <name>` (e.g., `pm2 delete project_*_8080`).
-
-**Connect via CLI utility (interactive or piped):**
-```bash
-npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:8080/ws --secret mysecret
-# Or for one-shot: echo "Review this code" | npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:8080/ws --secret mysecret
-```
-
-### Snippet: Spawning Agents (Portable via `createAgent` or `dave --spawn`)
-
-`createAgent` (examples/spawn_agent.js) uses `AgentManager` to interactively or programmatically generate new agent scripts, fully aware of WebSocket server/client modes and the CodeServer multi-agent pattern for networked setups. It supports all Startup Modes and is portable via npx.
-
-Now CodeServer-aware: Can generate PM2 multi-agent launchers (e.g., Generate CodeServer for coderev + todo). See updated [examples/spawn_agent.js](examples/spawn_agent.js) and [docs/codeserver-pattern.md](docs/codeserver-pattern.md).
-
-**Portable**: `createAgent` runs anywhere via `npx`—no local docs/examples needed. Uses online repo links (https://codeberg.org/duin/hello-dave). Auto-deps with `--cwd`. `dave --spawn` is a convenience alias for use within this package.
-
-```javascript
-// Core setup in createAgent (examples/spawn_agent.js)
-const agent = new AgentManager({ name: 'spawn_agent', secret });
-agent.setup({
-  prompt: 'You are AgentCreator... [detailed prompt for portability, validation]',
-  api: 'xai',
-  options: { model: 'grok-4-fast-reasoning', tools: [{ type: 'web_search' }], reasoning: { effort: 'high' } },
-  toolsetMode: 'auto',
-  contextWindow: 500000
-});
-agent.addGenericToolcall('execute_bash_script');  // For project inspection
-agent.addGenericToolcall('read_file');
-agent.addGenericToolcall('write_file');  // For generating bin/ scripts
-agent.addGenericToolcall('memory_recall');  // For recalling previous generations or prefs
-agent.addGenericToolcall('memory_write');   // For persisting agent configs or errors
-
-await agent.start();  // Guides user to create e.g., bin/myagent.js
-```
-
-- Validates generated ESM code with `node --check` and tool rules (xAI natives pre-setup, generics post-setup).
-- Ensures absolute imports for portability.
-
-**Example Usage (Portable Agent Generation & CodeServer)**:
-
-```bash
-# Interactive spawning (runs from npm without cloning; current dir)
-npx @j-o-r/hello-dave createAgent
-# Or via dave alias: npx @j-o-r/hello-dave dave --spawn
-
-# Portable to specific project (auto-switches cwd, installs deps if needed)
-npx @j-o-r/hello-dave createAgent --cwd ~/my-proj --model grok-4-fast-reasoning
+- **Defaults**: Port 9000, secret '123' (customizable via args).
+- **Prerequisites**: Install PM2 globally (`npm install -g pm2`).
+- **Quickstart**:
+  ```bash
+  codeDave 9000 --secret 123  # Launches PM2 cluster on ws://127.0.0.1:9000/ws
+  pm2 list  # Verify processes (e.g., code_agent, todo_agent instances)
+  echo "task" | bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123  # One-shot query to cluster
+  ```
+  This starts the cluster, lists running agents, and sends a test task (response routed to available agents).
 
-# Piped one-shot for quick agent (portable, no cloning)
-echo "Create a code-review agent: name=coderev, desc=Git diff analyzer, tools=read_file execute_bash_script web_search" | npx @j-o-r/hello-dave createAgent --cwd ~/proj
+- **Scaling & Management**: Use PM2 commands (e.g., `pm2 scale <app> 4`, `pm2 stop all`). For ecosystem config, PM2 JSON files, or agent orchestration, see the [full guide in docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
 
-# Generate CodeServer launcher (multi-agent)
-npx @j-o-r/hello-dave createAgent "Generate CodeServer launcher for coderev + tododave + npmdave" --cwd ~/proj
-# Outputs self-contained Bash script (e.g., examples/CodeServer.sh) for PM2-managed cluster
-```
+- **Integration**: Combine with `spawn_agent.js` for dynamic agent addition to clusters (e.g., spawn new agents and connect via `--connect ws://127.0.0.1:9000/ws`).
 
-- **Portable Agent Generation**: Creates `bin/<name>_agent.js` with full modes (CLI/server/client/hybrid), tests it, and provides usage guide. No local setup needed—auto-handles deps and validation.
-- **CodeServer Integration**: If prompted (e.g., "multi-agent setup"), generates PM2 launchers like `examples/<Custom>Server.sh` (main server + sub-agents). Portable and self-contained; run directly or via `dave --code`.
+## Usage Examples
 
-### Snippet: Using xAI Grok API Integration
-
-The unified xAI Grok API access supports options like reasoning and tools:
+- **Direct Spawn (Project)**:
+  ```bash
+  cd hello-dave  # Or any project with ./agents/
+  node agents/spawn_agent.js "Create code-review agent: name=coderev, desc=Git diff analyzer, tools=read_file,execute_bash_script,web_search"
+  # Deploys to ./agents/coderev_agent.js; test: node agents/coderev_agent.js "Review this diff"
+  ```
 
-```javascript
-// In AgentManager setup
-const options = {
-  model: 'grok-4-1-fast-reasoning',
-  temperature: 0.8,
-  tools: [{ type: 'web_search' }, { type: 'x_search', from_date: '2024-01-01' }],  // Native xAI tools
-  reasoning: { effort: 'medium', summary: 'auto' }  // Chain-of-thought support
-};
-```
+- **/tmp Workflow (Portable, Fresh Setup)**:
+  ```bash
+  mkdir -p /tmp/myportable/agents
+  cd /tmp/myportable
+  # Copy or fetch spawn_agent.js (e.g., curl from repo or npm install @j-o-r/hello-dave)
+  npm init -y && npm i @j-o-r/hello-dave @j-o-r/sh
+  node spawn_agent.js "Create todo agent: name=todo, desc=Task manager, tools=read_file,write_file"
+  # Deploys to ./agents/todo_agent.js; tools use /tmp/myportable as CWD
+  node agents/todo_agent.js --serve 8081 --secret abc  # Test server mode
+  ```
 
-Detailed examples for xAI integration (e.g., advanced tool calls, reasoning) are planned (see TODO).
+- **Hybrid Mode with Custom Tools**:
+  ```bash
+  node agents/spawn_agent.js --serve 8081 --connect ws://127.0.0.1:8080/ws --secret abc "Spawn a docs agent with custom email tool"
+  # Serves on 8081 (exposes new agent), connects to 8080 (gains remote tools like email)
+  # Test: In another term, node agents/spawn_agent.js --connect ws://127.0.0.1:8081/ws --secret abc "Use the new docs agent"
+  ```
 
-### Running Examples
+- **Spawn a Server**:
+  ```bash
+  node agents/spawn_agent.js --serve 8080 --secret '123'
+  # Then connect: echo "Task" | dave --connect 'ws://127.0.0.1:8080' --secret '123'
+  ```
 
-```bash
-# Music agent (examples/daisy_agent.js - full agent)
-chmod +x examples/daisy_agent.js
-./examples/daisy_agent.js "Generate lyrics for a pop song"
+- **Launch Code Cluster** (includes multiple agents):
+  ```bash
+  node agents/codeserver.sh 9000 '123'  # Or use codeDave 9000 --secret 123
+  # Connects code_agent, todo_agent, readme_agent, etc., to the server on ws://127.0.0.1:9000/ws.
+  # Test: pm2 list; echo "Optimize this code" | dave --connect ws://127.0.0.1:9000/ws --secret 123
+  # For advanced config: See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
+  ```
 
-# TODO manager (examples/todo_agent.js - full agent)
-./examples/todo_agent.js --connect ws://localhost:8080 --secret "secret"
+- **Local Agent Query** (no server):
+  ```bash
+  dave --ask --model 'grok-4-1-fast-reasoning' "Write a function"
+  ```
 
-# Server setup for networked examples (use full agents, not dave utility)
-./examples/npm_agent.js --serve 8080  # Expose as WS server
+- **Custom Agent**:
+  ```bash
+  node agents/docs_agent.js --connect 'ws://127.0.0.1:8080' --secret '123'
+  ```
 
-# Generate custom agent (via createAgent)
-npx @j-o-r/hello-dave createAgent "Create a docs agent"
-```
+See `scenarios/` for more test scenarios.
 
 ## Development
 
-- **Scripts**: `npm test` (runs scenarios/grok_agent.js), `npm run types` (generate TypeScript defs), `npm run release` (pack for release).
-- **Structure**: Core in `lib/` (AgentManager.js, wsCli.js, etc.), API integrations in `lib/API/`, examples in `examples/`, utils in `utils/`.
-- **Testing**: Basic validation via `npm test`. Unit tests for xAI integration planned (see TODO).
-- **Prep for v0.0.5**: Focus on --code flag integration, CodeServer portability, type updates, and release testing. Documentation for --spawn, --code, and bin/createAgent enhanced and marked complete.
-
-## Changelog
-
-### v0.0.5 (Released - May 2026)
-- **Release Complete**: Updated package.json to version "0.0.5". Full test suite passed 100% (no regressions). Types generated and verified. Git tagged and published.
-- **WebSocket Export Refinements**: lib/index.js now exports `wsCli` and `wsIO` for seamless programmatic access and integration (e.g., in bin/dave.js using package imports instead of relative paths). Improves modularity for consumers without breaking existing APIs.
-- **CodeServer Enhancements**: Added --code flag to bin/dave.js for one-command CodeServer launch (global/npx portable). Launches examples/codeserver.sh for PM2-managed multi-agent cluster (code_agent server + todo/readme/npm/docs/test/memory clients). Emphasizes shell script portability; aligns with Startup Modes (utility only, no --serve).
-- **Spawn Flag Documentation**: Enhanced --spawn in bin/dave.js for launching examples/spawn_agent.js. Added usage examples for interactive, one-shot (--spawn "prompt"), and piped input. Integrated into Quick Start and Usage sections.
-- **createAgent Bin Promotion**: Documented `createAgent` CLI (package.json bin mapping to examples/spawn_agent.js) as primary portable tool for agent generation. Added full Usage section with modes (interactive/one-shot/WS server/client/hybrid), options (--model etc.), and portability emphasis (npx anywhere, auto-deps). Linked as standalone equivalent to dave --spawn (convenience alias). Updated Quick Start/Examples/Startup Modes with createAgent examples; fixed direct calls from spawn_agent to createAgent.
-- **CLI Usage Section**: Confirmed and enhanced documentation for --code flag, preferring direct execution of examples/codeserver.sh for shell portability. Added dedicated examples and notes under Core CLI Utility.
-- **Package Alignment**: Bumped package.json to version "0.0.5" in preparation for release; regenerated types to include new exports and flag support.
-- **Prep Notes**: Git clean performed; full tests/types/docs verified post-updates. Focus on CodeServer integration, portability testing, and createAgent docs complete. v0.0.5 docs marked as complete.
-
-### v0.0.4 (Previous - April 2026)
-- **Release Preparation Complete**: Updated package.json to version "0.0.4" (pending final commit/tag). Full test suite passed 100% (no regressions in genericToolset.test.js or other scenarios). Types generated and verified.
-- **Agent Standardization**: All 12 example agents (e.g., code_agent.js, readme_agent.js, test_agent.js) now follow unified npm_agent.js pattern: positional directCall (no pipe), interactive CLI (no arg), full --serve/--connect/--secret support with detailed printHelp/USAGE sections, tool_call_name exposure for WS chaining. Syntax validated across all.
-- **Prompt Safeguards**: Added STRICT NO-CODING RULE to non-coding agents (e.g., todo_agent.js, readme_agent.js, docs_agent.js, prompt_agent.js) to prevent misuse of tools like execute_code, write_file, syntax_check. Matches todo_agent.js style; verified no regressions.
-- **Memory Protocol Enhancements**: Updated prompts (e.g., spawn_agent.js, test_agent.js) to mandate memory_recall/write FIRST/LAST for tasks/errors/prefs/decisions, reducing token burn and enabling human handoff. Integrated into workflows for iterative testing and agent generation.
-- **File Renames and Cleanup**: Renamed all examples/ files to *_agent.js (e.g., codedave.js → code_agent.js); updated references in README.md, docs/, TODO.md, package.json. Removed all old "Dave/dave" references (grep -r confirmed zero remnants).
-- **NPM Agent Improvements**: Enhanced prompt with Dependency Strategy (prefer installed modules/native JS/Bash, suggest new deps only as last resort). Added full npm ls -a scanning for subdeps; strict no-installs policy. Vague query handling improved (e.g., auto-cache for tests).
-- **Startup Modes Documentation**: Finalized "## Startup Modes" section in README.md with 5 unified modes (Direct Call, CLI, Server, Client, Hybrid), AgentManager.start() explanations, CLI/programmatic examples, and links to docs/agent-manager.md. Aligned with all agent help outputs.
-- **Test Agent Enhancements**: test_agent.js standardized; prompt updated for Test class usage in scenarios/*.test.js (e.g., toolset.test.js generation/validation). Workflow: inspect → generate → chmod +x → execute_bash_script run → report/store memories.
-- **WS Client Refinements**: lib/wsCli.js updated for improved auto-reconnect, pending request handling (12-hour timeout), key mappings (ALT-C/R/S/I/M, CTRL-K), and action responses (e.g., server_reset, sessionlist). Clipboard copy via xclip; better error logging.
-- **TODO Alignment**: High-priority items cleared (e.g., explain startup modes, agent standardization, prompt updates). No high-priority pending; project reviewed stable as of April 02, 2026.
-- **Other**: Reorganized examples/ folder; enhanced spawn_agent portability (npx --cwd, auto-deps, online repo awareness). Git ahead by 1 commit (cleanup toolset test); ready for v0.0.4 tag/publish.
-
-### v0.0.3 (Previous - March 2026)
-- Initial WS secrets, generic tools, AgentManager refinements.
-- Reorganized examples to `examples/` folder (readmeDave, todoDave, etc.).
-- Enhanced `bin/dave.js` for core utilities: spawning, WS with secrets, direct messaging.
-- Improved xAI Grok API integration; added native tools/reasoning support.
-- Removed heartbeat needs; direct CLI/cron support.
-- Added piped one-shot support to dave --ask.
-
-Full history in git tags (recent: cleanup toolset test, TODO status update, fixed test/README, syntax fixes, startup modes explanation).
+- **Build Types**: `npm run types`
+- **Test**: `npm run tests` (runs `utils/test.sh`)
+- **Release**: `npm run release` then `npm run publish`
+- **Local Linking**: `npm run link-self` / `npm run unlink-self`
 
-## Contributing
+Use `git status` and `ls` to inspect changes. Ensure ESM compatibility.
 
-Contributions are welcome! Fork the repo at [https://codeberg.org/duin/hello-dave](https://codeberg.org/duin/hello-dave), create a feature branch, and submit a pull request.
+## Contributing
 
-1. Install deps: `npm install`
-2. Self dep `npm run link-self`
-3. Run tests: `npm test`
-4. Generate types: `npm run types`
-5. Report issues: [https://codeberg.org/duin/hello-dave/issues](https://codeberg.org/duin/hello-dave/issues)
+Contributions welcome! Fork the repo, create a branch, and submit a pull request to https://codeberg.org/duin/hello-dave.
 
-Follow the [Code of Conduct](CODE_OF_CONDUCT.md) and Apache-2.0 license.
+- Report bugs: https://codeberg.org/duin/hello-dave/issues
+- Follow Apache-2.0 license.
 
 ## License
 
-Apache License 2.0. See [LICENSE](LICENSE) for details.
-
-## TODO Alignment
-
-This README aligns with high-priority items from [TODO.md](TODO.md):
-- **v0.0.5 Prep**: Changelog updated for --code flag, CodeServer enhancements, and bin/createAgent promotion; release steps emphasized (version bump to 0.0.5, tests, types, commit/tag, publish). Prep notes expanded for portability and utility alignment. Marked complete.
-- **CodeServer TODOs**: Related tasks marked complete (e.g., --code flag implementation/docs, preference for codeserver.sh portability). No high-priority pending; sub-tasks on testing/alternatives deprioritized.
-- **createAgent / spawn_agent Enhancements**: Fully documented as primary bin tool with modes, options, portability (npx/auto-deps), and CodeServer support. Linked to dave --spawn alias. Examples/Quick Start updated.
-- **Agent Standardization and Safeguards**: Integrated into Changelog and Usage notes (from v0.0.4).
-- xAI integration tests/examples: Deferred to post-v0.0.5 (future enhancements).
-- Documentation tasks (e.g., AgentManager internals, WS refinements) completed in Usage/Examples/Changelog.
-- **Status**: No high-priority pending; all tests stable. v0.0.5 docs complete. Focus shifted to release and future features like xAI files.js integration.
+This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.
 
-For full TODO, see [TODO.md](TODO.md).
+---
+*Repository: https://codeberg.org/duin/hello-dave*
+---