@knowsuchagency/fulcrum 4.2.0 → 4.3.0

package/bin/fulcrum.js

@@ -46712,7 +46712,7 @@ async function runMcpServer(urlOverride, portOverride) {
   const client = new FulcrumClient(urlOverride, portOverride);
   const server = new McpServer({
     name: "fulcrum",
-    version: "4.2.0"
+    version: "4.3.0"
   });
   registerTools(server, client);
   const transport = new StdioServerTransport;
@@ -49061,7 +49061,7 @@ var marketplace_default = `{
       "name": "fulcrum",
       "source": "./",
       "description": "Task orchestration for Claude Code",
-      "version": "4.2.0",
+      "version": "4.3.0",
       "skills": [
         "./skills/fulcrum"
       ],
@@ -49080,6 +49080,20 @@ var marketplace_default = `{
 }
 `;
 
+// plugins/fulcrum/.claude-plugin/plugin.json
+var plugin_default = `{
+  "name": "fulcrum",
+  "description": "Fulcrum task orchestration for Claude Code",
+  "version": "4.3.0",
+  "author": {
+    "name": "Fulcrum"
+  },
+  "hooks": "./hooks/hooks.json",
+  "skills": "./skills/",
+  "commands": "./commands/"
+}
+`;
+
 // plugins/fulcrum/hooks/hooks.json
 var hooks_default = `{
   "hooks": {
@@ -49107,17 +49121,6 @@ var hooks_default = `{
 }
 `;
 
-// plugins/fulcrum/.mcp.json
-var _mcp_default = `{
-  "mcpServers": {
-    "fulcrum": {
-      "command": "fulcrum",
-      "args": ["mcp"]
-    }
-  }
-}
-`;
-
 // plugins/fulcrum/commands/pr.md
 var pr_default = `---
 description: Link a GitHub PR to the current fulcrum task
@@ -49151,88 +49154,55 @@ description: AI orchestration and task management platform. Use this skill when
 
 # Fulcrum - AI Orchestration Platform
 
-## Overview
-
-Fulcrum is an AI orchestration and task management platform. It provides task tracking, project management, and tools for AI agents to work autonomously across isolated git worktrees.
-
-**Key Features:**
-- Task management with kanban boards and status tracking
-- Project and repository organization
-- Git worktree isolation for parallel development
-- Docker Compose app deployment
-- Multi-channel notifications
-- MCP tools for AI agent integration
-
 ## When to Use This Skill
 
 Use the Fulcrum CLI when:
-- **Working in a task worktree** - Use \`current-task\` commands to manage your current task
-- **Updating task status** - Mark tasks as in-progress, ready for review, done, or canceled
-- **Linking PRs** - Associate a GitHub PR with the current task
-- **Linking URLs** - Attach any relevant URLs (design docs, specs, external resources) to the task
-- **Sending notifications** - Alert the user when work is complete or needs attention
-- **Server management** - Start, stop, and check server status
-
-Use the Fulcrum MCP tools when:
-- **Task CRUD operations** - Create, list, update, delete tasks
-- **Project/repository management** - Create, organize, and manage projects and repositories
-- **App deployment** - Deploy, stop, and monitor Docker Compose applications
-- **Filesystem operations** - Read, write, and edit files on the Fulcrum server
-- **Executing commands remotely** - Run shell commands on the Fulcrum server from Claude Desktop
-- **Stateful workflows** - Use persistent sessions to maintain environment variables and working directory across commands
-
-## Core CLI Commands
+- **Working in a task worktree** \u2014 Use \`current-task\` commands to manage your current task
+- **Updating task status** \u2014 Mark tasks as in-progress, ready for review, done, or canceled
+- **Linking PRs** \u2014 Associate a GitHub PR with the current task
+- **Linking URLs** \u2014 Attach relevant URLs (design docs, specs, external resources) to the task
+- **Sending notifications** \u2014 Alert the user when work is complete or needs attention
+- **Server management** \u2014 Start, stop, and check server status
+- **API access** \u2014 Query or modify any Fulcrum data via \`fulcrum api\`
+
+## CLI Commands
 
 ### current-task (Primary Agent Workflow)
 
-When running inside a Fulcrum task worktree, use these commands to manage the current task:
+When running inside a Fulcrum task worktree, manage the current task:
 
 \`\`\`bash
-# Get current task info (comprehensive output with dependencies, attachments, etc.)
-fulcrum current-task
-
-# Update task status
-fulcrum current-task in-progress   # Mark as IN_PROGRESS
-fulcrum current-task review        # Mark as IN_REVIEW (notifies user)
-fulcrum current-task done          # Mark as DONE
-fulcrum current-task cancel        # Mark as CANCELED
-
-# Link a GitHub PR to the current task
-fulcrum current-task pr <github-pr-url>
-
-# Link a Linear ticket to the current task
-fulcrum current-task linear <linear-issue-url>
-
-# Add arbitrary URL links to the task
-fulcrum current-task link <url>                  # Add link (auto-detects type/label)
-fulcrum current-task link <url> --label "Docs"   # Add link with custom label
-fulcrum current-task link                        # List all links
-fulcrum current-task link --remove <url-or-id>   # Remove a link
+fulcrum current-task                          # Get full task info
+fulcrum current-task in-progress              # Mark as IN_PROGRESS
+fulcrum current-task review                   # Mark as IN_REVIEW (notifies user)
+fulcrum current-task done                     # Mark as DONE
+fulcrum current-task cancel                   # Mark as CANCELED
+fulcrum current-task pr <github-pr-url>       # Link a GitHub PR
+fulcrum current-task linear <linear-url>      # Link a Linear ticket
+fulcrum current-task link <url>               # Add link (auto-detects type/label)
+fulcrum current-task link <url> --label "Docs" # Add link with custom label
+fulcrum current-task link                     # List all links
+fulcrum current-task link --remove <url-or-id> # Remove a link
 \`\`\`
 
 ### notifications
 
-Send notifications to the user:
-
 \`\`\`bash
-# Send a notification
-fulcrum notify "Title" "Message body"
-
-# Check notification settings
-fulcrum notifications
-
-# Enable/disable notifications
-fulcrum notifications enable
-fulcrum notifications disable
+fulcrum notify "Title" "Message body"         # Send a notification
+fulcrum notifications                         # Check notification settings
+fulcrum notifications enable                  # Enable notifications
+fulcrum notifications disable                 # Disable notifications
+fulcrum notifications test slack              # Test a channel
+fulcrum notifications set slack webhookUrl <url> # Configure a channel
+\`\`\`
 
-# Test a notification channel
-fulcrum notifications test sound
-fulcrum notifications test slack
-fulcrum notifications test discord
-fulcrum notifications test pushover
+### config
 
-# Configure a channel
-fulcrum notifications set slack webhookUrl <url>
+\`\`\`bash
+fulcrum config list              # List all config values
+fulcrum config get <key>         # Get a specific value
+fulcrum config set <key> <value> # Set a value
+fulcrum config reset <key>       # Reset to default
 \`\`\`
 
 ### Server Management
@@ -49244,25 +49214,63 @@ fulcrum status      # Check if server is running
 fulcrum doctor      # Check all dependencies and versions
 \`\`\`
 
-### Configuration
+## fulcrum api \u2014 REST API Access
+
+The \`fulcrum api\` command provides direct access to all Fulcrum REST API endpoints via a resource/action CLI.
+
+### Syntax
 
 \`\`\`bash
-fulcrum config list              # List all config values
-fulcrum config get <key>         # Get a specific value
-fulcrum config set <key> <value> # Set a value
-fulcrum config reset <key>       # Reset to default
+fulcrum api <resource> <action> [<id> ...] [--flag value ...]
 \`\`\`
 
-### Agent Plugin Installation
+### Getting the Full Tool Reference
 
 \`\`\`bash
-# Claude Code integration
-fulcrum claude install       # Install Fulcrum plugin for Claude Code
-fulcrum claude uninstall     # Uninstall plugin
+fulcrum api tools    # Compact reference of all resources, actions, and flags
+\`\`\`
+
+The \`tools\` output is designed for context window injection (~2,000 tokens for ~130 actions).
+
+### Common Examples
+
+\`\`\`bash
+# Tasks
+fulcrum api tasks list --search bug --statuses TO_DO,IN_PROGRESS
+fulcrum api tasks create --title "Fix bug" --type worktree
+fulcrum api tasks get <id>
+fulcrum api tasks move <id> --status DONE
+fulcrum api tasks update <id> --priority high --tags "backend,urgent"
+
+# Memory
+fulcrum api memory store --content "Learned X" --tags "project,pattern"
+fulcrum api memory search --q "deployment"
+
+# Search
+fulcrum api search query --q "authentication" --entities tasks,projects
+
+# Backup
+fulcrum api backup create --description "Before migration"
+fulcrum api backup list
+
+# Calendar
+fulcrum api caldav events --from 2026-01-01 --to 2026-01-31
+fulcrum api caldav sync
+\`\`\`
+
+### Raw HTTP Mode (Backward Compatible)
+
+\`\`\`bash
+fulcrum api GET /api/tasks
+fulcrum api POST /api/tasks -d '{"title":"Fix bug"}'
+\`\`\`
 
-# OpenCode integration
-fulcrum opencode install     # Install Fulcrum plugin for OpenCode
-fulcrum opencode uninstall   # Uninstall plugin
+### Route Discovery
+
+\`\`\`bash
+fulcrum api routes                          # List all routes by category
+fulcrum api routes --category tasks         # Filter by category
+fulcrum api routes --search calendar        # Search routes by keyword
 \`\`\`
 
 ## Agent Workflow Patterns
@@ -49278,13 +49286,8 @@ fulcrum opencode uninstall   # Uninstall plugin
 ### Linking External Resources
 
 \`\`\`bash
-# After creating a GitHub PR
 fulcrum current-task pr https://github.com/owner/repo/pull/123
-
-# After identifying the relevant Linear ticket
 fulcrum current-task linear https://linear.app/team/issue/TEAM-123
-
-# Add any URL link (design docs, figma, notion, external resources)
 fulcrum current-task link https://figma.com/file/abc123/design
 fulcrum current-task link https://notion.so/team/spec --label "Product Spec"
 \`\`\`
@@ -49292,256 +49295,31 @@ fulcrum current-task link https://notion.so/team/spec --label "Product Spec"
 ### Notifying the User
 
 \`\`\`bash
-# When work is complete
 fulcrum notify "Task Complete" "Implemented the new feature and created PR #123"
-
-# When blocked or need input
 fulcrum notify "Need Input" "Which approach should I use for the database migration?"
 \`\`\`
 
 ## Global Options
 
-These flags work with most commands:
-
-- \`--port=<port>\` - Server port (default: 7777)
-- \`--url=<url>\` - Override full server URL
-- \`--json\` - Output as JSON for programmatic use
+- \`--port=<port>\` \u2014 Server port (default: 7777)
+- \`--url=<url>\` \u2014 Override full server URL
+- \`--json\` \u2014 Output as JSON for programmatic use
 
 ## Task Statuses
 
-- \`TO_DO\` - Task not yet started
-- \`IN_PROGRESS\` - Task is being worked on
-- \`IN_REVIEW\` - Task is complete and awaiting review
-- \`DONE\` - Task is finished
-- \`CANCELED\` - Task was abandoned
-
-## MCP Tools
-
-Fulcrum provides a comprehensive set of MCP tools for AI agents. Use \`search_tools\` to discover available tools.
-
-### Tool Discovery
-
-#### search_tools
-
-Search for available tools by keyword or category:
-
-\`\`\`json
-{
-  "query": "deploy",      // Optional: Search term
-  "category": "apps"      // Optional: Filter by category
-}
-\`\`\`
-
-**Categories:** core, tasks, projects, repositories, apps, filesystem, git, notifications, exec
-
-**Example Usage:**
-\`\`\`
-search_tools { query: "project create" }
-\u2192 Returns tools for creating projects
-
-search_tools { category: "filesystem" }
-\u2192 Returns all filesystem tools
-\`\`\`
-
-### Task Tools
-
-- \`list_tasks\` - List tasks with flexible filtering (search, tags, statuses, date range, overdue)
-- \`get_task\` - Get task details by ID (includes dependencies and attachments)
-- \`create_task\` - Create a new task with worktree
-- \`update_task\` - Update task metadata
-- \`delete_task\` - Delete a task
-- \`move_task\` - Move task to different status
-- \`add_task_link\` - Add URL link to task
-- \`remove_task_link\` - Remove link from task
-- \`list_task_links\` - List all task links
-- \`add_task_tag\` - Add a tag to a task (returns similar tags to catch typos)
-- \`remove_task_tag\` - Remove a tag from a task
-- \`set_task_due_date\` - Set or clear task due date
-- \`list_tags\` - List all unique tags in use with optional search
-
-#### Task Dependencies
-
-- \`get_task_dependencies\` - Get dependencies and dependents of a task, and whether it is blocked
-- \`add_task_dependency\` - Add a dependency (task cannot start until dependency is done)
-- \`remove_task_dependency\` - Remove a dependency
-- \`get_task_dependency_graph\` - Get all tasks and dependencies as a graph for visualization
-
-#### Task Attachments
-
-- \`list_task_attachments\` - List all file attachments for a task
-- \`upload_task_attachment\` - Upload a file to a task from a local path
-- \`delete_task_attachment\` - Delete a file attachment from a task
-- \`get_task_attachment_path\` - Get the local file path for a task attachment
-
-#### Task Search and Filtering
-
-The \`list_tasks\` tool supports powerful filtering for AI agents:
-
-\`\`\`json
-{
-  "search": "ocai",                              // Text search across title, tags, project name
-  "tags": ["bug", "urgent"],                     // Filter by multiple tags (OR logic)
-  "statuses": ["TO_DO", "IN_PROGRESS"],          // Filter by multiple statuses (OR logic)
-  "dueDateStart": "2026-01-18",                  // Start of date range
-  "dueDateEnd": "2026-01-25",                    // End of date range
-  "overdue": true                                // Only show overdue tasks
-}
-\`\`\`
-
-#### Tag Discovery
-
-Use \`list_tags\` to discover exact tag names before filtering:
-
-\`\`\`json
-// Find tags matching "communication"
-{ "search": "communication" }
-// Returns: [{ "name": "communication required", "count": 5 }]
-\`\`\`
-
-This helps handle typos and variations - search first, then use the exact tag name.
-
-### Project Tools
-
-- \`list_projects\` - List all projects
-- \`get_project\` - Get project details
-- \`create_project\` - Create from path, URL, or existing repo
-- \`update_project\` - Update name, description, status
-- \`delete_project\` - Delete project and optionally directory/app
-- \`scan_projects\` - Scan directory for git repos
-
-#### Project Tags
-
-- \`add_project_tag\` - Add a tag to a project (creates new if needed)
-- \`remove_project_tag\` - Remove a tag from a project
-
-#### Project Attachments
-
-- \`list_project_attachments\` - List all file attachments for a project
-- \`upload_project_attachment\` - Upload a file to a project from a local path
-- \`delete_project_attachment\` - Delete a file attachment from a project
-- \`get_project_attachment_path\` - Get the local file path for a project attachment
-
-#### Project Links
-
-- \`list_project_links\` - List all URL links attached to a project
-- \`add_project_link\` - Add a URL link to a project (auto-detects type)
-- \`remove_project_link\` - Remove a URL link from a project
-
-### Repository Tools
-
-- \`list_repositories\` - List all repositories (supports orphans filter)
-- \`get_repository\` - Get repository details by ID
-- \`add_repository\` - Add repository from local path
-- \`update_repository\` - Update repository metadata (name, agent, startup script)
-- \`delete_repository\` - Delete orphaned repository (fails if linked to project)
-- \`link_repository_to_project\` - Link repo to project (errors if already linked elsewhere)
-- \`unlink_repository_from_project\` - Unlink repo from project
-
-### App/Deployment Tools
-
-- \`list_apps\` - List all deployed apps
-- \`get_app\` - Get app details with services
-- \`create_app\` - Create app for deployment
-- \`deploy_app\` - Trigger deployment
-- \`stop_app\` - Stop running app
-- \`get_app_logs\` - Get container logs
-- \`get_app_status\` - Get container status
-- \`list_deployments\` - Get deployment history
-- \`delete_app\` - Delete app
-
-### Filesystem Tools
-
-Remote filesystem tools for working with files on the Fulcrum server. Useful when the agent runs on a different machine than the server (e.g., via SSH tunneling to Claude Desktop).
-
-- \`list_directory\` - List directory contents
-- \`get_file_tree\` - Get recursive file tree
-- \`read_file\` - Read file contents (secured)
-- \`write_file\` - Write entire file content (secured)
-- \`edit_file\` - Edit file by replacing a unique string (secured)
-- \`file_stat\` - Get file/directory metadata
-- \`is_git_repo\` - Check if directory is git repo
-
-### Command Execution
-
-When using Claude Desktop with Fulcrum's MCP server, you can execute commands on the remote Fulcrum server. This is useful when connecting to Fulcrum via SSH port forwarding.
-
-#### execute_command
-
-Execute shell commands with optional persistent session support:
-
-\`\`\`json
-{
-  "command": "echo hello world",
-  "sessionId": "optional-session-id",
-  "cwd": "/path/to/start",
-  "timeout": 30000,
-  "name": "my-session"
-}
-\`\`\`
-
-**Parameters:**
-- \`command\` (required) \u2014 The shell command to execute
-- \`sessionId\` (optional) \u2014 Reuse a session to preserve env vars, cwd, and shell state
-- \`cwd\` (optional) \u2014 Initial working directory (only used when creating new session)
-- \`timeout\` (optional) \u2014 Timeout in milliseconds (default: 30000)
-- \`name\` (optional) \u2014 Session name for identification (only used when creating new session)
-
-**Response:**
-\`\`\`json
-{
-  "sessionId": "uuid",
-  "stdout": "hello world",
-  "stderr": "",
-  "exitCode": 0,
-  "timedOut": false
-}
-\`\`\`
-
-### Session Workflow Example
-
-\`\`\`
-1. First command (creates named session):
-   execute_command { command: "cd /project && export API_KEY=secret", name: "dev-session" }
-   \u2192 Returns sessionId: "abc-123"
-
-2. Subsequent commands (reuse session):
-   execute_command { command: "echo $API_KEY", sessionId: "abc-123" }
-   \u2192 Returns stdout: "secret" (env var preserved)
-
-   execute_command { command: "pwd", sessionId: "abc-123" }
-   \u2192 Returns stdout: "/project" (cwd preserved)
-
-3. Rename session if needed:
-   update_exec_session { sessionId: "abc-123", name: "new-name" }
-
-4. Cleanup when done:
-   destroy_exec_session { sessionId: "abc-123" }
-\`\`\`
-
-Sessions persist until manually destroyed.
-
-### list_exec_sessions
-
-List all active sessions with their name, current working directory, and timestamps.
-
-### update_exec_session
-
-Rename an existing session for identification.
-
-### destroy_exec_session
-
-Clean up a session when you're done to free resources.
+- \`TO_DO\` \u2014 Task not yet started
+- \`IN_PROGRESS\` \u2014 Task is being worked on
+- \`IN_REVIEW\` \u2014 Task is complete and awaiting review
+- \`DONE\` \u2014 Task is finished
+- \`CANCELED\` \u2014 Task was abandoned
 
 ## Best Practices
 
-1. **Use \`current-task\` inside worktrees** - It auto-detects which task you're in
-2. **Link PRs immediately** - Run \`fulcrum current-task pr <url>\` right after creating a PR
-3. **Link relevant resources** - Attach design docs, specs, or reference materials with \`fulcrum current-task link <url>\`
-4. **Mark review when done** - \`fulcrum current-task review\` notifies the user
-5. **Send notifications for blocking issues** - Keep the user informed of progress
-6. **Name sessions for identification** - Use descriptive names to find sessions later
-7. **Reuse sessions for related commands** - Preserve state across multiple execute_command calls
-8. **Clean up sessions when done** - Use destroy_exec_session to free resources
+1. **Use \`current-task\` inside worktrees** \u2014 It auto-detects which task you're in
+2. **Link PRs immediately** \u2014 Run \`fulcrum current-task pr <url>\` right after creating a PR
+3. **Use \`fulcrum api routes --search <keyword>\`** to discover endpoints before making calls
+4. **Mark review when done** \u2014 \`fulcrum current-task review\` notifies the user
+5. **Send notifications for blocking issues** \u2014 Keep the user informed of progress
 `;
 
 // cli/src/commands/claude.ts
@@ -49551,15 +49329,13 @@ var PLUGIN_NAME = "fulcrum";
 var PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
 var PLUGIN_FILES = [
   { path: ".claude-plugin/marketplace.json", content: marketplace_default },
+  { path: ".claude-plugin/plugin.json", content: plugin_default },
   { path: "hooks/hooks.json", content: hooks_default },
-  { path: ".mcp.json", content: _mcp_default },
   { path: "commands/pr.md", content: pr_default },
   { path: "commands/task-info.md", content: task_info_default },
   { path: "commands/notify.md", content: notify_default },
   { path: "skills/fulcrum/SKILL.md", content: SKILL_default }
 ];
-var LEGACY_PLUGIN_DIR = join3(homedir3(), ".claude", "plugins", "fulcrum");
-var LEGACY_CACHE_DIR = join3(homedir3(), ".claude", "plugins", "cache", "fulcrum");
 function runClaude(args) {
   const result = spawnSync("claude", args, { encoding: "utf-8" });
   return {
@@ -49631,7 +49407,6 @@ async function installClaudePlugin(options = {}) {
       throw new Error("Failed to install plugin: " + installResult.output);
     }
     log("\u2713 Installed plugin");
-    cleanupLegacyPaths(log);
     log("");
     log("Installation complete! Restart Claude Code to apply changes.");
   } catch (err) {
@@ -49648,22 +49423,12 @@ async function uninstallClaudePlugin() {
       rmSync(MARKETPLACE_DIR, { recursive: true });
       console.log("\u2713 Removed plugin files from " + MARKETPLACE_DIR);
     }
-    cleanupLegacyPaths(console.log);
     console.log("");
     console.log("Uninstall complete! Restart Claude Code to apply changes.");
   } catch (err) {
     throw new CliError("UNINSTALL_FAILED", `Failed to uninstall Claude plugin: ${err instanceof Error ? err.message : String(err)}`, ExitCodes.ERROR);
   }
 }
-function cleanupLegacyPaths(log) {
-  const legacyPaths = [LEGACY_PLUGIN_DIR, LEGACY_CACHE_DIR];
-  for (const path of legacyPaths) {
-    if (existsSync3(path)) {
-      rmSync(path, { recursive: true });
-      log("\u2713 Removed legacy files from " + path);
-    }
-  }
-}
 var claudeInstallCommand = defineCommand({
   meta: { name: "install", description: "Install Claude Code plugin" },
   args: globalArgs,
@@ -50374,7 +50139,7 @@ function compareVersions(v1, v2) {
 var package_default = {
   name: "@knowsuchagency/fulcrum",
   private: true,
-  version: "4.2.0",
+  version: "4.3.0",
   description: "Harness Attention. Orchestrate Agents. Ship.",
   license: "PolyForm-Perimeter-1.0.0",
   type: "module",
@@ -50401,6 +50166,8 @@ var package_default = {
     "@fontsource/ibm-plex-mono": "^5.2.7",
     "@hono/node-server": "^1.19.7",
     "@hono/node-ws": "^1.2.0",
+    "@hono/swagger-ui": "^0.5.3",
+    "@hono/zod-openapi": "^1.2.2",
     "@hugeicons/core-free-icons": "^3.0.0",
     "@hugeicons/react": "^1.1.3",
     "@mdx-js/mdx": "^3.1.1",
@@ -50945,19 +50712,18 @@ async function handleStatusCommand(flags) {
   let healthOk = false;
   let version = null;
   let uptime = null;
-  if (pidRunning) {
-    try {
-      const res = await fetch(`${serverUrl}/health`, { signal: AbortSignal.timeout(2000) });
-      healthOk = res.ok;
-      if (res.ok) {
-        const health = await res.json();
-        version = health.version || null;
-        uptime = health.uptime || null;
-      }
-    } catch {}
-  }
+  try {
+    const res = await fetch(`${serverUrl}/health`, { signal: AbortSignal.timeout(2000) });
+    healthOk = res.ok;
+    if (res.ok) {
+      const health = await res.json();
+      version = health.version || null;
+      uptime = health.uptime || null;
+    }
+  } catch {}
+  const running = pidRunning || healthOk;
   const data = {
-    running: pidRunning,
+    running,
     healthy: healthOk,
     pid: pid || null,
     port,
@@ -50968,10 +50734,11 @@ async function handleStatusCommand(flags) {
   if (isJsonOutput()) {
     output(data);
   } else {
-    if (pidRunning) {
+    if (running) {
       const healthStatus = healthOk ? "healthy" : "not responding";
       console.log(`Fulcrum is running (${healthStatus})`);
-      console.log(`  PID:  ${pid}`);
+      if (pidRunning)
+        console.log(`  PID:  ${pid}`);
       console.log(`  URL:  ${serverUrl}`);
       if (version)
         console.log(`  Version: ${version}`);
@@ -51140,6 +50907,568 @@ var mcpCommand = defineCommand({
   }
 });
 
+// cli/src/commands/api.ts
+init_server();
+import { existsSync as existsSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync5, statSync } from "fs";
+import { tmpdir } from "os";
+import { join as join7 } from "path";
+init_errors();
+
+// cli/src/openapi-parser.ts
+function extractQueryParams(params) {
+  if (!params)
+    return;
+  const queryParams = params.filter((p) => p.in === "query").map((p) => p.name);
+  return queryParams.length > 0 ? queryParams.join(", ") : undefined;
+}
+function extractBodyFields(op) {
+  const schema = op.requestBody?.content?.["application/json"]?.schema;
+  if (!schema)
+    return;
+  if (schema.description?.startsWith("Fields: ")) {
+    return schema.description.slice("Fields: ".length);
+  }
+  if (schema.properties) {
+    const required3 = new Set(schema.required || []);
+    return Object.keys(schema.properties).map((name) => required3.has(name) ? name : `${name}?`).join(", ");
+  }
+  return;
+}
+function parseOpenAPISpec(spec) {
+  const tagDescriptions = new Map;
+  if (spec.tags) {
+    for (const tag of spec.tags) {
+      tagDescriptions.set(tag.name, tag.description || "");
+    }
+  }
+  const categories = new Map;
+  if (spec.paths) {
+    for (const [path, methods] of Object.entries(spec.paths)) {
+      for (const [method, op] of Object.entries(methods)) {
+        if (!op || typeof op !== "object")
+          continue;
+        if (["parameters", "summary", "description", "servers"].includes(method))
+          continue;
+        const tag = op.tags?.[0] || "other";
+        if (!categories.has(tag)) {
+          categories.set(tag, []);
+        }
+        const displayPath = path.replace(/\{(\w+)\}/g, ":$1");
+        categories.get(tag).push({
+          method: method.toUpperCase(),
+          path: displayPath,
+          description: op.summary || op.description || "",
+          queryParams: extractQueryParams(op.parameters),
+          bodyFields: extractBodyFields(op)
+        });
+      }
+    }
+  }
+  const result = [];
+  for (const [tag, routes] of [...categories.entries()].sort((a2, b2) => a2[0].localeCompare(b2[0]))) {
+    result.push({
+      category: tag,
+      description: tagDescriptions.get(tag) || "",
+      routes
+    });
+  }
+  return result;
+}
+function extractPathParams(path) {
+  const matches = path.match(/\{(\w+)\}/g);
+  return matches ? matches.map((m2) => m2.slice(1, -1)) : [];
+}
+function extractQueryParamNames(params) {
+  if (!params)
+    return [];
+  return params.filter((p) => p.in === "query").map((p) => p.name);
+}
+function extractBodyFieldList(op) {
+  const schema = op.requestBody?.content?.["application/json"]?.schema;
+  if (!schema)
+    return [];
+  if (schema.description?.startsWith("Fields: ")) {
+    const fieldsStr = schema.description.slice("Fields: ".length);
+    return fieldsStr.split(",").map((f3) => {
+      const trimmed = f3.trim();
+      const isOptional = trimmed.endsWith("?");
+      return {
+        name: isOptional ? trimmed.slice(0, -1) : trimmed,
+        required: !isOptional
+      };
+    });
+  }
+  if (schema.properties) {
+    const requiredSet = new Set(schema.required || []);
+    return Object.keys(schema.properties).map((name) => ({
+      name,
+      required: requiredSet.has(name)
+    }));
+  }
+  return [];
+}
+function parseOpenAPIActions(spec) {
+  const tagDescriptions = new Map;
+  if (spec.tags) {
+    for (const tag of spec.tags) {
+      tagDescriptions.set(tag.name, tag.description || "");
+    }
+  }
+  const resourceMap = new Map;
+  if (spec.paths) {
+    for (const [path, methods] of Object.entries(spec.paths)) {
+      for (const [method, op] of Object.entries(methods)) {
+        if (!op || typeof op !== "object")
+          continue;
+        if (["parameters", "summary", "description", "servers"].includes(method))
+          continue;
+        if (!op.operationId)
+          continue;
+        const tag = op.tags?.[0] || "other";
+        if (!resourceMap.has(tag)) {
+          resourceMap.set(tag, []);
+        }
+        const prefix = `${tag}-`;
+        const action = op.operationId.startsWith(prefix) ? op.operationId.slice(prefix.length) : op.operationId;
+        resourceMap.get(tag).push({
+          operationId: op.operationId,
+          action,
+          method: method.toUpperCase(),
+          path,
+          description: op.summary || op.description || "",
+          pathParams: extractPathParams(path),
+          queryParams: extractQueryParamNames(op.parameters),
+          bodyFields: extractBodyFieldList(op)
+        });
+      }
+    }
+  }
+  const result = [];
+  for (const [name, actions] of [...resourceMap.entries()].sort((a2, b2) => a2[0].localeCompare(b2[0]))) {
+    result.push({
+      name,
+      description: tagDescriptions.get(name) || "",
+      actions
+    });
+  }
+  return result;
+}
+
+// cli/src/commands/api.ts
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+var SPEC_CACHE_TTL_MS = 5 * 60 * 1000;
+function getSpecCachePath(baseUrl) {
+  const port = new URL(baseUrl).port || "7777";
+  return join7(tmpdir(), `fulcrum-openapi-${port}.json`);
+}
+async function fetchSpec(baseUrl) {
+  const cachePath = getSpecCachePath(baseUrl);
+  if (existsSync7(cachePath)) {
+    const stat = statSync(cachePath);
+    const age = Date.now() - stat.mtimeMs;
+    if (age < SPEC_CACHE_TTL_MS) {
+      try {
+        return JSON.parse(readFileSync6(cachePath, "utf-8"));
+      } catch {}
+    }
+  }
+  let res;
+  try {
+    res = await fetch(`${baseUrl}/openapi.json`);
+  } catch {
+    throw new CliError("SERVER_UNREACHABLE", `Server unreachable at ${baseUrl} \u2014 requires a running server`, ExitCodes.SERVER_UNREACHABLE);
+  }
+  if (!res.ok) {
+    throw new CliError("SPEC_ERROR", `Failed to fetch OpenAPI spec: ${res.status} ${res.statusText}`, ExitCodes.ERROR);
+  }
+  const contentType = res.headers.get("content-type") || "";
+  if (!contentType.includes("application/json")) {
+    throw new CliError("SPEC_ERROR", `Server returned ${contentType || "unknown content type"} instead of JSON \u2014 is the server up to date?`, ExitCodes.ERROR);
+  }
+  const spec = await res.json();
+  try {
+    writeFileSync5(cachePath, JSON.stringify(spec));
+  } catch {}
+  return spec;
+}
+async function fetchRoutes(baseUrl) {
+  const spec = await fetchSpec(baseUrl);
+  return parseOpenAPISpec(spec);
+}
+async function fetchResources(baseUrl) {
+  const spec = await fetchSpec(baseUrl);
+  return parseOpenAPIActions(spec);
+}
+async function handleRoutes(flags) {
+  const category = flags.category?.toLowerCase();
+  const search = flags.search?.toLowerCase();
+  const baseUrl = discoverServerUrl(flags.url, flags.port);
+  const apiRoutes = await fetchRoutes(baseUrl);
+  let filtered = apiRoutes;
+  if (category) {
+    filtered = filtered.filter((c3) => c3.category === category);
+    if (filtered.length === 0) {
+      const categories = apiRoutes.map((c3) => c3.category).join(", ");
+      throw new CliError("UNKNOWN_CATEGORY", `Unknown category: ${category}. Available: ${categories}`, ExitCodes.INVALID_ARGS);
+    }
+  }
+  if (search) {
+    filtered = filtered.map((cat) => ({
+      ...cat,
+      routes: cat.routes.filter((r3) => r3.path.toLowerCase().includes(search) || r3.description.toLowerCase().includes(search) || r3.method.toLowerCase().includes(search))
+    })).filter((cat) => cat.routes.length > 0);
+  }
+  if (isJsonOutput()) {
+    output(filtered);
+    return;
+  }
+  if (filtered.length === 0) {
+    console.log("No routes match your search.");
+    return;
+  }
+  for (const cat of filtered) {
+    console.log(`
+${cat.category} \u2014 ${cat.description}`);
+    console.log("\u2500".repeat(60));
+    for (const route of cat.routes) {
+      const method = route.method.padEnd(6);
+      console.log(`  ${method} ${route.path}`);
+      console.log(`         ${route.description}`);
+      if (route.queryParams) {
+        console.log(`         Query: ${route.queryParams}`);
+      }
+      if (route.bodyFields) {
+        console.log(`         Body:  ${route.bodyFields}`);
+      }
+    }
+  }
+  console.log("");
+}
+async function handleHttpRequest(method, pathAndQuery, data, flags) {
+  const upperMethod = method.toUpperCase();
+  if (!HTTP_METHODS.includes(upperMethod)) {
+    throw new CliError("INVALID_METHOD", `Invalid HTTP method: ${method}. Valid: ${HTTP_METHODS.join(", ")}`, ExitCodes.INVALID_ARGS);
+  }
+  if (!pathAndQuery) {
+    throw new CliError("MISSING_PATH", "API path is required. Example: fulcrum api GET /api/tasks", ExitCodes.INVALID_ARGS);
+  }
+  const normalizedPath = pathAndQuery.startsWith("/") ? pathAndQuery : `/${pathAndQuery}`;
+  const baseUrl = discoverServerUrl(flags.url, flags.port);
+  const url2 = `${baseUrl}${normalizedPath}`;
+  const fetchOptions = {
+    method: upperMethod,
+    headers: { "Content-Type": "application/json" }
+  };
+  if (data && ["POST", "PUT", "PATCH", "DELETE"].includes(upperMethod)) {
+    fetchOptions.body = data;
+  }
+  let res;
+  try {
+    res = await fetch(url2, fetchOptions);
+  } catch {
+    throw new CliError("SERVER_UNREACHABLE", `Server unreachable: ${baseUrl}`, ExitCodes.SERVER_UNREACHABLE);
+  }
+  let body;
+  const contentType = res.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    body = await res.json();
+  } else {
+    body = await res.text();
+  }
+  if (!res.ok) {
+    if (isJsonOutput()) {
+      console.log(JSON.stringify({ success: false, status: res.status, error: body }));
+    } else {
+      console.error(`Error ${res.status}: ${typeof body === "string" ? body : JSON.stringify(body, null, 2)}`);
+    }
+    process.exit(ExitCodes.ERROR);
+  }
+  if (isJsonOutput()) {
+    output(body);
+  } else {
+    console.log(typeof body === "string" ? body : JSON.stringify(body, null, 2));
+  }
+}
+function resolveAction(resources, resourceName, actionName) {
+  const resource = resources.find((r3) => r3.name === resourceName);
+  if (!resource) {
+    const available = resources.map((r3) => r3.name).join(", ");
+    throw new CliError("UNKNOWN_RESOURCE", `Unknown resource: ${resourceName}. Available: ${available}`, ExitCodes.INVALID_ARGS);
+  }
+  if (!actionName) {
+    return { resource };
+  }
+  const action = resource.actions.find((a2) => a2.action === actionName);
+  if (!action) {
+    const available = resource.actions.map((a2) => a2.action).join(", ");
+    throw new CliError("UNKNOWN_ACTION", `Unknown action: ${actionName} for ${resourceName}. Available: ${available}`, ExitCodes.INVALID_ARGS);
+  }
+  return { resource, action };
+}
+function coerceValue(value, isArrayField) {
+  if (isArrayField || value.includes(",")) {
+    return value.split(",").map((v2) => v2.trim());
+  }
+  if (value === "true")
+    return true;
+  if (value === "false")
+    return false;
+  if (value !== "" && !isNaN(Number(value)) && isFinite(Number(value))) {
+    return Number(value);
+  }
+  return value;
+}
+function buildRequest(action, positionalArgs, flags) {
+  let path = action.path;
+  for (let i2 = 0;i2 < action.pathParams.length; i2++) {
+    const param = action.pathParams[i2];
+    const value = positionalArgs[i2];
+    if (!value) {
+      throw new CliError("MISSING_PATH_PARAM", `Missing required path parameter: <${param}>`, ExitCodes.INVALID_ARGS);
+    }
+    path = path.replace(`{${param}}`, encodeURIComponent(value));
+  }
+  if (flags.data || flags.d) {
+    const body = flags.data || flags.d;
+    return { method: action.method, url: path, body };
+  }
+  const arrayBodyFields = new Set;
+  for (const f3 of action.bodyFields) {
+    if (["ids", "tags", "repositories", "services", "uids"].includes(f3.name)) {
+      arrayBodyFields.add(f3.name);
+    }
+  }
+  if (action.method === "GET" || action.method === "HEAD") {
+    const queryParts = [];
+    for (const [key, value] of Object.entries(flags)) {
+      queryParts.push(`${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
+    }
+    const queryString = queryParts.length > 0 ? `?${queryParts.join("&")}` : "";
+    return { method: action.method, url: `${path}${queryString}` };
+  }
+  if (Object.keys(flags).length > 0) {
+    const body = {};
+    for (const [key, value] of Object.entries(flags)) {
+      body[key] = coerceValue(value, arrayBodyFields.has(key));
+    }
+    return { method: action.method, url: path, body: JSON.stringify(body) };
+  }
+  return { method: action.method, url: path };
+}
+function parseRawArgs2(rawArgs) {
+  const positionalArgs = [];
+  const actionFlags = {};
+  const globalFlags = {};
+  const globalFlagNames = new Set(["port", "url", "json", "debug", "data", "d"]);
+  let i2 = 0;
+  while (i2 < rawArgs.length) {
+    const arg = rawArgs[i2];
+    if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      let key;
+      let value;
+      if (eqIdx !== -1) {
+        key = arg.slice(2, eqIdx);
+        value = arg.slice(eqIdx + 1);
+      } else {
+        key = arg.slice(2);
+        const next = rawArgs[i2 + 1];
+        if (next && !next.startsWith("-")) {
+          value = next;
+          i2++;
+        } else {
+          value = "true";
+        }
+      }
+      if (globalFlagNames.has(key)) {
+        globalFlags[key] = value;
+      } else {
+        actionFlags[key] = value;
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const key = arg.slice(1);
+      const next = rawArgs[i2 + 1];
+      if (next && !next.startsWith("-")) {
+        if (globalFlagNames.has(key)) {
+          globalFlags[key] = next;
+        } else {
+          actionFlags[key] = next;
+        }
+        i2++;
+      } else {
+        if (globalFlagNames.has(key)) {
+          globalFlags[key] = "true";
+        } else {
+          actionFlags[key] = "true";
+        }
+      }
+    } else {
+      positionalArgs.push(arg);
+    }
+    i2++;
+  }
+  return { positionalArgs, actionFlags, globalFlags };
+}
+async function handleResourceAction(rawArgs, globalFlagsFromCitty) {
+  const { positionalArgs, actionFlags, globalFlags } = parseRawArgs2(rawArgs);
+  const mergedGlobalFlags = { ...globalFlags, ...globalFlagsFromCitty };
+  const baseUrl = discoverServerUrl(mergedGlobalFlags.url, mergedGlobalFlags.port);
+  const resources = await fetchResources(baseUrl);
+  const resourceName = positionalArgs[0];
+  const actionName = positionalArgs[1];
+  const extraPositionals = positionalArgs.slice(2);
+  if (!resourceName) {
+    if (isJsonOutput()) {
+      output(resources.map((r3) => ({ name: r3.name, description: r3.description, actions: r3.actions.length })));
+      return;
+    }
+    console.log(`
+Fulcrum API Resources`);
+    console.log("\u2500".repeat(40));
+    for (const r3 of resources) {
+      console.log(`  ${r3.name.padEnd(16)} ${r3.description} (${r3.actions.length} actions)`);
+    }
+    console.log(`
+Use: fulcrum api <resource> to list actions`);
+    console.log(`     fulcrum api <resource> <action> [<id>] [--flag value]`);
+    console.log("");
+    return;
+  }
+  const resolved = resolveAction(resources, resourceName, actionName);
+  if (!resolved.action) {
+    if (isJsonOutput()) {
+      output(resolved.resource);
+      return;
+    }
+    console.log(`
+${resolved.resource.name} \u2014 ${resolved.resource.description}`);
+    console.log("\u2500".repeat(60));
+    for (const a2 of resolved.resource.actions) {
+      const params = a2.pathParams.map((p) => `<${p}>`).join(" ");
+      const flags = [
+        ...a2.queryParams.map((p) => `--${p}`),
+        ...a2.bodyFields.map((f3) => f3.required ? `--${f3.name}` : `[--${f3.name}]`)
+      ].join(" ");
+      console.log(`  ${a2.action} ${params} ${flags}`.trimEnd());
+      console.log(`    ${a2.description}`);
+    }
+    console.log("");
+    return;
+  }
+  const req = buildRequest(resolved.action, extraPositionals, actionFlags);
+  await handleHttpRequest(req.method, req.url, req.body, mergedGlobalFlags);
+}
+function formatToolsReference(resources) {
+  const lines = [];
+  lines.push("Fulcrum API \u2014 fulcrum api <resource> <action> [<id>] [--key value]");
+  lines.push("");
+  for (const r3 of resources) {
+    lines.push(`${r3.name} \u2014 ${r3.description}`);
+    for (const a2 of r3.actions) {
+      const parts = [`  ${a2.action}`];
+      for (const p of a2.pathParams) {
+        parts.push(`<${p}>`);
+      }
+      const requiredFlags = a2.bodyFields.filter((f3) => f3.required).map((f3) => `--${f3.name}`);
+      const optionalFlags = [
+        ...a2.queryParams.map((p) => `--${p}`),
+        ...a2.bodyFields.filter((f3) => !f3.required).map((f3) => `--${f3.name}`)
+      ];
+      if (requiredFlags.length > 0) {
+        parts.push(requiredFlags.join(" "));
+      }
+      if (optionalFlags.length > 0) {
+        parts.push(`[${optionalFlags.join(" ")}]`);
+      }
+      if (a2.description.toLowerCase().includes("multipart")) {
+        parts.push("(multipart)");
+      }
+      lines.push(parts.join(" "));
+    }
+  }
+  return lines.join(`
+`);
+}
+async function handleTools(flags) {
+  const baseUrl = discoverServerUrl(flags.url, flags.port);
+  const resources = await fetchResources(baseUrl);
+  if (isJsonOutput()) {
+    output(resources);
+    return;
+  }
+  console.log(formatToolsReference(resources));
+}
+function isHttpMethod(arg) {
+  return HTTP_METHODS.includes(arg.toUpperCase());
+}
+function getRawArgsAfterApi() {
+  const argv2 = process.argv;
+  const apiIdx = argv2.indexOf("api");
+  if (apiIdx === -1)
+    return [];
+  return argv2.slice(apiIdx + 1);
+}
+var routesCommand = defineCommand({
+  meta: { name: "routes", description: "List available API routes" },
+  args: {
+    ...globalArgs,
+    category: { type: "string", description: "Filter by category" },
+    search: { type: "string", description: "Search routes by keyword" }
+  },
+  async run({ args }) {
+    setupJsonOutput(args);
+    await handleRoutes(toFlags(args));
+  }
+});
+var toolsCommand = defineCommand({
+  meta: { name: "tools", description: "Print compact tool reference for context window injection" },
+  args: {
+    ...globalArgs
+  },
+  async run({ args }) {
+    setupJsonOutput(args);
+    await handleTools(toFlags(args));
+  }
+});
+var apiCommand = defineCommand({
+  meta: { name: "api", description: "REST API access \u2014 route discovery, HTTP proxy, and resource/action CLI" },
+  args: {
+    ...globalArgs,
+    method: { type: "positional", description: 'HTTP method, resource name, or "routes"/"tools"', required: false },
+    path: { type: "positional", description: "API path or action name", required: false },
+    data: { type: "string", alias: "d", description: "Request body (JSON)" },
+    category: { type: "string", description: "Filter routes by category" },
+    search: { type: "string", description: "Search routes by keyword" }
+  },
+  subCommands: {
+    routes: routesCommand,
+    tools: toolsCommand
+  },
+  async run({ args }) {
+    setupJsonOutput(args);
+    const flags = toFlags(args);
+    const firstArg = args.method;
+    if (!firstArg) {
+      await handleResourceAction([], flags);
+      return;
+    }
+    if (firstArg.toLowerCase() === "routes") {
+      await handleRoutes(flags);
+      return;
+    }
+    if (firstArg.toLowerCase() === "tools") {
+      await handleTools(flags);
+      return;
+    }
+    if (isHttpMethod(firstArg)) {
+      await handleHttpRequest(firstArg, args.path, args.data, flags);
+      return;
+    }
+    const rawArgs = getRawArgsAfterApi();
+    await handleResourceAction(rawArgs, flags);
+  }
+});
+
 // cli/src/commands/migrate-from-vibora.ts
 init_server();
 async function handleMigrateFromViboraCommand(flags) {
@@ -51242,6 +51571,7 @@ var main = defineCommand({
     doctor: doctorCommand,
     dev: devCommand,
     mcp: mcpCommand,
+    api: apiCommand,
     update: updateCommand,
     "migrate-from-vibora": migrateFromViboraCommand
   }