cognitive-kit 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/host/adapters/PostgresAdapter.js

@@ -0,0 +1,252 @@
+export class PostgresAdapter {
+    config;
+    pool = null;
+    pgModule = null;
+    available = false;
+    queryCount = 0;
+    constructor(config) {
+        this.config = {
+            connectionString: config?.connectionString ?? process.env.KIT_PG_CONNECTION,
+            host: config?.host ?? process.env.KIT_PG_HOST ?? 'localhost',
+            port: config?.port ?? parseInt(process.env.KIT_PG_PORT ?? '5432'),
+            database: config?.database ?? process.env.KIT_PG_DATABASE,
+            user: config?.user ?? process.env.KIT_PG_USER,
+            password: config?.password ?? process.env.KIT_PG_PASSWORD,
+            maxQueries: config?.maxQueries ?? 100,
+        };
+    }
+    get profile() {
+        return {
+            type: 'database',
+            name: 'PostgreSQL Adapter',
+            version: '1.0.0',
+            capabilities: this.getCapabilities(),
+            metadata: {
+                database: this.config.database ?? '(not configured)',
+                host: this.config.host ?? 'localhost',
+                port: String(this.config.port),
+                available: String(this.available),
+            },
+        };
+    }
+    async initialize() {
+        try {
+            this.pgModule = await import('pg');
+            const cs = this.config.connectionString ||
+                `postgres://${this.config.user}:${this.config.password}@${this.config.host}:${this.config.port}/${this.config.database}`;
+            if (!cs || cs === 'postgres://undefined:undefined@localhost:5432/undefined') {
+                console.error('[pg-adapter] No PostgreSQL connection configured. Set KIT_PG_CONNECTION or individual env vars.');
+                return;
+            }
+            this.pool = new this.pgModule.Pool({ connectionString: cs, max: 5 });
+            const client = await this.pool.connect();
+            await client.query('SELECT 1');
+            client.release();
+            this.available = true;
+            console.error(`[pg-adapter] Connected to ${this.config.host}:${this.config.port}/${this.config.database}`);
+        }
+        catch (err) {
+            console.error(`[pg-adapter] Not available: ${err instanceof Error ? err.message : err}`);
+            this.available = false;
+        }
+    }
+    async shutdown() {
+        if (this.pool) {
+            await this.pool.end();
+            this.available = false;
+        }
+    }
+    getHostTools() {
+        if (!this.available)
+            return [];
+        return [
+            this.createQueryTool(),
+            this.createSchemaTool(),
+            this.createListTablesTool(),
+            this.createDescribeTableTool(),
+        ];
+    }
+    getCapabilities() {
+        return this.available ? ['database'] : [];
+    }
+    async query(sql, params) {
+        if (!this.pool)
+            throw new Error('Not connected');
+        this.queryCount++;
+        const result = await this.pool.query(sql, params);
+        return {
+            rows: result.rows,
+            rowCount: result.rowCount ?? 0,
+            fields: result.fields?.map((f) => f.name) ?? [],
+        };
+    }
+    createQueryTool() {
+        return {
+            id: 'pg_query',
+            name: 'PostgreSQL Query',
+            description: 'Execute a read-only SQL query on the connected database. Returns rows, columns, and row count.',
+            inputSchema: {
+                sql: { type: 'string', description: 'SQL query (SELECT only)' },
+                params: { type: 'array', description: 'Query parameter values' },
+                limit: { type: 'number', description: 'Maximum rows to return' },
+            },
+            sovereignty: 0.4,
+            category: 'host',
+            handler: async (params, _ctx) => {
+                if (!this.available)
+                    return { success: false, data: null, error: 'PostgreSQL not connected' };
+                const sql = String(params.sql || '');
+                if (!sql)
+                    return { success: false, data: null, error: 'SQL query is required' };
+                if (!/^\s*SELECT/i.test(sql.trim())) {
+                    return { success: false, data: null, error: 'Only SELECT queries are allowed via pg_query' };
+                }
+                try {
+                    const result = await this.query(sql, Array.isArray(params.params) ? params.params : undefined);
+                    const limit = Number(params.limit) || 100;
+                    const truncated = result.rows.length > limit;
+                    return {
+                        success: true,
+                        data: {
+                            columns: result.fields,
+                            rows: result.rows.slice(0, limit),
+                            totalRows: result.rowCount,
+                            returnedRows: Math.min(result.rows.length, limit),
+                            truncated,
+                            queryCount: this.queryCount,
+                        },
+                    };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Query failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+    createSchemaTool() {
+        return {
+            id: 'pg_schema',
+            name: 'PostgreSQL Schema',
+            description: 'List all schemas, tables, columns, and their types in the database.',
+            inputSchema: { schema: { type: 'string', description: 'Filter by schema name (default: public)' } },
+            category: 'host',
+            handler: async (params, _ctx) => {
+                if (!this.available)
+                    return { success: false, data: null, error: 'PostgreSQL not connected' };
+                const schemaFilter = String(params.schema || 'public');
+                try {
+                    const result = await this.query(`
+            SELECT
+              t.table_schema, t.table_name, c.column_name, c.data_type,
+              c.is_nullable, c.character_maximum_length,
+              (SELECT json_agg(indexname) FROM pg_indexes WHERE tablename = t.table_name AND schemaname = t.table_schema) as indexes
+            FROM information_schema.tables t
+            JOIN information_schema.columns c ON t.table_schema = c.table_schema AND t.table_name = c.table_name
+            WHERE t.table_schema = $1 AND t.table_type = 'BASE TABLE'
+            ORDER BY t.table_name, c.ordinal_position
+          `, [schemaFilter]);
+                    const tables = new Map();
+                    for (const row of result.rows) {
+                        const key = `${row.table_schema}.${row.table_name}`;
+                        if (!tables.has(key))
+                            tables.set(key, []);
+                        tables.get(key).push({
+                            name: row.column_name, type: row.data_type,
+                            nullable: row.is_nullable === 'YES',
+                            maxLength: row.character_maximum_length,
+                        });
+                    }
+                    return {
+                        success: true,
+                        data: {
+                            schema: schemaFilter,
+                            tables: Array.from(tables.entries()).map(([name, columns]) => ({ name, columns, columnCount: columns.length })),
+                            totalTables: tables.size,
+                        },
+                    };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Schema query failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+    createListTablesTool() {
+        return {
+            id: 'pg_list_tables',
+            name: 'PostgreSQL List Tables',
+            description: 'List all tables in the database with row counts and sizes.',
+            inputSchema: { schema: { type: 'string', description: 'Schema filter (default: public)' } },
+            category: 'host',
+            handler: async (params, _ctx) => {
+                if (!this.available)
+                    return { success: false, data: null, error: 'PostgreSQL not connected' };
+                const schema = String(params.schema || 'public');
+                try {
+                    const result = await this.query(`
+            SELECT
+              relname as table_name,
+              n_live_tup as estimated_rows,
+              pg_size_pretty(pg_total_relation_size(relid)) as total_size
+            FROM pg_stat_user_tables
+            WHERE schemaname = $1
+            ORDER BY relname
+          `, [schema]);
+                    return {
+                        success: true,
+                        data: { schema, tables: result.rows, total: result.rows.length },
+                    };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Failed to list tables: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+    createDescribeTableTool() {
+        return {
+            id: 'pg_describe',
+            name: 'PostgreSQL Describe Table',
+            description: 'Get detailed info about a specific table including columns, constraints, and indexes.',
+            inputSchema: {
+                table: { type: 'string', description: 'Table name' },
+                schema: { type: 'string', description: 'Schema (default: public)' },
+            },
+            category: 'host',
+            handler: async (params, _ctx) => {
+                if (!this.available)
+                    return { success: false, data: null, error: 'PostgreSQL not connected' };
+                const table = String(params.table || '');
+                const schema = String(params.schema || 'public');
+                if (!table)
+                    return { success: false, data: null, error: 'table name is required' };
+                try {
+                    const [columns, indexes, sample] = await Promise.all([
+                        this.query(`
+              SELECT column_name, data_type, is_nullable, column_default, character_maximum_length
+              FROM information_schema.columns
+              WHERE table_schema = $1 AND table_name = $2
+              ORDER BY ordinal_position
+            `, [schema, table]),
+                        this.query(`SELECT indexname, indexdef FROM pg_indexes WHERE schemaname = $1 AND tablename = $2`, [schema, table]),
+                        this.query(`SELECT * FROM "${schema}"."${table}" LIMIT 5`),
+                    ]);
+                    return {
+                        success: true,
+                        data: {
+                            table: `${schema}.${table}`,
+                            columns: columns.rows,
+                            indexes: indexes.rows,
+                            sampleData: sample.rows,
+                            sampleCount: sample.rows.length,
+                        },
+                    };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Failed to describe table: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+}
+//# sourceMappingURL=PostgresAdapter.js.map

package/dist/host/adapters/PostgresAdapter.js.map

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

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { DirectTransport } from './mcp/transports/DirectTransport.js';
 export type { Transport } from './mcp/transports/Transport.js';
 export type { HostAdapter } from './host/HostAdapter.js';
 export { VSCodeAdapter } from './host/adapters/VSCodeAdapter.js';
+export { FileSystemAdapter } from './host/adapters/FileSystemAdapter.js';
+export { PostgresAdapter } from './host/adapters/PostgresAdapter.js';
 export { SkillRegistry } from './skills/SkillRegistry.js';
 export { AgencyRegistry } from './agencies/AgencyRegistry.js';
 export { AgencyOrchestrator } from './agencies/AgencyOrchestrator.js';

package/dist/index.js

@@ -15,6 +15,8 @@ export { StdioTransport } from './mcp/transports/StdioTransport.js';
 export { SSETransport } from './mcp/transports/SSETransport.js';
 export { DirectTransport } from './mcp/transports/DirectTransport.js';
 export { VSCodeAdapter } from './host/adapters/VSCodeAdapter.js';
+export { FileSystemAdapter } from './host/adapters/FileSystemAdapter.js';
+export { PostgresAdapter } from './host/adapters/PostgresAdapter.js';
 // Skills
 export { SkillRegistry } from './skills/SkillRegistry.js';
 // Agencies

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO;AACP,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,SAAS;AACT,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAExE,WAAW;AACX,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAEhE,SAAS;AACT,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAEtE,MAAM;AACN,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAKtE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEjE,SAAS;AACT,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D,WAAW;AACX,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE,WAAW;AACX,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,aAAa;AACb,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE,4BAA4B;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO;AACP,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,SAAS;AACT,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAExE,WAAW;AACX,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAEhE,SAAS;AACT,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAEtE,MAAM;AACN,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAKtE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAErE,SAAS;AACT,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D,WAAW;AACX,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE,WAAW;AACX,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,aAAa;AACb,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE,4BAA4B;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/docs/examples/custom-adapter.md

@@ -0,0 +1,79 @@
+# Example: Custom Host Adapter
+
+Create a custom adapter to integrate Cognitive Kit with any system.
+
+```typescript
+import { CognitiveKit, type HostAdapter, type HostProfile, type ToolDefinition, type ToolResult, type ToolContext, type HostCapability } from 'cognitive-kit';
+
+class MyAPIAdapter implements HostAdapter {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(apiKey: string, baseUrl: string) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+
+  get profile(): HostProfile {
+    return {
+      type: 'api',
+      name: 'My API Adapter',
+      version: '1.0.0',
+      capabilities: this.getCapabilities(),
+      metadata: { baseUrl: this.baseUrl },
+    };
+  }
+
+  async initialize(): Promise<void> {
+    console.error(`[my-adapter] Connected to ${this.baseUrl}`);
+  }
+
+  async shutdown(): Promise<void> {
+    console.error('[my-adapter] Disconnected');
+  }
+
+  getHostTools(): ToolDefinition[] {
+    return [
+      {
+        id: 'my_api_call',
+        name: 'My API Call',
+        description: 'Call an endpoint on My API',
+        inputSchema: {
+          endpoint: { type: 'string' },
+          method: { type: 'string', enum: ['GET', 'POST'] },
+          body: { type: 'object' },
+        },
+        category: 'host',
+        handler: async (params: Record<string, unknown>, _ctx: ToolContext): Promise<ToolResult> => {
+          const endpoint = String(params.endpoint || '');
+          const method = String(params.method || 'GET');
+          try {
+            const response = await fetch(`${this.baseUrl}${endpoint}`, {
+              method,
+              headers: { Authorization: `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+              body: method === 'POST' ? JSON.stringify(params.body || {}) : undefined,
+            });
+            const data = await response.json();
+            return { success: response.ok, data, error: response.ok ? undefined : data.error };
+          } catch (err) {
+            return { success: false, data: null, error: `API call failed: ${err instanceof Error ? err.message : String(err)}` };
+          }
+        },
+      },
+    ];
+  }
+
+  getCapabilities(): HostCapability[] {
+    return ['network'];
+  }
+}
+
+// Use it
+const kit = new CognitiveKit({
+  host: new MyAPIAdapter('sk-...', 'https://api.example.com'),
+  transport: { type: 'stdio' },
+});
+
+await kit.start();
+// Now has all cognitive tools + my_api_call
+```

package/docs/examples/federation.md

@@ -0,0 +1,60 @@
+# Example: Multi-Kit Federation
+
+Connect multiple Cognitive Kit instances. Kit in VS Code, Kit in Database, Kit in CI — all federated.
+
+```typescript
+// Kit A: Server (database side)
+import { CognitiveKit, PostgresAdapter } from 'cognitive-kit';
+
+const kitA = new CognitiveKit({
+  host: new PostgresAdapter({ connectionString: 'postgres://...' }),
+  storage: { type: 'sqlite', path: './kit-a.db' },
+  transport: { type: 'sse', port: 3100 },
+});
+
+await kitA.start();
+// Federation server listening on port 3100
+```
+
+```typescript
+// Kit B: Client (VS Code side)
+import { CognitiveKit, FileSystemAdapter } from 'cognitive-kit';
+
+const kitB = new CognitiveKit({
+  host: new FileSystemAdapter('./project'),
+  transport: { type: 'direct' },
+});
+
+await kitB.initialize();
+
+// Connect to Kit A
+await kitB.federationManager.connectTo('http://localhost:3100');
+
+// Execute database tools remotely
+const tables = await kitB.federationManager.executeOnPeer(
+  'http://localhost:3100',
+  'pg_list_tables',
+  {}
+);
+console.log(tables.data);
+
+// Use Kit A's cognitive tools + Kit B's filesystem tools together
+const analysis = await kitB.federationManager.executeOnPeer(
+  'http://localhost:3100',
+  'knowledge_evolve',
+  { knowledgeBase: JSON.stringify(tables), mode: 'gap' }
+);
+console.log(analysis.data);
+
+await kitB.stop();
+```
+
+## Federation Protocol
+
+```
+Kit A (SSE:4200)  ←→  Kit B (stdio)  ←→  Kit C (SSE:4201)
+       ↑                    ↑
+  PostgreSQL            Filesystem
+```
+
+Each kit exposes its tools via the federation protocol. Kits discover each other's tools and call them remotely with sovereignty delegation.

package/docs/examples/library-embed.md

@@ -0,0 +1,69 @@
+# Example: Library Embedding
+
+Embed Cognitive Kit directly into your Node.js application.
+
+```typescript
+import { CognitiveKit, FileSystemAdapter } from 'cognitive-kit';
+
+async function main() {
+  // Create kit with filesystem adapter
+  const kit = new CognitiveKit({
+    host: new FileSystemAdapter('./workspace', { allowWrite: true }),
+    storage: { type: 'sqlite', path: './.cognitive-kit.db' },
+    transport: { type: 'direct' }, // in-process, no stdio
+    sovereignty: {
+      hostId: 'my-app',
+      hostName: 'My Application',
+    },
+  });
+
+  await kit.initialize();
+
+  console.log(`Tools: ${kit.toolCount}`);
+  console.log(`Skills: ${kit.skillCount}`);
+  console.log(`Identity: ${kit.identityInfo}`);
+
+  // Register a custom tool
+  kit.registerTool({
+    id: 'my_tool',
+    name: 'My Custom Tool',
+    description: 'App-specific tool',
+    inputSchema: { input: { type: 'string' } },
+    category: 'cognitive',
+    handler: async (params, ctx) => ({
+      success: true,
+      data: { processed: `Hello ${params.input || 'world'}` },
+      metadata: { sovereignty: ctx.identity.sovereignty },
+    }),
+  });
+
+  // Execute built-in tools via the tool registry
+  const context = {
+    identity: { actorId: 'user', actorType: 'user', sovereignty: 0.9, permissions: ['execute'] },
+    host: { type: 'cli', name: 'app', capabilities: [] },
+    memory: kit['memory'],
+  };
+
+  const reason = await kit['toolRegistry'].execute('cognitive_reason', {
+    problem: 'Design a microservices architecture',
+    mode: 'logical',
+  }, context);
+
+  console.log(reason.data?.conclusion);
+
+  // Run an agency mission
+  const mission = await kit.executeAgency(
+    'Analyze system performance',
+    { mode: 'sequential' }
+  );
+  console.log(`Mission: ${mission.status} (${mission.synergyScore})`);
+
+  // Forge skills from usage
+  const skills = kit.forge.forgeFromPatterns(true);
+  console.log(`Forged ${skills.length} new skills`);
+
+  await kit.stop();
+}
+
+main().catch(console.error);
+```

package/docs/examples/mcp-server.md

@@ -0,0 +1,48 @@
+# Example: MCP Server (standalone)
+
+Run Cognitive Kit as a standalone MCP server for any client (VS Code, Cursor, Claude Desktop, or custom).
+
+```typescript
+// mcp-server.ts
+import { CognitiveKit } from 'cognitive-kit';
+
+const kit = new CognitiveKit({
+  host: {
+    type: 'cli',
+    name: 'My MCP Server',
+    capabilities: ['filesystem'],
+  },
+  storage: { type: 'sqlite', path: './.kit.db' },
+  transport: { type: 'stdio' },
+  sovereignty: {
+    hostId: process.env.KIT_HOST_ID || 'mcp-1',
+    hostName: process.env.KIT_HOST_NAME || 'MCP Server',
+  },
+});
+
+process.on('SIGINT', async () => { await kit.stop(); process.exit(0); });
+process.on('SIGTERM', async () => { await kit.stop(); process.exit(0); });
+
+await kit.start();
+// MCP protocol on stdio — 31 tools available
+```
+
+## Run
+
+```bash
+npx tsx mcp-server.ts
+```
+
+## Add to VS Code
+
+```json
+{
+  "servers": {
+    "cognitive-kit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["tsx", "/path/to/mcp-server.ts"]
+    }
+  }
+}
+```

package/docs/examples/pg-explorer.md

@@ -0,0 +1,48 @@
+# Example: PostgreSQL Knowledge Explorer
+
+Use Cognitive Kit + PostgreSQL adapter to explore, analyze, and document your database.
+
+```typescript
+import { CognitiveKit, PostgresAdapter } from 'cognitive-kit';
+
+const kit = new CognitiveKit({
+  host: new PostgresAdapter({
+    connectionString: process.env.DATABASE_URL,
+  }),
+  storage: { type: 'memory' },
+  transport: { type: 'direct' },
+  sovereignty: { hostId: 'pg-explorer', hostName: 'DB Explorer' },
+});
+
+await kit.initialize();
+
+const ctx = {
+  identity: { actorId: 'admin', actorType: 'host', sovereignty: 1.0, permissions: ['read', 'execute'] },
+  host: { type: 'database', name: 'pg', capabilities: ['database'] },
+  memory: kit['memory'],
+};
+
+// 1. Explore the schema
+const schema = await kit['toolRegistry'].execute('pg_schema', { schema: 'public' }, ctx);
+console.log(`Tables: ${schema.data.totalTables}`);
+
+// 2. Research each table
+for (const table of schema.data.tables) {
+  const analysis = await kit['toolRegistry'].execute('cognitive_reason', {
+    problem: `Analyze the ${table.name} table structure`,
+    context: JSON.stringify(table.columns),
+    mode: 'logical',
+  }, ctx);
+  console.log(`${table.name}: ${analysis.data?.conclusion}`);
+}
+
+// 3. Generate documentation
+const doc = await kit['toolRegistry'].execute('cognitive_plan', {
+  objective: 'Document all database schemas',
+  context: JSON.stringify(schema.data),
+}, ctx);
+
+console.log(doc.data?.pipeline);
+
+await kit.stop();
+```