glassframe-protocol 1.2.0

package/dist/src/moderation/PunishmentEngine.js

@@ -0,0 +1,175 @@
+"use strict";
+
+const EventEmitter = require("events");
+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).
+const ACTION_SEVERITY = { log: 0, alert: 1, quarantine: 2, timeout: 2, kick: 3, ban: 4 };
+
+/**
+ * The only place in GlassFrame Protocol that actually punishes a member.
+ * Every layer feeds signals through ThreatEngine; this engine turns a tier
+ * into an action, but only after checking: is there already an open case
+ * for this member (don't re-punish or re-log mid-resolution), can the bot
+ * even act on them (RoleAnalyzer), and does their real trust level call for
+ * a softer landing (quarantine instead of ban) regardless of what the
+ * ladder alone would say.
+ */
+class PunishmentEngine extends EventEmitter {
+  constructor({ config, threatEngine, roleAnalyzer, logger, whitelist, queue, performance, debug = false }) {
+    super();
+    this.config = config.punishment;
+    this.threatEngine = threatEngine;
+    this.roleAnalyzer = roleAnalyzer;
+    this.logger = logger;
+    // 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
+    // limits. Falls back to running inline if no queue is supplied.
+    this.queue = queue || { push: (task) => task() };
+    this.performance = performance || { recordEvent() {}, time: () => () => {} };
+    // Accept the same Set the rest of GlassFrame uses (not a copy), so
+    // runtime whitelist edits (e.g. !gf whitelist add) apply immediately here too.
+    this.whitelist = whitelist instanceof Set ? whitelist : new Set(whitelist || []);
+    this.cases = new ProtocolCache("open-cases", { ttlMs: this.config.caseCooldownMs, debug });
+  }
+
+  caseKey(guildId, userId) {
+    return `${guildId}:${userId}`;
+  }
+
+  /**
+   * A layer reports a signal; this decides whether - and how - to act.
+   * { guild, member, layer, weight, reason }
+   */
+  async report({ guild, member, layer, weight, reason }) {
+    if (!member) return null;
+    const userId = member.id;
+    if (this.whitelist.has(userId)) return null;
+
+    const { score, tier } = this.threatEngine.addSignal(guild.id, userId, { layer, weight, reason });
+    if (tier === "none") return null;
+
+    const key = this.caseKey(guild.id, userId);
+    const openCase = this.cases.get(key);
+
+    if (openCase) {
+      // Already handling this member - merge in the new reason rather than
+      // opening a second incident. If continued behavior has pushed the
+      // tier past what the open case was actually acted on at, escalate
+      // once (log -> timeout -> kick -> ban); otherwise stay silent so this
+      // never turns into repeat actions or repeat log lines for one incident.
+      openCase.reasons.push(reason);
+      openCase.tier = tier;
+
+      const trust = this.roleAnalyzer.trustLevel(member);
+      const nextAction = this._decideAction(tier, trust);
+      if (ACTION_SEVERITY[nextAction] > ACTION_SEVERITY[openCase.action]) {
+        openCase.action = nextAction;
+        openCase.trust = trust;
+        this.cases.set(key, openCase);
+        await this._execute(guild, member, nextAction, openCase);
+        return openCase;
+      }
+
+      this.cases.set(key, openCase);
+      return openCase;
+    }
+
+    const trust = this.roleAnalyzer.trustLevel(member);
+    const action = this._decideAction(tier, trust);
+    const record = {
+      id: `${key}:${Date.now()}`,
+      guildId: guild.id,
+      userId,
+      tier,
+      score,
+      trust,
+      action,
+      reasons: [reason],
+      openedAt: Date.now()
+    };
+    this.cases.set(key, record);
+
+    await this._execute(guild, member, action, record);
+    return record;
+  }
+
+  _decideAction(tier, trust) {
+    if (trust === "PROTECTED") return "alert"; // never auto-punish the owner or protected staff
+    if (trust === "HIGH" && (tier === "low" || tier === "medium")) return "log"; // benefit of the doubt on soft signals
+    if (trust === "HIGH" || trust === "MEDIUM") return this.config.protectedTrustAction; // quarantine, not kick/ban
+    return this.config.ladder[tier] || "log";
+  }
+
+  async _execute(guild, member, action, record) {
+    const botMember = guild.members.me;
+    const canAct = this.roleAnalyzer.canModerate(botMember, member);
+    let performed = false;
+    const done = this.performance.time("punishmentEngine.execute");
+
+    try {
+      if (action === "ban" && canAct) {
+        await this.queue.push(() => member.ban({ reason: this._reason(record) }));
+        performed = true;
+      } else if (action === "kick" && canAct) {
+        await this.queue.push(() => member.kick(this._reason(record)));
+        performed = true;
+      } else if (action === "timeout" && canAct && member.moderatable) {
+        await this.queue.push(() => member.timeout(this.config.timeoutDurationMs, this._reason(record)));
+        performed = true;
+      } else if (action === "quarantine" && canAct) {
+        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;
+      }
+    } catch (err) {
+      record.error = err.message;
+    } finally {
+      done();
+    }
+
+    this.performance.recordEvent(`punishmentEngine.action.${action}`);
+
+    if (!performed && action !== "log" && action !== "alert" && !record.error) {
+      record.note = "GlassFrame lacks role hierarchy or Discord permission to act - logged for manual review only.";
+    }
+
+    await this.logger.log(guild, {
+      level: action === "alert" ? "alert" : action === "log" ? "info" : "warn",
+      title: this._title(action),
+      description: `${member.user.tag} (${member.id}) - tier **${record.tier}**, trust **${record.trust}**.`,
+      fields: [
+        { name: "Reasons", value: record.reasons.slice(-5).join("\n") },
+        { name: "Outcome", value: record.note || record.error || `action: ${action}` }
+      ],
+      dedupeKey: `punish:${action}:${guild.id}`
+    });
+
+    this.emit("case", record);
+  }
+
+  _reason(record) {
+    return `GlassFrame Protocol (${record.tier}): ${record.reasons.slice(-3).join("; ")}`;
+  }
+
+  _title(action) {
+    const map = {
+      ban: "Member Banned",
+      kick: "Member Kicked",
+      timeout: "Member Timed Out",
+      quarantine: "Member Quarantined",
+      alert: "Protected Member Flagged - Review Needed",
+      log: "Signal Logged"
+    };
+    return map[action] || "Action Taken";
+  }
+
+  clearCase(guildId, userId) {
+    this.cases.delete(this.caseKey(guildId, userId));
+  }
+}
+
+module.exports = PunishmentEngine;

package/dist/src/moderation/RoleAnalyzer.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const { PermissionsBitField } = require("discord.js");
+
+/**
+ * Reads a member's roles - their hierarchy position and their names - to
+ * decide what the protocol is allowed, and wise, to do about them. This is
+ * what keeps punishment "smart" instead of reflexive: it stops the bot from
+ * attempting actions it has no hierarchy for, and stops the protocol from
+ * auto-banning someone who turns out to hold a real administrator role.
+ */
+class RoleAnalyzer {
+  constructor(config) {
+    this.config = config.roleAnalysis;
+  }
+
+  /** Can the bot's member act on the target at all, permission + hierarchy-wise? */
+  canModerate(botMember, targetMember) {
+    if (!botMember || !targetMember) return false;
+    if (targetMember.id === targetMember.guild.ownerId) return false;
+    return targetMember.manageable;
+  }
+
+  /** LOW / MEDIUM / HIGH / PROTECTED, based on the member's real permissions and role names. */
+  trustLevel(member) {
+    if (!member) return "LOW";
+    if (member.id === member.guild.ownerId) return "PROTECTED";
+
+    const perms = member.permissions;
+    const hasDangerous = this.config.dangerousPermissions.some((p) => perms.has(PermissionsBitField.Flags[p]));
+    const hasTrust = this.config.trustPermissions.some((p) => perms.has(PermissionsBitField.Flags[p]));
+    const nameMatch = member.roles.cache.some((role) =>
+      this.config.protectedNames.some((n) => role.name.toLowerCase().includes(n))
+    );
+
+    if (hasDangerous && nameMatch) return "PROTECTED";
+    if (hasTrust) return "HIGH";
+    if (nameMatch) return "MEDIUM";
+    return "LOW";
+  }
+
+  /**
+   * Scans a guild's current roles for name/permission mismatches: a role
+   * whose name signals authority ("admin", "staff", ...) but carries no real
+   * permissions (impersonation bait), or the opposite - an innocuous-looking
+   * role that was just created and quietly holds dangerous permissions.
+   * Returns flags only, never actions; a human decides what to do with them.
+   */
+  scanRoles(guild) {
+    const flags = [];
+    const now = Date.now();
+
+    for (const role of guild.roles.cache.values()) {
+      if (role.id === guild.id) continue; // skip @everyone
+
+      const looksOfficial = this.config.protectedNames.some((n) => role.name.toLowerCase().includes(n));
+      const hasDangerousPerms = this.config.dangerousPermissions.some((p) =>
+        role.permissions.has(PermissionsBitField.Flags[p])
+      );
+      const age = now - role.createdTimestamp;
+
+      if (looksOfficial && !hasDangerousPerms) {
+        flags.push({
+          roleId: role.id,
+          name: role.name,
+          reason: "name suggests authority but the role has no real permissions (possible impersonation bait)"
+        });
+      }
+      if (!looksOfficial && hasDangerousPerms && age < this.config.newRoleGraceMs) {
+        flags.push({
+          roleId: role.id,
+          name: role.name,
+          reason: "newly created role quietly holds dangerous permissions"
+        });
+      }
+    }
+
+    return flags;
+  }
+}
+
+module.exports = RoleAnalyzer;

package/dist/src/security/PhishingDatabase.js

@@ -0,0 +1,71 @@
+"use strict";
+
+const HOMOGRAPH_DIGIT_MAP = { 0: "o", 1: "i", 3: "e", 4: "a", 5: "s", 7: "t" };
+const WATCHED_BRANDS = /(discord|steam|paypal|riot|valve|epicgames|roblox|nitro)/i;
+const SHORTENERS = new Set(["bit.ly", "tinyurl.com", "cutt.ly", "is.gd", "t.co", "shorturl.at", "rb.gy"]);
+
+/**
+ * Fast, expandable domain/pattern reputation checker used by
+ * BasicSecurityLayer. Ships with no seed list of "known bad" domains - a
+ * hardcoded blocklist goes stale immediately and risks flagging an innocent
+ * domain on stale/unverified information. Instead it combines a live,
+ * server-editable blocklist (`!gf phishing add/remove/list`) with cheap,
+ * general-purpose heuristics that don't depend on any specific domain ever
+ * being named in advance.
+ *
+ * Every check is O(1) Set membership plus a few cheap regexes - this is
+ * never the slow part of message handling, which is the point: link
+ * checking has to keep up with every message, not just the flagged ones.
+ */
+class PhishingDatabase {
+  constructor(seedDomains = []) {
+    this.blocked = new Set(seedDomains.map((d) => d.toLowerCase()));
+  }
+
+  add(domain) {
+    this.blocked.add(String(domain).toLowerCase());
+  }
+
+  remove(domain) {
+    return this.blocked.delete(String(domain).toLowerCase());
+  }
+
+  list() {
+    return [...this.blocked];
+  }
+
+  /** Returns a short reason string if a URL looks dangerous, otherwise null. */
+  check(url) {
+    let hostname;
+    try {
+      hostname = new URL(url).hostname.toLowerCase();
+    } catch {
+      return null;
+    }
+
+    if (this.blocked.has(hostname)) return "known malicious domain (server blocklist)";
+
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname)) return "raw-IP link (common phishing evasion)";
+    if (/xn--/.test(hostname)) return "punycode/homograph domain";
+
+    const flattened = hostname.replace(/\./g, "");
+    if (/[0-9]/.test(flattened)) {
+      const desubstituted = flattened.replace(/[0-9]/g, (d) => HOMOGRAPH_DIGIT_MAP[d] || d);
+      const match = desubstituted.match(WATCHED_BRANDS);
+      // Only flag if THIS specific brand word wasn't already plainly present
+      // before substitution - e.g. "paypal-secure5.com" already shows
+      // "paypal" outright, so the trailing digit isn't hiding anything and
+      // shouldn't trip this rule; "d1scord-nitro.com" only shows "discord"
+      // once the "1" is read back as an "i".
+      if (match && !flattened.includes(match[0])) {
+        return "brand look-alike domain (digit-for-letter substitution)";
+      }
+    }
+
+    if (SHORTENERS.has(hostname)) return "shortened link (real destination hidden)";
+
+    return null;
+  }
+}
+
+module.exports = PhishingDatabase;

package/dist/src/ui/ControlPanel.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const {
+  ContainerBuilder,
+  TextDisplayBuilder,
+  SeparatorBuilder,
+  SeparatorSpacingSize,
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  MessageFlags
+} = require("discord.js");
+
+// Exactly five buttons, one row - Discord's own per-row button limit is five,
+// so this is the only layout this panel could ever need.
+const BUTTONS = [
+  { id: "gfp_toggle_antiRaid", layer: "antiRaid", label: "AntiRaid" },
+  { id: "gfp_toggle_aiModeration", layer: "aiModeration", label: "AI Moderation" },
+  { id: "gfp_toggle_antiNuke", layer: "antiNuke", label: "AntiNuke" },
+  { id: "gfp_toggle_basicSecurity", layer: "basicSecurity", label: "Basic Security" },
+  { id: "gfp_toggle_all", layer: "__all__", label: "Full Protocol" }
+];
+
+const REAL_LAYERS = ["antiRaid", "aiModeration", "antiNuke", "basicSecurity"];
+
+function buildPanel(frame, guildId) {
+  const status = frame.getStatus(guildId);
+  const allOn = REAL_LAYERS.every((l) => status[l]);
+
+  const row = new ActionRowBuilder().addComponents(
+    BUTTONS.map((b) => {
+      const active = b.layer === "__all__" ? allOn : status[b.layer];
+      return new ButtonBuilder()
+        .setCustomId(b.id)
+        .setLabel(`${active ? "Deactivate" : "Activate"} ${b.label}`)
+        .setStyle(active ? ButtonStyle.Success : ButtonStyle.Secondary);
+    })
+  );
+
+  const statusLines = REAL_LAYERS.map((l) => {
+    const meta = BUTTONS.find((b) => b.layer === l);
+    return `${status[l] ? "\u25CF" : "\u25CB"} ${meta.label} - ${status[l] ? "ACTIVE" : "INACTIVE"}`;
+  }).join("\n");
+
+  const container = new ContainerBuilder().setAccentColor(0x5865f2);
+  container.addTextDisplayComponents(new TextDisplayBuilder().setContent("**GlassFrame Protocol - Control Panel**"));
+  container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+  container.addTextDisplayComponents(new TextDisplayBuilder().setContent(statusLines));
+  container.addSeparatorComponents(new SeparatorBuilder().setSpacing(SeparatorSpacingSize.Small));
+  container.addActionRowComponents(row);
+  container.addTextDisplayComponents(
+    new TextDisplayBuilder().setContent("-# Only server admins (Manage Server) can use these controls.")
+  );
+
+  return { flags: MessageFlags.IsComponentsV2, components: [container] };
+}
+
+module.exports = { buildPanel, BUTTONS };

package/dist/src/utils/nlpEngine.js

@@ -0,0 +1,149 @@
+"use strict";
+
+/**
+ * Lightweight, dependency-free NLP utilities used across GlassFrame
+ * Protocol. No external ML services are called from here; everything runs
+ * locally and synchronously so detection stays fast enough to run on every
+ * message and every join event. This is the free "first opinion" that
+ * AIModerationLayer's gray-zone escalation to Groq builds on top of.
+ */
+
+function tokenize(text) {
+  return String(text)
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function shannonEntropy(str) {
+  const s = String(str);
+  if (s.length === 0) return 0;
+  const freq = {};
+  for (const ch of s) freq[ch] = (freq[ch] || 0) + 1;
+  let entropy = 0;
+  for (const count of Object.values(freq)) {
+    const p = count / s.length;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+function normalizedRepeatRatio(str) {
+  const s = String(str);
+  if (s.length < 2) return 0;
+  let repeats = 0;
+  for (let i = 1; i < s.length; i++) {
+    if (s[i] === s[i - 1]) repeats++;
+  }
+  return repeats / (s.length - 1);
+}
+
+// Bag-of-words lexicon scorer. Returns a 0..1 confidence score using
+// term-frequency weighting rather than a single keyword hit, which cuts
+// down on false positives from one incidental word.
+function lexiconScore(text, lexicon) {
+  const tokens = tokenize(text);
+  if (tokens.length === 0) return 0;
+  let hits = 0;
+  let weight = 0;
+  for (const token of tokens) {
+    if (lexicon.strong && lexicon.strong.has(token)) {
+      hits++;
+      weight += 1.0;
+    } else if (lexicon.weak && lexicon.weak.has(token)) {
+      hits++;
+      weight += 0.4;
+    }
+  }
+  // Bigram check for multi-word patterns (e.g. "free nitro", "steam gift")
+  if (lexicon.bigrams) {
+    for (let i = 0; i < tokens.length - 1; i++) {
+      const bigram = tokens[i] + " " + tokens[i + 1];
+      if (lexicon.bigrams.has(bigram)) {
+        hits++;
+        weight += 1.2;
+      }
+    }
+  }
+  if (hits === 0) return 0;
+  const density = hits / tokens.length;
+  const score = Math.min(1, weight / Math.max(3, tokens.length) + density * 0.3);
+  return score;
+}
+
+const SCAM_LEXICON = {
+  strong: new Set([
+    "nitro", "airdrop", "giveaway", "steam", "crypto", "wallet",
+    "verify", "claim", "gift", "free", "double", "investment",
+    "seed", "phrase", "otp", "recover", "unlock"
+  ]),
+  weak: new Set([
+    "link", "click", "limited", "hurry", "winner", "congratulations",
+    "exclusive", "only", "today", "now"
+  ]),
+  bigrams: new Set([
+    "free nitro", "steam gift", "double your", "claim now",
+    "verify account", "wallet connect", "seed phrase", "limited time",
+    "click here", "airdrop event"
+  ])
+};
+
+const PHISHING_LEXICON = {
+  strong: new Set([
+    "login", "signin", "password", "confirm", "suspend", "suspended",
+    "locked", "support", "billing", "invoice", "reset", "update"
+  ]),
+  weak: new Set(["account", "security", "immediately", "action", "required", "team"]),
+  bigrams: new Set([
+    "sign in", "reset password", "confirm identity", "account suspended",
+    "verify now", "click below", "update payment"
+  ])
+};
+
+const RAID_CALLOUT_LEXICON = {
+  strong: new Set(["raid", "nuke", "spam", "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"])
+};
+
+function suspiciousUsernameEntropy(username, floor, ceiling) {
+  const cleaned = String(username).replace(/\s+/g, "");
+  if (cleaned.length < 3) return { suspicious: false, entropy: 0, reason: null };
+  const entropy = shannonEntropy(cleaned);
+  const repeatRatio = normalizedRepeatRatio(cleaned);
+
+  if (repeatRatio > 0.5) return { suspicious: true, entropy, reason: "repeated character pattern" };
+  if (entropy < floor) return { suspicious: true, entropy, reason: "low character variety" };
+  if (entropy > ceiling) return { suspicious: true, entropy, reason: "high-entropy generated string" };
+  return { suspicious: false, entropy, reason: null };
+}
+
+function classifyMessage(text) {
+  const scam = lexiconScore(text, SCAM_LEXICON);
+  const phishing = lexiconScore(text, PHISHING_LEXICON);
+  const raidCallout = lexiconScore(text, RAID_CALLOUT_LEXICON);
+  return {
+    scam,
+    phishing,
+    raidCallout,
+    topLabel: [
+      ["scam", scam],
+      ["phishing", phishing],
+      ["raid_callout", raidCallout]
+    ].sort((a, b) => b[1] - a[1])[0][0]
+  };
+}
+
+module.exports = {
+  tokenize,
+  shannonEntropy,
+  normalizedRepeatRatio,
+  lexiconScore,
+  suspiciousUsernameEntropy,
+  classifyMessage,
+  SCAM_LEXICON,
+  PHISHING_LEXICON,
+  RAID_CALLOUT_LEXICON
+};

package/docs/CACHE_ARCHITECTURE.md

@@ -0,0 +1,78 @@
+# Cache Architecture
+
+GlassFrame Protocol keeps all of its state in memory via one shared
+primitive, `ProtocolCache` (`src/core/Cache.js`), rather than scattering
+plain `Map`s through every layer. Every cache instance below is a
+`ProtocolCache`, and every one of them can be put into debug mode so you can
+watch it operate at runtime - see "Turning on cache logging" below.
+
+## Why a shared cache primitive
+
+- One place to reason about TTL, eviction, and stats instead of five
+  slightly-different `Map` patterns spread across layers.
+- Optional debug logging is a constructor flag, not something bolted on
+  per-module after the fact.
+- `getStats()` returns hits/misses/sets/evictions/size for any cache at
+  runtime, which is useful when you're tuning thresholds in `config.js` and
+  want to know whether a value is actually being reused.
+
+## Caches in use
+
+| Cache | Owner | Key shape | TTL | Purpose |
+|---|---|---|---|---|
+| `threat-scores` | `ThreatEngine` | `guildId:userId` | none (decay-based; pruned once decayed near zero) | The running, decaying risk score every layer contributes signals to. |
+| `open-cases` | `PunishmentEngine` | `guildId:userId` | `punishment.caseCooldownMs` (default 30s) | Prevents re-punishing or re-logging the same member while an incident is still fresh. Expiry length **is** the debounce window. |
+| `nuke-snapshots` | `AntiNukeLayer` | `guildId` | `antiNuke.snapshotTtlMs` (default 1h) | A lightweight forensic snapshot of role/channel names and positions, captured the instant a threshold trips, kept only for reference. |
+| `recent-webhooks` | `AntiNukeLayer` | webhook ID | `antiNuke.webhookAbuse.watchPeriodMs` (default 5m) | Maps a freshly created webhook back to whoever created it, so a message flood through that webhook (which carries no guild member of its own) can still be traced to an executor. |
+| `groq-verdicts` | `GroqClient` | hash of the first 500 characters of the message | `aiModeration.cacheTtlMs` (default 5m) | Stops a burst of identical/near-identical messages from each costing a fresh Groq call. |
+
+Two more `Map`s exist outside `ProtocolCache` because they're pure sliding
+windows with no need for hit/miss stats: `AntiRaidLayer.joinTimestamps` /
+`AntiRaidLayer.joinProfiles` (cluster correlation) and
+`AntiNukeLayer.actionLog` / `AntiNukeLayer.webhookMessageCounts`. All four
+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.
+
+Bounded-concurrency queues (`frame.actionQueue`, `frame.aiQueue`) and the
+internal metrics collector (`frame.performance`) are a separate concern from
+caching - see `docs/PERFORMANCE.md`.
+
+## Turning on cache logging
+
+Pass `debug: true` when constructing GlassFrame:
+
+```js
+const frame = new GlassFrame(client, {
+  getLogChannel: (guild) => guild.channels.cache.find((c) => c.name === "security-logs"),
+  debug: true
+});
+```
+
+(Equivalently, set `cache: { debug: true }` in `config.js` - the
+constructor option takes priority if both are set.)
+
+With debug mode on, every cache above prints a line like:
+
+```
+[GlassFrame:Cache:open-cases] SET 123456789012345678:987654321098765432
+[GlassFrame:Cache:groq-verdicts] HIT h482910335
+[GlassFrame:Cache:threat-scores] EXPIRE 123456789012345678:555555555555555555
+```
+
+`SmartLogger` has its own separate debug channel for the same flag
+(`[GlassFrame:SmartLogger] merge ...` / `final edit ...`), covering the
+event-aggregation behavior described in `docs/PROTOCOL_LAYERS.md`.
+
+This is meant for local debugging while you tune `config.js` - leave it off
+in production, since it writes to `console.log` on every cache operation and
+will get noisy fast on an active server.
+
+## Memory growth
+
+`threat-scores` is the only cache with no hard TTL, since a member's score
+needs to persist and decay rather than vanish at a fixed time.
+`ThreatEngine` prunes it every 10 minutes, removing any entry whose decayed
+score has fallen under 0.5 **and** hasn't been touched in at least four
+half-lives - by then it's noise, not signal. Every other cache either has a
+real TTL or is a self-trimming sliding window, so none of them grow
+unbounded over a long-running process.

package/docs/COMMANDS.md

@@ -0,0 +1,38 @@
+# Commands
+
+GlassFrame Protocol registers **no slash commands**. Every command is a
+prefix command (default prefix `!gf `, configurable via `config.prefix`),
+requires Manage Server permission (or being the guild owner), and is
+throttled per user per guild by `performance.commandCooldownMs` (default
+3s) - a repeated or accidental double-send is silently ignored rather than
+running twice or getting a "slow down" reply of its own.
+
+| Command | Does |
+|---|---|
+| `!gf panel` | Sends the 5-button control panel (see below). |
+| `!gf status` | Shows which of the four layers are currently active. |
+| `!gf scan` | Runs `RoleAnalyzer.scanRoles()` on demand and reports any role name/permission mismatches. |
+| `!gf metrics` | Shows queue depth, cache stats, and average latency - see `docs/PERFORMANCE.md`. |
+| `!gf phishing add <domain>` | Adds a domain to the link blocklist. |
+| `!gf phishing remove <domain>` | Removes a domain from the blocklist. |
+| `!gf phishing list` | Lists every blocked domain. |
+| `!gf whitelist add <userId>` | Exempts a user from all punitive action. |
+| `!gf whitelist remove <userId>` | Removes an exemption. |
+| `!gf help` | Lists these commands. |
+
+## The control panel
+
+`!gf panel` sends a message with exactly five buttons in one row:
+
+1. **Activate/Deactivate AntiRaid**
+2. **Activate/Deactivate AI Moderation**
+3. **Activate/Deactivate AntiNuke**
+4. **Activate/Deactivate Basic Security**
+5. **Activate/Deactivate Full Protocol** - arms or disarms all four at once
+
+Every layer starts disabled - nothing runs until it's explicitly activated,
+either from the panel or via `frame.enableLayer("antiRaid")` in code. Button
+labels flip between Activate/Deactivate based on current state, and the
+panel message updates in place on every click rather than posting a new
+message each time. Clicking a button also drops one aggregated log line in
+the security log channel noting who changed what.