DreamLake

Folder and Bindr visibility

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

SettingVisitors with the direct linkPublic discovery
PrivateCannot openHidden
UnlistedCan openHidden
PublicCan openListed 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.