@thelogicatelier/sylva 1.0.11 → 1.0.12

package/dist/awareness/detector.js

@@ -46,8 +46,16 @@ const CONFIDENCE_SCORES = {
 function detectStacks(signals) {
     const grouped = new Map();
     for (const signal of signals) {
-        // Skip tooling/entrypoint signals for stack detection
-        if (signal.kind === "tooling" || signal.kind === "entrypoint")
+        // Skip non-framework signals from stack detection
+        if (signal.kind === "tooling" ||
+            signal.kind === "entrypoint" ||
+            signal.kind === "agent" ||
+            signal.kind === "subagent" ||
+            signal.kind === "heartbeat" ||
+            signal.kind === "cron" ||
+            signal.kind === "hook" ||
+            signal.kind === "skill" ||
+            signal.kind === "plugin")
             continue;
         if (!grouped.has(signal.frameworkId)) {
             grouped.set(signal.frameworkId, []);

package/dist/awareness/index.js

@@ -50,7 +50,7 @@ const webGrounding_1 = require("./webGrounding");
  * The ARCHITECTURE CONSTRAINTS block injected into LLM context.
  * This is authoritative and must not be overridden by the model.
  */
-function buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator) {
+function buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator, signals) {
     const lines = [
         "=== ARCHITECTURE CONSTRAINTS (AUTHORITATIVE) ===",
         "1) The detected frameworks/stacks listed below are authoritative because they were derived from repository manifest/config files.",
@@ -78,9 +78,71 @@ function buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator) {
             lines.push(`    Evidence: ${ev.evidence.reason} [${ev.evidence.file}]`);
         }
     }
+    // OpenClaw-specific constraint sections (only when detected)
+    if (hasOrchestrator) {
+        appendOpenClawConstraints(lines, signals);
+    }
     lines.push("=== END ARCHITECTURE CONSTRAINTS ===");
     return lines.join("\n");
 }
+/**
+ * Append OpenClaw-specific sections to the constraints block.
+ * Groups signals by kind (agent, hook, skill, subagent, plugin, heartbeat).
+ */
+function appendOpenClawConstraints(lines, signals) {
+    // Agent config
+    const agentSignals = signals.filter((s) => s.kind === "agent");
+    if (agentSignals.length > 0) {
+        lines.push("", "OPENCLAW AGENT CONFIG:");
+        for (const sig of agentSignals) {
+            lines.push(`  - ${sig.frameworkName}: ${sig.evidence.excerpt}`);
+        }
+    }
+    // Hooks
+    const hookSignals = signals.filter((s) => s.kind === "hook");
+    if (hookSignals.length > 0) {
+        lines.push("", "OPENCLAW HOOKS:");
+        for (const sig of hookSignals) {
+            const name = sig.frameworkName.replace("OpenClaw Hook: ", "");
+            lines.push(`  - /${name}: ${sig.evidence.reason}`);
+        }
+    }
+    // Skills
+    const skillSignals = signals.filter((s) => s.kind === "skill");
+    if (skillSignals.length > 0) {
+        lines.push("", "OPENCLAW SKILLS:");
+        for (const sig of skillSignals) {
+            lines.push(`  - ${sig.frameworkName.replace("OpenClaw Skill: ", "")}: ${sig.evidence.reason}`);
+        }
+    }
+    // Subagents
+    const subagentSignals = signals.filter((s) => s.kind === "subagent");
+    if (subagentSignals.length > 0) {
+        lines.push("", "OPENCLAW SUBAGENTS:");
+        for (const sig of subagentSignals) {
+            lines.push(`  - ${sig.frameworkName.replace("OpenClaw Subagent: ", "")}: ${sig.evidence.reason}`);
+            if (sig.evidence.excerpt) {
+                lines.push(`    ${sig.evidence.excerpt}`);
+            }
+        }
+    }
+    // Plugins
+    const pluginSignals = signals.filter((s) => s.kind === "plugin");
+    if (pluginSignals.length > 0) {
+        lines.push("", "OPENCLAW PLUGINS:");
+        for (const sig of pluginSignals) {
+            lines.push(`  - ${sig.frameworkName.replace("OpenClaw Plugin: ", "")}: ${sig.evidence.excerpt}`);
+        }
+    }
+    // Heartbeat
+    const heartbeatSignals = signals.filter((s) => s.kind === "heartbeat");
+    if (heartbeatSignals.length > 0) {
+        lines.push("", "OPENCLAW HEARTBEAT:");
+        for (const sig of heartbeatSignals) {
+            lines.push(`  - ${sig.evidence.excerpt}`);
+        }
+    }
+}
 /**
  * Build the full awareness context string for LLM prompts.
  */
@@ -170,6 +232,65 @@ function saveAwarenessJson(repoName, result, baseDir = "projects") {
             `   Check disk space and directory write permissions if you need this output.`);
     }
 }
+/**
+ * Save grounding.json for web grounding transparency.
+ * Always saved — contains references + structured errors.
+ */
+function saveGroundingJson(repoName, webReferences, errors, baseDir = "projects") {
+    const folderName = repoName.toLowerCase().replace(/\s+/g, "-");
+    const targetDir = path.join(baseDir, folderName);
+    fs.mkdirSync(targetDir, { recursive: true });
+    const filePath = path.join(targetDir, "grounding.json");
+    try {
+        // Build structured error entries
+        const structuredErrors = errors.map((err) => {
+            // Parse known error patterns
+            if (err.includes("BRAVE_API_KEY not set")) {
+                return {
+                    reason: "BRAVE_API_KEY not set",
+                    impact: "Web grounding disabled — no documentation references gathered",
+                    resolution: "Set BRAVE_API_KEY in your .env file. Get a free key at https://brave.com/search/api/",
+                };
+            }
+            if (err.includes("rate limit") || err.includes("HTTP 429")) {
+                const queryMatch = err.match(/Query: "([^"]+)"/);
+                return {
+                    query: queryMatch ? queryMatch[1] : undefined,
+                    reason: "Brave Search API rate limit exceeded (HTTP 429)",
+                    impact: "Results missing for this query",
+                    resolution: "Wait a moment and retry, or check your Brave API plan limits",
+                };
+            }
+            if (err.includes("Web search failed")) {
+                const queryMatch = err.match(/for "([^"]+)"/);
+                const reasonMatch = err.match(/: (.+)$/);
+                return {
+                    query: queryMatch ? queryMatch[1] : undefined,
+                    reason: reasonMatch ? reasonMatch[1] : err,
+                    impact: "Results missing for this query",
+                };
+            }
+            return {
+                reason: err,
+                impact: "Unknown web grounding error",
+            };
+        });
+        const grounding = {
+            generatedAt: new Date().toISOString(),
+            totalReferences: webReferences.reduce((sum, ref) => sum + ref.results.length, 0),
+            frameworksCovered: webReferences.length,
+            references: webReferences,
+            errors: structuredErrors,
+        };
+        fs.writeFileSync(filePath, JSON.stringify(grounding, null, 2), "utf-8");
+        console.log(`✅ Saved grounding.json to: ${filePath}`);
+    }
+    catch (error) {
+        console.warn(`⚠️  Could not save grounding.json to ${filePath}: ${error.message}\n` +
+            `   This is a debug file and does not affect AGENTS.md generation.\n` +
+            `   Check disk space and directory write permissions if you need this output.`);
+    }
+}
 /**
  * Run the full awareness pipeline.
  * This is the main entry point called from the CLI.
@@ -210,9 +331,28 @@ async function runAwareness(repoPath, repoName) {
     }
     if (hasOrchestrator) {
         console.log("    🎯 OpenClaw orchestrator detected");
+        // Log OpenClaw-specific discoveries
+        const hookCount = signals.filter((s) => s.kind === "hook").length;
+        const skillCount = signals.filter((s) => s.kind === "skill").length;
+        const subagentCount = signals.filter((s) => s.kind === "subagent").length;
+        const pluginCount = signals.filter((s) => s.kind === "plugin").length;
+        if (hookCount > 0)
+            console.log(`    🪝 ${hookCount} hook(s) detected`);
+        if (skillCount > 0)
+            console.log(`    🎯 ${skillCount} skill(s) detected`);
+        if (subagentCount > 0)
+            console.log(`    🤖 ${subagentCount} subagent(s) detected`);
+        if (pluginCount > 0)
+            console.log(`    🔌 ${pluginCount} plugin(s) detected`);
+        const heartbeat = signals.find((s) => s.kind === "heartbeat");
+        if (heartbeat) {
+            const active = heartbeat.evidence.excerpt?.includes("ACTIVE") &&
+                !heartbeat.evidence.excerpt?.includes("INACTIVE");
+            console.log(`    💓 Heartbeat: ${active ? "ACTIVE" : "INACTIVE"}`);
+        }
     }
-    // Step 5: Build constraints block
-    const constraintsBlock = buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator);
+    // Step 5: Build constraints block (now includes OpenClaw-specific sections)
+    const constraintsBlock = buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator, signals);
     // Step 6: Web grounding
     console.log("  → Gathering web references...");
     const cacheDir = path.join("projects", repoName.toLowerCase().replace(/\s+/g, "-"), "cache", "brave");
@@ -254,6 +394,8 @@ async function runAwareness(repoPath, repoName) {
     };
     // Step 8: Save awareness.json
     saveAwarenessJson(repoName, result);
+    // Step 9: Save grounding.json (always, even on errors)
+    saveGroundingJson(repoName, webReferences, errors);
     console.log("✅ Framework Awareness scan complete\n");
     return result;
 }

package/dist/awareness/manifestParsers/openclawParser.d.ts

@@ -1,6 +1,20 @@
 /**
- * OpenClaw manifest parser.
- * Parses openclaw.json to extract orchestrator configuration.
+ * OpenClaw manifest parser — deep extraction.
+ * Parses openclaw.json / .openclaw.json to extract:
+ *   - Orchestrator signal with version from meta
+ *   - Agent config (models, workspace, concurrency)
+ *   - Hooks (internal event scripts with paths + descriptions)
+ *   - Plugins (enabled extensions)
+ *   - Gateway config (port, auth, denied commands)
+ *   - Channels (policies, stream modes)
+ *   - Tools (web search, fetch)
+ *   - Commands / messages config
+ *
+ * Also scans the OpenClaw workspace directory for:
+ *   - Skills (reusable .md workflows)
+ *   - Subagents (background agent directories)
+ *   - Workspace .md files (AGENTS.md, IDENTITY.md, HEARTBEAT.md, etc.)
+ *   - Hook scripts
  */
 import { Signal, ManifestFile } from "../types";
 export declare function parseOpenclawJson(manifest: ManifestFile): Signal[];

package/dist/awareness/manifestParsers/openclawParser.js

@@ -1,7 +1,21 @@
 "use strict";
 /**
- * OpenClaw manifest parser.
- * Parses openclaw.json to extract orchestrator configuration.
+ * OpenClaw manifest parser — deep extraction.
+ * Parses openclaw.json / .openclaw.json to extract:
+ *   - Orchestrator signal with version from meta
+ *   - Agent config (models, workspace, concurrency)
+ *   - Hooks (internal event scripts with paths + descriptions)
+ *   - Plugins (enabled extensions)
+ *   - Gateway config (port, auth, denied commands)
+ *   - Channels (policies, stream modes)
+ *   - Tools (web search, fetch)
+ *   - Commands / messages config
+ *
+ * Also scans the OpenClaw workspace directory for:
+ *   - Skills (reusable .md workflows)
+ *   - Subagents (background agent directories)
+ *   - Workspace .md files (AGENTS.md, IDENTITY.md, HEARTBEAT.md, etc.)
+ *   - Hook scripts
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -40,6 +54,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseOpenclawJson = parseOpenclawJson;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+// ---------------------
+// Deep JSON extraction
+// ---------------------
 function parseOpenclawJson(manifest) {
     const signals = [];
     const content = fs.readFileSync(manifest.absolutePath, "utf-8");
@@ -54,50 +71,546 @@ function parseOpenclawJson(manifest) {
         return signals;
     }
     const rootPath = path.dirname(manifest.relativePath) || ".";
-    // Primary orchestrator signal
+    // --- Extract OpenClaw version from meta ---
+    const meta = config.meta;
+    const openclawVersion = meta?.lastTouchedVersion
+        ? {
+            value: String(meta.lastTouchedVersion),
+            certainty: "exact",
+            sourceFile: manifest.relativePath,
+            notes: "From meta.lastTouchedVersion in openclaw.json",
+        }
+        : undefined;
+    // --- Primary orchestrator signal ---
     signals.push({
         kind: "orchestrator",
         frameworkId: "openclaw",
         frameworkName: "OpenClaw",
+        ...(openclawVersion ? { version: openclawVersion } : {}),
         evidence: {
             file: manifest.relativePath,
             reason: "openclaw.json configuration file found",
-            excerpt: content.length > 500 ? content.substring(0, 500) + "..." : content,
+            excerpt: openclawVersion
+                ? `OpenClaw version ${openclawVersion.value}`
+                : "OpenClaw orchestrator (version not specified in config)",
+        },
+        scope: { pathRoot: rootPath },
+    });
+    // --- Agent config ---
+    extractAgentConfig(config, manifest, rootPath, signals);
+    // --- Hooks ---
+    extractHooks(config, manifest, rootPath, signals);
+    // --- Plugins ---
+    extractPlugins(config, manifest, rootPath, signals);
+    // --- Gateway ---
+    extractGateway(config, manifest, rootPath, signals);
+    // --- Channels (expanded) ---
+    extractChannels(config, manifest, rootPath, signals);
+    // --- Tools (expanded) ---
+    extractTools(config, manifest, rootPath, signals);
+    // --- Commands + messages ---
+    extractCommandsAndMessages(config, manifest, rootPath, signals);
+    // --- Workspace scanning ---
+    scanWorkspace(config, manifest, rootPath, signals);
+    return signals;
+}
+// ---------------------
+// Section extractors
+// ---------------------
+function extractAgentConfig(config, manifest, rootPath, signals) {
+    const agents = config.agents;
+    if (!agents || typeof agents !== "object")
+        return;
+    const defaults = agents.defaults;
+    if (!defaults || typeof defaults !== "object")
+        return;
+    // Primary model
+    const model = defaults.model;
+    const primaryModel = model?.primary ? String(model.primary) : undefined;
+    // Available models
+    const models = defaults.models;
+    const modelCatalog = models ? Object.keys(models) : [];
+    // Workspace path
+    const workspace = defaults.workspace ? String(defaults.workspace) : undefined;
+    // Concurrency
+    const maxConcurrent = typeof defaults.maxConcurrent === "number" ? defaults.maxConcurrent : undefined;
+    const subagentConfig = defaults.subagents;
+    const subagentMaxConcurrent = subagentConfig && typeof subagentConfig.maxConcurrent === "number"
+        ? subagentConfig.maxConcurrent
+        : undefined;
+    // Compaction
+    const compaction = defaults.compaction;
+    const compactionMode = compaction?.mode ? String(compaction.mode) : undefined;
+    const details = [];
+    if (primaryModel)
+        details.push(`primary model: ${primaryModel}`);
+    if (modelCatalog.length > 0)
+        details.push(`${modelCatalog.length} model(s) available`);
+    if (workspace)
+        details.push(`workspace: ${workspace}`);
+    if (maxConcurrent)
+        details.push(`maxConcurrent: ${maxConcurrent}`);
+    if (subagentMaxConcurrent)
+        details.push(`subagent maxConcurrent: ${subagentMaxConcurrent}`);
+    if (compactionMode)
+        details.push(`compaction: ${compactionMode}`);
+    signals.push({
+        kind: "agent",
+        frameworkId: "openclaw-agent-config",
+        frameworkName: "OpenClaw Agent Config",
+        evidence: {
+            file: manifest.relativePath,
+            reason: "Agent configuration in openclaw.json",
+            excerpt: details.join("; "),
         },
         scope: { pathRoot: rootPath },
     });
-    // Extract tool signals
+    // Emit individual model entries for the LLM to know available models
+    if (modelCatalog.length > 0) {
+        signals.push({
+            kind: "agent",
+            frameworkId: "openclaw-model-catalog",
+            frameworkName: "OpenClaw Model Catalog",
+            evidence: {
+                file: manifest.relativePath,
+                reason: "Available LLM models configured in openclaw.json",
+                excerpt: modelCatalog.join(", "),
+            },
+            scope: { pathRoot: rootPath },
+        });
+    }
+}
+function extractHooks(config, manifest, rootPath, signals) {
+    const hooks = config.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return;
+    const internal = hooks.internal;
+    if (!internal || typeof internal !== "object")
+        return;
+    if (internal.enabled === false)
+        return;
+    const entries = internal.entries;
+    if (!entries || typeof entries !== "object")
+        return;
+    for (const [hookName, hookConfig] of Object.entries(entries)) {
+        if (!hookConfig || typeof hookConfig !== "object")
+            continue;
+        const enabled = hookConfig.enabled !== false; // default true
+        const hookPath = hookConfig.path ? String(hookConfig.path) : undefined;
+        const description = hookConfig.description ? String(hookConfig.description) : undefined;
+        const details = [`enabled: ${enabled}`];
+        if (hookPath)
+            details.push(`path: ${hookPath}`);
+        if (description)
+            details.push(`desc: ${description}`);
+        signals.push({
+            kind: "hook",
+            frameworkId: `openclaw-hook-${hookName}`,
+            frameworkName: `OpenClaw Hook: ${hookName}`,
+            evidence: {
+                file: manifest.relativePath,
+                reason: description || `Hook '${hookName}' configured in openclaw.json`,
+                excerpt: details.join("; "),
+            },
+            scope: { pathRoot: rootPath },
+        });
+    }
+}
+function extractPlugins(config, manifest, rootPath, signals) {
+    const plugins = config.plugins;
+    if (!plugins || typeof plugins !== "object")
+        return;
+    const entries = plugins.entries;
+    if (!entries || typeof entries !== "object")
+        return;
+    for (const [pluginName, pluginConfig] of Object.entries(entries)) {
+        if (!pluginConfig || typeof pluginConfig !== "object")
+            continue;
+        const enabled = pluginConfig.enabled !== false;
+        signals.push({
+            kind: "plugin",
+            frameworkId: `openclaw-plugin-${pluginName}`,
+            frameworkName: `OpenClaw Plugin: ${pluginName}`,
+            evidence: {
+                file: manifest.relativePath,
+                reason: `Plugin '${pluginName}' ${enabled ? "enabled" : "disabled"} in openclaw.json`,
+                excerpt: `enabled: ${enabled}`,
+            },
+            scope: { pathRoot: rootPath },
+        });
+    }
+}
+function extractGateway(config, manifest, rootPath, signals) {
+    const gateway = config.gateway;
+    if (!gateway || typeof gateway !== "object")
+        return;
+    const details = [];
+    if (gateway.port)
+        details.push(`port: ${gateway.port}`);
+    if (gateway.mode)
+        details.push(`mode: ${gateway.mode}`);
+    if (gateway.bind)
+        details.push(`bind: ${gateway.bind}`);
+    const auth = gateway.auth;
+    if (auth?.mode)
+        details.push(`auth: ${auth.mode}`);
+    const tailscale = gateway.tailscale;
+    if (tailscale?.mode)
+        details.push(`tailscale: ${tailscale.mode}`);
+    const nodes = gateway.nodes;
+    const denyCommands = nodes?.denyCommands;
+    if (denyCommands && Array.isArray(denyCommands)) {
+        details.push(`denied commands: ${denyCommands.join(", ")}`);
+    }
+    signals.push({
+        kind: "tooling",
+        frameworkId: "openclaw-gateway",
+        frameworkName: "OpenClaw Gateway",
+        evidence: {
+            file: manifest.relativePath,
+            reason: "Gateway configuration in openclaw.json",
+            excerpt: details.join("; "),
+        },
+        scope: { pathRoot: rootPath },
+    });
+}
+function extractChannels(config, manifest, rootPath, signals) {
+    const channels = config.channels;
+    if (!channels || typeof channels !== "object")
+        return;
+    for (const [channelName, channelConfig] of Object.entries(channels)) {
+        if (!channelConfig || typeof channelConfig !== "object")
+            continue;
+        const ch = channelConfig;
+        const details = [];
+        if (ch.enabled === false)
+            details.push("disabled");
+        if (ch.dmPolicy)
+            details.push(`dmPolicy: ${ch.dmPolicy}`);
+        if (ch.groupPolicy)
+            details.push(`groupPolicy: ${ch.groupPolicy}`);
+        if (ch.streamMode)
+            details.push(`streamMode: ${ch.streamMode}`);
+        if (ch.selfChatMode !== undefined)
+            details.push(`selfChat: ${ch.selfChatMode}`);
+        if (ch.debounceMs !== undefined)
+            details.push(`debounce: ${ch.debounceMs}ms`);
+        if (ch.mediaMaxMb)
+            details.push(`mediaMax: ${ch.mediaMaxMb}MB`);
+        signals.push({
+            kind: "tooling",
+            frameworkId: `openclaw-channel-${channelName}`,
+            frameworkName: `OpenClaw Channel: ${channelName}`,
+            evidence: {
+                file: manifest.relativePath,
+                reason: `Channel '${channelName}' configured in openclaw.json`,
+                excerpt: details.length > 0 ? details.join("; ") : `channel ${channelName} configured`,
+            },
+            scope: { pathRoot: rootPath },
+        });
+    }
+}
+function extractTools(config, manifest, rootPath, signals) {
     const tools = config.tools;
-    if (tools && typeof tools === "object") {
-        for (const [toolName, toolConfig] of Object.entries(tools)) {
+    if (!tools || typeof tools !== "object")
+        return;
+    for (const [toolName, toolConfig] of Object.entries(tools)) {
+        if (!toolConfig || typeof toolConfig !== "object")
+            continue;
+        // Build a summary of the tool's sub-capabilities
+        const subCapabilities = [];
+        for (const [subName, subConfig] of Object.entries(toolConfig)) {
+            if (subConfig && typeof subConfig === "object") {
+                const sc = subConfig;
+                const enabled = sc.enabled !== false;
+                subCapabilities.push(`${subName}: ${enabled ? "enabled" : "disabled"}`);
+            }
+        }
+        signals.push({
+            kind: "tooling",
+            frameworkId: `openclaw-tool-${toolName}`,
+            frameworkName: `OpenClaw Tool: ${toolName}`,
+            evidence: {
+                file: manifest.relativePath,
+                reason: `Tool '${toolName}' configured in openclaw.json`,
+                excerpt: subCapabilities.length > 0 ? subCapabilities.join("; ") : `tool ${toolName} configured`,
+            },
+            scope: { pathRoot: rootPath },
+        });
+    }
+}
+function extractCommandsAndMessages(config, manifest, rootPath, signals) {
+    const commands = config.commands;
+    if (commands && typeof commands === "object") {
+        const details = [];
+        if (commands.native)
+            details.push(`native: ${commands.native}`);
+        if (commands.nativeSkills)
+            details.push(`nativeSkills: ${commands.nativeSkills}`);
+        if (details.length > 0) {
             signals.push({
                 kind: "tooling",
-                frameworkId: `openclaw-tool-${toolName}`,
-                frameworkName: `OpenClaw Tool: ${toolName}`,
+                frameworkId: "openclaw-commands",
+                frameworkName: "OpenClaw Commands",
                 evidence: {
                     file: manifest.relativePath,
-                    reason: `Tool '${toolName}' configured in openclaw.json`,
-                    excerpt: JSON.stringify(toolConfig, null, 2).substring(0, 200),
+                    reason: "Command configuration in openclaw.json",
+                    excerpt: details.join("; "),
                 },
                 scope: { pathRoot: rootPath },
             });
         }
     }
-    // Extract channel signals
-    const channels = config.channels;
-    if (channels && typeof channels === "object") {
-        for (const [channelName] of Object.entries(channels)) {
+    const messages = config.messages;
+    if (messages && typeof messages === "object") {
+        const details = [];
+        if (messages.ackReactionScope)
+            details.push(`ackReactionScope: ${messages.ackReactionScope}`);
+        if (details.length > 0) {
             signals.push({
                 kind: "tooling",
-                frameworkId: `openclaw-channel-${channelName}`,
-                frameworkName: `OpenClaw Channel: ${channelName}`,
+                frameworkId: "openclaw-messages",
+                frameworkName: "OpenClaw Messages",
                 evidence: {
                     file: manifest.relativePath,
-                    reason: `Channel '${channelName}' configured in openclaw.json`,
+                    reason: "Message configuration in openclaw.json",
+                    excerpt: details.join("; "),
                 },
                 scope: { pathRoot: rootPath },
             });
         }
     }
-    return signals;
+}
+// ---------------------
+// Workspace scanner
+// ---------------------
+function scanWorkspace(config, manifest, rootPath, signals) {
+    // Resolve workspace directory:
+    // 1. From agents.defaults.workspace in config
+    // 2. Fallback to sibling "workspace/" directory relative to the config file
+    const agents = config.agents;
+    const defaults = agents?.defaults;
+    const configuredWorkspace = defaults?.workspace ? String(defaults.workspace) : undefined;
+    const configDir = path.dirname(manifest.absolutePath);
+    let workspaceDir;
+    if (configuredWorkspace) {
+        // Could be absolute or relative — try both
+        const candidate = path.isAbsolute(configuredWorkspace)
+            ? configuredWorkspace
+            : path.resolve(configDir, configuredWorkspace);
+        if (existsAndIsDir(candidate)) {
+            workspaceDir = candidate;
+        }
+    }
+    if (!workspaceDir) {
+        // Fallback: sibling "workspace/" directory
+        const fallback = path.join(configDir, "workspace");
+        if (existsAndIsDir(fallback)) {
+            workspaceDir = fallback;
+        }
+    }
+    if (!workspaceDir)
+        return;
+    const workspaceRel = path.relative(path.dirname(manifest.absolutePath), workspaceDir);
+    // Scan workspace .md files (identity layer)
+    scanWorkspaceMdFiles(workspaceDir, workspaceRel, manifest, rootPath, signals);
+    // Scan skills
+    scanSkills(workspaceDir, workspaceRel, manifest, rootPath, signals);
+    // Scan subagents
+    scanSubagents(workspaceDir, workspaceRel, manifest, rootPath, signals);
+}
+function scanWorkspaceMdFiles(workspaceDir, workspaceRel, manifest, rootPath, signals) {
+    const WORKSPACE_FILES = {
+        "AGENTS.md": "Agent behavioral instructions and skill routing",
+        "IDENTITY.md": "Agent identity, personality, and avatar",
+        "HEARTBEAT.md": "Periodic awareness checklist (cron-like proactive checks)",
+        "MEMORY.md": "Long-term curated memory store",
+        "SOUL.md": "Agent personality and core values",
+        "USER.md": "User profile and preferences",
+        "TOOLS.md": "Tool configuration and capabilities",
+        "OPTIMIZATION.md": "Performance and cost optimization rules",
+    };
+    for (const [filename, description] of Object.entries(WORKSPACE_FILES)) {
+        const filePath = path.join(workspaceDir, filename);
+        if (!existsAndIsFile(filePath))
+            continue;
+        // For HEARTBEAT.md, check if it has actual tasks (non-empty, non-comment content)
+        if (filename === "HEARTBEAT.md") {
+            const heartbeatContent = safeReadFile(filePath);
+            const hasActiveTasks = heartbeatContent
+                ? heartbeatContent.split("\n").some((line) => line.trim() && !line.trim().startsWith("#"))
+                : false;
+            signals.push({
+                kind: "heartbeat",
+                frameworkId: "openclaw-heartbeat",
+                frameworkName: "OpenClaw Heartbeat",
+                evidence: {
+                    file: path.join(workspaceRel, filename),
+                    reason: hasActiveTasks
+                        ? "HEARTBEAT.md found with active periodic tasks"
+                        : "HEARTBEAT.md found but no active tasks configured",
+                    excerpt: hasActiveTasks ? "Status: ACTIVE" : "Status: INACTIVE (empty/comments only)",
+                },
+                scope: { pathRoot: rootPath },
+            });
+            continue;
+        }
+        // For IDENTITY.md, extract the agent name if present
+        let excerpt = description;
+        if (filename === "IDENTITY.md") {
+            const identityContent = safeReadFile(filePath);
+            if (identityContent) {
+                const nameMatch = identityContent.match(/\*\*Name:\*\*\s*(.+)/);
+                if (nameMatch) {
+                    excerpt = `Agent name: ${nameMatch[1].trim()} — ${description}`;
+                }
+            }
+        }
+        signals.push({
+            kind: "agent",
+            frameworkId: `openclaw-workspace-${filename.replace(".md", "").toLowerCase()}`,
+            frameworkName: `OpenClaw Workspace: ${filename}`,
+            evidence: {
+                file: path.join(workspaceRel, filename),
+                reason: `Workspace file ${filename} found`,
+                excerpt,
+            },
+            scope: { pathRoot: rootPath },
+        });
+    }
+}
+function scanSkills(workspaceDir, workspaceRel, manifest, rootPath, signals) {
+    const skillsDir = path.join(workspaceDir, "skills");
+    if (!existsAndIsDir(skillsDir))
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".md"))
+            continue;
+        if (entry === "SKILL_INDEX.md")
+            continue; // Index file, not a skill itself
+        const skillPath = path.join(skillsDir, entry);
+        if (!existsAndIsFile(skillPath))
+            continue;
+        // Read first meaningful line for description
+        const content = safeReadFile(skillPath);
+        let description = `Skill workflow: ${entry.replace(".md", "")}`;
+        if (content) {
+            const lines = content.split("\n").filter((l) => l.trim());
+            const firstLine = lines[0] || "";
+            if (firstLine.startsWith("#")) {
+                description = firstLine.replace(/^#+\s*/, "").trim();
+            }
+        }
+        const skillName = entry
+            .replace(".md", "")
+            .replace(/-/g, " ")
+            .replace(/\b\w/g, (c) => c.toUpperCase());
+        signals.push({
+            kind: "skill",
+            frameworkId: `openclaw-skill-${entry.replace(".md", "")}`,
+            frameworkName: `OpenClaw Skill: ${skillName}`,
+            evidence: {
+                file: path.join(workspaceRel, "skills", entry),
+                reason: description,
+                excerpt: `Skill file: ${entry}`,
+            },
+            scope: { pathRoot: rootPath },
+        });
+    }
+}
+function scanSubagents(workspaceDir, workspaceRel, manifest, rootPath, signals) {
+    const subagentsDir = path.join(workspaceDir, "subagents");
+    if (!existsAndIsDir(subagentsDir))
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(subagentsDir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const entryPath = path.join(subagentsDir, entry);
+        if (!existsAndIsDir(entryPath))
+            continue;
+        // List files in the subagent directory
+        let subFiles;
+        try {
+            subFiles = fs.readdirSync(entryPath).filter((f) => {
+                const fp = path.join(entryPath, f);
+                try {
+                    return fs.statSync(fp).isFile() && !f.startsWith(".");
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        catch {
+            continue;
+        }
+        // Filter out __pycache__ etc
+        const meaningfulFiles = subFiles.filter((f) => !f.endsWith(".pyc") && f !== "__pycache__");
+        // Try to read protocol.md for description
+        let description = `Subagent: ${entry}`;
+        const protocolPath = path.join(entryPath, "protocol.md");
+        if (existsAndIsFile(protocolPath)) {
+            const content = safeReadFile(protocolPath);
+            if (content) {
+                const lines = content.split("\n").filter((l) => l.trim());
+                const firstLine = lines[0] || "";
+                if (firstLine.startsWith("#")) {
+                    description = firstLine.replace(/^#+\s*/, "").trim();
+                }
+            }
+        }
+        const subagentName = entry.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+        signals.push({
+            kind: "subagent",
+            frameworkId: `openclaw-subagent-${entry}`,
+            frameworkName: `OpenClaw Subagent: ${subagentName}`,
+            evidence: {
+                file: path.join(workspaceRel, "subagents", entry),
+                reason: description,
+                excerpt: meaningfulFiles.length > 0
+                    ? `Files: ${meaningfulFiles.join(", ")}`
+                    : "Empty subagent directory",
+            },
+            scope: { pathRoot: rootPath },
+        });
+    }
+}
+// ---------------------
+// Helpers
+// ---------------------
+function existsAndIsDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function existsAndIsFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function safeReadFile(p) {
+    try {
+        return fs.readFileSync(p, "utf-8");
+    }
+    catch {
+        return null;
+    }
 }

package/dist/awareness/types.d.ts

@@ -13,7 +13,7 @@ export interface VersionInfo {
     notes?: string;
 }
 /** Signal kinds emitted by manifest parsers */
-export type SignalKind = "framework" | "version" | "orchestrator" | "entrypoint" | "tooling";
+export type SignalKind = "framework" | "version" | "orchestrator" | "entrypoint" | "tooling" | "agent" | "subagent" | "heartbeat" | "cron" | "hook" | "skill" | "plugin";
 /** Evidence for a detected signal */
 export interface SignalEvidence {
     file: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thelogicatelier/sylva",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Auto-generate AGENTS.md for your repository using Ax-LLM. Analyze the structural backbone, data flow, and day-to-day coding conventions natively.",
   "main": "dist/index.js",
   "bin": {