Folders and Structure

Paths are just strings, so any structure works and Surface does not enforce one. A Vault created in the app opens with Company/, Uploads/, Competitors/, Agent notes/ and Calls/, which is a fine place to start.

The layout below is what we suggest once a Vault grows past a handful of documents. Rename any of it.

brand/
  voice.md              How we sound. Words we use, words we never use.
  boilerplate.md        The company description, approved, in three lengths.
product/
  positioning.md        What it is, who for, what it replaces.
  icp.md                Who we sell to. And who we do not.
  <capability>.md       One per product area. Facts, limits, screenshots.
customers/
  proof.md              Named logos, real numbers, quotable lines.
  <customer>.md         The full story, for the ones worth a case study.
competitors/
  <competitor>.md       Our honest take, including where they win.
  landscape.md          How the category is usually framed, and how we reframe it.
sales/
  objections.md         What buyers push back on, and the answer that lands.
  pricing-rationale.md  Why it costs what it costs.
strategy/
  <initiative>.md       This quarter's bets, so campaigns ladder to something.

Why Folders Matter

browse_vault takes a pathPrefix, so an agent can list one folder instead of the whole Vault. An agent you write yourself, drafting a comparison, can pull competitors/ and product/positioning.md and leave your case studies alone.

A flat Vault of 60 files named doc-1.md to doc-60.md still works. It is just harder to point anything at a subset of it.

Naming Rules That Pay Off

• Make the path readable. browse_vault returns paths, titles and body snippets, and competitors/chili-piper.md is unambiguous in a list of 60.
• One subject per document. If the title needs an "and", split it.
• Kebab-case, no dates. pricing-rationale.md, not Pricing Rationale (2026 v3 FINAL).md.
• Say the negative. A product/icp.md listing who you do not sell to stops more bad drafts than the positive half.

Size

Short. Two failure modes:

If a document needs its own table of contents, it is usually two documents. read_vault_documents takes offset and maxChars, so a long document can be read in pieces, but splitting it is easier to correct later.

Moving Things Later

One apply_vault_changes call with move operations, up to 20 documents at a time. Each operation carries the revision you read.

apply_vault_changes {
  "commitMessage": "Split the brand book into voice + boilerplate",
  "operations": [
    { "type": "move", "from": "brand-book.md", "to": "brand/voice.md", "revision": "..." },
    { "type": "create", "path": "brand/boilerplate.md", "content": "..." }
  ]
}

Writing in your voice →