mhproto 0.8.0-preview.0

package/doc/publishing.md

@@ -0,0 +1,93 @@
+# Publishing MHProto to npm
+
+The library is public at https://github.com/rbsx/mhproto. The website lives in the
+private `rbsx/mhproto-site` repository and deploys independently to https://mhproto.dev.
+
+## Prepared preview — 2026-10-03
+
+Version `0.8.0-preview.0` is configured for public access on the `next` dist-tag.
+The package has not been published. The renderer's previous security gate is
+cleared by a reproducible patched build; see [the release review](release-review.md).
+This machine is not authenticated to npm, and `mhproto` returned E404 when checked.
+An absent package is not a name reservation.
+
+## 1. Prepare and test the exact archive
+
+From a clean, committed library checkout with Node 22.12+ and Chromium installed:
+
+```sh
+npm ci
+npx playwright install chromium
+npm run release:prepare
+```
+
+This runs formatting/tests, root audit/signatures, a clean Mermaid rebuild and
+notice verification, the exact bundled-version audit, build dependency audit,
+desktop/mobile browser flows, and a fresh install of the generated tarball.
+The installed CLI and HTTP/offline viewer are exercised from that consumer.
+
+Outputs:
+
+- `artifacts/release/mhproto-0.8.0-preview.0.tgz`
+- `artifacts/release/release-manifest.json` with source commit, SHA-256, npm SHA-512
+  integrity and full file list.
+- `test-results/release/` browser screenshots.
+
+Website source, build tools, tests, credentials and local project data are excluded.
+Require all GitHub checks for the manifest's source commit to pass. Review that
+archive and its manifest; publish those exact bytes. Preparation performs no
+registry write.
+
+## 2. Authenticate the package owner
+
+Use an npm account with two-factor authentication enabled:
+
+```sh
+npm login
+npm whoami
+npm view mhproto name version dist-tags --json
+```
+
+E404 means no package was found; it does not guarantee the registry will accept
+the name. If another owner has claimed it, choose an owned scope and update the
+package metadata, archive and installation instructions before publishing.
+Direct publication requires 2FA or a granular token configured to bypass 2FA;
+interactive 2FA is suitable for this first manual release.
+
+Source: [npm's public package publishing guide](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages/).
+
+## 3. Publish the approved archive
+
+After owner approval, current audit/name checks and green CI for the recorded
+source commit, publish the tested archive:
+
+```sh
+npm audit
+npm run audit:vendor
+npm publish artifacts/release/mhproto-0.8.0-preview.0.tgz --access public --tag next
+npm view mhproto@0.8.0-preview.0 version dist.integrity dist-tags --json
+```
+
+Complete npm's authentication/2FA prompt. Compare registry `dist.integrity` with
+the release manifest, then test `npm install --save-dev mhproto@next` in another
+fresh consumer. `next` keeps the preview explicit without making it `latest`.
+
+Tag the manifest's exact commit as `v0.8.0-preview.0` and publish the release notes
+only after registry verification. Update the private website's pinned library
+commit and installation copy to `npm install -D mhproto@next`, then deploy it.
+The source-preview copy remains accurate until publication succeeds.
+
+## Later releases
+
+Choose a new preview version, update root package/lock metadata, commit the reviewed
+changes and repeat `npm run release:prepare`. Promote a reviewed stable version to
+`latest` separately once preview feedback and supported-platform checks justify it.
+
+For automation after the first publication, configure npm trusted publishing for
+`rbsx/mhproto` and the exact GitHub release workflow filename. Use a GitHub-hosted
+runner, `id-token: write`, aligned repository metadata and an explicit release
+approval. Do not configure the private website as the npm publisher.
+Trusted publishing uses OIDC instead of a stored npm token; supported public
+repository releases can receive npm provenance automatically.
+
+Source: [npm trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).

package/doc/release-notes.md

@@ -0,0 +1,23 @@
+# MHProto 0.8.0-preview.0
+
+Prepared development preview for the npm `next` channel. Publication is pending.
+
+MHProto keeps behaviour, API contracts, examples and verification checks in your
+repository, with a shared browser view for humans and scoped context for agents.
+
+- Browse feature pages, endpoints and linked types; attach design references.
+- Compare iterations and keep evidence linked to contract rules and examples.
+- Scaffold a project and install five skills for Codex, Claude or both.
+- Retrieve scoped context and run structured checks with stale-evidence detection.
+- Export a portable browser preview with diagrams, attachments and notices.
+- Render diagrams with source-built Mermaid 12.1.0 and patched dependencies.
+
+Node 22/24 on Linux/macOS are tested targets. Windows and non-Chromium browser
+flows remain unverified. This preview supports a documented OpenAPI 3.1/JSON Schema
+subset, and check results are evidence rather than a proof of correctness.
+
+Project overview and demo: https://mhproto.dev/
+Documentation: https://mhproto.dev/docs/
+Source: https://github.com/rbsx/mhproto
+
+After npm publication, install explicitly with `npm install -D mhproto@next`.

package/doc/release-review-2026-10-02.md

@@ -0,0 +1,127 @@
+# Pre-release code review
+
+Reviewed 2026-10-02. **Decision: keep the package private; do not create or publish a new npm release yet.** The implementation is materially safer and more predictable after the fixes below. Remaining release gates are concrete verification work, not a request for a broad rewrite.
+
+## Status update: 2026-10-03
+
+The original findings and local-only evidence below are retained as a dated review.
+Subsequent work cleared these gates:
+
+- The hosted Linux/macOS, Node 22/24 matrix, dependency audit/signature job and
+  desktop/mobile Chromium suite passed for
+  [commit 7d75f8b](https://github.com/rbsx/mhproto/actions/runs/37068214828).
+- Live npm audits reported no known vulnerabilities in the locked dependency tree.
+  This does not authenticate the copied Mermaid bundle.
+- The library is public at https://github.com/rbsx/mhproto, and the homepage,
+  documentation and interactive demo are live at https://mhproto.dev.
+- Desktop/mobile website flows and offline demo save/reload passed in Chromium.
+
+The Mermaid bundle is now verified against the official `mermaid@11.16.1` npm
+archive with its deterministic local wrapper. Repeat with
+`node scripts/verify-mermaid.mjs`; hashes and registry integrity are recorded in
+the vendor manifest. Its source map identifies 59 bundled dependency versions.
+The bundled license inventory is now complete: 74 package/version entries,
+including 32 matching parser chunks and their nested dependencies, have verified
+archive integrity and retained license texts. Notices are also embedded in the
+renderer for portable HTML exports. Repeat with `npm run verify:vendor`.
+
+A separate live audit of those exact versions found advisories affecting
+DOMPurify 3.4.0, js-yaml 4.1.1 and lodash-es 4.17.23. These include high-severity
+YAML parsing and Lodash advisories. A clean ordinary `npm audit` did not cover the
+vendored code. See `viewer/vendor/bundled-audit.json`; update/rebuild the renderer
+and assess the affected call paths before clearing this release gate.
+A draft `0.7.0` tarball was created and installed into a fresh consumer with only
+runtime dependencies. Its public import, executable CLI, scaffold, both sets of
+five skills, validation, scoped context, structured linked checks, stale evidence,
+snapshot/diff and portable export passed. The installed HTTP viewer and exported
+HTML passed desktop/mobile Chromium checks for diagrams, linked types, comparison
+and offline navigation. The full notice appendix is present in the installed
+package and single-file export. This is a tested draft, not an npm release.
+
+Windows remains unverified. No npm version has been published; `private: true`
+remains enabled. See [publishing steps](publishing.md) for the release sequence.
+
+## Scope and method
+
+Reviewed the CLI, file loading and writes, metadata validation, OpenAPI/schema handling, scoped agent context, verification evidence, HTTP handler, portable exports, visual attachments, type navigation, comparison module, five bundled skills, dependency lockfile and planned npm contents. Checked the isolated Impostor pilot against the revised implementation. The original application was not edited.
+
+Used source inspection, actual CLI subprocesses, regression tests, JSDOM, the vendored Mermaid runtime, a fresh locked dependency install and an isolated planned-package layout. This is an engineering review, not a penetration test or a certification of the entire OpenAPI standard. Local checks ran on macOS with Node 24.18.1. The configured Node 22/24, Linux/macOS CI matrix has not run on a hosted repository.
+
+## Findings fixed
+
+Severity indicates the effect on MHProto's advertised guarantees. High means incorrect verification/contract acceptance or an unintended write/disclosure boundary; medium means incorrect output, comparison or workflow behaviour. It does not assert remote exploitability.
+
+| Priority        | Finding and prior consequence                                                                                                                                 | Change and evidence                                                                                                                                                                                                                                                                                           |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| High            | Node TODO tests could count as passing even though Node permits them without a failing exit code. Nonterminal reporter events could satisfy an expected name. | Require completed pass/fail events; reject TODO, skipped, missing and failing tests. Added real TODO and fabricated-event regressions, plus UTF-8 split handling.                                                                                                                                             |
+| High            | Unbounded or malformed structured reporter output could undermine verification and consume excessive memory.                                                  | Bound structured output to 1 MB, reject malformed/oversized streams and stop the command on overflow. Retain bounded ordinary output. Verification still runs trusted commands with inherited environment; it is not a sandbox.                                                                               |
+| High            | Boolean `false` schemas were treated as absent/empty; invalid inline schemas without examples could escape validation.                                        | Preserve boolean schemas; compile declared inline schemas even without payloads. Validate named media examples. Cache compiled schemas. Regressions cover rejection and display/context preservation.                                                                                                         |
+| High            | Evidence could remain fresh after configuration, system rules or declared test-file changes.                                                                  | Include those inputs in the revision digest alongside capability and tracked source files. Bound directory traversal through symlink cycles. Regression mutates each missing input.                                                                                                                           |
+| High            | Several generated writes lacked the same real-path containment as reads and could follow escaping symlinks.                                                   | Centralize contained writes and unique atomic replacement. Preflight CLI destinations; reject existing init/skill destinations and root-directory exports, including root aliases. Regressions prove outside files are preserved. This is not protection against a hostile concurrent filesystem mutator.     |
+| High            | Shareable exports contained captured process output, executed command records and the generated machine root path.                                            | Export an evidence-summary whitelist. Keep status, timing and observed test names; omit captured logs/errors and generated paths. Validate and prepare all output before replacing files. Authored commands/environment values, contracts, examples and attachments remain and require review before sharing. |
+| Medium          | Local OpenAPI object references and path-level parameter overrides were not consistently resolved.                                                            | Resolve local path/parameter/request-body/response refs, reject cycles and duplicate parameters, apply operation overrides by name/location, decode JSON pointer names and include TRACE. Regression verifies context and payload validation.                                                                 |
+| Medium          | Response example validation mishandled declared status ranges; metadata errors could become incidental runtime failures.                                      | Match explicit status, `2XX` and default responses. Validate MHProto metadata with source-file diagnostics, reject unknown fields and allow `x-*` extensions. Preserve the pilot's existing check description field.                                                                                          |
+| Medium          | Viewer nullability/false schemas and unsafe imported design links could be misrepresented.                                                                    | Preserve nullable object type arrays and `never` schemas. Actionable design links require HTTPS without credentials. Imported preview HTML is read as marked JSON without constructing an HTML document or executing scripts.                                                                                 |
+| Medium          | Diff normalization could ignore payload array order when a property happened to be named `rules`; path metadata could be missed.                              | Distinguish literal payloads from unordered reference sets and compare path-level metadata. Fenced rule examples remain prose rather than invented normative rules. Added regressions for each case.                                                                                                          |
+| Medium          | Missing CLI values, unsupported flags and invalid skill agents could fail after partial scaffolding.                                                          | Validate command-specific options and preflight destinations; help never performs work. Added CLI subprocess regressions.                                                                                                                                                                                     |
+| Release hygiene | License declaration lacked a top-level license file; source style, contributor guidance and dependency provenance were incomplete.                            | Added MIT LICENSE, third-party notices, contributor guide, formatter/check scripts, CI configuration and vendor hash/provenance manifest. Raised the YAML minimum to 2.8.3. Kept `private: true`.                                                                                                             |
+
+The YAML minimum follows the [maintainer's security advisory](https://github.com/eemeli/yaml/security/advisories/GHSA-48c2-rrv3-qjmp), which identifies 2.8.3 as the fix for deeply nested input causing a stack overflow. The locked install uses YAML 2.9.1. This specific fix does not establish that all dependencies are free of known vulnerabilities.
+
+## Validation results
+
+- **58/58 framework tests pass**, with no skips or TODOs. The previous suite had 44 tests; 14 additional regressions cover the review findings.
+- Formatting passes. Tests clean up their temporary projects.
+- **23/23 linked Impostor checks pass** with the revised verifier. The final contract check reports **0 errors and 12 warnings** for rules without linked executable checks. Those gaps remain visible; passing linked checks do not imply full behavioural coverage.
+- Pilot tests exercise application services and HTTP handlers in process with a request/response double, an in-memory database and stub witnesses. They do not prove socket transport, deployed behaviour or live model quality. No paid model evaluation was run.
+- A fresh `npm ci --offline --ignore-scripts` installs all 47 locked dependencies into an isolated source checkout. Offline installation verifies lock/cache consistency, not dependency security.
+- The isolated source checkout also passes formatting and all 58 tests.
+- Planned package-layout smoke verifies the public import, executable CLI, scaffold, five skill installs, validation, scoped context, snapshot/diff and portable viewer export from staged npm-listed files. It uses an isolated dependency install; it is not an installation from an npm tarball.
+- `npm pack --dry-run --json --ignore-scripts` inspects the planned files without creating an archive. No application copy, local evidence, screenshots, test fixtures, node_modules or credentials are included. CLI executable mode, skills, viewer assets and licenses are included.
+- The planned package now contains 33 files including the separate guide, approximately 1.05 MB packed and 3.80 MB unpacked. The reused Mermaid bundle accounts for about 94% of the unpacked bytes; a reproducible renderer build is the main dependency/size decision.
+- Standalone exports execute their shared comparison in JSDOM with network access disabled; Mermaid examples render with the actual local bundle. These checks do not establish painted layout, keyboard behaviour in a real browser or real HTTP transport. Local socket/browser preview was unavailable in this environment.
+- The final exported Impostor preview passes an offline DOM smoke with six endpoints, a linked type page, rendered Mermaid SVG and 23 fresh passing evidence summaries. It performs no fetch; SVG text measurement is approximate.
+
+## Release gates still open
+
+| Gate                                     | Required evidence                                                                                                                                                                                                                                                                                                |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Live dependency audit                    | Run a current audit and inspect relevant advisories for runtime dependencies and the vendored renderer. The attempted npm audit failed because registry DNS was unavailable; it did not return a clean audit.                                                                                                    |
+| Mermaid provenance and licenses          | Obtain an official upstream artifact or reproducible build; verify the bundle identity and complete transitive license inventory. The reused bundle's claimed version is 11.16.1, but that claim is **not authenticated**. Its recorded SHA-256 identifies the local bytes only. Embedded notices are preserved. |
+| Supported runtimes and real viewer smoke | Run the configured hosted Linux/macOS, Node 22/24 matrix. Test actual HTTP transport and review desktop/mobile pixels, keyboard navigation, attachment ownership, type pages and offline import/export in real browsers. Windows remains unverified.                                                             |
+| Actual package installation              | After the preceding gates, create a tarball, install it into a clean consumer and repeat the CLI/import/offline viewer smoke. Review final packed contents. The older downloadable 0.7.0 prototype predates this review and is not a reviewed release.                                                           |
+| Public project metadata                  | Choose the public repository and add accurate repository/issue links; verify npm package/scope ownership and the Cloudflare homepage setup. Remove `private: true` only as part of the reviewed release. Nothing was published or deployed by this review.                                                       |
+
+## Maintainability and declared limits
+
+Backend responsibilities are now separated into metadata validation, contained paths, contract handling, context, verification, visuals and serving. Comparison stays a single pure module shared by Node and the browser. Attachment actions retain one owner; fields render types and expansion only.
+
+The viewer remains a large DOM module. Before adding another major flow, separate type indexing, rendering and attachment/diff controllers behind the existing observable tests. A framework migration or comprehensive rewrite is not necessary for the current preview.
+
+The contract validator implements a documented subset of OpenAPI 3.1 and JSON Schema 2020-12 with local references. Viewer signatures primarily handle application/json. Check success is evidence, not proof; trusted commands can forge their own output. Evidence tracks files, not tool upgrades or external environment/service state. Separate viewer processes do not coordinate attachment writes. Diff is a contract delta, not breaking-change classification; unchanged visual metadata does not detect changed asset bytes. Scoped context reduces supplied material but does not guarantee billed token savings.
+
+Treat these as documented preview boundaries. Do not hide them behind an expansive “fully validated” claim.
+
+## Release-check preparation after the documentation move
+
+The concise README and separate guide are preserved. Repository/issue metadata now
+points to rbsx/mhproto. CI has additional dependency advisory/signature checks and a
+desktop/mobile Chromium flow suite using pinned Playwright 1.63.0. Browser artifacts
+include screenshots and console diagnostics; tests cover actual HTTP, navigation,
+type expansion/backlinks, attachment ownership/persistence, diff details and offline
+preview save/reload without external requests. These tests use a synthetic contract,
+not production data or live model calls.
+
+The preparation has not cleared those gates. GitHub/npm DNS is unavailable in this
+execution environment, so the new jobs cannot be pushed or inspected here, and the
+real-browser suite cannot run under the local socket/browser restrictions. The
+existing 58-test suite still passes. Browser syntax, fixture contract validity and
+the new locked dependency install are checked separately; none is reported as a
+successful real-browser run. Mermaid provenance/licences and actual tarball
+installation remain open. No package was created or published.
+
+The updated 49-dependency lock installs successfully from the offline cache into
+an isolated checkout, and that checkout passes formatting and all 58 tests. The
+browser fixture validates with no contract errors and produces the intended
+linked-type diff. Planned npm contents exclude the browser fixture, browser suite
+and screenshots. Offline installation does not clear the live audit/signature gate.

package/doc/release-review.md

@@ -0,0 +1,68 @@
+# Preview release review
+
+Reviewed 2026-10-03. **Prepared version: `0.8.0-preview.0`, for the npm `next` tag.**
+The previous renderer security gate is cleared by an independently repeatable
+source build with patched dependencies. No npm publication has occurred.
+
+## Changes that cleared the gate
+
+The renderer is rebuilt from Mermaid 12.1.0 at upstream commit
+`21f72f07ea22c0af48a3149c550654e80d8e40cb`. The verified source archive,
+unmodified upstream schema/Jison plugins and committed dependency lock reproduce
+the vendored executable bytes. DOMPurify is 3.4.16, js-yaml is 4.3.2, and all
+bundled Lodash is 4.18.1. The new parser uses Chevrotain 13.2.0 and Langium 4.4.0;
+the old vulnerable nested Lodash dependency is gone.
+
+The exact-version registry audit reports no known advisories for the 79 recorded
+renderer package versions, including dependencies inside 32 compiled parser
+chunks. Both the library's dependency tree and the renderer build dependency tree
+audit clean. Registry signatures and available provenance for the library's
+installed dependencies verify. Recheck these time-sensitive results before
+publication; an audit is not a penetration test.
+
+The retained license inventory covers those 79 entries. Original archive bytes,
+parser source-map identities and flattened vscode-uri/path-browserify sources
+verify. Full notices remain embedded in the renderer for offline exports. ELK's
+EPL-2.0 text, copyright and source availability links are included. DOMPurify's
+Apache-2.0 alternative is selected. See [third-party notices](../THIRD_PARTY_NOTICES.md)
+and [the renderer manifest](../viewer/vendor/manifest.json).
+
+## Required candidate evidence
+
+`npm run release:prepare` requires a clean committed checkout, then runs:
+
+- Formatting and all 58 tests, including actual flow/state/sequence SVG rendering.
+- Library advisory/signature checks, a clean renderer rebuild, archive license
+  verification, the exact bundled-version audit and build dependency audit.
+- Desktop/mobile Chromium flows over HTTP and offline save/reload.
+- A fresh install of the exact tarball: public import, executable CLI, scaffold,
+  ten Codex/Claude skill copies, validation, scoped context, linked checks,
+  evidence freshness, snapshot/diff and portable export.
+- Installed-package HTTP and offline browser flows with diagrams and linked types.
+
+It writes `artifacts/release/mhproto-0.8.0-preview.0.tgz` and a manifest containing
+its source commit, SHA-256, SHA-512 integrity and complete packed file list.
+Website source, test fixtures, build tooling and credentials are excluded.
+GitHub runs the Linux/macOS, Node 22/24 matrix, audits, renderer verification,
+desktop/mobile browser suite and packed-consumer smoke for the release commit.
+Require all jobs to pass before publication.
+
+## Remaining publication steps and limits
+
+This machine has no npm login (`npm whoami` returned ENEEDAUTH). The `mhproto` name
+returned E404, which is not a reservation or ownership guarantee. Publication
+requires the package owner's npm authentication, approval of the tested archive,
+and a final current audit/name check. Follow [the publishing steps](publishing.md).
+
+Node 22 and 24 on Linux/macOS are the tested targets. Windows and browsers other
+than Chromium remain unverified. Mermaid 12's browser targets are Safari/iOS 17.4,
+Chrome/Edge 121 and Firefox 123 or newer. The package remains a development preview:
+check results are evidence, the validator supports a documented OpenAPI/JSON
+Schema subset, evidence does not track external service or tool-version changes,
+and multiple viewer processes do not coordinate attachment writes. Diff reports
+contract changes, not a breaking-change classification.
+
+The website is maintained in a separate private repository. Its npm installation
+copy must change only after the package becomes available. The
+[dated original review](release-review-2026-10-02.md) preserves earlier findings
+and historical limitations; its old release gates are superseded here.

package/doc/viewer-design.md

@@ -0,0 +1,80 @@
+# MHProto viewer design
+
+Start with the feature the developer is working on, its app route, and the data exchanged to implement it.
+
+## Structure
+
+- Sidebar: [mh] logo linked to https://mhproto.dev/, Project → Impostor, Features → Daily case (blue link). Sources stays in the sidebar footer.
+- Search at the top of every page.
+- Feature overview: title, product/logic description, relative URL, API visible by default, play-state diagram, then Checks.
+- Endpoint page: back to the feature, method/path, purpose, copyable page link, inline request/response types, attached behaviour, useful diagrams, errors, examples and Checks.
+- Type names, Check and Sources links open pages. No tabs or modals.
+
+## Reading flow
+
+Read what the page loads and shows. Scan the endpoints in client-use order. Read request/response objects beside each endpoint; open it for complete behaviour and failures. Expand a nested object in place when its fields matter. Follow a rule or check through a stable URL.
+
+Passing checks and rules without checks are compact disclosures below the API. Failures, unchecked results and stale results are surfaced directly. Full commands and raw payloads stay deferred.
+
+## Diagrams
+
+Use Mermaid for state transitions, UI decisions, start/retry idempotence, action races and delayed public reveal. Avoid diagrams that repeat a trivial request/response. Mermaid fences and endpoint diagrams render using the bundled runtime, with white fills, black text and neutral lines. Source is available separately. Invalid syntax must not prevent reading the page.
+
+The pilot uses six diagrams: play states, page-loading branches, retrying a start, overlapping actions, tap eligibility/transitions, and public reveal timing.
+
+## Visual system
+
+White background, near-black text, neutral separators. Blue links and purple visited links. Colour accents are limited to HTTP methods, focus, errors and pale-yellow expandable object placeholders. Signature fields stay inline. Type names link to definitions and usage backlinks; no separate shared-type catalogue.
+
+## Acceptance
+
+- Search is the first main-page control; the project and feature are clear in the sidebar.
+- Daily case describes real client behaviour and shows /daily.
+- API and object signatures are visible without opening a tab or accordion.
+- Every endpoint has a directly loadable URL; Back returns to the feature.
+- Behaviour is attached to endpoints, including privacy, preconditions and failures.
+- Nested fields expand in context, with nullable/optional distinctions retained.
+- Checks appear below API, with freshness and coverage limits clear.
+- Flow, state and sequence diagrams render, including loops and branching.
+- A broken diagram retains its source and does not break navigation.
+- Responsive layout stacks request/response objects on narrow screens.
+
+DOM tests cover navigation and actual Mermaid SVG rendering using simulated text measurements. Desktop/mobile Chromium release flows now cover HTTP navigation and offline export/save/reload; non-Chromium browser flows remain unverified.
+
+## Visual attachment flow
+
+Use the single `+` after a feature/endpoint description, scenario, rule or check text block, or directly alongside a Request/Response header. Attach one image/PDF or design link, give it a descriptive title and optionally note the state or source. The result appears beneath that block/header. Object signatures, nested fields and Path/JSON-body labels do not offer attachment actions. Existing field/shared-object references are displayed beneath the matching header with their field path or type name; their metadata is retained.
+
+The workspace viewer writes files and metadata to the app. The exported preview keeps added visuals in memory until Save preview downloads the amended HTML. The footer and save action communicate that state. Existing attachments are embedded when exporting; their bytes live in a separate registry, outside the project model and agent context packets. Images load lazily; external design apps are linked instead of embedded.
+
+Collapsed objects show only `{...}` in pale yellow. Keep optional markers and nullable/array types alongside it. Do not squeeze nested keys into that placeholder.
+
+## Attachment ownership (0.4.1)
+
+One component owns the text/header, its single creation button, a read-only gallery and its editor. An explicit placement policy permits only text blocks and Request/Response headers to create controls. A page-scoped target registry gives repeated semantic targets one editing owner. The schema renderer has no attachment API or project/media dependency.
+
+Hover and keyboard focus styles address the creation button directly inside its text/header zone. They do not use API-column, field, gallery or ancestor-section hover selectors. Zones do not nest. This prevents hovering over a field from revealing a header action or multiple schema actions.
+
+Regression checks reproduce a request with path parameters plus a shared JSON-body schema, a response with nested shared objects, expanded fields and reused types. They assert one creation control per header, none inside signatures, one matching hover action on a text/header zone and none on fields/columns. Repeated rule targets retain one owner. Existing field/type visuals stay accessible under the header. Cancel restores keyboard focus to the original control. DOM/CSS selector tests do not claim painted browser layout validation.
+
+## Type reading flow (0.5)
+
+Read `GetTodayQuery { date: string; deviceId: string; }` below Request → Query and `DailyTodayResponse { ... }` below Response. Nested `case` and `play` fields show clickable `DailyCaseView` and `DailyPlayState` names beside their pale-yellow `{...}` expanders. Array items and named enum types are linked too. Keep required/optional markers, nullability and constraints visible.
+
+Follow a name to its definition page. Used in links back to every feature overview and endpoint whose request or response includes the type, including nested uses. Referenced by types links to other definitions containing it. Endpoint links include the request part or response status. The copy action and URL make the page shareable; search finds types as well. No type catalogue is added to navigation.
+
+The index is a separate logical layer from schema rendering and attachment ownership. Source identity uses the interface file and type/declaration id, not structural similarity or just the name. Anonymous structures get deterministic viewer labels with an explicit source note; they do not become new normative schemas. Recursive type relationships stop at visited identities. The index stays in memory and is regenerated for a new model, rather than expanding the serialized model or agent context.
+
+Acceptance: existing type names are preserved; root/nested fields link; generated labels resolve to the exact inline structure; required/optional markers survive; every use has an endpoint and overview backlink; incoming type links are present; shared interfaces link across features while unrelated homonyms stay separate; recursive schemas terminate; direct links, search, standalone export and the single-attachment-owner rules keep working.
+
+## Iteration review (0.6)
+
+Keep the reading view unchanged until the reader enters Changes. Its sidebar link shows a compact item count when a baseline exists. The Changes page identifies the baseline, shows added/changed/removed counts, and lists only changed items grouped by feature. A category dropdown narrows the list. No modal or raw project dump is introduced.
+
+Choose a snapshot JSON/earlier preview, or use the current spec as the iteration baseline. Open a change for a Before/Now table containing only changed fields. Open its current endpoint/type/feature/check page with comparison highlights enabled. Keep named type links and nested field expansion; show added/changed/removed field labels and changed item badges. Use words with pale green/yellow/red accents so colour is not the only signal. Hide highlights restores ordinary reading and preserves a rule deep link. Removed items retain their old definition on their change page.
+
+Diff computation is separate from rendering, type indexing and attachment ownership. The same semantic comparator runs in CLI/server/browser. Stable change identities use capability, kind and entity id, never row positions. A saved baseline is a detached snapshot; updates to live visuals cannot silently alter it. Metadata/evidence churn stays outside the comparator. No attachment controls appear in comparison pages or object fields. Type pages still provide affected-endpoint backlinks for indirect schema changes.
+
+The live viewer refreshes both model and baseline; a file selected by the reader stays local to that viewer. Explicit --against comparisons are protected from the baseline reset action. Standalone exports embed their baseline and work offline; Save preview retains a new/selected baseline alongside visual attachments. Earlier HTML imports are parsed as inert model data. Invalid imports keep the prior comparison and show an inline error.
+
+Acceptance: compare additions/changes/removals, including required/nullable/constraint edits; retain removed definitions; link to current pages and preserve comparison URLs; omit evidence/key-order/set-order noise; keep null distinct from absence; support legacy/new JSON snapshots and earlier HTML previews; preserve baseline on invalid files; save/reload offline with no network request; keep one attachment owner per text/header.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "mhproto",
+  "version": "0.8.0-preview.0",
+  "description": "Machine–Human Protocol: a shared contract workspace for humans and coding agents",
+  "type": "module",
+  "bin": {
+    "mhproto": "./bin/mhproto.mjs"
+  },
+  "exports": {
+    ".": "./src/core.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "viewer",
+    "skills",
+    "doc",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "npm run format:check && npm test",
+    "prepack": "npm run check",
+    "test:browser": "node --test test/browser.mjs",
+    "verify:vendor": "node scripts/verify-mermaid.mjs && node scripts/verify-mermaid-licenses.mjs",
+    "audit:vendor": "node scripts/audit-mermaid.mjs",
+    "test:packed": "node test/packed.mjs",
+    "release:prepare": "node scripts/prepare-release.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "yaml": "^2.8.3"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "jsdom": "^26.1.0",
+    "playwright": "1.63.0",
+    "prettier": "3.6.2"
+  },
+  "homepage": "https://mhproto.dev/",
+  "keywords": [
+    "specification",
+    "contracts",
+    "openapi",
+    "agents",
+    "spec-driven-development"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rbsx/mhproto.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rbsx/mhproto/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/mhproto-discover/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: mhproto-discover
+description: Discover a capability in an existing app and produce source-backed MHProto behaviour, interface and example drafts. Use for adopting MHProto or inspecting a capability before specification work.
+---
+
+# MHProto Discover
+
+Start with `mhproto context` for the feature index, then `mhproto context --capability ID --operation ID` for the affected endpoint. Load only relevant `--rule`, `--schema`, `--example` or `--check` detail; `--section` narrows a packet. Read every deferred rule group the change touches before editing. Inspect the authoritative source when deciding intent or making a change. Do not load the exported HTML or whole `mhproto inspect` model into the prompt. Visual packets contain references; open images/design links only when needed.
+
+Read the project’s AGENTS.md and authoritative product docs, then mhproto.yaml and the relevant capability. Inspect providers, consumers, existing schemas and tests. Reuse an existing OpenAPI 3.1 interface or its generator; do not invent a parallel schema.
+
+Record behaviour as confirmed, inferred or unknown with source paths. Preserve existing approval provenance. Reverse-engineered code describes observations; it does not approve requirements. Surface disagreements with product docs. Bound discovery to the requested capability.
+
+Write small capability drafts, numbered rules and representative examples, including a failure/recovery case. Leave missing checks and unknown decisions visible. Read ../mhproto-specify/references/format.md for the file model. Run `mhproto check` after changes. Do not alter application behaviour as part of discovery.

package/skills/mhproto-implement/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: mhproto-implement
+description: Implement an agreed MHProto contract in a project while preserving its interfaces and behaviour. Use when the user requests implementation of a specified capability or change.
+---
+
+# MHProto Implement
+
+Start with `mhproto context` for the feature index, then `mhproto context --capability ID --operation ID` for the affected endpoint. Load only relevant `--rule`, `--schema`, `--example` or `--check` detail; `--section` narrows a packet. Read every deferred rule group the change touches before editing. Inspect the authoritative source when deciding intent or making a change. Do not load the exported HTML or whole `mhproto inspect` model into the prompt. Visual packets contain references; open images/design links only when needed.
+
+Read AGENTS.md, the capability spec, interface schemas, examples and checks. Confirm unresolved decisions do not affect the requested work; surface contradictions rather than inventing requirements.
+
+Implement the requested delta, following the existing schema source and app conventions. Coordinate consumers/providers through the shared interface. Do not silently change the contract to fit the implementation; propose necessary contract changes explicitly.
+
+Keep application tests in their normal locations. Reference rule and example IDs in relevant tests. Use ../mhproto-specify/references/format.md when editing links. Run `mhproto check`, the required app checks and `mhproto verify --capability ID`. Report gaps separately from passing checks.

package/skills/mhproto-reconcile/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: mhproto-reconcile
+description: Find and reconcile disagreements between MHProto specs, interface schemas, examples and application implementation. Use for contract drift or capability upkeep.
+---
+
+# MHProto Reconcile
+
+Start with `mhproto context` for the feature index, then `mhproto context --capability ID --operation ID` for the affected endpoint. Load only relevant `--rule`, `--schema`, `--example` or `--check` detail; `--section` narrows a packet. Read every deferred rule group the change touches before editing. Inspect the authoritative source when deciding intent or making a change. Do not load the exported HTML or whole `mhproto inspect` model into the prompt. Visual packets contain references; open images/design links only when needed.
+
+Read repository authority/provenance and the capability. Run `mhproto check`, inspect stale evidence and review `mhproto diff` if a baseline exists. Inspect the relevant source and tests to distinguish missing checks, stale generated files, implementation bugs and changed product intent.
+
+State each discrepancy with its rule ID and evidence. Fix deterministic tooling or generated-artifact drift within scope. When intent is uncertain, present the decision instead of treating code as automatically authoritative. Preserve existing approvals and human examples.
+
+After the authorised resolution, update affected specs, schemas, examples and checks together. Run required app checks and `mhproto verify`. State remaining gaps. Read ../mhproto-specify/references/format.md for linking conventions.

package/skills/mhproto-specify/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: mhproto-specify
+description: Create or revise a MHProto capability contract before implementing a feature. Use for agreement on behaviour, interfaces, examples and verification expectations.
+---
+
+# MHProto Specify
+
+Start with `mhproto context` for the feature index, then `mhproto context --capability ID --operation ID` for the affected endpoint. Load only relevant `--rule`, `--schema`, `--example` or `--check` detail; `--section` narrows a packet. Read every deferred rule group the change touches before editing. Inspect the authoritative source when deciding intent or making a change. Do not load the exported HTML or whole `mhproto inspect` model into the prompt. Visual packets contain references; open images/design links only when needed.
+
+Read authoritative repository docs and the current capability. Preserve the user’s scope and established decisions. Read references/format.md.
+
+Run `mhproto snapshot` before the first change if no baseline exists; do not replace an existing baseline without intent. Propose precise numbered rules, permissions, state transitions, failure/recovery behaviour and concrete examples. Link interfaces to rule IDs. Reuse the app’s schema source/generator rather than editing generated OpenAPI by hand.
+
+Separate intended behaviour from observed implementation and unresolved decisions. Identify affected providers/consumers and compatibility consequences. Present the contract delta with `mhproto diff`; resolve decisions that affect implementation with the user, without asking them to reconfirm previously agreed behaviour.
+
+Run `mhproto check`. Unbound rules stay visibly unchecked. Changing a spec is not evidence that the app implements it.

package/skills/mhproto-specify/references/format.md

@@ -0,0 +1,20 @@
+# MHProto V0 file format
+
+`mhproto.yaml` uses version: 1, name, system (Markdown path), and capabilities.
+Each capability has id (lowercase slug), title, spec (Markdown), interface (OpenAPI 3.1 JSON/YAML), examples (YAML), checks (YAML), sources (tracked implementation files/directories), optional owner, description and gaps.
+All paths are relative to the application root and cannot escape it through symlinks.
+
+Rules are Markdown bullets: `- **DAILY-PLAY-1** Behaviour statement.` Indented continuation lines belong to that rule. Link OpenAPI operations through `x-mhproto-rules: [DAILY-PLAY-1]`; existing `x-clauses` also works. Local JSON Schema references are supported. Remote references and OpenAPI 3.0 are not supported in V0. Types stay in the established schema source.
+
+An examples.yaml file has an `examples` array. Each entry has id, title, rules (rule IDs), operations (operationIds), given, when and then. Optional request: {operation, body} and response: {status, body} payloads are schema-checked; rejected input scenarios describe the invalid payload in prose instead of claiming it conforms.
+
+A checks.yaml file has a `checks` array. Each entry has id, title, rules, examples, files and command (argv array), optional description, env and timeoutMs. Commands execute from the app root without a shell, with the inherited environment plus configured env. They are not sandboxed; run verification only in repositories whose check commands you trust. timeoutMs must be a positive integer (default 60,000).
+For Node’s runner, use runner: node-test, exact testNames, and command: [node, --import, tsx, --test, --test-reporter, "{mhprotoNodeReporter}", relative/test.ts]. Add --test-name-pattern when useful. The reporter requires completed passing events for exact test names, rejects skipped/TODO/missing tests, and fails closed on malformed or oversized (1 MB) structured output. Include test files in tracked sources.
+
+Evidence is local in .mhproto/evidence/<capability>.json and carries a digest of the contract and tracked implementation. Inputs include mhproto.yaml, the system document, capability files, tracked sources and declared check files. It becomes stale when an input changes. A passing command is evidence, not a proof of requirements correctness or complete coverage.
+
+`mhproto snapshot` stores .mhproto/baseline.json. `mhproto diff` compares rules, operations, schemas, examples and checks. Contract snapshots contain app documentation; review before sharing.
+
+Visual references are optional in `mhproto/visuals.yaml`, as a `visuals` array. Each entry has id, title, kind (screenshot/design), target and one of file (local image/PDF) or url (HTTPS design link). Optional mime, caption and sha256 describe the file. Targets have capability and kind: feature; operation/request/response plus operation id; schema plus schema name; example/rule/check plus id. Response targets also specify status. Field targets have operation id, scope (request/response), JSON-pointer path and response status when applicable. Request paths start at /body, /path, /query, /header or /cookie; response paths start at the body. Use `*` for array items, for example /rounds/_/answers/_/text. Uploaded files live in mhproto/assets. Treat visuals as references, not new normative rules; conflicting designs require a stated contract decision.
+
+`mhproto context` emits a compact feature index. `--capability ID --operation ID` retrieves an endpoint packet with exact directly linked rules, semantic preconditions, error codes, root request/response structures, scenario summaries, check status and visual metadata. Nested schema refs and named rule groups are deferred explicitly. `--schema NAME`, `--rule ID`, `--example ID`, `--check ID` or `--visual ID` retrieves detail. `--section request,response,behaviour,errors,examples,checks,visuals,sources` limits fields. A 12,000-character default budget fails with refinement guidance rather than truncating; increase --max-chars deliberately. Evidence freshness is retained, while full execution logs and image bytes are excluded. --stats reports text sizes on stderr, not model token counts.

package/skills/mhproto-verify/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: mhproto-verify
+description: Write and run MHProto checks linked to agreed behaviour and examples, and inspect evidence gaps. Use for verifying a capability or adding contract-based tests.
+---
+
+# MHProto Verify
+
+Start with `mhproto context` for the feature index, then `mhproto context --capability ID --operation ID` for the affected endpoint. Load only relevant `--rule`, `--schema`, `--example` or `--check` detail; `--section` narrows a packet. Read every deferred rule group the change touches before editing. Inspect the authoritative source when deciding intent or making a change. Do not load the exported HTML or whole `mhproto inspect` model into the prompt. Visual packets contain references; open images/design links only when needed.
+
+Read the agreed rules and examples before implementation details. Derive assertions from observable outcomes, not private helper structure. Cover the requested failure/recovery paths and preserve human-provided examples as the test oracle.
+
+Keep tests in the existing runner. Link each check to precise rules/examples and an argv command in checks.yaml. For Node tests, use the structured reporter and exact testNames; skipped, TODO or missing tests must fail verification. Generic command success proves only that command passed. Label prompt-text checks separately from live model evaluation.
+
+Use ../mhproto-specify/references/format.md. Run `mhproto check` then `mhproto verify --capability ID`. Inspect failures and the report, including freshness and missing test names. Do not claim all linked behaviour is proven, or run paid/live-production checks unless those actions are in scope. Do not rewrite the spec to make a failing implementation pass.