tres-settings-management

# TRES MCP - Organization & Platform Settings

## How This Skill Works

This skill lets users view and modify configuration for their TRES Finance organization and individual blockchain/exchange platforms. There are two levels:

- **Organization Settings** — Apply to the entire org: how cost basis is calculated, which features are enabled, ERP behavior, pricing sources, commit scheduling, etc.
- **Platform Settings** — Apply per-platform (e.g., Ethereum, Arbitrum) and optionally per-wallet: commit strategy, sync date boundaries, balance diff, asset filtering, etc.

---

## Ground Rules

### 1. Always Start by Identifying the Org

Before doing anything, confirm which organization the user is connected to:

```graphql
query { admin { orgName } }
```

Tell the user: "You're connected to **{orgName}**."

### 2. Read Before Write

Before any mutation, ALWAYS fetch the current value of the setting(s) being changed. Show a clear before/after comparison.

### 3. Mutations Require Explicit Approval

Before executing ANY mutation, you MUST:
1. Show a clear summary table with **Setting**, **Current Value**, and **New Value**
2. Explicitly ask: "Shall I apply these changes to **{orgName}**?"
3. Only proceed after the user confirms
4. After execution, show the confirmed result from the mutation response

### 4. Warn About High-Risk Changes

Flag these settings as potentially dangerous and add a warning:
- `costBasisStrategy` — Changing mid-period can cause recalculations across the entire org
- `disableAutoCommit` — Stops all automatic data processing
- `skipCostBasis` — Disables cost basis entirely
- `commitStrategy: SKIP_ALL` — Fully disables a platform's data pipeline
- `enableMultiEntity` — Structural change, hard to reverse
- `allowShort` — Enables short positions in cost basis

### 5. Use Schema Introspection for Field Discovery

Do NOT rely on hardcoded field lists. Use the MCP `introspect` tool to discover available fields and their types dynamically:

- `introspect("OrganizationSettingsObjectType")` — all readable org settings
- `introspect("setOrganizationSettings")` — all writable org settings with descriptions
- `introspect("PlatformSettingsObjectType")` — all readable platform settings
- `introspect("setPlatformSettings")` — all writable platform settings with descriptions

When a user asks "what can I configure?" or you need to verify a field name or enum values, introspect first.

---

## Setting Categories (use when users ask vaguely)

If the user says "show me the settings" without specifics, offer these categories with plain-language explanations:

| Category | What It Controls |
|---|---|
| **Cost Basis** | How gains/losses are calculated (FIFO, LIFO, etc.), per-wallet vs org-wide, impairment |
| **Commit Pipeline** | Automatic data processing schedule, priority, stuck detection, sync hours |
| **Internal Transfers** | How transfers between the org's own wallets are detected and matched |
| **Pricing** | Where asset prices come from, stablecoin pegging, swap alignment |
| **ERP Integration** | How data syncs to accounting systems (NetSuite, Xero, QuickBooks) |
| **Dashboard & Features** | Which UI features are enabled (pivot tables, vesting, payments, multi-entity) |
| **Staking** | Staking rewards tracking and position management |
| **Reconciliation** | Cross-org and subsystem reconciliation behavior |
| **Reports** | Scheduled report timing, format, and content |
| **Platform Collection** | Which blockchains/exchanges are enabled, their sync boundaries and filters |

---

## Reading Organization Settings

### Query Structure

```graphql
query {
  admin {
    orgName
    organizationSettings {
      # include only the fields relevant to the user's question
    }
  }
}
```

- Organization is resolved from the auth token — no org ID needed
- Never request all fields at once — pick the category relevant to the question
- Use `introspect("OrganizationSettingsObjectType")` to discover available fields if needed

### Nested Fields (must expand sub-fields when querying)

These fields return objects/lists, not scalars. Always include their sub-fields:

| Field | Sub-fields | What It Is |
|---|---|---|
| `peggedStableCoinsToFiat` | `assetName`, `currency` | Stablecoins treated as equivalent to fiat |
| `pricingApiSourcePerAsset` | `assetName`, `pricingApiSource` | Custom pricing source per asset |
| `netsuiteCurrencySymbolToInternalId` | `currency`, `internalId` | NetSuite currency mapping |
| `simpleMatchingStrategies` | `beforeRange`, `afterRange` | Reconciliation time windows |
| `proofOfFunds` | `organizationName` | Proof of funds client config |

### Additional Admin Fields

The `admin` query also provides:
- `orgName` — the organization's display name
- `disabledPlatforms` — quick list of platforms with collection fully disabled
- `auth0Connections` — available SSO login methods

---

## Writing Organization Settings

### Mutation Structure

Uses patch semantics — only include the fields you want to change. Everything else stays as-is.

```graphql
mutation {
  setOrganizationSettings(
    costBasisStrategy: FIFO
  ) {
    organizationSettings {
      costBasisStrategy
    }
  }
}
```

Use `introspect("setOrganizationSettings")` to discover all mutable fields, their types, and descriptions.

### Workflow for Changing Org Settings

1. **Read** the current values of the setting(s) being changed
2. **Show** the user a before/after comparison table
3. **Warn** if any high-risk settings are involved
4. **Ask** for approval
5. **Execute** the mutation
6. **Confirm** by showing the returned values

---

## Reading Platform Settings

### Query Structure (top-level query)

Returns only platforms/accounts with explicit overrides. Platforms using all defaults won't appear.

```graphql
query {
  platformSettings(platform: ETHEREUM) {
    results {
      settingsId
      platform
      internalAccountId
      platformSettings {
        commitStrategy
        calculateBalanceDiff
        minLastS