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 owner 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. The console's own search bar has no location control today, which is the honest gap this answer leaves you with.

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.

Because a refusal is an event worth keeping. A log that records only what succeeded cannot answer "did anything try", which is most of what an audit trail is for. The line is not a mark against you; it is the record that the boundary held.

What the refusal never does is describe itself to whoever hit it. No path, no id, not even a count comes back in the response — a count over content you cannot read, once per query you choose, is still an oracle. The denial resolves back to filenames only in the log, for an admin reading it.

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 named after a person is a member home: every member of an organization gets one at users/<their name>, beside the org's shared folders, private by default and shared outward only by explicit grant. Nobody holds anything on users itself, so opening it shows you your own home and no one else's.

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