{"id":50652003,"url":"https://github.com/ferdinandobons/brand-docs","last_synced_at":"2026-06-07T20:00:48.702Z","repository":{"id":362665020,"uuid":"1260255382","full_name":"ferdinandobons/brand-docs","owner":"ferdinandobons","description":"BrandDocs - extract a company's Word, PowerPoint or Excel template into a reusable Brand Profile, then generate unlimited on-brand documents of that same format. One skill per format.","archived":false,"fork":false,"pushed_at":"2026-06-06T17:34:23.000Z","size":2363,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T18:11:31.720Z","etag":null,"topics":["agent-skills","brand","claude-code","docx","office","ooxml","pptx","python","templates","xlsx"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ferdinandobons.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T09:55:35.000Z","updated_at":"2026-06-06T17:34:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ferdinandobons/brand-docs","commit_stats":null,"previous_names":["ferdinandobons/template-dna","ferdinandobons/docu-skills","ferdinandobons/brand-docs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ferdinandobons/brand-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdinandobons%2Fbrand-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdinandobons%2Fbrand-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdinandobons%2Fbrand-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdinandobons%2Fbrand-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ferdinandobons","download_url":"https://codeload.github.com/ferdinandobons/brand-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdinandobons%2Fbrand-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34035953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","brand","claude-code","docx","office","ooxml","pptx","python","templates","xlsx"],"created_at":"2026-06-07T20:00:19.013Z","updated_at":"2026-06-07T20:00:48.620Z","avatar_url":"https://github.com/ferdinandobons.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/hero.png\" alt=\"BrandDocs — AI on-brand document generator that turns a company's Word, PowerPoint or Excel template into a reusable Brand Profile and generates unlimited on-brand .docx, .pptx and .xlsx documents\" width=\"100%\" /\u003e\n\n\u003cbr/\u003e\n\n# BrandDocs — AI On-Brand Document Generator for Word, PowerPoint \u0026 Excel\n\n**BrandDocs turns existing Word, PowerPoint and Excel templates into reusable AI document-generation skills.** Unlike generic AI document generators, it preserves **brand, structure, styles and formulas by construction**. It is built for [Claude Code](https://www.anthropic.com/claude-code), Codex and compatible AI agents.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-3B82F6.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)\n[![CI](https://github.com/ferdinandobons/brand-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/ferdinandobons/brand-docs/actions/workflows/ci.yml)\n[![Website](https://img.shields.io/badge/website-GitHub%20Pages-16A34A.svg)](https://ferdinandobons.github.io/brand-docs/)\n[![Latest release](https://img.shields.io/github/v/release/ferdinandobons/brand-docs?label=latest%20release)](https://github.com/ferdinandobons/brand-docs/releases/latest)\n[![Skills](https://img.shields.io/badge/skills-docx%20·%20pptx%20·%20xlsx-6EA8FE.svg)](#the-three-skills)\n[![Status: alpha](https://img.shields.io/badge/status-alpha-F59E0B.svg)](#project-status)\n\n\u003c/div\u003e\n\n---\n\n## Contents\n\n- [What is BrandDocs?](#what-is-branddocs)\n- [At a glance](#at-a-glance)\n- [Why not just ask an AI to \"use this template\"?](#why-not-just-ask-an-ai-to-use-this-template)\n- [Common use cases](#common-use-cases)\n- [Highlights](#highlights)\n- [How it works](#how-it-works)\n- [Full plugin workflow](#full-plugin-workflow)\n- [Structure-aware, not just style-aware](#structure-aware-not-just-style-aware)\n- [Reliability \u0026 repair loop](#reliability--repair-loop)\n- [The three skills](#the-three-skills)\n- [The Brand Kit](#the-brand-kit)\n- [Prerequisites \u0026 installation](#prerequisites--installation)\n- [Quick start](#quick-start)\n- [Website, AI discovery \u0026 listings](#website-ai-discovery--listings)\n- [Project status](#project-status)\n- [Changelog](#changelog)\n- [Development](#development)\n- [FAQ](#faq)\n- [License \u0026 acknowledgements](#license--acknowledgements)\n\n---\n\n## What is BrandDocs?\n\n**BrandDocs** is an open-source **agent-skill bundle** that turns a company's existing Office templates into reusable AI document-generation skills.\n\nIn practical terms: make Claude Code, Codex or another compatible agent repeatedly generate Office documents - **DOCX, PPTX and XLSX** - from your company's real templates, while letting the **content vary** freely and keeping the **brand fixed**.\n\nYou give it one branded `.docx`, `.pptx`, or `.xlsx`. It **extracts** the brand - theme colors and fonts, named styles, the document's *structure*, layouts, cover anchors, logos and tables - into a portable **Brand Profile**. From then on, every document it **generates** is built *from the original template shell* and uses *only* the artifacts the template actually defines. Each format stays in its own lane: a Word template makes Word documents, a deck makes decks, a workbook makes workbooks - there is no cross-format conversion.\n\n\u003e **The core guarantee: off-brand output is impossible by construction.** No generator ever writes a literal style name, hex color, or font - those live only in the Brand Profile, and `verify` refuses a profile that points at anything the template doesn't contain. There is no \"creative\" path that drifts from the brand.\n\n---\n\n## At a glance\n\n| Question | Answer |\n|---|---|\n| **Input** | Existing company `.docx`, `.pptx`, or `.xlsx` templates |\n| **Output** | Same-format on-brand Word documents, PowerPoint decks, and Excel workbooks |\n| **Works with** | Claude Code, Codex, compatible AI agents, or the direct Python CLI |\n| **Best for** | Repeatable reports, decks, workbooks, proposals, memos, briefs, and internal document workflows |\n| **Privacy model** | Local-first; no cloud service is required, and real templates are git-ignored |\n| **Core guarantee** | Brand, structure, styles, layouts, ranges, and formulas are resolved from the extracted Brand Profile |\n| **Current release** | [v0.1.0](https://github.com/ferdinandobons/brand-docs/releases/tag/v0.1.0) alpha |\n\n### Why not just ask an AI to \"use this template\"?\n\nGeneral-purpose document skills generate *freely* and only loosely imitate a reference file - fonts drift, the palette wanders, the corporate structure is lost. BrandDocs is the opposite: narrow and faithful. It learns the template as a set of **rules and reusable parts**, remembers them in a `brand-kit/`, and **respects them** across an unlimited number of documents.\n\n|  | General-purpose Office skills | **BrandDocs** |\n|---|---|---|\n| Mental model | \"create a nice document\" | \"fill the company's template\" |\n| Brand fidelity | best-effort imitation | **by construction** - opens from the shell, applies only its artifacts |\n| Reusability | re-explain the brand every time | **extract once**, reuse forever via `brand-kit/` |\n| Structure | free-form | **respects the template's cover → contents → body order** |\n| Guardrails | none | `verify` fails if a profile references a missing style/layout/range |\n\n---\n\n## Common use cases\n\n- **Consulting and operations reports** - generate branded Word reports, memos,\n  briefs and status updates from the approved corporate template.\n- **Sales and marketing decks** - create PowerPoint presentations from real\n  masters and layouts instead of asking an AI to invent approximate slides.\n- **Finance and planning workbooks** - fill named Excel inputs and regions while\n  preserving formulas and workbook structure.\n- **Repeatable agent workflows** - give Claude Code, Codex or another agent a\n  reusable Brand Profile instead of re-explaining the brand for every document.\n\n---\n\n## Highlights\n\n- 🎯 **Brand-faithful by construction** - generation opens from the real template shell and applies only its named styles, theme colors, fonts and layouts. The content model is brand-agnostic; the **Brand Profile** is the single source of brand truth.\n- 🧠 **Extract once, reuse forever** - a portable `brand-kit/\u003cname\u003e/` is the template's memory; every later document reads it. No re-explaining the brand.\n- 🏛️ **Structure-aware** - captures the template's *ordered skeleton* (e.g. **cover → table of contents → body**) and tags each component as a **fixed structure to keep in order** or a **style to use on demand**. ([details](#structure-aware-not-just-style-aware))\n- ✅ **Enforced, not just promised** - `verify` opens the shell and **fails** if a role resolves to a style/layout/named-range that doesn't exist. Deterministic checks also cover allowed styles, palette adherence, residual template text, broken tables, **formula preservation** (Excel), native-component survival and language rules.\n- 🧪 **Auditable generation** - `doctor` preflights dependencies, `--qa fast|auto|deep|strict` makes QA depth explicit, and `--qa deep`/`strict` writes a visual manifest for render-based review and targeted repair.\n- 🧩 **One shared engine** - a single profile schema, resolver, OOXML layer and QA gate underpin all three formats. The Word vertical is the reference implementation; PowerPoint and Excel build on the same foundation.\n- 🗂️ **Full artifact catalog** - records OOXML parts, styles, media, layouts, formulas and named ranges, so an agent can reason about anything the template exposes - even artifacts it can't yet regenerate.\n- 🔓 **Self-contained \u0026 MIT** - pure `python-docx` / `python-pptx` / `openpyxl` + OOXML. No cloud, no external services, no vendor lock-in.\n\n---\n\n## How it works\n\n```\n company template ──▶ ① EXTRACT ──▶ brand-kit/\u003cname\u003e/ ──▶ ② GENERATE ──▶ on-brand document\n   .docx/.pptx/.xlsx      │          (profile + shell)         │\n                          │                                    ├─ opens FROM the template shell\n                          ├─ theme colors \u0026 fonts              ├─ resolves semantic blocks → brand styles\n                          ├─ named styles → roles              ├─ keeps the template's structure order\n                          ├─ document structure (skeleton)     └─ runs the QA gate\n                          ├─ layouts / cover anchors\n                          ├─ logos, media, tables, formulas\n                          └─ full artifact catalog\n```\n\n\u003e **Same format throughout.** A `.docx` template yields `.docx` documents, a `.pptx` yields `.pptx`, a `.xlsx` yields `.xlsx`. Each skill is its own lane: there is no cross-format conversion.\n\n1. **Extract** unpacks the template's OOXML and records its brand: theme, named styles mapped to semantic **roles**, the **document structure** (the ordered skeleton plus which parts are fixed vs free), layouts, cover anchors, logos, and a complete artifact catalog. The original file is kept **byte-for-byte** as the *shell*.\n2. **Generate** turns your content into an **IntermediateDocument** of brand-agnostic typed blocks (heading, paragraph, callout, list, table, …). A **pure resolver** maps each block to the concrete brand artifact from the profile, fills the shell **in the template's structural order**, and saves.\n3. **Verify / QA** runs deterministic checks - every role resolves to a real artifact, only allowed styles are used, the palette holds, no residual template text remains, tables are intact, **Excel formulas survive every region fill** - and, when LibreOffice is available, a render-based visual pass. When renderers are unavailable, the audit degrades explicitly instead of pretending visual proof happened.\n\n---\n\n## Full plugin workflow\n\nThe end-to-end agent workflow is documented in\n[`docs/PLUGIN_WORKFLOW.md`](docs/PLUGIN_WORKFLOW.md). It covers skill selection,\n`doctor` preflight, extract/comprehend/generate/QA, visual manifests, autonomous\nrepair rounds, and the final clean-output criteria.\n\n---\n\n## Structure-aware, not just style-aware\n\nMost \"use my template\" tools copy *styling*. BrandDocs also learns the template's **document structure** and reproduces it. During extraction it detects the ordered skeleton - typically **cover → table of contents → body** - and annotates every captured component with **how it is used**:\n\n- **Structural** parts (cover, table of contents) are kept **in order** in every generated document - the cover is filled in place, the TOC is preserved and refreshed.\n- **Freeform** parts (headings, callouts, lists, tables, quotes, captions) are styles to **use on demand**, in whatever order your content needs.\n\nSo a generated report opens with the company cover, keeps a live table of contents, and fills **only the body** with your content - exactly like a person starting from the corporate template, rather than a bare wall of text.\n\n---\n\n## Reliability \u0026 repair loop\n\nBrandDocs is designed so reliability is visible, testable, and improvable. The\nagent should not just produce a file; it should know which guarantees were\nproven, which were degraded, and what to repair next.\n\n| Layer | What it proves | What happens on failure |\n|---|---|---|\n| **Preflight** | `doctor` checks required Python packages, optional renderers (`soffice`, `pdftoppm`, PyMuPDF/`fitz`), and optional OCR (`tesseract`) before work starts. | Missing required packages must be installed/repaired. Missing visual/OCR tools downgrade only that proof layer. |\n| **L0 deterministic QA** | Schema validity, resolver targets, allowed styles/layouts/ranges, residual demo text, markdown leaks, structural diffs, formula preservation. | The gate fails or emits explicit findings before the output is treated as clean. |\n| **L1 visual proxies** | Rendered-page signals such as blank pages, zero pages, content near page/slide edges, and optional OCR hits for visible residual template text. | Findings are warnings because the engine can detect symptoms, not intent. |\n| **L2 visual judgement** | The orchestrator opens the PNGs from `visual_manifest.json`, judges checklist items, and decides whether the result is visually acceptable. `strict` turns unclean visual evidence into gate errors. | Apply a targeted repair, regenerate, and rerun `--qa deep` or `--qa strict` until clean or honestly blocked. |\n\nThe template is treated as a source of reusable brand affordances, not a script\nto preserve blindly. If an inherited section break, slide scaffold, print area,\nfield cache, or named-region geometry creates blank pages, stale entries,\noverlap, or clipped output, the right move is to diagnose the cause and make the\nsmallest targeted composition change. Preserving a broken structure is less\nimportant than producing a clean branded document.\n\nThe most valuable next reliability improvements are:\n\n1. **Native PPTX object authoring** - continue beyond native tables into real PowerPoint charts/images/SmartArt instead of down-rendering them to text, while keeping component-survival warnings.\n2. **Richer visual analysis** - build on the PyMuPDF fallback with optional `numpy`/`opencv-python` or `scikit-image` for overlap, clipping, and large-empty-region detection.\n3. **Broader skill evals** - expand the current template-based eval set with more corporate templates, visual-repair traces, and with/without-skill comparisons.\n\n---\n\n## The three skills\n\n| Skill | Format | Generates |\n|---|---|---|\n| **`brand-docx`** | Word `.docx` | reports, letters, memos: cover, headings, paragraphs, callouts, quotes, captions, lists, tables - in the template's structural order |\n| **`brand-pptx`** | PowerPoint `.pptx` | decks: title / section / content slides from the template's real masters \u0026 layouts, with real bullet levels and long-text splitting |\n| **`brand-xlsx`** | Excel `.xlsx` | workbooks: fills named cells \u0026 regions while **preserving formulas** and workbook structure |\n\nAll three expose the same three verbs: **`extract` → `verify` → `generate`** - each skill is self-contained and **same-format** (a Word template makes Word documents, never a deck or a sheet).\n\n---\n\n## The Brand Kit\n\nEach extracted template produces a self-contained, copyable directory:\n\n```text\nbrand-kit/\u003cname\u003e/\n├─ profile.json          # the brand rules: theme, roles, structure, anchors, catalog\n├─ PROFILE.md            # human-readable summary (role map + structure)\n├─ template/shell.docx   # the original template, kept byte-for-byte (the shell)\n└─ provenance.sha256     # source hash for drift detection\n```\n\n`brand-kit/` lives either in your **project** (`./brand-kit/`, versionable, wins) or **globally** (`~/.claude/brand-kit/`, reusable across projects). It is the template's portable memory - copy the folder and the brand travels with it.\n\n---\n\n## Prerequisites \u0026 installation\n\n### Required (core extract / generate / deterministic QA)\n\n- **Python ≥ 3.10**\n- Python packages (installed via `requirements.txt`): `python-docx\u003e=1.1`, `python-pptx\u003e=1.0`, `openpyxl\u003e=3.1`, `lxml\u003e=5.0`, `Pillow\u003e=10.0`\n\n```bash\ngit clone https://github.com/ferdinandobons/brand-docs.git\ncd brand-docs\npython3 -m venv .venv \u0026\u0026 . .venv/bin/activate     # Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\n### Optional (visual QA - render-based checks)\n\nNeeded only for the **visual** verification pass; their absence degrades gracefully and never blocks extraction, generation, or deterministic QA.\n\n- **LibreOffice** (`soffice`) - headless render to PDF\n- **Poppler** (`pdftoppm`) - PDF → PNG\n- **PyMuPDF** (`fitz`) - optional PDF → PNG fallback when Poppler is unavailable\n- **Tesseract** (`tesseract`) - optional OCR for rendered residual placeholder/demo text\n\n```bash\n# macOS (Homebrew)\nbrew install --cask libreoffice \u0026\u0026 brew install poppler tesseract\npython -m pip install PyMuPDF   # optional fallback\n# Debian / Ubuntu\nsudo apt-get install -y libreoffice poppler-utils tesseract-ocr\npython -m pip install PyMuPDF   # optional fallback\n# Fedora\nsudo dnf install -y libreoffice poppler-utils tesseract\npython -m pip install PyMuPDF   # optional fallback\n# Windows: winget install TheDocumentFoundation.LibreOffice\n#          + Poppler via conda-forge or a prebuilt binary on PATH\n#          + optional: winget install UB-Mannheim.TesseractOCR\n#          + optional: python -m pip install PyMuPDF\n```\n\nCheck what's available at any time:\n\n```bash\npython scripts/brandkit/cli.py doctor\n```\n\n`doctor` lists each dependency (present or missing) and prints the exact install command for anything missing - it never fails the run.\n\n### Install as an agent skill\n\n**Claude Code** (loads all three skills + the shared engine together):\n\n```text\n/plugin marketplace add ferdinandobons/brand-docs\n/plugin install brand-docs\n```\n\n**Codex** (clone + symlink the skills):\n\n```bash\ngit clone https://github.com/ferdinandobons/brand-docs.git ~/.codex/brand-docs\ncd ~/.codex/brand-docs \u0026\u0026 python3 -m venv .venv \u0026\u0026 . .venv/bin/activate \u0026\u0026 pip install -r requirements.txt\nmkdir -p ~/.codex/skills\nfor s in brand-docx brand-pptx brand-xlsx; do ln -s ~/.codex/brand-docs/skills/$s ~/.codex/skills/$s; done\n```\n\n\u003e Restart/reload the agent after installing if the skills don't appear immediately.\n\n---\n\n## Quick start\n\n### With an AI agent (the intended experience)\n\nJust describe what you want and attach a template:\n\n\u003e \"Use this company Word template and write a report on the history of Napoleon.\"\n\nThe agent activates `brand-docx`, extracts a Brand Profile from the template (or reuses an existing one), turns your request into the template's structure, generates the `.docx` from the original shell, runs QA, and returns the file.\n\n### Direct CLI (the engine - for tests \u0026 debugging)\n\n```bash\n# 1) Extract the brand from a template into a reusable kit\npython scripts/brandkit/cli.py extract --name acme --template template.docx --scope project\n\n# 2) Verify the profile (role mapping + QA; fails if a role points at a missing artifact)\npython scripts/brandkit/cli.py verify --name acme --scope auto --qa auto\n\n# 3) Generate a new on-brand document from structured content\npython scripts/brandkit/cli.py generate --name acme --input idoc.json --output out.docx --scope auto --qa auto\n```\n\nThe content you pass in (`idoc.json`) is an **IntermediateDocument** - brand-agnostic typed blocks. Notice there is **no style, color or font anywhere**: the profile resolves all of that.\n\n```json\n{\n  \"cover\": { \"title\": \"Quarterly Review\", \"fields\": { \"doc_id\": \"RPT-001\" } },\n  \"blocks\": [\n    { \"type\": \"heading\", \"level\": 1, \"text\": \"Highlights\" },\n    { \"type\": \"paragraph\", \"text\": \"This paragraph resolves to the brand body style.\" },\n    { \"type\": \"callout\", \"intent\": \"info\", \"text\": \"The profile chooses the callout style.\" },\n    { \"type\": \"list\", \"items\": [{ \"text\": \"List styling comes from the profile.\" }] },\n    { \"type\": \"table\", \"columns\": [\"Area\", \"Status\"], \"rows\": [[\"Pipeline\", \"Healthy\"], [\"Delivery\", \"Green\"]] }\n  ]\n}\n```\n\nPowerPoint uses the same `IntermediateDocument`; Excel uses a `GridDocument` (named-region fills, formulas preserved).\n\n---\n\n## Website, AI discovery \u0026 listings\n\n- Public website: [ferdinandobons.github.io/brand-docs](https://ferdinandobons.github.io/brand-docs/)\n- AI crawler summary: [`docs/llms.txt`](docs/llms.txt)\n- Directory submission kit: [`docs/DIRECTORY_SUBMISSIONS.md`](docs/DIRECTORY_SUBMISSIONS.md)\n\nThe website is a static GitHub Pages entry point for people searching for an\nAI Office document generator, Claude Code skill, Codex skill, document\nautomation tool, or template-to-document workflow. `llms.txt` gives AI search\nsystems a compact canonical summary, while the directory kit keeps listing\ncopy, categories, tags and pull-request text reusable.\n\n---\n\n## Project status\n\n**Alpha.** The Word vertical (`brand-docx`) is the reference implementation, verified end-to-end on real templates; PowerPoint and Excel share the engine and are catching up.\n\n| Area | Status |\n|---|---|\n| Shared engine (profile schema, resolver, OOXML, CLI, dual store) | ✅ working |\n| `brand-docx` - extract → verify → generate | ✅ working |\n| Document **structure** extraction \u0026 order-aware generation | ✅ working |\n| Brand-guarantee enforcement (`verify` fails on missing artifacts) | ✅ working |\n| Deterministic QA (L0: styles, palette, residual text, tables, formula preservation, language) | ✅ working |\n| `brand-pptx` - roles from real layouts, basic generation | 🚧 early |\n| `brand-xlsx` - named-region fills, formula-preserving | 🚧 early |\n| Visual QA (LibreOffice render + manifest-driven repair loop) | 🚧 implemented with graceful degraded mode |\n| Native PPTX charts / SmartArt / richer component regeneration | 🔭 catalogued, regeneration staged |\n| PyMuPDF PDF raster fallback | ✅ working |\n| Optional OCR rendered-text residual scan | ✅ working when Tesseract is installed |\n| Template-based skill eval set (DOCX/PPTX/XLSX) | ✅ working in CI |\n| Strict visual mode (`--qa strict`) | ✅ working |\n| Richer image analysis | 🔭 planned |\n\nVisual Word overflow needs LibreOffice, since Word lays out at render time.\n\n---\n\n## Changelog\n\nThe latest release is\n[v0.1.0](https://github.com/ferdinandobons/brand-docs/releases/tag/v0.1.0).\nSee [CHANGELOG.md](CHANGELOG.md) for release notes.\n\n---\n\n## Development\n\n```bash\npython3 -m venv .venv \u0026\u0026 . .venv/bin/activate\npip install -r requirements.txt pytest\nPYTHONPATH=scripts pytest -q        # docx / pptx / security / integration / smoke suites\n```\n\n\u003e **Never commit real templates or company assets.** `brand-kit/` and `generated/` are intentionally git-ignored, and `tests/test_no_proprietary.py` fails the build if any Office binary is tracked outside `tests/fixtures` (or a vendored proprietary import sneaks in). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and the frozen vocabulary in [`CONVENTIONS.md`](CONVENTIONS.md).\n\n---\n\n## FAQ\n\n**What is BrandDocs in one line?**\nAn open-source [Claude Code](https://www.anthropic.com/claude-code) skill bundle that turns a company's Word, PowerPoint or Excel template into unlimited on-brand documents of the same format.\n\n**How do I generate on-brand Word, PowerPoint and Excel documents from a company template?**\nPoint BrandDocs at one branded `.docx`, `.pptx` or `.xlsx`. It `extract`s a reusable **Brand Profile** (theme colors, fonts, named styles, document structure, layouts, logos, tables, formulas), then `generate`s new documents from the original template shell. See [Quick start](#quick-start).\n\n**How is this different from asking ChatGPT or Claude to \"use this template\"?**\nGeneral-purpose document skills only loosely imitate a reference file, so fonts drift, the palette wanders and the corporate cover → contents → body structure is lost. BrandDocs is faithful **by construction**: generators never write a literal style name, hex color or font, and `verify` refuses any profile that points at something the template doesn't define. See the [comparison table](#why-not-just-ask-an-ai-to-use-this-template).\n\n**Does it work with Codex or other agents, not just Claude Code?**\nYes. The three skills (`brand-docx`, `brand-pptx`, `brand-xlsx`) are plain agent skills; [installation](#install-as-an-agent-skill) covers both Claude Code and Codex. The underlying engine is also usable as a direct Python CLI.\n\n**Is it free and open source?**\nYes — **MIT licensed**, self-contained, pure `python-docx` / `python-pptx` / `openpyxl` + OOXML. No cloud, no external services, no vendor lock-in.\n\n**Does it keep my templates private?**\nEverything runs locally. `brand-kit/` and `generated/` are git-ignored, and a test fails the build if any real Office binary is committed. Never commit real company templates — use synthetic fixtures.\n\n**Can it preserve Excel formulas and the template's structure?**\nYes. Excel generation fills named cells and regions while **preserving formulas**, and Word/PowerPoint generation keeps the template's ordered skeleton (cover → table of contents → body). See [Structure-aware](#structure-aware-not-just-style-aware).\n\n**Keywords:** AI document generator · on-brand document generation · template to document · Claude Code skill · Codex skill · AI agent skill · brand template automation · corporate template to document · docx / pptx / xlsx generator · Word / PowerPoint / Excel automation · Office automation · OOXML · python-docx · python-pptx · openpyxl · brand profile · brand kit · document automation.\n\n---\n\n## License \u0026 acknowledgements\n\n- This project's own code is **[MIT](LICENSE)** © 2026 Ferdinando Bonsegna.\n- Self-contained: the OOXML engine is re-implemented from scratch; it does **not** vendor any proprietary or third-party Office tooling. See [`NOTICE`](NOTICE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fferdinandobons%2Fbrand-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fferdinandobons%2Fbrand-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fferdinandobons%2Fbrand-docs/lists"}