diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 4624313bc..c7501ff37 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -1,108 +1,127 @@
 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
+  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
+    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'.
   EOT
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    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:
 
     * `active_record`
     * `compiler`
     * `queue`
     * `rest`
     * `yaml`
   EOT
 
+  get_action(:destroy).summary "Invalid for this face."
+  get_action(:search).summary "Query format unknown; potentially invalid for this face."
+
   action(:apply) do
-    summary "Apply a Puppet::Resource::Catalog object"
-    description <<-EOT
-      Applies a catalog object retrieved with the `download` action. This
-      action cannot consume a serialized catalog, and is not intended for
-      command-line use."
+    summary "Apply a Puppet::Resource::Catalog object."
+    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.
     EOT
-    notes <<-EOT
-      This action returns a Puppet::Transaction::Report object.
+    returns <<-'EOT'
+      A Puppet::Transaction::Report object.
     EOT
-    examples <<-EOT
-      From `secret_agent.rb`:
+    examples <<-'EOT'
+      Apply the locally cached catalog:
 
-          Puppet::Face[:plugin, '0.0.1'].download
+      $ puppet catalog apply --terminus yaml
+
+      Retrieve a catalog from the master and apply it, in one step:
+
+      $ puppet catalog apply --terminus rest
 
-          facts   = Puppet::Face[:facts, '0.0.1'].find(certname)
-          catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
-          report  = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
+      From `secret_agent.rb` (API example):
 
-          Puppet::Face[:report, '0.0.1'].submit(report)
+          # ...
+          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. Unlike the `find` action,
-      `download` submits facts to the master as part of the request. This
-      action is not intended for command-line use.
+    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
+      alternate termini.
     EOT
-    notes "This action returns a Puppet::Resource::Catalog object."
-    examples <<-EOT
-      From `secret_agent.rb`:
+    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
+      terminus must be explicitly re-set for subsequent catalog actions.
+    EOT
+    examples <<-'EOT'
+      Retrieve and store a catalog:
 
-          Puppet::Face[:plugin, '0.0.1'].download
+      $ puppet catalog download
 
-          facts   = Puppet::Face[:facts, '0.0.1'].find(certname)
-          catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
-          report  = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
+      From `secret_agent.rb` (API example):
 
-          Puppet::Face[:report, '0.0.1'].submit(report)
+          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 a6c97a627..d86963e75 100644
--- a/lib/puppet/face/catalog/select.rb
+++ b/lib/puppet/face/catalog/select.rb
@@ -1,42 +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"
-    description <<-EOT
+    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]).
+    EOT
+    description <<-'EOT'
       Retrieves a catalog for the specified host and returns an array of
-      resources of the given type. This action is not intended for
-      command-line use.
+      resources of the given type.
     EOT
-    notes <<-NOTES
-      The type name for this action must be given in its capitalized form.
-      That is, calling `catalog select mynode file` will return an empty
-      array, whereas calling it with 'File' will return a list of the node's
-      file resources.
-
+    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 859946623..d77525ba8 100644
--- a/lib/puppet/face/certificate.rb
+++ b/lib/puppet/face/certificate.rb
@@ -1,76 +1,120 @@
 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"
-  description <<-EOT
+  description <<-'EOT'
     This face 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,
+    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
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    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:
 
     * `ca`
     * `file`
     * `rest`
   EOT
 
   option "--ca-location LOCATION" do
     summary "The certificate authority to query"
-    description <<-EOT
+    description <<-'EOT'
       Whether to act on the local certificate authority or one provided by a
       remote puppet master. Allowed values are 'local' and 'remote.'
     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"
-    description <<-EOT
+    summary "Generate a new certificate signing request for HOST."
+    arguments "<host>"
+    returns "Nothing."
+    description <<-'EOT'
       Generates and submits a certificate signing request (CSR) for the
-      provided host identifier. This CSR will then have to be signed by a user
+      specified host. This CSR will then have to be signed by a user
       with the proper authorization on the certificate authority.
 
-      Puppet agent handles CSR submission automatically. This action is
+      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"
+    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.
+    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"
+    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.
+    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.arguments "<host>"
+  find.returns <<-'EOT'
+    An x509 SSL certificate. You will usually want to render this as a
+    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.arguments "<host>"
+  destroy.returns "Nothing."
+  destroy.description <<-'EOT'
+    Deletes a certificate. This action currently only works with a local CA.
+  EOT
+
+  get_action(:search).summary "Invalid for this face."
+  get_action(:save).summary "Invalid for this face."
 end
diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb
index cc6021517..de52b7fb7 100644
--- a/lib/puppet/face/certificate_request.rb
+++ b/lib/puppet/face/certificate_request.rb
@@ -1,32 +1,54 @@
 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
+  description <<-'EOT'
     Retrieves and submits certificate signing requests (CSRs). Invoke
-    `search` with an unread key to retrieve all outstanding 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.
   EOT
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    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:
 
     * `ca`
     * `file`
     * `rest`
   EOT
-  examples <<-EOT
-    Retrieve all CSRs from the local CA:
 
-        puppet certificate_request search no_key --terminus ca
+  # Per-action doc overrides
+  get_action(:destroy).summary "Invalid for this face."
 
+  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').
+  EOT
+  get_action(:find).examples <<-'EOT'
     Retrieve a single CSR from the puppet master's CA:
 
-        puppet certificate_request find mynode.puppetlabs.lan --terminus rest
+    $ 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').
   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:
+
+    $ puppet certificate_request search x --terminus ca
+  EOT
+
+  get_action(:save).summary "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 2722b20f2..db00ea3ca 100644
--- a/lib/puppet/face/certificate_revocation_list.rb
+++ b/lib/puppet/face/certificate_revocation_list.rb
@@ -1,30 +1,48 @@
 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
+  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.
   EOT
-  notes <<-EOT
-    Although the find action must be given an argument, this argument is
-    never read, and can contain the descriptive text of your choice.
-
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    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:
 
     * `ca`
     * `file`
     * `rest`
   EOT
-  examples <<-EXAMPLES
-    Retrieve the CRL:
 
-        puppet certificate_revocation_list find crl
+  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').
+  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.
+  EOT
+
+  get_action(:search).summary "Invalid for this face."
+  get_action(:save).summary "Invalid for this face."
 end
diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb
index 9ca41085e..6e5bff071 100644
--- a/lib/puppet/face/config.rb
+++ b/lib/puppet/face/config.rb
@@ -1,48 +1,47 @@
 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 configuration options"
+  summary "Interact with Puppet's configuration options."
 
   action(:print) do
-    summary "Examine Puppet's current configuration options"
-    description <<-EOT
+    summary "Examine Puppet's current configuration options."
+    arguments "(all | <option> [<option> ...]"
+    returns <<-'EOT'
+      When called with one option: a single value.
+
+      When called with "all" or multiple options: a list of options and
+      their values.
+    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 agent --configprint`.
+      `puppet <subcommand> --configprint`.
     EOT
-    notes <<-EOT
-      The return data of this action varies depending on its arguments. When
-      called with "all," `print` will return a complete list of option names
-      and values. When called with a single configuration option name, it will
-      return the value of that option. When called with a list of
-      configuration option names, it will return the corresponding list of
-      option names and values.
-
-      By default, this action retrieves its configuration information in agent
-      mode. To examine the master's configuration, supply Puppet's global
-      `--mode master` option. To examine configurations from a specific
-      environment, you can use the `--environment` option.
+    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
+    examples <<-'EOT'
       Get puppet's runfile directory:
 
-          puppet config print rundir
+      $ 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)"
+      $ 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 ecf4e371e..d7ddf1d51 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -1,49 +1,88 @@
 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, store, and view facts."
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  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.
+
+    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.
+  EOT
+  notes <<-'EOT'
+    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:
 
     * `active_record`
     * `couch`
     * `facter`
     * `inventory_active_record`
     * `memory`
     * `network_device`
     * `rest`
     * `yaml`
   EOT
 
+  find = get_action(:find)
+  find.summary "Retrieve a host's facts."
+  find.arguments "<host>"
+  find.returns "A Puppet::Node::Facts object."
+  find.notes <<-'EOT'
+    When using the `facter` terminus, the host argument is essentially 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."
+
   action(:upload) do
-    summary "Upload our facts to the puppet master."
-    description <<-EOT
-      Retrieves facts for the local system and saves them to the puppet master
-      server. This is essentially a shortcut action: it calls the `find`
-      action with the facter terminus, then passes the returned facts object
-      to the `save` action, which uses the rest terminus.
+    summary "Upload local facts to the puppet master."
+    description <<-'EOT'
+      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
-    notes <<-EOT
-      This action uses the save action, which requires the puppet master's
-      auth.conf to allow save access to the `facts` REST terminus. See
-      `http://docs.puppetlabs.com/guides/rest_auth_conf.html` for more details.
+    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 707ceafd4..70b44c38f 100644
--- a/lib/puppet/face/file.rb
+++ b/lib/puppet/face/file.rb
@@ -1,21 +1,54 @@
 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"
-  # TK this needs a description of how to find files in a filebucket, and
-  # some good use cases for retrieving/storing them. I can't write either
-  # of these yet.
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  description <<-'EOT'
+    This face 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'
+    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:
 
     * `file`
     * `rest`
+
+    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
+    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."
+
   set_indirection_name :file_bucket_file
 end
diff --git a/lib/puppet/face/file/download.rb b/lib/puppet/face/file/download.rb
index f5413d493..8a300fbf1 100644
--- a/lib/puppet/face/file/download.rb
+++ b/lib/puppet/face/file/download.rb
@@ -1,36 +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"
+    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.
+    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/file/store.rb b/lib/puppet/face/file/store.rb
index 4c9523b6c..97dbd86b4 100644
--- a/lib/puppet/face/file/store.rb
+++ b/lib/puppet/face/file/store.rb
@@ -1,12 +1,21 @@
 # Store a specified file in our filebucket.
 Puppet::Face.define(:file, '0.0.1') do
   action :store do |*args|
+    summary "Store a file in the local filebucket."
+    arguments "<file>"
+    returns "Nothing."
+    examples <<-EOT
+      Store a file:
+
+      $ puppet file store /root/.bashrc
+    EOT
+
     when_invoked do |path, options|
       file = Puppet::FileBucket::File.new(File.read(path))
 
       Puppet::FileBucket::File.indirection.terminus_class = :file
       Puppet::FileBucket::File.indirection.save file
       file.checksum
     end
   end
 end
diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb
index aef917447..7a382b8c9 100644
--- a/lib/puppet/face/help.rb
+++ b/lib/puppet/face/help.rb
@@ -1,124 +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 "Displays help about puppet subcommands"
+  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."
+    examples <<-'EOT'
+      Get help for an action:
+
+      $ puppet help
+    EOT
 
     option "--version VERSION" do
-      summary "which version of the interface to show help for"
+      summary "The version of the face 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"
       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"
           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 c26958a35..aab7f2564 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -1,48 +1,22 @@
-puppet <%= face.name %><%= action.default? ? '' : " #{action.name}" %>(1) -- <%= action.summary || face.summary %>
-<%= '=' * (_erbout.length - 1) %>
+puppet <%= face.name %><%= action.default? ? '' : " #{action.name}" %> - <%= action.summary || face.summary %>
 
 % if action.synopsis
-SYNOPSIS
---------
-
-<%= action.synopsis %>
+usage: <%= action.synopsis %>
 
 % end
-% if action.description
-DESCRIPTION
------------
-<%= action.description %>
+% if action.description or action.short_description
+<%= action.short_description %>
 
 %end
 % unless action.options.empty?
-OPTIONS
--------
+OPTIONS:
 %   action.options.sort.each do |name|
 %     option = action.get_option name
-<%= "  " + option.optparse.join(" |" ) %>
-<%= option.summary %>
-<%= option.description %>
+<%= "  " + option.optparse.join(" |" ) %> - <%= option.summary %>
 
 %   end
 % end
 % if action.examples
-EXAMPLES
---------
+EXAMPLES:
 <%= action.examples %>
 % end
-% if action.notes
-NOTES
------
-<%= action.notes %>
-
-% end
-% unless action.authors.empty?
-AUTHOR
-------
-<%= action.authors.map {|x| " * " + x } .join("\n") %>
-
-%end
-COPYRIGHT AND LICENSE
----------------------
-<%= action.copyright %>
-<%= action.license   %>
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index 67d775ca4..f19ae198f 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -1,23 +1,23 @@
 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
-    Keys are created for you automatically when certificate requests are
-    generated with 'puppet certificate generate'. You should not have to use
-    this action directly from the command line.
+  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.
   EOT
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    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:
 
     * `ca`
     * `file`
   EOT
 
 end
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index be38ad388..c68d71846 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -1,26 +1,50 @@
 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 what Puppet uses to
+  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, additional top-scope variables, and classes.
+    environment, node parameters (exposed in the parser as top-scope
+    variables), and classes.
   EOT
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    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:
 
     * `active_record`
     * `exec`
     * `ldap`
     * `memory`
     * `plain`
     * `rest`
     * `yaml`
   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."
+
+  find = get_action(:find)
+  find.summary "Retrieve a node object."
+  find.arguments "<host>"
+  find.returns <<-'EOT'
+    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:
+
+    $ 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
+  EOT
 end
diff --git a/lib/puppet/face/parser.rb b/lib/puppet/face/parser.rb
index e6a9503dd..8dd3efb75 100644
--- a/lib/puppet/face/parser.rb
+++ b/lib/puppet/face/parser.rb
@@ -1,31 +1,33 @@
 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"
+  summary "Interact directly with the parser."
 
   action :validate do
-    summary "Validate the syntax of one or more Puppet manifests"
-    description <<-EOT
+    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
     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 969d42389..541468d39 100644
--- a/lib/puppet/face/plugin.rb
+++ b/lib/puppet/face/plugin.rb
@@ -1,47 +1,54 @@
 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
+  summary "Interact with the Puppet plugin system."
+  description <<-'EOT'
     This face provides network access to the puppet master's store of
-    plugins. It is intended for use in other faces, rather than for direct
-    command line access.
+    plugins.
   EOT
-  notes <<-EOT
+  notes <<-'EOT'
     The puppet master can serve 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.
   EOT
 
   action :download do
-    summary "Download plugins from the configured master"
-    returns <<-EOT
-      An array containing the files actually downloaded. If all files
-      were in sync, this array will be empty.
+    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.
     EOT
-    notes "This action modifies files on disk without returning any data."
-    examples <<-EOT
+    returns <<-'EOT'
+      A display-formatted list of the files downloaded. If all plugin
+      files were in sync, this list will be empty.
+    EOT
+    notes "This action modifies files on disk."
+    examples <<-'EOT'
       Retrieve plugins from the puppet master:
 
-          Puppet::Face[:plugin, '0.0.1'].download
+      $ 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 c8549b14f..a5718bc0c 100644
--- a/lib/puppet/face/report.rb
+++ b/lib/puppet/face/report.rb
@@ -1,47 +1,65 @@
 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"
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    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:
 
     * `processor`
     * `rest`
     * `yaml`
   EOT
 
+  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.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"
-    description <<-EOT
+    description <<-'EOT'
       This action is essentially a shortcut and wrapper for the `save` action
-      with a terminus of `rest`. It also can provide additional details in the
+      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.
     EOT
-    examples <<-EOT
+    examples <<-'EOT'
       From secret_agent.rb:
-          Puppet::Face[:plugin, '0.0.1'].download
-
-          facts   = Puppet::Face[:facts, '0.0.1'].find(certname)
-          catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
-          report  = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
 
+          # ...
+          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 87e587624..593776e53 100644
--- a/lib/puppet/face/resource.rb
+++ b/lib/puppet/face/resource.rb
@@ -1,23 +1,59 @@
 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"
-  description <<-EOT
+  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.
   EOT
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    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:
 
     * `ral`
     * `rest`
   EOT
 
-  examples "TK we really need some examples for this one."
+  get_action(:destroy).summary "Invalid for this face."
+
+  search = get_action(:search)
+  search.summary "Get all resources of a single type."
+  search.arguments "<resource_type>"
+  search.returns "An array of 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.arguments "<type>/<title>"
+  find.returns "A 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.arguments "<resource_object>"
+  save.returns "The same resource object passed."
+  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 77ccefa8f..3973eb3b8 100644
--- a/lib/puppet/face/resource_type.rb
+++ b/lib/puppet/face/resource_type.rb
@@ -1,17 +1,78 @@
 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 resource types, classes, and nodes from all manifests"
-  description "TK I have no idea what this does."
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  summary "View classes, defined resource types, and nodes from all manifests"
+  description <<-'EOT'
+    This face 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
+  notes <<-'EOT'
+    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:
 
     * `parser`
     * `rest`
   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:
+
+    * `file` (a string)
+    * `name` (a string)
+    * `type` (<hostclass>, <definition>, or <node>)
+    * `line` (an integer)
+
+    It may also include the following keys:
+
+    * `parent`    (<name_of_resource_collection>)
+    * `arguments` (a hash of parameters and default values)
+    * `doc`       (a string)
+
+    RENDERING ISSUES: yaml and string output for this indirection are
+    currently unusable; use json 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`.)
+
+    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 c8c8e6629..105850cd3 100644
--- a/lib/puppet/face/secret_agent.rb
+++ b/lib/puppet/face/secret_agent.rb
@@ -1,39 +1,53 @@
 require 'puppet/face'
 
 Puppet::Face.define(:secret_agent, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Provides agent-like behavior, with no plugin downloading or reporting"
-  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 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 drastically different
-    application logic.
+  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.
   EOT
 
   action(:synchronize) do
-    summary "Retrieve and apply a catalog from the puppet master"
-    description <<-EOT
-      This action mimics the behavior 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.
+    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.
+    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
+      <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 6a29debdd..08379550c 100644
--- a/lib/puppet/face/status.rb
+++ b/lib/puppet/face/status.rb
@@ -1,30 +1,47 @@
 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"
-  description <<-EOT
-    This subcommand is only useful for determining whether a puppet master
-    server (or an agent node, if puppet was started with the `--listen`
-    option) is responding to requests.
-
-    Only the `find` action is valid. If the server is responding to
-    requests, `find` will retrieve a status object; if not, the connection
-    will be refused. When invoked with the `local` terminus, `find` will
-    always return true.
-
-    If you wish to query a server other than the master configured in
-    puppet.conf, you must set the `--server` and `--masterport` options on
-    the command line.
-  EOT
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  summary "View puppet server status."
+  notes <<-'EOT'
+    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:
 
     * `local`
     * `rest`
   EOT
+
+  get_action(:destroy).summary "Invalid for this face."
+  get_action(:save).summary "Invalid for this face."
+  get_action(:search).summary "Invalid for this face."
+
+  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.description <<-'EOT'
+    Checks whether a Puppet server is properly receiving and processing
+    REST 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.
+  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 1371c647e..756306a2f 100644
--- a/lib/puppet/indirector/face.rb
+++ b/lib/puppet/indirector/face.rb
@@ -1,122 +1,125 @@
 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 for this action."
     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.
+      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"
+    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"
+    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 modify an object"
-    notes <<-EOT
-      Save actions cannot currently be invoked from the command line, and are
-      for API use only.
+    summary "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.
     EOT
     when_invoked { |key, options| call_indirection_method(:save, key, options) }
   end
 
   action :search do
-    summary "Search for an object"
+    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"
+    summary "Print the default terminus class for this face."
     description <<-EOT
-      TK So this is per-face, right? No way to tell what the default terminus
-      is per-action, for subsystems that switch to REST for save but query
-      locally for find?
+      Prints the default terminus class for this face. Note that
+      different run modes may have different default terminuses.
     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