@build-astron-co/nimbus 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -6,95 +6,274 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - 2025-06-15
+---
+
+## [0.4.2] - 2026-03-06
+
+### Added
+
+- **Categorized HelpModal** — `/help` now shows 5 categories (DevOps Commands,
+  Session, Navigation, Settings, Keyboard Shortcuts) with 33+ commands listed,
+  including `/plan`, `/apply`, `/drift`, `/rollback`, `/incident`, `/runbook`,
+  `/plugin`, `/tools`, `/remember`, `/share`, `/deploy`, `/logs`,
+  `/auth-refresh`, `/search`, `/watch`, and more.
+- **Help hint in InputBox** — Placeholder text updated to
+  "Ask me anything DevOps... (? for help, /help for commands)" so new users
+  immediately discover the help system.
+- **Additional slash command completions** — `/deploy`, `/rollback`, `/incident`,
+  `/runbook`, `/plugin`, `/share`, `/status`, `/remember`, `/logs` added to
+  Tab-autocomplete in the InputBox.
+- **Onboarding transition message** — After the setup wizard completes, a clear
+  "Setup complete! Launching Nimbus DevOps Agent..." message is shown before
+  the TUI opens, with keyboard hints (?, Tab, Ctrl+C).
+- **sql.js SQLite fallback** — When `better-sqlite3` native bindings cannot be
+  compiled (ARM Linux, Windows, some CI environments), Nimbus automatically
+  falls back to `sql.js` (pure JavaScript) with full file persistence. No
+  in-memory-only limitation.
+- **Auto-update badge** — Background version check against npm registry; new
+  version available shows `[update: vX.Y.Z] run: nimbus upgrade` in the
+  StatusBar without blocking startup.
+- **Human-readable session names** — Sessions are auto-renamed from the first
+  user message (e.g. "check-failing-pods") instead of showing UUID strings.
+- **Auto-init on fresh session** — When no `NIMBUS.md` exists and infrastructure
+  files are detected (`*.tf`, `Chart.yaml`, etc.), Nimbus auto-generates
+  `NIMBUS.md` silently at session start.
+- **Auto-doctor on first session** — First-ever session checks for missing
+  DevOps CLIs (terraform, kubectl, helm, docker) and surfaces warnings in the
+  TUI as a system message.
+- **OpenCode parity test suite** — `src/__tests__/opencode-parity-v2.test.ts`
+  with 51 assertions covering HelpModal categories, InputBox hints, onboarding
+  transition, doctor --fix wiring, and welcome-screen infra context.
+
+### Fixed
+
+- Removed stale `"prepare"` script from `package.json` — `tsc` no longer runs
+  on `npm install`, eliminating the 5–15 second delay for global installs.
+- `compat-sqlite.test.ts` updated to check for `persist` instead of `in-memory`
+  (sql.js fallback now writes to disk, not memory-only).
+- `devops-terminal-gaps.test.ts` placeholder assertion updated to match the new
+  DevOps-focused placeholder text.
+
+---
+
+## [0.4.1] - 2026-02-28
+
+### Added
+
+- **Full 29-gap DevOps fix plan** — All gaps from the C1–C4, H1–H7, M1–M10,
+  L1–L8 plan implemented (1408 → 1484 tests):
+  - **C1** — Per-tool Ctrl+C: cancels the running tool only; agent loop
+    continues with a synthetic "cancelled" result. Press Ctrl+C again to abort
+    the session.
+  - **C2** — Ansible tool with 10 actions: `playbook`, `syntax-check`,
+    `dry-run`, `inventory-list`, `vault-encrypt`, `vault-decrypt`, `vault-view`,
+    `galaxy-install`, `galaxy-search`, `facts`.
+  - **C3** — Terraform workspace auto-applied across turns: session workspace
+    stored in `ToolExecuteContext.infraContext.terraformWorkspace`; each
+    stateful terraform action auto-selects the session workspace.
+  - **C4** — ArgoCD/Flux GitOps `watch` action: streams
+    `kubectl get applications --watch` via `spawnExec` with `onChunk`.
+  - **H1** — Inline diff approval: `edit_file`/`multi_edit` in build/deploy
+    mode triggers a diff preview modal; user approves or rejects before the
+    write applies.
+  - **H2** — Async context compaction: `runCompaction()` fires in the
+    background; the result is awaited at the start of the next turn, shifting
+    the 1–2s wait to the user's thinking pause.
+  - **H3** — kubectl `events` and `watch` actions with streaming output.
+  - **H4** — `policy_check` tool: runs Checkov, tfsec, Trivy-config, Conftest,
+    or Kyverno; groups violations by severity; `auto_allow` permission tier.
+  - **H5** — `rollout_control` tool: Argo Rollouts and Flagger support
+    (status, promote, abort, pause, resume, set-weight, analyze).
+  - **H6** — Extended `secrets` tool: HashiCorp Vault (`vault-read`,
+    `vault-write`, `vault-rotate`, `vault-lease-renew`, `vault-list`) and
+    AWS Secrets Manager (`aws-get-secret`, `aws-put-secret`, `aws-rotate-secret`,
+    `aws-list-secrets`). Secret values masked as `[REDACTED]` in output.
+  - **H7** — Runbook step-by-step progress: `[STEP_START:N]` /
+    `[STEP_COMPLETE:N]` sentinels parsed from the agent stream; current step
+    shown in StatusBar.
+  - **M1** — Docker `scan` action: runs `trivy image` or `trivy fs`, groups
+    results by severity (CRITICAL/HIGH/MEDIUM/LOW).
+  - **M3** — `db_migrate` tool: Flyway, Liquibase, golang-migrate, Sqitch
+    (info/migrate/rollback/validate/clean/baseline). `always_ask` permission.
+  - **M5** — Pre-apply cost alert: after `terraform plan`, estimates monthly
+    cost delta; warns if > $100/month before proceeding.
+  - **M6** — Terraform plan truncation threshold increased to 1500 lines with
+    smarter summary (first 30 + resource list + last 20 lines).
+  - **M7** — `env_diff` tool: compares terraform workspaces, K8s namespaces,
+    or Helm releases side-by-side.
+  - **M9** — Doctor platform-aware install instructions: `brew install` on
+    macOS, `apt-get` / `dnf` on Linux with distro detection.
+  - **M10** — `notify` tool: Slack, PagerDuty, Microsoft Teams, or generic
+    webhook. Auto-fires after successful terraform apply if `## Notifications`
+    in NIMBUS.md has `slack_webhook:`.
+  - **L1** — README Bun binary mention corrected.
+  - **L3** — `/watch` defaults to DevOps files (`*.tf`, `*.yaml`, `*.yml`,
+    `Dockerfile`).
+  - **L4** — NIMBUS.md validation on load: checks for unclosed code fences,
+    invalid headers, and size > 50KB.
+  - **L5** — Live session sharing: `/ws/share/:id` WebSocket endpoint; all
+    connected viewers receive new messages in real time.
+  - **L7** — `nimbus status --watch`: refreshes every 30s, clears terminal with
+    ANSI escape.
+  - **L8** — Terraform module registry browser: `terraform_registry` tool with
+    `search` and `show` actions against the Terraform Registry API.
+
+---
+
+## [0.4.0] - 2026-02-10
 
 ### Added
 
-#### Core Platform
-
-- Microservices architecture with 18 services running on Bun runtime
-- Core Engine Service with task management, plan generation, and execution
-- LLM Service with multi-provider support (Anthropic, Google, Ollama)
-- Generator Service for IaC code generation with questionnaire-driven workflows
-- State Service for configuration, history, conversations, artifacts, and
-  templates
-- WebSocket support for real-time streaming on core engine, LLM, and generator
-  services
-
-#### CLI
-
-- Interactive AI chat with syntax-highlighted code output
-- Terraform commands: plan, apply, destroy, import, validate, fmt, state
-  management
-- Kubernetes commands: get, apply, delete, logs, exec, scale, rollout,
-  port-forward
-- Helm commands: install, upgrade, uninstall, list, rollback, template, lint
-- Git commands: status, clone, add, commit, push, pull, branch, merge, tag
-- File system commands: read, write, search, tree, diff, copy, move
-- GitHub integration: PRs, issues, releases, Actions workflows
-- AI-driven Terraform generation with conversational and questionnaire modes
-- Infrastructure cost estimation for Terraform plans
-- Doctor command for dependency verification
-- Login/logout with device code flow authentication
-- Telemetry integration (opt-in) via PostHog
-
-#### Cloud Provider Support
-
-- AWS Tools Service: infrastructure discovery across 10+ services, Terraform
-  generation
-- GCP Tools Service: Compute Engine, Cloud Storage, GKE, IAM, Cloud Functions,
-  VPC operations
-- Azure Tools Service: VMs, Storage, AKS, IAM, Functions, Virtual Network
-  operations
-- Infrastructure discovery with real-time progress streaming for all three
-  providers
-- Terraform code generation from discovered cloud resources
-
-#### DevOps Tools
-
-- Git Tools Service for local repository operations via simple-git
-- GitHub Tools Service for GitHub API operations via Octokit (PRs, issues,
-  Actions, releases)
-- Terraform Tools Service for full Terraform CLI lifecycle management
-- Kubernetes Tools Service for kubectl operations and cluster management
-- Helm Tools Service for chart and release lifecycle management
-- File System Tools Service with sensitive file protection
-
-#### Team and Enterprise
-
-- Auth Service with device code flow and token validation
-- Team Service with CRUD operations, member invitations, and role management
-- Billing Service with Stripe integration, subscriptions, and usage tracking
-- Audit Service with compliance logging, filterable queries, and CSV/JSON export
-- RBAC-based access control for team operations
-
-### Security
-
-- Service-to-service authentication middleware across all services
-- Rate limiting on all HTTP endpoints (configurable per service)
-- Sensitive file protection in file system operations
-- Input validation and sanitization on all API routes
-- Stripe webhook signature verification
-- Credential encryption for stored cloud provider credentials
-- No credentials logged or persisted in plain text
-
-### Infrastructure
-
-- Bun monorepo with workspace-based dependency management
-- Docker Compose configuration for local development
-- Dockerfiles for all services including GCP and Azure tools
-- CI/CD pipeline via GitHub Actions with type checking, linting, and tests
-- Health check endpoints on every service
-- Shared packages: clients, types, and utils across all services
-
-### Developer Experience
-
-- Swagger UI documentation on all tool services (`/swagger`)
-- OpenAPI 3.0 specs served at `/api/openapi.json` on each service
-- README documentation for every service
-- Distributed tracing support via shared tracing utility
-- Event bus for inter-service communication
-- Shared REST client with service discovery
-- Consistent error response format across all services
-  (`{ success, data/error }`)
-- Start-all script for launching the full platform locally
+- **Full OpenCode parity** — 30 DevOps UX gaps resolved; Nimbus now matches
+  OpenCode's terminal experience end-to-end, specialized for DevOps.
+- **Ctrl+C per-tool cancel** — Cancels the running subprocess only (not the
+  whole TUI). Agent loop continues. Press Ctrl+C again to exit.
+- **Scroll lock** — Message list pins to bottom while the agent is responding;
+  Up/Down arrows unlock scroll. `G` snaps back to the bottom.
+- **Streaming tool output window** — `ToolCallDisplay` shows the last 10 lines
+  of live output while a tool is running, with elapsed timer and a `LIVE`
+  indicator for log-streaming tools.
+- **Mode persistence** — Active mode (plan/build/deploy) is saved per working
+  directory to `~/.nimbus/mode-config.json` and restored on next session.
+- **Conversation search** — `/search <query>` filters the message list in real
+  time; result count shown in StatusBar.
+- **Per-turn token/cost stats** — After each LLM response, a compact
+  `[N in / N out — $X.XXXX]` line is emitted so you can track spend per turn.
+- **API-key setup banner** — If no LLM key is configured, a dismissable banner
+  explains how to set up credentials. Auto-dismisses after 8 seconds or on
+  first message.
+- **Auto-show TerminalPane** — For long-running DevOps tools (terraform, helm,
+  kubectl, docker), the terminal output pane opens automatically and closes 2
+  seconds after the tool completes.
+- **Shell completion auto-install** — `nimbus completions install` detects the
+  shell (bash/zsh/fish) and writes the completion script to the right location.
+- **Config profiles** — `nimbus profile <name>` loads a named config set
+  (model, mode, tool permissions) from `~/.nimbus/profiles/`.
+- **Session infra context** — Each session stores its Terraform workspace and
+  kubectl context in SQLite; infra context is restored on session resume and
+  shown in the Header.
+- **Token usage warning** — At 70% context window usage, a yellow warning
+  appears: "Context at 70% — consider /compact".
+
+### Changed
+
+- Empty state simplified: instead of generic tips, shows "Starting Nimbus..."
+  while the agent initializes.
+- Copy-to-clipboard (`pbcopy`/`xclip`/`clip`) available from MessageList code
+  blocks; success shown as a toast in StatusBar.
+- Deploy mode confirmation: Tab to deploy now shows a "Switch to DEPLOY mode?
+  [y/N]" prompt instead of switching immediately.
+
+---
+
+## [0.3.0] - 2026-01-20
+
+### Added
+
+- **Terminal Gap Fix Plan v2** — C1–C6, H1–H5, M1–M3, L1–L2 (1259 tests):
+  - Multi-cluster context display in Header with environment color coding.
+  - LSP diagnostics surfaced inline (TypeScript, Go, Python, HCL, YAML, Docker).
+  - Smarter context compaction: haiku model for summarization, preserves tool
+    state and last 5 messages.
+  - `nimbus rollout` command for canary/progressive delivery (Argo Rollouts).
+  - JSON output for `nimbus run --format json` includes `planSummary` field.
+  - Custom error hints for terraform/kubectl/helm/cloud errors (20+ patterns).
+  - FileDiffModal for inline diff approval before file edits apply.
+  - Compaction runs async (non-blocking) — result awaited at next turn start.
+
+- **Standalone Binary Migration** — C1–C8, H1–H3, M1–M3, L1 (1293 tests):
+  - Migrated from Bun to Node.js + npm for the npm distribution path.
+  - Tests use vitest@2 (`npm test`) instead of `bun:test`.
+  - `tsconfig.json` uses `moduleResolution: "bundler"` and `types: ["node"]`.
+  - `Timer` global replaced with `ReturnType<typeof setTimeout>` in 3 files.
+  - BrowserOAuthServer uses `node:http` instead of `Bun.serve()`.
+  - `better-sqlite3` as primary SQLite backend (native Node.js bindings).
+
+---
+
+## [0.2.0] - 2025-12-15
+
+### Added
+
+- **DevOps Identity Gap Fix** — Help/onboarding/header/welcome overhaul (1342
+  tests):
+  - Header shows terraform workspace and kubectl context with [PROD] warnings.
+  - Welcome screen shows detected infra context (tf/k8s/aws/gcp) with
+    context-aware suggestions.
+  - Onboarding wizard (11 providers): Anthropic, OpenAI, Google, Bedrock, Azure
+    OpenAI, Ollama, Groq, DeepSeek, OpenRouter, Together AI, Fireworks AI.
+  - Infrastructure auto-detection in onboarding (Terraform, K8s, Helm, Docker).
+  - `nimbus doctor` replaces stale localhost port checks with: SQLite DB check,
+    LLM auth check, DevOps CLI version checks (terraform, kubectl, helm, aws,
+    gcloud, az).
+
+- **DevOps Terminal Gap Fix** — C1–C3, H1–H5, M1–M5, L1–L3 (1328 tests):
+  - Logs tool with streaming via `spawnExec` + `onChunk`; StatusBar shows
+    "Esc:stop stream".
+  - Infra context (`SessionInfraContext`) stored per session in SQLite; wired
+    into `ToolExecuteContext` so tools receive live workspace/context.
+  - Terraform plan smart truncation (500 → 1500 lines) with summary line.
+  - ToolCallDisplay LIVE indicator for streaming tools.
+  - Parallel cloud discovery for AWS/GCP/Azure in `cloud_discover`.
+  - Compaction preserves `infraContext` across sessions.
+  - `generate_infra` tool for natural-language infrastructure generation.
+  - Docker build progress display in `ToolCallDisplay`.
+  - `nimbus rollout` command.
+  - `planSummary` field in `nimbus run --format json` output.
+  - Custom DevOps error hints injected into tool results.
+
+- **DevOps Polish Plan** — H1–H5, M1–M7, L1–L5 (1384 tests):
+  - `TerminalPane` and `TreePane` side panels toggled by `/terminal` and `/tree`.
+  - MCP plugin manager (`nimbus plugin install/uninstall/list`).
+  - Team-context NIMBUS.md sharing (`nimbus team-context`).
+  - NIMBUS.md diff shown on `nimbus init` re-run.
+  - Session cost/token summary on session close.
+
+---
+
+## [0.1.0] - 2025-10-01
+
+### Added
+
+- **5-Phase transformation complete** — 18 microservices consolidated into a
+  single embedded binary.
+- **Phase 1** — Core infrastructure: entry point, CLI router, app lifecycle,
+  LLM router (7 providers), tool schemas, SQLite state (16 tables), enterprise
+  layer. 188 tests, ~62 MB binary.
+- **Phase 2** — Tool system: Zod-based tool schemas, `ToolRegistry`, 4-tier
+  permission engine, MCP client (JSON-RPC over stdio/HTTP), subagent system,
+  agent loop with streaming. 173 new tests (361 total).
+- **Phase 3** — TUI: Ink v6 + React 19, 8 components (App, Header,
+  MessageList, ToolCallDisplay, InputBox, StatusBar, PermissionPrompt,
+  DeployPreview). Three-mode system (plan/build/deploy). Hooks (YAML config),
+  snapshots (git write-tree), audit (14 security rules, 25 compliance
+  controls). `nimbus init` with 6-language + 5-infra + 3-cloud detection.
+  177 new tests (538 total).
+- **Phase 4** — Distribution: npm packaging, Homebrew tap, shell script
+  installer, pre-built binaries for macOS/Linux/Windows, GitHub Actions CI.
+- **Phase 5** — Production features: LSP (6 languages, lazy-loaded), context
+  manager (auto-compact at 85%), session manager (SQLite-backed, conflict
+  detection), HTTP API server (Elysia, SSE streaming), session sharing
+  (URL-safe IDs, 30-day TTL), web UI integration. 109 new tests (647 total).
+- **DevOps Gaps v1** — 21 gaps resolved: DEVOPS_DOMAIN_KNOWLEDGE in system
+  prompt, terraform destroy guard, real DevOps CLI checks in doctor, infra
+  context discovery, terraform plan analyzer, DevOps error classification,
+  session infra context, auth-refresh command, kubectl_context tool,
+  helm_values tool, TerraformPlanCache, cloud_discover structured output,
+  stdin piping, DevOps-only file watcher, workspace-aware system prompt.
+- **DevOps Gaps v2** — 29 more gaps resolved: docker tool, secrets tool (helm-
+  secrets), cicd tool, auth keychain, monitor tool, gitops tool, syntax
+  highlighting (YAML/JSON/Bash/SQL/Dockerfile), elapsed timer in
+  ToolCallDisplay, 70% context warning, TerminalPane, cloudActionTool,
+  logsTool, certsTool, meshTool, cfnTool, k8sRbacTool, NIMBUS.md live reload,
+  TreePane sidebar, plugin manager, team-context, shell completions, session
+  cost summary, enhanced doctor.
+
+### Architecture
+
+- Runtime: Node.js >= 18 (npm distribution) with Bun support for compiled
+  binaries.
+- Single-process design: no HTTP microservices, no Docker required.
+- SQLite with WAL mode at `~/.nimbus/nimbus.db`.
+- Streaming-first: LLM responses and tool output stream token-by-token.
+- 4-tier permission engine: auto_allow → ask_once → always_ask → blocked.

package/README.md

@@ -6,605 +6,64 @@
 [![CI](https://github.com/the-ai-project-co/nimbus/actions/workflows/ci.yml/badge.svg)](https://github.com/the-ai-project-co/nimbus/actions)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-brightgreen.svg)](https://nodejs.org/)
-[![Tests](https://img.shields.io/badge/tests-1408%20passing-brightgreen.svg)](https://github.com/the-ai-project-co/nimbus/actions)
+[![Tests](https://img.shields.io/badge/tests-1529%20passing-brightgreen.svg)](https://github.com/the-ai-project-co/nimbus/actions)
 
-> AI-powered cloud engineering agent for your terminal
+> AI-powered DevOps terminal agent — type `nimbus`, get a live infrastructure operator
 
-Nimbus is an intelligent command-line agent that brings the power of large
-language models to DevOps and cloud engineering workflows. Think of it as an AI
-pair-programmer that understands Terraform, Kubernetes, Helm, and cloud
-providers natively. It ships as a single self-contained binary with an
-interactive terminal UI, 20 built-in tools, support for 11+ LLM providers, and a
-three-mode safety system that separates reading, building, and deploying.
+Nimbus is an intelligent command-line agent purpose-built for DevOps and cloud engineering. Type `nimbus`, describe what you want, and Nimbus plans, validates, and executes across Terraform, Kubernetes, Helm, AWS, GCP, and Azure — all from a single terminal session.
 
 ---
 
-## Table of Contents
-
-- [Features](#features)
-- [Quick Start](#quick-start)
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-- [Commands](#commands)
-- [Modes](#modes)
-- [LLM Providers](#llm-providers)
-- [MCP Support](#mcp-support)
-- [Project Configuration (NIMBUS.md)](#project-configuration-nimbusmd)
-- [Keyboard Shortcuts (TUI)](#keyboard-shortcuts-tui)
-- [Development](#development)
-- [Architecture](#architecture)
-- [License](#license)
-
----
-
-## Features
-
-- **Interactive TUI** -- Rich terminal interface built with Ink and React,
-  featuring syntax highlighting, markdown rendering, code blocks, and a status
-  bar with mode indicators.
-- **20 Built-in Tools** -- File operations (read, write, edit, glob, grep), git,
-  bash, terraform, kubectl, helm, AWS/GCP/Azure cloud discovery, web search,
-  cost estimation, drift detection, deploy preview, and subagent task spawning.
-- **11+ LLM Providers** -- Anthropic, OpenAI, Google, AWS Bedrock, Azure OpenAI,
-  Ollama, Groq, DeepSeek, OpenRouter, Together AI, Fireworks AI, and Perplexity.
-  Any OpenAI-compatible endpoint can be added.
-- **Three Modes** -- Plan (read-only), Build (edit/create), and Deploy (full
-  infra access). Each mode progressively expands tool availability and resets
-  permissions on switch.
-- **Session Persistence** -- Conversations are stored in SQLite and can be
-  resumed, branched, or shared. Multi-session support with file conflict
-  detection.
-- **MCP Server Support** -- Connect to Model Context Protocol servers to extend
-  Nimbus with external tools via JSON-RPC over stdio or HTTP.
-- **Subagent System** -- Spawn parallel sub-tasks (explore, infra, security,
-  cost, general) with isolated context and independent model selection.
-- **Context Management** -- Auto-compaction at 85% context window usage.
-  Preserves first message, last 5 messages, summaries, and active tool state.
-- **Snapshot / Undo / Redo** -- Uses `git write-tree` for git projects (or
-  filesystem copy for non-git) to checkpoint and roll back changes.
-- **Infrastructure Generation** -- Generate Terraform configurations, Kubernetes
-  manifests, and Helm charts from natural language descriptions with
-  best-practice templates.
-- **Cost Estimation and Drift Detection** -- Estimate infrastructure costs
-  before deploying and detect configuration drift across your environments.
-- **Enterprise Features** -- Teams, billing, audit logs, usage tracking,
-  security scanning, and compliance checking (SOC2, HIPAA, PCI-DSS, GDPR, ISO
-  27001).
-- **Web UI** -- Browser-based interface via `nimbus web`, backed by an Elysia
-  HTTP API with SSE streaming.
-- **Human-in-the-Loop Safety** -- 4-tier permission engine (auto_allow,
-  ask_once, always_ask, blocked) with action-specific escalation for destructive
-  operations.
-
----
-
-## Quick Start
-
-```bash
-# Install
-npm install -g @build-astron-co/nimbus
-# or via Homebrew
-brew tap the-ai-project-co/tap
-brew install nimbus
-
-# Set up authentication
-nimbus login
-
-# Start the interactive AI agent
-nimbus
-```
-
-On first run, Nimbus launches an onboarding flow that walks you through provider
-selection and API key configuration. After that, running `nimbus` drops you into
-the interactive chat.
-
----
-
-## Installation
-
-### npm (recommended)
+## Install
 
 ```bash
+# npm
 npm install -g @build-astron-co/nimbus
-```
 
-Works with Node.js >= 18. Uses `better-sqlite3` as the SQLite backend.
-
-### Homebrew (macOS / Linux)
-
-```bash
+# Homebrew (use the fully-qualified tap name to avoid name conflicts)
 brew tap the-ai-project-co/tap
-brew install nimbus
-```
-
-### Shell script (auto-detects best method)
+brew install the-ai-project-co/tap/nimbus
 
-```bash
+# Shell script (auto-detects best method)
 curl -fsSL https://raw.githubusercontent.com/the-ai-project-co/nimbus/main/scripts/install.sh | bash
 ```
 
-### Compiled binary (direct download)
-
-Pre-built standalone binaries for macOS, Linux, and Windows are available on the
-[GitHub Releases](https://github.com/the-ai-project-co/nimbus/releases) page.
-Standalone binaries bundle the Bun runtime (~68 MB), so no extra dependencies
-are needed.
-
-> Note: compiled binaries use the readline chat interface. Install via Bun or
-> npm for the full Ink TUI.
-
----
-
-## Getting Started
-
-### First run / onboarding
-
-```bash
-nimbus
-```
-
-The first time you run Nimbus, it launches an interactive onboarding that helps
-you select an LLM provider and configure your API key. Credentials are stored in
-`~/.nimbus/auth.json`.
-
-### Setting up providers
-
-You can configure providers through onboarding or by setting environment
-variables directly:
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-```
-
-Or log in interactively:
-
-```bash
-nimbus login
-```
-
-### Initialize a project
-
-```bash
-nimbus init
-```
-
-This detects your project type (TypeScript, Go, Python, Rust, Java, JavaScript),
-infrastructure tooling (Terraform, Kubernetes, Helm, Docker, CI/CD), and cloud
-providers (AWS, GCP, Azure), then generates a `NIMBUS.md` file with project
-context that Nimbus uses to tailor its responses.
-
-### Interactive chat
-
-```bash
-nimbus chat
-```
-
-Or just `nimbus` -- it launches the Ink TUI with the full agent loop, tool
-execution, and streaming responses.
-
-### Non-interactive mode
-
-```bash
-nimbus run "Create a Terraform module for an S3 bucket with versioning and encryption"
-nimbus run "Fix the failing test in src/__tests__/router.test.ts" --auto-approve
-nimbus run "Explain the architecture of this project" --format json
-```
-
-### One-off questions
-
-```bash
-nimbus ask "How do I set up an S3 bucket with versioning?"
-```
-
-### Check your environment
-
-```bash
-nimbus doctor
-```
-
-Verifies that required tools (git, terraform, kubectl, helm, cloud CLIs) are
-available and that provider credentials are configured.
-
----
-
-## Commands
-
-### Chat and AI
-
-| Command                 | Description                               |
-| ----------------------- | ----------------------------------------- |
-| `nimbus`                | Launch interactive chat (default)         |
-| `nimbus chat`           | Interactive AI chat session               |
-| `nimbus run "prompt"`   | Non-interactive mode with a single prompt |
-| `nimbus ask "question"` | Ask a one-off question                    |
-| `nimbus explain <file>` | Explain a file or code snippet            |
-| `nimbus fix <file>`     | Analyze and fix issues in a file          |
-| `nimbus analyze`        | Analyze the current project               |
-
-### Configuration
-
-| Command          | Description                                            |
-| ---------------- | ------------------------------------------------------ |
-| `nimbus init`    | Initialize a project (detect type, generate NIMBUS.md) |
-| `nimbus config`  | View or set configuration                              |
-| `nimbus login`   | Authenticate with an LLM provider                      |
-| `nimbus logout`  | Remove stored credentials                              |
-| `nimbus auth`    | Manage authentication                                  |
-| `nimbus doctor`  | Check environment and provider status                  |
-| `nimbus upgrade` | Self-update to the latest version                      |
-
-### Infrastructure Generation
-
-| Command                     | Description                                             |
-| --------------------------- | ------------------------------------------------------- |
-| `nimbus generate terraform` | Generate Terraform configurations from natural language |
-| `nimbus generate k8s`       | Generate Kubernetes manifests                           |
-| `nimbus generate helm`      | Generate Helm charts                                    |
-
-### Cloud Providers
-
-| Command                  | Description                            |
-| ------------------------ | -------------------------------------- |
-| `nimbus aws <service>`   | AWS operations (S3, EC2, Lambda, etc.) |
-| `nimbus gcp <service>`   | Google Cloud operations                |
-| `nimbus azure <service>` | Azure operations                       |
-
-### Infrastructure Management
-
-| Command                                               | Description                            |
-| ----------------------------------------------------- | -------------------------------------- |
-| `nimbus tf init/plan/apply/validate/destroy/fmt`      | Terraform operations                   |
-| `nimbus k8s get/apply/delete/logs/scale/exec`         | Kubernetes operations                  |
-| `nimbus helm list/install/upgrade/uninstall/rollback` | Helm operations                        |
-| `nimbus cost estimate/history`                        | Cost estimation and tracking           |
-| `nimbus drift detect/fix`                             | Configuration drift detection          |
-| `nimbus preview`                                      | Deploy preview (blast radius analysis) |
-
-### Git and Files
-
-| Command                                         | Description            |
-| ----------------------------------------------- | ---------------------- |
-| `nimbus git status/add/commit/push/merge/stash` | Git operations         |
-| `nimbus fs read/write/list/search`              | File system operations |
-
-### GitHub
-
-| Command                                  | Description             |
-| ---------------------------------------- | ----------------------- |
-| `nimbus gh pr list/create/view/merge`    | Pull request operations |
-| `nimbus gh issue list/create/view/close` | Issue operations        |
-| `nimbus gh repo view/clone`              | Repository operations   |
-
-### Enterprise
-
-| Command          | Description                         |
-| ---------------- | ----------------------------------- |
-| `nimbus team`    | Team management                     |
-| `nimbus billing` | Billing and subscription management |
-| `nimbus usage`   | Usage statistics and token tracking |
-| `nimbus audit`   | Audit logs and compliance reports   |
-
-### Server
-
-| Command        | Description                                        |
-| -------------- | -------------------------------------------------- |
-| `nimbus serve` | Start the HTTP API server (Elysia, SSE streaming)  |
-| `nimbus web`   | Start the API server and open the browser-based UI |
-
-### Utilities
-
-| Command                 | Description                         |
-| ----------------------- | ----------------------------------- |
-| `nimbus version`        | Print version and build date        |
-| `nimbus help`           | Show help for all commands          |
-| `nimbus help <command>` | Show help for a specific command    |
-| `nimbus doctor`         | Verify environment and dependencies |
-| `nimbus upgrade`        | Update Nimbus to the latest version |
-
-Run `nimbus help` for the full command list, or `nimbus help <command>` for
-details on any command.
-
----
-
-## Modes
-
-Nimbus uses a three-mode system that controls which tools are available,
-enforcing a progressive trust model. Switching modes resets the permission
-session so that previously approved tools require re-approval.
-
-### Plan mode
-
-Read-only exploration and analysis. The agent can read files, search codebases,
-estimate costs, detect drift, and propose changes -- but it cannot modify
-anything.
-
-**Available tools:** `read_file`, `glob`, `grep`, `list_dir`, `webfetch`,
-`cost_estimate`, `drift_detect`, `todo_read`, `todo_write`, `cloud_discover`
-
-### Build mode (default)
-
-Everything in Plan, plus file editing, shell access, git operations, and
-non-destructive DevOps commands. The agent can generate Terraform configs, write
-Kubernetes manifests, and validate them, but it cannot apply changes to live
-infrastructure.
-
-**Additional tools:** `edit_file`, `multi_edit`, `write_file`, `bash`, `git`,
-`task`, `deploy_preview`, `terraform` (validate/fmt/plan only), `kubectl`
-(get/describe only), `helm` (list/status/template only)
-
-### Deploy mode
-
-Full access to all 20 tools, including infrastructure-mutating operations.
-Destructive actions still go through the permission engine and require explicit
-user approval.
-
-**Additional tools:** All terraform subcommands (apply, destroy), all kubectl
-subcommands (apply, delete), all helm subcommands (install, upgrade, uninstall)
-
-Switch modes in the TUI by pressing **Tab**, or use the `/mode` slash command.
-
----
-
-## LLM Providers
-
-Nimbus routes requests through an intelligent LLM router with automatic
-fallback, cost optimization, circuit breaking, and retry with exponential
-backoff.
-
-| Provider     | Environment Variable(s)        | Notes                                                  |
-| ------------ | ------------------------------ | ------------------------------------------------------ |
-| Anthropic    | `ANTHROPIC_API_KEY`            | Claude models (Sonnet, Opus, Haiku). Default provider. |
-| OpenAI       | `OPENAI_API_KEY`               | GPT-4o, GPT-4, GPT-3.5                                 |
-| Google       | `GOOGLE_API_KEY`               | Gemini models                                          |
-| AWS Bedrock  | `AWS_REGION` + IAM credentials | Claude, Llama, and others via AWS                      |
-| Ollama       | `OLLAMA_BASE_URL` (optional)   | Local models, no API key needed                        |
-| Groq         | `GROQ_API_KEY`                 | Fast inference (Llama, Mixtral)                        |
-| DeepSeek     | `DEEPSEEK_API_KEY`             | DeepSeek models                                        |
-| OpenRouter   | `OPENROUTER_API_KEY`           | Multi-model proxy, access 100+ models                  |
-| Together AI  | `TOGETHER_API_KEY`             | Llama, Mixtral, and more                               |
-| Fireworks AI | `FIREWORKS_API_KEY`            | Fast open-source model inference                       |
-| Perplexity   | `PERPLEXITY_API_KEY`           | Online search-augmented models                         |
-
-Any OpenAI-compatible endpoint can be added via the `OpenAICompatibleProvider`
-class.
-
-You can also configure providers through `nimbus login`, which stores
-credentials in `~/.nimbus/auth.json`. The router checks `auth.json` first, then
-falls back to environment variables.
-
-### Model aliases
-
-Nimbus supports short aliases for common models:
-
-```bash
-nimbus chat --model sonnet    # resolves to claude-sonnet-4-20250514
-nimbus chat --model opus      # resolves to claude-opus-4-20250514
-nimbus chat --model gpt4o     # resolves to gpt-4o
-nimbus chat --model gemini    # resolves to gemini-pro
-```
-
-### Cost optimization
-
-When enabled (`ENABLE_COST_OPTIMIZATION=true`), the router automatically selects
-cheaper models for simple tasks (summarization, classification) and more capable
-models for complex tasks (code generation, planning).
-
----
-
-## MCP Support
-
-Nimbus supports the [Model Context Protocol](https://modelcontextprotocol.io/)
-for extending the agent with external tools. Configure MCP servers in
-`.nimbus/mcp.json` (project-level) or `~/.nimbus/mcp.json` (global):
-
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
-    },
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
-      }
-    },
-    "remote-server": {
-      "type": "http",
-      "url": "https://mcp.example.com",
-      "token": "your-auth-token"
-    }
-  }
-}
-```
-
-MCP servers are discovered from three locations, searched in order:
-
-1. `.nimbus/mcp.json` (project directory)
-2. `nimbus.json` (project directory)
-3. `~/.nimbus/mcp.json` (global)
-
-Servers support two transport modes: **command** (JSON-RPC over stdio) and
-**http** (JSON-RPC over HTTP). Tools from connected servers are automatically
-registered into the Nimbus tool registry and become available to the agent.
-
----
-
-## Project Configuration (NIMBUS.md)
-
-Running `nimbus init` in your project directory generates a `NIMBUS.md` file
-that provides project-specific context to the AI agent. Nimbus auto-detects:
-
-- **Project type** -- TypeScript, JavaScript, Go, Python, Rust, Java
-- **Infrastructure tools** -- Terraform, Kubernetes, Helm, Docker, CI/CD
-  pipelines
-- **Cloud providers** -- AWS, GCP, Azure (from config files and Terraform
-  providers)
-- **Package manager** -- npm, yarn, pnpm, bun
-- **Test framework** -- jest, vitest, mocha, pytest, go test, cargo test
-- **Git repository status**
-
-The generated `NIMBUS.md` file is included in the system prompt so the agent
-understands your project's technology stack, conventions, and infrastructure
-setup.
-
-```bash
-nimbus init              # auto-detect and generate
-nimbus init --force      # overwrite existing NIMBUS.md
-nimbus init --quiet      # suppress console output
-```
-
----
-
-## Keyboard Shortcuts (TUI)
-
-| Shortcut      | Action                                        |
-| ------------- | --------------------------------------------- |
-| **Tab**       | Cycle modes (Plan -> Build -> Deploy -> Plan) |
-| **Ctrl+C**    | Interrupt current operation or exit           |
-| **Escape**    | Cancel current operation                      |
-| **Up / Down** | Browse input history                          |
-| **Enter**     | Send message                                  |
-| `/mode`       | Switch mode via slash command                 |
-| `/clear`      | Clear the conversation                        |
-| `/compact`    | Manually trigger context compaction           |
-| `/help`       | Show available slash commands                 |
+Pre-built standalone binaries (~68 MB, no Node.js required) are on the [Releases](https://github.com/the-ai-project-co/nimbus/releases) page.
 
 ---
 
-## Development
-
-### Prerequisites
-
-- Node.js >= 18
-- Git
-
-### Setup
-
-```bash
-git clone https://github.com/the-ai-project-co/nimbus.git
-cd nimbus
-npm install
-```
-
-### Run from source
-
-```bash
-# Run directly
-npm run nimbus
-
-# Run with arguments
-npm run nimbus -- --help
-npm run nimbus -- chat
-npm run nimbus -- ask "explain this project"
-```
-
-### Test
+## Quick Start
 
 ```bash
-# Run all tests (1408 tests)
-npm test
-
-# Run with coverage
-npm run test:coverage
-
-# Watch mode
-npm run test:watch
+nimbus              # launches onboarding on first run, TUI on subsequent runs
 ```
 
-### Lint and format
+1. **First run** — onboarding wizard walks you through provider + API key setup
+2. **Initialize your project** — `nimbus init` detects your stack and generates `NIMBUS.md`
+3. **Start asking** — describe what you want in natural language
 
-```bash
-npm run lint
-npm run format
-npm run type-check
 ```
-
-### Build
-
-```bash
-# Build standalone binary for current platform
-./scripts/build-binary.sh
-
-# Or
-npm run build
+"Run terraform plan and show me what will change"
+"Check for pod restarts in the production namespace"
+"Is there any infrastructure drift in my staging workspace?"
 ```
 
-The binary is output to `dist/nimbus` (~68 MB, bundles the Bun runtime).
+If `ANTHROPIC_API_KEY` (or any [supported provider key](docs/guides/configuration.md#llm-providers)) is already set, onboarding is skipped and you go straight to the agent.
 
 ---
 
-## Architecture
-
-Nimbus runs on Node.js >= 18 (with optional Bun support for compiled binaries).
-All functionality runs in-process -- there are no HTTP microservices, no Docker
-containers, and no external orchestrators. The entire application is a single
-TypeScript process that manages LLM routing, tool execution, state persistence,
-and the TUI.
+## Learn More
 
-```
-src/
-  nimbus.ts          Entry point (shebang: #!/usr/bin/env node via tsx)
-  cli.ts             CLI command router
-  app.ts             App lifecycle (lazy DB + LLM router init)
-  version.ts         Version and build date constants
-
-  agent/             Agent loop, system prompt, permissions, modes, subagents
-  llm/               LLM router, 11+ providers, model aliases, cost calculator
-  tools/             Tool implementations and schemas (11 standard + 9 DevOps)
-  state/             SQLite WAL database (16 tables at ~/.nimbus/nimbus.db)
-  ui/                Ink/React TUI components (8 components)
-  commands/          CLI command implementations
-
-  engine/            Planner, executor, orchestrator, verifier, safety, drift, cost
-  generator/         Terraform, Kubernetes, Helm generators with best practices
-  enterprise/        Auth, teams, billing, audit
-  auth/              Authentication (OAuth, SSO, credential store)
-  hooks/             Pre/post tool-use hooks (YAML config)
-  snapshots/         Git write-tree undo/redo
-  audit/             Security scanner, compliance checker, cost tracker, activity log
-  lsp/               Language server protocol (6 languages: TS, Go, Python, HCL, YAML, Docker)
-  sessions/          Multi-session management with conflict detection
-  sharing/           Session sharing (URL-safe IDs, 30-day TTL)
-  mcp/               MCP client (JSON-RPC over stdio/HTTP)
-  cli/               Non-interactive run, serve, web, init commands
-  compat/            Runtime compatibility layer (Bun / Node.js)
-  context/           Context database for long-term memory
-  watcher/           Filesystem watcher for live file tracking
-
-  build.ts           Binary build script
-  __tests__/         1408 tests
-```
-
-### Key design decisions
-
-- **Single process** -- No IPC overhead. LLM calls, tool execution, and state
-  writes all happen in the same event loop.
-- **SQLite with WAL** -- All state (sessions, usage, audit, config, sharing) is
-  stored in a single SQLite database at `~/.nimbus/nimbus.db` using WAL mode for
-  concurrent read/write.
-- **Streaming-first** -- The agent loop streams LLM responses token-by-token
-  through the TUI. Tool calls appear inline as they execute.
-- **Progressive trust** -- The three-mode system (Plan/Build/Deploy) combined
-  with the 4-tier permission engine ensures that destructive operations always
-  require explicit approval.
-- **Provider fallback** -- The LLM router tries providers in order with circuit
-  breakers, exponential backoff, and automatic failover.
+| Topic | Description |
+|---|---|
+| [Configuration & Providers](docs/guides/configuration.md) | LLM providers, API keys, config profiles, MCP servers |
+| [Hooks & Extensibility](docs/guides/hooks.md) | Hook system, NIMBUS.md format, MCP plugins |
+| [CLI Commands](docs/reference/commands.md) | Full CLI command reference with examples |
+| [Tools Reference](docs/reference/tools.md) | All 33+ built-in tools with parameters |
+| [Architecture](docs/architecture.md) | How Nimbus works internally, component flow, design decisions |
 
 ---
 
 ## License
 
 [MIT](LICENSE)
-
----
-
-## Links
-
-- [npm Package](https://www.npmjs.com/package/@build-astron-co/nimbus)
-- [GitHub](https://github.com/the-ai-project-co/nimbus)
-- [Issues](https://github.com/the-ai-project-co/nimbus/issues)
-- [Releases](https://github.com/the-ai-project-co/nimbus/releases)
-- [Homebrew Tap](https://github.com/the-ai-project-co/homebrew-tap)

package/dist/src/commands/doctor.js

@@ -74,7 +74,7 @@ async function checkLLMProvider(options) {
         }
     }
     // Check credentials file
-    const credentialsFile = path.join(os.homedir(), '.nimbus', 'credentials.json');
+    const credentialsFile = path.join(os.homedir(), '.nimbus', 'auth.json');
     let hasStoredCredentials = false;
     try {
         await fs.access(credentialsFile);
@@ -342,7 +342,7 @@ async function checkCoreServices(options) {
         });
     }
     // Check LLM credentials
-    const credFile = path.join(os.homedir(), '.nimbus', 'credentials.json');
+    const credFile = path.join(os.homedir(), '.nimbus', 'auth.json');
     let llmStatus = 'not configured';
     let llmDetails;
     try {
@@ -1103,7 +1103,7 @@ export async function runStartupChecks() {
             const { join } = await import('node:path');
             const { homedir } = await import('node:os');
             const { readFileSync, existsSync } = await import('node:fs');
-            const credsFile = join(homedir(), '.nimbus', 'credentials.json');
+            const credsFile = join(homedir(), '.nimbus', 'auth.json');
             if (existsSync(credsFile)) {
                 const creds = JSON.parse(readFileSync(credsFile, 'utf-8'));
                 if (Object.keys(creds.providers ?? {}).length === 0) {

package/dist/src/commands/upgrade.js

@@ -265,9 +265,11 @@ async function upgradeViaHomebrew(spinner) {
         await runShellCommand(`brew upgrade ${HOMEBREW_TAP} 2>&1`);
     }
     catch {
-        // If the tap formula isn't found, try the short name
-        spinner.update('Trying brew upgrade nimbus...');
-        await runShellCommand('brew upgrade nimbus 2>&1');
+        // If the tap formula isn't found, tap it first then retry.
+        // Never fall back to bare `brew upgrade nimbus` — Homebrew core has an
+        // unrelated deprecated cask with the same name.
+        spinner.update('Adding tap and retrying...');
+        await runShellCommand(`brew tap the-ai-project-co/tap && brew upgrade ${HOMEBREW_TAP} 2>&1`);
     }
 }
 /**

package/dist/src/nimbus.js

@@ -156,6 +156,7 @@ async function main() {
             'version',
             'doctor',
             'onboarding',
+            'login',
             'upgrade',
             'update',
         ]);

package/dist/src/version.js

@@ -1,3 +1,3 @@
-export const VERSION = '0.4.1';
+export const VERSION = '0.4.2';
 const _RAW_BUILD_DATE = '__BUILD_DATE__';
 export const BUILD_DATE = _RAW_BUILD_DATE.startsWith('__') ? 'dev' : _RAW_BUILD_DATE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@build-astron-co/nimbus",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "AI-Powered DevOps Engineering Agent",
   "main": "dist/src/nimbus.js",
   "bin": {

package/src/commands/doctor.ts

@@ -110,7 +110,7 @@ async function checkLLMProvider(options: DoctorOptions): Promise<CheckResult> {
   }
 
   // Check credentials file
-  const credentialsFile = path.join(os.homedir(), '.nimbus', 'credentials.json');
+  const credentialsFile = path.join(os.homedir(), '.nimbus', 'auth.json');
   let hasStoredCredentials = false;
 
   try {
@@ -384,7 +384,7 @@ async function checkCoreServices(options: DoctorOptions): Promise<CheckResult> {
   }
 
   // Check LLM credentials
-  const credFile = path.join(os.homedir(), '.nimbus', 'credentials.json');
+  const credFile = path.join(os.homedir(), '.nimbus', 'auth.json');
   let llmStatus = 'not configured';
   let llmDetails: string | undefined;
   try {
@@ -1186,7 +1186,7 @@ export async function runStartupChecks(): Promise<StartupCheckResult> {
       const { join } = await import('node:path');
       const { homedir } = await import('node:os');
       const { readFileSync, existsSync } = await import('node:fs');
-      const credsFile = join(homedir(), '.nimbus', 'credentials.json');
+      const credsFile = join(homedir(), '.nimbus', 'auth.json');
       if (existsSync(credsFile)) {
         const creds = JSON.parse(readFileSync(credsFile, 'utf-8'));
         if (Object.keys(creds.providers ?? {}).length === 0) {

package/src/commands/upgrade.ts

@@ -316,9 +316,11 @@ async function upgradeViaHomebrew(spinner: Spinner): Promise<void> {
   try {
     await runShellCommand(`brew upgrade ${HOMEBREW_TAP} 2>&1`);
   } catch {
-    // If the tap formula isn't found, try the short name
-    spinner.update('Trying brew upgrade nimbus...');
-    await runShellCommand('brew upgrade nimbus 2>&1');
+    // If the tap formula isn't found, tap it first then retry.
+    // Never fall back to bare `brew upgrade nimbus` — Homebrew core has an
+    // unrelated deprecated cask with the same name.
+    spinner.update('Adding tap and retrying...');
+    await runShellCommand(`brew tap the-ai-project-co/tap && brew upgrade ${HOMEBREW_TAP} 2>&1`);
   }
 }
 

package/src/nimbus.ts

@@ -177,6 +177,7 @@ async function main() {
       'version',
       'doctor',
       'onboarding',
+      'login',
       'upgrade',
       'update',
     ]);

package/src/version.ts

@@ -1,4 +1,4 @@
-export const VERSION = '0.4.1';
+export const VERSION = '0.4.2';
 
 const _RAW_BUILD_DATE = '__BUILD_DATE__';
 export const BUILD_DATE = _RAW_BUILD_DATE.startsWith('__') ? 'dev' : _RAW_BUILD_DATE;