archforge 0.11.0

The preflight linter for AI-generated PowerPoint.

Catches silent font fallback, unreadable sizes, colliding frames, off-canvas text, and AI-tell punctuation in built .pptx files, before a human ever sees a render. Font-fallback and letter-tracking detection (E1/E4) is CJK-specific by design -- deepest for Hangul -- and does not fire on Latin-only decks, and the small-text rule W8 is gated the same way; every other gate is script-independent.

Try it in your browser -- no install, the deck never leaves the page: love-ash.github.io/archforge

Quickstart · What it catches · CI · Calibration record · Corpus results · Discussions · 한국어 README

AI agents / LLMs: read llms.txt, or pip install archforge then archforge skill --install to teach your agent the build-lint-fix loop.

PowerPoint opens both of these decks without a single warning. One of them is broken:

Code review cannot see any of it, because the defects live in font slots, autofit scales, and coordinates that only materialize at render time. Archforge reads the .pptx itself (XML, font-resolution chain, geometry, image alpha), so it needs no PowerPoint installation and runs anywhere your agent or CI runs.

30 seconds

pip install archforge
archforge demo        # builds broken.pptx + fixed.pptx and lints both, in front of you

Then point it at your own deck:

archforge deck.pptx                 # objective defects only (core profile, the default)
archforge deck.pptx --profile full  # + AI-tell / style rules: machine-made decks want this
archforge deck.pptx --json          # machine-readable JSON (agents / CI)
archforge scan decks/ --profile full   # many files, directories, or globs in one run

The decks in examples/ demonstrate the flagship defects and the profile split, each with expected outputs.

Why

The worst pptx defects are silent. No error is raised when:

• text lands on a font that lacks its glyphs and silently falls back to an OS default (the classic case: CJK text on a Latin-only font)
• positive letter-spacing quietly wrecks CJK character spacing
• autofit shrinks text below readable size
• text frames collide, or glyphs run off the canvas

These are exactly the defects machine-generated decks produce, and exactly the ones an LLM cannot see in its own output. Archforge is the gate between "the build succeeded" and "a human would sign off on the render." It is deliberately independent of the authoring side: whether the deck came from python-pptx, PptxGenJS, OfficeCLI, or PowerPoint itself, the same file goes in and the same exit code comes out, and the public corpus keeps fixtures from all four writers to enforce that.

Usage

archforge deck.pptx --profile full --fail-incomplete --json   # the agent/CI command
archforge scan decks/ --profile full         # many files, dirs, or globs at once
archforge fix deck.pptx -o fixed.pptx        # auto-fix E1/E2/E4 (new in 0.8.1)
archforge deck.pptx --html report.html       # annotated visual report (new in 0.8.1)
archforge deck.pptx --sarif o.sarif          # SARIF / --junit o.xml for CI systems
archforge rules                              # rule list; `archforge explain W15` for one

Every flag (thresholds, baseline, severity overrides, schema 2.0, timeout), the config file, and the JSON contract: docs/USAGE.md. Recipes: Claude Code · Codex/agents · PptxGenJS · OfficeCLI · GitHub Actions.

CI

GitHub Action (composite). Pinning the action tag pins the linter: by default it installs the exact source checked out at that ref, not whatever PyPI's latest is. Deck-folder config files are ignored (--no-config) and incomplete checks fail (fail-incomplete: true) unless you opt out, so a PR cannot weaken the gate by committing a config next to its deck. files takes one path, directory, or glob per line; globs are expanded by archforge scan itself, so paths with spaces and ** both behave.

jobs:
  deck-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Love-Ash/archforge@v0.11.0
        with:
          files: |
            decks/
          profile: full
          sarif: archforge.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: archforge.sarif

pre-commit:

repos:
  - repo: https://github.com/Love-Ash/archforge
    rev: v0.11.0
    hooks:
      - id: archforge
        # args: [--profile, full]

What it catches

ERRORs block shipping (exit 1):

WARNs are advisory:

Profiles separate objective defects from style policy, and since 0.4.0 the default is core: only the mechanical gates (E1/E3/E4, W1/W5/W7/W8, W15-W18) run unless you opt in. full adds the AI-tell and convention rules (E2 dashes, W6 repetition, W9-W14) and the render rules still soaking their thresholds (W19-W22), and is the right mode for agent build-loops linting machine-generated decks; editorial drops W6/W14 and the soaking W19-W22 for editorial and portfolio decks. Excluded rules are not merely hidden, they are not executed, and every choice is recorded in the JSON summary, so nothing is silently bypassed.

How it works

The E1 font-resolution model is measured, not guessed from the OOXML spec: probe decks rendered through PowerPoint COM pinned the actual priority (run a:ea > paragraph defRPr > lstStyle chain > theme ea > a:latin on an empty theme slot > OS fallback). Effective sizes walk the same chain; geometry approximates real glyph and image-ink areas with insets, group transforms, and merged cells; incompleteness is a first-class output (W18 / summary.incomplete), so summary.pass under --fail-incomplete is the honest gate. Font-coverage knowledge is Hangul-deep and CJK-aware; other scripts are never falsely flagged; the target renderer is PowerPoint for Windows.

Full model, calibration method, renderer-coverage matrix, and scope: docs/HOW_IT_WORKS.md and docs/CALIBRATION.md. Roadmap to 1.0: docs/ROADMAP.md. What is stable and what may move: docs/DEPRECATION.md.

Agent integration

Designed for LLM-agent build-lint-fix loops:

build deck.pptx
loop:
    result = archforge deck.pptx --profile full --fail-incomplete --json   # machine-made decks
    if result.summary.pass: break   # pass reflects the active policy (summary.policy)
    fix listed defects (location payloads point at the exact shape/run), rebuild
review WARNs against renders

The Agent Skills pack (standard SKILL.md + YAML frontmatter) teaches this loop and per-code fixes to any supporting agent (Claude Code, Codex, ...). It ships inside the wheel: archforge skill --install. If you cloned the repo, skills/archforge-pptx-lint/ is the same file.

A passing lint is not a finished deck: the linter owns the mechanical defect class; composition and narrative still need eyes on renders.

Community and contributing

• Found a false positive? Report it with the FP template: a repro deck makes it a permanent regression fixture, the most valuable contribution this project takes.
• Questions, ideas, decks you are unsure about: GitHub Discussions.
• Want to contribute code? CONTRIBUTING.md explains the evidence bar (gates are calibrated against renders, not taste); issues tagged good first issue are scoped for a first PR.
• Security: SECURITY.md.

Name

archforge = arch (structure) + forge. A forge where a deck's structure and typography get hammered straight before shipping.

Author

Built and calibrated by Minjae Kwon (Ash) (@Love-Ash · LinkedIn). If archforge caught something before your audience did, a star helps the next person find it. I write up the measurement work behind the gates (how PowerPoint actually resolves fonts, and what AI-built decks silently break); say hi on LinkedIn.

License

MIT © Minjae Kwon (Ash)