Reformat Markdown docs with mdformat-all

[lodyai]

Summary

Runs make fmt (which applies mdformat-all = mdtablefix + markdownlint-cli2 --fix) across the documentation tree and commits the result. Twelve Markdown files under docs/ are reformatted.

The changes are pure formatting — prose and list items re-wrapped to the house width, and long inline code spans pulled onto their own lines. No prose meaning, headings, links, ordered-list numbering, or Mermaid diagrams change. In a few places the formatter corrects previously broken code-span wrapping (e.g. closing backticks that had drifted to the start of the next line).

Inspection findings

I reviewed every hunk for semantic breakage and new lint violations:

• No semantic breakage in any of the 12 files. Every change is a re-wrap or a code-span moved onto its own line; meaning is preserved throughout.
• 4 newly-introduced MD013 (line-length > 80) violations — the only incorrect output. All share one root cause: mdtablefix --wrap places an unbreakable inline code span (a full type signature or a pytest invocation) on its own line, overflowing the 80-column limit, and markdownlint --fix cannot auto-fix MD013. These files passed markdownlint cleanly at HEAD, so the reformat introduced them:
  • docs/execplans/2-3-3-generate-guest-bios-from-reference-document-bindings.md:177 (86)
  • docs/execplans/4-1-2-finalize-rest-surfaces.md:772 (100), :782 (87), :859 (119)

Resolution

Added four <!-- markdownlint-disable-next-line MD013 --> guards immediately above the offending spans. Verified that mdtablefix preserves the guard lines and leaves the guarded spans untouched, so make fmt is idempotent (a second run produces no diff).

Gates

• make markdownlint — 0 errors.
• make nixie — all Mermaid diagrams validated (passes outwith the Chrome sandbox; under the sandbox every diagram times out because headless Chrome cannot launch — unrelated to this change, it fails the same way on untouched files).

Follow-up worth considering

The mdtablefix ↔ MD013 conflict will recur for any future doc containing an inline code span longer than ~78 characters. Options: raise MD013.line_length, teach mdtablefix to break before/after long atomic spans, or keep using per-line guards as here.

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 2500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3e16e73f-dfb0-46e7-9b54-3c1e6484bc22

📥 Commits

Reviewing files that changed from the base of the PR and between 792210b and 0103573.

📒 Files selected for processing (5)

• docs/developers-guide.md
• docs/episodic-podcast-generation-system-design.md
• docs/execplans/2-2-2-migration-tooling-with-alembic.md
• docs/execplans/4-1-2-finalize-rest-surfaces.md
• docs/users-guide.md

👮 Files not reviewed due to content moderation or server errors (5)

• docs/users-guide.md
• docs/developers-guide.md
• docs/episodic-podcast-generation-system-design.md
• docs/execplans/2-2-2-migration-tooling-with-alembic.md
• docs/execplans/4-1-2-finalize-rest-surfaces.md

---

Markdown documentation reformat using mdformat-all across five documentation files. Prose and list items are re-wrapped to the house width standard, and long inline code spans are moved to their own lines. No semantic changes to content, headings, links, ordered-list numbering or Mermaid diagrams.

Files affected:

• docs/developers-guide.md
• docs/episodic-podcast-generation-system-design.md
• docs/execplans/2-2-2-migration-tooling-with-alembic.md
• docs/execplans/4-1-2-finalize-rest-surfaces.md
• docs/users-guide.md

MD013 violations: Four line-length violations introduced by mdtablefix were manually resolved with <!-- markdownlint-disable-next-line MD013 --> guards (in 2-3-3-generate-guest-bios-from-reference-document-bindings.md and 4-1-2-finalize-rest-surfaces.md). The reformat is idempotent and passes all linting gates.

Total changes: +86 lines / −83 lines

Walkthrough

This pull request reformats and rewraps content across five documentation files without introducing code changes or altering functional contracts. REST pagination schemas, observability port abstractions, system design API specifications, execution plan milestones, and user guidance are restructured across multiple lines and adjusted for readability and consistency.

Changes

Documentation reflow and formatting

Layer / File(s)	Summary
Developer architecture and observability contracts docs/developers-guide.md	REST pagination response shapes, observability port abstractions (MetricsPort canonical typing versus feature-specific bounded protocols), and Chrono latency recording constraints are reformatted. The MetricsPort contract now explicitly distinguishes collections.abc.Mapping[str, str] from narrower dict[str, str] bounds in feature ports. LLM token estimation and architecture enforcement group documentation are rewrapped whilst preserving stated constraints.
API specifications and execution plan documentation docs/episodic-podcast-generation-system-design.md, docs/execplans/2-2-2-migration-tooling-with-alembic.md, docs/execplans/4-1-2-finalize-rest-surfaces.md	Pagination and error response envelopes are reformatted as structured multi-line JSON objects. Execution plan milestones (progress narratives for milestones 2, 3, 4, 5, and 8), outcome evidence paths, deviation notes, and quality gate checklists are rewrapped across lines. Inline code formatting is added to Constraints section references. Asyncio code snippet spacing is normalised.
User-facing token budget guidance docs/users-guide.md	The OpenAICompatibleLLMConfig(chars_per_token=...) calibration instruction is reflowed across multiple lines without changing the meaning or stated validation constraints.

Possibly related issues

• Align Markdown documents with make fmt formatter output netsuke#316: Both PRs apply documentation-only reflows and line-wrapping edits to align Markdown files with formatter or linting expectations rather than alter code functionality.

Possibly related PRs

• leynos/actix-v2a#35: Updates to docs/developers-guide.md regarding repository orientation guidance overlap with canonical repository layout guidance edits.

Poem

📚 A tidy reflow of docs so precise,
Pagination schemas reformatted nice,
Metrics ports clarified, milestones in view,
Line-wrapped with care—nothing broken, just new. ✨

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and accurately summarises the main change: reformatting Markdown documentation files using mdformat-all tooling.
Description check	✅ Passed	The description thoroughly relates to the changeset, detailing the formatting changes across twelve documentation files and addressing linting issues introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Testing (Overall)	✅ Passed	This PR contains only documentation formatting changes (5 .md files modified). No functionality or behavioural changes introduced; hence, no tests are required. Testing check does not apply.
User-Facing Documentation	✅ Passed	Pure markdown formatting with no prose meaning or functionality changes. Only line-wrapping and code-span adjustments. No new user-facing functionality to document.
Developer Documentation	✅ Passed	Pure documentation formatting PR. No new APIs, architectural changes, or semantic modifications to content. Roadmap item 4.1.2 marked complete. No multilingual docs require synchronisation.
Module-Level Documentation	✅ Passed	PR modifies only Markdown documentation files (docs/*.md), not Python modules. The custom check for module-level docstrings does not apply.
Testing (Unit And Behavioural)	✅ Passed	Documentation-only formatting PR with no code changes, no exported entity alterations, and no changes to public contracts. Unit and behavioural tests are not applicable.
Testing (Property / Proof)	✅ Passed	PR contains only documentation formatting (mdformat-all) with no code changes, invariant introductions, or proof assumptions—property tests/formal proofs unnecessary.
Testing (Compile-Time / Ui)	✅ Passed	PR applies markdown formatting only; no compile-time code or UI-output generation introduced. Existing make markdownlint and make nixie validation gates are appropriate.
Unit Architecture	✅ Passed	PR modifies only documentation Markdown files with formatting changes; no source code changes that could impact Unit Architecture principles.
Domain Architecture	✅ Passed	Documentation-only PR applying automated Markdown formatting. No source code files modified; domain architecture check is inapplicable to documentation formatting.
Observability	✅ Passed	PR reformats documentation files only; no operational code or behaviour changes exist, so observability requirements do not apply.
Security And Privacy	✅ Passed	Pure documentation formatting with mdformat-all; no secrets, credentials, sensitive data, or security-policy changes introduced. All existing credential examples use legitimate placeholders.
Performance And Resource Use	✅ Passed	This PR reformats Markdown documentation files exclusively using mdformat-all; no application code logic, algorithms, or resource-allocation patterns are modified.
Concurrency And State	✅ Passed	PR contains only documentation formatting changes (mdformat-all) with no code modifications; concurrency check is not applicable to pure documentation rewrites.
Architectural Complexity And Maintainability	✅ Passed	This PR contains documentation-only formatting changes with zero code modifications, new abstractions, interfaces, or dependencies—the custom check is not applicable.
Rust Compiler Lint Integrity	✅ Passed	This is a Python project with no Rust code. The PR reformats Markdown documentation and config files only. The Rust compiler lint integrity check does not apply.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/reformat-markdown-mdformat-all

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}