resolve-own-company

name	resolve-own-company
requires	["define-workspace"]
description	Resolve which company in a Well workspace is the user's own legal entity — the `own_company` pointer that decides which side of an invoice is a payable and which is a receivable — fold in its duplicate records, and hand the confirmed identity off as a typed result. Use when a Well skill needs to tell its own invoices from a counterparty's, when the user asks "which company is mine", or when `workspaces.own_company` is null, missing from the schema, or ambiguous. Do not use to pick the workspace, to look up an arbitrary company by name, to merge company records in Well, or to compute any financial figure.

Resolve Own Company with Well

Purpose

Answer "which of these companies is us?" for one Well workspace, and return an identity a calling skill can compare invoices against. Read workspaces.own_company, treat three distinct states as unresolved rather than only the null one, ask the user when it cannot be read, and fold in the duplicate companies rows that the same legal entity accumulates. Return a typed hand-off carrying the confirmed id, its alias set, and how it was resolved.

This exists because a wrong answer here is silent. Every skill that splits invoices into payables and receivables does it by comparing issuer_company_id and receiver_company_id against this pointer, so guessing it does not degrade an answer — it inverts one, and the output looks entirely plausible either way. Six Well skills carried their own copy of this logic before it lived here, in four different lengths.

When to use this skill

Use this skill when:

• A calling skill needs to separate its own invoices from a counterparty's — payables vs. receivables, revenue vs. spend, customer vs. vendor.
• workspaces.own_company is null, absent from the schema, or resolves to more than one plausible company.
• The user asks which company in Well is theirs, or wants to correct the one being used.
• A skill is about to group invoices by counterparty and duplicate company records would split one identity across rows.

When not to use this skill

Do not use this skill when:

• The workspace is not resolved yet — run define-workspace first and pass its workspace_id in.
• The user wants an arbitrary company looked up by name, not their own entity — query companies directly, or use company-profile for a full view.
• The user wants duplicate company records actually merged in Well — this skill proposes aliases for one run; it never writes. Point them at the Well app.
• The user wants a figure — the data skills call this internally.
• The user wants to set own_company permanently — no MCP tool writes it; only the picker in the Well app does.

Inputs

The calling skill provides:

• workspace_id — required. Comes from define-workspace. If absent, run that skill first — or, when it isn't installed, use step 1's documented inline fallback; never resolve it any other way.
• purpose — one line on why it is needed (e.g. "to tell your bills from your invoices"), used in the ask. Optional.
• consequence — one clause naming what a wrong pick breaks in the caller's answer (e.g. "swaps payables for receivables", "ranks the wrong side of the invoice", "inverts customer and vendor"). Used to tell the user why the question matters. Optional but strongly preferred.
• mode — strict (default) when the caller's answer is wrong without a confirmed identity, or suggest when the caller only needs a sensible default the user will confirm anyway (draft-invoice offering an issuer). In suggest mode a single unambiguous read is offered as a default and no alias folding runs.
• fold_aliases — whether to fold the own company's duplicate records. Default true; false in suggest mode.
• fold_counterparties — also propose alias sets among the other companies, for callers that group invoices by counterparty. Default false.
• on_decline — what the caller can still do if the user will not confirm (e.g. "report gross unpaid invoices, labeled as unsplit"). Quoted back to the user so declining is an informed choice.

Tooling

Runs over Well's MCP server (https://api.wellapp.ai/v1/mcp, streamable HTTP). If the well_* tools are not in your toolset, the host has not added the Well MCP server yet — tell the user to add it at that URL, then retry. Required once it is added:

• well_get_schema — call on workspaces before reading own_company, and on companies before the alias query. The schema read is not a formality here: whether the field exists at all is one of the three unresolved states, and you cannot distinguish "null" from "absent" without it.
• well_query_records — read workspaces (for own_company) and companies (for the alias candidates).

Never call well_update_company or well_delete_company from this skill. Folding an alias is a within-run decision about how to compare names; merging records is a destructive write on the user's data, and the two are not the same operation.

Composed skills. One atomic Well skill owns the step before this one — invoke it, don't reimplement it:

• define-workspace — pins exactly one workspace and supplies the workspace_id every call here carries.

It ships with the well-skills plugin. This skill is also installable on its own, so step 1 carries the inline fallback to use when it's absent.

Workflow

1. Require the workspace. Take workspace_id from the caller, and pass it explicitly on every well_* call below. If the caller did not pass one, run define-workspace and take its hand-off; never pick a workspace here. If it returns resolution: unresolved, stop — there is no workspace in which to have an own company.

   • If define-workspace isn't installed, resolve inline: with no well_* tool, tell the user a Well connection is mandatory at https://api.wellapp.ai/v1/mcp and stop; on an auth error, run the OAuth/DCR flow and retry in the same turn; then take the single workspace, or ask which to use.

2. Read the schema, then the field. well_get_schema({ root: "workspaces" }), then read workspaces.own_company for the pinned workspace. Treat all three of these as unresolved, not just the null case:

   • the relation is null;
   • the field is absent from the schema entirely — some workspaces don't expose it, and an absent field is not permission to work around it;
   • it resolves to more than one plausible company.

3. Never infer it. Do not derive the own company from the workspace's name, title, logo, slug, or email domain. A workspace named after its owner is a coincidence, not a record. This is the rule the whole skill exists to enforce: an inferred pick is indistinguishable from a correct one in the output, and consequence says what it breaks.

4. Resolved cleanly → take it. One unambiguous company from the schema field → resolution: schema_field, unless the caller passed mode: suggest, in which case → resolution: suggested, offered as an overridable default rather than a stated fact. Either way say which company in one line, do not ask for confirmation, and skip to step 7.

5. Unresolved → ask once. Query companies for the workspace and ask which one is theirs, with the list on screen so the user picks rather than recalls. Say why, using purpose and consequence ("I need to know which company is yours, or I'll swap your payables and receivables"). The answer holds for this run only → resolution: user_confirmed.

Output requirements

Return:

• One line naming the own company and how it was resolved (e.g. "Working as Acme SAS — read from the workspace's own-company setting." or "Using Acme SAS as your company for this run, from your answer.").

• When aliases were confirmed, one line naming them and noting the duplicate is worth fixing in Well.

• The hand-off block, exactly these keys, so a calling skill can read it:

  workspace_id: <uuid>
  own_company_id: <uuid or null>
  own_company_name: <name or null>
  identity_set: [<uuid>, …]
  aliases: [{ id: <uuid>, name: <name> }, …]
  counterparty_alias_sets: [[{ id: <uuid>, name: <name> }, …], …]
  resolution: schema_field | user_confirmed | suggested | unresolved
  persisted: <true|false>
  

  identity_set is what the caller compares invoice ids against — the own company plus every confirmed alias, and the only key a caller needs for the common case. persisted is true whenever the value came from the schema field — resolution: schema_field or resolution: suggested, since both read the same stored setting — and for , which holds for this run only. On , every key but is null or empty.

Do not return:

• A company inferred from the workspace's name, logo, slug, or domain.
• An alias folded without an explicit yes.
• A guess when the user declined to confirm.
• Any figure computed from invoice data.

How this reaches the user. A Well MCP tool that ships a widget attaches _meta.ui.resourceUri to its result, and the host decides whether to draw it. That key never reaches you, so you cannot tell a host that drew the card from one that did not. Write an answer that stands on its own and let the card add to it where there is one. State the company in text regardless — you cannot know whether anything drew them. What you must not add is a second rendering of what a card already shows.

Quality checks

Before finishing, verify:

• If well_* tools were absent, the user was pointed at https://api.wellapp.ai/v1/mcp instead of a tool error.
• workspace_id came from define-workspace (or the caller) — or, when that skill isn't installed, from step 1's documented inline fallback — and rode every well_* call.
• well_get_schema({ root: "workspaces" }) ran before reading own_company, so "absent from the schema" was distinguishable from "null".
• All three unresolved states were treated as unresolved — null, absent, and ambiguous.
• The own company was never derived from the workspace's name, title, logo, slug, or email domain.
• When the field could not be read, the user was asked once with the company list on screen, and told what a wrong pick would break.
• A user_confirmed answer was scoped to this run, persisted: false, and the Well app link was offered for setting it permanently.
• Alias candidates were found with both-direction containment on identically normalized names, punctuation folded to spaces — and were proposed, never merged silently.
• No well_update_company or well_delete_company call was made.
• On a decline, resolution: unresolved was returned with the caller's on_decline restated, and no guess was substituted.
• The hand-off block carries identity_set, resolution, and persisted.

Examples

Example request

bills-due calls with workspace_id for Acme SAS, purpose: "to tell your bills from your invoices", consequence: "swaps payables for receivables". The schema exposes own_company and it points at one company.

Expected behavior

Read the schema, read the field, take it without asking: "Working as Acme SAS — read from the workspace's own-company setting." Fold aliases, find none, hand off with resolution: schema_field, persisted: true, and identity_set holding the single id.

Example request

expense-breakdown calls with consequence: "swaps payables for receivables", on_decline: "report gross unpaid invoices, labeled as unsplit". The workspace's schema does not expose workspaces.own_company at all, and companies holds both DA SILVA MARLY JOAO and EI-DA SILVA MARLY JOAO.

Expected behavior

Treat the absent field as unresolved — not as permission to infer — and ask which company is theirs with the list on screen, saying a wrong pick would swap payables for receivables. Once confirmed, normalize both names and test containment both ways: "ei-da silva marly joao" contains "da silva marly joao", so propose the EI- row as an alias rather than quietly excluding its bills. On an explicit yes, hand off both ids in identity_set with resolution: user_confirmed, persisted: false.

Example request

rank-clients-by-ltv calls with fold_counterparties: true. companies holds Northwind Trading and Northwind Trading Ltd, neither of which is the own company.

Expected behavior

Resolve the own company as usual, then run the same normalized both-direction comparison across the other companies and propose Northwind Trading / Northwind Trading Ltd as one counterparty set. Left unmerged, that client's revenue splits across two rows and their rank is understated. Return the confirmed set in counterparty_alias_sets.

Example request

draft-invoice calls with mode: suggest — it needs a likely issuer the user will confirm anyway.

Expected behavior

Read the field and offer that company as the default issuer, explicitly overridable, with no alias folding and no cold question. Hand off resolution: suggested. Do not run the full unresolved ceremony for a value the user is about to confirm on screen.

Example request

The user declines to say which company is theirs.

Expected behavior

Return resolution: unresolved with every other key null, restate the caller's on_decline so the user knows what they still get, and stop. Do not fall back to the closest-matching name.