rojim666/sztucode/documents

Documents Skill (Read • Create • Edit • Redline • Comment)

Use this skill when you need to create or modify .docx, Word, or Google Docs-targeted document artifacts in this container environment and verify them visually.

Tools + Contract

• Use Codex workspace dependencies for docx artifact work: resolve them through the workspace dependency loader or runtime skill, then treat the returned Node/Python runtimes and package directory as authoritative. Do not use system node, system python, global npm packages, or repo-local installs.
• For document creation and deterministic OOXML edits, it is still acceptable to use the bundled Python/OOXML helper scripts in this skill package when the JS surface is incomplete.
• Run any builder or helper file from a writable workspace or temp directory, not from the managed dependency directory itself.
• Final user-facing responses should describe only the requested document result. Do not link QA intermediates unless the user explicitly asks for them.

Google Docs-targeted output

For a net-new Google Docs request, create and visually verify a local .docx with this skill first. The native Google Docs deliverable must then be produced by the Google Drive plugin's document import action, mcp__codex_apps__google_drive_import_document, with upload_mode: "native_google_docs".

Before rendering or importing any Google Docs-targeted DOCX, run the deterministic title sanitizer:

python scripts/google_docs_title_sanitize.py input.docx --out sanitized.docx
python scripts/google_docs_title_sanitize.py sanitized.docx --check

Use the sanitized DOCX for render QA and native Google Docs import. This is not a style preference or prose reminder: the sanitizer removes Word Title paragraph-style border residue, direct title-paragraph borders, and leading title-block paragraph borders from the OOXML so Word's built-in blue title rule cannot survive into the imported Google Doc.

Do not use Computer Use, Browser Use, blank-Google-Doc creation plus Google Docs write APIs, or another direct-to-Docs construction path for net-new Google Docs unless the user explicitly asks for that alternate workflow. If they do, mention first that output quality is expected to be best when a local .docx is imported through the Google Drive plugin.

If the Google Drive plugin is unavailable, use the plugin-install/user-elicitation flow to ask the user to install google-drive@openai-curated. If the plugin is available but _import_document is missing, ask the user to reinstall or refresh the Google Drive plugin before continuing with the native Google Docs deliverable.

Template Following

When an attached or retained DOCX is meant to control a new document, read template-distill.md and then template-create.md. Keep the reference file and the task-local $TMP_DIR/artifact.md together throughout authoring. In this mode, the retained reference is the design authority: do not apply a generic design preset, page baseline, or header pattern unless the user explicitly asks to depart from the template. The render gate and Google Docs import contract still apply. For a Google Docs-targeted result, record any change made by the required title sanitizer as an intentional fidelity deviation.

Non-negotiable: render → inspect PNGs → iterate

You do not “know” a DOCX is satisfactory until you’ve rendered it and visually inspected page images. DOCX text extraction (or reading XML) will miss layout defects: clipping, overlap, missing glyphs, broken tables, spacing drift, and header/footer issues.

Shipping gate: before delivering any DOCX, you must:

• Run render_docx.py to produce page-<N>.png images (optionally also a PDF with --emit_pdf)
• Open the PNGs (100% zoom) and confirm every page is clean
• If anything looks off, fix the DOCX and re-render (repeat until flawless)

If rendering fails because LibreOffice/soffice is missing, it is acceptable to return the requested DOCX without rendered PNG QA. In that fallback case, use the relevant Markdown task docs in this skill package as the authoritative guidance for building and checking the document structurally, state clearly in the final response that rendering/visual QA could not be completed, and do not imply that the document passed the render gate.

If rendering fails for any other reason, fix rendering first (LibreOffice profile/HOME, conversion errors, or renderer setup) rather than guessing.

Deliverable discipline: Rendered artifacts (PNGs and optional PDFs) are for internal QA only. Unless the user explicitly asks for intermediates, return only the requested final deliverable (e.g., when the task asks for a DOCX, deliver the DOCX — not page images or PDFs).

Design Preset Contract

Outside template-following mode, a design preset is mandatory for new DOCX creation and major rewrites unless the user explicitly asks for a different visual system. For existing-document edit tasks, preserve the original document and apply the minimal local edits described later in this skill.

Picking a preset is not enough. You must resolve the preset into exact numeric tokens and apply those numbers in the DOCX implementation. Do not rely on Word defaults, built-in list styles, theme defaults, inherited paragraph spacing, or renderer-dependent behavior for any preset-controlled value.

Before writing content, read references/design_presets.md and choose exactly one preset:

• google_docs_default for any net-new document whose destination is a native Google Doc, unless the user explicitly asks for a special, branded, or highly polished visual treatment.
• standard_business_brief for formal memos, RFI responses, decision memos, and board-style briefs.
• compact_reference_guide for launch guides, negotiation briefs, checklists, and dense operator references.
• narrative_proposal for grants, proposals, and persuasive documents with longer prose.
• Use an archetype alias from the reference file when it is a closer match: rfi_response, decision_memo, launch_messaging_guide, contract_negotiation_brief, neighborhood_business_proposal, or grant_proposal.

If the destination is Google Docs, choose google_docs_default. Google Docs-targeted documents should feel native: Arial-based typography, black hierarchy, simple title treatment.

For Google Docs-targeted documents, never create the title with the built-in Word Title paragraph style, including doc.add_paragraph(..., style="Title") or doc.add_paragraph(style="Title"). Always create a plain paragraph and apply the selected style-sheet title tokens directly: font family, size, color, weight, spacing, and border/rule settings. For google_docs_default, that means Arial 26 pt, black, normal weight, 0 pt before, 3 pt after, and no underline, bottom border, horizontal rule, or other Word-template residue. This instruction is not the enforcement layer; scripts/google_docs_title_sanitize.py is the deterministic enforcement layer and must still run before render/import.

If creating a new first-page header, cover, or title block for a non-Google-docs document, also read references/header_templates.md and choose one header pattern before drafting. For google_docs_default, keep the opening block simple unless the user explicitly requests richer first-page furniture.

Then resolve the preset into a token map and apply the tokens consistently:

1. Set page, margin, type scale, paragraph rhythm, heading, list, table, callout, header, footer, and color tokens before drafting. For google_docs_default, that means explicitly carrying the simple Google Docs defaults instead of inheriting the more polished Word-oriented defaults above.
2. Implement those tokens through Word styles, real numbering definitions, explicit table geometry, and header/footer parts. Do not fake headings, lists, or tables with one-off direct formatting.
3. Use ad-hoc formatting only when the document needs a specific exception; record the exception as a named override and reuse it consistently wherever that role appears.
4. Keep the preset stable throughout the document. Do not mix body spacing, heading colors, list indents, table fills, or page furniture from multiple presets.

Baseline geometry for all presets: US Letter portrait, 1 inch margins, 9360 DXA usable width, real Word styles for Normal/Title/Subtitle/Heading 1/Heading 2/Heading 3, real Word numbering for lists, and DXA table widths only.

Tables must use explicit Word geometry. Build rows first, compute exact DXA column widths, then use scripts/table_geometry.py or equivalent logic so tblW, tblInd, tblGrid, and every tcW agree. Set table indent to the start cell margin token (120 DXA by default) so the visible outer border aligns with surrounding paragraph text. Do not rely on autofit, percentage widths, centered default tables, fixed row heights, or tables as layout/divider hacks.

Lists must use real numbering definitions. Never create fake bullets with Unicode bullet text, hyphen-prefixed paragraphs, manual numbers, or newline-separated list items inside one paragraph. Wrapped list lines must align under the item text, not under the marker.

Before final render review, run a preset audit: page geometry, styles, heading spacing/colors, list indents, table widths/table indents/cell margins, callout fills, headers/footers, and direct-formatting exceptions must match the selected token map. Also check for fake headings, fake bullets, missing table geometry, clipped/pinned table text, inconsistent page furniture, and unexplained direct formatting drift. For google_docs_default, fail the audit if the title style or title paragraph contains w:pBdr, a bottom border, an underline, a horizontal rule, or any rendered decorative line under the title.

Form factor selection

For new DOCX creation and major rewrites, choose content form factors deliberately before drafting. Start from the information type, then calibrate the structure to the document archetype. Use the lightest readable structure that helps the reader understand, compare, act on, or fill in the information with the least friction.

First map each major content unit to a form factor:

• PROSE SECTION: narrative, explanation, background, or rationale. Use paragraphs under clear headings, with short supporting bullets only when they improve skimming.
• LEAD CALLOUT: decision, recommendation, or key takeaway. Use a short labeled paragraph, callout, or lead paragraph followed by concise rationale.
• NUMBERED STEPS: sequence, workflow, or procedure. Use step blocks with clear action verbs; add owner/status fields only when they are central to execution.
• GROUPED BULLETS: loose factors, considerations, pros/cons, or requirements. Use bullets or short subsections when order is not the main point.
• CHECKLIST: actions, acceptance checks, or review criteria. Use compact labels and enough spacing to scan.
• NOTE BOX: warnings, caveats, constraints, or important notes. Use a callout with restrained emphasis.
• DEFINITION LIST: definitions, metadata, or key facts. Use labeled paragraphs, definition lists, or compact key-value blocks.
• TABLE: repeated comparable records, status grids, budgets, RFI/compliance matrices, or schedules with shared fields.
• FORM LAYOUT: forms and questionnaires. Use readable fields, sectioning, and response space; use grids only where repeated response structure helps completion.
• SOURCE LIST: evidence, citations, and sources. Use footnotes, endnotes, short source lists, or appendices according to document type and density.

Table Gate

Use a table only when the content is truly row/column data: repeated items, shared fields, and useful comparison or lookup.

Do not use tables to package normal prose. If cells become mini-paragraphs, switch to prose sections, bullets, steps, checklists, callouts, or appendix material.

Before finalizing, run a table-overuse audit: