@jaimevalasek/aioson 1.4.0 → 1.6.0

package/docs/en/cli-reference.md

@@ -6,39 +6,50 @@ Complete reference for all `aioson` commands.
 
 ## init
 
-Create a new project directory and install AIOSON inside it.
+Create a new project directory and install AIOSON inside it. In interactive terminals, an **install wizard** runs first so you choose which AI tools and modes to install.
 
 ```bash
 aioson init <project-name>
 aioson init my-app --lang=pt-BR
 aioson init my-app --tool=codex
-aioson init my-app --lang=es --tool=gemini --json
+aioson init my-app --no-interactive
 ```
 
 **Options:**
 - `--lang=en|pt-BR|es|fr` — sets `conversation_language` in the generated context and applies the matching agent locale pack. Default: `en`.
 - `--tool=codex|claude|gemini|opencode` — configures the primary AI client. Affects which gateway file is used. Default: `codex`.
+- `--no-interactive` — skip the wizard and install all files (CI / automation).
 - `--json` — prints structured JSON result instead of human-readable output.
 
 **What it does:**
 1. Creates `<project-name>/` directory.
-2. Copies all template files into it.
-3. Applies the selected locale pack.
-4. Prints the recommended first command (`@setup`).
+2. Runs the install wizard (tools + mode selection).
+3. Copies only the files matching your profile.
+4. Shows the AIOSON reveal animation and install summary.
+5. Applies the selected locale pack.
 
 ---
 
 ## install
 
-Install AIOSON in an existing directory (or the current directory).
+Install AIOSON in an existing directory (or the current directory). Runs the same wizard as `init` when in a TTY.
 
 ```bash
 aioson install
 aioson install ./my-project
 aioson install --lang=pt-BR --tool=claude
+aioson install --reconfigure
+aioson install --no-interactive
 ```
 
-**Options:** same as `init`.
+**Options:**
+- `--lang=en|pt-BR|es|fr` — sets locale pack.
+- `--tool=codex|claude|gemini|opencode` — configures AI client.
+- `--reconfigure` — re-run the wizard even if a profile already exists (e.g. to add Gemini later).
+- `--no-interactive` — skip the wizard and install all files.
+- `--force` — overwrite existing files.
+- `--dry-run` — preview without writing.
+- `--json` — prints structured JSON result.
 
 **Use this when:**
 - The project already exists (legacy codebase, existing repo).
@@ -48,7 +59,7 @@ aioson install --lang=pt-BR --tool=claude
 
 ## update
 
-Update managed files to the latest template version. Preserves context files and anything not in the managed file list.
+Update managed files to the latest template version. Respects the saved install profile — only updates files that were originally installed.
 
 ```bash
 aioson update
@@ -60,7 +71,7 @@ aioson update --lang=pt-BR
 - `--lang=en|pt-BR|es|fr` — re-applies the locale pack after updating. If omitted, re-applies whatever locale is currently active.
 - `--json` — prints structured JSON result.
 
-**What it updates:** all files in the `MANAGED_FILES` list (agents, config, gateway files, skills). Does not touch `project.context.md`, `discovery.md`, `architecture.md`, or other context files you created.
+**What it updates:** all files in the `MANAGED_FILES` list that match your install profile (agents, config, gateway files, skills). Does not touch `project.context.md`, `discovery.md`, `architecture.md`, or other context files you created.
 
 ---
 

package/docs/en/squad-dashboard.md

@@ -0,0 +1,372 @@
+# Squad Dashboard
+
+The Squad Dashboard is a web panel built into the aioson CLI itself. It runs locally on the developer's machine and lets you monitor all squads in a project in real time — agents, active processes, context usage, tokens, execution logs, and metrics.
+
+No additional installation required. It ships with aioson.
+
+---
+
+## Prerequisites
+
+- aioson installed globally (`npm install -g @jaimevalasek/aioson`)
+- At least one squad created in the project (`aioson squad:create`)
+- Node.js ≥ 18 (already required by aioson)
+- A modern browser (Chrome, Firefox, Safari, Edge)
+
+---
+
+## Starting the Dashboard
+
+From the project root (where `.aioson/` lives):
+
+```bash
+aioson squad:dashboard
+```
+
+Expected output:
+```
+Squad Dashboard running at http://localhost:4180 (port 4180)
+Press Ctrl+C to stop.
+```
+
+Open `http://localhost:4180` in your browser. Press `Ctrl+C` in the terminal to shut it down.
+
+---
+
+## Options
+
+```bash
+aioson squad:dashboard [path] [--port=4180] [--squad=<slug>] [--locale=en]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `path` | `.` (current directory) | Project root |
+| `--port` | `4180` | HTTP port for the dashboard |
+| `--squad` | — | Open directly on a specific squad page |
+| `--locale` | `en` | Interface language |
+
+---
+
+## Examples
+
+### Start in the current project
+```bash
+cd ~/projects/dental-clinic
+aioson squad:dashboard
+```
+
+### Custom port
+```bash
+aioson squad:dashboard --port=4200
+```
+
+### Point to another directory
+```bash
+aioson squad:dashboard /home/user/projects/marketing
+```
+
+### Open directly on a specific squad
+```bash
+aioson squad:dashboard --squad=marketing-odonto
+# → Redirects automatically to http://localhost:4180/squad/marketing-odonto
+```
+
+### Multiple projects at the same time (different ports)
+```bash
+# Terminal 1
+aioson squad:dashboard ~/projects/clinic --port=4180
+
+# Terminal 2
+aioson squad:dashboard ~/projects/ecommerce --port=4181
+```
+
+---
+
+## Navigating the Dashboard
+
+### Home — Squad List
+
+At `http://localhost:4180` you see all squads in the project with:
+
+- Name and mode (`content`, `software`, `mixed`)
+- Number of executors (agents)
+- Current status
+- Link to the squad detail page
+
+If no squads appear, check that `.aioson/squads/*/squad.manifest.json` exists.
+
+---
+
+### Squad Page — Panels
+
+Each squad has its own URL: `http://localhost:4180/squad/{slug}`
+
+Available panels depend on squad configuration:
+
+#### Panel: Overview
+
+Summary of the squad:
+- Total content items produced
+- Number of registered sessions
+- Accumulated learnings
+- Delivery rate
+- Execution plan (if defined)
+- Pipeline information
+
+#### Panel: Agents (Processes)
+
+Lists active Claude/AI agents:
+
+| Column | What it shows |
+|--------|---------------|
+| Agent | Executor slug |
+| PID | OS process ID |
+| Elapsed | Session duration (`HH:MM:SS`) |
+| Context | Context window usage % |
+| URL | Link to open the AI session (if available) |
+| Action | Button to stop the process via SIGTERM |
+
+> Process data auto-refreshes every 5 seconds via SSE (Server-Sent Events).
+
+#### Panel: Context
+
+Context window monitor per agent:
+
+- **Visual gauge** showing % usage
+- **Alert level**:
+  - Green: 0–84% → Normal
+  - Yellow: 85–94% → Warning
+  - Red: 95–99% → Critical
+  - Purple: 100%+ → Overflow
+- Automatic compact detection (a drop > 30% indicates context was compacted)
+- Breakdown by category (system prompt, conversation history, tool outputs, etc.)
+
+#### Panel: Tokens
+
+Token usage and estimated cost per agent:
+
+- Total tokens consumed in the session
+- Estimated cost in USD (based on Sonnet-class model pricing)
+- **Waste flag**: appears when `tool_outputs > 60%` of total
+- Breakdown by category (input, output, tool_use_input, tool_outputs, cache_write, cache_read)
+
+#### Panel: Execution Logs
+
+Detailed history of task executions:
+
+- Entries filterable by type:
+  - `tool_call` — tool calls with input/output
+  - `reasoning` — agent reasoning
+  - `milestone` — important checkpoints
+  - `error` — errors with optional stack trace
+- Timeline ordered by timestamp
+- Filter by session
+
+#### Panel: Hunk Review
+
+Code review in hunks (for software squads):
+
+- List of hunks pending review
+- Available actions: **Approve**, **Reject** (comment required), **Comment**
+- Progress: `approved / rejected / pending / revised`
+- Re-submit: approved hunks keep their status; only rejected ones return to pending
+
+#### Panel: Content
+
+Content items produced by the squad (for content squads):
+
+- List of indexed outputs
+- Type and layout of each item
+- Responsible agent
+
+#### Panel: Learnings
+
+Learnings accumulated by the squad:
+
+- Active, stale, and archived learnings
+- Type: preference, process, domain, quality
+- Confidence: high, medium, low
+
+#### Panel: Metrics
+
+Custom metrics configured via `aioson squad:roi`:
+
+- Current value vs. baseline vs. target
+- Period
+- Visual progress bar
+- Calculated ROI (when configured)
+
+#### Panel: Integrations
+
+Status of MCPs configured in the squad:
+
+- Active connectors (WhatsApp, Telegram, Webhook, etc.)
+- Status: connected / unconfigured / error
+- Total calls and failures
+
+#### Panel: Recovery Context
+
+Recovery context generated for each agent (post-compact injection):
+
+- Content of `recovery-context.md`
+- Token estimate
+- Generation timestamp
+
+---
+
+## Use Cases by Squad Type
+
+### Content Squad (e.g. Dental Clinic Marketing)
+
+```bash
+# The squad is generating Instagram posts and blog content
+aioson squad:dashboard --squad=marketing-odonto
+
+# Most relevant panels:
+# → Content: see generated posts
+# → Agents: see copywriter and strategist running
+# → Learnings: accumulated tone and format preferences
+```
+
+### Software Squad (e.g. Scheduling Feature)
+
+```bash
+aioson squad:dashboard --squad=scheduling-v2
+
+# Most relevant panels:
+# → Hunk Review: review code before merging
+# → Logs: follow agent tool_calls
+# → Context: monitor if the agent is near the limit
+```
+
+### Squad with Workers and Daemon
+
+```bash
+# First start the daemon (automated workers)
+aioson squad:daemon start --squad=clinic
+
+# In another terminal, start the dashboard
+aioson squad:dashboard --squad=clinic
+
+# Most relevant panels:
+# → Metrics: no-show rate, ROI
+# → Integrations: WhatsApp Business status
+# → Agents: see live processes
+```
+
+---
+
+## Integration with Other Commands
+
+The dashboard reads data generated by other aioson commands. For panels to show rich data:
+
+| To see in the dashboard | Command that generates the data |
+|-------------------------|---------------------------------|
+| Metrics and ROI | `aioson squad:roi metric --squad=X` |
+| MCP status | `aioson squad:mcp configure --squad=X` |
+| Active processes | Agents running that write to `.aioson/squads/{slug}/processes/` |
+| Context window | Agents that write to `.aioson/squads/{slug}/context-monitor.json` |
+| Token usage | Agents that write to `.aioson/squads/{slug}/token-usage.json` |
+| Learnings | `aioson squad:learning` and auto-registered sessions |
+| Recovery context | `aioson squad:recovery --squad=X --agent=Y` |
+
+---
+
+## Data Requirements
+
+The dashboard works even without all data present. What each panel needs:
+
+```
+.aioson/
+  squads/
+    {slug}/
+      squad.manifest.json          ← required (squad appears in the list)
+      context-monitor.json         ← Context panel
+      token-usage.json             ← Tokens panel
+      processes/
+        {agent}.json               ← Agents panel
+      recovery-context.md          ← Recovery panel
+  runtime/
+    aios.sqlite                    ← Content, Learnings, Metrics, Integrations panels
+```
+
+If the SQLite database doesn't exist, dependent panels appear empty but the dashboard does not crash.
+
+---
+
+## Squad Dashboard vs. aioson-dashboard
+
+| | Squad Dashboard | aioson-dashboard |
+|---|---|---|
+| **What it is** | HTTP server embedded in the CLI | Installable Next.js app (premium) |
+| **How to access** | `aioson squad:dashboard` | Install and run separately |
+| **Focus** | Project squads in real time | General management — projects, genomes, pipelines, cloud |
+| **Port** | `localhost:4180` (configurable) | Defined by the app |
+| **Extra install** | No — ships with aioson | Yes |
+| **Cost** | Free | Premium |
+
+When both are running, aioson-dashboard shows an **"Open Squad Dashboard"** button on each squad page, linking directly to the correct URL.
+
+---
+
+## Troubleshooting
+
+### Dashboard won't start — port in use
+
+```
+Port 4180 is already in use. Try --port=<other>
+```
+
+Use a different port:
+```bash
+aioson squad:dashboard --port=4200
+```
+
+### No squads on the home page
+
+Check that the manifest exists:
+```bash
+ls .aioson/squads/*/squad.manifest.json
+```
+
+If not, create the squad first:
+```bash
+aioson squad:create . --squad=my-squad
+```
+
+### Panels appear empty
+
+Normal for new projects or squads without runtime data. Panels populate as agents run and write their data files.
+
+### Process panel stops updating
+
+The agents panel uses SSE with a 5-second interval. If it stops updating, refresh the page.
+
+### Command not found after updating aioson in a project
+
+The global binary may be outdated:
+```bash
+npm update -g @jaimevalasek/aioson
+```
+
+---
+
+## Quick Reference
+
+```bash
+# Start
+aioson squad:dashboard
+
+# Custom port
+aioson squad:dashboard --port=4200
+
+# Specific squad
+aioson squad:dashboard --squad=my-squad
+
+# Project in another directory
+aioson squad:dashboard /path/to/project
+
+# Help
+aioson squad:dashboard --help
+```