Scaffold Forgejo issue sync plugin

README.md

@@ -0,0 +1,40 @@
+# Forgejo Issue Sync Plugin
+
+Scaffold for a Paperclip plugin that will sync Forgejo issues/comments while enforcing the v1 policy from `PRIA-13`:
+
+- webhook intake stays inside the plugin worker
+- scheduled reconciliation stays in plugin `jobs`
+- mappings, dedupe, and review state stay in the plugin database/state
+- attachment handling is metadata-only
+- no managed agents or managed skills are declared in v1
+
+## Layout
+
+- `src/manifest.ts`: manifest, capabilities, jobs, webhook declaration, instance config schema
+- `src/worker.ts`: plugin bootstrap, health, config validation, data/action registration
+- `src/webhook-intake.ts`: webhook verification, normalization, dedupe recording, manual-review queueing
+- `src/reconciliation.ts`: scheduled reconciliation job and instance-level last-run state
+- `src/persistence.ts`: namespace-local persistence helpers for mappings, deliveries, reviews, and run snapshots
+- `src/attachment-policy.ts`: metadata-only attachment policy and synced markdown formatter
+- `migrations/001_initial.sql`: plugin-owned tables for mappings, dedupe, review queue, and reconciliation history
+
+## Attachment Policy
+
+This scaffold deliberately does not fetch attachment bytes and does not add any path that calls `/api/attachments/{id}/content`.
+
+Instead it:
+
+- preserves attachment metadata only
+- appends `Attachments are not synced. See the source Paperclip issue.` to generated sync content
+- stores a machine-readable review reason code when the issue/comment text suggests the attachment is required for context
+- queues those payloads in `review_queue` for later human-routing work
+
+## Follow-Up Needed
+
+The plugin now emits `attachments_context_required` as a durable review signal, but the human-review destination is still a follow-up decision:
+
+- create Paperclip-visible review issues/comments
+- expose a plugin UI or scoped API route for triage
+- route review-required payloads into an existing operator workflow
+
+That routing is intentionally left out of this v1 scaffold so the sync runtime stays inside plugin jobs/webhooks/state as requested.