--- a/README	Fri Sep 29 03:23:01 2017 +0000
+++ b/README	Sat Jul 28 17:37:41 2018 +0000
@@ -1,61 +1,62 @@
-You are looking at the source tree for FreeCalypso Citrine, which is one of the
-several Calypso GSM firmware offerings developed under the FreeCalypso umbrella.
-The key distinguishing features of FC Citrine are:
+You are looking at the source tree for FreeCalypso Citrine, which is the final
+state of our first attempt at gcc-built FreeCalypso modem firmware, the first
+attempt that started in late 2013 (then called simply FreeCalypso GSM fw) and
+was deemed a dead end in late 2016 (then named FC Citrine).
 
-* The firmware is built from full source, no blobs;
-* The compiler used to build the fw is gcc (free software) instead of TI's
-  proprietary compiler;
-* The way in which the firmware is put together is "from the bottom up".
+FC Citrine firmware project is now retired and will not receive any further
+development or support; it is now fully supplanted by the newer FreeCalypso
+Selenite firmware:
 
-Our Citrine firmware can be built for the following targets:
+https://bitbucket.org/falconian/fc-selenite
 
-  FreeCalypso FCDEV3B
-  Mot C11x/12x
-  Mot C139/140
-  Mot C155/156
-  Openmoko GTA01/02
-  Pirelli DP-L10
+FC Selenite offers the option of compiling either with TI's original TMS470
+compiler or with gcc; when built with gcc, FC Selenite does not contain any
+blobs and is no less free than FC Citrine.  However, the configuration and
+build system of FC Selenite has been derived from FC Magnetite, and is very
+different from FC Citrine.
 
-However, only minimal functionality is implemented so far: whichever target
-device you are using, it can only function as an AT-command-controlled voice+SMS
-pseudo-modem; because there is no UI code integrated yet, the LCD stays dark
-and the buttons do nothing on those target devices that have such hardware.
-No CSD, fax or GPRS support has been integrated yet either, and in general this
-Citrine firmware does NOT exhibit the level of functionality and stability
-offered by our production quality Magnetite fw.
-
-Please refer to the write-ups in the doc directory for instructions on how to
-compile and play with this firmware.
+FC Citrine does not contain any code for CSD, fax or GPRS support (only voice
+and SMS are supported), and it also omits the infrastructure for driving various
+Calypso DSP-based audio services, functionality that was considered mandatory
+and always included in TI's original TCS211 fw.  OTOH, FC Selenite retains the
+full architecture and functionality of TCS211, including CSD, fax, GPRS, audio
+services and L1 test modes, and CSD and audio functions already work in the
+gcc-built version, providing a functionality increase over Citrine.  (GPRS is
+currently broken in Selenite-gcc as of this writing.)
 
-Citrine vs. Magnetite
-=====================
-
-The following table lists the major differences between our two current
-FreeCalypso firmware offerings:
-
-Feature				Citrine			Magnetite
+FC Citrine has been unmaintained since 2016-10; there have been many new
+developments since then, including loudspeaker and MCSI digital voice interface
+control on our FCDEV3B platform and better support for the legacy Compal and
+Pirelli targets (more proper RF operation, battery charging and automatic
+power-off on host disconnection); these new developments are available in our
+newer Magnetite and Selenite firmwares, but not in Citrine.
 
-Support for Mot/Compal		All 3 subfamilies:	C139/140 only
-targets				C11x/12x, C139/140,
-				C155/156
+There are only a few features in Citrine which have not been replicated in our
+Magnetite or Selenite firmwares yet; these features *can* be replicated in FC
+Selenite, but there has been insufficient justification so far for expending
+the necessary effort:
 
-Source/blob status		Full source		Still has some blobs
-
-Compiler toolchain		gcc			TI's proprietary
+* FC Citrine supports the Motorola C155/156 target; FC Selenite currently
+  supports only C11x/12x and C139/140.  Mot C155/156 phones are not very common,
+  much less common than the other two subfamilies, and in any case the proper
+  way forward is our own FreeCalypso hardware, not hacking Mot C1xx phones of
+  any variant.
 
-GSM MS functionality		Voice and SMS only	Voice, SMS, CSD, fax
-							and GPRS
-
-Overall functionality		Experimental		Production
-and quality
+* FC Citrine supports an FFS-in-RAM hack; FC Selenite requires the FFS to be in
+  flash just like FC Magnetite and all of TI's original firmwares.  Citrine's
+  FFS-in-RAM hack is only useful on the C155/156 target (see the previous point)
+  and on the Pirelli DP-L10, thus it is ultimately deprecated when we see our
+  own FreeCalypso hw as the proper way forward.
 
-The current main focus in the FreeCalypso family of projects is on producing
-new Calypso-based GSM+GPRS modem products of full commercial quality and
-functionality, hence our primary firmware focus is currently on Magnetite.
-
-Citrine firmware is not currently receiving active new development, but it is
-maintained primarily for the purpose of winning users over from OsmocomBB: the
-limited GSM MS functionality (voice and SMS only) matches our competitor's
-offering, the blob-free status and the use of gcc are expected to be in line
-with the interests of that user population, and all 3 Mot C1xx subfamilies are
-supported.
+* FC Citrine supports a special hack for tapping voice TCH (traffic channel)
+  bits with FR and EFR speech codecs (but very notably not with AMR) - see the
+  doc/TCH-special-feature write-up.  This functionality has been implemented as
+  a paid-for feature for some folks who were working in some highly unusual
+  environment, but because the underlying DSP mechanism does not work with AMR,
+  its usefulness for the general public community is very dubious.  In the
+  Mother's opinion, it does not make sense to port this TCH hack to our newer
+  Magnetite and Selenite firmwares unless we also implement some way to force
+  the use of FR or EFR codecs on a per-call basis, or at least per GSM network
+  connection session, so that our mobile station fw would work in AMR mode
+  normally, but go into FR-only or FR&EFR-only restricted operation when the
+  user wishes to play with the TCH rerouting special feature.