diff --git a/MANIFEST.in b/MANIFEST.in
index 2c65a02..fab5a4d 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,3 @@
-include ChangeLog LICENSE test.py demo.py demo_simple.py demo_server.py demo_dss_key demo_rsa_key forward.py
+include ChangeLog LICENSE test.py demo.py demo_simple.py demo_server.py demo_windows.py forward.py
 recursive-include docs *
-recursive-include tests *.py
+recursive-include tests *.py *.key
diff --git a/README b/README
index 95f107c..c303965 100644
--- a/README
+++ b/README
@@ -76,40 +76,58 @@ Valeriy Pogrebitskiy says the best place to look is
 
 ***  DEMO
 
-the demo client (demo.py) is a raw implementation of the normal 'ssh' CLI tool.
-while the paramiko library should work on all platforms, the demo app will only
-run on posix, because it uses select.
+several demo scripts come with paramiko to demonstrate how to use it.  probably
+the simplest demo of all is this:
 
-you can run demo.py with no arguments, or you can give a hostname (or
-username@hostname) on the command line.  if you don't, it'll prompt you for
-a hostname and username.  if you have an ".ssh/" folder, it will try to read
-the host keys from there, though it's easily confused.  you can choose to
-authenticate with a password, or with an RSA or DSS key.
+    import paramiko, base64
+    key = paramiko.RSAKey(data=base64.decodestring('AAA...'))
+    t = paramiko.Transport('ssh.example.com')
+    t.connect(username='strongbad', password='thecheat', hostkey=key)
+    chan = t.open_session()
+    chan.exec_command('ls')
+    for line in chan.makefile('r+'):
+        print '... ' + line.strip('\n')
+    chan.close()
+    t.close()
 
-the demo app leaves a logfile called "demo.log" so you can see what paramiko
-logs as it works.  but the most interesting part is probably the code itself,
-which hopefully demonstrates how you can use the paramiko library.
+...which prints out the results of executing 'ls' on a remote server.  (the
+host key 'AAA...' should of course be replaced by the actual base64 encoding
+of the host key.  if you skip host key verification, the connection is not
+secure!)
 
-a simpler example is in demo_simple.py, which is a copy of the demo client
-that uses the simpler "connect" method call (new with 0.9-doduo).
+the following example scripts get progressively more detailed:
 
-a demo for windows is in demo_windows.py.  it executes 'ls' on the remote
-server and prints the results, avoiding terminal i/o and select() (which
-are missing in windows).
+demo_windows.py
+    executes 'ls' on any remote server, loading the host key from your openssh
+    key file.  (this script works on windows because it avoids using terminal
+    i/o or the 'select' module.)  it also creates a logfile 'demo_windows.log'.
 
-there's also now a demo server (demo_server.py) which listens on port 2200
-and accepts a login (robey/foo) and pretends to be a BBS, just to demonstrate
-how to perform the server side of things.
+demo_simple.py
+    calls invoke_shell() and emulates a terminal/tty through which you can
+    execute commands interactively on a remote server.  think of it as a poor
+    man's ssh command-line client.  (works only on posix [unix or macosx].)
+
+demo.py
+    same as demo_simple.py, but allows you to authenticiate using a private
+    key, and uses the long form of some of the API calls.  (posix only.)
+
+forward.py
+    command-line script to set up port-forwarding across an ssh transport.
+    (requires python 2.3 and posix.)
+
+demo_server.py
+    an ssh server that listens on port 2200 and accepts a login for 'robey'
+    (password 'foo'), and pretends to be a BBS.  meant to be a very simple
+    demo of writing an ssh server.  (should work on all platforms.)
 
 
 ***  USE
 
-the demo clients (demo.py, demo_simple.py, and demo_windows.py) and the demo
-server (demo_server.py) are probably the best example of how to use this
-package.  there is also a lot of documentation, generated with epydoc, in the
-doc/ folder.  point your browser there.  seriously, do it.  mad props to
-epydoc, which actually motivated me to write more documentation than i ever
-would have before.
+the demo scripts are probably the best example of how to use this package.
+there is also a lot of documentation, generated with epydoc, in the doc/
+folder.  point your browser there.  seriously, do it.  mad props to epydoc,
+which actually motivated me to write more documentation than i ever would have
+before.
 
 there are also unit tests here:
     $ python ./test.py
diff --git a/demo_server.py b/demo_server.py
index 2f08f59..84d2f5b 100755
--- a/demo_server.py
+++ b/demo_server.py
@@ -6,11 +6,8 @@ import paramiko
 # setup logging
 paramiko.util.log_to_file('demo_server.log')
 
-#host_key = paramiko.RSAKey()
-#host_key.read_private_key_file('demo_rsa_key')
-
-host_key = paramiko.DSSKey()
-host_key.read_private_key_file('demo_dss_key')
+#host_key = paramiko.RSAKey(filename='tests/test_rsa.key')
+host_key = paramiko.DSSKey(filename='tests/test_dss.key')
 
 print 'Read key: ' + paramiko.util.hexify(host_key.get_fingerprint())
 
diff --git a/demo_simple.py b/demo_simple.py
index d31b063..e11ebf1 100755
--- a/demo_simple.py
+++ b/demo_simple.py
@@ -32,7 +32,7 @@ def load_host_keys():
 
 
 # setup logging
-paramiko.util.log_to_file('demo.log')
+paramiko.util.log_to_file('demo_simple.log')
 
 # get hostname
 username = ''
diff --git a/demo_windows.py b/demo_windows.py
index a31a642..5d87090 100644
--- a/demo_windows.py
+++ b/demo_windows.py
@@ -38,7 +38,7 @@ def load_host_keys():
 
 
 # setup logging
-paramiko.util.log_to_file('demo.log')
+paramiko.util.log_to_file('demo_windows.log')
 
 # get hostname
 username = ''
@@ -81,16 +81,15 @@ try:
     t = paramiko.Transport((hostname, port))
     t.connect(username=username, password=password, hostkey=hostkey)
     chan = t.open_session()
-    chan.get_pty()
     print '*** Here we go!'
     print
 
     print '>>> ls'
-    chan.exec_command('ps auxww')
+    chan.exec_command('ls')
     f = chan.makefile('r+')
     for line in f:
         print line.strip('\n')
-        
+
     chan.close()
     t.close()