Folders in a Hosted Nest

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.

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.

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

The response returns one row per folder:

{
  "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:

POST /nests/:id/nodes

{
  "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:

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

{ "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 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 — steward scopes, grants, and deletion authority.
• Publishing a Nest — exposing folder-organized content to readers.

Sources

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