docorbit 0.1.0 → 0.1.1

package/dist/packages/core/src/dashboard/server.js

@@ -0,0 +1,267 @@
+import http from 'node:http';
+import { URL } from 'node:url';
+import { ExportService } from "../../../export/src/index.js";
+import { VerificationService, DiffService, ImpactAnalysisService, } from "../../../verification/src/index.js";
+import { renderDashboardHtml } from "./ui.js";
+export class DashboardServer {
+    repo;
+    projectDir;
+    dbPath;
+    exportService;
+    verificationService;
+    diffService;
+    impactService;
+    server = null;
+    constructor(options) {
+        this.repo = options.repo;
+        this.projectDir = options.projectDir;
+        this.dbPath = options.dbPath || '.docorbit/docorbit.db';
+        this.exportService = new ExportService(this.repo);
+        this.verificationService = new VerificationService(this.repo);
+        this.diffService = new DiffService(this.repo);
+        this.impactService = new ImpactAnalysisService(this.repo);
+    }
+    /**
+     * Starts the local dashboard HTTP server.
+     */
+    start(port = 3737, host = '127.0.0.1') {
+        return new Promise((resolve, reject) => {
+            this.server = http.createServer(async (req, res) => {
+                try {
+                    await this.handleRequest(req, res);
+                }
+                catch (err) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: err.message || 'Internal Server Error' }));
+                }
+            });
+            this.server.on('error', (err) => {
+                reject(err);
+            });
+            this.server.listen(port, host, () => {
+                const address = this.server.address();
+                const actualPort = address.port;
+                const url = `http://${host}:${actualPort}/`;
+                resolve({ server: this.server, url, port: actualPort });
+            });
+        });
+    }
+    /**
+     * Stops the server gracefully.
+     */
+    stop() {
+        return new Promise((resolve) => {
+            if (this.server) {
+                this.server.close(() => {
+                    this.server = null;
+                    resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    async handleRequest(req, res) {
+        const parsedUrl = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
+        const pathname = parsedUrl.pathname;
+        const method = (req.method || 'GET').toUpperCase();
+        // CORS for local development
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Root UI
+        if (pathname === '/' || pathname === '/index.html') {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(renderDashboardHtml());
+            return;
+        }
+        // JSON REST API
+        if (pathname.startsWith('/api/')) {
+            res.setHeader('Content-Type', 'application/json; charset=utf-8');
+            if (pathname === '/api/stats' && method === 'GET') {
+                const stats = this.getStats();
+                res.writeHead(200);
+                res.end(JSON.stringify(stats));
+                return;
+            }
+            if (pathname === '/api/sources' && method === 'GET') {
+                const sources = this.repo.sources.listSources();
+                res.writeHead(200);
+                res.end(JSON.stringify(sources));
+                return;
+            }
+            if (pathname === '/api/pages' && method === 'GET') {
+                const pages = this.repo.pages.listPages(200);
+                res.writeHead(200);
+                res.end(JSON.stringify(pages));
+                return;
+            }
+            if (pathname === '/api/apis' && method === 'GET') {
+                const q = parsedUrl.searchParams.get('q') || '';
+                const apiMethod = parsedUrl.searchParams.get('method') || undefined;
+                const docVersion = parsedUrl.searchParams.get('docVersion') || undefined;
+                const apis = this.repo.apis.searchApiEndpoints(q, {
+                    method: apiMethod,
+                    docVersion,
+                    limit: 100,
+                });
+                res.writeHead(200);
+                res.end(JSON.stringify(apis));
+                return;
+            }
+            if (pathname === '/api/pitfalls' && method === 'GET') {
+                const q = parsedUrl.searchParams.get('q') || '';
+                const kind = parsedUrl.searchParams.get('kind') || undefined;
+                const docVersion = parsedUrl.searchParams.get('docVersion') || undefined;
+                const pitfalls = this.repo.pitfalls.searchPitfalls(q, {
+                    kind,
+                    docVersion,
+                    limit: 100,
+                });
+                res.writeHead(200);
+                res.end(JSON.stringify(pitfalls));
+                return;
+            }
+            if (pathname === '/api/examples' && method === 'GET') {
+                const q = parsedUrl.searchParams.get('q') || '';
+                const language = parsedUrl.searchParams.get('language') || undefined;
+                const framework = parsedUrl.searchParams.get('framework') || undefined;
+                const docVersion = parsedUrl.searchParams.get('docVersion') || undefined;
+                const examples = this.repo.examples.searchIndexedExamples(q, {
+                    language,
+                    framework,
+                    docVersion,
+                    limit: 50,
+                });
+                res.writeHead(200);
+                res.end(JSON.stringify(examples));
+                return;
+            }
+            if (pathname === '/api/docs-map' && method === 'GET') {
+                const sourceId = parsedUrl.searchParams.get('sourceId') || undefined;
+                const docVersion = parsedUrl.searchParams.get('docVersion') || undefined;
+                const map = this.exportService.getDocumentationMap({ sourceId, docVersion });
+                res.writeHead(200);
+                res.end(JSON.stringify(map));
+                return;
+            }
+            if (pathname === '/api/export' && method === 'GET') {
+                const format = (parsedUrl.searchParams.get('format') || 'agents.md');
+                const docVersion = parsedUrl.searchParams.get('docVersion') || undefined;
+                const exp = await this.exportService.generateExport({
+                    format,
+                    docVersion,
+                    projectDir: this.projectDir,
+                });
+                res.writeHead(200);
+                res.end(JSON.stringify(exp));
+                return;
+            }
+            if (pathname === '/api/verify' && method === 'POST') {
+                const body = await this.readJsonBody(req);
+                const code = body.code || '';
+                const version = body.version || body.docVersion;
+                const library = body.library;
+                const language = body.language;
+                const verifyResult = this.verificationService.verifyCode({
+                    code,
+                    version,
+                    library,
+                    language,
+                    projectDir: this.projectDir,
+                });
+                res.writeHead(200);
+                res.end(JSON.stringify(verifyResult));
+                return;
+            }
+            if (pathname === '/api/diff' && method === 'GET') {
+                const from = parsedUrl.searchParams.get('from') || undefined;
+                const to = parsedUrl.searchParams.get('to') || undefined;
+                const source = parsedUrl.searchParams.get('source') || undefined;
+                const diffResult = this.diffService.diff({ from, to, source });
+                res.writeHead(200);
+                res.end(JSON.stringify(diffResult));
+                return;
+            }
+            if (pathname === '/api/impact' && method === 'GET') {
+                const from = parsedUrl.searchParams.get('from') || undefined;
+                const to = parsedUrl.searchParams.get('to') || undefined;
+                const targetDir = parsedUrl.searchParams.get('projectDir') || this.projectDir || process.cwd();
+                const impactResult = this.impactService.analyzeWorkspaceImpact({
+                    from,
+                    to,
+                    projectDir: targetDir,
+                });
+                res.writeHead(200);
+                res.end(JSON.stringify(impactResult));
+                return;
+            }
+            res.writeHead(404);
+            res.end(JSON.stringify({ error: `Route not found: ${pathname}` }));
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+    }
+    getStats() {
+        const sources = this.repo.sources.listSources();
+        const totalPages = this.repo.pages.countPages();
+        const totalChunks = this.repo.chunks.countChunks();
+        let totalApis = 0;
+        let totalPitfalls = 0;
+        let totalExamples = 0;
+        const activeVersions = new Set();
+        try {
+            const raw = this.repo.db.getRawDb();
+            const apiRow = raw.prepare('SELECT COUNT(*) as c FROM api_endpoints').get();
+            totalApis = apiRow?.c || 0;
+            const pitRow = raw.prepare('SELECT COUNT(*) as c FROM pitfalls').get();
+            totalPitfalls = pitRow?.c || 0;
+            const exRow = raw.prepare('SELECT COUNT(*) as c FROM indexed_examples').get();
+            totalExamples = exRow?.c || 0;
+            const verRows = raw.prepare('SELECT DISTINCT doc_version FROM snapshots WHERE doc_version IS NOT NULL').all();
+            for (const r of verRows) {
+                if (r.doc_version)
+                    activeVersions.add(r.doc_version);
+            }
+        }
+        catch {
+            // Best-effort stats aggregation
+        }
+        return {
+            totalSources: sources.length,
+            totalPages,
+            totalChunks,
+            totalApis,
+            totalPitfalls,
+            totalExamples,
+            totalRecipes: 5,
+            activeVersions: Array.from(activeVersions).sort(),
+            dbPath: this.dbPath,
+            untrusted: true,
+        };
+    }
+    readJsonBody(req) {
+        return new Promise((resolve, reject) => {
+            let body = '';
+            req.on('data', (chunk) => {
+                body += chunk.toString();
+            });
+            req.on('end', () => {
+                try {
+                    resolve(body ? JSON.parse(body) : {});
+                }
+                catch (err) {
+                    reject(new Error('Invalid JSON payload'));
+                }
+            });
+            req.on('error', (err) => reject(err));
+        });
+    }
+}

package/dist/packages/core/src/dashboard/ui.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Embedded HTML/CSS/JS dashboard UI for DocOrbit.
+ * Lightweight, zero external dependencies, zero CDN requests, fully offline capable.
+ */
+export declare function renderDashboardHtml(): string;

package/{packages/core/src/dashboard/ui.ts → dist/packages/core/src/dashboard/ui.js}

@@ -2,8 +2,8 @@
  * Embedded HTML/CSS/JS dashboard UI for DocOrbit.
  * Lightweight, zero external dependencies, zero CDN requests, fully offline capable.
  */
-export function renderDashboardHtml(): string {
-  return `<!DOCTYPE html>
+export function renderDashboardHtml() {
+    return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">

package/dist/packages/core/src/implementation-service.d.ts

@@ -0,0 +1,73 @@
+import type { DocOrbitRepository } from '../../storage/src/index.ts';
+import type { QueryIntent, Recipe, ApiEndpoint, IndexedExample, Pitfall, DocumentChunk } from '../../shared/src/index.ts';
+export interface ImplementationContextRequest {
+    task: string;
+    projectPath?: string;
+    library?: string;
+    version?: string;
+    tokenBudget?: number;
+}
+export interface ProjectResolutionInfo {
+    root: string;
+    matchedDependency?: {
+        name: string;
+        ecosystem: string;
+        requestedVersion: string;
+        resolvedVersion?: string;
+    };
+    versionResolution?: {
+        targetVersion: string;
+        confidence: number;
+        snapshotId?: string;
+        matchedBy?: string;
+    };
+    resolvedDependency?: string;
+    projectVersion?: string;
+    docVersion?: string;
+    confidence?: number;
+}
+export interface ProvenanceItem {
+    sourceUrl: string;
+    authority: string;
+    retrievedAt?: string;
+    untrusted: true;
+}
+export interface VerificationHint {
+    endpoint: string;
+    method: string;
+    requiredParameters: string[];
+    requiredBodyFields: string[];
+    deprecated?: boolean;
+    warnings?: string[];
+}
+export interface ImplementationContextResult {
+    task: string;
+    detectedIntent: QueryIntent;
+    project?: ProjectResolutionInfo;
+    recipe: Recipe;
+    apiEndpoints: ApiEndpoint[];
+    examples: IndexedExample[];
+    pitfalls: Pitfall[];
+    chunks: DocumentChunk[];
+    totalEstimatedTokens: number;
+    tokenBudget: number;
+    markdown: string;
+    provenance: ProvenanceItem[];
+    verificationHints?: VerificationHint[];
+    untrusted: true;
+    untrustedContentNotice?: string;
+}
+export declare class ImplementationContextService {
+    private repo;
+    private retrievalEngine;
+    private recipeEngine;
+    private workspaceResolver;
+    constructor(repo: DocOrbitRepository);
+    /**
+     * Orchestrates the complete documentation intelligence pipeline for an agent task:
+     * task → project/dependency detection → version resolution → intent → retrieval →
+     * APIs → examples → pitfalls → recipe → token-budgeted context → provenance.
+     */
+    getContext(request: ImplementationContextRequest): Promise<ImplementationContextResult>;
+    private synthesizeMarkdown;
+}

package/dist/packages/core/src/implementation-service.js

@@ -0,0 +1,325 @@
+import { RetrievalEngine, RecipeEngine, detectQueryIntent, } from "../../retrieval/src/index.js";
+import { detectWorkspaceDependencies, WorkspaceResolver, } from "../../workspace/src/index.js";
+import { estimateTokenCount, } from "../../shared/src/index.js";
+export class ImplementationContextService {
+    repo;
+    retrievalEngine;
+    recipeEngine;
+    workspaceResolver;
+    constructor(repo) {
+        this.repo = repo;
+        this.retrievalEngine = new RetrievalEngine(repo);
+        this.recipeEngine = new RecipeEngine(repo);
+        this.workspaceResolver = new WorkspaceResolver(repo);
+    }
+    /**
+     * Orchestrates the complete documentation intelligence pipeline for an agent task:
+     * task → project/dependency detection → version resolution → intent → retrieval →
+     * APIs → examples → pitfalls → recipe → token-budgeted context → provenance.
+     */
+    async getContext(request) {
+        const task = request.task.trim();
+        const tokenBudget = request.tokenBudget || 4000;
+        let targetVersion = request.version;
+        // 1. Intent Detection
+        const detectedIntent = detectQueryIntent(task);
+        // 2. Project Awareness & Version Resolution
+        let projectInfo;
+        if (request.projectPath) {
+            try {
+                const scan = detectWorkspaceDependencies(request.projectPath);
+                const resolution = this.workspaceResolver.resolveWorkspace(scan);
+                let matchedDep = undefined;
+                let versionRes = undefined;
+                // If library was specified, look for it specifically
+                if (request.library) {
+                    const libLower = request.library.toLowerCase();
+                    matchedDep = scan.dependencies.find(d => d.name.toLowerCase() === libLower);
+                    const match = resolution.matches.find(m => m.dependency.name.toLowerCase() === libLower);
+                    if (match && match.targetVersion) {
+                        targetVersion = targetVersion || match.targetVersion;
+                        versionRes = {
+                            targetVersion: match.targetVersion,
+                            confidence: match.confidence,
+                            snapshotId: match.snapshotId,
+                            matchedBy: match.matchedBy,
+                        };
+                    }
+                }
+                else {
+                    // Find any relevant dependency mentioned in the task
+                    const taskLower = task.toLowerCase();
+                    for (const m of resolution.matches) {
+                        if (taskLower.includes(m.dependency.name.toLowerCase()) && m.targetVersion) {
+                            matchedDep = m.dependency;
+                            targetVersion = targetVersion || m.targetVersion;
+                            versionRes = {
+                                targetVersion: m.targetVersion,
+                                confidence: m.confidence,
+                                snapshotId: m.snapshotId,
+                                matchedBy: m.matchedBy,
+                            };
+                            break;
+                        }
+                    }
+                }
+                projectInfo = {
+                    root: request.projectPath,
+                    matchedDependency: matchedDep ? {
+                        name: matchedDep.name,
+                        ecosystem: matchedDep.ecosystem,
+                        requestedVersion: matchedDep.requestedVersion,
+                        resolvedVersion: matchedDep.resolvedVersion,
+                    } : undefined,
+                    versionResolution: versionRes,
+                    resolvedDependency: matchedDep?.name,
+                    projectVersion: matchedDep?.requestedVersion,
+                    docVersion: versionRes?.targetVersion,
+                    confidence: versionRes?.confidence,
+                };
+            }
+            catch {
+                // Continue if workspace scan fails
+            }
+        }
+        // 3. Structured Recipe Generation
+        const recipe = await this.recipeEngine.assembleRecipe(task, {
+            docVersion: targetVersion,
+            projectDir: request.projectPath,
+        });
+        // 4. API Endpoints
+        const apiEndpoints = this.repo.searchApiEndpoints(task, {
+            docVersion: targetVersion,
+            limit: 5,
+        });
+        // 5. Verified Examples
+        const examples = this.repo.searchIndexedExamples(task, {
+            docVersion: targetVersion,
+            limit: 5,
+        });
+        // 6. Pitfalls & Deprecations
+        const pitfalls = this.repo.searchPitfalls(task, {
+            docVersion: targetVersion,
+            limit: 5,
+        });
+        // 7. Targeted Chunk Retrieval
+        const searchResults = await this.retrievalEngine.search(task, {
+            docVersion: targetVersion,
+            limit: 8,
+            projectDir: request.projectPath,
+        });
+        const chunks = searchResults.map(r => r.chunk);
+        // 8. Compile Provenance & Untrusted Boundaries
+        const provenanceMap = new Map();
+        const recordProvenance = (url, authority, date) => {
+            if (url && !provenanceMap.has(url)) {
+                provenanceMap.set(url, {
+                    sourceUrl: url,
+                    authority: authority || 'official',
+                    retrievedAt: date,
+                    untrusted: true,
+                });
+            }
+        };
+        for (const c of chunks) {
+            if (c.provenance?.sourceUrl) {
+                recordProvenance(c.provenance.sourceUrl, undefined, c.provenance.fetchedAt);
+            }
+        }
+        for (const ep of apiEndpoints) {
+            if (ep.provenance?.sourceUrl) {
+                recordProvenance(ep.provenance.sourceUrl, ep.provenance.sourceAuthority, ep.provenance.retrievedAt);
+            }
+        }
+        for (const ex of examples) {
+            if (ex.sourceUrl) {
+                recordProvenance(ex.sourceUrl, ex.sourceAuthority);
+            }
+        }
+        for (const pf of pitfalls) {
+            if (pf.provenance?.sourceUrl) {
+                recordProvenance(pf.provenance.sourceUrl, undefined, pf.provenance.retrievedAt);
+            }
+        }
+        for (const src of recipe.sources) {
+            recordProvenance(src);
+        }
+        const provenanceList = Array.from(provenanceMap.values());
+        // 9. Extract Verification Hints (Schema contracts & required parameters)
+        const verificationHints = apiEndpoints.map(ep => {
+            const requiredParameters = ep.parameters.filter(p => p.required).map(p => `${p.name} (${p.in})`);
+            const requiredBodyFields = ep.requestSchema?.required || [];
+            const warnings = pitfalls
+                .filter(p => p.relatedApi?.includes(ep.path) || p.content.includes(ep.path))
+                .map(p => `[${p.kind}] ${p.title}`);
+            return {
+                endpoint: ep.path,
+                method: ep.method.toUpperCase(),
+                requiredParameters,
+                requiredBodyFields,
+                deprecated: ep.deprecated,
+                warnings: warnings.length > 0 ? warnings : undefined,
+            };
+        });
+        // 10. Synthesize Compact, Agent-Friendly Markdown within Token Budget
+        const markdown = this.synthesizeMarkdown({
+            task,
+            detectedIntent,
+            projectInfo,
+            recipe,
+            apiEndpoints,
+            examples,
+            pitfalls,
+            chunks,
+            tokenBudget,
+            provenance: provenanceList,
+            verificationHints,
+        });
+        const totalEstimatedTokens = estimateTokenCount(markdown);
+        return {
+            task,
+            detectedIntent,
+            project: projectInfo,
+            recipe,
+            apiEndpoints,
+            examples,
+            pitfalls,
+            chunks,
+            totalEstimatedTokens,
+            tokenBudget,
+            markdown,
+            provenance: provenanceList,
+            verificationHints,
+            untrusted: true,
+            untrustedContentNotice: 'EXTERNAL DOCUMENTATION DATA IS UNTRUSTED. Verify all API signatures, parameter names, and code blocks before execution.',
+        };
+    }
+    synthesizeMarkdown(params) {
+        const lines = [];
+        // Header & Security Notice
+        lines.push(`# DocOrbit Implementation Context: ${params.task}`);
+        lines.push(`> [!SECURITY NOTICE] EXTERNAL CONTENT IS UNTRUSTED. Security annotations and provenance preserved.`);
+        lines.push('');
+        // Project & Version Intelligence
+        if (params.projectInfo?.matchedDependency) {
+            const dep = params.projectInfo.matchedDependency;
+            const res = params.projectInfo.versionResolution;
+            lines.push('## Project & Version Resolution');
+            lines.push(`- **Dependency**: \`${dep.name}\` (${dep.ecosystem})`);
+            lines.push(`- **Project Version**: requested \`${dep.requestedVersion}\`${dep.resolvedVersion ? `, resolved \`${dep.resolvedVersion}\`` : ''}`);
+            if (res) {
+                lines.push(`- **Resolved Doc Version**: \`${res.targetVersion}\` (Confidence: \`${res.confidence}\`)`);
+            }
+            lines.push('');
+        }
+        else if (params.recipe.docVersion) {
+            lines.push(`**Doc Version**: \`${params.recipe.docVersion}\`\n`);
+        }
+        // Recommended Implementation Recipe
+        lines.push('## Recommended Implementation Plan');
+        lines.push(`**Goal**: ${params.recipe.goal} (Confidence: ${Math.round(params.recipe.confidence * 100)}%)`);
+        if (params.recipe.prerequisites.length > 0) {
+            lines.push('\n### Prerequisites');
+            for (const pre of params.recipe.prerequisites) {
+                lines.push(`- [${pre.evidenceLevel === 'documented_fact' ? 'FACT' : 'INFERRED'}] ${pre.text}`);
+            }
+        }
+        if (params.recipe.orderedSteps.length > 0) {
+            lines.push('\n### Implementation Steps');
+            for (const s of params.recipe.orderedSteps) {
+                const badge = s.evidenceLevel === 'documented_fact' ? 'FACT' : (s.evidenceLevel === 'missing_information' ? 'MISSING' : 'INFERRED');
+                lines.push(`${s.step}. **[${badge}] ${s.title}**`);
+                if (s.apiEndpoint)
+                    lines.push(`   - Endpoint: \`${s.apiEndpoint}\``);
+                lines.push(`   - ${s.description}`);
+            }
+        }
+        if (params.recipe.validationSteps.length > 0) {
+            lines.push('\n### Validation & Verification');
+            for (const vs of params.recipe.validationSteps) {
+                lines.push(`${vs.step}. **[FACT]** ${vs.description}`);
+                if (vs.expectedResponse)
+                    lines.push(`   - Expected: \`${vs.expectedResponse}\``);
+            }
+        }
+        lines.push('');
+        // Structured Required APIs
+        if (params.apiEndpoints.length > 0) {
+            lines.push('## Required API Endpoints');
+            for (const ep of params.apiEndpoints.slice(0, 3)) {
+                lines.push(`### \`${ep.method.toUpperCase()} ${ep.path}\`${ep.deprecated ? ' (DEPRECATED)' : ''}`);
+                if (ep.summary)
+                    lines.push(`*${ep.summary}*`);
+                if (ep.parameters.length > 0) {
+                    const req = ep.parameters.filter(p => p.required).map(p => `\`${p.name}\` (${p.in}:${p.type || 'any'})`).join(', ');
+                    const opt = ep.parameters.filter(p => !p.required).map(p => `\`${p.name}\``).join(', ');
+                    if (req)
+                        lines.push(`- **Required Parameters**: ${req}`);
+                    if (opt)
+                        lines.push(`- **Optional Parameters**: ${opt}`);
+                }
+                if (ep.auth.length > 0) {
+                    lines.push(`- **Auth**: ${ep.auth.map(a => `${a.type}${a.scheme ? `:${a.scheme}` : ''}`).join(', ')}`);
+                }
+                if (ep.pagination) {
+                    lines.push(`- **Pagination**: ${ep.pagination.type} (${ep.pagination.parameters.join(', ')})`);
+                }
+                lines.push('');
+            }
+        }
+        // Best Code Examples
+        if (params.examples.length > 0) {
+            lines.push('## Verified Code Examples');
+            for (const ex of params.examples.slice(0, 2)) {
+                lines.push(`### ${ex.task} (${ex.language}${ex.framework ? `, ${ex.framework}` : ''})`);
+                lines.push('```' + ex.language);
+                lines.push(ex.code);
+                lines.push('```\n');
+            }
+        }
+        // Pitfalls, Gotchas & Deprecations
+        if (params.pitfalls.length > 0) {
+            lines.push('## Pitfalls & Warnings');
+            for (const pf of params.pitfalls.slice(0, 4)) {
+                lines.push(`- ⚠️ **[${pf.kind.toUpperCase()}] ${pf.title}**: ${pf.content}`);
+            }
+            lines.push('');
+        }
+        // Verification Constraints & Schema Contracts
+        if (params.verificationHints && params.verificationHints.length > 0) {
+            lines.push('## Verification Constraints & Schema Contracts');
+            for (const hint of params.verificationHints.slice(0, 3)) {
+                lines.push(`- **\`${hint.method} ${hint.endpoint}\`**${hint.deprecated ? ' (DEPRECATED)' : ''}`);
+                if (hint.requiredParameters.length > 0) {
+                    lines.push(`  - *Required Query/Path Params*: \`${hint.requiredParameters.join('`, `')}\``);
+                }
+                if (hint.requiredBodyFields.length > 0) {
+                    lines.push(`  - *Required Body Fields*: \`${hint.requiredBodyFields.join('`, `')}\``);
+                }
+                if (hint.warnings && hint.warnings.length > 0) {
+                    for (const w of hint.warnings) {
+                        lines.push(`  - ⚠️ ${w}`);
+                    }
+                }
+            }
+            lines.push('');
+        }
+        // Sources & Provenance
+        if (params.provenance.length > 0) {
+            lines.push('## Documentation Sources & Provenance');
+            for (const prov of params.provenance) {
+                lines.push(`- \`${prov.authority}\`: ${prov.sourceUrl} (untrusted)`);
+            }
+            lines.push('');
+        }
+        // Budget enforcement
+        let fullText = lines.join('\n');
+        let tokens = estimateTokenCount(fullText);
+        if (tokens > params.tokenBudget) {
+            // Trim examples or documentation chunks to fit strictly in budget
+            const truncated = fullText.slice(0, Math.floor(params.tokenBudget * 3.5)) + '\n\n... [Context truncated to fit token budget]';
+            return truncated;
+        }
+        return fullText;
+    }
+}

package/{packages/core/src/index.ts → dist/packages/core/src/index.d.ts}

@@ -4,4 +4,3 @@ export * from './implementation-service.ts';
 export * from '../../verification/src/index.ts';
 export * from '../../export/src/index.ts';
 export * from './dashboard/server.ts';
-