glassframe-protocol 2.0.0 → 2.2.0

package/dist/src/logging/SmartLogger.js

@@ -2,12 +2,23 @@
 
 const { buildLogMessage } = require("./ComponentsV2");
 
+const RECENT_LOG_LIMIT = 30;
+
 /**
  * Every GlassFrame alert goes through one gate that:
  *  (a) merges near-duplicate events inside a short window into a single,
- *      updated message instead of one message per event, and
+ *      updated message instead of one message per event,
  *  (b) never sends to a guild's log channel faster than a configured floor,
- * so a burst never turns into a wall of messages or a Discord 429.
+ *      so a burst never turns into a wall of messages or a Discord 429, and
+ *  (c) keeps a small in-memory record of the most recent events across
+ *      EVERY guild, for the owner-only `!gf engine` dashboard - see
+ *      getRecentLogs() below.
+ *
+ * `getLogChannel(guild, layerName)` receives the reporting layer's name as
+ * an optional second argument, so you can route different layers to
+ * different channels if you want. A `getLogChannel` that only takes one
+ * parameter (the common case) keeps working unchanged - JS simply ignores
+ * the extra argument.
  */
 class SmartLogger {
   constructor(getLogChannel, config, { debug = false } = {}) {
@@ -16,10 +27,12 @@ class SmartLogger {
     this.debug = debug;
     this.pending = new Map(); // dedupeKey -> { count, payload, sent }
     this.lastSend = new Map(); // guildId -> timestamp
+    this.recentLogs = []; // bounded ring buffer, newest first - see getRecentLogs()
   }
 
   async log(guild, payload) {
     const key = payload.dedupeKey ? `${guild.id}:${payload.dedupeKey}` : null;
+    this._recordRecent(guild, payload);
 
     if (key && this.pending.has(key)) {
       const entry = this.pending.get(key);
@@ -56,7 +69,7 @@ class SmartLogger {
 
   async _deliver(guild, payload, count) {
     await this._respectRateFloor(guild.id);
-    const channel = await this.getLogChannel(guild);
+    const channel = await this.getLogChannel(guild, payload.layer);
     if (!channel) return null;
 
     const message = buildLogMessage({ ...payload, count });
@@ -76,6 +89,23 @@ class SmartLogger {
     if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
   }
 
+  _recordRecent(guild, payload) {
+    this.recentLogs.unshift({
+      at: Date.now(),
+      guildId: guild.id,
+      guildName: guild.name,
+      level: payload.level || "info",
+      title: payload.title || "",
+      layer: payload.layer || null
+    });
+    if (this.recentLogs.length > RECENT_LOG_LIMIT) this.recentLogs.length = RECENT_LOG_LIMIT;
+  }
+
+  /** The most recent log events across every guild, newest first - powers the owner-only `!gf engine` command. */
+  getRecentLogs(limit = 10) {
+    return this.recentLogs.slice(0, limit);
+  }
+
   _debug(msg) {
     if (this.debug) console.log(`[GlassFrame:SmartLogger] ${msg}`);
   }

package/dist/src/moderation/PunishmentEngine.js

@@ -5,8 +5,11 @@ const ProtocolCache = require("../core/Cache");
 
 // Used only to decide whether continued bad behavior mid-case deserves a
 // stronger response - never to decide the response itself (_decideAction
-// still owns that, trust-gating included).
+// still owns that, trust-gating included). Custom actions (registerAction)
+// default to 2 - the same tier as quarantine/timeout - since there's no
+// way to know their real severity automatically.
 const ACTION_SEVERITY = { log: 0, alert: 1, quarantine: 2, timeout: 2, kick: 3, ban: 4 };
+const severityOf = (action) => ACTION_SEVERITY[action] ?? 2;
 
 /**
  * The only place in GlassFrame Protocol that actually punishes a member.
@@ -18,12 +21,16 @@ const ACTION_SEVERITY = { log: 0, alert: 1, quarantine: 2, timeout: 2, kick: 3,
  * ladder alone would say.
  */
 class PunishmentEngine extends EventEmitter {
-  constructor({ config, threatEngine, roleAnalyzer, logger, whitelist, queue, performance, debug = false }) {
+  constructor({ config, threatEngine, roleAnalyzer, logger, whitelist, customActions, queue, performance, debug = false }) {
     super();
     this.config = config.punishment;
     this.threatEngine = threatEngine;
     this.roleAnalyzer = roleAnalyzer;
     this.logger = logger;
+    // actionName -> async (member, record) => void, registered via
+    // frame.registerAction() so config.punishment.ladder can reference
+    // custom actions beyond ban/kick/timeout/quarantine.
+    this.customActions = customActions || new Map();
     // Actual Discord mutations (ban/kick/timeout/quarantine) go through this
     // bounded-concurrency queue rather than firing directly, so a burst of
     // simultaneous cases (a raid, a nuke sweep) can't overrun Discord's rate
@@ -67,7 +74,7 @@ class PunishmentEngine extends EventEmitter {
 
       const trust = this.roleAnalyzer.trustLevel(member);
       const nextAction = this._decideAction(tier, trust);
-      if (ACTION_SEVERITY[nextAction] > ACTION_SEVERITY[openCase.action]) {
+      if (severityOf(nextAction) > severityOf(openCase.action)) {
         openCase.action = nextAction;
         openCase.trust = trust;
         this.cases.set(key, openCase);
@@ -125,6 +132,9 @@ class PunishmentEngine extends EventEmitter {
         const removable = member.roles.cache.filter((r) => r.id !== guild.id && r.editable);
         await this.queue.push(() => member.roles.remove(removable, this._reason(record)));
         performed = true;
+      } else if (this.customActions.has(action) && canAct) {
+        await this.queue.push(() => this.customActions.get(action)(member, record));
+        performed = true;
       }
     } catch (err) {
       record.error = err.message;
@@ -141,6 +151,7 @@ class PunishmentEngine extends EventEmitter {
     await this.logger.log(guild, {
       level: action === "alert" ? "alert" : action === "log" ? "info" : "warn",
       title: this._title(action),
+      layer: "punishmentEngine",
       description: `${member.user.tag} (${member.id}) - tier **${record.tier}**, trust **${record.trust}**.`,
       fields: [
         { name: "Reasons", value: record.reasons.slice(-5).join("\n") },

package/dist/src/moderation/RoleAnalyzer.js

@@ -39,6 +39,32 @@ class RoleAnalyzer {
     return "LOW";
   }
 
+  /**
+   * A DIFFERENT question from trustLevel() above: not "does this member
+   * hold real authority," but "has this account and this membership simply
+   * existed long enough to not look like a fresh raid/alt account." No
+   * relation to roles or permissions - a totally ordinary member with no
+   * special role can be "established," and a MEDIUM-trust role holder with
+   * a week-old account isn't.
+   *
+   * This exists to soften pure rate/volume spam detection (see
+   * BasicSecurityLayer) for members who are simply very active, the way
+   * modern invisible CAPTCHA judges from signals already available instead
+   * of a one-size-fits-all challenge - it is deliberately NOT used to
+   * soften content-based detection (scam/phishing/raid language, links),
+   * since account age says nothing about whether a specific message is
+   * dangerous. An established account can still raid or spam; this only
+   * ever reduces false positives on "sends a lot of messages," never
+   * blanket-exempts anyone from everything else.
+   */
+  isEstablishedMember(member) {
+    if (!member || !member.user) return false;
+    const cfg = this.config.maturity;
+    const accountAge = Date.now() - member.user.createdTimestamp;
+    const serverTenure = member.joinedTimestamp ? Date.now() - member.joinedTimestamp : 0;
+    return accountAge >= cfg.minAccountAgeMs && serverTenure >= cfg.minServerTenureMs;
+  }
+
   /**
    * Scans a guild's current roles for name/permission mismatches: a role
    * whose name signals authority ("admin", "staff", ...) but carries no real

package/dist/src/ui/ControlPanel.js

@@ -74,24 +74,51 @@ function buildMetricsMessage(frame, guildId, scope = "guild") {
         .map(([name, ms]) => `${name}: ${ms}ms avg`)
         .join("\n") || "no samples yet";
 
+    const queueNote = (q) =>
+      q.pending > 0
+        ? `-# ${q.pending} task(s) queued behind the concurrency cap - normal during a burst, worth raising the cap in config if it's constant.`
+        : "-# Nothing queued - everything is running as soon as it's requested.";
+
     fields.push(
       { name: "Uptime", value: `${Math.round(m.performance.uptimeMs / 60000)} min` },
-      { name: "Action queue", value: fmtQueue(m.queues.actions) },
-      { name: "AI queue", value: fmtQueue(m.queues.ai) },
-      { name: "Threat score cache (all servers)", value: fmtCache(m.caches.threatScores) },
-      { name: "Open case cache (all servers)", value: fmtCache(m.caches.openCases) },
-      { name: "Groq verdict cache (all servers)", value: fmtCache(m.caches.groqVerdicts) },
-      { name: "Average latency", value: fmtLatency }
+      { name: "Action queue", value: `${fmtQueue(m.queues.actions)}\n${queueNote(m.queues.actions)}` },
+      { name: "AI queue", value: `${fmtQueue(m.queues.ai)}\n${queueNote(m.queues.ai)}` },
+      {
+        name: "Threat score cache (all servers)",
+        value: `${fmtCache(m.caches.threatScores)}\n-# One entry per member with any recent signal, across every server - this decays and self-prunes, so a high size alone isn't a problem.`
+      },
+      {
+        name: "Open case cache (all servers)",
+        value: `${fmtCache(m.caches.openCases)}\n-# Members currently inside their debounce window after being actioned - this is what stops a repeat trip from re-punishing or re-logging.`
+      },
+      {
+        name: "Groq verdict cache (all servers)",
+        value: `${fmtCache(m.caches.groqVerdicts)}\n-# A high hit rate means repeated/near-identical messages are being caught without a fresh API call each time.`
+      },
+      { name: "Average latency", value: fmtLatency || "no samples yet" }
     );
   } else {
     const gm = frame.getGuildMetrics(guildId);
     const statusLines = REAL_LAYERS.map((l) => `${gm.status[l] ? "ACTIVE" : "inactive"} - ${l}`).join("\n");
+    const activeCount = REAL_LAYERS.filter((l) => gm.status[l]).length;
 
     fields.push(
-      { name: "Layers", value: statusLines },
-      { name: "Flagged members right now", value: String(gm.flaggedMembers) },
-      { name: "Open cases", value: String(gm.openCases) },
-      { name: "Whitelisted users", value: String(gm.whitelistSize) }
+      {
+        name: "Layers",
+        value: `${statusLines}\n-# ${activeCount === 0 ? "Nothing is armed yet - use the panel or autoStart to turn a layer on." : `${activeCount}/4 layers watching this server.`}`
+      },
+      {
+        name: "Flagged members right now",
+        value: `${gm.flaggedMembers}\n-# Members with a live risk score above zero. This naturally decays over time on its own - a number that keeps climbing is worth a closer look, one that holds steady usually isn't.`
+      },
+      {
+        name: "Open cases",
+        value: `${gm.openCases}\n-# Members currently in their post-action cooldown window. A repeat trip within it escalates the same case rather than opening (or logging) a new one.`
+      },
+      {
+        name: "Whitelisted users",
+        value: `${gm.whitelistSize}\n-# Users exempt from punitive action in this server specifically - whitelisting elsewhere doesn't affect this count.`
+      }
     );
   }
 
@@ -119,4 +146,107 @@ function buildMetricsMessage(frame, guildId, scope = "guild") {
   return { flags: MessageFlags.IsComponentsV2, components: [container] };
 }
 
-module.exports = { buildPanel, buildMetricsMessage, BUTTONS };
+const ENGINE_PAGES = [
+  { id: "overview", label: "Overview" },
+  { id: "servers", label: "Servers" },
+  { id: "ai", label: "AI" },
+  { id: "performance", label: "Performance" },
+  { id: "logs", label: "Activity Log" }
+];
+
+/**
+ * The owner-only `!gf engine` dashboard - everything running across every
+ * guild at once, split into 5 pages so each one has room to actually go
+ * deep instead of cramming everything into one message. Built from
+ * `frame.getEngineReport()`. Reaching the FIRST page requires
+ * verifyEnginePassword() (see GlassFrame.js) if one is configured;
+ * navigating between pages afterward only re-checks isOwner() on the
+ * clicking Discord identity, not the password again.
+ */
+function buildEnginePage(report, page = "overview") {
+  const container = new ContainerBuilder().setAccentColor(0x5865f2);
+  container.addTextDisplayComponents(
+    new TextDisplayBuilder().setContent(
+      `**GlassFrame Protocol - Engine**\n${report.version.name} v${report.version.version} | up ${Math.round(report.uptimeMs / 60000)} min | serving ${report.guildCount} server(s)`
+    )
+  );
+  container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+
+  if (page === "overview") {
+    const layerLines = Object.entries(report.layerAdoption)
+      .map(([name, count]) => `${name}: armed in ${count}/${report.guildCount} server(s)`)
+      .join("\n");
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(`**Layer adoption across every server**\n${layerLines}`)
+    );
+  } else if (page === "servers") {
+    const lines = report.busiestGuilds.length
+      ? report.busiestGuilds.map((g, i) => `${i + 1}. ${g.name} (${g.guildId}) - ${g.count} events recorded`).join("\n")
+      : "No activity recorded yet.";
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(`**Busiest servers, ranked by event volume**\n${lines}`)
+    );
+    container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(
+        "-# \"Events\" counts messages/joins/audit entries any layer processed for that server since this process started - it resets on restart, and isn't a measure of how much trouble a server is causing, just how much traffic it has."
+      )
+    );
+  } else if (page === "ai") {
+    const lines = [
+      `Groq available: ${report.ai.available ? "yes" : "no (no keys configured)"}`,
+      `Key pool: ${report.ai.keyCount} total, ${report.ai.keysOnCooldown} currently on cooldown`,
+      `Calls in the last minute: ${report.ai.callsLastMinute}`,
+      `Total classify() calls this run: ${report.ai.totalCallsRecorded}`,
+      `Verdict cache: ${report.metrics.caches.groqVerdicts.size} entries, ${report.metrics.caches.groqVerdicts.hits} hits / ${report.metrics.caches.groqVerdicts.misses} misses`
+    ].join("\n");
+    container.addTextDisplayComponents(new TextDisplayBuilder().setContent(`**AI moderation usage**\n${lines}`));
+  } else if (page === "performance") {
+    const m = report.metrics;
+    const fmtCache = (c) => `size ${c.size} | hits ${c.hits} | misses ${c.misses} | evictions ${c.evictions}`;
+    const fmtQueue = (q) => `active ${q.active}/${q.concurrency} | pending ${q.pending} | completed ${q.completed} | failed ${q.failed}`;
+    const latencyLines =
+      Object.entries(m.performance.avgLatencyMs)
+        .map(([name, ms]) => `${name}: ${ms}ms avg`)
+        .join("\n") || "no samples yet";
+
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(
+        `**Queues**\nAction queue: ${fmtQueue(m.queues.actions)}\nAI queue: ${fmtQueue(m.queues.ai)}`
+      )
+    );
+    container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(
+        `**Caches**\nThreat scores: ${fmtCache(m.caches.threatScores)}\nOpen cases: ${fmtCache(m.caches.openCases)}\nGroq verdicts: ${fmtCache(m.caches.groqVerdicts)}`
+      )
+    );
+    container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+    container.addTextDisplayComponents(new TextDisplayBuilder().setContent(`**Average latency**\n${latencyLines}`));
+  } else if (page === "logs") {
+    const lines = report.recentLogs.length
+      ? report.recentLogs
+          .map((e) => `[${new Date(e.at).toISOString().slice(11, 19)}] ${e.guildName} - ${e.title}${e.layer ? ` (${e.layer})` : ""}`)
+          .join("\n")
+      : "Nothing logged yet.";
+    container.addTextDisplayComponents(
+      new TextDisplayBuilder().setContent(`**Recent activity, every server (last ${report.recentLogs.length})**\n${lines}`)
+    );
+  }
+
+  container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+  const row = new ActionRowBuilder().addComponents(
+    ENGINE_PAGES.map((p) =>
+      new ButtonBuilder()
+        .setCustomId(`gfp_engine_${p.id}`)
+        .setLabel(p.label)
+        .setStyle(p.id === page ? ButtonStyle.Success : ButtonStyle.Secondary)
+    )
+  );
+  container.addActionRowComponents(row);
+  container.addTextDisplayComponents(new TextDisplayBuilder().setContent("-# GlassFrame Protocol - owner-only view"));
+
+  return { flags: MessageFlags.IsComponentsV2, components: [container] };
+}
+
+module.exports = { buildPanel, buildMetricsMessage, buildEnginePage, ENGINE_PAGES, BUTTONS };

package/dist/src/utils/nlpEngine.js

@@ -103,9 +103,9 @@ const PHISHING_LEXICON = {
 };
 
 const RAID_CALLOUT_LEXICON = {
-  strong: new Set(["raid", "nuke", "spam", "flood", "wipe", "destroy", "invite", "bot"]),
+  strong: new Set(["raid", "raiding", "raids", "raided", "nuke", "nuking", "spam", "spamming", "flood", "wipe", "destroy", "invite", "bot"]),
   weak: new Set(["server", "join", "everyone", "ping", "mass"]),
-  bigrams: new Set(["raid this", "nuke server", "mass ping", "spam bots", "join now"])
+  bigrams: new Set(["raid this", "nuke server", "mass ping", "spam bots", "join now", "start raiding"])
 };
 
 function suspiciousUsernameEntropy(username, floor, ceiling) {

package/docs/CACHE_ARCHITECTURE.md

@@ -37,6 +37,11 @@ windows with no need for hit/miss stats: `AntiRaidLayer.joinTimestamps` /
 are swept lazily - old timestamps are filtered out on the next write rather
 than on a timer, since they're only ever read right after a write.
 
+`SmartLogger.recentLogs` is a fixed-size array (last 30, newest first, not
+a `ProtocolCache`) recording every log event across every guild - it's what
+powers the owner-only `!gf engine` dashboard's Activity Log page. See
+`docs/ENGINE.md`.
+
 Bounded-concurrency queues (`frame.actionQueue`, `frame.aiQueue`) and the
 internal metrics collector (`frame.performance`) are a separate concern from
 caching - see `docs/PERFORMANCE.md`.

package/docs/COMMANDS.md

@@ -18,7 +18,19 @@ running twice or getting a "slow down" reply of its own.
 | `!gf phishing list` | Lists every blocked domain. |
 | `!gf whitelist add <userId>` | Exempts a user from punitive action **in this server**. |
 | `!gf whitelist remove <userId>` | Removes that exemption for this server. |
-| `!gf help` | Lists these commands. |
+| `!gf prefix set <newPrefix>` | Changes this server's own command prefix. |
+| `!gf prefix reset` | Goes back to the default prefix. |
+| `!gf help` | Lists these commands (this list, minus `engine` - see below). |
+
+There is also an owner-only `!gf engine` command - deliberately left out of
+`!gf help` and out of this table's normal flow on purpose. See
+`docs/ENGINE.md`.
+
+Each server can set its own prefix (`!gf prefix set`) - the default from
+`config.prefix` always still works too, as a fallback, in case a server
+forgets its custom one. If a custom prefix happens to overlap with the
+default (e.g. custom `!` vs. default `!gf `), the longer one is tried
+first.
 
 Everything above operates on the server the command was sent in - arming
 AntiRaid, whitelisting someone, or checking status in one server has no

package/docs/ENGINE.md

@@ -0,0 +1,83 @@
+# The Engine Dashboard
+
+`!gf engine` is a bot-wide, cross-server dashboard for whoever actually runs
+the bot - not a per-server admin tool. It shows things a single server's
+admin shouldn't be able to see about *other* servers (which server is
+busiest, bot-wide AI usage, a live feed of what's happening everywhere), so
+it has its own, separate permission model from every other command.
+
+It is deliberately **not** listed in `!gf help` or `docs/COMMANDS.md`'s
+in-Discord command table - a random server admin shouldn't even know it
+exists. You're expected to learn about it from this file.
+
+## Who can use it
+
+Two independent checks, not one:
+
+1. **`isOwner(userId)`** - you must be listed in `options.owners` when you
+   construct `GlassFrame`. This is required, full stop, for the command
+   itself *and* every page-navigation button click afterward.
+2. **A password** (optional) - if `config.engine.password` is set, the
+   initial `!gf engine <password>` command also needs the correct password.
+   Page-navigation button clicks after that don't re-prompt for it, since a
+   button click is already tied to a real, verified Discord identity - only
+   the text-command entry point needs the second factor.
+
+```js
+const frame = new GlassFrame(client, {
+  getLogChannel: /* ... */,
+  owners: ["your-discord-user-id"],
+  config: {
+    engine: {
+      password: process.env.GLASSFRAME_ENGINE_PASSWORD // never hardcode a real one
+    }
+  }
+});
+```
+
+Leave `config.engine.password` unset to skip the second factor and rely on
+the owners list alone.
+
+## What happens to the password
+
+Typing a password into a normal Discord message means it briefly sits in
+plain text in a channel, visible to anyone watching and to Discord's own
+message history. GlassFrame does two things about that:
+
+- The command message is **deleted immediately** after being checked,
+  whether the password was right or wrong.
+- Wrong guesses count toward a **lockout** -
+  `config.engine.maxAttempts` wrong attempts (default 3) locks that user
+  out for `config.engine.lockoutMs` (default 10 minutes), making
+  brute-forcing impractical.
+
+Use a private channel (or a channel only you can see) for this command
+regardless - deletion happens right after Discord delivers the message, not
+before anyone in the channel could have glimpsed it.
+
+## The five pages
+
+One row of tab buttons switches between them; the active tab is highlighted.
+
+| Page | Shows |
+|---|---|
+| **Overview** | Version, uptime, guild count, layer adoption across every server |
+| **Servers** | The busiest servers ranked by event volume since this process started |
+| **AI** | Groq key pool status, cooldowns, call volume, verdict cache hit rate |
+| **Performance** | Action/AI queue depth, all three cache stats, average latency per operation |
+| **Activity Log** | The last several things logged anywhere, any server, newest first |
+
+All of it comes from one call: `frame.getEngineReport()`, if you want the
+raw data instead of the rendered message (for your own dashboard, an API
+endpoint, whatever).
+
+## "Busiest" and the activity log, precisely
+
+- **Busiest** is a count of events (messages/joins/audit entries) any armed
+  layer processed for that server, tracked in memory since the process
+  started - it resets on restart and isn't a judgment about which server is
+  causing trouble, just which one has the most traffic.
+- The **activity log** is the last 30 events logged anywhere (any server,
+  any layer), kept in memory by `SmartLogger` - see
+  `docs/CACHE_ARCHITECTURE.md`. The dashboard shows the most recent 10 of
+  those.

package/docs/PROTOCOL_LAYERS.md

@@ -83,13 +83,76 @@ that server*, and again on demand via `!gf scan`. It reports flags, never
 actions - a human decides what, if anything, to do about a role that looks
 like impersonation bait or quietly holds dangerous permissions.
 
-## Adding a fifth layer
-
-Extend `Layer`, implement `attach()` (register your event listener(s) once;
-gate all real work behind `this.isEnabled(guildId)`), report signals via
-`this.frame.punishmentEngine.report({ guild, member, layer, weight, reason })`,
-register the instance in `GlassFrame`'s `this.layers` map, and add a button
-in `src/ui/ControlPanel.js` if you want it on the panel. Nothing else in the
-pipeline needs to know the new layer exists - per-guild enable/disable,
-state persistence, and metrics all come from the base `Layer` class for
-free.
+## Adding a layer without editing the library
+
+`frame.registerLayer(name, layerInstance)` is the supported way to do this
+now - no need to edit `GlassFrame.js`'s `this.layers` map by hand.
+`layerInstance` must extend `core/Layer`: implement `attach()` (register
+your event listener(s) once - it's called exactly once, at registration),
+gate all real work behind `this.isEnabled(guildId)`, and report signals via
+`this.frame.punishmentEngine.report({ guild, member, layer, weight, reason })`.
+Per-guild enable/disable, state persistence, and `!gf status`/`!gf metrics`
+all pick it up automatically, since they iterate `frame.layers` rather than
+a fixed list. It does **not** get a button on the 5-button panel
+automatically (that stays fixed at exactly 5) - toggle it with
+`frame.enableLayer(name, guildId)` in code, or build your own command.
+
+```js
+const Layer = require("glassframe-protocol/src/core/Layer");
+
+class LinkAgeLayer extends Layer {
+  constructor(frame) { super("linkAge", frame); }
+  attach() {
+    this._listen(this.client, "messageCreate", (message) => this._handle(message).catch(() => {}));
+  }
+  async _handle(message) {
+    if (!message.guild || message.author.bot) return;
+    if (!this.isEnabled(message.guild.id)) return;
+    // ... your detection logic, then:
+    // await this.frame.punishmentEngine.report({ guild: message.guild, member: message.member, layer: "linkAge", weight: 40, reason: "..." });
+  }
+}
+
+frame.registerLayer("linkAge", new LinkAgeLayer(frame));
+```
+
+## Custom punishment actions
+
+`frame.registerAction(name, handler)` adds an action beyond the built-in
+ban/kick/timeout/quarantine, so `config.punishment.ladder` can reference it
+by name. `handler` is `async (member, record) => {}` and runs through the
+same bounded-concurrency action queue as the built-in ones.
+
+```js
+frame.registerAction("addMutedRole", async (member) => {
+  const role = member.guild.roles.cache.find((r) => r.name === "Muted");
+  if (role) await member.roles.add(role);
+});
+```
+```js
+config: { punishment: { ladder: { medium: "addMutedRole" } } }
+```
+
+## Established-member leniency
+
+A separate axis from role-based trust, for a question role trust can't
+answer: not "does this member have authority," but "has this account and
+this membership simply existed long enough to not look like a fresh raid
+account." `RoleAnalyzer.isEstablishedMember(member)` checks account age and
+server tenure against `roleAnalysis.maturity` (defaults: 6 months, 1
+month). A totally ordinary member with no special role can be
+"established"; a MEDIUM-trust role holder with a week-old account isn't.
+
+`BasicSecurityLayer` is the only place this is used, and only for the two
+pure rate/volume checks (message rate, duplicate flood) -
+`basicSecurity.establishedMemberLeniency` raises the threshold before
+either fires at all and reduces the weight when it does, and neither
+deletes an established member's message on its own. Every content-based
+check (scam/phishing/raid-recruitment language, links, non-trusted mass
+pings) is completely unaffected by tenure - full threshold, full weight,
+message still deleted - since how long an account has existed says nothing
+about whether a specific message is dangerous. This is deliberate: the
+point is recognizing "this is just a very active regular," not granting
+immunity. An established account can still raid, spam, or get compromised,
+and will still be caught the moment it does anything content-wise, not
+just volume-wise.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glassframe-protocol",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "A layered, self-contained Discord security engine - AntiRaid, AntiNuke, Basic Security, and optional Groq-powered AI Moderation sharing one threat-scoring and punishment pipeline. Prefix commands only, Components V2 output, no slash commands.",
   "main": "dist/index.js",
   "files": [