AlexandrAI AGENTS.md
agents-md

Gumroad CLI Publish Script Agent Guide

Project-specific AGENTS.md guidance for scripts/gumroad_cli.py, dry-run planning, publish refusal gates, local file upload, preview image ordering, and inline media handling.

AGENTS.md

Guidance for coding agents working on scripts/gumroad_cli.py.

Project Overview

scripts/gumroad_cli.py dry-runs or publishes one prepared Gumroad product directory. It reads product.json and build/manifest.json, collects optional preview images, writes gumroad_plan.json for dry-run, and refuses publish unless QA passed and a custom cover is present.

Source Files

  • scripts/gumroad_cli.py owns plan(), publish(), collect_preview_images(), gumroad_create_command(), and inline media description handling.
  • products//product.json provides title, price, taxonomy, tags, summary, and description.
  • products//build/manifest.json provides local PDF, template ZIP, cover, and cover_custom.
  • products//assets/page-images/ supplies sorted preview images.
  • tests/test_gumroad_cli_preview_images.py verifies preview ordering, taxonomy id inclusion, no default coupon, and inline preview figure insertion.

Setup Commands

bashpython3 scripts/gumroad_cli.py dry-run products/<slug>
python -m unittest tests/test_gumroad_cli_preview_images.py

Use publish only after QA passes and owner mode is explicit publish.

Change Rules For Agents

  • Keep dry-run side-effect-light and write gumroad_plan.json.
  • Do not create offer codes in the publish script; discounts belong to the discount manager.
  • Keep preview images sorted and passed as preview image arguments.
  • Preserve taxonomy id and taxonomy path in the dry-run output.
  • Refuse publish when qa_report.json is missing or failed.
  • Refuse publish when cover_custom is false.
  • Check Gumroad CLI auth before mutating the account.
  • Stop after publish failure; do not create duplicate products automatically.
  • Do not change product files after QA inside the publisher.

Verification

Run the unit test and dry-run command. Confirm gumroad_plan.json lists local PDF, ZIP, cover, previews, tags, taxonomy, cover_custom, and intended CLI calls.

Security Notes

Do not log credentials, private CLI auth state, buyer data, local absolute paths in public docs, private media URLs, or hidden account settings. Report repo-relative paths in human-facing summaries.

PR Checklist

  • Dry-run still works without account mutation.
  • Publish refusal gates remain strict.
  • Preview images are sorted and included.
  • No default coupon behavior was added.
  • Failure handling stops clearly.