docs: document config password recovery redesign

REDESIGN.md

@@ -986,6 +986,61 @@ Examples of setup-owned work:
 the local bootstrap path should avoid requiring a running LDAP server and should
 not make LDAP the canonical internal representation.
 
+### Admin, Supervisor, and directory password bootstrap/recovery
+
+The future typed INI must not carry reusable plaintext passwords for Admin,
+Supervisor, LDAP, NDS, Bindery, or provider IPC credentials.  The old legacy
+pattern of placing a cleartext Supervisor password in the config and restarting
+the server so the password is reset should be treated as a compatibility behavior
+for old Bindery-only setups, not as the NetWare 4.x/directory design.
+
+Initial password creation belongs to `nwsetup`:
+
+```text
+first setup:
+  nwsetup asks interactively for the initial Admin/Supervisor password
+  nwsetup calls libdirectory authentication primitives
+  libdirectory stores only password verifiers/hashes in the libflaim-backed store
+  nw.ini records object names, tree/context, and paths, but not the password
+```
+
+Planned password changes should also be explicit setup/admin operations, for
+example conceptually:
+
+```text
+nwsetup passwd supervisor
+nwsetup directory set-password cn=admin,o=mars
+```
+
+Those commands can authenticate using the current password, local root/admin
+rights, or a documented recovery mode.  They should update the directory store
+directly through `libdirectory`, not by writing a plaintext key into the INI and
+waiting for a daemon restart.
+
+Emergency recovery must be possible, but it should be one-shot and local.  The
+safe design is an explicit recovery command or recovery token/file, with strict
+permissions and exclusive store access:
+
+```text
+nwsetup recovery reset-admin-password
+  requires local root or the configured mars-nwe admin user
+  requires the server to be stopped or the store to be exclusively locked
+  updates password verifier/hash through libdirectory
+  logs the recovery event without logging the new secret
+  consumes or removes any one-shot recovery token/file
+```
+
+If a recovery file mechanism is added, it should live outside the main admin INI,
+be root-owned, mode `0600`, and be deleted or renamed after successful use.  The
+main INI may point to a recovery directory or policy, but it should not contain a
+standing plaintext reset password.
+
+Legacy compatibility can remain explicit and deprecated, for example as a
+Bindery-only option whose comments warn that it is not used by directory/NDS
+mode.  Migration tools should warn when they find old cleartext reset settings
+and should convert them into an interactive `nwsetup` password operation rather
+than copying the secret into the new documented INI.
+
 Kerberos should not be part of this initial design.  Classic NetWare 4.x/NDS
 compatibility should focus on native NDS-style authentication and directory
 semantics.  If a later eDirectory/NMAS compatibility effort ever needs Kerberos,
@@ -1118,11 +1173,31 @@ The migration path should be:
 
 The parser/writer choice should be made with write support in mind.  A read-only
 INI library is enough for daemons, but not enough for `nwsetup` or a future web
-configuration editor.  The writer should be schema-driven and should write a
-canonical file atomically rather than trying to preserve every arbitrary comment
-in-place.  Comments and examples can come from the schema/template, similar in
-spirit to the current `nw.ini.hook.cmake`, but with named keys instead of numeric
-records.
+configuration editor.  The writer should be schema-driven and should write
+atomically, but the generated INI is also administrator documentation.  It must
+not be rewritten into an undocumented minimal key/value dump.
+
+The shipped default file should be a documented INI, not only a machine config.
+Comments should explain the section purpose, defaults, safe values, compatibility
+notes, and examples.  `nwsetup` should therefore prefer one of these strategies:
+
+```text
+comment-preserving edit:
+  read existing file as text
+  replace only known key value lines
+  preserve surrounding comments, unknown keys, and unknown sections
+  insert missing keys near their documented section when possible
+
+or template regeneration:
+  regenerate from a full documented template/schema
+  include the explanatory comments again
+  preserve local overrides through the typed NwConfig model
+```
+
+Do not choose a writer that discards all comments unless `nwsetup` regenerates
+from a complete documented template.  Losing the documentation comments would be
+a regression because the INI is expected to be the primary admin-facing reference
+for normal deployments.
 
 Practical library guidance: