ApiliumCode · ApiliumDevTeam · Mar 5, 2026 · Mar 2, 2026 · Mar 2, 2026 · Mar 2, 2026
diff --git a/.gitignore b/.gitignore
@@ -132,3 +132,22 @@ USER.md
 # Claude Code project instructions (local only)
 CLAUDE.md
 **/CLAUDE.md
+
+.claude/RULES.md
+
+docs/evolution/
+
+# JetBrains plugin build artifacts
+tools/jetbrains-plugin/.gradle/
+tools/jetbrains-plugin/build/
+
+# VSCode extension build artifacts
+tools/vscode-extension/dist/
+tools/vscode-extension/*.vsix
+tools/vscode-extension/.claude/
+
+tools/PUBLISHING.md
+docs/internal/
+
+# IDE workspace settings (may contain tokens)
+.vscode/
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,169 @@
+# MAYROS v0.1.0 — Project Instructions
+
+## Project Info
+
+- **Product**: [apilium.com/us/products/mayros](https://apilium.com/us/products/mayros)
+- **Download**: [mayros.apilium.com](https://mayros.apilium.com)
+- **Documentation**: [apilium.com/us/doc/mayros](https://apilium.com/us/doc/mayros)
+- **Repo (public)**: [github.com/ApiliumCode/mayros](https://github.com/ApiliumCode/mayros)
+- **Repo (dev)**: `/Users/carlostovar/repositorios/apilium/maryosCode`
+- **AIngle**: [github.com/ApiliumCode/aingle](https://github.com/ApiliumCode/aingle)
+- **Skills Hub**: [github.com/ApiliumCode/skills-hub](https://github.com/ApiliumCode/skills-hub)
+
+## Repository Structure
+
+```
+src/                          # Core: CLI, commands, infra, media, agents
+extensions/                   # Plugin extensions (38 packages)
+  semantic-skills/            # Semantic skill SDK, 6 tools, sandbox
+    sandbox/                  # QuickJS WASM sandbox (quickjs-sandbox, marshal, transpiler)
+  agent-mesh/                 # Multi-agent coordination, delegation, fusion
+  skill-hub/                  # Apilium Hub marketplace, Ed25519 signing
+  memory-semantic/            # AIngle Cortex integration
+  semantic-observability/     # Trace emitter, decision graph
+  token-economy/              # Budget tracking, prompt cache
+  shared/                     # CortexClient, cortex-config, cortex-resilience
+  iot-bridge/                 # IoT node fleet management
+skills/examples/              # 5 example skills (verify-kyc, code-review, etc.)
+docs/                         # Product page, architecture docs
+```
+
+## Build & Test
+
+- Runtime: **Node >= 22**, pnpm 10.23.0
+- Install: `pnpm install`
+- Build: `pnpm build`
+- Tests: `pnpm test` (vitest) — 9205 tests, 1035 files
+- Type check: `pnpm tsgo` or `npx tsc --noEmit`
+- Sync extension versions: `pnpm plugins:sync` (reads root package.json)
+
+## Coding Conventions
+
+- TypeScript ESM, strict typing, no `any`
+- Plugin SDK: `@sinclair/typebox` for params, manual config validation (not Zod)
+- Tests: colocated `*.test.ts`, vitest
+- Product name: **Mayros** (headings), `mayros` (CLI, paths, config)
+- Extensions: keep plugin deps in extension `package.json`, not root
+
+## Security Architecture (18 layers)
+
+### Sandbox (Phase 7)
+
+Skills run in **QuickJS WASM** (`quickjs-emscripten@0.31.0`). The sandbox exposes only 7 host functions:
+
+- `graphClient`: createTriple, listTriples, patternQuery, deleteTriple
+- `logger`: info, warn, error
+
+**No access to**: fs, net, process, require, import, fetch, setTimeout, Worker, eval (harmless in WASM).
+
+Config: `extensions/semantic-skills/config.ts` — `SkillSandboxConfig`
+
+- `sandboxEnabled` (default: true) — false requires `MAYROS_UNSAFE_DIRECT_LOAD=1`
+- `memoryLimitBytes` (1MB–256MB, default 8MB)
+- `maxStackSizeBytes` (64KB–8MB, default 512KB)
+- `executionTimeoutMs` (100–60000, default 10s)
+- `maxCallsPerMinute` (1–1000, default 60)
+
+### Static Scanner (`src/security/skill-scanner.ts`)
+
+16 rules (12 line + 4 source):
+
+- dangerous-exec, dynamic-code-execution, crypto-mining, suspicious-network
+- semantic-unbounded-query, semantic-unproven-assertion
+- bracket-property-exec, dynamic-require, global-this-access, process-env-bracket, dynamic-import
+- potential-exfiltration, obfuscated-code (hex + base64), env-harvesting
+
+**Anti-evasion preprocessing** (H5):
+
+- `stripComments()` — preserves string literals, strips // and /\* \*/
+- `joinSplitStatements()` — tracks parens balance across lines (catches `eval\n(...)`)
+- `countNetParens()` — skips parens inside string literals
+
+### Enrichment Sanitizer (`extensions/semantic-skills/enrichment-sanitizer.ts`)
+
+- **Unicode normalization** (C3): NFC + homoglyph map (Cyrillic/Greek→ASCII) + zero-width strip + fullwidth collapse
+- **8 injection patterns**: ignore/disregard previous, you are/act as, system:override, execute the following, new instructions, important: you must, curl/wget/bash, rm -rf
+- **Depth limits**: MAX_DEPTH=4, MAX_ARRAY_LENGTH=50, MAX_STRING_LENGTH=512, MAX_ENRICHMENT_CHARS=4096
+- **Output**: wrapped in `<skill-enrichment type="data">` tags
+
+### Namespace Isolation
+
+- `enforceNsPrefix()` in index.ts — ALL queries forced to `${ns}:` prefix
+- scope:"global" is capped to own namespace (no cross-namespace)
+- scope:"agent" → `${ns}:agent:${agentId}`
+- Sandbox graphClient enforces ns prefix on createTriple/deleteTriple/listTriples/patternQuery
+- `skill_memory_context` scopes subject to `${ns}:` + defense-in-depth filter
+
+### Tool Allowlist
+
+- **Intersection model**: ALL active skills must allow a tool (not just any one)
+- Default: `DEFAULT_ALLOWED_TOOLS` (9 safe tools) applied when manifest omits allowedTools
+- `["*"]` escape hatch for unrestricted access
+- 6 core semantic tools always allowed
+
+### Rate Limiter
+
+- `SkillRateLimiter` class — sliding window (1-minute) per skill
+- Applied to: `skill_graph_query`, `skill_assert`, `skill_memory_context`
+- Default: 60 calls/min, configurable via `maxCallsPerMinute`
+
+### Query & Write Limits
+
+- Per-skill query counter (`queryCountPerSkill` Map)
+- `maxQueries` per manifest + global cap = maxGraphQueries x activeSkillCount
+- Write limits per sandbox (createTriple/deleteTriple)
+- `checkWriteLimit()` in QuickJS sandbox
+
+### Enrichment Timeout
+
+- `invokeQuery()` wrapped in `Promise.race()` with 2s timeout (C5)
+- Prevents DoS via slow enrichment
+
+### Hot-Reload Security
+
+- **Atomic swap** (H6): build temp maps → clear → swap
+- **Manifest validation** (H7): `validateManifest()` on reload
+- **Downgrade block**: rejects if `allowedTools` removed from original
+- **Diff logging**: `diffManifests()` logs changes to allowedTools, permissions, assertions, maxQueries
+
+### Other Controls
+
+- Path traversal: reject `..` + `isPathInside()` double-check
+- Verify-then-promote: temp extract → verify hashes → atomic promote
+- Circuit breaker: 3-state (closed/open/half-open) + exponential backoff
+- Audit logging: skill name + operation tagged on all sandbox writes
+- No default AssertionEngine: `skill_assert` / `skill_verify_assertion` fail without declared engine
+- Per-request skill tracking: `resolveCurrentSkill()` round-robin for multi-skill
+
+## Versioning
+
+- Mayros: **v0.1.0** (package.json + 38 extensions synced)
+- Cortex: aingle_cortex **0.2.6** (`REQUIRED_CORTEX_VERSION`)
+- Crates: aingle 0.0.101, zome_types 0.0.4
+- Sync versions: update root `package.json` → `pnpm plugins:sync`
+- Release: `git tag v0.1.0 && git push origin v0.1.0`
+
+## Key Files
+
+| File                                                    | Purpose                                                                  |
+| ------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `extensions/semantic-skills/index.ts`                   | Plugin entry: 6 tools, 3 hooks, CLI, rate limiter, namespace enforcement |
+| `extensions/semantic-skills/config.ts`                  | SkillSandboxConfig, VerificationConfig, clampInt                         |
+| `extensions/semantic-skills/sandbox/quickjs-sandbox.ts` | QuickJS WASM sandbox core                                                |
+| `extensions/semantic-skills/enrichment-sanitizer.ts`    | Injection detection + Unicode normalization                              |
+| `extensions/semantic-skills/skill-loader.ts`            | Sandbox/direct loading, scan gate, enrichment sanitization               |
+| `extensions/semantic-skills/skill-manifest.ts`          | Manifest parsing, DEFAULT_ALLOWED_TOOLS, validation                      |
+| `extensions/semantic-skills/permission-resolver.ts`     | Tool allowlist, permission checking                                      |
+| `src/security/skill-scanner.ts`                         | 16-rule scanner + preprocessing                                          |
+| `extensions/shared/cortex-client.ts`                    | Unified CortexClient, DTOs                                               |
+| `extensions/shared/cortex-resilience.ts`                | CircuitBreaker + resilientFetch                                          |
+
+## Translations (i18n)
+
+| Language        | Dir           | Status                            |
+| --------------- | ------------- | --------------------------------- |
+| Chinese (zh-CN) | `docs/zh-CN/` | **Complete**                      |
+| Spanish (es)    | `docs/es/`    | Pending — full translation needed |
+| Japanese (ja)   | `docs/ja/`    | Pending — full translation needed |
+| Korean (ko)     | `docs/ko/`    | Pending — full translation needed |
+| Hindi (hi)      | `docs/hi/`    | Pending — full translation needed |
diff --git a/README.md b/README.md
@@ -114,6 +114,77 @@ Run `mayros doctor` to surface risky/misconfigured DM policies.
 - **[First-class tools](https://apilium.com/en/doc/mayros/tools)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
 - **[Companion apps](https://apilium.com/en/doc/mayros/platforms/macos)** — macOS menu bar app + iOS/Android [nodes](https://apilium.com/en/doc/mayros/nodes).
 - **[Onboarding](https://apilium.com/en/doc/mayros/start/wizard) + [skills](https://apilium.com/en/doc/mayros/tools/skills)** — wizard-driven setup with bundled/managed/workspace skills.
+- **Terminal UI** — interactive TUI with themes, vim mode, image paste, slash commands.
+- **IDE plugins** — VSCode + JetBrains extensions connected via Gateway WebSocket.
+- **Knowledge Graph** — project memory, code indexer, cross-session recall via Cortex.
+- **Multi-agent mesh** — teams, workflows, agent mailbox, background tasks.
+- **Semantic plan mode** — explore, assert, approve, execute with Cortex backing.
+- **50+ extensions** — security sandbox, permissions, MCP client, observability, 17 channels.
+
+## Terminal UI
+
+Mayros includes an interactive terminal interface for direct coding and conversation.
+
+**Entry points:**
+
+- `mayros code` — main interactive TUI session
+- `mayros tui` — alias for `mayros code`
+- `mayros -p "query"` — headless mode (non-interactive, streams response to stdout)
+
+**Features:**
+
+- Welcome screen with shield mascot and two-column info panel
+- 3 themes (dark, light, high-contrast) — switch with `/theme`
+- 3 output styles (standard, explanatory, learning) — switch with `/style`
+- Vim mode with motions, operators, and undo — toggle with `/vim`
+- `Ctrl+V` image paste from clipboard
+- `/copy` pipes last response to system clipboard; `/export [file]` writes to file
+- `/diff` inline diff viewer with stats
+- `/context` token usage bar chart
+- `/plan` semantic plan mode (Cortex-backed)
+
+**Key slash commands:**
+
+| Command          | Description                 |
+| ---------------- | --------------------------- |
+| `/help`          | List all available commands |
+| `/new`, `/reset` | Reset session               |
+| `/compact`       | Compact session context     |
+| `/think <level>` | Set thinking level          |
+| `/model <name>`  | Switch model                |
+| `/plan`          | Enter semantic plan mode    |
+| `/diff`          | Show pending changes        |
+| `/context`       | Visualize token usage       |
+| `/theme`         | Cycle themes                |
+| `/style`         | Cycle output styles         |
+| `/vim`           | Toggle vim mode             |
+| `/copy`          | Copy last response          |
+| `/export [file]` | Export session              |
+| `/permission`    | Set permission mode         |
+| `/fast`          | Toggle fast mode            |
+
+**Markdown-driven extensibility:**
+
+- Custom agents: `~/.mayros/agents/*.md` — define persona, tools, and behavior in markdown
+- Custom commands: `~/.mayros/commands/*.md` — define slash commands as markdown templates
+- Interactive selectors when commands run without required arguments
+
+## IDE Plugins
+
+Mayros provides IDE extensions that connect to the running Gateway via WebSocket.
+
+**VSCode** (`tools/vscode-extension/`):
+
+- Sidebar tree views: sessions, agents, skills
+- Webview panels: chat, plan mode, trace viewer, knowledge graph
+- Context menu actions and gutter markers
+
+**JetBrains** (`tools/jetbrains-plugin/`):
+
+- Unified tabbed panel with the same feature set
+- Protocol v3 compatibility
+
+Both plugins connect via WebSocket to `ws://127.0.0.1:18789` (the Gateway).
 
 ## Semantic Memory (AIngle Cortex)
 
@@ -132,6 +203,74 @@ Key design points:
 
 Cortex version: **aingle_cortex 0.2.6** · AIngle crate: **0.0.101** · Zome types: **0.0.4**
 
+## Knowledge Graph & Code Indexer
+
+The code indexer scans your codebase and maps it to RDF triples stored in Cortex. Combined with project memory, this gives the assistant deep, persistent understanding of your project.
+
+- **Code indexer** — scans source files → RDF triples in Cortex (incremental, only re-indexes changed files)
+- **Project memory** — persists conventions, findings, and architecture decisions across sessions
+- **Smart compaction** — extracts key information before context pruning so nothing important is lost
+- **Cross-session recall** — injects relevant knowledge from previous sessions into new prompts
+
+CLI: `mayros kg search|explore|query|stats|triples|namespaces|export|import`
+
+## Multi-Agent Mesh
+
+Mayros supports coordinated multi-agent workflows where agents can form teams, delegate work, and communicate asynchronously.
+
+- **Team manager** — Cortex-backed lifecycle: create, assign roles, disband
+- **Workflow orchestrator** — built-in workflow definitions (code-review, research, refactor) + custom definitions via registry
+- **Agent mailbox** — persistent inter-agent messaging (send/inbox/outbox/archive)
+- **Background task tracker** — track long-running agent tasks with status and cancellation
+- **Git worktree isolation** — each agent can work in its own worktree to avoid conflicts
+
+CLI: `mayros workflow run|list`, `mayros dashboard team|summary|agent`, `mayros tasks list|status|cancel|summary`, `mayros mailbox list|read|send|archive|stats`
+
+## Plan Mode
+
+Cortex-backed semantic planning for complex multi-step tasks.
+
+- **Explore** — gather context from the codebase and Cortex graph
+- **Assert** — declare facts and constraints the plan must satisfy
+- **Approve** — review the plan before execution
+- **Execute** — run the approved plan with progress tracking
+
+CLI: `mayros plan start|explore|assert|show|approve|execute|done|list|status`
+TUI: `/plan` slash command
+
+## Extensions Ecosystem
+
+Mayros ships with 50+ extensions organized by category:
+
+| Category      | Extension                 | Purpose                                                                   |
+| ------------- | ------------------------- | ------------------------------------------------------------------------- |
+| Skills        | `semantic-skills`         | QuickJS WASM sandbox, 6 semantic tools, skill marketplace                 |
+| Agents        | `agent-mesh`              | Teams, workflows, delegation, mailbox, background tasks                   |
+| Memory        | `memory-semantic`         | Cortex integration, rules engine, agent memory, contextual awareness      |
+| Observability | `semantic-observability`  | Traces, decision graph, session fork/rewind                               |
+| Indexer       | `code-indexer`            | Codebase scanning + RDF mapping (incremental)                             |
+| Security      | `bash-sandbox`            | Command parsing, domain checker, blocklist, audit log                     |
+| Permissions   | `interactive-permissions` | Runtime permission dialogs, intent classification, policy store           |
+| Hooks         | `llm-hooks`               | Markdown-defined hook evaluation with safe condition parser               |
+| MCP           | `mcp-client`              | Model Context Protocol client (stdio, SSE, WebSocket, HTTP transports)    |
+| Economy       | `token-economy`           | Budget tracking, prompt cache optimization                                |
+| Hub           | `skill-hub`               | Apilium Hub marketplace, Ed25519 signing, dependency audit                |
+| IoT           | `iot-bridge`              | IoT node fleet management                                                 |
+| Channels      | 17 channel plugins        | Discord, Telegram, WhatsApp, Slack, Signal, iMessage, Teams, Matrix, etc. |
+
+Extensions live in `extensions/` and are loaded as plugins at startup.
+
+## Hooks System
+
+Mayros exposes 29 hook types across the assistant lifecycle:
+
+- **Lifecycle hooks** — `before_prompt_build`, `after_response`, `before_compaction`, `agent_end`, etc.
+- **Security hooks** — `permission_request` (modifying: allow/deny/ask), `config_change`
+- **Coordination hooks** — `teammate_idle`, `task_completed`, `notification` (info/warn/error)
+- **HTTP webhook dispatcher** — POST delivery with HMAC-SHA256 signatures, retry + exponential backoff
+- **Async hook queue** — background execution with concurrency limits and dead-letter queue
+- **Markdown-defined hooks** — place `.md` files in `~/.mayros/hooks/` for custom hook logic
+
 ## Everything we built so far
 
 ### Core platform
@@ -176,6 +315,23 @@ Cortex version: **aingle_cortex 0.2.6** · AIngle crate: **0.0.101** · Zome typ
 - [Docker](https://apilium.com/en/doc/mayros/install/docker)-based installs.
 - [Doctor](https://apilium.com/en/doc/mayros/gateway/doctor) migrations, [logging](https://apilium.com/en/doc/mayros/logging).
 
+### Developer tools
+
+- Terminal UI (`mayros code`) with themes, vim mode, slash commands, image paste, and headless mode (`mayros -p`).
+- VSCode and JetBrains IDE plugins connected via Gateway WebSocket.
+- Trace CLI (`mayros trace`), plan CLI (`mayros plan`), knowledge graph CLI (`mayros kg`).
+
+### Agent coordination
+
+- Teams, workflows, agent mailbox, background task tracker.
+- Session fork/rewind for checkpoint-based exploration.
+- Rules engine with hierarchical Cortex-backed rules.
+- Agent persistent memory and contextual awareness notifications.
+
+### Security layers
+
+- 18-layer security architecture: QuickJS WASM sandbox, static scanner (16 rules), enrichment sanitizer, bash sandbox, interactive permissions, namespace isolation, tool allowlist (intersection model), rate limiter, query/write limits, enrichment timeout, hot-reload validation, path traversal protection, verify-then-promote, circuit breaker, audit logging, and more.
+
 ## How it works (short)
 
 ```
@@ -188,6 +344,8 @@ WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBu
 │     ws://127.0.0.1:18789      │
 └──────────────┬────────────────┘
                │
+               ├─ TUI (mayros code)
+               ├─ VSCode / JetBrains
                ├─ Pi agent (RPC)
                ├─ CLI (mayros …)
                ├─ WebChat UI
@@ -263,6 +421,8 @@ Skills Hub is a minimal skill registry. With Skills Hub enabled, the agent can s
 
 ## Chat commands
 
+The Terminal UI (`mayros code`) supports 30+ slash commands — run `/help` for the full list.
+
 Send these in WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat (group commands are owner-only):
 
 - `/status` — compact session status (model + tokens, cost when available)