vectorforce 0.1.0 → 0.3.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

@@ -4,14 +4,8 @@
       "command": "node",
       "args": [
         "/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js",
-        "mcp",
-        "--workspace",
-        "/Users/omprakashprajapat/AgentAI/VectorForce"
-      ],
-      "env": {
-        "VF_WORKSPACE": "/Users/omprakashprajapat/AgentAI/VectorForce",
-        "VF_DB_PATH": "/Users/omprakashprajapat/AgentAI/VectorForce/.vectorforce/vectorforce.db"
-      }
+        "mcp"
+      ]
     }
   }
-}
+}

package/.codex/config.toml

@@ -3,6 +3,3 @@ command = "node"
 args = ["/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js", "mcp"]
 [mcp_servers.vectorforce.env]
 VF_HARNESS = "codex"
-
-[mcp_servers.vectorforce.tools.get_resume_briefing]
-approval_mode = "approve"

package/AGENTS.md

@@ -1,43 +1,115 @@
-# Agent Context Sharing & Continuity Guidelines (VectorForce)
+# VectorForce Workspace Architecture & Agent Continuity Guide (`AGENTS.md`)
 
-This project uses **VectorForce** as a local-first, privacy-preserving engineering context platform ("Git for AI context").
+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
+---
 
-Whenever you are working in this repository (in Google Antigravity, Command Code, Meta Muse, or OpenAI Codex):
+## 1. Context Protocol Workflow (Mandatory for All AI Agents)
 
 ### At the Start of a Task / Resuming Work:
 1. **Discover active tasks:**
-   - Call MCP tool: `list_tasks({ status: "active" })`
-   - Or CLI: `node bin/vf.js tasks active`
+   - MCP: `list_tasks({ status: "active" })` | CLI: `node bin/vf.js tasks active`
 2. **Check for workspace or document drift:**
-   - Call MCP tool: `check_workspace_drift({ task_id: "<task_id>" })`
-   - Or CLI: `node bin/vf.js drift --task <task_id>`
+   - MCP: `check_workspace_drift({ task_id: "<task_id>" })` | CLI: `node bin/vf.js drift --task <task_id>`
 3. **Retrieve the authorized briefing:**
-   - Call MCP tool: `get_resume_briefing({ task_id: "<task_id>", destination_harness: "antigravity" })` (use your harness: `"antigravity"`, `"codex"`, `"command-code"`, or `"muse-code"`)
-   - Or CLI: `node bin/vf.js resume --task <task_id> --dest antigravity`
+   - 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):**
-   - Call MCP tool: `reason_about_task({ task_id: "<task_id>" })`
-   - Or CLI: `node bin/vf.js reason --task <task_id>` (alias: `node bin/vf.js continue`)
-   - Produces a Llama-generated narrative: where you left off, what changed since the checkpoint, architectural risks, and ranked next actions. Requires a configured provider (`VF_LLM_*` cloud Llama/Muse or `VF_OLLAMA_*` local); it degrades to the deterministic briefing when unavailable.
-5. **Adhere to Invariant Constraints:** Respect all non-negotiable constraints listed under the briefing's `# Invariant Constraints` section.
+   - 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:**
-   - Call MCP tool: `save_checkpoint({ task_id, summary, goals, constraints, decisions, next_steps, requested_documents })`
-   - Or CLI:
+   - 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 "<allowlisted_doc.md>"
+       --next "<next_step>" --doc "AGENTS.md"
      ```
-2. **Verification Receipt:** Ensure the operation receipt returns `status: "committed"`.
+2. **Verify Receipt:** Ensure the operation receipt returns `status: "committed"`.
 
 ---
 
 ## 2. Security & Policy Invariants
 
-- **Claims vs Evidence Distinction:** Goals, constraints, and decisions are model assertions (`claims`). Git commits and document hashes are verifiable observations (`evidence`). Never confuse an unverified model claim with ground truth.
-- **Strict Document Allowlists:** Only files registered in the project allowlist (`node bin/vf.js policy list`) can be collected as document evidence. Never attempt path traversal outside the workspace.
-- **Safe Receipts:** Receipts never contain document bodies or private credentials.
+- **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/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to the `vectorforce` package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.2.0] - 2026-10-31
+
+### Added
+- **Unified Remote Sync Commands (`vf remote`, `vf push`, `vf pull`)**:
+  - `vf remote set <URL> [--key <KEY>] [--project <ID>]`: Configure remote cloud synchronization endpoint in `.vectorforce/config.json`.
+  - `vf push`: Read local `.vectorforce/vectorforce.db`, wrap tasks & checkpoints in End-to-End Encrypted (E2EE) envelopes (`AES-256-GCM` + `X25519` + `Ed25519`), and push to VectorForce Cloud / Modal.com.
+  - `vf pull`: Pull the latest encrypted envelope from the cloud, verify the `Ed25519` digital signature, decrypt via `X25519` + `AES-256-GCM`, reconcile into local SQLite, and synthesize the **Meta Muse (`muse-spark-open`)** reasoning briefing.
+- **VectorForce Cloud & Modal.com Serverless Deployment**:
+  - Dedicated cloud sync server supporting multi-project registries, B2B2B sub-customer tenant isolation, and developer task assignment boards.
+  - One-command deployment to Modal.com (`modal_app.py`) with persistent `modal.Volume` storage for encrypted SQLite WAL databases.
+- **Interactive Team Handoff & Studio UI Upgrades**:
+  - Added direct browser download of `.vfhandoff.json` bundle files.
+  - Added interactive in-browser **Import & Reconcile Teammate Handoff Package** modal (`POST /api/handoff/import`) with SHA-256 manifest validation.
+  - Automatic resolution of active tasks and divergent checkpoint heads in Studio export endpoints.
+- **Automated npm Lifecycle Hooks**:
+  - Added `prepublishOnly` script in `package.json` to ensure `npm --prefix studio run build` and all 75 tests run automatically before every `npm publish`.
+
+### Changed
+- **CLI Commands Simplified**: Unified remote cloud sync under the standard `vf` command (following the `git remote`, `git push`, `git pull` mental model).
+- **Workspace Agent Protocols**: Upgraded workspace-level `AGENTS.md` and role definitions for `vectorforce-architect`, `vectorforce-auditor`, and `vectorforce-samples-builder`.
+
+### Fixed
+- Fixed `TypeError` in `TeamHandoffView.jsx` when resolving checkpoints with differing `id` vs `checkpoint_id` shapes.
+- Fixed divergent leaf head resolution in `/api/handoff/export` by auto-selecting the latest timestamped checkpoint.
+- Fixed ephemeral key generation in serverless environments by persisting machine identities in durable SQLite storage.
+
+---
+
+## [0.1.0] - 2026-10-27
+
+### Added
+- Initial public release of VectorForce — "Git for AI Context".
+- Zero-dependency local SQLite WAL persistence engine (`node:sqlite`).
+- Model Context Protocol (MCP) server over JSON-RPC 2.0 stdio with 9 core tools (`save_checkpoint`, `get_resume_briefing`, `check_workspace_drift`, `reason_about_task`, `list_tasks`, `set_document_policy`, `export_handoff`, `import_handoff`, `get_timeline`).
+- Automatic multi-harness configuration generators for Google Antigravity, Claude Code, Command Code, Meta Muse, and OpenAI Codex.
+- Multi-provider AI reasoning engine supporting Meta Muse (`muse-spark-1.3`, `muse-spark-open`), Fireworks AI, OpenRouter, Local Ollama, OpenAI, Anthropic, and custom BYOK endpoints.
+- Local VectorForce Studio Web UI (`vf studio`) on port 3210 with interactive SVG architecture dependency and blast-radius graph.

package/README.md

@@ -2,11 +2,12 @@
 
 > **Git for AI Context** — A local-first, privacy-preserving engineering memory platform and architecture control center for AI coding agents.
 
-[![Tests](https://img.shields.io/badge/tests-65%20passing-brightgreen.svg)](#test-suite)
+[![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%20Command%20Code%20%7C%20Codex%20%7C%20Muse-purple.svg)](#harness-integrations)
-[![Hackathon](https://img.shields.io/badge/Meta%20Muse%20Hackathon-2026-blueviolet.svg)](#meta-muse-hackathon)
+[![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)
 
 ---
 
@@ -72,31 +73,92 @@ node bin/vf.js checkpoint --task auth-module \
   --doc "AGENTS.md"
 ```
 
-### 5. Reason Over Context (AI Engineering Memory)
+### 5. Multi-Machine & Team Cloud Sync (`vf remote`, `vf push`, `vf pull`)
+
+VectorForce follows the Git mental model for sharing context between two computers or across a team using Zero-Knowledge End-to-End Encryption (`X25519` + `AES-256-GCM` + `Ed25519`):
+
+```bash
+# 1. Connect local workspace to your Cloud Remote once:
+node bin/vf.js remote set https://omprakash-pce2011--vectorforce-cloud-vectorforce-cloud-web.modal.run \
+  --key vf_live_sub_98a7bc65f012e4d9 \
+  --project proj-bistro-pos
+
+# 2. Push local checkpoints & tasks to Cloud (E2EE):
+node bin/vf.js push
+
+# 3. Pull & reconcile context on Computer 2 (reconciles into SQLite & runs Meta Muse reasoning):
+node bin/vf.js pull
+```
+
+### 6. 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
-# Uses local Ollama by default, or cloud providers (Meta Muse, OpenRouter, OpenAI Codex)
-# With Meta Muse (Responses API at api.meta.ai):
-node bin/vf.js config muse <API_KEY>
+# 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
 
-# With OpenRouter + DeepSeek v4.1 Flash:
-export OPENROUTER_API_KEY="sk-or-v1-..."
+# 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
 
-# Or specify model explicitly:
-node bin/vf.js reason --task auth-module --model deepseek/deepseek-v4.1-flash-1017
+# 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
 
-# Degrades deterministically if no LLM provider is configured
-node bin/vf.js reason --task auth-module --no-llm
+# 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**, **Command Code**, **Meta Muse**, and **OpenAI Codex**:
+VectorForce exposes a standard stdio JSON-RPC MCP server for direct integration into **Google Antigravity**, **Claude Code**, **Command Code**, **Meta Muse**, and **OpenAI Codex**.
 
-### JSON Configuration (Antigravity, Command Code, Muse)
+> **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": {
@@ -117,17 +179,6 @@ args = ["/absolute/path/to/VectorForce/bin/vf.js", "mcp"]
 VF_HARNESS = "codex"
 ```
 
-### Automated Configuration
-```bash
-# Auto-configure for a specific harness:
-node bin/vf.js config install codex
-node bin/vf.js config install antigravity
-node bin/vf.js config install command-code
-
-# Or install for all supported harnesses at once:
-node bin/vf.js config install all
-```
-
 ### Available MCP Tools
 | Tool | Purpose |
 |---|---|
@@ -152,23 +203,14 @@ node bin/vf.js config install all
 
 ---
 
-## Architecture Decision Records (ADR)
+## Verification & Cross-OS Test Suite (Linux, macOS, Windows)
 
-All design decisions are formalized in the [`wiki/`](wiki/README.md):
-
-- [ADR-001: Event-driven context architecture](wiki/decisions/adr-001-event-driven-harness-independent-context-architecture.md)
-- [ADR-002: Local-first checkpoints & disclosure boundaries](wiki/decisions/adr-002-local-first-checkpoints-and-disclosure-boundaries.md)
-- [ADR-003: Portable checkpoints & cross-harness resume](wiki/decisions/adr-003-portable-checkpoints-and-cross-harness-resume.md)
-- [ADR-012: Target harnesses: Antigravity & Command Code](wiki/decisions/adr-012-target-harness-selection-antigravity-commandcode-pidev.md)
-- [ADR-013: AI reasoning layer & model provider authorization](wiki/decisions/adr-013-ai-reasoning-layer-and-provider-authorization.md)
-- [ADR-014: VectorForce Studio & local topology visualizer](wiki/decisions/adr-014-vectorforce-studio-and-local-topology-visualizer.md)
-
----
-
-## Verification & Test Suite
-
-Run the full automated test suite (62 tests across 15 suites):
+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
 ```