brand-docx

Use this skill when the user wants a reusable Word brand kit or wants to create a new on-brand .docx from a company template and variable content.

This is an AI-agent skill for Codex and Claude Code. The user should not need to write JSON or run shell commands. The agent converts the user's content into an IntermediateDocument, invokes the internal engine, verifies the output, and returns the generated .docx.

The seven verbs: three deterministic + four model-assisted

Every brand skill (brand-docx, brand-pptx, brand-xlsx) implements the same contract. The deterministic core is extract / verify / generate; on top of it sit the optional learning verbs comprehend / learn / propose-overrides / refine, each fail-closed (the engine validates every proposal and authors every value).

comprehend is optional: generate works on the deterministic profile alone. When a current comprehension is present, generate additionally reconciles the template's preserved cover/index structures with the new content. See reference/comprehension.md for the full step.

Hard Rules

• Treat python scripts/cli.py ... as an internal engine command, not the user-facing workflow.
• scripts/cli.py is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set BRAND_DOCS_ROOT to override). Never guess deeper paths like scripts/brandkit/....
• Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
• Extract opens the source template read-only and saves brand-kit/<name>/template/shell.docx byte-for-byte.
• Generate opens the saved shell and resolves every semantic block through profile.json.
• Do not put style names, colors, fonts, or brand identifiers in an IntermediateDocument.
• If the user did not provide a template or enough content, ask for the missing input.
• Return the generated file path plus a QA summary.
• Consult profile.json.artifact_catalog before generation when the user asks to mimic a specific piece of the template.

Preflight (always first)

Before doing any work, run:

python scripts/cli.py doctor

Use its output to decide the run mode:

• If a required Python dependency is missing, install/repair it before extraction or generation; the core engine is not ready.
• If only visual renderers are missing or unusable (soffice plus pdftoppm or optional PyMuPDF/fitz), the core L0 workflow can still run, but a full visual audit cannot be claimed. Tell the user what is missing, include the install/repair hint printed by doctor, and either proceed with degraded QA or install the renderer first.
• If optional OCR (tesseract) is missing, the visual audit can still run, but rendered residual-text proof is incomplete. Report that limitation when judging stale placeholders or field caches.
• For --qa deep or --qa strict, prefer repairing/installing renderers before generation. If the environment cannot run them, deep generates a degraded manifest and strict fails with a visual proof blocker.

Agent Workflow

1. Run the dependency preflight above and report any degraded capability.
2. Determine the brand name and locate the user-provided .docx template.
3. If no matching brand-kit/<name> exists, extract one.
4. Comprehend the template (optional, model-driven; see below). Skip when a current comprehension is already cached or no model is available.
5. Convert the user's requested content into IntermediateDocument JSON.
6. Generate the .docx with the internal engine.
7. Run QA and report any warnings honestly.
8. Feedback (only after returning the file): invite a refinement of the understanding for future documents (see below).

Before generation, inspect profile.json.artifact_catalog when the user asks to mimic a specific template piece. It records OOXML parts, media parts, paragraph/table styles, style details, sections/margins, paragraph samples, and table counts.

Authoring the IntermediateDocument

The IDoc is where "correct document" becomes "great document". Author it role-first, against the profile, never style-first:

1. Read brand-kit/<name>/PROFILE.md before writing a block. It lists the role table (with scope, placement, required slots), the brand palette tokens, and the template's structural order. Choose every block by MEANING from that table; the engine resolves it to the template's own artifacts.
2. Respect the skeleton. Cover fields first (cover.title, cover.subtitle, extra cover fields), a toc block only where the template keeps one, then the freeform body.
3. Shape the body for the reader. One heading level 1 per major section and a real 1-2-3 hierarchy below it (the TOC regenerates from exactly these headings); paragraphs of 2-5 sentences; list blocks for enumerations (bullet for unordered, number for sequences); every table and image with a caption block so derived indexes regenerate from real content; callout sparingly, for genuinely load-bearing notes; quote only for actual quotations.
4. Color discipline. The named style already carries the brand: the default is NO run color. When emphasis is truly needed, reference a palette role (primary, text, ...) or a theme slot (accent1) from PROFILE.md, never a hex.
5. Reuse before re-deriving. When a comprehension is present, prefer its component / section fragments (comprehension.fragments in profile.json) with {{slot}} values over hand-building a recurring layout.
6. Never name a style, font, size, or hex. If a block needs something the role table cannot express, say so in the QA summary instead of inventing formatting: the resolver is the only author of values.

Feedback (end of generation)

Ask for feedback only after you have returned the generated .docx and its QA summary - never before or during generation. Invite the user to reply with text or a screenshot of the document, and name the roles, palette colors, and sections you actually used so the answer is concrete. A screenshot is your own multimodal read; the engine only ever ingests the structured JSON delta you distil from it.

Turn the answer into a small refinement delta of verbatim ids and merge it with the refine verb (see reference/comprehension.md):

python scripts/cli.py refine --name <brand> --input refinement.json --accept

A refinement improves FUTURE generations of this brand only - it mutates the saved profile, never the .docx you just produced. To apply it, generate again.

When the SAME QA finding recurs across runs, you can also propose a shell-bound correction with propose-overrides: the comprehend-input bundle surfaces the recurring generation_history, and you NAME a shell-backed re-point (a stub role to an existing healthy role, a number_format mask the shell uses, or a captured demo value) that the engine binds fail-closed (see reference/comprehension.md). It is advisory until --accept, improves FUTURE generations only, and every live correction surfaces as an INFO override_applied finding in QA.

Internal Extract

python scripts/cli.py extract --name <brand> --template <template.docx> --scope project

Internal Comprehend (optional, model-driven)

Read reference/comprehension.md for the full guidance, the six questions, and the anti-overfitting directive. In short:

python scripts/cli.py comprehend-input --name <brand>   # prints {facts, excerpt} for the model
python scripts/cli.py comprehend --name <brand> --input comprehension.json  # the ONLY writer

Skip this verb when comprehension.status is present and its source_shell_sha256 equals the live provenance.shell.sha256 (a current comprehension is already cached). A re-extract resets it to absent; re-run comprehend only then. Never re-run it at generate time.

docx readiness. The Word extractor surfaces cover anchors, TOC/list fields when present, and text regions. A current comprehension can therefore steer cover fill, index regeneration, and demo-region clearing. If a document genuinely has no TOC/list field, do not force one; a ref into an empty field inventory is fail-closed and will be rejected.

Internal Verify

python scripts/cli.py verify --name <brand> --scope auto --qa auto

--qa selects the QA depth (see reference/visual-audit.md):

• fast: deterministic L0 only (schema, resolver targets, residual text, structural diffs).
• auto: L0 + L1 visual pixel proxies when renderers (soffice plus pdftoppm or optional PyMuPDF/fitz) are present; otherwise L0 plus a single INFO visual.unavailable.
• deep: L0 + L1 + a visual_manifest.json and per-page PNGs; if tesseract is installed the manifest also includes OCR text/hits. The orchestrator must then run the L2 step (see below).
• strict: deep visual audit plus gate errors when full render proof is unavailable or L1/OCR evidence is not clean.

Verify has no output to render, so all modes behave as L0 at verify time; the visual stages run at generate time.

Internal Generate

python scripts/cli.py generate --name <brand> --input <intermediate-document.json> --output <output.docx> --scope auto --qa auto

See reference/comprehension.md, reference/profile-schema.md, reference/generation.md, reference/visual-audit.md, and examples/intermediate-document.example.json.

Visual audit (two-stage)

The engine renders the output and runs deterministic pixel proxies, but the qualitative visual judgement is yours (the orchestrator), never the engine's - the Python engine never calls a model. To run the full two-stage audit:

1. Generate with --qa deep. The engine renders each page to a PNG, runs the L1 proxies, and writes visual_manifest.json next to the output in an <output-file>.visual/ dir, such as report.docx.visual/ (a side artifact; the .docx bytes never change).
2. Read the manifest path from stdout (visual manifest: <path>).
3. Open the PNGs listed in pages[*].png. For every entry in checklist, judge PASS/FAIL against the rendered pages, taking l1_findings and ocr.hits into account.
4. If any checklist item FAILS (or an L1 visual.blank_page / visual.edge_bleed WARNING or visual.ocr_residual_text hit is confirmed as a real defect): repair the IntermediateDocument/content or the generated composition, regenerate, then re-run the audit. Loop until the checklist is clean, or until no further targeted repair can be justified without user input.

L1 findings are WARNING-only and never fail the gate by themselves; the real qualitative gate is your L2 judgement.

During repair, treat the template as a source of reusable structure, not a rule to preserve blindly. If inherited section breaks, front-matter scaffolding, field-result caches, or other template structures create blank pages, stale entries, overlaps, or visibly broken pagination, diagnose the structure as the cause and make the smallest targeted composition change. It is acceptable to collapse, move, or remove a template section break when preserving it damages the final generated document. After every repair, regenerate and rerun --qa deep or --qa strict.

Current Guarantees and Limits

Generation opens the saved .docx shell, clears detected demo text, and applies only styles resolved from profile.json. L0 QA catches schema problems, unresolved roles, markdown literals, and residual demo text.

When a current comprehension is present, generation also fills the cover slots in place (no duplicate title) and reconciles preserved indexes (a table of contents, a list of tables/figures) against the new content (regenerating, preserving, or purging stale entries) instead of carrying demo entries forward. Destructive reconciliation is bounded: a clear/remove is honored only when determinism corroborates and confidence clears a threshold, else the structure is kept with a warning.

Extraction also records a broad artifact_catalog: OOXML parts, media parts, paragraph/table styles, style details, sections/margins, paragraph samples, and table counts. Use it to understand and describe template conventions beyond the roles that are directly generatable today.

The two-stage visual audit closes the "L0-only" gap: L1 deterministic pixel proxies catch rendered-layout defects L0 cannot see (blank/broken pages, content bleeding past the printable margins), and the L2 manifest drives the orchestrator's qualitative judgement and repair loop. See reference/visual-audit.md.

DOCX visual overflow requires render-time QA with LibreOffice because Word layout is not deterministic from OOXML alone. When soffice and both PDF rasterizers (pdftoppm, optional PyMuPDF/fitz) are absent (e.g. CI), the visual audit degrades cleanly to L0 plus a single INFO visual.unavailable; exit codes are unchanged and the skill does not claim a full no-overflow visual proof.

brand-pptx

Use this skill when the user wants reusable branded PowerPoint generation from a company .pptx template and variable user-provided content.

This is an AI-agent skill for Codex and Claude Code. The user should describe the deck they want; the agent converts that request into an IntermediateDocument, uses the internal Python engine, verifies the output, and returns the generated .pptx.

The seven verbs: three deterministic + four model-assisted

Every brand skill (brand-docx, brand-pptx, brand-xlsx) implements the same contract. The deterministic core is extract / verify / generate; on top of it sit the optional learning verbs comprehend / learn / propose-overrides / refine, each fail-closed (the engine validates every proposal and authors every value).

comprehend is optional: generate works on the deterministic profile alone. See reference/comprehension.md for the full step.

Hard Rules

• Treat python scripts/cli.py ... as an internal engine command, not the user-facing workflow.
• scripts/cli.py is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set BRAND_DOCS_ROOT to override). Never guess deeper paths like scripts/brandkit/....
• Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
• Extract opens the source template read-only and saves brand-kit/<name>/template/shell.pptx byte-for-byte.
• Generate opens the saved shell and resolves every semantic block through profile.json.
• Do not put style names, colors, fonts, or brand identifiers in an IntermediateDocument.
• If the user did not provide a template or enough content, ask for the missing input.
• Return the generated file path plus a QA summary.
• Consult profile.json.artifact_catalog before generation when the user asks to mimic a specific piece of the template.

Preflight (always first)

Before doing any work, run:

python scripts/cli.py doctor

Use its output to decide the run mode:

• If a required Python dependency is missing, install/repair it before extraction or generation; the core engine is not ready.
• If only visual renderers are missing or unusable (soffice plus pdftoppm or optional PyMuPDF/fitz), the core L0 workflow can still run, but a full visual audit cannot be claimed. Tell the user what is missing, include the install/repair hint printed by doctor, and either proceed with degraded QA or install the renderer first.
• If optional OCR (tesseract) is missing, the visual audit can still run, but rendered residual-text proof is incomplete. Report that limitation when judging stale placeholders or field caches.
• For --qa deep or --qa strict, prefer repairing/installing renderers before generation. If the environment cannot run them, deep generates a degraded manifest and strict fails with a visual proof blocker.

Agent Workflow

1. Run the dependency preflight above and report any degraded capability.
2. Determine the brand name and locate the user-provided .pptx template.
3. If no matching brand-kit/<name> exists, extract one.
4. Comprehend the template (optional, model-driven; see below). Skip when a current comprehension is already cached or no model is available.
5. Convert the user's outline/content into IntermediateDocument JSON.
6. Generate the .pptx with the internal engine.
7. Run QA and report any warnings honestly.
8. Feedback (only after returning the file): invite a refinement of the understanding for future decks (see below).

Before generation, inspect profile.json.artifact_catalog when the user asks to mimic a specific template piece. It records OOXML parts, media parts, slide layouts, masters, placeholder geometry, slide texts, and slide size.

Authoring the IntermediateDocument

The IDoc is where "correct deck" becomes "great deck". Author it role-first, against the profile, never layout-first:

1. Read brand-kit/<name>/PROFILE.md before writing a block. It lists the role table and the brand palette tokens. Choose every block by MEANING from that table; the engine maps it to the template's real masters and layouts.
2. One idea per slide. A slide carries one heading and a few supporting blocks; split dense content across slides instead of shrinking it. Decks read in seconds per slide, not minutes.
3. Lead with structure. Cover fields first, an agenda where the deck keeps sections, then one section heading per major topic so the template's section scaffolding stays meaningful.
4. Prefer native objects. chart, table (merged cells included) and diagram blocks are authored NATIVELY: never describe a chart in prose or paste it as an image when a native block exists.
5. Color discipline. Placeholders inherit the brand from the layout: the default is NO run color. For true emphasis, reference a palette role (primary, text, ...) or a theme slot (accent1), never a hex.
6. Reuse before re-deriving. When a comprehension is present, prefer its component / section fragments (comprehension.fragments in profile.json) with {{slot}} values over hand-building recurring slides.
7. Never name a layout, font, size, or hex. If a block needs something the role table cannot express, say so in the QA summary instead of inventing formatting: the resolver is the only author of values.

Feedback (end of generation)

Ask for feedback only after you have returned the generated .pptx and its QA summary - never before or during generation. Invite the user to reply with text or a screenshot of the deck, and name the roles, palette colors, and sections you actually used so the answer is concrete. A screenshot is your own multimodal read; the engine only ever ingests the structured JSON delta you distil from it.

Turn the answer into a small refinement delta of verbatim ids and merge it with the refine verb (see reference/comprehension.md):

python scripts/cli.py refine --name <brand> --input refinement.json --accept

A refinement improves FUTURE generations of this brand only - it mutates the saved profile, never the .pptx you just produced. To apply it, generate again.

When the SAME QA finding recurs across runs, you can also propose a shell-bound correction with propose-overrides: the comprehend-input bundle surfaces the recurring generation_history, and you NAME a shell-backed re-point (a stub role to an existing healthy role, a number_format mask the shell uses, or a captured demo value) that the engine binds fail-closed (see reference/comprehension.md). It is advisory until --accept, improves FUTURE generations only, and every live correction surfaces as an INFO override_applied finding in QA.

Internal Extract

python scripts/cli.py extract --name <brand> --template <template.pptx> --scope project

Internal Comprehend (optional, model-driven)

Read reference/comprehension.md for the full guidance, the six questions, and the anti-overfitting directive. In short:

python scripts/cli.py comprehend-input --name <brand>   # prints {facts, excerpt} for the model
python scripts/cli.py comprehend --name <brand> --input comprehension.json  # the ONLY writer

Skip this verb when comprehension.status is present and its source_shell_sha256 equals the live provenance.shell.sha256. Never re-run it at generate time.

pptx readiness. The PowerPoint extractor surfaces cover anchors, the agenda/section-list field inventory when present, and slide regions. A current comprehension can therefore steer cover fill, demo-slide clearing, and agenda/section-list regeneration. If a deck genuinely has no agenda/section field, do not force one; a ref into an empty inventory is fail-closed and will be rejected. Deeper native-object authoring remains a pptx enrichment milestone.

Internal Verify

python scripts/cli.py verify --name <brand> --scope auto --qa auto

--qa selects the QA depth (see reference/visual-audit.md):

• fast: deterministic L0 only.
• auto: L0 + L1 visual pixel proxies when renderers (soffice plus pdftoppm or optional PyMuPDF/fitz) are present; otherwise L0 plus a single INFO visual.unavailable.
• deep: L0 + L1 + a visual_manifest.json and per-page PNGs; if tesseract is installed the manifest also includes OCR text/hits. The orchestrator must then run the L2 step (see below).
• strict: deep visual audit plus gate errors when full render proof is unavailable or L1/OCR evidence is not clean.

Verify has no output to render, so all modes behave as L0 at verify time; the visual stages run at generate time.

Internal Generate

python scripts/cli.py generate --name <brand> --input <intermediate-document.json> --output <output.pptx> --scope auto --qa auto

See reference/comprehension.md and reference/visual-audit.md.

Visual audit (two-stage)

The engine renders the output and runs deterministic pixel proxies, but the qualitative visual judgement is yours (the orchestrator), never the engine's - the Python engine never calls a model. To run the full two-stage audit:

1. Generate with --qa deep. The engine renders each slide to a PNG, runs the L1 proxies, and writes visual_manifest.json next to the output in an <output-file>.visual/ dir, such as deck.pptx.visual/ (a side artifact; the .pptx bytes never change).
2. Read the manifest path from stdout (visual manifest: <path>).
3. Open the PNGs listed in pages[*].png. For every entry in checklist, judge PASS/FAIL against the rendered pages, taking l1_findings and ocr.hits into account.
4. If any checklist item FAILS (or an L1 WARNING is confirmed visually as a real defect, or a visual.ocr_residual_text hit is confirmed as stale visible template text): repair the IntermediateDocument/content or the generated composition, regenerate, then re-run the audit. Loop until the checklist is clean, or until no further targeted repair can be justified without user input.

L1 findings are WARNING-only and never fail the gate by themselves; the real qualitative gate is your L2 judgement.

During repair, treat the template as a source of reusable layout affordances, not a rule to preserve blindly. If inherited placeholders, section/agenda slides, layout geometry, or other template structures create blank slides, overlaps, stale entries, or visibly broken pagination, diagnose the structure as the cause and make the smallest targeted composition change. It is acceptable to collapse, move, or remove inherited scaffolding when preserving it damages the final deck. After every repair, regenerate and rerun --qa deep or --qa strict.

Current Guarantees and Limits

M2 supports title/content deck generation from the saved shell. Long content is split across multiple content slides with a conservative capacity guard. When a current comprehension block is present, generation reconciles the deck by keeping structural slides, filling cover placeholders in place, clearing corroborated demo slides, and regenerating the agenda/section list from the new headings. Table blocks are authored as native PowerPoint table objects (honoring colspan/rowspan merges). Chart, SmartArt, KPI and image blocks are also authored natively and on-brand (a real graphicFrame chart inheriting the deck theme, chevron/box autoshapes for SmartArt, a brand-styled metric table for KPIs, a placed picture for images). A divider has no native pptx form and degrades loudly (a visible block_degraded warning, never a silent drop).

The two-stage visual audit closes the "L0-only" gap: L1 deterministic pixel proxies catch rendered-layout defects L0 cannot see (blank/broken slides, content bleeding past the slide edges), and the L2 manifest drives the orchestrator's qualitative judgement and repair loop. See reference/visual-audit.md. When soffice and both PDF rasterizers (pdftoppm, optional PyMuPDF/fitz) are absent (e.g. CI), the audit degrades cleanly to L0 plus a single INFO visual.unavailable; exit codes are unchanged.

brand-xlsx

Use this skill when the user wants reusable branded Excel/workbook generation from a company .xlsx template and variable user-provided data.

This is an AI-agent skill for Codex and Claude Code. The user should describe the workbook/model they want filled; the agent maps that request to named cells and named regions, invokes the internal Python engine, verifies the output, and returns the generated .xlsx.

The seven verbs: three deterministic + four model-assisted

Every brand skill (brand-docx, brand-pptx, brand-xlsx) implements the same contract. The deterministic core is extract / verify / generate; on top of it sit the optional learning verbs comprehend / learn / propose-overrides / refine, each fail-closed (the engine validates every proposal and authors every value).

comprehend is optional: generate works on the deterministic profile alone. See reference/comprehension.md for the full step.

Hard Rules

• Treat python scripts/cli.py ... as an internal engine command, not the user-facing workflow.
• scripts/cli.py is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set BRAND_DOCS_ROOT to override). Never guess deeper paths like scripts/brandkit/....
• Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
• Extract opens the source template read-only and saves brand-kit/<name>/template/shell.xlsx byte-for-byte.
• Generate opens the saved shell and resolves every named cell/region through profile.json.
• Do not put style names, colors, fonts, or brand identifiers in a GridDocument.
• If the user did not provide a template or enough data, ask for the missing input.
• Return the generated file path plus a QA summary.
• Consult profile.json.artifact_catalog before generation when the user asks to mimic a specific piece of the template.

Preflight (always first)

Before doing any work, run:

python scripts/cli.py doctor

Use its output to decide the run mode:

• If a required Python dependency is missing, install/repair it before extraction or generation; the core engine is not ready.
• If only visual renderers are missing or unusable (soffice plus pdftoppm or optional PyMuPDF/fitz), the core L0 workflow can still run, but a full visual audit cannot be claimed. Tell the user what is missing, include the install/repair hint printed by doctor, and either proceed with degraded QA or install the renderer first.
• If optional OCR (tesseract) is missing, the visual audit can still run, but rendered residual-text proof is incomplete. Report that limitation when judging stale placeholders or field caches.
• For --qa deep or --qa strict, prefer repairing/installing renderers before generation. If the environment cannot run them, deep generates a degraded manifest and strict fails with a visual proof blocker.

Agent Workflow

1. Run the dependency preflight above and report any degraded capability.
2. Determine the brand name and locate the user-provided .xlsx template.
3. If no matching brand-kit/<name> exists, extract one.
4. Comprehend the template (optional, model-driven; see below). Skip when a current comprehension is already cached or no model is available.
5. Convert the user's tabular/model data into GridDocument JSON.
6. Generate the .xlsx with the internal engine.
7. Run QA and report any warnings honestly.
8. Feedback (only after returning the file): invite a refinement of the understanding for future workbooks (see below).

Before generation, inspect profile.json.artifact_catalog when the user asks to mimic a specific workbook piece. It records OOXML parts, named ranges, formulas, sheet dimensions, table names, merged cells, row/column sizing, cell styles, and number formats.

Authoring the GridDocument

The Grid is where "correct workbook" becomes "great workbook". Author it region-first, against the profile, never cell-address-first:

1. Read brand-kit/<name>/PROFILE.md before writing a fill. It lists the named-region roles, the brand cell styles, and the palette tokens. Address content to NAMED regions from that table; the engine fills the template's real ranges.
2. Respect region bounds. Size data to the region; when real data overflows, split it or ask the user to grow the template range instead of spilling into unnamed cells.
3. Formulas are content, not output. Never paste a computed value where the template keeps a formula: the engine preserves formulas, and QA fails the build if one is lost.
4. Numbers carry the brand too. Use the captured number.<family> roles (currency, percent, date, ...) for masks; never invent a format string.
5. Color discipline. Brand cell styles already carry the look: the default is NO direct color. For true emphasis, reference a palette role or a theme slot, never a hex.
6. Never name a style, font, or hex. If a fill needs something the role table cannot express, say so in the QA summary instead of inventing formatting: the resolver is the only author of values.

Feedback (end of generation)

Ask for feedback only after you have returned the generated .xlsx and its QA summary - never before or during generation. Invite the user to reply with text or a screenshot of the workbook, and name the roles, palette colors, and sections you actually used so the answer is concrete. A screenshot is your own multimodal read; the engine only ever ingests the structured JSON delta you distil from it.

Turn the answer into a small refinement delta of verbatim ids and merge it with the refine verb (see reference/comprehension.md):

python scripts/cli.py refine --name <brand> --input refinement.json --accept

A refinement improves FUTURE generations of this brand only - it mutates the saved profile, never the .xlsx you just produced. To apply it, generate again.

When the SAME QA finding recurs across runs, you can also propose a shell-bound correction with propose-overrides: the comprehend-input bundle surfaces the recurring generation_history, and you NAME a shell-backed re-point (a stub role to an existing healthy role, a number_format mask the shell uses, or a captured demo value) that the engine binds fail-closed (see reference/comprehension.md). It is advisory until --accept, improves FUTURE generations only, and every live correction surfaces as an INFO override_applied finding in QA.

Internal Extract

python scripts/cli.py extract --name <brand> --template <template.xlsx> --scope project

Internal Comprehend (optional, model-driven)

Read reference/comprehension.md for the full guidance, the six questions, and the anti-overfitting directive. In short:

python scripts/cli.py comprehend-input --name <brand>   # prints {facts, excerpt} for the model
python scripts/cli.py comprehend --name <brand> --input comprehension.json  # the ONLY writer

Skip this verb when comprehension.status is present and its source_shell_sha256 equals the live provenance.shell.sha256. Never re-run it at generate time.

xlsx readiness. The Excel extractor surfaces named-region cover anchors and sample-data regions, while fields is intentionally empty because workbooks do not have a TOC-style derived index. A current comprehension can therefore steer cover fills/clears and demo-region cleanup, but it must not invent an index ref; a ref into the empty field inventory is fail-closed and will be rejected.

Internal Verify

python scripts/cli.py verify --name <brand> --scope auto --qa auto

--qa selects the QA depth (see reference/visual-audit.md):

• fast: deterministic L0 only.
• auto: L0 + L1 visual pixel proxies when renderers (soffice plus pdftoppm or optional PyMuPDF/fitz) are present; otherwise L0 plus a single INFO visual.unavailable.
• deep: L0 + L1 + a visual_manifest.json and per-page PNGs; if tesseract is installed the manifest also includes OCR text/hits. The orchestrator must then run the L2 step (see below).
• strict: deep visual audit plus gate errors when full render proof is unavailable or L1/OCR evidence is not clean.

Verify has no output to render, so all modes behave as L0 at verify time; the visual stages run at generate time.

Internal Generate

python scripts/cli.py generate --name <brand> --input <grid-document.json> --output <output.xlsx> --scope auto --qa auto

See reference/comprehension.md and reference/visual-audit.md.

Visual audit (two-stage)

The engine renders the output and runs deterministic pixel proxies, but the qualitative visual judgement is yours (the orchestrator), never the engine's - the Python engine never calls a model. To run the full two-stage audit:

1. Generate with --qa deep. The engine renders each printed page to a PNG, runs the L1 proxies, and writes visual_manifest.json next to the output in an <output-file>.visual/ dir, such as workbook.xlsx.visual/ (a side artifact; the .xlsx bytes never change).
2. Read the manifest path from stdout (visual manifest: <path>).
3. Open the PNGs listed in pages[*].png. For every entry in checklist, judge PASS/FAIL against the rendered pages, taking l1_findings and ocr.hits into account.
4. If any checklist item FAILS (or an L1 WARNING is confirmed visually as a real defect, or a visual.ocr_residual_text hit is confirmed as stale visible template text): repair the grid/content or the generated composition, regenerate, then re-run the audit. Loop until the checklist is clean, or until no further targeted repair can be justified without user input.

L1 findings are WARNING-only and never fail the gate by themselves; the real qualitative gate is your L2 judgement.

During repair, treat the template as a source of reusable workbook affordances, not a rule to preserve blindly. If inherited print areas, hidden rows/columns, frozen regions, named-region geometry, or other template structures create blank printed pages, overflow, clipped tables, or stale visible content, diagnose the structure as the cause and make the smallest targeted composition change. It is acceptable to adjust or collapse inherited scaffolding when preserving it damages the final workbook. After every repair, regenerate and rerun --qa deep or --qa strict.

Current Guarantees and Limits

M2 fills named cells and named regions while preserving formulas and workbook topology in the shell. Region fills that exceed the named range are refused before saving. When a current comprehension block is present, generation can clear corroborated cover/demo regions while preserving formulas; derived indexes remain out of scope for XLSX because the field inventory is intentionally empty.

The two-stage visual audit closes the "L0-only" gap: L1 deterministic pixel proxies catch rendered-layout defects L0 cannot see (blank/broken printed pages, content bleeding past the printable margins), and the L2 manifest drives the orchestrator's qualitative judgement and repair loop. See reference/visual-audit.md. When soffice and both PDF rasterizers (pdftoppm, optional PyMuPDF/fitz) are absent (e.g. CI), the audit degrades cleanly to L0 plus a single INFO visual.unavailable; exit codes are unchanged.