# How `Mobility_relevant` field sets drive the local SQLite schema

## What a field set is

A Salesforce field set is an ordered list of fields on an SObject that an admin can maintain without code. In CG Mobile, the field set named exactly `Mobility_relevant` is the contract between the org and the mobile sync layer: fields in this set are synced to the device's SQLite database; fields outside it are not.

## Why this matters for DataSources

When a `.datasource.xml` file declares a column, the framework eventually reads it from the device's SQLite. If the column isn't in the field set on the org side, it was never synced, so the SQLite table doesn't have it, and the DS crashes at runtime with `SQLITE_ERROR: no such column`.

## Remediation contract (what this skill automates)

| Observed state                                      | Action                                                                     |
| --------------------------------------------------- | -------------------------------------------------------------------------- |
| Field exists on SObject, NOT in `Mobility_relevant` | Offer to add field to field set (gated by user approval)                   |
| Field exists on SObject, IS in `Mobility_relevant`  | Suggest resync — the field set is correct, local DB is stale               |
| Field does NOT exist on SObject                     | Stop — field must first be created on the org (outside this skill's scope) |

## Adding a field to the field set — XML shape

A field set XML file (`Mobility_relevant.fieldSet-meta.xml`) looks like:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<FieldSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Mobility_relevant</fullName>
    <description>Fields synced to CG Mobile</description>
    <displayedFields>
        <field>Id</field>
        <isFieldManaged>false</isFieldManaged>
        <isRequired>false</isRequired>
    </displayedFields>
    <displayedFields>
        <field>Name</field>
        <isFieldManaged>false</isFieldManaged>
        <isRequired>false</isRequired>
    </displayedFields>
    <!-- ... -->
    <label>Mobility Relevant</label>
</FieldSet>
```

To add a field, insert a new `<displayedFields>` block using the template at `templates/fieldset-addition.xml.template`.

## Managed-package quirks

If the SObject is `retailexecution__Visit__c` (managed package), the field set may have the same prefix: `retailexecution__Mobility_relevant`. In that case:

-   The field set may be read-only from your org (can only be modified by the package publisher)
-   Check the `deployable` property — if false, stop and suggest filing a request with the package team
-   If the field set is unmanaged (overridable), deploy proceeds normally

## After a successful deploy

1. Field is now in the field set on the org
2. Mobile sync brings the column down on next sync
3. Confirm locally: re-run `PRAGMA table_info(<table>)` and see the new column

The user may need to manually trigger a sync in the simulator — this is outside the skill's scope but worth mentioning in the report.