sinapse-ai 9.3.0 → 9.5.0

package/.sinapse-ai/development/workflows/fast-track.yaml

@@ -0,0 +1,87 @@
+workflow:
+  id: fast-track
+  name: Fast-Track Fix
+  version: "1.0"
+  description: >-
+    Streamlined workflow for trivial fixes that bypasses full story validation.
+    Auto-generates a Ready story, simplified QA (lint + typecheck + test only).
+  type: fast-fix
+
+  eligibility:
+    all_required:
+      - type: [bugfix, docs, typo, config]
+      - lines_changed: "<= 50"
+      - files_changed: "<= 3"
+      - no_new_dependencies: true
+      - no_architecture_or_api_or_schema_changes: true
+
+  metadata:
+    elicit: false
+    confirmation_required: false
+
+  execution_modes:
+    - mode: yolo
+      description: Fully autonomous
+      prompts: 0
+      default: true
+
+  phases:
+    - phase_1: Auto Story + Implement
+    - phase_2: Simplified QA
+
+  sequence:
+    - step: auto_story_and_implement
+      id: implement
+      phase: 1
+      agent: developer
+      action: Auto-generate story + implement fix
+      notes: |
+        1. Generate story: docs/stories/active/fast-track-{timestamp}.story.md
+           Status: Ready (auto-validated), Type: bugfix|docs|typo|config
+           AC: "Fix applied and verified by automated checks"
+        2. Implement the fix
+        3. Verify eligibility: diff <= 50 lines, <= 3 files, no dep changes
+        4. If eligibility fails → STOP, switch to full SDC
+        5. Commit with conventional message referencing story
+      outputs: [story_file, implementation_files, commit_hash]
+      next: quick_qa
+
+    - step: quick_qa
+      id: quick_qa
+      phase: 2
+      agent: developer
+      action: Automated checks only (no full QA gate)
+      requires: implement
+      notes: |
+        1. npm run lint (must pass)
+        2. npm run typecheck (must pass)
+        3. npm test (must pass, no new failures)
+        If all pass → mark story Done, ready for push.
+        If fail → fix and retry (max 2 iterations).
+        After 2 failures → escalate to full SDC.
+        No CodeRabbit. No @quality-gate involvement.
+      outputs: [lint_result, typecheck_result, test_result, story_final_status]
+      next: complete
+      on_failure: implement
+
+    - workflow_end:
+        id: complete
+        action: fast_track_complete
+        notes: Fast-track complete. Story auto-closed, ready for @devops push.
+
+  flow_diagram: |
+    Eligible? → [Yes] dev: auto-story + implement → lint+typecheck+test
+    → [Pass] Done | [Fail, iter<2] retry | [Fail, iter>=2] escalate to SDC
+
+  decision_guidance:
+    when_to_use:
+      - Single-line bug fixes, typos, config changes
+      - Import path fixes, small renames
+    when_not_to_use:
+      - New features, API/DB changes, 4+ files, architecture changes
+
+metadata:
+  author: SINAPSE Framework
+  created_date: 2026-04-10
+  version: 1.0.0
+  tags: [fast-track, bugfix, lightweight, simplified-qa]

package/.sinapse-ai/development/workflows/story-development-cycle.yaml

@@ -272,14 +272,53 @@ workflow:
 
       Retornando para Dev corrigir...
 
+  # ──────────────────────────────────────────────────────────────────────────
+  # Agent Handoff Compaction — wired v1.1 (fw-v2.6, EPIC-framework-upgrade-v2)
+  # ──────────────────────────────────────────────────────────────────────────
+  # Operational enforcement of the handoff compaction protocol. The outgoing
+  # agent of each phase MUST run `generate-agent-handoff` task before the
+  # incoming agent is activated. This collapses persona context from ~3-5K
+  # tokens to ~379 per switch (90%+ compaction).
+  #
+  # Reference:
+  #   - Task: .sinapse-ai/development/tasks/generate-agent-handoff.md
+  #   - Rule: .claude/rules/agent-handoff.md
+  #   - Template: .sinapse-ai/development/templates/agent-handoff-tmpl.yaml
+  handoff_hooks:
+    enabled: true
+    task: generate-agent-handoff
+    transitions:
+      - from: create        # sprint-lead (sm)
+        to: validate        # product-lead (po)
+        required: true
+      - from: validate      # product-lead (po)
+        to: implement       # developer (dev)
+        required: true
+      - from: implement     # developer (dev)
+        to: review          # quality-gate (qa)
+        required: true
+    storage: ".sinapse/handoffs/"
+    max_tokens_per_artifact: 500
+    on_failure: "warn-and-proceed"  # per graceful-degradation principle in ids-principles.md
+
 metadata:
   author: Orion (SINAPSE Master)
   created_date: 2025-01-30
-  version: 1.0.0
+  version: 1.1.0
+  version_history:
+    - version: 1.0.0
+      date: 2025-01-30
+      author: Orion
+      notes: "Initial 4-phase SDC workflow"
+    - version: 1.1.0
+      date: 2026-04-12
+      author: "Imperator (sinapse-orqx) via fw-v2.6"
+      notes: "Wired handoff_hooks to enforce agent handoff compaction between phase transitions. No breaking changes — existing sequence untouched."
   tags:
     - story
     - development-cycle
     - quality-gate
     - agile
     - generic
+    - handoff-compaction
 

package/.sinapse-ai/hooks/ids-post-commit.js

@@ -111,6 +111,28 @@ async function main() {
     // Post-commit hook should NEVER block workflow
     console.error(`[IDS-Hook] Registry update failed (non-blocking): ${err.message}`);
   }
+
+  // Story 10.27 — When .sinapse-ai/ files changed, the registry update we
+  // just ran (and any other auto-managed file under .sinapse-ai/) needs the
+  // install-manifest.yaml to be refreshed too, otherwise the next commit's
+  // pre-commit hook will print "manifest outdated". Regenerate it here so
+  // the working tree converges to a clean state after every commit.
+  const sinapseChanges = changes.some(
+    (c) => c.relativePath && c.relativePath.startsWith('.sinapse-ai/'),
+  );
+  if (sinapseChanges) {
+    try {
+      const { generateManifest, writeManifest } = require(
+        path.resolve(REPO_ROOT, 'scripts/generate-install-manifest.js'),
+      );
+      const manifest = await generateManifest();
+      await writeManifest(manifest);
+      console.log('[IDS-Hook] install-manifest.yaml regenerated to stay in sync.');
+    } catch (err) {
+      // Same non-blocking philosophy as the registry update
+      console.error(`[IDS-Hook] Manifest regen failed (non-blocking): ${err.message}`);
+    }
+  }
 }
 
 main();

package/.sinapse-ai/infrastructure/contracts/compatibility/README.md

@@ -0,0 +1,42 @@
+# Compatibility Contracts
+
+This directory stores the cross-IDE compatibility contracts read by
+`.sinapse-ai/infrastructure/scripts/validate-parity.js`.
+
+## Files
+
+| File | Purpose | When to edit |
+|------|---------|--------------|
+| `sinapse-current.yaml` | Authoritative contract for the current release | Whenever the IDE matrix, required-checks, or expected statuses change |
+| `sinapse-4.0.4.yaml` | Historical snapshot of the 4.0.4-era contract | Never (kept as a frozen reference for diffing) |
+
+## Resolution Policy
+
+The validator's `getDefaultContractPath()` always prefers `sinapse-current.yaml`
+when it exists on disk. The legacy `sinapse-4.0.4.yaml` is read only as a
+fallback for repositories that have not yet been migrated.
+
+Story 10.18 introduced this split because pinning the validator to a single
+versioned filename caused the contract to silently track a stale release for
+five major versions (4.0.4 → 9.4.0 → v10.0.0 target).
+
+## Updating the Contract
+
+1. Edit `sinapse-current.yaml` in place.
+2. Bump the `release` field to the new SINAPSE version label (e.g. `SINAPSE 10.1.0`).
+3. Bump `updated_at` to today's date (ISO format).
+4. Run `npm run validate:parity` to verify the new contract still passes.
+5. If the change adds or removes a required check, run `npm test` to make
+   sure no parity unit test is hard-coded to the old shape.
+
+## Diffing Two Contracts
+
+Use the validator's `--diff` flag to compare the current contract against
+any historical snapshot:
+
+```bash
+npm run validate:parity -- --diff=.sinapse-ai/infrastructure/contracts/compatibility/sinapse-4.0.4.yaml
+```
+
+The diff output is shown both in the human-readable report and in `--json`
+mode under `contractDiff`.

package/.sinapse-ai/infrastructure/contracts/compatibility/sinapse-current.yaml

@@ -0,0 +1,35 @@
+# Compatibility Contract — current
+#
+# This file is the authoritative compatibility contract for the CURRENT release.
+# When the IDE matrix or required-checks set changes, edit this file in place
+# and bump the release/updated_at fields.
+#
+# A snapshot of the previous contract may be kept under a versioned name
+# (e.g. sinapse-4.0.4.yaml) to support contract diffing via the validator's
+# --diff=<path> flag, but the loader always prefers sinapse-current.yaml.
+#
+# See README.md in this directory for the versioning policy.
+
+release: "SINAPSE 10.0.0"
+updated_at: "2026-04-12"
+source_of_truth:
+  docs_matrix: "docs/ide-integration.md"
+  validator: ".sinapse-ai/infrastructure/scripts/validate-parity.js"
+
+global_required_checks:
+  - paths
+
+ide_matrix:
+  - ide: "claude-code"
+    display_name: "Claude Code"
+    expected_status: "Works"
+    required_checks:
+      - claude-sync
+      - claude-integration
+  - ide: "codex"
+    display_name: "Codex CLI"
+    expected_status: "Limited"
+    required_checks:
+      - codex-sync
+      - codex-integration
+      - codex-skills

package/.sinapse-ai/infrastructure/scripts/llm-routing/templates/claude-free-tracked.cmd

@@ -1,127 +1,127 @@
-@echo off
-:: Claude Code - DeepSeek Native Mode with Usage Tracking
-:: Routes through local proxy to track per-alias usage
-:: Cost: ~$0.14/M tokens with tool calling support
-
-setlocal enabledelayedexpansion
-
-:: Configuration
-set "PROXY_PORT=8787"
-set "ALIAS=claude-free"
-
-:: Find tracker script
-if defined SINAPSE_HOME (
-    set "TRACKER_SCRIPT=%SINAPSE_HOME%\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
-    if exist "!TRACKER_SCRIPT!" goto :tracker_found
-)
-set "TRACKER_SCRIPT=%USERPROFILE%\sinapse-ai\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
-if exist "%TRACKER_SCRIPT%" goto :tracker_found
-set "TRACKER_SCRIPT=%USERPROFILE%\Workspaces\SINAPSE\SinapseAI\sinapse-ai\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
-if exist "%TRACKER_SCRIPT%" goto :tracker_found
-set "TRACKER_SCRIPT=%~dp0..\usage-tracker\index.js"
-:tracker_found
-
-:: Find project root (look for .env file)
-set "PROJECT_ROOT=%CD%"
-set /a "LOOP_COUNT=0"
-:find_env
-set /a "LOOP_COUNT+=1"
-if %LOOP_COUNT% gtr 50 goto :no_env
-if exist "%PROJECT_ROOT%\.env" goto :found_env
-if "%PROJECT_ROOT%"=="%PROJECT_ROOT:~0,3%" goto :no_env
-for %%i in ("%PROJECT_ROOT%\..") do set "PROJECT_ROOT=%%~fi"
-goto :find_env
-
-:no_env
-if not "%DEEPSEEK_API_KEY%"=="" goto :use_env_key
-
-echo.
-echo [91mERROR: No .env file found and DEEPSEEK_API_KEY not set![0m
-echo.
-echo Options:
-echo   1. Create .env in your project: cp .env.example .env
-echo   2. Set DEEPSEEK_API_KEY in the .env file
-echo   3. Or set it globally: setx DEEPSEEK_API_KEY "sk-your-key"
-echo.
-echo Get your API key at: https://platform.deepseek.com/api_keys
-echo.
-pause
-exit /b 1
-
-:found_env
-:: Load DEEPSEEK_API_KEY from .env
-for /f "usebackq eol=# tokens=1,* delims==" %%a in ("%PROJECT_ROOT%\.env") do (
-    if "%%a"=="DEEPSEEK_API_KEY" set "DEEPSEEK_API_KEY=%%b"
-)
-set "DEEPSEEK_API_KEY=!DEEPSEEK_API_KEY:"=!"
-
-if "!DEEPSEEK_API_KEY!"=="" (
-    echo.
-    echo [91mERROR: DEEPSEEK_API_KEY not found in .env![0m
-    echo.
-    pause
-    exit /b 1
-)
-
-:use_env_key
-:: Check if proxy is running
-curl -s http://127.0.0.1:%PROXY_PORT%/health >nul 2>&1
-if %errorlevel% neq 0 (
-    echo.
-    echo [93mUsage Tracker proxy not running. Starting in background...[0m
-
-    :: Start proxy in background
-    start /b "" node "%TRACKER_SCRIPT%" start --port=%PROXY_PORT% --alias=%ALIAS% >nul 2>&1
-
-    :: Wait for proxy to start
-    timeout /t 2 /nobreak >nul
-
-    :: Verify it started
-    curl -s http://127.0.0.1:%PROXY_PORT%/health >nul 2>&1
-    if %errorlevel% neq 0 (
-        echo [91mFailed to start proxy. Falling back to direct connection.[0m
-        goto :direct_connection
-    )
-    echo [92mProxy started successfully![0m
-)
-
-:: Use local proxy (proxy will forward to DeepSeek with original API key)
-set ANTHROPIC_BASE_URL=http://127.0.0.1:%PROXY_PORT%/anthropic
-set ANTHROPIC_API_KEY=%DEEPSEEK_API_KEY%
-set ANTHROPIC_MODEL=deepseek-chat
-set API_TIMEOUT_MS=600000
-
-echo.
-echo [92mClaude Code - DeepSeek Native Mode (TRACKED)[0m
-echo Proxy: 127.0.0.1:%PROXY_PORT%
-echo Alias: %ALIAS%
-echo [92mTool Calling: SUPPORTED[0m
-echo Cost: ~$0.14/M tokens
-echo.
-echo [96mUsage tracking enabled. Run 'deepseek-usage' to view stats.[0m
-echo.
-
-goto :run_claude
-
-:direct_connection
-:: Direct connection without tracking
-set ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
-set ANTHROPIC_API_KEY=%DEEPSEEK_API_KEY%
-set ANTHROPIC_MODEL=deepseek-chat
-set API_TIMEOUT_MS=600000
-
-echo.
-echo [92mClaude Code - DeepSeek Native Mode (DIRECT)[0m
-echo Endpoint: api.deepseek.com/anthropic
-echo [93mUsage tracking: DISABLED (proxy not running)[0m
-echo.
-
-:run_claude
-endlocal & set "ANTHROPIC_BASE_URL=%ANTHROPIC_BASE_URL%" & set "ANTHROPIC_API_KEY=%DEEPSEEK_API_KEY%" & set "ANTHROPIC_MODEL=deepseek-chat" & set "API_TIMEOUT_MS=600000"
-
->&2 echo.
->&2 echo [93mWARNING: Running with --dangerously-skip-permissions (no confirmation prompts)[0m
->&2 echo [93mOnly use in trusted repositories/environments.[0m
->&2 echo.
-
-claude --dangerously-skip-permissions %*
+@echo off
+:: Claude Code - DeepSeek Native Mode with Usage Tracking
+:: Routes through local proxy to track per-alias usage
+:: Cost: ~$0.14/M tokens with tool calling support
+
+setlocal enabledelayedexpansion
+
+:: Configuration
+set "PROXY_PORT=8787"
+set "ALIAS=claude-free"
+
+:: Find tracker script
+if defined SINAPSE_HOME (
+    set "TRACKER_SCRIPT=%SINAPSE_HOME%\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
+    if exist "!TRACKER_SCRIPT!" goto :tracker_found
+)
+set "TRACKER_SCRIPT=%USERPROFILE%\sinapse-ai\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
+if exist "%TRACKER_SCRIPT%" goto :tracker_found
+set "TRACKER_SCRIPT=%USERPROFILE%\Workspaces\SINAPSE\SinapseAI\sinapse-ai\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
+if exist "%TRACKER_SCRIPT%" goto :tracker_found
+set "TRACKER_SCRIPT=%~dp0..\usage-tracker\index.js"
+:tracker_found
+
+:: Find project root (look for .env file)
+set "PROJECT_ROOT=%CD%"
+set /a "LOOP_COUNT=0"
+:find_env
+set /a "LOOP_COUNT+=1"
+if %LOOP_COUNT% gtr 50 goto :no_env
+if exist "%PROJECT_ROOT%\.env" goto :found_env
+if "%PROJECT_ROOT%"=="%PROJECT_ROOT:~0,3%" goto :no_env
+for %%i in ("%PROJECT_ROOT%\..") do set "PROJECT_ROOT=%%~fi"
+goto :find_env
+
+:no_env
+if not "%DEEPSEEK_API_KEY%"=="" goto :use_env_key
+
+echo.
+echo [91mERROR: No .env file found and DEEPSEEK_API_KEY not set![0m
+echo.
+echo Options:
+echo   1. Create .env in your project: cp .env.example .env
+echo   2. Set DEEPSEEK_API_KEY in the .env file
+echo   3. Or set it globally: setx DEEPSEEK_API_KEY "sk-your-key"
+echo.
+echo Get your API key at: https://platform.deepseek.com/api_keys
+echo.
+pause
+exit /b 1
+
+:found_env
+:: Load DEEPSEEK_API_KEY from .env
+for /f "usebackq eol=# tokens=1,* delims==" %%a in ("%PROJECT_ROOT%\.env") do (
+    if "%%a"=="DEEPSEEK_API_KEY" set "DEEPSEEK_API_KEY=%%b"
+)
+set "DEEPSEEK_API_KEY=!DEEPSEEK_API_KEY:"=!"
+
+if "!DEEPSEEK_API_KEY!"=="" (
+    echo.
+    echo [91mERROR: DEEPSEEK_API_KEY not found in .env![0m
+    echo.
+    pause
+    exit /b 1
+)
+
+:use_env_key
+:: Check if proxy is running
+curl -s http://127.0.0.1:%PROXY_PORT%/health >nul 2>&1
+if %errorlevel% neq 0 (
+    echo.
+    echo [93mUsage Tracker proxy not running. Starting in background...[0m
+
+    :: Start proxy in background
+    start /b "" node "%TRACKER_SCRIPT%" start --port=%PROXY_PORT% --alias=%ALIAS% >nul 2>&1
+
+    :: Wait for proxy to start
+    timeout /t 2 /nobreak >nul
+
+    :: Verify it started
+    curl -s http://127.0.0.1:%PROXY_PORT%/health >nul 2>&1
+    if %errorlevel% neq 0 (
+        echo [91mFailed to start proxy. Falling back to direct connection.[0m
+        goto :direct_connection
+    )
+    echo [92mProxy started successfully![0m
+)
+
+:: Use local proxy (proxy will forward to DeepSeek with original API key)
+set ANTHROPIC_BASE_URL=http://127.0.0.1:%PROXY_PORT%/anthropic
+set ANTHROPIC_API_KEY=%DEEPSEEK_API_KEY%
+set ANTHROPIC_MODEL=deepseek-chat
+set API_TIMEOUT_MS=600000
+
+echo.
+echo [92mClaude Code - DeepSeek Native Mode (TRACKED)[0m
+echo Proxy: 127.0.0.1:%PROXY_PORT%
+echo Alias: %ALIAS%
+echo [92mTool Calling: SUPPORTED[0m
+echo Cost: ~$0.14/M tokens
+echo.
+echo [96mUsage tracking enabled. Run 'deepseek-usage' to view stats.[0m
+echo.
+
+goto :run_claude
+
+:direct_connection
+:: Direct connection without tracking
+set ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
+set ANTHROPIC_API_KEY=%DEEPSEEK_API_KEY%
+set ANTHROPIC_MODEL=deepseek-chat
+set API_TIMEOUT_MS=600000
+
+echo.
+echo [92mClaude Code - DeepSeek Native Mode (DIRECT)[0m
+echo Endpoint: api.deepseek.com/anthropic
+echo [93mUsage tracking: DISABLED (proxy not running)[0m
+echo.
+
+:run_claude
+endlocal & set "ANTHROPIC_BASE_URL=%ANTHROPIC_BASE_URL%" & set "ANTHROPIC_API_KEY=%DEEPSEEK_API_KEY%" & set "ANTHROPIC_MODEL=deepseek-chat" & set "API_TIMEOUT_MS=600000"
+
+>&2 echo.
+>&2 echo [93mWARNING: Running with --dangerously-skip-permissions (no confirmation prompts)[0m
+>&2 echo [93mOnly use in trusted repositories/environments.[0m
+>&2 echo.
+
+claude --dangerously-skip-permissions %*

package/.sinapse-ai/infrastructure/scripts/llm-routing/templates/deepseek-proxy.cmd

@@ -1,71 +1,71 @@
-@echo off
-:: DeepSeek Usage Tracker Proxy Manager
-:: Start/stop the tracking proxy server
-
-setlocal enabledelayedexpansion
-
-set "PROXY_PORT=8787"
-
-:: Try multiple locations for the tracker script
-if defined SINAPSE_HOME (
-    set "TRACKER_SCRIPT=%SINAPSE_HOME%\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
-    if exist "!TRACKER_SCRIPT!" goto :found
-)
-
-set "TRACKER_SCRIPT=%USERPROFILE%\sinapse-ai\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
-if exist "%TRACKER_SCRIPT%" goto :found
-
-set "TRACKER_SCRIPT=%USERPROFILE%\Workspaces\SINAPSE\SinapseAI\sinapse-ai\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
-if exist "%TRACKER_SCRIPT%" goto :found
-
-set "TRACKER_SCRIPT=%~dp0..\usage-tracker\index.js"
-if exist "%TRACKER_SCRIPT%" goto :found
-
-echo [91mERROR: Usage tracker not found![0m
-exit /b 1
-
-:found
-:: Check if Node.js is available
-where node >nul 2>&1
-if %errorlevel% neq 0 (
-    echo [91mERROR: Node.js not found in PATH[0m
-    exit /b 1
-)
-
-if "%1"=="start" (
-    echo Starting DeepSeek Usage Tracker Proxy...
-    node "%TRACKER_SCRIPT%" start --port=%PROXY_PORT% --alias=claude-free
-    goto :eof
-)
-
-if "%1"=="stop" (
-    echo Stopping proxy on port %PROXY_PORT%...
-    for /f "tokens=5" %%a in ('netstat -ano ^| findstr ":%PROXY_PORT%.*LISTENING"') do (
-        taskkill /PID %%a /F >nul 2>&1
-    )
-    echo Proxy stopped.
-    goto :eof
-)
-
-if "%1"=="status" (
-    curl -s http://127.0.0.1:%PROXY_PORT%/health >nul 2>&1
-    if %errorlevel% equ 0 (
-        echo [92mProxy is running on port %PROXY_PORT%[0m
-        curl -s http://127.0.0.1:%PROXY_PORT%/health
-    ) else (
-        echo [93mProxy is not running[0m
-    )
-    goto :eof
-)
-
-echo DeepSeek Usage Tracker Proxy
-echo.
-echo Usage:
-echo   deepseek-proxy start   Start the proxy server
-echo   deepseek-proxy stop    Stop the proxy server
-echo   deepseek-proxy status  Check if proxy is running
-echo.
-echo The proxy runs on port %PROXY_PORT% by default.
-echo.
-
-endlocal
+@echo off
+:: DeepSeek Usage Tracker Proxy Manager
+:: Start/stop the tracking proxy server
+
+setlocal enabledelayedexpansion
+
+set "PROXY_PORT=8787"
+
+:: Try multiple locations for the tracker script
+if defined SINAPSE_HOME (
+    set "TRACKER_SCRIPT=%SINAPSE_HOME%\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
+    if exist "!TRACKER_SCRIPT!" goto :found
+)
+
+set "TRACKER_SCRIPT=%USERPROFILE%\sinapse-ai\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
+if exist "%TRACKER_SCRIPT%" goto :found
+
+set "TRACKER_SCRIPT=%USERPROFILE%\Workspaces\SINAPSE\SinapseAI\sinapse-ai\.sinapse-ai\infrastructure\scripts\llm-routing\usage-tracker\index.js"
+if exist "%TRACKER_SCRIPT%" goto :found
+
+set "TRACKER_SCRIPT=%~dp0..\usage-tracker\index.js"
+if exist "%TRACKER_SCRIPT%" goto :found
+
+echo [91mERROR: Usage tracker not found![0m
+exit /b 1
+
+:found
+:: Check if Node.js is available
+where node >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [91mERROR: Node.js not found in PATH[0m
+    exit /b 1
+)
+
+if "%1"=="start" (
+    echo Starting DeepSeek Usage Tracker Proxy...
+    node "%TRACKER_SCRIPT%" start --port=%PROXY_PORT% --alias=claude-free
+    goto :eof
+)
+
+if "%1"=="stop" (
+    echo Stopping proxy on port %PROXY_PORT%...
+    for /f "tokens=5" %%a in ('netstat -ano ^| findstr ":%PROXY_PORT%.*LISTENING"') do (
+        taskkill /PID %%a /F >nul 2>&1
+    )
+    echo Proxy stopped.
+    goto :eof
+)
+
+if "%1"=="status" (
+    curl -s http://127.0.0.1:%PROXY_PORT%/health >nul 2>&1
+    if %errorlevel% equ 0 (
+        echo [92mProxy is running on port %PROXY_PORT%[0m
+        curl -s http://127.0.0.1:%PROXY_PORT%/health
+    ) else (
+        echo [93mProxy is not running[0m
+    )
+    goto :eof
+)
+
+echo DeepSeek Usage Tracker Proxy
+echo.
+echo Usage:
+echo   deepseek-proxy start   Start the proxy server
+echo   deepseek-proxy stop    Stop the proxy server
+echo   deepseek-proxy status  Check if proxy is running
+echo.
+echo The proxy runs on port %PROXY_PORT% by default.
+echo.
+
+endlocal