Roots and folders

Every document lives in exactly one root, in exactly one folder of that root. A root is the top of a folder tree and decides who the documents in it belong to.

Agents are stored as roots too, but they never appear in the navigator and have their own page.

My documents

Your private tree. A document an agent publishes without naming a root lands here. Nothing in it is visible to colleagues until you share it: through an explicit grant on the document or one of your folders. Restricted links require that permission; public/password links are separate, deliberate choices. Agents address it as root: "~", which is also the default everywhere.

General

Every workspace has one root called General, created with the workspace, with the slug general. Every member can read and write at its top level, so it is the default home for anything that is for the team. General cannot be deleted, its slug cannot change, and the list at its top cannot be edited: it is always the whole workspace at edit. A folder inside General can carry its own access list; see Narrowing and widening on folders.

Shared roots

Workspace owners and admins create shared roots, for example Engineering or Customer success: New shared root in the Shared section of the sidebar, or create_root from an agent. A root has a name, a slug made from the name, an optional icon and a one-line description. A few slugs are reserved (general, personal, me, shared, brain, brains, r).

Creating a shared root needs the Team plan or above; on Free the request is refused with a 402 that names the plan, and the workspace uses General. Roots that already exist keep working if the plan changes.

A new shared root starts restricted to its managers. Add people, a group such as Developers or Leadership, or an explicit whole-workspace grant in Root settings → Access, or with the share_root MCP tool. Members see only spaces and folders they can access. Groups require Team or above.

The access list

Managers can grant individual people or the whole workspace access on every plan. Group grants require Business or above. Existing grants continue to apply after a downgrade, and removing grants works on every plan. Anyone who can open a place can inspect its access list.

The list sits at the top of the root. Each entry names a person (by email), a group (on plans that have groups) or the whole workspace, with one of three levels:

When several entries match you, the highest level applies. Workspace owners and admins always hold edit and manage every root; the person who created a root manages it too while they are a member. Managing means changing the name, icon, description and slug, editing access lists, publishing folders and deleting the root. People outside the workspace never hold a level in a root.

Edit the list in Root settings (the folder menu at the top of a root, or Settings on the root's menu in the sidebar), under Access. Members who are not managers get Who has access on the root's menu instead: they can read the list, not change it.

Inheritance

Folders inherit the list of the root. A document takes the level of the folder it is in. A member sees a root in their sidebar when they hold any level anywhere inside it.

Narrowing and widening on folders

A folder can carry its own access list: Access on the folder. The rule is: walking up from a document's folder, the nearest folder that has a list of its own decides, and that list replaces what the folder would have inherited. It is not merged with the list above it. So a folder list can do both:

• narrow: Engineering/Security reviews lists only the security group, and the rest of Engineering no longer sees that folder;
• widen: Engineering/Handbook lists the whole workspace at view, and everyone can read it even though the root itself is limited to the engineering group.

A person who can see a folder deep inside a root, but not the folders above it, still gets those upper folders in the tree so they can walk down to it. The upper folders show no documents and no counts.

A grant made directly on one document can raise a person's level for that document only. It never lowers what the folder gives.

Removing the last entry from a restricted folder keeps it restricted to space managers. To restore inheritance deliberately, choose Use parent permissions instead, or call inherit_folder_access.

Every change to an access list is recorded in the audit log as access.grant or access.revoke; roots record root.create, root.update and root.delete.

A document in a shared root belongs to the root

This is the one rule to remember. In My documents a document belongs to you: only you move it, change its visibility or retention, or delete it. When a document is published into, or moved into, General or a shared root, it belongs to the root, not to the person:

• everyone with edit there can update it, rename it, move it, change its visibility, listing, retention and alias, and delete it;
• everyone the root lets in can find it in the navigator;
• who wrote each version is still recorded in its history;
• its size counts against the workspace that owns the root;
• folder grants you made in My documents do not follow it. Access now comes from the root.

Its URL does not change, and the link keeps working as the document's visibility says. A Restricted or legacy workspace-gated document in a root opens for the members the root lets in.

The app shows a one-time notice the first time you move something into a shared root: the document will belong to the root, people with access can edit it, and it stays if you leave.

When the author leaves

When a member is removed from the workspace, their My documents travel with them to a new personal workspace. Documents they put in General or a shared root stay where they are, with their history. Their personal entries on root access lists are removed. See Members and roles.

Moving between roots

Use Move to… on a document and pick the root and folder, drag it onto a root or folder in the sidebar, or ask an agent (move_doc with root).

Moving never changes a document's URL, never creates a version and does not touch retention. Deleting a shared root that still holds documents is refused unless you confirm; the documents then move into General with their folders intact.

Renaming, moving and deleting folders inside a root works as in Moving and organizing and needs edit on the folder (and on the new parent). A folder's settings, its access list, its shortcuts and members' stars move with it.

The navigator

One view serves as file browser and wiki. The sidebar shows My documents with its folders, then Shared with General first and the shared roots you can see, each opening into its folder tree. A lock marks a root you can only view. Selecting a root or folder fills the main pane:

• breadcrumbs, the folder's icon, name and description, a View only badge when you cannot edit, and a Published badge when the folder is a site;
• a Grid | List | Page switch;
• New: Note, Page, Snippet, Upload files, and Add shortcut here…. What you create lands in the folder you are looking at;
• actions for people with edit: New folder, Set index page, Reorder, Access, and in the menu Add description, Rename or move and Delete folder. Publish shows for people who may publish. At the top of a shared root the menu also has Root settings.

Grid, List and Page

Grid and List are the file browser: subfolders, documents and shortcuts as tiles or rows. Page reads like a wiki: the folder's index page rendered on top with an On this page outline, and everything else the folder holds listed beneath it under In this folder.

A folder with an index page opens in Page, any other folder in Grid. When someone with edit switches the view, the choice is saved on the folder for everyone. Your own last choice for a folder is also remembered in your browser and wins for you.

Index pages

Set index page picks one document as the folder's landing page. In a shared root it must be a document of that root; in My documents, one of your own. A markdown index page renders in place, diagrams included; an HTML page renders in a sandboxed frame. The index page is pinned first in Grid and List. Clearing it leaves the document untouched.

Manual order

Reorder opens the folder's children as a list you drag, then Save order. The order applies in Grid, in Page and as the navigation of the published site. Anything not placed follows: folders, then documents by title, then shortcuts. Reset returns to that default.

Shortcuts

A document lives in one folder. When it should also appear somewhere else, add a shortcut: Add shortcut here… in a folder's New menu, or Show in another folder… on the document's menu. A shortcut is a pointer, never a copy. It can point at any document of the same workspace that you can open, in any root, and can carry its own label. People who cannot open the target do not see the shortcut. Removing a shortcut leaves the document alone. Adding and removing one needs edit on the folder.

Publishing a folder as a site

Publish on a root or folder turns it, and everything under it, into a read-oriented site. The folder tree becomes the site's left navigation in its manual order, a folder with an index page opens on that page with its children listed beneath, and documents render with the same chrome as the wiki: breadcrumbs, table of contents, search, last edited and backlinks.

In a shared root, workspace owners and admins (and the root's creator) publish. In My documents you publish your own folders. Publishing and unpublishing are recorded in the audit log as folder.publish and folder.unpublish.

Publishing needs the Team plan or above. On Free, turning Published on, or changing who can read a published folder, is refused with a 402 that names the plan. Turning it off always works, and a folder published before a downgrade keeps being served.

On Business and above, the workspace policy can limit folder sites to signed-in readers or turn them off. A refused publish is a 403 that says so. The Publish dialog explains which of the two applies: a plan note links to billing, a policy note names the workspace policy.

Where it lives

A document's page is the folder address followed by its alias, or its id when it has none. /r/<root-slug>/ is the site's home, and /r/<root-slug>/search?q= searches it. A tree published from My documents uses ~<your member id> in place of the root slug. The Publish dialog shows the exact address with a copy button, and uses your workspace domain once it is the link host.

Who can read it

When the workspace policy allows signed-in sites only, public is not offered, and a folder already set to public is served as signed_in.

Subfolders follow the nearest published folder above them. To give a subfolder a different audience, publish it with its own setting. Turning Published off on a subfolder does not hide it while a folder above it is still published; move it out instead. A reader who is not signed in sees Sign in to see more where folders were withheld, and is sent to sign in when nothing at all is visible to them.

The scope rule

A published site serves only what is inside it: the live documents in published folders the reader is allowed to see, plus the targets of shortcuts in those folders. Any other document answers with the same neutral not-found page as a missing one, even if it is unlisted, and it is absent from the site's search and sitemap. Agent files are never published.

Publishing a folder does not change any document's visibility. An unlisted document opens for anyone who reaches its page; a password document shows a card that links to its own address, where the browser asks for the password; a Restricted or legacy workspace document requires a signed-in identity with permission to that document. Setting a folder to public makes its unlisted documents easy to find, so publish only what you mean to.

Search engines

Everything on the shared content host is served noindex and stays that way. A published folder can be indexed only on an active custom domain, and only when Allow search engines is on for the workspace's wiki settings (Team and above). With both, its public pages carry a canonical link, /w/r/<root-slug>/sitemap.xml lists what an anonymous visitor can see, and /robots.txt on the domain allows /w/ and lists a Sitemap: line for every root that has a published folder. Password and restricted documents, and search result pages, are never indexable.

From an agent

Every tool that takes a folder also takes root: omit it or pass "~" for My documents, "general" for General, or a shared root's slug.

Agents publish into My documents. A document an agent publishes lands in the person's own tree unless the agent names a root, and naming General or a shared root is refused until a workspace owner or admin turns on Agents may publish here in that root's settings. The same rule applies to an agent moving a document into a root. Taking a document back into My documents is always allowed. So by default nothing an agent writes reaches colleagues until a person grants access or moves it into a shared root with an appropriate audience. Listing alone grants no access. list_roots reports agent_write for each root so an agent knows where it may publish.

Agents are told that "for the team" is not an instruction to publish into General: they leave the document in My documents and tell you where it is, or list it for the team when you ask for that. They publish into a root only when you name the place and the root allows agent publishing. They publish a folder only when you ask, because it can make documents publicly reachable. Parameters are in the MCP reference; the REST endpoints are under Roots.

Prompts that work:

• "Which shared roots can I write to?" The agent calls list_roots and reads my_level.
• "Publish this runbook to General under Runbooks." publish_markdown with root: "general" and folder: "Runbooks", once General allows agent publishing. Otherwise the agent publishes it into My documents and you move it.
• "Move my incident write-up into the Engineering root, under Incidents/2026." move_doc with root: "engineering".
• "Make the onboarding overview the index page of Handbook and put it, then Tools, then People first." set_folder_meta with index_doc_id and child_order.
• "Show the pricing FAQ in the Sales folder too." create_shortcut.
• "Publish the Handbook folder of General for signed-in readers." set_folder_meta with published: true and publish_visibility: "signed_in".

Limits

Shared roots need Team or above, access lists need Business or above, and publishing a folder needs Team or above; see Plans and limits. Where they are available: 200 shared roots per workspace, root names up to 120 characters, descriptions up to 512, a manual order of up to 2,000 entries per folder, shortcut labels up to 160 characters. Folder path rules are on Folders, tags, and stars.

Keeping shared spaces organized

When a publish or move names a shared space but omits folder, Fermium chooses Members / member name. The destination is tied to the member's account and stays stable after name/email changes. Duplicate names get distinct folders. An explicit project path, such as Projects/Launch, takes precedence; folder: "" deliberately targets the top of the space. Nothing already filed is moved automatically.

Member folders inherit the space's permissions. A Developers space therefore stays visible only to its permitted members, including its Members folders. For common work, use a project folder instead of making copies in several member folders.

Agents use list_roots, create_root, list_root_access, share_root, unshare_root and configure_root. configure_root lets a manager enable Agents may publish here; agents still need edit access. Use share_folder for a folder that should stay in someone's My documents, and create_shortcut to show an accessible document elsewhere without copying it.

Removing every entry from a folder's own access list leaves that folder restricted to managers. To deliberately restore the parent's audience, choose Use parent permissions instead, or call inherit_folder_access(root, folder).