docs: finalized absolute comprehensive command and flag guide in root readme

Author: brainless3178

README.md

@@ -30,132 +30,140 @@ graph TD
 
 ---
 
-## 🚀 Ecosystem Infrastructure & Features
+## � Project Lifecycle & Orchestration
 
-### 1. Advanced Zero-Knowledge Stack
-- **Groth16 Proving Pipeline**: High-performance proving implementation on the **BN254 curve**.
-- **Poseidon-3 Hashing**: Standardized sponge construction ensuring 100% hash parity across **Circom (circuits)**, **Rust (Anchor program)**, and **TypeScript (SDK)**.
-- **20-Level Merkle Tree**: Optimized sparse tree supporting over 1.04M unique commitments per pool.
-
-### 2. Specialized ZK Circuitry
-- **`withdraw.circom`**: Orchestrates nullifier verification, Merkle membership checks, and public signal binding.
-- **`rescue.circom`**: A specialized emergency circuit for the Atomic Rescue Engine, enabling private migration of assets from compromised identities.
-- **`merkleTree.circom`**: Efficient logarithmic witness generation for state membership.
-
-### 3. On-Chain Cryptoeconomics & Programs
-- **Anchor Protocol**: A secure on-chain verifier and state management layer.
-- **Nullifier Management**: Persistent on-chain nullifier tracking to prevent double-spending without leaking deposit history.
-- **Protocol Economics**: Integrated fee-distribution and relayer-bounty mechanisms implemented in `economics.rs`.
-
-### 4. Shadow Relayer Network (Onion Routing)
-- **Identity Decoupling**: RSA-OAEP multi-hop encryption ensures the destination identity is never linked to the origin RPC metadata.
-- **Gasless Withdrawals**: Users can execute withdrawals without maintaining native SOL in the destination wallet; fees are deducted directly from the shielded commitment.
-
-### 5. Privacy Ghost Score (Anonymity Audit)
-- **Heuristic Diagnostic Engine**: Quantifies wallet privacy (0-100) by analyzing transaction-graph entropy, identity linkage, and temporal correlations.
-- **Social Artifacts**: Generate ZK-verified "Privacy Badges" to prove anonymity status without revealing sensitive data.
-
-### 6. Atomic Rescue Engine (MEV Protection)
-- **Jito Integration**: Leverages the **Jito-Solana mev-bundle** for sub-2s critical execution, protecting assets from front-running and sandwich attacks during emergency rotations.
-- **Private Migration**: Automates the batch-shielding process to transit leaked assets into a secure, private state.
-
-### 7. Global Command Center (CLI & Dashboard)
-- **SolVoid CLI**: High-performance terminal interface for system-wide orchestration, rescue ops, and auditing.
-- **Web Dashboard**: An institutional-grade Next.js interface providing real-time protocol telemetry, vault liquidity snapshots, and individual privacy audit histories.
-
-### 8. Quality Assurance & Engineering Standards
-- **Strict Data Integrity (DIE)**: Zod-powered schema enforcement at every operational boundary (CLI, API, SDK).
-- **Comprehensive Test Suite**: Unit, integration, and E2E testing using **Jest** and **Anchor Test**, ensuring ZK circuit parity and state consistency.
-- **Automated CI/CD**: Optimized GitHub Actions for continuous deployment and cryptographic validation.
-
----
-
-## 🛠 Command Orchestration & Implementation
-
-### 1. Environment Initialization
-Standard procedures for initializing the SolVoid development and deployment environment.
+### 1. Environment & Deployment Hub
+The foundation for building, testing, and deploying the SolVoid protocol.
 
 ```bash
-# Clone and Initialize
+# Repository Initialization
 git clone https://github.com/brainless3178/SolVoid.git
 cd SolVoid
 npm install
 
-# ZK Proving Pipeline Initialization
-# Ensure circom and snarkjs are present in the system path
+# ZK Cryptographic Pipeline
+# Compiles circuits and generates proving/verification keys
 ./scripts/build-zk.sh
 
-# On-Chain Deployment (Anchor)
+# On-Chain Program Lifecycle (Anchor)
 anchor build
 anchor deploy --provider.cluster devnet
+
+# Quality Assurance Suite
+npm test               # Execute full test matrix
+npm run lint           # Static code analysis
+npm run dashboard:dev  # Launch local UI environment
 ```
 
 ### 2. CLI Command Specification (`solvoid`)
-Standard orchestration for protocol interaction and emergency remediation.
+The primary interface for protocol interaction, auditing, and emergency response.
 
-#### **Shielding (Deposit)**
+#### **Surgical Shielding (Deposit)**
 ```bash
 solvoid shield <amount>
 ```
+*   **Args**: `<amount>` (SOL to shield)
+*   **Protocol Action**: Generates `Secret` and `Nullifier` keys and commits hashed state to the Merkle tree.
 
-#### **Withdrawal (Unlinking)**
+#### **Unlinkable Withdrawal**
 ```bash
-solvoid withdraw <secret> <nullifier> <recipient> <amount> [flags]
+solvoid withdraw <secret> <nullifier> <recipient> <amount> [options]
 ```
-| Flag | Description | Default |
+| Option | Description | Default |
 |:---|:---|:---|
-| `--relayer <url>` | Target Shadow Relayer endpoint | `http://localhost:8080` |
-| `--rpc <url>` | Override default Solana RPC | `.env` default |
+| `--relayer <url>`| Target Shadow Relayer endpoint | `.env` default |
+| `--rpc <url>`    | Override default Solana RPC | `.env` default |
 
-#### **Ghost Score (Anonymity Audit)**
+#### **Privacy Ghost Score (Audit)**
 ```bash
-solvoid ghost <address> [flags]
+solvoid ghost <address> [options]
 ```
-| Flag | Description |
+| Option | Description |
 |:---|:---|
-| `--badge` | Generate a ZK-verified privacy badge artifact |
-| `--json` | Return raw audit data for programmatic ingestion |
+| `--badge`      | Generate a ZK-verified Privacy Badge artifact |
+| `--share`      | Generate social metadata for X/Discord platforms |
+| `--verify <p>` | Cryptographically validate an external privacy proof |
+| `--json`       | Return raw audit data for programmatic ingestion |
 
-#### **Atomic Rescue (Emergency Remediation)**
+#### **Atomic Rescue (MEV Protection)**
+```bash
+solvoid rescue <wallet> [options]
+```
+| Option | Description |
+|:---|:---|
+| `--to <addr>`    | Specified recovery destination address |
+| `--auto-generate`| Initialize a fresh, secure remediation wallet |
+| `--jito-bundle`  | Utilize Jito-Solana MEV bundles for atomic execution |
+| `--emergency`    | Priority fee escalation for sub-2s critical rotation |
+| `--dry-run`      | Simulate orchestration without network broadcast |
+| `--monitor`      | Activate real-time post-remediation threat alerts |
+
+#### **Protocol Administration (Emergency Controls)**
 ```bash
-solvoid rescue <wallet_input> [flags]
+solvoid admin <command> [args]
 ```
-| Flag | Description |
+| Command | Action |
 |:---|:---|
-| `--to <address>` | Specified recovery destination for remediated assets |
-| `--emergency` | Escalated priority for Jito-MEV critical execution |
+| `pause`               | Trigger the ZK Circuit Breaker to suspend withdrawals |
+| `resume`              | Reset breaker and resume protocol operations |
+| `trigger-emergency`   | Escalates protocol-wide fee multipliers (x1-x10) |
+| `disable-emergency`   | Resets protocol fees to baseline state |
 
 ---
 
 ### 3. SDK Integration Patterns
+A professional integration layer for third-party dApps and services.
+
 ```typescript
 import { SolVoidClient } from 'solvoid';
 
+// 1. Client Orchestration
 const client = new SolVoidClient(config, wallet);
+
+// 2. Surgical Shielding
 const { commitmentData } = await client.shield(1.5 * LAMPORTS_PER_SOL);
+
+// 3. Privacy Auditing
 const passport = await client.getPassport(address);
+console.log(`Ghost Score: ${passport.overallScore}/100`);
+
+// 4. Low-level Proof Generation
+const proof = await client.prepareWithdrawal(secret, nullifier, ...);
 ```
 
-### 4. Relayer API Specification
-| Endpoint | Method | Data Requirement |
+---
+
+### 4. Shadow Relayer API Specification
+Technical endpoints for the decentralized relay network.
+
+| Endpoint | Method | Functional Requirement |
 |:---|:---|:---|
-| `/status` | `GET` | Service health & metrics |
-| `/commitments` | `GET` | Merkle state synchronization |
-| `/relay` | `POST` | `transaction` (base64) & `hops` (1-5) |
+| `/status` | `GET` | Health monitoring & protocol metrics |
+| `/commitments` | `GET` | Multi-hop Merkle state synchronization |
+| `/relay` | `POST` | `transaction` (base64) & `hops` (onion routing depth 1-5) |
+
+---
+
+## � Key Ecosystem Infrastructure
+
+*   **Groth16 ZK-SNARKs**: High-performance proving implementation on the **BN254 curve**.
+*   **Poseidon-3 Hashing**: Standardized sponge construction for 100% parity across Rust, TS, and Circom.
+*   **Jito-MEV Integration**: Advanced front-running protection for critical asset rotations.
+*   **Data Integrity Enforcement (DIE)**: Zod-powered schema validation at every operational boundary.
+*   **Global Dashboard**: Institutional Next.js interface providing real-time technical telemetry.
 
 ---
 
-## 📖 Reference Documentation Partitioning
+## 📖 Project Documentation
 
-- **Protocol Core:** [DOCS.md](DOCS.md) | [ZK_REFERENCE.md](ZK_REFERENCE.md) | [GHOST_REFERENCE.md](GHOST_REFERENCE.md)
-- **Integration Layer:** [SDK_REFERENCE.md](SDK_REFERENCE.md) | [CLI_REFERENCE.md](CLI_REFERENCE.md) | [API_REFERENCE.md](API_REFERENCE.md)
-- **Operations:** [CICD_REFERENCE.md](CICD_REFERENCE.md) | [SYSTEM_STATUS.md](SYSTEM_STATUS.md) | [DEPLOYMENT.md](DEPLOYMENT.md)
+- **Core:** [DOCS.md](DOCS.md) | [ZK_REFERENCE.md](ZK_REFERENCE.md) | [GHOST_REFERENCE.md](GHOST_REFERENCE.md)
+- **Integration:** [SDK_REFERENCE.md](SDK_REFERENCE.md) | [CLI_REFERENCE.md](CLI_REFERENCE.md) | [API_REFERENCE.md](API_REFERENCE.md)
+- **Ops:** [CICD_REFERENCE.md](CICD_REFERENCE.md) | [SYSTEM_STATUS.md](SYSTEM_STATUS.md) | [DEPLOYMENT.md](DEPLOYMENT.md)
 
 ---
 
 ## 🔒 Security Compliance
 - **Status:** Experimental Beta
-- **Audit Path:** Undergoing internal peer review; third-party audit scheduled for Q2.
 - **Policy:** Refer to [SECURITY.md](SECURITY.md) for disclosure protocols.
 
 ---