@digital-lake/lognexus 1.0.0-alpha.0 → 1.0.0-alpha.4

package/README.md

@@ -5,7 +5,7 @@
 # LogNexus
 
 <p align="center">
-  <strong>The Git-Powered Memory Nexus for AI Agents</strong>
+  <strong>The Universal, Git-Powered Context & Rules Framework for Native AI Agents</strong>
 </p>
 
 <p align="center">
@@ -19,9 +19,11 @@
 
 ## What is LogNexus?
 
-As AI coding agents take on multi-step engineering tasks, they suffer from a fundamental failure mode: **cognitive amnesia**. Between conversation resets, context compactations, model handoffs, and unexpected bugs, the *why* behind design decisions, discarded alternatives, and technical discoveries vanishes.
+As AI coding agents take on complex engineering tasks across different IDEs, they suffer from a fundamental failure mode: **cognitive amnesia**. Between conversation resets, context compactations, model handoffs, and unexpected bugs, the *why* behind design decisions, discarded alternatives, and technical discoveries vanishes.
 
-**LogNexus transforms Git and GitHub into a persistent, traceable knowledge graph.** It turns every brainstorm into an issue, every issue into a scoped branch, every commit into an annotated milestone, and every Pull Request into an auditable timeline of the entire development journey.
+**LogNexus transforms Git and GitHub into a persistent, traceable knowledge graph.** It is a **100% generic, model-agnostic and editor-agnostic framework** that operates directly inside your native AI development environments:
+- **Clients:** Claude Code, Cursor, Codex, Google Antigravity, Kimi Code, VS Code, Zed.
+- **Models:** Anthropic Claude (Opus, Sonnet, Haiku), OpenAI (o3, o1, GPT-4o), Google Gemini (2.5/3.8 Pro & Flash), DeepSeek (R1, V3, Chat).
 
 ```
 Issues (Why & Goals) ──▶ Branches (Task Scopes) ──▶ Commits (Context & Diffs) ──▶ PR (Timeline & Review)
@@ -29,26 +31,24 @@ Issues (Why & Goals) ──▶ Branches (Task Scopes) ──▶ Commits (Context
          └─────────────────────── Git-Backed Knowledge Graph ──────────────────────────────┘
 ```
 
+> **Framework, Not an API Proxy:** LogNexus never intercepts network calls or wraps vendor APIs. Your models remain inside their native IDEs with full access to editor buffers, interactive diff viewers, terminals, MCP servers, and local tools.
+
 ---
 
 ## Key Features
 
-- **Dual-Layer Architecture:**
-  - **Skill Layer (Markdown):** Drop-in compatibility with **Claude Code**, **Cursor**, **Codex**, **Antigravity**, and **Gemini CLI**.
-  - **Runtime Layer (TypeScript):** Lightweight, zero-heavy-dependency runtime with native `fetch` and a flexible **Strategy/Factory** pattern.
-- **Native Multi-Model Routing:**
-  - Route planning, PR synthesis, and cross-review to high-reasoning tiers (**Gemini / Claude Opus / DeepSeek Reasoner**).
-  - Ingest massive codebases using long-context windows (**Gemini** with 1M tokens).
-  - Delegate closed-contract implementation tasks to cost-effective execution engines (**DeepSeek Chat** at marginal cost).
-- **Cross-Model Review Gates:** Enforce non-negotiable review separation (`Authored-by:` vs `Reviewed-by:`). No model merges its own code without independent verification.
+- **Universal Multi-Model Support:** Native cognitive guidelines and prompt specifications for **Anthropic Claude**, **OpenAI**, **Google Gemini**, and **DeepSeek**.
+- **Universal Client Compatibility:** Drop-in support for **Claude Code**, **Cursor**, **Codex**, **Google Antigravity**, and **Kimi Code / VS Code**.
+- **Cross-Model Review Gates:** Non-negotiable review separation (`Authored-by:` vs `Reviewed-by:`). No model merges its own code without independent verification from another model family or version.
 - **Contract-First Subtasks:** Tasks are bounded by strict decision budgets, file allowlists, and stop conditions (`feat(#42/T1)`).
 - **Hidden Metadata Envelopes:** HTML comments preserve machine-parseable state (`<!-- lognexus: kind: state ... -->`) without cluttering human-readable markdown.
+- **Scaffolding & Health CLI (`@digital-lake/lognexus`):** Lightweight scaffolding utility (`npx @digital-lake/lognexus init`) and environment health checking (`doctor`).
 
 ---
 
-## Why Multi-Model Routing?
+## Model-Tier Routing Matrix
 
-Empirical benchmarks and community data demonstrate that routing specialized agent tasks to provider tiers according to context, reasoning, and execution profiles drastically reduces operating costs while improving quality.
+LogNexus organizes development phases into three cognitive tiers. You can assign any model or native client to any tier according to your team's workflow and cost preferences:
 
 <p align="center">
   <img src="docs/assets/multimodel-routing-costs.png" alt="Multi-Model Routing Cost and Performance Analysis" width="85%">
@@ -56,21 +56,26 @@ Empirical benchmarks and community data demonstrate that routing specialized age
 
 ### Operational Tiers
 
-| Tier | Default Provider / Model | Primary Role |
-|---|---|---|
-| **tier-1 (Reasoning)** | Gemini Pro/Flash (High) · DeepSeek Reasoner · Claude Opus | Architectural design, brainstorm synthesis, PR timelines, and cross-model review gates. |
-| **tier-2 (Context)** | Gemini (1M Context Window) | Rapid codebase exploration, large context loading, discovery triage, and documentation. |
-| **tier-3 (Execution)** | DeepSeek Chat | Routine implementation under closed delegation contracts, subtask commits, and timeline logging. |
-
----
+| Tier | Cognitive Role | Anthropic Claude | OpenAI | Google Gemini | DeepSeek | Primary Activities |
+|---|---|---|---|---|---|---|
+| **tier-1 (Reasoning)** | Deep synthesis, architectural design, narrative review | Claude Opus 3.7 / 4.x | o3, o1, GPT-5 | Gemini 2.5 / 3.8 Pro | DeepSeek R1 | Brainstorming-to-issue planning, PR journey timeline synthesis, cross-model review sign-offs. |
+| **tier-2 (Context & Triage)** | Long context ingestion, discovery triage, structured mapping | Claude Sonnet | GPT-4.1, GPT-4o | Gemini Flash / Pro (1M context) | DeepSeek V3 | Large codebase exploration, discovery classification, knowledge retrieval. |
+| **tier-3 (Execution)** | Surgical implementation, template filling, fast execution | Claude Haiku | GPT-4o-mini | Gemini Flash | DeepSeek Chat (V3) | Subtask commits (`feat(#N/Tk)`), atomic code changes under closed contracts, timeline logging. |
 
-## Architecture & Competitive Positioning
+### Example Deployment Setups
 
-LogNexus advances agentic development workflows beyond passive markdown instructions into an active, verifiable development platform.
+LogNexus adapts to your existing toolstack. Configure your advisory preferences in `.lognexus/routing.md`:
 
-<p align="center">
-  <img src="docs/assets/competitive-gap-map.png" alt="Competitive Gap Map and Roadmap" width="85%">
-</p>
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                                 POPULAR DEPLOYMENT SETUPS                              │
+├────────────────────────────────────────────────────────────────────────────────────────┤
+│ Setup A (Anthropic Pure):  Claude Opus (t1) + Claude Sonnet (t2) + Claude Haiku (t3)   │
+│ Setup B (Google + DeepSeek): Gemini Pro (t1/t2) in Antigravity + DeepSeek Chat in Kimi │
+│ Setup C (OpenAI + DeepSeek): OpenAI o3 (t1) in Cursor + DeepSeek Chat (t3) for code    │
+│ Setup D (Claude + OpenAI):   Claude Opus (t1) for design + GPT-4o-mini (t3) for tasks  │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+```
 
 ---
 
@@ -110,58 +115,79 @@ An independent model inspects the PR diff, verifies task contracts, and signs of
 
 ---
 
-## Installation
+## Installation & Setup
+
+### 1. Scaffold Rules & Manage State with the CLI
 
-### As a Claude Code Plugin
+Initialize `.lognexus/` rules, templates, and routing configuration:
 ```bash
-# From repository
-claude plugin add digital-lake-ai/lognexus
+npx @digital-lake/lognexus init
+```
 
-# Or link locally
-claude plugin add ./path/to/lognexus
+Verify your environment anytime:
+```bash
+npx @digital-lake/lognexus doctor
 ```
 
-### Via Agent Skills (Antigravity / Cursor / Codex)
+Inspect active branch and tier advisory:
 ```bash
-npx -y skills add digital-lake-ai/lognexus
+npx @digital-lake/lognexus status
 ```
 
-### Via Global CLI
+Manage persistent agent state (`.lognexus/state.json`) and session recovery:
 ```bash
-npm install -g @digital-lake/lognexus
-lognexus doctor
+npx @digital-lake/lognexus state sync
+npx @digital-lake/lognexus state show
+npx @digital-lake/lognexus state set-task T1 "Add user schema"
+npx @digital-lake/lognexus state finish-task T1
 ```
 
----
+Quiet Mode with Git Notes (`refs/notes/lognexus`, standard `git-ai` v3):
+```bash
+npx @digital-lake/lognexus note attach HEAD
+npx @digital-lake/lognexus note show HEAD
+npx @digital-lake/lognexus note push origin
+```
 
-## Configuration
+### 2. Connect via Model Context Protocol (MCP)
 
-Configure your active provider in `.lognexus/config.json` or through environment variables:
+LogNexus includes a native, lightweight JSON-RPC 2.0 stdio server (`lognexus mcp`) with zero external SDK dependencies. Connect it to Claude Desktop, Cursor, Google Antigravity, or any MCP-compliant client:
 
-```bash
-# Provider selection
-export LOGNEXUS_PROVIDER=gemini        # 'gemini' or 'deepseek'
+**`claude_desktop_config.json` or Cursor MCP settings:**
+```json
+{
+  "mcpServers": {
+    "lognexus": {
+      "command": "npx",
+      "args": ["-y", "@digital-lake/lognexus", "mcp"]
+    }
+  }
+}
+```
 
-# Google Gemini
-export GEMINI_API_KEY="your-api-key"
-export GEMINI_MODEL="gemini-3.8-flash"
+**Exposed Capabilities:**
+- **Tools:** `lognexus_status`, `lognexus_state_get`, `lognexus_state_sync`, `lognexus_state_set_task`, `lognexus_state_finish_task`, `lognexus_state_clear`, `lognexus_note_show`, `lognexus_note_attach`
+- **Resources:** `lognexus://state`, `lognexus://routing`
+- **Prompts:** `lognexus-plan`, `lognexus-review`
 
-# DeepSeek
-export DEEPSEEK_API_KEY="your-api-key"
-export DEEPSEEK_BASE_URL="https://api.deepseek.com"
-export DEEPSEEK_MODEL="deepseek-chat"
-```
+### 3. Install Rules in Your Agent Environment
 
-Verify your environment anytime:
-```bash
-lognexus doctor
-```
+- **Claude Code:**
+  ```bash
+  claude plugin add digital-lake-ai/lognexus
+  ```
+- **Cursor / Codex / Agent Skills:**
+  ```bash
+  npx skills add digital-lake-ai/lognexus
+  ```
+- **Google Antigravity:** Active automatically via `skills/lognexus/SKILL.md` or workspace skills.
+- **Kimi Code / VS Code:** Active via `.lognexus/` workspace instructions and prompts.
 
 ---
 
 ## Disambiguation
 
-**LogNexus** by Digital Lake is an open-source development orchestrator and Git memory system for AI agents. It is not affiliated with academic research papers on industrial log compression (e.g. ISSTA 2026).
+**LogNexus** by Digital Lake is an open-source development framework and Git memory system for AI agents. It is not affiliated with academic research papers on industrial log compression (e.g. ISSTA 2026).
 
 ---
 
@@ -169,10 +195,11 @@ lognexus doctor
 
 LogNexus is an independent hard fork and continuation of [`shiplog`](https://github.com/devallibus/shiplog), originally created by **devallibus** under the MIT License.
 
-We extend our deep gratitude to **devallibus** for pioneering the concept of Git-as-knowledge-graph for AI development. LogNexus builds upon that foundation by introducing:
-- Multi-model routing with native **Google Gemini** and **DeepSeek** provider strategies.
-- A standalone TypeScript runtime and automated verification CLI.
-- Resilient backwards-compatibility for existing `.shiplog` envelopes and workflows.
+We extend our deep gratitude to **devallibus** for pioneering the concept of Git-as-knowledge-graph for AI development. LogNexus builds upon that foundation by:
+- Expanding the model ecosystem to provide first-class native support for **Google Gemini** and **DeepSeek** alongside **Claude** and **OpenAI**.
+- Formalizing the multi-model tier routing taxonomy and closed delegation contracts.
+- Introducing the repository scaffolding CLI (`@digital-lake/lognexus`).
+- Providing seamless backwards-compatibility for existing `.shiplog` envelopes and workflows.
 
 Additional inspirations and patterns are derived from [OrchestKit](https://github.com/yonatangross/orchestkit) and [Superpowers](https://github.com/obra/superpowers). Detailed license texts are preserved in the [`LICENSES/`](LICENSES/) directory and in [`NOTICE.md`](NOTICE.md).
 

package/dist/cli.js

@@ -1,112 +1,295 @@
 #!/usr/bin/env node
-import { execSync } from "node:child_process";
-import { loadConfig } from "./config/loadConfig.js";
-import { createProvider } from "./providers/factory.js";
-import { resolveTier } from "./routing/tierRouter.js";
+import { runDiagnostics } from "./doctor.js";
+import { startMcpServer } from "./mcp/server.js";
+import { attachCurrentStateToCommit } from "./notes/attach.js";
+import { fetchNotes, getNote, listNotes, pushNotes } from "./notes/notes.js";
+import { initProject } from "./scaffold.js";
+import { clearState, finishSubtask, loadState, setSubtask } from "./state/manager.js";
+import { syncStateFromGit } from "./state/sync.js";
+import { getProjectStatus } from "./status.js";
 function printHeader() {
-    console.log("\n🔷 LogNexus CLI v1.0.0-alpha.0 — Digital Lake\n");
+    console.log("\n🔷 LogNexus CLI — Digital Lake");
+    console.log("   The Universal Git-Powered Context & Rules Framework for Native AI Agents\n");
 }
-function redactKey(key) {
-    if (!key)
-        return "❌ (not set)";
-    if (key.length <= 8)
-        return "•••••••• (set)";
-    return `${key.slice(0, 4)}••••${key.slice(-4)}`;
+function printUsage() {
+    printHeader();
+    console.log(`Usage:
+  lognexus <command> [subcommand] [options]
+
+Commands:
+  init         Scaffold .lognexus/ configuration and rules in current repository
+  doctor       Check Git, GitHub CLI authentication, and repository rules health
+  status       Inspect current branch, active issue, and recommended tier
+  state        Manage persistent agent state (.lognexus/state.json)
+  note         Manage Git Notes under refs/notes/lognexus (git-ai standard)
+  mcp          Start the LogNexus MCP server (stdio JSON-RPC 2.0) for native AI agents
+  help         Display this help message
+
+State Subcommands:
+  lognexus state [show]             Display current active issue and task state
+  lognexus state sync               Sync state from current Git branch & GitHub
+  lognexus state set-task <id> [t]  Set active subtask (e.g. lognexus state set-task T1 "Add schema")
+  lognexus state finish-task <id>   Mark subtask as completed (e.g. lognexus state finish-task T1)
+  lognexus state clear              Reset persistent state to empty
+
+Note Subcommands:
+  lognexus note [show] [commit]     Display LogNexus Git Note for commit (default: HEAD)
+  lognexus note attach [commit]     Attach current session state as Git Note to commit
+  lognexus note list                List all commits with LogNexus Git Notes
+  lognexus note push [remote]       Push refs/notes/lognexus to remote (default: origin)
+  lognexus note fetch [remote]      Fetch refs/notes/lognexus from remote
+
+MCP Server:
+  lognexus mcp                      Start MCP server on stdio (JSON-RPC 2.0) for Claude Code,
+                                    Cursor, VS Code, Antigravity or any MCP-compatible client
+  Tools:     lognexus_status, lognexus_state_get, lognexus_state_sync, lognexus_state_set_task,
+             lognexus_state_finish_task, lognexus_state_clear, lognexus_note_show, lognexus_note_attach
+  Resources: lognexus://state, lognexus://routing
+  Prompts:   lognexus-plan, lognexus-review
+
+Examples:
+  npx @digital-lake/lognexus init
+  npx @digital-lake/lognexus state sync
+  npx @digital-lake/lognexus note attach HEAD
+  npx @digital-lake/lognexus note show HEAD
+  npx @digital-lake/lognexus mcp
+`);
 }
-async function runDoctor(args) {
+async function handleInit() {
     printHeader();
-    console.log("Running diagnostics...\n");
-    const live = args.includes("--live");
-    // 1. Git Check
-    try {
-        const gitVer = execSync("git --version", { encoding: "utf-8" }).trim();
-        const isRepo = execSync("git rev-parse --is-inside-work-tree", {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "ignore"],
-        }).trim();
-        console.log(`[PASS] Git: ${gitVer} (inside git repository: ${isRepo})`);
-    }
-    catch {
-        console.log("[FAIL] Git: Git command failed or not in a git repository");
-    }
-    // 2. GitHub CLI Check
-    try {
-        const ghVer = execSync("gh --version", { encoding: "utf-8" }).split("\n")[0];
-        console.log(`[PASS] GitHub CLI: ${ghVer}`);
-    }
-    catch {
-        console.log("[WARN] GitHub CLI: 'gh' not found in PATH or not installed");
-    }
-    // 3. Load Configuration
-    const config = loadConfig();
-    console.log(`\n[INFO] Active Provider Strategy: ${config.provider.toUpperCase()}`);
-    console.log(`  - Gemini Key:   ${redactKey(config.gemini.apiKey)}`);
-    console.log(`  - Gemini Model: ${config.gemini.model}`);
-    console.log(`  - DeepSeek Key: ${redactKey(config.deepseek.apiKey)}`);
-    console.log(`  - DeepSeek Model: ${config.deepseek.model}`);
-    // 4. Live Provider Connectivity Check (Optional)
-    if (live) {
-        console.log("\nTesting live API connectivity...");
-        if (config.gemini.apiKey) {
-            const gemini = createProvider("gemini", config);
-            const health = await gemini.healthCheck();
-            console.log(`  - Gemini Live: ${health.ok ? "✅ PASS" : "❌ FAIL"} — ${health.message}`);
+    console.log("Initializing LogNexus in current repository...\n");
+    const res = initProject();
+    if (res.created.length > 0) {
+        console.log("Created files:");
+        for (const f of res.created) {
+            console.log(`  [+] ${f}`);
         }
-        if (config.deepseek.apiKey) {
-            const deepseek = createProvider("deepseek", config);
-            const health = await deepseek.healthCheck();
-            console.log(`  - DeepSeek Live: ${health.ok ? "✅ PASS" : "❌ FAIL"} — ${health.message}`);
+    }
+    if (res.skipped.length > 0) {
+        console.log("Existing files (skipped):");
+        for (const f of res.skipped) {
+            console.log(`  [.] ${f}`);
         }
     }
-    else {
-        console.log("\nTip: Pass --live to verify API keys with real connectivity checks.");
+    console.log("\nNext Steps:");
+    console.log("  • Claude Code / Cursor / Codex / Antigravity / Kimi: use /lognexus plan");
+    console.log("  • Configure model tiers in .lognexus/routing.md");
+    console.log("  • Verify environment anytime with: npx @digital-lake/lognexus doctor\n");
+}
+async function handleDoctor() {
+    printHeader();
+    console.log("Running diagnostics...\n");
+    const checks = runDiagnostics();
+    for (const c of checks) {
+        const tag = c.status === "pass" ? "[PASS]" : c.status === "warn" ? "[WARN]" : "[FAIL]";
+        console.log(`${tag} ${c.name}: ${c.message}`);
     }
     console.log("\nDiagnostic complete.\n");
 }
-function runRoute(args) {
-    const tierArg = args[0];
-    if (!tierArg || !["tier-1", "tier-2", "tier-3"].includes(tierArg)) {
-        console.error("Usage: lognexus route <tier-1 | tier-2 | tier-3>");
-        process.exit(1);
+async function handleStatus() {
+    printHeader();
+    const st = getProjectStatus();
+    console.log(`Git Repository:     ${st.isInsideGit ? "Yes" : "No"}`);
+    console.log(`Current Branch:     ${st.branch}`);
+    console.log(`Active Issue:       ${st.activeIssue ?? "(none — on base branch)"}`);
+    console.log(`Rules Routing Mode: ${st.routingMode}`);
+    console.log(`Recommended Tier:   ${st.recommendedTier}\n`);
+}
+async function handleState(args) {
+    const sub = args[0]?.toLowerCase() || "show";
+    switch (sub) {
+        case "show": {
+            printHeader();
+            const state = loadState();
+            console.log("Persistent Agent State (.lognexus/state.json):\n");
+            if (state.activeIssue) {
+                console.log(`Active Issue:      #${state.activeIssue.id} — ${state.activeIssue.title}`);
+                console.log(`Branch:            ${state.activeIssue.branch}`);
+                console.log(`Phase:             ${state.activeIssue.phase}`);
+                console.log(`Tier:              ${state.activeIssue.tier}`);
+                console.log(`Readiness:         ${state.activeIssue.readiness}`);
+            }
+            else {
+                console.log("Active Issue:      (none)");
+            }
+            console.log("");
+            if (state.currentSubtask) {
+                console.log(`Current Subtask:   ${state.currentSubtask.id} (${state.currentSubtask.status})`);
+                if (state.currentSubtask.title) {
+                    console.log(`  Title:           ${state.currentSubtask.title}`);
+                }
+                if (state.currentSubtask.contract) {
+                    console.log(`  Allowed Files:   ${state.currentSubtask.contract.allowedFiles.join(", ") || "(all)"}`);
+                    console.log(`  Decision Budget: ${state.currentSubtask.contract.decisionBudget}`);
+                    if (state.currentSubtask.contract.verificationCmd) {
+                        console.log(`  Verify Command:  ${state.currentSubtask.contract.verificationCmd}`);
+                    }
+                }
+            }
+            else {
+                console.log("Current Subtask:   (none)");
+            }
+            console.log(`Completed Tasks:   ${state.completedSubtasks.length > 0 ? state.completedSubtasks.join(", ") : "(none)"}`);
+            console.log(`Last Synchronized: ${state.lastSync}\n`);
+            break;
+        }
+        case "sync": {
+            printHeader();
+            console.log("Synchronizing state from current Git branch and GitHub...\n");
+            const synced = syncStateFromGit();
+            if (synced.activeIssue) {
+                console.log(`[OK] Synchronized with Issue #${synced.activeIssue.id} (${synced.activeIssue.title})`);
+                console.log(`     Branch: ${synced.activeIssue.branch}`);
+            }
+            else {
+                console.log("[OK] Synchronized. No active issue detected on current branch.");
+            }
+            console.log("");
+            break;
+        }
+        case "set-task": {
+            const taskId = args[1];
+            const title = args.slice(2).join(" ");
+            if (!taskId) {
+                console.error("Error: Subtask ID is required (e.g. lognexus state set-task T1 'Add schema')\n");
+                process.exit(1);
+            }
+            printHeader();
+            setSubtask(taskId, title);
+            console.log(`[OK] Active subtask set to: ${taskId}${title ? ` — ${title}` : ""}\n`);
+            break;
+        }
+        case "finish-task": {
+            const taskId = args[1];
+            if (!taskId) {
+                console.error("Error: Subtask ID is required (e.g. lognexus state finish-task T1)\n");
+                process.exit(1);
+            }
+            printHeader();
+            finishSubtask(taskId);
+            console.log(`[OK] Subtask ${taskId} marked as completed.\n`);
+            break;
+        }
+        case "clear": {
+            printHeader();
+            clearState();
+            console.log("[OK] Persistent state cleared.\n");
+            break;
+        }
+        default:
+            console.error(`Unknown state subcommand: ${sub}\n`);
+            printUsage();
+            process.exit(1);
     }
-    const tier = tierArg;
-    const config = loadConfig();
-    const assignment = resolveTier(tier, config);
-    console.log(`\n🔷 LogNexus Tier Route: [${assignment.tier}]`);
-    console.log(`Provider: ${assignment.provider.id}`);
-    console.log(`Model:    ${assignment.model}`);
-    console.log(`Purpose:  ${assignment.description}\n`);
 }
-function runHelp() {
-    printHeader();
-    console.log("Usage: lognexus <command> [options]\n");
-    console.log("Commands:");
-    console.log("  doctor [--live]     Run environment and credentials diagnostic");
-    console.log("  route <tier>        Resolve assigned model/provider for a tier (tier-1, tier-2, tier-3)");
-    console.log("  config              Display sanitized configuration");
-    console.log("  help                Show this help message\n");
+async function handleNote(args) {
+    const sub = args[0]?.toLowerCase() || "show";
+    switch (sub) {
+        case "show": {
+            const commit = args[1] || "HEAD";
+            printHeader();
+            const note = getNote(commit);
+            if (note) {
+                console.log(`Git Note for commit [${commit}] (refs/notes/lognexus):\n`);
+                console.log(note);
+            }
+            else {
+                console.log(`No LogNexus note found attached to commit [${commit}].`);
+                console.log("Tip: Run 'lognexus note attach' to attach current state to this commit.");
+            }
+            console.log("");
+            break;
+        }
+        case "attach": {
+            const commit = args[1] || "HEAD";
+            printHeader();
+            const payload = attachCurrentStateToCommit(commit);
+            console.log(`[OK] Attached LogNexus note to commit [${commit}] (refs/notes/lognexus):`);
+            console.log(`     Issue:   ${payload.issue ? `#${payload.issue.id} — ${payload.issue.title}` : "(none)"}`);
+            console.log(`     Subtask: ${payload.subtask ? `${payload.subtask.id} (${payload.subtask.title})` : "(none)"}`);
+            console.log(`     Tier:    ${payload.tier}\n`);
+            break;
+        }
+        case "list": {
+            printHeader();
+            const notes = listNotes();
+            console.log(`LogNexus Notes (refs/notes/lognexus) — ${notes.length} note(s):\n`);
+            if (notes.length === 0) {
+                console.log("No notes recorded yet.");
+            }
+            else {
+                for (const n of notes) {
+                    console.log(`  • Commit: ${n.commitSha} (blob: ${n.noteBlob})`);
+                }
+            }
+            console.log("");
+            break;
+        }
+        case "push": {
+            const remote = args[1] || "origin";
+            printHeader();
+            console.log(`Pushing refs/notes/lognexus to ${remote}...`);
+            const ok = pushNotes(remote);
+            if (ok) {
+                console.log(`[OK] Notes pushed to ${remote} successfully.\n`);
+            }
+            else {
+                console.error(`[FAIL] Could not push notes to ${remote}.\n`);
+            }
+            break;
+        }
+        case "fetch": {
+            const remote = args[1] || "origin";
+            printHeader();
+            console.log(`Fetching refs/notes/lognexus from ${remote}...`);
+            const ok = fetchNotes(remote);
+            if (ok) {
+                console.log(`[OK] Notes fetched from ${remote} successfully.\n`);
+            }
+            else {
+                console.error(`[FAIL] Could not fetch notes from ${remote}.\n`);
+            }
+            break;
+        }
+        default:
+            console.error(`Unknown note subcommand: ${sub}\n`);
+            printUsage();
+            process.exit(1);
+    }
 }
 async function main() {
-    const command = process.argv[2] || "help";
-    const args = process.argv.slice(3);
+    const args = process.argv.slice(2);
+    const command = args[0]?.toLowerCase();
     switch (command) {
+        case "init":
+            await handleInit();
+            break;
         case "doctor":
-            await runDoctor(args);
+            await handleDoctor();
             break;
-        case "route":
-            runRoute(args);
+        case "status":
+            await handleStatus();
             break;
-        case "config":
-            printHeader();
-            console.log(JSON.stringify({
-                ...loadConfig(),
-                gemini: { ...loadConfig().gemini, apiKey: redactKey(loadConfig().gemini.apiKey) },
-                deepseek: { ...loadConfig().deepseek, apiKey: redactKey(loadConfig().deepseek.apiKey) },
-            }, null, 2));
+        case "state":
+            await handleState(args.slice(1));
             break;
-        default:
-            runHelp();
+        case "note":
+            await handleNote(args.slice(1));
             break;
+        case "mcp":
+            // stdout is reserved for JSON-RPC frames: never print the banner here.
+            await startMcpServer();
+            break;
+        case "help":
+        case "--help":
+        case "-h":
+        case undefined:
+            printUsage();
+            break;
+        default:
+            console.error(`Unknown command: ${command}\n`);
+            printUsage();
+            process.exit(1);
     }
 }
 main().catch((err) => {