docs: add permissions documentation for actions registry

Signed-off-by: benjdlambert <ben@blam.sh>

.changeset/actions-permissions-api.md

@@ -3,3 +3,28 @@
 ---
 
 Added optional `permission` field to `ActionsRegistryActionOptions`, allowing actions to declare a `BasicPermission` that controls visibility and access.
+
+```typescript
+import { createPermission } from '@backstage/plugin-permission-common';
+
+const myPermission = createPermission({
+  name: 'myPlugin.myAction.use',
+  attributes: {},
+});
+
+actionsRegistry.register({
+  name: 'my-action',
+  title: 'My Action',
+  description: 'An action that requires permission',
+  permission: myPermission,
+  schema: {
+    input: z => z.object({ name: z.string() }),
+    output: z => z.object({ ok: z.boolean() }),
+  },
+  action: async ({ input }) => {
+    return { output: { ok: true } };
+  },
+});
+```
+
+Actions without a `permission` field continue to work as before.

.changeset/actions-permissions-defaults.md

@@ -2,4 +2,4 @@
 '@backstage/backend-defaults': patch
 ---
 
-Added permissions integration to the actions registry. Actions with a `permission` field are now checked against the permissions framework when listing and invoking. Denied actions are filtered from listings and return 404 on invocation.
+Added permissions integration to the actions registry. Actions registered with a `permission` field are now checked against the permissions framework when listing and invoking. Denied actions are filtered from list results, and invoking a denied action returns a `404 Not Found` as if the action does not exist.