@m14i/sith 1.21.1 → 1.23.0

package/README.md

@@ -8,163 +8,115 @@
 
 Standardize and share your OpenCode setup with a fully dockerized environment, designed for seamless collaboration and CI integration.
 
-## Usage
+---
 
-### Installation
+## Why?
 
-**Install globally (recommended):**
-```bash
-npm install -g @m14i/sith
-```
-
-**Or use npx (slower, pulls image every time):**
-```bash
-npx @m14i/sith@latest
-```
+AI coding tools are powerful in isolation. They become fragile at scale:
 
-### Quick Start
+- **Context drift** — every developer has a different CLAUDE.md, different tool versions, different configs. The AI sees a different project depending on who's running it.
+- **No CI path** — running `opencode` or `claude` in a pipeline requires wiring tokens, installing tools, and hoping the environment matches local.
+- **Multiple tools** — Claude Code and OpenCode serve different use cases (Anthropic auth vs GitHub Copilot). Switching between them shouldn't require manual setup.
 
-```bash
-# Interactive terminal UI (default)
-sith
-# Type your prompt to start OpenCode with that task
-# Or use slash commands: /shell, /config, /help
-
-# Direct commands
-sith --it          # Launch Docker shell immediately
-sith --pull        # Pull prebuilt image
-sith --build       # Build from scratch
-sith --legacy      # Use legacy menu interface
-```
+Sith solves this by packaging both tools, all config, and your team's context into a single Docker image. One pull, same environment, everywhere.
 
-### Distribution Options
+| Problem | Sith answer |
+|---------|-------------|
+| Inconsistent context across team | Shared `~/.sith/` skills + CLAUDE.md, mounted at runtime |
+| AI tools hard to run in CI | Prebuilt signed image + token injection via env vars |
+| Claude Code vs OpenCode friction | Both available, same container, same command |
+| "Works on my machine" builds | Nix-pinned dependencies inside Docker |
 
-| Method | Command | Speed | Trust Model | Use Case |
-|--------|---------|-------|-------------|----------|
-| **Prebuilt (Recommended)** | `sith --pull` | ⚡ Fast | GitHub Actions + Cosign | Production, CI/CD |
-| **Local Build** | `sith --build` | 🐌 Slow | Your machine | Air-gapped, custom builds |
+---
 
-### Commands
+## Docker
 
-| Command | Description |
-|---------|-------------|
-| `sith` | Interactive terminal UI (Claude Code style) |
-| `sith --it` | Launch Docker shell immediately |
-| `sith --pull` | Pull prebuilt image from GHCR |
-| `sith --build` | Build Docker image from scratch |
-| `sith --legacy` | Use legacy menu interface |
-| `sith --help` | Show all available commands |
+The recommended path. One image, works locally and in CI.
 
-### Terminal UI Usage
+### Install the CLI
 
-When you run `sith`, you get an interactive terminal interface:
+```bash
+npm install -g @m14i/sith
+```
 
-**Prompt input:**
-- Type any text → Starts OpenCode with that prompt using Claude Sonnet 4.6
-- Example: `Fix authentication bug` → OpenCode launches with this task
+Or without installing:
 
-**Slash commands:**
-- `/shell` → Start Docker shell only (no OpenCode)
-- `/config` → Open configuration menu (pull/build options)
-- `/help` → Show available commands
+```bash
+npx @m14i/sith@latest
+```
 
-**Navigation:**
-- `Ctrl+C` or `Esc` → Exit terminal UI
+### Get the image
 
-### Prebuilt Image Details
+**Prebuilt (recommended) — pull a signed image from GHCR:**
 
-**Pull and verify:**
 ```bash
-# Pull (supports linux/amd64 and linux/arm64)
 sith --pull
+```
+
+Supports `linux/amd64` and `linux/arm64`. Images are signed with cosign and include an SBOM.
 
-# Or use Docker directly
-docker pull ghcr.io/merzoukemanouri/sith:latest
+**Verify the signature (optional):**
 
-# Verify signature (optional)
+```bash
 cosign verify \
   --certificate-identity-regexp="https://github.com/MerzoukeMansouri/sith" \
   --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
   ghcr.io/merzoukemanouri/sith:latest
 ```
 
-**Benefits:**
-- ✅ Fast - no build time
-- ✅ Multi-platform - amd64 and arm64
-- ✅ Signed - cosign verification
-- ✅ SBOM - supply chain transparency
-- ✅ Auto-updated - tracks releases
+**Build from scratch — full control, no external trust:**
 
-## Authentication
-
-Sith supports two AI providers: **Claude Code** (via Anthropic) and **OpenCode** (via GitHub Copilot).
-
-### Claude Code (claude CLI)
-
-Sith ships with the `claude` CLI. Authenticate it with your Anthropic account using a long-lived OAuth token — no API key required.
-
-**Step 1 — Generate the token (once, on your local machine):**
 ```bash
-claude setup-token
+sith --build
 ```
-Follow the browser prompt, then copy the printed token. It is valid for one year and scoped to inference only.
 
-**Step 2 — Export it:**
-```bash
-export CLAUDE_CODE_OAUTH_TOKEN=your_token_here
-```
+| | `sith --pull` | `sith --build` |
+|--|--------------|----------------|
+| Speed | Fast | Slow |
+| Trust | GitHub Actions + Cosign | Your machine |
+| Use case | Daily use, CI/CD | Air-gapped, custom builds |
 
-**Make it persistent (add to ~/.zshrc or ~/.bashrc):**
-```bash
-export CLAUDE_CODE_OAUTH_TOKEN=your_token_here
-```
+### Use it
+
+**Interactive TUI** — type a prompt or use slash commands:
 
-**Verify:**
 ```bash
-claude auth status
-# Should show: "loggedIn": true, "authMethod": "claude.ai"
+sith
 ```
 
-**Requirements:** Claude Pro, Max, Team, or Enterprise subscription.
+| In the TUI | What it does |
+|------------|-------------|
+| Type any text + Enter | Starts OpenCode with that prompt |
+| `/shell` | Drop into Docker shell (no AI) |
+| `/claude` | Switch active tool to Claude Code |
+| `/opencode` | Switch active tool to OpenCode |
+| `/config` | Pull / build options |
+| `/help` | Show commands |
+| `Ctrl+C` / `Esc` | Exit |
 
-### GitHub Copilot (opencode CLI)
+**Direct commands** — skip the TUI:
 
-Sith uses **Claude Sonnet 4.6 via GitHub Copilot** by default for OpenCode. Requires a GitHub token with Copilot access.
-
-**Automatic (recommended):**
-If you have GitHub CLI (`gh`) installed and authenticated, Sith automatically fetches your token:
 ```bash
-sith  # Auto-detects token via gh auth token
+sith shell                        # Raw Nix shell inside Docker (alias: sith --it)
+sith opencode -p "fix the bug"    # OpenCode starts immediately with your task
+sith claude -p "fix the bug"      # Claude Code starts immediately with your task
 ```
 
-**Manual token:**
-If you don't have `gh` CLI or prefer manual setup:
+**Skills:**
 
-1. Ensure you have GitHub Copilot access
-2. Create a token at https://github.com/settings/tokens
-3. Required scopes: `copilot`, `repo`, `read:org`
-4. Export it:
 ```bash
-export GITHUB_TOKEN=gho_your_token_here
-sith
+sith skills    # Install / manage skills from catalog (~/.sith/skills/)
 ```
 
-**Make it persistent (add to ~/.zshrc or ~/.bashrc):**
-```bash
-export GITHUB_TOKEN=$(gh auth token)
-```
+### Cleanup & Uninstall
 
-**Inside container:**
-Once OpenCode starts, authenticate with GitHub Copilot:
 ```bash
-opencode providers login
-# Follow prompts to authenticate with GitHub
+sith --docker-cleanup    # Remove sith Docker images (sith:latest + prebuilt GHCR image)
+sith --uninstall         # Remove ~/.sith/ (skills, config, nix files)
 ```
 
 ### CI / GitHub Actions
 
-Add both tokens as repository secrets, then pass them to the container:
-
 ```yaml
 - name: Run sith
   env:
@@ -177,98 +129,70 @@ Add both tokens as repository secrets, then pass them to the container:
       ghcr.io/merzoukemanouri/sith:latest "claude auth status"
 ```
 
-Generate `CLAUDE_CODE_OAUTH_TOKEN` once with `claude setup-token` and store it in **Settings → Secrets → Actions** as `CLAUDE_CODE_OAUTH_TOKEN`.
+See [Authentication](./doc/AUTH_CLAUDE.md) for how to generate the tokens.
 
-## Features
+---
 
-- **Claude Code-style UI**: Interactive terminal interface with prompt input and slash commands
-- **OpenCode Integration**: Start coding with a simple text prompt
-- **Model Selection**: Uses Claude Sonnet 4.6 via GitHub Copilot by default
-- **Prebuilt Images**: Pull verified images from GitHub Container Registry
-- **Image Signing**: All images signed with cosign for supply chain security
-- **SBOM Attestation**: Software Bill of Materials included with every image
-- **Dockerized Environment**: Consistent setup across machines
-- **Nix Integration**: Full development environment with all tools
-- **CI-Ready**: Standardize builds across local and CI pipelines
-- **Non-root User**: Images run as non-root user (UID 1000) for better security
+## Direct Nix
 
-## Security
+No Docker. Runs the same Nix environment natively on your machine.
 
-### Image Verification
+```bash
+sith --nix-install    # Install Nix package manager (once)
+sith --nix            # Launch Nix shell directly
+```
 
-All Docker images published to `ghcr.io/merzoukemanouri/sith` are:
-- **Signed with cosign** using keyless signing (OIDC)
-- **Include SBOM** (Software Bill of Materials) for transparency
-- **Built automatically** via GitHub Actions with provenance
+Or via the `nix` subcommand:
+
+```bash
+sith nix --install    # Install Nix
+sith nix --shell      # Run Nix shell
+```
 
-See [SECURITY.md](./SECURITY.md) for detailed security practices and considerations.
+**Cleanup:**
 
-### Trust Model
+```bash
+sith --nix-cleanup      # Remove ~/.sith/nix/ + run nix-collect-garbage -d
+sith --nix-uninstall    # Fully remove Nix from system (daemon, /nix/store) — needs sudo
+```
 
-**Prebuilt Images:**
-- Built by GitHub Actions on public infrastructure
-- Signed with Sigstore keyless signing
-- Verifiable provenance chain from source to image
-- Trade-off: Trust GitHub's build infrastructure
+See [doc/NIX_INSTALLATION.md](./doc/NIX_INSTALLATION.md) for full setup guide.
 
-**Local Builds:**
-- Full control over build environment
-- Can inspect Dockerfile before building
-- No dependency on external registries
-- Trade-off: Slower, manual security updates
+---
 
-For more details, see the [Docker Distribution Guide](./doc/QUICKSTART.md#docker-distribution).
+## Authentication
 
-## Development
+Two AI providers, two token setups:
 
-For contributors working on the CLI:
+- **Claude Code** (Anthropic OAuth) → [doc/AUTH_CLAUDE.md](./doc/AUTH_CLAUDE.md)
+- **OpenCode** (GitHub Copilot) → [doc/AUTH_OPENCODE.md](./doc/AUTH_OPENCODE.md)
 
-```bash
-# Install dependencies
-pnpm install
+---
 
-# Run in development mode (no build)
-pnpm dev
+## Development
 
-# Build and test
+```bash
+pnpm install       # Install dependencies
+pnpm dev           # Run in development mode (no build)
 pnpm dev:build     # Build and run CLI
 pnpm dev:shell     # Build and launch shell
-
-# Type checking
-pnpm typecheck
-
-# Clean build artifacts
-pnpm clean
+pnpm typecheck     # Type checking
+pnpm clean         # Clean build artifacts
 ```
 
-## Publishing
-
-Automated releases using semantic-release and conventional commits.
+---
 
-### For Maintainers
+## Publishing
 
-**Commit Format:**
-- `feat:` - New feature (triggers minor version bump)
-- `fix:` - Bug fix (triggers patch version bump)
-- `BREAKING CHANGE:` - Breaking change (triggers major version bump)
-- `chore:`, `docs:`, `style:` - No release
+Automated via semantic-release and conventional commits.
 
-**Release Process:**
-1. Commit changes following conventional commit format
-2. Push to `main` branch
-3. GitHub Action automatically:
-   - Analyzes commits and determines version bump
-   - Generates CHANGELOG.md
-   - Creates GitHub release
-   - Publishes to npm
+| Prefix | Effect |
+|--------|--------|
+| `feat:` | Minor version bump |
+| `fix:` | Patch version bump |
+| `BREAKING CHANGE:` | Major version bump |
+| `chore:` `docs:` `style:` | No release |
 
-**Example:**
-```bash
-git commit -m "feat: add new interactive menu option"
-git push origin main
-# Automatic release triggered!
-```
+Push to `main` → GitHub Action bumps version, generates CHANGELOG, publishes to npm.
 
-**Requirements:**
-- `NPM_TOKEN` secret configured in GitHub repository settings
-- Commits must follow conventional commit format
+**Requirements:** `NPM_TOKEN` secret in repository settings.

package/dist/commands/docker.d.ts

@@ -1,4 +1,3 @@
 import type { DockerCommandOptions } from "../types.js";
 export declare function dockerCommand(options: DockerCommandOptions): Promise<void>;
-export declare function runShellDirect(): Promise<void>;
 //# sourceMappingURL=docker.d.ts.map

package/dist/commands/docker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/commands/docker.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAEX,oBAAoB,EAEpB,MAAM,aAAa,CAAC;AAsTrB,wBAAsB,aAAa,CAClC,OAAO,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAEpD"}
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/commands/docker.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAwBxD,wBAAsB,aAAa,CAClC,OAAO,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/commands/maintenance.d.ts

@@ -0,0 +1,5 @@
+export declare function dockerCleanupCommand(): Promise<void>;
+export declare function nixCleanupCommand(): Promise<void>;
+export declare function nixUninstallCommand(): Promise<void>;
+export declare function uninstallCommand(): Promise<void>;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/commands/maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/commands/maintenance.ts"],"names":[],"mappings":"AAkBA,wBAAsB,oBAAoB,kBAwBzC;AAED,wBAAsB,iBAAiB,kBAqBtC;AAED,wBAAsB,mBAAmB,kBAmExC;AAED,wBAAsB,gBAAgB,kBAwBrC"}

package/dist/components/TerminalUI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerminalUI.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/components/TerminalUI.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAwC,MAAM,OAAO,CAAC;AAiJ7D,wBAAgB,UAAU,IAAI,KAAK,CAAC,YAAY,CAoS/C;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}
+{"version":3,"file":"TerminalUI.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/components/TerminalUI.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAwC,MAAM,OAAO,CAAC;AA4I7D,wBAAgB,UAAU,IAAI,KAAK,CAAC,YAAY,CA0N/C;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}