docs updates

README.md

@@ -50,33 +50,12 @@ For example, on macOS with Homebrew: `brew install cmake pkg-config` and on Ubun
 ## Usage
 
 - `licensed list`: Output enumerated dependencies only.
-
 - `licensed cache`: Cache licenses and metadata.
-
 - `licensed status`: Check status of dependencies' cached licenses. For example:
-
-```
-$ bundle exec licensed status
-Checking cached dependency records for licensed
-..F.F....F...
-
-Errors:
-
-* bundler.pathname-common_prefix
-  filename: /Users/jonabc/github/licensed/.licenses/bundler/pathname-common_prefix.dep.yml
-    - license needs reviewed: other
-
-* bundler.bundler
-  filename: /Users/jonabc/github/licensed/.licenses/bundler/bundler.dep.yml
-    - cached dependency record not found  
-
-* bundler.addressable
-  filename: /Users/jonabc/github/licensed/.licenses/bundler/addressable.dep.yml
-    - license needs reviewed: apache-2.0
-```
-
 - `licensed version`: Show current installed version of Licensed. Aliases: `-v|--version`
 
+See the [commands documentation](./docs/commands.md) for additional documentation, or run `licensed -h` to see all of the current available commands.
+
 ### Configuration
 
 All commands, except `version`, accept a `-c|--config` option to specify a path to a configuration file or directory.
@@ -139,6 +118,12 @@ if Licensed::Shell.tool_available?('bundle')
 end
 ```
 
+See the [documentation on adding new sources](./docs/adding_a_new_source.md) for more information.
+
+#### Adding Commands
+
+See the [documentation on commands](./docs/commands.md) for information about adding a new CLI command.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/github/licensed. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org/) code of conduct.  See [CONTRIBUTING](CONTRIBUTING.md) for more details.

docs/adding_a_new_source.md

@@ -20,7 +20,21 @@ This section covers the `Licensed::Sources::Source#enabled?` method.  This metho
 whether `Licensed::Source::Sources#enumerate_dependencies` should be called on the current dependency source object.
 
 Determining whether dependencies should be enumerated depends on whether all the tools or files needed to find dependencies are present.
-For example, to enumerate `npm` dependencies the `npm` CLI tool must be reachable and a `package.json` file needs to exist in the licensed app's configured [`source_path`](./configuration.md#configuration-paths).
+For example, to enumerate `npm` dependencies the `npm` CLI tool must be found with `Licensed::Shell.tool_available?` and a `package.json` file needs to exist in the licensed app's configured [`source_path`](./configuration.md#configuration-paths).
+
+#### Gating functionality when required tools are not available.
+
+When adding new dependency sources, ensure that `script/bootstrap` scripting and tests are only run if the required tooling is available on the development machine.
+
+* See `script/bootstrap` for examples of gating scripting based on whether tooling executables are found.
+* Use `Licensed::Shell.tool_available?` when writing test files to gate running a test suite when tooling executables aren't available.
+```ruby
+if Licensed::Shell.tool_available?('bundle')
+  describe Licensed::Source::Bundler do
+    ...
+  end
+end
+```
 
 ## Enumerating dependencies
 

docs/commands.md

@@ -0,0 +1,81 @@
+# Commands
+
+Run `licensed -h` to see help content for running licensed commands.
+
+## `list`
+
+Running the list command finds the dependencies for all sources in all configured applications.  No additional actions are taken on each dependency.
+
+## `cache`
+
+The cache command finds all dependencies and ensures that each dependency has an up-to-date cached record.
+
+Dependency records will be saved if:
+1. The `force` option is set
+2. No cached record is found
+3. The cached record's version is different than the current dependency's version
+   - If the cached record's license text contents matches the current dependency's license text then the `license` metadata from the cached record is retained for the new saved record.
+
+After the cache command is run, any cached records that don't match up to a current application dependency will be deleted.
+
+## `status`
+
+The status command finds all dependencies and checks whether each dependency has a valid cached record.
+
+A dependency will fail the status checks if:
+1. No cached record is found
+2. The cached record's version is different than the current dependency's version
+3. The cached record doesn't contain any license text
+4. The cached record's `license` metadata doesn't match an `allowed` license from the dependency's application configuration.
+
+## `version`
+
+Displays the current licensed version.
+
+# Adding a new command
+
+## Implement new `Command` class
+
+Licensed commands inherit and override the [`Licensed::Sources::Command`](../lib/licensed/commands/command.rb) class.
+
+#### Required method overrides
+1. `Licensed::Commands::Command#evaluate_dependency`
+   - Runs a command execution on an application dependency.
+   
+The `evaluate_dependency` method should contain the specific command logic.  This method has access to the application configuration, dependency source enumerator and dependency currently being evaluated as well as a reporting hash to contain information about the command execution.
+
+#### Optional method overrides
+
+The following methods break apart the different levels of command execution.  Each method wraps lower levels of command execution in a corresponding reporter method.
+
+1. `Licensed::Commands::Command#run`
+   - Runs `run_app` for each application configuration found.  Wraps the execution of all applications in `Reporter#report_run`.
+2. `Licensed::Commands::Command#run_app`
+   - Runs `run_source` for each dependency source enumerator enabled for the application configuration.  Wraps the execution of all sources in `Reporter#report_app`.
+3. `Licensed::Commands::Command#run_source`
+   - Runs `run_dependency` for each dependency found in the source.  Wraps the execution of all dependencies in `Reporter#report_source`.
+4. `Licensed::Commands::Command#run_dependency`
+   - Runs `evaluate_dependency` for the dependency.  Wraps the execution of all dependencies in `Reporter#report_dependency`.
+
+As an example, `Licensed::Commands::Command#run_app` calls `Reporter#report_app` to wrap every call to `Licensed::Commands::Command#run_source`.
+
+##### Overriding optional methods
+
+The `run` methods can be overridden to provide additional reporting data or functionality.  Overriding a method should call the original method with a block for the additional logic.
+
+```ruby
+def run_app(app)
+  super do |report|
+    result = yield report
+    
+    # do other thing
+    call_additional_functionality(app)
+    
+    # add reporting information
+    report["result"] = result
+    
+    # return the result
+    result
+  end
+end
+```