Create a Tool

Tool authoring runs in the authoring lane and produces a versioned, verifiable, and discoverable BioLine Tool. The execution lane does not create it.

1. Documentation and draft

Load the exact fkit command pages needed for the operation and record their document IDs. Draft artifacts depend on the kind: a new Tool (tool) provides --config, --summary, and --image-metadata; a new Tool Version (tool_version) reuses the image already stored on the server for its baseline, so it provides only --config and --summary, and passing --image-metadata is rejected. Filenames never select artifact types. Summary front matter declares analysis_lane and fixed_command, and includes top-level # 中文 and # English sections. An upstream Tool requires fixed_command: true and a stable config command. A downstream Tool requires fixed_command: false and empty config command fields.

2. Build confirmation

At awaiting_build_confirmation, a new Tool shows the pinned image source, tag/digest, resource basis, and pull plan. Only explicit user confirmation may set confirmations.build and pull the fixed image. Record whether it existed before, its prior image ID, the post-pull image ID, and the task ID. This path applies to a new Tool.

A new Tool Version pulls nothing. After confirmation, fkit re-verifies that the exact baseline still resolves and records the reuse in draft.baseline: verified, reference, existing_tool_id, versions, selected_version, next_version, and the fixed value image: inherited-from-baseline. If the baseline's Tool ID or selected version changed since bootstrap, the build fails into build_failed and you must reload documentation before retrying.

Both paths enter built on success; failure enters build_failed with evidence. Publication is never automatic.

3. Static validation

test does not start a container, run a smoke command, or perform a real analysis. It statically checks config, summary, stable command, placeholders, ports, and resource fields, then stores checks, time, and evidence in validation. Publication requires passed static validation; failure enters test_failed.

4. Publish, register, handoff

After static validation passes, show the publication impact and obtain a separate publish confirmation. A new Tool uses fkit create-tool IMAGE NAME --json. A new Tool Version uses fkit update SOURCE_NAME:SOURCE_VERSION --mode new-version --config config.json --summary summary.md --json, where both files are required; fkit reuses the image already stored on the server for the source version, chooses max positive version plus one, and carries the command and summary inside the create request. Save the returned IDs and exact NAME:VERSION in result.json.

Then obtain a separate register confirmation. A new Tool dry-runs config/summary, applies the explicit files, and compares exact read-back exports. A new Tool Version already carried its config and summary inside the create request, so registration only reads BioLine back instead of issuing a redundant write that would hide a failed publish. BioLine rejects changes to Flow-referenced versions; surface the server error without retry or automatic new-version fallback.

Only a new Tool may clean up the task-pulled image, and only when the recorded ledger proves cleanup is safe after exact read-back verification. A new Tool Version pulled no local image, so cleanup is never eligible.

The handoff contains verified real IDs and time only; it never appends to a shared map. A future execution discovers this Tool or version dynamically through fkit.