---
name: biosimulant-readme-publish
title: Biosimulant README And Publishing
description: Generate lab README screenshots, document runtime visuals, publish labs to the Hub, and verify public completed-run availability.
version: 2026.05.23
tags: [biosimulant, readme, screenshots, hub, publishing]
audience: Claude Code, Cursor, Continue, Aider
recommended: true
---

# Biosimulant README And Publishing

Use this skill when documenting labs, capturing screenshots, publishing to Hub, or verifying that public labs show
successful runs.

Biosimulant public labs are runnable scientific packages. README screenshots should show real runtime visualisations
from the lab, not static marketing images or placeholder tables.

## README Requirements

Every publish-worthy lab should have a top-level `README.md` beside `lab.yaml`.

The README should explain:

- what the lab simulates or executes
- upstream source and bundled artifact
- public inputs and exact source/runtime mappings
- public outputs and exact source/runtime mappings
- scenario/defaults used in screenshots
- what each visual shows
- validation performed
- caveats and limits of scientific claims

Do not overclaim. Phrase results as simulation output from the configured run unless source/reference parity proves more.

## Screenshot Workflow

Use dark-mode runtime captures. Typical process:

```bash
cd /Volumes/dem-ssd/imp/projects/Nitoons/Biosimulant/bsim-active/stuff/utils/auto-readme

node capture-lab-visuals.mjs \
  /absolute/path/to/lab \
  --update-readme \
  --timeout-ms 600000 \
  --biosimulant-bin /Volumes/dem-ssd/imp/projects/Nitoons/Biosimulant/bsim-active/biosimulant-desktop/src-tauri/target/debug/biosimulant
```

Default output is `<lab>/assets/*.png`. README image paths should be relative:

```markdown
![Selected physiology trajectories](assets/02-selected-physiology-trajectories.png)
```

Preserve generated markers when present:

```markdown
<!-- BIOSIMULANT_VISUALS_START -->
<!-- BIOSIMULANT_VISUALS_END -->
```

## Visual QA

Before publishing:

- open at least one timeseries and one summary/table image when present
- confirm the graph is not empty
- confirm labels are readable and not stale
- confirm every generated PNG is referenced by README
- remove empty `assets/` folders
- stop leftover `labs serve` processes
- avoid accidental `.biosimulant-project.json` changes unless publishing is intended

## Publish Workflow

```bash
biosimulant auth status --json
biosimulant labs validate /absolute/path/to/lab --strict --json
biosimulant labs run /absolute/path/to/lab --json --no-open
biosimulant labs publish /absolute/path/to/lab --visibility public --json --no-open
```

Publishing writes or refreshes `<lab>/.biosimulant-project.json`. Keep that file when the lab should stay linked to the
Hub package.

## Successful Run Gate

Do not use `hub labs list --json` to verify completed runs; it may show `completed_runs: null`. Use the Hub detail
endpoint:

```bash
hub_id=$(jq -r '.hub_id' /absolute/path/to/lab/.biosimulant-project.json)
biosimulant hub labs get "$hub_id" --json \
  | jq '.data | {is_public, completed_runs, run_count, package_name}'
```

Acceptance condition:

```text
is_public == true
completed_runs >= 1
```

If `completed_runs` is `0`, `null`, or missing, upload or sync a completed local run:

```bash
biosimulant runs upload <run-id> --json

local_id=$(jq -r '.local_id' /absolute/path/to/lab/.biosimulant-project.json)
biosimulant raw hub_sync_lab_runs --input "{\"lab_id\":\"$local_id\"}" --json
```

Then re-run the Hub detail check.

## Batch Publishing

For large batches:

- publish serially or in small controlled batches
- log `slug`, `package_name`, `hub_id`, `is_public`, `completed_runs`, `run_count`, and warnings
- retry transient upload errors before editing lab manifests
- stop when repeated failures indicate a backend or network issue
- do not count a lab complete until the Hub detail endpoint passes the run gate