> ## Documentation Index
> Fetch the complete documentation index at: https://palette.team/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use README files to guide Palette Desktop agents

> Use a short README or index to explain a folder to teammates and give agents useful context when you link or point them to the relevant file for a task.

A README (or index) file is a short note at the top of a folder that explains what the folder is for and where things live. CLAUDE.md and AGENTS.md can instruct supported agents across the workspace; a folder README is a reference for one folder.

`README.md` is not a universal agent-instruction filename. Link important READMEs from CLAUDE.md or AGENTS.md, or point the agent to the relevant file in your prompt.

## Why folder READMEs help

* Agents can use the relevant README when you link or point them to it, so you need less explaining.
* New teammates get oriented without asking.
* The folder documents itself, so it stays useful as it grows.

## What to put in a folder README

* What this folder is for, in a sentence.
* What lives here and how it is organized.
* Any conventions specific to this folder.
* Where to go next.

## Example

Add READMEs where a folder needs explanation. Here is a slice of a go-to-market workspace in which parent READMEs point to what is below them.

```text theme={null}
gtm-workspace/
├── README.md                  # what this workspace is
├── foundations/
│   ├── README.md              # what you know: brand, market, strategy
│   ├── brand/
│   │   └── README.md          # voice, messaging, positioning
│   ├── market/
│   │   └── README.md          # your ICP and competitors
│   └── strategy/
│       └── README.md          # where you're going and why
└── accounts/
    ├── README.md              # one folder per customer
    ├── acme-corp/
    │   └── README.md          # the Acme account context
    └── globex/
        └── README.md          # the Globex account context
```

A folder README can list its sub-folders, so an agent or a teammate finds the right one fast:

```markdown theme={null}
# Foundations

What you're built on: the reference material that rarely changes. Ask agents
to read this before work that depends on the company's foundations.

## Subfolders

- **brand/:** voice, messaging, positioning. How you present yourself.
- **market/:** your ICP and competitors. Who you sell to and what you're up against.
- **strategy/:** where you're going and why.
```

## Set it up across your workspace

You do not have to write these by hand. Give your agent a prompt like this, and it will do the whole tree in one pass while you review before it saves.

```text theme={null}
Go through this workspace and add a short README.md to every folder that
doesn't have one, starting at the top level and working into the main
sub-folders. Each README should say, in a few lines: what the folder is for,
what lives in it and how it's organized, any conventions specific to it, and
where to go next. When a folder has sub-folders, list them with a one-line
description each. Keep them scannable and match the style of the parent
folder's README. Guidance: https://palette.team/docs/palette-desktop-readme-and-index-files
```

To cover folders outside this workspace, add them as [references](/docs/desktop/references) first, then name them in the prompt.

## Keeping them current

Ask your agent to update the README when the folder changes, the same way you keep CLAUDE.md and AGENTS.md sharp.

## Related

* [Working with CLAUDE.md and AGENTS.md](/docs/desktop/claude-md-and-agents-md), the same idea for the whole workspace
* [Structuring your workspace](/docs/desktop/structuring-your-workspace), how the folders fit together