Build the page, not a frontend project

Start here

Write the opening thesis as one emphasized prose paragraph, not as a callout or custom HTML component.

Use Node.js 24.18.0 or newer. Start with the agent quickstart, retrieve the direct Markdown version, or install the agent skill.

npx --yes agentic-report@0.21.1 init ./my-page --starter landing --json
# Edit ./my-page/report.md and its local assets.
npx --yes agentic-report@0.21.1 build ./my-page --output ./my-page.html --json

Open my-page.html through file://. Build validates before publishing; use validate or inspect only when a separate diagnostic or source-inventory result is useful.

Discuss a living document locally

The optional serve command connects a local document to its existing author Codex session. Select text and choose Ask agent to write beside the passage, or ask a general chat question. Waiting questions show their order and can be cancelled; the chat panel also holds width and visual settings. Replies stream and valid source revisions appear with change marks. Human text from that Codex/terminal conversation appears alongside agent replies; correlated browser questions appear once. Read the live operating guide for pinned-release or source-checkout startup, Codex setup, bounded text history, persistent questions and recovery. This local mode uses the same declarative source; ordinary builds remain standalone offline artifacts.

Build from source

If you prefer to inspect the implementation instead of executing the published agentic-report npm package, clone a specific release tag and run the compiler directly from its build:

git clone --branch v0.21.1 --depth 1 https://github.com/witqq/agentic-report.git
cd agentic-report
git rev-parse HEAD
git tag --points-at HEAD

# Review the source, package.json, pnpm-lock.yaml, and lifecycle scripts first.
pnpm install --frozen-lockfile
pnpm verify
pnpm build

node dist/node/cli.js init ../my-page --starter document --json
node dist/node/cli.js build ../my-page --output ../my-page.html --json

This path does not install or execute the agentic-report package from npm. It still uses the npm registry for the exact dependencies pinned by pnpm-lock.yaml; dependencies are not vendored. Review the lockfile and scripts before installation, use an isolated environment if your threat model requires it, and keep the tag pinned so later commands continue to use the revision you inspected.

Validate, explain, and repair

The CLI commands are discoverable: describe lists all of them under commands, and the authoring catalog prints the same list. Agent output is the default—NDJSON for run commands and one compact JSON line for reference commands. --json explicitly names that default; --human selects prose or indented JSON without dropping diagnostic facts.

One directive pass returns every independent authored violation it found. The first diagnostic carries the rest in related, ordered by source position, while declared dependencies suppress only conclusions that would rely on an already refused interpretation. Inspect those dependencies without compiling through describe → authoredRules.

When a diagnostic contains an exact source-range fix, run agentic-report fix ./my-page. It is the only compiler repair command and changes only the computed ranges; validate, inspect, build, and review remain read-only. Glossary definitions may declare exact inflections with forms; the compiler does not guess morphology. init accepts a symbolic-link parent such as macOS /tmp, reports the resolved destination, and still refuses every existing destination.

Authoring contract

Authors write declarative source rather than application code. Use Markdown for content, frontmatter or a manifest for page settings, allowlisted semantic directives for components, confined Markdown partials for composition, and local assets for media and downloads.

A top-level section composes a package-owned arrangement from closed attributes: composition, viewport rhythm, density, typography, media treatment, independent image and video fit/aspect/focal point, and a decorative surface. Every value is in the source contract. They work in both output formats without author CSS or JavaScript. Multi-column and layered arrangements flatten to the authored reading order on narrow screens; gallery overflow stays inside its rail. A multi-item rail shows compact continuation and receives localized focus and arrow-key scrolling only while it actually overflows; those scroll-only semantics disappear when a wide owner fits every item. Every section contains its floats and local layer order. Split and stage arrange only the section's opening, the blocks right after the title that read well in half the track, with at most one picture: split sets it beside the title, a stage sets its lead, paragraphs, and actions beside its opening picture under a full-width title, and a gallery stage keeps its title beside the rail. Every later block spans the whole section track, and split returns to flow before desktop navigation can make its tracks unreadable. Mosaic/stack composition cannot pair with layers/gallery media because both roles would own the same card layout; those four combinations fail before rendering.

A recipe is the short path to a coordinated section; explicit detailed attributes override only their own recipe roles. The default theme is neutral, and a page may extend any built-in theme with a theme of its own. The recipes, the built-in themes, and the page layouts are listed in the generated authoring catalog. A card may declare one safe href to become a single visibly linked keyboard target, but it cannot contain nested links.

Section tone owns its background and foreground relationship. Decorative surfaces remain behind the authored content, while nested cards and visualizations restore their own readable package surface text.

::::section{title="A visual argument" composition="stage" viewport="full" section-density="immersive" type="display" media="natural" media-fit="cover" media-aspect="cinematic" focal="right" surface="tint" transition="stagger" scene="progress" choreography="cascade"}
The content remains ordinary Markdown and semantic directives.
::::

Use media="natural" for ordinary rectangular media. The legacy mask spelling is accepted as natural without angular clipping; fit, aspect, and focal point remain independent. See the section attributes for the complete contract.

Sections also accept closed motion roles — transition, scene, interaction, and choreography — whose values are in the same source-contract table. Without a recipe they default to none; reduced motion leaves content visible and pointer effects require a fine pointer. Conflicting layout or transform owners fail validation. actions accepts placement="auto|edge|inline|bottom", with bottom kept in normal flow, and only a primary action may use the bounded effect="magnetic". The package owns timings, movement, responsive placement, and icons.

Recipes include their entrance and scene behavior. For a pointer-depth opening, use recipe="hero" scene="none" interaction="depth" with a local image; for a scrolling image rail, use recipe="rail" scene="progress" with cards. The Motion showcase demonstrates the complete combination and links to its Markdown source. The Executive brief shows a Daylight decision page with evidence, timeline and handoff. Long sections reveal when reached even when they are taller than the screen.

Package controls provide icons automatically. Authored modal/popover and toggle labels stay visible on phones, and action groups wrap without forcing every button across the screen. Large-screen composition tracks remain separate from the paragraph reading measure; no per-page CSS is needed.

For a bilingual page, the primary entry declares language: en or language: ru and maps the other confined Markdown entry under localizations. Translate that variant's prose, partials, directive labels, and visible asset text; the package does not machine-translate. One artifact embeds both variants, selects the initial language from ordered system preferences, falls back to the primary, and shows the native language selector only when localization exists. Switching replaces content, metadata, navigation, chrome, visualizations, and locale-specific review/response state together.

language: en
localizations:
  ru: report.ru.md

Compose a filmed explanation

A composition arranges named Markdown objects as a diagram beside code, a pipeline, before/after, an overview with detail, or owners passing a value. Cues reveal, focus, connect, copy, transfer, replace, compare, move the camera, trace a directional pass and annotate code. A compatible Screencast report scene binds them to measured narration. Read the directing guide for complete source and existing effects, or open the first-edit example, two color paths and event delivery. The pinned release supports this vocabulary; filming also requires a compatible Screencast bridge. Named slots preserve stable owners, scene groups arrange related objects, and code annotations explain exact operations while keeping their source intact.

Every system interface first appears as its complete application screen, then the reader or viewer moves into a detail. Preserve the detail's location in a still page, presentation or film of any format. The guide provides the recipes.

Review and return feedback

Set review: true in the frontmatter to ship local Review Workspace annotations; an ordinary page is a plain document, and a build given a prior sidecar through --review enables them automatically. Select an eligible passage and choose Create note; the anchored popover opens with the exact quote and keeps reply, edit, resolve, and reopen beside the text. A selection may cross inline markup or adjacent review targets. Saved open/resolved ranges stay visibly distinct; hover/tap exposes View thread, and focusable markers provide the keyboard route. The topbar Review action opens only a non-reflowing overlay list, prior evidence, import, and one export of every thread. Single-language pages export deterministic version 3; multilingual pages export version 4 with the active report.locale and retain separate threads for each locale. Valid version-2 whole-block files remain accepted and list-accessible, but new threads begin with selected text. Desktop uses a non-modal list overlay; mobile uses a modal sheet. Nothing is uploaded or stored in an account; ordinary decisions and checklists remain static report content. Try the complete Review Workspace example or read its declarative source. The target manifest is bounded to 5,000 reviewable blocks and 750,000 serialized bytes; unusually large handoffs must stay under both limits or be split.

The anchored thread surface never moves report content on desktop or mobile; how it is placed, and how its markers and topbar icons behave, is in the Review Workspace reader interface.

An agent resolves the downloaded review against the current source with:

agentic-report review ./review.json ./my-page --json

The result names exact, changed, missing, or ambiguous entry/partial targets without rewriting Markdown.

Use build --review review.json for a follow-up artifact. Exact state resumes; stale threads are labelled prior exact/changed/missing/ambiguous evidence. Continuing a changed fragment appends a current revision segment to the same exported thread, retaining every prior user/agent message and resolution state.

When the reader must return typed values instead of discussion, use Response Workspace. It supports bucket triage, per-item and global choices, priority ordering, bounded scores, free text, and sparse item comments. The page keeps state only in the current tab and exports the same deterministic response through clipboard and file download. Open the complete live example or inspect its English source and Russian source.

Use copyable when ordinary prose should be pasted elsewhere. It keeps Markdown typography/wrapping and copies only visible rendered text through the localized package control.

A Markdown table wraps its prose columns in the width of its column, and on a narrow track it turns each row into a card labelled with the column headers when its columns cannot fit readably. Wrap it in :::table{layout="stack"} to show cards on every narrow track, or :::table{layout="scroll"} to keep a wide numeric grid that scrolls sideways with its first column in view. Inline code wraps only between the parts of a path or identifier.

Output and operation

• single-file is the default: one portable HTML file with embedded local resources and runtime.
• directory writes index.html plus content-hashed resources for larger pages.
• Both formats open through normal file:// and preserve the same supported interactions.
• On the reference static host, mutable HTML, Markdown, and release metadata revalidate on every use; content-hashed directory assets alone receive a one-year immutable cache policy.
• Both formats show a bottom Made with Agentic Report link by default. Set root metadata attribution: false to omit only that package footer.
• Top-level ::contents keeps an exact compiler-generated section map in the article and on narrow screens; short section.nav labels remain exclusive to sidebar/mobile navigation.
• A section may start with one bounded :::lead paragraph. Appendix glossary definitions may be direct section children and compile into the existing ordered appendix without leaving an in-flow placeholder.
• A page served on the web declares its address as url (or build --url). The head gains a canonical link, OpenGraph with locale alternates and a Twitter card; an optional image becomes an absolute og:image in directory output. Build public pages as directory to keep the HTML under the 2,097,152 bytes search crawlers read; a larger public page reports PUBLIC_PAGE_OVER_CRAWLER_LIMIT.
• sitemap <directory> indexes a published tree of such pages: it writes sitemap.xml from their canonical URLs and a robots.txt naming it, and refuses without writing when a URL does not match the page's place in the tree or either file already exists.
• build --share derives path-free non-link filename/line text from each validated source helper, falls back to source:line for unsafe terminals, omits workstation paths and authored directory/free-form labels, and reports the exact count without editing Markdown.
• The compiler neither hosts nor deploys the result and never fetches remote source.

The public landing links to independently built bilingual starters, complete visual, interactive, and data catalogs, Terminal portfolio, Cinematic story, Executive brief, Motion showcase, decision showcases, and Review/Response workspaces. Every page uses the same declarative contract on its own layout and exposes its English and Russian Markdown sources from the landing.

Release identity

release.json records the package version, source revision, and hashes for the exact staged files. The hosted site is accepted only after ordinary trusted HTTPS, real route/MIME checks, and a real 404 prove that a static host is not serving a catch-all shell. Acceptance also verifies revalidation for mutable routes and immutable caching only for filenames carrying the compiler's content hash.