--- a/doc/Number-database	Sun Nov 26 18:14:19 2023 -0800
+++ b/doc/Number-database	Sun Nov 26 19:13:52 2023 -0800
@@ -63,7 +63,7 @@
 When abbreviations are enabled, each suffix line not only creates an entry in
 the owned-NANP portion of the local number database, but also adds an entry to
 the list of defined 4-digit short dialing numbers, mapping to the corresponding
-full number.
+full number - see Local-short-numbers article.
 
 2) If you have individual 10-digit NANP numbers that don't form a neat group
    under a single NPA-NXX prefix, you can enter them using this alternative
@@ -174,3 +174,29 @@
 sms	This flag indicates that the number in question is provisioned for
 	outside SMS connectivity, meaning that it is possible to send SMS to
 	the outside world with this number as source or "from".
+
+Local short number entries
+==========================
+
+In addition to entries that list locally owned NANP numbers, there are other
+types of entry in the master number database source file that list ITNs
+(internal test numbers) and test sinks.  These entries are described in
+Local-short-numbers article.
+
+Compiled binary format and updates
+==================================
+
+The human-edited ASCII source form of the just-described number database,
+located in /var/gsm/number-db2 master file, is read only by themwi-update-numdb2
+utility and no other programs.  This utility reads the ASCII source form of the
+number database, parses it with some basic validation, and compiles it into a
+binary format that is designed for fast lookups and read by long-running ThemWi
+processes.  The compiled binary form of the number database resides in
+/var/gsm/number-db2.bin, and the latter file is always updated via an atomic
+rename mechanism: themwi-update-numdb2 first writes out a temporary file named
+number-db2.newbin, then renames it to number-db2.bin, making the new version
+live.
+
+Long-running ThemWi server processes perform stat(2) checks on this file as part
+of call setup or SMS admission processing, and if they notice that the binary
+database file has changed, they read the new version.