/by-session

id: "skill_c83b4ac84baf4c5e8810cdd0f53a5153"
name: "by-session"
display-name: "BY Session"
short-description: "Session initialization, environment discovery, and first-run configuration for BY projects. Use when opening a new session, running first-time setup, refreshing environment.json, or auditing the active compute provider."
category: "session"
keywords: "session start, config questionnaire, environment.json, config.json, compute provider, local GPU, RunPod, HPC, Tamarind, resume, campaign detection, banner"
version: "1.0"
last-updated: "2026-05-20"

BY Session Skill

Session initialization and configuration for BY projects. This skill defines the full session-start sequence (banner, environment check, status display) and the first-run configuration questionnaire that writes `.by/config.json`. It is **not optional** — it runs every time a new session opens in a BY project directory.

The session skill is the single source of truth for **which compute provider BY will use this session**. Every downstream skill (by-design-workflow, by-screening, the design engines) reads `.by/config.json` written here.

---

When to Use This Skill

Use this skill when you have:

• ✅ **A new session opening** in a BY project directory — the SessionStart hook fires this skill automatically
• ✅ **No `.by/config.json` yet** — run the first-run questionnaire to capture compute provider, model profile, campaign defaults
• ✅ **A request to refresh environment discovery** — re-scan local tools, conda envs, GPU, API keys
• ✅ **A request to switch compute provider** — update `compute.default_provider` cleanly without overwriting unrelated fields
• ✅ **An in-progress campaign** to detect and surface (`campaigns/*/campaign_log.json` with status not `complete`)
• ✅ **Staleness checks** — `.by/environment.json` older than 24h should prompt a refresh

Do NOT use this skill when:

• ❌ **You are mid-campaign and just want status** → use the `status` skill (it reads but does not re-questionnaire)
• ❌ **You need to deploy compute on RunPod / HPC** → use `by-deploy-compute` (this skill only records the *choice* of HPC)
• ❌ **You are scoring designs or running design engines** → use `by-scoring`, `boltzgen`, `pxdesign`, or `protenix`
• ❌ **You want to inspect a specific campaign's state** → use `by-campaign-manager`
• ❌ **The user is editing `.by/config.json` by hand** → read it back with `validate_config.py`, do not re-run the questionnaire

---

Quick Start

User opens a new terminal in a BY project directory.

Agent (by-session):
  1. Banner    → BY ► Protein Design Agent
  2. Check     → .by/config.json exists?
  3a. NO       → run init_questionnaire.py (or its inline AskUserQuestion equivalent)
                 → writes .by/config.json with local-first defaults
  3b. YES      → read config + environment, no questions asked
  4. Resume    → check campaigns/*/campaign_log.json for in-progress work
  5. Status    → print compute + profile + campaign count
  6. Done      → "Ready" prompt with suggested actions

Total time: ~1 second when config exists; ~30 seconds for first-run questionnaire.

---

Inputs

**Required:**

• **Working directory** — the BY project root (current directory by default).
• **User input** (first run only) — answers to the 3-round questionnaire (compute provider, model profile, campaign defaults).

**Optional (auto-detected):**

• **`.by/config.json`** — if present, skip questionnaire entirely.
• **`.by/environment.json`** — written by `/by:setup`; used to confirm tools and GPU.
• **Environment variables** — `RUNPOD_API_KEY`, `TAMARIND_API_KEY`, etc. for provider detection.
• **`campaigns/*/campaign_log.json`** — used to surface in-progress campaigns.

See `references/config-schema.md` for the full schema of both JSON files.

---

Outputs

All outputs land under `.by/` in the project root.

| File | Type | When written | Purpose | |------|------|--------------|---------| | `.by/config.json` | JSON | First run, or on user-driven update | User preferences: compute provider, providers_priority, model_profile, campaign defaults | | `.by/environment.json` | JSON | First run + `/by:setup` refresh | Auto-detected hardware/tools snapshot (GPU model, VRAM, conda envs, tool paths, API keys present) | | Terminal banner | Text | Every session | Branded session header | | Status block | Text | Every session | Compute provider in use, profile, campaign count, next-step prompts |

The `.by/config.json` schema is canonical and downstream-critical: every BY skill that selects a compute provider reads this file. See `references/config-schema.md`.

---

Clarification Questions

⚠️ **CRITICAL: ASK THIS FIRST** — Confirm `.by/config.json` does not already exist before running the questionnaire. Re-running the questionnaire would overwrite the user's saved preferences.

1. **Config file presence (ASK THIS FIRST)** — Does `.by/config.json` already exist? If yes, skip the questionnaire and go straight to the session banner. If no, proceed to Q2. (You can check this silently — only ask the user if there's ambiguity, e.g., the file exists but is corrupted.) 2. **Compute provider** — Where should BY run design computations? Options: `local` (recommended default — uses local GPU), `hpc` (RunPod or other HPC target deployed via `by-deploy-compute`), `tamarind` (Tamarind Bio cloud), `auto` (detect best available in priority order). **The default is `local`.** 3. **Local GPU tool paths** (only if provider is `local` or `auto`) — Where are BoltzGen, Protenix, and PXDesign installed? Auto-detect from `PATH` and common locations, or accept a custom path per tool. Validate each path exists. 4. **HPC target** (only if provider is `hpc`) — Which HPC target? Default `runpod`. The actual deployment is handled by `by-deploy-compute`; this skill only records the choice and the `api_key_env` variable name. 5. **Tamarind API key** (only if provider is `tamarind`) — Is `TAMARIND_API_KEY` set in `.env` or