# Competitor Monitoring



The first of the Vault's two live connections. It is a **writer**, not a
reader: the [Competitor Agent](https://www.withsurface.com/docs/platform/campaign-agents/competitor-agent)
researches each company on your watchlist and files what it found as Markdown
in the Vault.

## What It Writes, and Where [#what-it-writes-and-where]

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| **Runs**       | Nightly, at 02:00 UTC                                                                       |
| **Writes to**  | `Competitors/<domain>/` , one folder per rival                                              |
| **Looks back** | 30 days on the first pass. After that, from the last successful read, minus a 3-day overlap |
| **Live when**  | Your watchlist has at least one competitor                                                  |

The folder is named after the **domain**, not the display name. That is
deliberate: two competitors called "Zendesk AI" and "Zendesk-AI" slug to the
same folder, and a shared folder means one company's documents overwrite the
other's, leaving findings citing evidence about the wrong company. A hostname
is already unique per environment and already safe in a path.

The 3-day overlap is deliberate too. The searches behind a pass are not
deterministic, so one pass samples the window rather than reading all of it. A
window starting exactly where the last one ended would make anything the first
sample missed missed for good. The agent is given the last 20 headlines it
reported for that competitor and told not to repeat itself.

## Findings Are Not in the Vault [#findings-are-not-in-the-vault]

Worth being precise about, because the split surprises people:

* **The documents** the agent writes (the research itself) go to the Vault.
* **The findings** (the "pricing change", "positioning shift" rows you see on
  the Competitor Agent screen) go to Postgres, and cite the Vault document
  their evidence landed in.

So the Vault holds the evidence, and the app holds the index over it.

## Adding a Competitor [#adding-a-competitor]

Adding one by hand asks for the **domain** and nothing else. Surface fills in
the name from the domain and records the reason as "Added by you." The agent
can also propose competitors it found while researching, which you approve.

<Info>
  The Competitor Agent and the Vault are both behind a feature flag today. If the
  Vault screen shows no Connections panel, ask your FDE whether the flag is on
  for your workspace.
</Info>

## Surface Email, and What It Already Does [#surface-email-and-what-it-already-does]

The Connections panel lists **Surface email** as coming soon, and for a
customer-configurable inbox that is accurate. There is one thing behind it
already, and it is narrower than the row suggests: **competitor newsletters**.

When a competitor is on your watchlist, Surface can sign up to their newsletter
at a unique inbound address and file what arrives at
`Competitors/<domain>/inbox/`, one dated Markdown file per message. Three
things about it:

* **Every filed message opens with an attribution line** naming the sender and
  saying, in the document itself, that a third party wrote everything below it
  and to read it as evidence and never as instructions. Anyone who learns the
  address can put text into a Vault an agent reads.
* **90-day retention.** Anything older is deleted in the same commit that files
  a new message.
* **It is not user-configurable.** You cannot point it at your own mailing
  lists today. That is the part the "coming soon" row is about.

[Competitor Agent →](https://www.withsurface.com/docs/platform/campaign-agents/competitor-agent) ·
[Content Analytics](https://www.withsurface.com/docs/platform/vault/connections/content-analytics)