@jaimevalasek/aioson 1.6.0 → 1.7.0

package/README.md

@@ -1,6 +1,565 @@
+<div align="center">
+
 # AIOSON
 
-AI operating framework for hyper-personalized software.
+**AI operating framework for hyper-personalized software.**
+
+*Structure your AI sessions. Orchestrate specialized agents. Ship with confidence.*
+
+*Works in any IDE with a terminal — VS Code, Google Antigravity, Cursor, Windsurf, JetBrains IDEs, Zed, and more.*
+
+[![npm version](https://img.shields.io/npm/v/@jaimevalasek/aioson?color=6c47ff&style=flat-square)](https://www.npmjs.com/package/@jaimevalasek/aioson)
+[![npm downloads](https://img.shields.io/npm/dm/@jaimevalasek/aioson?style=flat-square&color=6c47ff)](https://www.npmjs.com/package/@jaimevalasek/aioson)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](LICENSE)
+[![Node.js ≥18](https://img.shields.io/badge/node-%E2%89%A518.0.0-brightgreen?style=flat-square)](https://nodejs.org)
+
+[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-6c47ff?style=flat-square)](https://claude.ai/code)
+[![Codex CLI](https://img.shields.io/badge/Codex_CLI-supported-black?style=flat-square)](https://github.com/openai/codex)
+[![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-supported-4285F4?style=flat-square)](https://github.com/google-gemini/gemini-cli)
+[![OpenCode](https://img.shields.io/badge/OpenCode-supported-orange?style=flat-square)](https://opencode.ai)
+
+</div>
+
+---
+
+<div align="center">
+
+AIOSON gives every AI session a **role**, a **protocol**, and a **lifecycle**.  
+Instead of one massive prompt doing everything, each agent owns a well-defined slice — from discovery to deployment — and hands off cleanly to the next.
+
+</div>
+
+---
+
+## Installation
+
+```bash
+# New project
+npx @jaimevalasek/aioson init my-project
+
+# Existing project
+cd my-project
+npx @jaimevalasek/aioson install
+```
+
+Running `init` or `install` launches an **interactive wizard** to configure:
+
+1. Which AI tools to enable (Claude Code, Codex CLI, Gemini CLI, OpenCode)
+2. Mode — Development or Development + Squads
+3. Design system (optional) — Clean SaaS UI, Aurora Command UI, Cognitive Core UI, etc.
+4. Agent language — English, Português, Español, Français
+
+Only the relevant files are copied. No extra dependencies are installed.
+
+**Skip the wizard** — install everything at once with `--all`:
+
+```bash
+npx @jaimevalasek/aioson init my-project --all
+npx @jaimevalasek/aioson install --all
+```
+
+**Reconfigure** — add tools or activate Squads after the initial install:
+
+```bash
+npx @jaimevalasek/aioson install --reconfigure
+```
+
+**CI / automation** — install without prompts:
+
+```bash
+npx @jaimevalasek/aioson install --no-interactive
+```
+
+**Update** to a new version (respects your saved profile):
+
+```bash
+npx @jaimevalasek/aioson update
+```
+
+---
+
+## How it works
+
+```
+  New project                              Existing project
+       │                                         │
+       ▼                                         ▼
+  aioson init                           aioson install .
+       │                                aioson scan:project
+       └──────────────┬──────────────────────────┘
+                      │
+                      ▼
+              ┌───────────────┐
+              │  /setup       │  ← Project context & onboarding
+              └───────┬───────┘
+                      │
+          ┌───────────┼───────────┐
+          ▼           ▼           ▼
+    /analyst     /architect    /product      ← Discovery & planning
+          │           │           │
+          └───────────┼───────────┘
+                      ▼
+              ┌───────────────┐
+              │  /sheldon     │  ← PRD enrichment & deep technical reasoning
+              └───────┬───────┘
+                      ▼
+              ┌───────────────┐
+              │   /ux-ui      │  ← Design system & UI specs
+              └───────┬───────┘
+                      │
+          ┌───────────┼───────────┐
+          ▼           ▼           ▼
+      /deyvin       /dev        /pm          ← Implementation
+          │           │           │
+          └───────────┼───────────┘
+                      ▼
+              ┌───────────────┐
+              │    /qa        │  ← Review, tests, browser QA
+              └───────────────┘
+```
+
+Each agent runs as a tracked live session with full runtime observability — milestones, handoffs, and context snapshots recorded in the AIOSON dashboard.
+
+---
+
+## Why AIOSON
+
+Most AI sessions are conversations. AIOSON is a **protocol**.
+
+Every feature goes through a defined lifecycle — spec, gate, build, verify — and every agent knows exactly where it is in that lifecycle. The result: AI that doesn't guess, doesn't drift, and doesn't lose track when the context window fills up.
+
+### Spec-Driven Development
+
+Vague prompt → unambiguous spec → gated execution. No skipping phases, no silent assumptions.
+
+```
+"add a stock management feature"
+         │
+         ▼ @product
+   prd-stock-management.md
+   ┌──────────────────────────────────────┐
+   │ objectives, out-of-scope, open items │
+   └──────────────────────────────────────┘
+         │
+         ▼ @sheldon          ← PRD enrichment
+   sheldon-enrichment-stock.md
+   ┌──────────────────────────────────────┐
+   │ gray areas decided, readiness score  │
+   │ RF-GA extraction, AC hardening       │
+   └──────────────────────────────────────┘
+         │
+         ▼ Gate A            ← requirements approved?
+   requirements-stock.md     ← REQ-stock-001, AC-stock-001 …
+         │
+         ▼ Gate B            ← design approved?
+   architecture.md + design-doc-stock.md
+         │
+         ▼ Gate C            ← implementation plan reviewed?
+   implementation-plan-stock.md
+         │
+         ▼ @dev / @deyvin    ← code, commits, spec updates
+         │
+         ▼ Gate D            ← 4-tier verification
+   @qa forensics: Exists → Substantive → Wired → Functional
+```
+
+**Gates are blocking in MEDIUM projects, informational in SMALL.** Each gate is enforced by a checklist in `spec-{slug}.md` — agents can't advance without explicit approval signals. No more AI that starts coding before the requirements are clear.
+
+**What you get in the spec file:**
+
+| Field | What it tracks |
+|-------|----------------|
+| `phase_gates` | `requirements: approved`, `design: approved`, `plan: approved` |
+| `last_checkpoint` | Exactly where the agent stopped — resume without re-reading everything |
+| `gray_areas_decided` | Every ambiguity that was surfaced and decided, with rationale |
+| `must_haves` | Triplet contract: truths, artifacts, key links |
+| `readiness` / `readiness_notes` | @sheldon's go/no-go signal before implementation starts |
+
+---
+
+### Context intelligence
+
+AI sessions fail silently. Context fills up, the model forgets, the agent reinvents what was already decided. AIOSON ships a full context management layer so this never happens quietly.
+
+**5-phase context optimization system:**
+
+**Session Recovery** — when Claude compacts or a session crashes, one command restores the full working state:
+```bash
+aioson recovery:generate   # snapshot current state, < 2 000 tokens
+aioson recovery:show       # paste this into the new session — agent picks up exactly where it left
+```
+
+**Context Monitor** — real-time usage bars with adaptive thresholds per project size:
+```bash
+aioson context:monitor     # ASCII bars, warning/critical detection
+```
+```
+Context usage ████████████░░░░ 73%  ⚠ approaching threshold (SMALL: 65%)
+Agents recommend /clear before next phase
+```
+
+**FTS5 Search Index** — find anything across all your project artifacts in milliseconds:
+```bash
+aioson context:search "payment webhook retry logic"
+# BM25 ranking + recency reranking — surfaces the right doc, not just keyword matches
+```
+
+**Context Cache** — save and restore session snapshots without losing what the AI already knows:
+```bash
+aioson context:cache save --label="before-refactor"
+aioson context:cache restore --label="before-refactor"
+```
+
+**Agent Sharding** — agents load only the instructions relevant to the current goal. Irrelevant sections are stripped before the context window fills:
+```bash
+aioson agent:load deyvin --goal="fix stock modal validation"
+# 68% token reduction — agent arrives focused, not bloated
+```
+
+**Adaptive learning** — AIOSON tracks what worked and evolves agent behavior over time:
+```bash
+aioson learning:evolve    # distill patterns from completed sessions
+aioson learning:apply     # push improvements back into the agent chain
+```
+
+**Context budget thresholds by project size:**
+
+| Classification | Warning threshold | Why |
+|----------------|-------------------|-----|
+| MICRO | 75% | Short phases — ok to run higher |
+| SMALL | 65% | Default — balanced warning |
+| MEDIUM | 55% | Long phases — warn early, write artifacts first |
+
+When an agent approaches its threshold it writes all in-progress artifacts to disk, emits a warning, and records `last_checkpoint` — so the next session can start from state, not from memory.
+
+---
+
+## AIOSON Squads
+
+Squads are the part of AIOSON that most people don't expect.
+
+You can build a specialized, multi-agent team for **any domain** — software development, content creation, legal review, gastronomy, YouTube, music production, marketing, or anything you can describe. A squad is a fully packaged, versioned, invocable team of AI agents that lives inside your project and gets smarter over time.
+
+```
+                    ┌─────────────────────────────────────────────┐
+                    │              AIOSON Squad                    │
+                    │                                              │
+                    │  @orchestrator ─── coordinates the team      │
+                    │       │                                      │
+                    │  ┌────┴──────────────────────────┐          │
+                    │  │         Executors              │          │
+                    │  │  @scriptwriter  @copywriter    │          │
+                    │  │  @analyst       @reviewer      │          │
+                    │  └───────────────────────────────┘          │
+                    │       │                                      │
+                    │  ┌────┴──────────────────────────┐          │
+                    │  │  Genome (cognitive layer)      │          │
+                    │  │  "how this team thinks"        │          │
+                    │  │  domain · function · persona   │          │
+                    │  └───────────────────────────────┘          │
+                    │       │                                      │
+                    │  ┌────┴──────────────────────────┐          │
+                    │  │  Skills (operational layer)    │          │
+                    │  │  "what this team knows how to do"        │
+                    │  └───────────────────────────────┘          │
+                    └─────────────────────────────────────────────┘
+```
+
+### Create a squad for any domain
+
+```bash
+# Software squad
+@squad
+> domain: SaaS product development
+> goal: ship features end-to-end
+> roles: product, architect, dev, qa
+
+# YouTube content squad
+@squad
+> domain: YouTube content creation
+> goal: scriptwriting, hooks, retention
+> roles: scriptwriter, hook-analyst, thumbnail-strategist, orchestrator
+
+# Legal review squad
+@squad
+> domain: contract review — Brazilian corporate law
+> goal: flag risks, suggest amendments
+> roles: risk-analyst, clause-reviewer, summarizer
+```
+
+Each squad gets its own package under `.aioson/squads/{slug}/` — agents, manifest, output folder, execution logs. Every agent is directly invocable by the user: `@scriptwriter`, `@risk-analyst`, `@hook-analyst`.
+
+---
+
+### Genome — the cognitive layer
+
+Skills tell an agent what to do. A genome tells it **how to think**.
+
+```
+@genome
+> type: domain
+> domain: viral content strategy
+> depth: expert
+
+→ generates: .aioson/genomes/viral-content-strategy.md
+  - mental models and decision frameworks
+  - quality lenses and judgment heuristics
+  - anti-patterns and known failure modes
+  - vocabulary and reference benchmarks
+```
+
+Four genome types:
+
+| Type | What it encodes |
+|------|----------------|
+| `domain` | Deep knowledge of a field — editorial, legal, financial, technical |
+| `function` | Operational expertise — retention analysis, risk review, architecture |
+| `persona` | Cognitive profile of a real person — their mental models, blindspots, style |
+| `hybrid` | Combination of domain + persona with weighted influence |
+
+Apply a genome to any squad executor and the agent thinks with those lenses — not just follows instructions.
+
+---
+
+### Persona genomes and the Profiler pipeline
+
+When a squad revolves around a specific person's methodology — a creator, strategist, or thought leader — AIOSON can profile them and inject their cognitive fingerprint into the squad.
+
+```
+@genome --type=persona --person="Alex Hormozi"
+         │
+         ▼ @profiler-researcher
+   Web research, books, interviews, frameworks collected
+         │
+         ▼ @profiler-enricher
+   Cognitive analysis, psychometric profiling
+   DISC profile, Enneagram, Big Five, MBTI mapped
+         │
+         ▼ @profiler-forge
+   .aioson/profiler-reports/alex-hormozi/enriched-profile.md
+   genome-alex-hormozi.md (Genome 3.0)
+         │
+         ▼ applied to @copywriter in your squad
+   @copywriter now reasons with Hormozi's offer-framing mental models
+```
+
+Genome 3.0 fields include `disc`, `enneagram`, `big_five`, `mbti`, `confidence`, and `hybrid_mode` — so you know exactly how confident the profiling is and where it was inferred vs. evidence-based.
+
+---
+
+### DISC behavioral profiles
+
+Every squad executor can be assigned a behavioral profile so its communication style, decision speed, and conflict resolution match the squad's dynamics:
+
+| Profile | Traits | Best for |
+|---------|--------|----------|
+| `dominant-driver` | Direct, fast, results-first | Execution agents, sprint leads |
+| `influential-expressive` | Persuasive, creative, high energy | Content creators, copywriters |
+| `steady-amiable` | Patient, empathetic, consensus-driven | Reviewers, QA, support agents |
+| `compliant-analytical` | Precise, systematic, risk-aware | Analysts, architects, legal review |
+| + 4 hybrid combinations | — | — |
+
+---
+
+### Ephemeral squads
+
+Need a quick throwaway team for a one-off task?
+
+```bash
+@squad --ephemeral
+> domain: competitive analysis for this pitch
+> ttl: 24h
+```
+
+Ephemeral squads skip the full design-doc flow, use a timestamped slug, and self-expire after the TTL. They never pollute `CLAUDE.md` or `AGENTS.md`. Use them for research sessions, quick drafts, or exploratory tasks.
+
+---
+
+### Cross-squad orchestration
+
+Multiple squads can run in parallel in the same project. When an executor from one squad encounters a task outside its domain, it routes to the right sibling squad automatically — no manual handoff needed.
+
+```
+project/
+  .aioson/squads/
+    content-squad/      @scriptwriter, @hook-analyst, @orchestrator
+    dev-squad/          @architect, @dev, @qa, @orchestrator
+    legal-squad/        @risk-analyst, @clause-reviewer, @orchestrator
+
+# @scriptwriter receives a question about the privacy policy clause in a script
+→ cross-squad router detects: legal domain
+→ hands off to @clause-reviewer in legal-squad
+→ returns answer to content-squad session
+```
+
+The orchestrator of each squad knows its siblings, reads their manifests, and routes out-of-domain requests rather than silently absorbing them or hallucinating an answer.
+
+---
+
+### Webhook integration — trigger squads from anywhere
+
+AIOSON ships a built-in HTTP webhook server. External systems — WhatsApp, Telegram, Slack, ERPs — can trigger any squad and receive async responses via callback.
+
+```bash
+aioson squad:webhook start --squad=content-squad --port=3100
+```
+
+```
+[WhatsApp message]  →  POST /trigger  →  squad executes
+                                              ↓
+[user receives reply]  ←  POST callback_url  ←  async response
+```
+
+**Endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/trigger` | Async execution with callback URL + exponential backoff retry |
+| `GET` | `/status/:run_id` | Poll run status |
+| `POST` | `/query` | Sync execution (10s timeout) |
+| `GET` | `/health` | Server health check |
+
+Bearer token auth and rate limiting (60 req/min/IP) ship out of the box. No extra dependencies — pure `node:http`.
+
+---
+
+### Squad Dashboard
+
+Real-time web panel for monitoring all your squads. Ships with AIOSON, zero extra install.
+
+```bash
+aioson squad:dashboard              # → http://localhost:4180
+aioson squad:dashboard --squad=content-squad   # jump to a specific squad
+aioson squad:dashboard --port=4200  # custom port
+```
+
+**What the dashboard shows:**
+- Active agents and their current task
+- Context usage per agent with warning indicators
+- Token consumption over time
+- Execution logs and milestone history
+- Squad health score and ROI metrics
+- Cross-squad pipeline status
+
+Run multiple projects simultaneously on different ports — one dashboard per project.
+
+---
+
+### Squad commands reference
+
+<details>
+<summary><strong>Lifecycle — create, validate, maintain</strong></summary>
+
+```bash
+aioson squad:create <slug>          # create a new squad
+aioson squad:validate <slug>        # validate manifest, agents, and output config
+aioson squad:analyze <slug>         # deep analysis of squad health and coverage
+aioson squad:extend <slug>          # add executors or skills to existing squad
+aioson squad:repair <slug>          # fix broken genomes, missing agents, schema drift
+aioson squad:export <slug>          # export squad as portable package
+aioson squad:deploy <slug>          # deploy squad to target environment
+```
+
+</details>
+
+<details>
+<summary><strong>Execution — run, plan, orchestrate</strong></summary>
+
+```bash
+aioson squad:plan <slug>            # generate execution plan before running
+aioson squad:worker <slug>          # start a squad worker process
+aioson squad:daemon <slug>          # run squad as background daemon
+aioson squad:processes <slug>       # list running squad processes
+aioson squad:worktrees <slug>       # parallel git worktrees per worker
+aioson squad:merge <slug>           # merge worktree branches back
+```
+
+</details>
+
+<details>
+<summary><strong>Intelligence — genome, learning, profiling</strong></summary>
+
+```bash
+aioson squad:mcp <slug>             # MCP connector registry for squad
+aioson squad:learning <slug>        # review and apply learning from past sessions
+aioson squad:score <slug>           # quality and coverage score
+aioson squad:roi <slug>             # ROI metrics from session history
+aioson squad:investigate <domain>   # domain investigation before squad design
+aioson squad:agent-create <slug>    # create a custom agent inside a squad
+```
+
+</details>
+
+<details>
+<summary><strong>Integration — pipelines, webhooks, recovery</strong></summary>
+
+```bash
+aioson squad:pipeline <slug>        # inter-squad DAG pipeline with ports
+aioson squad:webhook start          # HTTP webhook server for external triggers
+aioson squad:recovery <slug>        # recover interrupted squad session
+aioson squad:dashboard              # real-time web monitoring panel
+```
+
+</details>
+
+---
+
+## Agents
+
+| Agent | Role | Best for |
+|-------|------|----------|
+| `/setup` | Project onboarding & context | First step on any project |
+| `/analyst` | Domain discovery & entity mapping | Understanding the problem space |
+| `/architect` | Project structure & technical decisions | Architecture, stack choices |
+| `/product` | Product decisions & PRD | Feature scope, user stories |
+| `/ux-ui` | UI/UX design system & component specs | Dashboards, flows, components |
+| `/pm` | Backlog & user stories | Sprint planning, task breakdown |
+| `/deyvin` / `/pair` | Feature implementation | Coding — greenfield or brownfield |
+| `/dev` | Feature implementation (any stack) | Focused dev tasks |
+| `/qa` | Risk-first review & test generation | Quality gates before ship |
+| `/orchestrator` | Session protocol & parallel execution | Multi-agent coordination |
+| `/squad` | Parallel agent squads | Large feature sets in parallel |
+| `/genome` | Agent knowledge & learning | Adaptive squad intelligence |
+| `/sheldon` | Deep technical reasoning | Hard engineering problems |
+| `/orache` | Orchestration & routing | Complex multi-step pipelines |
+| `/profiler-researcher` | Research & profiling | External data gathering |
+| `/profiler-enricher` | Profile enrichment | Data augmentation |
+| `/profiler-forge` | Profile generation | Structured output creation |
+| `/site-forge` | Site cloning & design extraction | Clone, harvest, blend, or forge skills from any URL |
+
+---
+
+## Quick start
+
+```bash
+# Install globally
+npm install -g @jaimevalasek/aioson
+
+# New project
+aioson init my-project
+
+# Existing project
+cd my-project
+aioson install .
+
+# One-off (no global install)
+npx @jaimevalasek/aioson init my-project
+```
+
+Then open your AI client and activate an agent:
+
+```bash
+# See all agents and their activation prompts
+aioson agents
+
+# Get the activation prompt for any agent
+aioson agent:prompt setup --tool=claude
+
+# See the recommended agent sequence for your project size
+aioson workflow:plan --classification=SMALL
+```
+
+---
 
 ## Requirements
 
@@ -8,239 +567,191 @@ AI operating framework for hyper-personalized software.
 
 | Requirement | Version | Notes |
 |-------------|---------|-------|
-| Node.js | ≥ 18.0.0 | Required by the CLI itself |
-| An AI CLI tool | — | At least one: [Claude Code](https://claude.ai/code), [Codex CLI](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [OpenCode](https://opencode.ai) |
+| Node.js | ≥ 18.0.0 | Required by the CLI |
+| An AI CLI tool | — | Claude Code, Codex CLI, Gemini CLI, or OpenCode |
 
 **Optional — by feature**
 
-| Feature | Extra requirement |
-|---------|-------------------|
-| `scan:project` (brownfield scanner) | `aioson-models.json` with a cheap LLM API key (DeepSeek, OpenAI, Gemini, Groq, Together, Mistral, or Anthropic) |
-| `qa:run` / `qa:scan` (browser QA) | Playwright + Chromium: `npm install -g playwright && npx playwright install chromium` |
-| `mcp:init` / `mcp:doctor` | MCP-compatible tool (Claude Code, Gemini CLI, OpenCode, or Codex CLI with MCP support) |
-| Web3 support | Project must use a supported chain toolchain (Hardhat, Foundry, Anchor, etc.) |
+| Feature | Requirement |
+|---------|-------------|
+| `scan:project` — brownfield scanner | `aioson-models.json` with a cheap LLM API key (DeepSeek, OpenAI, Gemini, Groq, Together, Mistral, or Anthropic) |
+| `qa:run` / `qa:scan` — browser QA | `npm install -g playwright && npx playwright install chromium` |
+| `mcp:init` / `mcp:doctor` | MCP-compatible tool (Claude Code, Gemini CLI, OpenCode, or Codex CLI) |
+| Web3 support | Hardhat, Foundry, Anchor, or other supported chain toolchain |
+
+---
+
+## Tracked live sessions
 
-## Install
+AIOSON can track every AI session with full runtime observability — useful when working from external clients like Claude Code, Codex CLI, or Gemini CLI.
 
 ```bash
-npm install -g @jaimevalasek/aioson
-# then use:
-aioson init my-project
+# Open a tracked session before the AI client starts
+aioson live:start . --tool=claude --agent=deyvin --plan=plan.md --no-launch
 
-# one-off execution without global install
-npx @jaimevalasek/aioson init my-project
-# or
-npx @jaimevalasek/aioson install
+# Emit milestones as work progresses
+aioson runtime:emit . --agent=deyvin --type=task_started --title="Fix stock modal"
+aioson runtime:emit . --agent=deyvin --type=task_completed --summary="Stock modal fixed" --refs="src/app.js"
+
+# Hand off the session to another agent (keeps the same session envelope)
+aioson live:handoff . --agent=deyvin --to=qa --reason="Ready for review"
+
+# Monitor in real-time
+aioson live:status . --watch=2
+
+# Close and generate summary.md
+aioson live:close . --agent=qa --summary="QA complete, shipped"
 ```
 
-## Legacy projects and custom stacks
-You can run AIOSON on existing/legacy projects (not only new projects).
+---
+
+## Commands
+
+<details>
+<summary><strong>Setup & install</strong></summary>
 
 ```bash
-# inside an existing project
-npx @jaimevalasek/aioson install .
-aioson setup:context . --defaults --framework="CodeIgniter 3" --backend="CodeIgniter 3" --database="MySQL"
+aioson init <project-name> [--lang=en|pt-BR|es|fr] [--tool=codex|claude|gemini|opencode]
+aioson install [path] [--lang=en|pt-BR|es|fr] [--tool=codex|claude|gemini|opencode]
+aioson update [path] [--lang=en|pt-BR|es|fr]
+aioson info [path] [--json]
+aioson doctor [path] [--fix] [--dry-run] [--json]
+aioson setup:context [path] [--defaults] [--framework=<name>] [--lang=en|pt-BR|es|fr]
+aioson context:validate [path] [--json]
+aioson scan:project [path] [--provider=<name>] [--dry-run] [--json]
+```
+
+</details>
 
-# generate discovery.md + skeleton-system.md using a cheap LLM (saves tokens in your AI session)
-# requires aioson-models.json with your API key
-aioson scan:project
+<details>
+<summary><strong>Agents & workflow</strong></summary>
+
+```bash
+aioson agents
+aioson agent:prompt <agent> [--tool=codex|claude|gemini|opencode]
+aioson workflow:plan [path] [--classification=MICRO|SMALL|MEDIUM] [--json]
 ```
 
-If your stack is not listed in menus, use free-text values via `--framework`, `--backend`, `--frontend`, `--database`, `--auth`, and `--uiux`.
+</details>
 
-The npm package is scoped as `@jaimevalasek/aioson`, but the installed CLI commands remain `aioson` and `aios`.
+<details>
+<summary><strong>Parallel orchestration</strong></summary>
 
-## Commands
+```bash
+aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json]
+aioson parallel:assign [path] [--source=auto|prd|architecture|discovery|<file>] [--workers=2..6]
+aioson parallel:status [path] [--json]
+aioson parallel:doctor [path] [--workers=2..6] [--fix] [--force] [--dry-run] [--json]
+```
 
-**Setup and install**
-- [`aioson init`](docs/en/cli-reference.md#init) `<project-name> [--lang=en|pt-BR|es|fr] [--tool=codex|claude|gemini|opencode]`
-- [`aioson install`](docs/en/cli-reference.md#install) `[path] [--lang=en|pt-BR|es|fr] [--tool=codex|claude|gemini|opencode]`
-- [`aioson update`](docs/en/cli-reference.md#update) `[path] [--lang=en|pt-BR|es|fr]`
-- [`aioson info`](docs/en/cli-reference.md#info) `[path] [--json]`
-- [`aioson doctor`](docs/en/cli-reference.md#doctor) `[path] [--fix] [--dry-run] [--json]`
-- [`aioson setup:context`](docs/en/cli-reference.md#setupcontext) `[path] [--defaults] [--framework=<name>] [--lang=en|pt-BR|es|fr]`
-- [`aioson context:validate`](docs/en/cli-reference.md#contextvalidate) `[path] [--json]`
-- [`aioson scan:project`](docs/en/cli-reference.md#scanproject) `[path] [--provider=<name>] [--dry-run] [--json]`
-
-**Agents**
-- [`aioson agents`](docs/en/cli-reference.md#agents)
-- [`aioson agent:prompt`](docs/en/cli-reference.md#agentprompt) `<agent> [--tool=codex|claude|gemini|opencode]`
-- [`aioson workflow:plan`](docs/en/cli-reference.md#workflowplan) `[path] [--classification=MICRO|SMALL|MEDIUM] [--json]`
-
-**Tracked live sessions for external AI clients**
-- `aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<agent> [--plan=<file>] [--no-launch]`
-- `aioson runtime:emit [path] --agent=<agent> --type=task_started|task_completed|milestone|correction|block|plan_checkpoint --summary="..."`
-- `aioson live:handoff [path] --agent=<agent> --to=<next-agent> --reason="..."`
-- `aioson live:status [path] [--agent=<agent>] [--watch=2] [--json]`
-- `aioson live:close [path] [--agent=<agent>] [--status=completed|failed] --summary="..."`
-
-**Locale**
-- [`aioson i18n:add`](docs/en/i18n.md#create-a-locale-scaffold) `<locale>`
-- [`aioson locale:apply`](docs/en/i18n.md#apply-localized-agent-prompts) `[path] [--lang=en|pt-BR|es|fr]`
-
-**Parallel orchestration**
-- [`aioson parallel:init`](docs/en/parallel.md) `[path] [--workers=2..6] [--force] [--dry-run] [--json]`
-- [`aioson parallel:assign`](docs/en/parallel.md#scope-assignment) `[path] [--source=auto|prd|architecture|discovery|<file>] [--workers=2..6] [--force] [--dry-run] [--json]`
-- [`aioson parallel:status`](docs/en/parallel.md#status-overview) `[path] [--json]`
-- [`aioson parallel:doctor`](docs/en/parallel.md#diagnose-and-repair) `[path] [--workers=2..6] [--fix] [--force] [--dry-run] [--json]`
-
-**MCP**
-- [`aioson mcp:init`](docs/en/mcp.md#mcpinit) `[path] [--tool=claude|codex|gemini|opencode] [--dry-run] [--json]`
-- [`aioson mcp:doctor`](docs/en/mcp.md#mcpdoctor) `[path] [--strict-env] [--json]`
-
-**Browser QA (Playwright)**
-- [`aioson qa:init`](docs/en/qa-browser.md#qainit) `[path] [--url=<app-url>] [--dry-run] [--json]`
-- [`aioson qa:doctor`](docs/en/qa-browser.md#qadoctor) `[path] [--json]`
-- [`aioson qa:run`](docs/en/qa-browser.md#qarun) `[path] [--url=<app-url>] [--persona=naive|hacker|power|mobile] [--headed] [--html] [--json]`
-- [`aioson qa:scan`](docs/en/qa-browser.md#qascan) `[path] [--url=<app-url>] [--depth=3] [--max-pages=50] [--headed] [--html] [--json]`
-- [`aioson qa:report`](docs/en/qa-browser.md#qareport) `[path] [--html] [--json]`
-
-**Testing and validation (CI / contributors)**
-- [`aioson test:smoke`](docs/en/cli-reference.md#testsmoke) `[workspace-path] [--lang=en|pt-BR|es|fr] [--web3=ethereum|solana|cardano] [--profile=standard|mixed|parallel] [--keep] [--json]`
-- [`aioson test:package`](docs/en/cli-reference.md#testpackage) `[source-path] [--keep] [--dry-run] [--json]`
-
-## Agent usage helper
-
-If your AI CLI does not show a visual agent picker, these commands let you interact with agents directly from the terminal. See the [CLI reference](docs/en/cli-reference.md) for full docs on each.
-
-**Discover agents**
-- [`aioson agents`](docs/en/cli-reference.md#agents) — list all agents and their paths
-- [`aioson agent:prompt setup --tool=codex`](docs/en/cli-reference.md#agentprompt) — get activation prompt for any agent
-- [`aioson workflow:plan --classification=SMALL`](docs/en/cli-reference.md#workflowplan) — see the recommended agent sequence
-
-**Tracked live session flow**
-- `aioson live:start . --tool=codex --agent=deyvin --plan=plan.md --no-launch` — open a tracked session envelope before the AI client starts working
-- `aioson runtime:emit . --agent=deyvin --type=task_started --title="Fix stock modal"` — mark the start of a visible work slice
-- `aioson runtime:emit . --agent=deyvin --type=task_completed --summary="Stock modal fixed" --refs="src/app.js,src/styles.css"` — register a completed slice
-- `aioson live:handoff . --agent=deyvin --to=product --reason="Scope needs product decision"` — keep the same live session and switch active AIOSON agent
-- `aioson live:status . --agent=product --watch=2` — monitor status, active agent, plan progress, and process liveness
-- `aioson live:close . --agent=product --summary="Session closed"` — finish the session and generate `summary.md`
-
-**Setup and locale**
-- [`aioson init my-project --lang=pt-BR --tool=codex`](docs/en/cli-reference.md#init)
-- [`aioson install --lang=es --tool=claude`](docs/en/cli-reference.md#install)
-- [`aioson update --lang=fr`](docs/en/cli-reference.md#update)
-- [`aioson locale:apply --lang=pt-BR`](docs/en/i18n.md#apply-localized-agent-prompts)
-
-**Maintenance**
-- [`aioson doctor --fix`](docs/en/cli-reference.md#doctor) — restore any missing managed files
-
-**Parallel orchestration**
-- [`aioson parallel:init --workers=3`](docs/en/parallel.md)
-- [`aioson parallel:assign --source=architecture --workers=3`](docs/en/parallel.md#scope-assignment)
-- [`aioson parallel:status`](docs/en/parallel.md#status-overview)
-- [`aioson parallel:doctor --fix --dry-run`](docs/en/parallel.md#diagnose-and-repair)
-
-**MCP**
-- [`aioson mcp:init --dry-run`](docs/en/mcp.md#mcpinit)
-- [`aioson mcp:doctor --strict-env`](docs/en/mcp.md#mcpdoctor)
-
-**Browser QA**
-- [`aioson qa:init --url=http://localhost:3000`](docs/en/qa-browser.md#qainit)
-- [`aioson qa:doctor`](docs/en/qa-browser.md#qadoctor)
-- [`aioson qa:run --persona=hacker`](docs/en/qa-browser.md#qarun)
-- [`aioson qa:run --html`](docs/en/qa-browser.md#html-reports) — visual HTML report in `reports/`
-- [`aioson qa:scan --depth=2 --max-pages=30`](docs/en/qa-browser.md#qascan)
-- [`aioson qa:report --html`](docs/en/qa-browser.md#html-reports) — retroactive HTML from last run
-- [`aioson qa:report`](docs/en/qa-browser.md#qareport)
-
-**Integration tests (CI)**
-- [`aioson test:smoke --lang=pt-BR`](docs/en/cli-reference.md#testsmoke)
-- [`aioson test:smoke --web3=ethereum`](docs/en/cli-reference.md#testsmoke)
-- [`aioson test:smoke --profile=parallel`](docs/en/cli-reference.md#testsmoke)
-- [`aioson test:package --dry-run`](docs/en/cli-reference.md#testpackage)
-
-Default planning includes `@product` → UI/UX (`@ux-ui`) for SMALL/MEDIUM projects.
+</details>
 
-## JSON output for CI
-Use `--json` on selected commands. See [JSON schemas](docs/en/json-schemas.md) for output contracts.
-- `aioson init <project-name> --json`
-- `aioson install [path] --json`
-- `aioson update [path] --json`
-- `aioson agents [path] --json`
-- `aioson agent:prompt <agent> [path] --json`
-- `aioson locale:apply [path] --json`
-- `aioson setup:context [path] --defaults --json`
-- `aioson i18n:add <locale> --dry-run --json`
-- `aioson info --json`
-- `aioson doctor --json`
-- `aioson context:validate --json`
-- `aioson test:smoke --json`
-- `aioson parallel:init --json`
-- `aioson parallel:assign --json`
-- `aioson parallel:status --json`
-- `aioson parallel:doctor --json`
-- `aioson mcp:doctor --json`
-- `aioson qa:run --json`
-- `aioson qa:scan --json`
-- `aioson qa:doctor --json`
-- `aioson qa:report --json`
-- `aioson scan:project --json`
-
-## i18n
-CLI localization is supported with:
-- `--locale=<code>`
-- `AIOS_LITE_LOCALE=<code>`
-
-Built-in locales: `en`, `pt-BR`, `es`, `fr`.
-Default locale is `en`.
-`pt`, `pt_br`, and `pt-BR` resolve to the same Portuguese dictionary.
-`es-*` resolves to `es`, and `fr-*` resolves to `fr`.
-Localized agent packs are built-in for `en`, `pt-BR`, `es`, and `fr`.
-
-Generate a new locale scaffold:
+<details>
+<summary><strong>MCP</strong></summary>
 
 ```bash
-aioson i18n:add fr
+aioson mcp:init [path] [--tool=claude|codex|gemini|opencode] [--dry-run] [--json]
+aioson mcp:doctor [path] [--strict-env] [--json]
 ```
 
+`mcp:init` generates `.aioson/mcp/servers.local.json` and tool-specific preset templates. Supports Context7 and Database MCP in remote-endpoint mode.
+
+</details>
+
+<details>
+<summary><strong>Browser QA (Playwright)</strong></summary>
+
+```bash
+aioson qa:init [path] [--url=<app-url>] [--dry-run] [--json]
+aioson qa:run [path] [--url=<app-url>] [--persona=naive|hacker|power|mobile] [--headed] [--html] [--json]
+aioson qa:scan [path] [--url=<app-url>] [--depth=3] [--max-pages=50] [--headed] [--html] [--json]
+aioson qa:report [path] [--html] [--json]
+aioson qa:doctor [path] [--json]
+```
+
+</details>
+
+<details>
+<summary><strong>i18n & locale</strong></summary>
+
+```bash
+aioson i18n:add <locale>
+aioson locale:apply [path] [--lang=en|pt-BR|es|fr]
+```
+
+Built-in locales: `en`, `pt-BR`, `es`, `fr`. Use `--lang` or `AIOS_LITE_LOCALE` env var.
+
+</details>
+
+<details>
+<summary><strong>Testing & CI</strong></summary>
+
+```bash
+aioson test:smoke [workspace-path] [--lang=en|pt-BR|es|fr] [--web3=ethereum|solana|cardano] [--profile=standard|mixed|parallel] [--keep] [--json]
+aioson test:package [source-path] [--keep] [--dry-run] [--json]
+```
+
+</details>
+
+---
+
 ## Multi-IDE support
-- Claude Code (`CLAUDE.md`)
-- Codex CLI (`AGENTS.md`)
-- Gemini CLI (`.gemini/GEMINI.md`)
-- OpenCode (`OPENCODE.md`)
+
+| IDE / Client | Config file |
+|--------------|-------------|
+| Claude Code | `CLAUDE.md` |
+| Codex CLI | `AGENTS.md` |
+| Gemini CLI | `.gemini/GEMINI.md` |
+| OpenCode | `OPENCODE.md` |
+
+---
 
 ## Web3 support
-See the [Web3 guide](docs/en/web3.md) for the full reference.
-- `project_type=dapp` is supported in context validation and setup.
-- Framework detection now includes:
-  - Ethereum: `Hardhat`, `Foundry`, `Truffle`
-  - Solana: `Anchor`, `Solana Web3`
-  - Cardano: `Cardano` (Aiken/Cardano SDK signals)
-- `setup:context` supports Web3 fields:
-  - `--web3-enabled=true|false`
-  - `--web3-networks=ethereum,solana`
-  - `--contract-framework=Hardhat`
-  - `--wallet-provider=wagmi`
-  - `--indexer=The Graph`
-  - `--rpc-provider=Alchemy`
-
-## Docs
-
-**CLI reference**
-- [CLI reference](docs/en/cli-reference.md) — `init`, `install`, `update`, `info`, `doctor`, `setup:context`, `context:validate`, `agents`, `agent:prompt`, `workflow:plan`, `test:smoke`, `test:package`
+
+Supports `project_type=dapp` with detection for Ethereum (Hardhat, Foundry, Truffle), Solana (Anchor, Solana Web3), and Cardano (Aiken/Cardano SDK).
+
+```bash
+aioson setup:context . \
+  --web3-enabled=true \
+  --web3-networks=ethereum,solana \
+  --contract-framework=Hardhat \
+  --wallet-provider=wagmi \
+  --indexer="The Graph" \
+  --rpc-provider=Alchemy
+```
+
+See the [Web3 guide](docs/en/web3.md) for full details.
+
+---
+
+## JSON output for CI
+
+Most commands support `--json` for structured output. See [JSON schemas](docs/en/json-schemas.md) for contracts.
+
+```bash
+aioson info --json
+aioson doctor --json
+aioson agents --json
+aioson parallel:status --json
+aioson qa:run --json
+aioson scan:project --json
+```
+
+---
+
+## Documentation
+
+**CLI & commands**
+- [CLI reference](docs/en/cli-reference.md) — full docs for every command
+- [JSON schemas](docs/en/json-schemas.md) — `--json` output contracts
 
 **Feature guides**
-- [i18n guide](docs/en/i18n.md) — `i18n:add`, `locale:apply`, locale resolution
-- [Parallel orchestration](docs/en/parallel.md) — `parallel:init`, `parallel:assign`, `parallel:status`, `parallel:doctor`
-- [MCP guide](docs/en/mcp.md) — `mcp:init`, `mcp:doctor`
-- [Browser QA guide](docs/en/qa-browser.md) — `qa:init`, `qa:doctor`, `qa:run`, `qa:scan`, `qa:report`
-- [Web3 guide](docs/en/web3.md) — `project_type=dapp`, framework detection, Web3 context fields
-- [JSON schemas](docs/en/json-schemas.md) — `--json` output contracts for all commands
-- [AI clients guide (PT-BR)](docs/pt/clientes-ai.md) — tracked usage with Codex, Claude, Gemini, and OpenCode
-- [Runtime observability (PT-BR)](docs/pt/runtime-observability.md) — `live:start`, `runtime:emit`, `live:handoff`, `live:status`, `live:close`, and dashboard projections
-- [Squad Dashboard](docs/en/squad-dashboard.md) — `squad:dashboard`, real-time monitoring of agents, context, tokens, logs and metrics
-- [Session recovery (PT-BR)](docs/pt/recuperacao-de-sessao.md) — `recovery:generate`, `recovery:show`, restore context after compaction
-- [Context monitor (PT-BR)](docs/pt/monitor-de-contexto.md) — `context:monitor`, usage bars and warning levels per agent
-- [Context search (PT-BR)](docs/pt/busca-de-contexto.md) — `context:search`, `context:search:index`, FTS5 full-text search
-- [Context cache (PT-BR)](docs/pt/cache-de-contexto.md) — `context:cache`, save and restore session snapshots
-- [Sandbox executor (PT-BR)](docs/pt/sandbox.md) — `sandbox:exec`, safe execution with secret redaction and timeout
-- [Agent sharding (PT-BR)](docs/pt/agent-sharding.md) — `agent:load`, `agent:shard:index`, load only relevant agent instruction sections
-
-**Release (internal)**
-- [Release guide](docs/en/release.md)
-- [Release flow](docs/en/release-flow.md)
-- [Release notes template](docs/en/release-notes-template.md)
+- [Parallel orchestration](docs/en/parallel.md)
+- [MCP guide](docs/en/mcp.md)
+- [Browser QA guide](docs/en/qa-browser.md)
+- [Web3 guide](docs/en/web3.md)
+- [i18n guide](docs/en/i18n.md)
+- [Squad Dashboard](docs/en/squad-dashboard.md)
 
 **Portuguese guides**
 - [Início rápido](docs/pt/inicio-rapido.md)
@@ -248,32 +759,18 @@ See the [Web3 guide](docs/en/web3.md) for the full reference.
 - [Squad e Genome](docs/pt/squad-genome.md)
 - [Cenários de uso](docs/pt/cenarios.md)
 - [Clientes AI](docs/pt/clientes-ai.md)
+- [Runtime observability](docs/pt/runtime-observability.md)
+- [Recuperação de sessão](docs/pt/recuperacao-de-sessao.md)
+- [Monitor de contexto](docs/pt/monitor-de-contexto.md)
+- [Busca de contexto](docs/pt/busca-de-contexto.md)
+- [Cache de contexto](docs/pt/cache-de-contexto.md)
+- [Sandbox executor](docs/pt/sandbox.md)
+- [Agent sharding](docs/pt/agent-sharding.md)
 - [Guia do engenheiro](docs/pt/guia-engineer.md)
-- [Squad Dashboard](docs/pt/squad-dashboard.md) — monitoramento em tempo real de agentes, contexto, tokens, logs e métricas
+- [Squad Dashboard (PT)](docs/pt/squad-dashboard.md)
 
-## MCP bootstrap
-Generate a local MCP server recommendation file from `project.context.md`:
-
-```bash
-aioson mcp:init
-aioson mcp:init --dry-run
-aioson mcp:init --tool=codex
-aioson mcp:doctor
-aioson mcp:doctor --strict-env
-```
-
-`mcp:init` generates:
-- `.aioson/mcp/servers.local.json` (project MCP plan)
-- `.aioson/mcp/presets/<tool>.json` (tool-specific preset templates)
-- Context7/Database presets in remote-endpoint mode (`mcp-remote`) using:
-  - `CONTEXT7_MCP_URL`
-  - `DATABASE_MCP_URL` (when database MCP is enabled)
-
-`mcp:doctor` validates:
-- core MCP servers (`filesystem`, `context7`)
-- preset coverage
-- required env vars from enabled servers
-- context compatibility for database and Web3 (`chain-rpc`)
+---
 
 ## License
-GNU Affero General Public License v3.0 (`AGPL-3.0-only`)
+
+[AGPL-3.0-only](LICENSE) — GNU Affero General Public License v3.0