[jpage-godaddy]

Summary

• guide <topic> human output now joins hard-wrapped paragraph and list-item lines into single lines before handing the markdown to termimad, so text fills the terminal width no matter how the guide source was wrapped.
• The pass is conservative: anything it doesn't positively recognize as flowing prose keeps its authored line breaks. That covers fenced/indented code (including fences opened on a list-marker line), headings and setext underlines, thematic breaks, tables, block quotes, HTML blocks (<pre>/<script>/<style>/comments run to their closing delimiter, blank lines included), link reference definitions (compact and multi-line), empty list items, and explicit hard breaks (trailing \ or two spaces).
• --output json / --output toon still return the raw markdown byte-for-byte.
• docs/concepts.md ("Guides → Rendering and authoring") previously told authors to write one line per paragraph; it now describes the reflow and its edge cases.

The logic lives in the new cli-engine/src/guide/reflow.rs and is applied in render_guide_human.

Test plan

• 25 unit tests for the reflow rules, including idempotence and a regression case for each review finding (refined during review)
• End-to-end Cli::run test: human output joins wrapped paragraphs and keeps code block breaks; json output stays verbatim
• cargo fmt --all --check, cargo clippy --all-targets -- -D warnings, cargo doc, cargo test --all-targets, cargo test --doc, check-module-size.sh

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Unresolved Markdown boundary handling can alter content and structure that the reflow pass promises to preserve.

4 open issues

• Preserve HTML blocks across internal blank lines · New
• Preserve empty list items as separate entries · New
• Reject over-indented closing fences inside code blocks · New
• Preserve compact and multiline reference definitions · New

What changed in this PR

This PR adds Markdown preprocessing to human-readable guide output so hard-wrapped prose can fill the terminal width, while leaving JSON and TOON output unchanged.

Changes:

• Join paragraph and list-item continuation lines before rendering with termimad.
• Add unit and integration tests for reflow and raw-output preservation.
• Update guide-authoring documentation to describe reflow behavior and exceptions.

File	Description
cli-engine/​tests/​foundation.rs	Tests human reflow, code-line preservation, and unchanged JSON output.
cli-engine/​src/​guide/​reflow.rs	Implements Markdown reflow and focused unit tests.
cli-engine/​src/​guide.rs	Applies preprocessing to human guide rendering and updates rustdoc.
cli-engine/​docs/​concepts.md	Documents reflow rules and renderer limitations.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Unresolved Markdown classification issues can merge list entries, remove heading boundaries, and concatenate fenced code.

3 open issues

• Preserve fenced code blocks after list markers · New
• Recognize short and trailing-space Setext underlines · New
• Preserve Markdown lists separated by tabs · New

4 resolved since last review

• Preserve compact and multiline reference definitions
• Reject over-indented closing fences inside code blocks
• Preserve empty list items as separate entries
• Preserve HTML blocks across internal blank lines

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Unresolved list-container and fence-indentation handling can merge code or preformatted lines in human guide output.

No open issues 🎉

3 previously missed issues

In code that hasn't changed since last review

Preserve indented code immediately after list markers

cli-engine/​src/​guide/​reflow.rs:101

A list item can begin directly with indented code, but this branch queues it as prose. For example, * echo first\n echo second\n echo third\n becomes * echo first echo second echo third\n, merging separate code lines before human rendering. Detect code indentation relative to the list item's content column, including the five-spaces-after-marker form, and preserve the code lines verbatim. Add a regression test that also checks ordinary wrapped list prose still joins.

Preserve HTML blocks opened within list items

cli-engine/​src/​guide/​reflow.rs:101

HTML blocks opened after a list marker enter this branch as prose because raw-block detection examines the whole line. For example, * <pre>\n first\n\n second\n third\n </pre>\n becomes * <pre> first\n\n second third\n </pre>\n, removing preformatted line breaks. Recognize HTML block openers in the list item's content and preserve them through their closing delimiter, including internal blank lines. Add regression coverage for this form while keeping HTML-like text inside indented code verbatim.

Limit closing fence indentation relative to container

cli-engine/​src/​guide/​reflow.rs:262

With a top-level opener indented three spaces, this limit becomes six, so a four-space fence-like code line is accepted as a closer. For example, ```\n ```\necho first\necho second\n ```\n has its two echo lines joined even though both are inside the original code block. Closing-fence indentation is limited to three spaces relative to the enclosing container, not three additional spaces beyond the opener. Track container indentation separately and add a regression test with an indented opener and a four-space fence-like line.

3 resolved since last review

• Preserve Markdown lists separated by tabs
• Recognize short and trailing-space Setext underlines
• Preserve fenced code blocks after list markers

_{Review effort: Balanced}