AlexandrAI AGENTS.md
agents-md

Gumroad Product Artifacts Render Pipeline Agent Guide

Project-specific AGENTS.md guidance for scripts/product_artifacts.py render, generated guide files, PDF, template ZIP, cover handling, description output, and manifest contract.

AGENTS.md

Guidance for coding agents working on the Gumroad product artifacts render pipeline.

Project Overview

scripts/product_artifacts.py render turns products/<slug>/product.json into buyer-facing build outputs. It writes guide markdown, guide HTML, a PDF, template files, a template ZIP, description HTML, a cover image, and build/manifest.json.

Source Files

  • scripts/product_artifacts.py owns render_product(), build_cover(), markdown_guide(), html_guide(), PDF writing, template extraction, and manifest writing.
  • products//product.json is the input.
  • products//assets/cover.png is the custom cover input when present.
  • products//build/ contains generated outputs.
  • tests/test_product_artifacts_content_quality.py checks quality gates.

Setup Commands

bashUV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT="$HOME/.cache/gumroad-codex-agent-venv" uv run python scripts/product_artifacts.py render products/<slug>/product.json

Generated Outputs

  • build/guide.md
  • build/guide.html
  • build/.pdf
  • build/-templates.zip
  • build/templates/
  • build/description.html
  • build/cover.png
  • build/manifest.json

Change Rules For Agents

  • Treat build/ as generated output.
  • Do not edit generated guide files directly; edit product.json and rerender.
  • Preserve template filenames through safe relative paths only.
  • Keep PDF content complete, not teaser-only.
  • Preserve the cover_custom flag so publisher can block fallback-cover publish attempts.
  • Keep manifest paths accurate for gumroad_cli.py.
  • Do not add remote fetches, private URLs, or credentials to render output.
  • Rerender after any product, cover, preview, or template change.

Verification

Run product QA after render. Confirm the PDF starts as a valid PDF, the template ZIP is non-empty, cover exists, description HTML exists, and manifest points to the files the publisher will use.

Security Notes

Generated artifacts become sale files or publishing inputs. Do not render secrets, buyer data, private hosts, hidden account ids, local absolute paths, or unreviewed automation credentials.

PR Checklist

  • product.json changed before render.
  • build outputs are regenerated.
  • manifest matches generated files.
  • cover_custom is correct.
  • QA runs after render.