AlexandrAI AGENTS.md
agents-md

Gumroad Publisher Agent Guide

Project-specific AGENTS.md guidance for the Gumroad publisher role, dry-run default, explicit publish flow, required artifacts, preview image handling, and failure boundaries.

AGENTS.md

Guidance for coding agents working on the Gumroad publisher role.

Project Overview

The publisher handles Gumroad mechanics only after QA. It verifies the product directory, manifest, local PDF, template ZIP, cover PNG, optional preview images, and mode. It dry-runs by default and publishes only when the owner explicitly requested publish mode.

Source Files

  • agents/gumroad-publisher.md defines the role.
  • skills/gumroad-cli-publisher/SKILL.md defines dry-run, publish, and failure handling.
  • scripts/gumroad_cli.py wraps the local Gumroad CLI.
  • products//qa_report.json must show passed QA.
  • products//build/manifest.json lists local PDF, ZIP, cover, and cover_custom state.
  • products//assets/page-images/ may contain optional preview images.
  • products//gumroad_plan.json is the dry-run record.
  • products//gumroad_result.json is the publish record.

Setup Commands

bashpython3 scripts/gumroad_cli.py dry-run products/<slug>
python3 scripts/gumroad_cli.py publish products/<slug>

Use publish only in explicit publish mode after QA and custom cover gates pass.

Change Rules For Agents

  • Do not rewrite product content in the publisher role.
  • Do not publish a directory different from the QA-checked directory.
  • Do not change files after QA without rerunning render and QA.
  • Do not require a separate API key for the normal local workflow.
  • Do not publish with a fallback cover.
  • Include prepared preview images when present.
  • Stop on the first publish failure and report whether a product id was created.
  • Do not create duplicate products automatically.
  • Do not create discount campaigns unless the owner explicitly requested that separate flow.

Dry-Run Expectations

Dry-run writes products/<slug>/gumroad_plan.json and should show title, price, currency, tags, local PDF path, local ZIP path, local cover path, preview image paths, cover_custom state, and the commands that would run.

Publish Expectations

Publish creates the product, uploads the PDF, template ZIP, cover, and previews, updates rich description with preview media when returned, publishes the product, and writes gumroad_result.json.

Verification

bashpython3 scripts/gumroad_cli.py dry-run products/<slug>

Before publish, confirm qa_report.json passed, build/manifest.json exists, cover_custom is true, and owner mode is publish.

Security Notes

Do not publish credentials, private paths, buyer data, or hidden account state. Report result files by repo-relative path only.

PR Checklist

  • Dry-run is default.
  • Publish is explicitly requested.
  • QA and custom cover gates pass.
  • Preview images are included when present.
  • Failure handling stops without automatic duplicate creation.