paths-engine 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,600 @@
-# Temporary Holding Version
-
-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.
+# Paths
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-3178C6?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-3178C6)](https://modelcontextprotocol.io/)
+[![Storage](https://img.shields.io/badge/Storage-SQLite_WAL-3178C6?logo=sqlite&logoColor=white)](https://www.sqlite.org/)
+[![Tests](https://img.shields.io/badge/Tests-701_Passing-3178C6)](#)
+[![Security](https://img.shields.io/badge/Security-Verified_Gate-3178C6)](#)
+[![Privacy](https://img.shields.io/badge/Privacy-100%25_Local-3178C6)](#)
+
+Paths preserves your development context across AI tools and sessions. Switch seamlessly between Antigravity, Claude Code, Gemini CLI, Cursor, or any AI assistant and pick up exactly where you left off — architectural decisions, work history, and open Todos included.
+
+No more re-explaining your project. No more lost decisions across session resets.
+
+---
+
+## Universal Canonical State Rule
+
+Paths is built on a strict, unbreakable single-source-of-truth invariant:
+
+```
+[ Local SQLite Database (WAL Mode) ]  ← CANONICAL PERSISTENCE
+                 ↓
+       [ Core Domain Services ]        ← DOMAIN INVARIANTS & COMPILER
+                 ↓
+     [ Database Repositories & Store ]  ← TYPED PERSISTENCE TRANSLATION
+                 ↓
+   [ CLI, MCP & Desktop GUI Adapters ]  ← INTERACTION PROJECTIONS
+```
+
+1. **SQLite is Canonical**: The local SQLite database is the sole authoritative state of truth.
+2. **Core Services Define Behavior**: All domain invariants, project resolution, knowledge ranking, and context compilation reside strictly in Core services.
+3. **Repositories Translate Persistence**: Data access is encapsulated in typed repositories with zero raw SQL leaks outside the store.
+4. **Adapters Project State**: The CLI, MCP, and Desktop GUI adapters are interaction projections over the shared SQLite foundation.
+5. **No Cross-Module DB Access**: Strict unidirectional dependency flow (`Adapter → Core Service → Repository → Store`).
+6. **External Integrations Enter Through Ingestion**: Tool logs, agent sessions, and user inputs enter exclusively through validated Core interfaces.
+
+---
+
+## How It Works
+
+Every project has **Lineages** — named development threads (e.g., `"Auth Refactor"`, `"Payments Migration"`). Each time work occurs, a **Session** (Node record) is appended inside the active lineage with automatic Git file change detection. Durable facts, constraints, and decisions are captured in **Knowledge** (scored and ranked dynamically). Open work is tracked in **Todos**.
+
+At the start of any session, `paths context <id>` or the MCP `get_project_context` tool compiles this into a structured, bounded context digest under 250 lines that any AI model can digest instantly.
+
+```
+Your Work History
+    + Project Identity (name, purpose, architecture, standards, scope, DoD)
+    + Durable Knowledge (decisions, constraints — scored & ranked by relevance)
+    + Sessions (Node records; 15 most recent, newest-first, with files touched)
+    + Open Todos (lineage-scoped and project-wide)
+                    ↓
+        paths context <lineage-id>  /  paths status
+                    ↓
+         Compiled JSON Digest / Human Card
+                    ↓
+     AI tool continues exactly where you left off
+```
+
+---
+
+## Installation & Distribution
+
+### Global CLI & MCP Binaries
+
+Paths is distributed as the `paths-engine` npm package, exposing two standalone executables:
+- **`paths`**: Interactive CLI for terminal usage and developer inspection.
+- **`paths-mcp`**: Stdio-based Model Context Protocol (MCP) server for AI assistants.
+
+```bash
+# Install globally via npm
+npm install -g paths-engine
+
+# Or run instantly via npx without global installation
+npx paths-engine --help
+npx paths-mcp
+```
+
+### Local Development from Source
+
+```bash
+git clone https://github.com/gnbaba/Paths.git
+cd Paths
+npm install
+npm run build
+```
+
+After compilation, the binaries are available directly:
+```bash
+# Run CLI from compiled output
+node dist/cli/index.js --help
+
+# Run MCP server from compiled output
+node dist/mcp/server.js
+```
+
+### Data Storage & Configuration Portability
+
+Paths stores all data in a single SQLite database file with WAL journal mode enabled:
+
+```
+~/.paths-engine/data.sqlite
+```
+
+- **Fully Local**: Zero servers, zero telemetry, zero cloud dependencies.
+- **Environment Override**: Override the database location using `PATHS_DB_PATH`:
+  ```bash
+  PATHS_DB_PATH=/custom/path/data.sqlite paths status
+  ```
+- **Working Directory Portability**: In Git repositories, Paths automatically identifies the project key by its remote origin URL across any clone or nested subdirectory. In non-Git directories, it deterministically falls back to the absolute directory path.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Define your project identity
+paths identity set \
+  --name "Platform Core" \
+  --purpose "Core backend payment routing engine" \
+  --architecture "Modular monolith with SQLite persistence" \
+  --stack "TypeScript, Node.js, SQLite, Stripe SDK" \
+  --scope "v1 release milestone"
+
+# 2. Create and switch to a Lineage
+paths lineage new "Stripe Integration"
+# → Created lineage 1: Stripe Integration. Now using Stripe Integration as the current lineage.
+
+# 3. Log your session work (git files touched are auto-detected)
+paths session "Implemented webhook signature verification and replay protection" --tool antigravity
+
+# 4. Save a durable architectural decision
+paths knowledge add --category Security \
+  "Webhook signatures require Ed25519 asymmetric verification" \
+  "Prevents replay attacks and secures public ingress"
+
+# 5. Add an open Todo
+paths todo add "Implement webhook idempotency replay test with duplicate event ID"
+
+# 6. Check human-readable project status card
+paths status
+
+# 7. Output machine-readable compiled context digest for AI tools
+paths context 1
+```
+
+---
+
+## CLI Reference
+
+### `paths status`
+
+Renders a human-readable summary card from the compiled context summary without performing database mutations. Supports machine-readable JSON output.
+
+```bash
+# Display human-readable status card
+paths status
+
+# Display machine-readable JSON status summary
+paths status --json
+```
+
+**Example Output:**
+```
+Paths
+────────────────────────────────────────
+Project      Platform Core
+Lineage      Stripe Integration
+
+Last Session
+  antigravity · just now
+  Implemented webhook signature verification and replay protection
+
+Next Task
+  Implement webhook idempotency replay test with duplicate event ID
+
+Open Todos   1
+Blockers     None
+```
+
+---
+
+### `paths identity`
+
+Manages the 8 core project identity fields included in every context compilation.
+
+```bash
+# Set any combination of fields (partial updates preserve untouched fields)
+paths identity set \
+  --name "Project Name" \
+  --purpose "What the project does" \
+  --architecture "Modular Monolith" \
+  --stack "Node.js, TypeScript, SQLite" \
+  --standards "Strict unidirectional layer flow" \
+  --folder-structure "src/core, src/cli, src/mcp, tests" \
+  --scope "v1 release scope" \
+  --dod "All tests passing, zero blocking defects"
+
+# Display all identity fields
+paths identity get
+```
+
+---
+
+### `paths lineage`
+
+Manages independent Lineages within the project.
+
+```bash
+# Create a new lineage (auto-activates as current)
+paths lineage new "Feature X"
+
+# List all lineages (> marks the active Lineage)
+paths lineage list
+
+# Switch the current active lineage
+paths lineage use <id>
+
+# View session history (capped at 15 newest sessions by default)
+paths lineage history <id>
+
+# View full session history without limit
+paths lineage history <id> --full
+```
+
+---
+
+### `paths session`
+
+Appends a Session (Node record) to the active lineage. Changes to tracked files since the last Git commit are automatically derived and logged. Supports reading session summary from a file.
+
+```bash
+# Log session against the active lineage
+paths session "Refactored payment routing middleware" --tool antigravity
+
+# Log session from a file (mutually exclusive with inline text)
+paths session --file ./notes/session.txt --tool antigravity
+
+# Log session against an explicit lineage ID
+paths session "Fixed auth token expiration bug" --tool claude-code --lineage 2
+```
+
+---
+
+### `paths knowledge`
+
+Stores durable, project-wide facts, decisions, and architectural contracts.
+
+```bash
+# Save a durable knowledge item (--category required)
+paths knowledge add --category Architecture \
+  "Operational datastore uses SQLite with WAL mode" \
+  "Provides local embedded persistence with concurrent read transactions"
+
+# Save a replacement fact and atomically supersede an older item
+paths knowledge add --category Security \
+  "New Auth uses Ed25519 asymmetric keypairs" \
+  "Modern cryptographic standard" \
+  --supersedes 2
+
+# List all active (non-superseded) knowledge facts
+paths knowledge list
+
+# Search all knowledge (including superseded facts) by literal substring match
+paths knowledge search "Ed25519"
+```
+
+**Allowed Categories**: `Architecture`, `Business`, `Deployment`, `Security`, `Testing`, `API`, `Database`, `Infrastructure`, `UI`.
+
+---
+
+### `paths todo`
+
+Tracks actionable Todos scoped to a lineage or across the entire project.
+
+```bash
+# Add a project-wide Todo
+paths todo add "Rotate production webhook signing secrets"
+
+# Add a lineage-scoped Todo
+paths todo add "Benchmark signature verification latency" --lineage 1
+
+# List open todos for active lineage (lineage todos + project-wide todos)
+paths todo list
+
+# List todos scoped to a specific lineage
+paths todo list --lineage 1
+
+# Complete a todo by case-insensitive partial substring match
+paths todo done "Rotate production webhook"
+```
+
+---
+
+### `paths context`
+
+Compiles and outputs the full context digest for a lineage as structured JSON.
+
+```bash
+paths context <lineage-id>
+```
+
+**Digest Structure:**
+- `summary`: High-level overview (`project`, `lineage`, `last_session`, `current_goal`, `next_suggested_task`, `open_todo_count`, `blockers`).
+- `identity`: Full 8-field project metadata block.
+- `knowledge`: Up to 50 active knowledge facts, dynamically scored and ranked by importance, reference count, recency, and active lineage origin boost.
+- `nodes`: Up to 15 most recent Sessions in newest-first order with files touched.
+- `todos`: Up to 25 open Todos (lineage-scoped and project-wide).
+
+---
+
+### `paths plan`
+
+Manages persistent development plans (intent, approach, definition of done).
+
+```bash
+# Create a new active plan (replaces current active plan)
+paths plan new "Payment Gateway Migration" \
+  --intent "Migrate from Stripe v2 to v3" \
+  --approach "Implement adapter pattern and dual-write" \
+  --done "All webhooks processed without data loss"
+
+# Create plan from file (mutually exclusive with inline options)
+paths plan new "Payment Gateway Migration" --file ./plan.json
+
+# Show active plan or specific plan by ID
+paths plan show
+paths plan show --id 1
+
+# List plans for the project (active only by default, or all)
+paths plan list
+paths plan list --all
+
+# Complete plan with retrospective summary
+paths plan complete 1 --summary "Dual-write completed and verified in production"
+
+# Abandon plan with explanation
+paths plan abandon 1 --reason "Superseded by alternative architecture"
+```
+
+---
+
+### `paths ingest`
+
+Ingests external software engineering events into Sessions, Todos, or Knowledge.
+
+```bash
+# Ingest from inline JSON string
+paths ingest '{"sourceSystem":"github","externalEventId":"gh-101","eventType":"pull_request","sourceRecord":{"title":"Fix bug"},"occurredAt":"2026-09-26T12:00:00Z"}'
+
+# Ingest from a JSON file
+paths ingest --file ./events/commit.json
+```
+
+---
+
+### `paths sync`
+
+Manages multi-machine distributed synchronization bundles.
+
+```bash
+# Export sync bundle of project changes to a file
+paths sync export --output ./sync-bundle.json
+
+# Apply a received sync bundle
+paths sync apply ./sync-bundle.json
+
+# Check sync status (device ID, sequence, applied counts)
+paths sync status
+```
+
+---
+
+### `paths gui`
+
+Launches or focuses the Visual Memory Explorer desktop application. The GUI operates as an always-warm resident application in the system tray, providing instantaneous (<10ms) recall after initial boot.
+
+```bash
+# Launch or focus GUI for current working directory
+paths gui
+
+# Start resident GUI silently in system tray without opening window
+paths gui --minimized
+
+# Launch or focus GUI for a specific project directory
+paths gui /path/to/project
+```
+
+---
+
+## Model Context Protocol (MCP) Server
+
+Paths includes a compliant Model Context Protocol server exposing **23 single-purpose tools** over stdio (complete inventory in the [MCP Tool Reference](#mcp-tool-reference) below).
+
+### Client Configuration
+
+Add Paths to your AI assistant's MCP configuration with auto-approval enabled for a zero-prompt developer experience:
+
+#### Standard Configuration (Global / Ambient Mode)
+When `args` is omitted, Paths runs in ambient mode and automatically resolves projects from the active workspace `cwd` or the IDE's MCP roots:
+```json
+{
+  "mcpServers": {
+    "paths": {
+      "command": "paths-mcp",
+      "autoApprove": [
+        "get_lineages", "start_lineage", "continue_lineage", "get_project_context",
+        "log_session", "save_knowledge", "search_knowledge", "get_lineage_history",
+        "search_nodes", "add_todo", "complete_todo", "list_todos",
+        "update_identity", "create_plan", "get_active_plan", "complete_plan",
+        "abandon_plan", "list_plans", "sync_export", "sync_apply",
+        "sync_status", "ingest_event", "open_gui"
+      ]
+    }
+  }
+}
+```
+
+#### OpenCode (`opencode.json`)
+```json
+{
+  "mcp": {
+    "paths": {
+      "command": "paths-mcp",
+      "autoApprove": true
+    }
+  }
+}
+```
+
+#### Project-Pinned Configuration (Single-Project Mode)
+To pin the MCP server to a specific workspace and enforce strict cross-project isolation:
+```json
+{
+  "mcpServers": {
+    "paths": {
+      "command": "paths-mcp",
+      "args": ["/path/to/your/workspace"]
+    }
+  }
+}
+```
+
+#### Development / Local Source Configuration
+```json
+{
+  "mcpServers": {
+    "paths": {
+      "command": "node",
+      "args": ["/absolute/path/to/paths-engine/dist/mcp/server.js"],
+      "env": {
+        "PATHS_DB_PATH": "/path/to/data.sqlite"
+      }
+    }
+  }
+}
+```
+
+### MCP Environment Variables
+
+- `PATHS_DB_PATH`: Override SQLite location (default `~/.paths-engine/data.sqlite`).
+- `PATHS_ALLOW_CROSS_PROJECT=1`: Opt-in cross-project lookups (`projectId` / `lineageId` / `cwd` targeting another project, e.g. querying Condensr while connected to Paths). Default denied to prevent cross-tenant leaks. Single-user workstation only — project IDs are enumerable. Example:
+```json
+{ "mcpServers": { "paths": { "command": "paths-mcp", "args": ["/path/to/workspace"], "env": { "PATHS_ALLOW_CROSS_PROJECT": "1" } } } }
+```
+- `PATHS_SYNC_KEY`: HMAC-SHA256 sync signing key (min 16 chars). When set, unsigned bundles are rejected by default.
+- `PATHS_SYNC_REQUIRE_SIGNATURE=1`: Strict mode — always reject unsigned bundles (wins over `ALLOW_UNSIGNED`).
+- `PATHS_SYNC_ALLOW_UNSIGNED=1`: Migration escape hatch — allow unsigned bundles even when `PATHS_SYNC_KEY` is set. Do not leave on permanently.
+- `PATHS_DISABLE_GIT_DISCOVERY=1`: Disable `git diff` auto-derive for `filesTouched` (deterministic CI/tests).
+
+### MCP Tool Reference
+
+> All Paths tools declare `destructiveHint: false`. Read-only tools also declare `readOnlyHint: true`.
+
+| Tool | Annotation | Parameters | Description |
+|---|---|---|---|
+| `get_lineages` | `readOnly: true, destructive: false` | `{}` | Lists all Lineages with active status and node counts. |
+| `start_lineage` | `readOnly: false, destructive: false` | `{ name: string }` | Creates a new Lineage and sets it current. |
+| `continue_lineage` | `readOnly: false, destructive: false` | `{ lineageId: number }` | Resumes an existing active Lineage and touches timestamp. |
+| `get_project_context` | `readOnly: true, destructive: false` | `{ lineageId?: number }` | Retrieves bounded compiled context digest (identity, ranked knowledge, Sessions, Todos). |
+| `log_session` | `readOnly: false, destructive: false` | `{ summary: string, tool?: string, filesTouched?: string[], lineageId?: number }` | Appends a Session (Node record) with parentNodeId provenance tracking. |
+| `save_knowledge` | `readOnly: false, destructive: false` | `{ category: string, fact: string, why: string, originNodeId?: number, supersedesId?: number }` | Records durable knowledge fact or atomically supersedes an existing item. |
+| `search_knowledge` | `readOnly: true, destructive: false` | `{ query: string }` | Searches Knowledge across all statuses (active, superseded, conflicted, draft) by substring across fact and why. |
+| `get_lineage_history` | `readOnly: true, destructive: false` | `{ lineageId?: number, full?: boolean }` | Retrieves Session history (Node records; capped at 15 by default, or full). |
+| `add_todo` | `readOnly: false, destructive: false` | `{ text: string, lineageId?: number, originNodeId?: number }` | Adds an open Todo (project-wide or lineage-scoped). |
+| `complete_todo` | `readOnly: false, destructive: false` | `{ id?: number, textMatch?: string }` | Marks an open Todo as done by ID or text match. |
+| `list_todos` | `readOnly: true, destructive: false` | `{ lineageId?: number }` | Lists open Todos for the project and lineage. |
+| `update_identity` | `readOnly: false, destructive: false` | `{ projectName?, purpose?, architecture?, techStack?, codingStandards?, folderStructure?, scope?, definitionOfDone? }` | Updates core project identity and architecture metadata. |
+| `create_plan` | `readOnly: false, destructive: false` | `{ title, intent, approach, definitionOfDone, lineageId?, projectId?, cwd? }` | Creates a persistent Plan (intent, approach, definition of done), replacing any active Plan with a history link. Does not modify Sessions, Knowledge, or Todos. |
+| `get_active_plan` | `readOnly: true, destructive: false` | `{ projectId?, cwd? }` | Retrieves the active Plan (intent, approach, definition of done); null when none exists. Read-only. |
+| `list_plans` | `readOnly: true, destructive: false` | `{ includeInactive?, projectId?, cwd? }` | Lists Plans newest first (all statuses by default; active only with `includeInactive: false`). Read-only. |
+| `complete_plan` | `readOnly: false, destructive: false` | `{ planId: number, completionSummary: string, projectId?, cwd? }` | Marks the active Plan completed with a retrospective summary. Associated Todos, Sessions, and Knowledge remain untouched. |
+| `abandon_plan` | `readOnly: false, destructive: false` | `{ planId: number, abandonmentReason: string, projectId?, cwd? }` | Abandons the active Plan with an explanation. Associated Todos, Sessions, and Knowledge remain untouched. |
+| `search_nodes` | `readOnly: true, destructive: false` | `{ query: string, lineageId?, projectId?, limit?, cwd? }` | Searches Session history (Node records) across all Lineages by summary or file path. Read-only. |
+| `ingest_event` | `readOnly: false, destructive: false` | `{ sourceSystem, externalEventId, eventType, sourceRecord, occurredAt, targetCanonicalType?, nodePayload?, todoPayload?, knowledgePayload? }` | Ingests an external event into a Session (Node record), Todo, or Knowledge with deduplication. Does not modify Plans or Identity. |
+| `sync_export` | `readOnly: true, destructive: false` | `{ cursor?, projectId?, cwd? }` | Exports a sync bundle of Project changes since a per-device cursor for multi-machine transfer. Read-only. |
+| `sync_apply` | `readOnly: false, destructive: false` | `SyncBundle` | Applies a sync bundle to merge Project state with causality tracking (Sessions, Knowledge, Todos); does not create Plans directly. |
+| `sync_status` | `readOnly: true, destructive: false` | `{ projectId?, cwd? }` | Returns sync status (device ID, sequence, applied/deferred counts). Read-only. |
+| `open_gui` | `readOnly: true, destructive: false` | `{ projectId?, cwd? }` | Launches the Visual Memory Explorer desktop app for the active project. Read-only. |
+
+---
+
+## Desktop GUI (Visual Memory Explorer)
+
+Paths includes an Electron and React desktop application architecture designed for visual exploration of project memory.
+
+### Architecture & Security Model
+
+```
+[ Renderer Process (React / Vite) ]  ← Sandboxed UI Shell (Zero Node/DB Access)
+                 ↓
+      [ Preload (PathsApi) ]         ← Explicit 15-Method Positive Surface (contextBridge)
+                 ↓
+     [ AppBridge (ipcMain) ]         ← 15-Channel Router, Zod Validation, Concurrency Queue
+                 ↓
+      [ AppContextManager ]          ← State Authority & Atomic Context-Switch Lifecycle
+                 ↓
+        [ Core Services ]            ← Domain Invariants & Compiler
+                 ↓
+    [ Repositories & SqliteStore ]   ← SQLite Persistence (Main Process Exclusive)
+```
+
+- **Single Database Authority**: The Main process is the sole owner of the SQLite database (`app.requestSingleInstanceLock()`).
+- **Sandboxed Renderer**: The renderer executes with `nodeIntegration: false`, `contextIsolation: true`, and `sandbox: true`. Direct access to SQLite, Electron, or Node.js built-ins is blocked by design and verified by automated static boundary tests.
+- **Strict Content Security Policy**: Production builds enforce a strict CSP (`default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;`).
+- **15-Channel IPC Surface**: Maps 1-to-1 to typed adapter DTO contracts:
+  - **8 Queries (Concurrent)**: `paths:get-context`, `paths:get-status`, `paths:list-lineages`, `paths:list-knowledge`, `paths:search-knowledge`, `paths:get-history`, `paths:list-todos`, `paths:get-identity`.
+  - **7 Commands (FIFO Serialized)**: `paths:start-lineage`, `paths:continue-lineage`, `paths:save-knowledge`, `paths:add-todo`, `paths:complete-todo-by-id`, `paths:log-session`, `paths:update-identity`.
+- **Atomic Context Switching**: Seamlessly switch active projects with guaranteed rollback on failed initialization and automatic rejection of stale mutations (`STALE_GENERATION`).
+### The Five Visual Surfaces
+
+| Surface | Component | Key Capabilities |
+|---|---|---|
+| **Dashboard** | `Dashboard.tsx` | High-level SDLC project overview, active goal, compiler-suggested next Todo, open Todo metrics, blockers, and top-3 compiler-ranked active knowledge items. |
+| **Lineage Manager** | `LineageManager.tsx` | Lineage orchestration, total session counts, relative/ISO activity timestamps, active Lineage indicators, lineage switching, and new Lineage creation. |
+| **Knowledge Explorer** | `KnowledgeExplorer.tsx` | Comprehensive knowledge base browser with 9 SDLC category filters, active vs. superseded tabs, 300ms debounced search, and collapsible Why/Rationale disclosure cards. |
+| **Session Timeline** | `SessionTimeline.tsx` | Chronological session history chain (oldest to newest), tool badges, dual timestamps, vertical parent links, full-history toggle, and expandable `filesTouched` path chips. |
+| **Todo Board** | `TodoBoard.tsx` | Todo management with "All Project" vs. "Active Lineage" scope toggles, origin badges, and canonical todo completion actions. |
+
+### Resident Desktop Mode & System Tray Lifecycle
+
+To eliminate cold-start latency (~4–6s) down to instantaneous recall (<10ms), the Desktop GUI runs as an always-warm resident application:
+
+- **Close-to-Tray Lifecycle**: Closing the window (`X`) minimizes the application to the Windows System Tray (`win.hide()`) rather than terminating the process. SQLite connections and compiled web bundles remain warm in memory.
+- **Instant Second-Instance Recall (<10ms)**: Subsequent invocations via terminal `paths gui` or AI assistant MCP `open_gui` communicate through Electron's `second-instance` IPC to immediately un-hide and focus the active window with zero cold-boot delay.
+- **Native Tray Controls**: The system tray icon provides single-click visibility toggling, current project path inspection, and a clean **Quit** option that safely checkpoints SQLite WAL journals before exiting.
+- **Silent Background Boot**: The `--minimized` flag allows the application to launch directly into the system tray at startup without interrupting the developer's workspace.
+
+---
+
+## Security & Privacy
+
+Paths is engineered with a local-first, zero-trust security architecture:
+
+* **Local-First & Offline Privacy**: 100% of project knowledge and session data resides strictly on your local machine. Zero telemetry, zero analytics, zero cloud dependencies.
+* **Process Sandboxing**: The Desktop UI operates in an isolated Chromium sandbox (`nodeIntegration: false`, `contextIsolation: true`) with strict CSP and typed IPC boundaries.
+* **Deterministic & Auditable**: Reproducible clean builds verified with SHA-256 artifact manifests.
+* **Automated Security Gates**: Integrated release verification pipeline enforcing dependency admission, secret scanning, and boundary isolation.
+
+```bash
+# Run security checks & boundary tests
+npm run security:check
+
+# Run full release security verification pipeline
+npm run security:gate
+```
+
+---
+
+## Development
+
+```bash
+# Build TypeScript Core, CLI, and MCP to dist/
+npm run build
+
+# Build Desktop GUI React renderer bundle
+npm run build:gui
+
+# Launch Desktop GUI application
+npm run gui
+
+# Start Desktop GUI renderer development server
+npm run dev:gui
+
+# Run automated test suite (Vitest)
+npm test
+
+# Run linter
+npm run lint
+
+# Run typechecker
+npm run typecheck
+
+# Run end-to-end release security pipeline
+npm run security:gate
+
+# Run full release verification & tarball packaging pipeline
+npm run release
+```
+

package/dist/cli/commands/context.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerContextCommands(parentCommand: Command): void;
+//# sourceMappingURL=context.d.ts.map

package/dist/cli/commands/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsDpC,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAyEpE"}