Diagnostics and public interfaces

validate checks source syntax/schema; check additionally renders and inspects geometry. Each diagnostic is one record: level, code, message and path, with fix, expected, retry, file, line, column, tag and details where they apply. Lines and columns count from 1, the frontmatter included; when file is set they are in that data or style file, otherwise in the .rmd. With --format json, init, validate, check, generate, publish and the report commands return one object, as do the MCP render, validate, check and publish tools: ok is true when no diagnostic is an error, status is issues when any error or warning was found and clean otherwise, output is the file written or null, and diagnostics lists the records. These commands exit 0 when ok, 1 on any error (a draft with block errors is still written) and 2 on a usage error. The other commands return no such object. learn prints the guide as text, and serve, server and mcp run until stopped; a failure prints one message and exits 1, or 2 on a usage error. With --format json, asset and image print their own JSON, {ok: false, code, error} on a failure; they exit 2 on invalid input or configuration and 3 when a transfer or the Unsplash request fails, and asset also exits 4 when verification finds a mismatch. The MCP learn, image and asset tools return what the matching command prints. On a server, publishing (POST /api/reports), POST /api/validate, POST /api/check, regenerating and every error body return the same object. /health answers {ok: true}, deleting, pinning and unpinning answer ok with the change, and the read, session and governance routes (people, tokens, access and the audit log) return their own records. Native checks distinguish emitted mark geometry from estimated font bounds. A clean native check is not proof of readability in every browser. See chart diagnostics.

A diagnostic’s path follows one grammar on every surface: dot-separated keys with [n] indices, rooted where the problem is. A block’s findings start at its tag (chart.encoding.y, table.columns[2].key). Other findings start at one of these roots:

frontmatter;
markdown, the body’s Markdown;
styles[n], a style file (styles[1].tokens.accent);
rows[n].field, a resolved data row;
source, the source text;
slug, the publication slug;
options.<name>, a host’s render options;
report_folder, the report folder itself;
output, what a host writes.

A message names a file by its report-relative path and a folder by its name, never by where either sits on the host. A finding about a file other than the .rmd also names that file in file.

The core provides parse, render, validate, validate_publish, check, and owned-AST render_document/check_document. The site runtime exposes rendering, validation, checking and page boot through generated wasm-bindgen bindings; schema objects and the retired learn, style and chart compatibility exports are absent. The site loader initializes Wasm before synchronous calls. Parsed body placeholders belong to the parser: literal source comments remain inert, and the AST carries an optional collision-free marker prefix when needed. richview learn supplies grammar, chart, style, workflow and design context for coding agents.

Core source (source.limit) and resolved-dataset (data.limit) limits are 16 MiB; native request/file boundaries add their own limits. MAX_REPORT_BYTES caps accumulated rich-block and complete HTML at 64 MiB, including embedded media, fonts and runtime. Repeated resolved media is checked before copying payloads; exceeding the budget returns a source-centered render.output-limit error, with a block line when available, rather than truncating the report. Recoverable errors stay visible; publication rejects hard source errors. Generated HTML carries the actual richview/<package-version> generator, and _richview metadata records block/chart counts, offline/runtime presence and chart diagnostics.

Chart treatments use the builtins in the style reference. hand-drawn draws data in greys (story grey, context grey, ink, mid grey) with a paper-to-ink heatmap ramp; its pencil strokes never touch gridlines, axes or data marks, and its chart labels use the bundled Patrick Hand face with browser measurement after fonts load. Axis ink uses the safe tokens.chart-ink color token. Compact magnitude suffixes attach directly (25k); known KBD values above 1,000 display as MBD. Values at the author’s chosen precision remain available in tooltips and tables.

An omitted chart style.palette inherits the report treatment. Explicit chart palettes retain priority. Reports without a style use the default in the style reference. Chart downloads include a PNG of the current view and a CSV of all original resolved observations at the author’s precision.