Desks

What it does

Desks are the projects work hangs on, so a task, a routine, and a workflow template all have a home.

Open Desks (/desks). Team is the org view. List is the project table. ?view=team or ?view=list picks one, and the choice is remembered in the browser. A desk is a project row. Routines and workflow templates bind to a desk so scheduled work has somewhere to land.

The screen is a thin client over the project routes. There is no separate desk table and no MCP tool named desk. Agents pass project_id on tasks and templates.

MCP tools

Tool	Scope	Role
task_list	tasks:read	Tasks on a desk. Filter project_id
task_create	tasks:write	Create a backlog task on a desk
entity_field_write	graph:write	Write one project field through provenance
entity_state_get	none (token still required)	Read agent_state on projects
entity_state_set	projects:write	Replace agent_state
entity_state_patch	projects:write	Shallow-merge agent_state
workflow_template_create	workflows:write	Save a template bound to project_id
workflow_apply	workflows:write	Instantiate that template into tasks on a desk

workflow_apply takes context_project_id for the desk the new tasks should land on.

HTTP endpoints

Method	Path	Role
GET	/cockpit/api/projects	List view
PATCH	/cockpit/api/projects/:id	Update a project from the list or the team view
GET	/cockpit/api/org-structure	Team view
GET, PATCH	/cockpit/api/entities/projects/:id	Drawer read and update
POST	/cockpit/api/entities/projects	Create from a signed-in session

Project actions also live under /cockpit/api/projects/:id for child counts and for convert, delete, merge, owner, and undo-delete.

Permissions

Token scopes come from one permission-set layer. Task reads need tasks:read. Project field state needs projects:write. Template writes need workflows:write and are token-only. The screen uses the signed-in session.

Row access is RLS by creator. Admins see all rows. Members see their own.

Agent example

Call task_create with the desk you want the work on. Set human_approval_to_close on purpose. The default is false.

{
  "tool": "task_create",
  "arguments": {
    "title": "Send the revised scope",
    "project_id": "desk-1",
    "human_approval_to_close": true
  }
}

Expected result: a backlog task on that project. It does not wake a runtime until it moves to todo. Because the flag is true, closing it later opens a card instead of finishing on its own.

{
  "ok": true,
  "status": "backlog",
  "title": "Send the revised scope",
  "human_approval_to_close": true
}