# Checking, formatting, and fixing mistakes

## Read a chapter in the terminal

```text
scorescript docs --list
scorescript docs first-score
scorescript docs connectors
```

The `docs` command prints one chapter as Markdown, without needing a network
connection. It is included in builds containing this wiki; an older installed
CLI may need updating. MCP readers can list the same chapters under
`scorescript://docs/`, starting with `scorescript://docs/index`.

## Check the actual file

```text
scorescript check piece.scorescript
scorescript format piece.scorescript
scorescript format piece.scorescript --write
scorescript render piece.scorescript -o piece.svg
scorescript pdf piece.scorescript -o piece.pdf
scorescript midi piece.scorescript -o piece.mid
```

Without `--write`, formatting reports canonical source without replacing the
file. Keep a saved revision before a broad edit. After formatting, check again
and inspect the rendered music. MIDI output is useful for checking sounding
duration and instrumentation but cannot certify printed spelling or layout.

## Read diagnostic severity

An error means the requested source was not fully understood or is
inconsistent. A warning can describe unfinished or ambiguous notation.
Information may explain a derived rest or other normal completion.
Read the code, location, and message together; do not just look for a green
preview, since the engine can draw the portions it did understand.

## Common mistakes

| Symptom | Check |
| --- | --- |
| A note is in the wrong octave | The previous pitch, apostrophe/comma, and first-note octave anchor |
| A rhythm exceeds the bar | Sticky duration, dotted values, tuplet ratio, and current meter |
| Eight bars of rest instead of an eighth rest | `r8` versus `8r` |
| Several short slurs instead of one long slur | Mark only the opening and closing endpoint |
| A chord becomes a label | Preserve its duration and use clear bracketed pitch members |
| Text lands on the other side | Before the node is above; after is below for text/dynamics |
| Extra silent measures | Addressed range gaps and misplaced physical row breaks |
| A dynamic prints but does not sound as expected | Playback interpretation and the selected sound source |

## What formatting does

It normalizes accepted duration spellings, groups measures compactly, anchors
the first sounding pitch of each authored section and voice, and condenses equivalent timeline points
into maps where useful. It preserves the selected sanctioned arrangement and
the order of chord members. Formatting is not a substitute for choosing the
right musical notes.

Plain formatting is not automatic musical consolidation. The
[normalization menu](normalization.md) separately controls orientation, maps,
duration spelling, whitespace density, shared readers, and named reuse.

## Import and export

The native reader can import MusicXML and the exporter can produce MusicXML
for interchange. Check diagnostics and the full piece after a conversion;
another notation program can carry constructs that this engine cannot yet
represent. A successfully opened first page does not prove every part or
movement survived.

```sh
scorescript import source.musicxml -o piece.scorescript
scorescript check piece.scorescript
scorescript musicxml piece.scorescript -o roundtrip.musicxml
```

Installation, editor connections, and host APIs are covered in
[integration](integration.md). Website display is covered in [embedding](embedding.md).

## Unsupported or limited notation

Do not assume that arbitrary drum-kit pitch names, multi-staff `rh:`/`lh:`
instruments, cue-note styling, arpeggio roll marks, or alternating two-note
tremolo have a supported compact spelling. Figured bass and custom lines
have the limits described in their chapters. Named bracket lines and
navigation can have rendering or playback limitations. Treat a diagnostic
or render report as part of the result, and verify the delivered pages and
audio for the features you use.

For AI-assisted writing, use this same wiki and the actual compile/format
tools. Supply complete source and address the exact file, movement, part,
and measures being edited. Never substitute a similar instrument or score
revision because its filename looks close.