create-snipara 1.2.0 → 1.3.0

package/README.md

@@ -1,213 +1,199 @@
 # create-snipara
 
-One-command setup for **Snipara MCP + RLM-Runtime** - context optimization, semantic memory, and safe code execution for AI agents.
+One-command setup and maintenance CLI for **Snipara MCP + snipara-companion + optional RLM-Runtime**.
 
 ```bash
 npx create-snipara
 ```
 
+`create-snipara` is the entry point. It bootstraps and maintains a complete local Snipara setup for one project. It does not replace the runtime packages. Instead, it installs and wires them together:
+
+- `snipara-mcp` for hosted MCP access
+- `snipara-companion` for local `rlm-hook` workflows
+- `rlm-runtime` for optional local code execution
+- local config, env files, hook scripts, and a project companion pack
+
+## Install Profiles
+
+The CLI now works around explicit install profiles:
+
+| Profile            | What it installs                          | Best for                                  |
+| ------------------ | ----------------------------------------- | ----------------------------------------- |
+| `hosted-only`      | MCP config only                           | SaaS-first setups without local workflows |
+| `hosted-companion` | MCP + `snipara-companion`                 | Recommended default                       |
+| `full-stack`       | MCP + `snipara-companion` + `rlm-runtime` | Hosted context plus local execution       |
+| `runtime-only`     | `rlm-runtime` only                        | Local execution without hosted API        |
+
+Default profile: `hosted-companion`
+
 ## What It Does
 
-- **Installs snipara-mcp** - MCP server for context-optimized documentation queries
-- **Installs rlm-runtime** - Safe code execution with Docker isolation
-- **Configures .mcp.json** - Ready for Claude Code, Cursor, Claude Desktop
-- **Sets up hooks** - Session memory automation (Claude Code)
-- **Updates environment files** - Adds API key configuration
+- detects local environment and project state
+- installs `snipara-companion` by default for local workflows
+- installs `snipara-mcp` and optional `rlm-runtime`
+- configures `.mcp.json`
+- updates `.env`, `.env.local`, and `.env.example`
+- generates `.snipara/companion/README.md`
+- generates `.snipara/companion/commands.json`
+- generates `.snipara/companion/doctor.json`
+- optionally installs Claude Code hooks
+- supports `doctor`, `repair`, `upgrade`, and `print-config`
 
-## Interactive Setup
+## Quick Start
 
 ```bash
 npx create-snipara
 ```
 
-You'll be prompted for:
-
-| Prompt | Description |
-|--------|-------------|
-| **Project slug** | Auto-detected from git remote or directory name |
-| **Project ID** | Optional, for advanced use cases |
-| **API key type** | Project key, Team key, Sign up, or Skip |
-| **API key** | Your Snipara API key |
-| **AI client** | Claude Code, Cursor, Claude Desktop, or other |
-| **Packages** | Choose what to install |
-| **LLM provider** | OpenAI, Anthropic, or None (for `rlm run`/`rlm agent` CLI) |
-| **Run rlm init** | Optional - configure execution environment (sandbox/docker/local) |
+The interactive flow now asks for:
 
-## API Key Requirements
+- install profile
+- project slug
+- optional project id
+- API key type and key when needed
+- AI client
+- whether hooks should be generated
+- optional runtime provider config when `rlm-runtime` is installed
 
-| Tool | Snipara API Key | LLM API Key (OpenAI/Anthropic) |
-|------|-----------------|-------------------------------|
-| `execute_python` MCP | Not needed | Not needed (your AI client is the LLM) |
-| `rlm_context_query` MCP | **Required** | Not needed |
-| `rlm_remember`/`rlm_recall` | **Required** | Not needed |
-| `rlm run` / `rlm agent` CLI | Optional (for context) | **Required** |
+## Main Commands
 
-### Key Types
+### Install or initialize
 
-| Type | Description |
-|------|-------------|
-| **Project API key** | Access to a single project |
-| **Team API key** | Access to all projects in your team |
+```bash
+npx create-snipara
+npx create-snipara init
+```
 
-## Command Line Options
+### Inspect local setup
 
 ```bash
-# Basic usage
-npx create-snipara
+npx create-snipara doctor
+```
 
-# With project API key
-npx create-snipara --api-key rlm_your_project_key
+Writes `.snipara/companion/doctor.json` and validates:
 
-# With team API key (access all team projects)
-npx create-snipara --team-key rlm_your_team_key
+- local config files
+- companion CLI presence
+- runtime CLI presence
+- environment files
+- hosted MCP reachability when a live API key is available
 
-# Specify project slug
-npx create-snipara --slug my-project
+### Repair local setup
 
-# Runtime only - no Snipara API key needed
-# (for execute_python MCP tool only)
-npx create-snipara --runtime-only
+```bash
+npx create-snipara repair
+```
 
-# Skip specific installations
-npx create-snipara --skip-mcp      # Skip snipara-mcp
-npx create-snipara --skip-runtime  # Skip rlm-runtime
-npx create-snipara --skip-hooks    # Skip Claude Code hooks
-npx create-snipara --skip-test     # Skip connection test
+Rebuilds local project wiring:
 
-# Accept all defaults (non-interactive)
-npx create-snipara -y --api-key rlm_xxx --slug my-project
+- `.mcp.json`
+- env files
+- companion pack
+- hooks when relevant
 
-# Full example with team key
-npx create-snipara --team-key rlm_team_xxx --slug my-project --skip-hooks
-```
+### Upgrade local pieces
 
-## What Gets Created
-
-### .mcp.json
-
-```json
-{
-  "mcpServers": {
-    "snipara": {
-      "type": "http",
-      "url": "https://api.snipara.com/mcp/your-project",
-      "headers": {
-        "X-API-Key": "rlm_your_key"
-      }
-    },
-    "rlm-runtime": {
-      "type": "http",
-      "url": "http://localhost:8765/mcp",
-      "headers": {}
-    }
-  }
-}
+```bash
+npx create-snipara upgrade
 ```
 
-### Claude Code Hooks (if selected)
+Upgrades installed local components and refreshes the companion pack.
 
-- `snipara-startup.sh` - Restores session context
-- `snipara-session.sh` - Auto-remembers commits
-- `snipara-compact.sh` - Saves context before compaction
+### Print inferred config
 
-### Environment Files
+```bash
+npx create-snipara print-config
+npx create-snipara print-config --json
+```
 
-Updates `.env.example` and `.env.local` with:
+## Common Flags
 
 ```bash
-# Snipara Configuration
-SNIPARA_API_KEY=your_api_key
-SNIPARA_PROJECT_SLUG=your-project
-
-# RLM-Runtime LLM Provider (if configured)
-OPENAI_API_KEY=sk-...
-# or
-ANTHROPIC_API_KEY=sk-ant-...
+# Use an explicit install profile
+npx create-snipara --profile hosted-companion
+npx create-snipara --profile full-stack
+
+# Runtime-only local execution
+npx create-snipara --runtime-only
+
+# Non-interactive setup
+npx create-snipara -y --api-key rlm_xxx --slug my-project
+
+# Skip selected layers
+npx create-snipara --skip-companion
+npx create-snipara --skip-mcp
+npx create-snipara --skip-runtime
+npx create-snipara --skip-hooks
+
+# Force extra layers during maintenance
+npx create-snipara repair --with-hooks
+npx create-snipara upgrade --with-runtime
 ```
 
-## After Installation
+## Packaging Model
 
-### For Claude Code / Cursor
+The intended split is:
 
-1. Restart your AI client
-2. MCP tools are automatically available
+- `create-snipara`: install, inspect, repair, and upgrade the local project setup
+- `snipara-companion`: ongoing local runtime workflows through `rlm-hook`
+- `snipara-mcp`: hosted MCP bridge
+- `rlm-runtime`: optional local execution engine
 
-### For Claude Desktop
+This keeps setup and runtime separated while still giving the user one obvious command to start from.
 
-1. Restart Claude Desktop
-2. Config is at `~/Library/Application Support/Claude/claude_desktop_config.json`
+## Generated Local Pack
 
-### RLM-Runtime Usage
+After setup, the project gets a local pack at `.snipara/companion/`:
 
-**MCP Tools (no LLM API key needed):**
+- `README.md`: local usage guidance
+- `commands.json`: starter commands for the current project
+- `doctor.json`: most recent validation report
 
-Your AI client (Claude, GPT, etc.) provides the LLM - no additional API key required.
+This pack is meant to be the local source of truth for machine-level setup.
 
-```
-• execute_python    - Run Python in sandbox
-• get_repl_context  - Get session variables
-• set_repl_context  - Set session variables
-• clear_repl_context - Clear session
-```
+## API Key Requirements
 
-**Execution Environments:**
+| Tooling                              | Snipara API key      | LLM API key |
+| ------------------------------------ | -------------------- | ----------- |
+| Hosted MCP queries                   | Required             | Not needed  |
+| Memory / planning tools              | Required             | Not needed  |
+| `snipara-companion` hosted workflows | Required             | Not needed  |
+| `rlm-runtime` `execute_python` MCP   | Not needed           | Not needed  |
+| `rlm run` / `rlm agent` CLI          | Optional for context | Required    |
 
-| Environment | Description | Use Case |
-|-------------|-------------|----------|
-| **sandbox** | RestrictedPython, safe stdlib only | Default, most secure |
-| **docker** | Full Python in isolated container | Recommended for full features |
-| **local** | Full access, no isolation | Development only |
+## Example Flows
 
-During setup, you can run `rlm init` to configure the default environment.
-Or configure later:
+### Default recommended setup
 
 ```bash
-rlm init  # Interactive configuration
+npx create-snipara --profile hosted-companion
 ```
 
-**CLI Commands (requires LLM API key):**
-
-For `rlm run` and `rlm agent`, you need an LLM provider API key:
+### Full local stack
 
 ```bash
-# Set your LLM provider
-export OPENAI_API_KEY=sk-...
-# or
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Run commands
-rlm init              # Initialize configuration
-rlm run --env docker  # Run with Docker isolation
-rlm agent "task"      # Autonomous agent mode
-rlm visualize         # Launch trajectory dashboard
+npx create-snipara --profile full-stack
 ```
 
-## Available MCP Tools
-
-After setup, you have access to 43+ MCP tools:
+### Repair after a broken workstation or new shell
 
-| Category | Tools |
-|----------|-------|
-| **Context** | `rlm_context_query`, `rlm_ask`, `rlm_search`, `rlm_sections` |
-| **Planning** | `rlm_plan`, `rlm_decompose`, `rlm_multi_query` |
-| **Memory** | `rlm_remember`, `rlm_recall`, `rlm_memories`, `rlm_forget` |
-| **Execution** | `execute_python`, `get_repl_context` (via RLM-Runtime) |
-| **Swarms** | `rlm_swarm_create`, `rlm_claim`, `rlm_task_create` |
+```bash
+npx create-snipara repair
+npx create-snipara doctor
+```
 
-## Requirements
+### Check what the CLI inferred from this project
 
-- Node.js 18+
-- Python 3.10+ (for snipara-mcp and rlm-runtime)
-- Docker (optional, for RLM-Runtime isolation)
+```bash
+npx create-snipara print-config --json
+```
 
-## Links
+## Local Tarball Testing
 
-- **Website**: https://snipara.com
-- **Documentation**: https://snipara.com/docs
-- **Dashboard**: https://snipara.com/dashboard
-- **npm**: https://www.npmjs.com/package/create-snipara
-- **Support**: hello@starbox-group.com
+When testing a locally packed tarball, use `npm exec --package` instead of `npx`, for example:
 
-## License
+```bash
+npm exec --package ./create-snipara-1.3.0.tgz create-snipara -- --help
+```
 
-MIT
+This avoids `npx` resolution issues with unpublished tarballs.