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

package/docs.bak.1774780058/agent-manager.md.bak2

@@ -1,157 +0,0 @@
-# AgentManager (`lib/AgentManager.js`)
-
-## Overview
-**AgentManager** is the central orchestrator class in the hello-dave framework. It manages agent lifecycle: setup (prompts, API, tools, sessions), execution modes (CLI, direct calls, WebSocket server/client), and tool integration. Designed for simplicity and extensibility, it abstracts LLM providers (`xai`, `gpt`, `claude`), `Prompt.js`, `ToolSet.js`, and `Session.js`.
-
-Key Features:
-- **Modes**: Interactive CLI, one-shot `directCall`, WS **server** (expose agent as tool), **client** (attach to remote server), hybrid (server + client).
-- **Tool Handling**: Pre-configured (`toolsetMode: 'auto'`/`'required'`), generics (`addGenericToolcall`), custom `ToolSet`.
-- **Persistence**: Sessions in `.cache/[name]/` (NDJSON logs).
-- **Networking**: WS with optional `secret` auth (base64-encoded).
-- **Validation**: Strict name regex `/^[a-z_0-9_]{2,}$/`.
-- **Events**: Leverages `Prompt` events (e.g., `reset` → server resetAll).
-
-Exports: `default AgentManager`.
-
-## Agent Naming Rules ⚠️
-**CRITICAL**: The `name` (constructor) and `toolName` (in `start()`) **MUST** match regex `/^[a-z_0-9_]{2,}$/`:
-- Lowercase `a-z`, digits `0-9`, `_` **only**.
-- **Minimum 2 characters**.
-
-**Valid ✅**:
-- `myagent`
-- `chatbot`
-- `weather_agent`
-- `tool123`
-- `ws_client`
-
-**Invalid ❌ (throws `Error`)**:
-- `MyAgent` (uppercase)
-- `agent-v1` (hyphen)
-- `a` (too short)
-- `agent#tool` (`#` invalid)
-- `Agent_` (uppercase)
-
-**Why?** Safe for folders, tool names, filesystems (no specials/caps/spaces).
-
-## Quick Usage
-```javascript
-import AgentManager from '../lib/AgentManager.js';  // or '@j-o-r/hello-dave'
-
-const agent = new AgentManager({ name: 'myagent', secret: 'mysecret' });
-agent.setup({
-  prompt: 'You are a helpful coding assistant.',
-  api: 'xai',
-  options: { model: 'grok-4-fast-reasoning' },
-  toolsetMode: 'auto',
-  contextWindow: 128000
-});
-agent.addGenericToolcall('execute_bash_script');
-
-await agent.start();  // CLI mode
-// Or: await agent.directCall('Write a Bash script');  // One-shot
-// Or: await agent.start(8000);  // WS server on port 8000
-```
-
-## Constructor Options
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `name` | string | `'agent'` | **Agent ID (session folder, tool name). MUST match `/^[a-z_0-9_]{2,}$/` (lowercase a-z0-9_; ≥2 chars).** |
-| `secret` | string | `''` | WS auth (base64-encoded; optional, match server/client). |
-| `cachePath` | string | `'.cache/hello-dave'` | Session storage root. |
-
-## setup(setup) → `this` (chainable)
-Configures the agent. Must call before `start()`/`directCall()`.
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `prompt` | string | - | **Required**: System prompt. |
-| `api` | `'xai'|'gpt'|'claude'` | `'gpt'` | LLM provider (uses `lib/API/[provider]/text.js`). |
-| `options` | `XAIOptions`/`OAOptions`/etc. | `{}` | Provider-specific (model, temperature, tools, reasoning). |
-| `contextWindow` | number | `300000` | Token limit for `Prompt`. |
-| `toolsetMode` | `'auto'|'required'` | `null` | `'auto'`: Generic tools; `'required'`: Empty `ToolSet` (add manually). |
-| `debug` | boolean | `false` | Verbose logging. |
-
-Internals: Creates `Prompt`, `Session`, sets `Prompt.setAdaptor(API.text[api], toolset, options)`.
-
-## Key Methods
-| Method | Args | Returns | Description |
-|--------|------|---------|-------------|
-| `directCall(input)` | `string` | `Promise<string>` | One-shot query (via `prompt.call()`). |
-| `getPrompt()` | - | `Prompt` | Access internal `Prompt`. |
-| `getToolset()` | - | `ToolSet\|void` | Access tools. |
-| `environment()` | - | `Promise<EnvironmentInfo>` | System info (via `fafs.js/env()`). |
-| `addGenericToolcall(name)` | string (e.g., `'read_file'`) | - | Copy from `genericToolset.js` pool. Post-setup only. |
-| `start(servePort?, connectUrl?, cliIntro?, toolName?, toolDesc?)` | Mixed | `Promise<void>` | **Smart launcher**:<br>- `servePort` (num): WS **server** (**toolName** MUST match name regex or auto-gen).<br>- `connectUrl` (str, e.g. `'ws://127.0.0.1:8000/ws'`): WS **client** (toolName/desc for attachment).<br>- Neither: **CLI** mode.<br>- Both: Hybrid. |
-
-## Workflow Diagram
-```mermaid
-graph TD
-    A[New AgentManager name, secret] --> B[setup prompt, api, options, toolsetMode]
-    B --> C{start args?}
-    C -->|servePort| D[enableServer port, name, desc<br/>+ optional attach client]
-    C -->|connectUrl| E[attach client url, name, desc]
-    C -->|none| F[startCli intro]
-    D --> G[Session Loop: Prompt → API/Tools → Response]
-    E --> G
-    F --> G
-    G --> H[directCall or persist]
-```
-
-**Per-Endpoint Options**:
-- **CLI**: `start()` → `Cli` (interactive/piped). Options via `setup`.
-- **WS Server**: `start(port)` → `AgentServer` (localhost only). Exposes agent as tool (name/desc). `secret` required for clients. `prompt.on('reset')` → `server.resetAll()`.
-- **WS Client**: `start(undefined, url)` → `AgentClient`. Connects to remote server; agent callable as tool.
-- **Direct**: `directCall()` bypasses networking/CLI.
-
-## Examples
-
-### 1. Interactive CLI Agent
-```javascript
-const agent = new AgentManager({ name: 'chatbot' });
-agent.setup({
-  prompt: 'You are a friendly chatbot.',
-  api: 'xai',
-  toolsetMode: 'auto'
-});
-await agent.start('Chatbot ready!');  // Auto-generates intro
-```
-
-### 2. WS Server (Expose as Tool)
-```javascript
-agent.setup({ ... });
-await agent.start(8000, undefined, undefined, 'weathertool', 'Get real-time weather');
-```
-- Clients: `npx @j-o-r/hello-dave dave --connect ws://localhost:8000/ws --secret mysecret`
-
-### 3. Hybrid + Direct Call
-```javascript
-await agent.start(8001, 'ws://other:8000/ws');  // Server on 8001 + client to other
-const resp = await agent.directCall('Hybrid query');  // Uses attached tools too
-```
-
-### 4. Custom Tools + Generics
-```javascript
-agent.setup({ toolsetMode: 'required' });
-const ts = agent.getToolset();
-ts.add('customMath', 'Add numbers', {
-  type: 'object', properties: {a: {type: 'number'}, b: {type: 'number'}},
-  required: ['a', 'b']
-}, async ({a, b}) => a + b);
-agent.addGenericToolcall('javascript_interpreter');
-```
-
-## Advanced: Networking & Secrets
-- **Server-Client Chain**: Server A attaches to Server B → A callable from B (and vice versa if mutual).
-- **Cron/CLI Messaging**: Pipe to client: `echo 'query' | npx ... dave --connect ...`
-- **Reset**: `Prompt` emits `'reset'` → propagates to attached servers/clients.
-
-## Errors
-- No `setup()`: Throws.
-- **Invalid `name`/`toolName`: Regex `/^[a-z_0-9_]{2,}$/` fail → `Error`.**
-- No `toolset` on server: Throws.
-
-See source `lib/AgentManager.js` for full JSDoc/types. Cross-links:
-- [Prompt](./prompt-class.md)
-- [ToolSet](./toolset.md)
-- [Generic Tools](../lib/genericToolset.js)

package/docs.bak.1774780058/codeserver-pattern.md

@@ -1,191 +0,0 @@
-# CodeServer Pattern
-
-[![PM2](https://img.shields.io/badge/PM2-Managed-green.svg)](https://pm2.keymetrics.io/) [![WebSocket](https://img.shields.io/badge/WebSocket-Persistent-blue.svg)](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
-
-## Table of Contents
-
-- [Introduction & Motivation](#introduction--motivation)
-- [Architecture](#architecture)
-- [Prerequisites](#prerequisites)
-- [Step-by-Step Setup](#step-by-step-setup)
-- [Interaction via \`bin/dave.js\`](#interaction-via-bindavejs)
-- [Monitoring & Stopping with PM2](#monitoring--stopping-with-pm2)
-- [Customization](#customization)
-- [Benefits](#benefits)
-- [Troubleshooting](#troubleshooting)
-- [Integration with AgentManager](#integration-with-agentmanager)
-- [References](#references)
-
-## Introduction & Motivation
-
-The **CodeServer pattern** demonstrates a production-ready setup for running a **persistent, always-on agent server** managed by [PM2](https://pm2.keymetrics.io/). It launches:
-
-- **Main Server**: \`code_agent.js\` as a WebSocket server (code-focused agent with JavaScript tools).
-- **Sub-Agents (Clients)**: Specialized agents (\`todo_agent.js\`, \`readme_agent.js\`, \`npm_agent.js\`, \`docs_agent.js\`) that **attach as tools** to the main server via WebSocket.
-
-**Motivation**:
-- **Persistence**: Long-running sessions without restarts (state in \`.cache/hello-dave/[agent]/\`).
-- **Delegation**: Main agent delegates to specialists (e.g., "update docs" → \`docsDave\` tool).
-- **No Heartbeats**: PM2 handles restarts, monitoring—no custom pings.
-- **Scalability**: Easy to add sub-agents, deploy across machines.
-- **CLI-Friendly**: Interact via \`bin/dave.js --connect\`.
-
-Ideal for dev workflows: code execution, docs mgmt, npm inspection, todos—all in one persistent hub.
-
-See live example: [examples/CodeServer](../examples/CodeServer)
-
-## Architecture
-
-```mermaid
-graph TB
-    PM2[PM2 Process Manager] --> Main[Main: code_agent.js<br/>--serve PORT --secret SECRET<br/>WS Server on /ws]
-    PM2 --> Todo[todo_agent.js<br/>--connect ws://localhost:PORT/ws<br/>tool: todo_agent]
-    PM2 --> Readme[readme_agent.js<br/>--connect ...<br/>tool: readme_agent]
-    PM2 --> NPM[npm_agent.js<br/>--connect ...<br/>tool: npm_module_inspector]
-    PM2 --> Docs[docs_agent.js<br/>--connect ...<br/>tool: agent_docs]
-
-    User[bin/dave.js --connect] -.-> Main
-    Main -->|Delegates via tools| Todo & Readme & NPM & Docs
-    Todo -.->|File ops| ProjectFiles[(TODO.md, etc.)]
-    Docs -.->|Docs mgmt| DocsFolder[./docs/*.md]
-```
-
-**Key Flows**:
-1. PM2 spawns all processes (named \`FOLDER_agent_PORT\`).
-2. Clients connect to main server → auto-register as **tools** (e.g., \`todo_agent\`, \`readme_agent\`).
-3. User queries main server → delegates (e.g., \`call todo_agent {add: "new task"}\`).
-4. Sessions persist independently per agent.
-
-## Prerequisites
-
-| Requirement | Install Command | Notes |
-|-------------|-----------------|-------|
-| **Node.js** | `node --version` (≥18) | ESM support required. |
-| **PM2** | `npm i -g pm2` | Process manager. Startup: `pm2 startup`. |
-| **Project** | `git clone <repo> && cd hello-dave` | Examples in \`./examples/\`. |
-
-Verify: `pm2 --version` & `node -e "import('@j-o-r/hello-dave')"`
-
-## Step-by-Step Setup
-
-1. **Navigate to project**:
-   ```bash
-   cd /path/to/hello-dave
-   ```
-
-2. **Launch CodeServer** (pick PORT 1024-65535, SECRET ≥3 chars):
-   ```bash
-   ./examples/CodeServer 8080 mysecret123
-   ```
-   Output:
-   ```
-   Starting CodeServer on port 8080 in folder 'hello-dave' ... with SECRET 'mysecret123'
-   CodeServer processes spawned with prefix 'hello-dave_' and suffix _8080.
-   dave --connect ws://127.0.0.1:8080/ws --secret 'mysecret123'
-   ```
-
-3. **Verify PM2**:
-   ```bash
-   pm2 list | grep 8080
-   ```
-   | Name                  | Status | CPU | Memory |
-   |-----------------------|--------|-----|--------|
-   | hello-dave_code_agent_8080 | online | ... | ... |
-   | hello-dave_todo_agent_8080 | online | ... | ... |
-   | ... (4 total)         | ...   | ... | ... |
-
-## Interaction via \`bin/dave.js\`
-
-**Interactive**:
-```bash
-./bin/dave.js --connect 'ws://localhost:8080/ws' --secret 'mysecret123'
-```
-- Chat with **code_agent** (main agent).
-- Delegates automatically: "Manage todos", "Inspect @j-o-r/cli", "Update docs/codeserver-pattern.md".
-
-**Piped (one-shot)**:
-```bash
-echo "List pending todos" | ./bin/dave.js --connect 'ws://localhost:8080/ws' --secret 'mysecret123'
-echo "user_reset" | ./bin/dave.js --connect ...  # Reset session
-```
-
-**Delegation Examples**:
-- \`code_agent\`: "Use todo_agent to add 'Review PRs'"
-- \`code_agent\`: "Call agent_docs to create nodejs-guide.md"
-
-## Monitoring & Stopping with PM2
-
-**Monitor**:
-- `pm2 list` / `pm2 monit` (dashboard)
-- `pm2 logs hello-dave_code_agent_8080` (agent logs)
-- `pm2 logs *8080 --lines 50`
-
-**Stop**:
-```bash
-pm2 stop hello-dave_*_8080  # All related
-# Or delete:
-pm2 delete hello-dave_code_agent_8080 hello-dave_todo_agent_8080 ...
-```
-
-**Startup** (auto-restart on boot): `pm2 save && pm2 startup`
-
-## Customization
-
-### Adding Sub-Agents
-Edit [examples/CodeServer](../examples/CodeServer):
-```bash
-# Add new agent
-pm2 start "${SCRIPT_DIR}/newAgent.js" --name "${FOLDER}_new_agent_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-```
-- Create \`newAgent.js\` like [examples/todo_agent.js](../examples/todo_agent.js): Set \`tool_call_name\`, prompt.
-
-### Changing Tools
-- Main server: Edit \`code_agent.js\`: \`--tools javascript,bash,ssh\`
-- Sub-agents: \`agent.addGenericToolcall('read_file')\` etc. See [toolset.md](../toolset.md).
-
-### Prompts/Models
-- Per-agent: Edit JS files (e.g., \`options.model = 'grok-4-1-fast-reasoning'\`).
-
-## Benefits
-
-| Feature | Advantage |
-|---------|-----------|
-| **Persistent Sessions** | State in \`.cache/hello-dave/[name]/sessions/\`—no re-explaining. |
-| **Delegation** | Main agent uses sub-agents as tools (parallel, specialized). |
-| **No Heartbeat** | PM2 restarts on crash; no custom logic. |
-| **Resource Efficient** | Shared context; subs only active on call. |
-| **Portable** | Script auto-prefixes PM2 names by folder/port. |
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| **Port in use** | Change PORT; `lsof -i :8080` & `kill`. |
-| **Secret mismatch** | Ensure exact match (no extra spaces). |
-| **PM2 not found** | `npm i -g pm2`. |
-| **Connection refused** | Wait 5s for server startup; check `pm2 logs`. |
-| **No delegation** | Verify client tool names in JS (e.g., \`todo_agent\`). |
-| **High memory** | `pm2 del *` or tweak \`contextWindow\`. |
-
-Logs: `.cache/hello-dave/[agent]/sessions/*.ndjson` (use \`bin/dave.js --inspect log.ndjson\`).
-
-## Integration with AgentManager
-
-Built on [AgentManager](../docs/agent-manager.md):
-
-- **Server**: `agent.start(PORT)` → WS server exposing \`code_agent\`.
-- **Clients**: `agent.start(undefined, 'ws://...', undefined, 'todo_agent', 'desc')` → Attaches as tool.
-
-**Tools**: Generic from [toolset.md](../docs/toolset.md) (e.g., \`execute_bash_script\`, \`javascript_interpreter\`).
-
-Cross-links:
-- [Prompt Class](../docs/prompt-class.md)
-- [Generic Tools](../lib/genericToolset.js)
-
-## References
-
-- [PM2 Docs](https://pm2.keymetrics.io/docs/usage/quick-start/)
-- Examples: [CodeServer](../examples/CodeServer), [code_agent.js](../examples/code_agent.js), [todo_agent.js](../examples/todo_agent.js), etc.
-- Sessions: \`bin/dave.js --list\`
-
-**Updated**: March 24, 2026

package/docs.bak.1774780058/path-resolution-best-practices.md

@@ -1,104 +0,0 @@
-# Path Resolution Best Practices for Generic Tools
-
-## Overview
-In `lib/genericToolset.js` and related tools (e.g., `syntax_check`, `write_file`), **path resolution** distinguishes between:
-- **Module-relative paths** (utils/scripts): Use `__dirname` for portability.
-- **User-provided file paths**: Resolve to `process.cwd()` (CWD sandbox) + strict validation.
-
-This ensures **sandboxing** (no escapes), **portability** (works from any CWD/PM2), and **security**. All tools enforce: no `/`, `..`, `\\\\`; `resolvedPath.startsWith(process.cwd())`.
-
-**ESM Setup** (genericToolset.js):
-```javascript
-const __dirname = path.dirname(fileURLToPath(import.meta.url));  // Polyfill for ESM
-```
-
-## __dirname vs process.cwd(): When to Use What
-
-| Context | Resolution | Example Code | Rationale |
-|---------|------------|--------------|-----------|
-| **Utils/Scripts** (e.g., syntax_check.sh, search_sessions.sh) | `__dirname` (module-rel) | `path.resolve(__dirname, '..', 'utils', 'syntax_check.sh')` | Portable: Locates utils/ from `lib/` regardless of CWD. Works in servers/clients. |
-| **User Files** (read/write/syntax/memory) | `process.cwd()` | `path.resolve(process.cwd(), params.file)` | Sandbox: Pins to project CWD (`~/devpri/js/hello-dave`). Prevents jailbreaks. |
-| **Cache/Memory** | `path.join(process.cwd(), '.cache/...')` | `.cache/hello-dave/memory.ndjson` | Per-project persistence. |
-| **Shebangs/Chmod** | Absolute (resolved) | `SH`chmod +x ${[resolvedPath]}` | Post-write on validated path. |
-
-**Universal Validation** (in read_file, write_file, syntax_check):
-```javascript
-const file = params.file?.trim();
-if (file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
-  throw new Error('Path must be relative within CWD only (no `/`, `..`, or `\\\\`).');
-}
-const resolvedPath = path.resolve(process.cwd(), file);
-if (!resolvedPath.startsWith(process.cwd())) {
-  throw new Error(`Path '${file}' escapes CWD scope.`);
-}
-```
-
-## syntax_check.sh Path Fix (User-Reported)
-
-**Issue** (Early Versions):
-- Relative paths passed to SH`` → Failed if CWD != lib/.
-- E.g., `SH`syntax_check.sh "rel/file.js"`` → "No such file" in sub-processes (PM2/CodeServer).
-
-**Fix** (Implemented):
-1. **Absolute Script Path**: `path.resolve(__dirname, '..', 'utils', 'syntax_check.sh')`.
-2. **Absolute File Arg**: `${syntaxChecker} "${resolvedPath}"` (resolvedPath = CWD-abs).
-3. **Script Handles Absolutes**: `FILE="$1"`; `head -n1 "$FILE"` works anywhere.
-
-**Test from Any CWD**:
-```bash
-cd /tmp
-/full/path/to/hello-dave/utils/syntax_check.sh /full/path/to/hello-dave/test.js  # ✅ JS OK
-# Or via tool: agent.directCall("syntax_check('test.js')")  # Resolves internally
-```
-
-**SH Best Practice**: Use array args `${[resolvedPath]}` → Auto-quotes/escapes paths with spaces.
-
-## Best Practices & Pitfalls
-
-### ✅ Do
-1. **Utils**: Always `__dirname, '..', 'utils', 'script.sh'` → Portable across deployments.
-2. **Files**: `process.cwd()` + validation → Sandboxed writes/reads.
-3. **SH Calls**: `SH`${script} ${[path]}`.run()` → Safe quoting via @j-o-r/sh.
-4. **Join vs Resolve**: `path.join(process.cwd(), '.cache')` for dirs; `resolve` for files.
-5. **ESM __dirname**: Polyfill with `fileURLToPath(import.meta.url)`.
-
-### ❌ Avoid
-1. `path.resolve(file)` → Assumes CWD; skips validation.
-2. `__dirname` for user files → Escapes to lib/ (security hole).
-3. Relative SH args → Breaks in non-lib CWD (e.g., WS clients).
-4. `process.chdir()` → Mutates global; use per-tool cwd.
-
-### Real-World Examples (from genericToolset.js)
-- **history_search**:
-  ```js
-  const history_search = path.resolve(__dirname, '..', 'utils', 'search_sessions.sh');
-  SH`${history_search} "${escapedQuery}"`.run();
-  ```
-- **syntax_check**:
-  ```js
-  const syntaxChecker = path.resolve(__dirname, '..', 'utils', 'syntax_check.sh');
-  return await SH`${syntaxChecker} "${resolvedPath}"`.run();
-  ```
-- **write_file** (AUTO-VALIDATE):
-  ```js
-  const syntaxChecker = path.resolve(__dirname, '..', 'utils', 'syntax_check.sh');
-  await SH`${syntaxChecker} ${[resolvedPath]}`.run();  // Throws on fail
-  ```
-
-## Troubleshooting
-| Issue | Cause | Fix |
-|-------|-------|-----|
-| "No such file: utils/script.sh" | Wrong CWD | Use `__dirname` for utils. |
-| "Path escapes CWD" | `..` in input | Input validation blocks. |
-| SH arg unescaped | Spaces/specials | Array `${[path]}` auto-handles. |
-| ESM no __dirname | Node <20 | Polyfill shown above. |
-
-**Pro Tip**: For custom tools, copy pattern: `__dirname` (utils), `process.cwd()` (files).
-
-## Cross-Links
-- [ToolSet](../toolset.md#generic-tools)
-- [Syntax Validation](../tools-syntax-validation.md)
-- [genericToolset.js](../lib/genericToolset.js) (grep "path.resolve")
-- Utils: [syntax_check.sh](../utils/syntax_check.sh)
-
-**Updated**: March 27, 2026 (syntax_check.sh path fix documented).

package/docs.bak.1774780058/project-overview.md

@@ -1,67 +0,0 @@
-# Hello-Dave Project Overview
-
-## Root Directory
-The root contains essential project configuration, documentation, and entry points:
-- **README.md**: Main project documentation and setup instructions.
-- **TODO.md**: Outstanding tasks and development notes.
-- **package.json**: NPM package metadata, dependencies, and scripts.
-- **LICENSE**: Project license (Apache 2.0).
-- **jsconfig.json** / **tsc.json**: TypeScript/JavaScript configuration for editor and compiler support.
-- **.gitignore** / **.npmignore**: Git and NPM ignore rules.
-- **workspace.js**: Development or workspace management script.
-- Directories: `bin/`, `docs/`, `examples/`, `lib/`, `scenarios/`, `types/`, `utils/`, `release/`, `node_modules/`, `.cache/` (for sessions).
-
-## bin/
-Executable CLI scripts (npm bin entries) for spawning and interacting with specialized \"Dave\" agents. These are user-facing tools for quick tasks:
-- `spawn_agent.js`: Generates and runs custom agent scripts.
-- `ask_agent.js`, `chat2Dave.js`: General interactive chat/query.
-- `code_agent.js`: Code-related agent.
-- `prompt_agent.js`, `docs_agent.js`: Prompt engineering and docs management.
-- `readme_agent.js`, `todo_agent.js`: Project maintenance (README/TODO).
-- `npm_agent.js`: NPM module inspection/publishing.
-- Others: `formatDave.js`, `clearDave.js`, `CodeServer`.
-
-## lib/
-Core library code (ESM modules) **named exports only** from `lib/index.js` (NO default export):
-- **index.js**: Main export barrel (`{ AgentManager, Prompt, ToolSet, ... }`).
-- **AgentManager.js**: Central orchestrator for agents—handles setup, sessions, tools, networking (WS server/client), and `start()` for CLI/server modes.
-- **Prompt.js**: Conversation manager (EventEmitter)—tracks messages, tools, truncation, token counting, provider adapters.
-- **ToolSet.js**: Defines/extends tools (JSON Schema + handlers) like bash execution, web search, JS interpreter.
-- **AgentServer.js**, **AgentClient.js**: WebSocket server/client for agent networking.
-- **Session.js**: Persistent chat history/logs (NDJSON in `.cache/`).
-- **Cli.js**: CLI input/output handling.
-- **genericToolset.js**: Pre-configured toolset with common tools.
-- **fafs.js**, **promptHelpers.js**: Utilities (env, file access, prompt ops).
-- **API/**: Provider-specific wrappers (subdirs):
-  - `anthropic.com/`: Claude API.
-  - `brave.com/`: Search API.
-  - `openai.com/`: GPT API.
-  - `x.ai/`: Grok/xAI API (responses, files, collections).
-
-## Agent Workflow
-An **Agent** (via `AgentManager`) is configured with:
-1. **System prompt** (via `Prompt.js`): Defines personality/task.
-2. **API provider** (from `lib/API/`): xAI/Grok, OpenAI/GPT, Anthropic/Claude.
-3. **ToolSet** (`ToolSet.js`): Custom/local functions (e.g., `execute_bash_script`, `web_search`); extensible.
-4. **Session**: Conversation history.
-
-Modes: Standalone CLI, one-shot query, WS **server** (expose as tool), **client** (attach to server), hybrid. `bin/spawn_agent.js` generates custom agents leveraging this.
-
-## docs/
-Project documentation (Markdown) ✅ **Complete** (reviewed Mar 24, 2026):
-- `project-overview.md`: This file.
-- `prompt-class.md`: Deep dive on `Prompt.js`.
-- `toolset.md`: `ToolSet.js` details + 9 generics.
-- `agent-manager.md`: **AgentManager** workflows, options, Mermaid diagrams.
-- `xai-responses.md`: xAI Responses API integration/examples.
-- `xai-collections.md`: xAI Collections (raw; Later priority).
-
-## Other Directories
-- **examples/**: Usage demos (e.g., `daisy_agent.js` music agent).
-- **scenarios/**: Tests/demos (e.g., `grok_agent.js`, `wsAgent.js`).
-- **types/**: TypeScript `.d.ts` files.
-- **utils/**: Miscellaneous utilities.
-- **release/**: NPM pack artifacts.
-
-## Summary
-`hello-dave` (@j-o-r/hello-dave NPM pkg) is a lightweight ESM Node.js framework for **tool-using AI agents** with unified LLM access (Grok/Claude/GPT), WS networking, and CLI tools. **Import via named exports: `import { AgentManager } from '@j-o-r/hello-dave';`**. Focus: Rapid prototyping of domain agents (code, docs, music) via `AgentManager` + `Prompt` + `ToolSet` + APIs. Sessions in `.cache/`. Node >=20.

package/docs.bak.1774780058/project-overview.md.bak

@@ -1,67 +0,0 @@
-# Hello-Dave Project Overview
-
-## Root Directory
-The root contains essential project configuration, documentation, and entry points:
-- **README.md**: Main project documentation and setup instructions.
-- **TODO.md**: Outstanding tasks and development notes.
-- **package.json**: NPM package metadata, dependencies, and scripts.
-- **LICENSE**: Project license (Apache 2.0).
-- **jsconfig.json** / **tsc.json**: TypeScript/JavaScript configuration for editor and compiler support.
-- **.gitignore** / **.npmignore**: Git and NPM ignore rules.
-- **workspace.js**: Development or workspace management script.
-- Directories: `bin/`, `docs/`, `examples/`, `lib/`, `scenarios/`, `types/`, `utils/`, `release/`, `node_modules/`, `.cache/` (for sessions).
-
-## bin/
-Executable CLI scripts (npm bin entries) for spawning and interacting with specialized \"Dave\" agents. These are user-facing tools for quick tasks:
-- `spawnDave.js`: Generates and runs custom agent scripts.
-- `ask_agent.js`, `chat2Dave.js`: General interactive chat/query.
-- `codeDave.js`: Code-related agent.
-- `prompt_agent.js`, `docsDave.js`: Prompt engineering and docs management.
-- `readmeDave.js`, `todoDave.js`: Project maintenance (README/TODO).
-- `npmDave.js`: NPM module inspection/publishing.
-- Others: `formatDave.js`, `clearDave.js`, `CodeServer`.
-
-## lib/
-Core library code (ESM modules) implementing the agent framework:
-- **index.js**: Main export barrel (AgentManager, Prompt, ToolSet, API wrappers, etc.).
-- **AgentManager.js**: Central orchestrator for agents—handles setup, sessions, tools, networking (WS server/client), and `start()` for CLI/server modes.
-- **Prompt.js**: Conversation manager (EventEmitter)—tracks messages, tools, truncation, token counting, provider adapters.
-- **ToolSet.js**: Defines/extends tools (JSON Schema + handlers) like bash execution, web search, JS interpreter.
-- **AgentServer.js**, **AgentClient.js**: WebSocket server/client for agent networking.
-- **Session.js**: Persistent chat history/logs (NDJSON in `.cache/`).
-- **Cli.js**: CLI input/output handling.
-- **genericToolset.js**: Pre-configured toolset with common tools.
-- **fafs.js**, **promptHelpers.js**: Utilities (env, file access, prompt ops).
-- **API/**: Provider-specific wrappers (subdirs):
-  - `anthropic.com/`: Claude API.
-  - `brave.com/`: Search API.
-  - `openai.com/`: GPT API.
-  - `x.ai/`: Grok/xAI API (responses, files, collections).
-
-## Agent Workflow
-An **Agent** (via `AgentManager`) is configured with:
-1. **System prompt** (via `Prompt.js`): Defines personality/task.
-2. **API provider** (from `lib/API/`): xAI/Grok, OpenAI/GPT, Anthropic/Claude.
-3. **ToolSet** (`ToolSet.js`): Custom/local functions (e.g., `execute_bash_script`, `web_search`); extensible.
-4. **Session**: Conversation history.
-
-Modes: Standalone CLI, one-shot query, WS **server** (expose as tool), **client** (attach to server), hybrid. `bin/spawnDave.js` generates custom agents leveraging this.
-
-## docs/
-Project documentation (Markdown) ✅ **Complete** (reviewed Mar 24, 2026):
-- `project-overview.md`: This file.
-- `prompt-class.md`: Deep dive on `Prompt.js`.
-- `toolset.md`: `ToolSet.js` details + 9 generics.
-- `agent-manager.md`: **AgentManager** workflows, options, Mermaid diagrams.
-- `xai-responses.md`: xAI Responses API integration/examples.
-- `xai-collections.md`: xAI Collections (raw; Later priority).
-
-## Other Directories
-- **examples/**: Usage demos (e.g., `daisy_agent.js` music agent).
-- **scenarios/**: Tests/demos (e.g., `grok_agent.js`, `wsAgent.js`).
-- **types/**: TypeScript `.d.ts` files.
-- **utils/**: Miscellaneous utilities.
-- **release/**: NPM pack artifacts.
-
-## Summary
-`hello-dave` (@j-o-r/hello-dave NPM pkg) is a lightweight ESM Node.js framework for **tool-using AI agents** with unified LLM access (Grok/Claude/GPT), WS networking, and CLI tools. Focus: Rapid prototyping of domain agents (code, docs, music) via `AgentManager` + `Prompt` + `ToolSet` + APIs. Sessions in `.cache/`. Node >=20."