# Getting Documents into the Vault



## Route 1: Crawl Your Website [#route-1-crawl-your-website]

Surface reads your public site and writes a first Vault: what the product does,
who for, the proof you publish, the words you use. No preparation needed.

```
create_vault { "websiteUrl": "https://www.yourcompany.com" }
```

One call, and it builds the environment's *first* Vault, so it is a one-time
move rather than a re-crawl. See the
[Vault tools](/mcp-server/tools#vault). In the app, the same step appears
as **Site scanned** on the Vault Setup checklist.

**Good for:** product facts, positioning, customer names, category language.
**Bad for:** anything true but unpublished.

## Route 2: Upload Files [#route-2-upload-files]

Upload what you already have: positioning, battlecard, pricing rationale,
messaging guide, call summaries. Uploads land in the Vault's `Uploads/` folder,
which is the one folder agents read but never write to.

<Info>
  Which file types the uploader accepts is not documented. Check in the app, or
  ask your FDE, before you plan a bulk upload of anything that is not Markdown.
</Info>

<Tip>
  Split before you upload. A 60-page brand book arrives as one enormous document,
  and an agent asked for your voice rules has to pull all of it. The same content
  as eight documents (`brand/voice.md`, `brand/words-we-avoid.md`,
  `product/positioning.md`) is cheaper to read and easier to correct.
</Tip>

## Route 3: Write Directly [#route-3-write-directly]

The most useful documents were never a file: the objection that keeps killing
deals, the phrase your CEO refuses to sign off, the reason you lose to one
competitor. Write them as short Markdown, in the app or over MCP.

```
apply_vault_changes {
  "commitMessage": "Add the three objections from Q3 closed-lost",
  "operations": [
    { "type": "create",
      "path": "sales/objections.md",
      "content": "# Objections we actually hear\n\n## \"We already pay for Chili Piper\"\n..." }
  ]
}
```

Edits are atomic and versioned: 20 documents per call, each carrying the
`revision` you read, so two agents cannot overwrite each other.
`read_vault_documents` returns that revision.

## What to Put in First [#what-to-put-in-first]

Paths are just strings, so the names below are our suggestion, not a convention
Surface enforces. In the order that changes output the most:

| Document                 | Why it earns its place                                          |
| ------------------------ | --------------------------------------------------------------- |
| `product/positioning.md` | Stops every draft opening with "in today's landscape"           |
| `brand/voice.md`         | The words you use, the words you refuse                         |
| `customers/proof.md`     | Named customers and real numbers instead of "leading companies" |
| `sales/objections.md`    | The five things buyers actually push back on                    |
| `competitors/<name>.md`  | Your honest take, including where they are better               |
| `product/icp.md`         | Who this is for, and explicitly who it is not for               |

## Keeping It Current [#keeping-it-current]

Treat every document as authoritative until someone changes it. Nothing in the
Vault flags itself as stale, so a positioning doc from two quarters ago reads to
an agent exactly like one written this morning.

* **After a positioning change**, update `product/positioning.md` the same day,
  before the next draft is written off the old one.
* **After a closed-lost review**, replace `sales/objections.md` wholesale rather
  than appending to it.

[Folders and structure →](/platform/vault/structure)