@suzumiyaaoba/mdxr 0.15.0 → 0.17.0

package/README.md

@@ -1,7 +1,14 @@
-# mdxr
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-wordmark-dark.svg">
+    <img src="assets/logo-wordmark.svg" alt="mdxr" width="218" height="70">
+  </picture>
+</h1>
 
 Render agent-authored MDX documents (plans, reports) to standalone HTML with a semantic component catalog.
 
+[![Watch the mdxr launch video](assets/mdxr-launch-poster.jpg)](assets/mdxr-launch.mp4)
+
 ## Usage
 
 Run directly with `npx` — no install required:
@@ -11,6 +18,7 @@ npx @suzumiyaaoba/mdxr render plan.mdx     # writes plan.html
 npx @suzumiyaaoba/mdxr serve               # serve .mdxr at http://localhost:3737
 npx @suzumiyaaoba/mdxr library             # browse and search .mdxr
 npx @suzumiyaaoba/mdxr catalog             # list available components
+npx @suzumiyaaoba/mdxr check               # validate all documents in .mdxr
 npx @suzumiyaaoba/mdxr --version           # print the package version
 npx @suzumiyaaoba/mdxr init                # install mdxr instructions for Codex and Claude
 ```
@@ -22,6 +30,20 @@ npm install -g @suzumiyaaoba/mdxr          # global CLI
 npm install @suzumiyaaoba/mdxr             # library: import { render } from "@suzumiyaaoba/mdxr"
 ```
 
+### `mdxr check [path]`
+
+Validate one Markdown/MDX document or every document under a directory (defaults to `.mdxr`) without writing HTML. Checks include syntax, component names and attributes, local resources, Include cycles, citations, and cross references. Diagnostics include file, line, and column; errors exit with code 1, and checking continues after a malformed document.
+
+```sh
+mdxr check                           # validate .mdxr
+mdxr check ./reports --format json   # structured diagnostics for CI and agents
+mdxr check ./reports --strict        # fail on warnings too
+mdxr check plan.mdx --render          # also load project components and validate rendering
+cat plan.mdx | mdxr check -           # validate stdin
+```
+
+The default check does not execute document JavaScript, project configuration, or custom components. Use `--render` when checking trusted project components. See the [CLI reference](docs/docs/cli.mdx) for the diagnostic format and reference rules.
+
 ### `mdxr library [dir]`
 
 Browse and search Markdown and MDX documents under a directory (defaults to `.mdxr`). The local browser UI searches titles, document text, and relative paths; supports status filtering and relevance, update-date, or title sorting; and opens each result in a new tab with the live preview workspace.
@@ -62,6 +84,8 @@ cat plan.mdx | mdxr serve - --open                                 # explicit st
 
 `--open <file>` takes a document path relative to the working directory, or an absolute path. It opens that document directly, with its relative file path in the preview URL. `--agent codex` or `--agent claude` enables chat in every document workspace. A file argument such as `mdxr serve .mdxr/20260930170000-plan/index.mdx --open` serves the containing `.mdxr/` library and opens that file; outside `.mdxr/`, it serves the file's parent directory.
 
+After all browser tabs are closed, unused previews and their file watchers stop automatically after five minutes. Active agent turns keep their preview alive. `--idle-timeout <seconds>` changes this delay; `--idle-timeout 0` keeps the server running until you stop it. This also applies to `mdxr library`. Ctrl+C, SIGTERM, and SIGHUP close the library, its document previews, and agent connections.
+
 ### Review the rendered document
 
 Select text and click **Add comment**, or open **Annotate → Select figure** to comment on an image, diagram, or chart. Edit or delete comments in the panel, then **Copy Markdown** to send the quoted targets, source locations, and feedback to a coding agent.
@@ -70,7 +94,13 @@ Saved annotations remain in your browser for that document; they do not modify t
 
 Each document-level `##` section also has a **Not reviewed / Reviewed** toggle. Review status is saved locally per document and restored after reload; sections with changed content require review again. In **Pages** view, the sidebar shows section statuses and review progress. See [Section review status](https://suzumiyaaoba.com/mdxr/authoring#section-review-status).
 
-In the `mdxr serve` workspace, choose **Export HTML** to download one standalone review archive with the rendered document, chat, comments, section review statuses, every saved MDX version, and their diffs. Comment status, resolution time, revision, and reviewed version are included; links jump to matching versions in the archive. Images and stylesheets are embedded in the snapshot; if an external resource cannot be captured, export reports an error instead of omitting it. Open the file locally to review or share the captured state without running the server.
+In the `mdxr serve` workspace, choose **Export HTML**, select the contents, then **Download HTML**:
+
+- **Document only** preserves the displayed document and entered values, omitting review controls and records. It does not fetch chat or version history.
+- **Document and review** adds current comments, section review statuses, and answers. Chat, unsent drafts, comment handoff history, saved MDX versions, and diffs are excluded from both visible HTML and embedded JSON.
+- **All records** (the default) includes the document, chat, comments, drafts, section reviews, every saved MDX version, and their diffs. Resolved comments retain their resolution time and reviewed version, with links to matching archived versions.
+
+Images and stylesheets are embedded in every snapshot; if an external resource cannot be captured, export reports an error instead of omitting it. Open the file locally to review or share the captured state without running the server. Escape or **Cancel** closes the dialog without exporting.
 
 ### `mdxr text [file]`
 
@@ -136,6 +166,14 @@ Once the instructions or skill are installed, ask your agent, for example:
 
 Plans, reports, reviews, investigation summaries, release notes, and postmortems all work. By default, new documents use `.mdxr/yyyyMMddhhmmss-<name>/index.mdx`, with a zero-padded 14-digit local creation time in 24-hour format (for example, `.mdxr/20260929140530-auth-plan/index.mdx`). Keep images and related MDX files in the document's directory. A file path you provide takes priority, and existing documents keep their current paths. If you specify only a directory, create a timestamped subdirectory there and save the document as `index.mdx`. Serve the directory and open the new document directly with `mdxr serve .mdxr/ --open .mdxr/20260929140530-auth-plan/index.mdx`.
 
+## Document workflows
+
+Create editable MDX with `mdxr new --template plan|investigation|review --title "…"`; list or inspect templates with `mdxr templates [name]`. Generated files include a stable document ID and are never overwritten. `check`, `render` and `serve` discover ancestor configuration and accept `--config` / `--project`.
+
+Use `mdxr check .mdxr --watch`, `--format github` for CI annotations, or the typed Node.js API from `@suzumiyaaoba/mdxr/check`. Live workspaces show validation diagnostics and source locations even when rendering fails; the library lists static diagnostic counts.
+
+The Review dialog saves and imports versioned review JSON with conflict previews and explicit document mapping. Ask answers and Board placement survive reloads; stable widget IDs protect restoration after source edits. HTML exports can include nested related documents for offline reading. History records dependency hashes and reports changed or missing files; historical previews still use current dependency contents. See [Document workflows](https://suzumiyaaoba.com/mdxr/workflows) for examples and details.
+
 ## License
 
 MIT