The folder is still the review.
Open Markdown Review is an MIT-licensed reference implementation of a file-based review protocol. A review package freezes the selected Markdown and its captured dependencies, and records actions as independent, append-only event files. The clients do not maintain competing copies of the discussion.
The package can live on a normal disk, in a Git working tree, or in a synchronized or mounted folder. Creation captures the selected files and required resources rather than leaving dependencies on the author's absolute source paths. Git still needs commits and synchronization; a folder protocol does not make Git a live collaboration service.
design-review/
├── manifest.json
├── revisions/
├── blobs/
├── events/
├── Review-Design.html
├── StartReview-windows-x64.exe # selected participant platforms
├── StartReview-macos-arm64
├── StartReview-linux-x64
└── START-HERE.txtTables, Mermaid diagrams, captured images and explicit attachments belong to the frozen revision. They are not fetched again merely because someone opens the review later. Required external resources must be captured successfully during creation; a link is not automatically a complete offline archive of its target.
The browser no longer has to own filesystem permission.
A double-clicked HTML client remains available where the browser permits local folder access. That is not a dependable assumption on every managed computer. A browser may expose showDirectoryPicker and still deny it because of its context, sandbox or policy.
The Go companion provides another transport. The participant runs the supplied platform executable, which opens the same review toolbox at a temporary 127.0.0.1 address. A scoped local capability connects that browser session to the selected review folder. The participant needs neither Node.js nor Go installed.
This is a local web server, not a central collaboration backend and not a policy bypass. The process runs on each participant's computer; the folder remains the shared state. Endpoint controls may still block execution or localhost access. Keep the companion running until saves finish.
Companions arrive inside the extension update
Both authoring VSIX packages include Windows x64, Linux x64 and macOS ARM64 Go companions. During creation, the initiator selects the participant platforms to copy into the review folder. There is no separate companion installer, runtime download or companion updater for participants.
Updating the installed extension does not silently replace tools in every existing shared review. The creator explicitly runs Update Portable Browser Client for the chosen review. That operation uses the installed bundled tools, retains recoverable backups and checks that review evidence is unchanged. Comments and review progress are not a migration target.
“Finished” is a state, not a guess.
The creator can invite a bounded list of reviewer email addresses and add participants later. The client guides a participant to enter the invited address. A reviewer can finish their own review and reopen it for another pass; the initiator can see individual progress.
| Participant state | What it communicates |
|---|---|
| Not started | No participating activity recorded for this invited reviewer. |
| In progress | The participant has started, but has not finalized their review. |
| Finished | The participant explicitly finished; reopening makes further work visible again. |
Approval or rejection is separate from completion. Someone can finish with objections. The review's global open/closed lifecycle is also separate: a closed review is not a writable review until the initiator reopens it.
Email addresses here are self-asserted identity, not proof of identity, Windows sign-in inheritance or Entra authentication. Initiator-only actions are enforced by the clients and event rules, but a person with direct write access can impersonate an unsigned actor. Folder access control remains essential.
A finding needs a route back to the document.
Anchored comments and suggested edits link in both directions: from the discussion to its text, and from highlighted content back to the discussion. A review-wide findings panel includes feedback on other Markdown files, not just the document currently selected.
The creator workbench helps triage findings, record decisions, apply accepted suggestions when source preconditions still hold, and connect a published fix with later verification. Frozen review text is not silently rewritten when the working source changes. The review retains the earlier revision and its discussion.
Resolved findings expose reopening rather than presenting normal reply/decision controls as if nothing changed. Creator decisions and reviewer verification are distinct actions. A conflict or stale source precondition should stop an automatic edit rather than overwrite someone else's work.
Less scrolling around the tool itself
Version 0.6.5 moves reading controls into the existing action toolbar beside PDF export. Selecting a document opens it at the top; following a heading or finding navigates to the intended location. Previous/next navigation and bounded continuous reading let the reader continue through a multi-document scope without another permanent header.
The clean document is not the audit archive.
| Export | Intended result |
|---|---|
| Review PDF | Frozen review documents, reviewer progress and native PDF comment annotations carrying the discussion, with a recorded export and evidence inventory. |
| Clean PDF | Document content without review comments, participant information or review audit additions. It does not append a review export event. |
Native annotations keep feedback in the PDF's comments interface instead of appending a separate page for every discussion. Open the comments panel in a PDF viewer that supports annotations; not every browser preview presents them equally. Tables, oversized images, links and Unicode text have dedicated layout and regression coverage, but arbitrary HTML/CSS and every writing system are not promised to reproduce perfectly.
The PDF is an offline reading artifact, not a replacement for the package. Retain the package and its inventory when exact revision bytes and complete event history matter. Browser print is a convenience feature, not the recorded review export.
Interchange rules, not toolbar coordinates.
The project keeps three layers explicit. Core protocol 0.6 defines identities, immutable evidence, revision-bound actions, participant progress, finding processing and deterministic state. Profiles specify concrete document/portable-client behavior, including captured resources and versioned Slidev source interpretation. Clients decide how to present those capabilities.
VS Code and the Go host share TypeScript validation and state rules. Go supplies the confined native filesystem and local HTTP boundary and executes the shared neutral core through Goja. The protocol reducer was not independently rewritten in Go. The older Node host remains in the repository as a legacy/reference client; it is not the default delivered companion.
Existing 0.5 and legacy 0.4 packages retain their versioned interpretation. A software version number and a protocol version number are different: publishing extension 0.6.5 does not rename the core wire contract to 0.6.5.
A usable reference, not a certification claim.
- Local-first is not instantaneous synchronization. Clients refresh and merge received events, but cannot accelerate OneDrive, a slow share or an unsynchronized Git clone.
- Executables are not universally approved. Signing/notarization and organization-managed endpoint acceptance remain separate deployment concerns.
- Authentication is not inferred. Entering an invited email address is not a verified login or a digital signature.
- Rendering is a supported subset. Sanitized Markdown/HTML and the Slidev source profile are not an arbitrary web application or a full interactive slide runtime.
- Tests have a scope. Native platform evidence must match the actual binary. Cross-compiling is not a Windows/Linux execution test, and real SMB qualification remains untested.
The implementation status, delivery guide and protocol entry point describe the concrete boundaries. The code is MIT-licensed; M.I.R.D.A. is the project's sharing philosophy, not an additional software license.
The useful change is fairly modest: fewer assumptions about the participant's browser, a clearer end to each person's review, and a better route from feedback to retained evidence. The folder still owns the review.