@jaimevalasek/aioson 1.3.0

package/docs/en/i18n.md

@@ -0,0 +1,52 @@
+# i18n Guide
+
+AIOSON CLI supports localization through message dictionaries.
+
+## How it works
+- Dictionaries are stored in `src/i18n/messages/`.
+- `src/i18n/index.js` resolves locale and fallback behavior.
+- Commands use translation keys instead of hardcoded strings.
+- Agent templates read `conversation_language` from `.aioson/context/project.context.md` and should use it for interaction/output language.
+- Localized agent packs live in `.aioson/locales/<locale>/agents/` and can be applied to active prompts with `aioson locale:apply`.
+
+## Runtime selection
+- CLI option: `--locale=en`
+- Env var: `AIOS_LITE_LOCALE=en`
+- Default: `en`
+
+Built-in locales:
+- `en`
+- `pt-BR`
+- `es`
+- `fr`
+
+Built-in localized agent packs:
+- `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`.
+
+## Create a locale scaffold
+```bash
+aioson i18n:add fr
+```
+
+## Apply localized agent prompts
+```bash
+# Use language from project.context.md
+aioson locale:apply
+
+# Or force a locale
+aioson locale:apply --lang=pt-BR
+```
+
+## Add a new 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

@@ -0,0 +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.

package/docs/en/mcp.md

@@ -0,0 +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"
+```

package/docs/en/parallel.md

@@ -0,0 +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`.

package/docs/en/qa-browser.md

@@ -0,0 +1,339 @@
+# QA Browser Testing Guide
+
+AIOSON includes a built-in browser QA engine powered by [Playwright](https://playwright.dev). It opens a real Chrome browser, runs automated tests across multiple personas, and generates a report in the same format as the `@qa` agent — so both can be used together.
+
+No LLM required. No separate tool to install beyond Playwright itself.
+
+---
+
+## Prerequisites
+
+```bash
+npm install -g playwright
+npx playwright install chromium
+```
+
+Verify everything is ready:
+
+```bash
+aioson qa:doctor
+```
+
+---
+
+## Quick start
+
+```bash
+# 1. Generate config (reads prd.md and discovery.md automatically)
+aioson qa:init --url=http://localhost:3000
+
+# 2. Start your application, then run
+aioson qa:run
+
+# 3. View the report
+aioson qa:report
+```
+
+Output files written to the project root:
+- `aios-qa-report.md` — full report (same severity format as `@qa`)
+- `aios-qa-report.json` — machine-readable for CI/CD
+- `aios-qa-screenshots/` — screenshot evidence per finding
+
+---
+
+## Commands
+
+### `qa:init`
+
+Generates `aios-qa.config.json` from your project context.
+
+```bash
+aioson qa:init [path] [--url=<app-url>] [--dry-run] [--json]
+```
+
+If `.aioson/context/project.context.md` exists, the project name and language are read automatically. If `prd.md` exists, acceptance criteria are extracted and added as test scenarios.
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--url=<url>` | Target application URL (default: `http://localhost:3000`) |
+| `--dry-run` | Preview config without writing |
+| `--json` | Output result as JSON |
+
+**Example output — `aios-qa.config.json`:**
+
+```json
+{
+  "project_name": "MyApp",
+  "url": "http://localhost:3000",
+  "language": "en",
+  "personas": ["naive", "hacker", "power", "mobile"],
+  "security_probes": [
+    "exposed_env_vars", "xss_inputs", "open_redirect",
+    "sensitive_files", "idor_probe", "console_leaks",
+    "debug_routes", "mixed_content", "sensitive_get_params"
+  ],
+  "performance_thresholds": {
+    "page_load_ms": 3000,
+    "ttfb_ms": 800,
+    "requests_max": 80,
+    "transfer_max_kb": 2048
+  },
+  "accessibility": true,
+  "network_capture": true,
+  "screenshot_on_finding": true,
+  "scenarios": []
+}
+```
+
+---
+
+### `qa:doctor`
+
+Checks all prerequisites before running tests.
+
+```bash
+aioson qa:doctor [path] [--json]
+```
+
+**Checks performed:**
+
+| Check | Severity |
+|-------|----------|
+| Playwright package installed | Error |
+| Chromium binary found | Error |
+| `aios-qa.config.json` exists and is valid JSON | Error |
+| Target URL is reachable | Warning |
+| `project.context.md` present (enriches tests) | Warning |
+| `prd.md` present (enables AC coverage) | Warning |
+
+**Example:**
+
+```
+[OK]   playwright.installed - Playwright is installed.
+[OK]   chromium.binary - Chromium browser binary found.
+[OK]   config.exists - aios-qa.config.json found and valid.
+[OK]   url.reachable - Target URL is reachable (http://localhost:3000).
+[OK]   context.exists - project.context.md found.
+[WARN] prd.md — prd.md not found — AC coverage mapping will be skipped.
+Summary: 5 passed, 0 failed, 1 warnings.
+```
+
+---
+
+### `qa:run`
+
+Runs a full browser QA session: 4 personas, security probes, accessibility audit, performance capture, and AC coverage.
+
+```bash
+aioson qa:run [path] [--url=<app-url>] [--persona=naive|hacker|power|mobile] [--headed] [--html] [--json]
+```
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--url=<url>` | Override URL from config |
+| `--persona=<name>` | Run only one persona |
+| `--headed` | Show browser window (useful for debugging) |
+| `--html` | Also generate an HTML report in `reports/<run-id>/index.html` |
+| `--json` | Output result as JSON |
+
+#### Personas
+
+**`naive` — Clumsy user**
+- Submits all forms empty → detects unhandled 5xx
+- Types 10,000-character strings → detects missing length validation
+- Clicks elements with `cursor:pointer` that have no handler → detects ghost clickables
+
+**`hacker` — Attacker mindset**
+- Scans `window.__NEXT_DATA__`, `window.__env__`, `window.ENV`, `window.CONFIG` for exposed secrets (OpenAI, Stripe, AWS, Google, GitHub, Slack patterns)
+- Scans rendered HTML source for the same patterns
+- Tries 10 sensitive file URLs: `/.env`, `/.env.local`, `/.env.production`, `/.git/config`, `/config.js`, and more
+- Injects XSS payload in all text inputs, detects execution
+- Probes 8 redirect parameters for open redirect
+- Types SQL injection payload, detects DB error messages in response
+- Tests IDOR: increments/decrements numeric IDs in URL by ±1 and +9999
+- Checks 8 debug/admin routes for unauthenticated access
+
+**`power` — Keyboard-only, boundary values**
+- Tabs through all interactive elements, detects missing visible focus indicator
+- Enters boundary values in number/range inputs: `-999999999`, `0`, `999999999999999`
+- Enters edge dates: `1900-01-01`, `9999-12-31`, `2000-02-29`
+
+**`mobile` — iPhone SE (375×667)**
+- Detects horizontal overflow (content wider than viewport)
+- Flags touch targets smaller than 44×44px (WCAG 2.5.5)
+- Flags text smaller than 12px
+
+#### Security probes (post-persona, network layer)
+- Console errors containing stack traces → Medium finding
+- Sensitive parameter names (`token`, `password`, `api_key`) in GET URLs → High finding
+- HTTP requests from HTTPS page (mixed content) → Medium finding
+
+#### Accessibility audit
+- Images missing `alt` attribute (WCAG 1.1.1)
+- Form inputs with no accessible label (WCAG 1.3.1)
+- Buttons with no accessible name (WCAG 4.1.2)
+- Heading levels skipped (e.g. `h1` → `h3`)
+- `<html>` missing `lang` attribute (WCAG 3.1.1)
+
+#### Performance capture
+| Metric | Default threshold |
+|--------|------------------|
+| Page load complete | 3000ms |
+| Time to First Byte (TTFB) | 800ms |
+| Network request count | 80 |
+| Total transfer size | 2048KB |
+
+Thresholds are configurable in `aios-qa.config.json` under `performance_thresholds`.
+
+#### AC coverage
+If `prd.md` exists, acceptance criteria are extracted from the table and 🔴 must-have items. For each AC, a screenshot is taken of the current page state and saved to `aios-qa-screenshots/`.
+
+---
+
+### `qa:scan`
+
+Autonomous crawl mode. No pre-defined scenarios needed — the tool discovers all routes and probes each one.
+
+```bash
+aioson qa:scan [path] [--url=<app-url>] [--depth=3] [--max-pages=50] [--headed] [--html] [--json]
+```
+
+**Flags:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--url=<url>` | from config | Override base URL |
+| `--depth=<n>` | `3` | Max crawl depth from base URL |
+| `--max-pages=<n>` | `50` | Max pages to visit |
+| `--headed` | false | Show browser window |
+| `--html` | false | Also generate an HTML report in `reports/<run-id>/index.html` |
+| `--json` | false | Output result as JSON |
+
+**What it does on each route:**
+- Scans HTML source and window globals for exposed secrets
+- Checks for stack trace leakage in console errors
+- Accessibility quick check (images alt, html lang)
+- Horizontal overflow detection
+
+Sensitive files (`/.env`, `/.git/config`, etc.) are probed once per domain at the start of the scan.
+
+---
+
+### `qa:report`
+
+Displays the last generated report.
+
+```bash
+aioson qa:report [path] [--html] [--json]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--html` | Regenerate an HTML report from the existing `aios-qa-report.json` |
+| `--json` | Return the parsed `aios-qa-report.json` as JSON |
+
+In default mode, prints `aios-qa-report.md` to the terminal.
+
+---
+
+## Integration with @qa agent
+
+When the `@qa` agent runs, it automatically checks for `aios-qa-report.md` in the project root. If found, it:
+
+1. Maps browser findings to AC status — any AC that failed in the browser is marked **Missing**
+2. Promotes severity — if both static review and browser test flag the same issue, severity goes up one level
+3. Adds a **Browser findings (aios-qa)** subsection to its report
+4. Tags ACs that passed in the browser with `[browser-validated]`
+
+This means running `aioson qa:run` before `@qa` gives you a richer, more complete QA report with zero extra effort.
+
+---
+
+## Typical workflow
+
+Two terminals, running in parallel:
+
+```bash
+# Terminal 1 — aioson agents
+@setup → @product → @analyst → @architect → @dev
+
+# Terminal 2 — browser QA (while app is running)
+aioson qa:init --url=http://localhost:3000
+aioson qa:run
+
+# Terminal 1 — continues with merged findings
+@qa   # reads aios-qa-report.md automatically
+```
+
+---
+
+## HTML reports
+
+Add `--html` to `qa:run` or `qa:scan` to generate a self-contained visual report alongside the default MD/JSON outputs.
+
+```bash
+aioson qa:run --html
+aioson qa:scan --html
+```
+
+Or generate HTML retroactively from an existing run:
+
+```bash
+aioson qa:report --html
+```
+
+**Output structure:**
+
+```
+reports/
+  index.html                    ← historical index of all runs
+  2026-03-04_15-30-00_run/
+    index.html                  ← full report (self-contained)
+    meta.json                   ← run metadata for the index
+  2026-03-04_14-00-00_scan/
+    index.html
+    meta.json
+```
+
+**Features:**
+- Screenshots embedded as base64 — no external file references, fully portable for sharing
+- Severity filter buttons (All / Critical / High / Medium / Low)
+- Collapsible finding cards with location, risk, fix, and screenshot
+- Performance cards with colour-coded thresholds
+- AC coverage table (when `prd.md` was used)
+- Routes discovered list (scan mode)
+- Click-to-zoom screenshot lightbox
+- `reports/index.html` auto-updated after each run with a sortable history table
+
+The MD and JSON outputs are never modified — `--html` is purely additive.
+
+---
+
+## CI/CD integration
+
+`aios-qa-report.json` is written alongside the markdown report and is suitable for CI pipelines:
+
+```bash
+aioson qa:run --json | jq '.summary'
+# { "critical": 0, "high": 1, "medium": 3, "low": 2 }
+
+# Fail CI if any critical findings
+aioson qa:run --json | jq 'if .summary.critical > 0 then error else . end'
+```
+
+For headless environments, Playwright runs in headless mode by default (no `--headed` flag needed in CI).
+
+---
+
+## Report severity reference
+
+| Severity | Examples |
+|----------|---------|
+| **Critical** | Exposed API key, XSS executed, sensitive file accessible, SQL error exposed |
+| **High** | IDOR potential, open redirect, 5xx on empty form, sensitive param in GET URL |
+| **Medium** | Missing auth on debug route, console stack traces, TTFB > 800ms, accessibility violations |
+| **Low** | Ghost clickable elements, touch targets < 44px, fonts < 12px, missing lang attribute |

package/docs/en/release-flow.md

@@ -0,0 +1,22 @@
+# Release Tag Flow
+
+## Preconditions
+- Git repository initialized and connected to GitHub.
+- `NPM_TOKEN` configured in repository secrets.
+- `main` branch green in CI.
+
+## Steps
+1. Update `CHANGELOG.md` and `package.json` version.
+2. Run local validation:
+   - `npm run ci`
+3. Commit release changes.
+4. Create tag:
+   - `git tag vX.Y.Z`
+5. Push branch and tag:
+   - `git push origin main --tags`
+6. Watch `Release` workflow in GitHub Actions.
+7. Publish GitHub release using `.github/release-notes-template.md`.
+
+## Verify publication
+- `npm view @jaimevalasek/aioson version`
+- `npx @jaimevalasek/aioson@latest info`

package/docs/en/release-notes-template.md

@@ -0,0 +1,41 @@
+# Release Notes Template
+
+## AIOSON vX.Y.Z
+
+### Highlights
+- [short summary 1]
+- [short summary 2]
+- [short summary 3]
+
+### Added
+- [feature]
+- [feature]
+
+### Changed
+- [change]
+- [change]
+
+### Fixed
+- [bug fix]
+- [bug fix]
+
+### CLI
+- Commands impacted: `[list]`
+- Breaking changes: `yes/no` (if yes, describe migration)
+
+### i18n
+- New locale scaffolds or translation keys:
+  - [item]
+
+### Upgrade notes
+1. Update package:
+   - `npx @jaimevalasek/aioson@latest update`
+2. Run health check:
+   - `aioson doctor`
+3. Verify local customizations in `.aioson/backups/` if applicable.
+
+### Checks
+- [ ] Lint passed
+- [ ] Tests passed
+- [ ] Smoke test passed
+

package/docs/en/release.md

@@ -0,0 +1,28 @@
+# Release Guide
+
+## CI
+- Workflow: `.github/workflows/ci.yml`
+- Triggers: push to `main`, pull requests
+- Steps: install, lint, test, `npm pack --dry-run`
+
+## npm publish
+- Workflow: `.github/workflows/release.yml`
+- Triggers: `v*` git tags or manual dispatch
+- Required secret: `NPM_TOKEN`
+
+## npm package name
+The published package name is `@jaimevalasek/aioson`.
+
+The unscoped name `aioson` was rejected by npm because it is considered too similar to an existing package, so releases should use the scoped package.
+
+## Recommended release flow
+1. Update `CHANGELOG.md`.
+2. Bump version in `package.json`.
+3. Commit and push to `main`.
+4. Create and push a tag like `v0.1.1`.
+5. Verify publish logs in GitHub Actions or in the local npm publish output.
+
+## Templates
+- Release notes template: `.github/release-notes-template.md`
+- Extended release notes guide: `docs/en/release-notes-template.md`
+- Tag flow checklist: `docs/en/release-flow.md`

package/docs/en/schemas/agent-prompt.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aiosforge.dev/schemas/agent-prompt.schema.json",
+  "title": "AIOSON agent:prompt --json output",
+  "type": "object",
+  "required": ["ok", "targetDir", "agent", "tool", "locale", "instructionPath", "prompt"],
+  "properties": {
+    "ok": { "type": "boolean", "const": true },
+    "targetDir": { "type": "string" },
+    "agent": { "type": "string" },
+    "tool": { "type": "string" },
+    "locale": { "type": "string" },
+    "instructionPath": { "type": "string" },
+    "prompt": { "type": "string" }
+  },
+  "additionalProperties": true
+}