Make the docs state things rather than argue them
Docs / docs (push) Successful in 37s
Playwright Tests / test-playwright (1, 2) (push) Failing after 1m35s
Playwright Tests / test-playwright (2, 2) (push) Failing after 17s
pre-commit / pre-commit (push) Failing after 2m8s
Test Backend / test-backend (push) Failing after 2m48s
Compose Smoke Test / test-compose (push) Failing after 13s
Playwright Tests / merge-reports (push) Failing after 2m25s

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`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015YrQnKV3bnQd4K342y8tKj
This commit is contained in:
2026-08-31 10:49:58 +02:00
co-authored by Claude Opus 5
parent 2422a9b22b
commit bdad6d7fc2
25 changed files with 450 additions and 479 deletions
+9 -10
View File
@@ -13,13 +13,13 @@ The **portal** is optional, and it exists to solve two specific problems:
An enrolled instance dials *out* to the portal and holds one websocket
open. The portal serves the dashboard from its own side, and only the API calls
travel down the tunnel so the interface loads at portal speed and your
travel down the tunnel, so the interface loads at portal speed and your
machine stays unreachable from the internet.
## Enrolling
Two halves, deliberately: whoever performs the second step decides what the
instance's owner gets.
Two halves: whoever performs the second step decides what the instance's owner
gets.
**On the portal** (`hub.${DOMAIN}`, or [fluksio.com](https://fluksio.com) for
the hosted one): **Instances → Add instance**, give it a name, and copy
@@ -39,10 +39,9 @@ fluksio enroll ABCD-1234 --portal https://hub.fluksio.com
The code is single-use and expires in fifteen minutes.
A portal session then arrives as *that local account* the settings screen
states this plainly, because it is the whole security model in one sentence.
Use `--as someone@example.com` to enrol as a specific local account when the
instance has several superusers.
A portal session then arrives as *that local account*, which the settings screen
states plainly. Use `--as someone@example.com` to enrol as a specific local
account when the instance has several superusers.
Once enrolled, the instance appears under **Instances** with its
status, when it was last seen and its version. **Open** takes you to its
@@ -55,7 +54,7 @@ the tunnel. What those requests may do is decided **on the instance**, by
the same checks a local session passes.
The trust anchor is a signing keypair on the portal. Every instance pins
its public half at enrolment and rejects anything else which is what stops a
its public half at enrolment and rejects anything else, which is what stops a
hijacked DNS entry or a mis-issued certificate from impersonating the portal.
## Letting someone else in
@@ -72,7 +71,7 @@ admits them, and they arrive as a local user of their own rather than as you.
you.
The instance redeems that code against the portal using its own credential.
A portal session cannot do this which is what stops somebody you let in from
A portal session cannot do this, which is what stops somebody you let in from
letting others in.
On the instance they appear under **Admin → Users**, badged *Portal*, never
@@ -95,7 +94,7 @@ unsure: it does not need the portal's cooperation.
## Running your own portal
The portal is the `index` stack's `hub` service accounts, the registry of
The portal is the `index` stack's `hub` service: accounts, the registry of
connected instances, and the websocket each one dials in on. Two things
about it are load-bearing: