diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5ff962c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# beffroi-tools + +This repository contains small Python command-line tools for everyday local +document and media workflows. Keep them simple to run and document their usage +in `README.md`. + +## Current tools + +- `pptx_videos.py` discovers and extracts embedded PPTX videos, maps them to + slides, probes metadata with FFmpeg's `ffprobe`, and generates timing reports + in Markdown, plain text, JSON, HTML, Typst, and PDF. PDF reports compile through + the Typst CLI. +- `exporter.py` uses DeckCraft to export PPTX presentations to PDF or PNG slides, + and PdfCraft to render PDF pages as PNGs. It discovers CLI executables or + locally installed AppImages. PDF-to-PDF is a successful no-op. +- `test_exporter.py` covers exporter validation, no-op behavior, conversion + failures, and overwrite behavior. + +## Working conventions + +- Prefer Python's standard library and existing external CLI tools over adding + dependencies. +- Preserve source documents. Keep temporary files temporary and require an + explicit overwrite option when replacing existing exports. +- Provide useful progress and actionable errors. Terminal colors should respect + `NO_COLOR` and disappear when output is redirected. +- Preserve slide order, readable aligned text reports, and consistent styling + in visual reports. +- Update `README.md` when command-line options or workflows change. +- Run checks appropriate to the change before committing. Exporter regression + tests run with `python -m unittest test_exporter -v`. For rendering changes, + test with the actual external tools when available and inspect visual output. + Report any checks that could not be completed. + +## Commit every task + +- Every completed task that changes repository files must end with a Git commit. + Committing the task is part of completing it; do not wait for a separate user + request to commit. +- Inspect the working tree first. Stage only changes belonging to the task; + preserve unrelated or pre-existing changes. +- Use a concise, descriptive commit message explaining the change. +- Do not commit generated exports, temporary files, credentials, or caches. +- Include the commit hash and validation summary in the final response. +- If committing is blocked, explain why and identify the uncommitted changes. + Do not claim the task was committed. +- Read-only tasks need no empty commit. Do not push commits unless requested.