docs: the Dashboard and the Roles page for the in-app guide

2026-08-24 21:53:46 +01:00
parent 9feaaaff29
commit 07f4082d3b
4 changed files with 112 additions and 1 deletions
@@ -10,6 +10,12 @@ release PR may merge — and a section is closed at the commit that bumps it.
 ### Added
 - The assistant can now explain the **Dashboard** and the admin's **Roles** page: ask it
  why the status line says *Degraded*, whose usage the charts show (everyone's, together
  — counts never content), what a role bundles — the simple interface, the default
  assistant, the security groups, the new-extensions switch — or why a role edit takes
  effect on open sessions immediately, and it answers from the in-app documentation
  instead of guessing.
 - The **Long-term memory** page (Honcho plugin) now shows, once you have opted in, what
  Honcho actually remembers about you: a service-status line (connected/unreachable with
  the specific error, and your memory's processing queue), a full overview (your card,
@@ -0,0 +1,58 @@
 # The Dashboard (the home overview)
 Sidebar → **Dashboard**, just below Chat: the overview page. One glance answers three questions — *is the assistant usable right now, is anything waiting for me, how much has it been used?* It is visible to everyone in the full interface; members with the simple interface ([roles.md](roles.md)) go straight to chat and never see it.
 ## The status line
 Under the title, one line summarising the configured LLM models:
 - **Online & ready** — at least one model answered its last check. Nothing to do.
 - **Degraded** — no model is fully healthy, but at least one is still partly answering. Expect slower answers and fallbacks to whatever works.
 - **All models offline** — no model answered. Chats will fail until it recovers or an admin looks at the provider.
 - **No LLM models** — the instance has no model configured at all. The banner below the hero says the same thing more loudly and points the admin at the Providers page.
 The status reflects the **whole instance**, not one person's account: there is one set of models, shared by everyone.
 ## LLM usage stats
 Four charts with a range switch (last hour / 24 hours / 7 days / 30 days):
 - **Requests** — how many LLM calls per minute, hour or day.
 - **Tokens** — the metered volume, split into input (split again into cached and non-cached) and output. The tooltip shows the cache-hit percentage: repeated context that was *cached* costs less and answers faster, so a high hit rate is good news, not a sign something is stuck.
 - **Avg latency** — how long a model call took on average.
 - **Models** — the top models by requests in the range.
 Three honest answers to give with a straight face:
 - **These numbers are everyone's, together.** The charts aggregate the whole instance; there is no per-person breakdown on this page.
 - **They record how much, when and which model — never what was said.** The content of a request lives in the requester's own encrypted space; the charts read only counters.
 - **Empty is normal on a new instance.** "No LLM requests in the selected range" means exactly that: nothing has run in that window.
 ## Pending
 The same cards as the [Inbox](inbox.md) — approvals, questions and sign-in prompts from background work — with a live count. It updates on its own while the page is open; answering here is the same as answering in the Inbox. An unanswered card means a stopped job, so this section is worth a look before "why hasn't it finished?".
 ## The tip and the quick guide
 - A suggestion box appears when a long-term-memory plugin is available but not running — it is a nudge for the admin, not an error.
 - The **Quick guide** at the bottom is seven cards pointing at the rest of the app (chat, inbox, agents, scheduled tasks, models, providers, security rules). It is a map for someone new, not a status of what is enabled.
 ## What this page is not
 - **Not a monitor.** Nothing here alerts anyone; it shows the present state to whoever is looking.
 - **Not where models are configured.** Adding providers and models, and their priority order, is the admin's Models and Providers pages.
 - **Not per-person.** No page on the instance shows "who used how much" — deliberately; usage is shared, like the models.
 ## Common questions
 - *"It says Degraded — should I worry?"* — it means the model checks are not all passing. Individual chats may still work on a fallback model; if it persists, the admin checks the provider (its key, its quota) on the Models/Providers pages.
 - *"Why are the bars so high at odd hours?"* — scheduled background work (system agents, cron tasks) uses the same models. The Tasks page and the system-agents page show what ran when.
 - *"What is a token?"* — the unit LLM providers meter and bill by, roughly a word fragment. Input is what was sent (long history = more input; caching repeats cheaply), output is what was written back.
 - *"Why doesn't my child see this page?"* — their role uses the simple interface: chat, inbox and projects only.
 - *"Does the dashboard show what people asked?"* — no. Only counts, timings and model names; never content.
 ## Related
 - [inbox.md](inbox.md) — the three kinds of pending request, and answering them
 - [agents.md](agents.md) and [tasks-page.md](tasks-page.md) — what may be running in the background
 - [roles.md](roles.md) — the simple interface, and who sees which pages
@@ -4,7 +4,7 @@ This folder is written for **you, the assistant**, not for the human directly. I
 Keep answers grounded in what's actually enabled and configured for this instance — check with the relevant tool (e.g. list installed/enabled plugins) rather than assuming everything described here is turned on. A feature documented here may not be enabled on this particular instance.
-This index will grow over time. Right now it covers the chat window, the inbox, the interface, view context, files, the file viewer, agents, memory, projects, shared folders, background tasks, the Tasks page, system agents, access grants, profiles and user administration, security groups, connectors, skills, the sandbox, voice input and plugins; more sections (the mobile app, the Roles page, models and providers…) will be added later.
+This index will grow over time. Right now it covers the chat window, the inbox, the interface, view context, files, the file viewer, agents, memory, projects, shared folders, background tasks, the Tasks page, system agents, access grants, profiles and user administration, security groups, connectors, skills, the sandbox, voice input, the dashboard, roles and plugins; more sections (the mobile app, models and providers…) will be added later.
 ## Features
@@ -12,6 +12,7 @@ This index will grow over time. Right now it covers the chat window, the inbox,
 | --- | --- |
 | [chat.md](chat.md) | The chat window: full-page vs docked, the tab bar and what lands where, the composer's controls, the slash commands, and what happens while an answer is being written |
 | [inbox.md](inbox.md) | The Inbox: the three kinds of pending request, why background work asks here rather than in the chat, answering one (and the time-limited approvals), and why an unanswered card means a stopped job |
 | [dashboard.md](dashboard.md) | The Dashboard: the instance status line, the LLM usage charts (everyone's together, counts never content), the pending-inbox section, and what the no-models banner means |
 | [security-groups.md](security-groups.md) | Security groups: allow / ask / deny per tool, the shield in the chat, what the default group already permits, and how an admin edits the rules |
 | [memory.md](memory.md) | Private and shared memory: what goes where, the indexes and history log, why some shared facts can't be changed on request |
 | [agents.md](agents.md) | Agents: the three kinds (chat, task, system), which one you are talking to and why, the specialist agents the assistant delegates to, how the model is chosen, and adding a custom agent |
@@ -26,6 +27,7 @@ This index will grow over time. Right now it covers the chat window, the inbox,
 | [access.md](access.md) | Who can use which plugin or connector: the open default, removing access per person, and the role switch that keeps children out of it |
 | [profile.md](profile.md) | A member's own Profile page: display name, language, password — and what an "encrypted account" means for them |
 | [users.md](users.md) | The admin's Users page: creating a member and the encryption choice, the directory profile the agents are told about, deactivating vs deleting, per-person event triage |
 | [roles.md](roles.md) | The admin's Roles page: what a role bundles (security groups, interface, default assistant, the auto-grant switch), what edits immediately, and why Administrator is locked |
 | [connectors.md](connectors.md) | Connectors (MCP servers): shared vs per-user, setting one up in the UI, the sign-in and QR-pairing flows, and what to do when one is not working |
 | [sandbox.md](sandbox.md) | Your sandbox: the private Linux container commands run in, which files survive a rebuild, why the command list in your prompt is partial, and installing what is missing |
 | [skills.md](skills.md) | Skills: instruction folders the assistant loads on demand — where they live, how to read and run one, and the contract for writing, installing and downloading one |
@@ -0,0 +1,45 @@
 # The Roles page (admin)
 Sidebar → **Roles**, admin only. A **role** is a bundle of settings that every member assigned to it picks up together: which security group their assistant runs under, which interface they see, which agent answers them, and whether new extensions reach them automatically. Picking a role for a person happens on [users.md](users.md); what that role *means* is edited here.
 The list ships with three roles (on the standard profile): **Administrator**, **Member** and **Children**. Roles are data, not built-in categories — "Children" is a preset row the admin can edit like any other, and a role for guests or staff is just a fourth row. Administrator is the one exception: it is built-in, locked, and neither editable nor deletable (admins hold every permission implicitly, so there is nothing meaningful to configure).
 ## The role editor
 Creating a role asks for an **ID** (a lowercase slug, permanent — it cannot be changed later) and a **Label**. Everything else is the same in create and edit:
 - **Default security group** — the group the role's conversations run under when the member has not chosen otherwise. What a group permits is edited on the Security page, not here: [security-groups.md](security-groups.md).
 - **Additional security groups** — extra groups the member *may* switch to in chat, via the shield pill. Leave it empty and there is no pill and nothing to choose: for most members one group is the whole point. The switch happens inside the conversation, and the server refuses any group the role does not list — whatever the interface shows.
 - **Interface** — **Full** (all pages) or **Simple** (chat, inbox and projects only, with the assistant's internal reasoning hidden from the message list). Simple mode is a *simpler menu*, not a fence: every page remains protected server-side, and a simple-mode member can still own and share projects like anyone else.
 - **Default assistant** — which chat agent the role's members talk to. Empty means the standard Assistant. The change lands on **new** conversations, picked up at the member's next login; an existing conversation keeps the agent it started with. (Project chats are unaffected: they always get the project's own coordinator.)
 - **New plugins and connectors** — whether anything the admin installs reaches this role automatically. This is the one setting with a page of its own, because it interacts with per-person grants: see [access.md](access.md). Existing access is never changed by this switch, in either direction.
 - **Attrs (JSON, optional)** — the raw store the fields above read from and write to. Editing it by hand is for attributes the form does not surface yet; normally you never touch it.
 Two things happen the moment a role is saved, worth knowing before an admin edits one mid-afternoon:
 - **Narrowing takes effect immediately, including on open sessions.** Removing a group from a role's allowed list pushes members who are logged in and sitting on that group back to a group they may use — the wider permission cannot be outrun by staying logged in.
 - **Nothing is re-granted or re-taken.** The auto-grant switch only decides what happens *next time* something is installed or someone is added; per-person grants stand exactly as they are.
 Deleting a role is refused while anyone is still assigned to it — the admin moves those members to another role first, from each person's page. Creating a role is always safe: a brand-new role starts with the standard self-service connector permissions (registering remote MCP servers and activating vetted catalog scripts), and nothing else.
 ## What this page is not
 - **Not the people.** Assigning a role to a person, or changing it, is done from their page on [users.md](users.md) — and applies immediately, open sessions included.
 - **Not the security rules.** What *allow / require / deny* means for a tool is edited per group on the Security page ([security-groups.md](security-groups.md)); here a group is only picked from a list.
 - **Not a personality dial.** The interface mode changes which pages a member sees, and the default assistant changes *who answers* — neither changes how the assistant behaves within a conversation. That is the agent's prompt ([agents.md](agents.md)).
 ## Common questions
 - *"Make the assistant simpler for my kid."* — Two different asks, one page: a **simple interface** (fewer pages, no reasoning blocks) and a **different default assistant** (a gentler agent). The Children preset sets both; a custom agent can be added too, see [agents.md](agents.md).
 - *"Why can't I edit Administrator?"* — it is built-in and locked. Admins hold everything implicitly; there is nothing to configure.
 - *"It won't let me delete the role."* — someone is still on it. Move them to another role from their own page, then delete.
 - *"I moved my child to Member — why don't they have the plugins everyone else has?"* — a role change never hands out or takes back what was already granted. The admin ticks the boxes once on that person's page: [access.md](access.md).
 - *"Can I show just one extra page in simple mode?"* — no; simple mode is chat, inbox and projects, as a set. Anything more is the full interface.
 - *"Does changing the role log them out?"* — no. It applies to their open sessions immediately; nothing needs to restart.
 ## Related
 - [users.md](users.md) — assigning a role to a person, and everything else on their page
 - [security-groups.md](security-groups.md) — what a security group permits, and the shield in the chat
 - [access.md](access.md) — the auto-grant switch in full: the open default, and why Children opts out
 - [agents.md](agents.md) — chat agents, custom agents, and how the default assistant is chosen