# Act on the desk’s suggestions

How the desk works for you: detectors watch your own data and draft plans — low stock worth ordering, reviews waiting too long, stock worth moving. You only ever see what your own permissions could run; taking one opens a scratchpad you approve and realize yourself.

Work · a guided walk in 3 steps.

## The steps

1. **Check the desk** — The check runs every active detector now — new findings become offers, each with its why and a drafted plan. — [refreshSuggestions](/reference/work-and-notes/refreshSuggestions/)
2. **Take what you agree with** — Taking mints a scratchpad from the drafted plan — reviewed and realized under your own permissions, like any other. — [takeSuggestion](/reference/work-and-notes/takeSuggestion/), [transitionScratchpad](/reference/scratchpad/transitionScratchpad/), [realizeScratchpad](/reference/work-and-notes/realizeScratchpad/)
3. **Decline what you won’t do** — A decline is a learning signal — the desk stops re-offering that finding while your reason stands. — [declineSuggestion](/reference/suggestion/declineSuggestion/)

## The calls

Every operation this use case runs, in the order it first appears, with the request and the response its reference page shows.

### refreshSuggestions

[refreshSuggestions](/reference/work-and-notes/refreshSuggestions/) — mutation · Ask the suggestions desk to look now — it runs every active detector for one organization and refreshes the offers.

**Example request**

```graphql
mutation ExampleRefreshSuggestions($organizationId: ID!) {
  refreshSuggestions(organizationId: $organizationId) {
    minted
    superseded
    expired
    skippedDuplicate
    skippedDeclined
    skippedTaken
    skippedCapped
    schemasEnsured
    doomedHeld
    parkedSkills
  }
}
```

Variables:

```json
{
  "organizationId": "01900000-0000-7000-8000-44b781470000"
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "refreshSuggestions": {
      "minted": 1,
      "superseded": 1,
      "expired": 1,
      "skippedDuplicate": 1,
      "skippedDeclined": 1,
      "skippedTaken": 1,
      "skippedCapped": 1,
      "schemasEnsured": 1,
      "doomedHeld": 1,
      "parkedSkills": 1
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### takeSuggestion

[takeSuggestion](/reference/work-and-notes/takeSuggestion/) — mutation · Take a suggestion — a scratchpad is created with its drafted plan, ready for your review and approval.

**Example request**

```graphql
mutation ExampleTakeSuggestion($input: TakeSuggestionInput!) {
  takeSuggestion(input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    origin
    intent
    planRevision
    approvedPlanRevision
    inFlightSeq
    realizationFault
  }
}
```

Variables:

```json
{
  "input": {
    "id": "01900000-0000-7000-8000-37386ae00000",
    "revision": "01900000-0000-7000-8000-b7960e180000",
    "reason": "Correcting a miscount."
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "takeSuggestion": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "SD-EXMP-0000-000F",
      "type": "Scratchpad",
      "caption": "Blue jeans",
      "status": "draft",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "origin": "<origin>",
      "intent": "<intent>",
      "planRevision": 1,
      "approvedPlanRevision": 1,
      "inFlightSeq": 1,
      "realizationFault": "<realization fault>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### transitionScratchpad

[transitionScratchpad](/reference/scratchpad/transitionScratchpad/) — mutation · Move a scratchpad through its life — hold the plan for review, reopen it for editing, approve it, or abandon it.

**Example request**

```graphql
mutation ExampleTransitionScratchpad($id: ID!, $revision: ID!, $op: ScratchpadTransitionOp!, $reason: String) {
  transitionScratchpad(id: $id, revision: $revision, op: $op, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    origin
    intent
    planRevision
    approvedPlanRevision
    inFlightSeq
    realizationFault
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "op": "ready",
  "reason": "Correcting a miscount."
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "transitionScratchpad": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "SD-EXMP-0000-000F",
      "type": "Scratchpad",
      "caption": "Blue jeans",
      "status": "draft",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "origin": "<origin>",
      "intent": "<intent>",
      "planRevision": 1,
      "approvedPlanRevision": 1,
      "inFlightSeq": 1,
      "realizationFault": "<realization fault>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### realizeScratchpad

[realizeScratchpad](/reference/work-and-notes/realizeScratchpad/) — mutation · Execute an approved plan — create its records one step at a time under YOUR OWN permissions.

**Example request**

```graphql
mutation ExampleRealizeScratchpad($id: ID!, $revision: ID!, $reason: String) {
  realizeScratchpad(id: $id, revision: $revision, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    origin
    intent
    planRevision
    approvedPlanRevision
    inFlightSeq
    realizationFault
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "reason": "Correcting a miscount."
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "realizeScratchpad": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "SD-EXMP-0000-000F",
      "type": "Scratchpad",
      "caption": "Blue jeans",
      "status": "draft",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "origin": "<origin>",
      "intent": "<intent>",
      "planRevision": 1,
      "approvedPlanRevision": 1,
      "inFlightSeq": 1,
      "realizationFault": "<realization fault>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

### declineSuggestion

[declineSuggestion](/reference/suggestion/declineSuggestion/) — mutation · Decline a suggestion — say why, and the desk keeps your reason so it learns.

**Example request**

```graphql
mutation ExampleDeclineSuggestion($id: ID!, $revision: ID!, $reason: String!) {
  declineSuggestion(id: $id, revision: $revision, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    skill
    schemaId
    why
    dedupKey
    expiresAt
    takenScratchpadId
    declineReason
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "reason": "Correcting a miscount."
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

**Example response**

```json
{
  "data": {
    "declineSuggestion": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "SU-EXMP-0000-000F",
      "type": "Suggestion",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "skill": "<skill>",
      "schemaId": "01900000-0000-7000-8000-e5ee57ab0000",
      "why": "<why>",
      "dedupKey": "<dedup key>",
      "expiresAt": "2027-01-31T00:00:00.000Z",
      "takenScratchpadId": "01900000-0000-7000-8000-65ec6b4e0000",
      "declineReason": "<decline reason>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```