network-ai 5.3.1 → 5.4.0

package/INTEGRATION_GUIDE.md

@@ -305,6 +305,83 @@ Connect your AI model to `http://localhost:3001/sse` — it can now:
 
 ---
 
+### Phase 7 — Multi-Environment Promotion (v5.4.0+)
+
+**Goal:** Promote validated config from dev → staging → production through gate-enforced checkpoints.
+
+```bash
+# Initialise the full environment chain in one command
+npx network-ai env init --all
+
+# After validating in dev, promote config to st (auto-gate — no approval needed)
+npx network-ai env promote --from dev --to st
+
+# Review differences before promoting further
+npx network-ai env diff --from st --to sit
+
+# preprod requires a human confirmation
+npx network-ai env promote --from sit --to qa
+npx network-ai env promote --from qa --to preprod --confirmed-by "jane.doe"
+
+# prod requires an approval token
+npx network-ai env promote --from preprod --to prod --approved-by "security-board"
+```
+
+**Backup and rollback:**
+
+```bash
+# Create a named backup before a risky change
+npx network-ai env backup create --env prod
+
+# List available backups
+npx network-ai env backup list --env prod
+
+# Roll back to the latest backup
+npx network-ai env backup restore --env prod --latest
+```
+
+**From TypeScript:**
+
+```typescript
+import { EnvironmentManager } from 'network-ai';
+
+const mgr = new EnvironmentManager('.');
+await mgr.initAll();
+
+// Promote config files only (live state never promotes)
+const result = await mgr.promote('dev', 'st');
+console.log(result.copiedFiles);   // ['trust_levels.json', 'budget_ceilings.json']
+
+// Auto-backup destination before overwriting
+const backup = await mgr.backup('st');
+console.log(backup.id);            // '2026-05-10T12-00-00-000Z'
+
+// Diff two envs
+const diff = await mgr.diff('dev', 'prod');
+for (const f of diff.files) {
+  console.log(f.file, f.status, f.changedKeys);
+}
+```
+
+**Source protection** — lock agents inside `data/<env>/`:
+
+```typescript
+import { AgentRuntime, SandboxPolicy } from 'network-ai';
+
+const policy: SandboxPolicy = {
+  allowedCommands: [],
+  allowedPaths: ['data/dev/'],
+  sourceProtection: true,
+  env: 'dev',
+};
+
+const runtime = new AgentRuntime({ policy });
+```
+
+Any `FileAccessor.read/write/list` call outside `data/dev/` will throw `SourceProtectionError` and be caught as `{ success: false, error: '...' }`.
+
+---
+
 ## 5. Enterprise Concerns
 
 ### Authentication & IAM
@@ -419,7 +496,7 @@ Run these before declaring the integration production-ready:
 - [ ] `npx ts-node test-phase4.ts` — 147 behavioral tests pass
 - [ ] `npx ts-node test-qa.ts` — 67 QA orchestrator tests pass
 - [ ] `npx ts-node test-phase7.ts` — 94 Phase 7 tests pass (hooks, flow control, composer, semantic search)
-- [ ] `npm run test:all` — all 2,711 tests pass across 26 suites
+- [ ] `npm run test:all` — all 2,976 tests pass across 29 suites
 - [ ] `npm run demo -- --08` runs to completion in < 10 seconds
 
 ### Race Condition Safety
@@ -477,7 +554,7 @@ Run these before declaring the integration production-ready:
 |----------|---------------|
 | [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 28 adapters with code examples |
+| [references/adapter-system.md](references/adapter-system.md) | All 29 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 |
 | [references/blackboard-schema.md](references/blackboard-schema.md) | Blackboard key conventions and namespacing |
@@ -487,4 +564,4 @@ Run these before declaring the integration production-ready:
 
 ---
 
-*Network-AI v5.1.4 · MIT License · https://github.com/Jovancoding/Network-AI*
+*Network-AI v5.4.0 · MIT License · https://github.com/Jovancoding/Network-AI*

package/QUICKSTART.md

@@ -323,6 +323,46 @@ network-ai auth check grant_a1b2c3...
 network-ai auth revoke grant_a1b2c3...
 ```
 
+### Multi-Environment (`env`) — v5.4.0+
+
+Isolate agent state across dev / staging / production using the promotion chain.
+
+```bash
+# Initialise all environments at once
+network-ai env init --all
+
+# Or initialise a single environment
+network-ai env init --env dev
+
+# List environments and key counts
+network-ai env list
+
+# Show the promotion chain
+network-ai env chain
+
+# Diff two environments (shows +added / -removed / ~changed config keys)
+network-ai env diff --from dev --to prod
+
+# Promote config from dev → st (auto-gate, no approval needed)
+network-ai env promote --from dev --to st
+
+# Promote to preprod (requires --confirmed-by)
+network-ai env promote --from qa --to preprod --confirmed-by "jane.doe"
+
+# Promote to prod (requires --approved-by)
+network-ai env promote --from preprod --to prod --approved-by "security-board"
+
+# Backup / restore
+network-ai env backup create --env prod
+network-ai env backup list   --env prod
+network-ai env backup restore --env prod --latest
+network-ai env backup prune  --env prod --keep 5
+```
+
+Set `NETWORK_AI_ENV=dev` to automatically route all blackboard and Python script operations to `data/dev/`.
+
+---
+
 ### Budget (`budget`)
 
 ```bash

package/README.md

@@ -5,9 +5,9 @@
 [![Website](https://img.shields.io/badge/website-network--ai.org-4b9df2?style=flat&logo=web&logoColor=white)](https://network-ai.org/)
 [![CI](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v5.3.1-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v5.4.0-blue.svg)](https://github.com/Jovancoding/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-2899%20passing-brightgreen.svg)](#testing)
+[![Tests](https://img.shields.io/badge/tests-2976%20passing-brightgreen.svg)](#testing)
 [![Adapters](https://img.shields.io/badge/frameworks-29%20supported-blueviolet.svg)](#adapter-system)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![Socket](https://socket.dev/api/badge/npm/package/network-ai)](https://socket.dev/npm/package/network-ai/overview)
@@ -354,7 +354,7 @@ npx ts-node examples/10-nemoclaw-sandbox-swarm.ts
 
 ## Adapter System
 
-28 adapters, zero adapter dependencies. You bring your own SDK objects.
+29 adapters, zero adapter dependencies. You bring your own SDK objects.
 
 | Adapter | Framework / Protocol | Register method |
 |---|---|---|
@@ -419,7 +419,7 @@ Extend `BaseAdapter` (or `StreamingBaseAdapter` for streaming) to add your own i
 npm run test:all          # All suites in sequence
 npm test                  # Core orchestrator
 npm run test:security     # Security module
-npm run test:adapters     # All 28 adapters
+npm run test:adapters     # All 29 adapters
 npm run test:streaming    # Streaming adapters
 npm run test:a2a          # A2A protocol adapter
 npm run test:codex        # Codex adapter
@@ -429,7 +429,7 @@ npm run test:phase9       # Agent runtime, console, strategy agent
 npm run test:phase12      # Context Throttler, Partition Planner, Coverage Gate, Route Classifier
 ```
 
-**2,899 passing assertions across 28 test suites** (`npm run test:all`):
+**2,976 passing assertions across 29 test suites** (`npm run test:all`):
 
 | Suite | Assertions | Covers |
 |---|---|---|
@@ -437,7 +437,7 @@ npm run test:phase12      # Context Throttler, Partition Planner, Coverage Gate,
 | `test-phase5f.ts` | 127 | SSE transport, `McpCombinedBridge`, extended MCP tools |
 | `test-phase5g.ts` | 121 | CRDT backend, vector clocks, bidirectional sync |
 | `test-phase6.ts` | 121 | MCP server, control-plane tools, audit tools |
-| `test-adapters.ts` | 218 | All 28 adapters, registry routing, integration, edge cases |
+| `test-adapters.ts` | 218 | All 29 adapters, registry routing, integration, edge cases |
 | `test-phase5d.ts` | 117 | Pluggable backend (Redis, CRDT, Memory) |
 | `test-standalone.ts` | 88 | Blackboard, auth, integration, persistence, parallelisation, quality gate |
 | `test-phase5e.ts` | 87 | Federated budget tracking |
@@ -460,6 +460,7 @@ npm run test:phase12      # Context Throttler, Partition Planner, Coverage Gate,
 | `test-topology.ts` | 304 | WorkTree, ControlPlane, dashboard server, topology visualization, WebSocket protocol |
 | `test-rlm-phases.ts` | 123 | FederatedBudget child spending, blackboard metadata API, best-partial result, HookContext depth, sub-goal recursion, semaphore fan-out, PhasePipeline compaction, RLMAdapter end-to-end |
 | `test-phase12.ts` | 65 | Context Throttler, Partition Planner, Coverage Gate, Route Classifier, EVALUATING FSM state, runTeam integration |
+| `test-env-manager.ts` | 77 | Multi-environment isolation, promotion chain, backup/restore, source protection, NETWORK_AI_ENV, blackboard env routing |
 | `test.ts` | 39 | Core orchestrator smoke tests |
 
 ---
@@ -476,7 +477,7 @@ npm run test:phase12      # Context Throttler, Partition Planner, Coverage Gate,
 | [AUDIT_LOG_SCHEMA.md](AUDIT_LOG_SCHEMA.md) | Audit log field reference, all event types, scoring formula |
 | [ADOPTERS.md](ADOPTERS.md) | Known adopters — open a PR to add yourself |
 | [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) | End-to-end integration walkthrough with v5.0 modules |
-| [references/adapter-system.md](references/adapter-system.md) | Adapter architecture, all 28 adapters, writing custom adapters |
+| [references/adapter-system.md](references/adapter-system.md) | Adapter architecture, all 29 adapters, writing custom adapters |
 | [references/auth-guardian.md](references/auth-guardian.md) | Permission scoring, resource types, IAuthValidator interface |
 | [references/trust-levels.md](references/trust-levels.md) | Trust level configuration, APS delegation-chain mapping |
 

package/SKILL.md

@@ -34,7 +34,7 @@ metadata:
 
 > **Advisory tokens notice:** Grant tokens issued by `check_permission.py` are **advisory scoring outputs only** — the caller-supplied `--agent` identity is not cryptographically verified. Downstream systems must not treat these tokens as authenticated credentials without adding a separate identity-verification step or human approval gate, especially for PAYMENTS, DATABASE, and FILE_EXPORT resources.
 
-> **Data-flow notice (host platform — not this skill):** This skill does NOT implement, invoke, or control `sessions_send`. That is a host-platform built-in (OpenClaw runtime). The orchestration instructions below describe *when* to call the platform’s `sessions_send` after budget checks pass — but the actual network call, model endpoint, and data transmission are entirely the **host platform’s** responsibility. If you need to prevent external network calls, disable or reroute `sessions_send` in your **platform settings** before installing this skill. This skill has no access to that configuration.
+> **Data-flow notice (host platform — not this skill):** This skill does NOT implement, invoke, or control `sessions_send` or any inter-agent messaging. All bundled Python scripts are local-only tools (budget guard, blackboard, permission scorer, context manager). If your platform has a `sessions_send` built-in, whether and how it is used is entirely the **host platform’s** responsibility and is outside this skill’s scope. If you need to prevent external network calls, disable or reroute delegation in your **platform settings** before installing this skill.
 
 > **Context file integrity:** The `context_manager.py inject` command now validates `data/project-context.json` for injection patterns and oversized fields before printing the context block. Review any warnings printed to stderr before passing the output to an agent system prompt.
 
@@ -60,6 +60,14 @@ pip install filelock  # only needed if you see locking issues on Windows
 
 The `data/` directory is created automatically on first run. No configuration files, environment variables, or credentials are required.
 
+> **Multi-environment support (v5.4.0):** All five Python scripts now read the `NETWORK_AI_ENV` environment variable at startup and accept a `--env <name>` CLI argument. When set, all data paths are routed to `data/<env>/` instead of the root `data/` directory. Use this to isolate dev, staging, and production state.
+>
+> ```bash
+> # Run against the dev environment
+> NETWORK_AI_ENV=dev python3 scripts/blackboard.py list
+> python3 scripts/check_permission.py --active-grants --env dev
+> ```
+
 Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.
 
 ## 🎯 Orchestrator System Instructions
@@ -117,12 +125,12 @@ Sub-Task 3 (RECOMMEND): [strategy_advisor]
   - Output: Recommendations with rationale
 ```
 
-### Budget-Aware Handoff Protocol
+### Budget Check Protocol
 
-**CRITICAL:** Before EVERY `sessions_send`, call the handoff interceptor:
+**Run the budget interceptor before any task delegation:**
 
 ```bash
-# ALWAYS run this BEFORE sessions_send
+# Run this before delegating to any sub-agent
 python {baseDir}/scripts/swarm_guard.py intercept-handoff \
   --task-id "task_001" \
   --from orchestrator \
@@ -133,10 +141,10 @@ python {baseDir}/scripts/swarm_guard.py intercept-handoff \
 **Decision Logic:**
 ```
 IF result.allowed == true:
-    → Proceed with sessions_send
+    → Budget check passed — proceed with the delegated task
     → Note tokens_spent and remaining_budget
 ELSE:
-    → STOP - Do NOT call sessions_send
+    → STOP — budget exceeded or handoff limit reached
     → Report blocked reason to user
     → Consider: reduce scope or abort task
 ```
@@ -273,11 +281,10 @@ python {baseDir}/scripts/swarm_guard.py budget-init \
   --description "Q4 Financial Analysis"
 ```
 
-### 2. Delegate a Task to Another Session
+### 2. Check Budget Before Task Delegation
 
-> **Platform note:** `sessions_list`, `sessions_send`, and `sessions_history` are **OpenClaw host platform built-ins** — they are part of the OpenClaw runtime, not provided or invoked by this skill's Python scripts. This skill only runs local `python scripts/*.py` commands. The guidance below describes how to combine the platform's session tools with this skill's budget guard.
 
-First check budget, then use the OpenClaw platform operation:
+Always run the budget guard before delegating any task:
 
 ```bash
 # 1. Check budget (this skill's Python script)
@@ -285,17 +292,8 @@ python {baseDir}/scripts/swarm_guard.py intercept-handoff \
   --task-id "task_001" --from orchestrator --to data_analyst \
   --message "Analyze Q4 revenue data"
 
-# 2. If allowed, delegate using the OpenClaw platform tool (not this skill):
-#    sessions_list    → see available sessions/agents
-#    sessions_send    → send task to another session
-#    sessions_history → check results from delegated work
-```
-
-**Example delegation prompt:**
-```
-After running swarm_guard.py intercept-handoff and getting result.allowed == true,
-use the OpenClaw sessions_send platform tool to ask the data_analyst session:
-"Analyze Q4 revenue trends from the SAP export data and summarize key insights"
+# 2. If result.allowed == true, proceed with delegation via your platform's built-in tools.
+# If result.allowed == false, stop — budget exceeded or handoff limit reached.
 ```
 
 ### 3. Check Permission Before API Access
@@ -330,7 +328,7 @@ python {baseDir}/scripts/blackboard.py list
 
 ## Agent-to-Agent Handoff Protocol
 
-When delegating tasks between agents/sessions:
+When delegating tasks between agents, always run the budget guard first.
 
 ### Step 1: Initialize Budget & Check Capacity
 ```bash
@@ -343,12 +341,6 @@ python {baseDir}/scripts/swarm_guard.py budget-check --task-id "task_001"
 
 ### Step 2: Identify Target Agent
 
-> **Platform note:** `sessions_list` is an **OpenClaw host platform built-in**, not provided by this skill.
-
-```
-sessions_list  # OpenClaw platform operation — find available agents
-```
-
 Common agent types:
 | Agent | Specialty |
 |-------|-----------|
@@ -357,10 +349,10 @@ Common agent types:
 | `risk_assessor` | Risk analysis, compliance checks |
 | `orchestrator` | Coordination, task decomposition |
 
-### Step 3: Intercept Before Handoff (REQUIRED)
+### Step 3: Run Budget Guard Before Delegation
 
 ```bash
-# This checks budget AND handoff limits before allowing the call
+# Check budget AND handoff limits before delegating
 python {baseDir}/scripts/swarm_guard.py intercept-handoff \
   --task-id "task_001" \
   --from orchestrator \
@@ -369,8 +361,8 @@ python {baseDir}/scripts/swarm_guard.py intercept-handoff \
   --artifact  # Include if expecting output
 ```
 
-**If ALLOWED:** Proceed to Step 4
-**If BLOCKED:** Stop - do not call sessions_send
+**If ALLOWED:** Proceed with delegation via your platform's own tools
+**If BLOCKED:** Stop — budget exceeded or handoff limit reached; do not delegate
 
 ### Step 4: Construct Handoff Message
 
@@ -380,38 +372,25 @@ Include these fields in your delegation:
 - **constraints**: Any limitations or requirements
 - **expectedOutput**: What format/content you need back
 
-### Step 5: Send via OpenClaw Platform Session Tool
+### Step 5: Check Results
 
-> **Platform note:** `sessions_send` is an **OpenClaw host platform built-in** — it is NOT implemented by this skill. This skill only provides the budget guard (`swarm_guard.py`) that must be run first.
+After delegation completes, read results from the blackboard:
 
+```bash
+python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"
 ```
-# OpenClaw platform operation (not this skill):
-sessions_send to data_analyst:
-"[HANDOFF]
-Instruction: Analyze Q4 revenue by product category
-Context: Using SAP export from ./data/q4_export.csv
-Constraints: Focus on top 5 categories only
-Expected Output: JSON summary with category, revenue, growth_pct
-[/HANDOFF]"
-```
-
-### Step 6: Check Results
 
-> **Platform note:** `sessions_history` is an **OpenClaw host platform built-in**, not provided by this skill.
+## Permission Scoring
 
-```
-sessions_history data_analyst  # OpenClaw platform operation — get the response
-```
+> **Tokens are audit scoring outputs only.** Grant tokens from `check_permission.py` are NOT authenticated credentials and must NOT be used as real access control. They are advisory hints based on a local scoring model. Require a separate authenticated identity and explicit human approval before accessing PAYMENTS, DATABASE, or FILE_EXPORT resources.
 
-## Permission Wall
+**Always score permission before accessing:**
+- `DATABASE` — Internal database / data store (abstract label — no external credentials)
+- `PAYMENTS` — Financial/payment data services (abstract label — requires `--confirm-high-risk`)
+- `EMAIL` — Email sending capability (abstract label)
+- `FILE_EXPORT` — Exporting data to local files (abstract label — requires `--confirm-high-risk`)
 
-**CRITICAL**: Always check permissions before accessing:
-- `DATABASE` - Internal database / data store access
-- `PAYMENTS` - Financial/payment data services
-- `EMAIL` - Email sending capability
-- `FILE_EXPORT` - Exporting data to local files
-
-> **Note**: These are abstract local resource type names used by `check_permission.py`. No external API credentials are required or used — all permission evaluation runs locally.
+> **Note**: These are abstract local resource type names used by `check_permission.py`. No external API credentials are required or used — all evaluation runs locally.
 
 ### Permission Evaluation Criteria
 
@@ -507,16 +486,14 @@ Sequential processing - output of one feeds into next.
 
 ### Example Parallel Workflow
 
-> **Platform note:** `sessions_send` and `sessions_history` are **OpenClaw host platform built-ins**, not provided by this skill. This skill provides only the `swarm_guard.py` budget/handoff check that runs before each delegation.
-
 ```
-# For each delegation below, first run:
+# For each delegation below, first run the budget guard:
 #   python {baseDir}/scripts/swarm_guard.py intercept-handoff --task-id "task_001" --from orchestrator --to <agent> --message "<task>"
-# Then, if allowed, use the OpenClaw platform tool:
-1. sessions_send to data_analyst: "Extract key metrics from Q4 data"
-2. sessions_send to risk_assessor: "Identify compliance risks in Q4 data"
-3. sessions_send to strategy_advisor: "Recommend actions based on Q4 trends"
-4. Wait for all responses via sessions_history
+# If result.allowed == true, delegate via your platform's own tools.
+1. Delegate to data_analyst: "Extract key metrics from Q4 data"
+2. Delegate to risk_assessor: "Identify compliance risks in Q4 data"
+3. Delegate to strategy_advisor: "Recommend actions based on Q4 trends"
+4. Wait for all results and read them from the blackboard
 5. Synthesize: Combine metrics + risks + recommendations into executive summary
 ```
 

package/bin/cli.ts

@@ -16,6 +16,7 @@ import * as readline from 'readline';
 import { LockedBlackboard } from '../lib/locked-blackboard';
 import { AuthGuardian } from '../index';
 import { FederatedBudget } from '../lib/federated-budget';
+import { EnvironmentManager } from '../lib/env-manager';
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = (() => {
@@ -30,6 +31,12 @@ function resolveData(opts: { data?: string }): string {
   return path.resolve(opts.data ?? path.join(process.cwd(), 'data'));
 }
 
+function resolveEnvData(opts: { data?: string; env?: string }): string {
+  const base = resolveData(opts);
+  if (opts.env) return path.join(base, opts.env);
+  return base;
+}
+
 function print(obj: unknown, asJson: boolean): void {
   if (asJson) {
     console.log(JSON.stringify(obj, null, 2));
@@ -59,6 +66,7 @@ program
   .version(pkg.version, '-v, --version')
   .enablePositionalOptions()
   .addOption(new Option('--data <path>', 'path to data directory').default('./data'))
+  .addOption(new Option('--env <name>', 'target environment (dev|st|sit|qa|sandbox|preprod|prod)'))
   .addOption(new Option('--json', 'output raw JSON (useful for piping)'));
 
 // ── bb (blackboard) ───────────────────────────────────────────────────────────
@@ -302,6 +310,153 @@ auditCmd.command('clear')
     print(g.json ? { cleared: logFile } : `✓ cleared ${logFile}`, g.json);
   });
 
+// ── env (environment management) ──────────────────────────────────────────────
+
+const envCmd = program.command('env').description('Multi-environment management (isolation, promotion, backup)');
+
+envCmd.command('init')
+  .description('Scaffold an environment data directory (all 7 envs if no --env given)')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; env?: string; json: boolean }>();
+    const mgr = new EnvironmentManager(resolveData(g));
+    if (g.env) {
+      mgr.init(g.env);
+      print(g.json ? { initialized: g.env } : `✓ initialized env '${g.env}'`, g.json);
+    } else {
+      mgr.initAll();
+      print(g.json ? { initialized: mgr.getChain().concat(['sandbox']) } : `✓ all environments initialized`, g.json);
+    }
+  });
+
+envCmd.command('list')
+  .description('List all environments with existence and key count')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; env?: string; json: boolean }>();
+    const mgr = new EnvironmentManager(resolveData(g));
+    const envs = mgr.list();
+    if (g.json) {
+      print(envs, true);
+    } else {
+      const lines = envs.map(e => `${e.name.padEnd(10)} ${e.exists ? '✓' : '✗'} (${e.keyCount} keys)`);
+      console.log(lines.join('\n'));
+    }
+  });
+
+envCmd.command('chain')
+  .description('Show the configured promotion chain')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const mgr = new EnvironmentManager(resolveData(g));
+    const chain = mgr.getChain();
+    print(g.json ? chain : chain.join(' → '), g.json);
+  });
+
+envCmd.command('diff')
+  .description('Compare config artefacts between two environments')
+  .requiredOption('--from <env>', 'source environment')
+  .requiredOption('--to <env>', 'target environment')
+  .action((opts: { from: string; to: string }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const mgr = new EnvironmentManager(resolveData(g));
+    const result = mgr.diff(opts.from, opts.to);
+    if (g.json) {
+      print(result, true);
+    } else if (result.differences.length === 0) {
+      console.log(`No differences between '${opts.from}' and '${opts.to}'`);
+    } else {
+      for (const d of result.differences) {
+        const sym = d.status === 'added' ? '+' : d.status === 'removed' ? '-' : '~';
+        console.log(`  ${sym} ${d.file} (${d.status})`);
+      }
+    }
+  });
+
+envCmd.command('promote')
+  .description('Promote config artefacts one step up the chain')
+  .requiredOption('--from <env>', 'source environment')
+  .requiredOption('--to <env>', 'target environment')
+  .option('--confirmed-by <name>', 'required for preprod gate')
+  .option('--approved-by <name>', 'required for prod gate')
+  .action((opts: { from: string; to: string; confirmedBy?: string; approvedBy?: string }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const mgr = new EnvironmentManager(resolveData(g));
+    try {
+      const result = mgr.promote(opts.from, opts.to, {
+        confirmedBy: opts.confirmedBy,
+        approvedBy: opts.approvedBy,
+      });
+      print(g.json ? result : `✓ promoted ${opts.from} → ${opts.to} (${result.configsCopied.length} configs copied)`, g.json);
+    } catch (err) {
+      die(err instanceof Error ? err.message : String(err));
+    }
+  });
+
+// ── env backup subcommand group ───────────────────────────────────────────────
+
+const envBackup = envCmd.command('backup').description('Backup management for an environment');
+
+envBackup.command('create')
+  .description('Create a backup of the environment data directory (alias: network-ai env backup)')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; env?: string; json: boolean }>();
+    if (!g.env) die('--env <name> is required for backup create');
+    const mgr = new EnvironmentManager(resolveData(g));
+    const result = mgr.backup(g.env);
+    print(g.json ? result : `✓ backup created: ${result.backupId} (${result.filesCount} files)`, g.json);
+  });
+
+envBackup.command('list')
+  .description('List available backups for an environment')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; env?: string; json: boolean }>();
+    if (!g.env) die('--env <name> is required for backup list');
+    const mgr = new EnvironmentManager(resolveData(g));
+    const backups = mgr.listBackups(g.env);
+    if (g.json) {
+      print(backups, true);
+    } else if (backups.length === 0) {
+      console.log('(no backups)');
+    } else {
+      for (const b of backups) {
+        console.log(`  ${b.backupId}  ${b.timestamp}  ${(b.sizeBytes / 1024).toFixed(1)} KB`);
+      }
+    }
+  });
+
+envBackup.command('restore')
+  .description('Restore an environment from a backup')
+  .option('--backup <id>', 'backup ID to restore')
+  .option('--latest', 'restore the most recent backup')
+  .action((opts: { backup?: string; latest?: boolean }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; env?: string; json: boolean }>();
+    if (!g.env) die('--env <name> is required for backup restore');
+    if (!opts.backup && !opts.latest) die('provide --backup <id> or --latest');
+    const mgr = new EnvironmentManager(resolveData(g));
+    let backupId = opts.backup;
+    if (opts.latest) {
+      const backups = mgr.listBackups(g.env);
+      if (backups.length === 0) die(`no backups found for env '${g.env}'`);
+      backupId = backups[0].backupId;
+    }
+    try {
+      const result = mgr.restore(g.env, backupId!);
+      print(g.json ? result : `✓ restored ${result.filesRestored} files from backup '${result.backupId}'`, g.json);
+    } catch (err) {
+      die(err instanceof Error ? err.message : String(err));
+    }
+  });
+
+envBackup.command('prune')
+  .description('Remove old backups, keeping the N most recent')
+  .requiredOption('--keep <n>', 'number of backups to retain', (v) => parseInt(v, 10))
+  .action((opts: { keep: number }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; env?: string; json: boolean }>();
+    if (!g.env) die('--env <name> is required for backup prune');
+    const mgr = new EnvironmentManager(resolveData(g));
+    const deleted = mgr.pruneBackups(g.env, opts.keep);
+    print(g.json ? { deleted } : `✓ pruned ${deleted} backup(s), keeping ${opts.keep}`, g.json);
+  });
+
 // ── parse ─────────────────────────────────────────────────────────────────────
 
 // Auto-detect MCP stdio mode: when stdin is piped (not a TTY) and no