@massa-ai/cursor-plugin 1.6.0

package/skills/massa-ai/references/installation.md

@@ -0,0 +1,110 @@
+# Massa-ai Installation And Diagnostics
+
+Load this only for installing, configuring, validating, or troubleshooting the
+massa-ai stack. Ordinary workflow routing should use MCP tools instead.
+
+## Install And Upgrade
+
+Current recommended installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/luizgmassa/massa-ai/main/install.sh | bash
+```
+
+Interactive modes:
+
+| Mode | Requires | Intended use |
+|---|---|---|
+| Docker | Docker | Default production/quick-start path. |
+| Docker build | Docker and Git | Local changes and custom images. |
+| Source | Git and Bun | Development and contribution. |
+
+Non-interactive installs may set `MASSA_AI_MODE`, `MASSA_AI_API_PORT`, and
+`MASSA_AI_NO_START`. Review the downloaded script and environment before using the
+one-line installer in sensitive environments.
+
+Manual source setup:
+
+```bash
+git clone https://github.com/luizgmassa/massa-ai.git
+cd massa-ai
+bun install
+./scripts/setup-local-first.sh
+bun run build
+bun run start:api
+```
+
+`setup-local-first.sh` configures Ollama, pulls the embedding model, creates
+defaults, and runs diagnostics. Confirm the selected mode and current upstream
+instructions before upgrades.
+
+## Configuration
+
+Relevant settings include:
+
+- `DATABASE_URL` and `POSTGRES_PASSWORD` for PostgreSQL/pgvector.
+- Embedding provider, model, dimensions, API key, and provider base URL.
+- `MASSA_AI_API_URL` for MCP/REST clients.
+- `MASSA_AI_API_KEY` for API protection; REST clients send it as `x-api-key`.
+- Search tuning such as `SEARCH_DISABLE_KEYWORD`, `SEARCH_MIN_SCORE`,
+  `RRF_KEYWORD_BOOST`, `RRF_VECTOR_WEIGHT`, and
+  `RRF_MAX_CHUNKS_PER_FILE`.
+- Synapse toggles including `SYNAPSE_ENABLED` and
+  `SYNAPSE_ATTENTION_ENABLED`.
+
+Current config CLI:
+
+```bash
+npx @massa-ai/mcp-client --config-show
+npx @massa-ai/mcp-client --config-path
+npx @massa-ai/mcp-client --config-dir
+npx @massa-ai/mcp-client --config-init
+npx @massa-ai/mcp-client --config-set embedding.dimensions 4096
+```
+
+Provider initialization supports Ollama plus `--mistral` and `--openai`
+credentials. Never place provider keys in committed config.
+
+Never print, persist, commit, or include API keys in memory or status output.
+
+## Validation And Diagnostics
+
+Use the installation's supported CLI diagnostics when present, including
+`bun run diagnose` and current config commands documented upstream. Also check:
+
+```bash
+docker compose ps
+rtk curl -sS http://localhost:3333/health
+rtk curl -sS http://localhost:3333/api/v1/system/status
+rtk curl -sS http://localhost:3333/api/v1/system/health/local
+rtk curl -sS http://localhost:3333/api/v1/system/ollama
+```
+
+Add `x-api-key` for protected deployments without echoing the value. Swagger is
+served at `/swagger`; its machine-readable contract is `/swagger/json`.
+
+Swagger response schemas may be empty and its displayed API version may lag the
+package release. Use it to inspect routes/request fields, then verify important
+behavior through MCP declarations and non-destructive runtime probes.
+
+## Deployment Notes
+
+- WSL/Linux Docker setups may need `host.docker.internal:host-gateway`.
+- Standard Docker startup should run migrations before the API process.
+- Confirm the embedding provider is reachable from inside the API container.
+- Do not reset vectors, symbols, or memories unless explicit destructive intent
+  exists. Prefer normal indexing or the verified full-index fallback.
+
+## Client Integrations
+
+- Preferred: `bash scripts/install-agents.sh --agent <host>` — the single writer
+  of host MCP config (Claude Code, Claude Desktop, Codex, Cursor, OpenCode).
+  Plugin installers call it; nothing else writes an MCP entry.
+- OpenCode: local MCP package via `bunx @massa-ai/mcp-client`, or
+  `@massa-ai/opencode-plugin` (which registers tools in-process, so
+  `install-agents.sh` skips the MCP entry when that plugin is present).
+- VS Code/Antigravity: `.vscode/mcp.json` or `./scripts/setup-vscode.sh`.
+- Docker: run the `mcp` service through `docker compose run --rm -i mcp`.
+
+All MCP clients need the correct `MASSA_AI_API_URL`; protected deployments also
+need `MASSA_AI_API_KEY` in the client environment.

package/skills/massa-ai/references/lessons.md

@@ -0,0 +1,119 @@
+# Lessons
+
+Use this reference when loading confirmed project lessons during startup, or recording grounded reusable failures after verification, across any workflow that produces verifiable outcomes.
+
+## Artifacts
+
+- `.specs/lessons.json` — canonical machine-owned lesson state. Read it; do not hand-edit.
+- `.specs/LESSONS.md` — rendered playbook generated by the script. Read it; do not hand-edit.
+- `skills/massa-ai/scripts/lessons.py` — deterministic bookkeeping script.
+
+## Lesson Signal Table
+
+| Signal | Use When | Do Not Use For |
+|---|---|---|
+| `ac_gap` | Acceptance criterion was too vague, missing, or not testable. | One-off user clarification already captured in a spec. |
+| `surviving_mutant` | A discrimination sensor or mutation-style check survived. | A mutation could not run for environmental reasons. |
+| `spec_precision_gap` | Validation could not identify the exact expected value or state. | Implementation bug with a precise existing criterion. |
+| `spec_deviation` | Implementation intentionally diverged from approved spec and needs future prevention. | Unapproved scope expansion that should be reverted now. |
+| `gate_fail` | A deterministic gate failed because the workflow missed a reusable convention. | Transient tool, network, credential, or sandbox failure. |
+
+## Capture
+
+After a workflow's verification step finds a concrete reusable signal, record it:
+
+```bash
+python3 skills/massa-ai/scripts/lessons.py --root . add \
+  --feature "<feature-slug>" \
+  --signal "<ac_gap|surviving_mutant|spec_precision_gap|spec_deviation|gate_fail>" \
+  --source "<validation.md source, AC id, file:line, mutant id, or SPEC_DEVIATION ref>" \
+  --text "<one terse reusable lesson>" \
+  --scope "<optional path/layer/tag>" \
+  --project "<projectId>" --session "<workflowSessionId>" \
+  --workflow "<active workflow type>" --entity "<entity>"
+```
+
+`--project`/`--session`/`--workflow`/`--entity` carry the active massa-ai
+context onto the lesson so the file store and massa-ai memory stay in the same
+recall namespace. They are optional for manual runs but supplied by the
+continuous-learning hook loop.
+
+Do not record one-off tool failures, transient environment issues, methodology opinions, or chat summaries as lessons.
+
+## Distill
+
+The script owns IDs, recurrence, candidate promotion, pruning, quarantine, and rendering. Lessons promote only after repeated distinct-feature evidence (default: 2 distinct features). A clean `Pass` with no signal records nothing.
+
+Run this self-check after verification: if a failed acceptance criterion, surviving mutant, spec-precision gap, `SPEC_DEVIATION`, or gate failure was found but no lesson was recorded, state the skipped reason.
+
+## Loading
+
+During startup of any applicable workflow, load confirmed lessons when `.specs/lessons.json` exists:
+
+```bash
+python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]
+```
+
+- Use `--scope` or `--query` to keep the loaded set small.
+- Do not load `candidate` or `quarantined` lessons as guidance.
+- Keep lesson content compact; do not turn it into a parallel memory system.
+
+## Promotion Lifecycle
+
+| Status | Condition |
+|---|---|
+| `candidate` | Recorded once from one feature's verification |
+| `confirmed` | Same normalized lesson seen across ≥`promote_threshold` (default 2) distinct features |
+| `quarantined` | A confirmed lesson penalized ≥`quarantine_threshold` times (failed when applied) |
+| **pruned** | A `candidate` that never recurred within `window_days` (default 45) |
+
+## No-Script Fallback
+
+If `lessons.py` is unavailable or cannot run, record `Lessons: skipped - script unavailable` in the validation report or evidence gate, keep the raw signal in the report, and do not hand-edit `lessons.json` or `LESSONS.md`. A future run with the script can import the validated signal.
+
+## Continuous-Learning Loop (hook-fed)
+
+The lessons layer is a closed loop, not manual-only. Two runtime hooks
+(`scripts/hooks/`, installed for Claude Code by the installer) feed it:
+
+1. **observe** — `observe_runner.py` (PostToolUse) captures raw tool-use
+   observations into the gitignored `.specs/observations.json` buffer. Grounding
+   is NOT assigned here.
+2. **evaluate** — `continuous_learning_evaluate.py` (Stop) reads the active
+   massa-ai context from `.specs/project/STATE.md` and the observations
+   buffer. For each observation that already carries grounded fields
+   (`signal`, `text`, `source`, `feature`), it calls `lessons.py add` with the
+   `--project`/`--session`/`--workflow`/`--entity` context. Ungrounded
+   observations are left in the buffer for agent input and logged as skipped.
+
+### massa-ai Dual-Write
+
+`lessons.py add` and `import` best-effort write massa-ai memory so the file store
+and durable memory stay consistent:
+
+- **type** is always `pattern` (lessons are procedural knowledge). `procedural`
+  is a **tag**, never a type (references/mcp-tools.md).
+- **tags** carry the full massa-ai persistence contract: `project:<id>`,
+  `session:<workflowSessionId>`, `workflow:<type>`, `entity:<name>`,
+  `memory:procedural`. This puts lessons in the same recall namespace as
+  massa-ai decisions/patterns, so future `recall` surfaces them at
+  Specify/Design.
+- massa-ai MCP is agent-side only; the hook/CLI subprocess writes via REST
+  (`MASSA_AI_API_URL`). When REST is unavailable, the lesson still lands in
+  `lessons.json` and the skipped memory write is logged (graceful degradation).
+
+### Round-Trip
+
+```bash
+python3 skills/massa-ai/scripts/lessons.py --root . export --out lessons.export.json
+python3 skills/massa-ai/scripts/lessons.py --root . import --in lessons.export.json
+```
+
+`export`/`import` round-trip the file store; `import` re-emits massa-ai memory
+best-effort. An ungrounded lesson is refused by both `add` and the massa-ai write.
+
+### Self-Check
+
+After verification: if a reusable signal was found but no lesson was recorded,
+state the skipped reason. The hook loop logs every skip to
+`scripts/hooks-state/skip.log`.

package/skills/massa-ai/references/maestro/artifacts-reports.md

@@ -0,0 +1,69 @@
+# Maestro Artifacts And Reports Reference
+
+Use this when running, auditing, or fixing flows that need report paths, artifact directories, screenshots, videos, debug output, or recording.
+
+## Reports
+
+Report generation is CLI-dependent. Use `--format` and `--output`; do not put report generation in `config.yaml`.
+
+Supported report formats from current official docs/live help:
+
+- `junit`
+- `html`
+- `html-detailed` when supported by current CLI help
+- `noop`/default no report when no format is selected
+
+JUnit reports default to `report.xml` in the current working directory when `--output` is omitted. Prefer explicit report paths in CI.
+
+```bash
+maestro test --format junit --output build/maestro/report.xml .maestro
+```
+
+## Artifact Directories
+
+`--test-output-dir` captures screenshots, videos, `commands-*.json`, and AI report files. `--debug-output` captures `maestro.log` and debug-oriented output.
+
+If both flags point to the same directory, artifacts consolidate there. If they differ, `maestro.log` stays in `--debug-output` while screenshots/videos/commands/AI reports stay in `--test-output-dir`.
+
+```bash
+maestro test \
+  --format junit \
+  --output build/maestro/report.xml \
+  --test-output-dir build/maestro/artifacts \
+  --debug-output build/maestro/debug \
+  .maestro
+```
+
+## Common Artifact Fields
+
+Record these in audit/fix reports and closure summaries:
+
+- command
+- exit status
+- JUnit or HTML report path
+- artifact directory
+- debug output directory
+- `maestro.log` path when JS logging matters
+- `commands-*.json` presence or absence
+- screenshots/videos presence or absence
+- AI report path when `--analyze` or AI commands run
+- device/platform/app build/flavor
+- skipped-check reason
+
+## Recording
+
+Use `maestro record --local` when a local MP4 recording is requested. Current official docs/live help mark local rendering as beta and restrict the optional output file to local rendering.
+
+```bash
+maestro record --local flows/checkout.yaml build/maestro/checkout.mp4
+```
+
+Remote recording behavior is not a normative contract here. Prefer `--local` for privacy and repeatability unless repository convention says otherwise.
+
+## AI Reports
+
+AI analysis via `maestro test --analyze` and AI assertion commands is experimental and Cloud-auth-backed. It can produce HTML/JSON insight reports in artifacts. Do not replace missing AI execution with model self-evaluation.
+
+## No-Coverage Rule
+
+A passing flow proves the flow's selected path on the selected device/platform. It does not prove full scenario coverage, Figma parity, accessibility compliance, or absence of app bugs unless those claims have separate deterministic evidence.

package/skills/massa-ai/references/maestro/cli-device.md

@@ -0,0 +1,65 @@
+# Maestro CLI And Device Reference
+
+Use this for CLI preflight, local command syntax, device/platform readiness, and local execution constraints.
+
+## Mandatory Preflight
+
+Before tracked Maestro flow edits, executable audit runs, or `MST-*` fixes:
+
+1. Run `command -v maestro`.
+2. Run `maestro --version` or `maestro --help`.
+3. Run relevant subcommand help for the surface: `maestro test --help`, `maestro cloud --help`, `maestro record --help`, or MCP startup/help.
+4. Check device/emulator readiness through repository convention when one exists; otherwise record `device-readiness: not available` with reason.
+
+Required transcript fields: command, exit code, stdout summary, stderr summary. If `maestro --version` or `maestro --help` fails, block mutation and executable audit/fix runs; do not install or repair Maestro automatically.
+
+## CLI Shape
+
+Official CLI pattern: `maestro [options] [subcommand] [subcommand options]`.
+
+Global options include `--[no-]ansi`, `--[no-]color`, `--device`/`--udid`, `--platform`, `--verbose`, `--version`, and `--help`. Prefer putting global `--device` before the subcommand for clarity, while noting live `maestro test --help` may also expose `--device`.
+
+Current official subcommands include `test`, `cloud`, `record`, `download-samples`, `login`, `logout`, `start-device`, `list-devices`, `list-cloud-devices`, `chat`, `bugreport`, `driver-setup`, and `mcp`. Treat subcommands visible only in live help, such as `hierarchy`, as `live-help` unless official docs also list them. Treat `maestro query` as `excluded/unverified` unless official docs or live help confirms it in the active environment.
+
+## `maestro test`
+
+Use for local simulator/emulator/device/web execution.
+
+Important options from official docs/live help:
+
+- `--config=<configFile>`: workspace config override.
+- `-e`, `--env=<Key=Value>`: inject flow variables.
+- `--include-tags` and `--exclude-tags`: run or remove flows by tag filters.
+- `--format=<format>` and `--output=<path>`: report generation and report path.
+- `--test-output-dir=<dir>`: screenshots, videos, command JSON, and AI report artifacts.
+- `--debug-output=<dir>`: `maestro.log` and debug outputs.
+- `--flatten-debug-output`: CI-friendly debug output layout.
+- `--headless` and `--screen-size`: web-only.
+- `--shards`, `--shard-all`, `--shard-split`: local sharding/parallel distribution across connected devices.
+- `--test-suite-name`: report suite name.
+- `--device`/`--udid` and `--platform`: target selection.
+- `--analyze`: beta AI analysis, requiring Maestro Cloud-backed authentication.
+
+Do not document unsupported aliases such as `--flavor`, singular `--shard`, or generic `--debug` as valid unless current live help confirms them. Use `--debug-output`, `--shards`, `--shard-all`, or `--shard-split` instead when supported.
+
+## Device And Platform Readiness
+
+Official platform support:
+
+- Android: emulators and physical devices; physical devices need USB debugging; app must already be installed.
+- iOS: Xcode-managed simulators; target app uses Bundle ID and simulator-compatible `.app`.
+- Web: beta support for Chromium-based browser automation; web flows use `url` instead of `appId`.
+
+For local sharding, require explicit device inventory before planning parallel local runs. Do not claim exact failure behavior for device-count mismatch unless a live run, official docs, or repo convention proves it.
+
+If a WSL caveat matters, verify it against official docs or repository convention first. Otherwise record WSL details as `excluded/unverified`.
+
+## Execution Command Template
+
+Prefer repository-specific wrappers when present. Otherwise use explicit outputs:
+
+```bash
+maestro test --format junit --output <report.xml> --test-output-dir <artifact-dir> <flow-or-directory>
+```
+
+Add `--debug-output <debug-dir>` when JavaScript logging or `maestro.log` is needed. Use `--no-ansi` in CI when supported by current CLI help or repo convention.

package/skills/massa-ai/references/maestro/cloud.md

@@ -0,0 +1,67 @@
+# Maestro Cloud Reference
+
+Use this only when a Maestro task touches Cloud execution, CI upload, Cloud devices, Cloud-auth-backed AI, or app binary reuse.
+
+## Cloud Command
+
+Maestro Cloud uses the normal Maestro CLI `cloud` subcommand, not a separate Cloud CLI.
+
+Prefer named parameters:
+
+```bash
+maestro cloud \
+  --app-file app/build/outputs/apk/debug/app-debug.apk \
+  --flows .maestro \
+  --format junit \
+  --output build/maestro/cloud-report.xml
+```
+
+Named parameters such as `--app-file` and `--flows` can appear in any order and are safer for CI scripts than positional arguments.
+
+## Auth And Plan Requirements
+
+- Cloud test execution requires Maestro Cloud access and a Cloud plan.
+- Cloud CLI calls need API key/login/project configuration according to repo convention.
+- AI commands and `maestro test --analyze` are Cloud-infrastructure-backed but can be enabled with a free account; do not confuse that with Cloud device execution plan requirements.
+
+Never commit API keys. Use `maestro login`, `MAESTRO_CLOUD_API_KEY`, or CI secrets according to repository policy.
+
+## App Binary Eligibility
+
+Android Cloud requirements:
+
+- Upload APK, not AAB.
+- APK must be ARM-compatible or multi-architecture; x86-only APKs fail in Cloud.
+- Debug and release builds are supported.
+
+iOS Cloud requirements:
+
+- Upload `.app` bundle.
+- Build for iOS Simulator, not physical iOS devices.
+
+Project-specific build steps are authoritative. Check README, build scripts, and CI before inventing build commands.
+
+## Reuse And Device Selection
+
+Use `--app-binary-id` to reuse a previously uploaded binary when official docs/repo convention expose the ID.
+
+Cloud device flags:
+
+- `--device-model`
+- `--device-os`
+- `--device-locale`
+- `maestro list-cloud-devices` for supported pairs
+
+Do not hardcode model/OS values unless requested or repo convention fixes them.
+
+## Cloud Limits
+
+Official Cloud limit: 15-minute soft execution limit per test execution. After that, a test may be stopped at any time. Split long suites into smaller, parallelizable flows.
+
+## Cloud Output And Async
+
+`maestro cloud` can block until analyses complete by default; current live help exposes `--async` to submit and exit immediately. Record upload/dashboard output when available, but do not invent dashboard polling schemas unless official docs, live MCP metadata, or repo convention provides them.
+
+## Cloud Boundary
+
+Use Cloud for hosted device execution, device matrix coverage, PR checks, and Cloud-only platform settings. Keep local CLI checks, static YAML checks, and repository validation as separate evidence.

package/skills/massa-ai/references/maestro/config-env-output.md

@@ -0,0 +1,76 @@
+# Maestro Config, Env, And Output Boundaries
+
+Use this when deciding whether a fact belongs in a Flow header, `config.yaml`, CLI invocation, report metadata, or artifact output.
+
+## Boundary Matrix
+
+| Surface | Owns | Does not own |
+|---|---|---|
+| Flow header | `appId` or `url`, `name`, `tags`, `env`, hooks, JUnit `properties` | Workspace discovery policy for all flows |
+| `config.yaml` | `flows`, `testOutputDir`, global tags, `executionOrder`, platform config, Cloud notifications/baseline | JUnit/HTML report generation |
+| CLI flags | `--env`, `--config`, `--format`, `--output`, `--test-output-dir`, `--debug-output`, tag overrides, device/platform | Persistent source truth |
+| Report file | JUnit/HTML result selected by `--format` and `--output` | Screenshots/videos/debug logs by default |
+| Artifact dirs | screenshots, videos, `commands-*.json`, AI reports, and optionally `maestro.log` | Test result XML unless explicitly written there by `--output` |
+
+## Flow Header Fields
+
+```yaml
+appId: com.example.app
+name: Checkout Critical Path
+tags:
+  - smoke
+env:
+  REGION: us
+onFlowStart:
+  - runFlow: setup/user.yaml
+onFlowComplete:
+  - runFlow: cleanup/user.yaml
+properties:
+  junitId: TC-CHECKOUT-001
+  junitClassname: com.example.CheckoutE2E
+---
+- launchApp
+```
+
+Use `properties` for JUnit metadata. `junitId` and `junitClassname` are reserved report attributes; other properties are emitted as JUnit properties.
+
+## Env Injection
+
+Pass runtime values through CLI or flow/subflow/script env:
+
+```bash
+maestro test -e APP_ID=com.example.android -e USER_KIND=admin flows/login.yaml
+```
+
+```yaml
+- runFlow:
+    file: login.yaml
+    env:
+      USER_KIND: admin
+- runScript:
+    file: setupUser.js
+    env:
+      role: admin
+```
+
+Do not hardcode secrets in YAML. Use repo-approved secret injection, Maestro Cloud secrets, or CI environment variables.
+
+## Output Rules
+
+- `--format junit --output <path>` creates CI-readable JUnit XML.
+- `--format html` or `--format html-detailed` creates HTML reports.
+- `--test-output-dir` stores screenshots, videos, `commands-*.json`, and AI reports.
+- `--debug-output` stores `maestro.log`; when same as `--test-output-dir`, outputs consolidate.
+- config.yaml cannot configure report generation; it can configure `testOutputDir`.
+
+## Closure Evidence
+
+Every Maestro closure should include:
+
+- command and exit status
+- report format and report path
+- `--test-output-dir`
+- `--debug-output` when used or skipped reason
+- app/platform/device
+- environment source, with secrets redacted
+- validation assets protected

package/skills/massa-ai/references/maestro/fact-ledger.md

@@ -0,0 +1,71 @@
+# Maestro Fact Ledger
+
+Use this before making Maestro claims. It defines source authority, fact tags, local transcript requirements, and quarantine rules for unsupported checklist items.
+
+## Authority Order
+
+1. `official-doc`: current official Maestro documentation, preferably `.md` pages under `https://docs.maestro.dev/`.
+2. `live-help`: successful local CLI transcript from the installed Maestro binary, including command, exit code, stdout, and stderr.
+3. `repo-convention`: current repository flows, config, CI, scripts, report paths, and existing naming/tag patterns.
+4. `excluded/unverified`: NotebookLM answers, `/Users/luizmassa/Downloads/questions.md`, blog posts, memory, or assumptions that are not confirmed by the first three sources.
+
+If sources conflict, prefer `official-doc` for product behavior and `live-help` for installed CLI syntax. Mention version drift when `live-help` differs from docs.
+
+## Fact Tag Rules
+
+Every normative statement in Maestro workflows, reports, or implementation notes must carry a source class in the agent's working notes:
+
+- `official-doc`: cite the page URL or title.
+- `live-help`: include command, exit code, stdout summary, stderr summary, and Maestro version when available.
+- `repo-convention`: cite local path or command evidence.
+- `excluded/unverified`: name the unsupported claim and do not use it as a requirement, fix direction, or verification gate.
+
+Do not copy long transcripts into final reports. Summarize exact evidence and keep raw logs behind context-firewall boundaries.
+
+## Required Live CLI Transcript Gate
+
+Before using a live CLI fact, capture:
+
+| Probe | Required evidence |
+|---|---|
+| `command -v maestro` | command, exit code, stdout path, stderr |
+| `maestro --version` | command, exit code, stdout version, stderr |
+| `maestro --help` | command, exit code, stdout subcommand/global option summary, stderr |
+| Relevant subcommand help | command, exit code, stdout option summary, stderr |
+
+Run relevant subcommand help for the surface in use: `maestro test --help`, `maestro cloud --help`, `maestro record --help`, `maestro mcp` or supported MCP help shape, and any repo-specific command wrapper.
+
+If PATH cannot resolve `maestro`, mark local CLI validation blocked. If the binary exists but cannot start, record the failure and avoid claiming executable readiness. Do not install Maestro automatically.
+
+## Coverage Checklist Handling
+
+Use `/Users/luizmassa/Downloads/questions.md` as a checklist to ask "did we cover this surface?" Never cite it as source truth.
+
+Checklist-only facts that must stay non-normative unless independently verified:
+
+- `maestro query` as a CLI subcommand.
+- Dashboard polling URL or API response shape not found in official docs or Maestro MCP tool metadata.
+- Unsupported flags such as `--flavor`, singular `--shard`, generic `--debug`, or non-web `--headless` when current docs/live help do not support them.
+- Obsolete BYO AI guidance such as `MAESTRO_CLI_AI_KEY` or `MAESTRO_CLI_AI_MODEL`.
+- WSL-specific caveats unless official docs or repo convention explicitly establish them for the target project.
+
+## Current Source Anchors
+
+Use these pages first:
+
+- CLI command matrix: https://docs.maestro.dev/maestro-cli/maestro-cli-commands-and-options.md
+- YAML commands: https://docs.maestro.dev/reference/commands-available.md
+- Selectors: https://docs.maestro.dev/reference/selectors.md
+- Workspace config: https://docs.maestro.dev/reference/workspace-configuration.md
+- Reports/artifacts: https://docs.maestro.dev/maestro-flows/workspace-management/test-reports-and-artifacts.md
+- JavaScript: https://docs.maestro.dev/maestro-flows/javascript/run-and-debug-javascript.md
+- Cloud build: https://docs.maestro.dev/maestro-cloud/build-your-app-for-the-cloud.md
+- Cloud limits: https://docs.maestro.dev/maestro-cloud/limits.md
+- MCP: https://docs.maestro.dev/get-started/maestro-mcp.md
+
+## Failure Handling
+
+- Missing official page: use the docs query interface or `llms.txt`; otherwise tag the fact `excluded/unverified`.
+- Live help blocked by sandbox or permissions: retry only when allowed, then record blocked reason and proceed with official-doc facts only.
+- Repo has no Maestro flows: ask for the target test root before creating one.
+- Repo convention conflicts with official docs: preserve repo behavior for existing suites, but do not generalize it beyond that repository without a source tag.

package/skills/massa-ai/references/maestro/js-scripting.md

@@ -0,0 +1,70 @@
+# Maestro JavaScript Reference
+
+Use this for `evalScript`, `runScript`, inline expressions, generated data, shared state, and JavaScript logging.
+
+## Execution Methods
+
+Maestro supports three JavaScript paths:
+
+1. Inline `${...}` expressions inside YAML command values.
+2. `evalScript` for short logic-only steps.
+3. `runScript` for external `.js` files with reusable or complex logic.
+
+```yaml
+- inputText: ${'User_' + faker.name().firstName()}
+- evalScript: ${output.timestamp = new Date().getTime()}
+- runScript:
+    file: setupUser.js
+    env:
+      role: admin
+```
+
+## Shared State
+
+Use `output` for data shared between scripts and later flow steps.
+
+```yaml
+- evalScript: ${output.email = 'qa_' + Date.now() + '@example.com'}
+- inputText: ${output.email}
+```
+
+Keep output values small and non-secret. Do not put tokens, raw PII, or credentials into logs or artifact reports.
+
+## Script Env
+
+```yaml
+- runScript:
+    file: setupUser.js
+    env:
+      userRole: admin
+```
+
+```javascript
+const role = userRole;
+console.log('Setting up role: ' + role);
+```
+
+## Logging
+
+`console.log` output is captured in `maestro.log` with a JavaScript console prefix. `maestro.log` belongs to `--debug-output`, not `--test-output-dir`, unless both flags point at the same directory.
+
+Limitations from official docs:
+
+- Multiple `console.log` arguments are not supported; concatenate or use template literals in external files.
+- Template literals do not work inside `evalScript` the way they do in external `.js` files because `evalScript` already uses `${...}` syntax.
+
+```yaml
+- evalScript: '${console.log("Value: " + output.email)}'
+```
+
+## When To Use JS
+
+Use JS for:
+
+- generated test data
+- lightweight derived values
+- setup/teardown API calls when the repo already permits them
+- assertions via `assertTrue`
+- reusable selector constants when the repository has that convention
+
+Avoid JS when a native Maestro command is clearer. Keep helpers deterministic and committed with the flow when they are part of the test contract.