Use relative links where the text lands in the docs collection

[miharp]

Follow-up to #279. That PR merged at its first commit, so the relative-link fix discussed in this review comment never landed on main. This is that commit, rebased.

@tuxmea raised it on #279: links should be relative so a locally served docs container works offline, without internet access.

Per openvox-docs CONTRIBUTING § Linking, links within a versioned collection should be bare page.html — not rooted /openbolt/latest/page.html, since those silently cross version boundaries when a new major collection is added.

The dividing line is whether a string is ever rendered as a docs page.

Relative — rendered into the collection

lib/bolt/config/options.rb and lib/bolt/inventory/options.rb. These feed the generated reference pages and the JSON schemas, and their siblings were already relative (projects.md, module_structure.md, supported_plugins.md#task), so the absolute URLs #279 introduced were the only ones out of step.

The .md form is deliberate: the importer at lib/puppet_references/openbolt/docs.rb rewrites relative .md → .html on the way in.

.gsub(/(\]\([^):]*?)\.md((?:#[^)]*)?)\)/, '\1.html\2)')

That regex excludes anything containing :, which is why absolute URLs passed through untouched and the problem was invisible.

The dual-purpose case — bolt_option_parser.rb

Those strings are printed by bolt --help, where a relative link has no base to resolve against, and imported as bolt_command_reference.md (it is in the importer's GENERATED_PAGES). 16 of them land on that page.

Rather than break one context for the other, rakelib/docs.rake now rewrites them to relative markdown links while generating that page. Terminal output keeps full URIs; the published page has none.

Absolute, deliberately — unchanged

Guide output, error messages, and the comments written into generated Puppetfiles and plan templates. None is ever a docs page; a user looking at plans.html in a terminal has nothing to resolve it against.

Verification

• rake docs:all → zero absolute docs URLs in any generated page.
• bolt plan run --help still prints the full URI.
• rake schemas:all reproduces the committed schema JSON exactly.
• rubocop clean.
• Anchors verified against openvox-docs.

AI usage disclosure

Per the Vox Pupuli and OpenVox AI Usage Policy: I used Claude Code to trace the docs import pipeline, make the change, run the verification above, and draft this description. The commit carries a Co-Authored-By trailer.