diff --git a/basis/furnace/auth/basic/basic-docs.factor b/basis/furnace/auth/basic/basic-docs.factor
index 25929d4346..c0d3184c78 100644
--- a/basis/furnace/auth/basic/basic-docs.factor
+++ b/basis/furnace/auth/basic/basic-docs.factor
@@ -3,10 +3,14 @@ IN: furnace.auth.basic
 
 HELP: <basic-auth-realm>
 { $values { "responder" "a responder" } { "name" "an authentication realm name" } { "realm" basic-auth-realm } }
-{ $description "Wraps a responder in a basic authentication realm." } ;
+{ $description "Wraps a responder in a basic authentication realm. The realm must be configured before use; see " { $link "furnace.auth.realm-config" } "." } ;
+
+HELP: basic-auth-realm
+{ $class-description "The basic authentication realm class. Slots are described in " { $link "furnace.auth.realm-config" } "." } ;
 
 ARTICLE: "furnace.auth.basic" "Basic authentication"
 "The " { $vocab-link "furnace.auth.basic" } " vocabulary implements HTTP basic authentication."
+{ $subsection basic-auth-realm }
 { $subsection <basic-auth-realm> } ;
 
 ABOUT: "furnace.auth.basic"
diff --git a/basis/furnace/auth/login/login-docs.factor b/basis/furnace/auth/login/login-docs.factor
new file mode 100644
index 0000000000..e461388e73
--- /dev/null
+++ b/basis/furnace/auth/login/login-docs.factor
@@ -0,0 +1,25 @@
+! Copyright (C) 2008 Your name.
+! See http://factorcode.org/license.txt for BSD license.
+USING: help.markup help.syntax kernel strings ;
+IN: furnace.auth.login
+
+HELP: <login-realm>
+{ $values
+     { "responder" "a responder" } { "name" string }
+     { "realm" "a new responder" }
+}
+{ $description "Wraps a responder in a new login realm with the given name. The realm must be configured before use; see " { $link "furnace.auth.realm-config" } "." } ;
+
+HELP: login-realm
+{ $class-description "The login realm class. Slots are described in " { $link "furnace.auth.realm-config" } "." } ;
+
+ARTICLE: "furnace.auth.login" "Login authentication"
+"The " { $vocab-link "furnace.auth.login" } " vocabulary implements an authentication realm which displays a login page with a username and password field."
+{ $subsection login-realm }
+{ $subsection <login-realm> }
+"The " { $snippet "logout" } " action logs the user out of the realm, and a link to this action can be inserted in Chloe templates using the following XML snippet:"
+{ $code
+    "<t:button t:action=\"$login-realm/logout\">Logout</t:button>"
+} ;
+
+ABOUT: "furnace.auth.login"
diff --git a/basis/furnace/auth/login/login.factor b/basis/furnace/auth/login/login.factor
index 2c98672490..4fc4e7e8be 100644
--- a/basis/furnace/auth/login/login.factor
+++ b/basis/furnace/auth/login/login.factor
@@ -58,9 +58,13 @@ M: login-realm modify-form ( responder -- )
     permit-id get [ delete-permit ] when*
     URL" $realm" end-aside ;
 
+<PRIVATE
+
 SYMBOL: description
 SYMBOL: capabilities
 
+PRIVATE>
+
 : flashed-variables { description capabilities } ;
 
 : login-failed ( -- * )
@@ -107,7 +111,7 @@ M: login-realm login-required* ( description capabilities login -- response )
 M: login-realm user-registered ( user realm -- )
     drop successful-login ;
 
-: <login-realm> ( responder name -- auth )
+: <login-realm> ( responder name -- realm )
     login-realm new-realm
         <login-action> "login" add-responder
         <logout-action> "logout" add-responder