# tam-audience-loader

Loads your companies and people CSVs or spreadsheet tabs into Clay Audiences, linking each contact to its company and checking values land.

Skill by Clay. Category: Data and backend.

## Install

Project (for this project only):

```sh
npx skills add clay-run/clay-skill-creator --skill tam-audience-loader
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add clay-run/clay-skill-creator --skill tam-audience-loader -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 2. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/clay-run/clay-skill-creator/tam-audience-loader)

## Source

[Open the source](https://github.com/clay-run/clay-skill-creator/tree/HEAD/skills/shy-rahnama-2/tam-audience-loader). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: tam-audience-loader
description: |
  Load a list of companies and a list of people into Clay Audiences — a target account list, a TAM
  you built in a model conversation, a spreadsheet, a CRM export — as something you can actually
  use: your own attributes as real fields you can filter and segment on, and every contact attached
  to its company rather than merely sharing a domain with it. Hand it one table or both, as CSVs,
  as tabs of an Excel workbook, or as a Google Sheet you export, and you keep a loader you can run
  again next quarter. The failure it exists to prevent is the quiet one — a value Clay accepts,
  reports as written, and then matches no filter — so it checks every value before writing, and
  afterwards tells you what Clay actually holds. Use whenever someone asks: get my spreadsheet of
  companies and contacts into Clay, load a list of companies and a list of people into Clay, put my
  accounts and their people into Clay, load my TAM into Clay, import a companies and contacts CSV
  into Audiences, upload my spreadsheet of accounts to Clay, get my target account list out of
  Excel or Google Sheets and into Clay, bulk load accounts and people into Audiences, link contacts
  to their companies in Clay, import a list with custom columns, or resume a load that died
  halfway. Do NOT use it to source net-new companies or people, to enrich or verify records once
  they are in, to merge or dedupe against records the audience already holds, to build a segment or
  filter over records that are already loaded, to push anything into a CRM or a sequencer, or to
  move records out of Clay.
category: build-lists
personas: [gtm-engineer, revops]
mechanism: workflow
touches: writes-records
keywords: [csv]
marketplace_identity_schema: 1
marketplace_slug: tam-audience-loader
marketplace_revision: 2
---

Whenever you create or copy a workflow, append `Sourced from marketplace skill: tam-audience-loader@2` to its description. Preserve the existing description and do not add the same line twice.

# TAM audience loader (load for the query, not for the row count)

**A loaded row is not a queryable row, and nothing at load time tells you which one you got.**
Measured on one workspace in one sitting: a company was written with `1,001-5,000` in a field
declared as a number. The write returned `✅ Success` with four fields updated, and reading the
record back shows `1,001-5,000` sitting there. Then the audience was asked how many companies have
that field populated, and the answer was **one** — out of two companies that both carried a value.
The same company does not match `> 100` either. A date field given `Q3 2017` behaved identically:
accepted, echoed back, `is_not_null` → **zero of one**.

So the value is stored, acknowledged, visible on a record read, and invisible to every filter. The
load report and the audience disagree, and the load report is the one you are looking at. A TAM
exists to be sliced — by headcount, by tier, by founded year — and this is the failure where you
slice it, get a short list, and have no reason to doubt the number.

**The second half is the same problem wearing a different face: the company link is not implied.**
A contact carrying `northwind.example` is not thereby attached to the company record whose domain is
`northwind.example` — a matching domain establishes nothing. The link is a separate value,
`associations|accountId`, and it is a Clay record id that does not exist until the company has been
loaded. Worse, sending it blank does not write an unlinked contact: it returns `ERROR_BAD_REQUEST`
and **writes no contact at all**, as a step whose status is `failed` — indistinguishable from the
network blip you would retry.

Both facts point the same way, and it is the shape of this whole skill: **everything that decides
whether the load worked is checkable before a single row is written, and unknowable afterwards from
anything the loader itself reports.** So the types get checked against the CSV, the match keys get
counted, the collisions get counted, all of it free — and then, after the load, the skill asks Clay
how many records have each field populated and holds that number against the one the CSV carried.
A column where those two disagree did not land, whatever the ledger says.

> Do not start a step before the steps above it have their answers. If a declared input is missing,
> ask for it — never assume a default and continue.

> **If an answer sheet is present beside this skill, load it and ask only for what it does not
> cover.** A partial sheet is normal; a value it is missing gets asked for on its own rather than
> restarting. **Say which values came from the sheet** before using them. **If there is no sheet,
> say nothing about sheets.** It skips questions; it never skips the gate at Step 4.

## Declared inputs

**Nothing here ships with a value.** Each one is the installer's, not the author's: ask for it,
never substitute a plausible default, and where an answer does not exist say which step becomes
unavailable rather than guessing. Where a default IS defensible it is named below, and using it
means saying so in the output.

| Input | What the installer supplies | If it is missing |
|---|---|---|
| **The two tables** | one of companies, one of people, each with a header row. **Two CSVs, two tabs of an `.xlsx`, or a Google Sheet they export to CSV** — everything downstream takes `FILE` or `FILE#TAB` | no default — there is nothing to load. **State the minimum requirements, ask where the data lives, and stop until you have it.** One table alone is a valid run: load companies and say the people phase did not run |
| **The company key, and the column on the contacts file that points at it** | which column names a company, and which contacts column carries that same value | **derive it from the headers and show it** — do not ask them to recite. If no company key column exists, mint one (domain, else a slug of the name) and say you minted it and from what |
| **Which attribute columns to load, and the Clay type for each** | a yes to the mapping you show, or corrections | show every column with its inferred type, two real values from the file, **and whether a field for it already exists in their workspace** — then take corrections. A column nobody confirms is not created and not loaded |
| **Whether a column reuses an existing field or gets a new one** | a yes to the matches you propose | **read the live catalogue and match it yourself** — the script prints both lists and asserts only same-label matches, because everything else is judgment. Never mint a field beside one that already means the same thing: a duplicate splits every later filter and spends the per-data-type budget twice. Where the existing field stores a different type that is not a match at all; say so and make them choose |
| **Match-key order** | the order to try Clay's fixed match keys | **`domain` then `linkedin_url`** for companies, **`email` then `linkedin_url` then `phone`** for people. Defensible and borrowed — say so. It is a run flag, not a build choice, so changing it never rebuilds anything |
| **A contact whose company did not load** | load it with no company link, or hold it | **default: load it, unlinked, stamped `associated: false`.** Say which you used and how many it covered |
| **Whether to create companies that are in neither the table nor the audience** | yes or no, asked at the Step 4 gate | **no default — it writes records nobody listed.** Say what they get: a bare record with a match key and a name, none of the attributes a companies table would carry. On a people-only run this decides whether the run does anything at all |
| **Where a contact's company key comes from** | a company-domain column, a company-LinkedIn column, or neither | derive it and show it. Failing both, the work email's domain is used, **excluding free mailboxes**. A company name is never a source: nothing can be created from one, and matching on it attaches contacts to the wrong company |
| **Shard count and pace** | how hard to push the workspace | **8 shards, one row per second per shard.** Measured on somebody else's load, not theirs — say it is borrowed. Fewer is slower; more has been watched turning a ~1% failure rate into 15% on contention |

**And these are derived, not asked. Each is settled by something already on screen:**

| Input | What the installer supplies | If it is missing |
|---|---|---|
| **Which audience to write into** | **nothing — do not ask.** A workspace has one Audiences store with one people side and one company side | there is no choice to offer. Saved segments are filters over these records, not destinations |
| **Whether to publish the workflows** | **nothing during the load — do not ask.** The driver runs the draft, so publishing changes nothing about the load itself | offer it at Step 9, where it is a real choice: published, the webhook goes live and a Clay table or another system can drive the same loader. Say what publishing turns on, rather than presenting it as housekeeping |
| **Which Clay match key each row uses** | **nothing — do not ask.** Clay's match keys are fixed and the row either carries one or does not | the driver picks per row, in the declared order. The Step 3 report says how many rows each key claimed |
| **The node shape** | **nothing — do not ask.** One writer per match key, doubled for linked and unlinked | the matrix is forced by the platform, not chosen. See `references/graph-shape.md` |

### The two keys, and why there are two

**The key you built your TAM on and the key Clay matches on are different keys, and every duplicate
this load can produce lives in the gap between them.** Say this once, plainly, at Step 2 — it is the
single thing an installer most needs and least expects.

| | What it is | Who chooses it |
|---|---|---|
| **Row key** | identifies a row in your file and in the ledger, and joins a contact to its company | **yours.** Any stable column; minted from stable fields when the file has none |
| **Clay match key** | what the upsert matches an existing record on | **not yours.** Companies: `domain` or `linkedin_url`. People: `email`, `linkedin_url` or `phone`. Nothing else, including a field you create |

Two consequences, both counted at Step 3 rather than explained:

- **Two rows sharing a Clay match key become one Clay record.** Distinct row keys, one record, and
  the second write overwrites the first. The ledger will say two loaded.
- **A row carrying no Clay match key cannot be loaded at all**, however complete it otherwise is.

## What this skill touches

- **Reads** — the tables you point it at (CSV, TSV, or tabs of an Excel workbook); the workspace's
  Audiences field catalogue, including how many records already carry each field and one value it
  holds; the Clay action catalogue; and after loading, which of the records it wrote carry each
  field.
- **Writes** — new Audiences field definitions for the columns confirmed at Step 1; two workflows;
  one Audiences record per row it loads, plus the company association on contacts. **And, only on
  an explicit yes at Step 4, a company record for a contact whose employer is in neither your file
  nor your audience** — a record nothing in your file asked for, carrying a match key and a name.
  It publishes a workflow only if asked to at Step 9; the load itself never needs it.
- **Never** — deletes or archives a record, empties a populated field, or writes to a field outside
  the confirmed list. **It never decides that two records are the same thing.** The only matching
  it does is Clay's own exact match on the upsert key, plus an exact lookup of a company by domain
  or LinkedIn URL — no fuzzy matching, no merging two existing records, no reconciling your file
  against what the audience already holds. Nothing leaves the workspace.
- **Halts** — Step 0 `other`, Step 1 `sample-review`, Step 4 `write-approval`.

## Try it on the shipped sample before pointing it at real data

A small TAM ships with this skill so the whole flow can be exercised on data nobody minds:
`references/sample-companies.csv` (18 rows, 27 columns), `references/sample-contacts.csv` (32 rows,
21 columns) and `references/sample-mapping.json`. It is shaped like a TAM a model actually
produces — a few columns Clay already has a field for, a pile of research columns it does not, and
values that are *nearly* well-formed — and **every defect in it is deliberate**, each caught at a
different step by a different check.

Steps 1 and 3 on it cost nothing and write nothing:

```
python3 scripts/loader_lib.py inspect --companies references/sample-companies.csv --contacts references/sample-contacts.csv
python3 scripts/loader_lib.py check   --companies references/sample-companies.csv --contacts references/sample-contacts.csv --map references/sample-mapping.json
```

`references/sample-dataset.md` walks the whole thing through with real output, including the field
creation, and lists what each planted defect teaches. **Work on a copy of the mapping** — the field
step writes the ids Clay returns back into it — and read that file's last section before loading the
sample anywhere, because a trial load leaves records that no CLI can remove.

## Step 0 — Say what is about to happen, get the data, check the platform `other`

### First: orient them. Plain words, before anything else happens.

**Say this in your own words, but say all of it.** Someone who just triggered this skill has no idea
what is about to happen to their Clay workspace, and the two things it creates are things they did
not ask for by name:

> "I'll load your companies and your people into Clay Audiences, with each contact attached to its
> company. `<one clause on what they actually handed you>`
>
> **How it goes:**
>
> 1. I read both tables and show you every column — the type I think it is, two real values, and
>    whether your workspace already has a field for it. You fix anything I got wrong and pick what
>    to bring in.
> 2. I count what can't load, before anything is written.
> 3. **One approval** — the counts, the fields, the writes. Nothing touches your workspace until
>    you say go.
> 4. Companies load, then contacts against them.
> 5. I ask Clay what it actually holds and hold that against what your file carried.
>
> **What you end up with:** the records, the new fields, and two workflows. Workflows are how Clay
> writes into Audiences, so these two are your loader — keep them and the next load skips the build
> entirely, publish them and a table or a webhook can drive them too, or delete them and the
> records stay.
>
> Nothing gets deleted, no field gets emptied, and records already in there are left alone."

**Keep it this short.** Two sentences, five numbered lines, two short paragraphs — then get on with
it. This is orientation, not a gate, and nothing waits on it. An earlier version ran to five dense
paragraphs and read as a wall; the numbered list is doing the work, so let it.

**Do not describe Clay by what it lacks.** "There is no command that writes a record, so a workflow
is the only way" is a complaint about someone's product and it is not how it reads from inside Clay:
workflows ARE the write path for Audiences, the same way a table is the read path. Say what the
thing is, not what it is instead of.

### Then: say what the data has to contain, ask where it lives, and stop until you have it

**One table or two — companies, people, or both — and "a table" does not mean "a CSV".** Say what
is required before asking for anything, so they can check their own data rather than find out four
steps later:

| What they have | What happens |
|---|---|
| **Both tables** | companies load first, then people against them. The normal case |
| **Companies only** | load them and say the people phase did not run |
| **People only** | every company has to be found in the audience or created from the contact, so the question at Step 4 is not optional — it decides whether the run does anything at all |


> **What this needs, per table:**
>
> - **A header row**, and one row per company or per person.
> - **Something that identifies each company to Clay: a website domain or a LinkedIn company URL.**
>   A row with neither cannot be loaded at all — Clay matches on those two and nothing else.
> - **Something that identifies each person: a work email, a LinkedIn profile URL, or a phone.**
>   Same rule; any one of the three is enough.
> - **A column on the people table naming which company they belong to** — an id, a domain, whatever
>   the companies table is keyed on — and **the same value has to appear on both sides.** This is the
>   one that quietly breaks: if the companies table says `ACME-01` and the people table says
>   `Acme Corp`, nothing links up.
> - Everything else is optional, and you choose which of it to bring across.

**Then ask where it lives, and name the shapes that work**, because most TAMs are not two loose CSVs:

> "Where is the data? Any of these work:
>
> - **Two CSV files** — one companies, one contacts.
> - **One Excel workbook** with a tab for each. Tell me the file and I'll list the tabs.
> - **A Google Sheet** — I can't read it directly, since that needs credentials I don't take and
>   won't ask for. In the sheet: File → Download → Comma-separated values, once per tab, then point
>   me at the two files. If you have a Google Drive connector set up, it can fetch them instead.
>
> One table alone is fine too — I'll load the companies and skip the people."

For a workbook, list the tabs and show which one you think is which rather than asking them to
recite tab names:

```
python3 scripts/loader_lib.py sheets --companies <book.xlsx>
```

Everything downstream takes `FILE` or `FILE#TAB`, so a workbook needs no conversion step:

```
--companies 'book.xlsx#Target Companies'   --contacts 'book.xlsx#People'
```

**A spreadsheet stores a date as a number**, and read raw it is a plausible five-digit integer that
survives a numeric check and lands in Clay as nonsense. The reader converts date-formatted cells to
ISO dates; say nothing about it unless something looks wrong, but know that a `founded` column
reading `40635` anywhere means this went wrong and the load should stop.

**If they named the files in their opening message, do not ask** — take the paths and say which two
you are using, in one line, so a wrong guess is correctable by reading.

**Never ask for a credential, a login, or a sharing change** to reach data. Not a Google account,
not a "publish to the web" link, not an API key. If it cannot be read from disk, say so and name
the export that makes it readable.

Ask for nothing else here. Every other decision has a step that needs it and a screen to show
alongside it, and front-loading them produces the interrogation this flow exists to avoid.

### Then: the platform

```
clay --version
clay whoami
```

`whoami` must return a workspace id and name. **Say the workspace name out loud, as a statement with
a handle on it** — *"loading into Northwind GTM; say so if that is the wrong one"* — because a load
into the wrong workspace is the one mistake here with no undo. Do not stop for an answer: the
workspace is named again at the Step 4 gate, which is where the stop belongs, and a reader looking
at the wrong name corrects it the moment they see it. If the host also has its own Clay connector,
check it reports the same workspace before anything is written.

**If the platform check fails, say which component is wrong, which version is required, and the one
command that fixes it — then stop.** Do not install, upgrade, clone or fetch anything to repair it.

Then confirm the audience surface answers at all:

```
clay audiences fields list --entity-type companies
```

Exit `3` means Audiences is not enabled on this workspace. That is a workspace-configuration answer
for the installer, not something to retry or work around — say so and stop.

## Step 1 — Read the tables and show the mapping you found `sample-review`

**Read the headers, infer a type per column, and show it. Never ask anyone to recite their own
column names.**

```
python3 scripts/loader_lib.py inspect --companies <path> --contacts <path>
```

That prints, per file: every column, the type it infers, two real values, how many rows are blank,
and which columns it proposes as the row key and the company-reference column. Type inference and
what each Clay type will and will not accept are in `references/column-mapping.md`.

Show the table. Then **one message, covering the whole mapping at once**: which columns to load, and
any corrections — to a type, to the proposed row key, or to the column that points a contact at its
company. All of it is on screen together, so all of it gets answered together; coming back for the
keys in a later step is two messages for one answer.

Columns nobody confirms are not created and not loaded — a TAM CSV usually carries far more than
belongs in Clay, and the default is to leave a column out rather than to bring it in.

**One of those corrections matters more than the rest and must not be waved through: the column on
the contacts file that says which company each contact belongs to.** It is joined to the company
row key by string equality and nothing else, so if the two name different things, every contact
loads with no company attached and every row still reports success. Show the proposal with two real
values from each side, so a mismatch is visible rather than assumed:

```
company row key     company_id   e.g. NW-001, CT-002
contact references  company_id   e.g. NW-001, CT-002     <- these must be the SAME key
```

### Before settling the mapping, lay it beside what the workspace already has

```
python3 scripts/build_loader.py match --companies <file[#tab]> --contacts <file[#tab]>
```

That prints two lists and asserts almost nothing: every field the workspace already holds, with its
id and the type it stores, and every column in the file, with what its values read as and two real
examples. **The matching is yours to do** — you can see a column called `staff_count` with values
`512` and `88`, and a field called `Employee count` that stores a number, and draw the obvious
conclusion. A lookup table cannot; it was tried, and it could not see `# of employees`, a header in
another language, or anything its author had not thought of, while printing "no field yet" in a way
that read as an answer rather than as nobody having looked.

The only matches the script asserts are **same-label** ones, where case and punctuation are the
only difference. Those are facts. Everything else is a judgment, and judgment is what you are for.

**Why it matters here rather than at Step 5.** A column that quietly mints its own field beside one
that already means the same thing splits every later filter — half the rows under one name, half
under the other, and neither total is right. The workspace also has a per-data-type field budget,
so the duplicate spends it twice.

For each column, decide one of three things, and **say why for every match that is not a
same-label one**:

| | Put in the mapping |
|---|---|
| it belongs in a field that already exists | that `field_id` |
| it is genuinely new | a `field_name` and a type |
| it does not belong in Clay at all | nothing — leave the column out |

**A `TYPE CONFLICT` line is not a match.** It means a field of that name exists and stores a
*different* type than the column reads as:

```
  employee_count  text  512 | 1,001-5,000 | 88   employee_count -- TYPE CONFLICT, stores number
```

Reuse that and every `1,001-5,000` writes, reports success, and matches no filter — this skill's
headline failure arriving through the back door. Retype the column or give it a field of its own.
**The build refuses that reuse**, so it cannot be waved through by accident, but it is far cheaper
to settle here.

**Two guards on your own judgment.** Do not match on words that overlap when the meaning does not —
a `revenue` column is not `net_new_arr_potential`, and a TAM's `location` is not necessarily the
headquarters field. And **when you are unsure, propose a new field**: a wrong reuse writes real
values into the wrong place and is tedious to unpick, while an extra field is a line in a list.

**Two more things to say while they look at it**, because both bite later and neither is visible in
a header row:

- **There is no list type.** A column holding several values per row becomes one text field. It can
  be matched with `contains`; it cannot be counted or split.
- **A workspace has a per-data-type field budget**, so a mapping with sixty columns may not fit. If
  `fields create` returns a validation error at Step 5, that is the budget — report it, name the
  columns that did not get a field, and let them cut. Never silently drop one.

## Step 2 — Say which key is yours and which one is Clay's

**Nothing is asked here.** The row key and the contacts column that points at it were shown in the
Step 1 table and corrected there; asking again is two messages for one answer.

What this step owes the installer is a disclosure. **If the file had no stable key and one was
minted** — a deterministic slug, from the domain where there is one and from a normalised company
name where there is not — say so, say which columns it came from, and say that re-running with the
same file produces the same keys. Minting is a legitimate answer; minting silently is not, and the
cost is real: two different companies with the same name collapse into one row.

Then state the two keys, as the table above states them. One short paragraph, no question attached —
the installer is not being asked to choose Clay's match key, because they cannot.

## Step 3 — Count what cannot load, before anything is written

Everything in this step is free and reads nothing but the files.

```
python3 scripts/loader_lib.py check --companies <path> --contacts <path> --map <mapping.json>
```

It produces the coverage report shown under `## Representative output`, and it is the evidence the
gate is built on. Four counts, and each has a different remedy:

| Count | What it means | What the installer can do |
|---|---|---|
| **rows with no Clay match key** | cannot be loaded, at all | supply a domain, LinkedIn URL, email or phone — or accept the loss with the number in front of them |
| **values Clay will not accept as that key** | present, and refused exactly like a blank | fix the value. A match key is checked for being *that kind of thing*, not merely non-empty — `linkedin_url` must be a `linkedin.com` URL, an email must parse, a phone must have digits. The loader falls through to the next key, so this only loses a row that had no other |
| **rows sharing a Clay match key** | will collapse into one record | split them, or accept the merge knowing which rows merge |
| **contacts whose company key is not in the companies file** | will load without a company link | fix the reference, or accept unlinked contacts |
| **values a field's type will not parse** | will write, report success, and be invisible to filters | change the column's type to text, or fix the values |

**The fourth is the one to lead with**, because it is the only one whose damage is silent. The
report names the column, the count and two offending values. A column where most values fail is
usually a type inference that should have been `text`.

## Step 4 — One gate: the rows, the fields, the writes, the ask `write-approval`

Everything free has now run. One message, then stop and wait:

- **the workspace**, by name, because this is the last point before anything in it changes;
- how many companies and how many contacts will be loaded, and how many will not, by reason;
- **how many contacts will get a company attached, and how many will not** — the single number
  most likely to be quietly wrong, so it is said out loud before anything is written;
- **the question about companies the contacts reference but the companies table does not have**,
  which has to be asked here because it decides whether records get written that nobody listed:

  > "N of your contacts work at companies that aren't in your companies list. M of those companies
  > are already in your Clay audience, so I'll just attach the contacts to them. The other K aren't
  > in Clay at all. Do you want me to create them?
  >
  > If yes: they'll be created from the contact's company domain or LinkedIn URL, and they'll be
  > **bare records** — a domain and a name, nothing else. None of the attributes your companies
  > table would have given them: no tier, no fit score, no research. They'll show up in your
  > audience looking thinner than everything else, and I'll hand you the list so you can load them
  > properly when you have data for them.
  >
  > If no: those contacts load without a company attached, and I'll tell you how many."

  **Say the bare-record part every time, even when they sound keen.** A company record with a
  domain and nothing else is indistinguishable from a real one in a list view, and someone
  filtering on tier next week will quietly miss every one of them.
- the field definitions about to be **created** in their workspace, by name and type;
- that this **writes records into their Audiences** — a mutation, not a read — naming both objects;
- **that it will build two new workflows in their Clay workspace, in plain words.** Not "a graph",
  not "the node matrix" — say what a person would see if they opened Clay:

  > "This creates two workflows in your Clay workspace — *<name> companies loader* and *<name>
  > contacts loader*. Workflows are how Clay writes into Audiences, so these are the loader itself:
  > each takes one row at a time and creates or updates the matching record.
  >
  > They stay as drafts while the load runs, which is all this needs — nothing fires unless the
  > load fires it. Afterwards they are yours to keep: a second load reuses them and skips the build
  > entirely. Publish them and a Clay table or a webhook can drive them too. Delete them and the
  > records stay."
- what it costs. **Say the honest thing: the Audiences actions carry no credit price in the
  catalogue at all** — no `creditCost`, no `paymentType` — and on one measured run neither meter
  moved: same credit balance and same action-execution balance before and after fourteen rows.
  That is one observation on one workspace, not a promise about theirs, so **take both meters
  before the load and again after and report the real movement** rather than repeating the
  number above. An estimate nobody reconciles is how an overrun goes unnoticed:

```
clay credits balance        # `balance` is credits; `actionExecutionBalance` is the meter this moves
```

**Never fold away this ask, and never split it into three.** Field creation, workflow creation and
the load are one decision and they happen in one order.

## Step 5 — Create the fields, then build the two loaders

**Say what is about to appear in their workspace, in plain words, before it appears.** The
installer is about to get two new things in Clay that they did not ask for by name, and finding
them later without being told is worse than being told now:

> "I'm building two workflows in your Clay workspace, one for companies and one for contacts.
> Workflows are how Clay writes into Audiences, so these two are the loader: each takes one row at
> a time and creates or updates the matching record. They stay as drafts while the load runs, and
> afterwards they are yours — keep them and a second load skips the build, publish them and a table
> or a webhook can drive them too, or delete them and the records stay."

**Why a workflow and not agent-side calls, for the record.** `clay audiences` is the read surface —
segments, fields, records — and `upsert-audiences-record` is the write surface, which runs in a
workflow node. So the graph is the loader rather than packaging around one. It also has to outlive
the run: tens of thousands of rows outlast any one conversation, and the driver has to be able to
die and restart against a graph that is still there.

**Confirm the node syntax on the installed CLI before writing anything** — the shape is dynamic per
node type and a hardcoded command form ages the same way a hardcoded provider does:

```
clay workflows nodes --help
clay workflows triggers --help
```

Then, before writing anything into the workspace, run the offline checks — no Clay, no network, no
credentials, a few seconds — because the failures they cover are the ones that build a perfect graph
and die on every row:

```
python3 scripts/test_loader.py
```

A non-zero exit means the payloads and routes this build would produce are wrong, and the right
response is to stop rather than to build and find out on row four thousand. Then:

```
python3 scripts/build_loader.py fields --map <mapping.json>
python3 scripts/build_loader.py build  --map <mapping.json> --out build-state.json
```

`fields` creates only what is missing, matching on name against the live catalogue, and **reads back
the id Clay returns rather than assuming the name it was given** — a name already in use is
silently suffixed, and a build wired to the name it asked for is wired to nothing.

**It refuses to reuse a field whose stored type disagrees with the column's**, and reports it
rather than creating one anyway. That is the last guard against the back-door version of the
headline failure: a `text` column pointed at a `number` field writes every value, reports success,
and matches no filter. The fix is at Step 1 — retype the column, or give it a field of its own.

`build` resolves the upsert action from the live catalogue with `clay workflows actions list` and
**stops if it is absent** — never a remembered package id, because a guessed one builds a graph
against the wrong action in any workspace that does not match the one it was written in, and it
validates perfectly either way. Then, per entity, in dependency order:

| | Node | `clay workflows` command | Edge in from |
|---|---|---|---|
| 1 | **Webhook trigger** — its `inputSchema` declares `row_key`, `match_key`, every Clay match key, every loaded field by its **field id**, and on contacts `company_record_id` | `triggers create`, then `triggers get` for its `workflowNodeId` | — |
| 2 | **Route by match key** — a rules conditional switching on `match_key`, and on contacts also on whether `company_record_id` is empty | `nodes create` | the trigger node |
| 3 | **One writer per route** — a tool node carrying the upsert. 2 for companies, 6 for contacts | `nodes create` | the router, by `ruleId` |
| 4 | **Reject — no match key** — a code node that raises | `nodes create` | the router, `isDefaultRoute: true` |

Four traps, each of which passes validation and fails at run time. The exact input mapping for
every writer is in `references/graph-shape.md`:

- **A trigger takes one outgoing edge, never two.** The router is the only thing that hangs off it,
  and deleting a node can sever that edge and orphan its siblings without saying so.
- **A conditional needs a default route as an EDGE.** Setting `defaultTargetNodeId` instead saves,
  validates, and fails the first run that matches nothing.
- **The `selected*` arrays must be `static`.** As references they resolve to nothing and the write
  reports success having written only the lookup field.
- **A trigger schema must be complete** or the fields it does not name are stripped at intake, which
  surfaces as a resolution failure two nodes later.

`build-state.json` is what makes a second run an extension rather than a rebuild.

**Two guards, because the file alone was not one.** `build` refuses while that file is present, and
it also asks the workspace whether loaders with this name prefix are already there — a filename
protects nothing against the normal way a second attempt happens, which is a fresh folder.

**If the workflows exist but the state file is gone, adopt them rather than rebuilding:**

```
python3 scripts/build_loader.py adopt --name-prefix "<the prefix they used>" --out build-state.json
```

That reads the loaders out of the workspace and reconstructs the state file. It checks the **shape**
— one trigger, one router, one writer per match key, a default that rejects — rather than the node
names, because names are not load-bearing at run time and anyone can rename a node on the canvas.
It prints the writers it found so they can be eyeballed, and refuses when a graph is missing one
rather than loading rows through a loader with nowhere to put them.

This is what makes Step 9's advice honest. Telling someone to keep the workflows for next quarter is
only true if losing a local JSON file does not strand them.

Then validate, and read every node back:

```
clay workflows graph validate <workflowId>
clay workflows graph get <workflowId> --mode full
```

**Read every node back after writing it.** A schema write rebuilds the binding map from exactly what
the call contained and reports success while dropping what was left out.

## Step 6 — Load the companies, ten first

```
python3 scripts/load_drive.py --entity companies --state build-state.json \
        --csv <path> --map <mapping.json> --ledger ledger/companies.jsonl --limit 10
```

Ten rows run. Then, before the rest: read those ten back out of Clay and show, per field, how many
of the ten have it populated against how many carried a value in the CSV. **Stop and ask only if
those numbers disagree** — that is the silent failure surfacing, and it is the one thing the
installer could not have anticipated. If they agree, say so in a line and keep going:

```
python3 scripts/load_drive.py --entity companies --state build-state.json \
        --csv <path> --map <mapping.json> --ledger ledger/companies.jsonl
```

Every row's verdict is appended to the ledger **the moment it settles**, carrying the Clay record id
the upsert returned. Nothing is held in memory. Re-running recomputes the remaining work from the
ledger, so a load that dies resumes and a completed row is never fired twice.
`references/ledger-and-resume.md` carries the record shape, the settled-versus-retryable rule, the
shard model and the resume breadcrumb the driver writes.

**Do not "fix" a transient failure before retrying it.** Only `completed` and the `rejected_*`
verdicts are settled; a `failed` or a `timeout` stays in the work set and the next pass picks it up.
A burst of failures that clears on its own is the normal shape of this, and diagnosing one before
re-running it is how a day gets spent.

**And a failure that repeats is still not proof of a rule.** Watched on a real run: one contact
failed twice, two minutes apart, with `Record was not upserted`; the run noticed she was the only
contact without an email, concluded Clay requires one to create a person, and reported that as a
finding. The identical payload succeeded later untouched, and creating a person by LinkedIn URL
with no email works fine. **Two samples and a plausible story is how a load ends up inventing email
addresses to satisfy a rule that does not exist.** Before claiming the platform behaves a certain
way, bisect it — one variable at a time, each with a fresh match value so every attempt is a real
create — and if you cannot, report the failure and say you could not explain it.
`references/graph-shape.md` carries this signature and what it is not.

## Step 6b — Resolve the companies the contacts reference but the table does not have

**Only when there are contacts, and only after the companies have settled.** A contact's company
can be in three places, and this step is where the second and third are settled — before any
contact is written, so the counts at Step 4 were true.

```
python3 scripts/load_drive.py prepass --state build-state.json --map <mapping.json> \
        --contacts-csv <file[#tab]> --ledger ledger/companies.jsonl --dry-run [--create]
```

Run it `--dry-run` first: it resolves and reports, and writes nothing.

| Where the company is | What happens |
|---|---|
| In the companies table | already in the ledger from Step 6. Nothing to do |
| **Already in the audience** | found by its match key and used. **Always on** — it is a free read, nothing about the company is modified, and the only write is the association on the contact |
| **In neither** | created **only if they said yes at Step 4**, from the contact's own match key |
| Nothing to identify it by | the contact loads unlinked, and the count is reported |

**The key is not necessarily a domain.** Clay matches a company on `domain` *or* `linkedin_url`, so
this resolves whichever the contact can supply, in that order: a company-domain column, a
company-LinkedIn column, then the work email's domain. **A free mailbox is never a company** — a
contact at a personal address yields nothing, because it says nothing about where they work, and one
webmail "company" with forty contacts hanging off it is worse than forty unlinked contacts, since it
looks like it worked.

**A company name is deliberately not a source.** Nothing can be created from one — `lookupFields`
takes only domain and LinkedIn URL — and matching on a name that is not unique attaches a contact
to the wrong company, which is the silent wrongness this whole skill refuses.

**Every lookup is per distinct company, never per contact.** `clay audiences` shares a
60-calls-per-minute budget across the workspace; a thousand contacts at one company cost one query.

Everything it resolves is appended to the **company ledger**, under the key the contacts load looks
up, and stamped `created_from`: `audience` when it was already there, `contact` when this step made
it. So the contacts phase needs no new logic, a re-run never repeats the work, and the delivery
report can say exactly which companies are thin and why.

## Step 7 — Load the contacts against the company ids

**This is the step the whole skill exists for, so here is exactly what happens, in order.** It is
spelled out because every part of it is invisible when it goes wrong: a misconfigured link loads
every contact successfully, with no company attached, and reports success end to end.

1. **Read the company ledger.** Every company line carries the Clay record id its upsert returned,
   in `entity_id`. Fold the file into a map of **company row key → Clay record id**, keeping only
   `completed` lines. This is a local file read — nothing is looked up in Clay.
2. **For each contact, take the value in the company-reference column** — the contacts column
   confirmed at Step 1 as `company_ref_column` — and look it up in that map.
3. **That lookup returns a Clay company record id**, an integer like `900100200`. It is not a
   domain, not a name, and not the company's row key.
4. **Put that id in `associations|accountId`** on the contact's upsert. That single attribute is
   the entire company link. Nothing else on the record creates one — a `domain` field matching a
   company's domain establishes nothing.
5. **A contact whose lookup returned nothing goes to a writer with no association mapping at all.**
   Not one mapping a blank. A blank `associations|accountId` returns `ERROR_BAD_REQUEST` and writes
   no contact whatsoever.

```
company ledger        {"row_key": "NW-001", "status": "completed", "entity_id": 900100200}
                                  │
contacts CSV          company_id = "NW-001"  ─────┘
                                  │
contact upsert        "associations|accountId": 900100200
```

**The two keys either side of that lookup have to be the same key.** The company row key and the
contacts company-reference column are joined by string equality and nothing else — no normalising,
no fuzzy match. If the companies file is keyed on `company_id` and the contacts file references
companies by name, **nothing resolves and every contact loads unlinked.**

So the driver counts the resolution before it fires anything and prints it:

```
company ids folded from the ledger: 16 of 17 settled company rows
contacts in this pass that resolve to a company: 28 of 29, via 'company_id'
```

**If that second number is zero it stops**, shows both key spaces side by side, and refuses to
load — because loading a whole file unlinked is not a mistake worth making quietly. Continue only
with `--allow-all-unlinked`, and only for a TAM that genuinely has no company links.

There is no second file to build and no join step: a company that settled since the last pass is
picked up by the next one.

```
python3 scripts/load_drive.py --entity contacts --state build-state.json \
        --csv <path> --map <mapping.json> --ledger ledger/contacts.jsonl \
        --company-ledger ledger/companies.jsonl
```

Each contact is routed by which Clay match key it carries and whether its company resolved. A
contact whose company did not resolve goes to a writer **with no association mapping at all** — not
to one mapping a blank value, which writes nothing and reports a failure shaped like a transient
one. Its ledger line is stamped `associated: false` so the count is recoverable afterwards.

## Step 8 — Verify against the audience, not against the ledger

The ledger says what was sent. This step asks Clay what it holds.

```
python3 scripts/load_drive.py verify --state build-state.json --map <mapping.json> \
        --csv <companies file[#tab]>          --ledger ledger/companies.jsonl \
        --contacts-csv <contacts file[#tab]>  --contacts-ledger ledger/contacts.jsonl
```

Per field, what should have landed against what Clay says this load's own records hold.

**Each ledger needs its file too** — the command takes `--csv` with `--ledger` and `--contacts-csv`
with `--contacts-ledger`, because the expected count is derived from the file. Passing a ledger
alone verifies nothing, and the step refuses rather than printing a pass.

**Scoped to the record ids in the ledger, never to the workspace.** This is the correction that
matters most in the whole step, and it shipped wrong: a workspace-wide
`count … is_not_null` returned 17 where the load had written 5, the pass test was `got >= want`,
and every field passed — including fields the load had not written at all. On an empty workspace it
looks right, which is how it survived. It now asks Clay for the **ids** of records the filter
matches and intersects them with the ids the ledger recorded, so the number beside each field is
about this load and nothing else. Where a workspace holds too many matching records to page
through, the field is reported `NOT CHECKED` rather than passed. **A row of that table where
the two numbers differ is a column that did not land.** Report it as a discrepancy with the field
and both numbers; never reconcile it by preferring the ledger.

**A boolean field cannot be coverage-checked, and the step says so rather than raising a false
alarm.** On a boolean, `is_not_null` returns exactly what `= true` returns, and `= false` returns
everything else — including every record the field was never set on. No query separates "explicitly
false" from "never set", so booleans are reported as unmeasurable with their true count, and are
never counted short.

**Traverse on a field every company is guaranteed to carry.** `company.domain is_not_null` was tried
and under-reported: it misses every company matched on `linkedin_url`, which has no domain, so
contacts that are genuinely linked look unlinked. `org_name` is the one to use — **and the pre-pass
is what makes that true**, because it now names every company it creates, falling back to the match
key when the contacts file offered nothing better. Before it did, a contact attached to a
contact-created company read as unlinked, and the unscoped count above hid it.

## Step 9 — Deliver

Hand over three things and say what each is for: the coverage report from Step 3, the verification
table from Step 8, and the ledger files. Say plainly what was loaded, what was refused and why, how
many contacts are unlinked, and the exact command that resumes if anything is still outstanding.

**If any companies were created from a contact, hand back that list too** — they carry a match key
and a name and none of the attributes the companies table would have given them, and they are
indistinguishable from the rest in a list view. The ledger has them under `created_from: contact`.

**Then the workflows, as a real choice rather than cleanup.** They are a working loader for this
audience, and what happens to them changes what the installer can do next:

| | |
|---|---|
| **Keep them as drafts** | the default. A second load points the driver at a new file and skips the build entirely — same fields, same graphs, nothing recreated. Keep `build-state.json` with them, and if it is ever lost, `build_loader.py adopt` rebuilds it from the workspace |
| **Publish them** | their webhook goes live, so a Clay table, another system or a scheduled job can drive the same loader without this script. Say that plainly: publishing turns the trigger on |
| **Delete them** | `clay workflows delete <id>`. The records and fields stay exactly as they are |

Say which you recommend and why, in one line, and let them pick. **Do not present deleting as
tidying up** — it throws away the build, and the next load pays for it again.

## Representative output

### Pre-load coverage report

| | Companies | Contacts |
|---|---|---|
| Rows in file | 4,180 | 26,402 |
| Loadable | 4,061 | 24,918 |
| No Clay match key | 119 | 1,484 |
| Duplicate row key | 0 | 12 |
| Sharing a match key with another row | 46 rows -> 21 records | 8 rows -> 4 records |
| Values Clay will not accept as that key | `linkedin_url` 7 | `email` 31 |
| **Company link** | — | **ok — 24,306 of 24,918 resolve via `company_id`** |
| Company reference not in the companies file | — | 612, of which 588 carry a domain to go on |
| Values their field's type will not parse | `employee_count` 338 of 4,180 (`1,001-5,000`, `~250`) | `tenure_years` 0 |

**The company-link row is the one to read twice.** `NOT CONFIGURED`, `COLUMN NOT IN FILE` or
`NOTHING RESOLVES` there means every contact would load with no company attached while every row
reported success, and the load refuses to start.

### Resolving the companies contacts reference but the table does not have

```
contacts referencing a company not in the companies table: 612, across 74 distinct companies
contacts with nothing to identify a company by: 24
  domain         northwind.example                             900100200
  domain         contoso.example                               would create
  linkedin_url   linkedin.com/company/fabrikam                 would create

already in the audience: 41   would be created: 31   cannot be identified at all: 2
```

### Post-load verification

`Expected` is the number of distinct Clay records that should carry the field: rows that settled,
minus values dropped at Step 3, and counting rows that collapsed onto one record once.

| Field | Entity | Type | Expected | Populated in Clay | |
|---|---|---|---|---|---|
| `org_name` | companies | text | 4,040 | 4,040 | ok |
| `domain` | companies | url | 4,040 | 4,040 | ok |
| `employee_count` | companies | text | 4,040 | 4,040 | ok |
| `founded` | companies | date | 2,904 | 2,821 | **83 short — the loader's type check and Clay's disagreed** |
| `expansion_signal` | companies | boolean | 4,040 | 2,110 true | not checkable — false and never-set are the same query |
| `title` | contacts | text | 24,918 | 24,918 | ok |
| Linked to a company | contacts | — | 24,882 | 24,882 | ok |

A short row is the whole reason this table exists. It does not mean rows went missing — the ledger
already accounted for those. It means a value this loader judged parseable was not, so it wrote,
reported success, and cannot be filtered on. Name the field and both numbers; the remedy is the
same as at Step 3, which is to move the column to `text` and load it again.

### Refused, by reason

| | Companies | Contacts |
|---|---|---|
| `rejected_no_match_key` | 119 | 1,484 |
| `rejected_duplicate_row_key` | 0 | 12 |
| Loaded without a company attached | — | 36 (`no_company_reference_and_no_domain` 24, `company_missing_not_created` 12) |
| Created from a contact, carrying only a match key and a name | 31 | — |

### Ledger line

```
{"row_key":"northwind","status":"completed","run_id":"<run id>","entity_id":900100200,
 "match_key":"domain","match_value":"northwind.example","associated":true,
 "link_source":"company_table","unlinked_reason":null,"dropped_fields":["employee_count"],
 "fields_written":4,"at":"2026-05-04T11:02:19Z"}
```

`link_source` is where the contact's company came from — `company_table`, `already_in_audience` or
`created_from_contact` — and on a company line the pre-pass writes `created_from` instead, either
`audience` or `contact`. Between them, "why does this contact have no company" and "which of these
companies are thin" are both answerable from the ledger alone.

## What this skill does not claim

- The silent-write behaviour was measured on one workspace on one day, across a number field and a
  date field. It is reported as what was observed, not as documented platform behaviour, and Clay
  may change it.
- Nothing here has been run at TAM scale by this skill. The shard count and the pace are carried
  over from a load of about nine thousand records driven by different code against a different
  workflow, and no equivalent measurement exists for this build.
- The Audiences actions carry no credit price in the catalogue, and one fourteen-row run moved
  neither meter. That is not a claim that a large load is free: it is one small observation on one
  workspace and one plan, and it is why the skill reads both meters itself rather than quoting
  that number. Balance movement is also not a clean per-call measurement — anything else running
  in the same workspace moves it too.
- Clay's set of match keys is taken from the action's own behaviour and from Clay's documentation,
  and both agreed. No one has confirmed the set will not change.
- The shape a match value has to take was established by trying values and reading the refusals, not
  from any published rule. The loader's local screen is an approximation of a check it cannot see,
  so it may refuse a value Clay would have taken.
- The query index lags the write. A verification run fired immediately after a load under-reported
  one field and read correctly a minute later, so a single discrepancy on a fresh load is worth
  re-reading before acting on.
- The verification counts a field as landed if one of this load's records carries it. Where a
  record already existed and already had that field, it is counted even if this load's value was
  dropped — so the check is a floor on what landed, not proof that every value did.
- Whether two rows genuinely are the same company is not something this skill decides. It counts the
  collisions its match key produces and shows them; the judgement is the installer's.
- The per-data-type field budget is named in the CLI's own help and its size is not stated anywhere
  this skill can read, so it is handled as an error to report rather than a limit to plan against.

## What good looks like

Every row in every table you were given reaches one of six verdicts and none is `unknown`: loaded;
loaded without a company attached; refused for carrying no Clay match key; refused as a second row
with a row key already seen; held because its company never loaded; or still outstanding with a
named reason. The counts add up to the row count of the table — a run where they do not has lost
rows somewhere and the load is not finished.

The verification table at Step 8 is the actual test, and a good run is one where every row of it
matches. **A run that loads every record and comes back with two columns short is a failed run that
looks like a successful one** — which is the whole reason that table exists and the reason it is
built from Clay's counts rather than the loader's.

A second run over the same files writes nothing new, reports every row already settled, and the
record counts in Clay do not move. If a re-run creates records, the row key and the Clay match key
have come apart and the load should stop until that is understood.

A thin run states its thinness: if most of a file carries no Clay match key, the honest outcome is
to say so with the number and stop, not to load the remainder quietly and report a success.

## Rules

- **NEVER** write a record into a field the installer did not confirm at Step 1.
- **NEVER** send a blank value as a lookup field or as `associations|accountId`. The first fails
  before the node runs and the second writes nothing at all — and both surface as `failed`, which
  reads exactly like a transient error and will be retried forever.
- **NEVER** fire a row whose match value Clay will refuse. A key is checked for being that KIND of
  thing, not for being non-empty: a non-`linkedin.com` LinkedIn URL, a malformed email and a phone
  with no digits all fail with wording that reads as though the field were blank. Screen locally
  and fall through to the next key in the order.
- **NEVER** treat `failed` or `timeout` as settled, and never edit anything before retrying one.
- **NEVER** hold a batch of verdicts in memory. One row settles, one line is appended.
- **NEVER** merge two existing records, archive one, or delete or empty a field. Attaching a
  contact to a company already in the audience is not merging — it is an exact lookup on a match
  key — but deciding two records are "probably the same" is, and this skill does not do it. Where
  the load would collapse two of your rows onto one record, say so before writing.
- **NEVER** infer that a contact belongs to a company because it carries the company's domain. The
  association is a record id and nothing else establishes it, and that id goes in exactly one
  place: `associations|accountId` on the contact's upsert.
- **NEVER** load a contacts file when nothing in it resolves to a company. That is a misconfigured
  join, not a TAM without companies, and it is indistinguishable from success afterwards. Stop,
  show both key spaces, and let the installer say which is wrong.
- **NEVER** report a load as complete on the ledger alone. The ledger says what was sent; only the
  audience says what it holds. And **never report a verification that compared nothing, or that
  compared the wrong population** — both have shipped here. A check over zero fields once printed
  "every field matches"; a workspace-wide count passed every field on a workspace that already held
  records. Scope to the ids the ledger recorded, and treat a number you cannot scope as unchecked
  rather than as a pass.
- **NEVER** turn a repeated failure into a claim about how the platform works without bisecting it
  first. Report it unexplained instead; an invented rule sends the next person to fabricate data.
- **NEVER** pin the upsert action's package id. Resolve it from the live catalogue and stop if it is
  absent rather than falling back.
- **NEVER** publish a workflow during the load, and never as housekeeping. The driver runs the
  draft, so publishing changes nothing about the load — it turns the webhook on. Offer it at Step 9
  as a choice, say what it switches on, and publish only on a yes.
- **NEVER** ask for a credential, a login, or a sharing change to reach the data. If it cannot be
  read from disk, name the export that makes it readable and stop.
- **NEVER** pass a spreadsheet's raw date serial through as a value. A date cell read without its
  format is a five-digit integer that passes a numeric check and means nothing in Clay.
- **NEVER** create a field for a column the workspace already has a field for, without showing
  the match first. Read both lists and match them yourself; do not wait for a script to assert a
  similarity it cannot see. And **never reuse a field whose stored type disagrees with the
  column** — that writes every value successfully into something no filter can see.
- **ALWAYS** read back the id a field creation returns rather than the name it was asked for.
- **ALWAYS** state which values came from a default and that the default is borrowed.

## Worked example

Someone opens with *"load my TAM into Clay"* and nothing else. Step 0 says what the next few minutes
look like in four short paragraphs — read the files, show the columns, count what cannot load, one
approval, then the load and a check at the end — names the two workflows it will build and why, and
then asks for the files, because none were given. They point at two exports from a TAM built in a
model conversation: 4,180 companies and 26,402 contacts.

They are one Excel workbook with a tab each, so Step 1 lists the tabs, proposes which is which,
reads both, and proposes eleven of the forty-three company columns — `company_id` as the row key,
`company_key` as the column pointing a contact at its company, and `headcount` as **text**, because
one value two thousand rows down reads `1,001-5,000` and one bad value demotes the whole column.

Then it lays those columns beside the fields the workspace already holds. `company_name` is the
same label as `Company name`, so that one is asserted. The rest are matched by reading them:
`website` carries `https://` values and belongs in `Domain`, `hq_city` belongs in `City`,
`job_title` belongs in `Title`. Each is shown with its reasoning and none is applied until the
installer says so, so eleven columns become five reused fields and six new ones rather than eleven
new fields beside the ones that already meant the same thing.

The installer overrides it to `number`, which is the reasonable thing to think: a headcount is a
number. Step 3 is what makes that survivable. It reports 338 values that a number field will not
parse, shows two of them, and the installer puts the column back to text — so the 338 rows that
would have written successfully into a field no filter could ever see stay visible instead.

Step 3 also reports 119 companies with neither a domain nor a LinkedIn URL, which cannot be loaded
at all, and 46 rows sharing a domain with another row, which will become 21 records. The installer
accepts both with the numbers in front of them.

The gate names the workspace, 4,061 companies, 24,918 contacts, the eight new company fields and
two new contact fields to be created — the rest map onto fields the workspace already has — and
that this writes records into Audiences. Yes. The fields are created, both workflows built and left
as drafts, and ten companies load. Their read-back matches on every field, so the rest follow
without a second stop.

Companies settle into the ledger with their record ids. Before the contacts run, the pre-pass takes
the 612 contacts whose company is not in the companies table and resolves the 74 distinct companies
behind them: 41 are already in the audience and get used, 31 are nowhere and get created because the
installer said yes at the gate, and 2 cannot be identified at all. The 31 created carry a domain and
a name and nothing else, and the delivery report says so and hands back the list.

The contact phase then folds that ledger into a map and links 24,882 of 24,918. Step 8 asks Clay for
the populated count per field, one row comes back 83 short and is reported as a discrepancy rather
than reconciled away, the boolean column is reported as unmeasurable rather than short, and the run
is finished — 119 companies and 1,484 contacts refused, each with its reason and its count.
````

- Previous: [spec-improve](https://syn4pse.dev/terminal/codacy-spec-improve.md)
- Next: [track-champion-job-changes](https://syn4pse.dev/terminal/clay-track-champion-job-changes.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
