Export the publication-ready DOCX

Who does this: FS Reviewer · Senior Accountant · Platform Admin (not FS Preparer — by SoD design) When: Notes are complete and you want a downloadable Word document for client review or final publication. Result: A .docx artifact in S3 with a signed URL. The engagement remains at NOTES_COMPLETE. Multiple exports are allowed; each is a separate version.

The exporter asserts three things before writing bytes:

1. The latest FsGeneratedStatement.isBalanced = true (or banner-warns on the cover, where an explicit reviewer override has been set).
2. Every triggered mandatory disclosure rule has every required prompt answered.
3. The mandatory policy text in note_policies matches the constitution mandatory_policies/*.md verbatim.

Any of these fails → 422 Unprocessable Entity with the typed reason. No artifact is produced.

Before you start

• [ ] Engagement at NOTES_COMPLETE.
• [ ] You hold EXPORT_FS_DOCUMENT — FS_REVIEWER, SENIOR_ACCOUNTANT, or PLATFORM_ADMIN. FS_PREPARER is rejected here.

Steps

1. Open the engagement detail page.
2. Click Export Word in the top right.
3. The handler enqueues export-statements-docx. The UI shows a polling indicator.
4. After ~5–15 seconds the download appears in the Exports panel with a signed URL. Click to download.

How to know it worked

1. A .docx lands in S3 at financial-statements/<clientId>/<engagementId>/<filename>-v<n>.docx.
2. The activity log shows fs.export.generated with the file id, signed URL, and version.
3. Open the DOCX in Word. Spot-check:
   • Cover page has the correct legal name, year-end, UEN
   • Running header: company on the left, year-end on the right, thin border
   • Directors Report contains the Financial Results table at the expected position
   • Notes are auto-numbered starting from 1
   • The income-tax paragraph matches constitution/mandatory_policies/income_tax.md verbatim

Common situations

If you see…	It means…	What to do
422 reason: "engagement_not_balanced"	The Statement of Financial Position is not balanced	Regenerate statements after fixing the mapping. See Export blocked: unbalanced
422 reason: "mandatory_disclosure_missing"	A triggered mandatory rule has a required prompt unanswered	Open Interrogation; complete; re-export
422 reason: "mandatory_policy_mismatch"	A note's policy paragraph drifted from the constitution	Regenerate notes. See Policy mismatch
Export refused with 403 Forbidden	Caller does not hold EXPORT_FS_DOCUMENT	FS_PREPARER cannot export — pass the engagement to a reviewer
The download link expires	S3 signed URL has a 1-hour lifetime by default	Re-export; the resulting artifact is a new version but functionally identical
Notes renumber unexpectedly	Notes are auto-numbered alphabetically by note_key then re-ordered by section	Verify the note_key slugs in FsNote rows; if a key drifted, regenerate notes

Related runbooks

• Dispatch the FS portal link — send the DOCX to the client for sign-off
• FS-07 userflow
• Financial Statements SOP §6 / Step 7.0
• Export blocked: unbalanced
• Mandatory policy mismatch