# 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](site-admin-guide.md#plugins).)

## 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.