--- a/README	Thu Jan 31 11:53:43 2013 +0100
+++ b/README	Thu Jan 31 10:56:26 2013 +0100
@@ -7,7 +7,7 @@
 1.  REQUIREMENTS
 2.  BUILDING THERMOSTAT
 2.1   BUILDING THERMOSTAT CORE
-2.2   BUILDING THERMOSTAT ECLIPSE
+2.2   BUILDING THERMOSTAT ECLIPSE (optional)
 3.  RUNNING THERMOSTAT
 3.1   RUNNING THERMOSTAT CORE
 3.1.1 PASSING JVM SPECIFIC OPTIONS
@@ -26,7 +26,7 @@
 
 * Maven (it will download all the java dependencies for you)
 
-* Make
+* Make + GCC
 
 * MongoDB server
 
@@ -34,7 +34,7 @@
 
 * Either a /etc/os-release file or lsb_release
 
-* Gnome Keyring Daemon development libraries, plus pkg-configs and gcc
+* Gnome Keyring Daemon development libraries plus pkg-configs
 
 Gnome Keyring development libraries are required at build time.
 
@@ -54,46 +54,51 @@
 --------------------------------------------------------------------------------
 2. BUILDING THERMOSTAT
 
-Thermostat consists of "Thermostat Core" and "Thermostat Eclipse".
+Thermostat consists of "Thermostat Core" and "Thermostat Eclipse". Building
+"Thermostat Eclipse" is optional. If you are a first-time Thermostat user, you
+might want to try try "Thermostat Core" first.
 
 Thermostat Core consists of:
   * CLI client
   * Swing GUI client
   * The thermostat agent
+  * The web service layer (plugged-in optionally)
 
-Thermostat Eclipse is an Eclipse-based Thermostat client.
+Thermostat Eclipse is an Eclipse-based Thermostat client. At this point the
+Eclipse-based client is experimental.
 
 --------------------------------------------------------------------------------
 2.1. BUILDING THERMOSTAT CORE
 
 2.1.1.
-   Run "make core". All tests should pass and the build should succeed.
-   Requires a graphical environment for the ui tests.
+   Run "mvn clean install". All tests should pass and the build should
+   succeed. It requires a graphical environment for the ui tests.
    
    You can skip the tests phase by running:
    
-   make core SKIP_TESTS=true
+   mvn -Dmaven.test.skip=true clean install
 
-   If maven is too chatty, you can try to pass the "-q" option via MAVEN_FLAGS::
+   If maven is too chatty, you can try to pass the "-q" option:
    
-   make core SKIP_TESTS=true MAVEN_FLAGS="-q"
+   mvn -q -Dmaven.test.skip=true clean install
    
 2.1.2.
    The resulting Thermostat system can now be found under the directory
    distribution/target.
            
 --------------------------------------------------------------------------------
-2.2. BUILDING THERMOSTAT ECLIPSE
+2.2. BUILDING THERMOSTAT ECLIPSE (optional)
 
 2.2.1.
-   Run "make eclipse". This will build both, Thermostat Core and Thermostat
-   Eclipse. All tests should pass and the build should succeed. Running Eclipse
-   plug-in tests will open an Eclipse instance during build. This requires a
-   working graphical environment and DISPLAY.
+   Run "make". This will build both, Thermostat Core and Thermostat Eclipse,
+   since Eclipse bits depend on Thermostat Core. All tests should pass and the
+   build should succeed. Running Eclipse plug-in tests will open an Eclipse
+   instance during build. This requires a working graphical environment and
+   DISPLAY.
 
    You can skip the tests phase by running:
 
-   make eclipse SKIP_TESTS=true
+   make SKIP_TESTS=true
 
 2.2.2.
    This produces a local "update-site" or p2 repository from which you can
@@ -110,16 +115,21 @@
   cd into distribution/target directory just created
 
   To start the agent and the db:
-  bin/thermostat service --start
+  bin/thermostat service
 
   To start the gui client:
   bin/thermostat gui
 
-  To start the cli client:
-  bin/thermostat [--help]
+  To start the thermostat shell:
+  bin/thermostat shell
+
+  Use the help command in order to find out about all available commands:
+  bin/thermostat help
+
+See also the user guide in the REFERECES section of this document.
 
 
-3.1.1. PASSING JVM SPECIFIC OPTIONS
+3.1.1. PASSING JVM SPECIFIC OPTIONS TO THERMOSTAT
 
 In some cases, it may be desirable to pass arguments to the virtual machine,
 for example to increase memory or change the look and feel for the Swing Client.
@@ -135,7 +145,7 @@
     -J-Dswing.defaultlaf=javax.swing.plaf.nimbus.NimbusLookAndFeel
 
 
-3.1.2. GNOME KEYRING
+3.1.2. GNOME KEYRING AND THERMOSTAT
 
 Thermostat includes experimental support to store user credentials in the
 Gnome Keyring daemon, this support is currently limited to passwords only.
@@ -157,6 +167,9 @@
 --------------------------------------------------------------------------------
 3.2. RUNNING THERMOSTAT ECLIPSE
 
+  Note that the Thermostat Eclipse client is an experimental feature at this
+  point.
+
   The "eclipse/composite-repo/target/composite-repo" directory was
   produced during step 2.2. In order to use this local repository
   follow these steps:
@@ -169,8 +182,11 @@
     Select "Thermostat Eclipse Plug-ins", then "Next >"
     Click through dialog, accepting options.
    
-  After this you should be able to see Thermostat views in Eclipse:
-    "Window" => "Show View" => "Other..." => "Thermostat" 
+  After this you should be able to open the Thermostat Eclipse perspective:
+    "Window" => "Open Perspective" => "Other..." => "Thermostat" 
+
+  Next, make sure you've got the thermostat service running (see above) and
+  click the "Connect" link/icon. Enjoy!
             
 
 --------------------------------------------------------------------------------