Make the docs state things rather than argue them

The site read as a design journal: rationale paragraphs, hedges
("deliberately", "on purpose", "genuinely"), meta-commentary about the docs
themselves, and one em-dash every ten lines carrying an aside.

Roughly twenty rationale blocks are gone or reduced to what a reader needs
in order to use the thing. Em-dashes go from 507 to 135, and what is left is
structural rather than prose: list and definition separators, table cells,
and four inside code blocks that quote what the CLI actually prints.

Also: api.example.com becomes api.fluksio.com (the emails stay, since
bootstrap.py really defaults to admin@example.com and RFC 2606 reserves it);
the mqtt table gains the two settings it had drifted behind on and inject's
wording matches the engine; llms.txt lists the two connector pages that were
in the nav but not in it; and the two device/device_policy notes now agree.

Builds clean under `zensical build --strict`.
This commit is contained in:
2026-08-31 10:49:58 +02:00
parent 82c853e690
commit 3b541d6dbc
25 changed files with 450 additions and 479 deletions
+6 -6
View File
@@ -23,8 +23,8 @@ They are encrypted at rest with a key derived from the instance's
flows are a git repository you may well push somewhere: what gets committed and
shared never contains a password.
A name that no longer resolves is a clear error on the node that wanted it —
"No secret named 'x' — add it under Secrets" — rather than a mysterious
A name that no longer resolves is a clear error on the node that wanted it
("No secret named 'x'; add it under Secrets") rather than a mysterious
authentication failure.
!!! warning "Rotating `SECRET_KEY`"
@@ -36,7 +36,7 @@ authentication failure.
## Modules
Node code runs in a virtual environment of its own, on the instance's data
volume — separate from the packages Fluksio itself runs on. A pin of yours can
volume, separate from the packages Fluksio itself runs on. A pin of yours can
never shadow one of ours, and vice versa.
**Modules** is a pip manifest and an **Apply** button. It is installed with
@@ -49,7 +49,7 @@ and whether the manifest and the environment agree. A failed resolve comes back
as `uv`'s own output, in the pane, because that is the only thing anyone can
act on.
An install takes effect immediately — the worker processes pick up the new
An install takes effect immediately: the worker processes pick up the new
interpreter state without the engine restarting.
!!! note "Big scientific stacks"
@@ -79,7 +79,7 @@ literal, so a webhook URL with a token in it does not sit in the config.
### Rules
A rule is a set of events and the channels they go to. **A rule with no events
ticked covers all of them**, including ones added in later versions — which is
ticked covers all of them**, including ones added in later versions, which is
usually what you want for the first rule you write.
| Event | Fires when |
@@ -113,7 +113,7 @@ Superusers get an **Admin** screen: add, edit and remove accounts, and see who
is a superuser.
Accounts that arrived through a portal are badged *Portal*. They have no
password — they sign in at the portal, not here — and they are never
password (they sign in at the portal, not here) and they are never
superusers. Deleting one cuts their access immediately and independently of the
portal, so it works even if the portal cannot be reached. See
[Accounts and the portal](portal.md).