diff --git a/README.md b/README.md index 60d8b8bc..19e23d64 100644 --- a/README.md +++ b/README.md @@ -14,15 +14,16 @@ For agents

-Markover is an **Early macOS preview** for reviewing Markdown as a document -tree and returning block-level feedback to an agent. +Markover is a macOS app for reviewing Markdown as a document tree and +returning block-level feedback to an agent. Instead of quoting fragments back +into chat, feedback stays attached to the blocks it concerns, and the agent +retrieves the whole review in a single structured handoff. -

- Markover showing a document inbox, structured Markdown, and an annotation with labeled screenshots. -

+Markover is in **early preview**. It is free and MIT-licensed, requires no +account, and keeps ordinary review data in your macOS account.

- Markover showing every rendered annotation in the active document. + Markover in Ember Light showing the review inbox, a launch brief in the center document tree, and an annotation with two labeled attachments.

## Features @@ -37,6 +38,14 @@ tree and returning block-level feedback to an agent. - One-shot agent handoff containing the exact source, checksum, document tree, annotations, attachments, and review context. +## Try it + +Ask your agent to open a Markdown document in Markover (the command it needs +is below), review the document, then tell the agent "Check Markover." To +review a document without an agent, choose **File → Open Markdown…** in the +app. The [user guide](https://lastobelus.github.io/markover/guide/) covers the +full workflow and keyboard controls. + ## Before you try the early preview - Markover supports macOS 14 Sonoma or newer on Apple Silicon Macs. Native @@ -46,7 +55,8 @@ tree and returning block-level feedback to an agent. notarized. macOS is expected to block the first launch. - Ordinary review work stays in your macOS account. Markover has no telemetry, analytics, cloud sync, or automatic review upload. -- Unreleased prototype formats may change directly. Released review schemas +- Data formats from unreleased prototype builds may change without migration + support. Released review schemas are converted automatically with an original backup; unknown future versions remain untouched until a compatible Markover release opens them. Back up important review data before changing versions. @@ -68,14 +78,16 @@ npx --yes \ --summary "Explain why this document exists and what feedback would help." ``` +The public npm package named `markover` is unrelated to this project. Use the +exact GitHub release-package URL above. + The command downloads the Apple Silicon app on first use. Native Intel releases -are deferred to the Broad announcement roadmap in -[issue #80](https://github.com/lastobelus/markover/issues/80). -Release launchers produced from the hardened preflight verify its checksum, -bundle identity, version, architecture, Sonoma floor, ad-hoc signature, and -code seal before moving it into the cache. Later commands reuse that validated -version. The launcher returns a review ID, status, and OS-openable custom URL, -then exits without waiting for the review: +are deferred; see [issue #80](https://github.com/lastobelus/markover/issues/80). +The launcher verifies the download's checksum, bundle identity, version, +architecture, minimum macOS version, ad-hoc signature, and code seal before +caching it. Later commands reuse that validated version. The launcher returns +a review ID, a status, and a `markover://` URL that macOS can open, then exits +without waiting for the review: ```json {"reviewId":"mko_8f3a2c","status":"editing","reviewUrl":"markover://review/mko_8f3a2c"} @@ -87,8 +99,8 @@ put the reliable Terminal fallback on its own line: `open 'markover://review/mko_8f3a2c'` -Custom-scheme Markdown links depend on the thread-host; T3 Code and the Codex app do not -currently dispatch them. Then stop. See the dedicated [agent +Some chat apps, including T3 Code and the Codex app, do not currently open +custom-scheme links from Markdown. Then stop. See the dedicated [agent workflow](https://lastobelus.github.io/markover/agents/) for retrieval, reopening, and interpretation guidance. @@ -130,4 +142,4 @@ operations. - [Discussions](https://github.com/lastobelus/markover/discussions) for early ideas, usage questions, and general support - [Report a problem](https://github.com/lastobelus/markover/issues/new?template=bug.yml) - with the smallest sanitized reproduction of a defect + with the smallest sanitized reproduction diff --git a/design/brand/markover-readme-leader.svg b/design/brand/markover-readme-leader.svg index f78a59e8..8bcb2aca 100644 --- a/design/brand/markover-readme-leader.svg +++ b/design/brand/markover-readme-leader.svg @@ -3,11 +3,11 @@ Structured review for Markdown.
Markover / visual assets pass
-

One identity, six contexts.

-

Usage mockups built from the final Affinity vectors. Public surfaces use the complete lockup; dense product navigation uses the mark and logotype as separate responsive pieces.

+

One identity, five contexts.

+

Current Ember Light usage built from the canonical vectors. Public surfaces use the complete lockup; dense product navigation uses the mark and logotype as separate responsive pieces.

#c94e1f#6d211f
@@ -203,8 +220,10 @@

Mark up the document. Hand back the decisions.

+
Markoverlaunch-readiness.md · Needs me
-
+
Documents
+
Document tree
Selected block
@@ -234,19 +253,11 @@

Mark up the document. Hand back the decisions.

-
A / mark + restrained logotype
+
Current / restrained identity with three-pane layout
-
Markover
visual-assets-pass.mdmko_8f3a2c · editing
-
Selected block
-
-
-
-
B / mark only
-
-
-
Markover
visual-assets-pass.mdmko_8f3a2c · editing
-
Selected block
+
Markover
launch-readiness.mdAtlas Studio · Needs me
+
Documents
Document tree
Selected block
diff --git a/doc/launch/issue-16/README.md b/doc/launch/issue-16/README.md new file mode 100644 index 00000000..91d6656a --- /dev/null +++ b/doc/launch/issue-16/README.md @@ -0,0 +1,80 @@ +# Public capture kit + +This directory defines the sanitized source material and recording contract for +Markover's focused-preview screenshots and demo. It supports roadmap issue #16 +without using a developer's real reviews, repositories, thread history, or +application state. + +## Prepare the capture instance + +Start from the exact clean commit that should appear in the capture receipt, +then run: + +```sh +npm run capture:stage +``` + +The command resets only its marked directory at +`/tmp/markover-public-capture`, creates five invented reviews across three +disposable Git repositories, applies Ember Light, builds an addressed Markover +bundle, and launches it with production branding. It uses the distinct +`markover-capture` scheme, suppresses protocol registration, and never reads or +writes canonical or development review state. + +Use `npm run capture:stage -- --prepare-only` when validating the fixture +without launching the app. The generated `session.json` records the exact +commit, fixture revision, theme, window size, and stable review IDs. + +## Capture stills + +The four replacement screenshots keep their existing names and Retina contract +so current README and Pages consumers do not need an asset migration. Arrange +these real UI states in the prepared app: + +1. `markover-review-editor@2x.png` — Inbox, Needs me, primary launch brief, + heading selected, feedback and both labeled attachments visible. +2. `markover-annotation-browser@2x.png` — Projects, All annotations, primary + launch brief with varied feedback and attachment context. +3. `markover-source-edit@2x.png` — primary opening paragraph selected, Source + expanded, word-level proposal visible. +4. `markover-review-context@2x.png` — primary review with Review context open, + showing only invented project, pull request, commit, and thread metadata. + +Each still is 2360×1520 at 144 dpi, captured from the app's 1180×760 logical +window at 2× scale. Keep notifications and unrelated application chrome out of +frame. + +## Record the demo + +Follow [demo-storyboard.md](demo-storyboard.md). Use `capture:cli` for every +agent-facing Markover command shown in the recording; it addresses only the +running capture service and refuses to start the canonical app implicitly. + +```sh +npm --silent run capture:cli -- get mko_capture01 \ + | jq -f doc/launch/issue-16/handoff-summary.jq +``` + +Export a silent, captioned H.264 MP4 at 1920×1080, 30 fps, 30–60 seconds, with +fast-start metadata. The capture PR records the final output path and checksums; +the later media PR owns the actual screenshot and movie binaries. + +## Safety checks + +Before publishing any visual: + +- confirm `session.json` names the intended clean commit; +- confirm Ember + Light and the 1180×760 logical window; +- scan every visible path, repository, pull request, review ID, thread ID, and + machine label against `capture-manifest.json`; +- inspect the four stills and every movie frame for notifications, private + paths, credentials, authorization material, or unrelated application chrome; +- run the deterministic checks documented by the media PR before upload. + +No canonical review, private path, real repository, real pull request, real +thread identity, credential, notification, unrelated application chrome, or +incidental audio may appear in any published still or recording. + +The marker file is the deletion boundary. The staging command refuses to +replace an unmarked directory, a symlink, or a fixture whose capture service is +still running. diff --git a/doc/launch/issue-16/capture-manifest.json b/doc/launch/issue-16/capture-manifest.json new file mode 100644 index 00000000..6f731814 --- /dev/null +++ b/doc/launch/issue-16/capture-manifest.json @@ -0,0 +1,104 @@ +{ + "format": "markover-public-capture", + "version": 1, + "stills": { + "command": "npm run capture:stills", + "sourceCommit": "b54b918fe7e6b0836afc80e98a8e9955cc68e9d3", + "sourceRef": "refs/tags/markover-media-stills-2026-08-31" + }, + "status": "captured", + "source": { + "redesignPullRequest": 195, + "designBrief": "doc/design/markover-design-brief.md", + "fixtureRevision": 1, + "captureCommit": "f93c68b22102f510760f49085465f64840d0ac81", + "captureRef": "refs/tags/markover-media-demo-2026-08-31" + }, + "staging": { + "command": "npm run capture:stage", + "stateRoot": "/tmp/markover-public-capture", + "appName": "Markover", + "scheme": "markover-capture", + "palette": "ember", + "appearance": "light", + "registersProtocol": false, + "usesNetworkContent": false + }, + "window": { + "logicalWidth": 1180, + "logicalHeight": 760, + "pixelWidth": 2360, + "pixelHeight": 1520, + "densityDpi": 144, + "scaleFactor": 2 + }, + "fixture": { + "projectRoot": "/tmp/markover-public-capture/projects", + "repositories": [ + "https://github.com/markover-demo/atlas-studio.git", + "https://github.com/markover-demo/field-research.git", + "https://github.com/markover-demo/review-protocol.git" + ], + "machine": "capture-mac", + "threadHost": "t3code", + "provider": "codex", + "notifications": "disabled" + }, + "screenshots": [ + { + "filename": "markover-review-editor@2x.png", + "sha256": "a312042e3d54def226a929e0fbfaf30b8b53a795eb0cb2b2196e4f2a6e2e9999", + "state": "inbox-needs-me-editor-with-two-labeled-attachments", + "consumers": ["README.md", "docs/user/index.html"] + }, + { + "filename": "markover-annotation-browser@2x.png", + "sha256": "4f4f5c7dc4e1c08db5744a29eef0563dd026cb7f9eb420ceb90d339c58917f4d", + "state": "projects-all-annotations-with-attachment-context", + "consumers": ["docs/user/index.html"] + }, + { + "filename": "markover-source-edit@2x.png", + "sha256": "71481cd78aaeda5a00f29e72ac3532efb1f41e4d9bf01137b60093e691518f43", + "state": "expanded-source-card-with-word-level-proposal", + "consumers": ["docs/user/index.html"] + }, + { + "filename": "markover-review-context@2x.png", + "sha256": "3fd1617c4aa07feb8b352b573bcb52c66dcfa56ef0b7f1329ec0d2c280d8a793", + "state": "review-context-with-sanitized-project-and-thread-metadata", + "consumers": ["docs/user/index.html"] + } + ], + "movie": { + "path": "docs/user/assets/markover-focused-preview-demo.mp4", + "sha256": "6b6db818391d526dcc22467923c35d29d1959e211d4facab89ec932127315197", + "poster": { + "path": "docs/user/assets/markover-demo-poster.jpg", + "sha256": "800d960723c05fe1ca0dcf3f07568fdec924e0fb91e2e88b653ec6b90e765d8a" + }, + "captionSource": "doc/launch/issue-16/demo-captions.srt", + "transcript": "doc/launch/issue-16/demo-transcript.md", + "minimumSeconds": 30, + "maximumSeconds": 60, + "durationSeconds": 44, + "width": 1920, + "height": 1080, + "framesPerSecond": 30, + "videoCodec": "h264", + "audio": false, + "fastStart": true, + "captions": "burned-in", + "inspectedCheckpointsSeconds": [0.5, 6.5, 14.5, 23.5, 31.5, 39.5, 43] + }, + "privacy": { + "allowOnlyInventedFixtureData": true, + "forbiddenContent": [ + "real home-directory paths", + "real repositories or pull requests", + "real review or thread identifiers", + "credentials or authorization material", + "notifications or unrelated application chrome" + ] + } +} diff --git a/doc/launch/issue-16/demo-captions.srt b/doc/launch/issue-16/demo-captions.srt new file mode 100644 index 00000000..1cc3cb4f --- /dev/null +++ b/doc/launch/issue-16/demo-captions.srt @@ -0,0 +1,27 @@ +1 +00:00:00,000 --> 00:00:01,000 +Open one review from the inbox. + +2 +00:00:01,000 --> 00:00:07,000 +Review agent-written Markdown as a document tree. + +3 +00:00:07,000 --> 00:00:15,000 +Attach labeled visual context to one exact block. + +4 +00:00:15,000 --> 00:00:25,000 +Propose an exact edit without changing the source document. + +5 +00:00:25,000 --> 00:00:32,000 +Scan the complete review before handing it back. + +6 +00:00:32,000 --> 00:00:40,000 +Agent retrieves one structured handoff. + +7 +00:00:40,000 --> 00:00:44,000 +Markover — Free, MIT-licensed macOS early preview. diff --git a/doc/launch/issue-16/demo-storyboard.md b/doc/launch/issue-16/demo-storyboard.md new file mode 100644 index 00000000..ccc042a0 --- /dev/null +++ b/doc/launch/issue-16/demo-storyboard.md @@ -0,0 +1,73 @@ +# Markover focused-preview demo storyboard + +## Recording setup + +- Prepare the exact clean capture commit with `npm run capture:stage`. +- Record only the sanitized capture instance and a clean terminal at 1920×1080, + 30 fps. +- Keep Ember Light selected, notifications off, and all unrelated application + chrome out of frame. +- Export a silent H.264 MP4 between 30 and 60 seconds with burned-in captions + and fast-start metadata. +- Use calm, descriptive language. Do not imply release guarantees or platform + support beyond the current repository documentation. + +## Timeline + +### 0:00–0:07 — Open one review from the inbox + +Show the prepared Inbox with **Needs me** active, then open **Launch readiness +brief** from its review row. Let the Ember Light Pane layout establish +the selected document block and feedback pane. + +Captions: **Open one review from the inbox.** then **Review agent-written +Markdown as a document tree.** + +### 0:07–0:15 — Inspect feedback with visual context + +Select the heading and reveal its feedback with the two fixture-owned images, +**workflow overview** and **annotation details**. Keep their rewritten Markdown +references visible long enough to read. + +Caption: **Attach labeled screenshots to a single block.** + +### 0:15–0:25 — Inspect an exact source change + +Select the opening paragraph and expand Source. Show the existing proposal that +narrows the rollout from everyone to the design-partner group. Hold on the real +word-level diff. + +Caption: **Propose an exact edit without changing the source document.** + +### 0:25–0:32 — Review every annotation together + +Switch to Projects and then **All annotations**. Briefly show the four varied +annotations and their block context in the redesigned browser. + +Caption: **Scan the complete review before handing it back.** + +### 0:32–0:40 — Retrieve one structured handoff + +Return to the terminal and run: + +```sh +npm --silent run capture:cli -- get mko_capture01 \ + | jq -f doc/launch/issue-16/handoff-summary.jq +``` + +Show the projected status, feedback, attachment IDs and labels, and source +proposal. The capture CLI addresses only the fixture service and does not start +or inspect canonical Markover state. + +Caption: **Return one structured handoff to the agent.** + +### 0:40–0:44 — End card + +Show the Markover lockup, **Structured review for Markdown**, **Free, +MIT-licensed macOS early preview**, and `github.com/lastobelus/markover`. + +## Pages transcript + +Pages uses the text of [demo-transcript.md](demo-transcript.md) verbatim. Do +not maintain a separate transcript here; update that file and sync the site's +inline copy when the demo is re-exported. diff --git a/doc/launch/issue-16/demo-transcript.md b/doc/launch/issue-16/demo-transcript.md new file mode 100644 index 00000000..2102780a --- /dev/null +++ b/doc/launch/issue-16/demo-transcript.md @@ -0,0 +1,32 @@ +# Markover focused-preview demo transcript + +This file is the canonical transcript. The inline transcript on the Pages demo +section must match the text between the markers below; update both together +when the demo changes. + + + +The 44-second silent demo uses burned-in captions and only invented fixture data. + +Markover starts with a sanitized participant guide, then opens the +launch-readiness review from the **Needs me** inbox. The current Ember Light +App header and Pane layout with Left, Center, and Right panes establish the +review. The reviewer sees agent-written Markdown as a document tree with +feedback and two labeled images attached to one heading. + +On the opening paragraph, Markover displays an exact word-level source proposal +without changing the source document. The reviewer switches to **Projects** and +**All annotations** to scan the complete review. + +Finally, the CLI (running against demo fixture data) returns structured JSON +containing the review status, block feedback, attachment IDs and labels, and +source proposal. The demo ends on the Markover lockup, “Structured review for +Markdown,” and the repository address. + + + +The end card also states the free, MIT-licensed macOS early-preview boundary. + +No canonical review, private path, real repository, real pull request, real +thread identity, credential, notification, unrelated application chrome, or +incidental audio appears in the recording. diff --git a/doc/launch/issue-16/focused-preview-copy.md b/doc/launch/issue-16/focused-preview-copy.md new file mode 100644 index 00000000..d91ee62d --- /dev/null +++ b/doc/launch/issue-16/focused-preview-copy.md @@ -0,0 +1,46 @@ +# Focused-preview launch copy + +These are staging drafts, not published announcements. Issue #17 owns the +audience choice, final release facts, publication timing, and feedback triage. +Each draft keeps the same verified product boundary but asks its audience a +different useful question. + +## Coding-agent community + +I’m preparing an early macOS preview of Markover, a free, MIT-licensed app +for reviewing agent-written Markdown block by block. It needs no account, and +ordinary review data stays in your macOS account. I’m looking for Codex and +coding-agent users willing to test one real document review and report where the +open → annotate → structured handoff loop breaks down. Apple Silicon +macOS 14+ only for this preview. [Watch the 44-second +workflow](https://lastobelus.github.io/markover/#demo). + +## Design-partner invitation + +Could you try one document you already ask an agent to write, then review it +in Markover instead of flattening feedback into chat? The early macOS preview +is free, MIT licensed, requires no account, and keeps ordinary review data in +your macOS account. I most need the exact moment the workflow becomes slower or +less clear than your current +process, plus any feedback the agent misinterprets after retrieval. Apple +Silicon macOS 14+ only. [Setup and limitations](https://lastobelus.github.io/markover/guide/). + +## GitHub repository summary + +Markover is a macOS app for reviewing agent-produced Markdown and returning +structured, block-level feedback to the agent thread. The early preview is +free and MIT licensed, requires no account, keeps ordinary review data in your +macOS account, and currently supports Apple Silicon macOS 14+. Start with the +[current UI and +44-second demo](https://lastobelus.github.io/markover/#demo), then report +concrete workflow failures in [Discussions](https://github.com/lastobelus/markover/discussions). + +One-line variant for the repository About field, which does not render +Markdown links and truncates long descriptions: + +> macOS app for reviewing agent-written Markdown block by block and returning +> structured feedback to the agent. Early preview; Apple Silicon, macOS 14+. + +Before publishing any draft, issue #17 must replace staging language with the +verified release tag, previous known-good release, rollback threshold, support +window, and chosen community’s native format. diff --git a/doc/launch/issue-16/github-social-preview.svg b/doc/launch/issue-16/github-social-preview.svg new file mode 100644 index 00000000..3f99d5f3 --- /dev/null +++ b/doc/launch/issue-16/github-social-preview.svg @@ -0,0 +1,11 @@ + + + Markover — Structured review for Markdown + Ember Light repository preview for Markover. + + + + Structured review for Markdown. + Local-first · macOS · early preview + + diff --git a/doc/launch/issue-16/handoff-summary.jq b/doc/launch/issue-16/handoff-summary.jq new file mode 100644 index 00000000..b9200472 --- /dev/null +++ b/doc/launch/issue-16/handoff-summary.jq @@ -0,0 +1,32 @@ +def reviewed_blocks: + [ + .. + | objects + | select((.id? // "") | startswith("block-")) + | select( + ((.feedback? // "") | length) > 0 + or (.sourceEdit? != null) + ) + | { id } + + (if ((.feedback? // "") | length) > 0 + then { feedback } + else {} + end) + + (if ((.attachments? // []) | length) > 0 + then { + attachments: [ + .attachments[] | { id, label } + ] + } + else {} + end) + + (if .sourceEdit? != null + then { sourceEdit } + else {} + end) + ]; + +{ + review: { status: .review.status }, + blocks: reviewed_blocks +} diff --git a/doc/launch/issue-16/launch-brief.md b/doc/launch/issue-16/launch-brief.md new file mode 100644 index 00000000..bd044a5a --- /dev/null +++ b/doc/launch/issue-16/launch-brief.md @@ -0,0 +1,25 @@ +# Launch readiness brief + +Ship the review pilot to everyone as soon as the first workflow is complete. + +## Success criteria + +- Every handoff names an owner and next action. +- Review feedback stays attached to the relevant Markdown block. +- Source proposals remain explicit and reversible. +- Attachments use clear labels. +- The pilot expands only after the loop is reliable. + +## Rollout plan + +Start with the design-partner group, observe three complete review loops, and +record blocked or deferred work before expanding. + +| Signal | Ready when | +| --- | --- | +| Ownership | Every note has a named owner | +| Reliability | Three handoffs complete without recovery | + +```ts +await openReview({ retry: true }) +``` diff --git a/doc/launch/issue-16/launch-manifest.json b/doc/launch/issue-16/launch-manifest.json new file mode 100644 index 00000000..0ff502e4 --- /dev/null +++ b/doc/launch/issue-16/launch-manifest.json @@ -0,0 +1,61 @@ +{ + "format": "markover-preview-launch", + "version": 1, + "desiredRepositoryMetadata": { + "description": "Local-first macOS app for reviewing agent-produced Markdown and returning structured, block-level feedback to the agent thread.", + "homepage": "https://lastobelus.github.io/markover/", + "topics": [ + "markdown", + "document-review", + "annotations", + "ai-agents", + "coding-agents", + "codex", + "local-first", + "macos", + "electron", + "developer-tools" + ], + "socialPreview": "docs/user/assets/markover-github-social-preview.png", + "profilePins": [ + "lastobelus/markover", + "lastobelus/lastCode" + ] + }, + "assets": { + "strongestScreenshot": "docs/user/assets/markover-review-editor@2x.png", + "demo": { + "path": "docs/user/assets/markover-focused-preview-demo.mp4", + "sha256": "6b6db818391d526dcc22467923c35d29d1959e211d4facab89ec932127315197" + }, + "poster": { + "path": "docs/user/assets/markover-demo-poster.jpg", + "sha256": "800d960723c05fe1ca0dcf3f07568fdec924e0fb91e2e88b653ec6b90e765d8a" + }, + "githubSocialPreview": { + "path": "docs/user/assets/markover-github-social-preview.png", + "sha256": "ff34c863c45af754c59050b4999372468a82258ca080ca841efda8421f168757" + }, + "pagesSocialCard": { + "path": "docs/user/assets/markover-pages-social-card.png", + "sha256": "2bc498658310cd16609916f8b09047fa2515ea254d911d273bf21253cc337779" + }, + "transcript": "doc/launch/issue-16/demo-transcript.md", + "captions": "doc/launch/issue-16/demo-captions.srt", + "tailoredCopy": "doc/launch/issue-16/focused-preview-copy.md" + }, + "liveVerification": { + "repositoryMetadataApplied": true, + "socialPreviewApplied": false, + "profilePinsApplied": false, + "pagesDeploymentVerified": false + }, + "outstanding": { + "socialPreview": "Upload the prepared PNG in an owner-authenticated GitHub repository settings session.", + "profilePins": "Confirm the maintainer-profile change before pinning Markover and lastCode.", + "pagesDeployment": "Verify the canonical URLs, sharing card, demo playback, and narrow layout after the stack reaches main." + }, + "focusedPreviewTag": null, + "releaseBlockers": [10, 11], + "announcementOwner": 17 +} diff --git a/doc/launch/issue-16/pages-social-card.svg b/doc/launch/issue-16/pages-social-card.svg new file mode 100644 index 00000000..e75dcede --- /dev/null +++ b/doc/launch/issue-16/pages-social-card.svg @@ -0,0 +1,13 @@ + + + Markover — Structured review for Markdown + Ember Light sharing card for the Markover website. + + + + Structured review for Markdown. + Precise feedback for agent-written documents + + + + diff --git a/doc/plans/2026-08-28__ember-light-public-visual-refresh-eli5.html b/doc/plans/2026-08-28__ember-light-public-visual-refresh-eli5.html new file mode 100644 index 00000000..59ff13bc --- /dev/null +++ b/doc/plans/2026-08-28__ember-light-public-visual-refresh-eli5.html @@ -0,0 +1,261 @@ + + + + + + Ember Light public visual refresh + + + +
+

Proposed stack after PR #195

+

Make every public picture look like the product again.

+

Markover's application has a new Ember Light interface, but the website, README, screenshots, banner, and launch assets still show the old one. This plan updates the sources first, captures the real app second, and publishes only after everything agrees.

+ +
+ Where this is true Proposed · August 28, 2026 +
+

This page explains the draft umbrella plan based on merged PR #195, open roadmap issue #16, and the stale preparation in PR #51. The exact stack may be refined in review, but its stable boundary is public visuals and reproducible media capture—not application behavior or announcement operations.

+
+
+ +
+

The tiny story

+
+
+ 01 · NOW +

The app moved on

+

The real product has a shorter header, left-side review navigation, three panes, and updated Ember Light surfaces.

+
+
+ 02 · GAP +

The public story did not

+

Four screenshots, the Pages mockup, README leader, and GitHub preview still describe the retired interface. No demo exists.

+
+
+ 03 · FIX +

One staged source, many truthful outputs

+

A current design brief defines the Ember roles; a sanitized real-app fixture then feeds truthful Pages, README, screenshots, social cards, and a short movie.

+
+
+
+ +
+

How the pull requests fit

+
+ + Four child pull requests feed one umbrella pull request + Capture foundation comes first, followed by the public Ember Light theme, current screenshots, then the demo and live launch assets. All merge into the umbrella before the umbrella merges to main. + + + + + + + + SLICE 1 + Capture foundation + + SLICE 2 + Public theme + + SLICE 3 + Screenshots + + SLICE 4 + Demo + launch + + + + + + UMBRELLA PR + Aggregate review, then merge to main + + +

Each child is independently reviewable. Later media depends on the visual and staging decisions below it, so the stack stays linear.

+
+
+ +
+

What each slice contributes

+
+
+ FOUNDATION +

Safe, repeatable staging

+
    +
  • One current design brief for product, public media, and diagrams.
    • +
  • Disposable state—never the user's real reviews.
    • +
  • Invented projects, paths, thread IDs, attachments, and Git metadata.
    • +
  • Production branding with no development badge.
    • +
  • Exact commit, window, theme, and output manifest.
    • +
+
+
+ THEME +

One Ember Light language

+
    +
  • SF/system typography and current ground, paper, and quiet panes.
    • +
  • A responsive three-pane HTML hero—not a fake raster.
    • +
  • Updated README leader, social cards, and undated brand references.
    • +
+
+
+ STILLS +

Four real application states

+
    +
  • Editor with labeled attachments.
    • +
  • All annotations in Projects navigation.
    • +
  • Exact source proposal diff.
    • +
  • Sanitized review context.
    • +
+
+
+ MOTION +

One complete review loop

+
    +
  • 30–60 seconds, silent, captioned, 1080p H.264.
    • +
  • Open, annotate, show attachment, propose edit, retrieve handoff.
    • +
  • Pages embed and transcript; README poster link.
    • +
  • Verified GitHub description, homepage, topics, card, and pins.
    • +
+
+
+
+ +
+

The capture matrix

+
+ + + + + + + + +
Stable assetWhat the current image must prove
review-editor@2xInbox and Needs me, current header and three panes, selected block, feedback, and labeled attachments.
annotation-browser@2xProjects navigation and a useful set of rendered annotations in the current right pane.
source-edit@2xThe current Source card and stacked word-level proposal without altering the review target.
review-context@2xThe current context surface with safe review, repository, pull-request, and agent metadata.
+
+
+ +
+

How we know it is real

+
+
+

Machines verify

+

Dimensions, density, hashes, asset references, social-card size, video codec/frame rate/duration/fast-start, documentation tests, local CI, and clean diffs.

+
+
+

People verify

+

Current #195 chrome, Ember Light fidelity, legibility, private-data absence, video pacing, README light/dark rendering, Pages desktop/narrow layouts, and live GitHub previews.

+
+
+
+ +
+

What stays outside

+
+
    +
  • No product behavior changes just to improve a capture.
    • +
  • No screenshot service, recording daemon, generic fixture framework, or compatibility path.
    • +
  • No real review data, private metadata, or AI-edited application pixels.
    • +
  • No rewriting clearly dated historical design artifacts.
    • +
  • No announcement posting or feedback operation; those remain with issues #17 and #18.
    • +
  • No early closure of issue #84's late human editorial pass.
    • +
+
+
+ +
+

Roadmap handoff

+
+

#16 comes in

The umbrella owns the public visual assets, demo, README examples, social cards, and verified repository metadata.

+

#51 is superseded

Its useful generator, manifest, storyboard, and transcript ideas are rebuilt on current main; its old UI outputs are discarded.

+

#84 stays late

This stack gives the later editorial pass current screenshots, links, commands, and responsive layouts without pretending post-preview feedback already happened.

+

#17 and #18 stay downstream

They consume the finished kit for announcement operations. They do not own the asset implementation.

+
+
+ +
+

Canonical plan: doc/plans/2026-08-28__ember-light-public-visual-refresh.md

+

Current visual brief: doc/design/markover-design-brief.md

+
+ Prompt/context Why this page exists +
+

The user asked to update GitHub Pages, README, banner, screenshots, movies, and other visual roadmap work after #195, using an umbrella PR, subagents, stacked PRs, and computer control. Repository and GitHub inventory found four stale screenshots, no movie, no reproducible capture state, issue #16 as the direct roadmap owner, issue #84 as a late editorial dependency, and PR #51 as stale preparation to salvage.

+
+
+
+
+ + diff --git a/doc/plans/2026-08-28__ember-light-public-visual-refresh.md b/doc/plans/2026-08-28__ember-light-public-visual-refresh.md new file mode 100644 index 00000000..7f962707 --- /dev/null +++ b/doc/plans/2026-08-28__ember-light-public-visual-refresh.md @@ -0,0 +1,326 @@ +# Ember Light public visual refresh + +## Status and truth context + +This is the implementation plan for the public visual refresh requested after +[PR #195](https://github.com/lastobelus/markover/pull/195), which merged the +current Markover application redesign on August 28, 2026. The plan coordinates +one umbrella pull request and a short stack of independently reviewable child +pull requests. + +The work directly takes over the visual and media portions of +[issue #16](https://github.com/lastobelus/markover/issues/16). It supersedes the +conflicted, pre-redesign draft [PR #51](https://github.com/lastobelus/markover/pull/51) +while preserving that draft's useful launch manifest, social-card generator, +storyboard, transcript, and validation ideas. + +[Issue #84](https://github.com/lastobelus/markover/issues/84) remains a late +Broad-announcement editorial pass. This stack will refresh its screenshot, +link, command, and responsive-layout prerequisites, but will not claim that the +post-feedback human editorial review has happened. + +## Outcome + +Every current public or undated visual representation of Markover matches the +application delivered by #195 and presents the Ember Light theme consistently. +The repository gains a reproducible, privacy-safe way to stage the app for +media capture, four current product screenshots, one 30–60 second product demo, +updated GitHub Pages and README presentation, and a verified set of repository +metadata and social-preview assets. + +The work is complete when a prospective user sees the same product structure, +theme, and workflow in the README, Pages site, screenshots, demo, social cards, +and live GitHub repository metadata. + +## Current gap + +- The four tracked product screenshots are unchanged since August 2. They show + the retired document-tab strip, visible checksum, old header geometry, old + review navigation, and pre-#195 pane colors. +- The README embeds the first two stale screenshots. The Pages gallery embeds + all four. +- The Pages site still uses the older public warm palette and Inter typography, + and its hand-built hero mock shows the old two-pane product structure. +- `design/brand/markover-readme-leader.svg` still uses the older muted ink and + typography stack. +- The repository has no tracked movie, no media-capture fixture, and no + repeatable staging workflow. +- GitHub currently has no homepage or topics and uses a generic social card. +- Draft PR #51 contains useful launch preparation, but it predates #195 and + conflicts with current `main`. + +## Public visual contract + +`doc/design/markover-design-brief.md` is the canonical current visual brief for +this stack and later product-facing material. The dated August 1 brand brief +remains historical. The public visual system follows the current Ember Light +application rather than inventing a separate marketing palette: + +| Role | Current Ember Light value or source | +| --- | --- | +| Typography | SF/system stack used by the app | +| App shell / page ground | `#e8e2d8` | +| Document paper | `#f7f4ee` | +| Quiet pane surface | `#ece9e2` | +| Primary text | `#26211e` | +| Muted text | `#6f6761` | +| Primary brand | `#c94e1f` | +| Secondary brand | `#6d211f` | +| Code surface | `#262b2b` | + +The Pages site may map these roles to web-specific component tokens, but the +rendered hierarchy must remain recognizably the same: App header above a +three-pane layout, neutral left and right panes around a paper center pane, +restrained Ember accents, and the current typography and spacing character. + +Merged PR #209 establishes that canonical brief, routes relevant agent work to +it from `AGENTS.md`, and provides Markover's repository-owned Diagram Design +profile. ELI5 threads use that profile without a setup wizard, consult the +optional shared skill for diagram grammar when it is available, and fall back +quietly when it is not. This umbrella consumes that foundation without copying +or depending on a machine-local profile. + +## Delivery shape + +The umbrella pull request remains a draft coordination and aggregate-review +surface until the child stack lands into it. Each child is reviewed against the +branch immediately below it; after a child merges downward, the next child is +retargeted to the umbrella branch. The completed umbrella is merged to `main` +last. + +| Order | Pull request | Base branch | Purpose | +| --- | --- | --- | --- | +| 0 | Umbrella PR | `main` | This plan, inventory, capture contract, child checklist, and aggregate review | +| 1 | Capture foundation | umbrella branch | Sanitized fixture, public-brand isolated staging, manifest/storyboard salvage, and deterministic media checks | +| 2 | Ember Light public theme | capture-foundation branch | Pages theme, three-pane hero mock, README leader/banner, current brand board, social-card sources, and tests | +| 3 | Current screenshots | public-theme branch | Four computer-captured Retina screenshots and updated README/gallery descriptions | +| 4 | Demo and launch assets | screenshot branch | 30–60 second movie, poster, transcript, Pages embed, README link, final social cards, and live repository metadata checklist | + +This is a real stack because each later slice consumes visual decisions or +capture state established below it. Work that does not depend on this stack +stays in an ordinary pull request. + +## Slice 1 — Capture foundation + +### Goal + +One command creates a disposable, sanitized, public-branded Markover state that +can be driven through the real UI without touching canonical reviews or showing +development badges. + +### Work + +- Salvage the useful fixture, launch manifest, storyboard, transcript, filtered + handoff, social-card generation, and validation concepts from PR #51. Rebuild + them on current `main`; do not rebase the stale PR wholesale. +- Add the smallest capture-only staging script needed to create a disposable + state root, seed representative reviews and metadata, launch the built app + with public branding, and suppress protocol-registration side effects. +- Keep staging deterministic and sanitized: invented project, repository, + branch, pull-request, thread, review, document, attachment, and path values; + no user review history, home-directory paths, real thread IDs, notifications, + or network-fetched content. +- Record the exact app commit, fixture revision, window size, theme, appearance, + and asset outputs in a versioned capture manifest. +- Keep computer use responsible for arranging final UI states and taking the + captures. The fixture prepares truth; it does not fake rendered screenshots. + +### Done when + +- A fresh run produces the same representative review set in isolated storage. +- The launched window uses production branding and current product behavior. +- Canonical and development-instance review stores remain untouched. +- A maintainer can reset and recreate the capture state without manual data + entry. +- Focused tests cover fixture sanitization, launch isolation, and manifest + validity. + +## Slice 2 — Ember Light public theme + +### Goal + +The public site, README leader, social cards, and undated brand references use +the visual language of #195 before current product media is dropped into them. + +### Work + +- Update `docs/user/styles.css` and every repeated public `theme-color` value to + the Ember Light role mapping. +- Rebuild the landing-page hero mock as the current App header plus Left, + Center, and Right panes. Preserve it as responsive HTML/CSS rather than a + baked image. +- Update the README leader/banner typography and muted color while preserving + the canonical mark and logotype geometry. +- Rebuild the GitHub 1280×640 social preview and Pages 1200×630 Open Graph card + from deterministic, editable sources. +- Add complete Open Graph and large-card metadata to every public page that + needs a share preview. +- Refresh the undated brand usage board and the reachable static inbox visual + fixture where they claim to show the current product. Keep dated design + explorations as historical records. +- Update useful semantic tests without locking the site to incidental prose. + +### Done when + +- The Pages home and documentation layouts are coherent at desktop and narrow + widths and visibly match Ember Light. +- The hero depicts the current three-pane structure and no retired tab strip or + checksum. +- Banner and social-card sources and exports pass dimension, size, reference, + and hash checks. +- Current undated visual references no longer depict the retired application. + +## Slice 3 — Current screenshots + +### Goal + +Replace the four stale product screenshots with real current-app captures while +preserving their useful semantic coverage and stable consumer paths. + +### Capture protocol + +Before launching or focusing Markover, read the machine interaction policy. +Run the isolated capture state from the exact committed foundation, choose +Ember + Light explicitly, use an 1180×760 point window on a Retina display, and +capture 2360×1520 RGB PNGs with 144-dpi metadata. Disable notifications and +inspect every frame for private or accidental content. + +Use computer control to stage each state in the current UI, then use native +screen capture. Do not composite, regenerate, or AI-edit product UI pixels. + +### Capture matrix + +| Existing filename | State to capture | +| --- | --- | +| `markover-review-editor@2x.png` | Inbox, Needs me, several project/review rows, selected heading, populated feedback, and two labeled attachments; canonical strongest image | +| `markover-annotation-browser@2x.png` | Projects navigation, All annotations, and several varied rendered annotations with attachment context | +| `markover-source-edit@2x.png` | Selected paragraph, expanded Source card, and the current stacked word-level source proposal | +| `markover-review-context@2x.png` | Current Review context surface with sanitized review, Git, pull-request, and agent/thread metadata | + +### Done when + +- All four files come from the recorded current commit and show #195's App + header and three-pane structure in Ember Light. +- Filenames, 2360×1520 dimensions, and 144-dpi density remain stable unless + visual review proves a contract change is worthwhile. +- README and gallery alternative text and captions describe what is actually + visible. +- The canonical screenshot appears once in the README; the gallery retains all + four states. +- Human QA confirms visual fidelity, legibility, privacy, cropping, and absence + of development-only UI. + +## Slice 4 — Demo and launch assets + +### Goal + +Show the real end-to-end review loop in one concise movie and finish issue +#16's current visual and repository-metadata deliverables. + +### Movie + +Record a silent 30–60 second, 1920×1080, 30 fps H.264 MP4 with fast-start +metadata, burned-in captions, deliberate cursor movement, and no private +content. Use the staged fixture and one review ID throughout: + +1. An agent opens a Markdown brief and stops. +2. The reviewer selects a block, writes precise feedback, and shows a labeled + screenshot attachment. +3. The reviewer proposes an exact source edit and shows the word-level diff. +4. The reviewer checks All annotations. +5. The agent retrieves the structured handoff using the retained review ID. +6. A short end card identifies the free MIT-licensed macOS early preview and + repository URL. + +Commit the optimized MP4, poster, transcript, captions, fixture document, and +filtered handoff example. Keep recording masters and editor projects outside +the repository. The Pages site embeds the movie with visible controls, +`preload="metadata"`, no autoplay, a poster, and a text transcript. The README +links its poster to the hosted demo rather than embedding a large animation. + +### Live repository metadata + +After the matching default-branch assets and Pages deployment are live, use +browser/computer control to apply and verify: + +- repository description; +- Pages homepage URL; +- selected topics; +- custom GitHub social preview; +- maintainer profile pin order. + +Record the intended and observed values in the launch manifest. External +metadata is not considered complete merely because a source asset exists in +the repository. + +### Done when + +- `ffprobe` confirms H.264, 1920×1080, 30 fps, 30–60 seconds, no audio, and + fast-start playback. +- Pages desktop and narrow layouts expose usable video controls, poster, + transcript, gallery, and share metadata. +- README light and dark GitHub rendering is legible and uses the strongest + current image consistently. +- The deployed Pages URL, repository settings, social preview, and profile pins + match the manifest. +- Issue #16 has closure evidence for every acceptance criterion that this stack + owns. Posting and operating the announcement remain with issue #17. + +## Roadmap integration + +| Item | Treatment | +| --- | --- | +| #16 | Directly owned by this umbrella; close only after final assets and live metadata are verified | +| #51 | Superseded after the umbrella exists; salvage selected preparation rather than stale UI outputs | +| #84 | Keep open; this stack supplies current screenshots, commands, links, and responsive visual prerequisites for its later human editorial pass | +| #5 | Parent launch gate; update with #16 progress but do not close from this work | +| #17 | Downstream focused-preview posting and feedback operation; consumes assets but stays out of scope | +| #18 | Downstream broad-announcement work; stays out of scope | +| #13 and #80 | Preserve truthful signing/notarization and Intel-support boundaries in refreshed copy; do not absorb implementation | +| #181 | Product modal redesign remains separate unless a selected public capture later requires that modal | +| #209 | Merged prerequisite that owns the canonical design brief and repository-owned Diagram Design onboarding; this umbrella consumes it without duplicating its edits | + +No other open roadmap issue directly owns screenshots, movies, banners, +branding, GitHub Pages presentation, tutorials, or onboarding. + +## Verification + +Every child PR runs the narrow checks for its surface plus `git diff --check`. +Before the umbrella merges: + +- run `npm run ci:local` on the aggregate head; +- verify the ELI5 and documentation site build; +- verify all local links and asset references; +- inspect screenshot dimensions, density, and privacy; +- inspect social-card dimensions, hashes, and GitHub's under-1-MB limit; +- inspect movie codec, dimensions, frame rate, duration, audio absence, and + fast-start metadata; +- use the collaborative browser to check Pages at desktop and narrow widths; +- use native computer control for the current Markover capture states; +- perform human QA of README light/dark rendering, Pages presentation, all + captures, movie pacing/captions, and live external metadata. + +The final media is pinned to the recorded app commit. A later UI change makes +recapture a new decision rather than silently invalidating this stack's finite +completion evidence. + +## Boundaries + +- Do not change application behavior merely to make a prettier capture. +- Do not add a general fixture framework, screenshot service, recording daemon, + background process, or compatibility path. +- Do not touch canonical review data or capture real private metadata. +- Do not use AI-generated or edited pixels as evidence of the application UI. +- Do not rewrite dated historical design artifacts that are clearly labelled + by date and no longer claim to be current. +- Do not publish announcement posts or operate their feedback rounds. +- Do not claim #84 complete before its late, post-feedback human editorial pass. +- Do not fold #181 or unrelated product UI refinements into public-collateral + work. + +## Completion + +The umbrella PR can leave draft status only when all four child slices have +landed into it, aggregate validation passes, current media has accepted human +QA, issue #16's live repository settings are verified, and every remaining +roadmap item above has an explicit handoff rather than an implied closure. diff --git a/docs/user/agents/index.html b/docs/user/agents/index.html index d2b295bb..0285f2b8 100644 --- a/docs/user/agents/index.html +++ b/docs/user/agents/index.html @@ -3,9 +3,44 @@ - + + For agents — Markover documentation + + + + + + + + + + + + + + + + @@ -21,6 +56,7 @@

Agents

Agent workflow Open a review + Identity examples Wait for the reviewer Retrieve the handoff Validate the format @@ -37,11 +73,27 @@ Repository agent guidance Source +
+ + +
View source on GitHub ↗
Markover docs +
+ + +
User guide
@@ -52,19 +104,50 @@

Review a Markdown document with Markover

Open one review

-

Run markover help before a pull-request-associated open, get, get-for-review, revise, or done. Its machine-readable pullRequestStatus contract is the source of truth for the live GitHub lookup, status mapping, flags, and lookup-failure behavior.

-

Give Markover one Markdown path and a short summary of why the document exists and what feedback would help:

+

Give Markover a Markdown path and a short summary of why the document exists and what feedback would help:

+
Pull-request-associated commands. Before an open, get, get-for-review, revise, or done that involves a pull request, run markover help. Its machine-readable pullRequestStatus contract defines the live GitHub lookup, status mapping, flags, and lookup-failure behavior.
npx --yes \
   --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
   markover open ./DOCUMENT.md \
   --summary "Review these decisions before implementation."
-

When reliable thread metadata is available, pass the best observable requesting-thread or session ID with --thread-id. Use --thread-host-kind for the user-facing product or lookup namespace where the user would look for the thread, and --thread-host-provider for the LLM provider or model family in use rather than an intermediate harness. Pass --thread-host-thread-id only for a distinct host-owned identifier. Try the local hostname command and pass its result as --thread-host-machine. Use recommended product values when they match observable facts, preserve truthful unknown values, and omit anything unavailable rather than guessing.

-

On first use, the launcher downloads the Apple Silicon app; verifies its checksum, bundle identity, version, architecture, Sonoma floor, ad-hoc signature, and code seal; then atomically caches it. A successful command exits promptly with one JSON value:

+

When reliable thread metadata is available:

+ +

On first use, the launcher downloads the Apple Silicon app; verifies its checksum, bundle identity, version, architecture, minimum macOS version, ad-hoc signature, and code seal; then atomically caches it. A successful command exits promptly with one JSON value:

{"reviewId":"mko_8f3a2c","status":"editing","reviewUrl":"markover://review/mko_8f3a2c"}
Retain the review ID. It is the stable identifier for every later operation on this review.

Give the reviewer all three opening aids: a best-effort [Open in Markover](<reviewUrl>) link, the raw review ID, and this Terminal fallback alone on its own line:

open 'markover://review/mko_8f3a2c'
-

Custom-scheme links work through macOS, but thread-hosts including T3 Code and the Codex app may strip or decline them. The standalone command is the reliable handoff.

+

Custom-scheme links work through macOS, but some chat apps, including T3 Code and the Codex app, do not currently open them from Markdown. The standalone command is the reliable handoff.

+
+ +
+

Use the identity your agent can actually observe

+

These routes are supported when their environment variable is present and nonblank. Keep the thread host and model provider as separate facts, use the local machine name, and omit any host-owned thread ID you cannot observe.

+

T3 Code with Codex

+ 
npx --yes \
+  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
+  markover open ./DOCUMENT.md \
+  --summary "Review these decisions before implementation." \
+  --thread-id "$CODEX_THREAD_ID" \
+  --thread-host-kind t3code \
+  --thread-host-provider codex \
+  --thread-host-machine "$(hostname)"
+

Claude Code with Claude

+ 
npx --yes \
+  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
+  markover open ./DOCUMENT.md \
+  --summary "Review these decisions before implementation." \
+  --thread-id "$CLAUDE_CODE_SESSION_ID" \
+  --thread-host-kind claude-code \
+  --thread-host-provider claude \
+  --thread-host-machine "$(hostname)"
+

When neither exact identifier is available, generate a fresh high-entropy --handoff-key for that one review instead of inventing thread metadata.

@@ -109,7 +192,7 @@

Record the completed handoff

Check and resolve pending reviews

At any point, an agent can ask Markover for every unresolved review opened by its exact current requesting thread. The result contains review links, document purpose, responsibility, age timestamps, and pull-request association without exposing draft feedback or changing review state.

markover pending --thread-id THREAD_ID --thread-host-kind t3code --thread-host-provider codex
-

Pending reviews are a soft gate: planning and implementation can continue, but the agent surfaces every result before merge or final thread completion. Silence and merge do not imply acceptance.

+

Pending reviews are a soft gate: planning and implementation can continue, but the agent surfaces every result before merging or finishing the thread. Silence and merge do not imply acceptance.

markover resolve mko_8f3a2c --outcome reviewed-no-notes
 markover resolve mko_8f3a2c --outcome accepted-unreviewed
 markover unresolve mko_8f3a2c
@@ -132,7 +215,7 @@

Use an agent as the reviewer

# The reviewer updates feedback and permitted sourceEdit fields in review.json. markover submit mko_8f3a2c --input review.json

The review must be pristine when claimed: no existing feedback, attachments, or source proposals. The returned artifact contains dedicated reviewer instructions under review.agentReviewer.agentGuidance, the effective permission under review.agentReviewer.mode, and reviewer thread provenance when available. The agent returns the complete artifact as one atomic batch; Markover accepts all permitted findings or none.

-

While the agent is reviewing, the document is read only in Markover and labeled Agent reviewing. After submission it is labeled Reviewed, remains immutable, and appears in history. Markover shows a completion notice with an Open action, including explicit no-findings copy when the reviewer returned an empty result.

+

While the agent is reviewing, the document is read only in Markover and labeled Agent reviewing. After submission it is labeled Reviewed, remains immutable, and appears in history. Markover shows a completion notice with an Open action, including an explicit no-findings message when the reviewer returned an empty result.

@@ -157,5 +240,6 @@

Possible stricter policies

Privacy, storage, and recovery → + diff --git a/docs/user/assets/markover-annotation-browser@2x.png b/docs/user/assets/markover-annotation-browser@2x.png index 77fb8a8e..86761ec3 100644 Binary files a/docs/user/assets/markover-annotation-browser@2x.png and b/docs/user/assets/markover-annotation-browser@2x.png differ diff --git a/docs/user/assets/markover-demo-poster.jpg b/docs/user/assets/markover-demo-poster.jpg new file mode 100644 index 00000000..aa3ce92f Binary files /dev/null and b/docs/user/assets/markover-demo-poster.jpg differ diff --git a/docs/user/assets/markover-focused-preview-demo.mp4 b/docs/user/assets/markover-focused-preview-demo.mp4 new file mode 100644 index 00000000..b36c4477 Binary files /dev/null and b/docs/user/assets/markover-focused-preview-demo.mp4 differ diff --git a/docs/user/assets/markover-github-social-preview.png b/docs/user/assets/markover-github-social-preview.png new file mode 100644 index 00000000..ed37844f Binary files /dev/null and b/docs/user/assets/markover-github-social-preview.png differ diff --git a/docs/user/assets/markover-lockup-dark.svg b/docs/user/assets/markover-lockup-dark.svg new file mode 100644 index 00000000..90acb7a7 --- /dev/null +++ b/docs/user/assets/markover-lockup-dark.svg @@ -0,0 +1,37 @@ + + Markover + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/user/assets/markover-logotype-dark.svg b/docs/user/assets/markover-logotype-dark.svg new file mode 100644 index 00000000..567c4c5f --- /dev/null +++ b/docs/user/assets/markover-logotype-dark.svg @@ -0,0 +1,29 @@ + + Markover + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/user/assets/markover-mark-dark.svg b/docs/user/assets/markover-mark-dark.svg new file mode 100644 index 00000000..9c01b7db --- /dev/null +++ b/docs/user/assets/markover-mark-dark.svg @@ -0,0 +1,13 @@ + + Markover mark + + + + + + + + + + + diff --git a/docs/user/assets/markover-pages-social-card.png b/docs/user/assets/markover-pages-social-card.png new file mode 100644 index 00000000..6a35049a Binary files /dev/null and b/docs/user/assets/markover-pages-social-card.png differ diff --git a/docs/user/assets/markover-review-context@2x.png b/docs/user/assets/markover-review-context@2x.png index a67cb4ab..58510247 100644 Binary files a/docs/user/assets/markover-review-context@2x.png and b/docs/user/assets/markover-review-context@2x.png differ diff --git a/docs/user/assets/markover-review-editor@2x.png b/docs/user/assets/markover-review-editor@2x.png index 6b1782a5..c26a3879 100644 Binary files a/docs/user/assets/markover-review-editor@2x.png and b/docs/user/assets/markover-review-editor@2x.png differ diff --git a/docs/user/assets/markover-source-edit@2x.png b/docs/user/assets/markover-source-edit@2x.png index 1a5756a6..135a8638 100644 Binary files a/docs/user/assets/markover-source-edit@2x.png and b/docs/user/assets/markover-source-edit@2x.png differ diff --git a/docs/user/compatibility/index.html b/docs/user/compatibility/index.html index 926c5125..4fd5f814 100644 --- a/docs/user/compatibility/index.html +++ b/docs/user/compatibility/index.html @@ -3,9 +3,44 @@ - + + Review format compatibility — Markover documentation + + + + + + + + + + + + + + + + @@ -26,11 +61,27 @@ Markdown and limitations Support +
+ + +
View source on GitHub ↗
Markover docs +
+ + +
User guide
@@ -45,7 +96,8 @@

Current catalog

ArtifactVersionFirst compatible release markover-review1Not yet assigned; development under issue #99 -

The first release carrying portable v1 must replace the pending entry before publication. Later releases update this table whenever they introduce a review-format version.

+ +

Later releases update this table whenever they introduce a review-format version.

Tools can read the same information from the machine-readable catalog.

@@ -66,5 +118,6 @@

Older released versions

Privacy, storage, and recovery → + diff --git a/docs/user/guide/index.html b/docs/user/guide/index.html index ac286295..a1f0e7d5 100644 --- a/docs/user/guide/index.html +++ b/docs/user/guide/index.html @@ -3,9 +3,44 @@ - + + Getting started — Markover documentation + + + + + + + + + + + + + + + + @@ -36,11 +71,27 @@ Developer documentation Source +
+ + +
View source on GitHub ↗
Markover docs +
+ + +
GitHub
@@ -51,9 +102,9 @@

Getting started

Before you try the early preview

-

Markover is an Early macOS preview. It supports macOS 14 Sonoma or newer on Apple Silicon Macs and requires Node.js 22.13.0 or newer for the bootstrap command. Native Intel releases are deferred to the Broad announcement roadmap. You do not need to clone the repository or install an npm package globally.

+

Markover is in early preview. It supports macOS 14 Sonoma or newer on Apple Silicon Macs and requires Node.js 22.13.0 or newer for the launcher. Native Intel releases are deferred; see issue #80.

Not Apple-verified. Markover uses a hardened ad-hoc code signature, but it has no authenticated Developer ID publisher and is not notarized. Gatekeeper is expected to block its first launch.
-

Ordinary review work stays in your macOS account. Markover has no telemetry, analytics, cloud sync, or automatic review upload. Unreleased prototype formats may change directly. Released review schemas are converted automatically with an original backup; unknown future versions remain untouched until a compatible Markover release opens them.

+

Ordinary review work stays in your macOS account. Markover has no telemetry, analytics, cloud sync, or automatic review upload. Data formats from unreleased prototype builds may change without migration support. Released review schemas are converted automatically with an original backup; unknown future versions remain untouched until a compatible Markover release opens them.

Before relying on Markover, read Markdown support and preview limitations and Privacy, storage, and recovery. Advanced users can follow the tailnet-only Tailscale Serve example for a manually authorized remote client. Ask usage questions in GitHub Discussions.

@@ -61,7 +112,7 @@

Before you try the early preview

Start a review with an agent

Tell your agent which Markdown file you want to review and why the review is useful. The agent opens that file in Markover and gives you a review ID, a best-effort Open in Markover link, and a standalone Terminal command. You do not need to clone the repository, install an npm package globally, or run the agent's launcher command yourself.

To start without an agent, choose File → Open Markdown…. Markover creates a managed local review from the selected snapshot, saves feedback and attachments separately, and restores that review after restart. The original Markdown file is never changed or deleted.

-
If the link does not open. Copy the standalone open 'markover://…' command the agent provides, paste it into Terminal, and press Return. Some thread-hosts do not dispatch custom-scheme links directly. Markover focuses and follows Settings → Incoming reviews → When you open a review link; links switch immediately by default.
+
If the link does not open. Copy the standalone open 'markover://…' command the agent provides, paste it into Terminal, and press Return. Some chat apps do not open custom-scheme links directly. Whether Markover switches to the incoming review immediately is controlled by Settings → Incoming reviews → When you open a review link; the default is to switch immediately.
Keep the agent thread available. When your feedback is ready, return to the same conversation and say “Check Markover.”

Agents and tool authors should follow the separate agent workflow for exact commands, review-ID handling, and feedback interpretation.

@@ -88,7 +139,7 @@

Review the document

Durability and recovery

-

While Markover is responsive and local storage is healthy, managed review changes are durably saved within a two-second window by default. A normal quit first captures the latest editable reviews and finishes their saves. Exact agent handoffs and reopened reviews are committed before Markover reports success.

+

While Markover is responsive and local storage is healthy, managed review changes are durably saved within a two-second window by default. A normal quit first captures the latest editable reviews and finishes their saves. Agent handoffs and reopened reviews are fully saved before Markover reports success.

After an app crash or restart, Markover restores both reviews still being edited and reviews already inflight with an agent. You do not need to retrieve or drain agent reviews before restarting. Attachment bytes are flushed before saved review JSON can refer to them; a crash can leave harmless unreferenced attachment bytes, but not a durable broken reference.

What the two-second window does not cover. The guarantee applies to an app-process crash. Power loss, operating-system or hardware failure, and unhealthy or unusually slow storage are outside it. A persistent autosave warning means Markover is retrying or waiting and the normal bound is suspended until storage recovers.

See Privacy, storage, and recovery for the advanced autosave setting, quit choices after a save problem, and backup guidance.

@@ -106,7 +157,7 @@

Keyboard controls

- + @@ -122,5 +173,6 @@

Keyboard controls

Markdown and limitations → + diff --git a/docs/user/index.html b/docs/user/index.html index 5190a9d2..1fcc796d 100644 --- a/docs/user/index.html +++ b/docs/user/index.html @@ -3,9 +3,44 @@ - - - Markover — Early macOS preview + + + + Markover — Structured review for Markdown + + + + + + + + + + + + + + + + @@ -21,6 +56,14 @@ PrivacyLimitationsGitHub +
+ + +
Try it @@ -40,25 +83,38 @@

Review the document.
Return the feedback.

KeyAction
Up / DownMove between sibling blocks; climb outward at a boundary
Up / DownMove between sibling blocks; at the first or last sibling, continue at the parent's level
LeftSelect the parent block
RightSelect the first child, then the next available sibling
Tab / Shift-TabMove among the left, center, and right panes