--- a/README	Fri Jun 14 18:48:58 2024 +0000
+++ b/README	Fri Jun 14 19:42:25 2024 +0000
@@ -1,16 +1,26 @@
-This code repository contains some utilities for encoding SMS in low-level test
-workflows:
+The present suite consists of utilities for encoding and decoding SMS message
+bodies and PDUs.  On the decoding side, it includes sms-pdu-decode and
+pcm-sms-decode utilities that were previously maintained as part of FreeCalypso
+host tools: they now extend beyond FreeCalypso GSM MS into SIM card exploration
+(fc-simtool) and network-side SMSC prototyping applications.  On the encoding
+side, there are two new programs described in doc/Generator-tool-summary and
+doc/Generator-tool-workflow articles.
 
-* sms-encode-text performs the same encoding from user text input (ASCII, ISO
-  Latin-1 or UTF-8) into SMS as performed by fcup-smsend, including support for
-  concatenated SMS and the choice between GSM7 and UCS-2.  However, the process
-  stops after GSM7 or UCS-2 encoding and (in the case of concatenated SMS) UDH
-  generation - the subsequent steps of SMS-SUBMIT PDU encoding and transmission
-  via GSM 07.05 are eliminated in this version.  The output is expected to be
-  fed to either sms-gen-tpdu or more specialized network-side test programs,
-  including those written for SMPP.
+Similarly to gsm-codec-lib, the present sms-coding-utils package stands between
+FreeCalypso and Themyscira Wireless software realms: it has potential
+applications on both the mobile side and the network side of GSM.  It is
+expected to be used together with any or all of the following software
+components:
 
-* sms-gen-tpdu takes the output of sms-encode-test, along with some additional
-  inputs, and generates either a pure GSM 03.40 SMS-DELIVER or SMS-SUBMIT TPDU
-  (for network-side testing) or the same TPDU preceded by an SC address, as used
-  on the mobile side in GSM 07.05 PDU mode and in EF_SMS SIM storage.
+* FreeCalypso host tools;
+* FreeCalypso SIM tools;
+* ThemWi proto-SMSC implementation used to exercise SMS-over-GSUP functionality
+  in Osmocom CNI suite.
+
+However, even though the present sms-coding-utils suite is designed to be useful
+with all of the above FC and ThemWi components, it does not depend on any of
+them.  The present package can be compiled and installed by itself (see INSTALL
+document); all run-time interactions between these utilities and other software
+happen through ASCII text files or pipes, or through binary files in externally
+defined record format (GSM 11.11 spec and its successors) in the case of
+pcm-sms-decode.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Generator-tool-summary	Fri Jun 14 19:42:25 2024 +0000
@@ -0,0 +1,16 @@
+This code repository contains some utilities for encoding SMS in low-level test
+workflows:
+
+* sms-encode-text performs the same encoding from user text input (ASCII, ISO
+  Latin-1 or UTF-8) into SMS as performed by fcup-smsend, including support for
+  concatenated SMS and the choice between GSM7 and UCS-2.  However, the process
+  stops after GSM7 or UCS-2 encoding and (in the case of concatenated SMS) UDH
+  generation - the subsequent steps of SMS-SUBMIT PDU encoding and transmission
+  via GSM 07.05 are eliminated in this version.  The output is expected to be
+  fed to either sms-gen-tpdu or more specialized network-side test programs,
+  including those written for SMPP.
+
+* sms-gen-tpdu takes the output of sms-encode-test, along with some additional
+  inputs, and generates either a pure GSM 03.40 SMS-DELIVER or SMS-SUBMIT TPDU
+  (for network-side testing) or the same TPDU preceded by an SC address, as used
+  on the mobile side in GSM 07.05 PDU mode and in EF_SMS SIM storage.