pdfcraft/AGENTS.md

AGENTS.md — rules for every agent and contributor

These rules bind every AI agent and every human contributor working in this repository. They come before any task, instruction or deadline. CLAUDE.md holds the day-to-day working instructions. If the two ever disagree, this file wins.

---

1. Asset policy (absolute — no exceptions)

An asset is any non-code material that the project includes, ships, embeds, generates for publication, or shows in its documentation. This covers:

• icons, images, illustrations, screenshots and logos;
• fonts;
• colour profiles and other binary data files;
• sounds and video;
• sample, demo and test documents that are committed or published;
• anything the app renders from those.

1.1 Nothing from Adobe products

• Never use icons, images, artwork, logos, UI graphics, fonts, stamps, cursors, sample documents or any other asset taken from an Adobe product, installer, website, document or package.

  • "Adobe product" includes Acrobat, Reader, Photoshop, Illustrator, Premiere, Lightroom and Creative Cloud, including the fonts they install (for example Minion, Myriad, Kozuka and the Adobe CJK families).
  • This holds even when Adobe publishes the material under an open licence, if it is visual design. For example, do not use Source Han, Source Serif or Source Sans, or Noto CJK, which is Source Han rebranded.

• Never recreate, trace, redraw or closely imitate an Adobe icon or graphic. Our icons come from Lucide, and our visual design is our own.

• Screenshots of Adobe software exist only as private, local observation notes under plan/acrobat/, which is gitignored. They must never be committed, published, linked, shown in docs, used as a design source to trace, or placed anywhere else in the repository or its outputs.

• The only Adobe-authored material allowed is non-visual technical data that is openly licensed and required for PDF compatibility. Each item needs its own entry in ATTRIBUTION.toml with adobe_data = true, and the list below is closed:

  • The CMap resources (BSD-3-Clause), bundled inside the hayro-cmap dependency.
  • The standard-14 font metrics and encoding tables in the PDF specification. They are data, not typefaces, and are embedded as code in hayro.

  Adding anything to this list needs the user's explicit approval.

1.2 Only open, provable licences

Every asset must be one of:

• Open source: ISC, MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, OFL-1.1, Ubuntu-Font-1.0 or Bitstream-Vera.
• Creative Commons: CC0-1.0, CC-BY-4.0 or CC-BY-SA-4.0.
• Public domain.
• Contributor-original: created, photographed or generated by a contributor who owns it and licenses it under the project licence (MIT OR Apache-2.0).

Anything else is forbidden, including assets whose licence you cannot prove from the source. Examples:

• system fonts (Apple, Microsoft, Google Android system UI fonts that are not openly licensed);
• emoji artwork from Apple, Microsoft or Samsung;
• stock photos;
• "free for personal use" material;
• screenshots of other people's software.

Screenshots of PrintCraft are contributor-original. Everything visible in them must itself be allowed: our UI, Lucide icons, OFL fonts, and demo documents built only from allowed assets. Never screenshot a document that uses proprietary fonts or images.

1.3 Every asset is attributed

• ATTRIBUTION.toml (repo root) is the single source of truth. It has one entry per asset file, whether committed, vendored, fetched at build time or bundled through a Cargo dependency. Each entry records:
  • path or URL, title, author;
  • source (URL, with version or commit);
  • SPDX licence, and the licence file in the repo;
  • SHA-256;
  • how it is used.
• ATTRIBUTION.md is generated from it (cargo xtask assets --write). Never edit it by hand.
• NOTICE keeps the licence notices that the licences require.
• cargo xtask assets runs in cargo xtask ci. It fails if:
  • an asset file in the repository has no entry;
  • an entry's hash does not match;
  • a licence is not on the allowlist;
  • a licence file is missing;
  • an image, icon or font names Adobe as author or source.
• cargo xtask demo-pdf downloads its fonts only from ATTRIBUTION.toml entries, pinned by SHA-256. Afterwards it fails if the PDF embeds any font not in its allowlist, which catches the browser silently falling back to a system font.

1.4 Procedure for adding or changing an asset

1. Find an asset under an allowed licence from its original source: the author's repository or a release, not a random mirror. Record the exact version or commit.
2. Confirm the authorship. It must not be Adobe (§1.1). Keep the licence text.
3. Add the file together with its licence file, plus an ATTRIBUTION.toml entry. Run cargo xtask assets --write, then cargo xtask assets.
4. If an asset's origin or licence is unclear, do not add it. Ask the user.

If you find an asset that breaks these rules, stop and remove it from the repository and every output, including docs, screenshots and generated PDFs. Then tell the user at once.

---

2. Clean-room rules (summary; details in CLAUDE.md and plan/adr/0001)

• Never read, disassemble or copy anything inside the Acrobat bundle. Only names and listings are allowed, and never open Contents/Resources/JavaScripts/.
• Behaviour comes only from public specifications (ISO 32000-2, the Arlington model), public documentation and black-box observation.
• Never copy GPL/AGPL code. Copyleft tools run only as external oracle processes.
• Observe Acrobat only with synthetic fixtures. Never capture personal data, account information or recent files.

3. Everything else

Follow CLAUDE.md. It covers quality gates, layering, commit rules and how to run and look at the app.