hablas-ai 2.4.0 → 2.4.2

package/README.md

@@ -1,267 +1,180 @@
 # Hablas CLI
 
-**Single-agent terminal AI engineering runtime**.
+**Single-agent terminal engineering runtime** — v2.4.0
 
-Hablas is being rebuilt from scratch around one strict product decision:
-
-> one visible agent, one execution surface, full tools, zero internal theatre
-
-This stable branch no longer treats multi-agent choreography as the product.
-The product is now **Hablas only**.
+> One agent. Full tool access. Plans, codes, tests, commits — without switching tools or losing context.
 
 ---
 
 ## Product principles
 
-1. **Single visible agent**
-2. **Fast direct path for trivial turns**
-3. **Full tool execution for real engineering work**
-4. **No hidden routing leaks in the UX**
-5. **No handoff theatre, no mode maze, no orchestration drama**
-6. **Read before edit, verify before claim**
-7. **Direct technical tone: no emojis, no hype, no filler**
-8. **Professional shell UX matters as much as model quality**
+1. **Single visible agent** — no hidden routing, no multi-agent theatre
+2. **Fast direct path** for trivial turns — instant response, no tool overhead
+3. **Full tool execution** for real engineering work
+4. **Read before edit, verify before claim**
+5. **TDD built-in** — failing tests first, implementation second
+6. **Checkpoints** — named snapshots before any risky change
+7. **Cross-turn reasoning memory** — Hablas never forgets what it learned
+8. **Direct technical tone** — no emojis, no hype, no filler
 
 ---
 
 ## Installation
 
 ```bash
-git clone https://github.com/Monopoly63/mobile-bot.git
-cd mobile-bot/flowagent
-npm install
-npm run build
-npm link
+npm install -g hablas-ai
 ```
 
-Requirements:
-- Node.js 20+
-- One provider:
-  - Ollama
-  - NVIDIA NIM
-  - any OpenAI-compatible API
-
----
-
-## Usage
-
-### First run / setup
-
-On first launch, Hablas now offers the restored classic setup flow:
-
-1. **Hablas Integrated Engine**
-   - ready-made
-   - preconfigured NVIDIA-backed endpoint
-   - selected model already configured
-   - user just chooses option 1
-
-2. **Custom Provider**
-   - Ollama
-   - OpenAI
-   - Groq
-   - OpenRouter
-   - Together
-   - DeepSeek
-   - custom OpenAI-compatible API
-   - NVIDIA NIM
+Requires Node.js 20+. One LLM provider:
 
-You can also run setup manually anytime:
+| Option | Description |
+|---|---|
+| **Hablas Integrated Engine** | Preconfigured NVIDIA NIM backend — ready in one click on first run |
+| **Ollama** | Fully local, private, no API key |
+| **OpenAI-compatible** | Any REST endpoint |
 
-```bash
-hablas --setup
-```
-
-### Interactive
-
-```bash
-hablas
-```
+---
 
-### Interactive with automatic tool confirmations where allowed
+## Quick start
 
 ```bash
-hablas --auto
+hablas --setup   # first-time configuration wizard
+hablas           # start the agent
 ```
 
-### One-shot
+---
 
-```bash
-hablas run "read package.json and tell me the version"
-```
+## CLI flags
 
-### Web and asset workflow
-Hablas now keeps the professional web tool chain active:
-- `web_search`
-- `search_image_candidates`
-- `inspect_image`
-- `scrape_url`
-- `extract_links`
-- `download_asset`
-
-This means Hablas can:
-- search the web for references and assets
-- rank trusted **image page candidates** before downloading
-- inspect a remote or local image candidate before adoption
-- resolve a page candidate into a direct image candidate with an explicit verdict
-- download real images/files into the project when appropriate
-- preserve full file reads in-context so long files are not silently cut into tiny fragments that force rereads
-
-### Image pipeline stance
-For image replacement work, the intended flow is:
-1. `search_image_candidates`
-2. `inspect_image`
-3. `download_asset`
-
-The runtime should stay inside this image toolchain.
-It should not fall back to shell hacks (`curl`, `powershell`, guessed public image IDs) for public asset discovery unless the user explicitly asks for low-level debugging.
+| Flag | Description |
+|---|---|
+| `hablas` | Start interactive session |
+| `hablas --setup` | Run the setup wizard |
+| `hablas --model <name>` | Override the configured model |
+| `hablas --verbose` | Enable verbose logging |
+| `hablas --no-color` | Disable ANSI output |
+| `hablas --version` | Print version and exit |
+| `hablas --help` | Show all flags |
 
 ---
 
-## Current command surface
-
-### CLI commands
-- `hablas`
-- `hablas run "..."`
-- `hablas doctor`
-- `hablas info`
-- `hablas security`
-- `hablas stats`
-- `hablas --setup`
-
-### Slash commands
-- `/help`
-- `/status`
-- `/model [name]`
-- `/models [query]`
-- `/provider [ollama|nvidia|custom|test]`
-- `/history [n]`
-- `/clear`
-- `/workspace`
-- `/doctor`
-- `/version`
-- `/about`
-- `/exit`
-
-### Shell UX
-- tab completion for slash commands
-- tab completion for common file paths after verbs like `read`, `write`, `edit`, `patch`
-- `#file` reference completion
-- persisted command history
-- rebuilt Apple-slate terminal styling
-- visible thinking state while the model is working
-- direct-turn streaming when the provider supports it
+## In-session commands
+
+### Planning & execution
+| Command | Description |
+|---|---|
+| `/plan <task>` | Break a task into steps, confirm before execution |
+| `/files <query>` | Rank and preview the most relevant files for a task |
+| `/git` | Show git status, staged changes, recent commits |
+
+### Checkpoints
+| Command | Description |
+|---|---|
+| `/checkpoint save <name>` | Save a named workspace snapshot |
+| `/checkpoint list` | List all saved checkpoints |
+| `/checkpoint diff <name>` | Show what changed since a checkpoint |
+| `/checkpoint restore <name>` | Restore workspace to a checkpoint |
+
+### Testing & TDD
+| Command | Description |
+|---|---|
+| `/tests` | Run project test suite, show parsed results |
+| `/tests coverage` | Full coverage report with per-file breakdown |
+| `/tdd <description>` | Scaffold failing tests first, then implement |
+
+### Context & memory
+| Command | Description |
+|---|---|
+| `/memory` | Show project memory + cross-turn reasoning accumulator |
+| `/compact` | Compress current context to free token budget |
+| `/help` | List all available commands |
 
 ---
 
-## Execution model
-
-Hablas analyzes a request into one of four internal task kinds:
-- `casual`
-- `read`
-- `analysis`
-- `implementation`
+## Example workflows
 
-The runtime uses a **lightweight local task profiler** so first-turn latency stays clean and there is no hidden pre-turn model call before Hablas starts responding.
+### TDD — write tests first, then implement
 
-Then it decides whether the turn should be:
-- **direct text execution**
-- **tool-based execution**
+```
+> /tdd add rate limiting to the /api/auth routes
+Scaffolding tests: tests/auth-rate-limit.test.ts
+  ✗ should block after 5 failed attempts  (RED)
+  ✗ should reset counter after 15 minutes (RED)
+Implementing: src/middleware/rate-limit.ts
+Running: npx jest tests/auth-rate-limit.test.ts
+  ✓ should block after 5 failed attempts  (GREEN)
+  ✓ should reset counter after 15 minutes (GREEN)
+Done. 2 tests passing.
+```
 
-There is no public `build/design/ask` mode system anymore.
-There is no visible team routing layer.
+### Checkpoint before a risky migration
 
----
+```
+> /checkpoint save before-db-migration
+Snapshot saved: before-db-migration (47 files)
 
-## Examples
+> migrate the users table to UUID primary keys
 
-### Simple direct turn
-```text
-hi
+> /checkpoint diff before-db-migration
+Modified: prisma/schema.prisma (+12 / -3)
+Added:    prisma/migrations/20260615_uuid.sql
 ```
-Expected behavior:
-- no tool calls
-- short direct answer
 
-### Project inspection
-```text
-what is the current version of this project
-```
-Expected behavior:
-- inspect the minimum relevant files
-- answer from evidence
+### Smart file discovery
 
-### Architecture request
-```text
-design the architecture for auth in this repository
 ```
-Expected behavior:
-- structured analysis
-- inspect files only if needed
-- answer as one agent
-
-### Continuation request
-```text
-continue the unfinished project
+> /files payment processing logic
+1. src/services/payment.ts      (score: 0.94)
+2. src/routes/checkout.ts       (score: 0.87)
+3. src/models/transaction.ts    (score: 0.81)
 ```
-Expected behavior:
-- continue from existing work
-- do not restart from zero
-
-### One-step delivery request
-```text
-just give me the finished project in one step no questions
-```
-Expected behavior:
-- aggressive execution posture
-- no unnecessary follow-up questions
-- verify before claiming done
-
----
-
-## Architecture docs
-
-See:
-- `docs/ARCHITECTURE.md`
-- `docs/CLI.md`
-- `docs/ROADMAP.md`
-- `docs/STATUS.md`
-- `docs/PUBLISH.md`
 
 ---
 
-## Development
+## Architecture
 
-```bash
-npm install
-npm run build
-npm test
-npm run dev -- run "your prompt"
+```
+User input
+  → Task analyzer (kind · complexity · language)
+  → Fast path (trivial turns — no tools)
+  → Full path: plan → tool execution → verification
+    ├─ file-ops      (read, write, atomic patch, rollback)
+    ├─ shell         (unrestricted terminal)
+    ├─ git-ops       (commit, PR, changelog, merge)
+    ├─ checkpoint    (save, list, diff, restore)
+    ├─ run_tests     (Jest, Vitest, Pytest, Go test)
+    ├─ tdd-engine    (scaffold failing tests → implement)
+    ├─ search        (web, DuckDuckGo)
+    ├─ image-intel   (vision for screenshots/diagrams)
+    └─ suggest_relevant_files (5-signal ranking)
+  → LongContextAccumulator (cross-turn reasoning memory)
+  → SmartContext (auto-inject top-K files for complex tasks)
+  → Response
 ```
 
-Current automated checks cover:
-- shared execution engine smoke behavior
-- analyzer behavior
-- session continuity behavior
-- image pipeline helper behavior
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for full detail.
 
 ---
 
-## Memory and state
-
-Hablas now uses larger defaults for the rebuilt runtime and also keeps a project-local state folder:
-- larger message history budget
-- larger context budget
-- project-local `.hablas/session.json` persistence for the current workspace
+## What's new in v2.4.0
 
-This is separate from the user-home config directory used for global config/history.
+**Phase 3 — Professional Intelligence**
 
-## Rebuild status
+- `checkpoint_save` / `list` / `restore` / `diff` — named workspace snapshots
+- `run_tests` — auto-detect Jest/Vitest/Pytest/Go, parse structured results
+- `test_coverage` — full coverage report with per-file breakdown
+- `tdd_scaffold` — red-green-refactor TDD workflow in the terminal
+- `suggest_relevant_files` — 5-signal smart file ranking
+- `LongContextAccumulator` — cross-turn reasoning memory with cosine dedup
+- `SmartContext` — auto-inject top-K relevant files for L/XL tasks
+- `/memory` upgraded — shows project memory + reasoning accumulator
+- `/checkpoint`, `/tests`, `/tdd` slash commands
+- TypeScript: 0 errors, clean build, 324KB bundle
 
-This branch is under an intentional **full rebuild** of the stable product surface.
-Dead code from the previous multi-agent product is being physically removed instead of patched.
+See [`CHANGELOG.md`](CHANGELOG.md) for the full history.
 
 ---
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE)