storage

Layerline Storage

Workflow for the file storage layer in Layerline (mcp__layerline__ls_* tools + the file-box tools).

Two layers, both important

1. Layerline Storage (LS) — the underlying file/version system. Every uploaded file has a UUID and a version chain. LS handles bytes, versioning, locking, sharing, sync rules.
2. File Boxes — per-entity containers (asset / task / shot / gdd_asset) that attach LS files to a higher-level entity. A box is just a grouping; the bytes live in LS.

A file can exist in LS without being attached to any box. Most production files end up in at least one box (the asset box for the asset they belong to).

File ops

ls_list_files(projectId, path?, lockStatus?, search?, limit?, offset?, sortBy?, sortOrder?)
   // path: prefix (e.g. "Characters/")
   // lockStatus: "locked" | "unlocked"
   // sortBy: "name" | "path" | "updatedAt" | "size"
   // sortOrder: "asc" | "desc"
ls_get_file(fileId)
ls_find_file_by_path(projectId, path)              // exact match; returns { found: false, ... } if missing
ls_rename_file(fileId, name)                        // changes display name only
ls_move_file(fileId, path)                          // changes the path within the project
ls_delete_file(fileId)                              // soft delete

path is the project-relative path including filename, e.g. "Characters/Hero/model.fbx". Don't prepend the project name.

Versions

ls_get_version_history(fileId, page?, limit?)       // newest first
ls_get_version(versionId)
ls_get_download_url(fileId, versionId?)             // omit versionId → current version
ls_restore_version(fileId, versionId)               // creates a new version that copies the restored one

ls_get_download_url returns a presigned S3 URL that's good for ~1 hour and doesn't need an auth header — fetch it with any HTTP client. Use this when you need to actually read the bytes (e.g. inspect a config, copy a model into a Godot project).

There is no upload tool exposed via MCP. Uploads happen through the desktop client or the REST upload endpoint. If the user asks "upload this", explain they need to drop the file via the Layerline app — the agent can't push bytes through MCP.

Locks

Exclusive locks: only the locker (or admin via force-unlock) can push new versions while a file is locked.

ls_lock_file(fileId, reason?)
ls_unlock_file(fileId)                              // owner only
ls_force_unlock_file(fileId, organizationId?)      // org admin/owner only
ls_get_lock_status(fileId)                          // { locked: true, ... } or { locked: false }
ls_get_lock_history(fileId)                         // audit trail

Use locks before "I'm starting work on this rig", and unlock when you push the new version. Don't force-unlock without authorization — it stomps another user's work in progress.

Activity & quota

ls_get_file_activity(fileId, page?, limit?)
ls_get_project_storage_activity(projectId, page?, limit?)
ls_get_storage_usage(organizationId?, projectId?)   // bytes used, file/version counts, quota

Share links

ls_create_share_link(projectId, fileId? | folderPath?, shareType, authMethod, password?, expiresIn?, maxDownloads?, label?)
   // shareType:  "public" | "protected"
   // authMethod: "none" | "password" | "email_invite"
   // expiresIn:  "1d" | "7d" | "30d" | "90d" | "never"
ls_list_shares(projectId, organizationId?)
ls_get_share(projectId, shareId)
ls_update_share(projectId, shareId, expiresIn?, password?, label?, maxDownloads?)
ls_revoke_share(projectId, shareId)                 // immediate; cannot be undone

Pick exactly one of fileId or folderPath. For password-protected shares, set authMethod: "password" and pass password. For email-invite shares, set authMethod: "email_invite" (the system handles invite emails out-of-band).

Sync rules

Glob patterns that include or exclude files from cloud sync at the project level.

ls_list_sync_rules(projectId)
ls_create_sync_rule(projectId, ruleType, pathPattern, isFolder)
   // ruleType: "include" | "exclude"
   // pathPattern: glob like "*.fbx", "Textures/**", "Backups/"
ls_delete_sync_rule(projectId, ruleId)
ls_batch_set_sync_rules(projectId, rules[])         // wipes existing, installs the new set

ls_batch_set_sync_rules is destructive — confirm with the user before calling if they didn't explicitly ask for a wipe.

File Boxes

A File Box groups LS files under one entity. Every project asset, task, shot, and GDD asset can have a box.

get_file_box(organizationId?, projectId, ownerType, ownerId)
   // ownerType: "task" | "shot" | "gdd_asset" | "project_asset"
   // returns { exists: false } if no box yet
get_or_create_file_box(organizationId?, projectId, ownerType, ownerId, displayName?)
list_file_box_files(boxId, limit?, offset?)
attach_file_to_box(boxId, lsFileId, notes?)
detach_file_from_box(boxId, fileId)                 // soft removal; LS file untouched
reattach_file_to_box(boxId, fileId)                 // restore a detached link
get_file_box_activity(boxId, cursor?, limit?)
delete_file_box(organizationId?, projectId, boxId)  // soft delete; LS files untouched

Use get_or_create_file_box when you're about to attach files and don't know if the box exists — it's idempotent.

list_file_box_files returns items that link to LS file ids. Pair the returned lsFileId with ls_get_download_url to get the bytes.

Common workflows

"Find Hero Knight's rig file and give me a download link"

1. ls_find_file_by_path(projectId, "Characters/Hero Knight/Rigging/hero_rig.fbx").
2. If missing, fall back to ls_list_files(projectId, search="hero_rig").
3. ls_get_download_url(fileId) → return the URL with its expiresAt.

"What files are attached to task MGP-42?"

1. Resolve taskId via list_tasks(projectId, search="MGP-42").
2. get_file_box(projectId, ownerType="task", ownerId=taskId). If exists: false, the task has no files yet.
3. list_file_box_files(boxId).
4. Optionally enrich each result with ls_get_file(lsFileId) for size/version metadata.

"Lock hero_rig.fbx for me, I'm about to rerig"

1. ls_find_file_by_path(...) → fileId.
2. ls_get_lock_status(fileId) → check it's not already locked.
3. ls_lock_file(fileId, reason="Rerigging skeleton").

"Roll Hero Knight's model back to v3"

1. ls_find_file_by_path(...) → fileId.
2. ls_get_version_history(fileId) → find the v3 entry's id.
3. ls_restore_version(fileId, versionId). (This creates a new current version that copies v3.)

"Share the latest art-direction folder with the external partner"

1. ls_create_share_link(projectId, folderPath="ArtDirection/2026-Q2/", shareType="protected", authMethod="email_invite", expiresIn="30d", label="Q2 Art Direction Review").
2. The link comes back in the response — paste it to the user.

"Attach the new sword model to the Hero Knight asset's box"

1. Resolve projectId and heroAssetId.
2. get_or_create_file_box(projectId, ownerType="project_asset", ownerId=heroAssetId) → boxId.
3. ls_find_file_by_path(projectId, "Props/Weapons/hero_sword_v01.fbx") → lsFileId.
4. attach_file_to_box(boxId, lsFileId, notes="primary sword for Hero Knight").

Pairings

• Reviewing a file? You'll need its fileId and versionId for create_review — see layerline:reviews.
• Wanting to know which task/asset/shot owns a given file? File ownership is via boxes — there's no reverse lookup tool yet, but ls_get_file_activity shows attach/detach events.
• Generating an asset and want it persisted? See layerline:genstudio — generate with projectId + assetName + assetTagFolder auto-uploads and attaches.