@jagilber-org/index-server 1.28.10 → 1.28.19

package/schemas/instruction.schema.json

@@ -132,26 +132,30 @@
     },
     "contentType": {
       "enum": [
+        "agent",
+        "skill",
         "instruction",
-        "template",
+        "prompt",
         "workflow",
-        "reference",
-        "example",
-        "agent"
+        "knowledge",
+        "template",
+        "integration"
       ],
       "default": "instruction",
-      "description": "Content type classification: instruction (actionable guidance), template (scaffolds/error templates), workflow (multi-step processes or runbooks), reference (docs/guides), example (code samples), agent (AI agent definitions/personas). The legacy value chat-session is accepted only by migration/write compatibility and is normalized to workflow before persistence; new records should use workflow."
+      "description": "Content type classification: agent (AI agent definitions and personas), skill (packaged agent capabilities or callable skills), instruction (actionable guidance and operating rules), prompt (prompt templates or prompt engineering assets), workflow (multi-step processes or runbooks), knowledge (reference material, examples, concepts, and documentation), template (reusable scaffolds or structured content templates), integration (external system, MCP, API, or tool integration guidance)."
     },
     "schemaVersion": {
       "type": "string",
       "enum": [
-        "5"
+        "6"
       ],
+      "x-fieldClass": "server-managed",
       "description": "Internal schema version for migration"
     },
     "sourceHash": {
       "type": "string",
       "pattern": "^[a-f0-9]{64}$",
+      "x-fieldClass": "server-managed",
       "description": "SHA256 hash of body for drift detection"
     },
     "deprecatedBy": {
@@ -161,26 +165,31 @@
     "createdAt": {
       "type": "string",
       "format": "date-time",
+      "x-fieldClass": "server-managed",
       "description": "Creation timestamp (ISO 8601)"
     },
     "updatedAt": {
       "type": "string",
       "format": "date-time",
+      "x-fieldClass": "server-managed",
       "description": "Last mutation timestamp (ISO 8601)"
     },
     "usageCount": {
       "type": "integer",
       "minimum": 0,
+      "x-fieldClass": "server-managed",
       "description": "Number of tracked usage events"
     },
     "firstSeenTs": {
       "type": "string",
       "format": "date-time",
+      "x-fieldClass": "server-managed",
       "description": "Timestamp when usage was first observed (ISO 8601)"
     },
     "lastUsedAt": {
       "type": "string",
       "format": "date-time",
+      "x-fieldClass": "server-managed",
       "description": "Last usage timestamp (ISO 8601)"
     },
     "riskScore": {
@@ -270,6 +279,7 @@
     "archivedAt": {
       "type": "string",
       "format": "date-time",
+      "x-fieldClass": "server-managed",
       "description": "Timestamp when archived (ISO 8601)"
     },
     "semanticSummary": {

package/schemas/manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.26.11",
-  "generatedAt": "2026-04-30T21:14:01.841Z",
+  "version": "1.28.19",
+  "generatedAt": "2026-05-11T01:35:27.991Z",
   "trackedDir": "schemas",
   "distDir": "dist/schemas",
   "jsonSchemas": [
@@ -67,7 +67,7 @@
       "src",
       "scripts"
     ],
-    "fileCount": 245,
+    "fileCount": 266,
     "features": {
       "jsdoc": true,
       "lineNumbers": true,

package/scripts/README.md

@@ -10,6 +10,7 @@ Organized by purpose. Each subdirectory has a clear role; naming conventions mak
 | `ci/` | CI-specific runners and validation | — |
 | `client/` | Client CLI tools and wizards | — |
 | `deploy/` | Deployment and production ops | `deploy-*`, `smoke-*`, `prod-*` |
+| `dev/` | Dev-server orchestrator + probes (see below) | — |
 | `diagnostics/` | Adhoc probes, health checks, inspection | `adhoc-*` for one-off probes |
 | `dist/` | Distributable scripts (shipped to users) | — |
 | `governance/` | Guards, validators, lint, coverage | `guard-*`, `check-*`, `validate-*` |
@@ -19,6 +20,25 @@ Organized by purpose. Each subdirectory has a clear role; naming conventions mak
 | `perf/` | Performance baselines, trends, benchmarks | `perf-*`, `benchmark-*`, `stress-*` |
 | `testing/` | Test runners, helpers, fixtures | `test-*`, `run-*`, `seed-*` |
 
+Root-level PowerShell files under `scripts/` are compatibility wrappers for
+template-managed paths. Prefer the categorized subdirectory implementation for
+new logic.
+
+## Dev-server layout
+
+`dev/` contains the profile-sandboxed dev orchestrator and its probes, organized
+by role:
+
+| Subdirectory | Role | Scripts |
+|---|---|---|
+| `dev/` | Orchestrator | `dev-server.ps1` |
+| `dev/transport/` | Shared harness | `mcp-stdio.mjs` |
+| `dev/diagnostic/` | Read-only probes | `info-probe.mjs`, `shape-probe.mjs` |
+| `dev/integrity/` | Mutation + verify probes | `crud-probe.mjs`, `disk-server-consistency.mjs`, `io-matrix.mjs` |
+| `dev/util/` | CLI utilities | `io-helper.mjs` |
+
+> See `scripts/dev/README.md` for the full dev-server runbook.
+
 ## Naming Conventions
 
 - **`adhoc-*`** — One-off diagnostic probes. Never referenced by CI or `package.json`. Safe to run manually during debugging; safe to delete when no longer needed.

package/scripts/build/README.md

@@ -0,0 +1,41 @@
+# scripts/build
+
+Build, release, schema generation, and publishing tools. Scripts here produce
+artifacts — compiled output, docs, schemas, manifests — and drive the release
+pipeline. Most are wired to `npm run` tasks or called by `Invoke-ReleaseWorkflow.ps1`.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `build.ps1` | Full build wrapper: `tsc` + asset copy |
+| `ci-build.mjs` | CI-mode build with strict exit codes |
+| `bump-version.mjs` | Bump `package.json` version; commits and tags |
+| `bump-version.ps1` | PowerShell wrapper around `bump-version.mjs` |
+| `copy-dashboard-assets.mjs` | Copy dashboard HTML/JS/CSS into `dist/` |
+| `generate-certs.mjs` | Generate self-signed TLS certs for local HTTPS |
+| `generate-drift-report.mjs` | Compare current schema vs last snapshot; report drift |
+| `generate-manifest.mjs` | Regenerate `schemas/manifest.json` from source |
+| `generate-schemas.mjs` | Regenerate all JSON schemas from TypeScript types |
+| `generate-tools-doc.mjs` | Regenerate `docs/TOOLS-GENERATED.md` from tool registry |
+| `generate-tools-snapshot.mjs` | Capture current tool-registry snapshot for drift checks |
+| `Invoke-ReleaseWorkflow.ps1` | End-to-end release: bump → build → publish → tag |
+| `publish-direct-to-remote.cjs` | Publish build artifacts directly to the remote mirror |
+| `Publish-ToMirror.ps1` | Copy clean-room build to the production mirror path |
+| `set-registry.mjs` | Switch npm registry for publish (scoped packages) |
+| `setup-wizard.mjs` | Interactive first-run setup wizard |
+| `setup-wizard-paths.mjs` | Path resolution helpers for the setup wizard |
+| `sync-constitution.ps1` | Regenerate `constitution.md` from `constitution.json` |
+| `sync-dist.ps1` | Sync `dist/` to production deployment path |
+| `append-agent-provenance.ps1` | Append agent provenance metadata to release artifacts |
+| `Compare-TemplateSpec.ps1` | Diff current template against canonical spec |
+
+## Key entry point
+
+```pwsh
+# Full release (bump → build → publish → tag)
+pwsh -File scripts/build/Invoke-ReleaseWorkflow.ps1
+
+# CI-compatible build with artifact verification
+npm run build:ci
+```

package/scripts/build/setup-wizard-paths.mjs

@@ -0,0 +1,27 @@
+/**
+ * setup-wizard-paths.mjs — Platform-standard per-user data directory resolver.
+ *
+ * Exported so the setup wizard and tests share a single source of truth.
+ *
+ * Convention (env-paths style; matches VS Code, npm, gh CLI):
+ *   Windows: %LOCALAPPDATA%\index-server      (default ~\AppData\Local\index-server)
+ *   macOS:   ~/Library/Application Support/index-server
+ *   Linux:   ${XDG_DATA_HOME:-~/.local/share}/index-server
+ */
+import path from 'path';
+
+const APP_NAME = 'index-server';
+
+/** @param {NodeJS.Platform} [platform] @param {NodeJS.ProcessEnv} [env] */
+export function defaultUserRoot(platform = process.platform, env = process.env) {
+  const home = env.HOME || env.USERPROFILE || '';
+  if (platform === 'win32') {
+    const base = env.LOCALAPPDATA || (home ? path.join(home, 'AppData', 'Local') : '');
+    return path.join(base, APP_NAME);
+  }
+  if (platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', APP_NAME);
+  }
+  const base = env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+  return path.join(base, APP_NAME);
+}

package/scripts/build/setup-wizard.mjs

@@ -15,7 +15,7 @@
  *   npx @jagilber-org/index-server --setup
  *   npm run setup
  *   node scripts/build/setup-wizard.mjs
- *   node scripts/build/setup-wizard.mjs --non-interactive --profile enhanced --root C:/mcp/index-server
+ *   node scripts/build/setup-wizard.mjs --non-interactive --profile enhanced --root C:/.tools/index-server
  */
 import fs from 'fs';
 import path from 'path';
@@ -23,6 +23,7 @@ import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { select, input, confirm, checkbox } from '@inquirer/prompts';
+import { defaultUserRoot } from './setup-wizard-paths.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..');
@@ -33,17 +34,6 @@ function writeTextFile(filePath, content) {
 }
 const IS_WINDOWS = process.platform === 'win32';
 
-// Default install root for non-repo installs. Lives under the user profile so
-// neither admin/elevated rights nor a cluttered C:\ root are required, and the
-// runtime self-deploys cleanly there (args + cwd resolve under this root).
-function defaultUserRoot() {
-  if (IS_WINDOWS) {
-    const base = process.env.LOCALAPPDATA || process.env.APPDATA || process.env.USERPROFILE || process.cwd();
-    return path.join(base, 'index-server');
-  }
-  const home = process.env.HOME || process.cwd();
-  return path.join(home, '.local', 'share', 'index-server');
-}
 function parsePositiveTimeout(value, fallback) {
   const parsed = Number(value);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
@@ -231,11 +221,10 @@ async function runInteractiveWizard() {
     default: 'default',
   });
 
-  // Step 2: Root directory
-  const defaultRoot = defaultUserRoot();
+  // Step 2: Root directory — defaults to per-user data dir (no admin rights, no hardcoded C:\ path)
   const root = path.resolve(await input({
     message: 'Base directory (all data paths resolve under this root)',
-    default: defaultRoot,
+    default: defaultUserRoot(),
   }));
 
   // Step 3: Server name for mcp.json entry
@@ -648,12 +637,6 @@ Non-interactive mode:
     console.log(`\n✅ .env written to: ${envPath}`);
   }
 
-  // ── Deploy runtime BEFORE config generation ─────────────────────────
-  // resolveServerLaunch picks 'local' source (cwd = config.root) only when
-  // <config.root>/dist/server/index-server.js exists. Deploy first so configs
-  // are emitted with stable user-data-root paths instead of npm-global paths.
-  await deployRuntime(config);
-
   // ── Multi-target config generation ──────────────────────────────────
   const configTargets = resolveConfigPaths(config);
 
@@ -711,6 +694,9 @@ Non-interactive mode:
     }
   }
 
+  // ── Deploy runtime if target root differs from package root ─────────
+  await deployRuntime(config);
+
   // ── Next steps ──────────────────────────────────────────────────────
   const proto = (config.profile === 'enhanced' || config.profile === 'experimental') ? 'https' : 'http';
   const launch = resolveServerLaunch(config);

package/scripts/client/README.md

@@ -0,0 +1,26 @@
+# scripts/client
+
+Client-side CLI tools and templates for connecting to a running Index Server via
+MCP. These are the scripts users run against a deployed server; they do not
+require the source tree to be built.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `index-server-client.ps1` | PowerShell MCP client: connect, call tools interactively |
+| `index-server-client.sh` | Bash equivalent for Linux/macOS |
+| `powershell-mcp-server.ps1` | Example PowerShell-hosted MCP server (reference implementation) |
+| `powershell-mcp-template.ps1` | Template for building a custom PowerShell MCP server |
+
+## Quick start
+
+```pwsh
+# Connect to a local dev server (stdio transport)
+pwsh -File scripts/client/index-server-client.ps1
+
+# Connect to a remote HTTP endpoint
+pwsh -File scripts/client/index-server-client.ps1 -Uri http://localhost:9100
+```
+
+> See `docs/client_scripts.md` and `docs/powershell_mcp_guide.md` for full usage.

package/scripts/client/index-server-client.ps1

@@ -0,0 +1,203 @@
+<#
+.SYNOPSIS
+  Index Server REST client for subagents without MCP tool access.
+
+.DESCRIPTION
+  Provides CRUD operations against the Index Server dashboard REST bridge
+  (POST /api/tools/:name). Works with both HTTP and HTTPS endpoints.
+  Returns structured JSON to stdout for machine consumption.
+
+.PARAMETER BaseUrl
+  Server URL, e.g. http://localhost:8787 or https://localhost:8787
+
+.PARAMETER Action
+  One of: search, get, list, add, remove, groom, health, track, hotset
+
+.PARAMETER Id
+  Instruction ID (for get, remove, track)
+
+.PARAMETER Keywords
+  Search keywords array (for search)
+
+.PARAMETER Mode
+  Search mode: keyword, regex, semantic (default: keyword)
+
+.PARAMETER Body
+  Instruction body text (for add)
+
+.PARAMETER Title
+  Instruction title (for add)
+
+.PARAMETER Priority
+  Instruction priority 1-100 (for add, default: 50)
+
+.PARAMETER Signal
+  Usage signal: helpful, not-relevant, outdated, applied (for track)
+
+.PARAMETER Overwrite
+  Allow overwriting existing instruction (for add)
+
+.PARAMETER DryRun
+  Preview groom changes without writing (for groom)
+
+.PARAMETER Limit
+  Max results (for search, list, hotset)
+
+.PARAMETER ExpectId
+  Optional ID to prioritize in list results when validating CRUD flows
+
+.PARAMETER SkipCertCheck
+  Skip TLS certificate validation (self-signed certs)
+
+.EXAMPLE
+  .\index-server-client.ps1 -BaseUrl http://localhost:8787 -Action health
+  .\index-server-client.ps1 -BaseUrl http://localhost:8787 -Action search -Keywords deploy,release
+  .\index-server-client.ps1 -BaseUrl http://localhost:8787 -Action get -Id my-instruction-id
+  .\index-server-client.ps1 -BaseUrl http://localhost:8787 -Action list -Limit 20
+  .\index-server-client.ps1 -BaseUrl http://localhost:8787 -Action add -Id new-inst -Title "My Instruction" -Body "Content here"
+  .\index-server-client.ps1 -BaseUrl http://localhost:8787 -Action remove -Id old-inst
+  .\index-server-client.ps1 -BaseUrl http://localhost:8787 -Action track -Id some-inst -Signal helpful
+  .\index-server-client.ps1 -BaseUrl http://localhost:8787 -Action groom -DryRun
+  .\index-server-client.ps1 -BaseUrl https://localhost:8787 -Action health -SkipCertCheck
+#>
+[CmdletBinding()]
+param(
+    [string]$BaseUrl = $env:INDEX_SERVER_URL,
+    [Parameter(Mandatory)]
+    [ValidateSet('search','get','list','add','remove','groom','health','track','hotset')]
+    [string]$Action,
+    [string]$Id,
+    [string[]]$Keywords,
+    [ValidateSet('keyword','regex','semantic')]
+    [string]$Mode = 'keyword',
+    [string]$Body,
+    [string]$Title,
+    [int]$Priority = 50,
+    [ValidateSet('helpful','not-relevant','outdated','applied')]
+    [string]$Signal,
+    [switch]$Overwrite,
+    [switch]$DryRun,
+    [int]$Limit = 50,
+    [string]$ExpectId,
+    [switch]$SkipCertCheck,
+    [string]$AdminKey = $env:INDEX_SERVER_ADMIN_API_KEY
+)
+
+$ErrorActionPreference = 'Stop'
+if (-not $BaseUrl) {
+    $BaseUrl = 'http://localhost:8787'
+}
+$BaseUrl = $BaseUrl.TrimEnd('/')
+
+function Invoke-Tool {
+    param([string]$Tool, [hashtable]$Params)
+    $uri = "$BaseUrl/api/tools/$Tool"
+    $jsonBody = $Params | ConvertTo-Json -Depth 10 -Compress
+    $splat = @{
+        Uri         = $uri
+        Method      = 'POST'
+        ContentType = 'application/json'
+        Body        = $jsonBody
+    }
+    if ($AdminKey) {
+        $splat.Headers = @{ Authorization = "Bearer $AdminKey" }
+    }
+    if ($SkipCertCheck) {
+        if ($PSVersionTable.PSVersion.Major -ge 7) {
+            $splat.SkipCertificateCheck = $true
+        } else {
+            # PS 5.1 workaround
+            if (-not ([System.Management.Automation.PSTypeName]'TrustAll').Type) {
+                Add-Type @"
+using System.Net;
+using System.Net.Security;
+using System.Security.Cryptography.X509Certificates;
+public class TrustAll {
+    public static void Enable() {
+        ServicePointManager.ServerCertificateValidationCallback =
+            delegate { return true; };
+    }
+}
+"@
+            }
+            [TrustAll]::Enable()
+        }
+    }
+    try {
+        $resp = Invoke-RestMethod @splat
+        return @{ success = $true; result = $resp }
+    } catch {
+        $msg = $_.Exception.Message
+        $status = $null
+        if ($_.Exception.Response) {
+            $status = [int]$_.Exception.Response.StatusCode
+            try {
+                $reader = [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream())
+                $errBody = $reader.ReadToEnd() | ConvertFrom-Json
+                $msg = $errBody.error
+            } catch { }
+        }
+        return @{ success = $false; error = $msg; status = $status }
+    }
+}
+
+$output = switch ($Action) {
+    'health' {
+        Invoke-Tool 'health_check' @{}
+    }
+    'search' {
+        if (-not $Keywords -or $Keywords.Count -eq 0) {
+            @{ success = $false; error = 'Keywords required for search' }
+        } else {
+            Invoke-Tool 'index_search' @{ keywords = $Keywords; mode = $Mode; limit = $Limit }
+        }
+    }
+    'get' {
+        if (-not $Id) { @{ success = $false; error = 'Id required for get' } }
+        else { Invoke-Tool 'index_dispatch' @{ action = 'get'; id = $Id } }
+    }
+    'list' {
+        $p = @{ action = 'list'; limit = $Limit }
+        if ($ExpectId) { $p.expectId = $ExpectId }
+        Invoke-Tool 'index_dispatch' $p
+    }
+    'add' {
+        if (-not $Id) { @{ success = $false; error = 'Id required for add' } }
+        elseif (-not $Body) { @{ success = $false; error = 'Body required for add' } }
+        else {
+            $entry = @{
+                id          = $Id
+                title       = if ($Title) { $Title } else { $Id }
+                body        = $Body
+                priority    = $Priority
+                audience    = 'all'
+                requirement = 'optional'
+                categories  = @('general')
+                contentType = 'instruction'
+            }
+            $params = @{ entry = $entry; lax = $true }
+            if ($Overwrite) { $params.overwrite = $true }
+            Invoke-Tool 'index_add' $params
+        }
+    }
+    'remove' {
+        if (-not $Id) { @{ success = $false; error = 'Id required for remove' } }
+        else { Invoke-Tool 'index_remove' @{ ids = @($Id) } }
+    }
+    'track' {
+        if (-not $Id) { @{ success = $false; error = 'Id required for track' } }
+        else {
+            $p = @{ id = $Id }
+            if ($Signal) { $p.signal = $Signal }
+            Invoke-Tool 'usage_track' $p
+        }
+    }
+    'hotset' {
+        Invoke-Tool 'usage_hotset' @{ limit = $Limit }
+    }
+    'groom' {
+        Invoke-Tool 'index_groom' @{ mode = @{ dryRun = [bool]$DryRun } }
+    }
+}
+
+$output | ConvertTo-Json -Depth 10

package/scripts/client/index-server-client.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# index-server-client.sh -- Index Server REST client for subagents without MCP tool access
+# Provides CRUD operations via the dashboard REST bridge (POST /api/tools/:name)
+# Works with both HTTP and HTTPS. Returns structured JSON to stdout.
+#
+# Usage:
+#   ./index-server-client.sh health
+#   ./index-server-client.sh search "deploy release" [keyword|regex|semantic] [limit]
+#   ./index-server-client.sh get <id>
+#   ./index-server-client.sh list [limit]
+#   ./index-server-client.sh add <id> <title> <body> [priority] [--overwrite]
+#   ./index-server-client.sh remove <id>
+#   ./index-server-client.sh track <id> [helpful|not-relevant|outdated|applied]
+#   ./index-server-client.sh hotset [limit]
+#   ./index-server-client.sh groom [--dry-run]
+#
+# Env: INDEX_SERVER_URL (default: http://localhost:8787)
+#      INDEX_SERVER_ADMIN_API_KEY to authenticate with Bearer token
+#      INDEX_SERVER_SKIP_CERT=1 to skip TLS cert validation (self-signed)
+
+set -euo pipefail
+
+BASE_URL="${INDEX_SERVER_URL:-http://localhost:8787}"
+BASE_URL="${BASE_URL%/}"
+ADMIN_KEY="${INDEX_SERVER_ADMIN_API_KEY:-}"
+
+CURL_OPTS=(-s -S --fail-with-body -H "Content-Type: application/json")
+if [ -n "$ADMIN_KEY" ]; then
+    CURL_OPTS+=(-H "Authorization: Bearer ${ADMIN_KEY}")
+fi
+if [ "${INDEX_SERVER_SKIP_CERT:-}" = "1" ]; then
+    CURL_OPTS+=(-k)
+fi
+
+call_tool() {
+    local tool="$1"
+    local body="$2"
+    local url="${BASE_URL}/api/tools/${tool}"
+    local http_code resp
+    resp=$(curl "${CURL_OPTS[@]}" -w "\n%{http_code}" -X POST -d "$body" "$url" 2>&1) || true
+    http_code=$(echo "$resp" | tail -1)
+    local json_body
+    json_body=$(echo "$resp" | sed '$d')
+    if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ] 2>/dev/null; then
+        echo "{\"success\":true,\"status\":${http_code},\"result\":${json_body:-null}}"
+    else
+        echo "{\"success\":false,\"status\":${http_code:-0},\"error\":${json_body:-\"request failed\"}}"
+    fi
+}
+
+ACTION="${1:-}"
+shift || true
+
+case "$ACTION" in
+    health)
+        call_tool "health_check" "{}"
+        ;;
+    search)
+        terms="${1:-}"
+        mode="${2:-keyword}"
+        limit="${3:-50}"
+        if [ -z "$terms" ]; then
+            echo '{"success":false,"error":"keywords required for search"}'
+            exit 1
+        fi
+        # Convert space-separated terms to JSON array
+        kw_json=$(echo "$terms" | tr ' ' '\n' | sed 's/.*/"&"/' | paste -sd, | sed 's/^/[/;s/$/]/')
+        call_tool "index_search" "{\"keywords\":${kw_json},\"mode\":\"${mode}\",\"limit\":${limit}}"
+        ;;
+    get)
+        id="${1:-}"
+        if [ -z "$id" ]; then
+            echo '{"success":false,"error":"id required for get"}'
+            exit 1
+        fi
+        call_tool "index_dispatch" "{\"action\":\"get\",\"id\":\"${id}\"}"
+        ;;
+    list)
+        limit="${1:-50}"
+        call_tool "index_dispatch" "{\"action\":\"list\",\"limit\":${limit}}"
+        ;;
+    add)
+        id="${1:-}"
+        title="${2:-}"
+        body="${3:-}"
+        priority="${4:-50}"
+        overwrite="false"
+        for arg in "$@"; do [ "$arg" = "--overwrite" ] && overwrite="true"; done
+        if [ -z "$id" ] || [ -z "$body" ]; then
+            echo '{"success":false,"error":"id and body required for add"}'
+            exit 1
+        fi
+        [ -z "$title" ] && title="$id"
+        # Escape body for JSON (newlines, quotes, backslashes)
+        esc_body=$(printf '%s' "$body" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read()))' 2>/dev/null || printf '%s' "$body" | sed 's/\\/\\\\/g;s/"/\\"/g' | tr '\n' ' ')
+        esc_title=$(printf '%s' "$title" | sed 's/\\/\\\\/g;s/"/\\"/g')
+        call_tool "index_add" "{\"entry\":{\"id\":\"${id}\",\"title\":\"${esc_title}\",\"body\":${esc_body},\"priority\":${priority},\"audience\":\"all\",\"requirement\":\"optional\",\"categories\":[\"general\"],\"contentType\":\"instruction\"},\"lax\":true,\"overwrite\":${overwrite}}"
+        ;;
+    remove)
+        id="${1:-}"
+        if [ -z "$id" ]; then
+            echo '{"success":false,"error":"id required for remove"}'
+            exit 1
+        fi
+        call_tool "index_remove" "{\"ids\":[\"${id}\"]}"
+        ;;
+    track)
+        id="${1:-}"
+        signal="${2:-}"
+        if [ -z "$id" ]; then
+            echo '{"success":false,"error":"id required for track"}'
+            exit 1
+        fi
+        if [ -n "$signal" ]; then
+            call_tool "usage_track" "{\"id\":\"${id}\",\"signal\":\"${signal}\"}"
+        else
+            call_tool "usage_track" "{\"id\":\"${id}\"}"
+        fi
+        ;;
+    hotset)
+        limit="${1:-10}"
+        call_tool "usage_hotset" "{\"limit\":${limit}}"
+        ;;
+    groom)
+        dry="false"
+        for arg in "$@"; do [ "$arg" = "--dry-run" ] && dry="true"; done
+        call_tool "index_groom" "{\"mode\":{\"dryRun\":${dry}}}"
+        ;;
+    *)
+        cat <<'EOF'
+{"success":false,"error":"unknown action","usage":{
+  "actions":["health","search","get","list","add","remove","track","hotset","groom"],
+  "examples":[
+    "index-server-client.sh health",
+    "index-server-client.sh search 'deploy release' semantic 10",
+    "index-server-client.sh get my-instruction-id",
+    "index-server-client.sh list 20",
+    "index-server-client.sh add my-id 'My Title' 'Body content' 50",
+    "index-server-client.sh remove my-id",
+    "index-server-client.sh track my-id helpful",
+    "index-server-client.sh hotset 10",
+    "index-server-client.sh groom --dry-run"
+  ],
+  "env":["INDEX_SERVER_URL=http://localhost:8787","INDEX_SERVER_SKIP_CERT=1"]
+}}
+EOF
+        exit 1
+        ;;
+esac