Folders give a hosted nest a nested, hierarchical structure. You can organize documents into folders at any depth, list a folder tree with per-folder counts served straight from a database index, create documents directly into a folder, and move documents between folders while their grants, stewards, and version history follow along. Folders are also the unit for scoped sharing and deletion, and they can group a document maturity board.

## Folder paths and limits

Folders nest to a maximum of 8 levels. Each path segment is slugified and limited to 100 characters, producing stable, URL-safe folder paths.

| Constraint | Value |
| --- | --- |
| Maximum nesting depth | 8 levels |
| Per-segment length | ≤ 100 characters |
| Segment format | Slugified |

## Listing folders

List the folders under a nest with a single call. The response is served from a database node index — no document bodies are opened — so it stays fast even on large nests.

```bash
GET /nests/:id/folders?folder=<path>&recursive=0
```

The response returns one row per folder:

```json
{
  "folders": [
    { "path": "engineering/runbooks", "count": 4, "total": 11 }
  ]
}
```

- **`count`** — documents directly in that folder.
- **`total`** — documents across the whole subtree beneath it.
- Folder-only levels (folders that contain sub-folders but no direct documents) still get a row, so the tree is complete.

## Creating a document in a folder

Create a node directly into a folder by including a `folder` field:

```bash
POST /nests/:id/nodes
```

```json
{
  "title": "Deploy Runbook",
  "folder": "engineering/runbooks"
}
```

The resulting node id is composed from the folder path and the slugified title:

```
nodes/<folder>/<slug(title)>
```

A `409` is returned if a document with the same folder and title already exists.

## Moving a document

Move a document to a different folder:

```bash
POST /nests/:id/nodes/:nodeId/move
```

```json
{ "folder": "engineering/archive" }
```

Grants, stewards, and version history follow the document to its new folder — a move re-homes the document without breaking its governance state or history.

## Folder-scoped sharing and deletion

Folders are a scope for both sharing and deletion:

- **Sharing** — grants can be applied at the folder level, so a whole folder (and its subtree) can be shared as a unit.
- **Deletion** — folder-scoped deletion is supported. Folder-level deletion flags require a nest-scope steward row to raise; see [Governance & Stewardship](https://nest.promptowl.ai/d/promptowl-documents/platform/governance/governance-stewardship) for the deletion authority model.

## Maturity board

A kanban-style maturity board can group documents by folder, giving a per-folder view of where each document sits in its lifecycle.

## Related

- [Governance & Stewardship](https://nest.promptowl.ai/d/promptowl-documents/platform/governance/governance-stewardship) — steward scopes, grants, and deletion authority.
- [Publishing a Nest](https://nest.promptowl.ai/d/promptowl-documents/platform/publishing/publishing-a-nest) — exposing folder-organized content to readers.

## Sources

- PromptOwl/contextnest-community PRs: #96, #136, #191, #232, #240, #246, #247.