@j-o-r/hello-dave 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+## Changelog
+
+### v0.0.4 (Upcoming - 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.

package/README.md

@@ -1,4 +1,4 @@
-# Updated README.md content
+# Updated README.md with enhanced Changelog for v0.0.4 prep
 
 # @j-o-r/hello-dave
 
@@ -13,6 +13,7 @@
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Usage](#usage)
+- [Startup Modes](#startup-modes)
 - [Examples](#examples)
 - [Development](#development)
 - [Changelog](#changelog)
@@ -39,6 +40,7 @@ Whether you're building a code reviewer, a research assistant, or a creative col
 - **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, and interactive queries; plus agent generator.
 - **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').
 
 ## Installation
 
@@ -72,11 +74,11 @@ mkdir .cache
    export XAIKEY=your_xai_api_key
    ```
 
-2. Use the core CLI utility `bin/dave.js` for interactive queries or management:
+2. Use the core CLI utility `bin/dave.js` (not a full agent) for interactive queries or management:
    ```bash
    npx @j-o-r/hello-dave dave --ask
    ```
-   - Launches an interactive agent session. Use `Alt+d` to exit, `Alt+r` to reset.
+   - 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:
@@ -85,32 +87,32 @@ mkdir .cache
    ```
    - Provides a direct response using the specified model (e.g., `--model grok-4`).
 
-4. Connect to a WebSocket server (e.g., for networked agents):
+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
+   Utility: npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret your_secret
    ```
 
-5. Generate a custom agent using the portable `spawndave` tool (CLI/WS agents + CodeServer launchers):
+5. Generate a custom agent using the portable `spawn_agent` tool (CLI/WS agents + CodeServer launchers):
    ```bash
-   npx @j-o-r/hello-dave spawndave
+   npx @j-o-r/hello-dave spawn_agent
    ```
    - 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`):
      ```bash
-     npx @j-o-r/hello-dave spawndave --cwd ~/my-project
+     npx @j-o-r/hello-dave spawn_agent --cwd ~/my-project
      ```
-   - Supports one-shot: `echo "Create code-review agent" | npx @j-o-r/hello-dave spawndave --cwd ~/proj`.
+   - Supports one-shot: `echo "Create code-review agent" | npx @j-o-r/hello-dave spawn_agent --cwd ~/proj`.
    - Aligns with CodeServer pattern for multi-agent setups (see Usage/Examples).
 
 `bin/dave.js` also supports cache operations like `--list` (list sessions), `--search "query"`, `--clear`, and `--inspect path/to/log.ndjson`.
 
 ## Usage
 
-### Core CLI via `bin/dave.js`
+### Core CLI Utility via `bin/dave.js` (Not a Full Agent)
 
-`bin/dave.js` provides essential utilities and examples for agent spawning, WS interactions, and basic querying. Key commands:
+`bin/dave.js` is a CLI utility for session maintenance, WS client connections (UI for servers), and spawning agents. 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):
+- **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
@@ -120,47 +122,48 @@ mkdir .cache
   ```
   - 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 `AgentManager` with xAI Grok API integration, adds tools like `web_search`, `x_search`, `open_link`, `send_email`, `history_search`.
+  - 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):
   ```bash
   # Interactive in current project
-  npx @j-o-r/hello-dave spawndave --model grok-4-fast-reasoning --temperature 0.7
+  npx @j-o-r/hello-dave spawn_agent --model grok-4-fast-reasoning --temperature 0.7
 
   # Portable to another project (switches cwd, auto-deps)
-  npx @j-o-r/hello-dave spawndave --cwd ../other-proj
+  npx @j-o-r/hello-dave spawn_agent --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 spawndave --cwd ~/my-proj
+  echo "name=coderev desc=Git diff analyzer tools=read_file execute_bash_script web_search" | npx @j-o-r/hello-dave spawn_agent --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.js`, tests it, provides server/client usage guide.
+  - Example output: Deploys `bin/coderev_agent.js`, tests it, provides server/client usage guide.
 
-- **WebSocket Client Mode** (with secrets for secure networking):
+- **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"
+  Utility: 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"
   ```
 
-- **Cache Management**:
+- **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 agents, use `AgentManager` programmatically (see Examples).
+For custom full agents (with prompts/tools/server support), use `AgentManager` programmatically (see Examples) or scripts like `examples/npm_agent.js`.
 
-### Programmatic Usage with AgentManager
+### Programmatic Usage with AgentManager (For Full Agents)
 
 ```javascript
 import AgentManager from '@j-o-r/hello-dave';
@@ -177,6 +180,8 @@ agent.setup({
 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
@@ -185,11 +190,154 @@ await agent.start();  // Interactive CLI
 
 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`) and the programmatic `AgentManager.start(serve, connect, cliIntro, tool_call_name, tool_call_description)`. These modes are standardized across agents generated by `spawn_agent` 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, and cache management (no custom prompts/tools or --serve). 
+
+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).
+
+### 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)**:
+```bash
+./examples/npm_agent.js "What modules are installed?" [--model grok-4]
+```
+- 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`).
+
+**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
+./examples/npm_agent.js [--model grok-4]
+```
+- No positional: Starts `agent.start()` with CLI intro.
+
+**Programmatic**:
+```javascript
+await agent.start(undefined, undefined, 'NPM Agent ready. Ask about modules or tools.' );  // Interactive CLI with custom intro
+```
+- 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
+./examples/npm_agent.js --serve 8080 [--secret mysecret] [--model grok-4]
+```
+- Exposes `tool_call_name` (e.g., `npm_module_inspector`) for remote calls.
+
+**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 server's tools (e.g., call `npm_module_inspector` in their prompts).
+
+### 4. WS Client (--connect [ws_url])
+Connects to a remote WS server as a client, gaining access to its tools, then launches interactive CLI.
+
+**CLI Example (Full Agent)**:
+```bash
+./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.
+
+**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).
+
+**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"
+```
+
+### 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.)
+
+**CLI Example (Full Agent)**:
+```bash
+./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).
+
+**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 agent's 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 and `AgentManager` API. For more, see [docs/agent-manager.md](docs/agent-manager.md) and [examples/](examples/).
+
 ## Examples
 
-Example scripts (e.g., `readmeDave.js` for README management, `todoDave.js` for task handling, `spawndave.js` for agent creation) are now organized in the `examples/` folder. These demonstrate specialized 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).
+Example scripts (e.g., `readme_agent.js` for README management, `todo_agent.js` for task handling, `spawn_agent.js` for agent creation) 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.js` (music agent), `codeDave.js` (code review), `npmDave.js` (NPM inspector).
+- **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
 
@@ -203,24 +351,24 @@ Benefits include seamless integration for dev sessions—agents stay online, han
 # Start the CodeServer (requires PM2: npm i -g pm2)
 ./examples/CodeServer 8080 mysecret
 
-# Connect via CLI (interactive or piped)
-npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:8080/ws --secret mysecret
+# Connect via CLI utility (interactive or piped)
+Utility: 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
 ```
 
 Monitor with `pm2 list` and stop via `pm2 delete <name>`.
 
-### Snippet: Spawning Agents (Portable via `bin/dave.js` --spawndave)
+### Snippet: Spawning Agents (Portable via `bin/dave.js` --spawn_agent)
 
-`spawndave` uses `AgentManager` to interactively generate new agent scripts, now fully aware of WebSocket server/client modes and the CodeServer multi-agent pattern for networked setups.
+`spawn_agent` uses `AgentManager` to interactively generate new agent scripts, now fully aware of WebSocket server/client modes and the CodeServer multi-agent pattern for networked setups.
 
-Now CodeServer-aware: Can generate PM2 multi-agent launchers (e.g., 'Generate CodeServer for coderev + todo'). See updated [examples/spawndave.js](examples/spawndave.js) and [docs/codeserver-pattern.md](docs/codeserver-pattern.md).
+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**: `spawndave` is fully portable—no local docs/examples needed. Uses online repo links (https://codeberg.org/duin/hello-dave). Works in any project via `npx` (auto-deps with `--cwd`).
+**Portable**: `spawn_agent` is fully portable—no local docs/examples needed. Uses online repo links (https://codeberg.org/duin/hello-dave). Works in any project via `npx` (auto-deps with `--cwd`).
 
 ```javascript
-// Core setup in spawndave
-const agent = new AgentManager({ name: 'spawn_dave', secret });
+// Core setup in spawn_agent
+const agent = new AgentManager({ name: 'spawn_agent', secret });
 agent.setup({
   prompt: 'You are AgentCreator... [detailed prompt for portability, validation]',
   api: 'xai',
@@ -231,6 +379,8 @@ agent.setup({
 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
 ```
@@ -242,13 +392,13 @@ await agent.start();  // Guides user to create e.g., bin/myagent.js
 
 ```bash
 # Interactive spawning (runs from npm without cloning; current dir)
-npx @j-o-r/hello-dave spawndave
+npx @j-o-r/hello-dave spawn_agent
 
 # Portable to specific project (auto-switches cwd, installs deps if needed)
-npx @j-o-r/hello-dave spawndave --cwd ~/my-proj
+npx @j-o-r/hello-dave spawn_agent --cwd ~/my-proj
 
 # Piped one-shot for CodeServer launcher (portable, no cloning)
-echo "Generate CodeServer launcher for coderev + tododave" | npx @j-o-r/hello-dave spawndave --cwd ~/proj
+echo "Generate CodeServer launcher for coderev + tododave" | npx @j-o-r/hello-dave spawn_agent --cwd ~/proj
 ```
 
 ### Snippet: Using xAI Grok API Integration
@@ -270,38 +420,48 @@ Detailed examples for xAI integration (e.g., advanced tool calls, reasoning) are
 ### Running Examples
 
 ```bash
-# Music agent (examples/daisy.js)
-chmod +x examples/daisy.js
-./examples/daisy.js "Generate lyrics for a pop song"
+# Music agent (examples/daisy_agent.js - full agent)
+chmod +x examples/daisy_agent.js
+./examples/daisy_agent.js "Generate lyrics for a pop song"
 
-# TODO manager (examples/todoDave.js)
-./examples/todoDave.js --connect ws://localhost:8080 --secret "secret"
+# TODO manager (examples/todo_agent.js - full agent)
+./examples/todo_agent.js --connect ws://localhost:8080 --secret "secret"
 
-# Server setup for networked examples
-npx @j-o-r/hello-dave dave --ask --serve 8080  # Expose as WS server
+# Server setup for networked examples (use full agents, not dave utility)
+./examples/npm_agent.js --serve 8080  # Expose as WS server
 ```
 
 ## Development
 
-- **Scripts**: `npm test` (runs scenarios/grok.js), `npm run types` (generate TypeScript defs), `npm run release` (pack for release).
+- **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.4**: Focus on spawnDave enhancements and release testing.
+- **Prep for v0.0.4**: Focus on spawn_agent enhancements and release testing.
 
 ## Changelog
 
-### v0.0.4 (Prep - March 2026)
+### v0.0.4 (Upcoming - 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.
-- TODO alignment: High-priority items noted (release prep, spawnDave enhancements).
 
-### v0.0.3 (Previous)
-- Initial WS secrets, generic tools, AgentManager refinements.
-
-Full history in git tags.
+Full history in git tags (recent: cleanup toolset test, TODO status update, fixed test/README, syntax fixes, startup modes explanation).
 
 ## Contributing
 
@@ -322,11 +482,11 @@ 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.4 Prep**: Changelog snippet added; release testing emphasized in Development.
-- **spawnDave Enhancements**: Highlighted in Examples with portability notes.
-- xAI integration tests/examples: Deferred to later (general enhancements).
-- Documentation tasks (e.g., AgentManager internals) integrated into Usage/Examples.
-- Deferred: Other xAI features to later; focus on core release and spawnDave.
+- **v0.0.4 Prep**: Changelog updated with recent completions; release steps emphasized (version bump, tests, types, commit/tag, publish).
+- **spawn_agent Enhancements**: Highlighted in Examples with portability and CodeServer awareness.
+- **Agent Standardization and Safeguards**: Integrated into Changelog and Usage notes.
+- xAI integration tests/examples: Deferred to post-v0.0.4 (future enhancements).
+- Documentation tasks (e.g., AgentManager internals, WS refinements) completed in Usage/Examples/Changelog.
+- **Status**: No high-priority pending; all tests stable. Focus shifted to release and future features like xAI files.js integration.
 
 For full TODO, see [TODO.md](TODO.md).
-