Platform Operations Handbook

Overview

This handbook describes the operational baseline for a multi-format document conversion platform. It focuses on repeatable execution, readable output, bounded fallbacks, and evidence-driven change control rather than pixel-perfect visual reproduction.

Readers who only need the release checklist can jump to the appendix, while implementers should also review the external runbook and the deployment contract.

Stable structure beats optimistic heuristics when the source format mixes headings, links, images, and noisy side material.

Info. The platform ships a native-first validation path and a documented fallback path for developer environments.

Documentation Shape

The typical conversion package contains at least five interacting structures:

top-level headings and local anchor links
nested procedures
1. prepare sample assets
2. run native validation
3. review output and metadata
inline code such as moon build --target native
tables with external references and operator notes
local figures and caption-like explanations

Warning. Ignore javascript links and data links during conversion.

Failure-mode checklist

Check malformed links, repeated navigation, entity decoding, and preformatted text boundaries.

Deployment

Production deployment uses a staged rollout. Teams publish a frozen build, update the registry cache, run a validation suite, and only then fan out to scheduled batch jobs.

moon build --target native
moon check
moon test
./samples/check.sh
./samples/check.sh --real-world --tags complex

On Windows hosts, the core native target is supported, but shell validation remains easier under WSL or another POSIX-like runtime.

Stage	Owner	Reference	Notes
Build	Release engineering	build policy	Prefer native CLI over wrapper timing.
Validate	Format owners	observability section	Capture metadata sidecars and asset refs.
Promote	Operations	promotion guide	Document deviations and explicit non-goals.

Observability

A good conversion trace keeps structure readable even when the input mixes dense lists, escaped entities like <sample>, and repeated section wrappers.

System overview diagram — Figure 1. Release-path overview with assets, metadata, and contracts.

The support bundle also includes a second visual artifact for chart references and a compact reminder that real-world samples do not imply broader performance claims.

Metrics trend chart — Figure 2. Trend chart for smoke validation and contract stability.

Appendix

Deployment Contract

Every release record should answer these questions:

Which checked-in corpora passed?
Which assets were emitted and where are they referenced?
Which format-specific boundaries remain explicit non-goals?