Polish focused-preview public copy

README.md

@@ -14,13 +14,16 @@
   <a href="https://lastobelus.github.io/markover/agents/">For agents</a>
 </p>
 
-Markover is an **Early macOS preview** for reviewing Markdown as a document
-tree and returning block-level feedback to an agent. It is free and
-MIT-licensed, requires no account, and keeps ordinary review data in your
-macOS account.
+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 is in **early preview**. It is free and MIT-licensed, requires no
+account, and keeps ordinary review data in your macOS account.
 
 <p align="center">
-  <a href="https://lastobelus.github.io/markover/#demo"><img src="./docs/user/assets/markover-review-editor@2x.png" width="920" alt="Markover in Ember Light showing the review inbox, a launch brief in the center document tree, and precise feedback with two labeled attachments."></a>
+  <a href="https://lastobelus.github.io/markover/#demo"><img src="./docs/user/assets/markover-review-editor@2x.png" width="920" alt="Markover in Ember Light showing the review inbox, a launch brief in the center document tree, and an annotation with two labeled attachments."></a>
 </p>
 
 ## Features
@@ -35,6 +38,14 @@ macOS account.
 - 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
@@ -44,7 +55,8 @@ macOS account.
   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.
@@ -70,13 +82,12 @@ 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"}
@@ -88,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.
 
@@ -131,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

doc/launch/issue-16/README.md

@@ -71,6 +71,10 @@ Before publishing any visual:
   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.

doc/launch/issue-16/demo-storyboard.md

@@ -17,7 +17,7 @@
 ### 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 three-pane Ember Light layout establish
+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
@@ -29,7 +29,7 @@ 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 visual context to one exact block.**
+Caption: **Attach labeled screenshots to a single block.**
 
 ### 0:15–0:25 — Inspect an exact source change
 
@@ -68,11 +68,6 @@ MIT-licensed macOS early preview**, and `github.com/lastobelus/markover`.
 
 ## Pages transcript
 
-Markover opens a sanitized launch brief in an Ember Light review inbox. The
-reviewer selects one Markdown block, adds precise feedback, and keeps two
-labeled images attached to that context. On the opening paragraph, Markover
-shows an exact source proposal as a word-level diff without changing the source
-document. The reviewer switches to All annotations to scan the complete review,
-then returns to the agent's terminal. One fixture-only command retrieves a
-structured handoff containing the feedback, attachment labels, and source
-proposal.
+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.

doc/launch/issue-16/demo-transcript.md

@@ -1,21 +1,31 @@
 # 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.
+
+<!-- pages-transcript:start -->
+
 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 Left, Center, and Right panes establish the review. The reviewer
-sees agent-written Markdown as a document tree with precise feedback and two
-labeled images attached to one heading.
+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 fixture-only CLI returns structured JSON containing the review
-status, block feedback, attachment IDs and labels, and source proposal. The demo
-ends on the canonical Markover lockup, “Structured review for Markdown,” the
-free, MIT-licensed macOS early-preview boundary, and the repository address.
+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.
+
+<!-- pages-transcript:end -->
+
+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

doc/launch/issue-16/focused-preview-copy.md

@@ -7,31 +7,39 @@ different useful question.
 
 ## Coding-agent community
 
-I’m preparing an early macOS preview of Markover, a free MIT-licensed,
-local-first app for reviewing agent-written Markdown block by block. It needs
-no account: 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—not for
-stars. Apple Silicon macOS 14+ only for this preview. [Watch the 44-second
+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, local-first, and requires no account. I most need the
-exact moment the workflow becomes slower or less clear than your current
+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 local-first 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, 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).
+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

docs/user/agents/index.html

@@ -104,19 +104,26 @@ <h1 id="overview">Review a Markdown document with Markover</h1>
 
       <section id="open">
         <h2>Open one review</h2>
-        <p>Run <code>markover help</code> before a pull-request-associated <code>open</code>, <code>get</code>, <code>get-for-review</code>, <code>revise</code>, or <code>done</code>. Its machine-readable <code>pullRequestStatus</code> contract is the source of truth for the live GitHub lookup, status mapping, flags, and lookup-failure behavior.</p>
-        <p>Give Markover one Markdown path and a short summary of why the document exists and what feedback would help:</p>
+        <p>Give Markover a Markdown path and a short summary of why the document exists and what feedback would help:</p>
+        <div class="callout"><strong>Pull-request-associated commands.</strong> Before an <code>open</code>, <code>get</code>, <code>get-for-review</code>, <code>revise</code>, or <code>done</code> that involves a pull request, run <code>markover help</code>. Its machine-readable <code>pullRequestStatus</code> contract defines the live GitHub lookup, status mapping, flags, and lookup-failure behavior.</div>
         <pre><code>npx --yes \
   --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
   markover open ./DOCUMENT.md \
   --summary "Review these decisions before implementation."</code></pre>
-        <p>When reliable thread metadata is available, pass the best observable requesting-thread or session ID with <code>--thread-id</code>. Use <code>--thread-host-kind</code> for the user-facing product or lookup namespace where the user would look for the thread, and <code>--thread-host-provider</code> for the LLM provider or model family in use rather than an intermediate harness. Pass <code>--thread-host-thread-id</code> only for a distinct host-owned identifier. Try the local <code>hostname</code> command and pass its result as <code>--thread-host-machine</code>. Use recommended product values when they match observable facts, preserve truthful unknown values, and omit anything unavailable rather than guessing.</p>
-        <p>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:</p>
+        <p>When reliable thread metadata is available:</p>
+        <ul>
+          <li>Pass the best observable requesting-thread or session ID with <code>--thread-id</code>.</li>
+          <li>Use <code>--thread-host-kind</code> for the user-facing product or lookup namespace where the user would look for the thread, and <code>--thread-host-provider</code> for the LLM provider or model family in use — not an intermediate harness.</li>
+          <li>Pass <code>--thread-host-thread-id</code> only for a distinct host-owned identifier.</li>
+          <li>Run the local <code>hostname</code> command and pass its result as <code>--thread-host-machine</code>.</li>
+          <li>Use recommended product values when they match observable facts, preserve truthful unknown values, and omit anything unavailable rather than guessing.</li>
+        </ul>
+        <p>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:</p>
         <pre><code>{"reviewId":"mko_8f3a2c","status":"editing","reviewUrl":"markover://review/mko_8f3a2c"}</code></pre>
         <div class="callout"><strong>Retain the review ID.</strong> It is the stable identifier for every later operation on this review.</div>
         <p>Give the reviewer all three opening aids: a best-effort <code>[Open in Markover](&lt;reviewUrl&gt;)</code> link, the raw review ID, and this Terminal fallback alone on its own line:</p>
         <pre><code>open 'markover://review/mko_8f3a2c'</code></pre>
-        <p>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.</p>
+        <p>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.</p>
       </section>
 
       <section id="identity-examples">
@@ -185,7 +192,7 @@ <h2>Record the completed handoff</h2>
         <h2>Check and resolve pending reviews</h2>
         <p>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.</p>
         <pre><code>markover pending --thread-id THREAD_ID --thread-host-kind t3code --thread-host-provider codex</code></pre>
-        <p>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.</p>
+        <p>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.</p>
         <pre><code>markover resolve mko_8f3a2c --outcome reviewed-no-notes
 markover resolve mko_8f3a2c --outcome accepted-unreviewed
 markover unresolve mko_8f3a2c</code></pre>
@@ -208,7 +215,7 @@ <h2>Use an agent as the reviewer</h2>
 # The reviewer updates feedback and permitted sourceEdit fields in review.json.
 markover submit mko_8f3a2c --input review.json</code></pre>
         <p>The review must be pristine when claimed: no existing feedback, attachments, or source proposals. The returned artifact contains dedicated reviewer instructions under <code>review.agentReviewer.agentGuidance</code>, the effective permission under <code>review.agentReviewer.mode</code>, and reviewer thread provenance when available. The agent returns the complete artifact as one atomic batch; Markover accepts all permitted findings or none.</p>
-        <p>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.</p>
+        <p>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.</p>
       </section>
 
       <section id="interpretation">

docs/user/compatibility/index.html

@@ -96,7 +96,8 @@ <h2>Current catalog</h2>
           <thead><tr><th>Artifact</th><th>Version</th><th>First compatible release</th></tr></thead>
           <tbody><tr><td><code>markover-review</code></td><td><code>1</code></td><td>Not yet assigned; development under issue #99</td></tr></tbody>
         </table>
-        <p>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.</p>
+        <!-- Release checklist: the first release carrying portable v1 must replace the pending entry before publication. -->
+        <p>Later releases update this table whenever they introduce a review-format version.</p>
         <p>Tools can read the same information from the <a href="./catalog.json">machine-readable catalog</a>.</p>
       </section>