# User Data Bookmarks

When a user picks something from the UI and copies it to their clipboard, they get a **bookmark** — a small JSON blob that tells the backend exactly what to fetch. These are the wire shapes for tables and lists.

The human-readable fields (`*_name`, `description`) are for display only. The IDs are what matters.

---

## Table Bookmarks

**Fetch implementation:** `user_data/table_reference_fetch.py`

### Entire table
```json
{
  "type": "full_table",
  "table_id": "3b81bb2e-740e-4c6b-817c-b6c6f750a018",
  "table_name": "AI Model Benchmarks",
  "description": "Reference to entire table \"AI Model Benchmarks\""
}
```

### Entire column
```json
{
  "type": "table_column",
  "table_id": "3b81bb2e-740e-4c6b-817c-b6c6f750a018",
  "table_name": "AI Model Benchmarks",
  "column_name": "model",
  "column_display_name": "Model",
  "description": "Reference to column \"Model\" in table \"AI Model Benchmarks\""
}
```

### Specific row
```json
{
  "type": "table_row",
  "table_id": "3b81bb2e-740e-4c6b-817c-b6c6f750a018",
  "table_name": "AI Model Benchmarks",
  "row_id": "cfc3841f-2343-4324-a1cd-3cf129ae1175",
  "description": "Reference to row cfc3841f-2343-4324-a1cd-3cf129ae1175 in table \"AI Model Benchmarks\""
}
```

### Specific cell
```json
{
  "type": "table_cell",
  "table_id": "3b81bb2e-740e-4c6b-817c-b6c6f750a018",
  "table_name": "AI Model Benchmarks",
  "row_id": "cfc3841f-2343-4324-a1cd-3cf129ae1175",
  "column_name": "model",
  "column_display_name": "Model",
  "description": "Reference to cell \"Model\" in row cfc3841f-2343-4324-a1cd-3cf129ae1175 of table \"AI Model Benchmarks\""
}
```

| `type` | Required IDs | What you get back |
|---|---|---|
| `full_table` | `table_id` | All rows — flattened JSONB + `id`, `created_at`, `updated_at` |
| `table_column` | `table_id`, `column_name` | All rows, that column only (+ `id`) |
| `table_row` | `table_id`, `row_id` | One flattened row or `null` |
| `table_cell` | `table_id`, `row_id`, `column_name` | Single value or `null` |

---

## List Bookmarks

**Fetch implementation:** `user_data/list_reference_fetch.py`

Lists are **flat collections of items** — each item has `label`, `description`, `help_text`, `group_name`, `icon_name`. There are no arbitrary columns, so there is no cell equivalent.

### Entire list
```json
{
  "type": "full_list",
  "list_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "list_name": "Resume Checklist",
  "description": "Reference to entire list \"Resume Checklist\""
}
```

### Items in one group
```json
{
  "type": "list_group",
  "list_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "list_name": "Resume Checklist",
  "group_name": "Personal Info",
  "description": "Reference to group \"Personal Info\" in list \"Resume Checklist\""
}
```

### Single item
```json
{
  "type": "list_item",
  "list_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "list_name": "Resume Checklist",
  "item_id": "e5f6a7b8-c9d0-1234-efab-567890abcdef",
  "item_label": "Full Name",
  "description": "Reference to item \"Full Name\" in list \"Resume Checklist\""
}
```

| `type` | Required IDs | What you get back |
|---|---|---|
| `full_list` | `list_id` | `{ "list": metadata, "items": [...] }` |
| `list_group` | `list_id`, `group_name` | Flat items in that group (empty string = ungrouped) |
| `list_item` | `list_id`, `item_id` | One item dict or `null` |

---

## Parallel summary

| Granularity | Table bookmark | List bookmark |
|---|---|---|
| Everything | `full_table` | `full_list` |
| Slice / column | `table_column` | `list_group` |
| Single row / item | `table_row` | `list_item` |
| Single value | `table_cell` | *(no equivalent)* |
