create-snipara 1.1.0 → 1.3.0

package/README.md

@@ -1,140 +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:
+The interactive flow now asks for:
+
+- 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
+
+## Main Commands
 
-| Prompt | Description |
-|--------|-------------|
-| **Project slug** | Auto-detected from git remote or directory name |
-| **Project ID** | Optional, for advanced use cases |
-| **API key** | Your Snipara API key (or sign up for free) |
-| **AI client** | Claude Code, Cursor, Claude Desktop, or other |
-| **Packages** | Choose what to install |
+### Install or initialize
+
+```bash
+npx create-snipara
+npx create-snipara init
+```
 
-## Command Line Options
+### Inspect local setup
 
 ```bash
-# Use existing API key
-npx create-snipara --api-key rlm_your_key_here
+npx create-snipara doctor
+```
 
-# Specify project slug
-npx create-snipara --slug my-project
+Writes `.snipara/companion/doctor.json` and validates:
 
-# 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
+- local config files
+- companion CLI presence
+- runtime CLI presence
+- environment files
+- hosted MCP reachability when a live API key is available
 
-# Accept all defaults
-npx create-snipara -y
+### Repair local setup
 
-# Full example
-npx create-snipara --api-key rlm_xxx --slug my-project --skip-hooks
+```bash
+npx create-snipara repair
 ```
 
-## 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": {}
-    }
-  }
-}
+Rebuilds local project wiring:
+
+- `.mcp.json`
+- env files
+- companion pack
+- hooks when relevant
+
+### Upgrade local pieces
+
+```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_API_KEY=your_api_key
-SNIPARA_PROJECT_SLUG=your-project
+# 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
+
+The intended split is:
+
+- `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
+
+This keeps setup and runtime separated while still giving the user one obvious command to start from.
+
+## Generated Local Pack
+
+After setup, the project gets a local pack at `.snipara/companion/`:
+
+- `README.md`: local usage guidance
+- `commands.json`: starter commands for the current project
+- `doctor.json`: most recent validation report
 
-### For Claude Code / Cursor
+This pack is meant to be the local source of truth for machine-level setup.
 
-1. Restart your AI client
-2. MCP tools are automatically available
+## API Key Requirements
 
-### For Claude Desktop
+| 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    |
 
-1. Restart Claude Desktop
-2. Config is at `~/Library/Application Support/Claude/claude_desktop_config.json`
+## Example Flows
 
-### RLM-Runtime Commands
+### Default recommended setup
 
 ```bash
-rlm init              # Initialize configuration
-rlm run --env docker  # Run with Docker isolation
-rlm serve             # Start MCP server
-rlm visualize         # Launch trajectory dashboard
+npx create-snipara --profile hosted-companion
 ```
 
-## Available MCP Tools
+### Full local stack
 
-After setup, you have access to 43+ MCP tools:
+```bash
+npx create-snipara --profile full-stack
+```
 
-| 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`, `rlm_agent_run` (via RLM-Runtime) |
-| **Swarms** | `rlm_swarm_create`, `rlm_claim`, `rlm_task_create` |
+### Repair after a broken workstation or new shell
 
-## Requirements
+```bash
+npx create-snipara repair
+npx create-snipara doctor
+```
 
-- Node.js 18+
-- Python 3.10+ (for snipara-mcp and rlm-runtime)
-- Docker (optional, for RLM-Runtime isolation)
+### Check what the CLI inferred from this project
 
-## Links
+```bash
+npx create-snipara print-config --json
+```
+
+## Local Tarball Testing
 
-- **Website**: https://snipara.com
-- **Documentation**: https://snipara.com/docs
-- **Dashboard**: https://snipara.com/dashboard
-- **Support**: hello@snipara.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.