limitless-cli 1.0.0

A beginner-friendly environment diagnostic tool
Documentation
# Usage

Limitless is run from your **project root** — the directory that contains
`package.json`, `requirements.txt`, `setup.py`, `pyproject.toml`, `Cargo.toml`,
or `go.mod`. Everything else is handled for you.

## Commands

### `limit` / `limit check` — Full environment audit

Scans the environment and prints a dashboard with a health score:

- Stack detection (Node, Python, Rust, Docker)
- Runtime version validation
- `.env` / `.env.example` audit
- Port scan for blocked ports (3000, 5000, 8000, 8080, 9000)
- Dependency health (`node_modules`, `requirements.txt`, `Cargo.lock`)
- PATH & proxy hygiene

Exit code `0` when healthy, `1` when issues were found (handy in scripts).

### `limit dev` — Audit + launch

Runs the audit; when the environment is **100% healthy** it launches the dev
server for the detected stack (`npm run dev`, `cargo run`, etc.). When issues
are found it shows the dashboard and suggested fixes instead.

### `limit fix` / `limit fix --all` — Auto-fix

Fixes detected issues in priority order:

1. Kill ghost processes holding blocked ports
2. Copy `.env.example` → `.env`
3. Install missing dependencies
4. Create missing `.gitignore` / `.editorconfig`

`limit fix` prompts for approval on each fix. `limit fix --all` applies every
fix without asking. Fixes are previewed before they run, reported after, and
rolled back if verification fails.

### `limit orbit` — Planetary mode

The same diagnostics, rendered as a sci-fi mission-control report, renaming
project files into "systems" and reporting each system's status.

### `limit arcade` — SyntaxBreaker

A terminal typing game. Correct answer flips a snippet. Score is kept on
disk (`~/.limitless/`); the top 5 are displayed. Playing unlocks badges.

## Options (global)

| Flag          | Effect                                        |
|---------------|-----------------------------------------------|
| `--fast`      | Skip animations & cached-snapshot trivia       |
| `--verbose`   | Show technical details behind every result     |
| `--color`     | Force ANSI colors (overrides config)           |
| `--no-color`  | Disable ANSI colors (beat `--color`)           |
| `-h, --help`  | Full help guide                               |
| `-V, --version` | Show version                               |

## Config

Preferences live in `~/.limitless/config.json`:

```json
{
  "preferred_stack": null,
  "auto_approve_safe_fixes": false,
  "color_enabled": true,
  "animation_enabled": true,
  "verbose_mode": false
}
```

Command-line flags override the config. `--no-color` beats `--color`.

## Badges

Activity unlocks badges: Port Whisperer, Env Master, Arcade Champion,
Night Owl, and Speed Runner. New unlocks are announced in a popup after
the run that earned them.

## Dashboard health

A 0–100% score. Healthy ≥ 85, Caution ≥ 60, Critical below. Every failing
check comes with a plain-English explanation and a concrete next step, so you
never need to decode a stack trace alone.

## Examples

```bash
# Run a complete health check
$ limit

# Check health, then start the dev server
$ limit dev

# Fix everything in one shot
$ limit fix --all

# Mission-control view
$ limit orbit

# Play the typing game
$ limit arcade

# Quiet, script-friendly scan captured as plain text
$ limit --fast --no-color
```