@andrian.yablonskyy/thub-coordinator 1.0.37 → 1.0.39

package/views/help/_docker.pug

@@ -0,0 +1,124 @@
++section('docker', 'Docker registry integration', 'box-seam')
+  p.
+    A job can use Docker in two different ways. Keep them apart, because they log in and run differently:
+  .row.g-3.mb-3
+    .col-md-6
+      .card.h-100
+        .card-body.small
+          h3.h6 #[code --docker-image]: the DUT
+          p.mb-0.
+            SW jobs only. The Client pulls the image and runs it as the job's #[strong DUT container]
+            (an emulator the tests talk to), sandboxed, next to your command. The pull uses the
+            #[strong Client host's] Docker login, made once by the service user.
+    .col-md-6
+      .card.h-100
+        .card-body.small
+          h3.h6 #[code docker …] inside #[code --command]
+          p.mb-0.
+            Any job type, on a host with Docker. Your command logs in, pulls and runs containers
+            itself, e.g. to run the tests #[em inside] an image. Credentials come from the job
+            (#[code --env]) and are scoped to the job.
+
+  h3.h6 Log in to a registry on the Client host (for --docker-image)
+  p.small.
+    #[code --docker-image] is pulled with #[code docker pull] as the Client's service user, from the registry the reference names
+    (Docker Hub for a short name such as #[code python:3.14]). Log in once per host, as that user:
+  +code('Client host').
+    # the user that runs thub-client (the one who ran sudo npm i -g), e.g. thub:
+    sudo -u thub docker login registry.lab.local:5000
+    sudo -u thub docker login ghcr.io -u <github-user>        # password: a PAT with read:packages
+    sudo -u thub docker pull registry.lab.local:5000/dut-emulator:2026.08   # check it works
+  p.small.
+    A plain-HTTP registry must be listed in the Docker daemon's #[code insecure-registries]:
+  +code('/etc/docker/daemon.json').
+    { "insecure-registries": ["registry.lab.local:5000"] }
+  p.small.
+    Then run #[code sudo systemctl restart docker]. An image that can't be pulled ends the job as #[code ERROR]
+    during #[em prepare], naming the registry and Docker's reason. An image already on the host isn't pulled again.
+
+  h3.h6 How the Client starts the DUT container
+  p.small.
+    You don't pass #[code docker run] parameters for the DUT. The Client always starts it like this (image default command,
+    sandboxed), and removes it and its network when the job ends:
+  +code('What the Client runs (equivalent)').
+    docker pull registry.lab.local:5000/dut-emulator:2026.08
+    docker network create --driver bridge thub-job-<jobId>
+    docker run -d --name thub-<jobId> --network thub-job-<jobId> \
+      --memory 2g --cpus 2 --read-only \
+      -v <workDir>/<jobId>/downloads:/downloads:ro \
+      -p 127.0.0.1::5555 registry.lab.local:5000/dut-emulator:2026.08
+  ul.small
+    li The image must #[strong start the DUT by itself] (its #[code CMD]/#[code ENTRYPOINT]) and should listen on port #[strong 5555].
+    li The job's #[code --download-file] files are mounted read-only at #[code /downloads] (e.g. the firmware to emulate).
+    li The command reaches it at #[code $THUB_DUT_HOST] (#[code 127.0.0.1:<port>]) and by name as #[code $THUB_DUT_CONTAINER].
+    li Its output is shipped as the #[code emulator] log stream. Its root filesystem is read-only: don't install or clone into it.
+    li #[code thub run --dry-run] prints the exact docker commands a job would run, without running anything.
+
+  h3.h6 Execute commands in the DUT container
+  +code('SW job: talk to the DUT').
+    thub run --type sw \
+      --docker-image registry.lab.local:5000/dut-emulator:2026.08 \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.elf \
+      --command 'docker exec "$THUB_DUT_CONTAINER" /opt/emu/status &&
+                 docker logs "$THUB_DUT_CONTAINER" | tail -n 20 &&
+                 ./ci/test.sh --dut "$THUB_DUT_HOST"' \
+      --wait
+
+  h3.h6 Log in and pull inside a job (credentials scoped to the job)
+  p.small.
+    Pass the credentials as #[code --env] (masked everywhere, dropped when the job ends). Set #[code DOCKER_CONFIG] to the
+    job's work directory so the login is deleted with the workspace instead of staying in the service user's
+    #[code ~/.docker] for every later job:
+  +code('Any job type').
+    export DOCKER_PASSWORD=…        # from your CI secret store, never on the command line
+    thub run --type hw \
+      --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
+      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
+                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+                 docker pull "$DOCKER_REGISTRY/team/test-runner:1.4"' \
+      --wait
+
+  h3.h6 Run the tests inside a container (docker run parameters)
+  p.small.
+    The command always starts on the Client host, in #[code $THUB_WORK_DIR] (the #[code --git-repo] checkout). Mount it,
+    hand over the variables the tests need with #[code -e NAME], and use #[code --rm]:
+  +code('Tests in an image').
+    thub run --type sw \
+      --env DOCKER_REGISTRY=registry.lab.local:5000,DOCKER_USER=ci --env DOCKER_PASSWORD \
+      --env TARGET=staging \
+      --git-repo git@github.com:yourorg/web-ui-tests.git main \
+      --command 'export DOCKER_CONFIG="$THUB_WORK_DIR/.docker" &&
+                 echo "$DOCKER_PASSWORD" | docker login "$DOCKER_REGISTRY" -u "$DOCKER_USER" --password-stdin &&
+                 docker run --rm \
+                   -v "$THUB_WORK_DIR:/work" -w /work \
+                   -e TARGET -e THUB_SUITE -e THUB_JOB_ID \
+                   --network host \
+                   "$DOCKER_REGISTRY/python:3.14" ./run-tests.sh --junit results/junit.xml' \
+      --wait
+  table.table.table-sm.small
+    thead
+      tr
+        th docker run option
+        th Why
+    tbody
+      tr
+        td: code --rm
+        td Removes the container when the tests end.
+      tr
+        td: code -v "$THUB_WORK_DIR:/work" -w /work
+        td The checkout and downloads, and the #[code results/] and #[code artifacts/] folders, where the Client reads JUnit XML for the test counts.
+      tr
+        td: code -e NAME
+        td Passes a job variable (#[code --env], #[code THUB_*], #[code JOB_*]) into the container.
+      tr
+        td: code --network host
+        td Lets the container reach the DUT at #[code $THUB_DUT_HOST] (#[code 127.0.0.1:<port>]).
+      tr
+        td: code --device /dev/thub/dut1-uart
+        td HW: gives the container the DUT's UART (#[code "$THUB_DUT_UART"]). Use #[code --privileged] only if you must.
+      tr
+        td: code --user "$(id -u):$(id -g)"
+        td Files written to #[code /work] stay owned by the Client user, so the workspace can be cleaned up.
+  +note('info').
+    Docker access is effectively root access on that host. The Client host must have Docker and the service user must be in the
+    #[code docker] group. The resource card's #[strong Capabilities] show whether a Client can use Docker, and why not.

package/views/help/_env.pug

@@ -0,0 +1,127 @@
++section('env', 'Environment variables on the Client', 'braces')
+  p.
+    #[code --command] runs on the Client with the service's own environment (#[code PATH], #[code HOME], …) plus three sets of
+    variables. Every value is a string. A variable whose option wasn't given is #[strong unset], so use
+    #[code ${VAR:-default}] in shell. A repeatable option gives one combined variable plus #[code NAME_1], #[code NAME_2], …
+    (1-based, in the order given).
+
+  h3.h6 Set by the Client: #[code THUB_*]
+  -
+    const thubVars = [
+      ['THUB_JOB_ID', 'The job id, e.g. M-00125'],
+      ['THUB_WORK_DIR', 'The directory the command runs in: the --git-repo checkout, else empty. JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
+      ['THUB_SUITE', '--suite (default: default)'],
+      ['THUB_GIT_COMMIT', 'The exact commit checked out for --git-repo'],
+      ['THUB_DOWNLOADS_DIR', 'Where the --download-file files are'],
+      ['THUB_DOWNLOADS / THUB_DOWNLOAD_<n>', 'Local paths of the downloads: all, one per line / each one'],
+      ['THUB_META_<KEY>', '--meta values; camelCase keys become SNAKE_CASE (ciJobId → THUB_META_CI_JOB_ID)'],
+      ['THUB_DUT_STLINK / _<n>', 'HW: ST-Link serials (device path if the serial couldn\'t be read); unsuffixed = the first'],
+      ['THUB_DUT_UART / _<n>', 'HW: UART device paths (/dev/thub/dut<N>-uart); unsuffixed = the first'],
+      ['THUB_DUT_USB / _<n>', 'HW: DUT USB device paths'],
+      ['THUB_DUT_HOST', 'SW with --docker-image: 127.0.0.1:<port> of the DUT container\'s port 5555'],
+      ['THUB_DUT_CONTAINER', 'SW with --docker-image: the DUT container\'s name (docker exec / docker logs)']
+    ]
+  .table-responsive
+    table.table.table-sm.small
+      tbody
+        each v in thubVars
+          tr
+            td(style="width: 34%"): code= v[0]
+            td= v[1]
+
+  h3.h6 Job parameters: #[code JOB_*]
+  p.small Each #[code thub run] option that reaches the Client, as given:
+  -
+    const jobVars = [
+      ['JOB_TYPE', '--type', 'hw or sw'],
+      ['JOB_BOARD', '--board', 'the board name'],
+      ['JOB_LABEL / JOB_LABEL_<n>', '--board, --label', 'all labels, comma-separated / each'],
+      ['JOB_GROUP', '--group', 'the group id'],
+      ['JOB_CLIENT', '--client', 'this Client\'s name'],
+      ['JOB_USER', '--user', 'as given'],
+      ['JOB_COMMAND', '--command', 'the command itself'],
+      ['JOB_DOWNLOAD_FILE / _<n>', '--download-file', 'the URLs (the local files are THUB_DOWNLOAD_<n>)'],
+      ['JOB_DOCKER_IMAGE', '--docker-image', 'the image reference'],
+      ['JOB_GIT_REPO_URL', '--git-repo <url>', 'the repository URL'],
+      ['JOB_GIT_BRANCH', '--git-repo <url> <ref>', 'branch, tag or commit as given (unset = default branch)'],
+      ['JOB_GIT_DEPTH', '--depth', 'commits fetched (1 by default, 0 = full)'],
+      ['JOB_GIT_OPTIONS', '--git-options', 'as given'],
+      ['JOB_SUITE', '--suite', 'as given, default when not'],
+      ['JOB_ARG / JOB_ARG_<n>', '--arg', 'all, space-separated / each (also "$@")'],
+      ['JOB_TIMEOUT', '--timeout', 'seconds'],
+      ['JOB_PRIORITY', '--priority', '0–100'],
+      ['JOB_META_<KEY>', '--meta key=value', 'the value'],
+      ['<NAME>', '--env NAME=value', 'your own variables, under the names you chose']
+    ]
+  .table-responsive
+    table.table.table-sm.small
+      thead
+        tr
+          th Variable
+          th From
+          th Value
+      tbody
+        each v in jobVars
+          tr
+            td: code= v[0]
+            td: code.text-nowrap= v[1]
+            td= v[2]
+  p.small.
+    #[code --url], #[code --token], #[code --wait], #[code --detach], #[code --json] and #[code --dry-run] only affect the Agent and
+    have no variable. The Client's own git commands also get #[code GIT_TERMINAL_PROMPT=0] and #[code GIT_ALLOW_PROTOCOL=http:https:ssh:git].
+
+  h3.h6 Your own variables: #[code --env]
+  ul.small
+    li #[code --env NAME=value[,NAME=value]], repeatable. A comma starts a new variable only when #[code NAME=] follows it, so values may contain commas.
+    li #[code --env NAME] alone takes the value from the Agent's environment. That keeps secrets off the command line, out of shell history and out of CI logs.
+    li Any names except #[code THUB_*], #[code JOB_*], #[code GIT_TERMINAL_PROMPT] and #[code GIT_ALLOW_PROTOCOL].
+    li They apply to every command the Client runs for the job: the #[code --git-repo] git commands and #[code --command].
+    li
+      | Every value is treated as a secret. It's sent only to the Client running the job, shown as #[code ***] by the API,
+      | #[code thub status --json] and #[code --dry-run], and wiped from the Coordinator's database when the job ends.
+      | The dashboard lists only the names.
+  +note('warning').
+    The command's own output #[strong is] the job log, which is stored and visible on the dashboard. Never #[code echo] a
+    secret, and avoid #[code set -x] in scripts that use one.
+
+  h3.h6 Using them in your scripts
+  +code('ci/test.sh (shell)').
+    #!/bin/sh
+    set -eu
+    echo "Job $THUB_JOB_ID on $(hostname), suite ${THUB_SUITE}, commit ${THUB_GIT_COMMIT:-n/a}"
+
+    # optional parameters with defaults
+    TARGET="${TARGET:-staging}"
+    BRANCH="${JOB_GIT_BRANCH:-main}"
+
+    # every downloaded file
+    printf '%s\n' "$THUB_DOWNLOADS" | while read -r f; do echo "downloaded: $f"; done
+
+    # HW: flash through the first ST-Link, talk to the second UART
+    st-flash --serial "$THUB_DUT_STLINK" --reset write "$THUB_DOWNLOAD_1" 0x08000000
+    python3 -m pytest tests/ --uart "${THUB_DUT_UART_2:-$THUB_DUT_UART}" --junitxml=results/junit.xml
+
+    # CI metadata passed with --meta ciJobId=… / --meta sha=…
+    echo "CI run ${THUB_META_CI_JOB_ID:-local}, sha ${THUB_META_SHA:-unknown}"
+  +code('conftest.py (Python)').
+    import os
+
+    DUT_HOST  = os.environ.get("THUB_DUT_HOST", "127.0.0.1:5555")   # SW DUT container
+    UARTS     = [v for k, v in sorted(os.environ.items()) if k.startswith("THUB_DUT_UART_")]
+    FIRMWARE  = os.environ.get("THUB_DOWNLOAD_1")
+    RESULTS   = os.path.join(os.environ.get("THUB_WORK_DIR", "."), "results")
+    API_TOKEN = os.environ["API_TOKEN"]                              # from --env API_TOKEN
+  +code('Into a container: -e NAME copies a variable from the job').
+    docker run --rm -v "$THUB_WORK_DIR:/work" -w /work \
+      -e THUB_JOB_ID -e THUB_SUITE -e TARGET -e API_TOKEN \
+      python:3.14 ./run-tests.sh
+  +code('Submitting the job that feeds these').
+    export API_TOKEN=…
+    thub run --type hw --board nucleo-f401re \
+      --download-file https://artifactory.example.com/fw-local/app/1.4.0-42/app.bin \
+      --git-repo git@github.com:yourorg/firmware-tests.git main \
+      --env TARGET=production --env API_TOKEN \
+      --meta ciJobId="$GITHUB_RUN_ID" --meta sha="$GITHUB_SHA" \
+      --suite smoke --command ./ci/test.sh --wait
+  p.small.text-body-secondary.mb-0.
+    Tip: #[code thub run … --dry-run] lists every variable the command would get on the chosen Client, with #[code --env] values as #[code ***].

package/views/help/_git.pug

@@ -0,0 +1,130 @@
++section('git', 'Git repository integration', 'git')
+  p.
+    #[code --git-repo] makes the Client clone a repository before the job runs. #[code --command] then runs inside the checkout
+    (#[code $THUB_WORK_DIR]). Typically the repository holds the test scripts. The firmware comes as a #[code --download-file]
+    or is built by the command.
+
+  h3.h6 1. Create a test repository
+  +code('Your machine').
+    mkdir firmware-tests && cd firmware-tests && git init -b main
+    mkdir -p ci
+    cat > ci/test.sh <<'EOF'
+    #!/bin/sh
+    set -eu
+    echo "job $THUB_JOB_ID, suite $THUB_SUITE, commit $THUB_GIT_COMMIT"
+    mkdir -p results
+    pytest --junitxml=results/junit.xml tests/     # results/*.xml is uploaded and summarized
+    EOF
+    chmod +x ci/test.sh
+    git add . && git commit -m "TestHub entry point"
+    git remote add origin git@github.com:yourorg/firmware-tests.git
+    git push -u origin main
+  p.small.
+    The exit code of #[code --command] is the verdict. JUnit files under #[code results/] or #[code artifacts/] are summed into
+    the job's test counts. Nothing is uploaded: the workspace is deleted when the job ends, so publish anything you need to keep
+    from the command itself (e.g. #[code curl -T report.html "$ARTIFACTORY/…"] with a token passed as #[code --env]).
+
+  h3.h6 2. Give Clients read access: SSH deploy key (recommended)
+  p.small.
+    git never prompts on a Client (#[code GIT_TERMINAL_PROMPT=0]), so credentials must already be on the Client host,
+    owned by the #[strong Client's service user]. Create a key on each Client host (or one shared key per lab):
+  +code('Client host, as the Client\'s user').
+    ssh-keygen -t ed25519 -N "" -C "thub-client@$(hostname)" -f ~/.ssh/thub_deploy
+    cat ~/.ssh/thub_deploy.pub          # → add as a read-only deploy key (below)
+    # trust the git server's host key now: the service can't answer prompts
+    # (and can't write ~/.ssh under systemd)
+    ssh-keyscan github.com bitbucket.org gitlab.com >> ~/.ssh/known_hosts
+    # use the key for that server
+    cat >> ~/.ssh/config <<'EOF'
+    Host github.com
+      IdentityFile ~/.ssh/thub_deploy
+      IdentitiesOnly yes
+    EOF
+    chmod 600 ~/.ssh/config
+    ssh -T git@github.com                # "…successfully authenticated…"
+  table.table.table-sm.small
+    thead
+      tr
+        th Git server
+        th Where to add the public key
+    tbody
+      tr
+        td GitHub
+        td Repository → Settings → Deploy keys → Add deploy key (leave “Allow write access” off). For many repositories, use a machine user's SSH key instead.
+      tr
+        td GitLab
+        td Project → Settings → Repository → Deploy keys.
+      tr
+        td Bitbucket
+        td Repository settings → Security → Access keys.
+      tr
+        td Gitea / self-hosted
+        td Repository → Settings → Deploy Keys, or the machine user's SSH keys.
+  p.small.
+    Without #[code ~/.ssh/config], pick the key per job with #[code --git-options] (stored with the job, so reference a key
+    #[em file], never inline a secret):
+  +code('Per-job SSH key / port').
+    thub run --type sw \
+      --git-repo ssh://git@git.lab.local:2222/qa/tests.git main \
+      --git-options '-c core.sshCommand="ssh -i ~/.ssh/thub_deploy -o IdentitiesOnly=yes"' \
+      --command ./ci/test.sh --wait
+
+  h3.h6 HTTPS with a token
+  p.small.
+    For #[code https://] repositories, either store a credential helper for the Client's user on the host
+    (#[code git config --global credential.helper store]), or pass the token #[strong per job] as a secret. #[code --env]
+    variables reach the Client's own git commands, and git reads config from #[code GIT_CONFIG_COUNT]/#[code _KEY_n]/#[code _VALUE_n]:
+  +code('Token per job, never stored').
+    # GitHub: user x-access-token; GitLab: oauth2; Bitbucket: x-token-auth
+    export GIT_CONFIG_VALUE_0="Authorization: Basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
+    thub run --type sw \
+      --git-repo https://github.com/yourorg/private-tests.git main \
+      --env GIT_CONFIG_COUNT=1,GIT_CONFIG_KEY_0=http.extraHeader --env GIT_CONFIG_VALUE_0 \
+      --command ./ci/test.sh --wait
+  p.small.
+    Don't put a token in the URL, #[code --git-options], #[code --command] or #[code --meta]: those are stored with the job
+    and visible to anyone who can read it. Only #[code --env] values are masked.
+
+  h3.h6 3. Clone options: ref, branch, tag, commit, depth
+  +code('--git-repo <url> [<branch>|<tag>|<commit>] [--depth <n>]').
+    --git-repo git@github.com:yourorg/tests.git                   # default branch, depth 1
+    --git-repo git@github.com:yourorg/tests.git develop           # a branch
+    --git-repo git@github.com:yourorg/tests.git v1.4.0            # a tag
+    --git-repo git@github.com:yourorg/tests.git a1b2c3d           # a commit (may be abbreviated)
+    --git-repo git@github.com:yourorg/tests.git main --depth 50   # last 50 commits
+    --git-repo git@github.com:yourorg/tests.git main --depth 0    # full history (git describe, changelogs)
+  table.table.table-sm.small
+    tbody
+      tr
+        th Transports
+        td #[code https://], #[code http://], #[code ssh://], #[code git://], #[code user@host:path]. #[code file://] and #[code ext::] are refused.
+      tr
+        th Default ref
+        td The repository's default branch.
+      tr
+        th Depth
+        td Default #[code 1]. #[code 0] = full history. If the server can't do shallow fetches (or the commit is abbreviated), the Client falls back to a full fetch.
+      tr
+        th Exact commit
+        td Logged, and passed to the command as #[code $THUB_GIT_COMMIT]. The requested ref is #[code $JOB_GIT_BRANCH].
+      tr
+        th Extra git options
+        td #[code --git-options] is inserted between #[code git] and its subcommand on every git call, e.g. #[code '-c http.sslVerify=false'] or #[code '-c core.sshCommand="…"'].
+  +code('What the Client runs (see it with --dry-run)').
+    git -C &lt;work> init -q
+    git -C &lt;work> remote add origin &lt;url>
+    git -C &lt;work> fetch -q --depth 1 origin &lt;ref>
+    git -C &lt;work> checkout -q --detach FETCH_HEAD
+    git -C &lt;work> rev-parse HEAD
+
+  h3.h6 Submodules, LFS and cloning inside a container
+  p.small.
+    The Client checks out only the repository itself. Do anything more in the command, which runs in the checkout with the same #[code --env] variables:
+  +code('Submodules / LFS').
+    thub run --type sw --git-repo git@github.com:yourorg/tests.git main \
+      --command 'git submodule update --init --recursive --depth 1 && git lfs pull && ./ci/test.sh' --wait
+  +code('Clone yourself, e.g. inside a container (JOB_GIT_* carry the --git-repo values)').
+    thub run --type sw --git-repo git@github.com:yourorg/tests.git main --depth 1 \
+      --command 'docker run --rm -v "$HOME/.ssh:/root/.ssh:ro" -e JOB_GIT_REPO_URL -e JOB_GIT_BRANCH -e JOB_GIT_DEPTH \
+                   --entrypoint sh alpine/git -c "git clone --depth \$JOB_GIT_DEPTH --branch \$JOB_GIT_BRANCH \$JOB_GIT_REPO_URL /src && ls /src"' \
+      --wait

package/views/help/_mixins.pug

@@ -0,0 +1,24 @@
+//- Help page building blocks. Code blocks are plain text: escape `<` as
+//- `&lt;` inside them (`>` and `&&` are fine). public/js/help.js adds a copy
+//- button to each, which copies the decoded text.
+mixin code(caption)
+  figure.thub-code.mb-3
+    if caption
+      figcaption.thub-code-caption= caption
+    pre
+      code
+        block
+
+//- One section of the help page: an anchor for the table of contents and a
+//- heading. `data-help-section` is what the filter box searches.
+mixin section(id, heading, icon)
+  section.thub-help-section.mb-5(id=id data-help-section)
+    h2.h4.border-bottom.pb-2.mb-3
+      if icon
+        i.bi.me-2.text-body-secondary(class=`bi-${icon}`)
+      = heading
+    block
+
+mixin note(tone)
+  .alert.small.py-2(class=`alert-${tone || 'info'}`)
+    block

package/views/help/_overview.pug

@@ -0,0 +1,118 @@
++section('overview', 'Product overview', 'info-circle')
+  p.
+    #[strong TestHub] is a small, self-hosted job network. It lets CI/CD pipelines and individual
+    developers run firmware and software tests on #[strong real hardware] or #[strong emulators]
+    that sit in a private lab behind a firewall. Nothing in the lab has to be reachable from outside.
+
+  .row.g-3.mb-3
+    .col-md-4
+      .card.h-100
+        .card-body
+          h3.h6.card-title
+            i.bi.bi-hdd-network.me-1
+            | Coordinator
+          p.card-text.small.mb-0.
+            This service. It holds the job queue and the resource registry, and runs the scheduler and
+            the heartbeat monitor. It stores job state and logs in SQLite,
+            and serves this dashboard. It's the only thing that needs a public HTTPS port.
+    .col-md-4
+      .card.h-100
+        .card-body
+          h3.h6.card-title
+            i.bi.bi-terminal.me-1
+            | Agent (#[code thub])
+          p.card-text.small.mb-0.
+            A CLI, and the only way to create jobs. The same #[code thub run] command works in a
+            GitHub Actions step and on a developer's laptop, so a CI failure can be reproduced exactly.
+    .col-md-4
+      .card.h-100
+        .card-body
+          h3.h6.card-title
+            i.bi.bi-motherboard.me-1
+            | Client (#[code thub-client])
+          p.card-text.small.mb-0.
+            A daemon (a systemd service) on a lab machine. Each instance owns one DUT slot. It connects
+            #[em outbound] to the Coordinator, picks up jobs, runs them and streams logs back.
+            Type #[strong HW] drives a physical board; type #[strong SW] runs a DUT emulator in Docker.
+
+  h3.h6 How a job flows
+  ol.small
+    li #[code thub run …] submits a job spec (type, labels, command, inputs) with an agent token.
+    li The Coordinator queues it (#[code QUEUED]) and the scheduler assigns it to an idle Client whose type, labels and group match.
+    li The Client accepts it, clones #[code --git-repo], downloads #[code --download-file] files and prepares the DUT (#[code PREPARING]).
+    li It runs #[code --command] with #[code sh -c], and output streams live to the Agent and the dashboard (#[code RUNNING]).
+    li The exit code is the verdict: #[code 0] = #[code PASSED], anything else = #[code FAILED]. The Client reports the JUnit test counts; the job's files stay on the Client and are deleted with its workspace.
+    li The Agent exits with the verdict code, so a CI step passes or fails with it.
+
+  h3.h6 Key design rules
+  ul.small
+    li #[strong Clients only connect outbound] over HTTPS: registration, heartbeat, long-poll, logs, results. The lab firewall allows no inbound traffic.
+    li #[strong The Agent is the only way to create jobs.] CI and manual runs are identical.
+    li #[strong The Coordinator is the single source of truth.] It assigns a job inside a single SQLite transaction, so a job can never be assigned twice.
+    li #[strong A job is a command, not a script upload.] The Client runs your #[code --command] as its service user, never as root. Issue agent tokens only to trusted pipelines and people.
+
+  h3.h6 Resource and job states
+  .row.g-3.small
+    .col-md-6
+      table.table.table-sm.mb-0
+        thead
+          tr
+            th Resource
+            th Meaning
+        tbody
+          tr
+            td: code REGISTERED
+            td Just registered, no heartbeat yet
+          tr
+            td: code IDLE
+            td Online and free: schedulable
+          tr
+            td: code BUSY
+            td Running a job (#[code ci] / #[code cli]) or locked by hand (#[code local])
+          tr
+            td: code OUT_OF_SERVICE
+            td 3 heartbeats missed
+          tr
+            td: code MAINTENANCE
+            td Disabled by an admin
+    .col-md-6
+      table.table.table-sm.mb-0
+        thead
+          tr
+            th Job
+            th Meaning
+        tbody
+          tr
+            td: code QUEUED → ASSIGNED
+            td Waiting for, then bound to, a Client
+          tr
+            td: code PREPARING → RUNNING
+            td Inputs and DUT being prepared, then the command runs
+          tr
+            td: code PASSED / FAILED
+            td The command's exit code: 0, or non-zero
+          tr
+            td: code ERROR / TIMEOUT
+            td Infrastructure problem, or #[code --timeout] exceeded
+          tr
+            td: code CANCELED / LOST
+            td Canceled, or the Client went offline mid-job
+
++section('use-cases', 'Use cases', 'lightbulb')
+  -
+    const useCases = [
+      { icon: 'cpu', title: 'Hardware-in-the-loop CI', text: 'Every push builds firmware in the cloud, then a GitHub Actions test job runs `thub run --type hw --wait`: a lab Client flashes a real board through ST-Link, captures its UART, runs the tests and fails the pipeline on a non-zero exit.' },
+      { icon: 'pc-display', title: 'Emulator (SW) test farms', text: 'SW Clients on real or virtual Linux machines run each job’s DUT image (QEMU, Renode, a simulator) in a sandboxed Docker container. The tests talk to it at $THUB_DUT_HOST. Scale out by adding VMs.' },
+      { icon: 'person-workspace', title: 'Remote access for developers', text: 'Developers reproduce a CI failure on the exact bench it happened on (`--client lab-hw-01`) from home, with the same command CI ran, and stream the board’s console live.' },
+      { icon: 'lock', title: 'Shared benches without collisions', text: 'The scheduler hands out one job per bench. An engineer who needs a board by hand runs `thub-client lock` so nothing is scheduled there until `unlock`.' },
+      { icon: 'collection', title: 'Dedicated pools', text: 'Groups and labels (`board:nucleo-f401re`, `uart`) route jobs to the right hardware, e.g. a nightly pool separate from the PR pool.' },
+      { icon: 'box-seam', title: 'Any command-line test suite', text: 'Anything that runs from a shell and reports through its exit code: pytest, ctest, Robot Framework, a Dockerized test runner, a flashing and smoke-test script.' }
+    ]
+  .row.g-3
+    each uc in useCases
+      .col-md-6
+        .d-flex.gap-3
+          i.bi.fs-4.text-primary(class=`bi-${uc.icon}`)
+          div
+            h3.h6.mb-1= uc.title
+            p.small.text-body-secondary.mb-0!= uc.text.replace(/`([^`]+)`/g, '<code>$1</code>')

package/views/help/_quick-start.pug

@@ -0,0 +1,37 @@
++section('quick-start', 'Quick start', 'rocket-takeoff')
+  p Five steps from nothing to a first job. Every step links to its full section.
+  ol.thub-help-steps
+    li
+      strong Install the Coordinator
+      |  on a cloud VM behind an HTTPS reverse proxy (#[a(href="#coordinator") Coordinator setup]):
+      +code('Coordinator host').
+        sudo npm i -g @andrian.yablonskyy/thub-coordinator
+        thub-admin join-key generate          # → put it in clientJoinKey
+        nano ~/.config/thub/coordinator.json  # publicUrl, clientJoinKey
+        sudo systemctl restart thub-coordinator
+        thub-admin create-admin admin 'a-strong-password'
+    li
+      strong Install a Client
+      |  on each lab machine, with the same join key (#[a(href="#client-setup") Client setup]):
+      +code('Lab machine (Ubuntu 26.04)').
+        sudo apt install -y nodejs npm docker.io      # + stlink-tools openocd for HW
+        sudo npm i -g @andrian.yablonskyy/thub-client
+        nano ~/.config/thub/client.json               # coordinatorUrl, type, joinKey
+        sudo systemctl enable --now thub-client@client
+      | It shows up on #[a(href="/resources") Resources] by itself, usually within 10 s.
+    li
+      strong Issue an agent token
+      |  on #[a(href="/admin/agents") Agents] (admins), or on the Coordinator host with
+      |  #[code thub-admin agent add <name> --kind ci|cli]. The token is shown once.
+    li
+      strong Install and configure the Agent
+      |  (#[a(href="#agent-setup") Agent setup]):
+      +code('Developer machine').
+        npm i -g @andrian.yablonskyy/thub-agent
+        thub config set url #{coordinatorUrl}
+        thub config set token agt_…
+    li
+      strong Run a job
+      |  (#[a(href="#agent-cli") Agent CLI reference]):
+      +code('Developer machine').
+        thub run --type sw --command 'uname -a && echo hello from the lab' --wait

package/views/help/_troubleshooting.pug

@@ -0,0 +1,44 @@
++section('troubleshooting', 'Troubleshooting', 'life-preserver')
+  //- `…` in a question or answer marks a command or parameter: rendered as
+  //- <code>, with everything else HTML-escaped first (so `<instance>` shows as text).
+  -
+    const faq = [
+      ['A Client doesn\'t appear on Resources', 'Check `journalctl -u thub-client@<instance> -f`. A `503` at registration means the Coordinator has no `clientJoinKey`; a `401` means the `joinKey` differs. Also check that `coordinatorUrl` is reachable from the lab (`curl -sI <url>/login`).'],
+      ['A Client flaps or two machines show as one resource', 'Both use the same `.client-id` (a cloned VM or a shared config file). Delete `<varDir>/<instance>/.client-id` on one of them and restart it, or set a distinct `clientId`.'],
+      ['Name already in use (`409`)', 'Another live Client holds that name. Rename one of them in its config or from the resource card. A name held by an `OUT_OF_SERVICE` resource is reclaimed automatically.'],
+      ['The job is rejected with `422`', 'No registered Client can ever match its type, labels, group or client. Compare `thub resources` with your `--type`, `--board`/`--label` and `--group`.'],
+      ['The job stays `QUEUED`', 'Matching Clients are all `BUSY`, locked (`local`), in `MAINTENANCE` or offline, or the job is pinned with `--client`. It times out after `--timeout`.'],
+      ['`ERROR` during prepare', 'The clone, download or DUT image pull failed; the job log names the reason. For git, check the Client user\'s keys and `known_hosts` (`ssh -T git@<host>` as that user). For images, check the Client user\'s `docker login`.'],
+      ['Permission denied on `/dev/ttyUSB*` or `docker.sock`', 'Docker or the device groups were added after the Client was installed. Re-run `sudo npm i -g @andrian.yablonskyy/thub-client` so the unit gets the `dialout`/`plugdev`/`docker` groups, then restart.'],
+      ['A configured device is shown as missing', 'Check the `devpath` with `udevadm info -a -n <dev>`, then `thub-client udev --print`; restart the Client to regenerate the udev rules.'],
+      ['Job `LOST`', 'The Client missed 3 heartbeats (network, reboot, crash). With `requeueOnLost` the job is retried once on another Client.'],
+      ['A job can\'t write to `~` (read-only file system)', 'Under systemd the Client can only write to its state directory. Write to `$THUB_WORK_DIR`, and set `DOCKER_CONFIG` there for `docker login`.'],
+      ['Live logs don\'t stream through the proxy', 'Turn off response buffering for the Coordinator (nginx: `proxy_buffering off;`, Caddy: `flush_interval -1`).'],
+      ['Finding a job, resource, group or agent', 'Use the search box on its list page (press `/` to jump to it). Every word must match, e.g. `lab-hw-01 FAILED` or a git ref. Job search covers ids, users, resources, agents, commands, repos and `--meta`, but not `--env` values (secrets). On a job page, search the log above the log viewer: `Enter`/`Shift+Enter` step through matches.'],
+      ['Lists don\'t update by themselves (navbar shows Offline or Paused)', '`Paused`: you\'re editing something on the page (a field, the inline rename, a dialog); it resumes when you\'re done. `Offline`: the browser can\'t hold the `/live` stream open, often a proxy buffering it (nginx: `proxy_buffering off;`); reloading the page always shows current data. `Session ended`: sign in again. Background updates never extend the session\'s idle timeout.'],
+      ['Sign-in says it needs HTTPS', 'The session cookie is HTTPS-only because `publicUrl` is `https://`, but the request arrived as plain HTTP. Open the dashboard through its https:// address; behind a reverse proxy, make it send `X-Forwarded-Proto: https` (nginx: `proxy_set_header X-Forwarded-Proto $scheme;`) and check `trustProxy`. To allow plain HTTP, set `session.secureCookie` to `false`.'],
+      ['Where are a job\'s test reports and output files?', 'The Coordinator keeps only the log and the result (verdict, exit code, JUnit test counts). Files the job creates stay in its workspace on the Client and are deleted when the job ends. To keep them, publish them from `--command`, e.g. `curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T results/report.xml "https://artifactory.example.com/qa/$THUB_JOB_ID/report.xml"` with `--env ART_TOKEN`. The full log is always available from the job page\'s Raw button.'],
+      ['Locked out of the dashboard', 'Restart the Coordinator once with `THUB_BOOTSTRAP_ADMIN_PASSWORD=<new>` (resets the `admin` user), then unset it.']
+    ]
+    const withCode = (text) => text
+      .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+      .replace(/`([^`]+)`/g, '<code>$1</code>')
+  .accordion#help-faq
+    each item, i in faq
+      .accordion-item
+        h3.accordion-header
+          button.accordion-button.collapsed.small(
+            type="button"
+            data-bs-toggle="collapse"
+            data-bs-target=`#faq-${i}`
+            aria-expanded="false"
+            aria-controls=`faq-${i}`
+          )
+            //- One inline box: .accordion-button is flex, which would drop
+            //- the spaces around <code>.
+            span!= withCode(item[0])
+        .accordion-collapse.collapse(id=`faq-${i}` data-bs-parent="#help-faq")
+          .accordion-body.small!= withCode(item[1])
+  p.small.text-body-secondary.mt-3.mb-0.
+    The full design reference (API, state machines, database schema) is in the project README. Everything
+    that happens is also recorded per job: open it from #[a(href="/jobs") Jobs] for its spec, timeline and log.