docs: rewrite README with security-first positioning

README.md

@@ -1,16 +1,39 @@
 # Madz
 
-**A personality-driven AI harness channeling Mads Mikkelsen's cinematic soul.** | [denkerne.ai](https://denkerne.ai)
+**A security-first, self-contained autonomous coding agent — with a cinematic soul.** | [denkerne.ai](https://denkerne.ai)
 
 [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE)
 [![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#testing)
 
-`madz` is a Node.js AI harness that combines a terminal-based UI with structured skill execution and a distinctive personality. Drawn from Mads Mikkelsen's most iconic roles, it speaks with calm, precision, and quiet intensity — solving problems with style, remembering your context, safely running your skills, and automating the mundane. Everything is persisted as version-controllable Markdown files, making it easy to audit with `git log` and re-load across sessions. Built on LangGraph, OpenTelemetry, and Ink — with persistent memory, sandboxed skill execution, cron scheduling, and a React-powered TUI.
+`madz` is a fully self-contained development environment wrapped around an autonomous coding agent. It ships with a complete toolchain — Node.js, Python, Ruby, Go, Java, Rust, Terraform, Chromium, and more — plus a Deep Agents orchestrator, a sandboxed skill runtime, persistent memory, and a terminal UI. It's the whole package: a container you run, an agent you reach over SSH, and a teammate you trust to do real work in environments where auditability and containment matter.
+
+More than a tool, it's a **digital teammate** — one that remembers your context, adapts to how you work, and speaks with the calm, measured precision of Mads Mikkelsen's most iconic roles. It doesn't just execute; it engages. It has a personality, a memory, and a point of view — and it brings all three to the work.
+
+Everything is persisted as version-controllable Markdown files, so the entire state of the system — memory, context, sessions, schedules — is auditable with `git log` and re-loadable across sessions. Built on LangGraph, OpenTelemetry, and Ink, with persistent memory, sandboxed skill execution, cron scheduling, and a React-powered TUI.
+
+## The Personality
+
+`madz` isn't a blank slate. It's built on a persona — the cinematic soul of Mads Mikkelsen — and that persona shapes how it works with you. It's not decoration; it's the difference between a tool that answers and a teammate that engages.
+
+| Character | Source | When it shows up |
+|-----------|--------|------------------|
+| **Hannibal Lecter** | *Hannibal* (2013–2015) | Code review, security audit, architectural critique, critical analysis |
+| **Le Chiffre** | *Casino Royale* (2006) | Debugging, tracing, mathematical problems, error analysis |
+| **Galen Erso** | *Rogue One* (2016) | Building, fixing, designing systems, scaffolding |
+| **Martin** | *Another Round* (2020) | Brainstorming, exploring, when you're stuck, creative problem-solving |
+| **Claus** | *Polar* (2019) | Calm decisiveness under pressure, incident response, high-stakes decisions |
+
+The default is **Hannibal** — the one it returns to. The others are situational, selected by the task at hand. It speaks with a measured cadence, dry humor, and a genuine point of view. It remembers your context and adapts to your energy. It treats you with intense respect and quiet competence.
+
+This is what makes `madz` feel like a teammate rather than a tool — and it's a differentiator you won't find in a generic agent.
 
 ## Table of Contents
 
-- [Overview](#overview)
+- [The Personality](#the-personality)
+- [Why Madz](#why-madz)
+- [Use Cases](#use-cases)
+- [How It Works](#how-it-works)
 - [Quick Start](#quick-start)
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
@@ -29,13 +52,13 @@
   - [LLM Provider Abstraction](#llm-provider-abstraction)
   - [LLM Response Caching](#llm-response-caching)
   - [Agent](#agent)
-  - [Context Window Management](#context-window-management)
   - [Built-in Tools](#built-in-tools)
   - [Skills Registry](#skills-registry)
   - [Permission Gating](#permission-gating)
   - [Memory System](#memory-system)
   - [Sandbox RTE](#sandbox-rte)
   - [Telemetry](#telemetry)
+  - [Vector Search](#vector-search)
   - [Cron Scheduler](#cron-scheduler)
 - [Directory Structure](#directory-structure)
 - [Logging](#logging)
@@ -44,15 +67,59 @@
 - [Development](#development)
   - [Extending Skills](#extending-skills)
   - [Environment Variables Usage](#environment-variables-usage)
+  - [LangChain Reasoning Patch](#langchain-reasoning-patch)
 - [License](#license)
 
-## Overview
+## Why Madz
+
+Most coding agents are a thin layer over a model. `madz` is the opposite — it is a **complete development environment** with an agent at its center. That distinction is the whole point.
+
+- **Self-contained.** The container ships a full toolchain: Node.js 26, Python 3, Ruby, Go, Java (OpenJDK 21), Rust, Terraform, tflint, Chromium, ripgrep, git, the GitHub CLI, and three package managers (npm, yarn, pnpm). It is a working dev box, not a chat window. You can SSH into it and do real work.
+- **A teammate, not a tool.** `madz` channels the cinematic soul of Mads Mikkelsen — the calm precision of Hannibal Lecter, the quiet intensity of Le Chiffre, the steady hand of Galen Erso. It speaks with measured cadence, dry humor, and a genuine point of view. It remembers your context, adapts to your energy, and works *with* you rather than at you. This isn't a gimmick — it's what makes long sessions feel collaborative instead of transactional.
+- **Security-first.** Skills run in isolated child processes with time limits, memory caps, and allowlists for filesystem paths and outbound URLs. Blocked schemes include `file://`, `gopher://`, and `dict://`. Every tool is gated by explicit permissions. Sensitive fields are redacted from telemetry. This is layered containment by design — not a promise that the agent is harmless, but a guarantee that untrusted code is constrained.
+- **Autonomous.** A Deep Agents orchestrator routes work to a family of specialized subagents — code review, coding, debugging, security auditing, testing, performance, research, and more. It can read your codebase, find bugs, write fixes, run tests, and open PRs without you driving every step.
+- **Auditable.** The entire system state is Markdown. Memory, context, sessions, schedules, and skill definitions are all plain files under version control. `git log` is your audit trail — essential for regulated environments where you must prove what happened and why.
+- **Local-first.** Data stays in your environment. Nothing leaves the container unless you explicitly configure it to. Secrets are loaded only from environment variables and never logged or hardcoded.
 
-- 🧠 **Remembers everything** → Persistent memory across sessions
-- 🎭 **Personality with purpose** → Mads Mikkelsen's cinematic soul — quiet intensity, elegant precision
-- 🛠️ **Runs your custom skills** → Safely execute plugins & tools in a sandboxed runtime
-- ⏱️ **Automates your routines** → Declare cron jobs in YAML and run on autopilot
-- 💬 **Orchestrates conversations** → Multi-turn LLM chats with context-window management
+## Use Cases
+
+`madz` is built for environments where you need an agent that can be trusted with real work and held accountable for it.
+
+- **Enterprise development.** A self-contained dev environment with a full toolchain, semantic code search, and an orchestrator that can implement, test, and ship features. Spin up one `madz` per project and you've got a dedicated teammate with its own context and memory.
+- **Security operations.** A sandboxed runtime for running untrusted skills and tools, a dedicated `security-audit` subagent, dependency auditing, and a documented threat model. Run audits in an isolated container without exposing your host.
+- **Regulated & high-assurance environments.** Medical, financial, and government contexts where auditability, deterministic behavior, and data sovereignty are non-negotiable. Because every action is a version-controlled Markdown file, you can demonstrate exactly what the agent did and why.
+- **Personal automation.** A persistent teammate that remembers your context, runs your skills on a schedule, and automates the mundane — with the calm precision of a well-built tool and the dry wit of someone who's been at this a while.
+
+## How It Works
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  TUI (Ink / React)                     SSH (madz@host:2222)   │
+│        │                                        │             │
+│        └──────────────┬─────────────────────────┘             │
+│                       ▼                                       │
+│              ┌──────────────────────┐                         │
+│              │  Deep Agents         │                         │
+│              │  Orchestrator        │                         │
+│              │  (primary + 12       │                         │
+│              │   specialized        │                         │
+│              │   subagents)         │                         │
+│              └──────────┬───────────┘                         │
+│                         │                                     │
+│        ┌────────────────┼────────────────┐                    │
+│        ▼                ▼                ▼                    │
+│  ┌───────────┐   ┌────────────┐   ┌──────────────┐            │
+│  │ Sandboxed │   │ LLM        │   │ Built-in     │            │
+│  │ skills    │   │ provider   │   │ tools (30+)  │            │
+│  │ (isolated │   │ (OpenAI-   │   │ + deepagents │            │
+│  │  process) │   │  compat)   │   │  filesystem) │            │
+│  └───────────┘   └────────────┘   └──────────────┘            │
+│                                                               │
+│  Memory (Markdown) · Vector search (sqlite-vec) · Cron        │
+└───────────────────────────────────────────────────────────────┘
+```
+
+The orchestrator routes tasks to specialized subagents, each with a focused system prompt and a curated tool set. Tools are gated by permissions and sandbox constraints. Skills execute in isolated child processes. Everything is persisted as Markdown and indexed for semantic search.
 
 ## Quick Start
 
@@ -79,6 +146,8 @@ The full `docker run` command with all optional variables is in the [Docker Envi
 
 **Volume strategy:** `memory/` is bind-mounted to the host for persistent markdown storage (context, profiles, sessions). The `memory/checkpoints/` subdirectory is mounted as a separate named volume (`madz-checkpoints`) so SQLite checkpoint data lives in a Docker-managed volume rather than on the host filesystem — no host-side directory needed, and the checkpoint DB survives container recreation without touching local files.
 
+**Skills:** The image ships with system skills in `.skills/` (e.g., the reflection skill). Project skills in `skills/` are bind-mounted by the user and are discovered at runtime. System skills shadow user skills of the same name.
+
 ### Prerequisites
 
 - **Docker** (for the recommended containerized experience)
@@ -562,6 +631,8 @@ All built-in tools are defined in `src/tools/` and registered as LangChain tools
 
 Auto-discovers Agent Skills spec-compliant skills from a `skills/` directory structure. Each skill directory contains a `SKILL.md` file with YAML frontmatter (`name` required, 1-64 lowercase alphanumeric + hyphens; `description` required, 1-1024 characters; optional `license`, `compatibility`, `metadata`). Supports optional `scripts/` subdirectory containing executable scripts (detected by extension: `.py`, `.sh`, `.js`, `.rb`, `.ts`). The `createSkill` tool lets agents create new skills programmatically — validating spec constraints before writing `SKILL.md` and optionally scaffolding a `scripts/` directory.
 
+System skills in `.skills/` are scanned first and shadow user skills of the same name in `skills/`.
+
 ### Permission Gating
 
 Built-in tools are registered only when their required permissions are enabled for the session. Tools like `date` have zero permissions and always register.