@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/en/5-reference/i18n.md

@@ -0,0 +1,52 @@
+# i18n Guide
+
+AIOSON CLI supports localization through message dictionaries and a decoupled interaction language system.
+
+## How it works
+
+### CLI localization
+- Dictionaries are stored in `src/i18n/messages/`.
+- `src/i18n/index.js` resolves locale and fallback behavior.
+- Commands use translation keys instead of hardcoded strings.
+- The CLI locale is controlled by `--locale=<lang>` or `AIOS_LITE_LOCALE` env var.
+
+### Agent interaction language (decoupled)
+Agent instruction files are maintained in **canonical English** only. The interaction language is decoupled from the agent prompts:
+
+- `conversation_language` in `.aioson/context/project.context.md` tells agents which language to use for **interaction and output** with the user.
+- Agent **prompts and reasoning instructions** remain in English to ensure consistency and reduce drift across locales.
+- `locale:apply` updates the agent files to reflect the chosen interaction language, but does **not** translate the core reasoning prompts.
+
+This architecture (introduced in v1.7.3+) replaces the previous "localized agent packs" system. Localized agent packs in `.aioson/locales/<locale>/agents/` were removed in favor of a single canonical source + interaction-language metadata.
+
+## Runtime selection
+- CLI option: `--locale=en|pt-BR|es|fr`
+- Env var: `AIOS_LITE_LOCALE=en|pt-BR|es|fr`
+- Default: `en`
+
+Built-in CLI locales:
+- `en`
+- `pt-BR`
+- `es`
+- `fr`
+
+Resolution behavior:
+- `pt-BR`, `pt_br`, and `pt` resolve to `pt-BR` dictionary.
+- `es-MX` and other `es-*` variants resolve to `es`.
+- `fr-CA` and other `fr-*` variants resolve to `fr`.
+- Unknown locales fall back to `en`.
+
+## Apply interaction language to agents
+
+```bash
+# Use language from project.context.md
+aioson locale:apply
+
+# Or force a locale
+aioson locale:apply --lang=pt-BR
+```
+
+## Add a new CLI locale
+1. Run `aioson i18n:add <locale>`.
+2. Replace English strings in `src/i18n/messages/<locale>.js`.
+3. Add tests for locale resolution and fallback behavior.

package/docs/en/{json-schemas.md → 5-reference/json-schemas.md}

@@ -1,41 +1,41 @@
-# JSON Schemas
-
-AIOSON exposes machine-readable JSON output on selected commands.
-
-This folder provides formal schemas for automation:
-- `docs/en/schemas/index.json`
-- `docs/en/schemas/*.schema.json`
-
-## Commands covered
-- `aioson init <project-name> --json`
-- `aioson install [path] --json`
-- `aioson update [path] --json`
-- `aioson info --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 doctor --json`
-- `aioson context:validate --json`
-- `aioson test:smoke --json`
-- `aioson mcp:init --json`
-- `aioson mcp:doctor --json`
-- `aioson test:package --json`
-- `aioson workflow:plan --json`
-- `aioson parallel:init --json`
-- `aioson parallel:assign --json`
-- `aioson parallel:status --json`
-- `aioson parallel:doctor --json`
-- Generic CLI JSON errors (`unknown_command`, `command_error`)
-
-## Compatibility policy
-- Keys listed in each schema `required` array are stable for automation.
-- New optional keys may be added in future releases.
-- Removing or renaming required keys is a breaking change and must be called out in release notes.
-
-## Suggested validation flow
-1. Load schema from `docs/en/schemas/index.json`.
-2. Validate command output against the corresponding schema.
-3. Treat missing required keys as contract breakage.
-4. Ignore unknown keys unless your integration explicitly disallows them.
+# JSON Schemas
+
+AIOSON exposes machine-readable JSON output on selected commands.
+
+This folder provides formal schemas for automation:
+- `docs/en/schemas/index.json`
+- `docs/en/schemas/*.schema.json`
+
+## Commands covered
+- `aioson init <project-name> --json`
+- `aioson install [path] --json`
+- `aioson update [path] --json`
+- `aioson info --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 doctor --json`
+- `aioson context:validate --json`
+- `aioson test:smoke --json`
+- `aioson mcp:init --json`
+- `aioson mcp:doctor --json`
+- `aioson test:package --json`
+- `aioson workflow:plan --json`
+- `aioson parallel:init --json`
+- `aioson parallel:assign --json`
+- `aioson parallel:status --json`
+- `aioson parallel:doctor --json`
+- Generic CLI JSON errors (`unknown_command`, `command_error`)
+
+## Compatibility policy
+- Keys listed in each schema `required` array are stable for automation.
+- New optional keys may be added in future releases.
+- Removing or renaming required keys is a breaking change and must be called out in release notes.
+
+## Suggested validation flow
+1. Load schema from `docs/en/schemas/index.json`.
+2. Validate command output against the corresponding schema.
+3. Treat missing required keys as contract breakage.
+4. Ignore unknown keys unless your integration explicitly disallows them.

package/docs/en/{mcp.md → 5-reference/mcp.md}

@@ -1,56 +1,56 @@
-# MCP Guide
-
-AIOSON provides lightweight MCP planning and validation for multi-tool usage.
-
-## Commands
-
-### `mcp:init`
-Generate a local MCP plan and tool presets:
-
-```bash
-aioson mcp:init
-aioson mcp:init --dry-run
-aioson mcp:init --tool=codex
-```
-
-Outputs:
-- `.aioson/mcp/servers.local.json`
-- `.aioson/mcp/presets/<tool>.json`
-
-Preset strategy:
-- Context7 and Database presets are generated in a remote-endpoint mode using `mcp-remote`.
-- This removes generic `<...>` placeholders and gives executable command templates.
-
-### `mcp:doctor`
-Validate MCP readiness:
-
-```bash
-aioson mcp:doctor
-aioson mcp:doctor --strict-env
-aioson mcp:doctor --json
-```
-
-Checks include:
-- `servers.local.json` existence and JSON validity
-- Core server baseline (`filesystem`, `context7`)
-- Preset coverage (`claude`, `codex`, `gemini`, `opencode`)
-- Required environment variables from enabled servers
-- Context compatibility for database and Web3 (`chain-rpc`)
-
-## Strict environment mode
-- Default mode reports missing env vars as warnings.
-- `--strict-env` upgrades missing env vars to failures.
-
-Use strict mode in CI when you want runtime-ready MCP validation gates.
-
-## Required environment variables (common)
-- `CONTEXT7_MCP_URL` for Context7 endpoint
-- `DATABASE_MCP_URL` when database MCP is enabled by project stack
-- `RPC_URL`, `CHAIN_ID`, `PRIVATE_KEY` for Web3 `chain-rpc` profile
-
-Example:
-
-```bash
-export CONTEXT7_MCP_URL="https://your-context7-endpoint"
-export DATABASE_MCP_URL="https://your-database-mcp-endpoint"
-```
+# MCP Guide
+
+AIOSON provides lightweight MCP planning and validation for multi-tool usage.
+
+## Commands
+
+### `mcp:init`
+Generate a local MCP plan and tool presets:
+
+```bash
+aioson mcp:init
+aioson mcp:init --dry-run
+aioson mcp:init --tool=codex
+```
+
+Outputs:
+- `.aioson/mcp/servers.local.json`
+- `.aioson/mcp/presets/<tool>.json`
+
+Preset strategy:
+- Context7 and Database presets are generated in a remote-endpoint mode using `mcp-remote`.
+- This removes generic `<...>` placeholders and gives executable command templates.
+
+### `mcp:doctor`
+Validate MCP readiness:
+
+```bash
+aioson mcp:doctor
+aioson mcp:doctor --strict-env
+aioson mcp:doctor --json
+```
+
+Checks include:
+- `servers.local.json` existence and JSON validity
+- Core server baseline (`filesystem`, `context7`)
+- Preset coverage (`claude`, `codex`, `gemini`, `opencode`)
+- Required environment variables from enabled servers
+- Context compatibility for database and Web3 (`chain-rpc`)
+
+## Strict environment mode
+- Default mode reports missing env vars as warnings.
+- `--strict-env` upgrades missing env vars to failures.
+
+Use strict mode in CI when you want runtime-ready MCP validation gates.
+
+## Required environment variables (common)
+- `CONTEXT7_MCP_URL` for Context7 endpoint
+- `DATABASE_MCP_URL` when database MCP is enabled by project stack
+- `RPC_URL`, `CHAIN_ID`, `PRIVATE_KEY` for Web3 `chain-rpc` profile
+
+Example:
+
+```bash
+export CONTEXT7_MCP_URL="https://your-context7-endpoint"
+export DATABASE_MCP_URL="https://your-database-mcp-endpoint"
+```

package/docs/en/{parallel.md → 5-reference/parallel.md}

@@ -1,82 +1,82 @@
-# Parallel Orchestration Guide
-
-Use `parallel:init` to bootstrap the parallel context files used by `@orchestrator`.
-
-## Command
-
-```bash
-aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json]
-```
-
-Aliases:
-- `aioson orchestrator:init`
-- `aioson parallel-init`
-
-## Behavior
-- Requires parseable `.aioson/context/project.context.md`.
-- Only allows `classification=MEDIUM` by default.
-- Use `--force` to initialize for other classifications.
-- Generates:
-  - `.aioson/context/parallel/shared-decisions.md`
-  - `.aioson/context/parallel/agent-N.status.md`
-
-## Prerequisite checks
-The command reports whether these files are present:
-- `.aioson/context/discovery.md`
-- `.aioson/context/architecture.md`
-- `.aioson/context/prd.md`
-
-Missing prerequisites are reported but do not block file generation.
-
-## Scope assignment
-
-```bash
-aioson parallel:assign
-aioson parallel:assign --source=architecture --workers=3
-aioson parallel:assign --source=prd
-aioson parallel:assign --dry-run
-```
-
-Aliases:
-- `aioson orchestrator:assign`
-- `aioson parallel-assign`
-
-Behavior:
-- Reads scope candidates from `prd`, `architecture`, or `discovery` context docs.
-- Distributes scope items across lane files in round-robin mode.
-- Updates `## Scope` section and `updated_at` in each lane file.
-- Appends a decision-log entry to `shared-decisions.md` when present.
-
-## Status overview
-
-```bash
-aioson parallel:status
-aioson parallel:status --json
-```
-
-Aliases:
-- `aioson orchestrator:status`
-- `aioson parallel-status`
-
-Behavior:
-- Reads all `agent-N.status.md` lane files under `.aioson/context/parallel`.
-- Aggregates lane status counts, scope counts, blocker counts, and deliverable progress.
-- Includes shared decision log entry count from `shared-decisions.md` when present.
-- Returns a structured machine-readable report with `--json`.
-
-## Diagnose and repair
-
-```bash
-aioson parallel:doctor
-aioson parallel:doctor --workers=3
-aioson parallel:doctor --fix
-aioson parallel:doctor --fix --dry-run
-```
-
-Aliases:
-- `aioson orchestrator:doctor`
-- `aioson parallel-doctor`
-
-Notes:
-- `--fix` can recreate missing `shared-decisions.md` and missing lane files.
-- For non-`MEDIUM` projects, `--fix` requires `--force`.
+# Parallel Orchestration Guide
+
+Use `parallel:init` to bootstrap the parallel context files used by `@orchestrator`.
+
+## Command
+
+```bash
+aioson parallel:init [path] [--workers=2..6] [--force] [--dry-run] [--json]
+```
+
+Aliases:
+- `aioson orchestrator:init`
+- `aioson parallel-init`
+
+## Behavior
+- Requires parseable `.aioson/context/project.context.md`.
+- Only allows `classification=MEDIUM` by default.
+- Use `--force` to initialize for other classifications.
+- Generates:
+  - `.aioson/context/parallel/shared-decisions.md`
+  - `.aioson/context/parallel/agent-N.status.md`
+
+## Prerequisite checks
+The command reports whether these files are present:
+- `.aioson/context/discovery.md`
+- `.aioson/context/architecture.md`
+- `.aioson/context/prd.md`
+
+Missing prerequisites are reported but do not block file generation.
+
+## Scope assignment
+
+```bash
+aioson parallel:assign
+aioson parallel:assign --source=architecture --workers=3
+aioson parallel:assign --source=prd
+aioson parallel:assign --dry-run
+```
+
+Aliases:
+- `aioson orchestrator:assign`
+- `aioson parallel-assign`
+
+Behavior:
+- Reads scope candidates from `prd`, `architecture`, or `discovery` context docs.
+- Distributes scope items across lane files in round-robin mode.
+- Updates `## Scope` section and `updated_at` in each lane file.
+- Appends a decision-log entry to `shared-decisions.md` when present.
+
+## Status overview
+
+```bash
+aioson parallel:status
+aioson parallel:status --json
+```
+
+Aliases:
+- `aioson orchestrator:status`
+- `aioson parallel-status`
+
+Behavior:
+- Reads all `agent-N.status.md` lane files under `.aioson/context/parallel`.
+- Aggregates lane status counts, scope counts, blocker counts, and deliverable progress.
+- Includes shared decision log entry count from `shared-decisions.md` when present.
+- Returns a structured machine-readable report with `--json`.
+
+## Diagnose and repair
+
+```bash
+aioson parallel:doctor
+aioson parallel:doctor --workers=3
+aioson parallel:doctor --fix
+aioson parallel:doctor --fix --dry-run
+```
+
+Aliases:
+- `aioson orchestrator:doctor`
+- `aioson parallel-doctor`
+
+Notes:
+- `--fix` can recreate missing `shared-decisions.md` and missing lane files.
+- For non-`MEDIUM` projects, `--fix` requires `--force`.