docs: add PLAN.md roadmap and Blueprint Protocol mandate

Author: Codeleafly

AGENTS.md

@@ -36,7 +36,7 @@ Nox is a high-performance, general-purpose programming language built from scrat
 22. **True Async VM Model:** The Nox VM MUST support non-blocking execution. All external I/O and time-based operations MUST use async workflows where appropriate.
 23. **Systemic Refactoring:** The codebase is now entirely Rust. Ensure all newly added code strictly follows idiomatic Rust practices and maintains 100% Modern Nox syntax compliance.
 24. **Professional Distribution:** AI agents MUST prioritize standard, professional installer packages for releases. For Windows releases, generate Microsoft Installer (`.msi`) packages. For Linux releases, generate Debian (`.deb`) packages. These installers must automatically add Nox to the global `PATH`. Raw executables (`.exe`, `./nox`) are strictly permitted for local development and testing only.
-25. **Workspace Hygiene:** Cargo build artifacts can become extremely heavy. AI agents MUST run `cargo clean` periodically after heavy builds or cross-compilation tasks to save disk space and maintain a lean workspace environment.
+26. **Blueprint Protocol (`PLAN.md`):** Use `PLAN.md` strictly as a temporary, human-readable roadmap for GitHub visibility and user coordination. AI agents MUST still rely on the internal `Plan Mode` tool for permanent AI task tracking, state management, and execution orchestration.
 
 ## Progressive Disclosure
 For detailed rules, architectural deep-dives, and coding patterns, refer to:

CONTRIBUTING.md

@@ -8,8 +8,8 @@ Thank you for your interest in contributing to Nox! This project follows a stric
 - **Pull Requests (PRs):** Every change must be submitted via a PR with a clear description of the "why" and "what".
 
 ## 2. Code Quality and Linting
-- **Automated Linting:** PRs will only be merged if they pass all automated linting checks (Prettier/ESLint).
-- **Zero Warnings Policy:** All warnings are treated as errors. The codebase must remain clean at all times.
+- **Automated Linting:** PRs will only be merged if they pass all automated linting checks (`cargo fmt` and `cargo clippy`).
+- **Zero Warnings Policy:** All warnings are treated as errors (`cargo check` must be clean). The codebase must remain clean at all times.
 
 ## 3. Safety and Security Rules
 - **Signed Commits:** All contributors are encouraged (and in some cases required) to GPG-sign their commits for verification.

PLAN.md

@@ -0,0 +1,51 @@
+# Nox Future Roadmap & Plan (Phase 11+)
+
+This document outlines the high-level roadmap for the next major evolution of the Nox programming language. This file serves as a temporary, human-readable blueprint for developers and users.
+
+> **AI Note:** AI Agents should use the internal `Plan Mode` tool for managing state and task tracking. This `PLAN.md` file is strictly for human consumption and project visibility on GitHub.
+
+## 1. Ultra-Modern Module System (Deno-Style)
+Nox will abandon the traditional `node_modules` approach in favor of a secure, URL-based module resolution system.
+
+- **Direct Imports:** Import packages directly from HTTP/HTTPS URLs or local paths.
+  ```javascript
+  import { fastMath } from "https://nox-lib.io/math/map.nx.json"
+  import { localHelper } from "./utils/helper.nx"
+  ```
+- **Smart Mapping (`map.nx.json`):** Instead of downloading a single file, Nox will fetch a map file that defines the entire package structure, its assets (like `.so` or `.dll` binaries), and its dependencies.
+
+## 2. Global Smart Caching & Storage
+To prevent "Dependency Hell" and save disk space, all modules will be stored globally on the OS.
+
+- **Storage Location:** 
+  - Linux/macOS: `$HOME/.nox_libx/`
+  - Windows: `%USERPROFILE%\.nox_libx\`
+- **Immutable Cache:** Once a module is downloaded, it is stored in an immutable, versioned hash-folder (e.g., `.nox_libx/pkg_cache/github.com/user/math_lib/v1.0.0/`).
+- **Deduplication:** If multiple projects require `math_lib@v1.0.0`, it is only downloaded once. Projects simply link to the global cache.
+
+## 3. Multi-Version Support
+Nox will support running multiple versions of the same package without conflict.
+- **Specific Version Import:** `import { add } from "github:user/math_lib@v1.0.0"`
+- **Semantic Versioning:** `import { sub } from "github:user/math_lib@^1.0.0"`
+
+## 4. Smart CLI & Auto-Installer
+The `nox` CLI will be heavily upgraded to act as an integrated package manager.
+
+- **Runtime Prompt:** If a script is executed and a dependency is missing, the runtime pauses and asks the user for permission to download and install it into the global cache.
+- **Explicit Commands:**
+  - `nox install <url>`: Install a package to the global cache.
+  - `nox clean`: Wipe the `.nox_libx` cache.
+  - `nox list`: Show installed packages.
+
+## 5. Optional Static Typing
+Nox will remain beginner-friendly (Python-like) but will introduce TS/Rust-inspired optional static typing for production safety.
+
+```javascript
+// Simple Function
+fn greet(name) { print name }
+
+// Type-Safe Function
+pub fn add(a: int, b: int) -> int {
+    return a + b
+}
+```

docs/STANDARDS.md

@@ -1,16 +1,16 @@
 # Nox Engineering Standards
 
 ## Coding Standards
-- **Modern TypeScript:** Adhere to ESM and modern TypeScript best practices. Avoid outdated patterns.
-- **Zero-Tolerance for `any`:** Use strict TypeScript typing. `any` is strictly prohibited.
-- **Strict Mode:** TypeScript `strict` mode must be enabled and enforced.
+- **Idiomatic Rust:** Adhere to modern Rust best practices (e.g., using `Result`/`Option` over panics where possible, clear lifetimes).
+- **Strict Typing:** Rust's strong type system must be utilized. Avoid overly generic `Any` equivalents unless strictly necessary.
+- **Zero-Tolerance for Warnings:** The codebase must compile with absolutely zero warnings (`cargo check` must be clean).
 - **Modular VM Architecture:** Keep opcode implementations separate from the main VM orchestration. Files should be small (< 200 lines) and focused.
-- **Async-First Execution:** Prioritize asynchronous execution for any I/O, timers, or long-running tasks. Use `async/await` in TypeScript and `!` in Nox.
+- **Async-First Execution:** Prioritize asynchronous execution for any I/O, timers, or long-running tasks. Use `tokio` for async operations.
 
 ## Quality Standards
 - **Modern Nox Syntax:** All new code and documentation MUST use the `is`/`mut` variables, `fn =>` arrows, and no-parens `if`/`while` syntax.
 - **Test-Driven Development (TDD):** Every feature must have corresponding unit tests. Aim for high coverage in Lexer, Parser, and VM.
-- **Clear Error Reporting:** Compiler/Interpreter errors must provide line/column numbers and helpful suggestions.
+- **Clear Error Reporting:** Compiler/Interpreter errors must provide helpful suggestions.
 - **Documentation-as-Code:** Major architectural decisions and language features must be documented in the `/docs` folder.
 
 For project-wide rules, see root [AGENTS.md](../AGENTS.md).

docs/WORKFLOW.md

@@ -8,8 +8,8 @@ This project is primarily developed, reviewed, and managed by AI agents.
 - **Research & Strategy:** Read all relevant files (`.ts`, `.txt`, `.md`, `.nx`) to fully understand the context before writing code.
 - **Systemic Refactoring:** Proactively refactor legacy syntax to Modern Nox standard (`is`/`mut`, no-parens) when modifying files.
 - **Verification:** 
-  - Run `npm run build` after every update.
-  - Execute and verify all integration tests in `tests/`.
+  - Run `cargo check` and `cargo build` after every update to ensure zero warnings.
+  - Execute and verify all integration tests in `tests/` using `cargo test`.
 
 ## AI Protocols
 - **Agent Identification:** Explicitly state your agent name (e.g., "Developed by Gemini CLI") in commit messages and documentation.

docs/cli.md

@@ -1,15 +1,16 @@
 # Nox CLI & REPL Guide
 
-Nox provides a modern, interactive CLI built with **React** and **Ink**.
+Nox provides a modern, interactive CLI built in **Rust**.
 
 ## Global Command
-If you have run `npm link`, you can use the `nox` command from anywhere.
+If you have installed Nox globally (e.g., using a `.msi` or `.deb` release, or via `cargo install --path packages/cli`), you can use the `nox` command from anywhere.
 
 ## Interactive REPL
 To start the REPL, simply run:
 ```bash
-nox
+nox repl
 ```
+*(Or use `cargo run --package nox -- repl` during development)*
 
 ### REPL Commands (Dot Commands)
 - `.help`: Displays available commands and syntax.
@@ -23,8 +24,9 @@ Nox REPL features intelligent multi-line detection. If you enter an incomplete c
 ## Running Files
 To execute a Nox script, pass the file path as an argument.
 ```bash
-nox my_script.nx
+nox run my_script.nx
 ```
+*(Or use `cargo run --package nox -- run my_script.nx` during development)*
 *Note: While any extension works, `.nx` is the recommended standard.*
 
 ### Permission Flags
@@ -38,5 +40,5 @@ By default, Nox scripts run in a sandbox with no access to the filesystem or she
 
 **Example:**
 ```bash
-nox --allow-read --allow-write log_processor.nx
+nox run --allow-read --allow-write log_processor.nx
 ```

docs/packages.md

@@ -1,51 +1,51 @@
 # Nox Package Ecosystem (High Detail Analysis)
 
-This document provides an exhaustive breakdown of the Nox monorepo structure, dependencies, and inter-package linkages. Nox is an **AI-Native** project where all packages are designed to be decoupled yet strictly synchronized through a shared contract.
+This document provides an exhaustive breakdown of the Nox Cargo workspace structure, dependencies, and inter-package linkages. Nox is an **AI-Native** project where all crates are designed to be decoupled yet strictly synchronized through a shared contract.
 
 ## 1. Root Workspace (`/`)
 The root directory acts as the orchestrator for the entire ecosystem.
 
--   **Purpose:** Manages the monorepo lifecycle, builds, and cross-package testing.
+-   **Purpose:** Manages the Cargo workspace lifecycle, builds, and cross-package testing.
 -   **Key Scripts:**
-    -   `npm run build`: Executes `tsc -b`. This uses TypeScript Project References to compile packages in the correct dependency order (`shared` -> `frontend`/`runtime` -> `cli`).
-    -   `npm run test`: Runs the Vitest suite. It ensures integration between the compiler and the VM.
-    -   `npm run clean`: Uses `tsc -b --clean` to wipe build artifacts safely.
+    -   `cargo build`: Compiles all packages in the correct dependency order (`nox-shared` -> `nox-frontend`/`nox-runtime` -> `nox`).
+    -   `cargo test`: Runs the native Rust test suite. It ensures integration between the compiler and the VM.
+    -   `cargo clean`: Wipes build artifacts safely to save disk space.
 -   **Tooling:**
-    -   `vitest`: Chosen for its speed and native ESM support, critical for the Nox 'module' architecture.
-    -   `typescript`: Strict mode is enforced globally via `tsconfig.base.json`.
+    -   `cargo`: Chosen for its speed and native Rust dependency management.
+    -   `rustc`: Strict mode and warnings are enforced globally.
 
 ---
 
-## 2. `@nox/shared` (`packages/shared`)
-The "Contract" of the language. This package contains no logic, only definitions.
+## 2. `nox-shared` (`packages/shared`)
+The "Contract" of the language. This crate contains no logic, only definitions.
 
 -   **Role:** Ensures that the Frontend (Compiler) and the Runtime (VM) use the exact same numeric identifiers for operations.
 -   **Key Exports:**
-    -   `Opcode`: An enum of 32-bit integers. Using numeric opcodes instead of strings prevents overhead during VM execution.
+    -   `Opcode`: An enum represented as `i64`. Using numeric opcodes instead of strings prevents overhead during VM execution.
     -   `TokenType`: Definitions for the Lexer and Parser.
--   **Linkage:** Every other package depends on `@nox/shared`. Any change here requires a full rebuild of the ecosystem.
+-   **Linkage:** Every other crate depends on `nox-shared`. Any change here requires a full rebuild of the ecosystem.
 
 ---
 
-## 3. `@nox/frontend` (`packages/frontend`)
+## 3. `nox-frontend` (`packages/frontend`)
 The "Architect". It transforms human-readable code into machine-executable bytecode.
 
 -   **Components:**
     -   **Lexer:** Handles string scanning, including complex escape sequences like `\e` (ANSI) for terminal styling.
     -   **Parser:** A recursive-descent parser that builds a formal AST. It supports hybrid JS/Python syntax.
     -   **Compiler:** A one-pass AST-to-Bytecode generator.
 -   **High-Detail Logic:**
-    -   **Scope Management:** Uses a stack of Maps to handle nested block scopes and function locals.
+    -   **Scope Management:** Uses a stack of HashMaps to handle nested block scopes and function locals.
     -   **Bytecode Optimization:** Implements short-circuiting for `&&` and `||` using `JMP_IF_FALSE` and `JMP_IF_TRUE`.
-    -   **Numeric Safety:** Validates that all integer literals fit within the 32-bit signed range before emitting `PUSH` opcodes.
+    -   **Numeric Safety:** Validates that all integer literals fit within the 64-bit signed range before emitting `PUSH` opcodes.
 
 ---
 
-## 4. `@nox/runtime` (`packages/runtime`)
+## 4. `nox-runtime` (`packages/runtime`)
 The "Engine". A high-performance, stack-based Virtual Machine.
 
 -   **Architecture:**
-    -   Uses `Int32Array` for bytecode storage to leverage TypedArray performance in V8.
+    -   Uses `Vec<i64>` for bytecode storage to leverage native Rust performance.
     -   **Memory Segments:**
         -   `Stack`: Operand processing (1024 slots).
         -   `Globals`: Absolute addressing (512 slots).
@@ -54,18 +54,17 @@ The "Engine". A high-performance, stack-based Virtual Machine.
     -   Implements a strict path-resolution algorithm to prevent "Sandbox Escapes" (`..` traversal).
     -   **Permissions:** Granular `read`, `write`, and `run` permissions.
 -   **Dependencies:**
-    -   `readline-sync`: Used for the `read_line()` built-in to provide blocking synchronous I/O.
+    -   `tokio`: Used for true async non-blocking execution inside the VM.
 
 ---
 
-## 5. `@nox/cli` (`packages/cli`)
+## 5. `nox` (`packages/cli`)
 The "Gateway". The primary entry point for users and agents.
 
 -   **Interface:**
-    -   Built using **React** and **Ink** to provide a modern, interactive CLI experience.
-    -   Features a multi-line REPL with state persistence.
+    -   Built using **clap** and **colored** to provide a modern, interactive CLI experience.
 -   **Functionality:**
-    -   Parses Deno-style flags (e.g., `--allow-read`, `--allow-all`).
+    -   Parses command-line arguments and commands.
     -   Handles file execution logic and error reporting with source-code context.
 -   **Binaries:**
     -   Exports the `nox` command globally.