glassframe-protocol 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -14,6 +14,150 @@ lives in `src/core/VersionInfo.js` (`VersionInfo.info()` /
 `VersionInfo.banner()`), so code can read the current version without
 parsing this file.
 
+## [2.2.0] - 2026-08-05
+
+Fixes a real bug in message deletion and adds tenure-aware leniency for
+spam detection. No breaking changes.
+
+### Fixed
+
+- **Protected/trusted members' messages were being deleted anyway.**
+  `BasicSecurityLayer` computed trust and used it to gate the @everyone
+  check, but every *other* trigger (message rate, duplicate flood, mention
+  spam, scam/phishing/raid language, links) deleted the message
+  unconditionally, before `PunishmentEngine` ever got a chance to decide
+  the sender shouldn't be punished. A real admin posting several messages
+  quickly during a busy conversation, or pasting a couple of links, had
+  their message removed even though they were never going to be actioned.
+  Deletion is now gated the same way punishment is: never for a HIGH/
+  PROTECTED-trust sender.
+
+### Added
+
+- **Expanded `roleAnalysis.protectedNames`**: added `co-owner`, `founder`,
+  `management`, `manager`, `support`, `helper`, `developer` alongside the
+  existing `owner`/`admin`/`administrator`/`moderator`/`mod`/`staff`/
+  `discord staff`/`security`.
+- **Established-member leniency** (`RoleAnalyzer.isEstablishedMember()`,
+  `roleAnalysis.maturity`, `basicSecurity.establishedMemberLeniency`) - a
+  member with an old-enough account (default 6 months) and long-enough
+  tenure in the server (default 1 month) needs a much bigger burst before
+  a pure rate/duplicate-flood signal fires at all (2.5x by default), that
+  signal counts for less when it does (0.3x weight by default), and their
+  messages are never deleted for tripping *only* a rate/volume signal.
+  This is a separate axis from role-based trust above - an ordinary member
+  with no special role can be "established."
+
+  Deliberately scoped narrow: this only ever softens detection of *sending
+  frequently*. Scam/phishing/raid-recruitment language, suspicious links,
+  and non-trusted mass pings stay at full sensitivity and still get
+  deleted and actioned regardless of how long the account has existed -
+  tenure says nothing about whether a specific message is dangerous, and a
+  long-standing account can still genuinely raid, spam, or get
+  compromised. Modeled on how invisible CAPTCHA works: judge from signals
+  already available rather than one blunt threshold, without ever handing
+  out blanket immunity.
+
+## [2.1.0] - 2026-08-01
+
+Additive - nothing from 2.0.0's API changes. New detections, a plugin
+system, per-guild customization, and an owner-only cross-server dashboard.
+
+### Added - security detections
+
+- **Dangerous role grants to a member.** The existing permission-grant
+  watchdog only caught a role's own permissions changing (`RoleUpdate`).
+  It missed the other half: someone with `ManageRoles` handing an
+  already-dangerous role directly to a member (`MemberRoleUpdate`) without
+  ever touching the role's definition. Now watched, gated the same way -
+  only flagged when the executor isn't recognized trusted staff.
+- **Channel permission-overwrite abuse.** A nuke doesn't have to delete
+  anything - locking @everyone out of a public channel, or opening a
+  private one up to @everyone, does equivalent damage through permission
+  overwrites. Only @everyone's own overwrite is watched; a role- or
+  member-specific overwrite change is routine administration and ignored.
+- **A dedicated @everyone/@here guard** in Basic Security, weighted well
+  above regular mention spam (a single mass ping reaches every member at
+  once) and skipped for recognized trusted staff, so a real admin's
+  announcement isn't flagged.
+- **Raid-recruitment language is now actually used.** `raidCallout` scoring
+  existed in the NLP engine already but was never wired into
+  `BasicSecurityLayer`'s real decision logic - fixed. Also added a specific
+  invite-link + raid-language combo check (the "join this server to raid
+  with us" pattern), and expanded the raid lexicon to catch common word
+  forms ("raiding", "raids") that the bare-verb-only version missed.
+
+### Added - extensibility
+
+- **`frame.registerLayer(name, layerInstance)`** - add a custom security
+  layer to the same shared pipeline the built-in four use. Must extend
+  `core/Layer`; gets per-guild enable/disable, state persistence, and
+  `!gf status`/`!gf metrics` visibility for free, since those now iterate
+  `frame.layers` dynamically instead of a fixed list. Does not get an
+  automatic button on the 5-button panel (that stays fixed at 5).
+- **`frame.registerAction(name, handler)`** - add a punishment action
+  beyond ban/kick/timeout/quarantine, referenceable from
+  `config.punishment.ladder`. Runs through the same action queue as the
+  built-in ones.
+- **Per-guild custom prefix** - `!gf prefix set <newPrefix>` /
+  `!gf prefix reset`. `config.prefix` always still works everywhere as a
+  fallback; an overlapping custom/default pair resolves by trying the
+  longer one first.
+- **Per-layer log channel routing** - `getLogChannel(guild, layerName)` now
+  receives the reporting layer's name as an optional second argument, so
+  different layers can route to different channels. Fully backward
+  compatible - a `getLogChannel` that only takes one parameter keeps
+  working unchanged.
+
+### Added - the owner-only engine dashboard
+
+- **`!gf engine`** - a bot-wide, cross-server dashboard: layer adoption
+  across every server, the busiest servers by event volume, AI usage
+  (Groq key pool/cooldowns/call volume), queue and cache health, and a live
+  feed of the last several things logged anywhere. See `docs/ENGINE.md`.
+  Deliberately not listed in `!gf help` - a per-server admin shouldn't know
+  it exists, let alone see data about other servers.
+- **Its own permission model**, separate from every other command:
+  `options.owners` (a list of Discord user IDs) is required regardless, and
+  an optional `config.engine.password` is a second factor on the initial
+  command only - page-navigation clicks re-check `isOwner()` but don't
+  re-prompt for the password. Wrong guesses count toward a lockout
+  (`config.engine.maxAttempts`, `config.engine.lockoutMs`), and the command
+  message is deleted immediately either way so the password doesn't sit
+  visible in channel history.
+- **5 pages** (Overview, Servers, AI, Performance, Activity Log), navigated
+  with a row of tab buttons - this is a second interactive surface,
+  entirely separate from the 5-button panel and the metrics command's own
+  button.
+- `frame.getEngineReport()` - the raw data behind the dashboard, if you
+  want it for your own tooling instead of the rendered message.
+- `PerformanceMonitor.recordEvent(name, guildId)` now optionally tracks
+  per-guild activity (`topGuildsByActivity()`) alongside the existing
+  by-name counters.
+- `SmartLogger` keeps a bounded in-memory ring buffer (`getRecentLogs()`,
+  last 30) of recent events across every guild, powering the Activity Log
+  page.
+
+### Changed
+
+- `!gf help` reorganized into sections (Getting started / Security tools /
+  Diagnostics / Customization) with a one-line explanation of what each
+  command actually does, instead of a flat list of syntax.
+- `!gf status` now explains what each layer actually watches for, not just
+  whether it's on, and iterates every registered layer (including custom
+  ones) instead of a fixed four.
+- `!gf metrics` and the global engine view now carry a short plain-language
+  explanation under every number - what it means, and whether it's
+  generally worth a closer look.
+
+### Fixed
+
+- `raidCallout` NLP scoring was computed but never checked anywhere.
+- The default `raidCalloutThreshold` (0.5) was miscalibrated against how
+  the scoring function actually behaves - lowered to 0.3, validated against
+  both a real raid-recruitment example and known-innocuous messages with
+  margin on both sides.
+
 ## [2.0.0] - 2026-08-01
 
 **Breaking.** Layer activation and the whitelist were accidentally global

package/GETTING_STARTED.md

@@ -123,11 +123,28 @@ Nobody needs this guide again after setup. Server admins use:
 | `!gf whitelist add/remove <userId>` | Exempt a user from punitive action in this server |
 | `!gf help` | Lists all of the above |
 
+## Step 6 (optional) - Your own bot-wide dashboard
+
+If you run the bot yourself, `!gf engine` gives you a cross-server view
+(busiest server, AI usage, a live activity feed) that regular server admins
+can't see:
+
+```js
+const frame = new GlassFrame(client, {
+  getLogChannel: /* ... */,
+  owners: ["your-discord-user-id"]
+});
+```
+
+See `docs/ENGINE.md` for the optional password/lockout system and what
+each of its 5 pages shows.
+
 ## Going deeper
 
 - `README.md` - full feature overview
 - `docs/PROTOCOL_LAYERS.md` - how a signal becomes an action
 - `docs/STATE.md` - per-server layer/whitelist state and persistence
+- `docs/ENGINE.md` - the owner-only bot-wide dashboard
 - `docs/CACHE_ARCHITECTURE.md` - every internal cache and its TTL
 - `docs/PERFORMANCE.md` - the bounded-concurrency queues and `!gf metrics`
 - `docs/COMMANDS.md` - full command/button reference

package/README.md

@@ -80,8 +80,10 @@ the 5-button control panel and arm layers from there instead of in code.
 
 ## The four layers
 
-- **Basic Security** - spam rate, duplicate flood, mention spam, local NLP
-  scam/phishing scoring, and link checks via `PhishingDatabase` (a
+- **Basic Security** - spam rate, duplicate flood, mention spam, a
+  dedicated trust-aware @everyone/@here guard, local NLP scam/phishing/
+  raid-recruitment scoring (including a specific invite-link +
+  raid-language combo check), and link checks via `PhishingDatabase` (a
   server-editable blocklist plus raw-IP/punycode/brand-look-alike/shortener
   heuristics - `!gf phishing add/remove/list`).
 - **AntiRaid** - join-velocity lockdown with automatic verification-level
@@ -90,12 +92,15 @@ the 5-button control panel and arm layers from there instead of in code.
   catches a raid trickling in too slowly to trip the rate counter.
 - **AntiNuke** - audit-log burst detection across channels, roles, bans,
   kicks, webhooks, emoji, and stickers per executor; a dangerous
-  permission-grant watchdog (catches a role quietly gaining Administrator
-  the moment it happens, with optional auto-revert); a server-identity
-  watchdog (name/icon/vanity URL changes); an invite-abuse watchdog
-  (unrestricted invites from non-staff); and webhook-flood containment
-  (deletes an abusive webhook and traces it back to its creator, since
-  webhook messages carry no guild member for other layers to see).
+  permission-grant watchdog covering both a role's own permissions
+  changing *and* a member being quietly handed an already-dangerous role
+  (with optional auto-revert); a channel permission-overwrite watchdog
+  (catches @everyone getting locked out of, or let into, a channel without
+  anything being deleted); a server-identity watchdog (name/icon/vanity URL
+  changes); an invite-abuse watchdog (unrestricted invites from non-staff);
+  and webhook-flood containment (deletes an abusive webhook and traces it
+  back to its creator, since webhook messages carry no guild member for
+  other layers to see).
 - **AI Moderation** (optional, off by default) - Groq-powered second opinion
   for messages the local NLP scores as "gray zone": not clean, not clearly
   over threshold. Supports a pool of API keys with automatic per-key
@@ -104,7 +109,8 @@ the 5-button control panel and arm layers from there instead of in code.
 
 Every layer starts disabled, per guild. Nothing runs until you list it in
 `autoStart`, call `frame.enableLayer(name, guildId)`, or arm it from the
-control panel.
+control panel. Add your own layer alongside these four with
+`frame.registerLayer()` - see "Extending it" below.
 
 ## Performance under load
 
@@ -128,17 +134,37 @@ for human review, never auto-banned), and only if there isn't already an
 open case for that member from a moment ago. Full write-up in
 `docs/PROTOCOL_LAYERS.md`.
 
+## Extending it
+
+- **`frame.registerLayer(name, layerInstance)`** - add your own security
+  layer to the same pipeline the built-in four use (per-guild enable/state/
+  persistence come free from extending `core/Layer`). Doesn't get a button
+  on the panel automatically - the panel stays fixed at exactly 5.
+- **`frame.registerAction(name, handler)`** - add a custom punishment
+  action beyond ban/kick/timeout/quarantine, referenceable from
+  `config.punishment.ladder`.
+- **`!gf prefix set <newPrefix>`** - each server can run its own prefix;
+  `config.prefix` always still works everywhere as a fallback.
+- **`getLogChannel(guild, layerName)`** - route different layers to
+  different channels, if you want; the second parameter is optional and
+  backward compatible.
+- **`!gf engine`** - an owner-only, bot-wide dashboard (busiest server, AI
+  usage, live cross-server activity feed), gated separately from every
+  other command and not listed in `!gf help`. See `docs/ENGINE.md`.
+
 ## Docs
 
 - `GETTING_STARTED.md` - adding GlassFrame to a bot you already have running.
 - `docs/PROTOCOL_LAYERS.md` - full architecture: containment vs. punishment,
-  how a signal becomes an action, how to add a fifth layer.
+  how a signal becomes an action, `registerLayer`/`registerAction`.
 - `docs/STATE.md` - per-guild layer/whitelist state and how persistence
   across restarts works.
 - `docs/CACHE_ARCHITECTURE.md` - every cache in the library, its key shape,
   its TTL, and how to turn on cache-level debug logging.
 - `docs/PERFORMANCE.md` - the bounded-concurrency queues and internal
   metrics collector, and what `!gf metrics` shows.
+- `docs/ENGINE.md` - the owner-only bot-wide dashboard: the password/lockout
+  system and what each of its 5 pages shows.
 - `docs/COMMANDS.md` - the full prefix command reference and the control
   panel's five buttons.
 - `docs/PUBLISHING.md` - publishing this package to npm, and what actually

package/dist/config.js

@@ -11,8 +11,9 @@ module.exports = {
   roleAnalysis: {
     // Role-name fragments (lowercased, substring match) that imply real authority.
     protectedNames: [
-      "owner", "admin", "administrator", "moderator", "mod",
-      "staff", "discord staff", "security"
+      "owner", "co-owner", "founder", "admin", "administrator",
+      "moderator", "mod", "staff", "discord staff", "security",
+      "management", "manager", "support", "helper", "developer"
     ],
     // Permission names (PermissionsBitField.Flags keys) treated as "dangerous"
     // when granted to a role - watched by AntiNuke's grant watchdog.
@@ -23,7 +24,16 @@ module.exports = {
     // Permission names that mark a member as genuinely trusted staff.
     trustPermissions: ["Administrator", "ManageGuild", "ManageRoles", "BanMembers", "KickMembers"],
     // A role younger than this that already holds a dangerous permission is extra suspicious.
-    newRoleGraceMs: 1000 * 60 * 10
+    newRoleGraceMs: 1000 * 60 * 10,
+    // A DIFFERENT axis from role-based trust above: how long an account
+    // and membership has simply existed, with no relation to roles or
+    // permissions. Used only to soften pure rate/volume spam detection for
+    // members who are just very active - see basicSecurity.establishedMemberLeniency
+    // and docs/PROTOCOL_LAYERS.md ("Established-member leniency").
+    maturity: {
+      minAccountAgeMs: 1000 * 60 * 60 * 24 * 180, // 6 months
+      minServerTenureMs: 1000 * 60 * 60 * 24 * 30 // 1 month in this server
+    }
   },
 
   threatEngine: {
@@ -44,11 +54,22 @@ module.exports = {
   basicSecurity: {
     spam: { windowMs: 6000, messageThreshold: 6, duplicateThreshold: 4 },
     mentionSpam: { maxMentionsPerMessage: 8 },
-    nlp: { scamScoreThreshold: 0.62, phishingScoreThreshold: 0.55 },
+    nlp: { scamScoreThreshold: 0.62, phishingScoreThreshold: 0.55, raidCalloutThreshold: 0.3 },
     // Seed domains for PhishingDatabase (src/security/PhishingDatabase.js).
     // Empty by default - populate with what you actually see via
     // `!gf phishing add <domain>` rather than shipping unverified blocklists.
-    linkGuard: { seedDomains: [] }
+    linkGuard: { seedDomains: [] },
+    // See roleAnalysis.maturity. Applies ONLY to pure rate/volume signals
+    // (message rate, duplicate flood) for established members - content
+    // signals (scam/phishing/raid language, links, non-trusted mass pings)
+    // stay at full strength no matter how old or long-tenured the sender
+    // is, since tenure says nothing about whether a given message is
+    // dangerous. Set both multipliers to 1 to disable this and treat
+    // every member identically.
+    establishedMemberLeniency: {
+      thresholdMultiplier: 2.5, // established members need this many times the normal rate before a signal fires at all
+      weightMultiplier: 0.3 // and the signal counts for less when it does
+    }
   },
 
   antiRaid: {
@@ -83,6 +104,10 @@ module.exports = {
     // A brand-new invite with no expiry and no use limit, created by anyone
     // other than the owner, is worth a look the moment it's created.
     watchInviteAbuse: true,
+    // Watches @everyone's channel permission overwrites specifically - a
+    // channel getting locked out for everyone, or a private channel getting
+    // opened to everyone, is a nuke technique that doesn't delete anything.
+    watchOverwriteAbuse: true,
     // A webhook that starts pushing a burst of messages within minutes of
     // being created is a classic "nuke via webhook" pattern - this catches
     // it even though the messages themselves look like normal messageCreate
@@ -134,5 +159,20 @@ module.exports = {
     // Default for GlassFrame's debug flag - logs every cache SET/HIT/MISS/EXPIRE to the console.
     // See docs/CACHE_ARCHITECTURE.md. Overridden by the `debug` constructor option if provided.
     debug: false
+  },
+
+  // The owner-only `!gf engine` dashboard - see docs/ENGINE.md. Being an
+  // owner (options.owners) is required no matter what; a password is an
+  // optional second factor on top of that for the initial command only -
+  // page-navigation button clicks are still gated by isOwner() but don't
+  // re-prompt for the password.
+  engine: {
+    // Set via an environment variable in your own bot, e.g.
+    // process.env.GLASSFRAME_ENGINE_PASSWORD - never hardcode a real
+    // password into a committed config.js. Leave null to skip the second
+    // factor and rely on the owners list alone.
+    password: null,
+    maxAttempts: 3,
+    lockoutMs: 1000 * 60 * 10
   }
 };

package/dist/src/GlassFrame.js

@@ -23,7 +23,7 @@ const AntiNukeLayer = require("./layers/AntiNukeLayer");
 const AIModerationLayer = require("./layers/AIModerationLayer");
 
 const PrefixRouter = require("./commands/PrefixRouter");
-const { buildPanel, buildMetricsMessage } = require("./ui/ControlPanel");
+const { buildPanel, buildMetricsMessage, buildEnginePage } = require("./ui/ControlPanel");
 
 const LAYER_NAMES = ["basicSecurity", "antiRaid", "antiNuke", "aiModeration"];
 
@@ -54,8 +54,15 @@ class GlassFrame extends EventEmitter {
     // as autoStart), never overriding a guild's own saved whitelist.
     this.defaultWhitelist = new Set(options.whitelist || []);
     this.whitelist = new Map(); // guildId -> Set<userId>
+    this.customActions = new Map(); // actionName -> async (member, record) => void, for registerAction()
+    this.guildPrefixes = new Map(); // guildId -> custom prefix, for setPrefix()
     this.panelMessages = new Map(); // messageId -> guildId
     this.debug = Boolean(options.debug ?? this.config.cache.debug);
+    // Bot-owner user IDs - separate from per-guild Manage Server admins,
+    // since cross-server data (busiest server, all-guild activity) isn't
+    // something a random single server's admin should see about others.
+    this.owners = new Set(options.owners || []);
+    this.engineAttempts = new Map(); // userId -> { count, lockedUntil }
 
     this.threatEngine = new ThreatEngine(this.config, { debug: this.debug });
     this.roleAnalyzer = new RoleAnalyzer(this.config);
@@ -77,6 +84,7 @@ class GlassFrame extends EventEmitter {
       roleAnalyzer: this.roleAnalyzer,
       logger: this.logger,
       whitelist: this.whitelist,
+      customActions: this.customActions,
       queue: this.actionQueue,
       performance: this.performance,
       debug: this.debug
@@ -123,6 +131,40 @@ class GlassFrame extends EventEmitter {
     return member.permissions.has(PermissionsBitField.Flags.ManageGuild);
   }
 
+  /** For the owner-only !gf engine dashboard - separate from per-guild isAuthorized(). */
+  isOwner(userId) {
+    return this.owners.has(userId);
+  }
+
+  /**
+   * Second factor on top of isOwner(), only for the initial `!gf engine`
+   * command - not required again for page-navigation button clicks, since
+   * those are already tied to a real, already-verified Discord identity.
+   * Returns true with no config.engine.password set (owner check alone is
+   * enough). Locks a user out for engine.lockoutMs after
+   * engine.maxAttempts wrong guesses, to make brute-forcing impractical.
+   */
+  verifyEnginePassword(userId, provided) {
+    const cfg = this.config.engine;
+    if (!cfg.password) return true;
+
+    const attempt = this.engineAttempts.get(userId) || { count: 0, lockedUntil: 0 };
+    if (Date.now() < attempt.lockedUntil) return false;
+
+    if (provided === cfg.password) {
+      this.engineAttempts.delete(userId);
+      return true;
+    }
+
+    attempt.count++;
+    if (attempt.count >= cfg.maxAttempts) {
+      attempt.lockedUntil = Date.now() + cfg.lockoutMs;
+      attempt.count = 0;
+    }
+    this.engineAttempts.set(userId, attempt);
+    return false;
+  }
+
   getStatus(guildId) {
     const out = {};
     for (const [name, layer] of Object.entries(this.layers)) {
@@ -174,6 +216,50 @@ class GlassFrame extends EventEmitter {
     };
   }
 
+  /**
+   * Everything about the running process at once, across every guild -
+   * what's live, what's fast/slow, which server is generating the most
+   * work, and the last several things that happened anywhere. Powers the
+   * owner-only `!gf engine` command. This is intentionally NOT reachable
+   * by a per-guild admin - see isOwner().
+   */
+  getEngineReport() {
+    const guilds = [...this.client.guilds.cache.values()];
+    const layerNames = Object.keys(this.layers);
+
+    const adoption = {};
+    for (const name of layerNames) {
+      adoption[name] = guilds.filter((g) => this.layers[name].isEnabled(g.id)).length;
+    }
+
+    const busiest = this.performance.topGuildsByActivity(5).map(([guildId, count]) => {
+      const guild = this.client.guilds.cache.get(guildId);
+      return { guildId, name: guild ? guild.name : "(left / unknown)", count };
+    });
+
+    const recentLogs = this.logger.getRecentLogs(10).map((entry) => ({
+      ...entry,
+      guildName: this.client.guilds.cache.get(entry.guildId)?.name || entry.guildName || entry.guildId
+    }));
+
+    return {
+      version: VersionInfo.info(),
+      uptimeMs: Date.now() - this.performance.startedAt,
+      guildCount: guilds.length,
+      layerAdoption: adoption,
+      metrics: this.getMetrics(),
+      busiestGuilds: busiest,
+      recentLogs,
+      ai: {
+        available: this.groqClient.available,
+        keyCount: this.groqClient.keys.length,
+        keysOnCooldown: this.groqClient.keys.filter((k) => k.cooldownUntil > Date.now()).length,
+        callsLastMinute: this.groqClient.callTimestamps.length,
+        totalCallsRecorded: this.performance.eventCounts["groqClient.classify"] || 0
+      }
+    };
+  }
+
   enableLayer(name, guildId) {
     if (!this.layers[name]) throw new Error(`GlassFrame Protocol: unknown layer "${name}"`);
     if (!guildId) throw new Error("GlassFrame Protocol: enableLayer(name, guildId) requires a guildId - layers are per-guild.");
@@ -188,29 +274,83 @@ class GlassFrame extends EventEmitter {
     return this;
   }
 
-  /** Snapshots one guild's layer + whitelist state into stateStore. Fire-and-forget by design (never blocks a handler on disk/network I/O). */
+  /**
+   * Adds your own security layer to the same pipeline the built-in four
+   * use - it gets per-guild enable/disable, state persistence, and can
+   * report signals to the shared ThreatEngine/PunishmentEngine, all for
+   * free. `layerInstance` must extend `core/Layer` (see
+   * docs/PROTOCOL_LAYERS.md, "Adding a fifth layer"). Custom layers do NOT
+   * get a button on the 5-button panel automatically - toggle them via
+   * `frame.enableLayer(name, guildId)` in code, or build your own command.
+   */
+  registerLayer(name, layerInstance) {
+    if (this.layers[name]) throw new Error(`GlassFrame Protocol: a layer named "${name}" already exists`);
+    if (typeof layerInstance?.attach !== "function" || typeof layerInstance?.enable !== "function") {
+      throw new Error("GlassFrame Protocol: registerLayer() expects an instance extending core/Layer");
+    }
+    this.layers[name] = layerInstance;
+    layerInstance.attach();
+    this.emit("layerRegistered", { layer: name });
+    return this;
+  }
+
+  /**
+   * Adds a custom punishment action beyond the built-in
+   * ban/kick/timeout/quarantine, so `config.punishment.ladder` can
+   * reference it by name. `handler` is `async (member, record) => {}` -
+   * `record` is the case object (tier, trust, reasons, ...). Runs through
+   * the same bounded-concurrency action queue as the built-in actions.
+   *
+   * @example
+   * frame.registerAction("addMutedRole", async (member) => {
+   *   const role = member.guild.roles.cache.find((r) => r.name === "Muted");
+   *   if (role) await member.roles.add(role);
+   * });
+   * // config: { punishment: { ladder: { medium: "addMutedRole" } } }
+   */
+  registerAction(name, handler) {
+    if (this.customActions.has(name)) throw new Error(`GlassFrame Protocol: an action named "${name}" is already registered`);
+    if (typeof handler !== "function") throw new Error("GlassFrame Protocol: registerAction() expects a function");
+    this.customActions.set(name, handler);
+    return this;
+  }
+
+  /** The prefix this guild actually uses - its own custom one if set, otherwise config.prefix. */
+  getPrefix(guildId) {
+    return this.guildPrefixes.get(guildId) || this.config.prefix;
+  }
+
+  /** Sets this guild's own command prefix. config.prefix keeps working everywhere as a fallback, in case a server forgets its custom one. */
+  setPrefix(guildId, prefix) {
+    this.guildPrefixes.set(guildId, prefix);
+    this._persistGuildState(guildId);
+  }
+
+  /** Snapshots one guild's layer + whitelist + prefix state into stateStore. Fire-and-forget by design (never blocks a handler on disk/network I/O). */
   _persistGuildState(guildId) {
     const state = {
       layers: this.getStatus(guildId),
-      whitelist: [...(this.whitelist.get(guildId) || [])]
+      whitelist: [...(this.whitelist.get(guildId) || [])],
+      prefix: this.guildPrefixes.get(guildId) || null
     };
     Promise.resolve(this.stateStore.set(guildId, state)).catch((err) =>
       this.emit("warning", { layer: "core", message: `failed to persist state for ${guildId}: ${err.message}` })
     );
   }
 
-  /** Loads a guild's saved state if one exists; otherwise applies the autoStart defaults (and persists that as the new baseline). */
+  /** Loads a guild's saved state if one exists; otherwise applies the autoStart/whitelist defaults (and persists that as the new baseline). */
   async _restoreGuildState(guildId) {
     const saved = await this.stateStore.get(guildId);
 
     if (saved) {
-      for (const name of LAYER_NAMES) {
+      for (const name of Object.keys(this.layers)) {
         if (saved.layers?.[name]) this.layers[name].enable(guildId);
       }
       for (const userId of saved.whitelist || []) {
         if (!this.whitelist.has(guildId)) this.whitelist.set(guildId, new Set());
         this.whitelist.get(guildId).add(userId);
       }
+      if (saved.prefix) this.guildPrefixes.set(guildId, saved.prefix);
       return;
     }
 
@@ -231,6 +371,8 @@ class GlassFrame extends EventEmitter {
           await this._handlePanelButton(interaction);
         } else if (interaction.customId.startsWith("gfp_metrics_")) {
           await this._handleMetricsButton(interaction);
+        } else if (interaction.customId.startsWith("gfp_engine_")) {
+          await this._handleEngineButton(interaction);
         }
       } catch (err) {
         this.emit("warning", { layer: "controlPanel", message: err.message });
@@ -267,6 +409,7 @@ class GlassFrame extends EventEmitter {
     await this.logger.log(interaction.guild, {
       level: "info",
       title: "Protocol Layer Toggled",
+      layer: "controlPanel",
       description: `${interaction.user.tag} updated GlassFrame Protocol layers from the control panel.`,
       dedupeKey: "panel:toggle"
     });
@@ -282,6 +425,24 @@ class GlassFrame extends EventEmitter {
     const payload = buildMetricsMessage(this, interaction.guild.id, scope);
     await interaction.update(payload);
   }
+
+  /**
+   * Page navigation on the engine dashboard. Gated by isOwner() on the
+   * clicking Discord identity - not by the password again, since a button
+   * click is already tied to a real, verified Discord session, and
+   * re-prompting for a password on every tab click would be unusable.
+   */
+  async _handleEngineButton(interaction) {
+    if (!this.isOwner(interaction.user.id)) {
+      await interaction.reply({ content: "This isn't for you.", ephemeral: true });
+      return;
+    }
+
+    const page = interaction.customId.replace("gfp_engine_", "");
+    const report = this.getEngineReport();
+    const payload = buildEnginePage(report, page);
+    await interaction.update(payload);
+  }
 }
 
 function mergeConfig(base, override) {