vantage-md 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -1,39 +1,134 @@
 # Changelog
 
-What changed in each release of Vantage, newest first.
-
-Releases before 0.7.0 are summarized one section per minor line — `0.6.x`,
-`0.5.x` — rather than one per patch release. The per-patch detail is in the
-commit log.
+What changed in each release of Vantage, newest first. Releases before 0.7.0
+are summarized one section per minor line; the commit log has the rest.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.1] - 2026-10-02
+
+If your `.vantage.toml` sets a `target` before 0.8, such as `target = "0.7"`,
+`vantage-check` no longer asks you to write `question` on an open question,
+because a viewer before 0.8 offers its one-click answer only on an `oq`: it stops
+warning on an `oq` (`vantage/oq-deprecated`), and tells a question with no
+directive to take one (`vantage/oq-missing`). An `oq` on a 🔒 or ✅ question is
+still an error. A checker before 0.8 ignores the `target` line, where 0.7.1
+rejects `"vantage/oq-deprecated" = "off"`. See
+[When Your Readers Are on 0.7](userguide/guides/vantage-check.md#when-your-readers-are-on-07).
+
+## [0.8.0] - 2026-10-02
+
+**Highlights.** Vantage 0.8 puts every open question in your design docs on one
+page, in roadmap order, hands your answers to an agent in one copy, and serves a
+whole folder of clones with `vantage ~/code`.
+
+### Added
+
+**The planning page.** Press `g p`, or run `vantage-check index`, to see what a
+repository's planning documents still owe: questions that need a ruling, what
+waits on what, and which documents are ready to build. Answer questions from
+their cards, then hand the work to an agent with **Copy answers** or **Copy
+agent request**. Links to planning documents get badges such as
+`in-review · DESIGN · 💬 5`, and with several `roadmap.md` files the page lets
+you pick one. See [Planning Documents](userguide/guides/planning.md).
+
+**Inline SVG.** An `<svg>` wrapped in a `<div>`, with no blank line inside,
+renders as a drawing. Colors written in `style` are dropped, so Inkscape and
+matplotlib exports render black. GitHub and Vantage 0.7 drop the drawing, so
+follow it with a `<!-- vantage: fallback -->` paragraph saying what it shows,
+which only Vantage 0.8 hides. See
+[Inline SVG](docs/reference/inline-markup.md#inline-svg).
+
+**`question` replaces `oq`.** One `question` directive declares a question in
+any state, and `oq` still works but is deprecated. Vantage 0.7 drops a
+`question`, losing its one-click answer, so keep `oq` on open questions until
+every reader is on 0.8, and turn its new warning off with
+`"vantage/oq-deprecated" = "off"` under `[check.rules]`. Keep running the newest
+checker meanwhile: 0.7.1 rejects that line and the new directives. See
+[When Your Readers Are on 0.7](userguide/guides/vantage-check.md#when-your-readers-are-on-07).
+
+**Answers by comment.** A comment on a question is its answer, whether you take
+its leaning, use **Answer…**, or comment anywhere in it. The question then shows
+as answered, in the document and on its planning card, and no longer counts as
+needing you. See
+[Planning Documents](userguide/guides/planning.md#a-comment-on-a-question-is-your-answer).
+
+### Changed
+
+**Unknown config keys.** An unknown `.vantage.toml` key no longer breaks the
+server or the checker. `vantage-check` used to exit `2`, and the server ignored
+the whole file over one in `[starred]`. From 0.8.0, a checker older than a
+top-level `target`, the oldest release your readers use, refuses to run. See
+[Keys From a Newer Release](userguide/reference/configuration.md#keys-from-a-newer-release).
+
+**Your release in the review prompt.** The prompt's check command names it, as
+`VANTAGE_VIEWER=0.8.0 uvx vantage-check <file>`, and so does the planning page's
+agent request, so a later checker can write for the viewer you run. See
+[How agents find out about it](userguide/guides/vantage-check.md#how-agents-find-out-about-it).
+
+**Hand-written HTML.** It and Mermaid can no longer draw over Vantage's own
+page. Vantage drops a `class` Markdown did not put there, a `style` whose
+`display` is `contents` or unlisted, and a Mermaid diagram's `themeCSS` and font
+families. `vantage-check` reports none of these. See
+[Security](docs/reference/inline-markup.md#security).
+
+**A folder of clones.** `vantage ~/code` serves each clone as its own project,
+and the Markdown outside them as one more, when the directory is not inside a
+git repository. Only `--one-project`, the old behavior, shows review comments
+left on that Markdown. See
+[Serve a directory of clones](userguide/getting-started.md#serve-a-directory-of-clones).
+
+**A startup tip.** `vantage` started in a terminal mentions the background
+service. `VANTAGE_NO_TIPS=1`, or `tips = false` in your config, turns it off.
+
+**New checker findings.** Some can fail a CI job, so
+[pin the checker](userguide/guides/vantage-check.md#in-ci) to take them when you
+choose. `planning/depends-on-missing` and `vantage/question-name`, an `oq` on a
+🔒 or ✅ question, are errors. The new warnings, which fail `--strict`, are
+`planning/question-length`, `vantage/oq-deprecated`, `vantage/question-layout`
+and `prose/inline-list`, on a paragraph that runs `(a) (b) (c)` together. Check
+a file named `index` as `vantage-check ./index`, since `index` is now a command.
+
+### Fixed
+
+- A request for `docs/../.vantage/…`, or on macOS for any case of `.git` or
+  `.vantage` such as `.GIT/config` (which can hold a token), read the real file.
+  Vantage refuses both now.
+- Review mode's **Copy** quotes each path, so a file name holding `$(…)` or a
+  backtick cannot run a command.
+- On a `vantage build` site, a heading's `#` link left an address that opened a
+  blank page. Rebuild and redeploy to fix it; see
+  [Page URLs](userguide/guides/static-sites.md#page-urls).
+- On macOS, a large tree could use up the server's open files and stop it.
+- A document reloaded when only its attributes changed, as Spotlight and backup
+  tools do.
+- A page in a project or folder named `api` showed a JSON 404 on a reload.
+- The sidebar's recent files could miss or misplace a document just written.
+
+### Contributors
+
+Thanks to Eduardo Hidalgo ([@edus44](https://github.com/edus44)) for inline SVG.
+
 ## [0.7.1] - 2026-09-27
 
 ### Added
 
-**Recent files across all projects on `Shift+R`.** Pressing `Shift+R` opens the
-recent files modal scoped to all configured projects, matching `r` for the
-current project. Rows show their project name and update live via the watcher.
-You can navigate the list with arrow keys or `j` and `k`. See
+**`Shift+R` lists recent files across all projects,** as `r` does for the
+current one, with each row's project name. See
 [Recently Changed Files](userguide/reference/keyboard-shortcuts.md#recently-changed-files).
 
-**Open picker items in a new tab.** Pressing `Alt+Enter` or `Ctrl+Enter` (or `Cmd+Enter`
-on macOS) in the file picker (`t`, `Shift+T`) or project picker (`Shift+P`) opens
-the highlighted row in a new browser tab. Ctrl-click and middle-click on any row
-work as well. See [File Picker](userguide/reference/keyboard-shortcuts.md#file-picker).
+**`Alt+Enter` or `Ctrl+Enter` (`Cmd+Enter` on macOS) opens the highlighted row
+of a picker in a new tab,** as do Ctrl-click and middle-click. See
+[File Picker](userguide/reference/keyboard-shortcuts.md#file-picker).
 
 ### Fixed
 
-- Build output directories (`target`, `build`, `dist`) and tool caches (`.cache`,
-  `__pycache__`, `.pi`, and test/lint caches) are excluded from file listings,
-  repository discovery, and the filesystem watcher by default. This prevents
-  inotify watch exhaustion and excessive disk I/O while running builds in
-  watched repositories. See [Ignore Files and Live Reload](userguide/reference/configuration.md#ignore-files-and-live-reload).
-- Linked Git worktrees are excluded from repository auto-discovery, directory
-  listings, file picker results, and the live watcher, avoiding duplicate
-  trees and redundant filesystem watches.
+- Build output (`target`, `build`, `dist`) and tool caches such as `.cache` and
+  `__pycache__` are no longer listed, discovered or watched by default, so a
+  build no longer exhausts inotify watches. Linked Git worktrees are left out
+  too, so no tree shows twice. See
+  [Ignore Files and Live Reload](userguide/reference/configuration.md#ignore-files-and-live-reload).
 
 ## [0.7.0] - 2026-09-23
 
@@ -42,101 +137,56 @@ from `.vantage.toml`.
 
 ### Added
 
-**Color themes.** Pick a palette under **Colors** in the settings menu. Six come
-with Vantage: Catppuccin, Gruvbox, Lila, Nord, Solarized, and Tokyo Night, each
-with its own light and dark variants, alongside the default look, now called
-Slate.
-
-To write your own, put a CSS file in `~/.config/vantage/themes/`. It shows up in
-the menu on the next page load, with no restart. Set `theme = "gruvbox"` in your
-config to start every browser in one. A project can suggest a theme in its
-`.vantage.toml`, and your own choice always wins. A theme with no dark colors is
-listed as "(light only)". Every built-in theme keeps its text at 3:1 contrast or
-better in both modes, checked in a real browser; your own themes aren't checked.
-Review mode's comment colors and printing still ignore the theme. See
+**Pick a color theme under Colors in the settings menu:** six come with Vantage,
+each with light and dark variants, and the default look is now called Slate.
+Add your own as a CSS file in `~/.config/vantage/themes/`, or set
+`theme = "gruvbox"` in your config to start every browser in one. See
 [Color Themes](userguide/guides/themes.md).
 
-**Bookmarks.** Click the star next to a document's name to bookmark it. Folders
-work too. Bookmarks appear in a **Starred** section above the file tree. They're
-stored in `~/.local/share/vantage/starred/` instead of in your browser, so they
-survive a restart and show up in every tab. If a bookmarked file disappears, the
-entry stays put and offers to remove itself when you open it.
-
-A project can also list the documents worth reading first in its `.vantage.toml`,
-and you can list files you always want starred in your own config. Those entries
-are marked with a pin and name the file that added them. See
+**Click the star beside a document or folder to bookmark it in the Starred
+section above the file tree.** Bookmarks are kept in
+`~/.local/share/vantage/starred/`, not your browser, so every tab sees them, and
+a project's `.vantage.toml` and your config can list pinned entries. See
 [Starred](userguide/features.md#starred).
 
-**Open questions in the contents panel.** A document's open questions now appear
-in the table of contents, under the heading they sit below, with a count next to
-**Contents**. `💬 3` means three are waiting on a decision; `💬 1 ✅ 2` means one
-is open and two are answered. Click one to jump to it. See
-[Table of Contents](userguide/features.md#table-of-contents).
+**A document's open questions appear under their headings in its table of
+contents,** with a count beside **Contents**: `💬 1 ✅ 2` means one open and two
+answered. See [Table of Contents](userguide/features.md#table-of-contents).
 
 ### Changed
 
-Settings now follow you between tabs. Before, a second tab read most settings
-once when it loaded and then drifted, so changing the theme in one tab left the
-other on the old one. `Shift+D` had the same problem inside a single tab: it
-changed the page without updating the settings menu. The sidebar and its width,
-the tree filters, the project sort order, light/dark, and the color theme all
-stay in sync now.
-
-Review mode is a deliberate exception. Two tabs are usually on different
-documents, and picking up a toggle from another tab would close the review pane
-while you're partway through a comment.
+**Settings follow you between tabs:** the sidebar and its width, the tree
+filters, the project sort order, light/dark and the color theme. Review mode
+does not, so a toggle in one tab cannot close the review pane in another.
 
 ### Fixed
 
-- The file pickers (`t`, `Shift+T`, `Shift+R`, `Shift+P`) reload their list every
-  time they open, and a picker that's already open keeps up with the filesystem.
-  Before, a file created after the page loaded was unfindable until you
-  reloaded.
-- A modified file's icon was too faint to read in the file tree in light mode.
-- A document that fails to load no longer moves you off the one you're reading,
-  and the error names the file you actually asked for.
-- A slow response for a document you've already navigated away from is thrown
-  away instead of replacing what you're reading.
-- `vantage-check check --config <a directory>` now says
-  `docs is a directory, not a config file` and exits 2, instead of printing a
-  stack trace.
+- The file pickers reload their list each time they open, so a file created
+  after the page loaded can be found without a reload.
+- A document that fails to load, or a slow response for one you have left, no
+  longer replaces the one you are reading.
+- `vantage-check check --config <a directory>` says it is a directory and exits
+  2, instead of printing a stack trace.
 
 ### Contributors
 
 Thanks to [@nichiflu](https://github.com/nichiflu) for the initial color-theme
 implementation.
 
-### Works well with
-
-[matt-craft](https://github.com/mschulkind-oss/matt-craft) is out — the skills I use to
-write the documents I then read in Vantage: design notes that carry their open
-questions, roadmaps, research rounds, user stories, and one for Vantage's own Markdown
-conventions. It is not part of Vantage and Vantage does not need it. If you write your
-own documents your own way, nothing here changes for you.
-
 ## 0.6.x
 
 _0.6.0 – 0.6.2, September 2026._
 
-Long documents have a table of contents. The list button beside the breadcrumb
-shows the document's headings in the left margin, and the list stays put while
-you scroll. The button beside it lets the text fill the pane. The reading band
-moved to the left edge too, so the file list, the contents, and the text sit
-together.
+Long documents have a table of contents: the list button beside the breadcrumb
+shows the headings in the left margin, and the button beside it lets the text
+fill the pane.
 
-- Serving a git repository no longer makes the browser reload itself once a
-  second. Vantage's own `git status` calls rewrote `.git/index`, and the watcher
-  read that as your edit.
+- Serving a git repository no longer makes the browser reload once a second.
 - A repository cloned under one of your `source_dirs` shows up within thirty
-  seconds, with no restart. One whose directory goes away is dropped, then
-  picked back up when it returns. See
-  [Daemon Mode](userguide/guides/daemon-mode.md).
+  seconds, with no restart. See [Daemon Mode](userguide/guides/daemon-mode.md).
 - A port you name is bound exactly or startup fails. Only the default 8000 walks
-  to the next free port, and it tells you which one it took.
-- Images on adjacent lines render on one row, the way GitHub lays them out. A
-  README's badges used to stack into a column.
-- `vantage-check` splits a run across worker threads by default, and the report
-  reads the same either way.
+  to the next free port.
+- Images on adjacent lines render on one row, as on GitHub.
 
 ### Contributors
 
@@ -148,90 +198,67 @@ browser reloads.
 
 _0.5.0 – 0.5.10, May to September 2026._
 
-Vantage stopped being a Python server and became one Go binary. The viewer and
-the shortcuts are the same; installing it is not. You install it with `brew
-install`, `uvx vantage-md ~/notes`, or a platform archive from a release.
+Vantage stopped being a Python server and became one Go binary. Install it with
+`brew install`, `uvx vantage-md ~/notes`, or a platform archive from a release.
 `vantage serve` opens your browser, and `--no-open` stops it.
 
-- `vantage-check` is new. It runs your documents through the viewer's own
-  pipeline and reports dead links, dead anchors, broken mermaid diagrams, and
-  style problems. See [vantage-check](userguide/guides/vantage-check.md).
-- You can mark a document up with `<!-- vantage: … -->` comments that GitHub
-  ignores and Vantage reads: a status chip beside a heading, collapsible
-  sections, emphasis, and badges. GitHub's alert blocks render too.
-- Review mode was rebuilt. A comment anchors to a whole block, replies thread, a
-  rail shows where the comments are, and you can answer an open question in one
-  click. Agents reply through a `.vantage/` directory. See
+- `vantage-check` is new. It reports dead links, dead anchors, broken Mermaid
+  diagrams, and style problems. See
+  [vantage-check](userguide/guides/vantage-check.md).
+- `<!-- vantage: … -->` comments, which GitHub ignores, add status chips,
+  collapsible sections, emphasis, and badges. GitHub's alert blocks render too.
+- Review mode was rebuilt: a comment anchors to a whole block, replies thread,
+  and agents reply through a `.vantage/` directory. See
   [The `.vantage/` directory](userguide/guides/review-inbox.md).
 - The "What's New" popup, the changed-document highlight, and the jj history
   viewer were removed.
-- `.vantageignore` and `~/.config/vantage/ignore` keep files out of the tree, and
-  the sidebar has a drag handle that remembers its width.
+- `.vantageignore` and `~/.config/vantage/ignore` keep files out of the tree.
 
 ## 0.4.x
 
 _0.4.0 – 0.4.2, April 2026._
 
-Installing Vantage got short. `uvx vantage-md ~/notes` started the server and
-opened your browser at the directory you named, and naming a file landed on that
-file with the sidebar already expanded. There was a Homebrew formula as well.
-macOS became a platform Vantage was tested on.
-
-- Review mode became per file. Turning it on for one document no longer followed
-  you to the next, and the toggle survived a reload even before you had written a
-  comment.
-- Hovering any paragraph in review mode put a button in the gutter, so you could
-  comment on a whole block without selecting text first.
-- You could edit a comment in place, from the document or from the sidebar.
-  Resolved comments collapsed into one indicator instead of asking to be
-  dismissed one at a time.
-- A comment you had just written was sometimes marked "Outdated" immediately.
-- `log_level` in the config, `VANTAGE_LOG_LEVEL` in the environment. The watcher
-  reported your inotify limits at startup and warned near the ceiling, which is
-  the usual reason live reload stops working.
+`uvx vantage-md ~/notes` started the server and opened your browser at the
+directory you named, a Homebrew formula arrived, and macOS became a tested
+platform.
+
+- Review mode became per file, and hovering a paragraph put a comment button in
+  the gutter.
+- You could edit a comment in place, and resolved comments collapsed into one
+  indicator.
+- `log_level` in the config and `VANTAGE_LOG_LEVEL` in the environment arrived,
+  and the watcher warned near your inotify limit, the usual reason live reload
+  stops.
 
 ## 0.3.x
 
 _0.3.0 – 0.3.8, April 2026._
 
-This is the line that added review mode. You turned it on for a document,
-selected some text, and left a comment. The server stored the comments, so they
-survived a restart. When the text under a comment changed, the comment turned
-amber and said "Outdated". Every save while review mode was on snapshotted the
-previous version, so you could step back through revisions and see which
-paragraphs had changed. One button copied every comment as Markdown quotes, with
-line numbers and surrounding context, ready to paste to an agent.
-
-- Opening a project no longer waited for its file tree. The document rendered
-  first and the sidebar filled in behind it.
-- Headings got hover anchors, and `#L42` or `#L42-L50` in the URL scrolled to
-  those source lines and highlighted them.
-- You could collapse the sidebar to give the document the window, and reveal
-  hidden or gitignored files with new toggles.
-- TOML frontmatter between `+++` fences was parsed and shown, with taxonomies and
-  extra fields as tag pills.
-- A red banner with a timer appeared when the page lost its connection, so a
-  document that had stopped live-reloading said so.
+This line added review mode. You selected text in a document and left a comment,
+which the server stored and marked "Outdated" when the text under it changed.
+Each save in review mode snapshotted the previous version so you could step
+back through revisions, and one button copied every comment as Markdown for an
+agent.
+
+- Opening a project no longer waited for its file tree.
+- Headings got hover anchors, and `#L42` or `#L42-L50` in the URL highlighted
+  those source lines.
+- You could collapse the sidebar and show hidden or gitignored files.
+- TOML frontmatter between `+++` fences was shown, with taxonomies as tag pills.
+- A red banner appeared when the page lost its connection.
 
 ## 0.2.x and earlier
 
 _0.0.1 – 0.2.0, February to March 2026._
 
-Where Vantage started. It served the Markdown in your git repositories over a
-local port and reloaded the page when you saved: GitHub-flavored Markdown,
-syntax highlighting, KaTeX math, mermaid diagrams you could click to zoom,
-commit history and diffs, a fuzzy file picker on `t`, dark mode on `Shift+D`,
-vim-style scrolling, and a print stylesheet. It could also export a static site
-to host on Cloudflare Pages or S3. The server was written in Python then.
+Where Vantage started: a Python server for the Markdown in your git
+repositories, reloading the page when you saved, with GitHub-flavored Markdown,
+syntax highlighting, KaTeX math, Mermaid diagrams, commit history and diffs, a
+fuzzy file picker on `t`, dark mode on `Shift+D`, vim-style scrolling, and
+static-site export.
 
 - `Shift+T` searched files across every project, `P` switched projects, `r` and
   `Shift+R` found recently modified files, and `y` copied the current file's
-  absolute path.
-- `source_dirs` in the config found every git repository under a directory, so
-  you did not have to list them one by one.
-- The project picker became a full page, with repository names, relative
-  timestamps, and a toggle between alphabetical and recent order.
-- A "What's New" popup showed the changelog the first time you opened a new
-  version. You could turn it off in settings. Vantage dropped it in 0.5.
-- A jj history and evolution viewer sat beside the git one, for Jujutsu
-  repositories. That went in 0.5 too.
+  path.
+- `source_dirs` in the config found every git repository under a directory.
+- The project picker became a full page.

package/README.md

@@ -73,6 +73,32 @@ function Docs({ content, path }) {
 
 The React component includes mermaid diagram rendering (lazy-loaded), frontmatter display, and syntax highlighting out of the box.
 
+### Frontmatter card
+
+`MarkdownViewer` draws a document's frontmatter with `FrontmatterDisplay`, which
+is also exported on its own. It takes the parsed `frontmatter` and one optional
+prop, `linkIds`: the ids of the document's own questions, as its
+`<!-- vantage: question id=OQ-… -->` directives name them (or the deprecated
+`<!-- vantage: oq id=OQ-… -->`). When it is given, each of
+those ids that appears as a whole word in the top-level `next` key (a document's
+next step, one line of text) is drawn as a link to `#OQ-…`, the question's
+anchor. The rest of `next`, and every other value, stays plain text.
+
+```tsx
+import { FrontmatterDisplay } from "vantage-md/react";
+
+<FrontmatterDisplay
+  frontmatter={{ status: "in-review", next: "Rule OQ-B2 first" }}
+  linkIds={["OQ-B2"]}
+/>;
+// next renders as: Rule <a href="#OQ-B2">OQ-B2</a> first
+```
+
+Pass only ids a question in the document carries. An id that is left only in
+the text, such as one kept in a table of past decisions after its question was
+removed, has no anchor to land on. Without `linkIds`, `next` renders like any
+other value, which is what `MarkdownViewer` does: it never passes the prop.
+
 ### Your own processor, Vantage's chain
 
 `buildPipeline` returns the exact remark and rehype lists `renderMarkdown` and