trellis 2.0.10 → 2.1.1

package/README.md

@@ -1,62 +1,79 @@
 <p align="center">
-  <img src="logo.png" alt="Trellis" width="128" />
+  <img src="https://trentbrew.pockethost.io/api/files/swvnum16u65or8w/75p6fv4xnwa3mq7/logomark_alpha_green_T3C3ypsMwI.png?token=" alt="Trellis" width="128" />
 </p>
 
 # Trellis
 
-> **Graph-native, code-first version control.**
-> Every file save is an op. Every op is a node. History is a causal graph, not a linear diff.
-
-Trellis is a from-scratch VCS built on five pillars:
-
-1. **Causal Stream** — an immutable, content-addressed log of ops where every change is causally chained to its predecessor.
-2. **Semantic Patching** — changes are recorded as structured AST patches (`symbolRename`, `symbolModify`, …) rather than line diffs, enabling conflict-free merges.
-3. **Narrative Milestones** — you never "commit". Instead you carve checkpoints and milestones out of a continuous stream of work.
-4. **Governance Subgraph** — op signing, identity management, and policy rules enforced before ops enter the stream.
-5. **Idea Garden** — abandoned work clusters are automatically detected and surfaced for later revival.
+> **A comprehensive graph-native platform for code, knowledge, and collaboration.**
+> Trellis combines version control, semantic analysis, knowledge graphs, and intelligent automation into a unified system that treats every action as a first-class graph entity.
 
 ---
 
 ## Table of Contents
 
-- [Trellis Overview](#trellis-overview)
+- [Platform Overview](#platform-overview)
+- [Core Capabilities](#core-capabilities)
 - [Project Surfaces](#project-surfaces)
 - [Quick Start](#quick-start)
+- [Package Architecture](#package-architecture)
 - [CLI Overview](#cli-overview)
 - [VS Code Extension](#vs-code-extension)
 - [Module & Subpath Guide](#module--subpath-guide)
-- [Architecture Overview](#architecture-overview)
 - [Development & Releases](#development--releases)
 - [Roadmap](#roadmap)
 
 ---
 
-## Trellis Overview
+## Platform Overview
+
+Trellis is a comprehensive platform that unifies version control, knowledge management, semantic analysis, and intelligent automation. Built on a graph-native foundation, it treats every action—code changes, decisions, links, and embeddings—as first-class entities in a causal graph.
+
+The platform consists of multiple integrated surfaces:
+
+- **`trellis` npm package** — the published package exposing all platform APIs through modular subpaths
+- **`trellis` CLI** — command-line interface for repository management, semantic tooling, knowledge operations, and automation
+- **VS Code extension** — visual interface for timeline exploration, issue management, knowledge navigation, and collaborative features
+- **Core platform modules** — reusable building blocks for graph storage, semantic analysis, sync, knowledge graphs, embeddings, and decision traces
+
+### Core Capabilities
+
+#### 1. **Graph-Native Foundation**
+
+- **EAV Store** — Entity-Attribute-Value graph database with SQLite backend
+- **TrellisKernel** — Generic graph CRUD operations independent of VCS
+- **Query Engine** — EQL-S query language and Datalog evaluator
+- **Ontology System** — Schema validation and built-in ontologies
 
-Trellis is an umbrella project with a few distinct surfaces that all sit on the same underlying model:
+#### 2. **Advanced Version Control**
 
-- **`trellis` npm package** — the published package for engine APIs, subpath exports, and reusable modules.
-- **`trellis` CLI** — the command-line interface for repo setup, history, milestones, semantic diffing, and automation.
-- **VS Code extension** — the visual shell for status, issues, timeline, kanban, and wiki-link navigation.
-- **Core modules** — reusable building blocks for graph storage, semantic analysis, sync, links, embeddings, and decision traces.
+- **Causal Stream** — Immutable, content-addressed operations with causal chaining
+- **Semantic Patching** — AST-aware changes enabling conflict-free merges
+- **Narrative Milestones** — Human-readable checkpoints over continuous work streams
+- **Governance** — Op signing, identity management, and policy enforcement
 
-The core idea stays the same across all of them:
+#### 3. **Knowledge & Intelligence**
 
-1. **Causal Stream** — immutable, content-addressed ops linked by causal history.
-2. **Semantic Patching** — AST-aware changes instead of line-only diffs.
-3. **Narrative Milestones** — human checkpoints over a continuous stream of work.
-4. **Governance Subgraph** — signing, identities, and policy enforcement.
-5. **Idea Garden** — abandoned work detection and revival.
+- **Wiki-Links** — Bidirectional reference system for cross-linking entities
+- **Embeddings** — Semantic indexing and vector search for intelligent discovery
+- **Decision Traces** — Automated capture and querying of agent decisions
+- **Idea Garden** — Detection and revival of abandoned work clusters
+
+#### 4. **Collaboration & Sync**
+
+- **Peer Sync** — CRDT-based reconciliation with HTTP/WebSocket transports
+- **Multi-Repo Federation** — Cross-repository entity references and linking
+- **Agent System** — Tool registry and decision trace capture
+- **Plugin Architecture** — Extensible system with event bus and workspace config
 
 ## Project Surfaces
 
-| Surface               | Location                                                      | Purpose                                                            |
-| :-------------------- | :------------------------------------------------------------ | :----------------------------------------------------------------- |
-| **npm package**       | `package.json`, `src/`, `dist/`                               | Published as `trellis`; exposes engine APIs and subpath exports    |
-| **CLI**               | `src/cli/index.ts`                                            | Repository lifecycle, branch/milestone workflows, semantic tooling |
-| **VS Code extension** | `vscode-extension/`                                           | Timeline, kanban, issue browser, wiki-link UX                      |
-| **Core store**        | `src/core/`                                                   | Inlined EAV store, kernel persistence, middleware types            |
-| **Platform modules**  | `src/vcs/`, `src/links/`, `src/embeddings/`, `src/decisions/` | Reusable building blocks behind the product surfaces               |
+| Surface               | Location                                                      | Purpose                                                                  |
+| :-------------------- | :------------------------------------------------------------ | :----------------------------------------------------------------------- |
+| **npm package**       | `package.json`, `src/`, `dist/`                               | Published as `trellis`; exposes all platform APIs via subpaths           |
+| **CLI**               | `src/cli/index.ts`                                            | Repository lifecycle, semantic tooling, knowledge operations, automation |
+| **VS Code extension** | `vscode-extension/`                                           | Timeline, knowledge navigation, issue management, collaborative UX       |
+| **Core platform**     | `src/core/`                                                   | EAV store, kernel, ontology, query, agents, plugins                      |
+| **Platform modules**  | `src/vcs/`, `src/links/`, `src/embeddings/`, `src/decisions/` | Specialized subsystems for version control, knowledge, and intelligence  |
 
 ---
 
@@ -96,27 +113,35 @@ bun run src/cli/index.ts import --from /path/to/git-repo
 
 ---
 
-## Architecture Overview
+## Package Architecture
 
 ```
 trellis/
 ├── src/
-│   ├── core/              # EAV store + kernel types exposed as trellis/core
-│   ├── vcs/               # Ops, branches, milestones, checkpoints, diff, merge
-│   ├── git/               # Git import/export bridge
+│   ├── core/              # EAV store, kernel, ontology, query, agents, plugins
+│   │   ├── kernel/        # TrellisKernel with entity CRUD and middleware
+│   │   ├── ontology/      # Schema registry, validation, built-in ontologies
+│   │   ├── query/         # EQL-S query engine and Datalog evaluator
+│   │   ├── agents/        # Agent harness, tool registry, decision traces
+│   │   └── plugins/       # Plugin registry, event bus, workspace config
+│   ├── vcs/               # Version control: ops, branches, milestones, diff, merge
 │   ├── links/             # Wiki-link parsing, resolution, backlink index
-│   ├── embeddings/        # Semantic indexing and vector search
+│   ├── embeddings/        # Semantic indexing, vector search, auto-embed, RAG
 │   ├── decisions/         # Decision trace capture and querying
 │   ├── semantic/          # AST parsers, semantic diff, semantic merge
-│   ├── sync/              # Peer sync and reconciler
+│   ├── sync/              # Peer sync, CRDT reconciler, HTTP/WebSocket transports, multi-repo
+│   ├── garden/            # Idea Garden: abandoned work detection and revival
+│   ├── git/               # Git import/export bridge
+│   ├── identity/          # Ed25519 identity management and governance
 │   ├── watcher/           # File watching + ingestion pipeline
+│   ├── mcp/               # Model Context Protocol server integration
 │   ├── cli/               # CLI entrypoint
 │   ├── engine.ts          # Composition root
 │   └── index.ts           # Main package entrypoint
 ├── vscode-extension/      # VS Code extension surface
-├── test/                  # Phase and subsystem tests
-├── DESIGN.md              # Detailed architecture spec
-└── justfile               # Local build/release recipes
+├── test/                  # Comprehensive test suites
+├── DESIGN.md              # Detailed architecture specification
+└── justfile               # Local build and development recipes
 ```
 
 ### The Op Stream
@@ -218,20 +243,61 @@ trellis garden stats                                  # Garden statistics
 ```bash
 trellis sync status                       # Local sync state
 trellis sync reconcile --remote <path>    # Reconcile with another local repo
+trellis sync push --peer <id>             # Push ops to a peer (HTTP/WebSocket)
+trellis sync pull --peer <id>             # Pull ops from a peer
+trellis link-repo <alias> <location>      # Link a remote repo for cross-repo refs
+```
+
+### Query & Search
+
+```bash
+trellis query "find Project where status = 'active'"     # EQL-S structured query
+trellis query-repl                                        # Interactive query REPL
+trellis ask "authentication code"                         # Natural language semantic search
+trellis ask "show me auth code" --rag                    # Output as RAG context for LLMs
+```
+
+### Ontology
+
+```bash
+trellis ontology list                     # List registered ontologies
+trellis ontology show <id>                # Show ontology details
+trellis ontology validate                 # Validate store against ontologies
+```
+
+### Agents
+
+```bash
+trellis agent list                        # List registered agents
+trellis agent create <name>               # Create a new agent definition
+trellis agent run <id> --input "task"     # Execute an agent run
+trellis agent inspect <run-id>            # View run details and decision traces
+```
+
+### Plugins
+
+```bash
+trellis plugin list                       # List loaded plugins
+trellis plugin add <id>                   # Register and load a plugin
+trellis plugin remove <id>                # Unload and unregister a plugin
 ```
 
 ---
 
 ## VS Code Extension
 
-The VS Code extension is the visual surface for Trellis.
+The VS Code extension provides a rich visual interface for the entire Trellis platform, making knowledge navigation, collaboration, and project management intuitive and efficient.
+
+### Core Features
 
-- **Status view** — current branch, op count, tracked files, recent activity
-- **Causal stream** — browse ops as a readable event timeline
-- **Issues view** — inspect and manage issue state directly in the editor
-- **Kanban board** — move work across lifecycle stages visually
-- **Timeline panel** — inspect history as a richer interactive visualization
-- **Wiki-link UX** — click, hover, validate, and autocomplete `[[wiki-links]]`
+- **Status Dashboard** — Real-time view of repository health, activity metrics, and system state
+- **Causal Timeline** — Interactive exploration of the complete operation history with filtering and search
+- **Knowledge Navigator** — Browse and traverse the wiki-link graph with visual connections
+- **Issue Management** — Full lifecycle issue management with drag-and-drop workflow automation
+- **Semantic Explorer** — Navigate code structure and relationships through AST-aware visualizations
+- **Decision Inspector** — Review decision traces and understand the reasoning behind changes
+- **Collaboration Hub** — Multi-repo federation view and cross-project relationship mapping
+- **Intelligence Panel** — Semantic search, RAG context, and AI-powered insights
 
 The extension lives in [`vscode-extension/`](./vscode-extension) and publishes separately from the npm package.
 
@@ -239,7 +305,7 @@ The extension lives in [`vscode-extension/`](./vscode-extension) and publishes s
 
 ## Module & Subpath Guide
 
-The `trellis` package is intentionally split into subpaths so consumers can depend on the surface they actually need.
+The `trellis` package is intentionally split into subpaths so consumers can depend on the specific capabilities they need, from core graph operations to advanced AI features.
 
 ### Published Package Surface
 
@@ -248,88 +314,104 @@ bun add trellis
 ```
 
 ```typescript
-// Main entry — engine + top-level API
+// Main entry — full platform engine
 import { TrellisVcsEngine } from 'trellis';
 
-// Core store and kernel types
-import { EAVStore } from 'trellis/core';
-import type { Fact, Link } from 'trellis/core';
+// Core graph foundation (independent of VCS)
+import { EAVStore, TrellisKernel } from 'trellis/core';
+import type { Fact, Link, EntityRecord } from 'trellis/core';
 
-// VCS primitives
+// Version control primitives
 import type { VcsOp, VcsOpKind } from 'trellis/vcs';
 
-// Semantic search
+// Knowledge and intelligence
 import { EmbeddingManager } from 'trellis/ai';
-
-// Wiki-linking
 import { parseFileRefs, resolveRef, RefIndex } from 'trellis/links';
-
-// Decision traces
 import { recordDecision, queryDecisions } from 'trellis/decisions';
 ```
 
-### `trellis` — Engine Entry Point (`TrellisVcsEngine`)
+### `trellis` — Platform Engine (`TrellisVcsEngine`)
 
-The main entry point. Ties together the kernel, file watcher, op log, branches, milestones, identity, garden, semantic parser, and sync.
+The main entry point that orchestrates the entire platform: kernel, file watcher, version control, knowledge graphs, semantic analysis, and collaboration features.
 
 ```typescript
 import { TrellisVcsEngine } from 'trellis';
 
 const engine = new TrellisVcsEngine({ rootPath: '/my/project' });
 
-// New repo
+// Repository management
 await engine.initRepo();
-
-// Existing repo
 engine.open();
 
-// Core queries
-engine.getOps(); // All ops
+// Core operations
+engine.getOps(); // All operations
 engine.status(); // Branch, op count, files
-engine.log(); // Formatted op history
+engine.log(); // Formatted history
 engine.getFiles(); // Currently tracked files
 
-// Branches
+// Version control
 await engine.createBranch('feature/x');
-engine.switchBranch('feature/x');
-engine.listBranches();
-await engine.deleteBranch('feature/x');
-
-// Milestones
 await engine.createMilestone('Implement auth', { fromOpHash, toOpHash });
-engine.listMilestones();
 
-// Semantic parsing
+// Semantic analysis
 engine.parseFile(content, 'src/auth.ts');
 engine.semanticDiff(oldContent, newContent, 'src/auth.ts');
 
-// Idea Garden
+// Knowledge operations
 const garden = engine.garden();
 garden.listClusters();
 garden.search({ keyword: 'auth' });
-garden.revive(clusterId);
+
+// Intelligence features
+const embeddings = engine.embeddings();
+await embeddings.search('authentication flow');
 ```
 
-### `trellis/core` — Core Store
+### `trellis/core` — Graph Foundation
 
-The inlined core store layer exposes the EAV primitives and kernel-adjacent types that the rest of Trellis is built on.
+The core graph layer exposes EAV primitives, ontology schemas, query engine, agent harness, and plugin system. This module is independent of version control and can be used for any graph-based application.
 
 ```typescript
-import { EAVStore } from 'trellis/core';
-import type { Fact, Link, KernelOp } from 'trellis/core';
+import { EAVStore, TrellisKernel } from 'trellis/core';
+import { OntologyRegistry, builtinOntologies } from 'trellis/core';
+import { QueryEngine, parseQuery } from 'trellis/core';
+import { AgentHarness } from 'trellis/core';
+import { PluginRegistry, EventBus } from 'trellis/core';
+import type { Fact, Link, KernelOp, AgentDef, PluginDef } from 'trellis/core';
+
+// Graph operations
+const kernel = new TrellisKernel({ backend, agentId: 'me' });
+await kernel.createEntity('proj:1', 'Project', {
+  name: 'Trellis',
+  status: 'active',
+});
+
+// Ontology validation
+const registry = new OntologyRegistry();
+for (const o of builtinOntologies) registry.register(o);
 
-const store = new EAVStore();
+// Graph queries
+const query = parseQuery('find Project where status = "active"');
+const results = new QueryEngine(store).eval(query);
+
+// Agent orchestration
+const harness = new AgentHarness(kernel);
+await harness.createAgent({ name: 'Reviewer', status: 'active' });
+
+// Plugin system
+const plugins = new PluginRegistry();
+plugins.register({ id: 'my:plugin', name: 'My Plugin', version: '1.0.0' });
 ```
 
-### `trellis/vcs` — VCS Model
+### `trellis/vcs` — Version Control Model
 
-The VCS subpath exposes operation types and domain-level building blocks for branches, milestones, checkpoints, issues, diffing, merging, and blob storage.
+The VCS subpath exposes operation types and domain-level building blocks for version control: branches, milestones, checkpoints, issues, diffing, merging, and blob storage.
 
-Use this subpath when you want Trellis domain types and behavior without importing the full engine surface.
+Use this subpath when you want Trellis version control capabilities without the full platform surface.
 
-### `trellis/links` — Wiki-Link References
+### `trellis/links` — Knowledge Graph & Wiki-Links
 
-Parse `[[wiki-links]]` from markdown, doc-comments, and source files. Resolve references to issues, files, symbols, milestones, and decisions. Build a bidirectional reference index.
+Parse `[[wiki-links]]` from markdown, doc-comments, and source files. Resolve references to issues, files, symbols, milestones, and decisions. Build a bidirectional knowledge graph that connects all entities in your workspace.
 
 ```typescript
 import { parseFileRefs, resolveRef, RefIndex } from 'trellis/links';
@@ -339,11 +421,14 @@ const resolved = resolveRef(ref, context);
 const index = new RefIndex();
 index.indexFile('README.md', refs, context);
 index.getIncoming('issue:TRL-5');
+
+// Cross-repository references
+index.addCrossRepoLink('frontend', 'proj:app', 'backend', 'api:users');
 ```
 
-### `trellis/ai` — Embeddings & Semantic Search
+### `trellis/ai` — Semantic Intelligence
 
-Embed issues, milestones, files, code entities, and decisions into a vector store for semantic search.
+Advanced semantic capabilities: embed issues, milestones, files, code entities, and decisions into a vector store for intelligent search, discovery, and RAG (Retrieval-Augmented Generation).
 
 ```typescript
 import { EmbeddingManager } from 'trellis/ai';
@@ -351,11 +436,14 @@ import { EmbeddingManager } from 'trellis/ai';
 const manager = new EmbeddingManager(engine, { dbPath: 'embeddings.db' });
 await manager.reindex();
 const results = await manager.search('auth flow');
+
+// RAG context for LLMs
+const context = await manager.getRAGContext('authentication implementation');
 ```
 
-### `trellis/decisions` — Decision Traces
+### `trellis/decisions` — Decision Intelligence
 
-Automatically capture tool invocations as auditable decision records. Enrich them with rationale via hooks and query them later by tool, entity, or chain.
+Automatically capture tool invocations and agent decisions as auditable traces. Enrich them with rationale via hooks and query them later by tool, entity, or decision chain. Perfect for understanding how and why decisions were made.
 
 ```typescript
 import { recordDecision, queryDecisions } from 'trellis/decisions';
@@ -364,9 +452,12 @@ const dec = await recordDecision(ctx, {
   toolName: 'trellis_issue_create',
   input: { title: 'Add parser' },
   output: { id: 'TRL-5' },
+  rationale: 'Needed for TypeScript support',
 });
 
+// Query decision patterns
 const decs = queryDecisions(ctx, { tool: 'trellis_issue_*' });
+const chain = queryDecisions(ctx, { entity: 'TRL-5' }); // Full decision chain
 ```
 
 ### `src/garden/` — Idea Garden
@@ -384,6 +475,14 @@ garden.stats(); // { total, abandoned, draft, revived, totalOps, totalFiles }
 garden.revive('cluster:abc');
 ```
 
+### Platform Subsystem Guides
+
+The following sections provide detailed guides for Trellis' internal subsystems. These are useful if you're contributing to the platform or extending its capabilities.
+
+#### Knowledge Graph & Wiki-Links (`src/links/`)
+
+Builds a bidirectional knowledge graph from wiki-link references across all workspace entities.
+
 **Detection heuristics:**
 
 | Heuristic               | Trigger             | Signal                                                            |
@@ -392,29 +491,29 @@ garden.revive('cluster:abc');
 | `revertDetector`        | Complementary ops   | Ops undone by a subsequent inverse op (add→delete, modify→revert) |
 | `staleBranchDetector`   | Time + no milestone | Ops on non-`main` branches untouched >7 days without a milestone  |
 
-### `src/semantic/` — Semantic Patching
+#### Semantic Intelligence (`src/semantic/`)
 
-Parses TypeScript/JavaScript into structural entities and computes semantic diffs.
+Advanced TypeScript/JavaScript analysis with structural entity extraction and semantic diffing for intelligent code understanding.
 
 ```typescript
 import { typescriptParser, semanticMerge } from './src/semantic/index.js';
 
-// Parse
+// Parse code into structural entities
 const result = typescriptParser.parse(source, 'file.ts');
 result.declarations; // ASTEntity[] — functions, classes, interfaces, enums, …
 result.imports; // ImportRelation[]
 result.exports; // ExportRelation[]
 
-// Diff
+// Compute semantic differences
 const patches = typescriptParser.diff(oldResult, newResult);
 // SemanticPatch[] — symbolAdd | symbolRemove | symbolModify |
 //                   symbolRename | importAdd | importRemove | …
 
-// Merge (patch commutativity per DESIGN.md §4.4)
+// Intelligent merging with conflict resolution
 const merged = semanticMerge(ourPatches, theirPatches, 'file.ts');
 merged.clean; // true if no conflicts
 merged.patches; // Merged patch list
-merged.conflicts; // SemanticMergeConflict[] — entity-level, with suggestion
+merged.conflicts; // SemanticMergeConflict[] — entity-level, with suggestions
 ```
 
 ### `src/sync/` — Peer Sync
@@ -447,7 +546,55 @@ await engine.pullFrom('peer-b');
 engine.reconcileWith(remoteOps);
 ```
 
-These `src/*` sections are internal subsystem guides rather than published npm subpaths. They are useful if you are contributing to Trellis itself or navigating the codebase.
+#### Collaboration & Sync (`src/sync/`)
+
+Enterprise-grade synchronization with CRDT reconciliation, multiple transport protocols, and multi-repo federation for distributed teams.
+
+```typescript
+import {
+  SyncEngine,
+  MemoryTransport,
+  reconcile,
+  HttpSyncTransport,
+  WebSocketSyncTransport,
+  MultiRepoManager,
+  formatCrossRepoRef,
+} from './src/sync/index.js';
+
+// CRDT reconciler for conflict-free merging
+const result = reconcile(localOps, remoteOps);
+result.merged; // Interleaved by timestamp
+result.forkPoint; // Last common op hash
+result.conflicts; // File-level conflicts
+
+// HTTP transport for network sync
+const httpTransport = new HttpSyncTransport('peer-a');
+httpTransport.addPeer('peer-b', 'http://192.168.1.10:4200');
+
+// WebSocket transport for real-time collaboration
+const wsTransport = new WebSocketSyncTransport('peer-a');
+await wsTransport.connect('peer-b', 'ws://192.168.1.10:4201');
+
+// Multi-repo federation — connect knowledge across repositories
+const repoManager = new MultiRepoManager(kernel);
+await repoManager.linkRepo(
+  'backend',
+  '/path/to/backend-api',
+  'Backend service',
+);
+await repoManager.addCrossRepoLink(
+  'proj:frontend',
+  'dependsOn',
+  'backend',
+  'lib:api-client',
+);
+// Creates: proj:frontend --dependsOn--> @backend:lib:api-client
+
+// Discover cross-repository relationships
+const refs = repoManager.findReferencesTo('backend', 'lib:api-client');
+```
+
+These subsystem guides provide insight into Trellis' internal architecture. They're particularly useful for platform contributors, extenders, or those building custom integrations.
 
 ---
 
@@ -513,14 +660,20 @@ Engine A sends 'have' { heads: { main: 'h42' }, opCount: 42 }
 
 ## Design Doc
 
-See [`DESIGN.md`](./DESIGN.md) for the full architecture specification, including:
+See [`DESIGN.md`](./DESIGN.md) for the complete platform architecture specification, including:
 
 - §3 — Causal stream and branch concurrency model
-- §4 — Semantic patching: parser adapter interface, patch types, commutativity table
+- §4 — Semantic patching: parser adapter interface, patch types, commutativity
 - §5 — Milestone narrative model
 - §6 — Identity, signing, and governance
 - §7 — Idea Garden cluster detection heuristics
-- §10 — Open questions and architectural trade-offs
+- §8 — Knowledge graph and wiki-link system
+- §9 — Embeddings and semantic search architecture
+- §10 — Decision trace capture and querying
+- §11 — Sync protocols and multi-repo federation
+- §12 — Core graph kernel and ontology system
+- §13 — Agent harness and plugin architecture
+- §14 — Open questions and architectural trade-offs
 
 ---
 
@@ -575,23 +728,33 @@ just publish-dry-run
 just publish
 ```
 
-> **Requires [Bun](https://bun.sh) ≥ 1.0** — Trellis uses `bun:sqlite` for the vector store and Bun's native TS support.
+> **Requires [Bun](https://bun.sh) ≥ 1.0** — Trellis uses `bun:sqlite` for the vector store and Bun's native TypeScript support for optimal performance.
 
 ---
 
 ## Roadmap
 
-| Phase | Deliverable                                     | Status | Commit    |
-| :---- | :---------------------------------------------- | :----- | :-------- |
-| P0    | Causal stream + CLI                             | ✅     | `51475d3` |
-| P0.5  | VS Code extension / visual timeline             | ✅     | `947d5a1` |
-| P1    | Git import bridge                               | ✅     | `f4cc4a6` |
-| P2    | Branches, milestones, checkpoints               | ✅     | `3f91e9a` |
-| P2.5  | Blob store, engine modularization, git exporter | ✅     | `5c43a31` |
-| P3    | File-level diff + text-based merge              | ✅     | `c953654` |
-| P4    | Identity + op signing + governance              | ✅     | `3acddda` |
-| P5    | Idea Garden — cluster detection + query         | ✅     | `105a207` |
-| P6    | Semantic patching — parser adapter + diff/merge | ✅     | `22192ae` |
-| P7    | Peer sync + CRDT reconciler                     | ✅     | `d02f3f7` |
-| P8    | Wiki-links, embeddings, decision traces         | ✅     | `b9cd5b7` |
-| P9    | npm package + VSCode extension publish          | 🚧     |           |
+| Phase | Deliverable                                        | Status | Commit      |
+| :---- | :------------------------------------------------- | :----- | :---------- |
+| P0    | Causal stream + CLI                                | ✅     | `51475d3`   |
+| P0.5  | VS Code extension / visual timeline                | ✅     | `947d5a1`   |
+| P1    | Git import bridge                                  | ✅     | `f4cc4a6`   |
+| P2    | Branches, milestones, checkpoints                  | ✅     | `3f91e9a`   |
+| P2.5  | Blob store, engine modularization, git exporter    | ✅     | `5c43a31`   |
+| P3    | File-level diff + text-based merge                 | ✅     | `c953654`   |
+| P4    | Identity + op signing + governance                 | ✅     | `3acddda`   |
+| P5    | Idea Garden — cluster detection + query            | ✅     | `105a207`   |
+| P6    | Semantic patching — parser adapter + diff/merge    | ✅     | `22192ae`   |
+| P7    | Peer sync + CRDT reconciler                        | ✅     | `d02f3f7`   |
+| P8    | Wiki-links, embeddings, decision traces            | ✅     | `b9cd5b7`   |
+| P9    | npm package + VSCode extension publish             | ✅     | `57bad37`   |
+| P10   | Graph kernel + SQLite backend + entity CRUD        | ✅     |             |
+| P11   | EQL-S query engine + Datalog evaluator             | ✅     |             |
+| P12   | Ontology system + validation middleware            | ✅     |             |
+| P13   | Transformers.js upgrade + auto-embed + RAG         | ✅     |             |
+| P14   | Agent harness + tool registry + decision traces    | ✅     |             |
+| P15   | Plugin system + event bus + workspace config       | ✅     |             |
+| P16   | Sync federation + multi-repo linking               | ✅     |             |
+| P17   | Advanced knowledge graph + cross-repo intelligence | 🚧     | In Progress |
+| P18   | Enterprise collaboration features + RBAC           | 📋     | Planned     |
+| P19   | Advanced AI capabilities + intelligent automation  | 📋     | Planned     |

package/dist/core/index.js

@@ -32,6 +32,7 @@ class AgentHarness {
   kernel;
   toolHandlers = new Map;
   config;
+  runCounter = 0;
   constructor(kernel, config) {
     this.kernel = kernel;
     this.config = {
@@ -114,7 +115,7 @@ class AgentHarness {
     const agent = this.getAgent(agentId);
     if (!agent)
       throw new Error(`Agent "${agentId}" not found.`);
-    const runId = `run:${agentId.replace("agent:", "")}:${Date.now()}`;
+    const runId = `run:${agentId.replace("agent:", "")}:${Date.now()}:${++this.runCounter}`;
     await this.kernel.createEntity(runId, "AgentRun", {
       startedAt: new Date().toISOString(),
       status: "running",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trellis",
-  "version": "2.0.10",
-  "description": "Graph-native, code-first version control system — causal ops, semantic patching, wiki-links, embeddings, and decision traces",
+  "version": "2.1.1",
+  "description": "A comprehensive graph-native platform for code, knowledge, and collaboration — version control, semantic analysis, knowledge graphs, embeddings, and decision traces",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./src/index.ts",
@@ -21,6 +21,10 @@
     "ast",
     "wiki-links",
     "embeddings",
+    "knowledge-graph",
+    "decision-traces",
+    "collaboration",
+    "sync",
     "causal",
     "bun"
   ],

package/src/core/agents/harness.ts

@@ -27,6 +27,7 @@ export class AgentHarness {
   private kernel: TrellisKernel;
   private toolHandlers: Map<string, ToolHandler> = new Map();
   private config: AgentHarnessConfig;
+  private runCounter: number = 0;
 
   constructor(kernel: TrellisKernel, config?: AgentHarnessConfig) {
     this.kernel = kernel;
@@ -41,11 +42,13 @@ export class AgentHarness {
   // Agent CRUD (via kernel entities)
   // -------------------------------------------------------------------------
 
-  async createAgent(def: Omit<AgentDef, 'id' | 'capabilities' | 'tools'> & {
-    id?: string;
-    capabilities?: string[];
-    tools?: string[];
-  }): Promise<AgentDef> {
+  async createAgent(
+    def: Omit<AgentDef, 'id' | 'capabilities' | 'tools'> & {
+      id?: string;
+      capabilities?: string[];
+      tools?: string[];
+    },
+  ): Promise<AgentDef> {
     const id = def.id ?? `agent:${def.name.toLowerCase().replace(/\s+/g, '-')}`;
     await this.kernel.createEntity(id, 'Agent', {
       name: def.name,
@@ -84,18 +87,29 @@ export class AgentHarness {
     return {
       id: entity.id,
       name: String(entity.facts.find((f) => f.a === 'name')?.v ?? ''),
-      description: entity.facts.find((f) => f.a === 'description')?.v as string | undefined,
+      description: entity.facts.find((f) => f.a === 'description')?.v as
+        | string
+        | undefined,
       model: entity.facts.find((f) => f.a === 'model')?.v as string | undefined,
-      provider: entity.facts.find((f) => f.a === 'provider')?.v as string | undefined,
-      systemPrompt: entity.facts.find((f) => f.a === 'systemPrompt')?.v as string | undefined,
-      status: (entity.facts.find((f) => f.a === 'status')?.v as AgentDef['status']) ?? 'active',
+      provider: entity.facts.find((f) => f.a === 'provider')?.v as
+        | string
+        | undefined,
+      systemPrompt: entity.facts.find((f) => f.a === 'systemPrompt')?.v as
+        | string
+        | undefined,
+      status:
+        (entity.facts.find((f) => f.a === 'status')?.v as AgentDef['status']) ??
+        'active',
       capabilities: capLinks.map((l) => l.e2),
       tools: toolLinks.map((l) => l.e2),
     };
   }
 
   listAgents(status?: AgentDef['status']): AgentDef[] {
-    const entities = this.kernel.listEntities('Agent', status ? { status } : undefined);
+    const entities = this.kernel.listEntities(
+      'Agent',
+      status ? { status } : undefined,
+    );
     return entities
       .map((e) => this.getAgent(e.id))
       .filter((a): a is AgentDef => a !== null);
@@ -105,7 +119,10 @@ export class AgentHarness {
   // Tool registration
   // -------------------------------------------------------------------------
 
-  async registerTool(def: Omit<ToolDef, 'id'> & { id?: string }, handler: ToolHandler): Promise<string> {
+  async registerTool(
+    def: Omit<ToolDef, 'id'> & { id?: string },
+    handler: ToolHandler,
+  ): Promise<string> {
     const id = def.id ?? `tool:${def.name.toLowerCase().replace(/\s+/g, '-')}`;
 
     // Create tool entity if it doesn't exist
@@ -130,9 +147,13 @@ export class AgentHarness {
     return this.kernel.listEntities('Tool').map((e) => ({
       id: e.id,
       name: String(e.facts.find((f) => f.a === 'name')?.v ?? ''),
-      description: e.facts.find((f) => f.a === 'description')?.v as string | undefined,
+      description: e.facts.find((f) => f.a === 'description')?.v as
+        | string
+        | undefined,
       schema: e.facts.find((f) => f.a === 'schema')?.v as string | undefined,
-      endpoint: e.facts.find((f) => f.a === 'endpoint')?.v as string | undefined,
+      endpoint: e.facts.find((f) => f.a === 'endpoint')?.v as
+        | string
+        | undefined,
     }));
   }
 
@@ -144,7 +165,8 @@ export class AgentHarness {
     const agent = this.getAgent(agentId);
     if (!agent) throw new Error(`Agent "${agentId}" not found.`);
 
-    const runId = `run:${agentId.replace('agent:', '')}:${Date.now()}`;
+    // Ensure unique run IDs even when called in rapid succession
+    const runId = `run:${agentId.replace('agent:', '')}:${Date.now()}:${++this.runCounter}`;
     await this.kernel.createEntity(runId, 'AgentRun', {
       startedAt: new Date().toISOString(),
       status: 'running',
@@ -155,7 +177,11 @@ export class AgentHarness {
     return runId;
   }
 
-  async completeRun(runId: string, output?: string, tokenCount?: number): Promise<void> {
+  async completeRun(
+    runId: string,
+    output?: string,
+    tokenCount?: number,
+  ): Promise<void> {
     const updates: Record<string, any> = {
       status: 'completed',
       completedAt: new Date().toISOString(),
@@ -183,8 +209,12 @@ export class AgentHarness {
 
     // Get decisions for this run
     const decisionLinks = store.getLinksByAttribute('belongsToRun');
-    const decisionIds = decisionLinks.filter((l) => l.e2 === runId).map((l) => l.e1);
-    const decisions = decisionIds.map((did) => this._buildDecisionTrace(did)).filter(Boolean) as DecisionTrace[];
+    const decisionIds = decisionLinks
+      .filter((l) => l.e2 === runId)
+      .map((l) => l.e1);
+    const decisions = decisionIds
+      .map((did) => this._buildDecisionTrace(did))
+      .filter(Boolean) as DecisionTrace[];
 
     const get = (a: string) => entity.facts.find((f) => f.a === a)?.v;
 
@@ -207,7 +237,10 @@ export class AgentHarness {
       .map((e) => this.getRun(e.id))
       .filter((r): r is AgentRun => r !== null)
       .filter((r) => !agentId || r.agentId === agentId)
-      .sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+      .sort(
+        (a, b) =>
+          new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime(),
+      );
   }
 
   // -------------------------------------------------------------------------
@@ -235,7 +268,9 @@ export class AgentHarness {
       ...(input ? { input: JSON.stringify(input) } : {}),
       ...(output ? { output } : {}),
       ...(opts?.rationale ? { rationale: opts.rationale } : {}),
-      ...(opts?.alternatives ? { alternatives: JSON.stringify(opts.alternatives) } : {}),
+      ...(opts?.alternatives
+        ? { alternatives: JSON.stringify(opts.alternatives) }
+        : {}),
     });
 
     // Link decision to run and agent
@@ -262,7 +297,8 @@ export class AgentHarness {
     opts?: { rationale?: string; relatedEntities?: string[] },
   ): Promise<ToolResult> {
     const handler = this.toolHandlers.get(toolId);
-    if (!handler) throw new Error(`No handler registered for tool "${toolId}".`);
+    if (!handler)
+      throw new Error(`No handler registered for tool "${toolId}".`);
 
     const result = await handler(input);
 
@@ -311,13 +347,21 @@ export class AgentHarness {
     let inputParsed: Record<string, unknown> | undefined;
     const inputRaw = get('input') as string | undefined;
     if (inputRaw) {
-      try { inputParsed = JSON.parse(inputRaw); } catch { inputParsed = { raw: inputRaw }; }
+      try {
+        inputParsed = JSON.parse(inputRaw);
+      } catch {
+        inputParsed = { raw: inputRaw };
+      }
     }
 
     let alternatives: string[] | undefined;
     const altRaw = get('alternatives') as string | undefined;
     if (altRaw) {
-      try { alternatives = JSON.parse(altRaw); } catch { alternatives = [altRaw]; }
+      try {
+        alternatives = JSON.parse(altRaw);
+      } catch {
+        alternatives = [altRaw];
+      }
     }
 
     return {