Stet.md

Stet.md is a local-first Markdown review utility. It opens one Markdown file in a loopback browser UI, lets humans add threaded review comments, saves those threads back into the same Markdown file, and lets AI agents reply through a safe CLI.

• npm package: @amit-t/stet-md
• binaries: stet-md, stmd
• marker: stet:thread
• thread IDs: stt_...
• transient state: .stet/

Documentation

Browsable docs site (GitHub Pages): https://amit-t.github.io/stet-md/

The site is a static neo-brutalist index served from docs/: a capability explorer (Browser UI, Agent CLI, Storage, Safety, Security) with per-capability commands, a changelog, search/filter, dark mode, and copy-to-clipboard. It was scaffolded with the gh-repo-mirror skill design system; source lives in docs/index.html, docs/site.css, and docs/site.js.

Deeper references:

• docs/AGENT_PROTOCOL.md — full agent CLI protocol.
• docs/RELEASE_NOTES.md — MVP limitations and release notes.
• docs/prd/ — product requirement docs per subsystem.

Enable Pages once: repo Settings → Pages → Source: Deploy from a branch → main / /docs. docs/.nojekyll is present so asset paths are served verbatim.

Install

Package metadata targets @amit-t/stet-md. Requires Node >=20.10.

Install from local checkout

Use this before the npm package is published:

pnpm install
pnpm run build
pnpm link --global
rehash
stet-md --version
stmd --help

If pnpm link --global says the global bin directory is not configured, run pnpm setup, restart the shell, then repeat pnpm link --global.

Run without installing after npm publish

npx @amit-t/stet-md@latest README.md
# or
pnpm dlx @amit-t/stet-md README.md

npx/pnpm dlx downloads the package to a temporary tool cache, runs the stet-md binary, and leaves no project dependency behind. Pass the same flags you would pass to stet-md:

npx @amit-t/stet-md@latest --author "Amit" --app "Google Chrome" docs/prd/00-stet-master-prd.md
pnpm dlx @amit-t/stet-md --no-open --port 43117 docs/prd/00-stet-master-prd.md

Persistent install after npm publish

For a permanent terminal command:

pnpm add --global @amit-t/stet-md
# or, if you prefer npm for global tools:
npm install -g @amit-t/stet-md

stet-md --version
stet-md README.md

Quick start

stet-md README.md
# or
stmd README.md

Useful launch flags:

stet-md --author "Amit" README.md
stet-md --app "Google Chrome" README.md
stet-md --port 43117 README.md
stet-md --no-open README.md

The server binds to 127.0.0.1, sets an HttpOnly SameSite=Strict cookie, and opens http://127.0.0.1:<port>/. The token is never placed in the URL.

Browser review UI

The UI includes:

• top bar with file name, dirty/saved state, open-thread count, Save, Reload, and patch preview;
• rendered Markdown body with commentable headings and paragraphs;
• + affordances, double-click comments, keyboard c on focused blocks, and document-level comments;
• side-panel thread cards with replies, resolve/reopen controls, orphan and content-drift warnings;
• localStorage draft recovery keyed by file path and loaded file hash;
• conflict banner when the file changes on disk before save.

Resolved threads are collapsed by default. Orphaned threads appear under Needs re-attach and remain preserved in the Markdown file.

Agent CLI

Agents should use CLI commands instead of hand-editing markers:

stet-md list --json FILE.md
stet-md reply FILE.md --thread stt_... --author Claude --message "I updated the paragraph above."
stet-md resolve FILE.md --thread stt_... --author Claude --message "Resolved by the edit above."
stet-md --print-agent-protocol

A helper exists for smoke tests and scripts:

stet-md comment FILE.md --target paragraph:0 --author Amit --message "Please tighten this."

Full protocol: docs/AGENT_PROTOCOL.md.

Storage format

Threads are stored inline as structured HTML-comment markers plus a generated visible blockquote:

<!-- stet:thread
version: 1
id: stt_20260607_150015_7f3a9c
status: open
created_at: 2026-06-07T15:00:15Z
updated_at: 2026-06-07T15:00:15Z
target:
  kind: paragraph
  heading_path:
    - Product goals
  block_ordinal: 0
  source_hash: sha256:...
  quote: Product goals
messages:
  - author: Amit
    created_at: 2026-06-07T15:00:15Z
    body: |-
      This needs a clearer agent workflow.
-->
> [!NOTE]
> **Review thread `stt_20260607_150015_7f3a9c` — open**
>
> **Amit** · 2026-06-07 15:00 UTC
>
> This needs a clearer agent workflow.
<!-- /stet:thread -->

The structured marker is the source of truth. The blockquote is regenerated from marker data on save. Message bodies containing unsafe -- sequences are escaped in the structured marker so they cannot terminate the HTML comment early, then decoded losslessly when Stet.md parses the thread.

Write safety and formatter caveats

Stet.md saves by byte splices only. It does not stringify or reformat the whole Markdown document. Tests cover preservation of LF, CRLF, BOM, final-newline state, trailing spaces, list markers, reference links, and paragraph wrapping outside expected splice ranges.

Formatter caveat: if an external formatter rewrites the file while Stet.md is open, Stet.md detects the file hash change and blocks save. Reload before saving staged comments. MVP intentionally has no force-save.

Backups are written before replacement:

.stet/
  .gitignore      # contains *
  backups/
  locks/

Security model

Stet.md is local-only and has no telemetry.

• Binds to 127.0.0.1 by default.
• Serves only the selected Markdown file and bundled UI assets.
• Uses an HttpOnly SameSite=Strict cookie token; missing/wrong tokens are rejected for API routes.
• Validates Host to reject DNS rebinding attempts.
• Sends Referrer-Policy: no-referrer.
• Sends restrictive CSP: self-only scripts/styles, self/data images, no objects/forms/framing.
• Escapes raw Markdown HTML by default.
• Blocks remote Markdown images/resources by default.

Development

Stet.md uses pnpm for repository development. Keep pnpm-lock.yaml as the only package-manager lockfile.

pnpm install
pnpm run typecheck
pnpm test
pnpm run test:packaging
pnpm run ci
pnpm run pack:dry

Test groups:

• tests/core/ parser, anchors, thread serialization, byte-splice writer.
• tests/server/ local server save/reopen/conflict flow.
• tests/security/ token, Host, CSP, no-referrer, remote-resource blocking.
• tests/browser/ browser UI smoke using a DOM-compatible runtime.
• tests/packaging/ package metadata and built CLI smoke.

Release gates

MVP release requires:

1. core parser/splice tests pass;
2. server, security, and browser smoke tests pass;
3. stet-md --version, stet-md --help, stet-md --print-agent-protocol, and stmd --help work;
4. README documents install, usage, storage, security, formatter caveats, and agent protocol;
5. release notes list MVP limitations;
6. dogfood run against the master PRD or a byte-identical copy.

MVP limitations

See docs/RELEASE_NOTES.md. Current MVP does not support list-item, table-row, or text-range comments.