docs: update AI handoff notes for redesign work

AI.md

@@ -11,38 +11,188 @@ When the user says this is a new chat or asks to continue mars-nwe work, first
 read this file before proposing patches or making assumptions.  Then ask for, or
 use, the current project status that the user pasted into the chat.
 
-## Current handoff status after patch 0171
+## Current handoff status after patch 0197
 
-The current accepted patch line for the endpoint-documentation work is expected
-to be:
+The current accepted patch line in this chat is expected to include:
 
-- `0141-log-normalize-afp-get-file-info-mask-fields.patch` through
-  `0171-docs-document-ncp23-queue-core-layouts.patch`
+- endpoint-audit/documentation patches through `0176-docs-audit-direct-lifecycle-buffer-endpoints.patch`;
+- redesign documentation patches `0177` through `0197`;
+- latest confirmed patch name: `0197-docs-define-nwserv-control-plane-role.patch`.
 
-Do not apply or base work on these rejected/superseded patches:
+When continuing in a new chat, first ask the user which patch was actually last
+applied.  If they confirm `0197`, build the next patch as `0198-...` against a
+tree that already contains `0197`.  If any patch failed or was skipped, rebuild
+against the last confirmed applied patch instead of assuming the file in
+`/mnt/data` was accepted.
 
-- `0141-log-normalize-afp-file-information-bitmap-fields.patch`
-- `0144-docs-add-root-changes-summary.patch` if it is the German version; use
-  `0144-docs-add-root-changes-summary-en.patch` instead
-- `0152-docs-note-message-control-subfunction.patch` because it documented a
-  later NetWare 5.x/MOAB message-control subfunction outside the current
-  default compatibility target
-- `0160-docs-gate-netware4-directory-stubs.patch` because it wrapped or moved
-  already implemented endpoints; use
-  `0160-docs-bucket-endpoint-audit-by-netware-generation.patch` instead
-- `0161-docs-recheck-ncp22-websdk-endpoint-coverage.patch` because it mixed
-  SDK decimal notation with wire hex cases and placed comments at the wrong
-  spot; use `0161-docs-recheck-ncp22-websdk-coverage-corrected.patch` instead
+Known numbering/patch-history notes from this chat:
 
-Next likely endpoint block: continue `0x2222/23` Queue Management after the
-core queue/job calls documented in `0171`.  The next patch should inspect the
-remaining queue/job-control subfunctions in `nwbind.c` and any `nwconn.c`
-prehandlers, compare them against WebSDK/PDF/includes, and record only real
-layout differences in `TODO.md`.
+- `0190-docs-clarify-imported-nwlog-backend-layout.patch` was superseded because
+  patch number `0189` was accidentally skipped and the old `0190` failed after
+  `0188`.  Do not reuse that old file.
+- Use `0189-docs-clarify-imported-nwlog-backend-layout.patch` instead.
+- Then use `0190-docs-clarify-simple-syslog-nwlog-backends.patch`, followed by
+  `0191` ... `0197`.
 
-When handing off to a new chat, paste the latest patch name the user has
-actually applied.  If the user says a patch was not applied, rebuild the next
-patch against the last confirmed applied patch, not against the rejected file.
+The user prefers patch verification snippets to contain only:
+
+```sh
+git am patchname.patch
+```
+
+Do not include `git diff --check HEAD^..HEAD` in the final summary unless the
+user asks for it.
+
+## Current redesign decisions to preserve
+
+`REDESIGN.md` is now the place for broad architecture notes.  Do not keep
+growing `TODO.md` with long-term redesign material.  `TODO.md` should remain
+for concrete endpoint/test/fix follow-ups.
+
+High-level NCP architecture direction:
+
+- Add a small internal NCP dispatch/handoff layer over time; avoid a large
+  message-bus rewrite.
+- Provider boundary is not the same as process boundary.
+- `nwbind` remains legacy bindery provider/service.
+- Queue is a strong candidate for a future `nwqueue` provider/process, but first
+  split it logically from bindery.
+- Filesystem/volume/namespace should become a provider/module boundary first; a
+  separate process would be risky and later only.
+- Semaphore, server-management, and most small call families should remain
+  modules/providers, not separate processes.
+- `nwserv` is the control plane/supervisor/provider registry, not a data-plane
+  payload router.  Normal requests should flow `client -> nwconn -> provider ->
+  nwconn -> client`, not through `nwserv` as broker.
+- Provider processes must always return one formal internal handoff reply.
+  `NO_REPLY` is an explicit reply kind, not silence.  `nwconn` owns the final
+  client NCP reply envelope and send.
+
+Transport direction:
+
+- TCP/IP support is a transport split below `nwconn`/`nwserv`, not a new daemon.
+- Planned code layout: `src/nwtransport.c`, `src/nwipx.c`, `src/nwtcp.c`.
+- `nwtransport` is a code/library boundary, not a process.
+- Higher providers must not depend on raw `ipxAddr_t` long-term.
+- IPX SAP/RIP/watchdog/broadcast behavior remains isolated as IPX-specific.
+
+Secure IPC/TLS direction:
+
+- Client-facing NetWare 4.x/NCP/NDS compatibility must not require TLS by
+  default.  Keep historical clients compatible.
+- LDAP/LDAPS/StartTLS for `nwdirectory` uses wolfSSL at the external LDAP edge.
+- Internal provider IPC over TCP, if added later, must always use wolfSSL-backed
+  TLS with mutual authentication.  No plaintext fallback for TCP provider IPC.
+- Local IPC may remain Unix-domain sockets, pipes, socketpairs, or inherited FDs
+  with strict permissions; still avoid logging decoded secrets.
+- Add `nwtls` as the internal TLS facade if/when wolfSSL is wired into runtime:
+  `include/nwtls.h`, `src/nwtls.c`, `src/nwtls_wolfssl.c`.
+
+Directory/NetWare 4.x direction:
+
+- `libdirectory` is the shared internal C API/library used by `nwbind`, future
+  `nwnds`, `nwdirectory`, and `nwsetup`.  These components should not talk LDAP
+  internally just to reach the directory store.
+- `libflaim` is the planned persistent store under `libdirectory`.  FLAIM is C++;
+  keep its C++ API behind `libdirectory` so old mars-nwe C code does not include
+  FLAIM C++ headers directly.
+- `nwdirectory` is the mars-nwe integration name for the tinyldap-derived
+  LDAP/LDAPS service.  Standalone/upstream identity remains `tinyldap`; inside
+  mars-nwe it builds the `nwdirectory` service.
+- Future `nwnds` is the NetWare 4.x/NDS compatibility layer and should use
+  `libdirectory`, not LDAP protocol calls, as its internal backend path.
+- `nwbind` should eventually become a legacy bindery adapter over
+  `libdirectory`/`libflaim`, not maintain a second persistent truth.
+- Do not mention or design Kerberos for the current NetWare 4.x target.
+
+Configuration and setup direction:
+
+- Move toward a real typed, documented INI format.  Do not use JSON as the admin
+  config format.
+- The generated INI is also user documentation.  Writers must preserve comments
+  where possible or regenerate from a full documented template; never rewrite it
+  into an undocumented minimal key/value dump.
+- `nwsetup` is the provisioning/setup tool.  It should initialize the
+  `libdirectory`/`libflaim` store, create initial schema/tree/admin/server
+  objects, migrate bindery data later, and edit config atomically.
+- No reusable Admin/Supervisor/NDS/LDAP plaintext passwords in the new typed INI.
+  Initial passwords and recovery resets belong to explicit `nwsetup` commands
+  and only hashes/verifiers go into the store.
+- Legacy bindery config-password reset may remain only as deprecated compatibility
+  behavior; Directory/NDS mode uses `nwsetup` recovery commands.
+
+Logging direction:
+
+- Add a small internal `nwlog` facade instead of direct zlog/log.c calls in
+  handlers/providers.  Project layout: `include/nwlog.h`, `src/nwlog.c`.
+- Category wrappers should exist for normal code: `nwlog_ncp()`,
+  `nwlog_handoff()`, `nwlog_bindery()`, `nwlog_queue()`, `nwlog_directory()`,
+  `nwlog_nds()`, `nwlog_ldap()`, `nwlog_auth()`, `nwlog_acl()`,
+  `nwlog_recovery()`, `nwlog_security()`.  They populate an internal
+  `nwlog_event` and call `nwlog_emit()`.
+- `rxi/log.c` may be vendored/adapted as `nwlog_simple`, not exposed directly:
+  `include/nwlog_simple.h`, `src/nwlog_simple.c`.  It is a simple
+  stderr/stdout/file/callback basis and is a good default for systemd/journald.
+- `nwlog_syslog` may later be derived/cloned from the simple backend for classic
+  `syslog(3)` explicitly: `src/nwlog_syslog.c`.
+- `zlog` is the preferred optional advanced routing backend behind the facade:
+  `src/nwlog_zlog.c`.  It may live as a `third_party/zlog` submodule.
+- Never route raw decoded NCP/handoff/auth payloads to remote loggers.  Only
+  redacted structured events should leave the host.
+
+Third-party/fork policy:
+
+- Fixed third-party libraries live under `third_party/`, such as existing
+  `yyjson`, planned `wolfssl`, planned `libflaim`, and optional `zlog`.
+- `wolfSSL` is the fixed bundled TLS implementation, similar in spirit to
+  `yyjson`.  Do not design a first-pass OpenSSL/LibreSSL backend matrix.
+- `libflaim` should live under `third_party/libflaim` as a mars-nwe-maintained
+  import/fork/mirror.  Source may come from SourceForge/SVN and/or a distro
+  source package such as openSUSE `libflaim-4.9.1046`.  Document exact import,
+  revision/version, license files, distro patches, and local patches in
+  `third_party/libflaim/README.mars-nwe.md`.
+- FLAIM r1112 has Autotools (`configure.ac`, `Makefile.am`, libtool, `config.h`,
+  subprojects `ftk`, `flaim`, `sql`, `xflaim`).  Do not wrap Autotools from
+  CMake; replace it with a real CMake build.  First required targets are
+  `FLAIM::ftk` and `FLAIM::flaim`; SQL/XFLAIM/tools/tests/docs can come later.
+- FLAIM source license observed by the user: library sources LGPL-2.1; helper
+  files like `svn2cl.xsl` may have separate licenses such as BSD-3-Clause.
+  Keep these separated in import docs.
+- Forked/integrated mars components that become project services live in the
+  repository root, matching existing style such as `mail`, `admin`, and
+  `dosutils`.  `mars-tinyldap` belongs in the root, not `third_party`, because it
+  will be heavily adapted into `nwdirectory`.
+- tinyldap currently has a hand-written Makefile and flat-file/mmap storage.
+  It needs a real CMake build, not a Makefile wrapper.  Standalone remains
+  `tinyldap`; mars-nwe integration builds `nwdirectory`.
+- For tinyldap/nwdirectory, first CMake split can expose internal targets such as
+  `tinyldap::asn1`, `tinyldap::ldap`, `tinyldap::ldif`, `tinyldap::auth`,
+  `tinyldap::storage`, and `tinyldap::server`.  Replace flat-file storage with
+  `libdirectory -> libflaim` later.
+- Old tinyldap TLS code can remain reference/legacy/standalone-only; mars-nwe
+  `nwdirectory` TLS should go through `nwtls`/wolfSSL.
+
+Schema/import direction:
+
+- Do not invent NetWare 4.11 schema by hand if a real source can be obtained.
+  The user expects the complete schema to be hidden in NetWare 4.11 installation
+  material such as `install.dat`; a real 4.11 install may be needed to extract
+  it.
+- `.SCH` files such as uploaded `NLS.SCH` are useful format examples/fragments.
+  They contain readable ASN.1-like `ATTRIBUTE` and `OBJECT-CLASS` blocks, but
+  are not the full schema truth.
+- `nwsetup` should eventually support native NetWare 4.11 schema import, `.SCH`
+  fragment import, and LDIF import/export.  LDIF remains human-readable,
+  diffable, and testable, but the canonical runtime representation is
+  `libdirectory` schema objects stored in `libflaim`.
+- tinyldap has useful ASN.1 BER/DER and LDIF code (`scan_asn1*`, `fmt_asn1*`,
+  `asn1dump`, `ldif_parse.c`), but it does not appear to be an NDS `.SCH` or
+  NetWare schema importer.  Reuse ideas/code carefully through the
+  `nwdirectory` fork, but plan a dedicated schema import layer.
+- Samba `source4/dsdb/schema` and setup schema conversion code are useful
+  references for OID/prefixMap/schema-loading ideas, but Samba is GPL-family; do
+  not blindly copy code into mars-nwe.  Use as a reference and implement a
+  mars-nwe-native importer/OID module.
 
 ## Patch workflow