mhproto 0.8.0-preview.0

package/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to MHProto
+
+Use Node 22 or 24 and npm. Install the locked dependencies with `npm ci`.
+
+```sh
+npm run check
+npm run format
+```
+
+`check` runs formatting and the Node/DOM tests. Tests use temporary projects and
+clean them up. They cover actual CLI calls, structured Node test events, path
+containment, schema validation, offline exports, type navigation and comparison.
+JSDOM tests do not establish painted browser layout.
+
+For real HTTP and desktop/mobile Chromium flows, install the pinned browser and run:
+
+```sh
+npx playwright install --with-deps chromium
+npm run test:browser
+```
+
+The browser suite starts a loopback viewer, exercises navigation, linked types,
+attachment ownership and persistence, iteration diffs and offline save/reload.
+It writes screenshots and console diagnostics to `test-results/browser/`. Review
+the screenshots for layout; automated assertions do not replace visual judgment.
+GitHub CI uploads these artifacts along with dependency-audit and registry-signature
+reports. The offline Mermaid renderer is source-built with a separate locked dependency
+set. CI verifies a clean byte-identical rebuild, all retained licenses, the
+exact bundled-version advisory audit and the build dependency audit. See
+[the renderer notes](viewer/vendor/README.md).
+
+Keep changes scoped. Add regression tests for observable bugs. Preserve the
+single-owner attachment policy and the distinction between failed, stale and
+unchecked evidence. Agent context must retain exact rules and explicit deferred
+references. Add a screenshot for changes to the reading flow.
+
+## Code map
+
+| Area                                                | Files                                 |
+| --------------------------------------------------- | ------------------------------------- |
+| Contract input and validation                       | src/core.mjs, src/config.mjs          |
+| Scoped agent context                                | src/context.mjs                       |
+| Verification and Node reporter                      | src/verify.mjs, src/node-reporter.mjs |
+| Contained writes and attachment metadata            | src/paths.mjs, src/visuals.mjs        |
+| Local HTTP viewer and offline export                | src/server.mjs                        |
+| CLI workflows                                       | bin/mhproto.mjs                       |
+| Reading, types, attachment ownership and navigation | viewer/app.js                         |
+| Pure snapshots and semantic comparison              | viewer/diff.js                        |
+| Agent workflows and format reference                | skills/                               |
+
+There is no compilation step. The shared comparison module runs in Node and in
+the browser. Standalone export inlines that module, the viewer and Mermaid.
+
+## Before a public release
+
+Read [the publishing steps](doc/publishing.md) and doc/release-review.md. Run `npm run release:prepare` from a clean committed checkout to produce and test
+the preview archive. Preparation does not publish it.
+`npm pack --dry-run --json --ignore-scripts` inspects the planned file list without
+creating an archive. `npm pack` runs the prepack check before creating a package.
+Verify a clean installation of the resulting tarball in a separate project before
+publishing. Do not put local app copies, evidence, screenshots, credentials or
+machine-specific paths in the npm package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MHProto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# MHProto
+
+**A shared contract for humans and coding agents.**
+
+MHProto (Machine–Human Protocol) keeps what your app should do alongside its API
+definitions, examples and verification checks. Humans review the contract in a browser; coding agents use
+the same source files to implement and verify it.
+
+Everything lives in your repository. No hosted service or AI account is required.
+
+## What it does
+
+- **Agree on a feature:** keep Behaviour, Interface, Verification and Examples
+  together—the BIVE approach.
+- **Review it:** browse features, endpoints and linked types; attach design
+  references and compare iterations.
+- **Work with agents:** install five skills for Codex or Claude and retrieve
+  scoped context for an endpoint, rule or type.
+- **Verify it:** link checks to the contract and see passing, failing, unchecked
+  and stale evidence.
+
+## Try it locally
+
+Development preview. Requires Node 22 or newer; the package is not published to npm.
+
+```sh
+git clone https://github.com/rbsx/mhproto.git
+cd mhproto
+npm ci
+npm run check
+```
+
+Then, from your application's directory:
+
+```sh
+npm install --save-dev /path/to/mhproto
+npx mhproto init --agent codex
+npx mhproto view
+```
+
+Use `--agent claude` or `--agent all` for other skill layouts. Edit the generated
+draft to describe your feature, then run `npx mhproto check`.
+
+## Learn more
+
+Visit the **[project website](https://mhproto.dev/)** for the overview,
+demo and [documentation](https://mhproto.dev/docs/). The
+[guide source](doc/guide.md) is also available in this repository.
+
+For development, see [CONTRIBUTING.md](CONTRIBUTING.md). Current preview boundaries
+and release gates are recorded in [the release review](doc/release-review.md).
+
+MIT-licensed. See [LICENSE](LICENSE) and [third-party notices](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,40 @@
+# Third-party software
+
+MHProto's own source is MIT-licensed; see LICENSE. Third-party components retain
+their respective licenses.
+
+## Offline Mermaid viewer
+
+The viewer includes a source rebuild of Mermaid 12.1.0 with patched, locked
+browser dependencies. Complete retained notices are in `viewer/vendor/NOTICE.txt`,
+with original texts in `viewer/vendor/licenses/`. The appendix is embedded in the
+renderer, so standalone HTML exports retain it.
+
+`viewer/vendor/license-inventory.json` records 79 package/version entries with
+archive integrity, notice sources and hashes. Coverage follows esbuild inputs and
+32 compiled parser chunks, including flattened vscode-uri/path-browserify sources.
+Embedded upstream and original Node.js path module attributions are retained.
+
+Licenses include MIT, ISC, BSD-3-Clause, Apache-2.0, EPL-2.0 and Unlicense.
+DOMPurify offers MPL-2.0 OR Apache-2.0; this distribution selects Apache-2.0 while
+retaining its complete original dual-license notice. Khroma's MIT terms come from
+its license file; Fastdom's MIT terms come from its README.
+
+ELK/elkjs is distributed under EPL-2.0. Copyright (c) 2017 Kiel University and
+others. No changes were made to the supplied elkjs implementation; it is bundled
+and minified by esbuild. JavaScript wrapper/build source for elkjs 0.9.3 is available
+at https://github.com/kieler/elkjs/tree/a8304cf79fde75bc2ab1a89d28320f53f8637436;
+ELK's Java algorithm source and tagged releases are at https://github.com/eclipse/elk.
+The original EPL-2.0 text and source availability notice travel with the bundle.
+
+Mermaid's runtime source and official build plugins are unchanged. MHProto uses
+its own committed dependency lock, adds a namespace wrapper and appends notices.
+Repeat the clean source rebuild and original-archive checks with
+`npm run verify:vendor`; repeat the separate bundled security audit with
+`npm run audit:vendor`. See `viewer/vendor/README.md`.
+
+## Separately installed dependencies
+
+Runtime npm dependencies (Ajv, ajv-formats and YAML) are installed separately by npm
+with their own licenses. Development and renderer build dependencies are excluded
+from the published runtime package.

package/bin/mhproto.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+import { mkdir, readFile, readdir, writeFile, cp, lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { loadProject, validateProject, packageRoot } from '../src/core.mjs';
+import { verifyCapability } from '../src/verify.mjs';
+import { compareModels, exportViewer, model, serve } from '../src/server.mjs';
+import { contextPacket, encodeContext } from '../src/context.mjs';
+import { contractSnapshot } from '../viewer/diff.js';
+import { atomicWrite, writePath } from '../src/paths.mjs';
+
+let command = 'help',
+  root = process.cwd();
+const options = new Map();
+const option = (name, fallback) => options.get(name) ?? fallback;
+const has = (name) => options.has(name);
+function parseArguments() {
+  const args = process.argv.slice(2);
+  command = args[0] && !args[0].startsWith('-') ? args.shift() : 'help';
+  const allowed = {
+    init: ['agent', 'no-skills'],
+    skills: ['agent'],
+    check: ['json'],
+    inspect: [],
+    context: [
+      'capability',
+      'operation',
+      'rule',
+      'schema',
+      'example',
+      'check',
+      'visual',
+      'section',
+      'max-chars',
+      'stats',
+    ],
+    verify: ['capability'],
+    view: ['port', 'against'],
+    snapshot: ['out', 'label'],
+    diff: ['against'],
+    build: ['out', 'against'],
+    help: [],
+  };
+  if (!Object.hasOwn(allowed, command)) throw new Error(`Unknown command: ${command}`);
+  const flags = new Set(['help', 'json', 'no-skills', 'stats']);
+  const valid = new Set(['root', 'help', ...allowed[command]]);
+  for (let i = 0; i < args.length; i++) {
+    const key = args[i].replace(/^--/, '');
+    if (!args[i].startsWith('--') || !valid.has(key))
+      throw new Error(`Unknown option for ${command}: ${args[i]}`);
+    if (options.has(key)) throw new Error(`Option --${key} was supplied twice`);
+    if (flags.has(key)) options.set(key, true);
+    else {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) throw new Error(`Option --${key} requires a value`);
+      options.set(key, value);
+    }
+  }
+  if (has('help')) command = 'help';
+  root = path.resolve(option('root', process.cwd()));
+}
+
+async function skillDestinations(agent) {
+  if (!['codex', 'claude', 'all'].includes(agent))
+    throw new Error('--agent must be codex, claude or all');
+  const directories =
+    agent === 'all'
+      ? ['.agents/skills', '.claude/skills']
+      : [agent === 'claude' ? '.claude/skills' : '.agents/skills'];
+  const names = await readdir(path.join(packageRoot, 'skills'));
+  const destinations = directories.flatMap((dir) =>
+    names.map((name) => ({ name, relative: path.join(dir, name) })),
+  );
+  for (const { relative } of destinations) {
+    const file = await writePath(root, relative);
+    try {
+      await lstat(file);
+      throw new Error(`Refusing to overwrite ${relative}`);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  return destinations;
+}
+
+async function installSkills(agent = 'codex') {
+  for (const { name, relative } of await skillDestinations(agent)) {
+    await cp(path.join(packageRoot, 'skills', name), await writePath(root, relative), {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+    });
+  }
+  console.log(`Installed MHProto skills for ${agent}`);
+}
+
+async function init() {
+  await mkdir(root, { recursive: true });
+  if (!has('no-skills')) await skillDestinations(option('agent', 'codex'));
+  const files = {
+    'mhproto.yaml':
+      'version: 1\nname: My app\nsystem: mhproto/system.md\ncapabilities:\n  - id: example\n    title: Example capability\n    spec: mhproto/capabilities/example/spec.md\n    interface: mhproto/interfaces/openapi.yaml\n    examples: mhproto/capabilities/example/examples.yaml\n    checks: mhproto/capabilities/example/checks.yaml\n    sources: []\n',
+    'mhproto/system.md':
+      '# System map\n\nReplace this with the app’s capabilities, owners and dependencies.\n',
+    'mhproto/capabilities/example/spec.md':
+      '# Example capability\n\nStatus: draft — replace this scaffold before implementing.\n\n## Purpose\nDescribe the capability and its boundaries.\n\n## Rules\n- **EXAMPLE-B-1** Reading status returns the current service status.\n\n## States and permissions\nDocument transitions, permissions, failures and recovery.\n',
+    'mhproto/interfaces/openapi.yaml':
+      'openapi: 3.1.0\ninfo:\n  title: Example API\n  version: "1"\npaths:\n  /status:\n    get:\n      operationId: getStatus\n      x-mhproto-rules: [EXAMPLE-B-1]\n      responses:\n        "200":\n          description: Current status\n          content:\n            application/json:\n              schema:\n                type: object\n                required: [status]\n                additionalProperties: false\n                properties:\n                  status: { type: string, enum: [ready] }\n              example: { status: ready }\n',
+    'mhproto/capabilities/example/examples.yaml':
+      'examples:\n  - id: EXAMPLE-E-1\n    title: Read service status\n    rules: [EXAMPLE-B-1]\n    operations: [getStatus]\n    given: The service is ready.\n    when: A client reads its status.\n    then: The response says ready.\n',
+    'mhproto/capabilities/example/checks.yaml':
+      '# Add argv commands and rule/example references. No tests are assumed to exist.\nchecks: []\n',
+  };
+  // Preflight all destinations; never overwrite an existing contract.
+  for (const file of Object.keys(files)) {
+    try {
+      await lstat(await writePath(root, file));
+      throw new Error(`Refusing to overwrite ${file}`);
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+  for (const [file, contents] of Object.entries(files))
+    await writeFile(await writePath(root, file), contents, { flag: 'wx' });
+  if (!has('no-skills')) await installSkills(option('agent', 'codex'));
+  console.log(
+    'Initialised MHProto. Replace the example capability; run mhproto check and mhproto view.',
+  );
+}
+
+try {
+  parseArguments();
+  if (command === 'init') await init();
+  else if (command === 'skills') await installSkills(option('agent', 'codex'));
+  else if (command === 'check') {
+    const project = await loadProject(root),
+      issues = await validateProject(project);
+    if (has('json')) console.log(JSON.stringify({ name: project.name, issues }, null, 2));
+    else {
+      console.log(
+        `${project.name}: ${project.capabilities.length} capability, ${project.capabilities.reduce((n, c) => n + c.rules.length, 0)} rules, ${project.capabilities.reduce((n, c) => n + c.operations.length, 0)} operations`,
+      );
+      for (const issue of issues)
+        console.log(`${issue.level.toUpperCase()} [${issue.capability}] ${issue.message}`);
+      console.log(
+        `${issues.filter((i) => i.level === 'error').length} errors, ${issues.filter((i) => i.level === 'warning').length} warnings`,
+      );
+    }
+    if (issues.some((i) => i.level === 'error')) process.exitCode = 1;
+  } else if (command === 'context') {
+    const options = Object.fromEntries(
+      ['capability', 'operation', 'rule', 'schema', 'example', 'check', 'visual', 'section'].map(
+        (k) => [k, option(k)],
+      ),
+    );
+    const output = encodeContext(
+      contextPacket(await loadProject(root), options),
+      Number(option('max-chars', '12000')),
+    );
+    console.log(output);
+    if (has('stats'))
+      console.error(
+        JSON.stringify({
+          characters: output.length,
+          bytes: Buffer.byteLength(output),
+          note: 'Exact text sizes; model token counts vary.',
+        }),
+      );
+  } else if (command === 'inspect') console.log(JSON.stringify(await model(root), null, 2));
+  else if (command === 'verify') {
+    const project = await loadProject(root),
+      issues = await validateProject(project);
+    if (issues.some((i) => i.level === 'error'))
+      throw new Error('Contract validation failed; run mhproto check');
+    const selected = option('capability');
+    const caps = project.capabilities.filter((c) => !selected || c.id === selected);
+    if (!caps.length) throw new Error(`Unknown capability: ${selected}`);
+    for (const cap of caps) {
+      if (!cap.checks.length) {
+        console.log(`${cap.id}: no checks configured; evidence remains unchecked`);
+        continue;
+      }
+      console.log(`Running ${cap.checks.length} checks for ${cap.id}`);
+      const result = await verifyCapability(project, cap, (r) => {
+        console.log(`${r.status.toUpperCase()} ${r.id} (${r.durationMs}ms)`);
+        if (r.status === 'failing')
+          console.log(
+            [
+              r.error,
+              r.stderr.slice(-1500),
+              ...r.missing.map((t) => 'Missing test: ' + t),
+              ...r.skipped.map((t) => 'Skipped test: ' + t),
+              ...r.todo.map((t) => 'TODO test: ' + t),
+            ]
+              .filter(Boolean)
+              .join('\n'),
+          );
+      });
+      if (result.results.some((r) => r.status === 'failing') || result.changedDuringRun)
+        process.exitCode = 1;
+    }
+  } else if (command === 'view') {
+    await loadProject(root);
+    const port = Number(option('port', '4317'));
+    if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port');
+    const server = await serve(root, port, { against: option('against') });
+    console.log(`MHProto viewer: http://127.0.0.1:${server.address().port}`);
+    console.log(
+      'Local browser view. Visual attachments save to mhproto/visuals.yaml; source edits refresh automatically.',
+    );
+    for (const signal of ['SIGINT', 'SIGTERM'])
+      process.on(signal, () => server.close(() => process.exit(0)));
+  } else if (command === 'snapshot') {
+    const destination = path.resolve(root, option('out', '.mhproto/baseline.json'));
+    const relative = path.relative(root, destination);
+    const data =
+      JSON.stringify(
+        contractSnapshot(await model(root), { label: option('label', 'Iteration baseline') }),
+        null,
+        2,
+      ) + '\n';
+    if (!relative.startsWith('..' + path.sep) && !path.isAbsolute(relative))
+      await atomicWrite(root, relative, data);
+    else {
+      await mkdir(path.dirname(destination), { recursive: true });
+      await atomicWrite(path.dirname(destination), path.basename(destination), data);
+    }
+    console.log(`Saved baseline: ${destination}`);
+  } else if (command === 'diff') {
+    const before = JSON.parse(
+      await readFile(path.resolve(root, option('against', '.mhproto/baseline.json')), 'utf8'),
+    );
+    console.log(JSON.stringify(compareModels(before, await model(root)), null, 2));
+  } else if (command === 'build') {
+    const destination = path.resolve(root, option('out', '.mhproto/viewer'));
+    await exportViewer(root, destination, { against: option('against') });
+    console.log(
+      `Exported viewer: ${destination}. Open viewer.html directly or serve this folder over HTTP.`,
+    );
+  } else if (command === 'help' || has('help')) {
+    const { version } = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    console.log(
+      `MHProto ${version}\n\nCommands: init, skills, check, context, inspect, verify, view, snapshot, diff, build\n\nOptions: --root PATH, --json (check), --capability ID (verify/context), --port PORT (view),\n         --operation ID|--rule ID|--schema NAME|--example ID|--check ID|--visual ID (context),\n         --section request,response,behaviour,errors,examples,checks,visuals,sources (context),\n         --max-chars N, --stats (context),\n         --agent codex|claude|all (init/skills), --no-skills (init),\n         --out PATH (snapshot/build), --label TEXT (snapshot), --against PATH (diff/view/build)`,
+    );
+  } else throw new Error(`Unknown command: ${command}`);
+} catch (error) {
+  console.error(`MHProto: ${error.message}`);
+  process.exitCode = 1;
+}

package/doc/context-design.md

@@ -0,0 +1,43 @@
+# Context design
+
+Keep MHProto useful to people in the viewer, and small for agents at its retrieval boundary. Collapsing browser content alone does not reduce tokens: an agent must request a smaller packet.
+
+## Established patterns
+
+[Anthropic: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) recommends high-signal context, just-in-time retrieval through references, and progressive disclosure. Applied here: a feature index first, then selected endpoint, rule, schema or example detail. The contract remains in authoritative files rather than a giant always-loaded prompt.
+
+[Anthropic: Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) describes discovering interfaces on demand and filtering/transforming results in code before passing them to a model. Applied here: deterministic CLI packets, deduplicated error schemas, scenario/check summaries and image metadata. No model call is needed to assemble them.
+
+[OpenAI: Harness engineering](https://openai.com/index/harness-engineering/) describes short agent instructions as a map into structured repository documentation, with progressive disclosure and mechanical validation. Applied here: concise installable skills, explicit deferred references, linked checks and revision-bound evidence.
+
+These are architecture patterns. Provider examples are not measurements of MHProto or a guarantee of our savings.
+
+## Retrieval flow
+
+1. `mhproto context` identifies the feature and endpoint.
+2. `mhproto context --capability daily --operation tap` supplies the endpoint contract.
+3. Fetch needed `--schema`, `--rule`, `--example` or `--check` detail. Read deferred groups before changing their behaviour.
+4. Fetch `--visual ID` metadata and open its image/design only if it helps the task.
+5. Inspect authoritative implementation/docs and run required checks for the change.
+
+Optional `--section` narrows a packet. The default 12,000-character output budget raises an actionable error rather than dropping trailing rules. `--stats` writes character and byte counts to stderr. No token count is assumed.
+
+Root structures preserve constraints, required fields, nullability and refs. Nested schemas are retrieved by name; grouped rules retain their IDs and an explicit instruction to fetch them. Exact rule text, semantic preconditions and error codes remain intact. Larger concrete payload examples are available through --example. Check summaries keep stale/failing/unchecked states; verbose runner logs do not enter the endpoint packet. Images are stored separately, never as base64 inside the project model or context output.
+
+## Pilot measurement
+
+Measured against the same fresh Impostor daily project on 2026-10-02. Compact JSON, excluding its trailing newline. See context-measurements.json.
+
+| Read                              | Characters |   Bytes |
+| --------------------------------- | ---------: | ------: |
+| Complete normalized project model |    129,642 | 129,766 |
+| Feature/operation index           |        980 |     980 |
+| Tap endpoint packet               |      8,501 |   8,505 |
+| Tap request/response only         |      1,914 |   1,914 |
+| Ask endpoint packet               |      9,279 |   9,281 |
+
+The tap packet is 93.44% smaller in characters than the complete model because it retrieves a different, relevant scope. This is not equivalent-content compression or a measured billing reduction. Model tokenization, follow-up reads, implementation files, retries and any opened images affect total consumption. Fetching every reference may approach or exceed a full read. Avoid summarizing away constraints just to improve this metric.
+
+## Current boundary
+
+This version supplies an on-demand CLI boundary and retrieval instructions. It does not intercept every agent tool call, enforce a model session token budget or implement provider prompt caching. Contract text still changes through repository files. Image interpretation remains an explicit agent action; no image analysis service runs automatically.

package/doc/context-measurements.json

@@ -0,0 +1,28 @@
+{
+  "fullModel": {
+    "characters": 129642,
+    "bytes": 129766
+  },
+  "packets": {
+    "index": {
+      "characters": 980,
+      "bytes": 980,
+      "reductionPercent": 99.24
+    },
+    "tap": {
+      "characters": 8501,
+      "bytes": 8505,
+      "reductionPercent": 93.44
+    },
+    "tapInterface": {
+      "characters": 1914,
+      "bytes": 1914,
+      "reductionPercent": 98.52
+    },
+    "ask": {
+      "characters": 9279,
+      "bytes": 9281,
+      "reductionPercent": 92.84
+    }
+  }
+}

package/doc/guide.md

@@ -0,0 +1,138 @@
+# MHProto guide
+
+Detailed usage and reference documentation for the [project website](https://mhproto.dev/docs/).
+
+## Start locally
+
+This is a development preview, not an npm registry release. Node 22+ is required.
+The hosted CI matrix covers Node 22/24 on Linux and macOS and [has passed](https://github.com/rbsx/mhproto/actions/runs/37059758163). Windows is unverified.
+
+From a checkout of this repository:
+
+```sh
+npm ci
+npm run check
+```
+
+In your application, install the checkout and create a draft contract:
+
+```sh
+npm install --save-dev /path/to/mhproto
+npx mhproto init --agent codex
+npx mhproto check
+npx mhproto snapshot
+npx mhproto view
+```
+
+Replace the example with your feature. `init` refuses to overwrite existing
+contracts or skills. `skills --agent codex|claude|all` installs repository-local
+skills in `.agents/skills` or `.claude/skills`; global agent settings stay unchanged.
+The isolated Impostor pilot is a development fixture, not a package prerequisite.
+
+## Commands
+
+| Command         | Result                                                                   |
+| --------------- | ------------------------------------------------------------------------ |
+| init            | Scaffold a draft capability and install skills                           |
+| skills          | Install the bundled agent skills separately                              |
+| check           | Validate references, schemas, payload examples and check bindings        |
+| context         | Retrieve a compact index or scoped endpoint/rule/schema packet           |
+| inspect         | Emit the normalised project model as JSON                                |
+| verify          | Run linked argv commands, store revision-bound evidence                  |
+| view            | Serve a local viewer; save visual attachments and refresh source changes |
+| snapshot / diff | Save a baseline and inspect contract changes                             |
+| build           | Export viewer assets, model.json and a self-contained viewer.html        |
+
+Use `--root PATH` for another app. See `mhproto help` for command options and `skills/mhproto-specify/references/format.md` for the data format.
+
+## Viewer
+
+The sidebar lists the project and its features. A feature opens one page: title, product/logic description, relative app URL, visible API request/response signatures, play-state diagrams and a Checks section. Search stays at the top; Sources is a secondary link in the sidebar.
+
+Each endpoint opens its own page with a stable `#/features/:feature/api/:operation` URL. Behaviour, errors, examples and checks are attached to that endpoint. Named types are clickable inside their signatures. Each type opens a shareable definition page with links to feature overviews, every endpoint using it and referencing type pages. Nested objects still expand in place; there is no separate type catalogue or modal navigation. The Copy page link action preserves direct navigation to the endpoint.
+
+The visual system uses white backgrounds, near-black text, neutral dividers and blue/purple links. HTTP method badges retain restrained colour coding. See `doc/viewer-design.md` for the flows and acceptance criteria.
+
+Optional capability `url` identifies the app route. `presentation.operationOrder` orders endpoints by use. `presentation.operations[operationId]` accepts `description`, a concise `behaviour` summary, additional `rules`, optional `ruleGroups` (`title`, `rules`) and `diagrams` (`title`, Mermaid `source`). `ruleTitles` supplies concise labels in search and check gaps. These are navigation and context; full source clauses remain authoritative. Operation and rule references are validated.
+
+Mermaid fences in the behaviour/system document and endpoint diagrams render as monochrome SVG. The bundled Mermaid runtime also works offline in the exported HTML. Diagram source stays available on demand; invalid diagrams show an error without blocking the rest of the page. The CLI validates diagram metadata, not Mermaid syntax; renderer tests and preview review establish diagram validity.
+
+`mhproto build --out ./mhproto-preview` creates a portable `viewer.html` that can be opened without a server. In the live viewer, attachments save to `mhproto/visuals.yaml` and `mhproto/assets`. In an exported snapshot, attachments stay in that preview; **Save preview** downloads a self-contained copy with them. Edit the source files to change normative contract text.
+
+Portable exports include check status, timing and observed test names, but omit captured stdout/stderr, failure messages, executed command records and the generated project-root path. Authored contracts, configured check commands/environment values, examples and attachments are retained. Review those files before sharing; export is not a secret scanner.
+
+## Verification semantics
+
+Unchecked, passing, failing and stale are distinct. Node checks require exact expected test names and structured results; missing/skipped/TODO tests fail. Evidence includes commands, exit status, timings, observed tests and a SHA-256 digest of the project configuration, system document, capability files, explicitly tracked sources and declared check files. Failures are recorded. Checks execute sequentially, with a timeout. They inherit the environment and execute the configured commands without a shell; they are not sandboxed. Run verification only for check commands you trust. Structured Node reporter output is bounded to 1 MB and fails closed if malformed or oversized.
+
+MHProto validates payload schemas and examples and its own cross-references; this is a bounded contract validator, not a complete OpenAPI standards validator. V0 supports OpenAPI 3.1 with local refs. Interfaces can originate in Zod, Protobuf tooling or handwritten OpenAPI, but only OpenAPI is consumed in this version. Optional type generation remains with the app’s chosen generator.
+
+A linked passing test is evidence for a rule, not proof of all its cases. Prompt-text tests do not establish live AI behaviour. Runtime permissions, races and retry behaviour require meaningful app tests. No paid evaluation is invoked by the pilot.
+
+Browser editing of normative contract text, type generation, remote schema refs and hosted collaboration are deferred.
+
+## Develop
+
+Node 22+. `npm ci`, `npm run check`, `npm run format`. See CONTRIBUTING.md and doc/release-review.md. The preview archive is prepared with `npm run release:prepare`; registry publication is a separate step. The CLI and viewer run directly from source; no build step is needed. Dependencies: yaml, Ajv, ajv-formats. The viewer uses platform DOM APIs and escapes source content.
+
+## Visual references
+
+Attach a screenshot, design image/PDF or HTTPS design link using the single `+` after a feature/endpoint description, scenario, rule or check text, or alongside a Request/Response header. The action appears on hover or keyboard focus and opens an inline form. Schema signatures and nested object fields only render types and expansion; they do not create attachment controls. Existing field/schema references appear beneath the matching request/response header. Supported files: PNG, JPEG, WebP, GIF and PDF, up to 8 MB. Design links open their source rather than loading an embedded design app. The metadata format is in the bundled format reference.
+
+Collapsed object fields show a pale-yellow `{...}`; optional markers, nullability, arrays and constraints remain visible. Expand in place to inspect their fields.
+
+## Compact agent context
+
+```sh
+mhproto context
+mhproto context --capability daily --operation tap --stats
+mhproto context --capability daily --operation tap --section request,response
+mhproto context --capability daily --rule DAILY-PLAY-4
+mhproto context --capability daily --schema DailyPlayState
+```
+
+Packets are assembled in code, not summarised by a model. Rule text and failure semantics remain exact. Nested types and grouped rules are explicit references, payload examples are fetched separately, and check summaries retain freshness. Image bytes, Mermaid's runtime, repeated OpenAPI examples and raw execution logs never enter these packets. The default 12,000-character budget fails visibly if exceeded; it never silently truncates rules. This reduces input context size; actual tokens and billed cost depend on the model and subsequent reads. See [context-design.md](context-design.md) for research, limitations and measurements.
+
+## Linked type entities
+
+Signatures label declared component types by their existing OpenAPI names: `DailyTodayResponse { ... }`, `case: DailyCaseView {...} | null`, and `play: DailyPlayState {...} | null`. Type names link to `#/features/:feature/types/:type-id`. Fields remain inline and expandable. Following the type link opens its page; selecting the yellow placeholder expands the object.
+
+The type page shows the definition and a Used in section containing feature overview and endpoint links. Backlinks include nested/transitive uses, all declared response statuses, and direct references from other type pages. A type name can also be found through project search. Nothing is added to the sidebar or to object attachment controls.
+
+Unnamed query/path/header/cookie structures, inline bodies/responses and nested object items receive deterministic viewer labels, such as `GetTodayQuery` and `DailyRoundAnswersItem`. These pages explain where the structure comes from; labels do not create new application types or change the contract. Declared names take priority, and generated name collisions remain separate. Types shared through the same interface file link across features; equally named types from different interfaces stay distinct. Cycles are bounded.
+
+The index is built once per loaded model in the viewer and cached until that model changes. It is not serialized into the project model, snapshots or scoped agent packets, and does not duplicate the authoritative schemas. Type pages remain compatible with the standalone export.
+
+## Review an iteration
+
+Open **Changes** in the sidebar. Choose an earlier snapshot JSON or exported MHProto preview HTML, or **Use current spec as baseline** before editing. Changes lists added, changed and removed items by feature. Open an item for its changed fields with Before/Now values, then follow **Open current** to see it in context. Comparison links retain `?compare=1`; **Hide highlights** returns to normal reading. Changed type names and added/changed/removed fields are marked inline. Removed definitions remain reviewable on their change page.
+
+```sh
+mhproto snapshot --label "Before case history" --out .mhproto/iterations/before-history.json
+# Edit the source contract, then:
+mhproto view --against .mhproto/iterations/before-history.json
+mhproto build --against .mhproto/iterations/before-history.json --out ./review
+mhproto diff --against .mhproto/iterations/before-history.json
+```
+
+Without `--against`, the viewer uses `.mhproto/baseline.json`. The live **Use current spec as baseline** action replaces that local baseline with the current contract. When using `--against`, this action is disabled by the server so an explicit saved iteration is retained. **Download current snapshot** exports a named JSON baseline. In a standalone preview, save the amended preview to retain its selected/new baseline. Imported files stay in the viewer; importing an HTML preview reads its model without executing its scripts. Shared URLs require the same current spec and baseline to produce the same comparison; the exported HTML carries both.
+
+The comparison is one pure module shared by CLI, server and browser. It covers feature/system text, API operations and global settings, named schemas, attached behaviour/presentation, examples, check definitions and visual metadata. Object key order and unordered sets (required fields, enums and rule references) do not count as changes. Runtime paths, digests, evidence timestamps, test output and renderer code are excluded. Snapshot data is detached from current data and carries no execution logs. This is a spec delta, not an automatic breaking-change assessment or a code diff. Visual asset bytes are not compared when their metadata/path stays unchanged. Agent context packets remain unchanged.
+
+## Release status and boundaries
+
+The `0.8.0-preview.0` release candidate is prepared for npm's `next` channel;
+publication is pending. Its renderer is rebuilt with patched dependencies and
+verified notices. See [the release review](release-review.md) for evidence and
+platform limits, and [publishing steps](publishing.md) for the final registry step.
+
+The validator is intentionally bounded: JSON Schema 2020-12 payloads, local JSON
+pointer references and linked metadata. It does not implement the whole OpenAPI
+standard. The viewer primarily renders application/json structures. Agent context
+is scoped retrieval, not equivalent-content compression or guaranteed token savings.
+Visual metadata writes are serialized within one process; concurrent writers
+from separate viewer processes are not coordinated. Revision-bound evidence
+tracks files, not every external service or environmental change.
+
+MHProto source is MIT-licensed. See LICENSE and THIRD_PARTY_NOTICES.md for the
+separately licensed viewer dependency.