<!-- source: https://docs.dreamlake.ai/workspaces/folder-visibility @ 0.1.192 b2f973b1 -->
# Folder and Bindr visibility

Ordinary filesystem folders and Bindrs are different kinds of organization.
Both support **Private**, **Unlisted**, and **Public** visibility:

| Setting | Visitors with the direct link | Public discovery |
| --- | --- | --- |
| Private | Cannot open | Hidden |
| Unlisted | Can open | Hidden |
| Public | Can open | Listed within an accessible project |

Project owners and explicitly admitted collaborators keep their existing access.
Only Project ADMIN can change visibility. An existing folder or Bindr without an
explicit setting retains its inherited behavior; introducing visibility does not
publish existing private content or hide existing public project trees.

An ordinary folder's files inherit its visibility. A nested folder with an
explicit Private setting remains private. An Unlisted subtree is excluded from
project listings, recursive discovery, search and public location tags. Opening
that folder by its ID opens its own inherited files. Private resources such as
Memos, Artifacts and infrastructure stacks retain their independent permissions.

A Bindr shares its grouping, not its Project or its members. Sharing an Unlisted
Bindr in a private Project does not publish the Project's files. Each resource
inside still needs its own read permission. Private and Unlisted Bindr names do
not appear in public trees, choices, search, affiliation tags or counts. A known
Unlisted Bindr can be opened directly; recursive browsing does not reveal hidden
child Bindrs. Signed-out visitors cannot read native run members.

## HTTP API

Ordinary folder visibility uses the Node ID:

- `GET /nodes/:id/visibility` returns `id`, effective `visibility`,
  `explicitVisibility` (null means inherited), and `updatedAt`.
- `PATCH /nodes/:id/visibility` accepts `visibility` and `expectedUpdatedAt`.
  The timestamp must match the current folder. A concurrent change returns 409.
- Existing Node detail and tree responses expose nullable `folderVisibility`.

Bindrs use their own IDs:

- `GET /bindrs/:id/summary` returns `{ bindr }`, including `updatedAt` and an
  optional explicit `visibility`.
- `PATCH /bindrs/:id` accepts `visibility` with `expectedUpdatedAt`. Existing
  metadata-only updates retain their current contract.
- `POST /namespaces/:slug/projects/:projectSlug/bindrs` accepts an optional
  `visibility`; setting it requires Project ADMIN.

Both writes are fenced against current Project ownership and permissions.
Use a fresh read before changing visibility. After a lost or invalid response,
read the object again and reconcile its state before deciding whether to retry.
Visibility changes preserve content, memberships and collaborator grants.

GraphQL exposes nullable `Node.folderVisibility` and `Bindr.visibility`.
Its trees, children, choices and affiliation reads enforce the same visibility.

## Agent tools

The local MCP adapter provides `folder_visibility_get`,
`folder_visibility_set`, `bindr_get`, and `bindr_visibility_set`. Pass the ID
and, for a write, `visibility` and the `expectedUpdatedAt` from the fresh read.
The adapter issues one write and reports an uncertain result for reconciliation.

The MCP adapter is source-only. These names describe the local adapter in the
repository; they do not imply a hosted endpoint or a published MCP package.

Built-in agents use `dreamlake_folder_visibility`,
`dreamlake_folder_visibility_set`, `dreamlake_bindr_visibility`, and
`dreamlake_bindr_visibility_set`. Each requires `projectId` and `id` and verifies
that the target belongs to that Project. Reads require an explicit service-account
READ grant; writes require ADMIN plus the human caller's current API permission.
The turn must grant `projects:read` or `projects:write`, respectively. A Project's
public visibility never substitutes for that service-account grant.

## CLI and SDKs

Use the folder's Node ID or the Bindr's ID. Reading visibility does not change
it; supplying a visibility makes one version-checked write.

```bash
dl folders visibility FOLDER_ID
dl folders visibility FOLDER_ID unlisted
dl bindrs visibility BINDR_ID
dl bindrs visibility BINDR_ID unlisted
```

The TypeScript client provides `client.nodes.visibility.get(id)` and
`client.nodes.visibility.set(id, visibility, expectedUpdatedAt)`, with the
corresponding Bindr methods under `client.bindrVisibility`. Pass the timestamp
from a fresh read to the setter.

The Python client provides `client.folders.get_visibility(id)` and
`client.folders.set_visibility(id, "unlisted", expected_updated_at=timestamp)`;
use `client.bindrs` for Bindrs. The required `expected_updated_at` pins the write
to a previously read version.
After an uncertain write, read again before deciding whether another change is
needed.
