@thelogicatelier/sylva 1.0.4 → 1.0.10

package/README.md

@@ -80,9 +80,29 @@ npx @thelogicatelier/sylva --local-repository . -m openai/gpt-5.2 -i 25
 
 For detailed guidance, see the [Choosing the Right Model](https://achatt89.github.io/sylva/models/choosing.html) and [Iteration Depth Guide](https://achatt89.github.io/sylva/models/iterations.html) docs.
 
+### Framework Awareness (NEW)
+
+Sylva now includes **deterministic framework detection** that scans the entire repository (including nested subprojects and monorepos) for manifest files before invoking the LLM. This prevents framework hallucination and produces more accurate `AGENTS.md` output.
+
+**What it detects:**
+- **OpenClaw** (`openclaw.json`) — treated as the primary orchestrator
+- **Node.js/JS/TS** — React, Angular, Vue, Next.js, Express, NestJS, etc. from `package.json`
+- **Python** — Django, Flask, FastAPI from `requirements.txt`, `pyproject.toml`, `Pipfile`
+- **Java/JVM** — Spring Boot, Quarkus from `pom.xml`, `build.gradle`
+- **.NET** — ASP.NET Core from `*.csproj`, `global.json`
+- **Go** — Gin, Echo, Fiber from `go.mod`
+- **Rust** — Actix, Axum, Tokio from `Cargo.toml`
+
+**Version certainty:** Versions are only reported when explicitly found in manifest/lockfiles. Never assumed.
+
+**Web grounding:** When `BRAVE_API_KEY` is set, Sylva fetches official docs for detected frameworks (version-specific when exact versions are known, latest fallback otherwise).
+
+**Debug output:** `awareness.json` is saved alongside `AGENTS.md` for full transparency.
+
 ### Environment Overrides
 - `AUTOSKILL_MODEL`: Set this to `gemini` or `anthropic` or `openai` to change the default execution provider globally without providing `-m` on every execution.
 - `GITHUB_REPO_URL`: Hardcode a repository for the CLI parser to utilize if no explicit configuration flags are provided.
+- `BRAVE_API_KEY`: Set this to enable web-grounded framework documentation retrieval via Brave Search. If not set, Sylva will still detect frameworks deterministically but will skip web reference gathering.
 
 ### Test Structure
 Unit tests are located at `tests/` which mirror the `/src` folder structure separating logical test groupings.

package/dist/awareness/braveSearch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Brave Search API client with caching.
+ * Uses BRAVE_API_KEY env var. Gracefully degrades if missing.
+ */
+import { WebSearchResult } from "./types";
+interface BraveSearchOptions {
+    cacheDir?: string;
+}
+/**
+ * Search Brave API for a query. Returns parsed results.
+ * Caches results to disk if cacheDir is provided.
+ */
+export declare function braveSearch(query: string, options?: BraveSearchOptions): Promise<WebSearchResult[]>;
+/**
+ * Check if Brave Search is available (API key set).
+ */
+export declare function isBraveSearchAvailable(): boolean;
+export {};

package/dist/awareness/braveSearch.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Brave Search API client with caching.
+ * Uses BRAVE_API_KEY env var. Gracefully degrades if missing.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.braveSearch = braveSearch;
+exports.isBraveSearchAvailable = isBraveSearchAvailable;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const BRAVE_SEARCH_URL = "https://api.search.brave.com/res/v1/web/search";
+/**
+ * Generate a cache key from query parameters.
+ */
+function cacheKey(query) {
+    return crypto.createHash("md5").update(query).digest("hex");
+}
+/**
+ * Search Brave API for a query. Returns parsed results.
+ * Caches results to disk if cacheDir is provided.
+ */
+async function braveSearch(query, options) {
+    const apiKey = process.env.BRAVE_API_KEY;
+    if (!apiKey) {
+        // Graceful degradation — detection still works, only web references are skipped
+        return [];
+    }
+    // Check cache first
+    if (options?.cacheDir) {
+        const cachedFile = path.join(options.cacheDir, `${cacheKey(query)}.json`);
+        if (fs.existsSync(cachedFile)) {
+            try {
+                const cached = JSON.parse(fs.readFileSync(cachedFile, "utf-8"));
+                return cached;
+            }
+            catch {
+                // Invalid cache, continue with search
+            }
+        }
+    }
+    try {
+        const url = `${BRAVE_SEARCH_URL}?q=${encodeURIComponent(query)}&count=5`;
+        const response = await fetch(url, {
+            headers: {
+                Accept: "application/json",
+                "Accept-Encoding": "gzip",
+                "X-Subscription-Token": apiKey,
+            },
+        });
+        if (!response.ok) {
+            const statusText = response.statusText || "Unknown error";
+            if (response.status === 401 || response.status === 403) {
+                console.warn(`❌ Brave Search API authentication failed (HTTP ${response.status}: ${statusText}).\n` +
+                    `   Your BRAVE_API_KEY may be invalid or expired.\n` +
+                    `   Get a valid key at: https://brave.com/search/api/\n` +
+                    `   Framework detection still works — only web doc references are affected.`);
+            }
+            else if (response.status === 429) {
+                console.warn(`⚠️  Brave Search API rate limit exceeded (HTTP 429).\n` +
+                    `   Query: "${query}"\n` +
+                    `   Wait a moment and retry, or check your Brave API plan limits.`);
+            }
+            else {
+                console.warn(`⚠️  Brave Search API returned HTTP ${response.status} (${statusText}) for query: "${query}"`);
+            }
+            return [];
+        }
+        const data = (await response.json());
+        const webResults = data.web?.results || [];
+        const results = webResults.slice(0, 5).map((r) => ({
+            title: r.title || "",
+            url: r.url || "",
+            snippet: r.description || "",
+        }));
+        // Write to cache
+        if (options?.cacheDir) {
+            fs.mkdirSync(options.cacheDir, { recursive: true });
+            const cachedFile = path.join(options.cacheDir, `${cacheKey(query)}.json`);
+            fs.writeFileSync(cachedFile, JSON.stringify(results, null, 2), "utf-8");
+        }
+        return results;
+    }
+    catch (error) {
+        const errMsg = error.message;
+        if (errMsg.includes("fetch") || errMsg.includes("ENOTFOUND") || errMsg.includes("network")) {
+            console.warn(`⚠️  Brave Search network error for query "${query}": ${errMsg}\n` +
+                `   Check your internet connection. Framework detection is unaffected.`);
+        }
+        else {
+            console.warn(`⚠️  Brave Search failed for query "${query}": ${errMsg}`);
+        }
+        return [];
+    }
+}
+/**
+ * Check if Brave Search is available (API key set).
+ */
+function isBraveSearchAvailable() {
+    return !!process.env.BRAVE_API_KEY;
+}

package/dist/awareness/detector.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Stack detector and architecture model builder.
+ * Deterministic — no LLM involvement.
+ */
+import { Signal, StackInfo, ArchitectureModel, VersionInfo } from "./types";
+/**
+ * Detect stacks from signals.
+ * Groups signals by frameworkId and scores confidence.
+ */
+export declare function detectStacks(signals: Signal[]): StackInfo[];
+/**
+ * Detect architecture model from stacks and signals.
+ */
+export declare function detectArchitecture(stacks: StackInfo[], signals: Signal[]): ArchitectureModel;
+/**
+ * Format a VersionInfo for display in AGENTS.md
+ */
+export declare function formatVersionForDisplay(frameworkName: string, version: VersionInfo): string;

package/dist/awareness/detector.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Stack detector and architecture model builder.
+ * Deterministic — no LLM involvement.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectStacks = detectStacks;
+exports.detectArchitecture = detectArchitecture;
+exports.formatVersionForDisplay = formatVersionForDisplay;
+const versionResolver_1 = require("./versionResolver");
+/** Confidence scoring rules */
+const CONFIDENCE_SCORES = {
+    orchestrator: 95,
+    angular: 85,
+    react: 80,
+    nextjs: 85,
+    vue: 80,
+    nuxt: 85,
+    svelte: 80,
+    sveltekit: 85,
+    express: 75,
+    nestjs: 85,
+    fastify: 75,
+    django: 85,
+    flask: 75,
+    fastapi: 80,
+    "spring-boot": 90,
+    spring: 80,
+    "java-maven": 70,
+    "java-gradle": 70,
+    dotnet: 80,
+    "aspnet-core": 85,
+    go: 80,
+    rust: 80,
+    "actix-web": 85,
+    axum: 85,
+    nodejs: 60,
+    python: 60,
+    typescript: 65,
+    docker: 50,
+};
+/**
+ * Detect stacks from signals.
+ * Groups signals by frameworkId and scores confidence.
+ */
+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")
+            continue;
+        if (!grouped.has(signal.frameworkId)) {
+            grouped.set(signal.frameworkId, []);
+        }
+        grouped.get(signal.frameworkId).push(signal);
+    }
+    const stacks = [];
+    for (const [frameworkId, frameworkSignals] of grouped) {
+        const frameworkName = frameworkSignals[0].frameworkName;
+        const confidence = CONFIDENCE_SCORES[frameworkId] || 50;
+        const version = (0, versionResolver_1.resolveVersion)(frameworkSignals);
+        // Determine rootPath — use the shallowest signal's scope
+        const rootPaths = frameworkSignals.map((s) => s.scope.pathRoot).filter(Boolean);
+        const rootPath = rootPaths.length > 0 ? rootPaths.sort((a, b) => a.length - b.length)[0] : undefined;
+        stacks.push({
+            frameworkId,
+            frameworkName,
+            confidence,
+            versions: version.certainty !== "unknown" || version.value ? [version] : [],
+            evidence: frameworkSignals,
+            rootPath,
+        });
+    }
+    // Sort by confidence descending
+    stacks.sort((a, b) => b.confidence - a.confidence);
+    return stacks;
+}
+/**
+ * Detect architecture model from stacks and signals.
+ */
+function detectArchitecture(stacks, signals) {
+    // Find orchestrator
+    const orchestratorSignals = signals.filter((s) => s.kind === "orchestrator");
+    let primaryOrchestrator;
+    if (orchestratorSignals.length > 0) {
+        const orcSignal = orchestratorSignals[0];
+        primaryOrchestrator = {
+            id: orcSignal.frameworkId,
+            configPath: orcSignal.evidence.file,
+            details: {
+                excerpt: orcSignal.evidence.excerpt,
+            },
+        };
+    }
+    // Build workloads — group stacks by rootPath
+    const rootPathGroups = new Map();
+    for (const stack of stacks) {
+        const root = stack.rootPath || ".";
+        if (!rootPathGroups.has(root)) {
+            rootPathGroups.set(root, []);
+        }
+        rootPathGroups.get(root).push(stack);
+    }
+    const workloads = [];
+    for (const [rootPath, groupStacks] of rootPathGroups) {
+        // Collect entrypoints from signals
+        const entrypoints = signals
+            .filter((s) => s.kind === "entrypoint" &&
+            (s.scope.pathRoot === rootPath || (!s.scope.pathRoot && rootPath === ".")))
+            .map((s) => s.evidence.excerpt || s.evidence.reason);
+        // Collect build tools
+        const buildTools = signals
+            .filter((s) => s.kind === "tooling" &&
+            (s.scope.pathRoot === rootPath || (!s.scope.pathRoot && rootPath === ".")))
+            .map((s) => s.frameworkName);
+        workloads.push({
+            id: rootPath.replace(/[^a-zA-Z0-9]/g, "-"),
+            name: rootPath === "." ? "Root Project" : rootPath,
+            rootPath,
+            frameworks: groupStacks.map((s) => s.frameworkName),
+            entrypoints,
+            buildTools,
+            evidence: groupStacks.flatMap((s) => s.evidence.map((e) => e.evidence)),
+        });
+    }
+    // Determine repo type
+    const uniqueRoots = [...rootPathGroups.keys()].filter((r) => r !== ".");
+    let repoType;
+    if (uniqueRoots.length >= 2) {
+        repoType = "monorepo";
+    }
+    else if (uniqueRoots.length === 1 && rootPathGroups.has(".")) {
+        repoType = "monorepo";
+    }
+    else if (uniqueRoots.length === 0) {
+        repoType = "single";
+    }
+    else {
+        repoType = "single";
+    }
+    // Build navigation guidance
+    const whatToReadFirst = [];
+    const whereThingsLive = [];
+    if (primaryOrchestrator) {
+        whatToReadFirst.push(`OpenClaw config: ${primaryOrchestrator.configPath}`);
+    }
+    for (const workload of workloads) {
+        if (workload.frameworks.length > 0) {
+            whereThingsLive.push(`${workload.name}: ${workload.frameworks.join(", ")} (at ${workload.rootPath})`);
+        }
+        if (workload.entrypoints.length > 0) {
+            whatToReadFirst.push(`${workload.name} entrypoints: ${workload.entrypoints.slice(0, 3).join("; ")}`);
+        }
+    }
+    return {
+        primaryOrchestrator,
+        workloads,
+        repoType,
+        navigation: {
+            whatToReadFirst,
+            whereThingsLive,
+        },
+    };
+}
+/**
+ * Format a VersionInfo for display in AGENTS.md
+ */
+function formatVersionForDisplay(frameworkName, version) {
+    if (version.certainty === "exact" && version.value) {
+        return `${frameworkName}: ${version.value} (exact; ${version.sourceFile || "manifest"})`;
+    }
+    if (version.certainty === "ambiguous" && version.value) {
+        return `${frameworkName}: ~${version.value} (ambiguous; ${version.notes || "range without lockfile resolution"})`;
+    }
+    return `${frameworkName}: unknown (no explicit version found)`;
+}

package/dist/awareness/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Awareness orchestrator.
+ * Top-level function that runs the entire awareness pipeline:
+ * scan → parse → resolve versions → detect stacks → web ground → build constraints.
+ */
+import { AwarenessResult } from "./types";
+/**
+ * Run the full awareness pipeline.
+ * This is the main entry point called from the CLI.
+ */
+export declare function runAwareness(repoPath: string, repoName: string): Promise<AwarenessResult>;

package/dist/awareness/index.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Awareness orchestrator.
+ * Top-level function that runs the entire awareness pipeline:
+ * scan → parse → resolve versions → detect stacks → web ground → build constraints.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAwareness = runAwareness;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const manifestScanner_1 = require("./manifestScanner");
+const manifestParsers_1 = require("./manifestParsers");
+const versionResolver_1 = require("./versionResolver");
+const detector_1 = require("./detector");
+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) {
+    const lines = [
+        "=== ARCHITECTURE CONSTRAINTS (AUTHORITATIVE) ===",
+        "1) The detected frameworks/stacks listed below are authoritative because they were derived from repository manifest/config files.",
+        "2) You MUST NOT invent additional frameworks, build systems, languages, entrypoints, or tooling not present in the evidence.",
+        '3) If evidence is missing or ambiguous, say "unknown" or "ambiguous" and provide safe navigation guidance rather than guessing.',
+        "4) Versions:",
+        "   - Only state a version if it is explicitly detected from manifests/locks.",
+        "   - If version is unknown/ambiguous, state that clearly.",
+        "   - If you cite docs, choose versioned docs when exact version is known; otherwise use latest docs and label as fallback.",
+    ];
+    if (hasOrchestrator) {
+        lines.push("5) OpenClaw:", "   - If openclaw.json exists anywhere in the repo, treat OpenClaw as the orchestrator and structure AGENTS.md accordingly (OpenClaw Runtime + workloads).");
+    }
+    lines.push("", "DETECTED STACKS:");
+    for (const stack of stacks) {
+        const version = resolvedVersions.get(stack.frameworkId);
+        if (version) {
+            lines.push(`  - ${(0, detector_1.formatVersionForDisplay)(stack.frameworkName, version)}`);
+        }
+        else {
+            lines.push(`  - ${stack.frameworkName}: detected (confidence: ${stack.confidence}%)`);
+        }
+        // Add evidence summary
+        for (const ev of stack.evidence.slice(0, 2)) {
+            lines.push(`    Evidence: ${ev.evidence.reason} [${ev.evidence.file}]`);
+        }
+    }
+    lines.push("=== END ARCHITECTURE CONSTRAINTS ===");
+    return lines.join("\n");
+}
+/**
+ * Build the full awareness context string for LLM prompts.
+ */
+function buildAwarenessContext(result) {
+    const parts = [];
+    // Constraints block
+    parts.push(result.constraintsBlock);
+    parts.push("");
+    // Architecture summary
+    const arch = result.architecture;
+    parts.push("ARCHITECTURE SUMMARY:");
+    parts.push(`  Repo type: ${arch.repoType}`);
+    if (arch.primaryOrchestrator) {
+        parts.push(`  Primary orchestrator: ${arch.primaryOrchestrator.id} (config: ${arch.primaryOrchestrator.configPath})`);
+    }
+    if (arch.workloads.length > 0) {
+        parts.push("  Workloads:");
+        for (const w of arch.workloads) {
+            parts.push(`    - ${w.name} (${w.rootPath}): ${w.frameworks.join(", ")}`);
+        }
+    }
+    if (arch.navigation.whatToReadFirst.length > 0) {
+        parts.push("  What to read first:");
+        for (const item of arch.navigation.whatToReadFirst) {
+            parts.push(`    - ${item}`);
+        }
+    }
+    // Web references summary
+    if (result.webReferences.length > 0) {
+        parts.push("");
+        parts.push("FRAMEWORK REFERENCES:");
+        for (const ref of result.webReferences) {
+            const mode = ref.referenceMode === "versioned"
+                ? `Docs selected for version ${ref.versionInfo.value} (exact)`
+                : "Version unknown/ambiguous; using latest docs fallback";
+            parts.push(`  ${ref.frameworkName}: ${mode}`);
+            for (const r of ref.results.slice(0, 3)) {
+                parts.push(`    - ${r.title}: ${r.url}`);
+            }
+        }
+    }
+    else if (result.errors.length > 0) {
+        parts.push("");
+        parts.push("FRAMEWORK REFERENCES: Unavailable");
+        for (const err of result.errors) {
+            parts.push(`  - ${err}`);
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Save awareness.json for debugging/transparency.
+ */
+function saveAwarenessJson(repoName, result, 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, "awareness.json");
+    try {
+        // Serialize without circular references — remove evidence signals' circular refs
+        const serializable = {
+            manifests: result.manifests,
+            stacks: result.stacks.map((s) => ({
+                frameworkId: s.frameworkId,
+                frameworkName: s.frameworkName,
+                confidence: s.confidence,
+                versions: s.versions,
+                rootPath: s.rootPath,
+                evidenceCount: s.evidence.length,
+                evidenceSummary: s.evidence.slice(0, 3).map((e) => ({
+                    kind: e.kind,
+                    file: e.evidence.file,
+                    reason: e.evidence.reason,
+                })),
+            })),
+            architecture: result.architecture,
+            webReferences: result.webReferences,
+            errors: result.errors,
+            constraintsBlock: result.constraintsBlock,
+        };
+        fs.writeFileSync(filePath, JSON.stringify(serializable, null, 2), "utf-8");
+        console.log(`✅ Saved awareness.json to: ${filePath}`);
+    }
+    catch (error) {
+        console.warn(`⚠️  Could not save awareness.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.
+ */
+async function runAwareness(repoPath, repoName) {
+    console.log("\n🔍 Running Framework Awareness scan...");
+    // Step 1: Scan for manifests (full-repo)
+    console.log("  → Scanning repository for manifest files...");
+    const manifests = (0, manifestScanner_1.scanManifests)(repoPath);
+    console.log(`  → Found ${manifests.length} manifest file(s)`);
+    if (manifests.length > 0) {
+        for (const m of manifests.slice(0, 10)) {
+            console.log(`    📄 ${m.relativePath} (depth: ${m.depth})`);
+        }
+        if (manifests.length > 10) {
+            console.log(`    ... and ${manifests.length - 10} more`);
+        }
+    }
+    // Step 2: Parse all manifests into signals
+    console.log("  → Parsing manifests...");
+    const signals = (0, manifestParsers_1.parseAllManifests)(manifests);
+    console.log(`  → Generated ${signals.length} signal(s)`);
+    // Step 3: Resolve versions
+    console.log("  → Resolving versions...");
+    const resolvedVersions = (0, versionResolver_1.resolveAllVersions)(signals);
+    // Step 4: Detect stacks and architecture
+    console.log("  → Detecting stacks and architecture...");
+    const stacks = (0, detector_1.detectStacks)(signals);
+    const architecture = (0, detector_1.detectArchitecture)(stacks, signals);
+    const hasOrchestrator = signals.some((s) => s.kind === "orchestrator");
+    console.log(`  → Detected ${stacks.length} stack(s), repo type: ${architecture.repoType}`);
+    for (const stack of stacks.slice(0, 8)) {
+        const version = resolvedVersions.get(stack.frameworkId);
+        const versionStr = version?.value
+            ? ` v${version.value} (${version.certainty})`
+            : ` (version ${version?.certainty || "unknown"})`;
+        console.log(`    🏗️  ${stack.frameworkName}${versionStr} [confidence: ${stack.confidence}%]`);
+    }
+    if (hasOrchestrator) {
+        console.log("    🎯 OpenClaw orchestrator detected");
+    }
+    // Step 5: Build constraints block
+    const constraintsBlock = buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator);
+    // Step 6: Web grounding
+    console.log("  → Gathering web references...");
+    const cacheDir = path.join("projects", repoName.toLowerCase().replace(/\s+/g, "-"), "cache", "brave");
+    const { references: webReferences, errors } = await (0, webGrounding_1.gatherReferences)(stacks, 3, cacheDir);
+    if (webReferences.length > 0) {
+        console.log(`  → Retrieved references for ${webReferences.length} framework(s)`);
+        for (const ref of webReferences) {
+            const mode = ref.referenceMode === "versioned"
+                ? `v${ref.versionInfo.value} docs`
+                : "latest docs (fallback)";
+            console.log(`    📚 ${ref.frameworkName}: ${ref.results.length} reference(s) [${mode}]`);
+        }
+    }
+    if (errors.length > 0) {
+        for (const err of errors) {
+            // Multi-line errors — indent subsequent lines
+            const lines = err.split("\n");
+            console.log(`  ⚠️  ${lines[0]}`);
+            for (const line of lines.slice(1)) {
+                console.log(`     ${line}`);
+            }
+        }
+    }
+    // Build partial result (without awarenessContext yet)
+    const partialResult = {
+        manifests,
+        signals,
+        stacks,
+        architecture,
+        webReferences,
+        constraintsBlock,
+        errors,
+    };
+    // Step 7: Build awareness context
+    const awarenessContext = buildAwarenessContext(partialResult);
+    const result = {
+        ...partialResult,
+        awarenessContext,
+    };
+    // Step 8: Save awareness.json
+    saveAwarenessJson(repoName, result);
+    console.log("✅ Framework Awareness scan complete\n");
+    return result;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * .NET manifest parsers.
+ * Handles *.csproj files and global.json.
+ */
+import { Signal, ManifestFile } from "../types";
+/**
+ * Parse a .csproj file (MSBuild XML format)
+ */
+export declare function parseCsproj(manifest: ManifestFile): Signal[];
+/**
+ * Parse global.json (.NET SDK version pinning)
+ */
+export declare function parseGlobalJson(manifest: ManifestFile): Signal[];