dorfteich/docs/manual/pond-admin-guide.md

Pond-admin guide

What you can configure on a pond you administer. You are a pond admin on your own personal pond and on every pond where you hold the pond_admin role. All of this lives behind the gear icon in the top bar (visible on pond routes when you may modify the pond).

Ponds in one minute

Every member gets a personal pond automatically. Additional shared ponds are created via "+ New pond" at the bottom of the pond switcher in the top bar (or through the API, POST /api/v1/ponds) and are subject to the per-user quota the site admin sets ("additional shared ponds per user", default 0). The creator becomes the pond admin.

Name, description, appearance

• Name and description of the pond.
• Fonts: pick heading/body/code typefaces per pond from the built-in, self-hosted catalog (browse it at /fonts) — they apply to the app view, public pages, and PDF exports.
• Sidebar sort for everyone: A–Z, creation date, or manual order.

Members and roles

The members section manages who is in the pond:

Role	May
reader	read pages (as far as rules allow)
editor	read + write pages, upload files
pond_admin	everything, including settings, members, labels

Member counts are limited by the instance quotas (editors/readers per pond). Personal ponds take members too — that is how you share yours.

Access rules (the fine print)

Beyond plain membership, the access rules section edits grants directly. A grant is: subject (a user, all signed-in users, or the public) + role (reader/editor/pond admin) + scope (whole pond, one label, or one page) + effect (allow or deny).

• Label-scoped rules are the power tool: give the "board" label to the confidential pages and allow only the board members' grant on that label — or deny a label to someone who may otherwise read everything.
• Public pages: an allow, reader, public grant on a page (or a label) publishes it read-only at /public/<pond>/<page>.
• Deny beats allow; reads that are denied look like "not found" (the system never reveals what exists).
• The permission inspector on a page explains the effective result for any user — use it whenever a rule combination surprises you.

Labels

Manage the pond's label tree (create, rename, recolor, nest, move, delete). Deleting a label that is still on pages asks for confirmation. Labels also appear in the page label picker, where creating new ones is reserved for you.

Comments policy

Choose whether all readers may comment or editors only. Existing comments stay readable either way.

Watching the pond

The bell in the pond settings header watches the whole pond — you will be notified about every page change and comment in it.

Plugins

Plugins the site admin has installed with mode optional appear here with a per-pond toggle. Required plugins are always active; disabled ones never show up. (Which plugins exist and what they do: site-admin guide.)

Machine access: API and MCP opt-in

Two separate switches expose this pond to token-based access — both off by default, and both only effective if the site admin has enabled the matching instance switch:

• Public REST API (apiEnabled): scripts and integrations may reach the pond with personal access tokens — with exactly the permissions of the token's owner.
• MCP / AI assistants (mcpEnabled): MCP clients such as Claude Code may reach the pond the same way.

A pond that has not opted in is invisible through those interfaces, even to its own members' tokens.

Files

The file manager lists the pond's uploads with their usage (which page references them) and lets you delete orphans. Storage counts against the pond's quota; the current usage is shown.

Export and deletion

• Export: the whole pond as a ZIP of Markdown files plus media.
• Delete pond: the danger section at the bottom of the pond settings moves a shared pond to the site-level trash (type the pond name to confirm); a site admin can restore it. Your personal pond cannot be deleted — it is your account's home.