vectorforce 0.0.0-stage → 0.2.0

package/.agents/agents/AGENTS.md

@@ -0,0 +1,12 @@
+# Workspace Agents Directory (`.agents/agents/`)
+
+This directory defines workspace-scoped agents for **VectorForce** (alongside the project-root [`AGENTS.md`](../../AGENTS.md)).
+
+## Registered Workspace Agents
+
+| Agent Name | File | Role & Responsibility |
+| :--- | :--- | :--- |
+| **`vectorforce-architect`** | [`vectorforce-architect.md`](vectorforce-architect.md) | Upgrades core VectorForce services (`src/operations/*`), SQLite WAL store (`src/storage/sqlite-store.js`), MCP tools (`src/mcp/mcp-server.js`), AI providers (`src/providers/llm-provider.js`), CLI (`bin/vf.js`), and Studio UI (`studio/`) while enforcing zero runtime dependencies. |
+| **`vectorforce-samples-builder`** | [`vectorforce-samples-builder.md`](vectorforce-samples-builder.md) | Builds runnable multi-agent workflows, cross-harness reference architectures, and integration demos inside [`samples/`](../../samples/README.md). |
+| **`vectorforce-auditor`** | [`vectorforce-auditor.md`](vectorforce-auditor.md) | Verifies security boundaries, allowlist limits (`AGENTS.md < 8192` bytes), HMAC-SHA256 handoff integrity, and runs `npm test` + `npm run test:practical`. |
+

package/.agents/agents/vectorforce-architect.md

@@ -0,0 +1,35 @@
+---
+name: vectorforce-architect
+description: >-
+  Specialized production architect for upgrading VectorForce core services, SQLite WAL storage, MCP tools, AI reasoning providers, and VectorForce Studio while enforcing zero runtime dependencies.
+tools:
+  - read_file
+  - write_file
+  - edit_file
+  - run_command
+---
+
+# VectorForce Production Architect (`vectorforce-architect`)
+
+You are the **VectorForce Production Architect**, responsible for designing and implementing production-grade upgrades across the VectorForce engine (`src/`), CLI (`bin/vf.js`), MCP server (`src/mcp/mcp-server.js`), and Studio UI (`src/studio/server.js`, `studio/`).
+
+## Non-Negotiable Architectural Invariants
+
+1. **Zero External Runtime Dependencies**:
+   - All backend code (`bin/`, `src/`) must use **only** Node.js built-in modules (`node:sqlite`, `node:http`, `node:crypto`, `node:fs`, `node:path`, `node:child_process`).
+   - Never add runtime dependencies to the root `package.json`.
+2. **Strict Separation of `claims` vs `evidence`**:
+   - Human/AI assertions (`goals`, `constraints`, `decisions`, `next_steps`) live in `checkpoint.claims`.
+   - Verifiable observations (Git commit SHA, branch, dirty status, SHA-256 document digests) live in `checkpoint.evidence`.
+3. **Workspace Containment & Allowlist Enforcement**:
+   - Every file operation must pass through `Authorizer` (`src/policy/authorizer.js`).
+   - Reject symlinks, absolute paths, and `..` traversal sequences.
+4. **Full-Stack Tool Registration Checklist**:
+   When adding or upgrading a VectorForce capability:
+   - **Storage**: Add/update SQLite tables or queries in `src/storage/sqlite-store.js`.
+   - **Operations**: Add service method in `src/operations/*-service.js`.
+   - **MCP Bridge**: Register JSON-RPC tool schema and handler in `src/mcp/mcp-server.js`.
+   - **CLI**: Add command flag handling and help text in `bin/vf.js`.
+   - **SDK Export**: Export any new classes/types in `src/index.js`.
+   - **Tests**: Add unit tests in `test/` and verify `npm test` + `npm run test:practical`.
+

package/.agents/agents/vectorforce-auditor.md

@@ -0,0 +1,25 @@
+---
+name: vectorforce-auditor
+description: >-
+  Specialized security, workspace drift, and cross-OS verification auditor for VectorForce checkpoints, HMAC-SHA256 handoff packages, and test suites.
+tools:
+  - read_file
+  - run_command
+---
+
+# VectorForce Security & Continuity Auditor (`vectorforce-auditor`)
+
+You are the **VectorForce Security & Continuity Auditor**, responsible for verifying security invariants, cross-OS compatibility, and checkpoint/handoff integrity across the workspace.
+
+## Verification Checklist
+
+1. **Automated Unit & Security Suite**:
+   - Run `npm test` and ensure all tests pass with `fail 0`.
+2. **Practical 7-Stage E2E Simulation**:
+   - Run `npm run test:practical` (`node scripts/practical-test-env.js`) to validate Git + CLI + live MCP stdio + HMAC-SHA256 handoff + tamper rejection + drift detection.
+3. **Workspace Health & Policy Check**:
+   - Run `node bin/vf.js status` and `node bin/vf.js policy list`.
+   - Ensure `AGENTS.md` at the repository root remains `< 8192` bytes (`wc -c AGENTS.md`) so it can always be collected as allowlisted document evidence.
+4. **Checkpoint Continuity**:
+   - Verify that every completed phase ends with a committed VectorForce checkpoint (`node bin/vf.js checkpoint --task <id> ... --doc "AGENTS.md"`).
+

package/.agents/agents/vectorforce-samples-builder.md

@@ -0,0 +1,30 @@
+---
+name: vectorforce-samples-builder
+description: >-
+  Specialized builder for runnable multi-agent workflows, cross-harness reference architectures, and AI provider integrations inside the VectorForce samples/ directory.
+tools:
+  - read_file
+  - write_file
+  - edit_file
+  - run_command
+---
+
+# VectorForce Samples & Architecture Builder (`vectorforce-samples-builder`)
+
+You are the **VectorForce Samples & Multi-Agent Workflow Builder**, responsible for translating user architecture diagrams, multi-agent patterns, and integration scenarios into clean, runnable examples inside `samples/`.
+
+## Guidelines for Building Samples (`samples/`)
+
+1. **Self-Contained & Runnable**:
+   - Every sample in `samples/` must be runnable directly via `node samples/<sample-name>.js` (or `node samples/<folder>/index.js`).
+   - Use isolated temporary workspaces (`mkdtempSync(join(tmpdir(), 'vf-sample-...'))`) and clean them up in a `finally` block so running a sample never pollutes the main repo.
+2. **SDK & MCP Coverage**:
+   - Import core classes directly from `../src/index.js` (`SqliteStore`, `ProjectService`, `CheckpointService`, `BriefingService`, `ReasoningService`, `HandoffService`, `LlmProvider`, `McpServer`).
+   - Demonstrate realistic multi-harness transitions across:
+     - **Google Antigravity** (`antigravity`)
+     - **Meta Muse / Fireworks AI (`Muse Spark Open`)** (`muse-code`)
+     - **Claude Code / Command Code** (`command-code`)
+     - **OpenAI Codex CLI** (`codex`)
+3. **Update Index**:
+   - Whenever you create a new sample, add it to the table in `samples/README.md` with its run command and architectural summary.
+

package/.agents/mcp_config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "vectorforce": {
+      "command": "node",
+      "args": [
+        "/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js",
+        "mcp"
+      ]
+    }
+  }
+}

package/.codex/config.toml

@@ -0,0 +1,5 @@
+[mcp_servers.vectorforce]
+command = "node"
+args = ["/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js", "mcp"]
+[mcp_servers.vectorforce.env]
+VF_HARNESS = "codex"

package/AGENTS.md

@@ -0,0 +1,115 @@
+# VectorForce Workspace Architecture & Agent Continuity Guide (`AGENTS.md`)
+
+This repository is the core workspace for **VectorForce** — a local-first, zero-dependency, privacy-preserving engineering context platform ("Git for AI Context") across **Google Antigravity**, **Meta Muse**, **Claude Code**, **Command Code**, and **OpenAI Codex**.
+
+---
+
+## 1. Context Protocol Workflow (Mandatory for All AI Agents)
+
+### At the Start of a Task / Resuming Work:
+1. **Discover active tasks:**
+   - MCP: `list_tasks({ status: "active" })` | CLI: `node bin/vf.js tasks active`
+2. **Check for workspace or document drift:**
+   - MCP: `check_workspace_drift({ task_id: "<task_id>" })` | CLI: `node bin/vf.js drift --task <task_id>`
+3. **Retrieve the authorized briefing:**
+   - MCP: `get_resume_briefing({ task_id: "<task_id>", destination_harness: "antigravity" })` (`"antigravity" | "muse-code" | "command-code" | "codex"`)
+   - CLI: `node bin/vf.js resume --task <task_id> --dest antigravity`
+4. **Reason over the context (AI memory):**
+   - MCP: `reason_about_task({ task_id: "<task_id>" })` | CLI: `node bin/vf.js reason --task <task_id>`
+5. **Adhere to Invariant Constraints:** Respect all rules under `# Invariant Constraints` in the briefing.
+
+### At the End of a Task Phase / Before Switching Harnesses:
+1. **Capture an immutable checkpoint:**
+   - MCP: `save_checkpoint({ task_id, summary, goals, constraints, decisions, next_steps, requested_documents })`
+   - CLI:
+     ```bash
+     node bin/vf.js checkpoint --task <id> --summary "<summary>" \
+       --goal "<goal>" --constraint "<constraint>" \
+       --decision "<ID>:<Title>:<Rationale>" \
+       --next "<next_step>" --doc "AGENTS.md"
+     ```
+2. **Verify Receipt:** Ensure the operation receipt returns `status: "committed"`.
+
+---
+
+## 2. Security & Policy Invariants
+
+- **Zero External Runtime Dependencies:** Core CLI, MCP server, and Studio backend use **only** Node.js built-ins (`node:sqlite`, `node:http`, `node:crypto`, `node:fs`, `node:child_process`).
+- **Claims vs Evidence Distinction:** Human/model inputs (`goals`, `constraints`, `decisions`, `next_steps`) are stored as unverifiable **`claims`**. Git commit SHAs, dirty states, and SHA-256 document digests are recorded as verifiable **`evidence`**.
+- **Strict Document Allowlist & Size Cap:** Only `.md`/`.txt` files in `node bin/vf.js policy list` (max `8 KiB` per file, `64 KiB` total) may be collected. `AGENTS.md` must stay `< 8192` bytes. Symlinks and path traversal (`..`) are strictly rejected.
+- **Safe Receipts:** Receipts and audit logs never contain raw document bodies or API credentials.
+
+---
+
+## 3. Workspace Directory & Module Map
+
+```text
+VectorForce/
+├── AGENTS.md                      # Workspace guide & agent protocol (< 8 KiB)
+├── README.md                      # Public documentation & quickstart
+├── package.json                   # Zero-dependency ESM package (Node >= 22.5.0)
+├── bin/vf.js                      # Unified CLI (init, status, checkpoint, resume, reason, studio, mcp, handoff, config)
+├── src/
+│   ├── index.js                   # Public programmatic SDK exports
+│   ├── core/                      # errors.js, hash.js (SHA-256 / HMAC), types.js (schema validators)
+│   ├── policy/authorizer.js       # Workspace containment, symlink rejection, allowlist & harness auth
+│   ├── storage/sqlite-store.js    # Local SQLite WAL engine (.vectorforce/vectorforce.db)
+│   ├── providers/
+│   │   ├── code-index-provider.js # Zero-dep AST/symbol & dependency graph indexer
+│   │   ├── document-provider.js   # Policy-enforced doc reader & SHA-256 evidence collector
+│   │   ├── git-provider.js        # Git branch, HEAD SHA, dirty status, and file diff observer
+│   │   └── llm-provider.js        # AI adapter (Fireworks, Muse, OpenRouter, Ollama, OpenAI, Anthropic, BYOK)
+│   ├── operations/
+│   │   ├── project-service.js     # Project & task lifecycle + allowlist management
+│   │   ├── checkpoint-service.js  # Immutable checkpoint creation + evidence collection
+│   │   ├── briefing-service.js    # Cross-harness resume briefing + live Git/doc drift reconciliation
+│   │   ├── reasoning-service.js   # AI reasoning synthesis over checkpoints + code index + drift
+│   │   └── handoff-service.js     # HMAC-SHA256 signed handoff export/import + lineage verification
+│   ├── mcp/
+│   │   ├── mcp-server.js          # JSON-RPC 2.0 stdio MCP server exposing 9 tools + 3 resources
+│   │   └── harness-config.js      # Auto-generator for Antigravity, Claude, Command Code, Muse, Codex configs
+│   └── studio/server.js           # Local HTTP server (127.0.0.1:3210) + REST API for VectorForce Studio
+├── studio/                        # React + Vite + Tailwind + XYFlow frontend for VectorForce Studio
+├── samples/                       # Runnable sample architectures, multi-agent workflows & integrations
+├── scripts/practical-test-env.js  # 7-stage cross-OS practical E2E simulation (Git + CLI + MCP + Handoff)
+├── test/                          # 75 automated unit, security, MCP, and cross-harness tests
+└── wiki/                          # Local-only ADRs (001-014) and phase planning (gitignored)
+```
+
+### Generated Harness Configs in Workspace Root (`vf init`):
+- `.mcp.json`, `.commandcode/mcp.json`, `commandcode.json` — Claude Code & Command Code
+- `.agents/mcp_config.json`, `~/.gemini/antigravity/mcp_config.json` — Google Antigravity
+- `.muse/mcp_config.json`, `musecode.json` — Meta Muse
+- `.codex/config.toml`, `codex.json` — OpenAI Codex CLI
+
+---
+
+## 4. MCP Tools & AI Provider Reference
+
+| MCP Tool (`src/mcp/mcp-server.js`) | Service Method | Purpose |
+| :--- | :--- | :--- |
+| `list_tasks` | `ProjectService.listTasks` | Discover active/completed tasks |
+| `save_checkpoint` | `CheckpointService.saveCheckpoint` | Commit claims + Git/doc evidence to SQLite |
+| `get_resume_briefing` | `BriefingService.generateBriefing` | Deterministic cross-harness briefing |
+| `check_workspace_drift` | `BriefingService.checkWorkspaceDrift` | Compare live Git & doc hashes vs checkpoint |
+| `reason_about_task` | `ReasoningService.reasonAboutTask` | AI architectural briefing + risk analysis |
+| `set_document_policy` | `ProjectService.setDocumentPolicy` | Update workspace document allowlist |
+| `export_handoff` | `HandoffService.exportHandoff` | Export HMAC-SHA256 signed `.vfhandoff.json` |
+| `import_handoff` | `HandoffService.importHandoff` | Verify signature/hashes & import handoff |
+| `get_timeline` | `SqliteStore.getAuditEvents` | Inspect chronological audit trail |
+
+### Supported AI Reasoning Providers (`src/providers/llm-provider.js`):
+1. **Fireworks AI (`Muse Spark Open`)**: `vf config fireworks <KEY>` (`accounts/fireworks/models/muse-spark-open`)
+2. **Meta Muse Direct**: `vf config muse <KEY>` (`muse-spark-1.3`)
+3. **OpenRouter (`Muse Spark Open`)**: `vf config openrouter <KEY> --model meta/muse-spark-open`
+4. **Local Ollama**: `vf config ollama --model llama3.3` (`http://127.0.0.1:11434`)
+5. **OpenAI / Anthropic / BYOK**: `vf config openai <KEY>` | `vf config anthropic <KEY>` | `vf config byok <URL> <KEY> --model <ID>`
+
+---
+
+## 5. Extension Playbook (Samples & Production Upgrades)
+
+1. **Adding Samples (`samples/`)**: Place runnable workflows, reference architectures, and multi-agent demos inside `samples/` using `src/index.js` or CLI/MCP bridges.
+2. **Adding/Upgrading MCP Tools**: Add business logic in `src/operations/*`, persistence in `src/storage/sqlite-store.js`, MCP registration in `src/mcp/mcp-server.js`, SDK export in `src/index.js`, and CLI command in `bin/vf.js`.
+3. **Upgrading Studio UI**: Add REST routes in `src/studio/server.js` and React views in `studio/src/components/`, then build via `npm --prefix studio run build`.
+4. **Verification Gate**: Always run `npm test` (75 unit/security tests) and `npm run test:practical` (7-stage E2E test) before committing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Learn With Ohm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# VectorForce (VF)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Git for AI Context** — A local-first, privacy-preserving engineering memory platform and architecture control center for AI coding agents.
+
+[![Website](https://img.shields.io/badge/website-getvectorforce.github.io-6366f1.svg)](https://getvectorforce.github.io/)
+[![Tests](https://img.shields.io/badge/tests-75%20passing%20(Linux%20%7C%20macOS%20%7C%20Windows)-brightgreen.svg)](https://github.com/getvectorforce/VectorForce/actions)
+[![Dependencies](https://img.shields.io/badge/backend%20runtime%20deps-zero-blue.svg)](#architecture-invariants)
+[![Storage](https://img.shields.io/badge/storage-local%20SQLite%20WAL-orange.svg)](#local-first-architecture)
+[![Harnesses](https://img.shields.io/badge/harnesses-Antigravity%20%7C%20Claude%20Code%20%7C%20Command%20Code%20%7C%20Codex%20%7C%20Muse-purple.svg)](#model-context-protocol-mcp)
+[![Hackathon](https://img.shields.io/badge/Meta%20Muse%20Hackathon-2026-blueviolet.svg)](#5-reason-over-context-ai-engineering-memory)
+
+---
+
+## The Problem: Coding Agent Amnesia
+
+Every autonomous coding agent today (Google Antigravity, Command Code, Claude Engineer, etc.) operates in isolated ephemeral sessions. When an agent closes its context window:
+1. **Architectural Decisions vanish**: Rationale, API boundaries, and non-negotiable constraints are forgotten.
+2. **Silent Drift goes unnoticed**: Files and documents change without verifying against prior invariant contracts.
+3. **No Cross-Harness Continuity**: A task started in Antigravity cannot cleanly resume in Command Code or be handed off to a teammate without losing the intent.
+
+## The Solution: VectorForce
+
+VectorForce provides an immutable, cryptographic context layer that tracks:
+- **Verifiable Evidence**: Git commit SHAs, file SHA-256 hashes, and workspace drift.
+- **Model Claims**: Explicit goals, constraints, architectural decisions (ADRs), and next steps.
+- **AI Engineering Memory**: Meta Llama / Muse reasoning layer that synthesizes where you left off, what changed, architectural risks, and ranked next actions.
+
+---
+
+## VectorForce Studio (Web UI)
+
+VectorForce includes a local-first engineering control center:
+
+```bash
+# Launch VectorForce Studio (opens on port 3210 by default)
+node bin/vf.js studio
+```
+
+### Studio Features
+- **Project Health & Metrics**: Live health score based on active drift, task completion, and checkpoint currency.
+- **Interactive Architecture Graph**: Interactive SVG topology mapping module dependencies across security, storage, reasoning, code index, and harness bridges. Click any node to inspect blast radius, governing ADRs, and active drift.
+- **AI Workspace Console**: Real-time prompt console powered by Meta Llama / Muse models with strict Claims vs Evidence visual fencing.
+- **Repository Memory & Timeline**: Search indexed symbols, view allowlisted documents, inspect decisions, and generate weekly context continuity recaps.
+- **Team Handoff Preview**: Secure, selective context sharing without leaking private secrets or un-allowlisted documents.
+
+---
+
+## Quickstart
+
+### 1. Initialize a Project
+```bash
+node bin/vf.js init
+```
+
+### 2. Create and Select a Task
+```bash
+node bin/vf.js task auth-module "Implement PKCE OAuth Authentication"
+```
+
+### 3. Check for Workspace Drift
+```bash
+node bin/vf.js drift --task auth-module
+```
+
+### 4. Commit an Immutable Checkpoint
+```bash
+node bin/vf.js checkpoint --task auth-module \
+  --summary "Completed PKCE OAuth handshake and token validation" \
+  --goal "Ship secure OAuth flow" \
+  --constraint "Zero external auth libraries" \
+  --decision "DEC-AUTH-01:PKCE:Use SHA-256 code challenge with local storage" \
+  --next "Implement refresh token rotation" \
+  --doc "AGENTS.md"
+```
+
+### 5. Reason Over Context (AI Engineering Memory)
+
+VectorForce prioritizes **Meta Muse (`muse-spark-1.3`)** and the open-weights **Meta Muse Spark Open (`muse-spark-open` • 1M token context window)** as its **#1 reasoning models**, while also supporting **Fireworks AI**, **OpenRouter**, **Local Ollama**, **OpenAI / Codex**, **Anthropic Claude**, and any **Custom BYOK** OpenAI-compatible endpoint:
+
+```bash
+# 1. [1st Priority] Meta Muse Direct API (Responses API at api.meta.ai/v1 • muse-spark-1.3):
+node bin/vf.js config muse <YOUR_META_API_KEY>
+node bin/vf.js reason --task auth-module
+
+# 2. [1st Priority Open-Weights] Meta "Muse Spark Open" (1M Context) via Fireworks AI:
+node bin/vf.js config fireworks <YOUR_FIREWORKS_API_KEY> accounts/fireworks/models/muse-spark-open
+node bin/vf.js reason --task auth-module
+
+# 3. OpenRouter — Meta Muse Spark Open (meta/muse-spark-open), DeepSeek, Claude, Llama 3.3:
+node bin/vf.js config openrouter <YOUR_OPENROUTER_API_KEY> meta/muse-spark-open
+node bin/vf.js config openrouter <YOUR_OPENROUTER_API_KEY> deepseek/deepseek-v4.1-flash-1017
+node bin/vf.js reason --task auth-module
+
+# 4. Local Ollama (100% Offline & Private — Default when no cloud API key is set):
+ollama pull llama3.1:8b
+node bin/vf.js config ollama llama3.1:8b
+node bin/vf.js reason --task auth-module
+
+# 5. OpenAI / Codex (o3-mini, gpt-4.1, gpt-4o):
+node bin/vf.js config openai <YOUR_OPENAI_API_KEY> o3-mini
+node bin/vf.js reason --task auth-module
+
+# 6. Anthropic Claude (claude-sonnet-4-20250514, claude-3-7-sonnet-latest):
+node bin/vf.js config anthropic <YOUR_ANTHROPIC_API_KEY> claude-sonnet-4-20250514
+node bin/vf.js reason --task auth-module
+
+# 7. Custom BYOK (Groq, Together AI, LM Studio, vLLM, Azure):
+node bin/vf.js config byok https://api.groq.com/openai/v1 <GROQ_API_KEY> llama-3.3-70b-versatile
+node bin/vf.js config byok http://127.0.0.1:1234/v1 lm-studio qwen2.5-coder-14b
+
+# Check active model configuration or run deterministic briefing (--raw):
+node bin/vf.js config status
+node bin/vf.js reason --task auth-module --raw
+
+# Launch VectorForce Studio Web Control Center on http://127.0.0.1:3210
+node bin/vf.js studio
+```
+
+---
+
+## Model Context Protocol (MCP)
+
+VectorForce exposes a standard stdio JSON-RPC MCP server for direct integration into **Google Antigravity**, **Claude Code**, **Command Code**, **Meta Muse**, and **OpenAI Codex**.
+
+> **How MCP Starts:** You **never** need to run `vf mcp` manually in a terminal. Each AI coding agent reads its configuration file below and automatically spawns VectorForce in the background over `stdio`.
+
+| AI Coding Client | Config File Read by Client | 1-Command Auto-Setup |
+|---|---|---|
+| **Google Antigravity** | `.agents/mcp_config.json` & `~/.gemini/antigravity/mcp_config.json` | `node bin/vf.js config install antigravity` |
+| **Claude Code (`claude`)** | `.mcp.json` (project root) | `node bin/vf.js config install claude-code` |
+| **Command Code (`cmd`)** | `.mcp.json` & `commandcode.json` | `node bin/vf.js config install command-code` |
+| **Meta Muse (`muse`)** | `.muse/mcp_config.json` & `~/.config/muse/settings.json` | `node bin/vf.js config install muse` |
+| **OpenAI Codex (`codex`)** | `.codex/config.toml` & `~/.codex/config.toml` | `node bin/vf.js config install codex` |
+
+### Automated Configuration & Health Check
+```bash
+# Auto-configure all supported AI harnesses at once:
+node bin/vf.js config install all
+
+# Verify SQLite DB, AGENTS.md, and all MCP client configs:
+node bin/vf.js status
+```
+
+### JSON Configuration (Antigravity, Claude Code, Command Code, Muse)
+```json
+{
+  "mcpServers": {
+    "vectorforce": {
+      "command": "node",
+      "args": ["/absolute/path/to/VectorForce/bin/vf.js", "mcp"]
+    }
+  }
+}
+```
+
+### TOML Configuration (OpenAI Codex CLI: `.codex/config.toml`)
+```toml
+[mcp_servers.vectorforce]
+command = "node"
+args = ["/absolute/path/to/VectorForce/bin/vf.js", "mcp"]
+[mcp_servers.vectorforce.env]
+VF_HARNESS = "codex"
+```
+
+### Available MCP Tools
+| Tool | Purpose |
+|---|---|
+| `save_checkpoint` | Commit an immutable context checkpoint with Git and document evidence |
+| `get_resume_briefing` | Retrieve authorized task briefing with invariant constraints and drift analysis |
+| `check_workspace_drift` | Compare working tree commit and allowlisted file hashes against checkpoint |
+| `reason_about_task` | Llama-powered AI continuation narrative and architectural risk assessment |
+| `list_tasks` | Discover and filter active, archived, or all tasks |
+| `set_document_policy` | Manage project allowlist for verifiable document evidence |
+| `export_handoff` | Create an encrypted, tamper-evident handoff bundle for teammates or other harnesses |
+| `import_handoff` | Safely verify and import a handoff bundle into destination workspace |
+| `get_timeline` | Generate weekly chronological context continuity recap |
+
+---
+
+## Architecture Invariants
+
+- **Zero Runtime Dependencies**: The core CLI, MCP server, and Studio backend use exclusively Node.js built-ins (`node:sqlite`, `node:http`, `node:crypto`, `node:fs`).
+- **Local-First Isolation**: Database (`.vectorforce/vectorforce.db`) uses SQLite WAL mode strictly within the user's local workspace. No telemetry or code leaks to external servers.
+- **Claims vs Evidence Distinction**: Human intent and AI outputs are strictly treated as unverifiable `claims`; Git commit SHAs and SHA-256 document hashes are recorded as verifiable `evidence`.
+- **Workspace Containment**: Document collection and AST indexing are strictly constrained to canonical workspace paths; symlinks and secrets (`.env`, `*.key`, `id_rsa`) are strictly ignored.
+
+---
+
+## Verification & Cross-OS Test Suite (Linux, macOS, Windows)
+
+Run the full automated test suite (75 unit & security tests) and the 7-stage practical multi-developer environment simulation:
+
+```bash
+# Run all 75 unit, policy, MCP, and security tests:
+npm test
+
+# Run the 7-stage practical real-world environment simulation (Git + CLI + live MCP stdio + Handoff + Drift):
+npm run test:practical
+```