diff --git a/package.json b/package.json
index ff4cbc4..7256a4d 100644
--- a/package.json
+++ b/package.json
@@ -47,7 +47,12 @@
   },
   "pi": {
     "extensions": [
-      "./extensions"
+      "./extensions/forgejo/index.ts"
+    ]
+  },
+  "omp": {
+    "extensions": [
+      "./extensions/forgejo/index.ts"
     ]
   },
   "peerDependencies": {
diff --git a/src/extension.ts b/src/extension.ts
index 7e7a527..c3bd0b0 100644
--- a/src/extension.ts
+++ b/src/extension.ts
@@ -396,7 +396,7 @@ export default function forgejoExtension(pi: ExtensionAPI): void {
 			const value = args.trim();
 			if (value) {
 				const ref = parseResourceRef(value);
-				if (!ref) throw new Error(`invalid Forgejo reference '${value}'`);
+				if (!ref) throw new Error(`invalid Forgejo reference '${value}' — expected 'server:owner/repo#N' (issue), 'server:owner/repo!N' (pull), 'server:owner/repo' (repo), or 'fj://server/owner/repo/<issue|pull>/<N>'; for git tags/branches use the git_ref parameter`);
 				const server = current.config.servers[ref.server];
 				if (!server) throw new Error(`unknown server '${ref.server}'`);
 				await openExternal(pi, resourceWebUrl(ref, server), server.baseUrl);
diff --git a/src/runtime.ts b/src/runtime.ts
index 214e940..3b6bb73 100644
--- a/src/runtime.ts
+++ b/src/runtime.ts
@@ -15,6 +15,9 @@ import type {
   ReviewDraft,
 } from "./types.js";
 
+const REF_FORMAT_HINT =
+	"expected 'server:owner/repo#N' (issue), 'server:owner/repo!N' (pull), 'server:owner/repo' (repo), or 'fj://server/owner/repo/<issue|pull>/<N>'; for git tags/branches use the git_ref parameter";
+
 export interface RepoInput {
   ref?: string;
   server?: string;
@@ -102,7 +105,7 @@ export class ForgejoRuntime {
     if (input.ref) {
       const resource = parseResourceRef(input.ref);
       if (!resource)
-        throw new Error(`invalid Forgejo reference '${input.ref}'`);
+        throw new Error(`invalid Forgejo reference '${input.ref}' — ${REF_FORMAT_HINT}`);
       this.clients.get(resource.server);
       return {
         server: resource.server,
@@ -139,7 +142,7 @@ export class ForgejoRuntime {
     if (input.ref) {
       const resource = parseResourceRef(input.ref);
       if (!resource)
-        throw new Error(`invalid Forgejo reference '${input.ref}'`);
+        throw new Error(`invalid Forgejo reference '${input.ref}' — ${REF_FORMAT_HINT}`);
       if (resource.kind !== kind)
         throw new Error(`reference '${input.ref}' is not a ${kind}`);
       this.clients.get(resource.server);