diff --git a/doc/ui.txt b/doc/ui.txt
new file mode 100644
index 0000000000..9d7348dbbb
--- /dev/null
+++ b/doc/ui.txt
@@ -0,0 +1,277 @@
+User setup experience
+---------------------
+
+This document describes the user experience in
+setting up BOINC for the first time on a computer,
+and for attaching to a project from a running client.
+
+This document does NOT describe how things are implemented.
+I've used function notation only because there is some overlap
+between the various cases.
+
+
+A) Project-specific installer case
+--------------------------------
+
+- Get installer for project (PROJ_URL)
+	either by downloading from site or by project-specific CD-ROM
+
+- Run installer
+
+- Manager starts up, opens window
+
+- If there is not already an account for PROJ_URL
+	call attach_to_project(PROJECT_URL, false)
+
+--------------------
+
+B) Generic installer case
+
+1) user gets generic installer from boinc.berkeley.edu
+	or on CD-ROM
+
+2) run installer
+
+3) manager starts up, opens window
+
+4) if there are no accounts
+	call get_url_and_attach()
+
+----------------------
+
+C) "Attach to new project" case
+
+1) call get_url_and_attach()
+
+=======================================================
+
+function get_url_and_attach()
+
+1) Dialog:
+
+Enter the URL of a BOINC-based project: _____________ (text field)
+
+For more information, and to see a list
+of some BOINC-based projects, go to
+http://boinc.berkeley.edu [link]
+
+OK [button]
+Cancel [button]
+
+2) if OK:
+call attach_to_project(PROJ_URL, true)
+
+-------------------------
+
+function attach_to_project(PROJ_URL, bool user_supplied_url)
+
+1) Dialog:
+
+	Do you already have an account on PROJ_URL?
+
+	No [button]
+	Yes [button]  paste account key here: ______________________ [text field]
+				  How to find an existing account key [button]
+
+Dialog (how to find an existing account key):
+
+	Each account on PROJ_URL has an "account key".
+	An account key is a string of 32 random characters.  For example:
+		xxxx
+	There are two ways to find an account key:
+	1) On the computer where you created the account,
+		- run the BOINC Manager,
+		- select this project in the Projects tab,
+		- click on the Account Key button.
+	2) If you entered an email address for the account,
+		the account key was sent to you in an email message
+		(you can request another email by going to the
+		My Account page on foo.edu and clicking Email Account Key).
+
+	Copying an account key by hand is prone to errors.
+	We recommend that you transfer the account key in a file or email message
+	to the computer where it is needed,
+	and then copy and paste it into the BOINC Manager.
+
+	OK [button]
+
+If answer to 1) is "no":
+
+2) BOINC client tries to communicates with project, create account
+
+3) if succeed in creating account
+Dialog:
+
+	Welcome to PROJ_NAME
+	Your web browser should now show a
+	form for entering your name and email.
+	If you don't see this form, check your browser settings,
+	visit PROJ_URL [link] and click on My Account.
+
+	OK [button]
+
+Web page (foo.edu/welcome.php?auth=xxxxx)
+
+	Welcome to PROJ_NAME.
+
+	Your new account has a name and optional email address.
+	You can changes these if you like:
+	Name: xxx
+	(this wil be shown on our web site)
+	Email address:
+	(this will not be displayed or distributed)
+	OK to send periodic email newsletters [checkbox]
+	Update [button]
+
+	Foo@home will use processing time and disk space on your computer,
+	and will periodically make Internet connections.
+	You can control a number of 'settings' that limit these activities.
+	The default settings are OK for most people.
+	To view or modify your settings, click here [link]
+
+	You can also keep track of your computers and work totals,
+	find answers to common problems,
+	exchange messages with other users,
+	and create a "profile" of yourself
+	(including a picture, if you like)
+	that other participants can see.
+	To access these features,
+	go to the Foo@home home page [link]
+
+
+	(update button goes to a "account info updated" page)
+
+(User is done)
+
+
+4) if project replies with an error message:
+
+Dialog:
+
+	PROJ_NAME is temporarily unavailable.
+	Please check PROJ_URL [link] for information.
+	To try again later, select the "Projects" tab,
+	and click on "Attach to new project".
+
+	OK [button]
+
+Go to Projects tab.
+user is done.
+
+5) If no connection failure or no reply
+	call network_failure()
+	Go to 6)
+
+
+If answer to 4) is "yes":
+
+10) if account key is syntactically invalid
+
+Dialog:
+
+	The account key xxx is invalid.
+	Account keys are 32 characters, each of which is a-f or 0-9.
+	Please reenter the key.
+
+	OK [button]
+
+11) If project is up, and account key is verified
+
+Dialog:
+	Account key is valid.
+	This computer is now participating in Foo@home.
+
+	OK [button]
+
+User is done.
+
+12) If project is up, and account key is not verified
+Dialog:
+	xxx is not the key of any existing account on Foo@home.
+	Account keys from other BOINC projects will not work on Foo@home.
+	Please check your account key.
+
+	OK [button]
+
+Go to 4
+
+13) if project replies with an error message:
+
+Dialog:
+
+	Foo@home is temporarily unavailable.
+	Please check http://foo.edu [link] for information.
+	To try again later, select the "Projects" tab,
+	and click on "Attach to new project".
+
+	OK [button]
+
+Go to Projects tab.
+user is done.
+
+14) else (if no reply): call network_failure()
+
+----------------
+
+function network_failure(bool user_supplied_url):
+
+(called when an operation to a project failed to connect
+or got no reply.
+Returns true if we should retry the operation.)
+
+Dialog:
+
+	BOINC is unable to contact PROJ_URL
+	Possible reasons are:
+
+	1) You may need to tell BOINC your proxy settings.
+	We are opening a web page with instructions for how to do this.
+
+	Change proxy settings now [button]
+
+	2) You may be running network security software that is
+	blocking BOINC's network access.
+	Unblock BOINC and click Retry.
+
+	3) There may be a network problem
+	or the PROJ_URL servers may be down.
+	(In either case your web browser will show
+	an error for the proxy instruction page).
+	To try again later, select the "Projects" tab,
+	and click on "Attach to new project".
+
+if User_supplied_url is true, add
+
+	3) You may have entered the project URL incorrectly.
+
+	Retry [button]
+	Cancel [button]
+
+If chose "change proxy settings"
+	put up Options dialog
+
+If chose Retry
+	return true
+
+If chose Cancel
+	return false
+
+Web page (PROJ_URL/proxy_problems.php)
+
+	Some computers access the Internet via "proxies".
+	In this case BOINC must be told the names and types
+	of these proxies in order to work correctly.
+
+	Since you are able to see this page,
+	your web browser already has the right proxy settings.
+	You can find these settings as follows:
+	Mozilla/FireFox:
+		Select "Preferences" in the Edit menu.
+		Then select Advanced/Proxies
+	Internet Explorer:
+		Select "Internet Options" in the Tools menu.
+		Select the "Connections" tab.
+		Click "LAN Settings".
+
+	You can change BOINC's proxy setting by selecting
+	the Options item in the Tools menu.
diff --git a/doc/ui_impl.txt b/doc/ui_impl.txt
new file mode 100644
index 0000000000..d622b011a4
--- /dev/null
+++ b/doc/ui_impl.txt
@@ -0,0 +1,6 @@
+Implementation notes
+
+What do we know at the start?
+If they downloaded the installer then they have network connectivity
+and working proxy setup for their browser.
+If via CD-ROM, nothing is known.