template-based-document-generation

Template-Based Document Generation

One command inventories the template, you write a plan as data, one command applies and verifies it.

Branding survives: every part the plan does not touch (logo, styles, theme, fonts, numbering, headers and footers with nothing to fill) stays byte-identical, and in a touched part only the runs holding a replaced value are rewritten. Nothing is invented silently: a missing value follows the field's absence policy and is named in the report rather than guessed, every literal, sentinel, empty and unused input is a review item, and every change is verified against the plan or the run fails and nothing is published.

Workflow

1. python scripts/run_job.py inspect --template <file.docx> --workdir <dir> [--profile <profile.json>] creates <dir>/<job_id>/ with snapshot.docx, manifest.json (paragraph inventory, candidates, findings) and plan.draft.json, and prints a listing: every paragraph with its id and text, every candidate marked ! (needs your decision), ? (optional) or x (cannot be filled, reason given).
2. Copy plan.draft.json to plan.json and complete it. A complete, working pair to copy the shape from is references/examples/plan.json and references/examples/values.json: every decision kind, typed and formatted fields, a sentinel, a derived literal, a repeated row, a range deletion and a multi-paragraph insert. It is written for assets/fixtures/mixed-conventions.docx and selftest runs it, so every key name in it is current. Read it instead of the contract or the scripts when you need a setting's name.
   • decisions[]: one per ! candidate. field (fill it), literal (ordinary text, leave it), remove_text (delete just that text), remove_paragraph, or keep (leave it and flag it).
   • fields[]: name, type (string, integer, decimal, date, boolean), format, absence_policy (required, sentinel, empty) and source, a path into the data such as client.name or items[0].qty. source is a plain path, traversed key by key: there are no expressions, so it cannot join, compute or summarise. When the value needs working out rather than looking up, put the worked-out value in the field's literal instead of a source; it is always flagged for review. (Careful: literal in decisions[] means the opposite of this one — there it means "this text is real content, leave it alone". In fields[] it is the value you supply.)
   • operations[]: delete_paragraph, delete_range (from and to paragraph ids in the same container; tables in between go too), delete_row, delete_break (one line or page break, so deleting a cover page does not leave a blank first page), repeat_row (an id, any paragraph in the row, a source list; the row's fields carry "repeat": "<id>" and sources relative to each item; add "group": true to a field such as a phase or category to print it only on the first of consecutive rows that share its value), insert_paragraph_after (text or field; a field whose value is a list becomes one paragraph per item, which is how a multi-paragraph answer goes in at an anchor).
   • locale when the document is not English: months, true and false text, separators, date pattern.
   • notes: optional free text for the record, at most 2000 characters. The draft carries a reminder here; remove or replace it.
3. Write values.json as {"data": <the input, any JSON, shaped however you like>}.
4. python scripts/run_job.py execute --job <job dir> --dry-run prints every change as before and after text plus every review item, or the errors that stop it. Fix the plan and repeat until it compiles.
5. python scripts/run_job.py execute --job <job dir> [--out <dir>] applies, verifies, and writes report.json, attempts/<id>/ and, when verification passes, output/<stem>__<job_id>.docx. Exit 0 ok, 2 needs_review, 1 failed. Rerunnable, and a failed rerun never deletes a document an earlier attempt verified.
6. Deliver the document before you report on it. output/<stem>__<job_id>.docx sits in the job directory, which the user never sees: copy it into the folder this session hands deliverables from, or run step 5 with --out pointing there. A report without the file is not a delivery. If execute exits 1 there is nothing to deliver; say so and name the check that failed.
7. Relay the result word, the change list and every review item. Each command prints its own elapsed: line; pass those figures on unchanged rather than estimating, if anyone is measuring. ok means mechanically verified against the template and the plan. Nobody has opened the document in Word.