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

```plain text
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 [#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 [#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 [#size]

Short. Two failure modes:

| Too short                                                                               | Too long                                                    |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `voice.md` containing "be professional and friendly", true of everyone, changes nothing | A brand book where the one useful rule is buried on page 12 |

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 [#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 →](/platform/vault/voice)