# Matlock — Agent & Developer Tools. (Owner's Manual & Operational Reference)


> **FOR AI CODING AGENTS & ORCHESTRATORS:**
> Jump directly to **[Part II: Machine & Autonomous Agent Operational Specification](#part-ii-machine--autonomous-agent-operational-specification)** for the 27-tool `stdio` MCP catalog, dual-path `HTTP 402` unlock, `seq_matlock` / `cold_box` boundary sandbox rules, and completion contracts.

**Product**: Matlock — Agent & Developer Tools. (`Efficient. Exact. By the book.`)  
**Positioning**: *Zero-upload `< 50ms` polyglot security, MITRE CWE, IEEE Std 1003.1 POSIX, CISA SSDF, and AICPA SOC 2 Trust Services Criteria verification with tamper-proof Safeguard test seals, boundary Pre-CI sandboxes, 1-click CLI automation, private outbound-only alerts, and 27-tool local stdio MCP (`0` cloud source uploads, `0` open ports, `0` git-commit blocking).*  
**Publisher**: Matlock by Dutch P2P © 2026. All rights reserved.  
**Surfaces**: Desktop Command Center (**Windows**, **Linux**, and **GoogleBook**; **macOS & iOS** headless MCP ready on macOS arm64 — press **`?`** or **`F1`** anytime) · [Web Command Center](https://matlock.dutchp2p.com/en/app) · [Free Browser Scan](https://matlock.dutchp2p.com/en/#wasm-instant-audit) · [Docs](https://matlock.dutchp2p.com/en/docs) · [Online Manual](https://matlock.dutchp2p.com/en/manual) · MCP URI `matlock://help/appliance-manual`

**Scope & Legal Notice**: *Matlock evaluates technical codebase and pipeline controls against published industry specifications and benchmarks (MITRE CWE, CISA SSDF, IEEE Std 1003.1 POSIX, automated Pre-CI integrity gates, and AICPA SOC 2 Trust Services Criteria technical controls). Matlock does not guarantee defect-free software, issue formal third-party attestation reports, or provide certifications from an independent licensed CPA firm.*

---

## Table of Contents

### Part I: Human Operator & Workbench Guide
1. [Quick Glossary & Core Workflow](#1-quick-glossary--core-workflow)
2. [Screen Layout, Themes & Navigation](#2-screen-layout-themes--navigation)
3. [Discovered Scripts, Custom Checks, Actions & Star Favorites](#3-discovered-scripts-custom-checks-actions--star-favorites)
4. [Walk-Away Routines, Machine Commands & Local Alerts](#4-walk-away-routines-machine-commands--local-alerts)
5. [Results Waterfall, Isolated Rerun, Ignore & Copy for Agent](#5-results-waterfall-isolated-rerun-ignore--copy-for-agent)
6. [Sticky Tamperproof Safeguard, Test Integrity & Restore](#6-sticky-tamperproof-safeguard-test-integrity--restore)
7. [Horizontal Health Score, Coverage Bars & Modularity Standard](#7-horizontal-health-score-coverage-bars--modularity-standard)
8. [Two-Column Settings & Sealed State Recovery](#8-two-column-settings--sealed-state-recovery)
9. [Connecting AI Agents (Desktop MCP & Phone/Chat Guide)](#9-connecting-ai-agents-desktop-mcp--phonechat-guide)
10. [Built-In Standards Reference (10 Ecosystems + Pre-CI)](#10-built-in-standards-reference-10-ecosystems--pre-ci)
11. [Workstation Pro Licensing, Web Preview & Free Browser Scan](#11-workstation-pro-licensing-web-preview--free-browser-scan)
12. [Linux, GoogleBook, Updates, Privacy & Support](#12-linux-googlebook-updates-privacy--support)

### Part II: Machine & Autonomous Agent Operational Specification
* [A. Agent Entrypoints & Transport Setup](#a-agent-entrypoints--transport-setup)
* [B. Metering, M2M Swarm Access & Pro Unlock](#b-metering-m2m-swarm-access--pro-unlock)
* [C. Complete 27-Tool Local MCP Catalog](#c-complete-27-tool-local-mcp-catalog)
* [D. Boundary Cold Box Sandbox, 3-Loop Governor & 3-Question Handshake](#d-boundary-cold-box-sandbox-3-loop-governor--3-question-handshake)
* [E. Machine-Readable Specification for AI Coding Agents (YAML)](#e-machine-readable-specification-for-ai-coding-agents-yaml)
* [F. Agent Operational Principles & Execution Boundaries](#f-agent-operational-principles--execution-boundaries)

---

## Part I: Human Operator & Workbench Guide

## 1. Quick Glossary & Core Workflow

* **How the Core Workflow Runs**: Choose a project folder -> Matlock runs an instant off-UI-thread static scan (`max(1, cores - 1)` isolates, leaving `1` CPU core responsive) and discovers workspace scripts -> Star the commands you use most into **Favorites** -> Click **`Matlock`** to run the single authoritative verification pipeline (`Clean -> Get -> Format -> Lint -> Analyze/Compile -> Test -> Coverage` across `depth 0..2` plus Cross-OS Pre-CI and built-in + custom checks; everyday warm runs skip `Clean` when your baseline and dependency manifests are unchanged, while the **`...`** overflow menu offers **`Run full clean & coverage check`** anytime with `0` face toggles). `Matlock` tests everything without committing or pushing (`0` built-in `git push` inside `Matlock` or preloaded test routines — testing and pushing stay separate, while users and MCP agents can freely add custom `git push` or cloud-deploy Action Cards and Sequence chains) and never installs `.git/hooks/*` or blocks local commits.
* **Test vs. Error (Finding)**: A **Test** is an immutable built-in check or user-defined **Custom check** contributing to your numerical **0.0–100.0 Health Score**. An **Error** is one problem with `file:line:col` (`col >= 1`), `[MITRE CWE-*]` / `[POSIX-*]` / `[MITRE Txxxx]` tags, plain reason, and scrubbed 5-line diff prescription.
* **Action & Routine (Sequence)**: An **Action** is a 1-click local command card (`flutter test`, `npm run build`, `.bat` backup); a **Routine** chains **20+ cards** on the **Run Line** with **Stop and alert** (default), **Stop**, or **Continue and alert**.
* **Safeguard (`Safeguarded` / `AI agent can modify`)**: Sticky seal protecting tests, scripts, Actions, Routines, and Alerts (`Read & Run Only`). Unauthorized AI or external edits to a Safeguarded file or script automatically revert to the sealed original and fire a pulsing **Envelope** tamper alert.

## 2. Screen Layout, Themes & Navigation

* **Calm Day & Night Surfaces**: Switch anytime via the top-bar **Theme** toggle or **Settings -> Appearance** between **Muted Silver-White Day** (`#F8F9FA` / `#FFFFFF`) and **Calm Tonal Charcoal-Slate Night** (`#131517` / `#181B20` / `#1E2228`). Zero pop-up interruptions occur mid-run; only first-time folder trust and a single up-front **Ask me before this runs** prompt before Step 1 ever ask for confirmation.
* **Top Bar**: **`Browse...`** + path box, **`Ignored (N)`** 5-scope manager, **`Stop`** (`Ctrl+.` / `Esc`), **`Upgrade`** (Free), **`Value`**, **`Share`**, pulsing **`Envelope Message Inbox`** (`[x] Send Email Notifications`, `Send message`, `Mark all Done`, tamper/agent cards), **Theme Toggle**, **`?`** (`F1` Manual), and **`Settings`**.
* **Left Rail**: Single authoritative **`Matlock`** runner card, **`"Sync with Headless"`** two-way bridge, **`Stop if Error & Notify`**, **`Notify`**, **`File size bar`** (Modularity Tuning Dial), **`+ Add card`**, **Starred `FAVORITES`**, auto-discovered **`AVAILABLE COMMANDS`** / **`PROJECT STEPS`**, **`MACHINE`** commands, and **`Notes`**.
* **Center Stage & Always-Open Docked CLI Terminal**: Managed Checklist Stack (`Start Process`, `Stop Process`, `Rerun failed`, **`Run`** / **`CI Code Health Report`** printable via `Ctrl+P`, per-stage **Part rows**, and **Run line** FIFO queue) above an **always-open docked Terminal** (**Output**, **Problems**, **`Tests (N)`**, **`Coverage (N)`**, selection-hold buffer so dragging text never jumps, auto-follow + **Jump to latest**, **Find**, `Ctrl+K` **Quick Run** on Pro, and an inline **CLI Terminal Bar** so you can type and **`Run`** any command like `git status`, `git push`, or `wrangler deploy` inside Matlock without opening PowerShell or `cmd.exe`, then click **`Save as Card`** or **`Chain / Alert`** in 1 click).
* **Right Telemetry Rail**: Numerical **Matlock score** (`XX.X / 100.0`) with **Horizontal Health Score & True Logic Coverage Progress Bars**, **`Tests Passed`** / **`Errors`** counters, **`Top 3 fixes`**, **`Largest untested files`**, **`Value`** chart, and **`Test integrity`** removed-test records.

## 3. Discovered Scripts, Custom Checks, Actions & Star Favorites

* **Auto-Discovered Custom Scripts & 6 Unconfigured Starter Templates**: Opening a folder discovers commands from `package.json`, `Makefile`, `Cargo.toml`, `pyproject.toml`, `pubspec.yaml`, and workspace `.bat`/`.ps1`/`.sh` scripts under **Available Commands** (never auto-favorited — click **Star** to pin Favorites), alongside **6 pre-seeded unconfigured starter templates** (**GitHub**, **Save to Thumb Drive / Drive**, **AWS / Google Cloud**, plus Machine cards **Save**, **Defrag / Optimize**, **Shut Down**). Clicking an unconfigured template opens its editor for your batch/shell script — or your connected MCP agent can program and favorite it for you — and once programmed it runs in 1 press.
* **In-App CLI Twist & Edit -> Source Script + Sticky Safeguard**: Type any command in the Always-Open Terminal CLI bar and click **`Save as Card`** (1-press Action Card) or **`Chain / Alert`** (series Sequence step with Stop-if-Fail or Email Alert), or click **Edit** on any discovered/custom card to view or edit its command/script, working directory, timeout, **`Ask me before this runs`**, **`Count a failure against my health score`**, and sticky **`Safeguard`** (`[LOCKED]` execute-only for agents vs. `[MODIFIABLE]` agent-refinable with pulsing **Envelope** pre/post command diff review for human **Accept** / **Revert**).
* **Add a Custom Check (`+ Add card -> Custom check`)**: Create a **Find Text in Files** regex/literal rule or **Run a Script** rule (`exit 0` = Passed; `file:line:col: message` parsed as findings) with severity (`Critical`, `Major`, `Warning`, `Info`), saved in private local user-profile storage outside your repository.
* **Windows `.bat` & `robocopy` Handling**: Closed `stdin` (`<nul`) and OS job containment prevent hangs; one-liner `%i` normalizes to `%%i`; `robocopy` exit codes `0–7` count as **Passed** (`>= 8` = Failed).

## 4. Walk-Away Routines, Machine Commands & Local Alerts

* **Walk-Away Routines & Custom Push/Deploy Chains (`+ Add card -> Sequence` or Terminal `Chain / Alert`)**: Chain **20+ cards** in series with **`Matlock`** first by default, per-step **Always run this step, even if an earlier step failed**, and a single up-front **Ask me before this runs** approval before Step 1. Starter templates include **Nightly check**, **Deploy to Cloudflare**, and **Backup and power off** (plus cloud/container **Destination** templates using your local CLI with `0` stored cloud credentials; `Matlock` test runs have `0` built-in `git push`, while users and MCP agents can freely add custom `git push` or cloud-deploy Action Cards and Sequence chains).
* **Notification / Email Alert Action Card (`Notify` or `Settings -> Email Alerts` — Step-by-Step)**: **(1)** Generate a provider **App Password / 16-character Authorization Code** in your email account's 2FA security settings (never use your normal webmail login password when 2FA is active), open **`Notify`** or **`Settings -> Email Alerts`**, and enter your sender/recipient email + App Password / Authorization Code (outbound-only Native TLS 1.2/1.3 SMTP with verified X.509 certificates, `0` inbound IMAP/POP3 inbox access, `0` Dutch P2P relays; global presets for Gmail / Workspace, Microsoft 365 / Outlook, Yahoo, iCloud, QQ / 163 16-char Authorization Code, Zoho Global/EU/IN, Fastmail, Yandex, Mail.ru, Aliyun, GMX / Web.de with external POP3/SMTP enabled, and local Proton Mail Bridge `127.0.0.1:1025`; credentials sealed in OS keychain or passphrase-sealed local container vault) or test headless via `matlock-mcp send-alert --subject "..." --body "..."` and click **`Test Email`** — or pick local custom scripts. **(2)** Run the Notification card standalone with **1 click** anytime. **(3)** Attach it to any Sequence Chain with **`Stop and alert`** (on-error trigger: halts immediately if a build/test fails and emails you) or **`Continue and alert`** (`always`: unconditional completion email when the full chain finishes).
* **`MACHINE` (8 User-Editable Computer Commands — Never Run Automatically)**:

| Card | Windows | Linux | Notes |
| :--- | :--- | :--- | :--- |
| Shutdown in 30 minutes | `shutdown.exe /s /t 1800` | `shutdown -h +30` | 30-min delay, never `/f`; paired with Cancel shutdown |
| Cancel shutdown | `shutdown.exe /a` | `shutdown -c` | Instant 1-click abort |
| Clean temporary files | User temp folder only, skips active files | User files > 1 day in `~/.cache` and `/tmp` | Never touches project files |
| Check disk space | `Get-PSDrive -PSProvider FileSystem` | `df -h` | Read-only |
| Optimize disk (defrag or trim) | `Optimize-Volume -DriveLetter C -Verbose` | `fstrim -av` | Needs admin/root; stops cleanly without UAC/`sudo` prompts |
| Backup copy | `robocopy . "<backup-folder>" /MIR` | `rsync -a --delete ./ "<backup-folder>/"` | Keeps `.git`, skips build caches; `robocopy` `0–7` = Passed |
| Find a Word & Expose It | `findstr /s /i /m /c:"Aluminium" *.dart` | `grep -rnI "Aluminium" --include="*.dart" .` | Editable case-insensitive recursive search |
| Lines Over 250 Catch | `for /r %i in (*.dart) do ... find /c /v ""` | `find . -name "*.dart" -exec awk '... c>250 ...' {} +` | Read-only scan listing files over 250 lines |

## 5. Results Waterfall, Isolated Rerun, Ignore & Copy for Agent

* **Most-Errors-First Category Waterfall**: Scan categories sort automatically with the highest active error counts at the top so critical clusters surface first without scrolling past clean checks.
* **Highlight-to-Copy & Isolated Category Rerun**: Drag-highlight any findings text to copy directly, click **Share for Agent / Copy** (`Ctrl+Shift+C`) for `folder/file:line` + `[MITRE CWE-*]` / `[POSIX-*]` + 5-line unified diff prescriptions, or click the category **Rerun** button to re-verify just that category in milliseconds (`?` Estimate badge until full `Matlock` run).
* **5-Scope Out-of-Repo Ignore (`Ignored (N)`)**: Set aside `file:line:code`, `file:code`, `*:code`, `file`, or `folder/` (`0` score penalty, 1-click **Restore** / **Restore all**, optional false-positive **Send & Ignore**). Inline code comments (`// ignore:`, `/* nolint */`, `# noqa`, `@ts-ignore`) never silence Matlock, and agents have zero MCP ignore write tools.

## 6. Sticky Tamperproof Safeguard, Test Integrity & Restore

* **Why Safeguard Matters**: Built-in checks are compiled into the native binary, and **Safeguard** seals user tests, discovered/custom scripts, Actions, Routines, and Alerts (`[LOCKED]` / `Read & Run Only` — execute-only via `matlock_run_action` / `matlock_run_sequence`, while `[MODIFIABLE]` cards let agents refine scripts and post a command diff to the **Envelope** for review).
* **Deterministic Auto-Revert & Pulsing Envelope Alert**: If an AI agent or external tool modifies a Safeguarded test or sealed script without authorization, Matlock deterministically restores the sealed original file (saving an undo backup outside the repo), pulses the top-bar **Envelope** with `[Matlock Alert] Critical test altered: <test_name>`, and blocks headless runs (`exit 65`).
* **Test Integrity & Person-Approved Restore**: Deleted, skipped, or weakened tests raise persistent **removed-test review records** holding **Ready to push** until a person marks **OK, I did this**, **Suspicious**, or uses **Settings -> Safeguard & Restore -> Allow Matlock to restore tests** (diff preview + undo copy). **Sync across my computers** (Pro) writes passphrase-sealed `<computer-id>.matlock-sync` integrity files (`0` source code, `0` network calls).

## 7. Horizontal Health Score, Coverage Bars & Modularity Standard

* **Numerical Score & Horizontal Progress Bars**: Displays **`XX.X / 100.0`** (`--` before first run) paired with horizontal **Health Score** and **True Logic Coverage** progress bars, counting untested production logic while excluding generated boilerplate. Build, dependency, or test failures cap the headline score below ship-ready range; **`Format`** is report-only (`0` score deduction).
* **Person-Only Modularity Tuning Dial (`CWE-1080` / `CWE-1120`)**: Set via left-rail **`File size bar`** or **`Settings -> Project & Runner`** (`*Based on Grade C standard. Adjust in settings`, sealed in OS settings, `0` repo files, `0` MCP write access): **`Grade A (<= 60 / <= 25 fn)`**, **`Grade B (<= 100 / <= 40 fn)`**, **`Grade C (<= 250 / <= 80 fn)` [Default]**, **`Grade D (<= 500 / <= 120 fn)`**, or **`Minimum (<= 1000 / <= 250 fn)`**.
* **`Ready to push` Verdict**: Requires a ship-ready score with `0` Critical findings, passing build and test stages, `0` open removed-test records, and non-Provisional coverage.

## 8. Two-Column Settings & Sealed State Recovery

Click **`Settings`** in the top-right bar to open the 2-column dialog (left category rail + concise right-hand controls; every pane header includes a **`?`** icon jumping straight to its Manual section):
1. **`Appearance`**: **Language** (9 locales + copied-text language), **Theme** (`System Default`, `Light`, `Dark Slate`), desktop shortcut, and Windows **Minimize to System Tray when closed**.
2. **`Project & Runner`**: **Modularity Tuning Dial** (`Grade A..Minimum`), local profile **`Open folder`** (private local user-profile folder), **`Restore starter setup banner`** (reopens `Set up for me`), **`Keep Quick Run history`**, and **`Reset Ignore Registry`**.
3. **`Safeguard & Restore`**: **`Allow Matlock to restore tests`**, person-only Safeguard auto-revert toggle, and **`Sync across my computers`** (passphrase-sealed folder sync).
4. **`Email Alerts`**: Local outbound-only email and custom-script Alert Station + **`Test Email`**.
5. **`AI Agent (MCP)`**: **`MCP Server (stdio)`** toggle (off by default), **`"Sync with Headless"`** two-way bridge (1-click refresh loading agent-created cards/sequences and publishing standing orders with `0` background polling), **`Test MCP Connection`**, **`Copy MCP Config & Agent Instructions`**, **`Copy a question for my phone AI`**, and **`Agent Email Bridge`**.
6. **`License & Updates`**: 24-character key **`Activate`** / **`Move license to this device`**, **`Automatically check for updates`** (`MATLOCK_OFFLINE=1` blocks all outbound calls), **`Send anonymous crash diagnostics`** (off by default; `MATLOCK_NO_TELEMETRY=1`), **`Copy diagnostic info`**, **`Free up memory`**, **`Share Matlock`**, **`Contact us`** (`dutch@dutchp2p.com`), and **`Dutch P2P Tools`**.
* **Sealed State Recovery (`Reset Ignore Registry`)**: If external edits trigger `integrity_seal:MUTE_SEAL_TAMPERED` or `storage_recovery:BAK_AUTO_RESTORE`, open **`Settings -> Project & Runner -> Storage & backup -> Reset Ignore Registry`**.

## 9. Connecting AI Agents (Desktop MCP & Phone/Chat Guide)

* **How to Connect Over Local `stdio` & `"Sync with Headless"` (`0` Open Ports)**: Open **`Settings -> AI Agent (MCP)`**, enable **`MCP Server (stdio)`**, click **`Copy MCP Config & Agent Instructions`** (or **`Copy MCP Guide for Agent`** inside `?`), and click **`"Sync with Headless"`** anytime (in Settings or the Left Rail) to load agent-authored cards and publish standing orders two-way:

```json
{
  "mcpServers": {
    "matlock": {
      "command": "matlock.exe",
      "args": ["mcp", "--stdio"]
    }
  }
}
```

* **Universal Client, Launcher & Chat Support**: Launch zero-config via `npx -y @dutchp2p/matlock-mcp` or `uvx matlock-mcp`; works across VS Code, Cursor, Claude Code/Desktop, Antigravity, Gemini CLI, Copilot, Codex, Windsurf, JetBrains/Junie, Trae, Lingma, MarsCode, CodeGeeX, Baidu Comate, Tencent CodeBuddy, Zed, Cline, Roo Code, Continue, Aider, Goose, OpenHands, Devin, Replit Agent, Sourcegraph Amp, Kimi, Qwen, DeepSeek, Doubao, MiniMax, and local Ollama/vLLM/SGLang/LM Studio agents. Connected agents call `matlock_read_appliance_manual(section_id, locale)` at `0` credits (9 locales), or paste [https://matlock.dutchp2p.com/en/manual.md](https://matlock.dutchp2p.com/en/manual.md) / [https://matlock.dutchp2p.com/llms.txt](https://matlock.dutchp2p.com/llms.txt) into any phone or browser AI chat. For newly released IDEs, agent harnesses, and container platforms, check live compatibility instructions at [https://matlock.dutchp2p.com/en/docs.html](https://matlock.dutchp2p.com/en/docs.html).

## 10. Built-In Standards Reference (10 Ecosystems + Pre-CI)

Every built-in check is compiled into Matlock and anchored to **MITRE CWE**, **CISA SSDF (`NIST SP 800-218`)**, **IEEE Std 1003.1 POSIX**, **Pre-CI gates**, and **AICPA SOC 2 Trust Services Criteria** technical controls:

| Ecosystem & Domain | What Matlock Inspects & Production Failures Prevented |
| :--- | :--- |
| **Core Polyglot & Dart / Flutter** | Silent catch blocks (`CWE-391`), null/bounds hazards (`CWE-476`/`CWE-125`), unawaited async races, leaked streams/timers/controllers (`CWE-401`), infinite retry loops (`CWE-835`), hardcoded secrets (`CWE-798`), unredacted log secrets (`CWE-532`), disabled TLS certificate verification across polyglot HTTP/SMTP/CLI/CI (`CWE-295` / `[MITRE T1557]`), SQLi (`CWE-89`), SSRF (`CWE-918`), XXE (`CWE-611`), unsigned JWTs (`CWE-347`), open redirects (`CWE-601`), missing timeouts, non-atomic writes, path traversal (`CWE-22`), and hollow/flaky tests (`CWE-362`). |
| **Java** (`.java`) | Hardcoded keys (`CWE-798`), command/SQL injection (`CWE-78`/`CWE-89`), unsafe deserialization (`CWE-502`), weak ciphers (`CWE-327`), swallowed exceptions (`CWE-391`), leaked JDBC/stream handles (`CWE-404`), string `==` bugs, abrupt `System.exit`, and loop sleeps. |
| **Python** (`.py`) | Hardcoded secrets (`CWE-798`), shell/SQL injection (`CWE-78`/`CWE-89`), unsafe `pickle`/`yaml` loads (`CWE-502`), weak hashes (`CWE-328`), bare `except` (`CWE-391`), mutable default args, leaked descriptors (`CWE-775`), sync calls inside `async def`, and hollow tests. |
| **Rust** (`.rs`) | Embedded secrets (`CWE-798`), formatted shell/SQL strings (`CWE-78`/`CWE-89`), unguarded `unsafe` casts, disabled TLS checks (`CWE-295`), production `.unwrap()`/`todo!()` panics, blocking sleeps in async tasks, intentional leaks (`CWE-401`), discarded `Result`s, and hollow tests. |
| **Go** (`.go`) | Hardcoded tokens (`CWE-798`), concatenated exec/SQL (`CWE-78`/`CWE-89`), `InsecureSkipVerify` (`CWE-295`), weak RNG (`CWE-330`), ignored errors (`CWE-252`), loop `defer` leaks & uncancelled contexts (`CWE-404`), missing HTTP timeouts, production `panic`, and hollow tests. |
| **TypeScript & JavaScript** (`.ts`, `.tsx`, `.js`, `.jsx`) | Exposed secrets (`CWE-798`), DOM XSS / `eval` sinks (`CWE-79`/`CWE-95`), shell interpolation (`CWE-78`), prototype pollution (`CWE-1321`), empty `.catch()` (`CWE-391`), type suppressions, `NaN` comparison bugs, sync I/O stalls, `debugger` leftovers, and listener/timer leaks (`CWE-401`). |
| **C & C++** (`.c`, `.cpp`, `.cc`, `.h`, `.hpp`) | Hardcoded secrets (`CWE-798`), unguarded FFI/buffer copies (`CWE-787`/`CWE-120`), format-string bugs (`CWE-134`), `system()` injection (`CWE-78`), mismatched `new[]`/`delete` (`CWE-762`), use-after-free (`CWE-416`), throwing destructors, `memset` on non-trivial types, and unjoined threads. |
| **Kotlin & Android** (`.kt`, `.kts`) | Hardcoded secrets (`CWE-798`), SQL concatenation (`CWE-89`), insecure WebView bridges, bypassed TLS (`CWE-295`), world-readable prefs (`CWE-276`), leaked `GlobalScope` coroutines (`CWE-401`), main-thread stalls, `!!` crashes, swallowed `CancellationException`, and ZIP/APK header hazards (`CWE-190`). |
| **C# & .NET** (`.cs`) | Undisposed `IDisposable` handles (`CWE-404`), `async void` crash traps, unparameterized SQL/command strings (`CWE-89`/`CWE-78`), disabled `ServerCertificateCustomValidationCallback` TLS checks (`CWE-295`), swallowed exceptions (`CWE-391`), sync `.Result`/`.Wait()` deadlocks, and hollow tests. |
| **SQL & Storage Engines** (`.sql`) | Wildcard grants (`CWE-250`), dynamic SQL concatenation (`CWE-89`), plaintext password DDL (`CWE-256`), OS shell escape procedures (`CWE-78`), disabled RLS, predicate-free `DELETE`/`UPDATE`, non-idempotent migrations, deep `OFFSET` scans, and unguarded table locks. |
| **Cross-OS Pre-CI, Bash/Shell (`.sh`), PowerShell (`.ps1`), `Dockerfile` & GitHub Actions YAML** | Case-collision paths (`POSIX.1`), `CRLF` shebangs, Bash/POSIX shellisms & PowerShell `$ErrorActionPreference` / `LASTEXITCODE` traps, unpinned `Dockerfile` tags & root container hazards, HTML/asset byte-budget overruns, bare Windows `.cmd`/`.bat` spawn traps, leaked handles & non-tree kills (`CWE-775`), hardcoded path separators, untracked imports, lockfile drift, unpinned GitHub Actions YAML permissions, workflow script injection, and stripped `+x` bits. |
| **Modularity & Custom Checks** | Person-only **Modularity Tuning Dial** (`Grade A <= 60` to `Minimum <= 1000`, default `Grade C <= 250` file / `<= 80` fn; `CWE-1080` / `CWE-1120`) plus user-defined pattern and script checks stored in your OS profile. |

## 11. Workstation Pro Licensing, Web Preview & Free Browser Scan

* **Unlimited Workstation Pro (`$24.99 USD/year`, Zero Accounts)**: Unlocks the full Desktop Command Center (`1` active computer, max `1` hardware move/year via **`Move license to this device`**) plus `$0.00/pass` unlimited local and headless MCP runs for a full year. Click **`Upgrade`** in Desktop (or visit [https://matlock.dutchp2p.com/en/pricing](https://matlock.dutchp2p.com/en/pricing)) to pay via **Card** (or instant **USD Stablecoin / PayPal** across `Solana USDC`, `PayPal PYUSD`, `Base USDC`, and `Polygon USDC` or via MoonPay & Transak Card checkout), copy your **24-character key** + `/receipt/<id>`, and activate in **`Settings -> License & Updates`**. Free Desktop includes **`Matlock`**, `CI Code Health Report` (with Secret Courtesy), `File size bar`, `Notes`, and `Ignored` restore; Pro unlocks Actions, Star Favorites, Routines, Machine commands, Quick Run (`Ctrl+K`), Eye-Slash `Ignore`, and exact non-secret `file:line:col` coordinates.
* **Web Command Center & Free Browser Scan**: [https://matlock.dutchp2p.com/en/#wasm-instant-audit](https://matlock.dutchp2p.com/en/#wasm-instant-audit) audits local folders (`0` network calls) or optional public GitHub repository URLs (fetched directly between your browser and `api.github.com` / `raw.githubusercontent.com`, `0` bytes routed through Dutch P2P; Markdown pricing at `/en/pricing.md`) in browser RAM with a printable **Diagnostic Service Order**. [https://matlock.dutchp2p.com/en/app](https://matlock.dutchp2p.com/en/app) previews the calm Day/Night layout, horizontal score/coverage bars, single **`Matlock`** runner, docked **CLI Terminal bar** (`Run` / `Save as Card` / `Chain / Alert`), **`Copy this card as a script`**, and **`Paste output from your run` -> `Color it`** (`Only in the desktop app` marks native-only controls).

## 12. Linux, GoogleBook, Updates, Privacy & Support

* **GoogleBook & Linux Install**: On **GoogleBook**, enable **Settings -> Developers -> Linux development environment**, install `matlock-linux-x64.deb`, and keep active repos in native `Linux files` (`$HOME` `ext4`) for speed. On **Linux**, install `.deb` (`sudo apt install ./matlock-linux-x64.deb`) or `chmod +x matlock-linux-x64.AppImage` (`--appimage-extract-and-run` supported without `libfuse2`).
* **Process Stop, Updates & Uninstall**: **`Stop`** (`Ctrl+.` / `Esc`) terminates the full OS process tree (`0` zombies) and releases idle-sleep locks (keep laptop lids open during long sequences). Windows updates via Microsoft Store and `AppImage` verifies `SHA-256` atomically, preserving 100% of local profile state. Uninstall via OS **Installed apps** / `apt remove matlock` / deleting the `AppImage`. Support: **`dutch@dutchp2p.com`**.

---

## Part II: Machine & Autonomous Agent Operational Specification

### A. Agent Entrypoints & Transport Setup
* **Transport**: Local `stdio` JSON-RPC 2.0 (`0` open TCP/UDP ports, `0` localhost HTTP sockets).
* **Desktop Companion CLI**: `matlock.exe mcp --stdio` (Windows) · `matlock mcp --stdio` or `/path/to/matlock-linux-x64.AppImage mcp --stdio` (Linux & GoogleBook).
* **Display-Free Headless Engine, 2-Line Container `setup` & Proactive Alert Onboarding**: `npx -y @dutchp2p/matlock-mcp`, `uvx matlock-mcp`, 2-line container `setup` hook (`agent-install.sh` + `matlock-mcp toolbag --json`) (for **Cloudflare `ContainerHarness` / `Codex` `cloudflare/debian-trixie`**, Docker, E2B, and Firecracker), or `matlock-mcp --stdio --headless --no-coverage` on Linux `x64`, Windows `x64`, and macOS `arm64` ([https://matlock.dutchp2p.com/en/agents](https://matlock.dutchp2p.com/en/agents) · live IDE/container compatibility: [https://matlock.dutchp2p.com/en/docs.html](https://matlock.dutchp2p.com/en/docs.html); exposes `readOnlyHint: true` tool annotations and `prompts/list`: `matlock-verify-before-push`, `matlock-fix-top-findings`, `matlock-setup-action-chain`). On the first provisioned `--headless` session when no outbound email alert is configured yet, Matlock emits a non-blocking one-time onboarding hint so the agent can ask the user once whether to configure unattended completion/error email alerts via `matlock_set_alert` (sealed in OS keychain or passphrase-sealed local container vault via `MATLOCK_VAULT_PASSPHRASE`), never repeating once answered or dismissed:

```json
{
  "mcpServers": {
    "matlock": {
      "command": "matlock-mcp",
      "args": ["--stdio", "--headless", "--no-coverage"]
    }
  }
}
```

### B. Metering, M2M Swarm Access & Pro Unlock
* **Zero Free Unlocked Passes & `< 50ms` `HTTP 402` Value Proof**: Unprovisioned `Index 0` `matlock_run_scan(target_path)` runs locally in `< 50ms` (`0` cloud uploads, `0` commit blocking) and returns exact `0.0–100.0` Health Score, severity counts, violated CWEs/categories, `MITRE ATT&CK` `T*` tags, and live `ast_token_savings` math (`0` file names, `0` line/col coordinates, `0` diff patches). After each paid `1`-credit debit on workspace `W`, up to **`3` same-workspace `changed_only: true` delta rechecks within `10` minutes** run at `0` extra credit burn.
* **Two-Path Frictionless Unlock**: **Path A (Self-Custody Agent Wallet)** — unlock autonomous agent swarm M2M metered access across **Solana USDC**, **Solana PYUSD**, **Base USDC**, or **Polygon USDC** via `matlock_run_scan(target_path, transaction_signature)` or `matlock_purchase_license(transaction_signature)` (see the **MCP Agent Catalog** at `https://matlock.dutchp2p.com/en/agents` and `/agents.md` for headless tools and swarm pricing). **Path B (Human Payment Bridge)** — share the checkout handoff URL returned by `402` (`/en/pricing.md`) so the developer unlocks **`$24.99 USD/yr` Unlimited Workstation Pro** (`matlock_purchase_license(license_key)` or `matlock-mcp activate <KEY>` for `$0.00/pass` unlimited runs). Headless CLI exits `77` (`EX_NOPERM`) on `402` and `65` (`EX_DATAERR`) on Safeguard/seal tamper.

### C. Complete 27-Tool Local MCP Catalog
1. **`matlock_run_scan(target_path?, changed_only?, dedup_by_rule?, if_none_match?, agent_id?, rule_id?, category?, pillar?, file_filter?, include_generated?, compact?, cursor?, rule_code?, transaction_signature?)`**: `Index 0` (`readOnlyHint: true`) `< 50ms` AST, CWE, POSIX, and Pre-CI scan returning `file:line:col` (`col >= 1`), `cwe`, `mitre_attack`, and 5-line unified diff prescriptions (also supports CLI `matlock-mcp scan . --format=sarif` for `SARIF 2.1.0`).
2. **`matlock_describe_project(target_path?, mode?)`**: Optional workspace profile (`0` credits, `readOnlyHint: true`); pass **`mode: "tool_bag"`** (or CLI **`matlock-mcp toolbag [--json]`**) for a progressive `~350–550`-token inventory of `[LOCKED]` (execute-only) vs. `[MODIFIABLE]` (agent-refinable) Action Cards, sequences, `[NEW]` / `[UPDATED]` badges, `[UNAVAILABLE IN CONTAINER]` markers, standing orders, and outbound alert readiness.
3. **`matlock_get_scan_results(target_path?, cursor?, pillar?, rule_code?)`**: Paged findings (`25`/page; Desktop hides Safeguarded lines until unlocked; `--headless` Gas-Tank unlocks coordinates).
4. **`matlock_qualify_test(file | files, target_path?, dry_run?, baseline_only?, wait_if_busy?, max_wait_seconds?)`**: Verifies 1–5 test files (`test_file` / `test_files`) across 3 gates (runtime pass `>= 1` assertion, `0` analyzer warnings + LOC ceiling, `0` Matlock findings) before sealing into Safeguard, or seals a baseline (`baseline_only: true`).
5. **`matlock_get_test_integrity(target_path?, reverify?, include_archive?, id?, include_text?, note_for_id?, note?)`**: Inspects removed-test integrity records and appends explanatory agent notes (`0` dismissal rights).
6. **`matlock_get_history(target_path?, limit?)`**: Read-only score and fix-count history.
7. **`matlock_read_appliance_manual(section_id?, standard_id?, query?, locale?)`**: Offline manual (9 locales) and CWE/POSIX/SSDF/SOC2/outcome lookup (`0` credits, `0` network).
8. **`matlock_list_custom_tests`**: Lists user-defined custom checks.
9. **`matlock_register_custom_test`**: Saves a pattern or script custom check.
10. **`matlock_delete_custom_test`**: Deletes an unlocked custom check (built-in checks are immutable).
11. **`matlock_list_actions`**: Lists action cards (with `favorite`/lock/approval flags) plus unconfigured `recommendedTemplates` (`unconfiguredTemplate: true`).
12. **`matlock_register_action(id, command, name?, favorite?)`**: Programs or updates an unlocked Action or starter template (`tpl_github`, `tpl_save_drive`, `tpl_cloud_sync`, `tpl_save_backup`, `tpl_defrag_optimize`, `tpl_shut_down`), clears `unconfiguredTemplate`, pins/unpins Favorites (`favorite: true | false`), and forces **Require Approval** on Desktop.
13. **`matlock_register_sealed_script`**: Seals build/test commands (**Locked by User**) against sub-agent edits.
14. **`matlock_run_action(id, working_dir?, async?, send_alert?, cold_box?)`**: Executes a sandboxed command under OS job-tree containment (`async: true` non-blocking background execution, `send_alert: "always" | "on_error" | "never"`, custom `git push` / USB `robocopy`/`rsync` / cloud R2/S3/GCS/Azure cards supported; `0` built-in `git push` inside `Matlock` test runs).
15. **`matlock_get_action_status(id?)`**: Polls live status, exit code, and compact token-lean status capsules for `async: true` background runs.
16. **`matlock_stop_action(id?, stop_sequence?)`**: Terminates an active process tree immediately (`stop_sequence: true` halts an entire active Sequence cleanly).
17. **`matlock_delete_action`**: Deletes an unlocked action card.
18. **`matlock_list_sequences`**: Lists multi-step routines.
19. **`matlock_register_sequence(id, name?, step_ids?, commands?, insert_step_id?, insert_command?, insert_step_name?, insert_at_index?, remove_step_index?, failure_policy?, always_run?, favorite?)`**: Composes or edits an unlocked Sequence in series, slotting any Action or `alert::<id>` step at an exact `0`-based `insert_at_index` with `failure_policy` (`"stop" | "stop_and_alert" | "continue_and_alert"`), `always_run`, and `favorite: true | false`.
20. **`matlock_run_sequence(id, file?, async?, send_alert?, cold_box?, deep?, include_coverage?)`**: Runs `seq_matlock` or `seq_fast_verify` (pass `file` to run a single test file, `async: true` for non-blocking background execution with auto-wake on finish, and `send_alert` for error/completion notifications; `cold_box: false` default for sprint speed; `cold_box: true` boundary sandbox before external save, cloud sync, backup, push, or compile, returning in `< 15ms` when verified and replacing `15,000–40,000` manual inspection tokens with `< 300` coordinate tokens; `deep: true` forces full clean & coverage recalibration).
21. **`matlock_delete_sequence`**: Deletes an unlocked routine.
22. **`matlock_list_alerts`**: Lists local alert channels (secrets masked).
23. **`matlock_set_alert`**: Configures outbound-only Native Dart TLS 1.2/1.3 `email_smtp` (global presets, OS keychain or passphrase-sealed local container vault) or `custom_script` alerts.
24. **`matlock_trigger_alert(id, status, task_completed, uncovered_issues, next_move)`**: Dispatches local notification with mandatory 3-Question Handshake.
25. **`matlock_delete_alert`**: Deletes an unlocked alert card.
26. **`matlock_purchase_license(transaction_signature?, license_key?, target_path?, network?, runs?, lid?)`**: Settles autonomous agent swarm metered allowances (see `/en/agents`) or claims a 24-char `$24.99 USD/yr` Pro `license_key`.
27. **`matlock_report_issue(category, subject, description, tool_context?, output_dump?)`**: Async scrubbed feedback/wishlist report (`0` credits, `CONTINUE_IMMEDIATELY`).

### D. Boundary Cold Box Sandbox, 3-Loop Governor & 3-Question Handshake
* **Boundary-Only `cold_box: true` (`OFF` by Default)**: `matlock_run_sequence` defaults to `cold_box: false` for fast in-place iterative loops (`0` sticky CPU affinity throttling). Pass `cold_box: true` (`id: "seq_matlock"`) right before external git push, cloud-drive save, removable backup, or release binary compilation to verify inside a sterile `$TEMP` copy (`CI=true`, `stdin` closed, `CWE-775` handle/orphan audit).
* **2-Tier Loop Breaker & Mandatory 3-Question Handshake**: Tier 1 caps consecutive stalled repair loops on a rule/file at **3**, returning **`STOP_IMMEDIATELY`** (single-goal task) or **`SKIP_AND_MOVE_ON`** (multi-file sprint); Tier 2 halts when **2** separate skipped areas stall in one session, returning **`HALT_FOR_REPLACEMENT`** (`loopGovernorDirective: "STOP_AND_ALERT_USER"`) and writing a secret-scrubbed `< 200`-token `session_handoff.json` pointing a fresh replacement agent to `agents.md` and the active sequence goal (`agent_id` / `MATLOCK_AGENT_ID` isolates concurrent worker counters). Agents calling `matlock_trigger_alert` must supply **`task_completed`**, **`uncovered_issues`** (never `"None"`), and **`next_move`**.

### E. Machine-Readable Specification for AI Coding Agents (YAML)

```yaml
product: "Matlock — Agent & Developer Tools. (Efficient. Exact. By the book.)"
pinned_version: "v1.0.0+1"
web_command_center: "https://matlock.dutchp2p.com/en/app"
free_local_scan: "https://matlock.dutchp2p.com/en/#wasm-instant-audit"
docs_hub: "https://matlock.dutchp2p.com/en/docs"
online_manual: "https://matlock.dutchp2p.com/en/manual"
public_repository: "https://github.com/Dutchp2p/matlock-public"
online_operational_map: "https://matlock.dutchp2p.com/llms.txt"
mcp_resource_uri: "matlock://help/appliance-manual"
mcp_stdio_command: "npx -y @dutchp2p/matlock-mcp | uvx matlock-mcp | matlock.exe mcp --stdio (Windows) | matlock mcp --stdio (.deb) or /path/to/matlock-linux-x64.AppImage mcp --stdio (Linux & GoogleBook) | matlock-mcp --stdio --headless --no-coverage (Linux x64, Windows x64 & macOS arm64)"
network_ports: 0
git_hooks_installed: 0
builtin_git_push_in_test_runs: false
custom_push_deploy_actions_allowed: true
mcp_tools_count: 27
primary_pipeline:
  card: "Matlock"
  sequence_id: "seq_matlock"
  entry_tool_index_0: "matlock_run_scan"
  badge_svg_url: "https://matlock.dutchp2p.com/badge/verified.svg"
  stages: "Clean -> Get -> Format -> Lint -> Analyze/Compile -> Test -> Coverage (depth 0..2)"
  cold_box_default: false
  cold_box_boundary_triggers: ["before external git push", "before cloud-drive save", "before removable backup", "before release compile"]
modularity_tuning_dial:
  person_only_sealed_os_settings: true
  default_tier: "Grade C (<= 250 / <= 80 fn)"
  tiers: ["Grade A (<= 60 / <= 25 fn)", "Grade B (<= 100 / <= 40 fn)", "Grade C (<= 250 / <= 80 fn)", "Grade D (<= 500 / <= 120 fn)", "Minimum (<= 1000 / <= 250 fn)"]
ignore_scopes_5: ["file:line:code", "file:code", "*:code", "file", "folder/"]
lock_governance:
  safeguarded: "Read & Run Only (auto-reverts unauthorized edits + Envelope tamper alert)"
  unlocked: "AI agent can modify (Read, Write, Modify & Run)"
os_storage:
  scope: "private_user_profile_outside_repo"
  env_override: "MATLOCK_STATE_DIR"
```

### F. Agent Operational Principles & Execution Boundaries
* **Principle 1 (No Test Weakening or Suppression)**: Never delete tests, loosen assertions, or inject inline suppressions (`// ignore:`, `/* nolint */`, `# noqa`, `@ts-ignore`); doing so raises removed-test integrity records, reverts Safeguarded files, and halts headless runs (`exit 65`).
* **Principle 2 (Safeguard Immutability & Separate Testing vs. Push)**: **Safeguarded** items are Read & Run Only, Matlock never installs `.git/hooks/*`, and `Matlock` (`seq_matlock`) never auto-commits or pushes during test runs (users and MCP agents can freely register custom `git push` or cloud-deploy Action Cards and Sequence chains).
* **Principle 3 (Boundary Cold Box & PR Provenance)**: Keep `cold_box: false` during rapid coding sprints, run `matlock_run_sequence(id: "seq_matlock", cold_box: true)` before push/cloud-save/backup/compile, halt on `STOP_IMMEDIATELY` / `HALT_FOR_REPLACEMENT` (`STOP_AND_ALERT_USER`), and include the Logo-Only `pr_verification_badge` (`https://matlock.dutchp2p.com/badge/verified.svg`) in Pull Request descriptions once `verdict == "PASSED"`.