git clone https://github.com/hyperpolymath/wokelang.git
cd wokelang

# Install dependencies (asdf + tools)
asdf install  # installs rust, deno, idris2, zig

# Build
cargo build --release

2. Run the REPL

cargo run --release -- repl

Example REPL Session:

wokelang> remember x = 5 measured in km
wokelang> x + 3 measured in km
Result: 8 measured in km

3. Run Examples

# Hello World
cargo run --release -- run examples/01_hello.woke

# Fibonacci
cargo run --release -- run examples/13_fibonacci.woke

# All examples
ls examples/*.woke

4. Build & Execute

# Compile to bytecode
cargo run --release -- compile examples/01_hello.woke -o hello.wbc

# Run on VM
cargo run --release -- run-vm hello.wbc

```markdown
## 🌟 Key Features

| Feature               | Example                                  | Why It’s Special                          |
|-----------------------|------------------------------------------|-------------------------------------------|
| **Human Syntax**      | `to add(a, b) -> a + b`                  | Reads like plain English.                 |
| **Empathy Annotations** | `@feeling(confident=true)`              | Codes with emotional context.             |
| **Consent Gates**     | `only if okay "Delete?" { ... }`         | Ethical scaffolding for dangerous ops.    |
| **Gratitude Blocks**  | `thanks to { "Alice" → "Fixed X!" }`      | Acknowledges contributors in code.       |
| **Units of Measure**  | `5 measured in km`                       | Prevents unit-related bugs.               |
| **Pipelines**         | `data then clean then analyze`           | Intuitive data transformations.          |
| **Vyper FFI**         | `vyper call "gratitude.add_entry"`      | Immutable, auditable blockchain ops.      |
| **WASM Target**       | Compile to run in browsers/Node.js.      | Portable and fast.                       |

## 📦 Project Structure

```bash
wokelang/
├── .bot_directives/     # Bot constraint files for gitbot-fleet
├── .claude/             # Project-specific AI instructions
├── .github/workflows/   # CI/CD (Hypatia, CodeQL, Scorecard)
├── .machine_readable/   # Machine-readable metadata
│   └── 6scm/           # SCM checkpoint files
├── contractiles/        # Contractile definitions
│   ├── dust/           # External dependencies
│   ├── k9/             # Security constraints
│   ├── lust/           # Desired features
│   ├── must/           # Required features & must runner
│   └── trust/          # Trust boundaries
├── docs/               # Documentation
│   ├── architecture/   # Architecture docs (COMPILER-ROADMAP.adoc)
│   ├── sessions/       # Development session reports
│   ├── ABI-FFI-README.adoc        # ABI/FFI integration guide
│   ├── DEPLOYMENT.adoc            # Deployment documentation
│   ├── GAP-ANALYSIS.adoc          # Implementation gaps
│   ├── NEXT-STEPS.adoc            # Development roadmap
│   ├── PALIMPSEST.adoc            # License philosophy
│   ├── PROVEN.md                  # proven library integration
│   └── WORKERS.adoc               # Worker documentation
├── examples/           # Example WokeLang programs
├── ffi/
│   └── zig/           # Zig FFI implementation (C ABI)
│       └── src/
├── license/            # License files
│   └── PMPL-1.0-or-later.txt
├── scripts/
│   ├── install-hooks.sh  # Install git hooks
│   └── setup.sh          # Setup script
├── site/               # wokelang.org website
│   ├── content/        # Markdown content
│   ├── templates/      # Tera templates
│   └── config.yaml     # Site configuration
├── src/
│   ├── abi/            # Idris2 ABI definitions with formal proofs
│   │   ├── Foreign.idr
│   │   ├── Layout.idr
│   │   └── Types.idr
│   ├── ast/            # Abstract Syntax Tree
│   ├── interpreter/    # Tree-walking interpreter
│   ├── lexer/          # Token generation (logos)
│   ├── parser/         # Parser (tokens → AST)
│   ├── stdlib/         # Standard library modules
│   │   ├── array.rs
│   │   ├── chan.rs     # Go-style channels
│   │   ├── io.rs       # File I/O with consent
│   │   ├── math.rs
│   │   ├── net.rs      # HTTP with consent
│   │   ├── string.rs
│   │   └── time.rs
│   ├── typechecker/    # Hindley-Milner type inference
│   ├── vm/             # Bytecode VM
│   │   ├── bytecode.rs
│   │   ├── compiler.rs
│   │   ├── machine.rs
│   │   └── optimizer.rs
│   ├── main.rs         # CLI entry point
│   └── repl.rs         # REPL
├── tests/              # Test suite
├── .tool-versions      # asdf tool versions (rust, deno, idris2, zig)
├── AI.a2ml             # AI assistant instructions
├── Cargo.toml          # Rust dependencies
├── .machine_readable/6a2/ECOSYSTEM.a2ml       # Ecosystem relationships
├── .machine_readable/6a2/META.a2ml            # Architectural decisions
├── .machine_readable/6a2/STATE.a2ml           # Current project state
└── README.adoc         # This file

## 🛠 Development

### Must Runner (Contractile Enforcement)

WokeLang uses a **Mustfile** (in `contractiles/must/`) to enforce mandatory checks:

```bash
# Run all mandatory checks (security, tests, format)
must run

# Individual checks
just lint    # Security checks
just test    # Test suite
just fmt     # Code formatting

# Install asdf
git clone https://github.com/asdf-vm/asdf.git ~/.asdf

# Install plugins
asdf plugin add rust
asdf plugin add deno
asdf plugin add idris2
asdf plugin add zig

# Install versions (from .tool-versions)
asdf install

# Build
cargo build --release