Document ASPEN dryrun/run console output examples

[kopardev]

Summary

The docs currently explain the run artifacts such as dryrun.log, submit_script.sbatch, pipeline.running, and pipeline.status.json, but they do not show users what the wrapper's structured console output looks like during dryrun and run.

This caused confusion during issue #141 testing: the wrapper printed helpful STEP, OK, INFO, and NEXT lines, but there is no example in the docs showing that this is expected or how those lines relate to the files in WORKDIR.

Example output that should be documented

During run, ASPEN prints output like:

OK    Dry-run was successful.
STEP  [run] Preparing workdir for new execution
OK    Created <WORKDIR>/submit_script.sbatch
INFO  State marker updated: pipeline.running (reason=submission_started, slurm_job_id=NA)
INFO  State marker updated: pipeline.running (reason=sbatch_submitted, slurm_job_id=<jobid>)
------------------------------------------------------------------
OK    Job submitted successfully (SLURM job ID: <jobid>)
NEXT  Monitor:  squeue -u $USER
NEXT  Progress: tail -f <WORKDIR>/snakemake.log
NEXT  Status:   ls -1 <WORKDIR>/pipeline.*
NEXT  Sidecar:  <WORKDIR>/pipeline.status.json

During dryrun, ASPEN now also prints:

OK    Dry-run completed.
INFO  Full dry-run output captured in <WORKDIR>/dryrun.log
NEXT  Submit run with: aspen --workdir=<WORKDIR> --runmode=run

Problem

A new or occasional user may not realize that:

• these STEP / OK / INFO / NEXT lines are intentional wrapper output
• the NEXT lines are effectively the "what should I do now?" guidance
• the INFO lines about pipeline.running and pipeline.status.json correspond to concrete files already documented elsewhere
• the full dry-run transcript is saved in dryrun.log, not just the short terminal summary

Suggested docs change

Add a short subsection to docs/deployment.md such as:

• "What successful dry-run output looks like"
• "What successful run submission output looks like"

Include:

• a small realistic example block for dryrun
• a small realistic example block for run
• one or two sentences explaining what STEP, OK, INFO, and NEXT mean in practice
• explicit linkage between the console output and the files in WORKDIR (dryrun.log, submit_script.sbatch, pipeline.running, pipeline.status.json, snakemake.log)

Acceptance criteria

• docs/deployment.md contains at least one concrete example of successful dryrun output.
• docs/deployment.md contains at least one concrete example of successful run submission output.
• The docs explain that the full dry-run transcript is written to dryrun.log.
• The docs explain that the NEXT lines are follow-up actions or monitoring hints.
• The docs cross-reference the already-documented state files rather than duplicating long file descriptions.

Why this matters

This is a small documentation improvement, but it reduces confusion at exactly the moment a user is deciding whether ASPEN behaved correctly after dryrun or run.

_{⚡ Generated using AI ⚡}

[kopardev]

Completed by #153, which added successful dry-run and run-submission console examples to the deployment documentation. The documentation now explains the STEP, OK, INFO, and NEXT prefixes; identifies dryrun.log as the full dry-run transcript; and maps the console guidance to submit_script.sbatch, pipeline.running, pipeline.status.json, and snakemake.log.

_{⚡ Generated using AI ⚡}