Skip to content

Documentation Agent

Yes: this is Gadarr's dedicated documentation agent page. Use it before publishing docs changes, screenshots, or release notes.

Gadarr has a dedicated documentation agent: scripts/documentation-agent.mjs. It owns the README/docs publish pass, the Loom-style MkDocs page format, safe demo seeding, screenshot capture and verification, game-native language drift checks, source-backed feature claims, and publish-state checks.

Mission

Keep Gadarr documentation accurate, game-native, screenshot-backed, source-backed, and honest about publish/deployment state. The agent should compare docs against the current code, routes, UI, screenshots, GitHub branch state, and deployment scripts before recommending or writing changes.

Dedicated Page Format

The docs site follows the same broad shape as the Loom page: a Material for MkDocs site with a short home page, a "Where to start" section, a screenshot-backed "What's in Gadarr" feature table, product principles, a complete guide, screenshot gallery, deployment notes, architecture/reference material, and an Agents section for this documentation agent.

The source lives in:

  • mkdocs.yml
  • docs/index.md
  • docs/guide.md
  • docs/screenshots/index.md
  • docs/documentation-agent.md

When publishing is explicitly in scope, the generated site can be published to the gh-pages branch with python3 -m mkdocs gh-deploy --force. The target URL is https://bigbeardedman.github.io/Gadarr/ after GitHub Pages is enabled for the repository. For documentation-only audit passes, do not run deploy commands.

Current hosting note: GitHub Pages is available for the public repository. Keep the gh-pages branch fresh, and only claim the public URL is live after pnpm exec node scripts/documentation-agent.mjs --check-pages or an equivalent HTTP check passes.

Loom-Style Home Checklist

Keep docs/index.md short enough to scan in one sitting:

  • One product sentence and one short explanation of how Gadarr maps the Arr loop to games.
  • A small screenshot strip using committed PNGs from docs/screenshots.
  • A "Where to start" list for install, Docker, indexers, parity, and publish-state checks.
  • A screenshot-backed feature table that links every major claim to a real UI capture.
  • Product principles that explain game-native behavior, compatibility boundaries, safety, Docker deployment, and documentation truth rules.
  • An Agents/publish-status section that links this page and states whether GitHub Pages is actually live.

Agent Prompt

Use this role when delegating, resuming, or automating documentation work:

You are Gadarr's documentation agent. Audit the current repository, running UI, screenshots, GitHub branch state, hosted Pages state, and deploy scripts before editing public docs. Keep every claim game-native and source-backed. Refresh screenshots from a live-safe local instance, verify the image files and README embeds, update README first, then supporting docs, and publish only after `git diff --check` passes. Do not claim GitHub, GitHub Pages, GHCR, Docker Hub, or runtime deployment success unless the relevant remote state proves it.

Required Pass

  1. Audit stale media-language and replace TV/movie/book phrasing with game vocabulary.
  2. Verify route names and feature claims from source before naming them in docs.
  3. Refresh screenshots from a seeded demo or live-safe local instance with --seed-demo --capture-screenshots.
  4. Confirm screenshots render as real PNG files, have useful dimensions, are committed under docs/screenshots, and are embedded from README.
  5. Update README first, then deeper docs: architecture, deployment, Prowlarr/indexer integration, parity check, roadmap, and historical research notes.
  6. Verify new source-backed claims before publishing, including Steam Owned Games, GOG Owned Games, Epic Owned Games, Legendary/Heroic Cache, Itch.io Library, Lutris Library, Amazon Games Library, EA App Library, Ubisoft Connect Library, and Battle.net Library import-list support plus deployment build-revision stamp guards.
  7. Verify the web UI button audit passes so every button, including every icon-only button, has both an accessible name and a hover title.
  8. Run the documentation agent script, then git diff --check before committing. Run typecheck/tests/build when code, scripts, examples, or documented commands changed.
  9. Push documentation commits to GitHub after local verification, then rerun the agent with --check-github to prove the remote branch contains the commit.
  10. When publishing is explicitly requested, publish or refresh gh-pages with MkDocs, then rerun the agent with --check-pages before calling the public docs page live.

Local Runbook

  1. Start from a clean understanding of the worktree:
git status --short --branch
rg -n -i "series|episode|movie|book|author|qBittorrent-only|private project scaffold|default crack exclusion" README.md docs apps packages -g '!node_modules'
  1. Verify the app state from source before writing claims:
rg -n "server\\.(get|post|patch|put|delete)|register.*Routes|type .*Kind|implementationName" apps/api packages/core apps/web/src/App.tsx
node scripts/sonarr-route-parity.mjs
node scripts/sonarr-query-parity.mjs
node scripts/sonarr-body-parity.mjs
node scripts/sonarr-resource-parity.mjs
  1. Use an existing live-safe local instance when available. If no UI is running, start one against a disposable database and external auth so screenshots do not require a first-run password:
export DATABASE_PATH=/tmp/gadarr-docs-demo.db
export GADARR_AUTH_METHOD=external
pnpm dev
  1. Seed the disposable docs database with safe demo rows. The seed uses deterministic IDs and placeholder paths only; it refuses non-demo database paths unless explicitly overridden:
DATABASE_PATH=/tmp/gadarr-docs-demo.db pnpm exec node scripts/documentation-agent.mjs --seed-demo --skip-parity
  1. Capture the screenshot set below from real UI routes. The agent uses a local Chromium-compatible browser such as Chrome or Edge and saves exact PNG files to the documented paths:
DATABASE_PATH=/tmp/gadarr-docs-demo.db pnpm docs:screenshots -- --seed-demo --base-url http://127.0.0.1:3000

Pass --browser /path/to/browser or set GADARR_DOCS_BROWSER if browser discovery cannot find Chrome, Edge, Chromium, or Brave. Use --width, --height, and --wait-ms only when the default 1440x1000 capture needs adjustment. The seeded demo data includes 007 First Light as the release-filter game, Crimson Desert as the live queue item with a visible game title and progress, Hades II as an installed patch example, one safe placeholder game indexer, store/library/TMDb import lists including Lutris Library, Amazon Games Library, EA App Library, Ubisoft Connect Library, and Battle.net Library, one enabled blackhole download client, and one remote path mapping. If a screenshot does not show every Servarr-compatible provider row, document that limitation and keep provider claims source-backed.

  1. Confirm image format and basic dimensions:
file docs/screenshots/*.png

Every screenshot must report PNG image data. If a browser saves JPEG bytes with a .png name, convert it before committing:

for f in docs/screenshots/*.png; do tmp="$f.tmp.png"; sips -s format png "$f" --out "$tmp" >/dev/null && mv "$tmp" "$f"; done
  1. Run the agent script and review the diff:
pnpm docs:agent
git diff -- README.md docs
git diff --check
  1. Build the hosted docs site before publishing:
python3 -m mkdocs build --strict

For documentation-only audit passes, stop after the local agent run, git diff --check, and python3 -m mkdocs build --strict. The remaining steps are for a requested publish.

  1. Commit only the intended documentation, screenshot, and documentation-agent files, push to GitHub, and verify the remote branch contains the commit:
git add README.md docs mkdocs.yml scripts/documentation-agent.mjs
git commit -m "Update documentation and screenshots"
git push origin main
pnpm exec node scripts/documentation-agent.mjs --check-github
  1. Publish the hosted GitHub Pages branch from the verified commit:
python3 -m mkdocs gh-deploy --force
  1. Check whether GitHub Pages is enabled and serving:
pnpm exec node scripts/documentation-agent.mjs --check-pages

Script Contract

scripts/documentation-agent.mjs is the executable documentation agent. It can seed safe demo rows with --seed-demo, capture screenshots with --capture-screenshots, checks required docs and hosted MkDocs files, verifies the screenshot set is real PNG bytes with dimensions, confirms README embeds every screenshot, scans for hard stale wording, warns about media vocabulary that is not clearly compatibility/historical context, verifies every React button has both aria-label and title, confirms current Steam Owned Games, GOG Owned Games, Epic Owned Games, Legendary/Heroic Cache, Itch.io Library, Lutris Library, Amazon Games Library, EA App Library, Ubisoft Connect Library, Battle.net Library, TMDb, GOG/Epic/Itch launcher-manifest, platform-mapping, build-revision stamp, and default release-filter claims against source, runs the Sonarr parity scripts, and runs git diff --check.

Use --seed-demo after starting Gadarr with a disposable docs database. The seed refuses ordinary database paths by default; use a path like /tmp/gadarr-docs-demo.db so real libraries, usernames, hostnames, API keys, host paths, and private queue items never become public screenshots:

DATABASE_PATH=/tmp/gadarr-docs-demo.db pnpm exec node scripts/documentation-agent.mjs --seed-demo --skip-parity

Use --skip-parity only while iterating locally on prose or screenshots. Do not use the skipped run as the final publish check.

Use --capture-screenshots with --seed-demo to refresh the screenshot set from a running disposable local UI before verification:

DATABASE_PATH=/tmp/gadarr-docs-demo.db pnpm exec node scripts/documentation-agent.mjs --seed-demo --capture-screenshots --skip-parity --base-url http://127.0.0.1:3000

Use --check-github after pushing to compare local HEAD against origin/<current-branch>. Override the remote or branch with --remote <name> or --branch <name> when publishing somewhere other than origin/main.

Use --check-pages after mkdocs gh-deploy to confirm GitHub Pages is enabled for BigBeardedMan/Gadarr and serving the configured site_url. If GitHub Pages is not enabled or the hosted URL still returns an error, report that as a hosting blocker instead of describing the docs page as live.

Use live-deploy proof only when the docs or release note explicitly claim the current commit is deployed on that runtime. Keep status files local and untracked; do not publish private share paths.

Screenshot Set

Capture these views whenever the UI materially changes:

  • docs/screenshots/games-library.png
  • docs/screenshots/game-detail-release-filters.png
  • docs/screenshots/activity-queue-live-download-tracking.png
  • docs/screenshots/settings-import-lists-steam-wishlist.png
  • docs/screenshots/settings-download-clients-remote-paths.png
  • docs/screenshots/system-status-deployment-doctor.png

Screenshot Route Hints

Use the current dev-server port. In local development the web app is usually http://127.0.0.1:3000; an already-running instance may use another free port such as 3100.

  • Games library: /games
  • Game detail release filters: /games/details
  • Activity queue live download tracking: /activity/queue
  • Store and watchlist import lists: /settings/import-lists
  • Download clients and remote path mappings: /settings/download-clients
  • System status and deployment health: /system/status

Truth Rules

  • Say game, library, release, patch, DLC, mod, queue, and download client; do not drift back to Series, Episode, Movie, Book, or Author language except when explaining Sonarr/Radarr compatibility aliases.
  • Do not describe download behavior as qBittorrent-only. qBittorrent is one supported client among protocol-aware torrent, Usenet, Synology Download Station, and blackhole handoff options.
  • Do not describe Prowlarr as owning grabs. Gadarr owns release decisions, queue records, and download-client handoff.
  • Do not claim live deploy success unless the deployed health endpoint reports the target commit or a local status file proves it.
  • Keep cracked/keygen/DRM-bypass releases documented as visible-for-review but blocked from grabs.
  • Prefer game-native import-list wording: Steam Library, Steam Owned Games, Steam Wishlist, GOG Library, GOG Owned Games, Epic Library, Epic Owned Games, Legendary/Heroic Cache, Itch.io Library, Lutris Library, Amazon Games Library, EA App Library, Ubisoft Connect Library, Battle.net Library, TMDb List/Popular/User where compatibility requires those names, store/library/watchlist sync, exclusions, tags, cleanup modes, and search-on-add.
  • Do not claim a screenshot shows a provider row unless the seeded UI actually shows it. Compatibility-only providers should be documented with source-backed wording when the native settings screenshot does not display them directly.

Output Contract

A completed documentation-agent run should produce:

  • Updated README and relevant docs.
  • Refreshed PNG screenshots when the UI changed.
  • A strict local MkDocs build for the hosted docs page.
  • A short validation note listing screenshot verification and git diff --check.
  • The pushed GitHub commit SHA, or a clear blocker if push is unavailable.
  • The GitHub Pages state, or the current blocker if the hosted site is not available.
  • A separate live-deploy note only when the app was actually staged or deployed; docs-only commits do not imply runtime changes.