# mx-auto Learning Guide

Use one trigger-oriented rule set:

1. Normalize the user request into one local trigger list or trigger execution request.
2. Current active mode is `local` only.
3. Resolve config from per-run args, then environment, then stored preferences.
4. Resolve trigger identity from cached exact trigger name first, then explicit `triggerId`.
5. Dispatch only through the local Runtime path.
6. For agent-to-agent usage, prefer explicit structured output over prose when a script supports it.

## Asking Rules

Ask only for values that are still missing after checking args, environment, and stored preferences.

Missing values worth asking for:

- local mode
  - a reachable local Runtime setup when the Runtime URL cannot be discovered
  - `triggerId` or `triggerName`

Do not ask for values that are already present in:

- `MX_AUTO_CONNECTION_MODE`
- `MX_AUTO_LOCAL_BASE_URL`
- `MX_AUTO_WAIT`
- `MX_AUTO_LEASE_TTL_MS`
- `MX_AUTO_POLL_SEC`
- `MX_AUTO_TIMEOUT_SEC`
- `MX_APP_RUNTIME_BASE_URL`
- `RPA_RUNTIME_BASE_URL`
- stored `triggerSnapshot`

Hard defaults for local mode:

- do not proactively ask for port
- do not proactively ask for keyword or `input`
- first try auto-discovery
- first try empty-input execution when a trigger is already named
- ask follow-up questions only if auto-discovery fails or Runtime explicitly reports missing required input

## Shared Flow

1. Run `scripts/preflight_check.sh`
2. Persist user-facing defaults when this turn provides them
3. If listing triggers, refresh `triggerSnapshot` from `/trigger-services` and return a human-readable list
   - for agent parsing, use `--list-format json`
4. If executing a trigger, refresh `triggerSnapshot` from local Runtime when local access is available and the request benefits from it
5. Resolve `triggerId`
6. Build the command:
   - `{ target: "trigger.execute", payload: { triggerId, input? }, wait, leaseTtlMs }`
7. Dispatch through `scripts/local_dispatch_loop.sh`
8. When the user did not provide explicit business input, try the trigger with no `payload.input` first
9. Only ask for business fields after a clear missing-input failure from Runtime or from the trigger itself

## Trigger Payload

Minimum payload:

```json
{
  "triggerId": "trigger_xxx"
}
```

Input handling:

- If the user supplies structured business input, pass it as `payload.input`.
- `payload.input` must be a JSON object when present.
- Do not invent extra fields.

## Trigger Snapshot Rules

When refreshing from `/trigger-services`:

- cache only stable fields used for later selection
- cache only callable and available trigger services
- keep:
  - `id`
  - `name`
  - `summary`
  - `status`
  - `callable`
  - `available`
  - `lastRunAt`
  - `updatedAt`

When resolving by `triggerName`:

- require exact match
- if the cache is missing or stale, tell the user to refresh triggers locally
- do not fuzzy-match and risk running the wrong trigger
- when exact match fails, include the cached candidate names in the error when possible

When listing triggers:

- default to a human-readable list
- show:
  - name
  - status
  - summary only when it is human-meaningful
- do not default to raw JSON
- when another agent needs deterministic parsing, use JSON output with:
  - `mode`
  - `sourceMode`
  - `loadedAt`
  - `registryPath`
  - `triggerCount`
  - `triggers[]`

## Failure Framing

Local mode failures should say whether the problem is:

1. Runtime unavailable
2. Runtime unauthorized
3. trigger resolution/cache miss
4. trigger execution failure

Use this minimal failure guidance:

- Runtime unavailable
  - tell the user to check whether the local Runtime is running
- Runtime unauthorized or local auth/config mismatch
  - tell the user to check local Runtime permissions or local Runtime configuration

Cloud-related files are reserved only. If the user explicitly tries cloud mode in this version, say it is reserved and not enabled yet.