> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapping.travel/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules and decisions

> How the rule set shapes what your agent can do — and what it can't.

The rule set is the contract between you and your agent. It lists, per surface (mapping jobs, unmatched results, mismatch reports, coverage, data sources/sinks, exports, bulk updates, notifications), what the agent is allowed to do autonomously. Tool calls against a disabled rule return `error: "rule_disabled"` to the LLM, which then adapts — typically by filing a pending item or summarising differently.

## Orchestration + triage, not confidence judgement

<Warning>
  Agents in v1 are an **orchestration and triage layer**, not a per-row confidence-judgement layer. Confidence-threshold rules (e.g. *"auto-approve any match above 0.95 confidence"*) are **not** supported in v1. The `PartnerMappingResult.matchConfidence` field is nullable in production and is not relied upon by the rule engine.
</Warning>

What this means in practice:

* The agent **proposes** matches for unmatched rows. A human approves.
* The agent **drafts** proposed resolutions for mismatch reports. A human marks `FIXED` / `REJECTED`.
* The agent **never** auto-links a result to a reference hotel.
* The agent **never** auto-marks a mismatch as fixed or rejected.

Confidence-based auto-approval is on the roadmap but explicitly excluded from v1. See the [overview roadmap section](/agents/overview#v1-roadmap-not-yet-shipped).

## Rule set JSON shape

```json theme={null}
{
  "mapping_jobs": {
    "trigger_on_new_inventory_upload": true,
    "trigger_on_cron": false,
    "re_run_on_golden_dataset_change": false
  },
  "unmatched_results": {
    "propose_candidates_for_review": true,
    "max_candidates_per_row": 3,
    "search_strategies": ["geo", "name"]
  },
  "mismatch_reports": {
    "auto_transition_open_to_in_progress": false,
    "group_similar": true,
    "post_proposed_resolution": true
  },
  "coverage": {
    "alert_below_pct": 95,
    "weekly_digest": true
  },
  "data_sources": {
    "auto_pull_on_schedule": true,
    "pause_source_after_failures": 3
  },
  "data_sinks": {
    "auto_push_on_job_complete": false,
    "retry_failed_push": 2
  },
  "mode_preference": { "allow_auto_change": false },
  "export":          { "allow_auto_export": false },
  "bulk_update":     { "allow_auto_bulk_update": false },
  "notifications": {
    "on_action": true,
    "on_escalation": true,
    "on_pause": true,
    "on_cost_threshold_pct": 80
  }
}
```

## What the agent can vs cannot do (v1)

| Surface                            | Agent CAN                                                                       | Agent CANNOT                                 |
| ---------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------- |
| `MappingJob`                       | Trigger on upload + cron, poll, summarise                                       | Cancel a running job (deferred)              |
| `PartnerMappingResult` (unmatched) | Search candidates, file proposed matches as pending                             | Auto-link a result                           |
| `PartnerMappingResult` (matched)   | Read, count, report                                                             | Modify or unlink                             |
| `MismatchReport`                   | `OPEN → IN_PROGRESS` (rule-gated, default off), group, post proposed resolution | Auto-mark `FIXED` or `REJECTED`              |
| `ReferenceHotelDuplicateReport`    | Read + summarise                                                                | Anything mutating (cross-tenant golden data) |
| Coverage statistics                | Compute, alert, weekly digest                                                   | —                                            |
| `mapping_mode_preference`          | Read                                                                            | Change (rule-gated, default off)             |
| Exports                            | Read                                                                            | Auto-export (rule-gated, default off)        |
| Bulk partner updates               | Nothing                                                                         | Nothing                                      |
| Data sources (inbound)             | Auto-pull (default on once configured)                                          | Pull from unconfigured sources               |
| Data sinks (outbound)              | Auto-push (rule-gated, **default off**)                                         | Push to unconfigured sinks                   |
| Memory + pending items             | Read/write its own                                                              | —                                            |

## Versioning

Every rule-set save creates a new row with `version = max(version) + 1` and a `supersedes_id` pointing to the previous version. Every `AgentRun` records the version it executed under. The UI shows *"this action was taken under rule set v3"* alongside historic runs.

## Editing rules

<Tabs>
  <Tab title="Web UI">
    Go to **Agents → \[your agent] → Settings → Rules**. Toggle the rule, click **Save**. Active cycles finish under the old rule set; the next cycle picks up the new one.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://api.mapping.travel/api/v1/agents/{id}/rule-sets \
      -H 'X-API-Key: mt_...' \
      -H 'Content-Type: application/json' \
      -d @new-rules.json
    ```

    Returns the new version with `supersedes_id` set.
  </Tab>
</Tabs>

## Related

* [Agents overview](/agents/overview) — what agents are and the trust model.
* [Configuration reference](/agents/configuration-reference) — field-by-field.
* [Audit and undo](/agents/audit-and-undo) — every rule-set change is audit-logged.
* [Cost and limits](/agents/cost-and-limits) — separate from rules but co-enforced.