Folders, tags, and stars

Fermium has three ways to organize documents. They do different jobs, so it helps to keep them straight:

• A folder is where a document lives. Every document is in exactly one folder (or at the root), and folders nest, like a file system.
• A tag is a topic. A document can carry several, and a tag view lists every document with that tag no matter which folder it is in.
• A star is a personal shortcut to a document or a folder. Stars are yours alone and sit at the top of the sidebar.

None of these changes who can open a document. Access is set by visibility and listing; folders, tags and stars only affect how you find things.

Folders

A folder is a path such as Customers/Acme or Runbooks/Payments/On-call. Publishing into a path that does not exist yet creates it, so you rarely need to make folders by hand. A document at the root has an empty folder path.

Every folder tree hangs under a root. In My documents folders are per account: they organize your own documents, and two people in the same workspace each have their own tree. In General and in shared roots the tree is shared: everyone the root lets in sees the same folders. Everything on this page applies to both; where an agent tool or endpoint takes a folder, it also takes root.

In the app

The sidebar shows My documents and, under Shared, General and the shared roots you can open, each as a folder tree. Open a folder to see its subfolders and the documents directly in it, as a grid, a list or a page with the folder's index page on top, with a breadcrumb trail back to the root. You can create a folder, rename it, and delete it from there, and move documents between folders by dragging them or with a Move action on the document. Details of moving, renaming and deleting are on Moving and organizing.

From an agent

Every publish_* tool takes a folder parameter, and existing documents move with move_doc. The folder tools are list_folders, create_folder, rename_folder and delete_folder; list_docs takes folder (with recursive to include subfolders). The MCP reference has the parameters.

Prompts that work:

• "Publish this proposal into Customers/Acme."
• "Move the Q3 roadmap into Planning/2026."
• "What is in Customers/Acme? Update the proposal there instead of making a new one."
• "Rename Clients to Customers." The agent calls rename_folder; everything inside moves with it.
• "Delete the Scratch folder and put whatever is in it at the root." The agent calls delete_folder with force.

Agents are told in their instructions to check list_folders before inventing a new top-level folder, so a tree you set up in the app is what the agent will use. If you want a particular layout, say so once: "put customer work under Customers/<name>".

Path rules

• Segments are separated by / (a \ is accepted and treated the same).
• Each segment is 1 to 64 characters of letters, digits, spaces, ., _ and -. It must start with a letter or digit and cannot end in ..
• Up to 8 levels deep, and the whole path is at most 512 characters.
• Case is kept as you typed it: Customers/Acme stays Customers/Acme.
• Leading and trailing spaces in a segment are trimmed and runs of spaces collapse to one.

A path that breaks a rule is rejected with a message naming the bad segment.

Tags

A tag is a lowercase label like customer-facing, q3 or runbook. A document can carry up to ten. Tags are for topics that cut across your folders: the customer-facing documents live in different customer folders, but one tag view shows them all together.

In the app

Tags have their own section in the sidebar. Open a tag to see every document carrying it, with the folder each one lives in, so you can jump from the tag view to the folder. Tags show on tiles and can be edited in the inspector.

From an agent

• At publish time: tags: ["customer-facing", "q3"] on any publish_* tool or on create_upload.
• Later: set_tags(doc_id, tags) replaces the whole set. Pass [] to clear. To add one tag, read the current tags from any tool response and pass the full list back. Full replacement makes retries safe.
• Finding: list_docs(tag="customer-facing") lists the topic across all folders. folder and tag can be combined to narrow a topic to one folder.
• REST: PATCH /api/docs/{id} with tags, GET /api/docs?tag=..., and GET /api/tags for your tags with counts.

Prompts that work:

• "Tag the proposal customer-facing."
• "Show me everything tagged runbook."
• "Publish this postmortem into Incidents/2026 and tag it postmortem and payments."

Format

Tags are normalized to lowercase slugs of 1 to 32 characters from a-z, 0-9 and -, with no leading or trailing dash. Spaces and underscores become dashes, so "Customer Facing" is stored as customer-facing. Anything that still does not fit is rejected with a message naming the tag. Duplicates are collapsed and the set is stored sorted.

Good tagging practice

Tags work when the set is small and everyone uses the same words. A handful of tags that describe what kind of thing this is or who it is for is more useful than one tag per project (folders already do that):

• audience: customer-facing, internal
• kind: runbook, postmortem, proposal, dashboard
• time: q3, 2026

Avoid a tag that duplicates a folder name. If every document in Customers/Acme is tagged acme, the tag adds nothing. Tell your agent the convention once ("tag anything a client will see customer-facing") and it will follow it.

Stars

A star is a shortcut for you. Star a document you keep coming back to, or a folder you are working in this week, and it appears in a Starred section at the top of the sidebar. Stars are personal: nobody else sees them, and they do not change the document.

You can star your own documents, your own folders, and documents that workspace members have listed for the team. The root cannot be starred.

Stars follow their targets. Renaming a folder keeps the star pointing at the new path. If a starred document is deleted, the star disappears. Stars are set in the app (the inspector and the tile menu); there is no MCP tool for them, since they are a reading aid for people rather than something an agent needs. The REST endpoints are GET, POST and DELETE /api/stars, documented in the REST reference.

Icons, agents and the wiki

Folders and tags can carry an icon and a short description. A folder can also have an index page, a manual order and shortcuts, and can be published as a site whose navigation is the folder tree, so organizing by folder is also how you build a wiki. An agent can name a root, a folder or a tag as a source: agents that load the agent then get the live documents under it that their user may open, without anyone curating each document by hand.

Agents get the folder tree in one call with list_tree, and can mirror a folder locally with download_bundle; both include only documents the agent's user may open. See Orientation.

Links never break

A document's URL is https://fermiumusercontent.app/d/<slug>/, and the slug is fixed when the document is created. No URL contains a folder or a tag. Moving a document, renaming or deleting the folder it is in, or changing its tags leaves every link, embed and bookmark working. This is the reason folders are a property of the document rather than part of its address.

Limits

Folders and access

In General and shared roots, access comes from the root's access list and from lists on its folders; see Roots and folders. In My documents, on Business and above, a grant set on one of your folders gives a person, a group or the workspace view, comment or edit on every document of yours at or under that path. See Members and roles. Folders and tags never change who can open a link on their own.

Documents can also link to each other by name rather than by URL, with [[alias]] in markdown or /x/alias anywhere, and cite a file and a line range with [[alias/path#L12-L20]]; see Links between documents.