Claude Fable 5
2d51a55119
All checks were successful
CD / Build and push images (push) Successful in 2m40s
CD / Deploy to Test (push) Successful in 10s
CD / Smoke tests against Test (push) Successful in 1m9s
CI / Lint, typecheck, test (push) Successful in 4m23s
CI / Build container images (push) Has been skipped
CD / Promote to Int (push) Successful in 12s
CI / Auth e2e pack (push) Successful in 6m15s
CI / Import/export fidelity gate (push) Successful in 47s
Release / Build release images and notes (push) Successful in 1m7s
Release / Release-candidate operations QA (push) Successful in 41s
Prod deploy / Deploy the released images to Prod (push) Successful in 16s
CI runs the two new packs after the graph pack (chained, each preceded by the login rate-limit reset): create-missing-page.spec.ts (#115) and import-vault.spec.ts (#117/#118). Docs: the pond-admin guide gains a full 'Import an Obsidian vault' chapter — the three dialog choices, and what happens to folders, links (including the duplicate-name rule: the alphabetically first vault path wins), tags, images, and embeds, plus the limits and the all-or-nothing semantics. The user guide explains following a link to a page that does not exist yet. features.md gets both bullets. German mirrors updated throughout (English stays authoritative). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
149 lines
6.5 KiB
Markdown
149 lines
6.5 KiB
Markdown
# 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 ``) 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.
|