diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 13351540a..9bcaa19c6 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -1,116 +1,130 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:catalog, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Compile, save, view, and convert catalogs."
   description <<-'EOT'
-    This face primarily interacts with the compiling subsystem. By default,
-    it compiles a catalog using the default manifest and the hostname from
-    `certname`, but you can choose to retrieve a catalog from the server by
-    specifying '--terminus rest'.  You can also choose to print any catalog
-    in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
-    with '--render-as dot'.
+    This subcommand deals with catalogs, which are compiled per-node artifacts
+    generated from a set of Puppet manifests. By default, it interacts with the
+    compiling subsystem and compiles a catalog using the default manifest and
+    `certname`, but you can change the source of the catalog with the
+    `--terminus` option. You can also choose to print any catalog in 'dot'
+    format (for easy graph viewing with OmniGraffle or Graphviz) with
+    '--render-as dot'.
+  EOT
+  short_description <<-'EOT'
+    This subcommand deals with catalogs, which are compiled per-node artifacts
+    generated from a set of Puppet manifests. By default, it interacts with the
+    compiling subsystem and compiles a catalog using the default manifest and
+    `certname`; use the `--terminus` option to change the source of the catalog.
   EOT
 
-  get_action(:destroy).summary "Invalid for this face."
-  get_action(:search).summary "Query format unknown; potentially invalid for this face."
+  get_action(:destroy).summary "Invalid for this subcommand."
+  get_action(:search).summary "Invalid for this subcommand."
+  find = get_action(:find)
+  find.summary "Retrieve the catalog for a node."
+  find.arguments "<certname>"
+  find.returns <<-'EOT'
+    A serialized catalog. When used from the Ruby API, returns a
+    Puppet::Resource::Catalog object.
+  EOT
 
   action(:apply) do
-    summary "Apply a Puppet::Resource::Catalog object."
+    summary "Find and apply a catalog."
     description <<-'EOT'
       Finds and applies a catalog. This action takes no arguments, but
-      the source of the catalog can be managed with the --terminus option.
+      the source of the catalog can be managed with the `--terminus` option.
     EOT
     returns <<-'EOT'
-      A Puppet::Transaction::Report object.
+      Nothing. When used from the Ruby API, returns a Puppet::Transaction::Report
+      object.
     EOT
     examples <<-'EOT'
       Apply the locally cached catalog:
 
       $ puppet catalog apply --terminus yaml
 
       Retrieve a catalog from the master and apply it, in one step:
 
       $ puppet catalog apply --terminus rest
 
       From `secret_agent.rb` (API example):
 
           # ...
           Puppet::Face[:catalog, '0.0.1'].download
           # (Termini are singletons; catalog.download has a side effect of
           # setting the catalog terminus to yaml)
           report  = Puppet::Face[:catalog, '0.0.1'].apply
           # ...
     EOT
 
     when_invoked do |options|
       catalog = Puppet::Face[:catalog, "0.0.1"].find(Puppet[:certname]) or raise "Could not find catalog for #{Puppet[:certname]}"
       catalog = catalog.to_ral
 
       report = Puppet::Transaction::Report.new("apply")
       report.configuration_version = catalog.version
 
       Puppet::Util::Log.newdestination(report)
 
       begin
         benchmark(:notice, "Finished catalog run") do
           catalog.apply(:report => report)
         end
       rescue => detail
         puts detail.backtrace if Puppet[:trace]
         Puppet.err "Failed to apply catalog: #{detail}"
       end
 
       report.finalize_report
       report
     end
   end
 
   action(:download) do
     summary "Download this node's catalog from the puppet master server."
     description <<-'EOT'
-      Retrieves a catalog from the puppet master and saves it to the
-      local yaml cache. The saved catalog can be used in subsequent
-      catalog actions by specifying '--terminus rest'.
-
-      This action always contacts the puppet master and will ignore
+      Retrieves a catalog from the puppet master and saves it to the local yaml
+      cache. This action always contacts the puppet master and will ignore
       alternate termini.
+
+      The saved catalog can be used in any subsequent catalog action by specifying
+      '--terminus yaml' for that action.
     EOT
     returns "Nothing."
     notes <<-'EOT'
-      As termini are singletons, this action has a side effect of
-      exporting Puppet::Resource::Catalog.indirection.terminus_class =
-      yaml to the calling context when used with the Ruby Faces API. The
+      When used from the Ruby API, this action has a side effect of leaving
+      Puppet::Resource::Catalog.indirection.terminus_class set to yaml. The
       terminus must be explicitly re-set for subsequent catalog actions.
     EOT
     examples <<-'EOT'
       Retrieve and store a catalog:
 
       $ puppet catalog download
 
       From `secret_agent.rb` (API example):
 
           Puppet::Face[:plugin, '0.0.1'].download
           Puppet::Face[:facts, '0.0.1'].upload
           Puppet::Face[:catalog, '0.0.1'].download
           # ...
     EOT
     when_invoked do |options|
       Puppet::Resource::Catalog.indirection.terminus_class = :rest
       Puppet::Resource::Catalog.indirection.cache_class = nil
       catalog = nil
       retrieval_duration = thinmark do
         catalog = Puppet::Face[:catalog, '0.0.1'].find(Puppet[:certname])
       end
       catalog.retrieval_duration = retrieval_duration
       catalog.write_class_file
 
       Puppet::Resource::Catalog.indirection.terminus_class = :yaml
       Puppet::Face[:catalog, "0.0.1"].save(catalog)
       Puppet.notice "Saved catalog for #{Puppet[:certname]} to yaml"
       nil
     end
   end
 end
diff --git a/lib/puppet/face/catalog/select.rb b/lib/puppet/face/catalog/select.rb
index d86963e75..de2ca803b 100644
--- a/lib/puppet/face/catalog/select.rb
+++ b/lib/puppet/face/catalog/select.rb
@@ -1,49 +1,49 @@
 # Select and show a list of resources of a given type.
 Puppet::Face.define(:catalog, '0.0.1') do
   action :select do
-    summary "Select and show a list of resources of a given type"
+    summary "Retrieve a catalog and filter it for resources of a given type."
     arguments "<host> <resource_type>"
     returns <<-'EOT'
-      An array of resource objects excised from a catalog. When used at
-      the command line, returns a list of resource references (Type[title]).
+      A list of resource references ("Type[title]"). When used from the API,
+      returns an array of Puppet::Resource objects excised from a catalog.
     EOT
     description <<-'EOT'
-      Retrieves a catalog for the specified host and returns an array of
-      resources of the given type.
+      Retrieves a catalog for the specified host, then searches it for all
+      resources of the requested type.
     EOT
     notes <<-'NOTES'
       By default, this action will retrieve a catalog from Puppet's compiler
       subsystem; you must call the action with `--terminus rest` if you wish
       to retrieve a catalog from the puppet master.
 
       FORMATTING ISSUES: This action cannot currently render useful yaml;
       instead, it returns an entire catalog. Use json instead.
     NOTES
     examples <<-'EOT'
       Ask the puppet master for a list of managed file resources for a node:
 
       $ puppet catalog select --terminus rest somenode.magpie.lan file
     EOT
     when_invoked do |host, type, options|
       # REVISIT: Eventually, type should have a default value that triggers
       # the non-specific behaviour.  For now, though, this will do.
       # --daniel 2011-05-03
       catalog = Puppet::Resource::Catalog.indirection.find(host)
 
       if type == '*'
         catalog.resources
       else
         type = type.downcase
         catalog.resources.reject { |res| res.type.downcase != type }
       end
     end
 
     when_rendering :console do |value|
       if value.nil? then
         "no matching resources found"
       else
         value.map {|x| x.to_s }.join("\n")
       end
     end
   end
 end
diff --git a/lib/puppet/face/certificate.rb b/lib/puppet/face/certificate.rb
index cab8817e3..cb0f61e3b 100644
--- a/lib/puppet/face/certificate.rb
+++ b/lib/puppet/face/certificate.rb
@@ -1,111 +1,114 @@
 require 'puppet/indirector/face'
 require 'puppet/ssl/host'
 
 Puppet::Indirector::Face.define(:certificate, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Provide access to the CA for certificate management"
+  summary "Provide access to the CA for certificate management."
   description <<-'EOT'
-    This face interacts with a local or remote Puppet certificate
+    This subcommand interacts with a local or remote Puppet certificate
     authority. Currently, its behavior is not a full superset of `puppet
     cert`; specifically, it is unable to mimic puppet cert's "clean" option,
     and its "generate" action submits a CSR rather than creating a
     signed certificate.
   EOT
 
   option "--ca-location LOCATION" do
-    summary "The certificate authority to query"
+    summary "The certificate authority to query (local or remote)."
     description <<-'EOT'
       Whether to act on the local certificate authority or one provided by a
       remote puppet master. Allowed values are 'local' and 'remote.'
+
+      This option is required.
     EOT
 
     before_action do |action, args, options|
       Puppet::SSL::Host.ca_location = options[:ca_location].to_sym
     end
   end
 
   action :generate do
-    summary "Generate a new certificate signing request for HOST."
+    summary "Generate a new certificate signing request."
     arguments "<host>"
     returns "Nothing."
     description <<-'EOT'
       Generates and submits a certificate signing request (CSR) for the
       specified host. This CSR will then have to be signed by a user
       with the proper authorization on the certificate authority.
 
       Puppet agent usually handles CSR submission automatically. This action is
       primarily useful for requesting certificates for individual users and
       external applications.
     EOT
     examples <<-'EOT'
       Request a certificate for "somenode" from the site's CA:
 
       $ puppet certificate generate somenode.puppetlabs.lan --ca-location remote
     EOT
 
     when_invoked do |name, options|
       host = Puppet::SSL::Host.new(name)
       host.generate_certificate_request
       host.certificate_request.class.indirection.save(host.certificate_request)
     end
   end
 
   action :list do
     summary "List all certificate signing requests."
     returns <<-'EOT'
-      An array of CSR object #inspect strings. This output is currently messy,
-      but does contain the names of nodes requesting certificates.
+      An array of #inspect output from CSR objects. This output is
+      currently messy, but does contain the names of nodes requesting
+      certificates. This action returns #inspect strings even when used
+      from the Ruby API.
     EOT
 
     when_invoked do |options|
       Puppet::SSL::Host.indirection.search("*", {
         :for => :certificate_request,
       }).map { |h| h.inspect }
     end
   end
 
   action :sign do
     summary "Sign a certificate signing request for HOST."
     arguments "<host>"
     returns <<-'EOT'
-      A string that appears to be an x509 certificate, but is actually
-      not. Retrieve certificates using the `find` action.
+      A string that appears to be (but isn't) an x509 certificate.
     EOT
     examples <<-'EOT'
       Sign somenode.puppetlabs.lan's certificate:
 
       $ puppet certificate sign somenode.puppetlabs.lan --ca-location remote
     EOT
 
     when_invoked do |name, options|
       host = Puppet::SSL::Host.new(name)
       host.desired_state = 'signed'
       Puppet::SSL::Host.indirection.save(host)
     end
   end
 
   # Indirector action doc overrides
   find = get_action(:find)
-  find.summary "Retrieve a certificate"
+  find.summary "Retrieve a certificate."
   find.arguments "<host>"
   find.returns <<-'EOT'
     An x509 SSL certificate. You will usually want to render this as a
-    string ('--render-as s').
+    string (--render-as s).
 
     Note that this action has a side effect of caching a copy of the
     certificate in Puppet's `ssldir`.
   EOT
 
   destroy = get_action(:destroy)
-  destroy.summary "Delete a local certificate."
+  destroy.summary "Delete a certificate."
   destroy.arguments "<host>"
   destroy.returns "Nothing."
   destroy.description <<-'EOT'
-    Deletes a certificate. This action currently only works with a local CA.
+    Deletes a certificate. This action currently only works on the local CA.
   EOT
 
-  get_action(:search).summary "Invalid for this face."
-  get_action(:save).summary "Invalid for this face."
+  get_action(:search).summary "Invalid for this subcommand."
+  get_action(:save).summary "Invalid for this subcommand."
 end
diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb
index 29cf7dc78..12694ba21 100644
--- a/lib/puppet/face/certificate_request.rb
+++ b/lib/puppet/face/certificate_request.rb
@@ -1,45 +1,46 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Manage certificate requests."
   description <<-'EOT'
-    Retrieves and submits certificate signing requests (CSRs). Invoke
-    `search` with a dummy key to retrieve all outstanding CSRs, invoke
-    `find` with a node certificate name to retrieve a specific request, and
-    invoke `save` to submit a CSR.
+    This subcommand retrieves and submits certificate signing requests (CSRs).
   EOT
 
   # Per-action doc overrides
-  get_action(:destroy).summary "Invalid for this face."
+  get_action(:destroy).summary "Invalid for this subcommand."
 
   get_action(:find).summary "Retrieve a single CSR."
   get_action(:find).arguments "<host>"
   get_action(:find).returns <<-'EOT'
-    A single certificate request. In most cases, you will want to render
-    this as a string ('--render-as s').
+    A single certificate request. When used from the Ruby API, returns a
+    Puppet::SSL::CertificateRequest object.
+
+    RENDERING ISSUES: In most cases, you will want to render this as a string
+    ('--render-as s').
   EOT
   get_action(:find).examples <<-'EOT'
     Retrieve a single CSR from the puppet master's CA:
 
     $ puppet certificate_request find somenode.puppetlabs.lan --terminus rest
   EOT
 
   get_action(:search).summary "Retrieve all outstanding CSRs."
   get_action(:search).arguments "<dummy_key>"
   get_action(:search).returns <<-'EOT'
-    An array of certificate request objects. In most cases, you will
-    want to render this as a string ('--render-as s').
+    A list of certificate requests; be sure to to render this as a string
+    ('--render-as s'). When used from the Ruby API, returns an array of
+    Puppet::SSL::CertificateRequest objects.
   EOT
   get_action(:search).notes "This action always returns all CSRs, but requires a dummy search key."
   get_action(:search).examples <<-'EOT'
-    Retrieve all CSRs from the local CA:
+    Retrieve all CSRs from the local CA (similar to 'puppet cert list'):
 
     $ puppet certificate_request search x --terminus ca
   EOT
 
-  get_action(:save).summary "Submit a certificate signing request."
+  get_action(:save).summary "API only: submit a certificate signing request."
   get_action(:save).arguments "<x509_CSR>"
 end
diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb
index 0525a601f..12ba1f73f 100644
--- a/lib/puppet/face/certificate_revocation_list.rb
+++ b/lib/puppet/face/certificate_revocation_list.rb
@@ -1,39 +1,39 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:certificate_revocation_list, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Manage the list of revoked certificates."
   description <<-'EOT'
-    This face is primarily for retrieving the certificate revocation
-    list from the CA. Although it exposes search/save/destroy methods,
-    they shouldn't be used under normal circumstances.
+    This subcommand is primarily for retrieving the certificate revocation
+    list from the CA.
   EOT
 
   get_action(:find).summary "Retrieve the certificate revocation list."
   get_action(:find).arguments "<dummy_key>"
   get_action(:find).returns <<-'EOT'
-    A certificate revocation list. You will usually want to render this
-    as a string ('--render-as s').
+    A certificate revocation list. When used from the Ruby API: returns an
+    OpenSSL::X509::CRL object.
+
+    RENDERING ISSUES: this should usually be rendered as a string
+    ('--render-as s').
   EOT
   get_action(:find).examples <<-'EXAMPLES'
     Retrieve a copy of the puppet master's CRL:
 
     $ puppet certificate_revocation_list find crl --terminus rest
   EXAMPLES
 
   get_action(:destroy).summary "Delete the certificate revocation list."
   get_action(:destroy).arguments "<dummy_key>"
   get_action(:destroy).returns "Nothing."
   get_action(:destroy).description <<-'EOT'
-    Deletes the certificate revocation list. This cannot be done over
-    REST, but it is possible to both delete the locally cached copy of
-    the CA's CRL and delete the CA's own copy (if running on the CA
-    machine and invoked with '--terminus ca'). Needless to say, don't do
-    this unless you know what you're up to.
+    Deletes the certificate revocation list. This cannot be done over REST, but
+    it is possible to delete the locally cached copy or (if run from the CA) the
+    CA's own copy of the CRL.
   EOT
 
-  get_action(:search).summary "Invalid for this face."
-  get_action(:save).summary "Invalid for this face."
+  get_action(:search).summary "Invalid for this subcommand."
+  get_action(:save).summary "Invalid for this subcommand."
 end
diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb
index 6e5bff071..3fce0ed70 100644
--- a/lib/puppet/face/config.rb
+++ b/lib/puppet/face/config.rb
@@ -1,47 +1,45 @@
 require 'puppet/face'
 
 Puppet::Face.define(:config, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Interact with Puppet's configuration options."
 
   action(:print) do
-    summary "Examine Puppet's current configuration options."
-    arguments "(all | <option> [<option> ...]"
+    summary "Examine Puppet's current configuration settings."
+    arguments "(all | <setting> [<setting> ...]"
     returns <<-'EOT'
-      When called with one option: a single value.
-
-      When called with "all" or multiple options: a list of options and
-      their values.
+      A single value when called with one config setting, and a list of settings
+      and values when called with multiple options or "all."
     EOT
     description <<-'EOT'
       Prints the value of a single configuration option or a list of
       configuration options.
 
       This action is an alternate interface to the information available with
       `puppet <subcommand> --configprint`.
     EOT
     notes <<-'EOT'
       By default, this action reads the configuration in agent mode.
       Use the '--mode' and '--environment' flags to examine other
       configuration domains.
     EOT
     examples <<-'EOT'
       Get puppet's runfile directory:
 
       $ puppet config print rundir
 
       Get a list of important directories from the master's config:
 
       $ puppet config print all --mode master | grep -E "(path|dir)"
     EOT
 
     when_invoked do |*args|
       options = args.pop
       Puppet.settings[:configprint] = args.join(",")
       Puppet.settings.print_config_options
       nil
     end
   end
 end
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index 05028a435..99ff14bd9 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -1,74 +1,80 @@
 require 'puppet/indirector/face'
 require 'puppet/node/facts'
 
 Puppet::Indirector::Face.define(:facts, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Retrieve and store facts."
   description <<-'EOT'
-    This face manages facts, the collections of normalized system
-    information used by Puppet. It can read facts directly from the
-    local system (using the default `facter` terminus), look up facts
-    reported by other systems, and submit facts to the puppet master.
+    This subcommand manages facts, which are collections of normalized system
+    information used by Puppet. It can read facts directly from the local system
+    (with the default `facter` terminus), look up facts reported by other
+    systems, and submit facts to the puppet master.
 
-    When used with the `rest` terminus, this face is essentially a
-    front-end to the inventory service REST API. See the inventory
-    service documentation for more detail.
+    When used with the `rest` terminus, this subcommand is essentially a front-end
+    to the inventory service REST API. See the inventory service documentation at
+    <http://docs.puppetlabs.com/guides/inventory_service.html> for more detail.
   EOT
 
   find = get_action(:find)
-  find.summary "Retrieve a host's facts."
-  find.arguments "<host>"
-  find.returns "A Puppet::Node::Facts object."
+  find.summary "Retrieve a node's facts."
+  find.arguments "<node_certname>"
+  find.returns <<-'EOT'
+    A hash containing some metadata and (under the "values" key) the set
+    of facts for the requested node. When used from the Ruby API: A
+    Puppet::Node::Facts object.
+
+    RENDERING ISSUES: Facts cannot currently be rendered as a string.
+  EOT
   find.notes <<-'EOT'
-    When using the `facter` terminus, the host argument is essentially ignored.
+    When using the `facter` terminus, the host argument is ignored.
   EOT
   find.examples <<-'EOT'
     Get facts from the local system:
 
     $ puppet facts find x
 
     Ask the puppet master for facts for an arbitrary node:
 
     $ puppet facts find somenode.puppetlabs.lan --terminus rest
 
     Query a DB-backed inventory directly (bypassing the REST API):
 
     $ puppet facts find somenode.puppetlabs.lan --terminus inventory_active_record --mode master
   EOT
 
-  get_action(:destroy).summary "Invalid for this face."
-  get_action(:search).summary "Query format unknown; potentially invalid for this face."
+  get_action(:destroy).summary "Invalid for this subcommand."
+  get_action(:search).summary "Invalid for this subcommand."
 
   action(:upload) do
     summary "Upload local facts to the puppet master."
     description <<-'EOT'
-      Reads facts from the local system using the facter terminus, then
+      Reads facts from the local system using the `facter` terminus, then
       saves the returned facts using the rest terminus.
     EOT
     returns "Nothing."
     notes <<-'EOT'
       This action requires that the puppet master's `auth.conf` file
       allow save access to the `facts` REST terminus. Puppet agent does
       not use this facility, and it is turned off by default. See
       <http://docs.puppetlabs.com/guides/rest_auth_conf.html> for more details.
     EOT
     examples <<-'EOT'
       Upload facts:
 
       $ puppet facts upload
     EOT
 
     render_as :yaml
 
     when_invoked do |options|
       Puppet::Node::Facts.indirection.terminus_class = :facter
       facts = Puppet::Node::Facts.indirection.find(Puppet[:certname])
       Puppet::Node::Facts.indirection.terminus_class = :rest
       Puppet::Node::Facts.indirection.save(facts)
       Puppet.notice "Uploaded facts for '#{Puppet[:certname]}'"
       nil
     end
   end
 end
diff --git a/lib/puppet/face/file.rb b/lib/puppet/face/file.rb
index 1cf9bc7f3..f63350e3b 100644
--- a/lib/puppet/face/file.rb
+++ b/lib/puppet/face/file.rb
@@ -1,47 +1,47 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:file, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Retrieve and store files in a filebucket"
   description <<-'EOT'
-    This face interacts with objects stored in a local or remote
+    This subcommand interacts with objects stored in a local or remote
     filebucket. File objects are accessed by their MD5 sum; see the
     examples for the relevant syntax.
   EOT
   notes <<-'EOT'
     To retrieve the unmunged contents of a file, you must call find with
     --render-as s. Rendering as yaml will return a hash of metadata
     about the file, including its contents.
 
-    This face does not interact with the `clientbucketdir` (the default
+    This subcommand does not interact with the `clientbucketdir` (the default
     local filebucket for puppet agent); it interacts with the primary
     "master"-type filebucket located in the `bucketdir`. If you wish to
     interact with puppet agent's default filebucket, you'll need to set
     the <--bucketdir> option appropriately when invoking actions.
   EOT
 
   file = get_action(:find)
   file.summary "Retrieve a file from the filebucket."
   file.arguments "md5/<md5sum>"
   file.returns <<-'EOT'
     The file object with the specified checksum.
 
     RENDERING ISSUES: Rendering as a string returns the contents of the
     file object; rendering as yaml returns a hash of metadata about said
     file, including but not limited to its contents. Rendering as json
     is currently broken, and returns a hash containing only the contents
     of the file.
   EOT
   file.examples <<-'EOT'
     Retrieve the contents of a file:
 
     $ puppet file find md5/9aedba7f413c97dc65895b1cd9421f2c --render-as s
   EOT
 
-  get_action(:search).summary "Invalid for this face."
-  get_action(:destroy).summary "Invalid for this face."
+  get_action(:search).summary "Invalid for this subcommand."
+  get_action(:destroy).summary "Invalid for this subcommand."
 
   set_indirection_name :file_bucket_file
 end
diff --git a/lib/puppet/face/file/download.rb b/lib/puppet/face/file/download.rb
index 8a300fbf1..3e67e452a 100644
--- a/lib/puppet/face/file/download.rb
+++ b/lib/puppet/face/file/download.rb
@@ -1,54 +1,54 @@
 # Download a specified file into the local filebucket.
 Puppet::Face.define(:file, '0.0.1') do
   action :download do |*args|
     summary "Download a file into the local filebucket."
-    arguments "( {md5}<checksum> | puppet:///... )"
-    returns "Nothing"
+    arguments "( {md5}<checksum> | <puppet_url> )"
+    returns "Nothing."
     description <<-EOT
-      Downloads a file from the puppet master's filebucket and
-      duplicates it in the local filebucket. This action's checksum
-      syntax differs from `find`'s, and it can accept a <puppet:///> URL.
+      Downloads a file from the puppet master's filebucket and duplicates it in
+      the local filebucket. This action's checksum syntax differs from `find`'s,
+      and it can accept a <puppet:///> URL.
     EOT
     examples <<-'EOT'
       Download a file by URL:
 
       $ puppet file download puppet:///modules/editors/vim/.vimrc
 
       Download a file by MD5 sum:
 
       $ puppet file download {md5}8f798d4e754db0ac89186bbaeaf0af18
     EOT
 
     when_invoked do |sum, options|
       if sum =~ /^puppet:\/\// # it's a puppet url
         require 'puppet/file_serving'
         require 'puppet/file_serving/content'
         raise "Could not find metadata for #{sum}" unless content = Puppet::FileServing::Content.indirection.find(sum)
         file = Puppet::FileBucket::File.new(content.content)
       else
         tester = Object.new
         tester.extend(Puppet::Util::Checksums)
 
         type    = tester.sumtype(sum)
         sumdata = tester.sumdata(sum)
 
         key = "#{type}/#{sumdata}"
 
         Puppet::FileBucket::File.indirection.terminus_class = :file
         if Puppet::FileBucket::File.indirection.find(key)
           Puppet.info "Content for '#{sum}' already exists"
           return
         end
 
         Puppet::FileBucket::File.indirection.terminus_class = :rest
         raise "Could not download content for '#{sum}'" unless file = Puppet::FileBucket::File.indirection.find(key)
       end
 
 
       Puppet::FileBucket::File.indirection.terminus_class = :file
       Puppet.notice "Saved #{sum} to filebucket"
       Puppet::FileBucket::File.indirection.save file
       return nil
     end
   end
 end
diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb
index 9376adf04..4a16a0d51 100644
--- a/lib/puppet/face/help.rb
+++ b/lib/puppet/face/help.rb
@@ -1,131 +1,131 @@
 require 'puppet/face'
 require 'puppet/util/command_line'
 require 'pathname'
 require 'erb'
 
 Puppet::Face.define(:help, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Display Puppet help."
 
   action(:help) do
-    summary "Display help about faces and their actions."
-    arguments "[<face>] [<action>]"
-    returns "Short help text for the specified face or action."
+    summary "Display help about Puppet subcommands and their actions."
+    arguments "[<subcommand>] [<action>]"
+    returns "Short help text for the specified subcommand or action."
     examples <<-'EOT'
       Get help for an action:
 
       $ puppet help
     EOT
 
     option "--version VERSION" do
-      summary "The version of the face for which to show help."
+      summary "The version of the subcommand for which to show help."
     end
 
     default
     when_invoked do |*args|
       # Check our invocation, because we want varargs and can't do defaults
       # yet.  REVISIT: when we do option defaults, and positional options, we
       # should rewrite this to use those. --daniel 2011-04-04
       options = args.pop
       if options.nil? or args.length > 2 then
         if args.select { |x| x == 'help' }.length > 2 then
           c = "\n %'(),-./=ADEFHILORSTUXY\\_`gnv|".split('')
           i = <<-'EOT'.gsub(/\s*/, '').to_i(36)
             3he6737w1aghshs6nwrivl8mz5mu9nywg9tbtlt081uv6fq5kvxse1td3tj1wvccmte806nb
             cy6de2ogw0fqjymbfwi6a304vd56vlq71atwmqsvz3gpu0hj42200otlycweufh0hylu79t3
             gmrijm6pgn26ic575qkexyuoncbujv0vcscgzh5us2swklsp5cqnuanlrbnget7rt3956kam
             j8adhdrzqqt9bor0cv2fqgkloref0ygk3dekiwfj1zxrt13moyhn217yy6w4shwyywik7w0l
             xtuevmh0m7xp6eoswin70khm5nrggkui6z8vdjnrgdqeojq40fya5qexk97g4d8qgw0hvokr
             pli1biaz503grqf2ycy0ppkhz1hwhl6ifbpet7xd6jjepq4oe0ofl575lxdzjeg25217zyl4
             nokn6tj5pq7gcdsjre75rqylydh7iia7s3yrko4f5ud9v8hdtqhu60stcitirvfj6zphppmx
             7wfm7i9641d00bhs44n6vh6qvx39pg3urifgr6ihx3e0j1ychzypunyou7iplevitkyg6gbg
             wm08oy1rvogcjakkqc1f7y1awdfvlb4ego8wrtgu9vzw4vmj59utwifn2ejcs569dh1oaavi
             sc581n7jjg1dugzdu094fdobtx6rsvk3sfctvqnr36xctold
           EOT
           353.times{i,x=i.divmod(1184);a,b=x.divmod(37);print(c[a]*b)}
         end
-        raise ArgumentError, "help only takes two (optional) arguments, a face name, and an action"
+        raise ArgumentError, "Puppet help only takes two (optional) arguments: a subcommand and an action"
       end
 
       version = :current
       if options.has_key? :version then
         if options[:version].to_s !~ /^current$/i then
           version = options[:version]
         else
           if args.length == 0 then
-            raise ArgumentError, "version only makes sense when a face is given"
+            raise ArgumentError, "Version only makes sense when a Faces subcommand is given"
           end
         end
       end
 
       # Name those parameters...
       facename, actionname = args
 
       if facename then
         if legacy_applications.include? facename then
           actionname and raise ArgumentError, "Legacy subcommands don't take actions"
           return Puppet::Application[facename].help
         else
           face = Puppet::Face[facename.to_sym, version]
           actionname and action = face.get_action(actionname.to_sym)
         end
       end
 
       case args.length
       when 0 then
         template = erb 'global.erb'
       when 1 then
         face or fail ArgumentError, "Unable to load face #{facename}"
         template = erb 'face.erb'
       when 2 then
         face or fail ArgumentError, "Unable to load face #{facename}"
         action or fail ArgumentError, "Unable to load action #{actionname} from #{face}"
         template = erb 'action.erb'
       else
         fail ArgumentError, "Too many arguments to help action"
       end
 
       # Run the ERB template in our current binding, including all the local
       # variables we established just above. --daniel 2011-04-11
       return template.result(binding)
     end
   end
 
   def erb(name)
     template = (Pathname(__FILE__).dirname + "help" + name)
     erb = ERB.new(template.read, nil, '-')
     erb.filename = template.to_s
     return erb
   end
 
   def legacy_applications
     # The list of applications, less those that are duplicated as a face.
     Puppet::Util::CommandLine.available_subcommands.reject do |appname|
       Puppet::Face.face? appname.to_sym, :current or
         # ...this is a nasty way to exclude non-applications. :(
         %w{face_base indirection_base}.include? appname
     end.sort
   end
 
   def horribly_extract_summary_from(appname)
     begin
       require "puppet/application/#{appname}"
       help = Puppet::Application[appname].help.split("\n")
       # Now we find the line with our summary, extract it, and return it.  This
       # depends on the implementation coincidence of how our pages are
       # formatted.  If we can't match the pattern we expect we return the empty
       # string to ensure we don't blow up in the summary. --daniel 2011-04-11
       while line = help.shift do
         if md = /^puppet-#{appname}\([^\)]+\) -- (.*)$/.match(line) then
           return md[1]
         end
       end
     rescue Exception
       # Damn, but I hate this: we just ignore errors here, no matter what
       # class they are.  Meh.
     end
     return ''
   end
 end
diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb
index c788f34fd..5242ed218 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -1,57 +1,49 @@
-<%= action.summary || face.summary || "unknown face..." %>
-
 <% if action.synopsis -%>
 USAGE: <%= action.synopsis %>
 
 <% end -%>
-<% if action.short_description -%>
-<%= action.short_description.strip %>
+<%= action.short_description || action.summary || face.summary || "undocumented subcommand" %>
 
-<% end -%>
 <% if action.returns -%>
 RETURNS: <%= action.returns.strip %>
 
 <% end -%>
 OPTIONS:
 <%# Remove these options once we can introspect them normally. -%>
-  --mode MODE                    - The run mode to use (`user`, `agent`, or
-                                   `master`).
+  --mode MODE                    - The run mode to use (user, agent, or master).
   --render-as FORMAT             - The rendering format to use.
   --verbose                      - Whether to log verbosely.
   --debug                        - Whether to log debug information.
 <% unless action.options.empty?
      optionroom = 30
      summaryroom = 80 - 5 - optionroom
       action.options.sort.each do |name|
         option = action.get_option name -%>
 <%= "  " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%>
 <%     if !(option.summary) -%>
-unknown option...
+undocumented option
 <%     elsif option.summary.length <= summaryroom -%>
 <%= option.summary %>
 <%
         else
           words = option.summary.split
           wrapped = ['']
           i = 0
           words.each do |word|
             if wrapped[i].length + word.length <= summaryroom
               wrapped[i] << word + ' '
             else
               i += 1
               wrapped[i] = word + ' '
             end
           end
 -%>
 <%= wrapped.shift.strip %>
 <%       wrapped.each do |line| -%>
 <%= (' ' * (optionroom + 5) ) + line.strip %>
 <%       end
         end
       end -%>
 <% end -%>
 
-<% if action.examples -%>
-EXAMPLES:
-<%= action.examples %>
-<% end -%>
+See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.
diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb
index 2a0f0181c..870cc547f 100644
--- a/lib/puppet/face/help/face.erb
+++ b/lib/puppet/face/help/face.erb
@@ -1,91 +1,84 @@
-<%= face.summary || "unknown face..." %>
-
 <% if face.synopsis -%>
 USAGE: <%= face.synopsis %>
 
 <% end -%>
-<% if face.short_description -%>
-<%= face.short_description %>
+<%= (face.short_description || face.summary || "undocumented subcommand").strip %>
 
-<% end -%>
 OPTIONS:
 <%# Remove these options once we can introspect them normally. -%>
-  --mode MODE                    - The run mode to use (`user`, `agent`, or
-                                   `master`).
+  --mode MODE                    - The run mode to use (user, agent, or master).
   --render-as FORMAT             - The rendering format to use.
   --verbose                      - Whether to log verbosely.
   --debug                        - Whether to log debug information.
 <% unless face.options.empty?
      optionroom = 30
      summaryroom = 80 - 5 - optionroom
       face.options.sort.each do |name|
         option = face.get_option name -%>
 <%= "  " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%>
 <%     if !(option.summary) -%>
-unknown option...
+undocumented option
 <%     elsif option.summary.length <= summaryroom -%>
 <%= option.summary %>
 <%
        else
          words = option.summary.split
          wrapped = ['']
          i = 0
          words.each do |word|
            if wrapped[i].length + word.length <= summaryroom
              wrapped[i] << word + ' '
            else
              i += 1
              wrapped[i] = word + ' '
            end
          end
 -%>
 <%= wrapped.shift.strip %>
 <%       wrapped.each do |line| -%>
 <%= (' ' * (optionroom + 5) ) + line.strip %>
 <%       end
         end
       end -%>
 <% end -%>
 
 ACTIONS:
 <% padding = face.actions.map{|x| x.to_s.length}.max + 2
    summaryroom = 80 - (padding + 4)
    face.actions.each do |actionname|
      action = face.get_action(actionname) -%>
   <%= action.name.to_s.ljust(padding) + '  ' -%>
 <% if !(action.summary) -%>
-unknown action...
+undocumented action
 <% elsif action.summary.length <= summaryroom -%>
 <%= action.summary %>
 <% else
           words = action.summary.split
           wrapped = ['']
           i = 0
           words.each do |word|
             if wrapped[i].length + word.length <= summaryroom
               wrapped[i] << word + ' '
             else
               i += 1
               wrapped[i] = word + ' '
             end
           end
 -%>
 <%= wrapped.shift.strip %>
 <%       wrapped.each do |line| -%>
 <%= (' ' * (padding + 4) ) + line.strip %>
 <%       end
         end
 end -%>
 
 <% if face.respond_to? :indirection -%>
 TERMINI: <%= face.class.terminus_classes(face.indirection.name).join(", ") %>
 
 <% end
    unless face.authors.empty? -%>
 AUTHOR
 <%= face.authors.join("\n").gsub(/^/, ' * ') %>
 
 <% end -%>
-COPYRIGHT AND LICENSE:
-<%= face.copyright.gsub(/^/, '  ') %>
-<%= face.license.gsub(/^/, '  ')   %>
+See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.
diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb
index 6f21fe413..90e27964c 100644
--- a/lib/puppet/face/help/man.erb
+++ b/lib/puppet/face/help/man.erb
@@ -1,132 +1,136 @@
-puppet-<%= face.name %>(8) -- <%= face.summary || "Unknown face." %>
+puppet-<%= face.name %>(8) -- <%= face.summary || "Undocumented subcommand." %>
 <%= '=' * (_erbout.length - 1) %>
 
 <% if face.synopsis -%>
 SYNOPSIS
 --------
 <%= face.synopsis %>
 
 <% end
    if face.description -%>
 DESCRIPTION
 -----------
 <%= face.description.strip %>
 
 <% end -%>
 OPTIONS
 -------
 Note that any configuration parameter that's valid in the configuration
 file is also a valid long argument, although it may or may not be
 relevant to the present action. For example, `server` is a valid
 configuration parameter, so you can specify `--server <servername>` as
 an argument.
 
 See the configuration file documentation at
 <http://docs.puppetlabs.com/references/stable/configuration.html> for the
 full list of acceptable parameters. A commented list of all
 configuration options can also be generated by running puppet with
 `--genconfig`.
 
 * --mode MODE:
   The run mode to use for the current action. Valid modes are `user`, `agent`,
   and `master`.
 * --render-as FORMAT:
   The format in which to render output. The most common formats are `json`,
-  `s` (string), and `yaml`, but other options such as `dot` are
+  `s` (string), `yaml`, and `console`, but other options such as `dot` are
   sometimes available.
 * --verbose:
   Whether to log verbosely.
 * --debug:
   Whether to log debug information.
 <% unless face.options.empty?
      face.options.sort.each do |name|
        option = face.get_option name -%>
 <%= "* " + option.optparse.join(" | " ) %>:
 <%= option.description.gsub(/^/, '  ') || '  ' + option.summary %>
 <%   end
    end -%>
 
 ACTIONS
 -------
 <% face.actions.each do |actionname|
      action = face.get_action(actionname) -%>
 * `<%= action.name.to_s %>` - <%= action.summary %>:
 <%   if action.synopsis -%>
   `SYNOPSIS`
 
   <%= action.synopsis %>
 
 <%   end -%>
-<%   if action.description -%>
   `DESCRIPTION`
 
+<%   if action.description -%>
 <%= action.description.gsub(/^/, '  ') %>
-<%   end
-     unique_options = action.options - face.options
+<% else -%>
+  <%= action.summary || "Undocumented action." %>
+<%   end -%>
+
+<%   unique_options = action.options - face.options
      unless unique_options.empty? -%>
   `OPTIONS`
 
 <%     unique_options.sort.each do |name|
          option = action.get_option name
          text = option.description || option.summary -%>
   <%= '<' + option.optparse.join("> | <") + '>' %> -
 <%= text.gsub(/^/, '  ') %>
 <%     end -%>
 
 <%   end -%>
 <%   if action.returns -%>
   `RETURNS`
 
 <%= action.returns.gsub(/^/, '  ') %>
 
 <%   end
      if action.notes -%>
   `NOTES`
 
 <%= action.notes.gsub(/^/, '  ') %>
 
 <%   end
    end
    if face.examples or face.actions.any? {|actionname| face.get_action(actionname).examples} -%>
 EXAMPLES
 --------
 <% end
    if face.examples -%>
 <%= face.examples %>
 
 <% end
    face.actions.each do |actionname|
      action = face.get_action(actionname)
      if action.examples -%>
 `<%= action.name.to_s %>`
 
 <%= action.examples.strip %>
+
 <%   end
    end -%>
 
 <% if face.notes or face.respond_to? :indirection -%>
 NOTES
 -----
 <% if face.notes -%>
 <%= face.notes.strip %>
 
 <% end # notes
 if face.respond_to? :indirection -%>
-This is an indirector face, which exposes `find`, `search`, `save`, and
-`destroy` actions for an indirected subsystem of Puppet. Valid termini
-for this face include:
+This subcommand is an indirector face, which exposes `find`, `search`, `save`,
+and `destroy` actions for an indirected subsystem of Puppet. Valid termini for
+this face include:
 
 * `<%= face.class.terminus_classes(face.indirection.name).join("`\n* `") %>`
 
 <% end # indirection
    end # notes or indirection
    unless face.authors.empty? -%>
 AUTHOR
 ------
 <%= face.authors.join("\n").gsub(/^/, ' * ') %>
 
 <% end -%>
 COPYRIGHT AND LICENSE
 ---------------------
 <%= face.copyright %>
 <%= face.license %>
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index 54c4975c5..96cfebe3a 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -1,15 +1,15 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:key, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Create, save, and remove certificate keys."
   description <<-'EOT'
-    Manages certificate private keys. Keys are created for you
-    automatically when certificate requests are generated with 'puppet
-    certificate generate', and it should not be necessary to use this action
-    directly.
+    This subcommand manages certificate private keys. Keys are created
+    automatically by puppet agent and when certificate requests are generated
+    with 'puppet certificate generate'; it should not be necessary to use this
+    subcommand directly.
   EOT
 
 end
diff --git a/lib/puppet/face/man.rb b/lib/puppet/face/man.rb
index 38b9202eb..c43ead3ec 100644
--- a/lib/puppet/face/man.rb
+++ b/lib/puppet/face/man.rb
@@ -1,95 +1,93 @@
 require 'puppet/face'
 require 'puppet/util'
 require 'pathname'
 require 'erb'
 
 Puppet::Face.define(:man, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Display Puppet subcommand manual pages."
+  summary "Display Puppet manual pages."
 
   description <<-EOT
-    The man face, when invoked from the command line, tries very hard to
-    behave nicely for interactive use.  If possible, it delegates to the
-    ronn(1) command to format the output as a real manual page.
-
-    If ronn(1) is not available, it will use the first of `$MANPAGER`,
-    `$PAGER`, `less`, `most`, or `more` to paginate the (human-readable)
-    input text for the manual page.
-
-    We do try hard to ensure that this behaves correctly when used as
-    part of a pipeline.  (Well, we delegate to tools that do the right
-    thing, which is more or less the same.)
+    This subcommand displays manual pages for all Puppet subcommands. If the
+    `ronn` gem (<https://github.com/rtomayko/ronn/>) is installed on your
+    system, puppet man will display fully-formated man pages. If `ronn` is not
+    available, puppet man will display the raw (but human-readable) source text
+    in a pager.
   EOT
 
   notes <<-EOT
-    We strongly encourage you to install the `ronn` gem on your system,
-    or otherwise make it available, so that we can display well structured
-    output from this face.
+    The pager used for display will be the first found of `$MANPAGER`, `$PAGER`,
+    `less`, `most`, or `more`.
   EOT
 
   action(:man) do
-    summary "Display the manual page for a face."
-    arguments "<face>"
-    returns "The man data, in markdown format, suitable for consumption by Ronn."
+    summary "Display the manual page for a Puppet subcommand."
+    arguments "<subcommand>"
+    returns <<-'EOT'
+      The man data, in Markdown format, suitable for consumption by Ronn.
+
+      RENDERING ISSUES: To skip fancy formatting and output the raw Markdown
+      text (e.g. for use in a pipeline), call this action with '--render-as s'.
+    EOT
     examples <<-'EOT'
-      Get the manual page for a face:
+      View the manual page for a subcommand:
 
       $ puppet man facts
     EOT
 
     default
     when_invoked do |name, options|
       if legacy_applications.include? name then
         return Puppet::Application[name].help
       end
 
       face = Puppet::Face[name.to_sym, :current]
 
       file = (Pathname(__FILE__).dirname + "help" + 'man.erb')
       erb = ERB.new(file.read, nil, '-')
       erb.filename = file.to_s
 
       # Run the ERB template in our current binding, including all the local
       # variables we established just above. --daniel 2011-04-11
       return erb.result(binding)
     end
 
 
     when_rendering :console do |text|
       # OK, if we have Ronn on the path we can delegate to it and override the
       # normal output process.  Otherwise delegate to a pager on the raw text,
       # otherwise we finally just delegate to our parent.  Oh, well.
       ENV['LESS'] ||= 'FRSX'    # emulate git...
 
       ronn  = Puppet::Util.which('ronn')
       pager = [ENV['MANPAGER'], ENV['PAGER'], 'less', 'most', 'more'].
         detect {|x| x and x.length > 0 and Puppet::Util.which(x) }
 
       if ronn then
         # ronn is a stupid about pager selection, we can be smarter. :)
         if pager then ENV['PAGER'] = pager end
 
         args  = "--man --manual='Puppet Manual' --organization='Puppet Labs, LLC'"
         IO.popen("#{ronn} #{args}", 'w') do |fh| fh.write text end
 
         ''                      # suppress local output, neh?
       elsif pager then
         IO.popen(pager, 'w') do |fh| fh.write text end
         ''
       else
         text
       end
     end
   end
 
   def legacy_applications
     # The list of applications, less those that are duplicated as a face.
     Puppet::Util::CommandLine.available_subcommands.reject do |appname|
       Puppet::Face.face? appname.to_sym, :current or
         # ...this is a nasty way to exclude non-applications. :(
         %w{face_base indirection_base}.include? appname
     end
   end
 end
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index d244127a4..cd27e0b26 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -1,37 +1,42 @@
 require 'puppet/indirector/face'
 Puppet::Indirector::Face.define(:node, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "View and manage node definitions."
   description <<-'EOT'
-    This face interacts with node objects, which are used by Puppet to
-    build a catalog. A node object consists of the node's facts,
-    environment, node parameters (exposed in the parser as top-scope
-    variables), and classes.
+    This subcommand interacts with node objects, which are used by Puppet to
+    build a catalog. A node object consists of the node's facts, environment,
+    node parameters (exposed in the parser as top-scope variables), and classes.
   EOT
 
-  get_action(:destroy).summary "Invalid for this face."
-  get_action(:search).summary "Invalid for this face."
-  get_action(:save).summary "Invalid for this face."
+  get_action(:destroy).summary "Invalid for this subcommand."
+  get_action(:search).summary "Invalid for this subcommand."
+  get_action(:save).summary "Invalid for this subcommand."
 
   find = get_action(:find)
   find.summary "Retrieve a node object."
   find.arguments "<host>"
   find.returns <<-'EOT'
-    A Puppet::Node object.
+    A hash containing the node's `classes`, `environment`, `expiration`, `name`,
+    `parameters` (its facts, combined with any ENC-set parameters), and `time`.
+    When used from the Ruby API: a Puppet::Node object.
 
     RENDERING ISSUES: Rendering as string and json are currently broken;
     node objects can only be rendered as yaml.
   EOT
   find.examples <<-'EOT'
-    Retrieve an "empty" (no classes, fact and bulit-in parameters only,
-    and an environment of "production") node:
+    Retrieve an "empty" (no classes, no ENC-imposed parameters, and an
+    environment of "production") node:
 
     $ puppet node find somenode.puppetlabs.lan --terminus plain --render-as yaml
 
     Retrieve a node using the puppet master's configured ENC:
 
     $ puppet node find somenode.puppetlabs.lan --terminus exec --mode master --render-as yaml
+
+    Retrieve the same node from the puppet master:
+
+    $ puppet node find somenode.puppetlabs.lan --terminus rest --render-as yaml
   EOT
 end
diff --git a/lib/puppet/face/parser.rb b/lib/puppet/face/parser.rb
index 8dd3efb75..c99cbb747 100644
--- a/lib/puppet/face/parser.rb
+++ b/lib/puppet/face/parser.rb
@@ -1,33 +1,42 @@
 require 'puppet/face'
 require 'puppet/parser'
 
 Puppet::Face.define(:parser, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Interact directly with the parser."
 
   action :validate do
     summary "Validate the syntax of one or more Puppet manifests."
     arguments "[<manifest>] [<manifest> ...]"
     returns "Nothing, or the first syntax error encountered."
     description <<-'EOT'
       This action validates Puppet DSL syntax without compiling a catalog or
       syncing any resources. If no manifest files are provided, it will
       validate the default site manifest.
     EOT
+    examples <<-'EOT'
+      Validate the default site manifest at /etc/puppet/manifests/site.pp:
+
+      $ puppet parser validate
+
+      Validate two arbitrary manifest files:
+
+      $ puppet parser validate init.pp vhost.pp
+    EOT
     when_invoked do |*args|
       args.pop
       files = args
       if files.empty?
         files << Puppet[:manifest]
         Puppet.notice "No manifest specified. Validating the default manifest #{Puppet[:manifest]}"
       end
       files.each do |file|
         Puppet[:manifest] = file
         Puppet::Node::Environment.new(Puppet[:environment]).known_resource_types.clear
       end
       nil
     end
   end
 end
diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb
index 541468d39..76c79f38d 100644
--- a/lib/puppet/face/plugin.rb
+++ b/lib/puppet/face/plugin.rb
@@ -1,54 +1,55 @@
 require 'puppet/face'
 Puppet::Face.define(:plugin, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Interact with the Puppet plugin system."
   description <<-'EOT'
-    This face provides network access to the puppet master's store of
+    This subcommand provides network access to the puppet master's store of
     plugins.
-  EOT
-  notes <<-'EOT'
-    The puppet master can serve Ruby code collected from the lib directories
+
+    The puppet master serves Ruby code collected from the `lib` directories
     of its modules. These plugins can be used on agent nodes to extend
-    Facter and implement custom types and providers.
+    Facter and implement custom types and providers. Plugins are normally
+    downloaded by puppet agent during the course of a run.
   EOT
 
   action :download do
     summary "Download plugins from the puppet master."
     description <<-'EOT'
       Downloads plugins from the configured puppet master. Any plugins
       downloaded in this way will be used in all subsequent Puppet activity.
+      This action modifies files on disk.
     EOT
     returns <<-'EOT'
-      A display-formatted list of the files downloaded. If all plugin
-      files were in sync, this list will be empty.
+      A list of the files downloaded, or a confirmation that no files were
+      downloaded. When used from the Ruby API, this action returns an array of
+      the files downloaded, which will be empty if none were retrieved.
     EOT
-    notes "This action modifies files on disk."
     examples <<-'EOT'
       Retrieve plugins from the puppet master:
 
       $ puppet plugin download
 
       Retrieve plugins from the puppet master (API example):
 
       $ Puppet::Face[:plugin, '0.0.1'].download
     EOT
 
     when_invoked do |options|
       require 'puppet/configurer/downloader'
       Puppet::Configurer::Downloader.new("plugin",
                                          Puppet[:plugindest],
                                          Puppet[:pluginsource],
                                          Puppet[:pluginsignore]).evaluate
     end
 
     when_rendering :console do |value|
       if value.empty? then
         "No plugins downloaded."
       else
         "Downloaded these plugins: #{value.join(', ')}"
       end
     end
   end
 end
diff --git a/lib/puppet/face/report.rb b/lib/puppet/face/report.rb
index 1345d6359..22737103c 100644
--- a/lib/puppet/face/report.rb
+++ b/lib/puppet/face/report.rb
@@ -1,56 +1,56 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:report, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Create, display, and submit reports"
+  summary "Create, display, and submit reports."
 
   get_action(:find).summary "Invalid for this face."
   get_action(:search).summary "Invalid for this face."
   get_action(:destroy).summary "Invalid for this face."
   save = get_action(:save)
-  save.summary "Submit a report."
+  save.summary "API only: submit a report."
   save.arguments "<report>"
   save.returns "Nothing."
   save.examples <<-'EOT'
     From the implementation of `puppet report submit` (API example):
 
         begin
           Puppet::Transaction::Report.indirection.terminus_class = :rest
           Puppet::Face[:report, "0.0.1"].save(report)
           Puppet.notice "Uploaded report for #{report.name}"
         rescue => detail
           puts detail.backtrace if Puppet[:trace]
           Puppet.err "Could not send report: #{detail}"
         end
   EOT
 
   action(:submit) do
-    summary "Submit a report object to the puppet master"
+    summary "API only: submit a report with error handling."
     description <<-'EOT'
-      This action is essentially a shortcut and wrapper for the `save` action
-      with the `rest` terminus, which provides additional details in the
-      event of a report submission failure. It is not intended for use from
-      a command line.
+      API only: Submits a report to the puppet master. This action is
+      essentially a shortcut and wrapper for the `save` action with the `rest`
+      terminus, and provides additional details in the event of a failure.
     EOT
+    arguments "<report>"
     examples <<-'EOT'
-      From secret_agent.rb:
+      From secret_agent.rb (API example):
 
           # ...
           report  = Puppet::Face[:catalog, '0.0.1'].apply
           Puppet::Face[:report, '0.0.1'].submit(report)
           return report
     EOT
     when_invoked do |report, options|
       begin
         Puppet::Transaction::Report.indirection.terminus_class = :rest
         Puppet::Face[:report, "0.0.1"].save(report)
         Puppet.notice "Uploaded report for #{report.name}"
       rescue => detail
         puts detail.backtrace if Puppet[:trace]
         Puppet.err "Could not send report: #{detail}"
       end
     end
   end
 end
diff --git a/lib/puppet/face/resource.rb b/lib/puppet/face/resource.rb
index 59f628675..95a2ffc9a 100644
--- a/lib/puppet/face/resource.rb
+++ b/lib/puppet/face/resource.rb
@@ -1,51 +1,53 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:resource, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Interact directly with resources via the RAL, like ralsh"
+  summary "API only: interact directly with resources via the RAL."
   description <<-'EOT'
-    This face provides a Ruby API with functionality similar to the puppet
-    resource (originally ralsh) command line application. It is not intended to be
-    used from the command line.
+    API only: this face provides a Ruby API with functionality similar to the
+    puppet resource (or ralsh) subcommand.
   EOT
 
-  get_action(:destroy).summary "Invalid for this face."
+  get_action(:destroy).summary "Invalid for this subcommand."
 
   search = get_action(:search)
-  search.summary "Get all resources of a single type."
+  search.summary "API only: get all resources of a single type."
   search.arguments "<resource_type>"
-  search.returns "An array of resource objects."
+  search.returns "An array of Puppet::Resource objects."
   search.examples <<-'EOT'
     Get a list of all user resources (API example):
 
         all_users = Puppet::Face[:resource, '0.0.1'].search("user")
   EOT
 
   find = get_action(:find)
-  find.summary "Get a single resource."
+  find.summary "API only: get a single resource."
   find.arguments "<type>/<title>"
-  find.returns "A resource object."
+  find.returns "A Puppet::Resource object."
   find.examples <<-'EOT'
     Print information about a user on this system (API example):
 
         puts Puppet::Face[:resource, '0.0.1'].find("user/luke").to_pson
   EOT
 
   save = get_action(:save)
-  save.summary "Create a new resource."
+  save.summary "API only: create a new resource."
+  save.description <<-EOT
+    API only: creates a new resource.
+  EOT
   save.arguments "<resource_object>"
-  save.returns "The same resource object passed."
+  save.returns "The same resource object passed as an argument."
   save.examples <<-'EOT'
     Create a new file resource (API example):
 
         my_resource = Puppet::Resource.new(
           :file,
           "/tmp/demonstration",
           :parameters => {:ensure => :present, :content => "some\nthing\n"}
         )
 
         Puppet::Face[:resource, '0.0.1'].save(my_resource)
   EOT
 end
diff --git a/lib/puppet/face/resource_type.rb b/lib/puppet/face/resource_type.rb
index 9d7639fc5..dc6d9de90 100644
--- a/lib/puppet/face/resource_type.rb
+++ b/lib/puppet/face/resource_type.rb
@@ -1,70 +1,80 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:resource_type, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "View classes, defined resource types, and nodes from all manifests"
+  summary "View classes, defined resource types, and nodes from all manifests."
   description <<-'EOT'
-    This face reads information about the resource collections (classes,
+    This subcommand reads information about the resource collections (classes,
     nodes, and defined types) available in Puppet's site manifest and
     modules.
 
     It will eventually be extended to examine native resource types.
   EOT
-
-  # Action documentation overrides:
-  get_action(:save).summary = "Invalid for this face."
-  get_action(:destroy).summary = "Invalid for this face."
-
-  find = get_action(:find)
-  find.summary "Retrieve info about a resource collection."
-  find.arguments "<collection_name>"
-  find.returns <<-'EOT'
-    A hash of info about one resource collection. This hash will include the
-    following four keys:
+  notes <<-'EOT'
+    The `find` and `search` actions return similar hashes of resource collection
+    info. These hashes will include the following four keys:
 
     * `file` (a string)
     * `name` (a string)
     * `type` (<hostclass>, <definition>, or <node>)
     * `line` (an integer)
 
-    It may also include the following keys:
+    They may optionally include the following keys:
 
     * `parent`    (<name_of_resource_collection>)
     * `arguments` (a hash of parameters and default values)
     * `doc`       (a string)
+  EOT
 
-    RENDERING ISSUES: yaml and string output for this indirection are
-    currently unusable; use json instead.
+  # Action documentation overrides:
+  get_action(:save).summary = "Invalid for this subcommand."
+  get_action(:destroy).summary = "Invalid for this subcommand."
+
+  find = get_action(:find)
+  find.summary "Retrieve info about a resource collection."
+  find.arguments "<collection_name>"
+  find.returns <<-'EOT'
+    A hash of info about the requested resource collection. When used from the
+    Ruby API: returns a Puppet::Resource::Type object.
+
+    RENDERING ISSUES: yaml and string output for this indirection are currently
+    unusable; use json instead.
+  EOT
+  find.notes <<-'EOT'
+    If two resource collections share the same name (e.g. you have both a node
+    and a class named "default"), `find` will only return one of them. This can
+    be worked around by using `search` instead.
   EOT
   find.examples <<-'EOT'
     Retrieve info about a specific locally-defined class:
 
     $ puppet resource_type find ntp::disabled
 
     Retrieve info from the puppet master about a specific class:
 
     $ puppet resource_type find ntp --terminus rest
   EOT
 
   search = get_action(:search)
   search.summary "Search for collections matching a regular expression."
   search.arguments "<regular_expression>"
   search.returns <<-'EOT'
-    An array of resource collection info hashes. (See "RETURNS" under `find`.)
+    An array of hashes of resource collection info. When used from the Ruby API:
+    returns an array of Puppet::Resource::Type objects.
 
-    RENDERING ISSUES: yaml and string output for this indirection are
-    currently unusable; use json instead.
+    RENDERING ISSUES: yaml and string output for this indirection are currently
+    unusable; use json instead.
   EOT
   search.examples <<-'EOT'
     Retrieve all classes, nodes, and defined types:
 
     $ puppet resource_type search '.*'
 
     Search for classes related to Nagios:
 
     $ puppet resource_type search nagios
   EOT
 
 end
diff --git a/lib/puppet/face/secret_agent.rb b/lib/puppet/face/secret_agent.rb
index 79241da72..7771d576a 100644
--- a/lib/puppet/face/secret_agent.rb
+++ b/lib/puppet/face/secret_agent.rb
@@ -1,54 +1,54 @@
 require 'puppet/face'
 
 Puppet::Face.define(:secret_agent, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "Mimics puppet agent."
   description <<-'EOT'
-    This face currently functions as a proof of concept, demonstrating
-    how Faces allows the separation of application logic from Puppet's
-    internal systems; compare the actual code for puppet agent. It will
-    eventually replace puppet agent entirely, and can provide a template
-    for users who wish to implement agent-like functionality with
-    non-standard application logic.
+    This subcommand currently functions as a proof of concept, demonstrating how
+    the Faces API exposes Puppet's internal systems to application logic;
+    compare the actual code for puppet agent. It will eventually replace puppet
+    agent entirely, and can provide a template for users who wish to implement
+    agent-like functionality with non-standard application logic.
   EOT
 
   action(:synchronize) do
     default
     summary "Run secret_agent once."
-    arguments "[-v | --verbose] [-d | --debug]" # Remove this once options are introspectible
     description <<-'EOT'
-      This action mimics a single run of the puppet agent application.
-      It does not currently daemonize, but can download plugins, submit
-      facts, retrieve and apply a catalog, and submit a report to the
-      puppet master.
+      Mimics a single run of puppet agent. This action does not currently
+      daemonize, but can download plugins, submit facts, retrieve and apply a
+      catalog, and submit a report to the puppet master.
+    EOT
+    returns <<-'EOT'
+      Verbose logging from the completed run. When used from the Ruby API:
+      returns a Puppet::Transaction::Report object.
     EOT
-    returns "A Puppet::Transaction::Report object."
     examples <<-'EOT'
       Trigger a Puppet run with the configured puppet master:
 
       $ puppet secret_agent
     EOT
     notes <<-'EOT'
-      This action requires that the puppet master's `auth.conf` file
-      allow save access to the `facts` REST terminus. Puppet agent does
-      not use this facility, and it is turned off by default. See
+      This action requires that the puppet master's `auth.conf` file allow save
+      access to the `facts` REST terminus. Puppet agent does not use this
+      facility, and it is turned off by default. See
       <http://docs.puppetlabs.com/guides/rest_auth_conf.html> for more details.
     EOT
 
     when_invoked do |options|
       Puppet::Face[:plugin, '0.0.1'].download
 
       Puppet::Face[:facts, '0.0.1'].upload
 
       Puppet::Face[:catalog, '0.0.1'].download
 
       report  = Puppet::Face[:catalog, '0.0.1'].apply
 
       Puppet::Face[:report, '0.0.1'].submit(report)
 
       return report
     end
   end
 end
diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb
index 4ae24e81b..690c6b371 100644
--- a/lib/puppet/face/status.rb
+++ b/lib/puppet/face/status.rb
@@ -1,39 +1,42 @@
 require 'puppet/indirector/face'
 
 Puppet::Indirector::Face.define(:status, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
   summary "View puppet server status."
 
-  get_action(:destroy).summary "Invalid for this face."
-  get_action(:save).summary "Invalid for this face."
-  get_action(:search).summary "Invalid for this face."
+  get_action(:destroy).summary "Invalid for this subcommand."
+  get_action(:save).summary "Invalid for this subcommand."
+  get_action(:search).summary "Invalid for this subcommand."
 
   find = get_action(:find)
   find.summary "Check status of puppet master server."
   find.arguments "<dummy_key>"
-  find.returns "A Puppet::Status object, or a low-level connection error."
+  find.returns <<-'EOT'
+    A "true" response or a low-level connection error. When used from the Ruby
+    API: returns a Puppet::Status object.
+  EOT
   find.description <<-'EOT'
     Checks whether a Puppet server is properly receiving and processing
-    REST requests. This action is only useful when used with '--terminus
+    HTTP requests. This action is only useful when used with '--terminus
     rest'; when invoked with the `local` terminus, `find` will always
     return true.
 
-    This action will query the configured puppet master. To query other
-    servers, including puppet agent nodes started with the --listen
-    option, you can set set the global --server and --masterport options
-    on the command line; note that agent nodes listen on port 8139.
+    Over REST, this action will query the configured puppet master by default.
+    To query other servers, including puppet agent nodes started with the
+    <--listen> option, you can set set the global <--server> and <--masterport>
+    options on the command line; note that agent nodes listen on port 8139.
   EOT
   find.notes <<-'EOT'
     This action requires that the server's `auth.conf` file allow find
     access to the `status` REST terminus. Puppet agent does not use this
     facility, and it is turned off by default. See
     <http://docs.puppetlabs.com/guides/rest_auth_conf.html> for more details.
   EOT
   find.examples <<-'EOT'
     Check the status of the configured puppet master:
 
     $ puppet status find x --terminus rest
   EOT
 end
diff --git a/lib/puppet/indirector/face.rb b/lib/puppet/indirector/face.rb
index 756306a2f..ead3f4b46 100644
--- a/lib/puppet/indirector/face.rb
+++ b/lib/puppet/indirector/face.rb
@@ -1,125 +1,127 @@
 require 'puppet/face'
 
 class Puppet::Indirector::Face < Puppet::Face
   option "--terminus TERMINUS" do
-    summary "The indirector terminus to use for this action."
+    summary "The indirector terminus to use."
     description <<-EOT
       Indirector faces expose indirected subsystems of Puppet. These
       subsystems are each able to retrieve and alter a specific type of data
       (with the familiar actions of `find`, `search`, `save`, and `destroy`)
       from an arbitrary number of pluggable backends. In Puppet parlance,
       these backends are called terminuses.
 
       Almost all indirected subsystems have a `rest` terminus that interacts
       with the puppet master's data. Most of them have additional terminuses
       for various local data models, which are in turn used by the indirected
       subsystem on the puppet master whenever it receives a remote request.
 
       The terminus for an action is often determined by context, but
       occasionally needs to be set explicitly. See the "Notes" section of this
       face's manpage for more details.
     EOT
 
     before_action do |action, args, options|
       set_terminus(options[:terminus])
     end
 
     after_action do |action, args, options|
       indirection.reset_terminus_class
     end
   end
 
   def self.indirections
     Puppet::Indirector::Indirection.instances.collect { |t| t.to_s }.sort
   end
 
   def self.terminus_classes(indirection)
     Puppet::Indirector::Terminus.terminus_classes(indirection.to_sym).collect { |t| t.to_s }.sort
   end
 
   def call_indirection_method(method, key, options)
     begin
       result = indirection.__send__(method, key, options)
     rescue => detail
       puts detail.backtrace if Puppet[:trace]
       raise "Could not call '#{method}' on '#{indirection_name}': #{detail}"
     end
 
     return result
   end
 
   action :destroy do
     summary "Delete an object."
     arguments "<key>"
     when_invoked { |key, options| call_indirection_method(:destroy, key, options) }
   end
 
   action :find do
     summary "Retrieve an object by name."
     arguments "<key>"
     when_invoked { |key, options| call_indirection_method(:find, key, options) }
   end
 
   action :save do
-    summary "Create or overwrite an object."
+    summary "API only: create or overwrite an object."
     arguments "<object>"
     description <<-EOT
-      Create or overwrite an object. Save actions cannot currently be
-      invoked from the command line, and are for API use only.
+      API only: create or overwrite an object. As the Faces framework does not
+      currently accept data from STDIN, save actions cannot currently be invoked
+      from the command line.
     EOT
     when_invoked { |key, options| call_indirection_method(:save, key, options) }
   end
 
   action :search do
     summary "Search for an object or retrieve multiple objects."
     arguments "<query>"
     when_invoked { |key, options| call_indirection_method(:search, key, options) }
   end
 
   # Print the configuration for the current terminus class
   action :info do
     summary "Print the default terminus class for this face."
     description <<-EOT
-      Prints the default terminus class for this face. Note that
-      different run modes may have different default terminuses.
+      Prints the default terminus class for this subcommand. Note that different
+      run modes may have different default termini; when in doubt, specify the
+      run mode with the '--mode' option.
     EOT
 
     when_invoked do |*args|
       if t = indirection.terminus_class
         puts "Run mode '#{Puppet.run_mode.name}': #{t}"
       else
         $stderr.puts "No default terminus class for run mode '#{Puppet.run_mode.name}'"
       end
     end
   end
 
   attr_accessor :from
 
   def indirection_name
     @indirection_name || name.to_sym
   end
 
   # Here's your opportunity to override the indirection name.  By default it
   # will be the same name as the face.
   def set_indirection_name(name)
     @indirection_name = name
   end
 
   # Return an indirection associated with a face, if one exists;
   # One usually does.
   def indirection
     unless @indirection
       @indirection = Puppet::Indirector::Indirection.instance(indirection_name)
       @indirection or raise "Could not find terminus for #{indirection_name}"
     end
     @indirection
   end
 
   def set_terminus(from)
     begin
       indirection.terminus_class = from
     rescue => detail
       raise "Could not set '#{indirection.name}' terminus to '#{from}' (#{detail}); valid terminus types are #{self.class.terminus_classes(indirection.name).join(", ") }"
     end
   end
 end