releasehx 0.1.0

data/lib/releasehx/configuration.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'psych'
+require_relative '../schemagraphy/loader'
+
+module ReleaseHx
+  # Manages the application's configuration by loading and merging settings
+  #  from a definition file and a user-provided configuration file.
+  class Configuration
+    # Public: Global gem attributes copied from the generated README attributes.
+    #
+    # This constant is used to locate the internal schema/definition file and
+    # to determine sane defaults for the user's configuration path.
+    # @return [Hash] Global attributes for the gem.
+    GEM_GLOBALS = ReleaseHx::ATTRIBUTES[:globals].freeze
+    GEM_ROOT_PATH = File.expand_path('../..', __dir__).freeze
+    # @return [String] The path to the internal configuration definition file.
+    CONFIG_DEF_PATH = File.join(
+      GEM_ROOT_PATH,
+      GEM_GLOBALS['gem_config_definition_path']).freeze
+    # @return [String] The default path to the user's configuration file.
+    DEFAULT_CONFIG_PATH = File.join(
+      File.expand_path('.'),
+      GEM_GLOBALS['app_default_config_path'] || 'releasehx.yml').freeze
+
+    # @param settings [Hash] A hash of configuration settings.
+    def initialize settings = {}
+      @settings = settings
+    end
+
+    # Loads and merges the user configuration with the internal definition/schema
+    #  and performs the SGYML precompilation and staged rendering.
+    #
+    # This method returns a fully-resolved Configuration object suitable for use across the application.
+    #
+    # @param user_config_path [String] Path to the user's config file (defaults to app default).
+    # @param definition_path [String] Path to the internal schema/definition file.
+    # @return [Configuration] The final, merged configuration object.
+    def self.load user_config_path = DEFAULT_CONFIG_PATH, definition_path = CONFIG_DEF_PATH
+      ReleaseHx.logger.debug "Loading configuration from: #{user_config_path}"
+
+      # Use SchemaGraphy to load config definition with resolved attributes
+      attrs = ReleaseHx::ATTRIBUTES[:globals]
+      definition = SchemaGraphy::Loader.load_yaml_with_attributes(definition_path, attrs)
+      SchemaGraphy::SchemaUtils.crawl_meta(definition, 'history.head')
+
+      user_config = File.exist?(user_config_path) ? SchemaGraphy::Loader.load_yaml_with_tags(user_config_path) : {}
+      merged_settings = apply_schema(definition['properties'], user_config)
+      config = new(merged_settings)
+
+      ReleaseHx::SgymlHelpers.precompile_from_schema!(
+        config.settings,
+        definition, # should contain $schema or be the schema
+        scope: { 'config' => config.settings })
+      ReleaseHx::SgymlHelpers.render_stage_fields!(config.settings, :load)
+
+      config
+    end
+
+    # Provides convenient dot-style access to top-level configuration sections.
+    #
+    # Example:
+    #   config = ReleaseHx::Configuration.load
+    #   source = config.origin['source']
+    #
+    # This method returns the sub-hash stored under the given key name when present;
+    #  otherwise it delegates to the normal method_missing implementation.
+    def method_missing(name, *args, &)
+      # If settings has a key matching the method name, return that sub-hash
+      key_str = name.to_s
+      return settings[key_str] if settings.key?(key_str)
+
+      super
+    end
+
+    # Indicates whether the configuration has a setting for the given key.
+    #
+    # @param name [Symbol] The method name being queried.
+    # @param include_private [Boolean] Whether to include private methods.
+    # @return [Boolean] True if the key exists in settings; otherwise false.
+    def respond_to_missing? name, include_private = false
+      settings.key?(name.to_s) || super
+    end
+
+    # @return [Hash] The underlying hash of configuration settings.
+    attr_reader :settings
+
+    # Provides bracket access to configuration settings.
+    #
+    # Accepts String or Symbol keys and returns the stored value (or nil).
+    #
+    # @param key [String, Symbol] The key to access.
+    # @return [Object] The value associated with the key.
+    def [] key
+      @settings[key.to_s]
+    end
+
+    # @api private
+    # Recursively applies schema defaults and normalizes the user's config.
+    #
+    # Special handling:
+    # - A user value of the literal string "$nil" will explicitly remove the
+    #   property (treated as nil)
+    # - Unknown user-supplied keys are preserved so extensions are not lost
+    #
+    # @param schema_properties [Hash] The properties from the schema.
+    # @param user_hash [Hash] The user's configuration hash.
+    # @return [Hash] The merged hash with defaults applied.
+    def self.apply_schema schema_properties, user_hash
+      final_hash = {}
+
+      (schema_properties || {}).each do |prop_key, prop_def|
+        user_val = user_hash.fetch(prop_key, nil)
+        # Skip processing this property if user explicitly set it to $nil
+        unless user_val.to_s.strip == '$nil'
+          final_val = apply_property(prop_def, user_val)
+          final_hash[prop_key] = final_val
+        end
+      end
+
+      # Preserves extra user-supplied keys that aren't in the definition/schema
+      user_hash.each do |unk_key, unk_val|
+        final_hash[unk_key] = unk_val unless final_hash.key?(unk_key) || unk_val.to_s.strip == '$nil'
+      end
+
+      final_hash
+    end
+
+    # @api private
+    # Applies a single property definition from the schema to a user-supplied value.
+    #
+    # Handles nested objects and array defaults declared in the schema.
+    # User values are preserved unless they are absent (nil) or explicitly set to the literal "$nil" marker.
+    #
+    # @param prop_def [Hash] The property definition from the schema.
+    # @param user_val [Object] The user's value for this property.
+    # @return [Object] The final value for the property.
+    def self.apply_property prop_def, user_val
+      return nil if user_val.to_s.strip == '$nil'
+
+      default_val = prop_def['dflt'] if prop_def.key?('dflt')
+      val = user_val.nil? ? default_val : user_val
+
+      # If this prop has nested "properties", treat as a sub-object
+      if prop_def['properties']
+        val_hash = val.is_a?(Hash) ? val : {}
+        # recursively handle sub-properties
+        val = apply_schema(prop_def['properties'], val_hash)
+      elsif prop_def['type'] == 'ArrayList' && val.nil?
+        # It's an array type with a default and we have no user value
+        val = default_val || []
+      end
+
+      val
+    end
+
+    # List of configuration validation rules used by {validate_config}.
+    # Each rule is a Hash with :scopes, :message and :check (callable).
+    #
+    # The :check callable should raise an ArgumentError when validation fails.
+    #
+    # @return [Array<Hash>] A list of validation rules.
+    VALIDATION_RULES = [
+      {
+        scopes: [:fetch],
+        message: "'origin.href' is required for remote sources",
+        check: lambda { |config|
+          if %w[jira github gitlab].include?(config.origin['source']) && config.origin['href'].to_s.empty?
+            raise ArgumentError, "'origin.href' is required for remote source '#{config.origin['source']}'"
+          end
+        }
+      },
+      {
+        scopes: [:fetch],
+        message: "'rhyml' file must exist at origin.href",
+        check: lambda { |config|
+          if config.origin['source'] == 'rhyml' && !File.exist?(config.origin['href'].to_s)
+            raise ArgumentError, "Missing RHYML file at: #{config.origin['href']}"
+          end
+        }
+      }
+    ].freeze
+
+    # Validates the configuration against rules that match the provided scopes.
+    #
+    # @param config [Configuration] The configuration object to validate.
+    # @param scopes [Array<Symbol>] The scopes to validate against.
+    def self.validate_config config, *scopes
+      scopes.flatten!
+      rules = VALIDATION_RULES.select { |rule| rule[:scopes].intersect?(scopes) }
+      rules.each { |rule| rule[:check].call(config) }
+    end
+
+    # Scans built-in and custom mapping files and produces a unique list of known API source names.
+    # The result always includes the special entries 'rhyml' and 'git'.
+    #
+    # @param config [Configuration] The configuration object.
+    # @return [Array<String>] A unique list of known API source names.
+    def self.known_api_sources config
+      builtin_path = File.join(GEM_ROOT_PATH, 'lib/releasehx/rhyml/mappings')
+      custom_path = File.expand_path(config.paths['mappings_dir'] || '_mappings')
+
+      mapping_files = Dir["#{builtin_path}/*.{yml,yaml}", "#{custom_path}/*-api.yml"]
+
+      base_names = mapping_files.map do |file|
+        base = File.basename(file).sub(/\.ya?ml$/, '')
+        base.sub('-api', '')
+      end
+
+      base_names = base_names.reject { |name| name == 'verb_past_tenses' }
+
+      (base_names + %w[rhyml git]).uniq
+    end
+  end
+end

data/lib/releasehx/generated.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# Auto-generated by Sourcerer::Builder
+
+module ReleaseHx
+  ATTRIBUTES = {:globals=>{"attribute-undefined"=>"drop-line", "attribute-missing"=>"skip", "appendix-caption"=>"Appendix", "appendix-refsig"=>"Appendix", "caution-caption"=>"Caution", "chapter-refsig"=>"Chapter", "example-caption"=>"Example", "figure-caption"=>"Figure", "important-caption"=>"Important", "last-update-label"=>"Last updated", "note-caption"=>"Note", "part-refsig"=>"Part", "prewrap"=>"", "sectids"=>"", "section-refsig"=>"Section", "table-caption"=>"Table", "tip-caption"=>"Tip", "toc-placement"=>"macro", "toc-title"=>"Table of Contents", "untitled-label"=>"Untitled", "version-label"=>"Version", "warning-caption"=>"Warning", "notitle"=>"", "docfile"=>"/home/brian/Documents/work/releasehx/README.adoc", "docdir"=>"/home/brian/Documents/work/releasehx", "docfilesuffix"=>".adoc", "docname"=>"README", "embedded"=>"", "asciidoctor"=>"", "asciidoctor-version"=>"2.0.23", "safe-mode-name"=>"unsafe", "safe-mode-unsafe"=>"", "safe-mode-level"=>0, "max-include-depth"=>64, "user-home"=>"/home/brian", "doctype"=>"article", "htmlsyntax"=>"html", "backend-html5-doctype-article"=>"", "doctype-article"=>"", "backend-html5"=>"", "backend"=>"html5", "outfilesuffix"=>".html", "filetype"=>"html", "filetype-html"=>"", "basebackend-html-doctype-article"=>"", "basebackend-html"=>"", "basebackend"=>"html", "stylesdir"=>".", "iconsdir"=>"./images/icons", "localdate"=>"2026-01-01", "localyear"=>"2026", "localtime"=>"13:06:29 -0500", "localdatetime"=>"2026-01-01 13:06:29 -0500", "docdate"=>"2026-01-01", "docyear"=>"2026", "doctime"=>"04:37:26 -0500", "docdatetime"=>"2026-01-01 04:37:26 -0500", "page-layout"=>"default", "page-permalink"=>"/docs", "page-nav_order"=>"1", "doctitle"=>"ReleaseHx", "docopslab_git_www"=>"https://github.com/DocOps", "this_prod_slug"=>"releasehx", "releasehx_prod_repo"=>"https://github.com/DocOps/releasehx", "releasehx_demo_repo"=>"https://github.com/DocOps/releasehx-demo", "this_prod_repo"=>"https://github.com/DocOps/releasehx", "this_prod_vrsn_major"=>"0", "this_prod_vrsn_minor"=>"1", "this_prod_vrsn_major-minor"=>"0.1", "this_prod_vrsn_patch"=>"0", "this_prod_vrsn"=>"0.1.0", "next_prod_vrsn"=>"0.2.0", "tagline"=>"Generate formatted release histories from Jira, GitHub, GitLab, YAML, or JSON sources.", "description"=>"CLI utility and Ruby API for generating structured release notes and changelog documents from various issue-tracking platforms or YAML definitions into plaintext drafts (<strong>AsciiDoc</strong>, <strong>Markdown</strong>, <strong>YAML</strong>) and rich-text output (<strong>HTML</strong> and <strong>PDF</strong>).", "gem_config_definition_path"=>"./specs/data/config-def.yml", "app_default_config_path"=>"./.releasehx.yml", "default_markup"=>"markdown", "default_slug_type"=>"kebab", "default_tplt_lang"=>"liquid", "default_drafts_dir"=>"_drafts", "default_enrich_dir"=>"_publish", "default_output_dir"=>".", "default_payloads_dir"=>"_payloads", "default_templates_dir"=>"_templates", "default_mappings_dir"=>"_mappings", "default_api_clients_dir"=>"_apis", "default_cache_dir"=>".releasehx/cache", "default_api_cred_env"=>"RELEASEHX_API_CRED", "default_api_key_env"=>"RELEASEHX_API_KEY", "default_api_user_env"=>"RELEASEHX_API_USER", "default_api_org_env"=>"RELEASEHX_API_ORG", "markdown_extensions"=>".md, .markdown", "asciidoc_extensions"=>".adoc, .ad, .asciidoc", "yaml_extensions"=>".yml, .yaml, .rhyml", "draft_source_file_types"=>"AsciiDoc, Markdown, YAML", "draft_source_extensions"=>".md, .markdown, .adoc, .ad, .asciidoc, .yml, .yaml, .rhyml", "enrich_file_types"=>"HTML, PDF", "enrich_extensions"=>".html, .pdf", "docker_base_command"=>"docker run -it --rm --user $(id -u):$(id -g) -v $(pwd):/workdir docopslab/releasehx rhx", "this_prod_repo_branch"=>"https://github.com/DocOps/releasehx/tree/release/0.1", "docs_extn"=>"", "toc"=>"", "toclevels"=>"3", "authorcount"=>0, "toc-position"=>"content"}}
+
+  SNIPPET_LOOKUP = {"helpscreen"=>"helpscreen.txt"}
+
+  REGION_LOOKUP = {"ai-prompt"=>"releasehx-ai-prompt.adoc"}
+
+  def self.read_built_snippet name
+    fname = SNIPPET_LOOKUP[name.to_s] || name.to_s
+    path = File.expand_path("../../../build/snippets/#{fname}", __FILE__)
+    raise "Snippet not found: #{name}" unless File.exist?(path)
+    File.read(path)
+  end
+end

data/lib/releasehx/helpers.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ReleaseHx
+  # Utility methods for file format handling and extension mapping.
+  # Provides helpers for converting between file extensions and canonical format names.
+
+  # A map of file extensions to their canonical format names.
+  # Used internally by format detection and extension resolution methods.
+  #
+  # @return [Hash<String, String>] Extension-to-format mapping.
+  #
+  # TODO: We should externalize this into a YAML file for easier docs integration.
+  #       Maybe even something that goes in Sourcerer or somewhere to universalize these.
+  FORMAT_MAP = {
+    'md' => 'markdown',
+    'mkd' => 'markdown',
+    'mkdn' => 'markdown',
+    'mdown' => 'markdown',
+    'markdown' => 'markdown',
+    'ad' => 'asciidoc',
+    'adoc' => 'asciidoc',
+    'asciidoc' => 'asciidoc',
+    'yaml' => 'yaml',
+    'yml' => 'yaml',
+    'json' => 'json',
+    'pdf' => 'pdf',
+    'html' => 'html'
+  }.freeze
+
+  # Resolves the user's preferred file extension for a given format.
+  # Consults the configuration's extension preferences and falls back to format detection.
+  #
+  # @param string [String] The format or extension to look up.
+  # @param config [Hash] The configuration hash containing extension preferences.
+  # @return [String] The preferred file extension.
+  def self.format_extension string, config
+    return string unless config.is_a?(Hash) && config.key?('extensions')
+
+    format = file_format_id(string)
+    return string.downcase unless format
+
+    config.dig('extensions', format) || string.downcase
+  end
+
+  # Converts a file extension or format name to its canonical format identifier.
+  # Used to normalize various extension formats (e.g., 'md', 'mkd', 'markdown') to a standard ID.
+  #
+  # @param key [String] The format or extension to look up.
+  # @return [String, nil] The canonical format ID, or nil if not recognized.
+  def self.file_format_id key
+    return nil if key.nil?
+
+    string = key.to_s.strip
+    return nil if string.empty?
+
+    FORMAT_MAP[string.downcase]
+  end
+end

data/lib/releasehx/mcp/asset_packager.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../../docopslab/mcp/asset_packager'
+require_relative 'manifest'
+
+module ReleaseHx
+  module MCP
+    # Copies MCP resource assets into a packaged location for runtime access.
+    class AssetPackager < DocOpsLab::MCP::AssetPackager
+      def initialize manifest: Manifest.load, asset_root: default_asset_root
+        super
+      end
+
+      private
+
+      def default_asset_root
+        File.expand_path('assets', __dir__)
+      end
+    end
+  end
+end

data/lib/releasehx/mcp/assets/agent-config-guide.md

@@ -0,0 +1,178 @@
+# ReleaseHx configuration: agent guide (MVP)
+
+This server exposes several authoritative artifacts for configuration work:
+
+- `releasehx://agent/guide` (this file): how to use the two files above effectively
+- `releasehx://config/sample` (YAML): the best map of the entire config tree (defaults + comments + commented-out optional keys)
+- `releasehx://config/schema` (YAML): the authoritative definition (types, constraints, long docs)
+- `releasehx://config/reference.json` (JSON): a queryable version of the complete config-reference docs
+- tool `config.reference.get` (accepts: JSON Pointer string; returns JSON object)
+- `releasehx://config/reference.adoc` (AsciiDoc) the formatted version of the reference output.
+
+## DSL Notice
+
+You are interacting with a YAML extension called SGYML, with its own ways of referencing YAML nodes and data types. It may be worth being able to "translate" some of this terminology or tailor it to your Operator's needs or preferences.
+
+### Glossary
+
+**object**: Any instance of keyed data in the YAML file.
+**Map**: A "mapping" in YAML or "object" in JSON.
+**Array**: A sequence in YAML, "array" in most languages.
+**ArrayTable**: A sequence of sibling Maps with expected parameters.
+
+### Key Tip: Distinguish *declared* keys from *arbitrary* keys
+
+ReleaseHx has both:
+
+**Declared keys** (fixed, “standard” properties):
+   These are explicitly defined in the schema/sample tree. Do not make up new *declared* keys.
+
+**Arbitrary keys** (user-defined names inside certain maps):  
+   Some objects are intentionally “free-key” dictionaries where the user supplies their own key names (for example: named type definitions, named tag definitions, named link templates, etc). In those places, inventing keys is correct and expected.
+
+How to tell which you’re in:
+
+- If the sample tree shows placeholder keys like `<name>`, `<type_name>`, `<id>`, or similar “template keys,” treat the *key name* as arbitrary and user-defined.
+- If the sample tree shows a concrete key name (e.g., `origin`, `href`, `mode`) treat it as declared and do not invent siblings that aren’t present.
+- When in doubt, consult `releasehx://config/schema` for the node’s semantics (look for wording indicating “map of … keyed by …”, wildcard keys, or examples using placeholders).
+
+## What You Can Help With, Agent
+
+Use these assets for any of the following scenarios:
+
+### Scenario A: Create a new config
+- Generate a minimal `.releasehx.yml` that sets only what the user needs.
+- Start from the sample tree to avoid missing required structure.
+- Keep changes small: only override what must differ from defaults.
+- If the user needs a named item (type/tag/link/etc), create it under the appropriate “arbitrary keys” map using a sensible name.
+
+### Scenario B: Modify an existing config
+- Read the user’s current config.
+- Compare the affected subtree against the sample tree.
+- Make the smallest possible edit (avoid restructuring unrelated blocks).
+- If the change involves a named entry (arbitrary key map), add/update only that one entry.
+
+### Scenario C: Troubleshoot behavior
+- When output/content is surprising, locate the relevant top-level block in the sample tree first.
+- Use the schema definition to confirm allowed values and semantics before proposing changes.
+- Prefer quoting the schema’s constraints/intent rather than guessing.
+- If behavior depends on a named entry (type/tag/link/etc), confirm the user’s key name matches the referenced name elsewhere.
+
+### Scenario D: Discover available knobs
+- Use the sample config as a TOC.
+- If you need deeper meaning, consult the schema entry for that subtree.
+- If the user asks for “all options,” point them to the sample tree and offer to focus on one subtree at a time.
+
+## Where config comes from
+
+- Defaults are defined by the schema definition (`releasehx://config/schema`).
+- Users override defaults via `.releasehx.yml` or a `--config <path>` flag.
+
+## How to navigate quickly (recommended method)
+
+1) Load `releasehx://config/sample` and use it as the “table of contents.”
+2) Identify the smallest subtree relevant to the user’s goal.
+3) Decide whether you are working with:
+   - a declared-key subtree (fixed property names), or
+   - an arbitrary-key map (user-defined item names).
+4) Only if needed, consult `releasehx://config/schema` for:
+   - allowed values (enums)
+   - types (string/boolean/integer/uri/path/template/etc)
+   - templating rules and any special behaviors
+5) Apply minimal edits to the user’s config.
+
+## Hack for inspecting the effective config
+
+Append the following to any proper `rhx` command to write an "effective config" to file.
+
+```shell
+--debug 2>&1 | awk '
+  /^DEBUG: Operative config settings:/ {p=1; next}
+  p && /^---[[:space:]]*$/ {y=1}
+  y {print}
+  y && /^[[:space:]]*$/ {exit}
+' > .agent/tmp/effective-config.yml
+```
+
+Replace the `> PATH` with one appropriate to your Operator's preferences or local application structure.
+
+## Counter-prompts (questions to ask the Operator)
+
+Ask only what you need to select the right subtree and values:
+
+- What is the issues origin source? (Jira / GitHub / GitLab / RHYML file)
+- What is the origin endpoint or file location?
+- Do you want Markdown or AsciiDoc output? (and do you want frontmatter?)
+- Are you generating drafts, final outputs, or both?
+- Do you want to group/sort by type/part/tags, or keep defaults?
+- Are credentials provided via environment variables, or do you need explicit auth config?
+- If you’re defining named items (types/tags/links/etc), what names do you want to use for those entries?
+
+If the user provides only a vague goal, ask one question at a time until you can pick the right subtree.
+
+## Common top-level blocks (use the sample tree as the source of truth)
+
+Typical blocks include (names may vary; consult the sample tree):
+
+- `$meta` (markup + conventions)
+- `origin` (API/file source + auth + project identifiers)
+- `conversions` (how summaries/heads/notes are derived)
+- `extensions` (file extension settings)
+- `types`, `parts`, `tags` (classification/grouping controls; often include arbitrary keys)
+- `links` (templated link formats; often include arbitrary keys)
+- `paths` (input/output locations)
+- `modes` (execution defaults)
+- `rhyml` (RHYML-specific behaviors)
+
+## When to consult schema (instead of sample)
+
+Use `releasehx://config/schema` when:
+
+- the user’s desired value is not obvious from comments
+- you need to confirm an enum (e.g., `origin.source` values)
+- a property is templated and you need to understand substitution variables
+- you suspect a type mismatch (URI vs Path vs String, etc)
+- you need to confirm whether a subtree allows arbitrary keys, and what each entry’s structure must be
+
+## Potentially unintuitive principles
+
+- **“Frontmatter” is controlled in two places (toggle vs template).**  
+  If you’re trying to *turn frontmatter on/off*, look under `modes.*_frontmatter`. If you’re trying to *change what frontmatter contains*, look under `templates.*_frontmatter` (Markdown/AsciiDoc/HTML each have their own). Also note `modes.wrapped` affects HTML wrapping, which can look like a frontmatter problem when it’s really wrapping/boilerplate.
+
+- **Links require both a template and an enable switch.**  
+  Defining URL templates under `links.web.href` / `links.git.href` does nothing by itself. You must also enable display under `history.items.show_issue_links` / `history.items.show_git_links` (or the per-section overrides under changelog/notes items, if present). If a user says “I set the link template but no links appear,” check the `history.*items*` flags.
+
+- **There are multiple “markup” concepts.**  
+  `$meta.markup` is the markup format used inside *config strings* (and is meant to keep defaults cross-compatible). `rhyml.markup` is the markup for the *RHYML note/memo content* and can also be overridden inside RHYML documents themselves. If a user complains “my Markdown isn’t converting to AsciiDoc,” don’t only look at `$meta`.
+
+- **API source selection is under `origin`, but API customization lives under `paths`.**  
+  `origin.source` selects the API type (`jira`, `github`, `gitlab`, `rhyml`) and `origin.href` points at the endpoint or payload location. But “where do I put custom mappings/clients?” is not in `origin.*`; it’s in `paths.mappings_dir` and `paths.api_clients_dir`, and those directories are searched using filenames derived from `origin.source`.
+
+- **`origin.href` can be templated, and its variables come from siblings and CLI args.**  
+  If the endpoint/path needs to vary by project or version, `origin.href` supports templating (for example, using the sibling `origin.project` and the argued release version). If a user expects `{{ version }}` or project placeholders to work and they don’t, treat it as a templating/evaluation-order issue, not a path issue.
+
+- **“How do I change what becomes `summ` / `head` / note text?” is under `conversions`, not templates.**  
+  The `conversions` block is about *where content originates* (issue title vs custom field vs commit message, etc) and how it maps into RHYML fields. If the user asks “use a custom field for summaries,” don’t go hunting in output templates first.
+
+- **Classification maps are intentionally “invent-your-own-key” dictionaries.**  
+  Blocks like `types`, `parts`, and (parts of) `tags` are designed so users define named entries. If you see placeholder keys like `<type_name>` or `<part_name>` or language implying “arbitrarily named,” that means the *map keys are user-defined identifiers* and should be invented to match the user’s taxonomy or existing labels.
+
+- **Tags are both a filter and a dictionary of tag definitions.**  
+  The tags system is easy to misread:
+  - Some keys (like `_include` / `_exclude`) behave like filter controls for *including* or *excluding* entire issue/change records at RHYML conversion time.
+  - Many other keys represent *individual tags* that may be imported from the issue system or assigned in RHYML.
+  - Only tags that are declared in the tags block will typically be preserved/ported from API payload into RHYML tags.  
+  If a user says “my label exists in GitHub but it’s not showing up,” it’s usually because it isn’t declared under `tags`.
+
+- **Some tags are “operational” and default to being dropped.**  
+  A tag can exist only to drive inclusion (example: `changelog`) and may default to `drop: true`, meaning it influences selection but is not shown in published output unless explicitly configured otherwise. If the user expects to see it in output, check the tag’s `drop` and `groupable` settings.
+
+- **Output location is split into base dir, subdirs, and filename templates.**
+  If a user says “ReleaseHx is writing to the wrong folder,” check:
+  - `paths.output_dir` (the base)
+  - `paths.drafts_dir` and `paths.enrich_dir` (subdirectories)
+  - `paths.*_filename` templates (which may include `{{ version }}` and `{{ format_ext }}` and are resolved late).  
+  If file extensions look wrong, it may be an `extensions.*` issue, not a `paths.*` issue, because `format_ext` comes from extension preferences.
+
+- **Cache settings live under `paths.cache` (not under origin or modes).**  
+  If a user wants fewer API calls or wonders “why am I seeing cached payload behavior,” look under `paths.cache.*` (enabled/ttl/dir) and related gitignore prompting. This often presents like an origin/API issue but isn’t.