command-blacklist: publish to the docs Cookbook tab

[jpshackelford]

Why

This is the first example rewritten for the docs conventions, as a reference for migrating the rest. The ASCII flow diagram is now a mermaid diagram. The two launch options are tabs on the docs site and plain sections on GitHub. Asides are GitHub alerts, which become Mintlify callouts. "Why inline?" is a collapsible section, and Related is a card grid. The hook code block is tied to safety-guardian/hooks/hooks.json: the README keeps a short excerpt, the docs page shows the full file, and the build fails if the file moves. The prose is otherwise unchanged. example.yaml puts the page under Guardrails.

Validation

• Docs render — npm run check renders both published examples without errors.
• GitHub rendering — GitHub's Markdown renderer shows the alerts, collapsible section and diagram natively, and none of the docs: comments are visible.
• Docs page — see the preview comment below for the rendered page on the docs site.

This PR was drafted by an AI agent on behalf of the user.

@jpshackelford can click here to continue refining the PR

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	5	0	100%
cli.py	65	3	95%	59–60, 100
client.py	105	17	84%	56, 109, 117, 150, 160–162, 173, 203, 206–208, 210, 217–219, 221
metrics.py	80	2	98%	102, 182
v0.py	48	3	94%	88, 104, 141
v1.py	83	9	89%	86, 90, 94, 131, 135, 155, 178, 206, 214
TOTAL	386	34	91%

[github-actions]

Docs preview

✅ Docs preview is ready: https://allhandsai-cookbook-preview-pr-8.mintlify.site

Page	Change
/cookbook/command-blacklist	added
/cookbook/conversation-tags	added
/cookbook	added

Docs PR: OpenHands/docs#885 (draft preview; never merged, closes with this PR).
Rendered from 36a2d02. After merge, a separate sync PR updates the docs.

[github-actions]

Good. This PR successfully migrates the command-blacklist example to the new docs conventions. All formatting changes follow the documented standards in tools/docs-render/README.md.

Validation

✅ Docs render check passes (npm run check)
✅ All tests pass (24/24)
✅ CI checks pass (docs-render, pre-commit, docs-preview, tests)
✅ Mermaid diagram correctly represents the flow
✅ GitHub alerts properly formatted (NOTE, TIP, WARNING)
✅ docs:tabs and docs:cards directives correctly used
✅ Code block references file with excerpt marker
✅ example.yaml valid (category "Guardrails" exists in cookbook.yaml)

Observations

Badge URLs: The launch badge on line 71 points to github:jpshackelford/oh-examples rather than OpenHands/enterprise-cookbook. This is a pre-existing issue across multiple examples in the repository (gpg-commit-signing, finish-callback, launch-plugin-badge all have the same pattern). While the badge currently works, users will load plugins from an unofficial fork instead of the canonical repository. Consider updating all badge URLs in a follow-up PR to point to OpenHands/enterprise-cookbook.

[RISK ASSESSMENT]

Risk Level: LOW

• Documentation/formatting change only
• No functional code changes
• All validation passes
• Pre-existing code patterns unchanged

Verdict: APPROVE

Key insight: This establishes a clean migration pattern for other cookbook examples - the dual-rendering approach (GitHub alerts, docs: comments, file-linked code blocks) works well for maintaining readable GitHub READMEs that also generate polished docs pages.

---

Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/enterprise-cookbook/actions/runs/37144893306