docs: toolbox: toolbox-command-guide: new guide

[kpouget]

Summary by CodeRabbit

• Documentation
  • Added a comprehensive Toolbox Command Writing Guide covering the three-layer architecture and the toolbox DSL.
  • Prescriptive guidance on command structure, decorators (conditional, retries, always/cleanup), execution and IO conventions, and artifact directory practices.
  • Security best practices to avoid secret leakage, templating guidance, troubleshooting tips, end-to-end examples, antipatterns, and a ready checklist.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign ashishkamra for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9eaa234c-5a0e-40b8-a438-df8f73190881

📥 Commits

Reviewing files that changed from the base of the PR and between 19c3311 and 0bb0859.

📒 Files selected for processing (1)

• docs/toolbox/toolbox-command-guide.md

✅ Files skipped from review due to trivial changes (1)

• docs/toolbox/toolbox-command-guide.md

---

📝 Walkthrough

Walkthrough

A comprehensive new documentation guide for the FORGE Toolbox Command Writing is added, covering architecture, design principles, DSL usage, I/O guidelines, artifact management, security practices, templating, troubleshooting, examples, and antipatterns. No code changes are made.

Changes

FORGE Toolbox Command Writing Guide

Layer / File(s)	Summary
Documentation docs/toolbox/toolbox-command-guide.md	New guide introducing the three-layer toolbox architecture, design principles, command structure, DSL usage patterns, input/output standards, artifact management, security practices, Kubernetes templating, troubleshooting steps, practical examples, antipatterns to avoid, and quick reference checklist.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Poem

🐰 A burrow of wisdom, so neatly penned,
Three layers of toolbox, from start to the end,
Patterns and checklists in tidy array,
Hops of guidance to brighten the day,
A carrot of clarity for coders at play.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a new documentation guide for the FORGE Toolbox command writing. It is concise, directly related to the changeset, and provides sufficient context for understanding the primary contribution.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/toolbox/toolbox-command-guide.md`:
- Around line 766-769: The "Getting Help" lines use filesystem-style paths that
may not resolve from docs/toolbox/toolbox-command-guide.md; update the three
references (`specs/008-toolbox-dsl/`, `projects/*/toolbox/`, and
`../topsail/projects/*/toolbox/`) to repo-root-relative links or full repo URLs
so they render correctly (for example change to /specs/008-toolbox-dsl/,
/projects/<project>/toolbox/, or the full GitHub/Docs URL for the TOPSAIL
patterns), and verify the links work when viewing the rendered Markdown.
- Around line 336-347: The example claims sensitive parameters won't be logged
but never sets log_command=False; update the task decorator for
handle_sensitive_data to explicitly disable command logging by adding the
log_command=False argument to the `@task` decorator (i.e., use
`@task`(log_command=False) on the handle_sensitive_data function) and keep the
rest of the function reading args.secret_file so the snippet clearly
demonstrates the intended behavior.
- Around line 329-331: The example shows unsafe shell interpolation in the
shell.run call (f"cat {args.secret_file} | oc create secret generic mysecret
--from-file=-"); change it to a safe invocation that avoids interpolating
args.secret_file into a shell string—use a parameterized API or pass argv as a
list to shell.run (or use subprocess.run with args list), or avoid the pipe
entirely by calling oc create secret with --from-file pointing directly to
args.secret_file; reference the shell.run call and args.secret_file when making
the replacement.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: eb9b172d-fbf5-4a6c-a9e1-b1f8c8c375f0

📥 Commits

Reviewing files that changed from the base of the PR and between 8392886 and 19c3311.

📒 Files selected for processing (1)

• docs/toolbox/toolbox-command-guide.md