trellis 2.0.5 → 2.0.6

package/README.md

@@ -1,13 +1,13 @@
 <p align="center">
-  <img src="logo.png" alt="TrellisVCS" width="128" />
+  <img src="logo.png" alt="Trellis" width="128" />
 </p>
 
-# TrellisVCS
+# 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.
 
-TrellisVCS is a from-scratch VCS built on five pillars:
+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.
@@ -19,23 +19,69 @@ TrellisVCS is a from-scratch VCS built on five pillars:
 
 ## Table of Contents
 
+- [Trellis Overview](#trellis-overview)
+- [Project Surfaces](#project-surfaces)
 - [Quick Start](#quick-start)
-- [Architecture](#architecture)
-- [CLI Reference](#cli-reference)
-- [Module Guide](#module-guide)
-- [How It Works](#how-it-works)
-- [Design Doc](#design-doc)
-- [Development](#development)
+- [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
+
+Trellis is an umbrella project with a few distinct surfaces that all sit on the same underlying model:
+
+- **`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.
+
+The core idea stays the same across all of them:
+
+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.
+
+## 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               |
 
 ---
 
 ## Quick Start
 
+### Use the npm package
+
+```bash
+bun add trellis
+```
+
+```typescript
+import { TrellisVcsEngine } from 'trellis';
+
+const engine = new TrellisVcsEngine({ rootPath: '/my/project' });
+engine.open();
+```
+
+### Work on the repo locally
+
 ```bash
 # Install dependencies
 bun install
 
-# Initialize a new TrellisVCS repo in the current directory
+# Initialize a new Trellis repo in the current directory
 bun run src/cli/index.ts init
 
 # Watch for file changes (continuous op stream)
@@ -50,77 +96,32 @@ bun run src/cli/index.ts import --from /path/to/git-repo
 
 ---
 
-## Architecture
+## Architecture Overview
 
 ```
-TrellisVCS/
+trellis/
 ├── src/
-│   ├── vcs/               # Core op types, constructors, decomposition
-│   │   ├── types.ts       # VcsOp, VcsOpKind (16 kinds), VcsPayload
-│   │   ├── ops.ts         # createVcsOp() — SHA-256 content-addressed ops
-│   │   ├── decompose.ts   # VcsOp → EAV graph facts
-│   │   ├── branch.ts      # Branch create/switch/list/delete
-│   │   ├── milestone.ts   # Milestone creation with op-range tracking
-│   │   ├── checkpoint.ts  # Auto/manual checkpoints
-│   │   ├── diff.ts        # File-level diff (file state at op)
-│   │   ├── merge.ts       # Three-way merge engine
-│   │   ├── blob-store.ts  # Content-addressed blob storage (SHA-256)
-│   │   └── vcs-middleware.ts  # Middleware plug for trellis-core kernel
-│   │
-│   ├── git/               # Git interop bridge
-│   │   ├── git-reader.ts      # Read commits, file changes, history
-│   │   ├── git-importer.ts    # Git → TrellisVCS (milestones + file ops)
-│   │   └── git-exporter.ts    # TrellisVCS milestones → Git commits
-│   │
-│   ├── identity/          # Cryptographic identity + governance
-│   │   ├── identity.ts            # Ed25519 keypair + DID generation
-│   │   ├── signing-middleware.ts  # Op signing middleware
-│   │   └── governance.ts          # Policy rules + enforcement
-│   │
-│   ├── garden/            # Idea Garden — abandoned work detection
-│   │   ├── cluster.ts     # IdeaCluster types + 3 detection heuristics
-│   │   └── garden.ts      # IdeaGarden query class (search, revive, stats)
-│   │
-│   ├── semantic/          # AST-level semantic patching
-│   │   ├── types.ts           # ParserAdapter, ASTEntity, SemanticPatch (11 kinds)
-│   │   ├── ts-parser.ts       # TypeScript/JS structural parser adapter
-│   │   └── semantic-merge.ts  # Patch commutativity + merge engine
-│   │
-│   ├── sync/              # Peer sync + CRDT reconciler
-│   │   ├── types.ts             # PeerId, SyncMessage, BranchPolicy
-│   │   ├── reconciler.ts        # Fork detection + op stream merging
-│   │   ├── sync-engine.ts       # Push/pull protocol, linear/CRDT modes
-│   │   └── memory-transport.ts  # In-memory transport for testing
-│   │
-│   ├── watcher/           # Filesystem monitoring
-│   │   ├── fs-watcher.ts  # Bun fs.watch wrapper with debounce + SHA-256
-│   │   └── ingestion.ts   # FileChangeEvent → VcsOp pipeline
-│   │
-│   ├── cli/
-│   │   └── index.ts       # 15+ CLI commands (Commander.js)
-│   │
-│   ├── engine.ts          # Composition root — ties everything together
-│   └── index.ts           # Public API surface
-│
-├── test/
-│   ├── vcs/               # Op creation, decomposition
-│   ├── git/               # Git reader, importer, exporter
-│   ├── p2/                # Branches, milestones, checkpoints
-│   ├── p3/                # Diff, merge
-│   ├── p4/                # Identity, signing, governance
-│   ├── p5/                # Idea Garden clusters
-│   ├── p6/                # Semantic parser + merge
-│   ├── p7/                # CRDT reconciler + sync engine
-│   └── engine.test.ts     # Integration tests
-│
-├── trellis-core/          # Kernel dependency (source-linked)
-├── DESIGN.md              # Full architecture specification
-└── PILLARS.md             # Design philosophy
+│   ├── core/              # EAV store + kernel types exposed as trellis/core
+│   ├── vcs/               # Ops, branches, milestones, checkpoints, diff, merge
+│   ├── git/               # Git import/export bridge
+│   ├── links/             # Wiki-link parsing, resolution, backlink index
+│   ├── embeddings/        # Semantic indexing and vector search
+│   ├── decisions/         # Decision trace capture and querying
+│   ├── semantic/          # AST parsers, semantic diff, semantic merge
+│   ├── sync/              # Peer sync and reconciler
+│   ├── watcher/           # File watching + ingestion pipeline
+│   ├── 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
 ```
 
 ### The Op Stream
 
-Every action in TrellisVCS is an immutable `VcsOp`:
+Every action in Trellis is an immutable `VcsOp`:
 
 ```typescript
 interface VcsOp {
@@ -146,7 +147,9 @@ Ops are written to `.trellis/ops.json` and replayed into an in-memory EAV graph
 
 ---
 
-## CLI Reference
+## CLI Overview
+
+The CLI is the operational surface for Trellis repositories. It is the fastest way to initialize repos, inspect history, create milestones, diff/merge work, and script automation around the op stream.
 
 ### Repository Setup
 
@@ -219,14 +222,58 @@ trellis sync reconcile --remote <path>    # Reconcile with another local repo
 
 ---
 
-## Module Guide
+## VS Code Extension
+
+The VS Code extension is the visual surface for Trellis.
+
+- **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]]`
+
+The extension lives in [`vscode-extension/`](./vscode-extension) and publishes separately from the npm package.
+
+---
+
+## Module & Subpath Guide
+
+The `trellis` package is intentionally split into subpaths so consumers can depend on the surface they actually need.
 
-### `TrellisVcsEngine`
+### Published Package Surface
+
+```bash
+bun add trellis
+```
+
+```typescript
+// Main entry — engine + top-level API
+import { TrellisVcsEngine } from 'trellis';
+
+// Core store and kernel types
+import { EAVStore } from 'trellis/core';
+import type { Fact, Link } from 'trellis/core';
+
+// VCS primitives
+import type { VcsOp, VcsOpKind } from 'trellis/vcs';
+
+// Semantic search
+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`)
 
 The main entry point. Ties together the kernel, file watcher, op log, branches, milestones, identity, garden, semantic parser, and sync.
 
 ```typescript
-import { TrellisVcsEngine } from 'trellisvcs';
+import { TrellisVcsEngine } from 'trellis';
 
 const engine = new TrellisVcsEngine({ rootPath: '/my/project' });
 
@@ -263,6 +310,65 @@ garden.search({ keyword: 'auth' });
 garden.revive(clusterId);
 ```
 
+### `trellis/core` — Core Store
+
+The inlined core store layer exposes the EAV primitives and kernel-adjacent types that the rest of Trellis is built on.
+
+```typescript
+import { EAVStore } from 'trellis/core';
+import type { Fact, Link, KernelOp } from 'trellis/core';
+
+const store = new EAVStore();
+```
+
+### `trellis/vcs` — VCS Model
+
+The VCS subpath exposes operation types and domain-level building blocks for 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.
+
+### `trellis/links` — Wiki-Link References
+
+Parse `[[wiki-links]]` from markdown, doc-comments, and source files. Resolve references to issues, files, symbols, milestones, and decisions. Build a bidirectional reference index.
+
+```typescript
+import { parseFileRefs, resolveRef, RefIndex } from 'trellis/links';
+
+const refs = parseFileRefs('src/engine.ts', source);
+const resolved = resolveRef(ref, context);
+const index = new RefIndex();
+index.indexFile('README.md', refs, context);
+index.getIncoming('issue:TRL-5');
+```
+
+### `trellis/ai` — Embeddings & Semantic Search
+
+Embed issues, milestones, files, code entities, and decisions into a vector store for semantic search.
+
+```typescript
+import { EmbeddingManager } from 'trellis/ai';
+
+const manager = new EmbeddingManager(engine, { dbPath: 'embeddings.db' });
+await manager.reindex();
+const results = await manager.search('auth flow');
+```
+
+### `trellis/decisions` — Decision Traces
+
+Automatically capture tool invocations as auditable decision records. Enrich them with rationale via hooks and query them later by tool, entity, or chain.
+
+```typescript
+import { recordDecision, queryDecisions } from 'trellis/decisions';
+
+const dec = await recordDecision(ctx, {
+  toolName: 'trellis_issue_create',
+  input: { title: 'Add parser' },
+  output: { id: 'TRL-5' },
+});
+
+const decs = queryDecisions(ctx, { tool: 'trellis_issue_*' });
+```
+
 ### `src/garden/` — Idea Garden
 
 Detects abandoned work using three heuristics, then exposes a query API.
@@ -341,6 +447,8 @@ 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.
+
 ---
 
 ## How It Works
@@ -416,7 +524,7 @@ See [`DESIGN.md`](./DESIGN.md) for the full architecture specification, includin
 
 ---
 
-## Development
+## Development & Releases
 
 ### Prerequisites
 
@@ -432,13 +540,12 @@ bun install
 ### Test
 
 ```bash
+just test-core
+# or run the full suite when working on those areas:
 bun test
-# Run a specific phase:
-bun test test/p6
-bun test test/p7
 ```
 
-**266 tests across 21 files, all passing.**
+**The release flow currently validates against the targeted passing core suite.**
 
 ### Typecheck
 
@@ -458,94 +565,17 @@ bun run src/cli/index.ts <command>
 
 ---
 
-## npm Package
-
-### Install
+### Release Workflow
 
 ```bash
-bun add trellis
-```
-
-> **Requires [Bun](https://bun.sh) ≥ 1.0** — TrellisVCS uses `bun:sqlite` for the vector store and Bun's native TS support.
+# Validate locally without publishing
+just publish-dry-run
 
-### Subpath Exports
-
-```typescript
-// Main entry — engine + core VCS types
-import { TrellisVcsEngine } from 'trellis';
-
-// Core — EAV store, kernel types
-import { EAVStore } from 'trellis/core';
-import type { Fact, Link } from 'trellis/core';
-
-// VCS — ops, branches, milestones, issues, diff, merge
-import type { VcsOp, VcsOpKind } from 'trellis/vcs';
-
-// AI — semantic embeddings + vector search
-import { EmbeddingManager, VectorStore } from 'trellis/ai';
-
-// Links — wiki-link parser, resolver, ref index
-import { parseFileRefs, resolveRef, RefIndex } from 'trellis/links';
-
-// Decisions — decision trace recording + queries
-import { recordDecision, queryDecisions } from 'trellis/decisions';
+# Publish to npm locally, then tag/push/create release metadata
+just publish
 ```
 
----
-
-## New Modules
-
-### `src/links/` — Wiki-Link References
-
-Parse `[[wiki-links]]` from markdown, doc-comments, and source files. Resolve references to issues, files, symbols, milestones, and decisions. Build a bidirectional reference index.
-
-```typescript
-import { parseFileRefs, resolveRef, RefIndex } from 'trellis/links';
-
-// Parse wiki-links from a file
-const refs = parseFileRefs('src/engine.ts', source);
-// → [{ raw: '[[TRL-5]]', namespace: 'issue', target: 'TRL-5', ... }]
-
-// Resolve a reference
-const resolved = resolveRef(ref, context);
-// → { state: 'resolved', title: 'Add Python parser', uri: '...' }
-
-// Build bidirectional index
-const index = new RefIndex();
-index.indexFile('README.md', refs, context);
-index.getIncoming('issue:TRL-5'); // All files that reference TRL-5
-```
-
-### `src/embeddings/` — Semantic Search
-
-Embed issues, milestones, files, code entities, and decisions into a vector store for semantic search.
-
-```typescript
-import { EmbeddingManager } from 'trellis/ai';
-
-const manager = new EmbeddingManager(engine, { dbPath: 'embeddings.db' });
-await manager.reindex(); // Index all content
-const results = await manager.search('auth flow'); // Semantic search
-// → [{ id: 'issue:TRL-5', content: '...', score: 0.87 }]
-```
-
-### `src/decisions/` — Decision Traces
-
-Automatically capture tool invocations as auditable decision records. Enrich with rationale via pre/post hooks.
-
-```typescript
-import { recordDecision, queryDecisions } from 'trellis/decisions';
-
-// Record a decision
-const dec = await recordDecision(ctx, {
-  toolName: 'trellis_issue_create',
-  input: { title: 'Add parser' },
-  output: { id: 'TRL-5' },
-});
-
-// Query decisions
-const decs = queryDecisions(ctx, { tool: 'trellis_issue_*' });
-```
+> **Requires [Bun](https://bun.sh) ≥ 1.0** — Trellis uses `bun:sqlite` for the vector store and Bun's native TS support.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trellis",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Graph-native, code-first version control system — causal ops, semantic patching, wiki-links, embeddings, and decision traces",
   "type": "module",
   "main": "./dist/index.js",