docs: add guide for optional output-format dependencies and strict JSON consumer validation

[bogusdeck]

Summary

This PR addresses two documentation issues:

1. docs: add a focused guide for optional output-format dependencies #346: Add a guide for optional output-format dependencies.
2. docs: document strict JSON consumer validation with Node #345: Document strict JSON consumer validation with Node.js.

Changes

• docs/output-contracts.md

  • Added a table documenting optional output-format dependencies, including yaml and rich.

• docs/json-contracts.md

  • Added a section explaining how to validate base CLI JSON and NDJSON output using Node.js's JSON.parse.

Notes

Both changes are documentation-only and follow the acceptance criteria defined in their respective issues.

[codeforester]

Cleanup: the new "Contract fixtures and validator" section is a near-verbatim duplicate of the paragraph already present ~25 lines above it in the same file (both describe CI validating fixtures against packaged schemas via a Python validator and a Node.js reader). Consider merging to avoid having to update the same claim in two places.

[codeforester]

Fixed — the duplicate paragraph is gone in the latest commit (docs: remove duplicate contract guidance). Thanks!

[codeforester]

Doc accuracy: this table says a missing PyYAML surfaces a raw ImportError: No module named 'yaml', but the code never lets that propagate — require_yaml() (lib/python/base_cli/_dependencies.py) catches ImportError and re-raises a RuntimeError with an actionable install hint, which the caller wraps into OutputFormatError. A user grepping logs for the documented string won't find it, and the doc omits the actual (more useful) message the CLI produces.

[codeforester]

Fixed — the table now shows the actual wrapped message (OutputFormatError: PyYAML is required...) instead of the raw ImportError text. Thanks!

[codeforester]

Blocking: this PR currently fails the base/issue-branch-policy check (see the failed run) — "Pull request #350: branch name is not canonical."

This repo's branch-naming policy (.github/workflows/issue-branch-policy.yml) requires the pattern:

^(bug|enhancement|documentation|ci|security)/([1-9][0-9]*)-([0-9]{8})-[a-z0-9]+(-[a-z0-9]+)*$

i.e. <category>/<issue-number>-<YYYYMMDD>-<slug>, matching every other open PR in this repo (e.g. documentation/348-20260914-community-health-templates). The current branch, docs-updates, doesn't match — it's missing the category prefix, issue number, and date.

Since this PR's commits reference issues #345 and #346, renaming the branch to something like documentation/346-20260924-optional-output-format-dependencies (adjust the issue number/date/slug as appropriate) and re-pushing under that branch name should clear the gate. The doc content itself looks good — both of my earlier comments (duplicate paragraph, ImportError message accuracy) are resolved in the latest commits, so this branch rename is the only remaining blocker I can see.

[codeforester]

Hey @bogusdeck, thank you for taking this on and for the careful work here — the table and the Node validation examples are clear and follow the issues' acceptance criteria well.

Closing this one only because of timing, not quality: while this PR was open, #345 and #346 ended up getting addressed independently in #352 and #353, which merged the same day. Those landed as dedicated pages (docs/strict-json-consumer.md and docs/optional-output-dependencies.md, linked from the docs index/nav) with their own validator tests, so the two issues are already closed on main. That's just an unlucky overlap in timing on our end, not anything about how you approached it — sorry for the wasted effort.

I'll close this PR rather than merge duplicate content on top of what's already there. If you're up for it, I'd genuinely welcome you picking up another open issue — your approach here (matching the acceptance criteria, keeping the diff focused) was solid. Thanks again for contributing!