# Pond-admin guide

_Deutsche Fassung: [docs/de/manual/pond-admin-guide.md](../de/manual/pond-admin-guide.md)_

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.
- **Sidebar view** default: the page tree ("folders") or pages grouped
  under the label tree. Members can still switch their own sidebar
  locally — the setting only picks the starting point.

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

## Import an Obsidian vault

Pond settings → **Import an Obsidian vault** takes a ZIP of a whole vault
and turns it into pages. You choose three things:

- **Mount under** — the page the vault hangs below (or the top level).
- **Additional labels** — assigned to every imported page, on top of the
  labels made from the vault's tags.
- **YAML frontmatter** — removed, or kept as a code block at the top of
  the page.

What happens to the vault:

- **Folders become pages.** Each folder turns into a container page and
  the notes hang below it, mirroring the vault. Pages nest six levels
  deep at most; if the vault (plus the mount depth) is deeper, the
  deepest folder levels are merged into one page titled `like/this`.
- **`[[Wikilinks]]` keep working.** Obsidian links point at note _names_,
  Dorfteich links at page _addresses_, so every link is rewritten to the
  address the note actually got — including `[[Note|shown text]]`,
  `[[Note#Heading]]` (the heading part is dropped), and
  `[[folder/Note]]`. Links to notes that are not in the vault become
  missing-page links, exactly as if you had typed them. When two notes in
  different folders share a name, a plain `[[Name]]` resolves to the one
  whose vault path comes first alphabetically.
- **Tags become labels.** Both `tags:` in the frontmatter and `#tags` in
  the text (which are removed from the text). Nested tags like
  `#status/active` become a label hierarchy.
- **Images and files come along.** Images referenced by a note
  (`![[image.png]]` or `![](media/image.png)`) become pond files shown in
  the page; other allowed file types become attachments. They count
  against the pond's storage quota. `![[Another note]]` embeds become
  plain links (Dorfteich does not transclude pages).

Limits: the ZIP may be up to 64 MiB, and 256 MiB unpacked. **An import is
all-or-nothing** — if anything fails (a full pond, a broken archive),
nothing is left behind and you can simply try again.

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