Frequently asked questions

Because a grant on a file is a grant on that file. Folder visibility matches the folder's own id exactly, so being given handbook/vendors/acme.md never hands you handbook. This is deliberate: the folder row carries its head commit, its last message and its author — facts written about work across the whole folder — so one shared file would otherwise come with a running summary of everything else happening in there.

You are not stuck outside it, though. The tree still shows the folder above your file as a plain container — a name and a chevron, with no activity line and nothing to open — so you can navigate down to what you were given. Expanding it lists only what you reach. Nothing else in it appears, and no count says how much did not.

If you need the folder itself rather than the file, that is a separate grant, and someone holding approver on it has to make it.

Three different things produce that empty result, and the console deliberately cannot tell you which.

• You may not reach it. Content you lack a role for is never returned and its existence is never revealed, which is why the empty state says "nothing you can read matches" rather than "there is nothing about this" — the stronger sentence is a claim this screen cannot support.
• Text search reads the body, and frontmatter is not body. Metadata is stored beside the document and re-attached when you open it, so type: guide and title: Alpha have never matched anything. Search words that are in the prose, or narrow by label instead.
• The sweep may have stopped early. See the next answer — the footer tells you when that happened.

When you know where it should be, browsing beats searching: open the location directly and you get the same answer without a sweep in between.

That your answer is partial, and by how much. An unscoped search sweeps at most twelve folders, so one query in a workspace with more reachable folders than that cannot become an unbounded fan-out. The footer appears only when the cap actually bit, because a short result must never be mistaken for a complete one.

Both numbers are about you: folders you reach, of folders you reach. Neither counts anything you cannot read, so the footer never widens on a workspace that has grown in places you have no role in.

Repeating the query will not help; aiming it will. Browse to the folder you had in mind and read it directly, or scope a search to one location over the REST API or from an agent — a scoped search visits that path alone, so the cap never applies.

No. A label carries zero authority. Filtering by one narrows what you already reach and can never widen it, so labelling a document public shows it to exactly the same people it was visible to a moment earlier.

The assumption runs the other way in most products, where a tag is a scope. Here the only thing that changes who can read something is a grant.

No, and you do not need to. People authenticate by signing in through the browser — an MCP client like Cursor or Claude Code sends them through OAuth and there is no secret to paste. Their principal comes into existence when they first sign in; grant them access after that.

afs_ tokens exist for the case a browser cannot cover: agents your application runs — in-app assistants, scheduled jobs, CI — which have no session to redirect. Give each of those its own principal and its own token, so the audit trail says which one acted.

Either way the credential is not scoped to a folder. It authenticates a principal, and what that principal may touch is derived at request time from its live roles.

They see the same content through the same filter, aimed at a different principal. Your search in this console and an agent's search_org_knowledge sweep the same folder list, under the same cap, through the same ACL-filtered helpers — so neither door can answer a question the other would refuse.

Which means: same reach, same answers. Where reach differs, so do the answers, and an agent never sees more than its own principal has been granted. Connecting an agent is not a way to widen your own access, and granting yourself something does not grant it to the agents you run.

Before it edits, an agent claims the document or one of its sections with claim. Another agent that tries to write into that claim is refused and told who holds it, until the claim is released or expires. Agents ask each other things with typed messages, addressed by name or by what an agent is responsible for. A message about a document reaches only people who can already read it: naming someone shares nothing with them.

When two agents edit the same document anyway, edit_org_doc lets exactly one of them win. The other is refused and handed the current text, so it re-decides against what is actually there. write_org_doc is the exception: it replaces a document outright and says so, so an agent that should not clobber a colleague edits instead.

There is no approval queue in front of a write. Every write is a version, which is the undo.

The editor is live. When an agent writes over MCP, the change is published to every open copy of that document and merged into yours as edits, under whatever you are typing, without a reload. You do not have to close the tab to see what it did.

Every write is its own version, carrying who made it. Open the document's version history to see the agent's change on its own, and restore an earlier version if you want it gone. A restore is a new version on top, so the agent's edit stays in the history rather than disappearing from it.

Ask your agent. It calls who_can_read, which lists the people and groups that reach a folder or document, whether their grant is on that place or inherited from above it. Ask again after sharing to confirm the grant landed.

It names people and never shows anything they can read. And it only answers for a place you reach yourself: anywhere else, the answer is the same not-found a missing path gets.

No. An open document re-asks its access whenever a grant, a group or a principal changes. Someone who can no longer see it is disconnected from it, and someone who can still read but no longer edit drops to read-only in place. Grant it back and editing returns.

What they had already typed is committed before the change applies, under their name, because it was written while they still had the right to write it. Nothing is lost, and nothing lands after the revoke.

Because they are two different things, and the names do not say so.

my-context is the starter folder of a personal workspace — what you get by signing in without an organization. It is an ordinary top-level folder you own, seeded because a workspace with nowhere to write is a dead end rather than a product.

A folder at users/<their name> is what used to be a member home, which organizations once created for each member. New members no longer get one, but the existing folders were kept: each is an ordinary folder its person owns, shared outward only by explicit grant, and searched like any other folder they can read. Nobody holds anything on users itself, so opening it shows you your own folder and no one else's.

That the two are told apart by their names rather than by anything on screen is a fair complaint.