Claude Fable 5
627f128ab8
Some checks failed
CD / Build and push images (push) Successful in 3m54s
CD / Deploy to Test (push) Successful in 11s
CI / Lint, typecheck, test (push) Successful in 4m8s
CI / Build container images (push) Has been skipped
CD / Smoke tests against Test (push) Failing after 11s
CD / Promote to Int (push) Has been skipped
CI / Auth e2e pack (push) Successful in 5m40s
CI / Import/export fidelity gate (push) Successful in 54s
The pond switcher grows a "+ New pond" entry with an inline form (name + optional description, quota errors surfaced translated); the pond settings of shared ponds end in a danger section that moves the pond to the site-level trash after typing its name to confirm. Personal ponds keep hiding the section. .button--danger is now a solid red button (also fixes the admin restore button, which showed red text on the accent-green background). Manuals no longer call these actions API-only; covered by a members-pack e2e test. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
106 lines
4.3 KiB
Markdown
106 lines
4.3 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 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.
|