Claude Fable 5
eeb0ef6794
All checks were successful
CD / Build and push images (push) Successful in 1m9s
CD / Deploy to Test (push) Successful in 10s
CD / Smoke tests against Test (push) Successful in 1m10s
CD / Promote to Int (push) Successful in 11s
CI / Lint, typecheck, test (push) Successful in 4m7s
CI / Build container images (push) Has been skipped
CI / Auth e2e pack (push) Successful in 5m34s
CI / Import/export fidelity gate (push) Successful in 47s
Seven audience-targeted documents (English first, German translation to follow), linked from the README and a new docs/manual/ index: - docs/features.md — public-facing feature overview: what Dorfteich can do and why that matters - docs/manual/user-guide.md — everyday use: editor, wikilinks, labels, search, comments, watches/digests, import/export, settings - docs/manual/pond-admin-guide.md — pond configuration: members/roles, access rules incl. label scoping and public pages, labels, comment policy, plugins, API/MCP opt-ins, files, export - docs/manual/site-admin-guide.md — instance administration: wizard, settings, quotas, uploads, API/MCP switches, legal pages, plugins, users, and the system panel (jobs/backups/audit/storage) - docs/manual/api-guide.md — example-driven public-API walkthrough (tokens, reading, writing through the collab-safe path, labels, comments, error semantics) - docs/manual/mcp-guide.md — connecting AI assistants: switches, token scopes, Claude Code one-liner, mcp-remote bridge, tool table, audit and safety properties - docs/developer/extending.md — plugin development (sandbox contract, SDK, block plugins, bundled apps/fullscreen, shipping) and core contributions (stack, dev environment, gates, house rules) README: documentation index, repository-layout rows for docs/manual and docs/developer, and the stale "architecture phase" status brought up to reality. All relative links verified. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# 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 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**: shared ponds can be moved to the site-level trash by
|
||
their admin via the API (`DELETE /api/v1/ponds/<id>` — there is no UI
|
||
button yet); a site admin can restore them. Your personal pond cannot
|
||
be deleted — it is your account's home.
|