Docs/issues README review and GemDocs links (#30)

* Adds dynamic (version-specific) URLs for GemDocs documentation links.

* Cleans up numerous typos.

* Fixes markup syntax errors.

* Removes literals from reference term listings.

* Clarifies --tags usage.

Author: briandominick

README.adoc

@@ -3,7 +3,7 @@
 :toclevels: 3
 :this_prod_vrsn: 0.2.0
 :next_prod_vrsn: 0.3.0
-:docker_base_command: docker run -it --rm -v $(pwd):/workdir -e GITHUB_TOKEN=$ISSUER_API_TOKEN docopslab/issuer
+:docker_base_command: docker run -it --rm -v $(pwd):/workdir -e ISSUER_API_TOKEN=$GITHUB_TOKEN docopslab/issuer
 :append_or_impose: Prepend items with `+` to indicate they should be appended to existing labels. Items without `+` will only be used for issues with no `tags` designated.
 ifdef::env-github[]
 :icons: font
@@ -22,7 +22,7 @@ _Issuer_ lets you define all your work tickets in one place as YAML, apply defau
 * *Configurable defaults* and label application
 * *Environment variable support* for authentication
 * *Issue validation* with helpful error messages
-* *GitHub API integration* via Octokit
+* *GitHub API integration*
 
 Future plans include extending this capability to *Jira*, *GitLab* Issues, GitHub *Projects*, and other services.
 
@@ -57,15 +57,18 @@ With Docker installed and running...
 For actual issue creation, use something like:
 
 [.prompt,subs=+attributes]
- {docker_base_command} your-issues.yml --dry
+ {docker_base_command} your-issues.yml
 
 The above command:
 
 * mounts your local directory to be readable by the Docker container
-* passes your GitHub access token environment variable into the container (`$ISSUER_API_TOKEN` could be `$ISSER_GITHUB_TOKEN`, `$GITHUB_ACCESS_TOKEN`, or `$GITHUB_TOKEN`).
+* passes your GitHub access token environment variable into the container (`$ISSUER_API_TOKEN` could be `$ISSUER_GITHUB_TOKEN`, `$GITHUB_ACCESS_TOKEN`, or `$GITHUB_TOKEN`).
+* connects to GitHub and creates issue entries one at a time from `your-issues.yml`
 
 Everything after `docopslab/issuer` accepts the standard arguments and options of the issuer CLI.
 
+See <<usage>> for more.
+
 [[docker-alias]]
 ==== Alias the Docker Command
 
@@ -82,7 +85,7 @@ Reload your shell configuration for the alias to take effect:
 
 === For Ruby Users
 
-If you have Ruby on your workstation, there are two common ways to install thi gem.
+If you have Ruby on your workstation, there are two common ways to install this gem.
 
 ==== Global Installation
 
@@ -91,7 +94,7 @@ If you have Ruby on your workstation, there are two common ways to install thi g
 
 Then you can use the `issuer` command from anywhere in your system.
 
-==== Local/Applicaition Installation
+==== Local/Application Installation
 
 Add this line to your Gemfile:
 
@@ -106,14 +109,14 @@ And then execute:
 
 Now you can use `bundle exec issuer` to perform operations inside the project directory.
 
-
+[[usage]]
 == Usage
 
 Once installed, you can start using `issuer` to create issues in GitHub.
 
 === Quickstart Overview
 
-The following steps assume the gem is either installed globally or `issuer` is <<docker-alias,established as an alias>>.
+The following steps assume the gem is either installed globally or `issuer` is <<docker-alias,established as an alias>> (Docker method).
 For Ruby Bundler usage, prepend `bundle exec ` and for un-aliased Docker usage, prepend `{docker_base_command}`.
 
 . Prepare your issue definitions in an IMYML file (see <<imyml-format,examples and docs>> below).
@@ -122,7 +125,7 @@ For Ruby Bundler usage, prepend `bundle exec ` and for un-aliased Docker usage,
 +
  issuer example.yml --dry
 
-. Establish a Personal Access Token for GitHub (see <<authentication,Authentication>> below).
+. Establish a Personal Access Token for GitHub and store it as an environment variable (see <<authentication>> below).
 
 . Post issues to GitHub:
 +
@@ -170,7 +173,7 @@ issues: # block for listing issues to post to cloud
     # This is the default text that will appear if an issue record is a _stub_ and no `body` field is designated.
     # ---
     # This issue was automatically generated by issuer.
-  - summ: Documentaton issue
+  - summ: Documentation issue
     tags: [-needs:docs] # skip the default needs:docs label
 ----
 
@@ -207,93 +210,95 @@ The IMYML format will be standardized and formally specified in a future release
 [[imyml-ref]]
 ==== IMYML Properties Reference
 
-`$meta`::
+$meta::
 Optional block for establishing operation-wide modes and settings.
 
-`$meta.proj`:::
+$meta.proj:::
 (String)
 Designates the target project/repository.
 
-`$meta.defaults`:::
-Designates the default values to use for any issue record that does not specify a value for a given property.
+$meta.defaults:::
+Properties in this block establish the default values to be used for any issue record that does not specify a value for the given property.
 
-`$meta.defaults.vrsn`::::
+$meta.defaults.vrsn::::
 (String)
 Sets default version or milestone for all issues.
 
-`$meta.defaults.user`::::
+$meta.defaults.user::::
 (String)
 Sets default assignee (GitHub username).
 
-`$meta.defaults.type`::::
+$meta.defaults.type::::
 (String)
 Sets default issue type to apply to all issues when no `type` property is specified in the issue record.
 
-`$meta.defaults.tags`::::
+$meta.defaults.tags::::
 (Array):
 Labels to append to issues (comma-separated).
 {append_or_impose}
 
-`$meta.defaults.stub`::::
+$meta.defaults.stub::::
 (Boolean)
 Establishes the state whether to insert stub texts (`body` / `head` / `tail`).
 
-`$meta.defaults.body`::::
+$meta.defaults.body::::
 (String)
 Sets default body text to apply to all issues when no `body` property is specified in the issue record.
 
-`$meta.defaults.head`::::
+$meta.defaults.head::::
 (String)
 Sets default text to insert before the body of all issues for which `stub`.
 
-`$meta.defaults.tail`::::
+$meta.defaults.tail::::
 (String)
 Sets default text to insert after the body of all issues for which `stub`.
 
-`issues`::
-(Array) Tabular listing of issue records as Array itmes.
+issues::
+(Array)
+Tabular listing of *issue records* as Array items.
 If an item is Scalar (not a Map with named keys), the value must be a String and it will be treated as the `summ` (summary/title) property.
 +
 Otherwise, any `issues` Array items must be Map-formatted "`dictionaries`" with the following properties:
 
-`summ`:::
+summ:::
 (String, *required*)
 A one-line title or summary of the issue.
 
-`body`:::
+body:::
 (String)
 The main body or description text for the issue.
 Defaults to `$meta.defaults.body` if `stub == true` for the record, in which case, upon submission, will also incorporate any values for `$meta.defaults.head` and `$meta.defaults.tail`.
 
-`vrsn`:::
+vrsn:::
 (String)
 The milestone associated with the issue.
 +
 Defaults to `$meta.defaults.vrsn` or else `null`.
 
-`type`:::
+type:::
 (String)
 The type of issue, which must already be registered in the target project or repository.
 Defaults to `$meta.defaults.type` or else `null`.
 
-`tags`:::
+tags:::
 (Array of Strings)
 A listing of specific labels to assign to the issue.
 +
 Supports special prefix notation for label management:
 +
-* Regular labels (e.g., `bug`, `priority:high`) are applied based on default tag logic
-* Append labels (e.g., `+urgent`) are always applied to all issues
-* Removal labels (e.g., `-needs:docs`) remove the specified label from the default/appended labels list
+* Regular labels (example: `bug`, `priority:high`) are applied based on default tag logic
+* Append labels (example: `+urgent`) are always applied to all issues
+* Removal labels (example: `-needs:docs`) remove the specified label from the default/appended labels list
 +
 Example: `tags: [documentation, +critical, -needs:review]` would add `documentation` and `critical` labels while removing any `needs:review` label from defaults.
 
-`user`:::
+user:::
 (String)
 The system username of the person or bot to which the ticket is assigned.
 
-`stub [true+++*+++|false]`:::
+stub:::
 (Boolean)
+Accepts `true` or `false`.
 Whether to treat the issue as a stub entry, meaning prepend any `$meta.defaults.head` text or append any `$meta.defaults.tail` text, and in case the ticket has no `body` property, insert the text of `$meta.defaults.body`.
 
 [[cli-usage]]
@@ -326,21 +331,21 @@ IMYML file path (alternative to positional argument).
 The target project (org/repo or user/repo format for GitHub).
 
 --vrsn _VERSION_::
-Argues default milestone for all issues.
+Sets default milestone for all issues.
 
 --user _USERNAME_::
-Argues default assignee (GitHub username).
+Sets default assignee (GitHub username).
 
 --tags _TAG_[,_TAG_]::
-Argues labels to impose or add issues (comma-separated).
+Sets labels to apply to issues (comma-separated).
 {append_or_impose}
 
 --stub [_true_+++*+++|_false_]::
 Whether to treat all issues as stubs, meaning prepend any `$meta.defaults.head` text or append any `$meta.defaults.tail` text, and in case the ticket has no `body` property, insert the text of `$meta.defaults.body`.
 
 ==== Mode Options
 
---dry::
+--dry, --dry-run::
 Dry-run: print actions but do not post to GitHub.
 
 --auto-versions, --auto-milestones::
@@ -352,7 +357,7 @@ Automatically create missing labels/tags without prompting for confirmation.
 --auto-metadata::
 Automatically create all missing metadata (milestones and labels) without prompting for confirmation. Equivalent to using both `--auto-versions` and `--auto-tags`.
 
---help::
+--help, -h::
 Prints the usage screen.
 
 --version::
@@ -373,14 +378,21 @@ The application will check for environment variables in the following order:
 To *create and set a token*:
 
 . In the GitHub Web interface, go to *Settings* (under your user icon) → *Developer Settings* (bottom of left menu) → *Personal Access Tokens* → *Fine-grained tokens*.
-. Generate a new token with access to *All repositoriess* or any *Select repositories* you wish to post to, and include read/write permissions GitHub Issues (under *Repository permissions*).
+. Generate a new token with access to *All repositories* or any *Select repositories* you wish to post to, and include read/write permissions GitHub Issues (under *Repository permissions*).
 . Copy the token and set it as an environment variable.
 +
 .Example
  export ISSUER_API_TOKEN=github_pat_xxxxxxxxxxxxxxxxxxxxxxxx
 +
 Where `github_pat_xxxxxxxxxxxxxxxxxxxxxxxx` is your actual token.
 
+If your GitHub token is stored under *any other name*, you can alias it inline by prepending to your `issuer` command.
+For example:
+
+ ISSUER_API_TOKEN=$MY_GITHUB_API_KEY issuer my-issues.yml
+
+When using Docker, you can pass any such key into the container this way, using the `-e` option: `-e ISSUER_API_TOKEN=$MY_GITHUB_API_KEY`.
+
 
 == Advanced Usage
 
@@ -449,7 +461,7 @@ I will probably adapt the API to other systems in future releases, and I welcome
 
 === Methodology Confession
 
-I should note up front that this is the closest I have come to "`vibe coding`" anything bigger than a local script, let alone a shippable production code.
+I should note up front that this is the closest I have come to "`vibe coding`" anything bigger than a local script, let alone shippable production code.
 Nevertheless, I intervened to make substantial and specific changes at least 100 times, and I rearranged major aspects of the codebase.
 
 I designed the IMYML format and the CLI up front, then I let Claud 4 (via GH Copilot) draft most of the code.
@@ -504,10 +516,10 @@ bundle exec rspec --pattern "*ops*"
 
 The `pr_test` task runs the exact same tests that GitHub Actions runs for pull requests:
 
-* **RSpec Tests**: All unit tests (`bundle exec rake spec`)
-* **CLI Tests**: Command-line interface functionality tests
-* **YAML Validation**: Validates all example YAML files
-* **Documentation Quality**: Vale linting on all documentation files
+* *RSpec Tests*: All unit tests (`bundle exec rake spec`)
+* *CLI Tests*: Command-line interface functionality tests
+* *YAML Validation*: Validates all example YAML files
+* *Documentation Quality*: Vale linting on all documentation files
 
 This ensures you can validate your changes locally before pushing to GitHub.
 
@@ -553,6 +565,19 @@ The GitHub API test suite validates:
 * Automation flags (`--auto-metadata`, `--auto-versions`, etc.)
 * Error handling and edge cases
 
+=== API Reference
+
+For detailed API documentation, see the automatically generated documentation at https://gemdocs.org/gems/issuer/{this_prod_vrsn}[GemDocs].
+
+The API reference includes:
+
+* Complete class and method documentation
+* Method signatures and parameters
+* Return types and examples
+* Internal implementation details
+
+This documentation is automatically updated with each gem release.
+
 [[contributing]]
 === Contributing
 

issuer.gemspec

@@ -15,6 +15,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/DocOps/issuer"
   spec.metadata["changelog_uri"] = "https://github.com/DocOps/issuer/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://gemdocs.org/gems/issuer/#{Issuer::VERSION}"
 
   # Specify which files should be added to the gem when it is released.
   spec.files = Dir['lib/**/*.rb'] +

lib/issuer/cli.rb

@@ -15,7 +15,7 @@ def self.exit_on_failure?
     class_option :proj, type: :string, desc: 'Override $meta.proj (org/repo)'
     class_option :vrsn, type: :string, desc: 'Default version for all issues'
     class_option :user, type: :string, desc: 'Default assignee (GitHub username)'
-    class_option :tags, type: :string, desc: 'Comma-separated extra labels for all issues'
+    class_option :tags, type: :string, desc: 'Comma-separated default or appended (+) labels for all issues'
     class_option :stub, type: :boolean, desc: 'Enable stub mode for all issues'
     class_option :dry, type: :boolean, default: false, aliases: ['--dry-run'], desc: 'Print issues, don\'t post'
     class_option :tokenv, type: :string, desc: 'Name of environment variable containing GitHub token'
@@ -167,7 +167,7 @@ def self.show_help
       Issue Default Options:
         --vrsn VERSION           #{self.class_options[:vrsn].description}
         --user USERNAME          #{self.class_options[:user].description}
-        --tags tag1,tag2         #{self.class_options[:tags].description}
+        --tags tag1,+tag2        #{self.class_options[:tags].description}
         --stub                   #{self.class_options[:stub].description}
 
       Site Options: