network-ai 4.3.0 → 4.3.1

package/INTEGRATION_GUIDE.md

@@ -457,6 +457,7 @@ Run these before declaring the integration production-ready:
 | Document | What It Covers |
 |----------|---------------|
 | [QUICKSTART.md](QUICKSTART.md) | Get running in 5 minutes |
+| [QUICKSTART.md § CLI](QUICKSTART.md) | CLI reference — bb, auth, budget, audit commands |
 | [references/adapter-system.md](references/adapter-system.md) | All 12 adapters with code examples |
 | [references/trust-levels.md](references/trust-levels.md) | Trust scoring formula and agent roles |
 | [references/auth-guardian.md](references/auth-guardian.md) | Permission system, justification scoring, token lifecycle |

package/QUICKSTART.md

@@ -215,7 +215,8 @@ export class MyFrameworkAdapter extends BaseAdapter {
 ```bash
 npx ts-node test-standalone.ts    # 79 core tests
 npx ts-node test-security.ts      # 33 security tests
-npx ts-node test-adapters.ts      # 100+ adapter tests (all 12 frameworks)
+npx ts-node test-adapters.ts      # 100+ adapter tests (all 14 frameworks)
+npx ts-node test-cli.ts           # 65 CLI tests
 ```
 
 ---
@@ -230,6 +231,95 @@ npx ts-node setup.ts --example    # Generate example.ts
 
 ---
 
+## 10. CLI
+
+Control Network-AI directly from the terminal — no server or running process required.  
+The CLI imports the same `LockedBlackboard`, `AuthGuardian`, and `FederatedBudget` core used everywhere else.
+
+### Install (global)
+
+```bash
+npm install -g network-ai
+network-ai --help
+```
+
+Or run from source without installing:
+
+```bash
+npx ts-node bin/cli.ts --help
+```
+
+### Blackboard (`bb`)
+
+```bash
+# Write / read / delete
+network-ai bb set agent:status running --agent orchestrator
+network-ai bb get agent:status
+network-ai bb delete agent:status
+
+# List all keys
+network-ai bb list
+
+# Snapshot (pretty-print full state)
+network-ai bb snapshot
+
+# Atomic propose → commit workflow
+network-ai bb propose agent:status complete --agent orchestrator   # prints changeId
+network-ai bb commit  <changeId>
+network-ai bb abort   <changeId>
+```
+
+### Auth (`auth`)
+
+```bash
+# Issue a permission token
+network-ai auth token my-bot --resource DATABASE --action read \
+  --justification "Need Q4 invoices for report"
+
+# Validate a token
+network-ai auth check grant_a1b2c3...
+
+# Revoke a token
+network-ai auth revoke grant_a1b2c3...
+```
+
+### Budget (`budget`)
+
+```bash
+# View current spend across all agents
+network-ai budget status
+
+# Set a new ceiling
+network-ai budget set-ceiling 50000
+```
+
+### Audit (`audit`)
+
+```bash
+# Print recent entries (last 50 by default)
+network-ai audit log --limit 50
+
+# Live-stream new entries as they arrive
+network-ai audit tail
+
+# Clear the log (irreversible)
+network-ai audit clear
+```
+
+### Global flags
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--data <path>` | `./data` | Override the data directory |
+| `--json` | off | Machine-readable JSON output on every command |
+
+```bash
+# Example: point at a non-default data dir and get JSON output
+network-ai --data /var/swarm/data --json bb list
+```
+
+---
+
 ## Architecture
 
 ```

package/README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v4.3.0-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v4.3.1-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
 [![npm](https://img.shields.io/npm/dw/network-ai.svg?label=npm%20downloads)](https://www.npmjs.com/package/network-ai)
 [![Tests](https://img.shields.io/badge/tests-1399%20passing-brightgreen.svg)](#testing)
 [![Adapters](https://img.shields.io/badge/frameworks-14%20supported-blueviolet.svg)](#adapter-system)
@@ -31,6 +31,7 @@ Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordinati
 **Use Network-AI as:**
 - A **TypeScript/Node.js library** — `import { createSwarmOrchestrator } from 'network-ai'`
 - An **MCP server** — `npx network-ai-server --port 3001`
+- A **CLI** — `network-ai bb get status` / `network-ai audit tail`
 - An **OpenClaw skill** — `clawhub install network-ai`
 
 [**5-minute quickstart →**](QUICKSTART.md)  |  [**Architecture →**](ARCHITECTURE.md)  |  [**All adapters →**](#adapter-system)  |  [**Benchmarks →**](BENCHMARKS.md)
@@ -164,6 +165,35 @@ Options: `--no-budget`, `--no-token`, `--no-control`, `--ceiling <n>`, `--board
 
 ---
 
+## CLI
+
+Control Network-AI directly from the terminal — no server required. The CLI imports the same core engine used by the MCP server.
+
+```bash
+# One-off commands (no server needed)
+npx ts-node bin/cli.ts bb set status running --agent cli
+npx ts-node bin/cli.ts bb get status
+npx ts-node bin/cli.ts bb snapshot
+
+# After npm install -g network-ai:
+network-ai bb list
+network-ai audit tail          # live-stream the audit log
+network-ai auth token my-bot --resource blackboard
+```
+
+| Command group | What it controls |
+|---|---|
+| `network-ai bb` | Blackboard — get, set, delete, list, snapshot, propose, commit, abort |
+| `network-ai auth` | AuthGuardian — issue tokens, revoke, check permissions |
+| `network-ai budget` | FederatedBudget — spend status, set ceiling |
+| `network-ai audit` | Audit log — print, live-tail, clear |
+
+Global flags on every command: `--data <path>` (data directory, default `./data`) · `--json` (machine-readable output)
+
+→ Full reference in [QUICKSTART.md § CLI](QUICKSTART.md)
+
+---
+
 ## Two agents, one shared state — without race conditions
 
 The real differentiator is coordination. Here is what no single-framework solution handles: two agents writing to the same resource concurrently, atomically, without corrupting each other.
@@ -288,9 +318,10 @@ npm run test:streaming    # Streaming adapters
 npm run test:a2a          # A2A protocol adapter
 npm run test:codex        # Codex adapter
 npm run test:priority     # Priority & preemption
+npm run test:cli          # CLI layer
 ```
 
-**1,334 passing assertions across 16 test suites** (`npm run test:all`):
+**1,399 passing assertions across 17 test suites** (`npm run test:all`):
 
 | Suite | Assertions | Covers |
 |---|---|---|
@@ -310,6 +341,7 @@ npm run test:priority     # Priority & preemption
 | `test-phase5b.ts` | 55 | Pluggable backend part 2, consistency levels |
 | `test-phase5.ts` | 42 | Named multi-blackboard base |
 | `test-security.ts` | 34 | Tokens, sanitization, rate limiting, encryption, audit |
+| `test-cli.ts` | 65 | CLI layer: bb, auth, budget, audit commands |
 
 ---
 
@@ -317,7 +349,7 @@ npm run test:priority     # Priority & preemption
 
 | Doc | Contents |
 |---|---|
-| [QUICKSTART.md](QUICKSTART.md) | Installation, first run, PowerShell guide, Python scripts CLI |
+| [QUICKSTART.md](QUICKSTART.md) | Installation, first run, CLI reference, PowerShell guide, Python scripts CLI |
 | [ARCHITECTURE.md](ARCHITECTURE.md) | Race condition problem, FSM design, handoff protocol, project structure |
 | [BENCHMARKS.md](BENCHMARKS.md) | Provider performance, rate limits, local GPU, `max_completion_tokens` guide |
 | [SECURITY.md](SECURITY.md) | Security module, permission system, trust levels, audit trail |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "AI agent orchestration framework for TypeScript/Node.js - 14 adapters (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, A2A, Codex + streaming variants). Built-in CLI, security, swarm intelligence, real-time streaming, and agentic workflow patterns.",
   "homepage": "https://github.com/jovanSAPFIONEER/Network-AI#readme",
   "main": "dist/index.js",