feat(prd-1): complete M9 - documentation & upstream merge validation

- Created docs/forgejo.md: comprehensive setup guide (prerequisites,
  quick start, platform detection, GitHub differences, CI workflows,
  upstream merge process, known limitations, troubleshooting)
- Updated README.md with Forgejo support mention and docs link
- Updated CLAUDE.md with Forgejo architecture section
- Added platform input to docs/usage.md inputs table
- Added 5 Forgejo FAQ entries to docs/faq.md
- Upstream merge validated: zero conflicts (based on latest upstream)
- PRD #1 100% complete: all milestones M1-M9 done, 794 tests passing

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/faq.md

@@ -251,6 +251,28 @@ For specialized environments like Nix, NixOS, or custom container setups where y
 - The action will skip automatic installation when custom paths are provided
 - Ensure the custom executables are available in your GitHub Actions environment
 
+## Forgejo-Specific Questions
+
+### Can I use this action on Forgejo?
+
+Yes. Set `platform: "forgejo"` in your workflow and provide a `github_token` with repo access. See the [Forgejo Setup Guide](./forgejo.md) for complete instructions.
+
+### Why is GraphQL not used on Forgejo?
+
+Forgejo doesn't have a GraphQL API. The action uses parallel REST API calls instead, which provides the same data with slightly more HTTP requests. This is handled automatically — no configuration needed.
+
+### Why is actor validation skipped on Forgejo?
+
+Forgejo has no bot or app accounts, so the bot/app check that GitHub uses is unnecessary. Additionally, the `read:user` scope required for `getByUsername()` isn't available with standard Forgejo workflow tokens.
+
+### Why does `oven-sh/setup-bun` fail on my Forgejo runner?
+
+Forgejo runners pre-fetch all `uses:` action references before evaluating `if:` conditions. If `oven-sh/setup-bun` isn't mirrored to your Forgejo instance, the prefetch fails even when the step would be skipped. This fork replaces it with a universal `curl` install that works on both platforms.
+
+### How do I keep my Forgejo fork in sync with upstream?
+
+The included `upstream-sync.yml` workflow runs weekly and creates an issue when upstream has new commits. It includes merge instructions and lists the conflict-prone files. See [Merging Upstream Changes](./forgejo.md#merging-upstream-changes).
+
 ## Best Practices
 
 1. **Always specify permissions explicitly** in your workflow file