From 40920f9775ea5b0bd111623289d002ecc3965ec9 Mon Sep 17 00:00:00 2001
From: PrivateGER <privateger@privateger.me>
Date: Fri, 3 Jul 2026 12:25:59 +0200
Subject: [PATCH 1/2] feat(frontend): add Lua syntax reference to MRF policy
 admin UI

Adds a collapsible 'Syntax reference' panel documenting the full policy
API surface: the filter(ctx) contract, params schema types, ctx fields,
mrf.accept/reject/rewrite decisions, mrf.activity.*/mrf.note.*/mrf.lookup.*
helpers, sandbox constraints, and a worked example. Content is grounded in
the SANDBOX_PRELUDE and parseDecision rules.

Also renders string_array params as comma-separated inputs (matching the
existing coerceParams round-trip) and reseeds the params form from the
dry-run result so live editing converges.
---
 locales/index.d.ts                            | 166 ++++++++++++++++
 .../src/pages/admin/mrf-policies.policy.vue   |  12 +-
 .../pages/admin/mrf-policies.reference.vue    | 179 ++++++++++++++++++
 .../frontend/src/pages/admin/mrf-policies.vue |   7 +
 sharkey-locales/en-US.yml                     |  42 ++++
 5 files changed, 399 insertions(+), 7 deletions(-)
 create mode 100644 packages/frontend/src/pages/admin/mrf-policies.reference.vue

diff --git a/locales/index.d.ts b/locales/index.d.ts
index 57421fd422..54452b3062 100644
--- a/locales/index.d.ts
+++ b/locales/index.d.ts
@@ -12772,6 +12772,172 @@ export interface Locale extends ILocale {
          * New policy
          */
         "newPolicyName": string;
+        /**
+         * Comma-separated.
+         */
+        "commaSeparated": string;
+        /**
+         * Syntax reference
+         */
+        "reference": string;
+        "_reference": {
+            /**
+             * Every policy must define a global filter(ctx) function that returns a decision. An optional policy table declares configurable parameters.
+             */
+            "contract": string;
+            /**
+             * Example
+             */
+            "example": string;
+            /**
+             * Runs in a sandboxed Lua 5.4 VM. os, io, package, require, load and debug are unavailable. Define helpers as local; extra globals trigger persistence warnings. Execution is bounded by the policy timeout.
+             */
+            "sandboxNote": string;
+            /**
+             * Context (ctx)
+             */
+            "contextTitle": string;
+            /**
+             * The context passed to filter(ctx).
+             */
+            "contextNote": string;
+            /**
+             * The raw ActivityPub activity as a table (mutate this for rewrites).
+             */
+            "ctxActivity": string;
+            /**
+             * URI of the activity's actor.
+             */
+            "ctxActorUri": string;
+            /**
+             * Host of the actor, or nil for local.
+             */
+            "ctxActorHost": string;
+            /**
+             * Actor follower count, if known.
+             */
+            "ctxFollowers": string;
+            /**
+             * Actor following count, if known.
+             */
+            "ctxFollowing": string;
+            /**
+             * This instance's host.
+             */
+            "ctxLocalHost": string;
+            /**
+             * Host that signed the request.
+             */
+            "ctxSignerHost": string;
+            /**
+             * ISO timestamp of when the activity was received.
+             */
+            "ctxReceivedAt": string;
+            /**
+             * Configured parameter values, with schema defaults applied.
+             */
+            "ctxParams": string;
+            /**
+             * Decisions
+             */
+            "decisionsTitle": string;
+            /**
+             * Accept the activity unchanged. Optional reason.
+             */
+            "decAccept": string;
+            /**
+             * Reject the activity. Requires a non-empty reason (logged).
+             */
+            "decReject": string;
+            /**
+             * Accept a modified activity. Must be JSON-serializable.
+             */
+            "decRewrite": string;
+            /**
+             * Activity helpers
+             */
+            "activityTitle": string;
+            /**
+             * Activity type string (e.g. Create, Announce), or nil.
+             */
+            "actType": string;
+            /**
+             * The activity's object, or nil.
+             */
+            "actObject": string;
+            /**
+             * Actor URI whether actor is a string or object, or nil.
+             */
+            "actActorUri": string;
+            /**
+             * The Note object if this is a Create of a Note, else nil.
+             */
+            "actNote": string;
+            /**
+             * Note helpers
+             */
+            "noteTitle": string;
+            /**
+             * The note's content string, or nil.
+             */
+            "noteContent": string;
+            /**
+             * Array of Mention tags on the note.
+             */
+            "noteMentions": string;
+            /**
+             * Number of mentions on the note.
+             */
+            "noteMentionCount": string;
+            /**
+             * Remove all Mention tags; returns the note.
+             */
+            "noteRemoveMentions": string;
+            /**
+             * Mark the note sensitive; sets summary to reason if unset.
+             */
+            "noteMarkSensitive": string;
+            /**
+             * Move Public from 'to' into 'cc' (unlists the note).
+             */
+            "noteUnlist": string;
+            /**
+             * True if the note has at least one attachment.
+             */
+            "noteHasMedia": string;
+            /**
+             * Lookups
+             */
+            "lookupTitle": string;
+            /**
+             * Query the local database. These are async and their latency counts against the policy timeout.
+             */
+            "lookupSectionNote": string;
+            /**
+             * Fetch a known user by URI, or nil.
+             */
+            "lookupUserUri": string;
+            /**
+             * Fetch a known user by mention tag or acct string, or nil.
+             */
+            "lookupUserMention": string;
+            /**
+             * Fetch instance metadata by host, or nil.
+             */
+            "lookupInstance": string;
+            /**
+             * Fetch a known note by URI, or nil.
+             */
+            "lookupNoteUri": string;
+            /**
+             * Utilities
+             */
+            "miscTitle": string;
+            /**
+             * True if the value is Lua nil or a JSON null.
+             */
+            "miscIsNil": string;
+        };
     };
     "_mfm": {
         /**
diff --git a/packages/frontend/src/pages/admin/mrf-policies.policy.vue b/packages/frontend/src/pages/admin/mrf-policies.policy.vue
index 588e5eee1a..daf4d81a9f 100644
--- a/packages/frontend/src/pages/admin/mrf-policies.policy.vue
+++ b/packages/frontend/src/pages/admin/mrf-policies.policy.vue
@@ -40,6 +40,10 @@ SPDX-License-Identifier: AGPL-3.0-only
 					<template #label>{{ entry.def.label ?? entry.key }}</template>
 					<template v-if="entry.def.description" #caption>{{ entry.def.description }}</template>
 				</MkInput>
+				<MkInput v-else-if="entry.def.type === 'string_array'" v-model="draft.params[entry.key]">
+					<template #label>{{ entry.def.label ?? entry.key }}</template>
+					<template #caption>{{ entry.def.description ? entry.def.description + ' ' : '' }}{{ i18n.ts._mrfPolicies.commaSeparated }}</template>
+				</MkInput>
 				<MkInput v-else v-model="draft.params[entry.key]">
 					<template #label>{{ entry.def.label ?? entry.key }}</template>
 					<template v-if="entry.def.description" #caption>{{ entry.def.description }}</template>
@@ -210,12 +214,6 @@ const currentSchema = ref<Record<string, ParamDef>>(initialSchema);
 
 const paramEntries = computed(() => Object.entries(currentSchema.value).map(([key, def]) => ({ key, def })));
 
-function pruneParams(schema: Record<string, ParamDef>) {
-	for (const key of Object.keys(draft.params)) {
-		if (!Object.hasOwn(schema, key)) delete draft.params[key];
-	}
-}
-
 const scopeActivityTypes = ref((props.policy.scope?.activityTypes ?? []).join(', '));
 const scopeObjectTypes = ref((props.policy.scope?.objectTypes ?? []).join(', '));
 
@@ -324,7 +322,7 @@ async function runTest() {
 		// Sync the param form to the schema the tested source actually produced, so editing
 		// the source live and re-testing converges instead of leaving stale param fields.
 		currentSchema.value = { ...(result.paramsSchema ?? {}) as Record<string, ParamDef> };
-		pruneParams(currentSchema.value);
+		draft.params = toEditableParams(currentSchema.value, { ...(result.params ?? {}) });
 	} catch (err: any) {
 		os.alert({ type: 'error', text: err.message ?? String(err) });
 	} finally {
diff --git a/packages/frontend/src/pages/admin/mrf-policies.reference.vue b/packages/frontend/src/pages/admin/mrf-policies.reference.vue
new file mode 100644
index 0000000000..7384bc5e36
--- /dev/null
+++ b/packages/frontend/src/pages/admin/mrf-policies.reference.vue
@@ -0,0 +1,179 @@
+<!--
+SPDX-FileCopyrightText: syuilo and misskey-project
+SPDX-License-Identifier: AGPL-3.0-only
+-->
+
+<template>
+<div class="_gaps_m">
+	<div>
+		<p :class="$style.lead">{{ i18n.ts._mrfPolicies._reference.contract }}</p>
+		<MkCode :code="contractExample" lang="lua"/>
+	</div>
+
+	<section v-for="group in groups" :key="group.title" class="_gaps_s">
+		<div :class="$style.groupTitle">{{ group.title }}</div>
+		<p v-if="group.note" :class="$style.note">{{ group.note }}</p>
+		<table :class="$style.table">
+			<tbody>
+				<tr v-for="row in group.rows" :key="row.sig">
+					<td :class="$style.sig"><code>{{ row.sig }}</code></td>
+					<td :class="$style.desc">{{ row.desc }}</td>
+				</tr>
+			</tbody>
+		</table>
+	</section>
+
+	<div>
+		<div :class="$style.groupTitle">{{ i18n.ts._mrfPolicies._reference.example }}</div>
+		<MkCode :code="workedExample" lang="lua"/>
+	</div>
+
+	<MkInfo warn>{{ i18n.ts._mrfPolicies._reference.sandboxNote }}</MkInfo>
+</div>
+</template>
+
+<script lang="ts" setup>
+import MkCode from '@/components/MkCode.vue';
+import MkInfo from '@/components/MkInfo.vue';
+import { i18n } from '@/i18n.js';
+
+const t = i18n.ts._mrfPolicies._reference;
+
+const contractExample = `-- Optional: declare configurable parameters (shown as form fields).
+policy = {
+\tparams = {
+\t\tmax_mentions = { type = "integer", default = 5, label = "Max mentions" },
+\t\tblocked_words = { type = "string_array", default = {} },
+\t},
+}
+
+-- Required: filter(ctx) runs for every matching inbound activity.
+function filter(ctx)
+\treturn mrf.accept()
+end`;
+
+const workedExample = `function filter(ctx)
+\tlocal note = mrf.activity.note(ctx.activity)
+\tif note == nil then
+\t\treturn mrf.accept()
+\tend
+
+\t-- Reject hellthreads.
+\tif mrf.note.mention_count(note) > ctx.params.max_mentions then
+\t\treturn mrf.reject("too many mentions")
+\tend
+
+\t-- Force-CW posts from brand-new remote accounts.
+\tif (ctx.actor.followersCount or 0) < 1 then
+\t\tmrf.note.mark_sensitive(note, "new account")
+\t\treturn mrf.rewrite(ctx.activity, "cw new account")
+\tend
+
+\treturn mrf.accept()
+end`;
+
+const groups = [
+	{
+		title: t.contextTitle,
+		note: t.contextNote,
+		rows: [
+			{ sig: 'ctx.activity', desc: t.ctxActivity },
+			{ sig: 'ctx.actor.uri', desc: t.ctxActorUri },
+			{ sig: 'ctx.actor.host', desc: t.ctxActorHost },
+			{ sig: 'ctx.actor.followersCount', desc: t.ctxFollowers },
+			{ sig: 'ctx.actor.followingCount', desc: t.ctxFollowing },
+			{ sig: 'ctx.localHost', desc: t.ctxLocalHost },
+			{ sig: 'ctx.signerHost', desc: t.ctxSignerHost },
+			{ sig: 'ctx.receivedAt', desc: t.ctxReceivedAt },
+			{ sig: 'ctx.params.<key>', desc: t.ctxParams },
+		],
+	},
+	{
+		title: t.decisionsTitle,
+		rows: [
+			{ sig: 'mrf.accept(reason?)', desc: t.decAccept },
+			{ sig: 'mrf.reject(reason)', desc: t.decReject },
+			{ sig: 'mrf.rewrite(activity, reason?)', desc: t.decRewrite },
+		],
+	},
+	{
+		title: t.activityTitle,
+		rows: [
+			{ sig: 'mrf.activity.type(activity)', desc: t.actType },
+			{ sig: 'mrf.activity.object(activity)', desc: t.actObject },
+			{ sig: 'mrf.activity.actor_uri(activity)', desc: t.actActorUri },
+			{ sig: 'mrf.activity.note(activity)', desc: t.actNote },
+		],
+	},
+	{
+		title: t.noteTitle,
+		rows: [
+			{ sig: 'mrf.note.content(note)', desc: t.noteContent },
+			{ sig: 'mrf.note.mentions(note)', desc: t.noteMentions },
+			{ sig: 'mrf.note.mention_count(note)', desc: t.noteMentionCount },
+			{ sig: 'mrf.note.remove_mentions(note)', desc: t.noteRemoveMentions },
+			{ sig: 'mrf.note.mark_sensitive(note, reason?)', desc: t.noteMarkSensitive },
+			{ sig: 'mrf.note.unlist(note)', desc: t.noteUnlist },
+			{ sig: 'mrf.note.has_media(note)', desc: t.noteHasMedia },
+		],
+	},
+	{
+		title: t.lookupTitle,
+		note: t.lookupSectionNote,
+		rows: [
+			{ sig: 'mrf.lookup.user_by_uri(uri)', desc: t.lookupUserUri },
+			{ sig: 'mrf.lookup.user_by_mention(mention)', desc: t.lookupUserMention },
+			{ sig: 'mrf.lookup.instance_by_host(host)', desc: t.lookupInstance },
+			{ sig: 'mrf.lookup.note_by_uri(uri)', desc: t.lookupNoteUri },
+		],
+	},
+	{
+		title: t.miscTitle,
+		rows: [
+			{ sig: 'mrf.is_nil(value)', desc: t.miscIsNil },
+		],
+	},
+];
+</script>
+
+<style lang="scss" module>
+.lead {
+	margin: 0 0 8px;
+}
+
+.groupTitle {
+	font-weight: bold;
+	margin-bottom: 4px;
+}
+
+.note {
+	margin: 0 0 6px;
+	opacity: 0.8;
+	font-size: 0.9em;
+}
+
+.table {
+	width: 100%;
+	border-collapse: collapse;
+}
+
+.table td {
+	vertical-align: top;
+	padding: 4px 8px 4px 0;
+	border-bottom: 1px solid var(--MI_THEME-divider);
+}
+
+.sig {
+	white-space: nowrap;
+
+	> code {
+		font-family: Consolas, Monaco, monospace;
+		font-size: 0.9em;
+	}
+}
+
+.desc {
+	width: 100%;
+	opacity: 0.9;
+}
+</style>
diff --git a/packages/frontend/src/pages/admin/mrf-policies.vue b/packages/frontend/src/pages/admin/mrf-policies.vue
index 7b48ec19ca..e5aeda0966 100644
--- a/packages/frontend/src/pages/admin/mrf-policies.vue
+++ b/packages/frontend/src/pages/admin/mrf-policies.vue
@@ -9,6 +9,12 @@ SPDX-License-Identifier: AGPL-3.0-only
 		<div class="_gaps_m">
 			<MkInfo>{{ i18n.ts._mrfPolicies.description }}</MkInfo>
 
+			<MkFolder :defaultOpen="false">
+				<template #icon><i class="ti ti-help-circle"></i></template>
+				<template #label>{{ i18n.ts._mrfPolicies.reference }}</template>
+				<XReference/>
+			</MkFolder>
+
 			<MkFolder v-for="policy in policies" :key="policy.id" :defaultOpen="false">
 				<template #icon>
 					<i v-if="!policy.enabled" class="ti ti-circle-off"></i>
@@ -32,6 +38,7 @@ SPDX-License-Identifier: AGPL-3.0-only
 import { ref, computed } from 'vue';
 import * as Misskey from 'misskey-js';
 import XPolicy from './mrf-policies.policy.vue';
+import XReference from './mrf-policies.reference.vue';
 import MkFolder from '@/components/MkFolder.vue';
 import MkInfo from '@/components/MkInfo.vue';
 import * as os from '@/os.js';
diff --git a/sharkey-locales/en-US.yml b/sharkey-locales/en-US.yml
index 101310bce4..460c4954cb 100644
--- a/sharkey-locales/en-US.yml
+++ b/sharkey-locales/en-US.yml
@@ -386,6 +386,48 @@ _mrfPolicies:
   invalidActivityJson: "The activity field does not contain valid JSON."
   deleteConfirm: "Delete the MRF policy \"{name}\"?"
   newPolicyName: "New policy"
+  commaSeparated: "Comma-separated."
+  reference: "Syntax reference"
+  _reference:
+    contract: "Every policy must define a global filter(ctx) function that returns a decision. An optional policy table declares configurable parameters."
+    example: "Example"
+    sandboxNote: "Runs in a sandboxed Lua 5.4 VM. os, io, package, require, load and debug are unavailable. Define helpers as local; extra globals trigger persistence warnings. Execution is bounded by the policy timeout."
+    contextTitle: "Context (ctx)"
+    contextNote: "The context passed to filter(ctx)."
+    ctxActivity: "The raw ActivityPub activity as a table (mutate this for rewrites)."
+    ctxActorUri: "URI of the activity's actor."
+    ctxActorHost: "Host of the actor, or nil for local."
+    ctxFollowers: "Actor follower count, if known."
+    ctxFollowing: "Actor following count, if known."
+    ctxLocalHost: "This instance's host."
+    ctxSignerHost: "Host that signed the request."
+    ctxReceivedAt: "ISO timestamp of when the activity was received."
+    ctxParams: "Configured parameter values, with schema defaults applied."
+    decisionsTitle: "Decisions"
+    decAccept: "Accept the activity unchanged. Optional reason."
+    decReject: "Reject the activity. Requires a non-empty reason (logged)."
+    decRewrite: "Accept a modified activity. Must be JSON-serializable."
+    activityTitle: "Activity helpers"
+    actType: "Activity type string (e.g. Create, Announce), or nil."
+    actObject: "The activity's object, or nil."
+    actActorUri: "Actor URI whether actor is a string or object, or nil."
+    actNote: "The Note object if this is a Create of a Note, else nil."
+    noteTitle: "Note helpers"
+    noteContent: "The note's content string, or nil."
+    noteMentions: "Array of Mention tags on the note."
+    noteMentionCount: "Number of mentions on the note."
+    noteRemoveMentions: "Remove all Mention tags; returns the note."
+    noteMarkSensitive: "Mark the note sensitive; sets summary to reason if unset."
+    noteUnlist: "Move Public from 'to' into 'cc' (unlists the note)."
+    noteHasMedia: "True if the note has at least one attachment."
+    lookupTitle: "Lookups"
+    lookupSectionNote: "Query the local database. These are async and their latency counts against the policy timeout."
+    lookupUserUri: "Fetch a known user by URI, or nil."
+    lookupUserMention: "Fetch a known user by mention tag or acct string, or nil."
+    lookupInstance: "Fetch instance metadata by host, or nil."
+    lookupNoteUri: "Fetch a known note by URI, or nil."
+    miscTitle: "Utilities"
+    miscIsNil: "True if the value is Lua nil or a JSON null."
 _moderationLogTypes:
   approve: "Approved"
   decline: "Declined"

From eb6cec443c19fd8d9e59401881b2f594dfc39e85 Mon Sep 17 00:00:00 2001
From: PrivateGER <privateger@privateger.me>
Date: Fri, 3 Jul 2026 12:31:02 +0200
Subject: [PATCH 2/2] docs(frontend): make MRF worked example self-contained

The worked example read ctx.params.max_mentions without declaring it, so
copying it alone would error on a nil comparison. Declare the parameter in
the example's own policy.params block.
---
 .../frontend/src/pages/admin/mrf-policies.reference.vue  | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/frontend/src/pages/admin/mrf-policies.reference.vue b/packages/frontend/src/pages/admin/mrf-policies.reference.vue
index 7384bc5e36..528b345ad4 100644
--- a/packages/frontend/src/pages/admin/mrf-policies.reference.vue
+++ b/packages/frontend/src/pages/admin/mrf-policies.reference.vue
@@ -52,7 +52,14 @@ function filter(ctx)
 \treturn mrf.accept()
 end`;
 
-const workedExample = `function filter(ctx)
+const workedExample = `-- Declare the parameter this policy reads.
+policy = {
+\tparams = {
+\t\tmax_mentions = { type = "integer", default = 5, label = "Max mentions" },
+\t},
+}
+
+function filter(ctx)
 \tlocal note = mrf.activity.note(ctx.activity)
 \tif note == nil then
 \t\treturn mrf.accept()