@tpsdev-ai/flair 0.8.3 → 0.10.0

package/dist/resources/AdminInstance.js

@@ -1,15 +1,97 @@
 import { Resource } from "@harperfast/harper";
 import { layout, htmlResponse } from "./admin-layout.js";
-import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+/**
+ * Resolve the public URL operators reach this Flair on.
+ *
+ * Production deployments (Fabric, VPS-hosted, behind any reverse proxy)
+ * should set `FLAIR_PUBLIC_URL` in their launchd / systemd unit. The
+ * admin pane then shows the URL operators actually type — not the
+ * 127.0.0.1 binding address Harper sees internally — so the Endpoints
+ * table is copy-pasteable.
+ *
+ * Resolution order:
+ *   1. `FLAIR_PUBLIC_URL` env var (explicit override, always wins)
+ *   2. Request headers (X-Forwarded-Proto + X-Forwarded-Host, or Host)
+ *      — derives from how the operator actually reached the page
+ *   3. `http://127.0.0.1:${HTTP_PORT}` — local-only installs fallback
+ *
+ * The request-header path closes the common case from flair#404:
+ * remote/Fabric deployments without FLAIR_PUBLIC_URL set rendered
+ * localhost URLs that operators couldn't copy-paste. Trusting the Host
+ * header is correct when Harper terminates TLS directly; behind a
+ * reverse proxy that doesn't set X-Forwarded-* headers correctly, the
+ * operator should set FLAIR_PUBLIC_URL explicitly (which wins).
+ */
+function resolvePublicUrl(request) {
+    if (process.env.FLAIR_PUBLIC_URL) {
+        return process.env.FLAIR_PUBLIC_URL.replace(/\/$/, "");
+    }
+    // Best-effort header derivation. Harper's request.headers exposes
+    // both .get(name) and .asObject (case-insensitive). Prefer X-Forwarded-*
+    // when present (caller is behind a proxy that set them); fall back
+    // to the direct Host header.
+    const getHeader = (name) => {
+        const h = request?.headers;
+        if (!h)
+            return undefined;
+        if (typeof h.get === "function")
+            return h.get(name) ?? h.get(name.toLowerCase()) ?? undefined;
+        if (typeof h === "object") {
+            const obj = h.asObject ?? h;
+            return obj[name] ?? obj[name.toLowerCase()] ?? undefined;
+        }
+        return undefined;
+    };
+    const fwdProto = getHeader("X-Forwarded-Proto");
+    const fwdHost = getHeader("X-Forwarded-Host");
+    const host = fwdHost ?? getHeader("Host");
+    if (host && /^[\w.\-:]+$/.test(host)) {
+        const scheme = fwdProto && (fwdProto === "http" || fwdProto === "https") ? fwdProto : "https";
+        // If no proxy headers and host has no port, assume http for safety —
+        // most production deployments are behind a proxy with X-Forwarded-Proto.
+        const effectiveScheme = fwdProto ? scheme : (host.includes(":") ? "http" : scheme);
+        return `${effectiveScheme}://${host}`;
+    }
+    return `http://127.0.0.1:${process.env.HTTP_PORT ?? "19926"}`;
+}
+/**
+ * Read the runtime package version from the bundled package.json so the
+ * Instance pane shows the real version (e.g. 0.8.3) rather than "dev" —
+ * `process.env.npm_package_version` is only populated inside `npm run`.
+ */
+function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}
 /**
  * GET /AdminInstance — instance info, public key, version.
  */
 export class AdminInstance extends Resource {
     async get() {
-        const version = process.env.npm_package_version ?? "dev";
-        const httpPort = process.env.HTTP_PORT ?? "19926";
-        const publicUrl = process.env.FLAIR_PUBLIC_URL ?? `http://127.0.0.1:${httpPort}`;
+        const version = resolveVersion();
+        // Pass the request through so URL resolution can derive from
+        // X-Forwarded-* / Host headers when FLAIR_PUBLIC_URL isn't set.
+        const ctx = this.getContext?.() ?? {};
+        const request = ctx.request ?? ctx;
+        const publicUrl = resolvePublicUrl(request);
         // Try to read instance public key
         let publicKey = "—";
         const keyDir = join(homedir(), ".flair", "keys");

package/dist/resources/AdminMemory.js

@@ -41,10 +41,16 @@ export class AdminMemory extends Resource {
             if (subject) {
                 conditions.push({ attribute: "subject", comparator: "equals", value: subject.toLowerCase() });
             }
-            conditions.push({ attribute: "archived", comparator: "not_equal", value: true });
+            // Note: Harper's `not_equal true` predicate doesn't match rows where
+            // `archived` is `false` *or* unset — boolean comparators behave
+            // unevenly across boolean / undefined / null storage states. We skip
+            // archived rows in the JS-side filter loop below instead, so the list
+            // view actually returns non-archived memories rather than zero.
             const searchQuery = conditions.length > 0 ? { conditions } : {};
             let count = 0;
             for await (const m of databases.flair.Memory.search(searchQuery)) {
+                if (m.archived === true)
+                    continue;
                 if (m.expiresAt && Date.parse(m.expiresAt) < Date.now())
                     continue;
                 if (query && !String(m.content || "").toLowerCase().includes(query.toLowerCase()))

package/dist/resources/Federation.js

@@ -3,6 +3,8 @@ import { randomBytes } from "node:crypto";
 import nacl from "tweetnacl";
 import { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, createNonceStore, generateNonce, } from "./federation-crypto.js";
 import { initFederationCleanup } from "./federation-cleanup.js";
+import { classifyRecord } from "./federation-classify.js";
+export { classifyRecord } from "./federation-classify.js";
 // Module-level nonce store for federation anti-replay.
 // Shared across FederationPair + FederationSync — nonces are globally unique
 // (generated by signBodyFresh per request with 128-bit random nonces).
@@ -268,6 +270,12 @@ export class FederationSync extends Resource {
         const startTime = Date.now();
         let merged = 0;
         let skipped = 0;
+        const skippedReasons = {};
+        const mergeErrors = [];
+        function recordSkip(reason) {
+            skipped++;
+            skippedReasons[reason] = (skippedReasons[reason] ?? 0) + 1;
+        }
         // Table name → Harper database table mapping
         const tableMap = {
             Memory: databases.flair.Memory,
@@ -275,66 +283,88 @@ export class FederationSync extends Resource {
             Agent: databases.flair.Agent,
             Relationship: databases.flair.Relationship,
         };
+        const knownTables = new Set(Object.keys(tableMap));
         for (const record of records) {
-            const table = tableMap[record.table];
-            if (!table) {
-                skipped++;
-                continue;
-            }
-            // Originator enforcement: peers can only push records they originated.
-            // The hub can relay records from other peers (role === "hub"),
-            // but spokes can only push their own records.
-            const originator = record.originatorInstanceId ?? instanceId;
-            if (originator !== instanceId && peer.role !== "hub") {
-                skipped++;
-                continue;
-            }
             try {
-                const local = await table.get(record.id);
-                // Timestamp ceiling: reject records with updatedAt more than 5 minutes in the future.
-                // Prevents attackers from using far-future timestamps to permanently win LWW.
-                const fiveMinFromNow = new Date(Date.now() + 5 * 60 * 1000).toISOString();
-                if (record.updatedAt > fiveMinFromNow) {
-                    skipped++;
+                const table = tableMap[record.table];
+                const local = table ? await table.get(record.id) : null;
+                const decision = classifyRecord(record, peer.role, instanceId, local, knownTables);
+                if (decision.action === "skip") {
+                    recordSkip(decision.reason);
                     continue;
                 }
                 const mergedData = mergeRecord(local, record);
-                // Preserve originator for provenance
-                mergedData._originatorInstanceId = originator;
+                mergedData._originatorInstanceId = decision.originator;
                 mergedData._syncedFrom = instanceId;
                 mergedData._syncedAt = new Date().toISOString();
                 await table.put(mergedData);
                 merged++;
             }
-            catch {
-                skipped++;
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                recordSkip("merge_error");
+                // Cap the captured-error list so a hostile/buggy peer can't blow up
+                // the SyncLog row, but ALWAYS log to console so operators don't lose
+                // the per-record signal — the silent-swallow is the bug we're fixing.
+                if (mergeErrors.length < 10) {
+                    mergeErrors.push(`${record.table}/${record.id}: ${msg}`);
+                }
+                console.warn(`[Federation] merge error for ${record.table}/${record.id} from ${instanceId}: ${msg}`);
             }
         }
-        // Update peer sync cursor
-        await databases.flair.Peer.put({
+        // Peer cursor update — distinguish liveness from progress:
+        //   lastSyncAt → "we heard from this peer just now" (always update)
+        //   lastMergeAt → "data actually flowed in" (only when merged > 0)
+        // Conflating them produced the "green dashboard while burning" failure
+        // mode — dogfood pass 2026-05-26 surfaced unconditional update masking
+        // 100%-skip syncs.
+        const nowIso = new Date().toISOString();
+        const peerUpdate = {
             ...peer,
-            lastSyncAt: new Date().toISOString(),
-            lastSyncCursor: lamportClock?.toString() ?? new Date().toISOString(),
+            lastSyncAt: nowIso,
+            lastSyncCursor: lamportClock?.toString() ?? nowIso,
             status: "connected",
-            updatedAt: new Date().toISOString(),
-        });
-        // Log sync operation
+            updatedAt: nowIso,
+        };
+        if (merged > 0) {
+            peerUpdate.lastMergeAt = nowIso;
+        }
+        await databases.flair.Peer.put(peerUpdate);
+        // Log sync operation with skip-reason breakdown so the partial state
+        // is debuggable instead of a black box.
         try {
+            const errorParts = [];
+            if (Object.keys(skippedReasons).length > 0) {
+                errorParts.push("skipped: " +
+                    Object.entries(skippedReasons)
+                        .map(([reason, n]) => `${n} ${reason}`)
+                        .join(", "));
+            }
+            if (mergeErrors.length > 0) {
+                errorParts.push("merge_errors: " + mergeErrors.join("; "));
+            }
+            const errorSummary = errorParts.length > 0 ? errorParts.join(" | ") : undefined;
+            const status = mergeErrors.length > 0
+                ? "partial"
+                : skipped > 0 ? "partial" : "success";
             await databases.flair.SyncLog.put({
                 id: `sync_${Date.now()}_${randomBytes(4).toString("hex")}`,
                 peerId: instanceId,
                 direction: "pull",
                 recordCount: merged,
-                status: skipped > 0 ? "partial" : "success",
-                error: skipped > 0 ? `${skipped} records skipped` : undefined,
+                skippedCount: skipped,
+                skippedReasons: JSON.stringify(skippedReasons),
+                status,
+                error: errorSummary,
                 durationMs: Date.now() - startTime,
-                createdAt: new Date().toISOString(),
+                createdAt: nowIso,
             });
         }
         catch { /* non-fatal */ }
         return {
             merged,
             skipped,
+            skippedReasons,
             total: records.length,
             durationMs: Date.now() - startTime,
         };
@@ -354,6 +384,7 @@ export class FederationPeers extends Resource {
                     status: p.status,
                     endpoint: p.endpoint,
                     lastSyncAt: p.lastSyncAt,
+                    lastMergeAt: p.lastMergeAt,
                     relayOnly: p.relayOnly,
                     pairedAt: p.pairedAt,
                 });

package/dist/resources/MemoryMaintenance.js

@@ -1,34 +1,56 @@
 /**
  * MemoryMaintenance.ts — Maintenance worker for memory hygiene.
  *
- * POST /MemoryMaintenance/ — runs cleanup tasks:
+ * POST /MemoryMaintenance — runs cleanup tasks:
  *   1. Delete expired ephemeral memories (expiresAt < now)
  *   2. Archive old session memories (> 30 days, standard durability)
  *   3. Report stats
  *
- * Designed to run periodically (daily cron or heartbeat).
- * Requires admin auth.
+ * Designed to run periodically (daily cron, scheduler, or REM nightly cycle).
+ * Authenticated via Ed25519 (agent acts on own memories) or admin (system-wide).
+ *
+ * History: prior to slice-2 PR-3, this class used a static-ROUTE pattern
+ * (`export default class MemoryMaintenance` with `static ROUTE`/`METHOD`)
+ * that Harper 5.x does not auto-register. Both `flair rem light` and the
+ * REM nightly runner were returning "Not found" against the endpoint.
+ * Migrated to the standard `extends Resource` shape with `allowCreate()`
+ * to gate auth correctly.
  */
-export default class MemoryMaintenance {
-    static ROUTE = "MemoryMaintenance";
-    static METHOD = "POST";
+import { Resource, databases } from "@harperfast/harper";
+import { isAdmin } from "./auth-middleware.js";
+export class MemoryMaintenance extends Resource {
+    /** POST requires auth — either an agent acting on its own memories, or admin. */
+    allowCreate() {
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        return !!(request?.tpsAgent || request?.tpsAgentIsAdmin);
+    }
     async post(data) {
-        const { databases } = this;
-        const request = this.request;
-        const { dryRun = false, agentId } = data || {};
-        // Scope to authenticated agent. Admin can pass agentId for system-wide
-        // maintenance; non-admin always scoped to their own agent.
-        const authAgent = request?.headers?.get?.("x-tps-agent");
-        const isAdmin = request?.tpsAgentIsAdmin === true;
-        const targetAgent = isAdmin && agentId ? agentId : authAgent;
-        if (!targetAgent && !isAdmin) {
-            return { error: "agentId required" };
+        const { dryRun = false, agentId: bodyAgentId } = data || {};
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const actorId = request?.tpsAgent;
+        const callerIsAdmin = request?.tpsAgentIsAdmin === true
+            || (actorId ? await isAdmin(actorId) : false);
+        // Scope rules:
+        //   - Admin can pass agentId to maintain a specific agent (or omit it
+        //     for fleet-wide maintenance).
+        //   - Non-admin agents are scoped to their own memories — bodyAgentId
+        //     either matches the authenticated agent or is ignored.
+        const targetAgent = callerIsAdmin
+            ? bodyAgentId
+            : actorId;
+        if (!targetAgent && !callerIsAdmin) {
+            return new Response(JSON.stringify({ error: "agentId required" }), {
+                status: 400,
+                headers: { "content-type": "application/json" },
+            });
         }
         const now = new Date();
         const stats = { expired: 0, archived: 0, total: 0, errors: 0, agent: targetAgent || "all" };
         try {
             for await (const record of databases.flair.Memory.search()) {
-                // Skip records not belonging to target agent (unless admin running system-wide)
+                // Skip records not belonging to target agent (unless admin running fleet-wide).
                 if (targetAgent && record.agentId !== targetAgent)
                     continue;
                 stats.total++;
@@ -48,9 +70,9 @@ export default class MemoryMaintenance {
                     }
                     continue;
                 }
-                // 2. Archive old standard session memories (> 30 days)
-                // These are low-value session notes that weren't promoted to persistent.
-                // Archiving removes them from search results but keeps the data.
+                // 2. Archive old standard session memories (> 30 days). These are
+                // low-value session notes that weren't promoted to persistent.
+                // Soft-archive removes them from search results but keeps the data.
                 if (record.durability === "standard" &&
                     record.type === "session" &&
                     !record.archived &&
@@ -60,7 +82,6 @@ export default class MemoryMaintenance {
                     if (ageDays > 30) {
                         if (!dryRun) {
                             try {
-                                // Soft archive — set archived flag, keep data
                                 await databases.flair.Memory.update(record.id, {
                                     ...record,
                                     archived: true,
@@ -80,11 +101,18 @@ export default class MemoryMaintenance {
             }
         }
         catch (err) {
-            return { error: err.message, stats };
+            return new Response(JSON.stringify({ error: err.message, stats }), { status: 500, headers: { "content-type": "application/json" } });
         }
+        // Flatten the historical { stats } wrapper into the top level so callers
+        // can read `.expired` / `.archived` directly. The wrapper shape is kept
+        // for backward compatibility with `flair rem light`.
         return {
             message: dryRun ? "Dry run complete" : "Maintenance complete",
             stats,
+            expired: stats.expired,
+            archived: stats.archived,
+            total: stats.total,
+            errors: stats.errors,
         };
     }
 }

package/dist/resources/OAuth.js

@@ -36,6 +36,12 @@ function futureISO(ms) {
 }
 // ─── Discovery metadata ──────────────────────────────────────────────────────
 export class OAuthMetadata extends Resource {
+    // OAuth discovery metadata is intentionally public — RFC 8414 § 3 requires
+    // it be accessible without authentication so clients can bootstrap their
+    // flow. `allowRead() { return true }` opens Harper's role gate so remote
+    // operators (e.g. Fabric-hosted Flair) get the metadata document instead
+    // of a 401 from Harper's intrinsic auth layer. Same pattern as Health (#386).
+    allowRead() { return true; }
     async get() {
         const baseUrl = process.env.FLAIR_PUBLIC_URL || `http://127.0.0.1:${process.env.HTTP_PORT || 19926}`;
         return {
@@ -65,6 +71,10 @@ export class OAuthMetadata extends Resource {
 }
 // ─── Dynamic Client Registration (RFC 7591) ──────────────────────────────────
 export class OAuthRegister extends Resource {
+    // Dynamic Client Registration (RFC 7591) — clients must be able to register
+    // anonymously to bootstrap. Validation (redirect_uri allow-list, etc.)
+    // happens in post(). Pattern matches FederationPair.allowCreate (#299).
+    allowCreate() { return true; }
     async post(data) {
         const redirectUris = data?.redirect_uris ?? [];
         const clientName = data?.client_name ?? "Unknown Client";
@@ -103,6 +113,11 @@ export class OAuthRegister extends Resource {
 }
 // ─── Authorization endpoint ──────────────────────────────────────────────────
 export class OAuthAuthorize extends Resource {
+    // OAuth authorize endpoint must accept anonymous GET/POST — the whole
+    // point of authorize is to start an unauthenticated user's flow. PKCE
+    // and state-parameter validation in the handler enforce real auth.
+    allowRead() { return true; }
+    allowCreate() { return true; }
     async get() {
         // In 1.0, this returns a simple HTML consent page.
         // The user (Nathan) approves or denies, which POSTs back.
@@ -202,6 +217,10 @@ ${scope.split(" ").map((s) => `<div class="scope">${s}</div>`).join("")}
 }
 // ─── Token endpoint ──────────────────────────────────────────────────────────
 export class OAuthToken extends Resource {
+    // OAuth token exchange — client must hit this without prior Harper auth
+    // since they're trading code/refresh for a token. Authentication is in
+    // the post() handler via PKCE verifier + client_secret_basic.
+    allowCreate() { return true; }
     async post(data) {
         const grantType = data?.grant_type;
         if (grantType === "authorization_code") {
@@ -359,6 +378,9 @@ export class OAuthToken extends Resource {
 }
 // ─── Revocation endpoint ─────────────────────────────────────────────────────
 export class OAuthRevoke extends Resource {
+    // RFC 7009 — token revocation accepts the token itself as proof; clients
+    // may not have a separate auth credential. Handler validates the token.
+    allowCreate() { return true; }
     async post(data) {
         const token = data?.token;
         if (!token) {

package/dist/resources/ObservationCenter.js

@@ -10,6 +10,10 @@ const HTML = readFileSync(HTML_PATH, "utf8");
  * The HTML handles its own Basic-auth prompt and polls authenticated JSON endpoints.
  */
 export class ObservationCenter extends Resource {
+    // The dashboard shell is just HTML + inline JS; the JS prompts the user
+    // for admin-pass and authenticates each API call. The shell itself is
+    // intentionally public so it can render before auth happens.
+    allowRead() { return true; }
     async get() {
         return new Response(HTML, {
             status: 200,

package/dist/resources/SkillScan.js

@@ -1,101 +1,44 @@
 import { Resource } from "@harperfast/harper";
-const SHELL_PATTERNS = [
-    { regex: /\bexec\s*\(/, type: "shell_command" },
-    { regex: /\bspawn\s*\(/, type: "shell_command" },
-    { regex: /\bsystem\s*\(/, type: "shell_command" },
-    { regex: /`[^`]*`/, type: "shell_backtick" },
-    { regex: /\bchild_process\b/, type: "shell_command" },
-];
-const NETWORK_PATTERNS = [
-    { regex: /\bfetch\s*\(/, type: "network_call" },
-    { regex: /\bcurl\b/, type: "network_call" },
-    { regex: /https?:\/\//, type: "url_reference" },
-    { regex: /\bXMLHttpRequest\b/, type: "network_call" },
-    { regex: /\baxios\b/, type: "network_call" },
-];
-const FS_PATTERNS = [
-    { regex: /\bfs\.write/, type: "fs_write" },
-    { regex: /\bwriteFile/, type: "fs_write" },
-    { regex: />[>]?\s*[\/~]/, type: "fs_redirect" },
-];
-const ENV_PATTERNS = [
-    { regex: /\bprocess\.env\b/, type: "env_access" },
-    { regex: /\$ENV\b/, type: "env_access" },
-    { regex: /\$\{?\w+\}?/, type: "env_variable" },
-];
-const ENCODING_PATTERNS = [
-    { regex: /\batob\s*\(/, type: "base64_decode" },
-    { regex: /\bbtoa\s*\(/, type: "base64_encode" },
-    { regex: /Buffer\.from\s*\([^)]*,\s*['"]base64['"]/, type: "base64_decode" },
-    { regex: /Buffer\.from\s*\([^)]*,\s*['"]hex['"]/, type: "hex_decode" },
-    { regex: /\\x[0-9a-fA-F]{2}/, type: "hex_escape" },
-    { regex: /\\u200[b-f]|\\u2060|\\ufeff/, type: "zero_width_char" },
-];
-// Unicode zero-width and homoglyph detection (raw chars)
-const UNICODE_PATTERNS = [
-    { regex: /[\u200B-\u200F\u2060\uFEFF]/, type: "zero_width_char" },
-    { regex: /[\u0410-\u044F]/, type: "cyrillic_homoglyph" }, // Cyrillic chars that look like Latin
-];
-const ALL_PATTERNS = [
-    ...SHELL_PATTERNS,
-    ...NETWORK_PATTERNS,
-    ...FS_PATTERNS,
-    ...ENV_PATTERNS,
-    ...ENCODING_PATTERNS,
-    ...UNICODE_PATTERNS,
-];
-function assessRisk(violations) {
-    if (violations.length === 0)
-        return "low";
-    const types = new Set(violations.map((v) => v.type));
-    const hasShell = types.has("shell_command") || types.has("shell_backtick");
-    const hasNetwork = types.has("network_call");
-    const hasFs = types.has("fs_write") || types.has("fs_redirect");
-    const hasZeroWidth = types.has("zero_width_char");
-    const hasHomoglyph = types.has("cyrillic_homoglyph");
-    // Critical: shell + encoding, or zero-width/homoglyph obfuscation
-    if ((hasShell && (types.has("base64_decode") || types.has("hex_decode"))) ||
-        hasZeroWidth || hasHomoglyph) {
-        return "critical";
-    }
-    // High: direct shell commands or fs writes
-    if (hasShell || hasFs)
-        return "high";
-    // Medium: network calls or encoding without shell
-    if (hasNetwork || types.has("base64_decode") || types.has("hex_decode"))
-        return "medium";
-    return "low";
-}
+import { scanSkillContent } from "./scan/skill-scanner.js";
+/**
+ * POST /SkillScan/
+ *
+ * Static analysis of skill content for security violations.
+ * Scans for shell commands, network calls, fs writes, env access,
+ * encoded payloads, zero-width chars, and homoglyphs.
+ *
+ * Request:  { content: string }
+ * Response: { safe, violations, riskLevel }
+ *
+ * Auth: any authenticated agent (read-only analysis).
+ * Size limit: 8KB (8192 bytes).
+ *
+ * Scanner logic lives in `./scan/skill-scanner.ts` (pure module, no Harper
+ * runtime deps) so unit tests can exercise it without instantiating the
+ * Harper database.
+ *
+ * Markdown awareness:
+ *  - Inline `single-token` backticks (markdown identifier convention) are NOT
+ *    flagged. Only inline backticks whose content actually looks shell-ish
+ *    (whitespace, pipe, semicolon, env-var, $(), &&, ||) fire shell_backtick.
+ *  - Fenced ```code blocks``` with no language hint or a shell-family
+ *    language (sh|bash|shell|zsh) are scanned for shell patterns. Non-shell
+ *    language hints (json, yaml, ts, py, graphql, etc.) skip the shell
+ *    patterns but keep network/fs/encoding/unicode detection active — those
+ *    are language-agnostic attack surfaces.
+ *  - This prevents the documentation-as-skill false-positive class without
+ *    weakening detection on actual shell content.
+ */
 export class SkillScan extends Resource {
-    async post(data, context) {
+    async post(data, _context) {
         const { content } = data || {};
         if (!content || typeof content !== "string") {
             return new Response(JSON.stringify({ error: "content (string) required" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
-        // 8KB size limit
         const byteLength = new TextEncoder().encode(content).length;
         if (byteLength > 8192) {
             return new Response(JSON.stringify({ error: `Content exceeds 8KB limit (${byteLength} bytes)` }), { status: 413, headers: { "Content-Type": "application/json" } });
         }
-        const lines = content.split("\n");
-        const violations = [];
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i];
-            for (const pattern of ALL_PATTERNS) {
-                if (pattern.regex.test(line)) {
-                    violations.push({
-                        type: pattern.type,
-                        line: i + 1,
-                        content: line.trim().slice(0, 200),
-                    });
-                }
-            }
-        }
-        const riskLevel = assessRisk(violations);
-        return {
-            safe: violations.length === 0,
-            violations,
-            riskLevel,
-        };
+        return scanSkillContent(content);
     }
 }

package/dist/resources/admin-layout.js

@@ -2,7 +2,31 @@
  * Shared HTML layout for the Flair web admin.
  * Server-rendered, no JS framework. Minimal CSS for Nathan-grade UX.
  */
-const VERSION = process.env.npm_package_version ?? "dev";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// Resolve the runtime package version from package.json — process.env.npm_package_version
+// is only populated inside `npm run`, so it returned "dev" in production and rendered
+// "vdev" in the admin sidebar footer for anyone running the published binary.
+function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}
+const VERSION = resolveVersion();
 /** Escape HTML special characters to prevent stored XSS. */
 export function esc(str) {
     if (!str)