@jaimevalasek/aioson 1.3.0

package/README.md

@@ -0,0 +1,254 @@
+# AIOSON
+
+AI operating framework for hyper-personalized software.
+
+## Requirements
+
+**Core**
+
+| 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) |
+
+**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.) |
+
+## Install
+
+```bash
+npm install -g @jaimevalasek/aioson
+# then use:
+aioson init my-project
+
+# one-off execution without global install
+npx @jaimevalasek/aioson init my-project
+# or
+npx @jaimevalasek/aioson install
+```
+
+## Legacy projects and custom stacks
+You can run AIOSON on existing/legacy projects (not only new projects).
+
+```bash
+# inside an existing project
+npx @jaimevalasek/aioson install .
+aioson setup:context . --defaults --framework="CodeIgniter 3" --backend="CodeIgniter 3" --database="MySQL"
+
+# 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
+```
+
+If your stack is not listed in menus, use free-text values via `--framework`, `--backend`, `--frontend`, `--database`, `--auth`, and `--uiux`.
+
+The npm package is scoped as `@jaimevalasek/aioson`, but the installed CLI commands remain `aioson` and `aios`.
+
+## Commands
+
+**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]`
+
+**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
+
+**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` → `@ux-ui` for SMALL/MEDIUM projects.
+
+## 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:
+
+```bash
+aioson i18n:add fr
+```
+
+## Multi-IDE support
+- 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`
+
+**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
+
+**Release (internal)**
+- [Release guide](docs/en/release.md)
+- [Release flow](docs/en/release-flow.md)
+- [Release notes template](docs/en/release-notes-template.md)
+
+**Portuguese guides**
+- [Início rápido](docs/pt/inicio-rapido.md)
+- [Guia de agentes](docs/pt/agentes.md)
+- [Squad e Genoma](docs/pt/squad-genoma.md)
+- [Cenários de uso](docs/pt/cenarios.md)
+- [Clientes AI](docs/pt/clientes-ai.md)
+- [Guia do engenheiro](docs/pt/guia-engineer.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
+MIT

package/bin/aioson.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/cli.js');

package/docs/en/cli-reference.md

@@ -0,0 +1,398 @@
+# CLI Reference
+
+Complete reference for all `aioson` commands.
+
+---
+
+## init
+
+Create a new project directory and install AIOSON inside it.
+
+```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
+```
+
+**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`.
+- `--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`).
+
+---
+
+## install
+
+Install AIOSON in an existing directory (or the current directory).
+
+```bash
+aioson install
+aioson install ./my-project
+aioson install --lang=pt-BR --tool=claude
+```
+
+**Options:** same as `init`.
+
+**Use this when:**
+- The project already exists (legacy codebase, existing repo).
+- You want to add AIOSON to a monorepo package.
+
+---
+
+## update
+
+Update managed files to the latest template version. Preserves context files and anything not in the managed file list.
+
+```bash
+aioson update
+aioson update ./my-project
+aioson update --lang=pt-BR
+```
+
+**Options:**
+- `--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.
+
+---
+
+## info
+
+Show CLI version, installation status, and detected framework for a directory.
+
+```bash
+aioson info
+aioson info ./my-project
+aioson info --json
+```
+
+**Output:**
+```
+aioson v0.1.25
+Directory: /path/to/my-project
+Installed here: yes
+Framework detected: Laravel
+Evidence: composer.json, artisan
+```
+
+**With `--json`:**
+```json
+{
+  "ok": true,
+  "version": "0.1.25",
+  "targetDir": "/path/to/my-project",
+  "installed": true,
+  "detection": {
+    "framework": "Laravel",
+    "evidence": "composer.json, artisan"
+  }
+}
+```
+
+---
+
+## doctor
+
+Verify that all managed files are present and valid. Use `--fix` to restore any missing files.
+
+```bash
+aioson doctor
+aioson doctor ./my-project
+aioson doctor --fix
+aioson doctor --fix --dry-run
+aioson doctor --json
+```
+
+**Options:**
+- `--fix` — copies missing managed files from the template. Does not overwrite existing files.
+- `--dry-run` — shows what `--fix` would do without making changes.
+- `--json` — structured JSON output with per-check results.
+
+**Checks performed:**
+- All files in `MANAGED_FILES` exist.
+- Gateway files (`CLAUDE.md`, `AGENTS.md`, `OPENCODE.md`, `.gemini/GEMINI.md`) are present.
+- `.aioson/agents/` directory is populated.
+- `.aioson/context/` directory exists.
+
+**Typical workflow after an update:**
+```bash
+aioson update
+aioson doctor --fix
+```
+
+---
+
+## setup:context
+
+Interactive wizard that creates `.aioson/context/project.context.md`. This is the main context file that all agents read.
+
+```bash
+# Interactive mode
+aioson setup:context
+
+# Non-interactive (CI / scripted)
+aioson setup:context --defaults
+aioson setup:context --defaults --framework="Laravel" --backend="PHP" --database="MySQL"
+aioson setup:context --defaults --framework="Next.js" --frontend="React" --lang=pt-BR
+```
+
+**Non-interactive flags:**
+- `--defaults` — skips all prompts, uses detected or provided values.
+- `--framework=<name>` — e.g. `"Laravel"`, `"Next.js"`, `"Django"`, `"Hardhat"`. Any free-text value accepted.
+- `--backend=<name>` — e.g. `"PHP"`, `"Python"`, `"Node.js"`.
+- `--frontend=<name>` — e.g. `"React"`, `"Vue"`, `"Livewire"`.
+- `--database=<name>` — e.g. `"PostgreSQL"`, `"MySQL"`, `"SQLite"`.
+- `--auth=<name>` — e.g. `"Laravel Breeze"`, `"JWT"`, `"None"`.
+- `--uiux=<name>` — e.g. `"Tailwind CSS"`, `"shadcn/ui"`.
+- `--classification=MICRO|SMALL|MEDIUM` — override the auto-calculated score.
+- `--profile=developer|beginner|team` — sets the AI interaction style.
+- `--lang=en|pt-BR|es|fr` — sets `conversation_language`.
+- `--json` — structured JSON output.
+
+**Web3 flags:**
+- `--web3-enabled=true|false`
+- `--web3-networks=ethereum,solana`
+- `--contract-framework=Hardhat`
+- `--wallet-provider=wagmi`
+- `--indexer="The Graph"`
+- `--rpc-provider=Alchemy`
+
+**Brownfield / legacy project example:**
+```bash
+aioson install .
+aioson setup:context --defaults --framework="CodeIgniter 3" --backend="PHP" --database="MySQL"
+```
+
+---
+
+## context:validate
+
+Validate the existing `project.context.md` file — checks YAML frontmatter structure, required fields, and allowed values.
+
+```bash
+aioson context:validate
+aioson context:validate ./my-project
+aioson context:validate --json
+```
+
+**What it validates:**
+- File exists at `.aioson/context/project.context.md`.
+- YAML frontmatter is parseable.
+- All required fields are present: `project_name`, `project_type`, `profile`, `framework`, `framework_installed`, `classification`, `conversation_language`, `aioson_version`.
+- `project_type` is one of: `web_app`, `api`, `site`, `script`, `dapp`.
+- `classification` is one of: `MICRO`, `SMALL`, `MEDIUM`.
+- `profile` is one of: `developer`, `beginner`, `team`.
+
+**Typical use:** run after manually editing `project.context.md` to confirm it's still valid.
+
+```bash
+# edit project.context.md
+aioson context:validate
+# ✓ project.context.md is valid
+```
+
+---
+
+## agents
+
+List all registered agents with their paths, dependencies, and outputs.
+
+```bash
+aioson agents
+aioson agents ./my-project
+aioson agents --json
+```
+
+**Output example:**
+```
+Agents (locale: en):
+@setup (setup)
+  Path: .aioson/locales/en/agents/setup.md
+  Active: .aioson/agents/setup.md
+  Depends on: none
+  Output: .aioson/context/project.context.md
+
+@product (product)
+  Path: .aioson/locales/en/agents/product.md
+  Active: .aioson/agents/product.md
+  Depends on: none
+  Output: .aioson/context/prd.md
+...
+```
+
+The locale shown reflects the active agent locale pack (from `project.context.md` or the `--lang` flag).
+
+---
+
+## agent:prompt
+
+Print the activation prompt for a specific agent, ready to paste into any AI CLI that does not support slash commands.
+
+```bash
+aioson agent:prompt setup
+aioson agent:prompt setup --tool=codex
+aioson agent:prompt ux-ui --tool=claude
+aioson agent:prompt dev --tool=gemini --json
+```
+
+**Arguments:**
+- `<agent>` — agent id: `setup`, `product`, `analyst`, `architect`, `ux-ui`, `pm`, `dev`, `qa`, `orchestrator`.
+
+**Options:**
+- `--tool=codex|claude|gemini|opencode` — formats the prompt for the target CLI. Default: `codex`.
+- `--json` — returns structured JSON with the prompt string.
+
+**When to use:** if you're using an AI CLI that doesn't support `/setup` slash commands, run this to get the exact text to paste into the chat.
+
+```bash
+# Copy the prompt for @analyst in Gemini
+aioson agent:prompt analyst --tool=gemini
+# → paste the output into Gemini CLI
+```
+
+---
+
+## workflow:plan
+
+Show the recommended agent sequence for the current project based on its `classification`.
+
+```bash
+aioson workflow:plan
+aioson workflow:plan ./my-project
+aioson workflow:plan --classification=SMALL
+aioson workflow:plan --json
+```
+
+**Options:**
+- `--classification=MICRO|SMALL|MEDIUM` — override the value from `project.context.md`.
+- `--json` — structured JSON with `sequence`, `commands`, and `notes` arrays.
+
+**Output example:**
+```
+Workflow plan — SMALL:
+  @setup
+  @product
+  @analyst
+  @architect
+  @dev
+  @qa
+
+Notes:
+  — Framework not installed: agents will include installation steps.
+```
+
+**Sequences by classification:**
+- `MICRO`: `@setup → @product (optional) → @dev`
+- `SMALL`: `@setup → @product → @analyst → @architect → @dev → @qa`
+- `MEDIUM`: `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa`
+
+**Feature development workflow (after initial setup):**
+
+Once the project is set up, each new feature follows a shorter sequence — no `@setup` required:
+
+```
+@product → @analyst → @dev → @qa
+```
+
+`@product` creates a feature-scoped `prd-{slug}.md` and registers the feature in `features.md`. `@analyst` produces `requirements-{slug}.md` and `spec-{slug}.md`. `@dev` reads the feature spec. `@qa` closes the feature by updating `spec-{slug}.md` with a QA sign-off and marking it `done` in `features.md`.
+
+The `SMALL` and MEDIUM outputs include a note reminding you of this sequence.
+
+---
+
+## workflow:next
+
+Advance the active workflow, complete the current stage, trigger a controlled detour, or skip ahead until `@dev`.
+
+```bash
+aioson workflow:next
+aioson workflow:next ./my-project --tool=codex
+aioson workflow:next ./my-project --complete
+aioson workflow:next ./my-project --agent=ux-ui
+aioson workflow:next ./my-project --skip=dev
+```
+
+**What it does:**
+- initializes `.aioson/context/workflow.state.json` if it does not exist
+- infers the current project stage from existing artifacts like `project.context.md`, `prd.md`, `discovery.md`, and `architecture.md`
+- follows the default sequence by classification, or a custom `.aioson/context/workflow.config.json` if the project defines one
+- supports detours such as `--agent=ux-ui`, then returns to the saved next stage automatically
+- allows skipping ahead only until `@dev`; it never allows skipping past `@dev`
+
+**Notes:**
+- `workflow:next` is the canonical command
+- `agent:next` is an alias for compatibility
+- `workflow.config.json` and `workflow.state.json` live under `.aioson/context/`, so normal framework updates preserve them
+
+---
+
+## test:smoke
+
+End-to-end integration test that installs AIOSON in a temporary directory, runs all major commands, and verifies the output. Used for CI and release validation.
+
+```bash
+aioson test:smoke
+aioson test:smoke --lang=pt-BR
+aioson test:smoke --web3=ethereum
+aioson test:smoke --web3=solana
+aioson test:smoke --web3=cardano
+aioson test:smoke --profile=mixed
+aioson test:smoke --profile=parallel
+aioson test:smoke --keep
+aioson test:smoke --json
+```
+
+**Options:**
+- `--lang=en|pt-BR|es|fr` — runs the test with the given locale active.
+- `--web3=ethereum|solana|cardano` — seeds a Web3 project structure and tests Web3 context generation.
+- `--profile=standard|mixed|parallel` — `standard` runs the default flow; `mixed` runs a combined locale+web3 test; `parallel` includes `parallel:init` and `parallel:assign`.
+- `--keep` — preserves the temporary directory after the test for inspection.
+- `--json` — structured JSON output with per-step results.
+
+**What the standard profile tests:**
+1. `install` in temp dir
+2. `setup:context --defaults`
+3. `locale:apply`
+4. `agents` list
+5. `agent:prompt setup`
+6. `context:validate`
+7. `doctor`
+8. `update`
+9. `workflow:plan`
+
+**Note:** this command is intended for contributors and CI pipelines, not for daily project use.
+
+---
+
+## test:package
+
+Simulate `npm pack` in a temporary directory to verify what would be published and that the package installs correctly.
+
+```bash
+aioson test:package
+aioson test:package ./path/to/source
+aioson test:package --keep
+aioson test:package --dry-run
+aioson test:package --json
+```
+
+**Options:**
+- `--keep` — preserves the temp directory after the test.
+- `--dry-run` — checks prerequisites without actually running `npm pack`.
+- `--json` — structured JSON output.
+
+**What it does:**
+1. Runs `npm pack` on the source directory.
+2. Extracts the `.tgz` in a temporary directory.
+3. Verifies the key files are present in the package.
+4. Reports pass/fail.
+
+**Note:** requires Node.js and npm to be available. Intended for release validation.