@jive-ai/cli 0.0.3 → 0.0.4

package/docs/getting-started.md

@@ -0,0 +1,263 @@
+# Getting Started with Jive CLI
+
+Jive CLI is a command-line tool for managing MCP (Model Context Protocol) servers, tools, and subagents across teams. It integrates with Claude Code to provide team-based collaboration features for AI development.
+
+## What is Jive?
+
+Jive enables teams to:
+- Share and collaborate on **subagents** (custom AI agents with specialized prompts)
+- Share and manage **MCP servers** (tools that extend Claude's capabilities)
+- Track usage and telemetry across team projects
+- Synchronize AI resources across team members
+
+## Prerequisites
+
+- Node.js installed (for running MCP servers)
+- Claude Code installed
+- A Jive account (created in the app, or via `jive signup`)
+
+## Quick Start
+
+### 1. Install Jive CLI
+
+```bash
+npm install -g @jive-ai/cli
+```
+
+### 2. Create an Account
+
+```bash
+jive signup
+```
+
+You'll be prompted for:
+- Email address
+- Password (minimum 8 characters)
+
+Your credentials are securely stored in `~/.jive/credentials.json`.
+
+### 3. Create or Join a Team
+
+Create a new team:
+```bash
+jive team create
+```
+
+Or accept an invitation to join an existing team (invitations are sent via email).
+
+### 4. Initialize Jive in Your Project
+
+Navigate to your project directory and run:
+
+```bash
+jive init
+```
+
+This command will:
+- Scan and upload any existing MCP servers from `.mcp.json`
+- Scan and upload any existing subagents from `.claude/agents/*.md`
+- Add the `jive-mcp` server to your MCP configuration
+- Install the telemetry plugin for tracking tool usage
+- Create project configuration files in `.jive/`
+
+### 5. Restart Claude Code
+
+After initialization, restart Claude Code to load the new MCP server and telemetry plugin.
+
+## Project Structure
+
+After initialization, Jive creates the following structure:
+
+```
+your-project/
+├── .jive/
+│   ├── config.json          # Project configuration (team ID, API settings)
+│   └── sync.json            # Sync state tracking
+├── .claude/
+│   ├── agents/
+│   │   └── subagent-runner.md  # Dynamic subagent loader
+│   └── plugins/
+│       └── jive-mcp-telemetry/  # Telemetry tracking plugin
+└── .mcp.json                # MCP server configurations (includes jive-mcp)
+```
+
+**Important:** Add these to your `.gitignore`:
+```
+.jive/config.json
+.jive/sync.json
+.claude/plugins/
+```
+
+These are automatically added by `jive init`.
+
+## Core Concepts
+
+### Subagents
+
+Subagents are custom AI agents defined by markdown files with YAML frontmatter. They provide specialized prompts and behaviors for specific tasks.
+
+**Example subagent file** (`.claude/agents/code-reviewer.md`):
+```markdown
+---
+name: code-reviewer
+description: Reviews code for best practices and potential issues
+jive-id: "123"
+---
+
+You are a code reviewer. Analyze the provided code and:
+1. Identify potential bugs or issues
+2. Suggest improvements for readability
+3. Check for security vulnerabilities
+4. Recommend best practices
+```
+
+### MCP Servers
+
+MCP servers extend Claude's capabilities by providing additional tools. They can:
+- Access external APIs
+- Read and write files
+- Execute commands
+- Interact with databases
+- And much more
+
+Jive helps teams share MCP server configurations across projects.
+
+### Teams
+
+Teams are the organizational unit in Jive. All subagents and MCP servers belong to a team. Team members can:
+- Access shared subagents and MCP servers
+- Collaborate on AI resources
+- View usage analytics and telemetry
+
+## Common Workflows
+
+### Sharing a New Subagent
+
+1. Create a subagent file locally:
+   ```bash
+   jive subagents create
+   ```
+
+2. Push it to your team:
+   ```bash
+   jive subagents push
+   ```
+
+3. Team members can pull it:
+   ```bash
+   jive subagents pull
+   ```
+
+### Sharing a New MCP Server
+
+1. Add the server to your team:
+   ```bash
+   jive mcp add my-server
+   ```
+
+2. Team members can pull it:
+   ```bash
+   jive mcp pull
+   ```
+
+### Keeping Resources in Sync
+
+Pull the latest resources from your team:
+```bash
+jive sync
+```
+
+Check the status of your local resources:
+```bash
+jive status
+```
+
+### Switching Between Teams
+
+If you're a member of multiple teams:
+
+1. List your teams:
+   ```bash
+   jive team list
+   ```
+
+2. Switch to a different team:
+   ```bash
+   jive team switch
+   ```
+
+## Configuration
+
+### API URL
+
+By default, Jive connects to `https://next.getjive.app`. You can override this with the `JIVE_API_URL` environment variable:
+
+```bash
+export JIVE_API_URL=https://your-custom-api.com
+```
+
+### Credentials Location
+
+Credentials are stored in `~/.jive/credentials.json` with secure file permissions (mode 0600).
+
+### Project Configuration
+
+Each project has its own configuration in `.jive/config.json`:
+```json
+{
+  "activeTeamId": "team-123",
+  "apiUrl": "https://next.getjive.app",
+  "telemetry": {
+    "enabled": true
+  },
+  "lastSync": "2025-01-15T10:30:00.000Z"
+}
+```
+
+## Troubleshooting
+
+### Check Installation Health
+
+Run the doctor command to diagnose issues:
+```bash
+jive doctor
+```
+
+This checks:
+- Authentication status
+- Project initialization
+- MCP server configuration
+- Subagent runner installation
+- Telemetry plugin setup
+- API connectivity
+- Team membership
+
+### Common Issues
+
+**"Not authenticated"**
+- Run `jive login` to authenticate
+
+**"Project not initialized"**
+- Run `jive init` in your project directory
+
+**"Cannot find team"**
+- Ensure you've created or joined a team with `jive team create` or accepted an invitation
+
+**MCP server not loading**
+- Restart Claude Code after running `jive init`
+- Check `.mcp.json` for the `jive-mcp` entry
+- Run `jive doctor` to verify configuration
+
+## Next Steps
+
+- Learn about [Authentication Commands](./auth.md)
+- Set up your [Team](./team.md)
+- Explore [Subagent Management](./subagents.md)
+- Configure [MCP Servers](./mcp.md)
+- Master [Synchronization](./sync.md)
+
+## Getting Help
+
+- Run `jive --help` to see all available commands
+- Run `jive <command> --help` for command-specific help
+- Report issues at: https://github.com/anthropics/jive-cli/issues