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).

One narrow exception: the ArtCraft brand. The ArtCraft name, wordmark and logos in docs/brand/ are trademarks of the ArtCraft Team and are not open source (manifest identifier LicenseRef-Storyteller-Trademark, terms in docs/brand/LICENSE-brand.txt). They may be used only unmodified, only within PrintCraft, and only as kind = "logo" entries from that directory, to identify the project. Forks and modified versions must remove them. Never add other files under this licence, and never modify the logos.

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 Fonts live in craft-fonts

• Font assets shared by the Crafting Apps, including every Japanese font, live in storytold/craft-fonts, not here. Never commit a font file to this repository; adding a font means adding it to craft-fonts. (The Latin UI fonts already in assets/fonts/ — Inter, JetBrains Mono, Dancing Script — stay.) The rules are in craftrules standards/fonts.md.
• craft-fonts is an optional build input, never a Cargo dependency: CRAFT_FONTS_DIR=<checkout> cargo build makes crates/fonts/build.rs embed its fonts as printcraft_fonts::CRAFT_FONTS. Without it PrintCraft builds, tests and runs, but has no Japanese face (Japanese UI text shows replacement boxes, and writing Japanese into a PDF returns a clear error). Release builds always set it (.github/workflows/release.yml), and ATTRIBUTION.toml lists it as a [[build_input]].

1.5 Procedure for adding or changing an asset

Fonts go to craft-fonts instead (§1.4).

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.
• Shared real-file test oracles (Photoshop-authored PSDs, etc.) live in storytold/photocraft-corpus, explained in craftrules standards/test-corpora.md. Never commit large binary fixtures to this repo; fetch them pinned by commit and sha256-verified, as PhotoCraft does with cargo xtask corpus.

3. Agent control (automation and MCP)

• Everything is reachable headlessly. Every user-facing feature must be callable without the GUI: an engine API, then a tool in crates/automation (printcraft-cli run and MCP use the same table). A feature is not done until its tool exists and has an end-to-end test (crates/automation/README.md, "Adding a tool").
• The UI control channel is opt-in too. It runs only when the app is launched with --control <file>. It binds to loopback, uses a fresh random token per launch, and writes it to an owner-only file. Never enable it by default, widen the bind address, or log the token.
• The MCP server is opt-in. Never make the app, the CLI or an installer start it, register it with an agent, or listen on a port by default. It runs only when a user (or an agent the user configured) launches printcraft-cli mcp. Any future network transport must be off by default, bound to loopback and authenticated with a token.
• Safe by default. Tools must never discard unsaved work silently, must write atomically, must honour --root, and must return errors an agent can act on (say what was wrong and what is allowed).
• Track parity honestly. Every user-facing feature has an entry in parity/acrobat-features.toml. Mark it shipped only when it works end to end and the entry cites a passing test (evidence); cargo xtask parity (part of xtask ci) rejects claims whose commands, tools or tests don't exist.
• Use it to test. Agents should drive the engine through printcraft-cli run --script or the MCP tools, and look at page_render output, to check their own changes. For UI changes, launch the app with --control and use printcraft-cli ui (inspect, click, screenshot) to check the real interface.

4. Never crash

PrintCraft opens files from strangers, and people trust it with their work. A malformed PDF, a bad tool argument, a corrupt settings file or a full disk must produce an error the user (or agent) can act on, never a crash and never lost work. This outranks feature work: don't ship a feature by adding a panic path, and fix a crash before building on top of it. The shared standard for every Crafting App is craftrules/standards/never-crash.md.

• Fail with Result. Non-test code returns errors through the crate's error type and ?. Where readers are lenient by design, fall back gracefully and record the repair (see Fidelity in CLAUDE.md).
• No panicking shortcuts. No unwrap(), expect(), panic!, unreachable!, todo! or unimplemented! outside tests, unless the call is provably infallible (e.g. writing to a Vec), with a comment saying why. assert! only for internal invariants that input cannot reach.
• No unsafe. The workspace sets unsafe_code = "forbid". If a platform API needs it, use a maintained safe wrapper crate; a real exception needs the owner's sign-off.
• Treat every input-derived number as hostile. Use get() instead of [i] or [a..b]. Slice strings only at char boundaries. Use checked/saturating arithmetic for lengths, offsets and counts. Guard against division by zero and NaN/inf casts, and never cast a negative value to usize. Cap allocations sized by the file.
• Bound recursion. Object graphs can be cyclic or deeply nested. Walk them with seen-sets or depth limits.
• Don't cascade. Handle lock poisoning, and keep a panic in a worker thread from taking the app down. Engine entry points that run untrusted-document code keep their last-resort catch_unwind guard, and command execution and file import/export must sit behind one that turns an escaped panic into an error message and keeps the user's document. Keep panic = "unwind" (the default) so the guard works. It is a safety net, not a substitute for the rules above.
• Prove it. Every crash fix comes with a small synthetic regression test that panicked before the fix. Turn fuzzer findings (cargo xtask fuzz) into such tests before fixing them.
• Enforced by clippy. Root clippy.toml lets tests use unwrap/expect/panic!. A crate that is clean carries #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]; new crates start with it.

5. Everything else

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