network-ai 5.3.2 → 5.4.1

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.1 · MIT License · https://github.com/Jovancoding/Network-AI*

package/QUICKSTART.md

@@ -42,7 +42,8 @@ npx ts-node setup.ts --check
 | `a2a` | A2A | none | Agent-to-Agent protocol |
 | `codex` | Codex | `openai` | OpenAI Codex CLI |
 | `minimax` | MiniMax | none | MiniMax chat completions |
-| `nemoclaw` | NemoClaw | none | NVIDIA sandboxed agent execution |\n| `aps` | APS | none | Delegation-chain trust mapping |
+| `nemoclaw` | NemoClaw | none | NVIDIA sandboxed agent execution |
+| `aps` | APS | none | Delegation-chain trust mapping |
 | `copilot` | GitHub Copilot | none | Code generate/review/explain/fix/test/refactor |
 | `langgraph` | LangGraph | `@langchain/langgraph` | Compiled StateGraph execution |
 | `anthropic-computer-use` | Anthropic Computer Use | `@anthropic-ai/sdk` | Screenshot/click/type/scroll automation |
@@ -323,6 +324,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.2-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v5.4.1-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 |
 |---|---|---|
@@ -403,7 +403,7 @@ Extend `BaseAdapter` (or `StreamingBaseAdapter` for streaming) to add your own i
 
 | Capability | Network-AI | LangGraph | CrewAI | AutoGen |
 |---|---|---|---|---|
-| Cross-framework agents in one swarm | ✅ 28 built-in adapters | ⚠️ Nodes can call any code; no adapter abstraction | ⚠️ Extensible via tools; CrewAI-native agents only | ⚠️ Extensible via plugins; AutoGen-native agents only |
+| Cross-framework agents in one swarm | ✅ 29 built-in adapters | ⚠️ Nodes can call any code; no adapter abstraction | ⚠️ Extensible via tools; CrewAI-native agents only | ⚠️ Extensible via plugins; AutoGen-native agents only |
 | Atomic shared state (conflict-safe) | ✅ `propose → validate → commit` mutex | ⚠️ State passed between nodes; last-write-wins | ⚠️ Shared memory available; no conflict resolution | ⚠️ Shared context available; no conflict resolution |
 | Hard token ceiling per agent | ✅ `FederatedBudget` (first-class API) | ⚠️ Via callbacks / custom middleware | ⚠️ Via callbacks / custom middleware | ⚠️ Built-in token tracking in v0.4+; no swarm-level ceiling |
 | Permission gating before sensitive ops | ✅ `AuthGuardian` (built-in) | ⚠️ Possible via custom node logic | ⚠️ Possible via custom tools | ⚠️ Possible via custom middleware |
@@ -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

@@ -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

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 = (() => {
@@ -59,6 +60,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 +304,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

package/dist/bin/cli.js

@@ -49,6 +49,7 @@ const readline = __importStar(require("readline"));
 const locked_blackboard_1 = require("../lib/locked-blackboard");
 const index_1 = require("../index");
 const federated_budget_1 = require("../lib/federated-budget");
+const env_manager_1 = require("../lib/env-manager");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = (() => {
     try {
@@ -93,6 +94,7 @@ program
     .version(pkg.version, '-v, --version')
     .enablePositionalOptions()
     .addOption(new commander_1.Option('--data <path>', 'path to data directory').default('./data'))
+    .addOption(new commander_1.Option('--env <name>', 'target environment (dev|st|sit|qa|sandbox|preprod|prod)'))
     .addOption(new commander_1.Option('--json', 'output raw JSON (useful for piping)'));
 // ── bb (blackboard) ───────────────────────────────────────────────────────────
 const bb = program.command('bb').description('Blackboard operations');
@@ -333,6 +335,154 @@ auditCmd.command('clear')
     fs.writeFileSync(logFile, '');
     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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const mgr = new env_manager_1.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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const mgr = new env_manager_1.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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const mgr = new env_manager_1.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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const mgr = new env_manager_1.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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    const mgr = new env_manager_1.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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    if (!g.env)
+        die('--env <name> is required for backup create');
+    const mgr = new env_manager_1.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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    if (!g.env)
+        die('--env <name> is required for backup list');
+    const mgr = new env_manager_1.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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    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 env_manager_1.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, cmd) => {
+    const g = cmd.optsWithGlobals();
+    if (!g.env)
+        die('--env <name> is required for backup prune');
+    const mgr = new env_manager_1.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
 // subcommand was given, start the MCP server in stdio transport mode.