Metadata-Version: 2.4
Name: corvinos
Version: 0.1.5
Summary: CorvinOS — universal, self-contained, cross-platform AI assistant framework
Project-URL: Homepage, https://corvin.ai
Project-URL: Documentation, https://corvin.ai/docs
Project-URL: Repository, https://github.com/CorvinLabs/CorvinOS
Project-URL: Issues, https://github.com/CorvinLabs/CorvinOS/issues
Author-email: Shumway <silvio.jurk@googlemail.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,ai,cross-platform,installer,multi-platform
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Shells
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.25
Requires-Dist: cryptography>=42
Requires-Dist: edge-tts>=6.1.8
Requires-Dist: fastapi>=0.110
Requires-Dist: faster-whisper>=1.0.0
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4.0
Requires-Dist: piper-tts>=1.2.0
Requires-Dist: pydantic>=2.4
Requires-Dist: pyjwt[crypto]>=2.8
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: qrcode>=7.0
Requires-Dist: uvicorn[standard]>=0.27
Provides-Extra: all
Requires-Dist: discord-py>=2.0; extra == 'all'
Requires-Dist: duckdb>=0.9; extra == 'all'
Requires-Dist: matplotlib>=3.7; extra == 'all'
Requires-Dist: prometheus-client>=0.19; extra == 'all'
Requires-Dist: psycopg2-binary>=2.9; extra == 'all'
Requires-Dist: python-telegram-bot>=20.0; extra == 'all'
Requires-Dist: slack-bolt>=1.18; extra == 'all'
Requires-Dist: whatsapp-web-py>=0.1; extra == 'all'
Provides-Extra: bridges
Requires-Dist: discord-py>=2.0; extra == 'bridges'
Requires-Dist: python-telegram-bot>=20.0; extra == 'bridges'
Requires-Dist: slack-bolt>=1.18; extra == 'bridges'
Requires-Dist: whatsapp-web-py>=0.1; extra == 'bridges'
Provides-Extra: compute
Requires-Dist: duckdb>=0.9; extra == 'compute'
Requires-Dist: matplotlib>=3.7; extra == 'compute'
Requires-Dist: psycopg2-binary>=2.9; extra == 'compute'
Provides-Extra: console
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: metrics
Requires-Dist: prometheus-client>=0.19; extra == 'metrics'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)"  srcset="docs/assets/banner.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/assets/banner.svg">
  <img src="docs/assets/banner.svg" alt="Corvin — Self-hosted · Multi-engine · Self-improving agent runtime" width="100%">
</picture>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-f0b429?style=flat-square&labelColor=161b22" alt="Apache 2.0"/></a>
  <a href="docs/eu-ai-act/README.md"><img src="https://img.shields.io/badge/EU%20AI%20Act-enforced-3b82f6?style=flat-square&labelColor=161b22" alt="EU AI Act enforced"/></a>
  <a href="docs/audit-and-compliance.md"><img src="https://img.shields.io/badge/GDPR-Art.%206%2C7%2C30%2C32-3b82f6?style=flat-square&labelColor=161b22" alt="GDPR"/></a>
  <img src="https://img.shields.io/badge/engines-Claude%20·%20Codex%20·%20OpenCode%20·%20Hermes%20·%20Copilot-a78bfa?style=flat-square&labelColor=161b22" alt="Engines"/>
</p>

<p align="center">
  <a href="docs/architecture.md">Architecture</a> ·
  <a href="docs/plugin-system.md">Plugin System</a> ·
  <a href="docs/runtime-generation.md">Runtime Generation</a> ·
  <a href="docs/memory-model.md">Memory Model</a> ·
  <a href="docs/data-and-compute.md">Data &amp; Compute</a> ·
  <a href="docs/audit-and-compliance.md">Audit &amp; Compliance</a> ·
  <a href="docs/agent-communication.md"><strong>Agent Communication</strong></a> ·
  <a href="docs/a2a-social-fabric.md"><strong>A2A Social Fabric</strong></a> ·
  <a href="docs/engine-layer.md">Engine Layer</a> ·
  <a href="docs/awpkg.md">Workflow Packages</a>
</p>

<p align="center">
  <code>pip install corvinOS &amp;&amp; corvin-serve</code>
</p>

<p align="center">
  <a href="docs/handbook/README.md"><strong>📖 Web Console Handbook</strong></a> — screenshots and step-by-step guide for every console page
</p>

---

## Quick Start

### Install

```bash
pip install corvinOS
corvin-serve          # opens the web console at http://localhost:8000
```

**Requirements:** Python 3.11+ · Node.js 20+ · Linux, macOS, or WSL2  
**Windows:** use WSL2 (Ubuntu) and run the commands above inside the WSL shell.  
**Default engine:** Claude Code — requires a Claude Pro or Max subscription.
For a fully local, zero-egress setup use `--engine hermes` (Ollama, no API key needed).

### Restore

```bash
corvin-restore             # force-rebuild the web console and restart all services
```

`corvin-restore` stops all services, wipes and rebuilds the React frontend from scratch
(`npm install && npm run build`), then restarts the webui and all bridge services.
Use this after pulling new UI changes or when the console shows a 503 page.

### Uninstall

```bash
corvin-uninstall           # stops services, removes plugins and data (asks before deleting)
pip uninstall corvinOS -y

# Complete purge without any prompts:
corvin-uninstall --purge && pip uninstall corvinOS -y
```

`corvin-uninstall` removes: systemd services and timers · Claude Code plugins · bridge venvs ·
`~/.config/corvin-voice/` (API keys, secrets) · `~/.corvin/` (audit logs, sessions, models).
`pip uninstall` then removes the Python package itself.

### Developer install (from source)

```bash
git clone https://github.com/CorvinLabs/CorvinOS.git
cd CorvinOS
pip install -e ".[all]"
corvin-install
```

---

Corvin turns an LLM-CLI agent into a **learning helper that lives in your chats** — it generates new tools and skills at runtime, remembers what worked, learns from how you react to its replies, and adapts its voice to who's listening. Everything runs on **your** infrastructure, behind **your** whitelist, audited end-to-end on **your** disk.

> **For companies and compliance owners:** engineering teams, CISOs → [`docs/for-companies.md`](docs/for-companies.md).
> Drop your own personas, channels, engines and compliance policies as declarative config — no fork.
> Audit chain is hash-linked, offline-verifiable, tamper-evident.

---

## Features

### 1 — EU AI Act 2026 + GDPR: Built In, Not Bolted On

<img src="docs/assets/compliance.svg" alt="Four compliance pillars: Bot Disclosure (Art. 50), Consent Gate (GDPR Art. 6/7), Hash-Chained Audit (Art. 30/32), Data Residency (Art. 14)" width="100%"/>

Corvin is designed against EU AI Act 2026 and GDPR as **structural constraints** — not as a checkbox layer bolted on afterwards. Every feature must answer: *does this weaken a compliance guarantee?*

| Mechanism | Layer | Regulation | Key property |
|---|---|---|---|
| **Bot Disclosure** card | L19 | EU AI Act Art. 50 | One-time per uid · `/join /pass /leave` · structurally locked |
| **Consent Gate** | L16 | GDPR Art. 6 & 7 | Deny-by-default · TTL-capped · re-validated at every consume |
| **Hash-Chained Audit** | L16 | GDPR Art. 30 & 32 | SHA-256 chain · offline-verifiable · daily auto-verify at 04:30 |
| **Data Residency** | L34 / L35 | EU AI Act Art. 14 | Zone routing · `allowed_engines` / `forbid_engines` allowlist |

**Absolute constraints** (cannot be disabled via any env var, flag, or config):
AI-nature disclosure · audit chain integrity · consent-before-processing · cross-zone LLM call prevention.

**Agentic Communication** (Layer 38) extends these guarantees to agent-to-agent calls: every cross-instance call is HMAC-signed, bidirectionally attested, consent-gated, data-classified, and fully audited — with a no-oracle rejection policy so a probing attacker learns nothing. → [`docs/agent-communication.md`](docs/agent-communication.md)

Corvin instances form a **decentralized agent mesh** — individuals, teams, and companies connect peer-to-peer via Friendship Tokens, with no central server, no platform intermediary, and structural GDPR compliance at every node. → [`docs/a2a-social-fabric.md`](docs/a2a-social-fabric.md)

---

### 2 — Runtime Self-Improvement: The Agent That Writes Its Own Tools

<img src="docs/assets/self-improve.svg" alt="Self-improvement cycle: Chat → Forge (bwrap tool) → SkillForge (markdown skill) → Grading → better next turn" width="100%"/>

Every conversation is a feedback signal. Four layers turn talk into durable capability — no retraining, no annotation team:

| Layer | What it does |
|---|---|
| **Forge** (L6) | Creates a new Python tool at runtime, sandboxed under `bwrap` (no network, fresh `/tmp`); callable as `mcp__forge__<name>` in the same turn |
| **SkillForge** (L7) | Distills knowledge into a `SKILL.md`; linted fail-closed for prompt-injection / homoglyph attacks; injected into the very next bridge turn |
| **Outcome grading** (L15) | Approval → 0.9 · Rejection → 0.1 · Rephrase → 0.3 — your reactions *are* the gradient |
| **Auto-promotion** | task → session (≥1 grade) → project (≥3, mean ≥0.5) → user (explicit). TTL-purge after 7 days without a grade |
| **Method-evolution** | Same rubric violation 3+ times across tasks → LDD surfaces the pattern → update the skill → next session uses the better method |

---

### 3 — Big-Data Compute: Run Calculations Without LLM Round-trips

<img src="docs/assets/bigdata.svg" alt="Three-zone diagram: Dataset on disk → Compute Worker (bwrap isolated, grid/random/bayesian) → LLM firewall → LLM sees only schema+stats+k-anon sample" width="100%"/>

The **Compute Worker** (L25) runs iterative computations — grid search, random search, Bayesian optimisation — directly against large datasets without loading rows into any LLM context:

```
data_register  → register a dataset (path + schema)
compute_run    → kick off a worker job (strategy + params)
compute_status → poll progress
compute_result → fetch the winning parameter set
compute_abort  → cancel a running job
```

Worker is **opt-in** (`compute.enabled: true` in tenant config) and **never auto-starts** from bridge or adapter code. It communicates through a Unix socket (`worker.sock`) — the LLM issues MCP calls, never direct filesystem reads.

---

### 4 — LLM Data Firewall: Raw Data Never Enters the Context Window

The firewall between the Compute Worker and the LLM is **architectural** — not a setting, not a policy file, not a flag. The only path from dataset to LLM context is through `data_snapshot` (L24), which enforces:

| What arrives in context | What is blocked |
|---|---|
| Column names + data types (schema) | Raw rows |
| Aggregate stats: count · mean · min · max · stddev · null-rate | Individual cell values |
| k-anonymised sample, PII-redacted, Laplace-noised (L32) | Un-redacted samples |
| Bucketed distinct-counts with proportional noise | Exact distinct values |
| Total token budget: ≤ 4 000 tokens | Anything exceeding the cap |

**Strict-anonymisation mode** (L32, opt-in): k-anonymity bucketing with k ≥ 5, post-projection PII scan that rejects or redacts before the snapshot is written.

---

### 5 — Any Messenger, Any LLM

**Seven bridge daemons** — WhatsApp, Telegram, Discord, Slack, Email, Teams, Signal — each a separate daemon with its own settings. Settings hot-reload on every read; no restart for whitelist edits, rate-limit changes, or persona tweaks.

**Five LLM backends** via the `WorkerEngine` abstraction: Claude Code (full feature set), Codex CLI (OpenAI), OpenCode (Ollama, OpenRouter, Google), **Hermes** (fully-local NousResearch models via Ollama — zero network egress, CONFIDENTIAL-capable, no cloud API key needed), and **Copilot CLI** (GitHub Copilot — zero incremental cost for Business/Enterprise, worker-only). Swap the backend per persona without touching anything above it.

**All engines share the same path-gate, audit chain, and artifact-registration guarantees** via the Tool Execution Broker. Engine-native commands surface under the **/e:** namespace; Hermes gains MCP tool-calling through the Function-Call Bridge. → [`docs/engine-layer.md`](docs/engine-layer.md)

---

### 6 — More Features

**🎙️ Voice that meets the listener where they are**

The TTS pipeline shapes the voice for the specific person on the other end:

| Field | What it controls |
|---|---|
| `level` | `novice` · `intermediate` · `expert` |
| `jargon` | `0`–`5` (0 = translate every term, 5 = keep all jargon) |
| `style` | `concise` · `verbose` · `example-driven` |
| `background` | free text ≤200 chars (e.g. _"Senior Go-Dev, new to React"_) |
| `learning` | `0`–`3` — appends a structurally-marked **LEARNING ANNEX** after the faithful summary |

Hot-reload: `/voice-user-set learning=2` takes effect on the next TTS turn.

**📦 Installable workflow packages (AWPKG)**

<img src="docs/assets/awpkg-lifecycle.svg" alt="AWPKG lifecycle: AUTHOR → INSPECT → INSTALL → ACTIVE → REMOVED" width="100%"/>

AWP workflows, Forge tools, SkillForge skills and Cowork personas can be bundled into a single `.awpkg` file and shared like app packages:

```bash
corvin pkg install market-research-suite-2.1.0.awpkg
corvin pkg list
corvin pkg remove com.corvin.market-research-suite
```

Eight pre-extraction security checks enforce fail-closed installation. → [`docs/awpkg.md`](docs/awpkg.md)

**🎭 Per-chat personas with auto-routing**

Pin a chat to a persona (`coder`, `research`, `inbox`, `forge`, `orchestrator`, `homeassistant`, `os`, `assistant`) — or let a Haiku-based router pick one per message. Each persona ships with its own MCP servers, tool lists and working directory. Personas are JSON files; author your own.

**🔒 Hash-chained audit, end-to-end verifiable**

Every lifecycle event lands in a SHA-256-chained `audit.jsonl`. `voice-audit verify` walks the chain; a daily systemd timer at 04:30 re-verifies automatically and sends a notification if the chain breaks.

**👥 Multi-user, role-gated**

Owner, admin, member, observer roles with per-chat consent gates and quota management. The proposal stack (`/propose` → `/go`) lets contributors queue steering inputs for the owner to execute atomically.

---

## How it works

<img src="docs/assets/arch.svg" alt="Corvin architecture — channels → Bridge Adapter → WorkerEngine" width="100%"/>

Seven bridge daemons funnel messages into a shared inbox. The **Bridge Adapter** processes them per-chat-sequentially, cross-chat-parallel — enforcing ACL, routing to the right persona, running the TTS pipeline and grading skills. Below that, the **WorkerEngine** abstraction swaps the LLM backend per persona without touching anything above it.

---

## Layer model

<img src="docs/assets/layers.svg" alt="Corvin layer model — stacked opt-in layers" width="100%"/>

Full breakdown in [`docs/layer-model.md`](docs/layer-model.md) · Architecture diagrams in [`docs/diagrams/`](docs/diagrams/).

---

## Services & Configuration

After `pip install corvinOS && corvin-serve` you can configure everything in the web console.
For production use (persistent services, multiple bridges, Docker) see below.

### Run as persistent services

```bash
# Linux / WSL2 — register and start as systemd user services
bash operator/bridges/bridge.sh up
bash operator/bridges/bridge.sh tail        # live log stream

# macOS or any host without systemd — foreground mode
bash operator/bridges/bridge.sh fg

# Web console only — configure in-browser (no Claude Code required)
bash operator/bridges/bridge.sh console     # http://127.0.0.1:8765
```

### Docker

```bash
docker compose -f ops/docker-compose.yml up -d
```

Channel-specific setup (tokens, webhook URLs) is in [`docs/setup.md`](docs/setup.md) and the per-channel `README.md` inside each bridge directory.

---

## Platform support

| Platform | Voice in | Voice out (TTS) | Systemd services | Notes |
|---|---|---|---|---|
| Linux (Ubuntu/Debian/Arch) | ✓ | ✓ | ✓ | Recommended for production |
| macOS | ✓ | ✗ | ✗ (launchd or fg) | Messenger voice notes work; TTS synthesis unavailable |
| WSL2 | ✓ | ✓ | ✓ (optional) | `bridge.sh fg` always works |
| Windows (native) | ✓ | Limited | ✗ | Use WSL2 (Ubuntu) and run `pip install -e ".[all]" && corvin-install` inside the WSL shell |
| Docker | ✓ | ✓ | ✗ (supervisord) | `ops/docker-compose.yml` for production |

---

## Multi-engine support

The `WorkerEngine` protocol (Layer 22) swaps the LLM backend per persona without touching anything above it. Every audit hook, voice layer and LDD discipline stays identical regardless of which CLI drives the turn.

| Engine | Providers | Status |
|---|---|---|
| **Claude Code** | Claude (Anthropic, Pro/Max) | default — full feature set |
| **Codex CLI** | OpenAI (`gpt-4o`, `gpt-5`, …) | shipped — capability-degraded |
| **OpenCode** | Ollama, Ollama Cloud, OpenAI, Google, OpenRouter | shipped — capability-degraded |
| **Hermes** | NousResearch Hermes via local Ollama — **zero egress, no API key** | shipped — L34 CONFIDENTIAL-capable |
| **Copilot CLI** | GitHub Copilot — **zero incremental cost for Business/Enterprise** | shipped — worker-only |
| **Gemini CLI** | Google Gemini | planned |

**Feature matrix** — ✓ native · ⚠ degraded · ✗ unsupported

| Feature | Claude Code | Codex CLI | OpenCode | Hermes | Copilot CLI |
|---|---|---|---|---|---|
| MCP — Forge / SkillForge (L6 / L7) | ✓ | ✓ | ✗ | ✗ (M3 roadmap) | ✗ |
| `Skill` tool — runtime skill loading | ✓ | ✗ | ✗ | ✗ | ✗ |
| PreToolUse hooks — path-gate (L10) | ✓ native | ⚠ teb_brokered | ⚠ teb_brokered | ⚠ teb_brokered | ⚠ teb_brokered |
| `/btw` mid-stream inject (L13) | ✓ | ✗ | ✗ | ✗ | ✗ |
| Per-token streaming | ✓ | ✗ | ✗ | ✓ | ✗ |
| Session continuation | ✓ | ✓ | ✓ | ✗ | ✗ |
| Zero network egress | ✗ | ✗ | ✗ | ✓ | ✗ |
| L34 CONFIDENTIAL-capable | ✗ | ✗ | ✗ | ✓ | ✗ |
| No cloud API key needed | ✗ | ✗ | ✗ | ✓ | ✗ |

**Engine-agnostic layers** (run on every backend regardless): whitelist + audit chain · session lifecycle · LDD-toggle system · outcome-graded skill grading · roles / consent / quotas · voice TTS · speech-to-text.

---

## In-chat slash commands

Everything that isn't a slash command goes straight to the LLM.
German aliases exist for most commands (`/abbruch`, `/halt`, `/hilfe`, `/willkommen`, `/einstellungen`).

### Chat control

| Command | Effect |
|---|---|
| `/on` | enable the AI for this chat |
| `/off` | disable the AI for this chat (owner/admin) |
| `/status` | show this chat's current state (persona, mode, consent, voice) |
| `/all` | open the chat to all members (default: owner-only scope) |
| `/help` | full slash-command reference card |

### Task control

| Command | Effect |
|---|---|
| `/stop`, `/cancel`, `/halt` | SIGTERM the running subprocess |
| `/btw <text>` | inject a follow-up while the task is still running |
| `/new`, `/clear`, `/reset` | purge session: skills + tools + voice state |
| `/debug [on\|off]` | live tool-use stream |

### `/btw` — mid-stream injection

```
you: write me a detailed blog post about loss-driven development
bot: ⏳ working on it…

you: /btw and please cite at least three concrete sources
bot: 📝 note passed to the running task.
     [continues, picks up the citation requirement mid-task]
```

### Personas & engine

| Command | Effect |
|---|---|
| `/personas` | list available roles |
| `/persona <name>` | pin a persona to this chat |
| `/persona reset` | back to default |
| `/whoami`, `/skills` | role + capability overview |
| `/engine <name>` | pin worker engine per-chat: `claude` · `codex` · `opencode` · `hermes` (local Ollama, zero egress) |

### Voice

| Command | Effect |
|---|---|
| `/voice-on`, `/voice-off` | enable / disable read-aloud |
| `/voice-auto` · `/voice-full` · `/voice-summary` | reading mode |
| `/voice-status` | current TTS mode + engine |
| `/voice-lang <auto\|de\|en>` | force TTS language |
| `/voice-user-set <key>=<value>` | level · jargon · style · background · metaphors · domains · learning |
| `/voice-user-show` / `/voice-user-preview` / `/voice-user-clear` | inspect · preview · reset |

### Profile / memory / vault

| Command | Effect |
|---|---|
| `/profile show / set / get / rm / reset` | bridge-wide profile injected into every reply |
| `/memory list / show / write / append / forget` | long-term memory topics |
| `/vault list / get / set / unlock / forget / audit` | secrets vault, audit-logged |
| `/auth-up <pin>` | time-bounded elevation for forge / skill-forge promotion (L16) |
| `/goal set <text>` / `/goal show` / `/goal clear` | session goal pinned into every turn |
| `/settings` | full system-state dump for this chat |

### Rights & access (L18–L21)

How team members join, consent, and collaborate in a shared chat:

| Command | Who | Effect |
|---|---|---|
| `/join` | anyone | self-register as observer; triggers one-time bot-disclosure card (EU AI Act Art. 50) |
| `/pass` | anyone | acknowledge the disclosure card without joining |
| `/leave` | any member | give up your own granted role |
| `/consent on \| off \| <ttl>` | observer | control observer-transcript sharing; deny-by-default (GDPR Art. 6/7) |
| `/role` | anyone | show your own role + capabilities |
| `/roles` | admin+ | list every member in this chat with their role |
| `/grant <@user> <role>` | owner/admin | delegate authority — member · observer |
| `/revoke <@user>` | owner/admin | drop a member's granted role |
| `/quota` | anyone | show your own usage budget for today |
| `/audit` | admin+ | tail the tamper-evident audit log for this chat |

### Proposals (L21)

Contributors queue steering inputs; the owner executes them atomically:

| Command | Effect |
|---|---|
| `/propose <text>` | add a steering input to the stack (max 50 items · 2 000 chars each) |
| `/proposals` | list the current proposal stack |
| `/go [steering]` | owner executes the stack — consumed atomically before the LLM turn |

### A2A agent network (L38)

| Command | Effect |
|---|---|
| `/agents` | list all known named remote agents |
| `/a2a <agent> <instruction>` | send a signed instruction to a named remote agent |
| `/a2a-label <id> <name>` | give a remote agent a friendly display name |

### Workflow packages (L26)

| Command | Effect |
|---|---|
| `/workflow list` / `/workflow show <id>` | browse available AWP workflow packages |
| `/workflow run <id>` / `/workflow cancel <id>` | execute or abort a workflow |

### Layer toggles (L11 · L14)

| Command | Effect |
|---|---|
| `/dialectic-on` · `/dialectic-off` | global dialectic reasoning switch |
| `/dialectic-status` | current modes + thresholds for all six sites |
| `/dialectic-set <site> <mode>` | per-site override: `fast` · `skill` · `llm` · `off` |
| `/dialectic-show` | toggle per-reply dialectic footer |
| `/ldd-on` · `/ldd-off` | LDD master switch |
| `/ldd-status` | master + per-layer state (all 12 layers) |
| `/ldd-set <layer> on\|off` | toggle a single LDD layer |
| `/ldd-preset <name>` | swap to a named LDD config preset |

### Advanced / operator

| Command | Effect |
|---|---|
| `/ps` | process table — active Claude sessions with token usage |
| `/kill <id>` | terminate a session by process ID |
| `/sig <id> <signal>` | send `KILL` · `PLAN` · `SUMMARIZE` · `CONTEXT_DROP` · `QUIET` · `RESUME` |
| `/budget` | context budget + token usage for this chat |

---

## Deep-dive docs

| Subsystem | Doc | What's inside |
|---|---|---|
| 🛠️ Tool Creation | [docs/forge.md](docs/forge.md) | runtime sandboxed Python tools — bwrap, schema-bound I/O, per-persona network policy, output streaming, audit chain |
| 📝 Skill Creation | [docs/skills.md](docs/skills.md) | runtime knowledge artifacts — linter (NFKC + confusables), outcome-grading, scope ladder, slot-mirror |
| 🎭 Personas & Routing | [docs/personas-and-routing.md](docs/personas-and-routing.md) | per-chat agent roles, auto-routing (heuristic / embedding), ACL allowlist, namespace gates |
| 🔒 Security Model | [docs/security.md](docs/security.md) | six enforcement surfaces — whitelist, persona ACL, policy, sandbox, path-gate, operator elevation — plus audit chain |
| 👥 Rights & Teamwork | [docs/rights-and-teamwork.md](docs/rights-and-teamwork.md) | owner / admin / member / observer roles, bot-disclosure card, consent gate, proposal stack, per-user quotas |
| 📦 Workflow Packages | [docs/awpkg.md](docs/awpkg.md) | AWPKG format — archive layout, manifest schema, lifecycle, security checks, CLI, audit events, fixture workflows |
| 🏛️ EU AI Act & GDPR | [docs/eu-ai-act/README.md](docs/eu-ai-act/README.md) | compliance hub — risk classification, article-to-layer mapping, operator quick-start, regulator evidence commands |
| 🏗️ Architecture | [docs/architecture.md](docs/architecture.md) | full system architecture, component boundaries, extension points |

Full doc index at [`docs/README.md`](docs/README.md).

---

## Testing

```bash
bash operator/bridges/run-all-tests.sh
```

Test suites span the Python adapter, Node daemon-boot smoke tests, cowork, forge, skill-forge and all security layers. Tests run hermetically — inbox/outbox under `/tmp`, claude stubbed via `ADAPTER_FAKE_CLAUDE=1`, real `bwrap` where namespace isolation is the actual subject under test.

---

## Storage layout

| Path | Contents |
|---|---|
| `~/.config/corvin-voice/` | TTS engine config · listener profile · `.env` |
| `<repo>/.corvin/global/` | user-scope forge tools · skills · audit chain |
| `<repo>/.corvin/sessions/<bridge>:<chat>/` | session-scope tools · skills · voice state |
| `<repo>/operator/skill-forge/skills/dyn/` | engine-facing slot mirror (gitignored) |

Override the workspace root via `CORVIN_HOME=/path/to/dir` (useful for tests and CI). The legacy alias `CORVIN_HOME` is still accepted.

---

## Security model

Whitelists gate the bridge edge; every chat outside the whitelist is silently dropped. Inside the whitelist, the **path-gate hook** (L10) keeps forge / skill-forge workspaces safe from direct `Write` / `Edit` / `Bash` writes — regardless of the persona's `permission_mode`. The MCP servers are the only writable path. Every lifecycle event lands in a SHA-chained `audit.jsonl` that `voice-audit verify` walks end-to-end.

Full threat model in [`docs/security.md`](docs/security.md).

---

## Sponsorship

Corvin is free and open source. If it saves you time, keeps you compliant, or just sparks ideas — consider sponsoring the project.

<p align="center">
  <a href="https://github.com/sponsors/veegee82">
    <img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?style=for-the-badge&logo=github&logoColor=white" alt="Sponsor on GitHub"/>
  </a>
</p>

Sponsorship directly funds continued development, security audits, and the infrastructure needed to maintain structural EU AI Act compliance guarantees across every release.

---

## License

Licensed under the [Apache License, Version 2.0](LICENSE) — free for all uses,
including internal production use and building commercial products on top of Corvin.

"Corvin" (and its former name "corvinOS") remain project identifiers per Apache § 6 —
the license does not grant trademark rights. Forks under a different name are welcome.

### Contributing

By opening a pull request you accept [`CLA.md`](CLA.md).
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow.
