The last mile: which file, and what it will look like

A build turns the run's document and its two ledgers into files. It is not a check of the document: a build can succeed on a sentence nothing has read. This is the skill that says which file leaves the run, and the one that must not let a clean build be mistaken for a verified one.

Ask what this build writes — never carry the list in your head

rs_open action=capabilities is the authority: it names the formats this build can write and the six citation styles it renders. Formats and styles arrive over time, so a list remembered from a previous session is the one thing guaranteed to go stale.

rs_open action=capabilities

What each format is FOR, so the right file leaves the run:

• md — the reader-ready source. Citations resolved by the style, the reference list computed from the ledger, and in a draft the claim endnotes visible as footnotes. Read this one yourself, and hand it to anything that reads Markdown.
• docx — the submission. A real Office document built from the same Markdown by this package's own OOXML writer: no process is spawned, no engine is looked for on PATH, and two builds of one run are byte-identical. That determinism is what makes a diff of two DOCX builds mean something.
• html — one self-contained page: the CSS inline, so no stylesheet URL, no font, no script and no remote image. For a reader who has no Word, and for printing from a browser on a machine with no network.
• ris / bib / enw — the run's whole LIBRARY, not only the part this draft cites, in formats Zotero, EndNote and pandoc import. A complete export someone prunes is more useful than one they have to reconstruct — and rs_cite action=import reads those exports back, so a library can move both ways.
• tex — writes paper.tex and prints the command that compiles it. Nothing is run here: a .tex is for a machine with its own LaTeX toolchain, and the build answer says what to run.

format=all writes every format this build has, in one call, from one parse — so a sentence, a citation or a footnote cannot be in the .docx and missing from the .html. A format that is advertised but not implemented in your build refuses by name (FORMAT_NOT_YET), which is the answer that names what it can write, and writes nothing.

Six styles, and a reference list you never type

The run's style is recorded at rs_new (style=) and overridden for a single build with rs_build style= — that is how one run is submitted to two journals without re-citing anything. What the style decides:

• APA 7, Chicago author-date, Chicago notes, MLA 9 sort the list alphabetically; IEEE and Vancouver number it in citation order.
• Chicago notes is the one notes style: its citations are footnotes rather than parentheticals, so the sentence stays unbroken and the reference list still stands.
• The list is headed by the style's own referenceHeading — Works Cited is not a synonym for Bibliography — and the DOCX and HTML writers use that heading to find where the bibliography starts, so an entry after it keeps its hanging indent.

The reference list is computed from the ledger, never typed. There is nowhere to put a citation by hand, and a hand-edited built file is overwritten by the next build. So a missing field in a source record is a missing field in the bibliography: the fix is rs_cite again with the field, not a sentence added to the artifact.

Two drafts, and the difference is the whole point

draft=watermark (the default) always builds. It writes a banner at the top and an endnote on every claim naming its status and the rung it reached, so a half-checked document cannot be read as a finished one. Use it while you are still working, and to show someone what the run currently says.

draft=clean is the mode whose output looks finished, so it is the one that refuses — for exactly three reasons, each with its own code:

• the document and its ledger disagree (BUILD_BLOCKED, and the message names the structure code and the claim, e.g. span-unrecorded);
• a claim a check found unsupported, contradicted or misattributed is still in the text (BLOCKING_CLAIMS);
• a person has not answered gate g3-integrity (GATE_UNANSWERED) — this call opens that gate, and only the person answers it, in the Research tab.

Say which of the three it was, and what would clear it — then stop. Retrying the same call changes nothing, and answering the gate yourself is the one thing this plugin refuses to let a model do.

One run, built twice

format=all as a draft, then the clean build for hand-over:

rs_build slug=sleep-memory-review format=all draft=watermark

Built sleep-memory-review (watermark, apa7)
- document: sections, 27 words
- claims: 1 (1 unverified)
- sources: 2 in the ledger, 1 cited, 1 with text
- structure: agrees with the ledger
- note: the outline names `synthesis`, which has no file in doc/sections/

Files:
  build/paper.md  860 B  sha256 d491860e3045…
  build/references.ris  430 B  sha256 244f8c30a0dd…
  build/references.bib  496 B  sha256 ed9f0fe42ae3…
  build/references.enw  370 B  sha256 34cfdc38f1d3…
  build/paper.docx  4.9 KiB  sha256 9895a1c4b2ed…
  build/paper.html  2.8 KiB  sha256 ebe6dbfcc104…
  build/paper.tex  1.4 KiB  sha256 6f977c7915a5…
  build/build.json  (the report above, stored)

This is a DRAFT: the banner and the endnotes are what say so. `draft=clean` needs the
document and its ledger to agree, no unsupported claim, and gate `g3-integrity`
answered - it is waiting in the Research tab.

A - note: line is not a failure: that one is the outline warning about a section with no file. Errors are separate, and they are what block a clean build.

rs_build slug=sleep-memory-review format=docx draft=clean

Built sleep-memory-review (clean, apa7)
- document: sections, 27 words
- claims: 1 (1 unverified)
- sources: 2 in the ledger, 1 cited, 1 with text
- structure: agrees with the ledger
- note: the outline names `synthesis`, which has no file in doc/sections/
- note: docx line 9: a raw HTML comment is not Markdown this writer renders

Files:
  build/paper.docx  4.6 KiB  sha256 bbef034114c4…
  build/build.json  (the report above, stored)

The second build is smaller than the first on purpose: clean removes the banner, the claim markers and the endnotes. Note also that a clean build still says 1 unverified — it is not a claim that the content was checked, only that nothing in the document contradicts the ledger.

And the refusal, which is the reason to read the ledger before asking for clean:

Refused (BUILD_BLOCKED): a clean build needs a document that agrees with its ledger,
and these do not: span-unrecorded (claim c0999 is marked in the document but has no
ledger row - it is tracked by nothing). Build with draft=watermark to read the draft
anyway.

build/build.json — what was handed over, on disk

Beside every artifact, and readable with rs_read what=build, it records the format, the draft mode, the style, the document's source and word count, the sha256 of the assembled document, the claim counts by status at that moment, the source counts, the structure verdict, and every output's path, bytes and sha256. That is what makes "which claims had been checked when this file went to the reviewer?" a question about the folder rather than about anyone's memory.

Two honest limits: it is written fresh by each build, so it describes the most recent one — and after format=all it holds the last format's report. The Files: list in the build answer is the complete record of an all build; the report beside the artifacts is not.

When this build's output is not what is wanted

Both escape hatches keep the ledger as the source of truth:

• A house citation style this package does not implement is not a rewrite. Every style's list is available as references.bib, which Zotero, EndNote and pandoc all read: run pandoc with the journal's own CSL file over the exported .bib and the .md, and the bibliography is in their style. Nothing in the run has to change.
• A LaTeX submission gets paper.tex plus the command to compile it, on a machine that has the toolchain. This plugin runs no engine and looks for none.

The DOCX limits, stated rather than discovered

Say these before promising a DOCX meets a submission rule:

• IEEE is single column. The two-column layout is not emitted; a two-column page built without the rest of that template's rules would be worse than an honest single-column one.
• Page setup is Letter with 1-inch margins for every style (APA 7 pins exactly that; the other styles pin none, so it is a deliberate uniform choice).
• A construct outside the Markdown subset is REPORTED with its line number, not dropped — nested emphasis inside emphasis, list nesting past one level, indented code, setext headings, raw HTML. So when the build report names a line, the artifact is missing something: fix that sentence in the document and build again. Accepting the file is accepting a document nobody has seen.

Before you say the file is ready

Run rs_verify action=report, and say which rungs reached what. A clean build is not a check of correctness: it means the document agrees with its ledger, that no claim a check found unsupported is still in the text, and that a person said the run had been checked as far as they need it. It says nothing about whether a source exists or a sentence is true — r1-record is provenance, and r2/r3 only ask whether the stored words are there and whether they support the sentence as written.