Configure PR automation and detectors

Overview

Use Moxie Docs’ repository automation to keep docs PRs consistent, tune drift detectors, and control weekly Friday Recaps. After setup, you can align PR templates, enable or disable specific detectors per repo, and choose whether Friday Cleanup PRs are proposed. Detector toggles immediately affect what you see in the dashboard without deleting historical context.

Before you start

• A Moxie Docs account with access to the target GitHub repository.
• Admin or maintainer permission for the repo in GitHub and in Moxie Docs.
• The repository already connected to Moxie Docs.

Connect

1. Open Moxie Docs and go to Account → Settings.
2. Select the PR automation tab.
3. Choose the target repository from the repo picker, if prompted.
4. If your repository is not yet linked, connect your GitHub account and authorize access to the repository. Follow the GitHub screens to grant the required permissions.

Configure

After connecting, set per-repo automation and detector options in Account → Settings → PR automation.

• PR template alignment

  • Ensure docs-only PRs opened by Moxie use your standard format.
  • Toggle on to apply your repository’s default PR template to Moxie-generated PRs.

• Friday Recap and Cleanup PRs

  • Enable to receive a Friday Recap card on the dashboard and propose a Friday Cleanup PR when useful doc changes exist.
  • Disable to stop recap cards and skip Friday Cleanup PR proposals for this repo.

• Detectors (per repository)

  • thin
    • Flags shallow or under-explained docs; proposes additions.
  • convention_mismatch
    • Highlights docs that diverge from team conventions; proposes alignment.
  • undocumented_api
    • Detects public APIs, endpoints, or CLI commands lacking docs; proposes coverage.
  • stale_content
    • Finds outdated docs and classifies severity; proposes refresh or removal.

Behavior details

• Detector toggles are checkboxes per repo. When you disable a detector, existing rows from that detector are hidden from the dashboard (cards and tables) but history is not deleted.
• Cosmetic-only findings are automatically hidden; only actionable opportunities appear.
• From the dashboard’s Docs opportunities cards, use the overflow menu (Dismiss / Mute) to manage noisy alerts. Admins can reverse these later.
• Severity pills appear on stale-content opportunities to help you prioritize.

Example configuration

• Enable: thin, undocumented_api, stale_content
• Disable: convention_mismatch (if you’re mid-migration on conventions)
• Friday Recap: On
• PR template alignment: On

Verify it works

• In the dashboard, check the Docs opportunities section. You should see cards only for detectors you left enabled; disabled detectors’ items will be hidden.
• On Friday, look for the Friday Recap card. If enabled and changes are warranted, you’ll also see a proposed Friday Cleanup PR entry.
• Open a Moxie-generated docs-only PR and confirm the repository’s standard PR template appears when PR template alignment is on.
• Mute or dismiss a card via the overflow menu and confirm it no longer appears in the dashboard for that repo.

Disconnect or change access

• To change detector or recap behavior: go to Account → Settings → PR automation, select the repository, and update the checkboxes. Changes apply immediately to visibility and automation going forward.
• To stop Friday Recap for a repo: uncheck the Friday Recap option in the same tab.
• To revoke repository access entirely: remove the repository connection from your GitHub settings for the Moxie Docs app, then return to Moxie Docs to confirm the repo no longer appears in the PR automation tab. You can reconnect later if needed.