Say it once, and say it plainly

The docs stacked four ideas into a sentence, explained the shell's internals to
an app author, and pointed at another screen the author never sees. Both pages
now use short sentences with a named actor, the contract carries the detail,
and the guide carries only what an author does about it.

Author: czpython

backend/druks/ui/fields.py

@@ -101,10 +101,8 @@ class UploadField(Schema):
 
 
 class SecretField(Schema):
-    """A secret the operator hands over — a token, a key. It carries no
-    ``value``, the way ``UploadField`` carries none: a file input cannot be
-    seeded, and a secret must not be, so an app can never echo a stored secret
-    back to the browser by declaring one."""
+    """One secret the operator hands over: a token, a key. It has no ``value``,
+    so a page cannot send a stored secret back to the browser."""
 
     field: Literal["secret"] = "secret"
     name: str

docs/druks-ui.md

@@ -1432,21 +1432,20 @@ ui.SecretField(name="token", label="Access token", help_text="From your account
 {"field": "secret", "name": "token", "label": "Access token", "helpText": "From your account settings.", "isRequired": false}
 ```
 
-One secret the operator hands over — a token, a key — and, like `UploadField`,
-no starting `value`: a file input cannot be seeded, and a secret must not be, so
-an app can never echo a stored secret back to the browser by declaring one.
-
-The shell renders it as a masked `type="password"` input that the browser's
-password managers leave alone, the same input the settings modal uses for a
-bearer token. On a successful submit the form's reset returns the field to empty,
-so nothing has to clear it.
-
-Masking protects the screen, not the stored secret. When a route rejects the
-submitted value, its 422 message can carry the secret back — Pydantic embeds the
-submitted input in many of its messages. So the shell shows a fixed line on a
-secret field, and a fixed form-level line for any refusal that names no field on
-screen, whenever the form holds a secret. Every other field still shows the
-server's own words.
+One secret the operator hands over: a token, a key.
+
+It has no `value`. A file input cannot be seeded, and a secret must not be. A
+field with nowhere to put one cannot send a stored secret back to the browser.
+
+The shell masks it and keeps it from the browser's password managers. A
+successful submit leaves it empty.
+
+Masking protects the screen. It does not protect the stored secret.
+
+A refusal never repeats the server's words on a secret field. The shell shows a
+fixed line, because a validation message can carry the submitted value back. It
+shows a fixed line on the form too, for a refusal that names no field on screen.
+Every other field keeps the server's own words.
 
 ## Page and Follows
 

docs/writing-an-app.md

@@ -1321,18 +1321,15 @@ A form that needs a token takes a `ui.SecretField`:
 ui.SecretField(name="token", label="Access token", help_text="From your account settings.")
 ```
 
-It renders masked, is kept from the browser's password managers, carries no
-starting value, and clears itself on a successful submit. When a route rejects
-the value, the shell shows a fixed line rather than the server's — a validation
-message can echo the submitted token back — and does the same for any refusal
-that names no field on screen while the form holds a secret.
-
-That masking protects the screen, not the stored secret. Your operation receives
-the plaintext token and stays responsible for keeping it safe. For one secret per
-record — a credential per connected account — store it in an
-`EncryptedJsonField` column or a `SecretsMapping`, never a plain string. A token
-the whole app shares belongs in `AppSettings` with a `Secret` field instead,
-where the platform masks, encrypts, and never reads it back — not in a form.
+Druks masks it, keeps it from the browser's password managers, and leaves it
+empty after a successful submit. A refusal shows a fixed line, never the
+server's words, because a validation message can carry the token back.
+
+The masking protects the screen. Your operation receives the token in plain
+text and owns it from there. Keep one secret per record in an
+`EncryptedJsonField` column or a `SecretsMapping`. A token the whole app shares
+belongs in `AppSettings` as a `Secret`, where Druks encrypts it and never reads
+it back.
 
 Two routes of one app cannot share an `operation_id`. An action that names an
 operation the app does not declare, a GET route, or a route with a query

frontend/src/druksui/Fields.tsx

@@ -216,8 +216,8 @@ function Input({
         <input
           {...shared}
           className="dui-input"
-          // The same masked, password-manager-ignored input the settings modal
-          // uses for the MCP bearer token.
+          // The set the settings modal uses for its bearer token. Keep them
+          // together.
           type="password"
           autoComplete="new-password"
           data-1p-ignore=""

frontend/src/druksui/Form.tsx

@@ -325,9 +325,8 @@ function problems(
       continue
     }
     if (hasSecret) {
-      // No field on screen owns this — a model-level validator, or a route
-      // parameter named otherwise. Either could have seen the secret, so keep
-      // its words off the screen.
+      // No field on screen owns this one. Whatever raised it saw the whole
+      // body, so keep its words off the screen.
       redactForm = true
       continue
     }