3x CLI and Format Reference

Commands, fields, content shapes, and automation behavior

The exact interface for authoring and generating 3x manuals. Return to the scheme guide for the underlying method.

Python 3.9+JSON SchemaNo packages required

The 3x reading contract: every entry explains what it does, how it works, and why it works that way.

No entries match that search.

CLI Commands

Run every command from the repository root with Python 3.9 or newer.

init

scaffoldwrite

Create a new manual source with the required structure and visible writing prompts.

python3 scripts/manual.py init OUTPUT [--name NAME] [--force]

What it does

Writes an editable JSON source containing project metadata, theme defaults, one section, and one entry. Its triad contains unfinished-writing prompts and therefore does not pass validation until adapted.

How it works

OUTPUT selects the new JSON file.
--name sets the project name and derives a starter entry ID.
--force permits intentional replacement of an existing target.

Why it works this way

A complete structural example is faster and less error-prone than starting from an empty file. Deliberately failing prompts prevent the scaffold from being mistaken for finished documentation.

Evidence

scripts/manual.py scripts/manual.py
tests/test_manual.py tests/test_manual.py

check

validateCI

Validate a source without creating an output artifact.

python3 scripts/manual.py check SOURCE [--set PATH=VALUE ...]

What it does

Reports structural errors and quality warnings, prints coverage counts, and exits nonzero when errors exist.

How it works

The command loads JSON, applies overrides, resolves placeholders, validates the complete model, and writes diagnostics to standard error. A successful summary is written to standard output.

Why it works this way

A read-only validation command fits editor hooks, pre-commit checks, and CI without creating generated-file churn.

Evidence

scripts/manual.py scripts/manual.py
tests/test_manual.py tests/test_manual.py

build

renderHTML

Validate and render a standalone HTML manual.

python3 scripts/manual.py build SOURCE [--output FILE] [--set PATH=VALUE ...]

What it does

Creates the requested HTML file only when the prepared source has no validation errors. The default output is manual.html.

How it works

After validation, the renderer escapes source text, applies safe inline formatting, embeds presentation and search behavior, creates parent directories as needed, and writes one UTF-8 file.

Why it works this way

Validation-before-write prevents a failed build from presenting a newly generated incomplete artifact as current documentation.

Evidence

scripts/manual.py scripts/manual.py
tests/test_manual.py tests/test_manual.py

watch

previewdevelopment

Rebuild whenever the source file changes.

python3 scripts/manual.py watch SOURCE [--output FILE] [--set PATH=VALUE ...]

What it does

Monitors the source modification time, performs an initial build, and repeats the build after each saved change until interrupted.

How it works

A small polling loop checks the file twice per second. If the source temporarily disappears during an editor's atomic save, the command waits for it to return.

Why it works this way

Fast feedback makes structural writing and visual review feel like one task while retaining a zero-dependency implementation.

Evidence

scripts/manual.py scripts/manual.py

Source Format

The JSON Schema is authoritative; these entries explain how its pieces are intended to be used.

Root and metadata fields

JSONmetadata

A manual combines project identity, document identity, optional theme values, and sections.

What it does

Defines the top-level project, manual, theme, and sections values. An optional $schema field lets compatible editors locate the contract.

How it works

project requires name and version and may contain other scalar placeholder values.
manual requires title and may add subtitle, description, badges, and footer.
theme may set six-digit accent and accent_secondary colors plus a short icon.
sections is a nonempty ordered array.

Why it works this way

Separating project identity from document metadata supports multiple manuals for one project and keeps release values reusable.

Evidence

scheme/manual.schema.json scheme/manual.schema.json
scheme/example.manual.json scheme/example.manual.json

Section fields

navigationgrouping

Sections create ordered navigation groups around reader-oriented concepts.

What it does

Each section requires a stable id, a title, and at least one entry. It may include a short description.

How it works

IDs use lowercase kebab-case and share one namespace with entry IDs. Array order controls both sidebar and document order.

Why it works this way

Stable identifiers make links durable while explicit order lets authors teach a subject progressively rather than accepting an alphabetical or filesystem-derived sequence.

Evidence

scheme/manual.schema.json scheme/manual.schema.json
scripts/manual.py scripts/manual.py

Entry fields

triadcontent

Entries hold one documented subject and its complete 3x explanation.

What it does

Requires id, title, what, how, and why. Optional fields are summary, synopsis, tags, evidence, and related.

How it works

Use summary for the one-sentence orientation shown before the triad.
Use synopsis for a literal command, API, signature, or compact contract.
Use tags for filtering vocabulary and evidence for supporting targets.
Use related to list stable entry IDs in reading order.

Why it works this way

The required core guarantees a useful minimum. Optional context supports discovery and verification without making every subject pretend to be a command or source-code component.

Evidence

scheme/manual.schema.json scheme/manual.schema.json
scheme/example.manual.json scheme/example.manual.json

What, How, and Why shapes

content shapetriad

A dimension can be prose, ordered points, or a lead paragraph followed by points.

What it does

Accepts a nonempty string, a nonempty array of strings, or an object containing lead, points, or both.

How it works

Strings render as paragraphs. Arrays render as ordered lists. Objects render lead as a paragraph and points as an ordered list.

Why it works this way

A small set of semantic shapes covers most technical explanations while remaining predictable for validation, transformation, and agent generation.

Evidence

scheme/manual.schema.json scheme/manual.schema.json
scripts/manual.py scripts/manual.py

Evidence and related fields

provenancelinks

Evidence records provenance; related IDs create lateral navigation.

What it does

Evidence accepts either a target string or an object with label and target. Related accepts an array of entry IDs.

How it works

Local evidence targets render as code-like paths and HTTP targets render as links. Related IDs resolve to entry titles and local anchors; unknown IDs produce warnings.

Why it works this way

Keeping provenance structured enables future renderers and audits while allowing concise input for the common file-path case.

Evidence

scheme/manual.schema.json scheme/manual.schema.json
scripts/manual.py scripts/manual.py

Processing Rules

Preparation is deterministic: overrides, placeholders, validation, then rendering.

Overrides and placeholders

variablesrelease automation

Scalar configuration can flow from source metadata or the build command.

--set project.version=2.1.0 --set 'theme.accent=#ff6b35'

What it does

Overrides existing dotted paths and resolves double-braced dotted-path placeholders in all strings.

How it works

Values that parse as JSON scalars retain their types; other values remain strings. Paths must already exist, placeholders must resolve to scalars, and unknown paths stop processing.

Why it works this way

Existing-path enforcement catches spelling mistakes and prevents command-line options from silently inventing configuration the schema does not describe.

Evidence

scripts/manual.py scripts/manual.py
tests/test_manual.py tests/test_manual.py

Errors and warnings

diagnosticsquality

Errors reject the document; warnings flag concerns that still need contextual judgment.

What it does

Treats invalid JSON, missing required values, unknown fields, malformed IDs, duplicate IDs, invalid content shapes, empty dimensions, and recognized writing placeholders as errors. Missing evidence and unknown related IDs are warnings.

How it works

Diagnostics include a JSON-like location so authors and agents can identify the affected section, entry, or field. The process exits with status one when errors exist.

Why it works this way

A deterministic validity boundary makes automation dependable, while warnings keep nonmechanical quality issues visible without blocking early discovery work.

Evidence

scripts/manual.py scripts/manual.py
tests/test_manual.py tests/test_manual.py

Safe inline notation

securityformatting

A deliberately small formatting vocabulary improves readability without accepting raw HTML.

What it does

Supports backticks for code, double asterisks for strong text, single asterisks for emphasis, and Markdown-style links to HTTP, email, relative, or local-anchor targets.

How it works

The renderer escapes source text first, recognizes only the supported patterns, validates link schemes or relative paths, and leaves unsupported markup visible as text.

Why it works this way

Restricting markup keeps generated manuals portable and reduces injection risk while preserving the inline conventions technical authors use most often.

Evidence

scripts/manual.py scripts/manual.py
tests/test_manual.py tests/test_manual.py

Generated output contract

artifactbrowser

HTML is a disposable artifact; JSON remains the source of truth.

What it does

Emits semantic headings, stable anchors, sidebar navigation, client-side search, responsive layouts, evidence details, related links, and print rules in one file.

How it works

CSS and a small search script are embedded. Content remains usable without a server or network connection, and narrow screens stack triad columns into a single reading flow.

Why it works this way

Treating HTML as generated prevents hand edits from diverging from machine-readable content and makes alternate renderers possible later.

Evidence

scripts/manual.py scripts/manual.py
index.html index.html
commands.html commands.html