Document plugin secret-ref platform blocker

docs/forgejo-token-secret-ref-status.md

@@ -0,0 +1,32 @@
+## Forgejo token secret-ref status
+
+`forgejoTokenRef` is declared as `format: "secret-ref"` in the plugin manifest so the Paperclip settings UI renders a secret picker instead of a plain text field.
+
+### Current Paperclip runtime behavior
+
+- The picker can select a Paperclip company secret and shows the secret binding in the UI.
+- Saving plugin instance config that contains a secret ref is intentionally rejected by Paperclip core with:
+  `Plugin secret references are disabled until company-scoped plugin config lands`
+- Plugin workers also cannot resolve plugin secret refs yet. `ctx.secrets.resolve(...)` fails closed with the same platform-level restriction.
+
+This means the Forgejo plugin currently cannot complete a safe end-to-end `forgejoTokenRef` flow through Paperclip-managed secrets alone.
+
+### Supported current operator flow
+
+1. Open the plugin settings page.
+2. Select the Forgejo token through the secret picker.
+3. Observe that the UI binds the chosen secret, but the save is rejected by the Paperclip core guard.
+
+Expected stored value after the upstream fix lands:
+
+- `forgejoTokenRef` should persist the Paperclip secret UUID, not the visible secret name.
+- The worker should read that stored UUID from config and call `ctx.secrets.resolve(forgejoTokenRef)` during outbound Forgejo requests.
+
+### Scope of the required upstream fix
+
+Paperclip core must re-enable plugin secret refs only after both of these exist:
+
+- company-scoped plugin config persistence and reads
+- company-scoped secret resolution for plugin worker invocations
+
+Until then, there is no plugin-side workaround that keeps the Forgejo token in Paperclip-managed secrets without exposing the raw token in plain plugin config.