@jive-ai/cli 0.0.26 → 0.0.30

package/docs/init.md

@@ -1,591 +0,0 @@
-# Project Initialization Commands
-
-These commands help you set up, verify, and remove Jive integration from your projects.
-
-## Overview
-
-Jive needs to be initialized in each project directory where you want to use team-based MCP servers and subagents. The initialization process:
-- Connects your project to a team
-- Uploads existing resources to the team
-- Adds the Jive MCP server to your configuration
-- Installs telemetry tracking
-
-## Commands
-
-### `jive init`
-
-Initialize Jive in the current project directory.
-
-**Usage:**
-```bash
-jive init
-```
-
-**Requirements:**
-- Must be authenticated (`jive login`)
-- Must be a member of at least one team
-- Must be in the root directory of your project
-
-**Interactive Prompts:**
-- **Select a team:** Choose which team to associate with this project
-- **Re-initialization confirmation:** If already initialized, confirms overwrite
-
-**Process:**
-
-1. **Check existing initialization:**
-   - If `.jive/config.json` exists, prompts for confirmation to re-initialize
-
-2. **Team selection:**
-   - Fetches all teams you're a member of
-   - Prompts for team selection
-
-3. **Scan and upload existing resources:**
-   - **MCP Servers:** Scans `.mcp.json` for existing servers
-     - Uploads each server to the team (except `jive-mcp` itself)
-     - Preserves all server configurations (command, args, env)
-   - **Subagents:** Scans `.claude/agents/*.md` for existing subagents
-     - Parses frontmatter and content
-     - Uploads each to the team
-     - Adds `jive-id` field to frontmatter for tracking
-
-4. **Add Jive integrations:**
-   - **Jive MCP Server:** Adds to `.mcp.json`:
-     ```json
-     {
-       "jive-mcp": {
-         "command": "npx",
-         "args": ["-y", "jive-cli", "mcp", "start"],
-         "env": {
-           "JIVE_API_URL": "https://next.getjive.app",
-           "JIVE_TEAM_ID": "team-abc123",
-           "JIVE_AUTH_TOKEN": "your-token"
-         }
-       }
-     }
-     ```
-
-5. **Create project files:**
-   - **`.jive/config.json`:** Project configuration
-     ```json
-     {
-       "activeTeamId": "team-abc123",
-       "apiUrl": "https://next.getjive.app",
-       "telemetry": {
-         "enabled": true
-       },
-       "lastSync": "2025-01-15T10:30:00.000Z"
-     }
-     ```
-
-   - **`.jive/sync.json`:** Sync state tracking
-     ```json
-     {
-       "lastSync": "2025-01-15T10:30:00.000Z",
-       "subagents": {},
-       "mcpServers": {}
-     }
-     ```
-
-   - **`.claude/agents/subagent-runner.md`:** Dynamic subagent loader
-
-6. **Install telemetry plugin:**
-   - Creates `.claude/plugins/jive-mcp-telemetry/`
-   - Creates plugin manifest
-   - Sets up PostToolUse hook for capturing tool calls
-   - Tracks MCP tool usage and subagent executions
-
-7. **Update .gitignore:**
-   - Adds `.jive/config.json` (contains sensitive team info)
-   - Adds `.jive/sync.json` (local sync state)
-   - Adds `.claude/plugins/` (generated plugin files)
-
-**Output:**
-```
-Initializing Jive...
-
-Scanning for existing resources...
-Found 2 MCP servers in .mcp.json
-Found 3 subagents in .claude/agents/
-
-Uploading existing MCP servers...
-✓ weather-api
-✓ file-system
-
-Uploading existing subagents...
-✓ code-reviewer
-✓ bug-fixer
-✓ test-writer
-
-Adding Jive MCP server to .mcp.json...
-Creating .jive/config.json...
-Creating .claude/agents/subagent-runner.md...
-Installing telemetry plugin...
-Updating .gitignore...
-
-Jive initialized successfully!
-
-Summary:
-- Team: My Team (team-abc123)
-- Uploaded 2 MCP servers
-- Uploaded 3 subagents
-- Added jive-mcp server
-- Installed telemetry plugin
-
-Next steps:
-1. Restart Claude Code to load the new MCP server
-2. Use 'jive sync' to pull team resources
-3. Use 'jive doctor' to verify setup
-```
-
-**Directory Structure After Init:**
-```
-your-project/
-├── .jive/
-│   ├── config.json          # Team and API configuration
-│   └── sync.json            # Sync state tracking
-├── .claude/
-│   ├── agents/
-│   │   ├── code-reviewer.md    # Existing subagents (now with jive-id)
-│   │   ├── bug-fixer.md
-│   │   ├── test-writer.md
-│   │   └── subagent-runner.md  # Dynamic subagent loader (added by Jive)
-│   └── plugins/
-│       └── jive-mcp-telemetry/  # Telemetry plugin
-│           ├── manifest.json
-│           └── hooks/
-│               └── post-tool-use.js
-├── .mcp.json                # Now includes jive-mcp server
-└── .gitignore               # Updated with Jive entries
-```
-
-**Notes:**
-- Existing MCP servers and subagents are preserved
-- You can re-initialize to change teams or fix configuration
-- Restart Claude Code after initialization
-
-**Error Conditions:**
-- Not authenticated
-- No teams available (create one with `jive team create`)
-- Permission issues creating files/directories
-- Network connectivity issues
-
-**Implementation:** `src/commands/init.ts`
-
----
-
-### `jive detach`
-
-Remove Jive integration from the current project.
-
-**Usage:**
-```bash
-jive detach
-```
-
-**Requirements:**
-- Must be in a Jive-initialized project
-
-**Interactive Prompts:**
-- **Confirmation:** "Are you sure you want to detach from Jive?" (Y/n)
-
-**Process:**
-
-1. **Confirmation:**
-   - Warns about removing Jive integration
-   - Prompts for confirmation
-
-2. **Pull all content from platform:**
-   - **Downloads all team subagents** to `.claude/agents/`
-   - **Removes `jive-id` from frontmatter** (converts to local-only)
-   - **Downloads all team MCP servers** to `.mcp.json`
-   - This ensures you keep all team resources locally
-
-3. **Remove Jive integrations:**
-   - Removes `jive-mcp` server from `.mcp.json`
-   - Deletes `.claude/plugins/jive-mcp-telemetry/` directory
-   - Deletes `.claude/agents/subagent-runner.md`
-   - Deletes `.jive/` directory (config.json and sync.json)
-
-4. **Clean up .gitignore:**
-   - Removes Jive-specific entries:
-     - `.jive/config.json`
-     - `.jive/sync.json`
-     - `.claude/plugins/`
-
-5. **Display next steps:**
-   - Suggests restarting Claude Code
-
-**Output:**
-```
-This will remove Jive integration from this project.
-Your local files will be preserved.
-
-? Are you sure you want to detach from Jive? (Y/n) Yes
-
-Pulling all content from platform...
-✓ Downloaded 5 subagents
-✓ Downloaded 3 MCP servers
-
-Removing Jive integrations...
-✓ Removed jive-mcp from .mcp.json
-✓ Removed telemetry plugin
-✓ Removed subagent-runner
-✓ Removed .jive/ directory
-✓ Cleaned up .gitignore
-
-Detached successfully!
-
-All team resources have been saved locally.
-Your subagents and MCP servers are now local-only.
-
-Next steps:
-1. Restart Claude Code
-2. (Optional) Re-initialize with 'jive init' to reconnect to a team
-```
-
-**What Happens to Your Files:**
-
-Before detach:
-```markdown
----
-name: code-reviewer
-description: Reviews code
-jive-id: "sub-123"
----
-Review code for issues...
-```
-
-After detach:
-```markdown
----
-name: code-reviewer
-description: Reviews code
----
-Review code for issues...
-```
-
-**Notes:**
-- All team resources are downloaded before detaching
-- Local files are preserved and converted to local-only
-- You can re-initialize later with `jive init`
-- This doesn't delete resources from the team (other members still have access)
-
-**Use Cases:**
-- Switching to a different team (detach then `jive init` with new team)
-- Working offline without Jive integration
-- Removing team dependency from a project
-
-**Error Conditions:**
-- Project not initialized (nothing to detach)
-- User cancels confirmation
-- File system errors during cleanup
-
-**Implementation:** `src/commands/detach.ts`
-
----
-
-### `jive doctor`
-
-Diagnose Jive installation and configuration issues.
-
-**Usage:**
-```bash
-jive doctor
-```
-
-**Requirements:**
-- None (works without authentication to help diagnose auth issues)
-
-**Process:**
-
-Runs a series of health checks and reports status:
-
-**Checks Performed:**
-
-1. **Authentication:**
-   - Verifies `~/.jive/credentials.json` exists
-   - Validates token is present
-   - **Status:** ✓ Pass / ⚠ Warning / ✗ Fail
-
-2. **Project Initialization:**
-   - Checks `.jive/config.json` exists
-   - Validates team ID is configured
-   - **Status:** ✓ Pass / ⚠ Warning / ✗ Fail
-
-3. **MCP Server Configuration:**
-   - Verifies `.mcp.json` exists
-   - Checks `jive-mcp` server is configured
-   - Validates server has required env vars
-   - **Status:** ✓ Pass / ⚠ Warning / ✗ Fail
-
-4. **Subagent Runner:**
-   - Checks `.claude/agents/subagent-runner.md` exists
-   - Validates file has correct frontmatter
-   - **Status:** ✓ Pass / ⚠ Warning / ✗ Fail
-
-5. **Telemetry Plugin:**
-   - Verifies `.claude/plugins/jive-mcp-telemetry/` exists
-   - Checks plugin structure is valid
-   - **Status:** ✓ Pass / ⚠ Warning / ✗ Fail
-
-6. **Plugin Configuration:**
-   - Validates plugin manifest exists
-   - Checks hooks are configured
-   - **Status:** ✓ Pass / ⚠ Warning / ✗ Fail
-
-7. **API Connectivity:**
-   - Tests connection to Jive API
-   - Verifies API is reachable
-   - **Status:** ✓ Pass / ⚠ Warning / ✗ Fail
-
-8. **Team Membership:**
-   - Verifies user is member of at least one team
-   - Checks active team is valid
-   - **Status:** ✓ Pass / ⚠ Warning / ✗ Fail
-
-**Output:**
-```
-Running Jive diagnostics...
-
-✓ Authentication: Logged in as user@example.com
-✓ Project Initialization: Initialized with team 'My Team'
-✓ MCP Server Configuration: jive-mcp server found
-✓ Subagent Runner: subagent-runner.md exists
-⚠ Telemetry Plugin: Plugin directory not found
-  Fix: Run 'jive init' to reinstall
-✗ Plugin Configuration: Hooks not configured
-  Fix: Run 'jive init' to reinstall
-✓ API Connectivity: Connected to https://next.getjive.app
-✓ Team Membership: Member of 2 teams
-
-Summary: 6 passed, 1 warning, 1 failed
-
-Suggested actions:
-1. Run 'jive init' to fix plugin configuration
-2. Restart Claude Code after fixing issues
-```
-
-**Status Indicators:**
-
-- **✓ (Green):** Check passed, no issues
-- **⚠ (Yellow):** Warning, may cause issues
-- **✗ (Red):** Check failed, action required
-
-**Common Issues and Fixes:**
-
-| Issue | Fix |
-|-------|-----|
-| Not authenticated | Run `jive login` |
-| Project not initialized | Run `jive init` |
-| MCP server missing | Run `jive init` to add jive-mcp |
-| Plugin not installed | Run `jive init` to install plugin |
-| Cannot reach API | Check network / JIVE_API_URL |
-| Not a team member | Run `jive team create` or accept invitation |
-
-**Use Cases:**
-- Troubleshooting setup issues
-- Verifying installation before using Jive
-- Checking configuration after updates
-- Diagnosing API connectivity problems
-
-**Notes:**
-- Safe to run multiple times
-- Doesn't modify any files (read-only)
-- Provides actionable fix suggestions
-- Works in any directory (checks vary based on context)
-
-**Error Conditions:**
-- None (designed to diagnose errors, not throw them)
-
-**Implementation:** `src/commands/doctor.ts`
-
----
-
-## Initialization Workflows
-
-### First-Time Project Setup
-
-1. **Authenticate:**
-   ```bash
-   jive login
-   ```
-
-2. **Create or join a team:**
-   ```bash
-   jive team create
-   ```
-
-3. **Initialize project:**
-   ```bash
-   cd my-project
-   jive init
-   ```
-   Select your team when prompted.
-
-4. **Verify setup:**
-   ```bash
-   jive doctor
-   ```
-
-5. **Restart Claude Code:**
-   - Restart to load the new MCP server and plugin
-
-### Moving Project to Different Team
-
-1. **Detach from current team:**
-   ```bash
-   jive detach
-   ```
-   This preserves all resources locally.
-
-2. **Re-initialize with new team:**
-   ```bash
-   jive init
-   ```
-   Select the new team when prompted.
-
-3. **Sync resources:**
-   ```bash
-   jive sync
-   ```
-
-4. **Restart Claude Code**
-
-### Troubleshooting Setup
-
-1. **Run diagnostics:**
-   ```bash
-   jive doctor
-   ```
-
-2. **Fix issues based on output:**
-   ```bash
-   # If not authenticated
-   jive login
-
-   # If project not initialized
-   jive init
-
-   # If MCP config broken
-   jive init  # Re-initialize
-   ```
-
-3. **Verify fixes:**
-   ```bash
-   jive doctor
-   ```
-
-4. **Restart Claude Code**
-
-## Configuration Files
-
-### `.jive/config.json`
-
-Project-level configuration:
-
-```json
-{
-  "activeTeamId": "team-abc123",
-  "apiUrl": "https://next.getjive.app",
-  "telemetry": {
-    "enabled": true
-  },
-  "lastSync": "2025-01-15T10:30:00.000Z"
-}
-```
-
-**Should be in .gitignore** (contains team-specific info)
-
-### `.jive/sync.json`
-
-Sync state tracking:
-
-```json
-{
-  "lastSync": "2025-01-15T10:30:00.000Z",
-  "subagents": {
-    "code-reviewer": {
-      "lastModified": "2025-01-14T15:20:00.000Z",
-      "jiveId": "sub-123"
-    }
-  },
-  "mcpServers": {
-    "weather-api": {
-      "lastModified": "2025-01-14T12:00:00.000Z",
-      "jiveId": "mcp-456"
-    }
-  }
-}
-```
-
-**Should be in .gitignore** (local state only)
-
-### `.claude/agents/subagent-runner.md`
-
-Dynamic subagent loader created by Jive:
-
-```markdown
----
-name: subagent-runner
-description: Execute dynamically loaded subagent prompts
----
-
-[Prompt content for loading and executing subagents]
-```
-
-**Should NOT be modified manually** (regenerated by `jive init`)
-
-## Telemetry Plugin
-
-### Purpose
-
-Tracks tool usage and subagent executions for:
-- Usage analytics
-- Team collaboration insights
-- Debugging and optimization
-
-### Structure
-
-```
-.claude/plugins/jive-mcp-telemetry/
-├── manifest.json           # Plugin configuration
-└── hooks/
-    └── post-tool-use.js   # PostToolUse hook handler
-```
-
-### What's Tracked
-
-- Tool calls (name, arguments, results)
-- Subagent executions
-- Timestamps and user context
-- Project and team association
-
-### Privacy
-
-- Only tracks tool usage metadata
-- Doesn't capture file contents or sensitive data
-- Can be disabled by removing the plugin
-
-## Related Commands
-
-- [`jive login`](./auth.md#jive-login) - Authenticate before init
-- [`jive team create`](./team.md#jive-team-create) - Create team before init
-- [`jive sync`](./sync.md#jive-sync) - Sync resources after init
-- [`jive team switch`](./team.md#jive-team-switch) - Change active team
-
-## Implementation Details
-
-**Source Files:**
-- Init: `src/commands/init.ts`
-- Detach: `src/commands/detach.ts`
-- Doctor: `src/commands/doctor.ts`
-- Config utilities: `src/lib/config.ts`
-- File system utilities: `src/lib/fs-utils.ts`
-
-**Key Functions:**
-- `initCommand()` - Main initialization logic
-- `detachCommand()` - Cleanup and detachment
-- `doctorCommand()` - Health checks
-- `scanAndUploadMcpServers()` - Upload existing MCP servers
-- `scanAndUploadSubagents()` - Upload existing subagents
-- `installTelemetryPlugin()` - Install telemetry plugin