Agents

Folders and recipes

Pull a project folder before creating, so new work lands in the owner's style.

When a user says "make another one like the ones in my launch folder" or "in my usual style", the style is not in your training data. It is on their shelf. Pull the folder before you author.

The pull

Folders are the user's private shelves (the workspace presents a folder as a project; on the wire the noun stays folder). They hold voses, assets, recipes, and nested subfolders up to five levels.

Text
GET /api/folders          all folders: id, name, slug, parentId, counts
GET /api/folders/{id}     one folder's own contents:
  folder            id, name, slug, description, parentId
  subfolders        listed, never inlined; pull one by id when it matters
  recipes           full markdown bodies included
  inheritedRecipes  ancestor recipes, root first, each marked with its
                    source folder (folderId, folderName, folderSlug)
  voses             exemplars, with contentUrls for config and thumbnail
  assets            reusable files, by absolute fileUrl

Match a named folder against name and slug across the whole list; slugs are unique across all levels. A folder's pull is its own contents only, with one addition: recipes inherit down the tree. A parent folder's recipes bind every descendant, so the pull inlines them as inheritedRecipes with their source folder named on each. On contradiction the deeper file wins: the folder's own recipes beat inherited ones, nearer ancestors beat farther.

Recipes

A recipe is a plain markdown file in the asset pipeline: SKILL.md-shaped frontmatter (name, description), then instructions that say how this user's work should look and feel. The folder is the collection and its .md files are facets named by role: TASTE.md is the judging bar, DESIGN.md the technique spec, and whatever else intent demands (MOTION.md, COPY.md, BRAND.md). Role names are convention the platform never enforces; any .md is a recipe.

Name a recipe in caps. It is the file read before anything is made, the role CLAUDE.md and AGENTS.md play in a repo, and the name is what says so. A recipe an API key uploads or renames is stored with its stem uppercased (cut.md lands as CUT.md), so write it that way and the terminal and the shelf agree. A person's own upload keeps whatever they typed.

Read every .md in the folder, own and inherited alike, and follow them over your own defaults. On conflict the more specific file wins, deeper beats shallower, and a genuine contradiction goes back to the user as a question. When a recipe and the folder's recent exemplars disagree, prefer the exemplars and tell the user the recipe looks stale.

Your content key can write recipes, for when the user asks you to distill a style you converged on together:

Text
POST /api/assets/uploads           declare <STYLE.md> with folderId and
                                   intent "library", send it, then /complete
PUT  /api/assets/{id}/file         replace in place, raw markdown body
PATCH /api/assets/{id}             { "filename": "DESIGN.md" } renames in
                                   place; bytes and fileUrl untouched, a
                                   recipe stays .md
GET  /api/assets?category=recipe   locate recipes outside a folder pull

Only write or update a recipe when the user asks for it.

Create onto the shelf

Author with the exemplars and recipes in mind, then create with the folder so the work lands where the user will look for it:

Text
POST /api/vos    { ..., "folderId": "{folder id}" }

The shelf is the human's

Your key may add organization, and only when the user asks for it: create a folder (POST /api/folders, nesting via parentId) and move your work into it (PATCH /api/vos/{id} or PATCH /api/assets/{id} with folderId; null unfiles). The CLI wraps all three as vos folder list, vos folder create and vos folder move, renames an asset as vos asset rename, and writes a recipe as vos recipe push (--folder creates, --asset replaces in place with the prior body kept). Renaming, deleting and reordering FOLDERS stay session-only and your key gets refused; an asset is work, not shelf structure, so renaming one is an ordinary edit. You fill the shelf; you do not reshape it.