typescript-virtual-container 1.2.4 → 1.2.6

package/README.md

@@ -1,6 +1,6 @@
 # `typescript-virtual-container`
 
-> Scalable SSH/SFTP server with a virtual filesystem and typed programmatic API for testing, automation, and interactive shell scripting in TypeScript/JavaScript.
+> Pure in-memory SSH/SFTP server with a virtual filesystem, a real shell interpreter, and a typed programmatic API for testing, automation, honeypots, and interactive shell scripting in TypeScript/JavaScript.
 
 [![npm version](https://badge.fury.io/js/typescript-virtual-container.svg)](https://www.npmjs.com/package/typescript-virtual-container)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -17,14 +17,22 @@
 - [Quick Start](#quick-start)
 - [Architecture Overview](#architecture-overview)
 - [API Reference](#api-reference)
+  - [VirtualSshServer](#virtualsshserver)
+  - [VirtualSftpServer](#virtualsftpserver)
+  - [VirtualShell](#virtualshell)
+  - [VirtualFileSystem](#virtualfilesystem)
+  - [VirtualUserManager](#virtualusermanager)
+  - [HoneyPot](#honeypot)
+  - [SshClient](#sshclient-programmatic-api)
+  - [Key Types](#key-types)
 - [Usage Examples](#usage-examples)
 - [Built-in Commands](#built-in-commands)
+- [Shell Scripting](#shell-scripting)
 - [Configuration](#configuration)
 - [Performance & Scalability](#performance--scalability)
 - [Types & TypeScript](#types--typescript)
 - [FAQ](#faq)
 - [Troubleshooting](#troubleshooting)
-- [Migration Guide](#migration-guide)
 - [Contributing](#contributing)
 - [Security](#security)
 - [Support](#support)
@@ -32,43 +40,58 @@
 - [Roadmap](#roadmap)
 - [Changelog](#changelog)
 
+---
+
 ## Overview
 
 `typescript-virtual-container` is a lightweight, fully-typed SSH/SFTP runtime written in TypeScript that provides:
 
+- **Pure in-memory filesystem**: No disk I/O at runtime. All state lives in a fast recursive in-memory tree. Use JSON snapshots for optional persistence.
 - **SSH + SFTP Protocol Support**: Serve SSH shell/exec sessions and SFTP file operations on configurable ports.
-- **Virtual Filesystem**: Fast developer workflow backed by a mirror directory under `.vfs/mirror`, with optional gzip compression and programmatic access.
-- **User Management**: Create, authenticate, and manage virtual users with strict password hashing (scrypt) and sudo-like privilege elevation.
+- **Password & public-key authentication**: Register SSH public keys per user alongside (or instead of) password auth.
+- **Rate limiting / brute-force protection**: Configurable per-IP lockout after N failed auth attempts.
+- **User Management**: Create, authenticate, and manage virtual users with scrypt password hashing, sudo-like privilege elevation, and optional per-user disk quotas.
 - **Programmatic Shell API**: Execute shell commands and query filesystem state directly from TypeScript without SSH overhead.
-- **Event-Driven Architecture**: All core classes extend `EventEmitter` for lifecycle and operation tracking. Listen to auth events, filesystem operations, session lifecycle, and command execution for auditing and integration.
+- **Real shell interpreter**: `&&` / `||` / `;` operators, `if`/`elif`/`else`/`fi`, `for`/`do`/`done`, `while`/`do`/`done`, variable expansion (`$VAR`, `${VAR:-default}`), `$?`, per-session environment.
+- **`.bashrc` support**: Loaded automatically at interactive session start from `/home/<user>/.bashrc`.
+- **Event-Driven Architecture**: All core classes extend `EventEmitter` for lifecycle and operation tracking.
 - **Security Auditing**: Built-in `HoneyPot` utility for comprehensive activity logging, event tracking, statistics collection, and anomaly detection across all components.
-- **Built-in Commands**: `ls`, `cd`, `pwd`, `cat`, `mkdir`, `touch`, `rm`, `tree`, `whoami`, `hostname`, `who`, `sudo`, `su`, `adduser`, `deluser`, `nano` (text editor), `curl`, `wget`, and a growing set of additional commands. Not everything is implemented yet, and shell compatibility is still being expanded.
+- **60+ Built-in Commands**: Full navigation, text processing, archiving, system info, and user management commands — grouped and documented in the interactive `help` system.
 - **Full TypeScript Support**: Complete JSDoc coverage, exported types, and first-class async/await for all operations.
 
+---
+
 ## What This Is / What This Is Not
 
 ### What This Is
 
-- A virtual shell runtime written in TypeScript.
-- A virtual environment with its own virtual filesystem, user management, and command runtime.
+- A virtual shell runtime written in TypeScript with a **pure in-memory filesystem**.
+- A virtual environment with its own filesystem, user management, and a real shell interpreter.
 - A practical tool for deterministic testing, automation pipelines, and SSH-like workflows without running real containers.
+- A honeypot framework for capturing and auditing attacker behavior.
 
 ### What This Is Not
 
 - Not a fully isolated container runtime.
-- Not a security sandbox.
+- Not a security sandbox — the VFS does not sandbox host filesystem access by spawned child processes (e.g. `wget`, `curl` delegate to the host binary).
 - Not a kernel-level isolation boundary (unlike Docker/VM-based isolation).
 
 This project emulates shell behavior for developer workflows. It is designed for realism and productivity, not hard security isolation.
 
+---
+
 ## Why This Package
 
 This package is designed for teams that need a realistic SSH-like runtime without spinning up real containers or VMs.
 
-- **Deterministic test environments**: Repeatable state for CI pipelines and integration tests.
+- **Zero disk footprint by default**: The VFS operates entirely in memory. Opt into JSON snapshot persistence when you need it.
+- **Deterministic test environments**: Repeatable state for CI pipelines and integration tests. Build a fixture snapshot once, hydrate for each test.
 - **Low operational overhead**: No Docker daemon, no kernel namespaces, no privileged setup.
 - **Fast feedback loops**: Programmatic API for command execution and filesystem assertions.
-- **Developer-friendly internals**: Typed APIs, clear boundaries, and composable building blocks.
+- **Real shell scripting**: `&&`/`||`/`;`, `if`/`for`/`while`, variable expansion — not just command dispatch.
+- **Developer-friendly internals**: Typed APIs, clear boundaries, composable building blocks, and full JSDoc.
+
+---
 
 ## Installation
 
@@ -86,12 +109,23 @@ bun add typescript-virtual-container
 
 ```bash
 git clone https://github.com/itsrealfortune/typescript-virtual-container/
-cd virtual-env-js
+cd typescript-virtual-container
 bun install
-bun format  # Format code per Biome
-bun check   # Lint and typecheck
+bun format   # Format code per Biome
+bun check    # Lint and typecheck
+bun run build
 ```
 
+### Standalone (zero install)
+
+To quickly try a standalone demo:
+
+```bash
+curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/standalone.js -o standalone.js && node standalone.js && rm -f standalone.js
+```
+
+---
+
 ## Compatibility
 
 - **Node.js**: Recommended `>=18`
@@ -101,6 +135,8 @@ bun check   # Lint and typecheck
 
 The virtual filesystem and shell behavior are intentionally portable and do not depend on host-specific POSIX syscalls.
 
+---
+
 ## Quick Start
 
 ### Running an SSH Server
@@ -108,23 +144,21 @@ The virtual filesystem and shell behavior are intentionally portable and do not
 ```typescript
 import { VirtualSshServer } from "typescript-virtual-container";
 
-// Create server on port 2222
-const ssh = new VirtualSshServer({ 
-	port: 2222, 
-	hostname: "my-container" 
+const ssh = new VirtualSshServer({
+  port: 2222,
+  hostname: "my-container",
 });
 
-// Start server
 await ssh.start();
 console.log("SSH server listening on :2222");
 
-// Connect externally via SSH
-// ssh root@localhost -p 2222  (password: "root")
+// Connect externally:
+// ssh root@localhost -p 2222
+// root has no password by default — login is allowed without verification.
 
-// Graceful shutdown
 process.on("SIGTERM", () => {
-	ssh.stop();
-	process.exit(0);
+  ssh.stop();
+  process.exit(0);
 });
 ```
 
@@ -135,17 +169,8 @@ import { VirtualSftpServer, VirtualShell, VirtualSshServer } from "typescript-vi
 
 const shell = new VirtualShell("my-container");
 
-const ssh = new VirtualSshServer({
-	port: 2222,
-	hostname: "my-container",
-	shell,
-});
-
-const sftp = new VirtualSftpServer({
-	port: 2223,
-	hostname: "my-container",
-	shell,
-});
+const ssh  = new VirtualSshServer({ port: 2222, hostname: "my-container", shell });
+const sftp = new VirtualSftpServer({ port: 2223, hostname: "my-container", shell });
 
 await ssh.start();
 await sftp.start();
@@ -156,18 +181,16 @@ console.log("SSH on :2222, SFTP on :2223");
 ### Using the Programmatic Client API
 
 ```typescript
-import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
+import { SshClient, VirtualShell, VirtualSshServer } from "typescript-virtual-container";
 
 const shell = new VirtualShell("typescript-vm");
-const ssh = new VirtualSshServer({ port: 2222, shell });
+const ssh   = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
-// Create authenticated client for specific user
 const client = new SshClient(shell, "root");
 
-// Execute commands programmatically
 const list = await client.ls("/home");
-console.log("stdout:", list.stdout);  // Directory listing
+console.log("stdout:", list.stdout);
 
 const result = await client.pwd();
 console.log("Current dir:", result.stdout);
@@ -183,109 +206,101 @@ await client.writeFile("output.txt", "Hello, World!");
 ssh.stop();
 ```
 
-## Architecture Overview
-
-<!-- ### Core Components
+---
 
-```
-┌─────────────────────────────────────────────┐
-│       SSH Server (SshMimic)                 │
-│  Listens on :port, handles auth & sessions │
-└──────────────┬──────────────────────────────┘
-							 │
-			 ┌───────┴────────┬──────────────┐
-			 │                │              │
-┌──────┴──────┐  ┌─────┴─────┐  ┌────┴─────┐
-│ VirtualFileSystem   │ VirtualUserManager  │  Command Runtime
-│ In-mem FS w/ persist      │ Auth & Sudoers    │  Shell/Exec Mode
-└──────────────┘  └──────────┘  └──────────┘
-			 ▲
-│              Backed by disk
-│              .vfs/mirror
-└──────────────────────────────────┘
-``` -->
+## Architecture Overview
 
 ### Execution Modes
 
-1. **SSH Shell Mode**: Interactive terminal session over SSH with readline, prompt, TTY resizing.
-2. **SSH Exec Mode**: Non-interactive command execution (e.g., `ssh user@host "ls -la"`).
+1. **SSH Shell Mode**: Interactive terminal session over SSH with readline, history, `.bashrc` loading, TTY resizing, `Ctrl+W` word delete, `Ctrl+U` line clear.
+2. **SSH Exec Mode**: Non-interactive command execution (e.g. `ssh user@host "ls -la"`).
 3. **SFTP Mode**: Remote file operations (`readdir`, `stat`, `readFile`, `writeFile`, `mkdir`, `rename`, etc.) with home-directory confinement.
-4. **Programmatic Mode**: Direct TypeScript API via `SshClient`, no SSH protocol overhead.
-
-### Persistence
-
-- Filesystem state is stored under `.vfs/mirror` inside the configured `basePath`
-- Users/passwords stored in virtual paths `/virtual-env-js/.auth/htpasswd` and `/virtual-env-js/.auth/sudoers`
-- `restoreMirror()` and `flushMirror()` are lightweight compatibility hooks for initialization boundaries
+4. **Programmatic Mode**: Direct TypeScript API via `SshClient` — no SSH protocol overhead.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  SshMimic (VirtualSshServer)             SftpMimic (VirtualSftpServer)  │
+│  password auth · publickey auth          SFTP protocol handlers          │
+│  per-IP rate limiting / lockout          home-dir confinement            │
+└─────────────────────────┬────────────────────────────────────────────────┘
+                          │
+               ┌──────────▼──────────┐
+               │    VirtualShell     │
+               │  script parser      │  ← &&/||/; · if/for/while
+               │  command executor   │  ← per-session ShellEnv
+               │  .bashrc loader     │  ← /home/<user>/.bashrc
+               │  session manager    │
+               └──┬──────────────┬───┘
+                  │              │
+     ┌────────────▼───┐    ┌─────▼───────────────┐
+     │VirtualFileSystem│   │ VirtualUserManager   │
+     │ in-memory tree  │   │ scrypt · sudoers     │
+     │ gzip · symlinks │   │ publickey auth       │
+     │ snapshot I/O    │   │ quotas · sessions    │
+     │ mode:memory|fs  │   └─────────────────────-┘
+     └─────────────────┘
+                  │
+     ┌────────────▼────────────┐
+     │        HoneyPot         │
+     │ audit log · stats       │
+     │ anomaly detection       │
+     └─────────────────────────┘
+```
 
 ---
 
 ## API Reference
 
-### SshMimic (SSH Server)
+### `VirtualSshServer`
 
-Main SSH server class, exported as `VirtualSshServer` in the package entrypoint. It wires the virtual shell runtime into ssh2 sessions and manages authentication/session handlers.
+Main SSH server class. Wires the virtual shell runtime into `ssh2` sessions and manages authentication and session handlers.
 
 #### Constructor
 
 ```typescript
-new SshMimic(options: {
-	port: number;           // TCP port to bind on localhost
-	hostname?: string;      // Virtual hostname (default: "typescript-vm")
-	shell?: VirtualShell;   // Optional preconfigured shell instance
+new VirtualSshServer({
+  port: number;               // TCP port to bind
+  hostname?: string;          // Virtual hostname (default: "typescript-vm")
+  shell?: VirtualShell;       // Optional shared shell instance (share state with SFTP)
+  maxAuthAttempts?: number;   // Max failed auth per IP before lockout (default: 5)
+  lockoutDurationMs?: number; // Lockout duration in ms (default: 60_000)
 })
 ```
 
-- `hostname` controls the SSH ident label and the default hostname used by a generated shell.
-- If `shell` is omitted, the server creates `new VirtualShell(hostname)` for you.
+If `shell` is omitted, the server creates `new VirtualShell(hostname)` internally.
 
 **Example:**
 
 ```typescript
-const virtualShell = new VirtualShell("my-lab", {
-	kernel: "1.0.0+itsrealfortune+1-amd64",
-	os: "Fortune GNU/Linux x64",
-	arch: "x86_64",
-}, "./data");
-const ssh = new SshMimic({
-	port: 2222,
-	hostname: "my-lab",
-	shell: virtualShell
+const shell = new VirtualShell("my-lab", {
+  kernel: "1.0.0+itsrealfortune+1-amd64",
+  os: "Fortune GNU/Linux x64",
+  arch: "x86_64",
 });
-```
-
-#### Methods
 
-##### `async start(): Promise<number>`
-
-Initializes virtual filesystem, user manager, and starts listening for SSH connections.
-
-- **Returns**: Bound port number
-- **Throws**: Error if port not available or initialization fails
-
-```typescript
-const port = await ssh.start();
-console.log(`Listening on ${port}`);
+const ssh = new VirtualSshServer({ port: 2222, hostname: "my-lab", shell });
 ```
 
-##### `stop(): void`
+#### Methods
 
-Cleanly closes server and all active connections.
-
-```typescript
-ssh.stop();
-```
+| Method | Description |
+|--------|-------------|
+| `start(): Promise<number>` | Initialize VFS, users, start listening. Returns bound port. |
+| `stop(): void` | Gracefully close server and all active connections. |
+| `clearLockout(ip: string): void` | Manually lift a rate-limit lockout for an IP. |
+| `getVfs(): VirtualFileSystem \| null` | Access VFS instance (null before start). |
+| `getUsers(): VirtualUserManager \| null` | Access user manager (null before start). |
+| `getHostname(): string` | Returns configured hostname. |
 
 #### Events
 
-`SshMimic` extends `EventEmitter` and emits the following events:
-
 | Event | Data | Description |
 |-------|------|-------------|
 | `start` | `{ port: number }` | Server started and listening |
 | `stop` | — | Server stopped |
-| `auth:success` | `{ username: string; remoteAddress: string }` | User authenticated |
-| `auth:failure` | `{ username: string; remoteAddress: string }` | Auth failed for user |
+| `auth:success` | `{ username, remoteAddress, method? }` | User authenticated |
+| `auth:failure` | `{ username, remoteAddress, reason?, method? }` | Auth failed |
+| `auth:lockout` | `{ ip, until: Date }` | IP locked out after too many failures |
 | `client:connect` | — | New SSH client connected |
 | `client:disconnect` | `{ user: string }` | SSH client disconnected |
 
@@ -293,943 +308,574 @@ ssh.stop();
 
 ```typescript
 ssh.on("auth:success", ({ username, remoteAddress }) => {
-	console.log(`[SSH] User ${username} authenticated from ${remoteAddress}`);
+  console.log(`[SSH] ${username} authenticated from ${remoteAddress}`);
 });
 
-ssh.on("auth:failure", ({ username }) => {
-	console.log(`[SSH] Auth failed for user ${username}`);
+ssh.on("auth:lockout", ({ ip, until }) => {
+  console.warn(`[SSH] ${ip} locked until ${until}`);
 });
 ```
 
-##### `getVfs(): VirtualFileSystem | null`
-
-Returns the virtual filesystem instance. Null if server not started.
-
-```typescript
-const vfs = ssh.getVfs();
-if (vfs) {
-	const content = vfs.readFile("/etc/hosts");
-}
-```
-
-##### `getUsers(): VirtualUserManager | null`
-
-Returns the user manager instance. Null if server not started.
-
-```typescript
-const users = ssh.getUsers();
-const sessions = users.listActiveSessions();
-```
-
-##### `getHostname(): string`
-
-Returns configured server hostname.
-
-```typescript
-console.log(`Server name: ${ssh.getHostname()}`);
-```
-
 ---
 
-### SftpMimic (SFTP Server)
+### `VirtualSftpServer`
 
-SFTP server class, exported as `VirtualSftpServer` in the package entrypoint. It can run with a shared `VirtualShell` (recommended) or with explicit `vfs + users` dependencies.
+SFTP server class. Can share a `VirtualShell` with `VirtualSshServer` (recommended) or accept explicit `vfs` + `users` dependencies.
 
 #### Constructor
 
 ```typescript
-new SftpMimic(options: {
-	port: number;
-	hostname?: string;
-	shell?: VirtualShell;
-	vfs?: VirtualFileSystem;
-	users?: VirtualUserManager;
+new VirtualSftpServer({
+  port: number;
+  hostname?: string;
+  shell?: VirtualShell;          // share state with SSH server
+  vfs?: VirtualFileSystem;       // explicit if no shell
+  users?: VirtualUserManager;    // explicit if no shell
 })
 ```
 
-- If `shell` is provided, SFTP reuses the same users/filesystem state as SSH.
-- If `shell` is omitted, pass `vfs` and `users` explicitly.
-
 #### Methods
 
-##### `async start(): Promise<number>`
-
-Starts the SFTP server and returns the bound port (useful with `port: 0`).
-
-```typescript
-const sftp = new SftpMimic({ port: 0, shell });
-const boundPort = await sftp.start();
-console.log(`SFTP listening on ${boundPort}`);
-```
-
-##### `stop(): void`
-
-Stops the SFTP server.
-
-```typescript
-sftp.stop();
-```
+| Method | Description |
+|--------|-------------|
+| `start(): Promise<number>` | Start SFTP server, returns bound port. |
+| `stop(): void` | Stop SFTP server. |
 
 #### Behavior Notes
 
-- Supports `password` and `keyboard-interactive` authentication.
+- Supports `password` and `keyboard-interactive` authentication. Users without a password set are accepted on any attempt.
 - Resolves relative SFTP paths from `/home/<user>`.
-- Confines all SFTP operations to `/home/<user>` and blocks traversal attempts outside the user home.
+- Confines all SFTP operations to `/home/<user>` — blocks traversal attempts outside home.
 - Unsupported operations (`READLINK`, `SYMLINK`) return `OP_UNSUPPORTED`.
 
 #### Events
 
-`SftpMimic` extends `EventEmitter` and emits the following events:
-
 | Event | Data | Description |
 |-------|------|-------------|
-| `start` | `{ port: number }` | SFTP server started and listening |
+| `start` | `{ port: number }` | SFTP server started |
 | `stop` | — | SFTP server stopped |
-| `auth:success` | `{ username: string; remoteAddress: string }` | User authenticated for SFTP |
-| `auth:failure` | `{ username: string; remoteAddress: string }` | SFTP auth failed for user |
+| `auth:success` | `{ username, remoteAddress }` | User authenticated |
+| `auth:failure` | `{ username, remoteAddress }` | Auth failed |
 | `client:connect` | — | New SFTP client connected |
 | `client:disconnect` | `{ user: string }` | SFTP client disconnected |
 
-**Example:**
-
-```typescript
-sftp.on("auth:success", ({ username }) => {
-	console.log(`[SFTP] User ${username} authenticated`);
-});
-```
-
 ---
 
-### SshClient (Programmatic Shell API)
+### `VirtualShell`
 
-Execute shell commands against a `VirtualShell` instance without SSH overhead. Maintains connection state (current working directory) across calls.
+Coordinates the virtual filesystem, user manager, and command runtime. Used by both SSH servers and the programmatic `SshClient`.
 
 #### Constructor
 
 ```typescript
-new SshClient(shell: VirtualShell, username: string)
-```
-
-- **shell**: Parent virtual shell instance
-- **username**: User to authenticate as (no password required)
-
-**Example:**
-
-```typescript
-const shell = new VirtualShell("typescript-vm");
-const client = new SshClient(shell, "alice");
-```
-
-#### Methods
-
-##### `async exec(command: string): Promise<CommandResult>`
-
-Raw command execution. Returns structured output.
-
-```typescript
-const result = await client.exec("echo hello && exit 42");
-console.log(result.stdout);      // "hello"
-console.log(result.exitCode);    // 42
-```
-
-##### `async ls(path?: string): Promise<CommandResult>`
-
-Lists directory contents. Defaults to current directory.
-
-```typescript
-const result = await client.ls("/tmp");
-// result.stdout contains formatted listing
-```
-
-##### `async pwd(): Promise<CommandResult>`
-
-Prints current working directory.
-
-```typescript
-const result = await client.pwd();
-console.log("cwd:", result.stdout);  // "/home/alice"
-```
-
-##### `async cd(path: string): Promise<CommandResult>`
-
-Changes working directory. Updates internal state on success.
-
-```typescript
-const result = await client.cd("/var/log");
-// Internal cwd now "/var/log"
-
-const result2 = await client.ls();  // Listed from /var/log
-```
-
-##### `async cat(path: string): Promise<CommandResult>`
-
-Reads file content via command.
-
-```typescript
-const result = await client.cat("/etc/hostname");
-console.log(result.stdout);
-```
-
-##### `async mkdir(path: string, recursive?: boolean): Promise<CommandResult>`
-
-Creates directory. Set `recursive=true` for `-p` flag.
-
-```typescript
-await client.mkdir("/tmp/nested/dirs", true);
-```
-
-##### `async touch(path: string): Promise<CommandResult>`
-
-Creates empty file.
-
-```typescript
-await client.touch("/tmp/marker.txt");
-```
-
-##### `async rm(path: string, recursive?: boolean): Promise<CommandResult>`
-
-Removes file or directory. Set `recursive=true` for `-r` flag.
-
-```typescript
-await client.rm("/tmp/old", true);  // rm -r /tmp/old
-```
-
-##### `async readFile(path: string): Promise<CommandResult>`
-
-Reads file content directly from VFS (programmatic, no shell).
-
-```typescript
-const result = await client.readFile("/etc/hostname");
-console.log(result.stdout);  // File content
-if (result.exitCode !== 0) console.error(result.stderr);
-```
-
-##### `async writeFile(path: string, content: string): Promise<CommandResult>`
-
-Writes file content directly to VFS (programmatic, no shell).
-
-```typescript
-await client.writeFile("/tmp/config.txt", "port=8080\nhost=localhost");
-```
-
-##### `async tree(path?: string): Promise<CommandResult>`
-
-Renders ASCII directory tree.
-
-```typescript
-const result = await client.tree("/home");
-console.log(result.stdout);
-```
-
-##### `async whoami(): Promise<CommandResult>`
-
-Shows authenticated user.
-
-```typescript
-const result = await client.whoami();
-console.log(result.stdout);  // "alice" (or user passed to constructor)
-```
-
-##### `async hostname(): Promise<CommandResult>`
-
-Shows server hostname.
-
-```typescript
-const result = await client.hostname();
-```
-
-##### `async who(): Promise<CommandResult>`
-
-Lists active user sessions.
-
-```typescript
-const result = await client.who();
-console.log(result.stdout);  // Active sessions
-```
-
-##### `getCwd(): string`
-
-Returns current working directory (local state, no I/O).
-
-```typescript
-await client.cd("/tmp");
-console.log(client.getCwd());  // "/tmp"
-```
-
-##### `getUsername(): string`
-
-Returns authenticated username (local state, no I/O).
-
-```typescript
-console.log(client.getUsername());  // Username from constructor
+new VirtualShell(
+  hostname: string,
+  properties?: ShellProperties,
+  vfsOptions?: VfsOptions,
+)
 ```
 
----
-
-### VirtualShell
-
-Encapsulates shell execution primitives used by the SSH runtime for command dispatch, interactive sessions, and the programmatic client.
-
-#### ShellProperties
+- **hostname**: Injected into command context and prompt.
+- **properties**: Optional shell metadata shown in `uname`-like output. Defaults to `defaultShellProperties`.
+- **vfsOptions**: Optional VFS persistence options — see [VirtualFileSystem](#virtualfilesystem).
 
 ```typescript
 interface ShellProperties {
-	kernel: string;
-	os: "Fortune GNU/Linux x64";
-	arch: "x86_64";
+  kernel: string;  // e.g. "1.0.0+itsrealfortune+1-amd64"
+  os: string;      // e.g. "Fortune GNU/Linux x64"
+  arch: string;    // e.g. "x86_64"
 }
-
-const defaultShellProperties: ShellProperties;
 ```
 
-- `kernel` is displayed in shell/system information output.
-- `os` and `arch` are fixed labels used by the shell runtime.
-
-#### Constructor
-
-```typescript
-new VirtualShell(
-	hostname: string,
-	properties?: ShellProperties,
-	basePath?: string,
-)
-```
-
-- **hostname**: Hostname injected into command context and prompt behavior.
-- **properties**: Optional shell metadata. Defaults to `defaultShellProperties`.
-- **basePath**: Optional directory used to resolve `.vfs/mirror` and auth storage (defaults to `.`).
-
 **Example:**
 
 ```typescript
 const shell = new VirtualShell("typescript-vm", {
-	kernel: "1.0.0+itsrealfortune+1-amd64",
-	os: "Fortune GNU/Linux x64",
-	arch: "x86_64",
-}, "./data");
+  kernel: "1.0.0+itsrealfortune+1-amd64",
+  os: "Fortune GNU/Linux x64",
+  arch: "x86_64",
+}, {
+  mode: "fs",
+  snapshotPath: "./data",
+});
 ```
 
 #### Methods
 
-##### `addCommand(name: string, params: string[], callback: (ctx: CommandContext) => CommandResult | Promise<CommandResult>): void`
+| Method | Description |
+|--------|-------------|
+| `ensureInitialized(): Promise<void>` | Await this before using the shell programmatically. |
+| `addCommand(name, params, callback)` | Register a custom shell command. |
+| `executeCommand(rawInput, authUser, cwd)` | Run a raw command string. |
+| `startInteractiveSession(stream, authUser, sessionId, remoteAddress, terminalSize)` | Start an SSH interactive session. |
+| `writeFileAsUser(authUser, path, content)` | Write a file with quota enforcement. |
+| `getVfs(): VirtualFileSystem \| null` | Access the VFS instance. |
+| `getUsers(): VirtualUserManager \| null` | Access the user manager. |
+| `getHostname(): string` | Returns the configured hostname. |
 
-Registers a custom command at runtime.
+**Custom command example:**
 
 ```typescript
-shell.addCommand("hello", [], () => ({ stdout: "hello", exitCode: 0 }));
-```
-
-##### `executeCommand(rawInput: string, authUser: string, cwd: string): void`
-
-Runs one command input in shell mode for a given user and working directory.
-
-```typescript
-shell.executeCommand("ls -la", "root", "/home/root");
-```
-
-##### `startInteractiveSession(stream: ShellStream, authUser: string, sessionId: string | null, remoteAddress: string, terminalSize: { cols: number; rows: number }): void`
-
-Starts an interactive shell session over a shell stream.
-
-```typescript
-shell.startInteractiveSession(
-	stream,
-	"root",
-	sessionId,
-	"127.0.0.1",
-	{ cols: 120, rows: 30 },
-);
+shell.addCommand("greet", ["[name]"], ({ args, authUser }) => {
+  const name = args[0] ?? authUser;
+  return { stdout: `Hello, ${name}!`, exitCode: 0 };
+});
+// Inside the shell: greet world → Hello, world!
 ```
 
 #### Events
 
-`VirtualShell` extends `EventEmitter` and emits the following events:
-
 | Event | Data | Description |
 |-------|------|-------------|
 | `initialized` | — | Shell initialization complete |
-| `command` | `{ command: string; user: string; cwd: string }` | Command executed |
-| `session:start` | `{ user: string; sessionId: string \| null; remoteAddress: string }` | Interactive session started |
-
-**Example:**
-
-```typescript
-shell.on("command", ({ command, user, cwd }) => {
-	console.log(`[SHELL] User ${user} executed: ${command} (cwd: ${cwd})`);
-});
-
-shell.on("session:start", ({ user, remoteAddress }) => {
-	console.log(`[SHELL] Session started for ${user} from ${remoteAddress}`);
-});
-```
+| `command` | `{ command, user, cwd }` | A command was executed |
+| `session:start` | `{ user, sessionId, remoteAddress }` | Interactive session started |
 
 ---
 
-### VirtualFileSystem
-
-Virtual filesystem abstraction backed by a mirror directory on disk, with optional gzip compression per file.
-
-#### Constructor
+### `VirtualFileSystem`
 
-```typescript
-new VirtualFileSystem(baseDir?: string)
-```
+Pure in-memory virtual filesystem. All state lives in a recursive `Map`-based tree — no host filesystem access at runtime.
 
-- **baseDir**: Directory used for the `.vfs/mirror` root (default: current working directory)
+Two persistence modes are available via the `VfsOptions` constructor argument:
 
 ```typescript
-const vfs = new VirtualFileSystem("./container-data");
-// Mirror root at ./container-data/.vfs/mirror
-```
-
-#### Methods
+// Default — pure in-memory, zero disk I/O
+const vfs = new VirtualFileSystem();
+const vfs = new VirtualFileSystem({ mode: "memory" });
 
-#### Events
-
-`VirtualFileSystem` extends `EventEmitter` and emits the following events:
-
-| Event | Data | Description |
-|-------|------|-------------|
-| `file:read` | `{ path: string; size: number }` | File read |
-| `file:write` | `{ path: string; size: number }` | File written |
-| `dir:create` | `{ path: string; mode: number }` | Directory created |
-| `mirror:flush` | — | Mirror persisted to disk |
-
-**Example:**
-
-```typescript
-vfs.on("file:write", ({ path, size }) => {
-	console.log(`[VFS] File written: ${path} (${size} bytes)`);
+// FS mode — JSON snapshot auto-saved to disk on flushMirror()
+const vfs = new VirtualFileSystem({
+  mode: "fs",
+  snapshotPath: "./data",  // writes ./data/vfs-snapshot.json
 });
-
-vfs.on("dir:create", ({ path, mode }) => {
-	console.log(`[VFS] Directory created: ${path} (mode: ${mode.toString(8)})`);
-});
-```
-
-##### `async restoreMirror(): Promise<void>`
-
-Ensures mirror directory structure exists and is ready for operations.
-
-```typescript
-await vfs.restoreMirror();
-```
-
-##### `async flushMirror(): Promise<void>`
-
-Compatibility hook to finalize mirror boundary operations.
-
-```typescript
-// After file modifications...
-await vfs.flushMirror();
-```
-
-##### `mkdir(path: string, mode?: number): void`
-
-Creates directory and any missing parents. Throws if parent is a file.
-
-```typescript
-vfs.mkdir("/home/user/.ssh", 0o700);
-```
-
-##### `writeFile(path: string, content: string | Buffer, options?: WriteFileOptions): void`
-
-Writes file content. Creates parent directories if missing.
-
-- **options.mode**: POSIX file mode (default: 0o644)
-- **options.compress**: Store as gzip (default: false)
-
-```typescript
-vfs.writeFile("/etc/app.conf", "debug=true\n", { compress: true });
-```
-
-##### `readFile(path: string): string`
-
-Reads file as UTF-8 string. Transparently decompresses if needed.
-
-```typescript
-const content = vfs.readFile("/etc/app.conf");
-```
-
-##### `exists(path: string): boolean`
-
-Checks node existence (file or directory).
-
-```typescript
-if (!vfs.exists("/var/log")) {
-	vfs.mkdir("/var/log");
-}
-```
-
-##### `stat(path: string): VfsNodeStats`
-
-Returns metadata (type, size, dates, mode, etc.).
-
-```typescript
-const stats = vfs.stat("/etc/hostname");
-if (stats.type === "file") {
-	console.log(`File size: ${stats.size} bytes`);
-}
-```
-
-##### `list(dirPath?: string): string[]`
-
-Lists child names in directory (sorted). Throws if path not a directory.
-
-```typescript
-const files = vfs.list("/home");
-// ["alice", "bob", "root"]
+await vfs.restoreMirror(); // load from disk (silent no-op if no file yet)
+// ... use vfs ...
+await vfs.flushMirror();   // persist to disk
 ```
 
-##### `tree(dirPath?: string): string`
-
-Renders ASCII tree view of directory hierarchy.
-
-```typescript
-console.log(vfs.tree("/home"));
-```
-
-##### `chmod(path: string, mode: number): void`
-
-Updates file/dir permissions.
-
-```typescript
-vfs.chmod("/tmp/script.sh", 0o755);
-```
-
-##### `remove(path: string, options?: RemoveOptions): void`
-
-Removes file or directory. Throws if directory not empty unless `recursive: true`.
-
-```typescript
-vfs.remove("/tmp/old", { recursive: true });
-```
-
-##### `move(fromPath: string, toPath: string): void`
-
-Renames or moves node. Throws if destination exists.
-
-```typescript
-vfs.move("/var/tmp", "/var/backup");
-```
-
-##### `compressFile(path: string): void`
-
-Gzip-compresses file content and marks as compressed.
-
-```typescript
-vfs.compressFile("/var/log/app.log");
-```
-
-##### `decompressFile(path: string): void`
-
-Decompresses file content (inverse of `compressFile`).
-
-```typescript
-vfs.decompressFile("/var/log/app.log");
-```
-
-**Example:**
-
-```typescript
-vfs.on("file:write", ({ path, size }) => {
-	console.log(`[VFS] File written: ${path} (${size} bytes)`);
-});
-
-vfs.on("dir:create", ({ path, mode }) => {
-	console.log(`[VFS] Directory created: ${path} (mode: ${mode.toString(8)})`);
-});
-```
-
----
-
-### VirtualUserManager
-
-User authentication, password hashing (scrypt), sudo privilege management, and session tracking.
+Both modes expose exactly the same API. The tree always lives in memory; `"fs"` mode adds a JSON round-trip on `restoreMirror` / `flushMirror`.
 
 #### Constructor
 
 ```typescript
-new VirtualUserManager(vfs: VirtualFileSystem, defaultRootPassword?: string, autoSudoForNewUsers?: boolean)
-```
-
-- **vfs**: Virtual filesystem (for auth data persistence)
-- **defaultRootPassword**: Root password used when root is created (default: "root")
-- **autoSudoForNewUsers**: When true, new users are added to sudoers automatically (default: `true` unless `SSH_MIMIC_AUTO_SUDO_NEW_USERS` disables it)
-
-```typescript
-const users = new VirtualUserManager(vfs, "SecureRootPass123");
-```
-
-#### Methods
-
-##### `async initialize(): Promise<void>`
-
-Loads users/sudoers from disk, ensures root exists, and initializes sessions.
-
-```typescript
-await users.initialize();
-```
-
-##### `verifyPassword(username: string, password: string): boolean`
-
-Checks plaintext password against hashed record.
-
-```typescript
-if (users.verifyPassword("alice", "password123")) {
-	console.log("Auth OK");
+interface VfsOptions {
+  mode?: "memory" | "fs";  // default: "memory"
+  snapshotPath?: string;   // required when mode is "fs"
 }
-```
 
-##### `async addUser(username: string, password: string): Promise<void>`
-
-Creates new user with home directory.
-
-```typescript
-await users.addUser("bob", "bob_password");
-// ~/bob created, added to sudoers
-```
-
-##### `async deleteUser(username: string): Promise<void>`
-
-Removes user. Cannot delete root.
-
-```typescript
-await users.deleteUser("bob");
+new VirtualFileSystem(options?: VfsOptions)
 ```
 
-##### `isSudoer(username: string): boolean`
-
-Checks sudo access.
-
-
-```typescript
-if (users.isSudoer("alice")) {
-	console.log("alice can use sudo");
-}
-```
-
-##### `async addSudoer(username: string): Promise<void>`
-
-Grants sudo privileges to user.
-
-```typescript
-await users.addSudoer("charlie");
-```
-
-##### `async removeSudoer(username: string): Promise<void>`
-
-Revokes sudo privileges. Cannot remove root.
-
-```typescript
-await users.removeSudoer("charlie");
-```
-
-##### `async setQuotaBytes(username: string, maxBytes: number): Promise<void>`
+#### Methods
 
-Sets an optional per-user quota (bytes) for writes under `/home/<username>`.
+| Method | Description |
+|--------|-------------|
+| `mkdir(path, mode?)` | Create directory and any missing parents. |
+| `writeFile(path, content, options?)` | Write file (creates parent dirs). `options.compress` stores as gzip; `options.mode` sets POSIX mode bits. |
+| `readFile(path): string` | Read file as UTF-8. Transparently decompresses gzip files. |
+| `readFileRaw(path): Buffer` | Read file as Buffer (decompresses if needed). |
+| `exists(path): boolean` | Test whether a file or directory exists. |
+| `stat(path): VfsNodeStats` | Returns file/directory metadata. |
+| `list(path?): string[]` | List direct children of a directory (sorted). |
+| `tree(path?): string` | Render ASCII directory tree. |
+| `move(from, to)` | Move or rename a node. Throws if destination exists. |
+| `remove(path, options?)` | Delete file or directory. `options.recursive` required for non-empty dirs. |
+| `chmod(path, mode)` | Update POSIX mode bits. |
+| `compressFile(path)` | Gzip-compress file content in place. |
+| `decompressFile(path)` | Gunzip file content in place. |
+| `symlink(target, linkPath)` | Create a symbolic link (mode `0o120777`). |
+| `isSymlink(path): boolean` | Returns true if the path is a symlink node. |
+| `resolveSymlink(path, maxDepth?): string` | Resolve symlink chain to real path (default max 8 hops). |
+| `getUsageBytes(path?): number` | Total stored bytes under a path. |
+| `getMode(): VfsPersistenceMode` | Returns `"memory"` or `"fs"`. |
+| `getSnapshotPath(): string \| null` | Snapshot file path in `"fs"` mode, or null. |
+| `toSnapshot(): VfsSnapshot` | Export the whole tree as a JSON-serialisable snapshot. |
+| `importSnapshot(snapshot)` | Replace current state from a snapshot (preserves mode). |
+| `restoreMirror(): Promise<void>` | Load from disk (`"fs"` mode) / no-op (`"memory"` mode). |
+| `flushMirror(): Promise<void>` | Save to disk (`"fs"` mode) / emit `mirror:flush` (`"memory"` mode). |
+| `VirtualFileSystem.fromSnapshot(snapshot)` | **Static.** Create a new memory-mode instance from a snapshot. |
 
-```typescript
-await users.setQuotaBytes("alice", 5 * 1024 * 1024); // 5 MB
-```
+#### Events
 
-##### `async clearQuota(username: string): Promise<void>`
+| Event | Data | Description |
+|-------|------|-------------|
+| `file:write` | `{ path, size }` | File written |
+| `file:read` | `{ path, size }` | File read |
+| `dir:create` | `{ path, mode }` | Directory created |
+| `node:remove` | `{ path }` | File or directory deleted |
+| `symlink:create` | `{ link, target }` | Symlink created |
+| `snapshot:import` | — | `importSnapshot()` called |
+| `snapshot:restore` | `{ path }` | Restored from disk (fs mode) |
+| `mirror:flush` | `{ path? }` | Flushed (path present in fs mode) |
 
-Removes quota limit for a user.
+**Example:**
 
 ```typescript
-await users.clearQuota("alice");
-```
+vfs.on("file:write", ({ path, size }) => {
+  console.log(`[VFS] Written: ${path} (${size} bytes)`);
+});
 
-##### `getQuotaBytes(username: string): number | null`
+vfs.on("dir:create", ({ path, mode }) => {
+  console.log(`[VFS] Dir created: ${path} (mode: ${mode.toString(8)})`);
+});
+```
 
-Returns configured quota in bytes, or `null` if unlimited.
+#### Memory mode — manual snapshot persistence
 
 ```typescript
-console.log(users.getQuotaBytes("alice"));
-```
+import { VirtualFileSystem } from "typescript-virtual-container";
+import { writeFileSync, readFileSync } from "node:fs";
 
-##### `getUsageBytes(username: string): number`
+const vfs = new VirtualFileSystem(); // mode: "memory"
+vfs.writeFile("/etc/config.json", JSON.stringify({ debug: true }));
 
-Returns current stored usage in bytes under `/home/<username>`.
+// Export to disk manually
+writeFileSync("vfs-snapshot.json", JSON.stringify(vfs.toSnapshot()));
 
-```typescript
-console.log(users.getUsageBytes("alice"));
+// Restore into a new instance
+const snapshot = JSON.parse(readFileSync("vfs-snapshot.json", "utf8"));
+const restored = VirtualFileSystem.fromSnapshot(snapshot);
+console.log(restored.readFile("/etc/config.json")); // {"debug":true}
 ```
 
-##### `assertWriteWithinQuota(username: string, targetPath: string, nextContent: string | Buffer): void`
-
-Validates a write operation against quota rules; throws when projected usage exceeds quota.
+#### FS mode — automatic persistence across restarts
 
 ```typescript
-users.assertWriteWithinQuota("alice", "/home/alice/data.txt", "payload");
-```
+import { VirtualShell, VirtualSshServer } from "typescript-virtual-container";
 
-##### `registerSession(username: string, remoteAddress: string): VirtualActiveSession`
-
-Creates active session (called on SSH auth). Returns session descriptor with UUID, tty, start time.
+const shell = new VirtualShell("my-vm", undefined, {
+  mode: "fs",
+  snapshotPath: "./vfs-data",
+});
 
-```typescript
-const session = users.registerSession("alice", "192.168.1.100");
-console.log(session.id);  // UUID
+const ssh = new VirtualSshServer({ port: 2222, shell });
+await ssh.start();
+// VFS is restored from ./vfs-data/vfs-snapshot.json on start (if it exists).
+// flushMirror() is called after each write, persisting state to disk automatically.
 ```
 
-##### `unregisterSession(sessionId: string | null): void`
-
-Closes session. Safe to call with null.
+---
 
-```typescript
-users.unregisterSession(sessionId);
-```
+### `VirtualUserManager`
 
-##### `updateSession(sessionId: string | null, username: string, remoteAddress: string): void`
+Manages virtual users, password hashing (scrypt), sudo privileges, per-user storage quotas, SSH public keys, and active session tracking.
 
-Updates session metadata (used for su/sudo).
+#### Constructor
 
 ```typescript
-users.updateSession(sessionId, "root", "192.168.1.100");
+new VirtualUserManager(
+  vfs: VirtualFileSystem,
+  autoSudoForNewUsers?: boolean,  // default: true
+)
 ```
 
-##### `listActiveSessions(): VirtualActiveSession[]`
+- Auth data is stored inside the VFS at protected paths under `/virtual-env-js/.auth/`.
+- `autoSudoForNewUsers`: when true, newly created users are automatically added to sudoers.
 
-Returns snapshot of active sessions (sorted by start time).
+#### Methods
 
-```typescript
-const sessions = users.listActiveSessions();
-sessions.forEach(s => {
-	console.log(`${s.username}@${s.remoteAddress} on ${s.tty}`);
-});
-```
+| Method | Description |
+|--------|-------------|
+| `initialize(): Promise<void>` | Load users/sudoers from VFS, ensure root exists. Call once on startup. |
+| `verifyPassword(username, password): boolean` | Check plaintext password against stored hash. |
+| `hasPassword(username): boolean` | Returns true if a password is set for the user. |
+| `hashPassword(password): string` | Hash a password using the configured algorithm. |
+| `addUser(username, password): Promise<void>` | Create user with home directory. |
+| `deleteUser(username): Promise<void>` | Delete user. Cannot delete root. |
+| `setPassword(username, password): Promise<void>` | Update password for an existing user. |
+| `isSudoer(username): boolean` | Check if user has sudo privileges. |
+| `addSudoer(username): Promise<void>` | Grant sudo privileges. |
+| `removeSudoer(username): Promise<void>` | Revoke sudo privileges. Cannot remove root. |
+| `setQuotaBytes(username, maxBytes): Promise<void>` | Set per-user write quota (bytes under `/home/<user>`). |
+| `clearQuota(username): Promise<void>` | Remove quota limit. |
+| `getQuotaBytes(username): number \| null` | Returns quota in bytes, or null if unlimited. |
+| `getUsageBytes(username): number` | Returns current usage in bytes under `/home/<user>`. |
+| `assertWriteWithinQuota(username, path, content)` | Throws if the write would exceed the user's quota. |
+| `addAuthorizedKey(username, algo, data)` | Register an SSH public key for the user. |
+| `getAuthorizedKeys(username)` | Returns the list of authorized keys for a user. |
+| `removeAuthorizedKeys(username)` | Revoke all authorized keys for a user. |
+| `registerSession(username, remoteAddress): VirtualActiveSession` | Start session tracking, returns session descriptor. |
+| `unregisterSession(sessionId): void` | End session. Safe to call with null. |
+| `updateSession(sessionId, username, remoteAddress): void` | Update session metadata (used by `su`/`sudo`). |
+| `listActiveSessions(): VirtualActiveSession[]` | Returns all active sessions sorted by start time. |
 
 #### Events
 
-`VirtualUserManager` extends `EventEmitter` and emits the following events:
-
 | Event | Data | Description |
 |-------|------|-------------|
-| `initialized` | — | User manager initialization complete, root user ready |
-| `user:add` | `{ username: string }` | New user created |
-| `user:delete` | `{ username: string }` | User deleted |
-| `session:register` | `{ sessionId: string; username: string; remoteAddress: string }` | Session registered (user logged in) |
-| `session:unregister` | `{ sessionId: string; username: string }` | Session unregistered (user logged out) |
+| `initialized` | — | User manager ready, root account ensured |
+| `user:add` | `{ username }` | New user created |
+| `user:delete` | `{ username }` | User deleted |
+| `key:add` | `{ username, algo }` | Public key added |
+| `key:remove` | `{ username }` | Public keys removed |
+| `session:register` | `{ sessionId, username, remoteAddress }` | Session started |
+| `session:unregister` | `{ sessionId, username }` | Session ended |
 
 **Example:**
 
 ```typescript
 users.on("user:add", ({ username }) => {
-	console.log(`[USERS] User created: ${username}`);
+  console.log(`[USERS] Created: ${username}`);
 });
 
 users.on("session:register", ({ sessionId, username, remoteAddress }) => {
-	console.log(`[USERS] Session ${sessionId}: ${username} from ${remoteAddress}`);
-});
-
-users.on("session:unregister", ({ sessionId, username }) => {
-	console.log(`[USERS] Session ${sessionId} (${username}) closed`);
+  console.log(`[USERS] Session ${sessionId}: ${username} from ${remoteAddress}`);
 });
 ```
 
 ---
 
-### HoneyPot (Auditing & Event Tracking)
+### `HoneyPot`
 
-Comprehensive security auditing and event tracking utility. Attaches to all core components (VirtualShell, VirtualFileSystem, VirtualUserManager, SshMimic, SftpMimic) to log activity, track statistics, and detect anomalies.
+Comprehensive security auditing and event tracking utility. Attaches listeners to all core components to log activity, track statistics, and detect anomalies.
 
 #### Constructor
 
 ```typescript
-new HoneyPot(maxLogSize?: number)
-```
-
-- **maxLogSize**: Maximum audit log entries to retain (default: 10000)
-
-```typescript
-const honeypot = new HoneyPot(5000);  // Keep last 5000 audit entries
+new HoneyPot(maxLogSize?: number)  // default: 10000
 ```
 
 #### Methods
 
-##### `attach(shell: VirtualShell, vfs: VirtualFileSystem, users: VirtualUserManager, ssh?: SshMimic, sftp?: SftpMimic): void`
+| Method | Description |
+|--------|-------------|
+| `attach(shell, vfs, users, ssh?, sftp?)` | Subscribe to all event sources. |
+| `getAuditLog(type?, source?): AuditLogEntry[]` | Full log, optionally filtered by event type and/or source component. |
+| `getStats(): Readonly<HoneyPotStats>` | Aggregated activity counters. |
+| `getRecent(limit?): AuditLogEntry[]` | Most recent entries in reverse chronological order. |
+| `detectAnomalies()` | Analyze patterns — returns `{ type, severity, message }[]`. |
+| `reset()` | Clear audit log and reset all stat counters. |
+| `exportJson(): string` | Serialise full log + stats to a JSON string. |
+
+#### HoneyPotStats fields
+
+```typescript
+interface HoneyPotStats {
+  authAttempts: number;
+  authSuccesses: number;
+  authFailures: number;
+  commands: number;
+  fileWrites: number;
+  fileReads: number;
+  sessionStarts: number;
+  sessionEnds: number;
+  userCreated: number;
+  userDeleted: number;
+  clientConnects: number;
+  clientDisconnects: number;
+}
+```
 
-Attaches honeypot listeners to all provided event emitters. This wires up all audit tracking across the entire virtual environment.
+#### Audit Log Entry
 
 ```typescript
-honeypot.attach(shell, vfs, users, ssh, sftp);
-// All components now emit events to honeypot
+interface AuditLogEntry {
+  timestamp: string;                // ISO-8601
+  type: string;                     // e.g. "auth:failure", "file:write"
+  source: string;                   // e.g. "SshMimic", "VirtualFileSystem"
+  details: Record<string, unknown>; // event-specific payload
+}
 ```
 
-##### `getAuditLog(type?: string, source?: string): AuditLogEntry[]`
+`detectAnomalies` detects: high authentication failure rates, excessive auth failures, unusual command volume, unusual file write volume.
 
-Returns audit log entries with optional filtering by event type or source component.
+#### Example
 
 ```typescript
-// All entries
-const allLogs = honeypot.getAuditLog();
+import { HoneyPot, VirtualShell, VirtualSshServer } from "typescript-virtual-container";
 
-// Only auth events
-const authLogs = honeypot.getAuditLog("auth:failure");
+const shell = new VirtualShell("honeypot");
+const ssh   = new VirtualSshServer({ port: 2222, shell });
+const hp    = new HoneyPot(50_000);
 
-// Only SshMimic events
-const sshLogs = honeypot.getAuditLog(undefined, "SshMimic");
-
-// Combine filters
-const sshAuthLogs = honeypot.getAuditLog("auth:success", "SshMimic");
-```
+await ssh.start();
+hp.attach(shell, shell.vfs, shell.users, ssh);
 
-##### `getStats(): Readonly<HoneyPotStats>`
+// Filter audit log
+const failures = hp.getAuditLog("auth:failure");
+failures.forEach(e => console.log(e.details.username, e.details.remoteAddress));
 
-Returns current activity statistics snapshot.
+// Detect anomalies
+hp.detectAnomalies().forEach(a =>
+  console.log(`[${a.severity.toUpperCase()}] ${a.type}: ${a.message}`)
+);
 
-```typescript
-const stats = honeypot.getStats();
-console.log(`Auth attempts: ${stats.authAttempts}`);
-console.log(`Auth successes: ${stats.authSuccesses}`);
-console.log(`Auth failures: ${stats.authFailures}`);
-console.log(`Commands executed: ${stats.commands}`);
-console.log(`File writes: ${stats.fileWrites}`);
-console.log(`File reads: ${stats.fileReads}`);
-console.log(`Sessions started: ${stats.sessionStarts}`);
-console.log(`Sessions ended: ${stats.sessionEnds}`);
-console.log(`Users created: ${stats.userCreated}`);
-console.log(`Users deleted: ${stats.userDeleted}`);
-console.log(`Client connects: ${stats.clientConnects}`);
-console.log(`Client disconnects: ${stats.clientDisconnects}`);
+// Export on shutdown
+process.on("SIGINT", () => {
+  require("fs").writeFileSync("audit.json", hp.exportJson());
+  process.exit(0);
+});
 ```
 
-##### `getRecent(limit?: number): AuditLogEntry[]`
-
-Returns most recent audit entries in reverse chronological order.
+---
 
-```typescript
-const last50 = honeypot.getRecent(50);
-last50.forEach(entry => {
-	console.log(`${entry.timestamp} | ${entry.source} | ${entry.type}`);
-	console.log(`Details:`, entry.details);
-});
-```
+### `SshClient` (Programmatic API)
 
-##### `detectAnomalies(): Array<{ type: string; severity: "low" | "medium" | "high"; message: string }>`
+Execute shell commands against a `VirtualShell` without SSH protocol overhead. Maintains working-directory state across calls.
 
-Analyzes activity patterns and detects potential security issues.
+#### Constructor
 
 ```typescript
-const anomalies = honeypot.detectAnomalies();
-anomalies.forEach(anomaly => {
-	console.log(`[${anomaly.severity.toUpperCase()}] ${anomaly.type}`);
-	console.log(`  ${anomaly.message}`);
-});
+new SshClient(shell: VirtualShell, username: string)
 ```
 
-Detects:
-- High authentication failure rates
-- Excessive authentication failures
-- Unusual command execution volume
-- Unusual file write volume
+No password required — the client authenticates by username only.
+
+#### Methods
 
-##### `reset(): void`
+| Method | Description |
+|--------|-------------|
+| `exec(command): Promise<CommandResult>` | Run arbitrary raw command string (supports `&&`, `\|`, etc.). |
+| `ls(path?)` | List directory (default: cwd). |
+| `pwd()` | Print current working directory. |
+| `cd(path)` | Change directory. Updates internal cwd state on success. |
+| `cat(path)` | Read file content via `cat` command. |
+| `readFile(path)` | Read file directly from VFS (programmatic, no shell parse). |
+| `writeFile(path, content)` | Write file directly to VFS (programmatic). |
+| `mkdir(path, recursive?)` | Create directory. `recursive=true` adds `-p`. |
+| `touch(path)` | Create empty file. |
+| `rm(path, recursive?)` | Remove file or directory. `recursive=true` adds `-r`. |
+| `tree(path?)` | Render ASCII directory tree. |
+| `whoami()` | Print current user. |
+| `hostname()` | Print server hostname. |
+| `who()` | List active sessions. |
+| `getCwd(): string` | Returns current working directory (local, no I/O). |
+| `getUsername(): string` | Returns authenticated username. |
 
-Clears audit log and resets all statistics counters.
+**Example:**
 
 ```typescript
-honeypot.reset();  // Fresh start
-```
+const shell  = new VirtualShell("typescript-vm");
+const client = new SshClient(shell, "alice");
 
-#### Audit Log Entry Structure
+await client.mkdir("/home/alice/projects", true);
+await client.cd("/home/alice/projects");
 
-```typescript
-interface AuditLogEntry {
-	timestamp: string;              // ISO-8601 timestamp
-	type: string;                   // Event type (e.g., "auth:success", "file:write")
-	source: string;                 // Event source component
-	details: Record<string, unknown>; // Event-specific data
-}
-```
+console.log(client.getCwd());  // /home/alice/projects
+
+await client.writeFile("notes.txt", "Work in progress");
+const list = await client.ls();
+console.log(list.stdout);  // notes.txt
 
-#### Example Usage
+const read = await client.readFile("notes.txt");
+console.log(read.stdout);  // Work in progress
 
-See [Example 8: Security Auditing with HoneyPot](#example-8-security-auditing-with-honeypot) in Usage Examples.
+// Shell operators work in exec()
+const r = await client.exec("echo hello && echo world");
+console.log(r.stdout); // hello\nworld
+```
 
 ---
 
-### Demo: Standalone Version
+### Key Types
 
-To quickly try out a standalone version of the project, you can use the following command:
+#### `CommandResult`
 
-```bash
-curl -s https://raw.githubusercontent.com/itsrealfortune/typescript-virtual-container/refs/heads/main/standalone.js -o standalone.js && node standalone.js && rm -f standalone.js
+Returned by all command executions (shell or programmatic).
+
+```typescript
+interface CommandResult {
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number;
+  nextCwd?: string;
+  clearScreen?: boolean;
+  closeSession?: boolean;
+  switchUser?: string;
+  openEditor?: NanoEditorSession;
+  openHtop?: boolean;
+  sudoChallenge?: SudoChallenge;
+}
 ```
 
-This will:
-1. Download the standalone script.
-2. Execute it using Node.js.
-3. Clean up by removing the script after execution.
+#### `ShellEnv`
 
-Enjoy exploring the standalone features of the project!
+Per-session shell environment. Passed as `env` in `CommandContext`.
 
----
+```typescript
+interface ShellEnv {
+  vars: Record<string, string>;  // $VAR accessible in expansions
+  lastExitCode: number;          // $? value
+}
+```
 
-### Key Types
+Default variables initialized per session: `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `TERM`, `HOSTNAME`, `PS1`.
 
-#### CommandResult
+#### `ShellModule`
 
-Response from command execution (shell or programmatic).
+Contract for custom command plugins:
 
 ```typescript
-interface CommandResult {
-	stdout?: string;          // Standard output
-	stderr?: string;          // Standard error
-	exitCode?: number;        // Exit code (default: 0)
-	nextCwd?: string;         // Updated cwd (used by cd command)
-	clearScreen?: boolean;    // Request terminal clear
-	closeSession?: boolean;   // Request session close
-	switchUser?: string;      // User change request (su/sudo)
-	openEditor?: NanoEditorSession;  // Text editor launch
-	openHtop?: boolean;       // System monitor launch
-	sudoChallenge?: SudoChallenge;   // Sudo password challenge
+interface ShellModule {
+  name: string;
+  params: string[];
+  aliases?: string[];
+  description?: string;    // shown in grouped help
+  category?: string;       // navigation|files|text|archive|system|network|shell|users|misc
+  run: (ctx: CommandContext) => CommandResult | Promise<CommandResult>;
 }
-```
 
-#### VfsNodeStats
+interface CommandContext {
+  authUser: string;
+  hostname: string;
+  activeSessions: VirtualActiveSession[];
+  rawInput: string;
+  mode: "shell" | "exec";
+  args: string[];
+  stdin?: string;
+  cwd: string;
+  shell: VirtualShell;
+  env: ShellEnv;           // per-session environment (read/write)
+}
+```
 
-File/directory metadata.
+#### `VfsNodeStats`
 
 ```typescript
 type VfsNodeStats = VfsFileNode | VfsDirectoryNode;
 
 interface VfsFileNode {
-	type: "file";
-	name: string;
-	path: string;
-	mode: number;          // POSIX mode bits
-	size: number;          // Byte length
-	compressed: boolean;   // Is gzip compressed?
-	createdAt: Date;
-	updatedAt: Date;
+  type: "file";
+  name: string;
+  path: string;
+  mode: number;
+  size: number;
+  compressed: boolean;
+  createdAt: Date;
+  updatedAt: Date;
 }
 
 interface VfsDirectoryNode {
-	type: "directory";
-	name: string;
-	path: string;
-	mode: number;
-	childrenCount: number;
-	createdAt: Date;
-	updatedAt: Date;
+  type: "directory";
+  name: string;
+  path: string;
+  mode: number;
+  childrenCount: number;
+  createdAt: Date;
+  updatedAt: Date;
 }
 ```
 
-#### VirtualActiveSession
-
-Active SSH/programmatic session descriptor.
+#### `VirtualActiveSession`
 
 ```typescript
 interface VirtualActiveSession {
-	id: string;            // UUID
-	username: string;
-	tty: string;           // e.g., "pts/0"
-	remoteAddress: string; // Client IP or label
-	startedAt: string;     // ISO-8601 timestamp
+  id: string;
+  username: string;
+  tty: string;
+  remoteAddress: string;
+  startedAt: string;  // ISO-8601
+}
+```
+
+#### `VfsSnapshot`
+
+```typescript
+interface VfsSnapshot {
+  root: VfsSnapshotDirectoryNode;
 }
+// File nodes store content as base64 in contentBase64.
 ```
 
 ---
@@ -1238,434 +884,557 @@ interface VirtualActiveSession {
 
 ### Example 1: Basic SSH Server
 
-Minimal server startup that accepts SSH connections:
-
 ```typescript
 import { VirtualSshServer } from "typescript-virtual-container";
 
-const ssh = new VirtualSshServer({
-	port: 2222,
-	hostname: "lab-environment"
-});
-
+const ssh = new VirtualSshServer({ port: 2222, hostname: "lab-environment" });
 await ssh.start();
-console.log("SSH server ready. Connect via: ssh root@localhost -p 2222");
+console.log("SSH server ready. Connect: ssh root@localhost -p 2222");
 
-// Keep running (e.g., in cloud deployment)
-process.on("SIGINT", () => {
-	ssh.stop();
-	process.exit(0);
-});
+process.on("SIGINT", () => { ssh.stop(); process.exit(0); });
 ```
 
-**External SSH connection:**
-
 ```bash
 ssh root@localhost -p 2222
-# Password: root
 # $ whoami
 # root
-# $
 ```
 
 ---
 
 ### Example 2: Programmatic File Operations
 
-Create, read, modify files without SSH:
-
 ```typescript
-import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
+import { SshClient, VirtualShell, VirtualSshServer } from "typescript-virtual-container";
 
-const shell = new VirtualShell("typescript-vm");
-const ssh = new VirtualSshServer({ port: 2222, shell });
+const shell  = new VirtualShell("typescript-vm");
+const ssh    = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
 const client = new SshClient(shell, "root");
 
-// Create structure
 await client.mkdir("/app/config", true);
 await client.mkdir("/app/logs", true);
 
-// Write config
 await client.writeFile("/app/config/settings.json", JSON.stringify({
-	environment: "dev",
-	port: 8080,
-	debug: true
+  environment: "dev",
+  port: 8080,
+  debug: true,
 }, null, 2));
 
-// Read it back
 const result = await client.readFile("/app/config/settings.json");
 console.log("Config:", result.stdout);
 
-// List directory
-const list = await client.ls("/app");
-console.log(list.stdout);
-
-// Verify tree
-console.log(await client.tree("/app"));
+const tree = await client.tree("/app");
+console.log(tree.stdout);
 
 ssh.stop();
 ```
 
 ---
 
-### Example 3: Multi-User Environment
-
-Create users, manage permissions, session tracking:
+### Example 3: Multi-User Environment with Quotas
 
 ```typescript
-import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
+import { SshClient, VirtualShell, VirtualSshServer } from "typescript-virtual-container";
 
 const shell = new VirtualShell("typescript-vm");
-const ssh = new VirtualSshServer({ port: 2222, shell });
+const ssh   = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
 const users = ssh.getUsers()!;
 
-// Create users
 await users.addUser("alice", "alice123");
 await users.addUser("bob", "bob456");
-console.log("Created users: alice, bob");
 
-// Grant sudo to alice only
 await users.removeSudoer("bob");
-await users.addSudoer("alice");
+await users.setQuotaBytes("bob", 5 * 1024 * 1024); // 5 MB
 
-// Alice: High privilege
 const alice = new SshClient(shell, "alice");
 await alice.writeFile("/etc/important.conf", "secret=yes");
 
-// Bob: Regular user
 const bob = new SshClient(shell, "bob");
 const result = await bob.cat("/etc/important.conf");
-console.log("Bob read file:", result.stderr);
+console.log("Bob read file:", result.stderr); // permission denied
 
 ssh.stop();
 ```
 
 ---
 
-### Example 4: Persistent State
+### Example 4: Persistent State across Restarts
 
-Save filesystem state between runs:
+#### Memory mode (manual)
 
 ```typescript
-import { VirtualSshServer, VirtualShell } from "typescript-virtual-container";
+import { VirtualFileSystem } from "typescript-virtual-container";
+import { writeFileSync, readFileSync } from "node:fs";
 
-// First run: Initialize
-const shell1 = new VirtualShell("typescript-vm", undefined, "./container");
-const ssh1 = new VirtualSshServer({ 
-	port: 2222,
-	shell: shell1 
-});
-await ssh1.start();
-const vfs1 = ssh1.getVfs()!;
+const vfs = new VirtualFileSystem();
+vfs.writeFile("/data/report.txt", "Baseline data");
+
+writeFileSync("snapshot.json", JSON.stringify(vfs.toSnapshot()));
 
-vfs1.mkdir("/data", 0o777);
-vfs1.writeFile("/data/report.txt", "Baseline data");
-await vfs1.flushMirror();
-ssh1.stop();
+const snapshot = JSON.parse(readFileSync("snapshot.json", "utf8"));
+const restored = VirtualFileSystem.fromSnapshot(snapshot);
+console.log(restored.readFile("/data/report.txt")); // Baseline data
+```
 
-console.log("State available under ./container/.vfs/mirror");
+#### FS mode (automatic)
 
-// Later: Reload and continue
-const shell2 = new VirtualShell("typescript-vm", undefined, "./container");
-const ssh2 = new VirtualSshServer({ 
-	port: 2223,
-	shell: shell2 
-});
-await ssh2.start();
-const vfs2 = ssh2.getVfs()!;
-await vfs2.restoreMirror();
+```typescript
+import { VirtualShell, VirtualSshServer } from "typescript-virtual-container";
 
-const content = vfs2.readFile("/data/report.txt");
-console.log("Restored:", content);
+const shell = new VirtualShell("my-vm", undefined, {
+  mode: "fs",
+  snapshotPath: "./container-data",
+});
 
-ssh2.stop();
+const ssh = new VirtualSshServer({ port: 2222, shell });
+await ssh.start();
+process.on("SIGTERM", () => { ssh.stop(); process.exit(0); });
 ```
 
 ---
 
-### Example 5: CI/CD Automation
-
-Simulate filesystem changes and verify outcomes:
+### Example 5: Public-Key Authentication
 
 ```typescript
-import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
+import { VirtualShell, VirtualSshServer } from "typescript-virtual-container";
+import { readFileSync } from "node:fs";
+
+const shell = new VirtualShell("secure-vm");
+await shell.ensureInitialized();
 
-async function testDeployment() {
-	const shell = new VirtualShell("typescript-vm");
-	const ssh = new VirtualSshServer({ port: 2222, shell });
-	await ssh.start();
+await shell.users.addUser("alice", "fallback-password");
 
-	const client = new SshClient(shell, "root");
+const pubLine = readFileSync(`${process.env.HOME}/.ssh/id_ed25519.pub`, "utf8").trim();
+const [algo, b64] = pubLine.split(" ");
+shell.users.addAuthorizedKey("alice", algo, Buffer.from(b64, "base64"));
+
+const ssh = new VirtualSshServer({ port: 2222, shell });
+await ssh.start();
+// ssh -i ~/.ssh/id_ed25519 alice@localhost -p 2222
+```
 
-	// Pre-deployment: Set up base structure
-	await client.mkdir("/srv/app", true);
-	await client.writeFile("/srv/app/package.json", '{"name":"myapp"}');
+---
 
-	// Simulate deployment: Write new version
-	await client.writeFile("/srv/app/app.js", 'console.log("v2.0");');
+### Example 6: Rate Limiting
 
-	// Verify deployment: Read and validate
-	const appContent = await client.readFile("/srv/app/app.js");
-	if (appContent.stdout.includes("v2.0")) {
-		console.log("✓ Deployment verified");
-	} else {
-		console.error("✗ Deployment failed");
-	}
+```typescript
+const ssh = new VirtualSshServer({
+  port: 2222,
+  maxAuthAttempts: 3,
+  lockoutDurationMs: 300_000,
+});
 
-	ssh.stop();
-}
+ssh.on("auth:lockout", ({ ip, until }) => {
+  console.warn(`[SSH] ${ip} locked until ${until}`);
+});
 
-testDeployment().catch(console.error);
+ssh.clearLockout("192.168.1.100"); // manual override
 ```
 
 ---
 
-### Example 6: Complex Navigation
+### Example 7: Shell Operators and Variables
+
+```typescript
+import { SshClient, VirtualShell } from "typescript-virtual-container";
+
+const shell  = new VirtualShell("typescript-vm");
+await shell.ensureInitialized();
+const client = new SshClient(shell, "root");
+
+// && and || operators
+await client.exec("mkdir /tmp/test && echo created || echo failed");
+
+// Chaining with ;
+await client.exec("echo a; echo b; echo c");
+
+// Variable expansion via export then use
+await client.exec("export GREETING=hello");
+await client.exec("echo $GREETING world");  // hello world
+
+// $? last exit code
+await client.exec("false; echo exit=$?");   // exit=1
 
-Simulate shell workflows:
+// Piping
+const r = await client.exec("echo -e 'banana\\napple\\ncherry' | sort");
+console.log(r.stdout); // apple\nbanana\ncherry
+```
+
+---
+
+### Example 8: .bashrc
 
 ```typescript
-import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
+import { VirtualShell, VirtualSshServer } from "typescript-virtual-container";
 
 const shell = new VirtualShell("typescript-vm");
+await shell.ensureInitialized();
+
+// Write a .bashrc for the root user
+shell.vfs.mkdir("/home/root", 0o755);
+shell.vfs.writeFile("/home/root/.bashrc", `
+export PS1="\\u@\\h:\\w\\$ "
+export EDITOR=nano
+export PATH="/usr/local/bin:/usr/bin:/bin"
+alias ll="ls -l"
+echo "Welcome back, root!"
+`.trim());
+
 const ssh = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
+// On interactive login, .bashrc is sourced automatically.
+// "Welcome back, root!" is printed, and $EDITOR is set in the session.
+```
 
-const client = new SshClient(shell, "root");
+---
 
-// Create nested structure
-await client.mkdir("/home/user/projects/myapp/src", true);
-await client.cd("/home/user/projects");
+### Example 9: Shell Scripting
 
-console.log(client.getCwd());  // "/home/user/projects"
+```typescript
+import { SshClient, VirtualShell } from "typescript-virtual-container";
+
+const shell  = new VirtualShell("typescript-vm");
+await shell.ensureInitialized();
+const client = new SshClient(shell, "root");
 
-// Navigate deeper
-await client.cd("myapp/src");
-console.log(client.getCwd());  // "/home/user/projects/myapp/src"
+// Write a script to VFS
+shell.vfs.writeFile("/usr/local/bin/setup.sh", `
+#!/bin/sh
+for dir in config logs tmp; do
+  mkdir /app/$dir
+  echo "Created /app/$dir"
+done
+if [ -d /app/config ]; then
+  echo "Setup complete"
+else
+  echo "Setup failed"
+fi
+`);
+
+// Execute it
+const r = await client.exec("sh /usr/local/bin/setup.sh");
+console.log(r.stdout);
+// Created /app/config
+// Created /app/logs
+// Created /app/tmp
+// Setup complete
+```
 
-// Create files in new location
-await client.writeFile("main.ts", "export function main() {}");
-await client.writeFile("utils.ts", "export function util() {}");
+---
 
-// List current
-const srcFiles = await client.ls();
-console.log(srcFiles.stdout);  // main.ts, utils.ts
+### Example 10: Snapshot-Based Test Fixtures
 
-// Navigate up (relative paths)
-await client.cd("..");
-console.log(client.getCwd());  // "/home/user/projects/myapp"
+```typescript
+import { VirtualFileSystem } from "typescript-virtual-container";
+import type { VfsSnapshot } from "typescript-virtual-container";
 
-const appTree = await client.tree();
-console.log(appTree.stdout);
+function buildFixture(): VfsSnapshot {
+  const vfs = new VirtualFileSystem();
+  vfs.mkdir("/app/config");
+  vfs.writeFile("/app/config/settings.json", JSON.stringify({ env: "test" }));
+  vfs.writeFile("/app/README.md", "# My App");
+  return vfs.toSnapshot();
+}
 
-ssh.stop();
+const FIXTURE = buildFixture();
+
+test("reads config file", () => {
+  const vfs = VirtualFileSystem.fromSnapshot(FIXTURE);
+  const content = JSON.parse(vfs.readFile("/app/config/settings.json"));
+  expect(content.env).toBe("test");
+});
 ```
 
 ---
 
-### Example 7: Error Handling
+### Example 11: Symlinks
+
+```typescript
+const vfs = new VirtualFileSystem();
+vfs.mkdir("/usr/local/bin");
+vfs.writeFile("/opt/myapp/bin/app", "#!/bin/sh\necho hello");
+vfs.symlink("/opt/myapp/bin/app", "/usr/local/bin/app");
+
+console.log(vfs.isSymlink("/usr/local/bin/app"));     // true
+console.log(vfs.resolveSymlink("/usr/local/bin/app")); // /opt/myapp/bin/app
+```
+
+---
 
-Graceful error handling in programmatic workflows:
+### Example 12: Security Auditing with HoneyPot
 
 ```typescript
-import { VirtualSshServer, SshClient, VirtualShell } from "typescript-virtual-container";
+import { HoneyPot, SshClient, VirtualShell, VirtualSshServer } from "typescript-virtual-container";
 
 const shell = new VirtualShell("typescript-vm");
-const ssh = new VirtualSshServer({ port: 2222, shell });
+const ssh   = new VirtualSshServer({ port: 2222, shell });
 await ssh.start();
 
-const client = new SshClient(shell, "root");
+const hp = new HoneyPot(5000);
+hp.attach(shell, shell.vfs, shell.users, ssh);
 
-// Try read non-existent file
-const result = await client.readFile("/etc/nonexistent.conf");
-if (result.exitCode !== 0) {
-	console.error("Read error:", result.stderr);
-}
+const alice = new SshClient(shell, "alice");
+await alice.mkdir("/home/alice/projects", true);
+await alice.writeFile("/home/alice/projects/app.txt", "My application");
 
-// Try change to non-existent directory
-const cdResult = await client.cd("/invalid/path");
-if (cdResult.exitCode !== 0) {
-	console.error("Invalid path");
-}
+const stats = hp.getStats();
+console.log(`Commands run: ${stats.commands}`);
+console.log(`File writes:  ${stats.fileWrites}`);
+
+hp.detectAnomalies().forEach(a =>
+  console.log(`[${a.severity.toUpperCase()}] ${a.type}: ${a.message}`)
+);
 
-// Try remove root
-const rmResult = await client.rm("/", true);
-console.log("Remove root:", rmResult.stderr);  // Error
+const authFailures = hp.getAuditLog("auth:failure");
+const sshEvents    = hp.getAuditLog(undefined, "SshMimic");
+console.log(`Auth failures: ${authFailures.length}`);
+console.log(`SSH events:    ${sshEvents.length}`);
 
 ssh.stop();
 ```
 
 ---
 
-### Example 8: Security Auditing with HoneyPot
+### Example 13: Error Handling
+
+```typescript
+const client = new SshClient(shell, "root");
+
+const r1 = await client.readFile("/etc/nonexistent.conf");
+if (r1.exitCode !== 0) console.error("Read error:", r1.stderr);
+
+const r2 = await client.cd("/invalid/path");
+if (r2.exitCode !== 0) console.error("cd failed");
+
+const r3 = await client.rm("/", true);
+console.log("Remove root:", r3.stderr); // Cannot remove root directory.
+```
+
+---
 
-Track all system activity, detect anomalies, and maintain security audit logs:
+### Example 14: Concurrent Clients
 
 ```typescript
-import {
-	VirtualSshServer,
-	VirtualShell,
-	SshClient,
-	HoneyPot,
-} from "typescript-virtual-container";
+const shell   = new VirtualShell("typescript-vm");
+const client1 = new SshClient(shell, "alice");
+const client2 = new SshClient(shell, "bob");
 
-const shell = new VirtualShell("typescript-vm");
-const ssh = new VirtualSshServer({ port: 2222, shell });
-await ssh.start();
+const [r1, r2] = await Promise.all([
+  client1.writeFile("/tmp/alice.txt", "Alice's data"),
+  client2.writeFile("/tmp/bob.txt",   "Bob's data"),
+]);
+```
 
-const users = ssh.getUsers()!;
-const vfs = ssh.getVfs()!;
+---
 
-// Initialize honeypot with 5000-entry log limit
-const honeypot = new HoneyPot(5000);
-honeypot.attach(shell, vfs, users, ssh);
+## Built-in Commands
 
-// Create users
-await users.addUser("alice", "alice123");
-await users.addUser("bob", "bob456");
+All commands are available in SSH shell mode and via `SshClient.exec()`. Type `help` in the shell for a grouped, colorized listing. Type `help <command>` for detailed usage.
+
+### Navigation
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `cd <path>` | | Change directory |
+| `ls [path]` | `-l` | List directory contents |
+| `pwd` | | Print working directory |
+| `tree [path]` | | ASCII directory tree |
+
+### Files & Filesystem
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `cat <path>` | | Print file contents |
+| `chmod <mode> <file>` | | Change file permissions (octal) |
+| `cp <src> <dest>` | `-r` | Copy file or directory |
+| `find [path]` | `-name <pat>` `-type f\|d` | Search for files |
+| `ln <target> <link>` | `-s` | Create hard or symbolic link |
+| `mkdir <path>` | `-p` | Create directory |
+| `mv <src> <dest>` | | Move or rename |
+| `rm <path>` | `-r` | Remove file or directory |
+| `touch <path>` | | Create or update file |
+
+### Text Processing
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `awk [-F <sep>] '<prog>'` | | Pattern scanning (print $N) |
+| `cut` | `-d <sep>` `-f <cols>` | Remove sections from lines |
+| `diff <f1> <f2>` | | Compare files line by line |
+| `grep <pattern> [files]` | `-i` `-v` `-n` `-r` | Search file content |
+| `head [files]` | `-n <N>` | First N lines (default 10) |
+| `sed -e 's/pat/rep/[g]'` | `-i` | Stream editor |
+| `sort [files]` | `-r` `-n` `-u` | Sort lines |
+| `tail [files]` | `-n <N>` | Last N lines (default 10) |
+| `tee [files]` | `-a` | Read stdin, write to stdout and files |
+| `tr <set1> [set2]` | `-d` | Translate or delete characters |
+| `uniq` | `-c` `-d` `-u` | Filter repeated lines |
+| `wc [files]` | `-l` `-w` `-c` | Word/line/byte count |
+| `xargs [cmd]` | | Build and execute commands from stdin |
+
+### Archive & Compression
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `base64` | `-d` | Encode/decode base64 |
+| `gzip <file>` | | Compress file |
+| `gunzip <file>` | | Decompress file |
+| `tar <archive> [files]` | `-czf` `-xzf` `-tf` | Archive utility |
+
+### System
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `date` | `+format` | Print current date and time |
+| `df` | `-h` | Filesystem disk space usage |
+| `du [path]` | `-h` `-s` | Estimate file space usage |
+| `groups [user]` | | Print group memberships |
+| `hostname` | | Print hostname |
+| `htop` | | System monitor (mock) |
+| `id [user]` | | Print user identity (uid/gid/groups) |
+| `kill [-9] <pid>` | | Send signal to process (mock) |
+| `neofetch` | | System info display (mock) |
+| `ping [-c <n>] <host>` | | Send ICMP ECHO_REQUEST (mock) |
+| `ps` | `-a` `-u` `-x` | Report process status |
+| `sleep <seconds>` | | Delay execution |
+| `uname` | `-a` `-r` `-m` | Print system information |
+| `who` | | List active sessions |
+| `whoami` | | Print current user |
+
+### Network
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `curl <url>` | | HTTP client (delegates to host binary) |
+| `wget <url>` | | File downloader (delegates to host binary) |
+
+### Shell
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `clear` | | Clear terminal screen (full ANSI reset) |
+| `echo <text>` | | Display text |
+| `env` | | Print session environment variables |
+| `exit [code]` | | Exit session |
+| `export NAME=VALUE` | | Set shell variable in current session |
+| `help [command]` | | List commands (grouped) or show command details |
+| `set [VAR=val]` | | Display or set shell variables |
+| `sh` | `-c <script>` `[file]` | Execute shell script (supports if/for/while) |
+| `unset <VAR>` | | Remove shell variable |
+
+### Users & Permissions
+
+| Command | Flags | Description |
+|---------|-------|-------------|
+| `adduser <name> <pass>` | | Create user (root only) |
+| `deluser <name>` | | Delete user (root only) |
+| `nano <path>` | | Interactive text editor |
+| `passwd [user]` | | Change password |
+| `su [user]` | | Switch user |
+| `sudo <cmd>` | `-i` | Run as root |
+
+Custom commands can be added via `shell.addCommand()`.
 
-// Simulate activity
-const alice = new SshClient(shell, "alice");
-await alice.mkdir("/home/alice/projects", true);
-await alice.writeFile("/home/alice/projects/app.txt", "My application");
-await alice.ls("/home/alice/projects");
+---
 
-const bob = new SshClient(shell, "bob");
-// Bob tries invalid operations
-await bob.readFile("/etc/shadow");  // Will fail
-await bob.writeFile("/etc/passwd", "hacked");  // Will fail
-
-// Collect stats
-const stats = honeypot.getStats();
-console.log("\n=== Activity Summary ===");
-console.log(`Auth attempts: ${stats.authAttempts}`);
-console.log(`Auth successes: ${stats.authSuccesses}`);
-console.log(`Auth failures: ${stats.authFailures}`);
-console.log(`Commands executed: ${stats.commands}`);
-console.log(`File writes: ${stats.fileWrites}`);
-console.log(`File reads: ${stats.fileReads}`);
-console.log(`Sessions active: ${stats.sessionStarts}`);
-console.log(`Users created: ${stats.userCreated}`);
-
-// Get recent events
-console.log("\n=== Last 5 Events ===");
-honeypot.getRecent(5).forEach((entry) => {
-	console.log(`[${entry.timestamp}] ${entry.source} -> ${entry.type}`);
-	console.log(`  Details: ${JSON.stringify(entry.details, null, 2)}`);
-});
+## Shell Scripting
 
-// Detect anomalies
-console.log("\n=== Security Analysis ===");
-const anomalies = honeypot.detectAnomalies();
-if (anomalies.length > 0) {
-	anomalies.forEach((anomaly) => {
-		console.log(
-			`[${anomaly.severity.toUpperCase()}] ${anomaly.type}: ${anomaly.message}`,
-		);
-	});
-} else {
-	console.log("No anomalies detected");
-}
+The shell interpreter supports a subset of POSIX sh syntax, usable both interactively and via `sh -c '...'` or `sh <file>`.
 
-// Filter audit log by event type
-console.log("\n=== Auth Failures ===");
-const authFailures = honeypot.getAuditLog("auth:failure");
-authFailures.forEach((entry) => {
-	console.log(
-		`  ${entry.details.username} from ${entry.details.remoteAddress}`,
-	);
-});
+### Logical Operators
 
-// Filter by source component
-console.log("\n=== All SSH Events ===");
-const sshEvents = honeypot.getAuditLog(undefined, "SshMimic");
-console.log(`  Total SSH events: ${sshEvents.length}`);
+```bash
+mkdir /app && echo "created"       # run second only if first succeeds
+rm /missing || echo "not found"    # run second only if first fails
+echo a; echo b; echo c             # always run all three
+```
 
-// Export full audit log (for external storage/analysis)
-const fullAuditLog = honeypot.getAuditLog();
-console.log(`\nTotal audit entries: ${fullAuditLog.length}`);
+### Pipes and Redirections
+
+```bash
+cat /etc/hosts | grep local
+ls /home | sort | head -5
+echo "hello world" > /tmp/out.txt
+cat /tmp/out.txt >> /tmp/log.txt
+```
 
-// Optional: Reset for next test phase
-// honeypot.reset();
+### Variable Expansion
 
-ssh.stop();
+```bash
+export NAME=world
+echo "Hello $NAME"           # Hello world
+echo "${NAME:-fallback}"     # world (or fallback if unset)
+echo "${UNSET:-default}"     # default
+echo "Exit: $?"              # last exit code
 ```
 
-**Output example:**
+### Conditionals
+
+```bash
+if [ -f /etc/config ]; then
+  echo "config exists"
+elif [ -d /etc ]; then
+  echo "etc is a directory"
+else
+  echo "nothing found"
+fi
+
+# String comparison
+if [ "$USER" = "root" ]; then echo "root"; fi
 
+# Numeric comparison
+if [ $COUNT -gt 10 ]; then echo "large"; fi
 ```
-[AUDIT] 2026-04-16T10:30:45.123Z | SshMimic | start { port: 2222 }
-[AUDIT] 2026-04-16T10:30:46.234Z | VirtualUserManager | user:add { username: 'alice' }
-[AUDIT] 2026-04-16T10:30:47.345Z | VirtualUserManager | user:add { username: 'bob' }
-[AUDIT] 2026-04-16T10:30:48.456Z | VirtualShell | command { command: 'mkdir /home/alice/projects', user: 'alice', cwd: '/home/alice' }
-[AUDIT] 2026-04-16T10:30:49.567Z | VirtualFileSystem | dir:create { path: '/home/alice/projects', mode: 16877 }
-[AUDIT] 2026-04-16T10:30:50.678Z | VirtualShell | command { command: 'writeFile /home/alice/projects/app.txt', user: 'alice', cwd: '/home/alice' }
-
-=== Activity Summary ===
-Auth attempts: 2
-Auth successes: 2
-Auth failures: 0
-Commands executed: 8
-File writes: 1
-File reads: 2
-Sessions active: 2
-Users created: 2
-
-=== Last 5 Events ===
-[2026-04-16T10:30:50.678Z] VirtualShell -> command
-  Details: { command: 'ls /home/alice/projects', user: 'alice', cwd: '/home/alice/projects' }
-
-=== Security Analysis ===
-No anomalies detected
-
-=== All SSH Events ===
-  Total SSH events: 4
+
+### Loops
+
+```bash
+# for loop
+for name in alice bob charlie; do
+  echo "Hello $name"
+done
+
+# while loop
+COUNT=0
+while [ $COUNT -lt 3 ]; do
+  echo "Count: $COUNT"
+  export COUNT=$((COUNT + 1))
+done
 ```
 
----
+### Script Files
 
-## Built-in Commands
+Write a script to the VFS and execute it:
 
-The following commands are currently registered and available in both SSH shell mode and via `SshClient.exec()`. Some flags and edge-case behavior are still being expanded for shell compatibility.
-
-| Command | Purpose | Notes |
-|---------|---------|-------|
-| `adduser <name> <pass>` | Create user | Root only |
-| `cat <path>` | Read file | Displays content |
-| `cd <path>` | Change directory | Updates client cwd |
-| `clear` | Clear screen | No args |
-| `curl <url>` | Fetch URL | Mock implementation |
-| `deluser <name>` | Delete user | Root only, not root |
-| `echo <text...>` | Print text | Supports shell-like argument output |
-| `env` | List environment variables | Shell environment view |
-| `exit [code]` | Close session | Optional exit code |
-| `export NAME=VALUE` | Set/export environment variable | Persists in shell env |
-| `grep <pattern> [path]` | Search for text | Simplified grep behavior |
-| `help` | List commands | No args |
-| `hostname` | Server hostname | No args |
-| `htop` | System monitor | Mock display |
-| `pwd` | Print working directory | No args |
-| `ls [path]` | List directory | Defaults to `.` |
-| `mkdir [-p] <path>` | Create directory | `-p` for parents |
-| `nano <path>` | Text editor | Interactive mode |
-| `neofetch` | Show system summary | Mock display |
-| `touch <path>` | Create empty file | Updates timestamps |
-| `rm [-r] <path>` | Remove file/dir | `-r` for recursive |
-| `set` | Show shell options/variables | Simplified behavior |
-| `sh <script>` | Run shell script | Simplified execution model |
-| `su <user>` | Switch user | Requires password/sudo |
-| `sudo [-i] <cmd>` | Elevation | Requires sudoer status |
-| `tree [path]` | ASCII tree view | Defaults to `.` |
-| `unset <name>` | Remove environment variable | Shell environment update |
-| `wget <url>` | Download | Mock implementation |
-| `who` | Active sessions | No args |
-| `whoami` | Current user | No args |
-
-Commands can be added via the VirtualShell addCommand() method for custom behavior.
+```bash
+# Via SSH shell:
+nano /usr/local/bin/deploy.sh
+# ... write the script ...
+sh /usr/local/bin/deploy.sh
+
+# Via programmatic client:
+await client.writeFile("/usr/local/bin/setup.sh", `
+for dir in config logs tmp; do
+  mkdir /app/$dir
+done
+`);
+await client.exec("sh /usr/local/bin/setup.sh");
+```
+
+### .bashrc
+
+On every interactive SSH login, `/home/<user>/.bashrc` is sourced automatically. Use it to set environment variables, aliases (via `sh -c`), or print a welcome message.
+
+```bash
+# /home/alice/.bashrc
+export EDITOR=nano
+export PATH="/usr/local/bin:/usr/bin:/bin"
+echo "Welcome, Alice!"
+```
 
 ---
 
@@ -1673,28 +1442,46 @@ Commands can be added via the VirtualShell addCommand() method for custom behavi
 
 ### Environment Variables
 
-- **`SSH_MIMIC_HOSTNAME`**: Override server hostname at startup (default: "typescript-vm")
-- **`SSH_MIMIC_AUTO_SUDO_NEW_USERS`**: Control whether new users are added to sudoers automatically (default: enabled). Set to `0`, `false`, `no`, or `off` to disable.
-
-**Note:** By default, no password is set for the root user or any new users during the first initialization. Ensure to configure user passwords manually if required.
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SSH_MIMIC_FAST_PASSWORD_HASH` | `""` | Use SHA-256 instead of scrypt (faster, less secure — dev only). Set to `1` or `true`. |
+| `SSH_MIMIC_AUTO_SUDO_NEW_USERS` | `"true"` | Auto-grant sudo to new users. Set to `0`, `false`, `no`, or `off` to disable. |
+| `DEV_MODE` | `""` | Enable performance logging. |
+| `RENDER_PERF` | `""` | Enable render performance logging. |
 
 **Example:**
 
 ```bash
-export SSH_MIMIC_HOSTNAME=production-lab
+export SSH_MIMIC_FAST_PASSWORD_HASH=1
 export SSH_MIMIC_AUTO_SUDO_NEW_USERS=false
-npm run start
+node server.js
 ```
 
-### Runtime Options
+### Runtime Options Summary
 
 ```typescript
-const shell = new VirtualShell("my-container", undefined, "./data");
-const ssh = new VirtualSshServer({
-	port: 2222,                    // Required
-	hostname: "my-container",      // Optional
-	shell                          // Optional, prebuilt shell instance
-});
+// VirtualShell
+new VirtualShell(
+  hostname,
+  properties?,          // kernel, os, arch strings
+  vfsOptions?,          // { mode: "memory"|"fs", snapshotPath?: string }
+)
+
+// VirtualSshServer
+new VirtualSshServer({
+  port,
+  hostname?,
+  shell?,
+  maxAuthAttempts?,     // default: 5
+  lockoutDurationMs?,   // default: 60_000
+})
+
+// VirtualSftpServer
+new VirtualSftpServer({
+  port,
+  hostname?,
+  shell?,               // or: vfs + users separately
+})
 ```
 
 ---
@@ -1703,43 +1490,41 @@ const ssh = new VirtualSshServer({
 
 ### Benchmarking
 
-Use the built-in benchmark script to measure initialization and command throughput under concurrent shell loads:
+Use the built-in benchmark script:
 
 ```bash
 bun ./benchmark-virtualshell.ts
 ```
 
 The benchmark reports:
-
-- shell initialization time by concurrency level
-- command execution time across all active shells
+- Shell initialization time by concurrency level
+- Command execution time across active shells
 - RSS memory growth during the run
 
-Recent baseline runs show strong startup behavior up to 100 concurrent shells, and the runtime is designed to scale up to **1000 environments very easily** for testing and automation workloads.
+Recent baselines show strong startup behavior up to 100 concurrent shells. The runtime is designed to scale easily to **1000+ parallel environments** for testing and automation workloads.
 
 ### Concurrency
 
-- SSH server handles multiple concurrent connections (event-driven)
-- Programmatic `SshClient` is synchronous (executes sequentially per instance)
-- Create multiple client instances for parallel operations
-- Horizontal shell instantiation (`new VirtualShell(...)`) is intended for high-volume scenarios, including large test matrices and multi-tenant simulation batches
+- SSH server is event-driven and handles multiple concurrent connections.
+- `SshClient` is sequential per instance — create multiple instances for parallel operations.
+- Each `VirtualShell` instance is fully independent (separate VFS, users, env state).
 
-### Scalability Notes
+### Performance Tips
 
-- Use a dedicated `basePath` per isolated environment to parallelize safely
-- Reuse long-lived shell instances when you need low-latency command bursts
-- Keep performance logging enabled in development (`DEV_MODE=1` or `RENDER_PERF=1`) to locate hotspots quickly
+- Use `SSH_MIMIC_FAST_PASSWORD_HASH=1` in test environments to skip scrypt overhead.
+- Reuse long-lived shell instances for low-latency command bursts.
+- Keep `DEV_MODE=1` enabled only during development (adds logging overhead).
 
-**Example:**
+**Parallel clients example:**
 
 ```typescript
-const shell = new VirtualShell("typescript-vm");
+const shell   = new VirtualShell("typescript-vm");
 const client1 = new SshClient(shell, "alice");
 const client2 = new SshClient(shell, "bob");
 
-const [result1, result2] = await Promise.all([
-	client1.writeFile("/tmp/alice.txt", "..."),
-	client2.writeFile("/tmp/bob.txt", "...")
+const [r1, r2] = await Promise.all([
+  client1.writeFile("/tmp/alice.txt", "..."),
+  client2.writeFile("/tmp/bob.txt",   "..."),
 ]);
 ```
 
@@ -1751,145 +1536,177 @@ Full TypeScript support with exported types:
 
 ```typescript
 import type {
-	CommandResult,
-	VirtualActiveSession,
-	VfsNodeStats,
-	VfsFileNode,
-	VfsDirectoryNode,
-	SudoChallenge
+  // Persistence
+  VfsOptions,
+  VfsPersistenceMode,
+  // Filesystem
+  VfsSnapshot,
+  VfsNodeStats,
+  VfsFileNode,
+  VfsDirectoryNode,
+  WriteFileOptions,
+  RemoveOptions,
+  // Commands
+  CommandContext,
+  CommandResult,
+  CommandMode,
+  CommandOutcome,
+  ShellModule,
+  ShellEnv,
+  SudoChallenge,
+  NanoEditorSession,
+  // Audit
+  AuditLogEntry,
+  HoneyPotStats,
+  // Streams
+  ShellStream,
+  ExecStream,
 } from "typescript-virtual-container";
-
-async function processResult(r: CommandResult) {
-	if (r.exitCode === 0 && r.stdout) {
-		console.log("Success:", r.stdout);
-	} else if (r.stderr) {
-		console.error("Error:", r.stderr);
-	}
-}
 ```
 
 ---
 
 ## FAQ
 
-### Is this a real container runtime?
-
-No. It emulates SSH sessions, users, and filesystem behavior in a virtual runtime. It is ideal for testing, simulations, and automation workflows where full OS isolation is not required.
-
-### Can I use this in production?
+**Is this a real container runtime?**
+No. It emulates SSH sessions, users, and filesystem behavior in a virtual runtime. Ideal for testing, simulations, and automation where full OS isolation is not required.
 
-You can use it in production-like automation contexts (sandboxed command runners, test harnesses, training environments), but it is not a security boundary like a real container/VM. And at the moment, all commands are not implemented with full fidelity, so it may not be suitable for all production use cases.
+**Can I use this in production?**
+You can use it in production-like automation contexts (sandboxed command runners, test harnesses, training environments, honeypots). It is not a security boundary like a real container/VM.
 
-### Does data persist between restarts?
+**Does the VFS touch the host filesystem?**
+In the default `"memory"` mode: no, all data lives in memory. In `"fs"` mode, it reads/writes a single JSON file (`vfs-snapshot.json`) inside the configured `snapshotPath` directory. No other host paths are accessed.
 
-Yes, when using a stable `basePath`. Files are stored under `.vfs/mirror`.
+**Does data persist between restarts?**
+Only if you explicitly use `"fs"` mode or call `toSnapshot()` / `fromSnapshot()` manually. Memory mode is ephemeral.
 
-### Is networking fully implemented for curl/wget?
+**Can I run multiple isolated shells?**
+Yes. Each `new VirtualShell(...)` creates a completely independent VFS, user manager, and shell environment.
 
-`curl` and `wget` are command-layer implementations intended for realistic workflows, not full parity with GNU tooling.
+**Are custom commands shared between shell instances?**
+No. Custom commands registered with `shell.addCommand()` are instance-local.
 
-### Can I create custom commands?
+**Does the shell support `&&`, `||`, and `;`?**
+Yes. The shell parser handles logical operators, pipes, and redirections. `if`/`elif`/`else`/`fi`, `for`/`do`/`done`, and `while`/`do`/`done` are supported in scripts.
 
-Yes. Commands are modular and can be extended in the command runtime layer to fit project-specific use cases.
+**Does `.bashrc` work?**
+Yes. When an interactive SSH session starts, `/home/<user>/.bashrc` is loaded automatically and each non-comment line is executed in the session environment.
 
----
-
-## Troubleshooting
-
-### Port Already in Use
+**Is networking fully implemented for curl/wget?**
+`curl` and `wget` delegate to the host binaries. They are intended for realistic workflows, not full GNU tooling parity.
 
-```
-Error: listen EADDRINUSE :::2222
-```
+**Can I create custom commands?**
+Yes — use `shell.addCommand()` or implement the `ShellModule` interface directly. Set `description` and `category` to appear in the grouped `help` output.
 
-**Solution**: Use a different port
-
-```typescript
-const ssh = new VirtualSshServer({ port: 3333 });
-```
+**Is SFTP fully supported?**
+Core SFTP operations (open, read, write, stat, mkdir, remove, rename) are implemented. Some optional operations (extended attributes, symlinks) return `OP_UNSUPPORTED`.
 
-### SSH Authentication Failed
+**Can I use this for honeypot deployments?**
+Yes — that is one of its primary use-cases. Use `HoneyPot.attach()` to capture all activity, configure `maxAuthAttempts` to throttle scanners, and export audit logs on shutdown.
 
-**Causes**: Server not started, wrong password, SSH client not found
+---
 
-**Solution**:
+## Troubleshooting
 
-```typescript
-process.env.SSH_MIMIC_ROOT_PASSWORD = "your-password";
-await ssh.start();
-```
+**`Error: listen EADDRINUSE :::2222`**
+The port is already in use. Use a different port or stop the existing process.
 
-### File Not Found Errors
+**SSH authentication always fails**
+Check the password (root has no password by default). If you set a password, verify it with `users.verifyPassword(username, password)`. Check if the IP is rate-limited: call `ssh.clearLockout(ip)`.
 
-**Cause**: Directory doesn't exist
+**Auth always fails with "lockout"**
+Call `ssh.clearLockout(ip)` or increase `maxAuthAttempts`. In tests, use `maxAuthAttempts: Infinity`.
 
-**Solution**: Create directories first
+**`Error: Too many levels of symbolic links`**
+A symlink chain exceeds 8 hops. Check for circular links or pass a larger `maxDepth` to `resolveSymlink()`.
 
-```typescript
-const vfs = ssh.getVfs();
-vfs.mkdir("/home/alice", 0o755);
-```
+**`Command 'xyz' not found` (exit code 127)**
+The command is not registered. Register it with `shell.addCommand()`.
 
-### Filesystem State Not Persisted
+**Shell scripting — `if` block not working**
+Ensure each keyword is on its own line or separated by `;`. The interpreter does not support complex one-liners like `if condition; then cmd; fi` as a single string passed to `sh -c` — split by line or use semicolons.
 
-**Cause**: `flushMirror()` not called
+**File not found errors**
+Create the parent directory first with `vfs.mkdir(path, 0o755)`.
 
-**Solution**:
+**`snapshotPath` is required error**
+You set `mode: "fs"` without providing `snapshotPath`: `new VirtualFileSystem({ mode: "fs", snapshotPath: "./data" })`.
 
-```typescript
-await ssh.getVfs().flushMirror();
-```
+**Variables not persisting between `exec()` calls**
+Each `SshClient.exec()` call shares the same `ShellEnv` object per shell instance. Variables set via `export` in one exec call are visible in the next. If you need full isolation, create a new `SshClient` instance.
 
 ---
 
 ## Contributing
 
-1. Fork repository
-2. Create feature branch: `git checkout -b feat/my-feature`
-3. Make changes and add tests
-4. Format & lint: `bun format && bun check`
-5. Push and open PR
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make changes and add tests.
+4. Format and lint: `bun format && bun check`
+5. Push and open a PR.
 
-**Code Quality**:
-- Biome formatting (opinionated)
-- Full TypeScript (no `any`)
-- JSDoc comments on public API
-- Async/await (no callbacks)
+**Code quality standards:**
+- Biome formatting (opinionated, enforced by CI)
+- Full TypeScript — no `any`
+- JSDoc comments on all public API surface
+- Async/await throughout — no callbacks
+- Tests for new commands and VFS behavior
+- New commands must include `description` and `category` fields for `help`
 
 ---
 
 ## Security
 
-- Passwords are hashed with `scrypt` in the virtual auth store.
-- Root account is always protected and cannot be deleted.
-- Sudo privileges are explicit and persisted in sudoers data.
-- Protect the root password in production by setting `SSH_MIMIC_ROOT_PASSWORD`; otherwise startup logs a generated ephemeral password.
-- Disable `SSH_MIMIC_AUTO_SUDO_NEW_USERS` when you want newly created users to stay unprivileged by default.
-- This project is not intended to provide kernel-level or process-level isolation.
+- Passwords are hashed with `scrypt` by default (N=32768, r=8, p=1), with a random per-user salt.
+- Root account always exists and cannot be deleted.
+- Sudo privileges are explicit and stored in the VFS under `/virtual-env-js/.auth/sudoers`.
+- Per-IP rate limiting prevents automated brute-force attacks on the SSH server.
+- This project does **not** provide kernel-level or process-level isolation.
+- Do **not** expose a running instance to the public internet without understanding the risks.
 
-If you discover a vulnerability, avoid public disclosure in issues and contact maintainers privately first.
+If you discover a vulnerability, avoid public disclosure in GitHub Issues. Contact maintainers privately first — see `SECURITY.md`.
 
 ---
 
 ## Support
 
 - Open an issue for bugs, regressions, or feature requests.
-- Include Node/Bun version, package version, and a minimal reproduction.
-- For API questions, include the exact command sequence and expected vs actual result.
+- Include your Node.js/Bun version, package version, and a minimal reproduction.
+- For API questions, include the exact call sequence plus expected vs. actual behavior.
 
 ---
 
 ## License
 
-MIT License. See LICENSE file for details.
+MIT — see [LICENSE](./LICENSE).
 
 ---
 
 ## Roadmap
 
 - [x] Custom command plugin API
-- [x] Optional per-user quotas for virtual filesystem usage
-- [x] Improved shell compatibility for complex piping and redirection
-- [ ] Snapshot diff tooling for test assertions
+- [x] Optional per-user storage quotas
+- [x] Improved shell compatibility (pipelines, redirections)
+- [x] Pure in-memory VFS with snapshot import/export
+- [x] Symlinks (`ln -s`, `isSymlink`, `resolveSymlink`)
+- [x] SSH public-key authentication
+- [x] Per-IP rate limiting and lockout
+- [x] Shell operators: `&&` / `||` / `;`
+- [x] Shell scripting: `if`/`elif`/`else`/`fi`, `for`/`do`/`done`, `while`/`do`/`done`
+- [x] Variable expansion: `$VAR`, `${VAR:-default}`, `$?`
+- [x] Per-session `ShellEnv` (no more global variable store)
+- [x] `.bashrc` auto-sourced on interactive login
+- [x] `clear` with full ANSI screen reset (`\x1b[2J\x1b[H\x1b[3J`)
+- [x] `Ctrl+W` delete word in interactive shell
+- [x] Grouped, colorized `help` with per-command detail
+- [x] New commands: `sort`, `uniq`, `tee`, `cut`, `tr`, `xargs`, `diff`, `sed`, `awk`, `tar`, `gzip`, `gunzip`, `base64`, `date`, `sleep`, `id`, `groups`, `uname`, `ps`, `kill`, `df`, `du`, `ping`
 - [x] Structured event hooks (session open/close, file write, sudo challenge)
-- [ ] WebSocket-based remote shell client (experimental)
+- [ ] Snapshot diff tooling for test assertions
+- [ ] WebSocket-based remote shell client (experimental)
+- [ ] `$(cmd)` command substitution in variable expansion
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).