Create a Tool: complete operating guide

Purpose

This page lets a user or AI agent create one or more new BioLine tools from start to finish: check names, establish image and software evidence, prepare configuration, pull the image, create the tool, apply configuration, read it back, and optionally validate it through a cloud job. All configuration rules are included here. Creation requires no local Skill, dedicated Python/Shell helper, or Gateway.

Distinguish the command from this workflow. fkit create-tool exports, compresses, and uploads an existing local Docker image and creates a remote tool. It does not pull an image, generate or apply configuration, write a summary, create a Flow/Job, or enforce the confirmations and checks described here. The operator or agent performs those steps; this guide is not a state machine enforced by fkit.

Syntax

fkit create-tool [OPTIONS] <IMAGE_NAME> <TOOL_NAME>

Arguments and options

• IMAGE_NAME: the exact, verified image reference already present in local Docker storage.
• TOOL_NAME: a new, unique tool name in the current project.
• -t, --tmp <TMP>: temporary directory for image export and compression; allow sufficient disk space.
• --json: return toolId, toolVersionId, toolName, and version.

create-tool has no --dry-run, --yes, --config, or --summary option. Configuration application uses tool config apply and tool summary apply below.

Effect

Pulling writes to local Docker storage. Creation creates a remote tool and uploads its image. Config/summary apply without --dry-run write configuration and description separately; the two writes are not atomic. Flow creation and Job submission are separate later actions.

Safe use and scope

Only create previously nonexistent tools whose initial platform version is the integer 1. Software, environment, database, image tag, and platform tool versions are different concepts. For an existing-tool update, stop this workflow and read fkit update --docs; do not automatically create a version or overwrite a tool.

Without a concrete tool name, ask only for the tool name. Accept commas, Chinese commas, semicolons, newlines, and numbered lists. Deduplicate names using Unicode case-insensitive comparison, retaining the first occurrence and original order. Process tools sequentially in separate working directories.

One confirmation of the complete creation plan authorizes its image pull (if needed), tool creation, configuration and summary writes, and read-back verification. Continue through those steps without stage-by-stage confirmation or config/summary dry-runs. Pause on failure, cancellation, or a required change to confirmed content; obtain approval for a changed plan. Optional Flow/Job validation is outside this authorization and remains separately selected and confirmed. Do not run host bioinformatics programs, local containers, image builds, or smoke tests as a substitute for cloud validation.

Never print or persist passwords, tokens, cookies, STS, or registry credentials. Do not bypass server reference locks or modify existing Flows. If a referenced tool cannot be configured, report the server rejection and let the user address the reference.

1. Check names and prepare a working directory

Establish that fkit is available, authentication works, and the current project is known. When login is needed, have the user complete fkit login --host https://www.bioline.cloud. Do not put secrets in command records or artifacts. Do not use the interactive fkit project picker as an unattended probe.

Query once for the initial batch:

fkit tool list --json

Match requested names against the real array's name using case-insensitive exact or substring matching. Treat any match as potentially existing: report real names and versions, skip that target, and direct the user to inspect it in the web interface or pursue the separate update workflow. Flow lists, web search, and image searches cannot substitute for this query. Stop the batch if it fails, authentication/project context is uncertain, or the result cannot be parsed.

The default display name is the last image repository segment without tag/digest. An explicitly chosen name must not contain path separators, colons, whitespace, or control characters. Check both the requested name and final display name; recheck if the name changes.

Choose a new absolute WORKSPACE per unmatched tool, for example /data/authoring/tool-<safe-name>-<unique-run>/. Ensure it is writable and does not overwrite another run. WORKSPACE, IMAGE, TOOL_NAME, and TOOL:VERSION below are placeholders: replace them with verified values before execution. Keep:

WORKSPACE/intent.md
WORKSPACE/spec/duplicate_check.json
WORKSPACE/spec/tool_request.json
WORKSPACE/spec/tool_config.json
WORKSPACE/spec/README.md
WORKSPACE/spec/plan.md
WORKSPACE/spec/state.json
WORKSPACE/spec/pull_result.json
WORKSPACE/logs/
WORKSPACE/result.json

These are task records, not installed programs. Record stage times, evidence, authorization scope, and actual responses. Never pre-record success. Keep the initial duplicate-check evidence; refresh the list before and after creation as described below, independently of the once-per-batch initial query.

2. Establish image, command, and resource evidence

Use version-specific official websites, documentation, source repositories, or releases for software versions, commands, inputs, outputs, environment, databases, and resources. Search only locates primary evidence. Record actual URLs and the specific claim each supports; examples and guesses are not evidence. Do not claim dependencies such as SignalP without proof or turn a possible last release into a confirmed final release.

Check image sources in this order: official → BioContainers → Docker Trusted Content → linked GHCR. Record all four slots as available, unavailable, or rejected, with evidence and a reason, and separately identify the single selected source. Choose the first available source; do not fabricate unchecked slots. GHCR requires a link from the official source repository. Preserve BioContainers' original quay.io/biocontainers/... source.

Require an exact registry/repository:tag, never latest, a missing tag, or a guessed tag. Pin linux/amd64 and a complete lowercase sha256: digest. For multi-platform images, distinguish the index digest from the amd64 child manifest digest and record their relationship. Compare RepoDigests against the same object type, not a different level of the manifest. Stop if the platform and image identity cannot be established uniquely.

For Docker Hub, investigate cache candidates in this order while preserving repository path and tag; keep BioContainers/GHCR on their original registry:

https://docker.m.daocloud.io
https://docker.nju.edu.cn
https://do.nark.eu.org
https://docker.mirrors.ustc.edu.cn
https://docker.1ms.run
https://docker.1ms.run

Do not reorder by speed tests or alter global Docker proxy/daemon settings. For official images on other unsupported registries, stop and request a verifiable, approved access source. One plan selects one exact address. A failed pull must not trigger automatic cache, registry, tag, or image-build fallback.

Read metadata using a registry's read-only manifest API or docker manifest inspect --verbose IMAGE, without running a container. Record compressed layer bytes for the selected amd64 image. Estimate seconds at 1, 5, and 10 MB/s as bytes / (speed × 1000000). These theoretical times exclude decompression, retries, and upload; do not promise them as completion times.

In tool_request.json, record requested/final names, original and pull references, source kind, software/environment/database versions, platform, manifest identity and expected RepoDigest, four candidate slots, evidence, per-resource rationale, database compatibility, and output-directory strategy. Record not_applicable for no database; otherwise evidence must bind both tool and database versions. Pause that tool if dependencies or versions cannot be established instead of inventing them.

If the tool requires a reference database at runtime, inspect the pulled image before creating the remote Tool to verify that the database files actually exist. Check the application's default search path or configured path, database version, and required indexes; an image name, installed executable, or documentation example does not prove the database is bundled. Record the inspection command and result. If the database is absent, explain its identity, version, estimated download size and storage needs, source, and integration method (a new image containing it or a separately mounted input), then ask the user whether to download it. Do not download the database or create the dependent Tool without an explicit answer. After authorization, download and integrate it, then run the minimal test with the final image or mount. A missing database is not a skippable test exception.

3. Complete configuration contract (no additional document needed)

Actual command and parameter verification

Verify parameters, accepted values, and default behavior using evidence available for the selected tool version. --help is only one possible source and is not supported by every tool. Depending on the tool, use its image-provided help/version/usage command, bundled README/man page/examples, the matching official documentation/source/release notes, and a minimal valid-data run.

Help or official documentation proves that parameters and values exist; a minimal run proves that the final command, output paths, and post-processing actually work. Record the evidence source and version for every parameter. Do not configure unsupported or unproven defaults.

When an optional parameter means default or disabled, follow the software's actual semantics and omit the entire option when required. Never pass default, an empty string, or a placeholder as a universal default; if the software's default mode is selected by omitting --presets, omit --presets from the command.

The minimal run must cover the actual input modes and important runtime branches declared by the plan: single-end/paired-end, compressed/uncompressed, file/directory inputs, database use, and enabled optional parameters. For software that requires paired flags, companion switches, or mutually exclusive options for a mode, verify those conditions from the current image's help, official documentation, or an actual error, and include the required arguments in the final command. Do not test only that the executable starts or validate a different mode. If the plan supports multiple modes, test each one or explicitly limit the Tool to the modes that were tested.

This check must use the complete command after final endpoint expansion. For paired, grouped, or multi-file inputs, provide test files with the same number and endpoint types as the final configuration and validate the related options together. For database-dependent tools, mount the verified database directory and run with the final database option and path. A mode passes only when that command exits with code 0 and produces the declared outputs; --help, a single-end example, a run without the database, or merely starting the executable cannot substitute for it.

If suitable test data is unavailable, state that parameter evidence is verified but the minimal run is not tested. If the command creates directories, copies/moves files, uses pipes, or has conditional logic, the minimal test must cover those post-processing steps.

Local minimal-run gate

After pulling the image and before creating the remote Tool, run one minimal valid test in local Docker whenever feasible. Use the final command after configuration placeholders have been expanded. Do not test only the main program or its help output; cover the complete command, default parameters, input and output paths, and all directory creation, copy, move, rename, pipe, and conditional post-processing.

The test passes only when the program exits with code 0; every declared output file or directory is actually produced; names, extensions, and directory levels match the endpoint type, path, and pattern; all post-processing succeeds; and outputs are usable by the intended downstream ports. Save the test log, expanded command, image identity, and artifact inventory as plan evidence.

If the local test fails, repair the command or endpoint contract before creating the remote Tool. If suitable data, a required large database, special hardware, or local execution is unavailable, record an explicit “minimal run not tested” exception and its risk. Help checks or configuration read-back do not count as a runtime pass.

Pre-creation minimal-run gate

When local Docker is available and the image can run, a minimal smoke test is mandatory before remote fkit create-tool. The test must use the real image and command, replace every placeholder with actual paths in a temporary directory, and execute the complete command including mkdir, cp, mv, renames, pipes, and conditional logic.

Check all of the following: the program exits with code 0; every input receives the intended file path, directory path, or scalar value; every declared output is produced according to its configured type/path/pattern; every referenced filename actually exists rather than being guessed; output files are not created as directories and output directories are not passed as files; and files intended for downstream connections can be opened independently.

Also verify that the test input mode, database mount, and optional-argument combination exactly match the plan, and that all mode-specific companion arguments take effect.

If the smoke test fails, stop and repair the command or endpoint contract locally. Do not create the remote Tool or claim validation success. Only after the smoke test passes may the one-time user creation plan be confirmed. If Docker, suitable test data, or a realistic small run is unavailable, explicitly state that the pre-creation run was not completed and show the risk before asking whether to continue.

Generate a complete JSON object with exactly command, inputs, outputs, and resources. Do not use a partial patch. Top-level name, version, parameters, image, and runtime_preflight are forbidden. Establish command evidence first; label inferences explicitly for confirmation within the complete creation plan.

Command placeholders

Use <:> inside components and <|> between components:

Meaning	Syntax
Required I/O	#{io<:>input_file}
Optional I/O	`#{io<:>mask<
String parameter	#{string<:>mode<:>fast}
Numeric parameter	#{number<:>threads<:>8}
Prefixed I/O	`#{prefix<:>--out<
Boolean flag	#{prefix<:>--verbose}

Keys start with a letter and contain only letters, digits, and underscores. option appears at most once, last. Repeated keys must agree on type, default, prefix, and optionality. Every I/O key corresponds to exactly one endpoint directory, with no missing or extra endpoints.

A file_group can expand to multiple paths; do not quote the entire placeholder as one ordinary string. In sh -c 'script' sh args..., the second sh occupies $0, so real arguments start at $1. Establish argument expansion and subdirectory preservation from evidence, not assumed container paths.

Input and output endpoints

Each endpoint has name, type, directory, pattern, and path. name is the display label. directory is the placeholder key and runtime /io/<directory>/ directory name. Names and directory keys must each be globally unique across inputs and outputs. Array order determines endpoint order; impose no arbitrary endpoint-count limit.

Both input and output name values must fully match ^[A-Za-z0-9][A-Za-z0-9_-]{0,254}$: 1–255 characters, starting with an ASCII letter or digit, containing only ASCII letters, digits, underscores, and hyphens. Spaces and Chinese characters are not allowed. Use contigs_fasta, not Contigs FASTA; put descriptive prose in the README. directory must still follow the placeholder-key rules above; do not confuse display names with command keys.

Prefer pattern: "*" for inputs and outputs. The platform automatically expands path: "file", inCmd: 1, and a concrete pattern to /io/<directory>/<pattern>. Prefer this native expansion; use sh -c only when the platform cannot express the required command. Output file groups cannot use path: "file".

A shell wrapper is not the default. If the program can consume endpoint placeholders directly, generate a plain command first, for example megahit -r #{io<:>reads} -o #{io<:>assembly}. Use sh -c or bash -c only when directory creation, file moves/copies, environment variables, pipelines, conditions, loops, or another behavior cannot be expressed by native endpoints; when used, verify $0, $1, and subsequent argument positions.

Choose type from file, file_group, or folder according to actual use; path is file or directory. A folder requires path: "directory". Inputs cannot have subpath. Outputs may have a safe relative directory subpath, without absolute paths, backslashes, or ... A nonempty subpath must end in /; it is not an output filename.

Output decomposition for downstream composition

Endpoint type and I/O display path are independent settings. type: "file" declares a single-file endpoint; it does not guarantee that the command placeholder expands to a file path. For I/O passed directly to a program's input-file or output-file argument, explicitly set path: "file" (File path in the UI). Use path: "directory" (Directory path) only when the program argument expects a directory. Storing a file inside an endpoint directory is not a reason to select directory display. path maps to API inCmd (1 for file paths, 0 for directory paths). API paramType values 2/3 identify input/output direction, not path display.

For fastp, -i, -I, -o, -O, -j, and -h all accept file paths. Inputs r1, r2 and outputs cleaned_r1, cleaned_r2, json_report, html_report should all have type: "file" and path: "file". Prefer pattern: "*" for inputs and outputs; when fixed output filenames are required, set each filename as pattern and let the platform expand it. fastp should use -o #{io<:>cleaned_r1} and similar placeholders directly, without sh -c. Example output endpoint:

{"name":"cleaned_r1","type":"file","directory":"cleaned_r1","pattern":"*","path":"file"}

The creation plan must show each endpoint's type, path, and associated program argument. Check them locally and in configuration read-back. Check expansion semantics: a direct output-file argument must use path: "file" plus a concrete pattern so the platform expands an actual filename, not just an endpoint directory ending in /. For example, -o /io/cleaned_r1/ makes fastp write to a directory as if it were a file, causing Failed to write. Filenames, extensions, and compression must also satisfy the program and downstream consumers; do not treat illustrative placeholder paths as actual filenames. Compare read-back type, path, pattern, directory, subpath, and command with the intended configuration. Any difference must be reported as unverified, never as successful verification. This check does not require running a job or restoring dry-run.

Design output endpoints around how later Flow nodes will consume them. Results with different meanings, filenames, or likely consumers must use separate endpoints; do not hide several important results inside one folder endpoint. For example, fastp paired-end cleaned reads should be two file outputs, cleaned_r1 and cleaned_r2, rather than one cleaned_reads folder containing cleaned_R1.fq.gz and cleaned_R2.fq.gz. A downstream node can then connect exactly the file it needs.

Use folder only for a real directory collection, an unknown number of files, required directory structure, or a result consumed as a whole. Use file_group for a homogeneous set that must travel together. Split HTML/JSON reports into separate file outputs when downstream nodes read them separately; combine them in a report folder only when they are user-facing artifacts that do not participate in the workflow. The plan must state each output's downstream consumer and why file, file_group, or folder was chosen.

For assemblers, aligners, annotators, and other tools that produce several predictable result files, create a separate file output for every file that a later workflow may connect independently, such as contigs, assembly_graph, contig_paths, or json_report. Do not expose only one assembly_output folder containing all important results. Keep a folder only when filenames or counts are unknown, directory structure must be preserved, or downstream consumers genuinely need the whole directory. The plan must list each fixed filename, pattern, downstream purpose, and intended connection.

Resources

Require positive cpu, memory, and disk; disk_type is normal or high; network_mbps is one of 0, 1, 5, 10, 50, or 100. Optional gpu has the shape {"spec":"actual specification name","count":1}, with a nonempty specification and positive integer count.

Explain each resource value, including optional GPU, and include recommendations in the complete plan for confirmation. CPU, memory, disk, and GPU must match a currently available platform machine specification exactly. Formal config apply performs platform validation; this workflow omits dry-run. Local checks do not establish platform acceptance. A resource rejection can occur after the remote tool exists: report partial completion and stop.

Complete example

This example intentionally uses a direct command without a shell wrapper. Replace the command and resources with verified values. Do not use sh -c or bash -c as a template unless special shell behavior is required.

{
  "command": "megahit -r #{io<:>input_a} -o #{io<:>output_a}",
  "inputs": [
    {"name":"input_a","type":"file","directory":"input_a","pattern":"*","path":"file"},
    {"name":"input_b","type":"file","directory":"input_b","pattern":"*","path":"file"}
  ],
  "outputs": [
    {"name":"output_a","type":"folder","directory":"output_a","pattern":"*","path":"directory"},
    {"name":"output_b","type":"folder","directory":"output_b","pattern":"*","path":"directory"}
  ],
  "resources": {"cpu":2,"memory":4.0,"disk":20,"disk_type":"normal","network_mbps":0}
}

Output-directory compatibility and description

BioLine may pre-create folder output directories. For each folder output, record the verified policy under tool_request.json.runtime_preflight.outputs: application_accepts_existing, dedicated_child_directory, or force_flag. The command must implement that policy. For a dedicated child directory, verify output collection paths too. Prokka using the pre-created --outdir directly must include --force. Missing compatibility evidence blocks creation.

Write a bilingual Chinese/English spec/README.md with overview, image/software versions, inputs, outputs, parameters, resources, database, limitations, and evidence links. Ground facts in the reviewed configuration and evidence, without claiming untested outcomes. Present the complete configuration and description together.

Check the four top-level fields, placeholder/endpoint correspondence, every input/output name against the regex above, input/output patterns and command filename construction according to the rules above, endpoint types and paths, resources, and directory strategy locally. Correct violations before presenting the creation plan, not after creating the remote tool. Generic JSON tools may check syntax; no dedicated local validator is required. This workflow omits config/summary dry-runs. Do not first export an unconfigured tool as a prerequisite to preparing its complete configuration.

4. Confirm the plan, pull, and record stages

Save final name, initial version 1, image identity, command, endpoints, resources, README, evidence, and exact commands in plan.md. Use confirmed file snapshots and field-by-field checks instead of the former helper-specific plan-hash protocol. pullPlanDigest, publishPlanDigest, and configuration checkpoint digests are not required. Optional file SHA-256 values do not replace content review. If any confirmed field changes, update the plan and obtain authorization for the changed action before executing it.

Record stages sequentially; these labels are task records, not fkit arguments:

PLANNED → IMAGE_VERIFIED → CREATED → CONFIGURED_VERIFIED

Enter PLANNED after duplicate, evidence, and local configuration checks. Present a user-facing plan once: the tool purpose and key features, name and version, command, inputs and outputs, parameters, resource recommendation, downstream connections, and known limitations. Keep image digests, worker type, workspace, internal validation commands, and cleanup steps in internal evidence instead of the main display. End with one confirmation asking whether to create and configure according to this plan; after confirmation, continue through the complete workflow.

After confirmation, continue without stage approvals. Reuse an existing local image only after its identity matches the plan; otherwise pull the planned image once and inspect it:

docker pull --platform linux/amd64 IMAGE
docker image inspect IMAGE

Check actual Os, Architecture, and RepoDigests against the planned identity. Record local image ID, platform, and tag-to-digest evidence before entering IMAGE_VERIFIED. A matching tag or successful exit alone is insufficient. Missing evidence, wrong architecture, tag drift, or digest mismatch stops the tool. Preserve the result; do not rewrite the plan to conceal a mismatch.

5. Create the tool and continue

Within the approved plan, continue directly after IMAGE_VERIFIED. Refresh fkit tool list --json and inspect the local image before creation. Stop on a duplicate, changed identity, or failed query; do not ask again at a normal stage transition.

fkit create-tool IMAGE TOOL_NAME --json

Record real toolId, toolVersionId, toolName, and version. Require the planned name and version exactly 1. Query fkit tool list --json again, locate the real ID/name, and require versionList to equal [1]. Do not invent IDs or derive platform versions from software versions.

A remote object now exists. Record CREATED and continue directly to formal configuration, without config/summary dry-runs or a configuration confirmation checkpoint. Do not yet claim configuration success.

6. Apply and read back

Use the complete plan’s existing authorization. Verify the files against confirmed snapshots and the same tool identity and initial version. Execute the following commands sequentially without another confirmation. Stop if any command fails. Formal apply has no --yes:

fkit tool config apply TOOL:VERSION --file WORKSPACE/spec/tool_config.json
fkit tool summary apply TOOL:VERSION --file WORKSPACE/spec/README.md
fkit tool config export TOOL:VERSION --output WORKSPACE/spec/tool_config.after.json
fkit tool summary export TOOL:VERSION --output WORKSPACE/spec/README.after.md

Use new export filenames without overwriting configuration or prior evidence. Compare parsed JSON structure and values, ignoring object-key order, indentation, and equivalent numeric formatting while preserving array order and detecting missing/extra fields. Compare the complete exported raw Markdown summary, not --section output or a JSON wrapper; do not ignore actual content differences.

Only a complete match permits CONFIGURED_VERIFIED. Write result.json with real tool/version IDs, name, version, image tag/digest, configuration/summary and read-back paths, and comparison outcome. If configuration succeeds but summary fails, report partial success and stop, preserving what was written. Do not automatically retry, roll back, create a version, or begin validation. Failed exports or mismatches cannot be reported as verified.

7. Completion state

Clean up the image pulled for this creation

The complete creation plan must include automatic cleanup of the newly pulled local image after creation, configuration, and read-back all succeed. The single plan confirmation covers this cleanup; do not ask again. Before pulling, record whether the exact reference already exists and its image ID. After pulling, record the actual reference, image ID, and RepoDigest. Preserve pre-existing images reused by this operation; also preserve an image if its ownership by this operation cannot be established.

Clean up only after CONFIGURED_VERIFIED, not immediately after upload while configuration or read-back is pending. Reinspect the reference and confirm it still points to the recorded image ID; skip it if identity changed. Run docker image rm IMAGE for the exact newly added reference, without --force. Do not remove other references by image ID, run global image/system prune, or stop/remove containers. Other tags or containers may retain the image or prevent removal: report whether only the tag was removed or space could not be reclaimed, without forcing cleanup.

Check whether the reference remains afterward and record the target, outcome, and any reason for retaining it in result.json. Cleanup failure does not reverse remote success: report that the tool was created and configured but local image cleanup remains incomplete. Preserve the error without retrying creation. Retain the image for diagnosis if creation, configuration, or read-back fails. Removing a local reference does not delete the uploaded BioLine tool image.

After a successful read-back, report that the BioLine tool was created and configured. This workflow ends here and does not proactively suggest or start Flow/Job validation. If the user later explicitly requests validation, read the relevant online command pages and run that as a separate workflow.

Clean up the local temporary workspace

After the tool reaches CONFIGURED_VERIFIED and image cleanup completes, delete the dedicated WORKSPACE, including draft configs, summaries, exports, logs, and temporary archives; also remove temporary files created under --tmp. Persist the final status, tool ID, version ID, and cleanup result before deletion. Never delete another task's directory, pre-existing images, or shared caches.

If creation, configuration, read-back verification, or image cleanup fails, retain WORKSPACE, logs, and evidence, report the path, and do not delete diagnostic evidence just to clean up.

Output and failure handling

Report conclusion, evidence, risk, and next step at each stage. Evidence consists of paths, image identity, previews, or real returned identifiers, not internal reasoning, raw protocols, debug dumps, or credentials. In logs/error.md, record stage, mismatch, reason, and permitted next choices: more evidence, corrected request, human review, or cancellation.

Preserve working directories, logs, and existing remote objects on failure or cancellation. Do not fabricate success. A failed creation command may already have created a remote object: record the uncertainty and investigate read-only before any further action, never blindly rerun. Continue independent tools after one fails unless the user stops the batch; project/authentication query failure stops the batch. Summarize existing/skipped, creation failed, configured/not validated, validation passed, and validation failed separately.

Read this page

fkit create-tool --docs
fkit create-tool --docs --docs-json --docs-lang en

Before validating business arguments, checking login, or creating a tool, fkit reads the official index at https://www.bioline.cloud/ai/commandLineAndFkit/, resolves create-tool, and returns that page in full. It does not recursively fetch links. --docs-json wraps documentation only. The current AI service publishes Chinese content; --docs-lang en does not translate it or select the English website. Reading documentation creates no tool, and editing local source does not publish it online.

Output-directory lifecycle

Before creating a Tool, establish the program's actual output-directory behavior. If the program requires the -o directory not to exist before execution, the command must not run mkdir -p first. Pre-creation is allowed only when evidence shows that the program accepts an existing directory; overwrite flags are allowed only when the selected version explicitly supports them. mkdir -p, --force, and rm -rf are not universal templates and must not be added without tool-version evidence.

Run local tests from a clean work directory: confirm the output directory is absent, run the complete command, and check exit status and every artifact; repeat when needed to record behavior on an existing output directory. Do not add directory creation, overwrite, or cleanup logic merely to make a test pass.

Hard file endpoint rule

A ype: file and path: file placeholder is the final file path; never append a subdirectory or pass it to mkdir. Only directory endpoints may have filenames appended. Minimal tests must use the real /io/directory/filename expansion and verify the complete command and all cp/mv post-processing.