@datafog/fogclaw 0.1.0

package/dist/index.js

@@ -0,0 +1,157 @@
+import { Scanner } from "./scanner.js";
+import { redact } from "./redactor.js";
+import { loadConfig } from "./config.js";
+export { Scanner } from "./scanner.js";
+export { redact } from "./redactor.js";
+export { loadConfig, DEFAULT_CONFIG } from "./config.js";
+/**
+ * OpenClaw plugin definition.
+ *
+ * Registers:
+ * - `before_agent_start` hook for automatic PII guardrail
+ * - `fogclaw_scan` tool for on-demand entity detection
+ * - `fogclaw_redact` tool for on-demand redaction
+ */
+const fogclaw = {
+    id: "fogclaw",
+    name: "FogClaw",
+    register(api) {
+        const rawConfig = api.pluginConfig ?? api.getConfig?.() ?? {};
+        const config = loadConfig(rawConfig);
+        if (!config.enabled) {
+            api.logger?.info("[fogclaw] Plugin disabled via config");
+            return;
+        }
+        const scanner = new Scanner(config);
+        // Initialize GLiNER in the background — regex works immediately,
+        // GLiNER becomes available once the model loads.
+        scanner.initialize().catch((err) => {
+            api.logger?.warn(`[fogclaw] GLiNER background init failed: ${String(err)}`);
+        });
+        // --- HOOK: Guardrail on incoming messages ---
+        api.on("before_agent_start", async (event) => {
+            const message = event.prompt ?? "";
+            if (!message)
+                return;
+            const result = await scanner.scan(message);
+            if (result.entities.length === 0)
+                return;
+            // Classify entities by their configured action
+            const blocked = [];
+            const warned = [];
+            const toRedact = [];
+            for (const entity of result.entities) {
+                const action = config.entityActions[entity.label] ?? config.guardrail_mode;
+                if (action === "block")
+                    blocked.push(entity);
+                else if (action === "warn")
+                    warned.push(entity);
+                else if (action === "redact")
+                    toRedact.push(entity);
+            }
+            const contextParts = [];
+            // "block" — inject a strong instruction to refuse
+            if (blocked.length > 0) {
+                const types = [...new Set(blocked.map((e) => e.label))].join(", ");
+                contextParts.push(`[FOGCLAW GUARDRAIL — BLOCKED] The user's message contains sensitive information (${types}). ` +
+                    `Do NOT process or repeat this information. Ask the user to rephrase without sensitive data.`);
+            }
+            // "warn" — inject a warning notice
+            if (warned.length > 0) {
+                const types = [...new Set(warned.map((e) => e.label))].join(", ");
+                contextParts.push(`[FOGCLAW NOTICE] PII detected in user message: ${types}. Handle with care.`);
+            }
+            // "redact" — replace PII with tokens
+            if (toRedact.length > 0) {
+                const redacted = redact(message, toRedact, config.redactStrategy);
+                contextParts.push(`[FOGCLAW REDACTED] The following is the user's message with PII redacted:\n${redacted.redacted_text}`);
+            }
+            if (contextParts.length > 0) {
+                return { prependContext: contextParts.join("\n\n") };
+            }
+        });
+        // --- TOOL: On-demand scan ---
+        api.registerTool({
+            name: "fogclaw_scan",
+            id: "fogclaw_scan",
+            description: "Scan text for PII and custom entities. Returns detected entities with types, positions, and confidence scores.",
+            schema: {
+                type: "object",
+                properties: {
+                    text: {
+                        type: "string",
+                        description: "Text to scan for entities",
+                    },
+                    custom_labels: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Additional entity labels for zero-shot detection (e.g., ['competitor name', 'project codename'])",
+                    },
+                },
+                required: ["text"],
+            },
+            handler: async ({ text, custom_labels, }) => {
+                const result = await scanner.scan(text, custom_labels);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                entities: result.entities,
+                                count: result.entities.length,
+                                summary: result.entities.length > 0
+                                    ? `Found ${result.entities.length} entities: ${[...new Set(result.entities.map((e) => e.label))].join(", ")}`
+                                    : "No entities detected",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            },
+        });
+        // --- TOOL: On-demand redact ---
+        api.registerTool({
+            name: "fogclaw_redact",
+            id: "fogclaw_redact",
+            description: "Scan and redact PII/custom entities from text. Returns sanitized text with entities replaced.",
+            schema: {
+                type: "object",
+                properties: {
+                    text: {
+                        type: "string",
+                        description: "Text to scan and redact",
+                    },
+                    strategy: {
+                        type: "string",
+                        description: 'Redaction strategy: "token" ([EMAIL_1]), "mask" (****), or "hash" ([EMAIL_a1b2c3...])',
+                        enum: ["token", "mask", "hash"],
+                    },
+                    custom_labels: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Additional entity labels for zero-shot detection",
+                    },
+                },
+                required: ["text"],
+            },
+            handler: async ({ text, strategy, custom_labels, }) => {
+                const result = await scanner.scan(text, custom_labels);
+                const redacted = redact(text, result.entities, strategy ?? config.redactStrategy);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                redacted_text: redacted.redacted_text,
+                                entities_found: result.entities.length,
+                                mapping: redacted.mapping,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            },
+        });
+        api.logger?.info(`[fogclaw] Plugin registered — guardrail: ${config.guardrail_mode}, model: ${config.model}, custom entities: ${config.custom_entities.length}`);
+    },
+};
+export default fogclaw;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/redactor.d.ts

@@ -0,0 +1,3 @@
+import type { Entity, RedactResult, RedactStrategy } from "./types.js";
+export declare function redact(text: string, entities: Entity[], strategy?: RedactStrategy): RedactResult;
+//# sourceMappingURL=redactor.d.ts.map

package/dist/redactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redactor.d.ts","sourceRoot":"","sources":["../src/redactor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEvE,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,GAAE,cAAwB,GACjC,YAAY,CAoBd"}

package/dist/redactor.js

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+export function redact(text, entities, strategy = "token") {
+    if (entities.length === 0) {
+        return { redacted_text: text, mapping: {}, entities: [] };
+    }
+    // Sort by start position descending so we replace from end to start
+    // without corrupting earlier offsets
+    const sorted = [...entities].sort((a, b) => b.start - a.start);
+    const counters = {};
+    const mapping = {};
+    let result = text;
+    for (const entity of sorted) {
+        const replacement = makeReplacement(entity, strategy, counters);
+        mapping[replacement] = entity.text;
+        result = result.slice(0, entity.start) + replacement + result.slice(entity.end);
+    }
+    return { redacted_text: result, mapping, entities };
+}
+function makeReplacement(entity, strategy, counters) {
+    switch (strategy) {
+        case "token": {
+            counters[entity.label] = (counters[entity.label] ?? 0) + 1;
+            return `[${entity.label}_${counters[entity.label]}]`;
+        }
+        case "mask": {
+            return "*".repeat(Math.max(entity.text.length, 1));
+        }
+        case "hash": {
+            const digest = createHash("sha256")
+                .update(entity.text)
+                .digest("hex")
+                .slice(0, 12);
+            return `[${entity.label}_${digest}]`;
+        }
+    }
+}
+//# sourceMappingURL=redactor.js.map

package/dist/redactor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redactor.js","sourceRoot":"","sources":["../src/redactor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,UAAU,MAAM,CACpB,IAAY,EACZ,QAAkB,EAClB,WAA2B,OAAO;IAElC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC5D,CAAC;IAED,oEAAoE;IACpE,qCAAqC;IACrC,MAAM,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAE/D,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,MAAM,GAAG,IAAI,CAAC;IAElB,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,WAAW,GAAG,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAChE,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;QACnC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClF,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtD,CAAC;AAED,SAAS,eAAe,CACtB,MAAc,EACd,QAAwB,EACxB,QAAgC;IAEhC,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC3D,OAAO,IAAI,MAAM,CAAC,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;QACvD,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;iBAChC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;iBACnB,MAAM,CAAC,KAAK,CAAC;iBACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAChB,OAAO,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,GAAG,CAAC;QACvC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/scanner.d.ts

@@ -0,0 +1,11 @@
+import type { FogClawConfig, ScanResult } from "./types.js";
+export declare class Scanner {
+    private regexEngine;
+    private glinerEngine;
+    private glinerAvailable;
+    private config;
+    constructor(config: FogClawConfig);
+    initialize(): Promise<void>;
+    scan(text: string, extraLabels?: string[]): Promise<ScanResult>;
+}
+//# sourceMappingURL=scanner.d.ts.map

package/dist/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAIpE,qBAAa,OAAO;IAClB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,aAAa;IAY3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;CAqBtE"}

package/dist/scanner.js

@@ -0,0 +1,77 @@
+import { RegexEngine } from "./engines/regex.js";
+import { GlinerEngine } from "./engines/gliner.js";
+export class Scanner {
+    regexEngine;
+    glinerEngine;
+    glinerAvailable = false;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.regexEngine = new RegexEngine();
+        this.glinerEngine = new GlinerEngine(config.model, config.confidence_threshold);
+        if (config.custom_entities.length > 0) {
+            this.glinerEngine.setCustomLabels(config.custom_entities);
+        }
+    }
+    async initialize() {
+        try {
+            await this.glinerEngine.initialize();
+            this.glinerAvailable = true;
+        }
+        catch (err) {
+            console.warn(`[fogclaw] GLiNER failed to initialize, falling back to regex-only mode: ${err instanceof Error ? err.message : String(err)}`);
+            this.glinerAvailable = false;
+        }
+    }
+    async scan(text, extraLabels) {
+        if (!text)
+            return { entities: [], text };
+        // Step 1: Regex pass (always runs, synchronous)
+        const regexEntities = this.regexEngine.scan(text);
+        // Step 2: GLiNER pass (if available)
+        let glinerEntities = [];
+        if (this.glinerAvailable) {
+            try {
+                glinerEntities = await this.glinerEngine.scan(text, extraLabels);
+            }
+            catch (err) {
+                console.warn(`[fogclaw] GLiNER scan failed, using regex results only: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Step 3: Merge and deduplicate
+        const merged = deduplicateEntities([...regexEntities, ...glinerEntities]);
+        return { entities: merged, text };
+    }
+}
+/**
+ * Remove overlapping entity spans. When two entities overlap,
+ * keep the one with higher confidence. If equal, prefer regex.
+ */
+function deduplicateEntities(entities) {
+    if (entities.length <= 1)
+        return entities;
+    // Sort by start position, then by confidence descending
+    const sorted = [...entities].sort((a, b) => {
+        if (a.start !== b.start)
+            return a.start - b.start;
+        return b.confidence - a.confidence;
+    });
+    const result = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        const current = sorted[i];
+        const last = result[result.length - 1];
+        // Check for overlap
+        if (current.start < last.end) {
+            // Overlapping: keep higher confidence (already in result if first)
+            if (current.confidence > last.confidence) {
+                result[result.length - 1] = current;
+            }
+            // Otherwise keep what's already in result
+        }
+        else {
+            result.push(current);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=scanner.js.map

package/dist/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+export interface Entity {
+    text: string;
+    label: string;
+    start: number;
+    end: number;
+    confidence: number;
+    source: "regex" | "gliner";
+}
+export type RedactStrategy = "token" | "mask" | "hash";
+export type GuardrailAction = "redact" | "block" | "warn";
+export interface FogClawConfig {
+    enabled: boolean;
+    guardrail_mode: GuardrailAction;
+    redactStrategy: RedactStrategy;
+    model: string;
+    confidence_threshold: number;
+    custom_entities: string[];
+    entityActions: Record<string, GuardrailAction>;
+}
+export interface ScanResult {
+    entities: Entity[];
+    text: string;
+}
+export interface RedactResult {
+    redacted_text: string;
+    mapping: Record<string, string>;
+    entities: Entity[];
+}
+export declare const CANONICAL_TYPE_MAP: Record<string, string>;
+export declare function canonicalType(entityType: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC5B;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,eAAe,CAAC;IAChC,cAAc,EAAE,cAAc,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAYrD,CAAC;AAEF,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/types.js

@@ -0,0 +1,18 @@
+export const CANONICAL_TYPE_MAP = {
+    DOB: "DATE",
+    ZIP: "ZIP_CODE",
+    PER: "PERSON",
+    ORG: "ORGANIZATION",
+    GPE: "LOCATION",
+    LOC: "LOCATION",
+    FAC: "ADDRESS",
+    PHONE_NUMBER: "PHONE",
+    SOCIAL_SECURITY_NUMBER: "SSN",
+    CREDIT_CARD_NUMBER: "CREDIT_CARD",
+    DATE_OF_BIRTH: "DATE",
+};
+export function canonicalType(entityType) {
+    const normalized = entityType.toUpperCase().trim();
+    return CANONICAL_TYPE_MAP[normalized] ?? normalized;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkCA,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,SAAS;IACd,YAAY,EAAE,OAAO;IACrB,sBAAsB,EAAE,KAAK;IAC7B,kBAAkB,EAAE,aAAa;IACjC,aAAa,EAAE,MAAM;CACtB,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IACnD,OAAO,kBAAkB,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC;AACtD,CAAC"}

package/docs/DATA.md

@@ -0,0 +1,28 @@
+---
+title: "Data"
+use_when: "Capturing data model and data-change safety rules for this repo (schemas, migrations, backfills, integrity, and operational safety)."
+---
+
+## Data Model
+
+- Source of truth for schemas (ORM models, migrations, schema dump files) and where they live.
+- Entity ownership boundaries (what owns IDs, who can write which tables/collections).
+
+## Migrations
+
+- Migration rules (forward-only vs reversible, locking/online migration expectations, index/constraint strategy).
+- Validation steps for schema changes (commands and what to check).
+
+## Backfills And Data Fixes
+
+- How to run backfills safely (idempotence, batching, checkpoints).
+- How to verify correctness and how to roll back (or compensate) if needed.
+
+## Integrity And Consistency
+
+- Constraints and invariants that must remain true (unique keys, foreign keys, referential rules).
+- Concurrency expectations (transactions/isolation, retry policies) where relevant.
+
+## Sensitive Data Notes
+
+- Pointers to where sensitive fields live and how they must be handled (logging/redaction, retention, deletion).

package/docs/DESIGN.md

@@ -0,0 +1,17 @@
+---
+title: "Design"
+use_when: "Documenting UI/UX design principles, visual direction, and interaction standards for this repo."
+---
+
+## Design Principles
+- Clarity over cleverness; make the primary action obvious.
+- Consistency beats novelty; reuse patterns unless there is a strong reason not to.
+- Accessible by default (contrast, focus, keyboard).
+
+## Visual Direction
+- Use design tokens (colors, spacing, typography) to keep the UI cohesive.
+- Prefer a small, intentional palette and a consistent type scale.
+
+## Interaction Standards
+- Every async action has loading, success, and error states with clear messaging.
+- Forms validate inline and preserve user input; errors explain how to recover.

package/docs/DOMAIN_DOCS.md

@@ -0,0 +1,30 @@
+# Domain Docs Registry
+
+Reference for agents: what domain docs exist, how to detect relevant content, and when to create or update them. Domain docs are deployed at bootstrap with baseline guidance. Flesh them out with real, repo-specific content on demand.
+
+## Domain Docs
+
+| Doc | Path | Purpose | Auto-Detect Signals | Seed Question |
+|---|---|---|---|---|
+| DESIGN.md | `docs/DESIGN.md` | Design principles, visual direction, interaction standards | — | What are your core design principles? |
+| DATA.md | `docs/DATA.md` | Data model and data-change safety rules (migrations/backfills/integrity) | `db/`, migrations, ORM schema files, backfill scripts | What are your data model and migration/backfill safety rules? |
+| FRONTEND.md | `docs/FRONTEND.md` | Frontend stack, conventions, component architecture | `package.json` (react/vue/angular/svelte), `next.config.*`, `vite.config.*`, `tsconfig.json` | What's your frontend stack and key conventions? |
+| PRODUCT_SENSE.md | `docs/PRODUCT_SENSE.md` | Target users, key outcomes, decision heuristics | — | Who are your target users and what outcomes matter most? |
+| RELIABILITY.md | `docs/RELIABILITY.md` | Uptime targets, failure modes, operational guardrails | Dockerfile, health check routes, CI config | What are your reliability requirements? |
+| SECURITY.md | `docs/SECURITY.md` | Threat model, auth, data sensitivity, compliance | Auth deps, middleware files, env var references | What security concerns apply? |
+| OBSERVABILITY.md | `docs/OBSERVABILITY.md` | Logging, metrics, traces, health checks, agent access | Logging libs (winston/pino/structlog/slog), `/metrics`, opentelemetry/jaeger config, `/healthz` | What observability tools do you use? |
+| core-beliefs.md | `docs/design-docs/core-beliefs.md` | Non-negotiable engineering beliefs | — | What are 2-3 non-negotiable engineering beliefs? |
+
+## When to Create or Update
+
+- **he-plan**: Identify relevant/missing domain docs during planning, then create/populate them at end-of-`he-plan` after final plan approval and before transition
+- **he-implement**: If implementation reveals a missing, wrong, or incomplete domain doc, create or update it in-place and note in Revision Notes
+- **he-learn**: Post-release policy updates from lessons learned
+- **he-doc-gardening**: Flag stale domain docs for refresh
+
+## How to Create or Update
+
+1. Check if the domain doc file exists (bootstrap deploys all baseline docs)
+2. If the doc has only baseline guidance (template defaults): replace with real, repo-specific content using auto-detect signals and current context
+3. If it has real content: append or revise — never overwrite working policies without replacing them with something better
+4. Preserve section structure (headings stay, content fills in)

package/docs/FRONTEND.md

@@ -0,0 +1,24 @@
+---
+title: "Frontend"
+use_when: "Documenting frontend stack, conventions, component architecture, performance budgets, and accessibility requirements for this repo."
+---
+
+## Stack
+- Define supported browsers/platforms and the minimum accessibility target.
+- Prefer a small set of core dependencies and consistent build tooling across the app.
+
+## Conventions
+- Keep components small and named by what they do; avoid "utils soup" without ownership.
+- Centralize shared UI primitives; avoid duplicating patterns across pages.
+
+## Component Architecture
+- Separate UI rendering from data fetching/mutations where practical.
+- Prefer explicit data flow and local state; introduce global state only with a clear boundary.
+
+## Performance
+- Avoid unnecessary client work: minimize re-renders, split code on route/feature boundaries, and lazy-load heavy modules.
+- Measure before optimizing; keep a short list of performance budgets that matter to users.
+
+## Accessibility
+- Keyboard navigation works for all interactive controls; focus states are visible.
+- Use semantic HTML first; ARIA is for filling gaps, not replacing semantics.

package/docs/OBSERVABILITY.md

@@ -0,0 +1,25 @@
+---
+title: "Observability"
+use_when: "Documenting logging, metrics, tracing, and health check conventions for this repo, including how agents can access signals to self-verify behavior."
+---
+
+## Logging Strategy
+- Prefer structured logs with consistent fields (service, env, request_id/trace_id, user_id when safe).
+- Never log secrets; be deliberate about PII.
+- Log at boundaries and on errors; avoid noisy per-loop logging in hot paths.
+
+## Metrics
+- Track the golden signals: latency, traffic, errors, saturation.
+- Prefer histograms for latency; keep label cardinality low.
+
+## Traces
+- Propagate trace context across service boundaries.
+- Trace the critical paths (requests, background jobs) with stable span names.
+
+## Health Checks
+- Health checks are fast and deterministic; readiness reflects dependency availability when needed.
+- Document expected status codes and what "unhealthy" means operationally.
+
+## Agent Access
+- Provide at least one concrete way to query each signal (logs, metrics, traces) without tribal knowledge.
+- Include 1-2 copy-pastable examples per signal once the stack is known (commands, URLs, or queries).