One icon grammar for documents, folders, tags, agents and agent members: curated icon names with twelve colours, emoji, and an uploaded SVG library on Team and above.

Every document, folder, tag, agent and agent member can carry an icon. Icons are presentation only: they never change where a document lives or who can open it. They show in the file browser, the sidebar, the command palette, the inspector and the wiki, so a reader can tell a runbook from a proposal at a glance.

The grammar

An icon is stored as one short string, the same wherever it appears:

Form	Example	Notes
`lucide:<name>`	`lucide:rocket`	a name from the curated set of about 400 icons; unknown names are rejected, not rendered blank
`lucide:<name>/<colour>`	`lucide:rocket/amber`	one of twelve named colours: `gray`, `red`, `orange`, `amber`, `yellow`, `green`, `teal`, `cyan`, `blue`, `indigo`, `violet`, `pink`. No hex values; each name maps to a light and a dark shade so the icon stays legible in both themes
`emoji:U+1F680`		an emoji, stored as code points. You can also pass the emoji itself and it is stored this way. Up to 8 code points, so flags and skin-tone sequences work; plain ASCII text is refused
`svg:<id>`	`svg:3`	an SVG from the workspace library (Team and above)

A bare curated name such as rocket is accepted as a convenience and stored as lucide:rocket. Names use dashes, file-text, shield-check; an underscore is folded to a dash. list_icons returns the full list of valid names, the colours and the library.

Without an icon of its own, each thing falls back to a default: a document shows a glyph for its kind (page, markdown, code, PDF, image, video and so on), a folder shows the folder glyph, a tag the tag glyph. An agent member that points at a document falls back to the document's icon and then to the kind glyph.

Where you set them

In the app:

Documents: click the icon next to the title in the inspector. The owner and anyone with edit access can change it.
Folders: the folder tile's menu in the file browser. Icons on folders are workspace-wide: members can set them on folders that hold their own documents; workspace owners and admins on any folder.
Tags: the icon next to the tag name at the top of a tag view. Any member of the workspace can set it, and everyone in the workspace sees it.
Roots and folders in them: click the icon in the folder pane's header (needs edit on the folder); root managers can also set a root's icon in Root settings.
Agents: an agent's icon is set through the API (PATCH /api/brain-roots/{slug}). Workspace owners and admins only.

The picker has three tabs. Icons searches the curated names and offers the colour row. Emoji offers a searchable grid. Library lists the workspace's uploaded SVGs, with an upload button on Team and above. Remove goes back to the default glyph.

From an agent, set_icon(target, icon) and clear_icon(target) take the same grammar, where target is one of:

Target	Who may set it
`doc:<id>`	the owner or an editor
`folder:<path>`	a member with documents in the folder, or a workspace owner or admin
`tag:<slug>`	any member
`nav:<entry_id>`	an entry in an agent-tree wiki's navigation; a workspace owner or admin
`navigation:<slug>`	an agent-tree wiki's agent, by slug; a workspace owner or admin

Prompts that work:

"Give the runbooks folder a wrench icon." The agent calls set_icon with folder:Runbooks and lucide:wrench.
"Mark everything tagged customer-facing with a green briefcase." The agent calls list_icons to confirm the name, then set_icon on tag:customer-facing with lucide:briefcase/green.
"Use the rocket emoji for the launch plan." The agent passes the emoji itself; it is stored as code points.
"Put our logo on the Onboarding folder." The agent calls upload_icon with the SVG text, then set_icon on folder:Onboarding with the returned svg:<id>.

REST: GET /api/icons, PUT and DELETE /api/icons/target, POST and DELETE /api/icons; see the REST reference. Folders and tags can also carry a short description through PUT /api/icons/description; the file tree returns it with folders.

The SVG library

On Team and above a workspace can upload its own icons: a product mark, a team badge, a partner logo. Each upload is:

small: at most 32 KiB;
validated, not rewritten: an SVG is rejected with the reason when it contains a <script>, an event-handler attribute, <foreignObject> and similar embedding elements, a DOCTYPE or entity declaration, or any href or url() reference that leaves the file. Only same-document #fragment references and inline data:image/ URIs are allowed. The root element must be <svg> in the SVG namespace. Comments do not survive;
deduplicated: uploading the same bytes again returns the existing entry;
served from the content host at /icons/<workspace-slug>/<id>.svg as image/svg+xml, with the same sandbox policy as any published file, so an icon can never run in the app's origin. On a custom domain only that workspace's icons resolve.

Use a square viewBox and currentColor for strokes and fills so the icon follows the theme.

Deleting a library icon (the uploader or a workspace owner or admin) clears every reference to it, so nothing renders a dead svg:<id>; those items fall back to their default glyph. Icon names are 1 to 64 characters of letters, digits, spaces, ., _ and -.

Free workspaces can use curated names and emoji; the Library tab shows what a paid plan adds.

Good icons

Pick icons a reader decodes at a glance and keep one style per agent: all curated icons, or all emoji, not a mix. Use colour for meaning, not decoration: red for anything about incidents, green for anything customer-facing. Agents receive the same advice in their instructions.