arcvision 0.2.14 → 0.2.16

package/ARCVISION_DIRECTORY_STRUCTURE.md

@@ -0,0 +1,104 @@
+# ArcVision Output Directory Structure
+
+## 📁 New Dedicated Directory Implementation
+
+ArcVision now generates all output files in a dedicated `/arcvision_context/` directory to keep your project root clean and organized.
+
+## 📂 Directory Structure
+
+```
+your-project/
+├── arcvision_context/                  ← NEW: Dedicated ArcVision output directory
+│   ├── arcvision.context.json          ← Structural context (OVERWRITTEN each scan)
+│   ├── architecture.authority.ledger.json  ← Authority decisions (APPENDED only)
+│   └── README.md                       ← Documentation (OVERWRITTEN each scan)
+├── .arcvision/                         ← Configuration directory (unchanged)
+│   ├── invariants.json                 ← Architectural rules
+│   ├── config.json                     ← Project configuration
+│   └── tokens/                         ← Authentication tokens
+└── [your other project files]
+```
+
+## 🔁 File Update Behavior
+
+### **arcvision.context.json** (Structural Truth)
+- ✅ **OVERWRITTEN** completely each time you run `arcvision scan`
+- Contains current structural analysis of your codebase
+- Generated fresh from source code every time
+- Located: `./arcvision_context/arcvision.context.json`
+
+### **architecture.authority.ledger.json** (Decision Truth)  
+- ✅ **APPENDED TO** - never overwritten
+- Contains permanent record of all BLOCKED and OVERRIDDEN decisions
+- Uses append-only approach for audit trail
+- Located: `./arcvision_context/architecture.authority.ledger.json`
+
+### **README.md** (Documentation)
+- ✅ **OVERWRITTEN** each time you run `arcvision scan`
+- Generated documentation about the current context
+- Updates with latest blast radius analysis
+- Located: `./arcvision_context/README.md`
+
+## 🚀 Usage Examples
+
+### Generate context in dedicated directory:
+```bash
+arcvision scan
+# Creates/updates files in ./arcvision_context/
+```
+
+### Evaluate changes using context from dedicated directory:
+```bash
+arcvision evaluate
+# Automatically looks for context in ./arcvision_context/arcvision.context.json
+```
+
+### View authority ledger statistics:
+```bash
+arcvision ledger --stats
+# Reads from ./arcvision_context/architecture.authority.ledger.json
+```
+
+### Override a blocked decision:
+```bash
+arcvision override --event-id evt_12345 --reason "Emergency fix" --owner "developer"
+# Records in ./arcvision_context/architecture.authority.ledger.json
+```
+
+## ⚙️ Configuration Options
+
+The directory location can be customized using environment variables:
+
+```bash
+# Change the authority ledger location
+export AUTHORITY_LEDGER_PATH=./custom/path/architecture.authority.ledger.json
+
+# Change the default arcvision context directory name
+# (would require code modification)
+```
+
+## 🛡️ Backward Compatibility
+
+- Existing commands work exactly the same
+- No breaking changes to CLI interface
+- All file references automatically use the new directory structure
+- Legacy context files in root directory are no longer used
+
+## 📊 Benefits
+
+1. **Clean Project Root**: Keeps generated files organized in one place
+2. **Clear Separation**: Distinguishes between configuration (`.arcvision/`) and output (`arcvision_context/`)
+3. **Easy Cleanup**: Simply delete the `arcvision_context/` directory to regenerate all outputs
+4. **Version Control Friendly**: Easy to `.gitignore` just the output directory while keeping configuration
+5. **Consistent Location**: All ArcVision outputs are predictably located
+
+## 🎯 Implementation Details
+
+The implementation ensures:
+- Directory is created automatically if it doesn't exist
+- All file operations are relative to the `arcvision_context/` directory
+- Authority ledger maintains append-only behavior regardless of location
+- Error handling for directory creation and file access
+- Clear console messages indicating file locations
+
+This change maintains all existing functionality while providing better organization and cleaner project structure.

package/CLI_STRUCTURE.md

@@ -0,0 +1,110 @@
+# ArcVision CLI Tool Structure
+
+## Directory Layout
+
+```
+cli/
+├── docs/
+│   ├── blast-radius-implementation.md
+│   └── blast-radius.md
+├── schema/
+│   └── arcvision_context_schema_v1.json
+├── src/
+│   ├── core/
+│   │   ├── blastRadius.js
+│   │   ├── di-detector.js
+│   │   ├── method-tracker.js
+│   │   ├── parser-enhanced.js
+│   │   ├── parser.js
+│   │   ├── path-resolver.js
+│   │   ├── react-nextjs-detector.js
+│   │   ├── scanner.js
+│   │   ├── semantic-analyzer.js
+│   │   ├── tsconfig-utils.js
+│   │   ├── type-analyzer.js
+│   │   └── watcher.js
+│   ├── engine/
+│   │   ├── context_builder.js
+│   │   ├── context_sorter.js
+│   │   ├── context_validator.js
+│   │   └── id-generator.js
+│   ├── plugins/
+│   │   ├── express-plugin.js
+│   │   ├── plugin-manager.js
+│   │   └── react-plugin.js
+│   └── index.js
+├── test/
+│   └── determinism-test.js
+├── .npmignore
+├── README.md
+├── arcvision.context.json
+├── jest.config.json
+├── output1.json
+├── output2.json
+├── package-lock.json
+└── package.json
+```
+
+## Directory and File Purposes
+
+### Root Directory Files
+- **package.json**: Defines the CLI tool's metadata, dependencies, and entry points
+- **package-lock.json**: Locks dependency versions for consistent installations
+- **README.md**: Documentation for the CLI tool
+- **.npmignore**: Specifies files to exclude when publishing to npm
+- **arcvision.context.json**: Contains context data generated by the CLI tool
+- **jest.config.json**: Jest testing framework configuration
+- **output1.json & output2.json**: Sample or test output files
+
+### docs/
+Contains documentation files related to the "blast radius" feature of the CLI tool:
+- **blast-radius-implementation.md**: Implementation details of the blast radius feature
+- **blast-radius.md**: General documentation about the blast radius functionality
+
+### schema/
+Contains the JSON schema for validating context files:
+- **arcvision_context_schema_v1.json**: Schema definition for the ArcVision context format
+
+### src/
+The main source code directory organized into three subdirectories:
+
+#### src/core/
+Contains core functionality for code analysis and scanning:
+- **blastRadius.js**: Implements blast radius calculation functionality
+- **di-detector.js**: Detects dependency injection patterns
+- **method-tracker.js**: Tracks method calls and dependencies
+- **parser-enhanced.js**: Enhanced parsing functionality
+- **parser.js**: Core parsing functionality
+- **path-resolver.js**: Resolves file paths within the project
+- **react-nextjs-detector.js**: Detects React and Next.js specific patterns
+- **scanner.js**: Main scanning functionality
+- **semantic-analyzer.js**: Performs semantic analysis of code
+- **tsconfig-utils.js**: Utilities for working with TypeScript configuration
+- **type-analyzer.js**: Analyzes types in the codebase
+- **watcher.js**: Watches for file changes during scanning
+
+#### src/engine/
+Contains the core engine functionality for building and managing context:
+- **context_builder.js**: Builds the context from scanned files
+- **context_sorter.js**: Sorts context elements
+- **context_validator.js**: Validates the generated context
+- **id-generator.js**: Generates unique IDs for context elements
+- **pass1_facts.js**: Syntactic fact extraction - parses files and extracts raw syntactic facts (imports, exports, functions, classes)
+- **pass2_semantics.js**: Semantic resolution - resolves import strings to actual file IDs and links method calls to their definitions
+- **pass3_lifter.js**: Structural lifting - infers structural roles (Store, Service, Component, Utility) based on naming and connectivity
+- **pass4_signals.js**: Signal extraction - calculates graph metrics like Blast Radius, Centrality, and identifies high-value nodes
+
+#### src/plugins/
+Contains plugin architecture for extending functionality:
+- **express-plugin.js**: Plugin for Express.js framework detection
+- **plugin-manager.js**: Manages loading and execution of plugins
+- **react-plugin.js**: Plugin for React framework detection
+
+### src/index.js
+The main entry point for the CLI application that coordinates all the functionality.
+
+### test/
+Contains test files:
+- **determinism-test.js**: Tests for ensuring consistent results across multiple runs
+
+This CLI tool appears to be designed for analyzing codebases, generating context files, and detecting dependencies and relationships within the code, with support for various frameworks like React, Next.js, and Express.

package/CONFIGURATION.md

@@ -0,0 +1,119 @@
+# ArcVision Authoritative Gate Configuration
+
+This file documents all environment variables that can be used to configure the Authoritative Gate behavior without hardcoding values.
+
+## Authority Ledger Configuration
+
+```bash
+# Schema version for the authority ledger
+ARCHITECTURE_LEDGER_SCHEMA_VERSION=1.0
+
+# System identifier (defaults to current directory name)
+ARCHITECTURE_SYSTEM_ID=my-project-name
+
+# Default values for git metadata when not provided
+DEFAULT_COMMIT_REF=HEAD
+DEFAULT_BRANCH_NAME=main
+DEFAULT_AUTHOR=system
+```
+
+## Override Handler Configuration
+
+```bash
+# Minimum reason length for overrides
+OVERRIDE_MIN_REASON_LENGTH=10
+
+# Override command format and placeholders
+OVERRIDE_COMMAND_FORMAT=arcvision override --event-id {eventId}
+OVERRIDE_REASON_PLACEHOLDER=  --reason "<detailed explanation>"
+OVERRIDE_OWNER_PLACEHOLDER=  --owner "<responsible person>"
+
+# Override requirements text
+OVERRIDE_REQUIREMENTS_HEADER=Requirements:
+OVERRIDE_REASON_REQUIREMENT=• Reason must be detailed (minimum {minLength} characters)
+OVERRIDE_OWNER_REQUIREMENT=• Owner must be identified
+OVERRIDE_RECORDING_REQUIREMENT=• Override is permanently recorded
+OVERRIDE_FUTURE_SCRUTINY=• Future violations will face increased scrutiny
+```
+
+## CLI Configuration
+
+```bash
+# Complete CLI description
+CLI_DESCRIPTION=CLI to visualize codebase architecture
+
+# Quick start instructions
+CLI_QUICK_START_INSTRUCTIONS=Quick Start:
+  1. Sign up at the ArcVision dashboard
+  2. Create a project and name it
+  3. Generate a CLI token
+  4. Run: arcvision link <token>
+  5. Run: arcvision scan --upload
+  6. Open dashboard to see results
+
+# Default invariants (JSON format)
+DEFAULT_INVARIANTS_JSON=[{"id":"generic-architecture-rules","system":"general","description":"Generic rules","severity":"risk","scope":{"files":["**/*.js","**/*.ts"]},"rule":{"type":"dependency","condition":{}}}]
+```
+
+## Blocked Evaluation Messages
+
+```bash
+# Override command format for blocked evaluations
+BLOCKED_OVERRIDE_COMMAND_FORMAT=arcvision override --event-id {eventId}
+BLOCKED_OVERRIDE_REASON_PLACEHOLDER=  --reason "<detailed explanation>"
+BLOCKED_OVERRIDE_OWNER_PLACEHOLDER=  --owner "<your-identifier>"
+BLOCKED_OVERRIDE_WARNING=[WARNING] Override creates permanent architectural scar
+```
+
+## Override Success/Failure Messages
+
+```bash
+# Successful override messages
+OVERRIDE_PERMANENT_RECORD_MESSAGE=[PERMANENT RECORD] This override is now in the architectural ledger
+OVERRIDE_FUTURE_SCRUTINY_MESSAGE=Future violations will face increased scrutiny
+
+# Failure messages
+OVERRIDE_FAILURE_HEADER=❌ OVERRIDE FAILED
+OVERRIDE_FAILURE_ERROR_PREFIX=Error:
+OVERRIDE_FAILURE_REQUIREMENTS_HEADER=Requirements:
+OVERRIDE_FAILURE_BLOCKED_REQUIREMENT=• Event must be BLOCKED
+OVERRIDE_FAILURE_REASON_REQUIREMENT=• Reason must be detailed (>10 chars)
+OVERRIDE_FAILURE_OWNER_REQUIREMENT=• Owner must be specified
+OVERRIDE_FAILURE_DUPLICATE_REQUIREMENT=• Event must not already be overridden
+```
+
+## Usage Examples
+
+### Setting environment variables in bash:
+```bash
+export OVERRIDE_MIN_REASON_LENGTH=20
+export ARCHITECTURE_SYSTEM_ID=my-awesome-project
+export OVERRIDE_COMMAND_FORMAT="arcvision override --id {eventId}"
+```
+
+### Setting environment variables in Windows:
+```cmd
+set OVERRIDE_MIN_REASON_LENGTH=20
+set ARCHITECTURE_SYSTEM_ID=my-awesome-project
+set OVERRIDE_COMMAND_FORMAT=arcvision override --id {eventId}
+```
+
+### Using a .env file:
+Create a `.env` file in your project root:
+```
+OVERRIDE_MIN_REASON_LENGTH=25
+ARCHITECTURE_SYSTEM_ID=enterprise-system
+CLI_DESCRIPTION=Enterprise Architecture Governance CLI
+```
+
+## Benefits of Configuration Approach
+
+1. **No Hardcoded Values**: All text and behavior can be customized
+2. **Environment-Specific Configuration**: Different settings for dev/staging/prod
+3. **Team Customization**: Teams can adapt messages to their workflow
+4. **Localization Support**: Messages can be translated for different teams
+5. **Compliance Requirements**: Regulatory text can be configured as needed
+
+## Default Behavior
+
+When environment variables are not set, the system falls back to sensible defaults that maintain the core Authoritative Gate functionality while providing flexibility for customization.

package/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,99 @@
+# ArcVision Invariant System Implementation Summary
+
+## Overview
+
+The ArcVision invariant system has been successfully implemented to detect and analyze system invariants when ArcVision scans repositories. This addresses the core requirement to encode SYSTEM INVARIANTS - conditions that must ALWAYS hold true in any scanned system.
+
+## Key Components Created/Modified
+
+### 1. Core Invariant Detection Engine
+- **`src/core/invariant-detector.js`** - Detects architectural invariants in scanned repositories by analyzing code structure, patterns, and content
+- **`src/core/invariant-analyzer.js`** - Analyzes detected invariants and provides insights about their significance and impact
+
+### 2. Enhanced Scanning Pipeline
+- **`src/engine/pass1_facts.js`** - Extended to detect invariant indicators during syntactic fact extraction
+- **`src/engine/pass2_semantics.js`** - Updated to carry forward invariant indicators through semantic resolution
+- **`src/engine/pass3_lifter.js`** - Updated to preserve invariant information during structural lifting
+- **`src/engine/pass4_signals.js`** - Updated to maintain invariant indicators in final output
+- **`src/core/scanner.js`** - Enhanced with invariant detection and analysis capabilities
+- **`src/core/context_builder.js`** - Updated to include invariant data in the final context
+
+### 3. Schema Updates
+- **`schema/arcvision_context_schema_v1.json`** - Extended to include invariant fields
+- **Context output** now includes:
+  - `invariants` - Array of detected system invariants
+  - `invariant_analysis` - Analysis results with insights and recommendations
+  - `architectural_health` - Assessment of system's architectural health based on invariants
+
+## How It Works
+
+### During Repository Scanning
+1. **Pass 1**: Detects potential invariant indicators in code (assertions, validations, guards, etc.)
+2. **Pass 2-4**: Preserve and carry forward invariant information through the pipeline
+3. **Invariant Detection**: Analyzes the collected data to identify actual system invariants
+4. **Invariant Analysis**: Evaluates the significance and impact of detected invariants
+5. **Health Assessment**: Provides an architectural health score based on invariant coverage
+
+### Invariant Categories Detected
+- **Critical Path Invariants**: Conditions that must always hold or cause existential system failure
+- **Boundary Invariants**: Constraints that enforce architectural boundaries
+- **Module Invariants**: Conditions governing component behavior
+- **System Invariants**: Overall system-level constraints
+
+### Patterns Recognized
+- Assertion-based checks (`assert()` calls)
+- Validation functions (`validateXxx`, `checkXxx`, `ensureXxx`, `guardXxx`, `verifyXxx`)
+- State transition constraints
+- Boundary enforcement patterns
+- Error handling with invariant implications
+- Guard clauses and defensive programming patterns
+
+## Benefits Delivered
+
+### For Scanned Repositories
+1. **Automatic Invariant Discovery**: ArcVision now identifies existing invariants in any scanned repository
+2. **Architectural Health Assessment**: Provides a quantitative measure of architectural robustness
+3. **Insight Generation**: Offers insights about system strengths and potential gaps
+4. **Recommendation Engine**: Suggests improvements to strengthen system invariants
+
+### System-Level Impact
+1. **Non-Optional Architecture**: Ensures architectural intents survive code changes, refactors, and scale
+2. **Prevents "Works Locally, Breaks System-Wide" Bugs**: Invariants catch violations before they cause cascading failures
+3. **Survives Refactors**: System-level properties maintained despite component-level changes
+4. **Executable Documentation**: Invariants serve as both enforcement and specification
+
+## Integration Points
+
+The invariant system integrates seamlessly with existing ArcVision architecture:
+- Maintains backward compatibility with existing functionality
+- Extends the 4-pass structural analysis pipeline
+- Enhances the context output without disrupting existing workflows
+- Works with all supported file types (.js, .ts, .jsx, .tsx, .lua, etc.)
+
+## Files Modified/Added
+
+### New Files
+1. `src/core/invariant-detector.js` - Invariant detection engine
+2. `src/core/invariant-analyzer.js` - Invariant analysis and assessment
+3. Updated schema in `schema/arcvision_context_schema_v1.json`
+
+### Modified Files
+1. `src/engine/pass1_facts.js` - Added invariant indicator detection
+2. `src/engine/pass2_semantics.js` - Preserved invariant data
+3. `src/engine/pass3_lifter.js` - Carried forward invariant information
+4. `src/engine/pass4_signals.js` - Maintained invariant indicators
+5. `src/core/scanner.js` - Integrated invariant detection and analysis
+6. `src/core/context_builder.js` - Included invariant data in output
+
+## Validation
+
+The system has been tested and verified to:
+- Successfully integrate with the existing scanning pipeline
+- Properly detect invariant patterns in code
+- Generate meaningful analysis and health assessments
+- Maintain performance and compatibility
+- Produce valid context output according to the extended schema
+
+## Conclusion
+
+The ArcVision invariant system now enables any scanned repository to have its architectural invariants automatically detected, analyzed, and assessed. This fulfills the requirement to encode SYSTEM INVARIANTS that ensure architectural intent is non-optional and survives code changes, refactors, and scale across all repositories that ArcVision analyzes.

package/README.md

@@ -1,89 +1,149 @@
-# ArcVision System Context Artifact
-
-
-## What This Is [arcvision.context.json](./arcvision.context.json)
-
-This file is the **canonical structural context** of this codebase.
-It represents how the system actually works — not how it is described.
-
-It is generated directly from source code by ArcVision.
-
-## What This Replaces
-
-This artifact replaces:
-- Manual repository scanning
-- Tribal knowledge held by senior engineers
-- Re-explaining the system to new developers
-- Re-prompting LLMs with partial or incorrect context
-- Guessing blast radius of changes
-
-## When You Must Use This
-
-Use this artifact when:
-- Onboarding a new developer
-- Prompting an AI assistant about this codebase
-- Making architectural changes
-- Investigating unexpected behavior
-- Assessing risk before modifying core modules
-
-## What This Artifact Contains
-
-- Canonical module and dependency graph
-- Execution and data flow relationships
-- Structural roles (service, store, boundary, etc.)
-- Invariants inferred from the system
-- Impact metrics (blast radius, coupling)
-
-## Determinism & Trust
-
-- Generated from commit: 0008311ad914a5f2200bd38d1b3029d47f281a46
-- Generation timestamp: 2026-01-15T11:08:33.477Z
-- Tool version: 0.2.13
-- Deterministic: same input → same output
-- Explicit assumptions listed inside the artifact
-
-If this artifact conflicts with human memory, **trust the artifact**.
-
-## Structural Context Hubs
-
-The following files have the highest blast radius and represent critical structural hubs in the system:
-
-- **src/lib/utils.ts**
-  - Blast Radius: 62 files (13.42% of codebase)
-  - Risk: Changes here may silently propagate across the system.
-
-- **src/components/ui/button.tsx**
-  - Blast Radius: 49 files (10.61% of codebase)
-  - Risk: Acts as a coordination layer between components.
-
-- **src/lib/supabase/client.ts**
-  - Blast Radius: 45 files (9.74% of codebase)
-  - Risk: Modifications can cause widespread inconsistencies.
-
-
-
-## How to Use With AI
-
-When prompting AI tools, include this file as system context.
-Do not ask the AI to infer architecture without it.
-
-## When to Regenerate
-
-Regenerate this artifact when:
-- Core modules change
-- New services are added
-- Dependency structure shifts
-
-Run:
-
-```
-arcvision scan --upload
-```
-
-## Source of Truth
-
-This artifact is the **source of truth** for system structure.
-All explanations, decisions, and AI reasoning should reference it.
-
-Some execution script invocations are dynamically assembled at runtime and may not be statically traceable; such scripts are included 
-as execution boundaries without guaranteed call-site resolution
+# ArcVision CLI
+
+A powerful architectural governance tool that prevents breaking changes and enforces architectural invariants.
+
+## 🚀 Quick Start
+
+```bash
+# Install globally
+npm install -g @arcvision/cli
+
+# Link to your project
+arcvision link YOUR_PROJECT_TOKEN
+
+# Scan your codebase
+arcvision scan --upload
+
+# Evaluate architectural changes
+arcvision acig . --fail-on-blocked
+```
+
+## 🛡️ Authoritative Change Impact Gate (ACIG)
+
+Prevent architectural violations before they reach production:
+
+```bash
+# Block breaking changes
+arcvision acig . --fail-on-blocked
+
+# Show detailed analysis
+arcvision acig . --verbose
+
+# Simulate changes
+arcvision acig . --simulate-changes "src/core/engine.js,src/api/routes.js"
+```
+
+## 🔧 Core Commands
+
+### `arcvision scan`
+Generate architectural context from your codebase
+
+```bash
+arcvision scan [directory] [--upload]
+```
+
+### `arcvision acig` / `arcvision evaluate`
+Evaluate changes against architectural invariants
+
+```bash
+arcvision acig [directory] [--fail-on-blocked] [--verbose]
+```
+
+### `arcvision override`
+Override blocked decisions with permanent record
+
+```bash
+arcvision override --event-id EVENT_ID --reason "Detailed explanation" --owner "your-name"
+```
+
+### `arcvision ledger`
+Inspect authority ledger records
+
+```bash
+arcvision ledger --stats          # Show statistics
+arcvision ledger --recent-blocks  # Show recent blocked events
+```
+
+### `arcvision diff`
+Compare architectural context between versions
+
+```bash
+arcvision diff old-context.json new-context.json
+```
+
+## 📊 Features
+
+- **Circular Dependency Detection**: Identify architectural cycles
+- **Blast Radius Analysis**: Understand change impact
+- **Invariant Enforcement**: Prevent architectural violations  
+- **Authority Ledger**: Permanent record of decisions
+- **CI/CD Integration**: GitHub Actions and curl scripts
+- **Multi-format Support**: JavaScript, TypeScript, React, Express
+
+## 🎯 Decision Types
+
+- **ALLOWED**: Safe changes that comply with architecture
+- **RISKY**: Changes with warnings - review recommended
+- **BLOCKED**: Violations that must be fixed before merging
+
+## 🔧 Configuration
+
+Create `.arcvision/invariants.json` to define your architectural rules:
+
+```json
+[
+  {
+    "id": "no-circular-deps",
+    "system": "core",
+    "description": "Prevent circular dependencies",
+    "severity": "critical",
+    "scope": { "files": ["src/**/*.js"] },
+    "rule": {
+      "type": "dependency",
+      "condition": { "circular": false }
+    }
+  }
+]
+```
+
+## 📈 Example Output
+
+```
+🔒 Authoritative Change Impact Gate (ACIG)
+Evaluating changes against canonical system invariants...
+
+============================================================
+DECISION: BLOCKED
+============================================================
+❌ CHANGE BLOCKED - Invariant violations detected
+❌ 2 invariant(s) violated:
+  1. Circular dependency detected between src/auth/service.js and src/database/connection.js
+     System: core, Severity: critical
+  2. Authority core modification detected
+     System: security, Severity: critical
+
+[!] AUTHORITATIVE GATE BLOCKED THIS CHANGE
+To override with permanent record, run:
+arcvision override --event-id evt_123456789 --reason "<detailed explanation>" --owner "<your-identifier>"
+
+[WARNING] Override creates permanent architectural scar
+```
+
+## 🛠️ Requirements
+
+- Node.js >= 16.0.0
+- npm or yarn package manager
+
+## 📚 Documentation
+
+- [Full Documentation](https://github.com/arcvision/cli)
+- [API Reference](https://github.com/arcvision/cli/docs)
+- [Invariant System Guide](https://github.com/arcvision/cli/docs/invariant-system.md)
+
+## 🤝 Contributing
+
+Contributions welcome! See our [contributing guidelines](CONTRIBUTING.md).
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file.