---
name: preview
description: "Paved command paved.preview. Open a local review of a Markdown file or folder where a person comments on selected text across its documents."
---
<!-- Generated by Paved plugin paved@2.0.0 from paved.preview; edit Paved Core instead. -->
# Paved `preview` command (paved.preview)

Open a local review of a Markdown file or folder where a person comments on selected text across its documents.

**Input:** A Markdown file or a folder of Markdown files, and a preview operation.
**Output:** Loopback preview URL, the reviewed documents, and comments with their document, status and revision.
**Required lifecycle:** RESOLVED, GENERATED, VALIDATED, READY
**Required context:** Markdown file or folder in the project
**Required capabilities:** none declared
**Allowed side effects:** local loopback preview server, .paved/generated/previews/

## Execution contract

1. Invoke `node "<plugin root>/scripts/paved.mjs" preview --json` from the repository root, passing the user's command inputs as supported CLI arguments. The launcher loads the pinned project-local runtime and returns the canonical structured result. `<plugin root>` is the installed Paved plugin directory, two directories above this SKILL.md. Always run the launcher from the repository being worked on, never from the plugin directory.
2. Follow the structured result's status, diagnostics, evidence, and next action. Stop when the runtime blocks execution.
3. Start with `paved preview start <target> --json`, where the target is one Markdown file or a folder whose Markdown files are reviewed together (an epic and its tasks, a plan and its specs). Give the returned URL to the user.
4. Keep the review active: call `paved preview wait <target> <revision> --json`, starting with the revision from `status`, and follow its `next_action`. A timeout means call `wait` again immediately, because comments reach you only while `wait` runs. Each comment names its `document`. For each one: run `paved preview working <target> <comment-id> --json`, edit that document, then run `paved preview resolve <target> <comment-id> --reply "<what changed>" --json`. Never resolve before applying the change, and ask in the conversation when a comment needs a fact you do not have.
5. The preview approves nothing. Keep waiting until the user says in the conversation that the review is finished; ask any approval or confirmation there.

## Failure behavior

- A comment on a stale document version is refused.
- The preview approves nothing; approvals and confirmations are asked in the conversation.
- A folder with no Markdown files, or more than the limit, is refused.
- If a required ToolImplementation or runtime is unavailable, stop and explain the missing prerequisite. Never infer or execute a command from repository scripts.
- Do not edit human-owned Paved state or bypass lifecycle, ownership, approval, or verification gates.

## Conversational contract

1. Invoke the command. If it returns `"status": "awaiting_input"`, it is waiting on the user.
2. Present every decision in `decisions[]` to the user: what Paved detected, what
   remains to decide, why it matters, the options, Paved's recommendation and its evidence.
3. Collect the user's answer. Do not answer on their behalf.
4. Resume the same command with `--answer <decision-id>=<value> --answered-by <identity>`,
   repeating `--answer` once per value for a multi-choice decision.
5. Present the result.

Follow `core.decisions.decisions` for the full interaction protocol and its prohibitions.