Getting Documents into the Vault

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. 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

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.

The uploader takes .pdf, .md, .markdown, .txt and .docx, up to 25 MB per file and 20 files per batch. There are three tabs behind the same pipeline: upload files, paste text, paste a URL. See Uploads.

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": [
    { "op": "create",
      "path": "sales/objections.md",
      "title": "Objections We Actually Hear",
      "body": "## \"We already pay for Chili Piper\"\n..." }
  ]
}

title is its own field because Surface composes the frontmatter block. Write your own --- block into body and the document ends up with two.

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.

The full write contract is on Vault over MCP.

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:

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 →