Getting Documents into the Vault
Three routes in: crawl your website, upload files, or write directly. Here is which one suits which kind of knowledge.
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.
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.
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.
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
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
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.mdthe same day, before the next draft is written off the old one. - After a closed-lost review, replace
sales/objections.mdwholesale rather than appending to it.