docs: refresh Academy workflow pages

[TheFactoriousDROID]

What changed

• Reworked the GitHub Actions guide around direct droid exec workflows for pull request review, scheduled maintenance, and security scans.
• Tightened the local /review page around review modes, severity levels, output, and when to use automated review instead.
• Refreshed the Plugins page around plugin concepts, package structure, manifests, scopes, hooks, and when to package reusable Droid customization.
• Added a dedicated Plugin Marketplaces page for adding and managing marketplaces, installing official Factory plugins, using external marketplaces, and rolling out team or organization-managed plugins.

Why

These pages now align more closely with the Academy training flow while separating plugin concepts from marketplace distribution so each page is easier to scan and follow.

Risk / impact

Docs-only. No product behavior changes.

Testing

• git diff --check
• Custom docs navigation and changed-file local link check
• npx --yes prettier --check docs/guides/droid-exec/github-actions.mdx docs/cli/features/code-review.mdx docs/cli/configuration/plugins.mdx docs/cli/configuration/plugin-marketplaces.mdx docs/docs.json

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
factory	🟢 Ready	View Preview	May 2, 2026, 10:12 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[factory-droid]

Droid finished @TheFactoriousDROID's task —— View job

---

Docs-only change with generally clear rewrites; the main correctness issue is that the PR review-and-fix GitHub Actions example won’t be able to push commits back to the PR branch as written. Consider tightening the basic CI example to be truly read-only by default and adding a short note about secrets/permissions on forked PRs.

[factory-droid]

[P1] PR review workflow can’t push fixes (detached HEAD checkout)

In Example 1, actions/checkout@v4 is not configured to check out the PR head branch, so the job runs on a detached merge commit; if Droid commits changes, the later git push will fail (e.g., “not currently on a branch” / no upstream), so fixes won’t actually be pushed back to the PR source branch.

[factory-droid]

[P2] Keep the basic example truly read-only by omitting --auto

The basic workflow says “Do not modify files.” but runs droid exec --auto low, which still grants file-write capability and contradicts the later guidance to “Start read-only” without --auto; using droid exec without --auto here reduces accidental writes and makes the example match the intended safety posture.

[factory-droid]

[P2] Note that pull_request workflows won’t get secrets on fork PRs

These examples use on: pull_request while relying on ${{ secrets.FACTORY_API_KEY }}, but GitHub does not pass repository secrets to workflows triggered by forked PRs; calling this out (or scoping the examples to same-repo PRs / trusted actors) prevents users from copying a workflow that silently fails due to missing secrets.

[factory-droid]

[P1] [security] Guard against prompt-injection when reviewing untrusted diffs

Example 1 runs droid exec over attacker-controlled PR diff content while also providing FACTORY_API_KEY and granting write permissions; a malicious PR can embed prompt-injection strings that trick the agent into leaking secrets (e.g., into PR comments) or making unintended writes. Add explicit guardrails (run only for trusted actors/labels, keep permissions read-only by default, and avoid secrets/write access on untrusted PR events) to reduce exfiltration and unauthorized-change risk.

[factory-droid]

[P2] [security] Avoid curl | sh installs without integrity verification

The docs recommend curl -fsSL https://app.factory.ai/cli | sh, which executes a remote script without pinning or integrity checks; if the delivery chain is compromised, this becomes immediate RCE on the runner. Prefer a pinned artifact with checksum/signature verification (or an official package/action) and document an integrity-verification option for security-sensitive CI.