canfar-lab 0.7.0__tar.gz

canfar_lab-0.7.0/.cursor/harness/.gitignore

@@ -0,0 +1,4 @@
+trajectories/
+failures/
+state/
+proposals/rejected.md

canfar_lab-0.7.0/.cursor/harness/config.json

@@ -0,0 +1,7 @@
+{
+  "verify_fast": ["./scripts/ci.sh"],
+  "verify": ["./scripts/ci.sh"],
+  "verify_full": ["./scripts/ci.sh"],
+  "reflect_min_turns": 5,
+  "reflect_min_minutes": 45
+}

canfar_lab-0.7.0/.cursor/harness/failures/2026-08-27-epistemic-stack-verifier.md

@@ -0,0 +1,13 @@
+# verifier failure 2026-08-27-epistemic-stack
+
+- `pixi run preflight-push` is configured as `verify_fast`, but this checkout
+  has no `preflight-push` Pixi task.
+- `pixi run pytest -q tests/unit/test_addons.py tests/unit/test_plugins.py`
+  could not launch `pytest` because the current Pixi environment has no
+  `pytest` executable.
+- `pixi run format-check` could not acquire the Pixi prefix lock from this
+  restricted checkout. Running the bundled Ruff directly with its cache under
+  `/private/tmp` passed (`153 files already formatted`).
+- Follow-up: use the available `lint` task and direct catalog/skill checks;
+  do not classify the catalog changes as test failures until the environment
+  is provisioned.

canfar_lab-0.7.0/.cursor/harness/playbook.md

@@ -0,0 +1,12 @@
+# Harness Playbook
+
+## Bullets
+
+- id: verify-tiers
+  desc: verify_fast during edits; verify (ci-local) before push; verify_full only when human opts in.
+
+- id: file-memory
+  desc: Put durable notes in .cursor/harness/ — not long chat scrollback.
+
+- id: minimal-diff
+  desc: Smallest correct change; match existing repo style and tools.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-08-27-epistemic-stack.md

@@ -0,0 +1,5 @@
+# trajectory 2026-08-27-epistemic-stack
+status: completed
+verifier: `pixi run lint`; bundled Ruff `format --check` with cache under `/private/tmp`; direct YAML/catalog invariant check; skill-creator quick validation
+outcome: pass — lint, formatting, registry parsing, and bundled skill validation pass; pytest unavailable in current environment
+lesson: The configured `pixi run preflight-push` task is absent from this checkout; keep the mismatch recorded until the repository verifier is reconciled.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-08-27-writing-skills.md

@@ -0,0 +1,5 @@
+# trajectory 2026-08-27-writing-skills
+status: completed
+verifier: pixi run ci; static registry and syntax checks
+outcome: pass for lint/format/static checks; CI stopped at pre-existing missing tomli in the stale environment
+lesson: Root-layout GitHub skills need the plugin id as their destination name.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-08-31-viz-skills.md

@@ -0,0 +1,5 @@
+# trajectory 2026-08-31-viz-skills
+status: completed
+verifier: pixi python load_plugins() for matplotlib-data-visualization
+outcome: comment-only on matplotlib plugin; orx-* not added
+lesson: openresearch image already runs `orx install-skills`; do not duplicate that tree in plugins/.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-09-07-consolidate-astroai-main.md

@@ -0,0 +1,7 @@
+# 2026-09-07 consolidate onto astroai/main
+
+- Rebased fork-only Ray autoscaler commits onto upstream; resolved `dashboard.py` (keep `live=` gate + manager_id probe path).
+- Merged via https://github.com/astroai/canfar-lab/pull/11 → `af5ab3b`.
+- Force-aligned `sfabbro/canfar-lab` `origin/main` to `upstream/main` (0/0 divergence).
+- Deleted obsolete `wip/npx-platform-skills` and `wip/ray-autoscaler-cap`; removed vendor-astroai-ray worktree.
+- Local only: harness `viz-skills` playbook bullet (unstaged).

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-09-07-update-upstream.md

@@ -0,0 +1,6 @@
+# 2026-09-07 update from upstream/main
+
+- FF `main` 758d6f3 → 8ca2ac3 (20 commits; agent CLIs home-canonical, plugin pack slimmed).
+- Stash pop conflict: `matplotlib-data-visualization.yaml` modify/delete — kept upstream deletion (skills no longer vendored here).
+- Re-applied local harness `viz-skills` bullet (worded for no in-tree plugin).
+- Worktree `wip/npx-platform-skills`: rebase onto upstream skipped cherry-pick 97f6024 (already PR #10). Branch tip == upstream/main; origin/wip still has the old tip (needs force-push if retaining the remote branch).

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-10-21-studio-agent-layout.md

@@ -0,0 +1,5 @@
+# trajectory 2026-10-21-studio-agent-layout
+status: completed
+verifier: ./scripts/ci.sh
+outcome: pass (1121 passed, 19 skipped, coverage 75.85%)
+lesson: a home drop symlink into the scratch bin is one binary; classify must not call it a second home install. Key reload must use BSD `stat -f` and `date +%s` — macOS bash 3.2 has no `stat -c` and no `EPOCHSECONDS`, and an empty stamp matches the unset stamp so keys never load. Download allow-list must include `tempfile.gettempdir()` (macOS pytest tmp is `/var/folders`, not `/tmp`). Panel key assertions must clear every catalog key, or a developer `ANTHROPIC_API_KEY` changes `keys_present`.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-10-21-studio-settings-usability.md

@@ -0,0 +1,5 @@
+# trajectory 2026-10-21-studio-settings-usability
+status: completed
+verifier: pixi run pytest tests/unit/test_bin_root.py tests/cli/test_cli_agent_contract.py --no-cov; node --check settings client
+outcome: pass
+lesson: a missing settings payload must not render the laptop sentence; keep the last good layout and show the error. Key rows need catalog labels, and only https signup links.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-10-22-desktop-studio-launch.md

@@ -0,0 +1,5 @@
+# trajectory 2026-10-22-desktop-studio-launch
+status: completed
+verifier: ./scripts/ci.sh and python3 scripts/lib/test_studio_canfar_proxy.py
+outcome: pass (1126 passed, proxy test ok). xmatcher stays the sync name; ~/src/astroai/xmatch is a separate checkout.
+lesson: `--json` on `agent settings` must be a verb flag. A laptop `SCRATCH` directory is not a CANFAR session. The studio image pins `ARG DSH_VERSION` to canfar-lab's `DSH_VERSION`.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-10-22-desktop-sync-dock.md

@@ -0,0 +1,5 @@
+# trajectory 2026-10-22-desktop-sync-dock
+status: completed
+verifier: pixi run pytest tests/unit/test_studio.py tests/unit/test_desk_proxy.py tests/unit/test_studio_profile.py tests/unit/test_desk_state_actions.py -o addopts= -q
+outcome: pass (110)
+lesson: Laptop `canfar lab studio` must serve the desk proxy on the public port; bare dsh has no sync dock. A live :3080 that is not the proxy has to be quit before the dock can bind.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-10-22-local-notebooks-dock-bar.md

@@ -0,0 +1,5 @@
+# trajectory 2026-10-22-local-notebooks-dock-bar
+status: completed
+verifier: pixi run pytest tests/unit/test_desk_apps.py tests/unit/test_desk_state_actions.py tests/unit/test_desk_proxy.py -o addopts= -q
+outcome: pass (70)
+lesson: Laptop JupyterLab and marimo are local loopback servers; the desk bar is a 44px top strip with a Hide handle.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-10-22-studio-launch.md

@@ -0,0 +1,7 @@
+# Studio launch on the laptop
+
+`pixi run canfar` is the platform client. canfar 1.4.1 (PyPI) reads `~/.canfar/config.yaml` on import and exits when the file is schema version 2 (written by canfar 1.5). `canfar lab` does not use that file. The pixi task `canfar` routes a leading `lab` through `canfar_lab.cli.dispatch` and only then the platform client.
+
+The astroai dsh profile must pin `@deepseek-ai/dsh-experimental-agent-team-profile` to `studio.DSH_VERSION`. npm `latest` for that package is still `0.1.5-alpha.2`, and a bare `dsh plugin add` installs it. Those 0.1.5 modules in the profile `node_modules` shadow the 0.2.1-rc.2 CLI and `typert-loader` dies on startup. One `dsh plugin add <name>@<pin>` upgrades and prunes the retired web-profile. A `remove` before that add aborts the upgrade.
+
+`dsh plugin` needs `pnpm` on PATH. The studio image activates pnpm 12.6.0 with corepack.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-10-24-dsh-rc3-arc-doorbell.md

@@ -0,0 +1,5 @@
+# trajectory 2026-10-24-dsh-rc3-arc-doorbell
+status: completed
+verifier: pixi run pytest tests/unit/test_arc_data.py tests/unit/test_dsh_release.py tests/unit/test_studio.py tests/unit/test_desk_state_actions.py -o addopts= -q
+outcome: pass after newest-tag fixture moved above the pin
+lesson: npm latest can lag next. The doorbell uses canfar data cp to arc:/home; vosfs stays inside that client.

canfar_lab-0.7.0/.cursor/harness/trajectories/2026-10-24-review-ship.md

@@ -0,0 +1,5 @@
+# trajectory 2026-10-24-review-ship
+status: completed
+verifier: ./scripts/ci.sh
+outcome: pass — 1270 passed, 19 skipped, coverage 76.92%
+lesson: pixi upgrade strips [project.dependencies] floors; restore canfar and the version bounds before committing the lock. ty 0.0.91 rejects @contextmanager -> Iterator.

canfar_lab-0.7.0/.cursor/hooks/harness-session-start.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Inject playbook context at session start when .cursor/harness exists.
+set -euo pipefail
+
+input=$(cat)
+playbook=".cursor/harness/playbook.md"
+
+if [[ ! -f "$playbook" ]]; then
+  echo '{}'
+  exit 0
+fi
+
+export HARNESS_PLAYBOOK="$playbook"
+python3 <<'PY'
+import json, os, re
+
+path = os.environ.get("HARNESS_PLAYBOOK", ".cursor/harness/playbook.md")
+try:
+    text = open(path).read()
+except OSError:
+    print("{}")
+    raise SystemExit(0)
+
+# ponytail: cap at 12 bullets to limit context injection
+ids = re.findall(r"^- id:\s*(\S+)\s*\n\s*desc:\s*(.+)$", text, re.M)
+if not ids:
+    print("{}")
+    raise SystemExit(0)
+
+lines = [f"- id: {i}\n  desc: {d.strip()}" for i, d in ids[:12]]
+msg = (
+    "Harness playbook (full file: .cursor/harness/playbook.md). "
+    "Follow harness-coding: plan → execute → verify → file memory.\n\n"
+    + "\n\n".join(lines)
+)
+print(json.dumps({"additional_context": msg}))
+PY

canfar_lab-0.7.0/.cursor/hooks.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": ".cursor/hooks/harness-session-start.sh"
+      }
+    ]
+  }
+}

canfar_lab-0.7.0/.dockerignore

@@ -0,0 +1,11 @@
+.venv
+.git
+.pytest_cache
+.ruff_cache
+htmlcov
+.coverage
+dist
+**/__pycache__
+*.pyc
+*.egg-info
+.mypy_cache

canfar_lab-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+# Remote gate mirroring ./scripts/ci.sh: ruff, ty, wheel data, CLI audit, pytest.
+# Run ./scripts/ci.sh locally before pushing.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# The test job only checks out and runs checks; it never writes back to
+# the repo, so restrict the GITHUB_TOKEN to read-only contents.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: prefix-dev/setup-pixi@v0.10.2
+        with:
+          cache: true
+
+      - name: Lockfile integrity — pixi install --frozen
+        # Hard-fail on lockfile drift: --frozen refuses to touch pixi.lock
+        # and errors if the manifest changed without re-locking.
+        run: pixi install --frozen
+
+      - name: Ruff check
+        run: pixi run lint
+
+      - name: Ruff format
+        run: pixi run format-check
+
+      - name: ty typecheck
+        run: pixi run typecheck
+
+      - name: Wheel data
+        run: bash scripts/check-wheel.sh
+
+      - name: CLI audit
+        run: pixi run cli-audit
+
+      - name: Pytest
+        run: pixi run test

canfar_lab-0.7.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Build
+        run: python -m pip install build hatchling && python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

canfar_lab-0.7.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.coverage
+htmlcov/
+
+# Local MNIST example artifacts
+examples/workload/mnist_cnn/data/
+examples/workload/mnist_cnn/*.pt
+uv.lock
+
+# Agent scratch directories
+.freebuff/
+.agents/
+.codex/
+

canfar_lab-0.7.0/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md — canfar-lab
+
+In-session CANFAR Science Platform workbench and workload tooling (`canfar-lab`).
+CANFAR is the platform. This package is one command tree: `canfar lab` on the
+platform CLI, and the standalone `canfar-lab` binary.
+
+## Remotes (AstroAI fork workflow)
+
+| Remote | Points at | Use |
+|--------|-----------|-----|
+| `origin` | `<github_user>/canfar-lab` | Push fork `main` |
+| `upstream` | `astroai/canfar-lab` | Sync `main`; PR target |
+
+`main` tracks `upstream/main`. Prefer working and pushing on fork `main`.
+Never force-push `astroai` `main`.
+
+```bash
+git fetch upstream && git rebase upstream/main
+# edit on main
+git push origin main
+gh pr create -R astroai/canfar-lab --head <github_user>:main
+```
+
+## Environment
+
+Pixi (`[tool.pixi]` in `pyproject.toml`). Prefer `pixi run` over system Python.
+
+```bash
+pixi install
+```
+
+## Verification
+
+```bash
+./scripts/ci.sh                 # lint, format, typecheck, CLI audit, pytest
+canfar lab studio --doctor      # Studio pre-flight (needs dsh on PATH)
+canfar lab panel doctor         # headless Team / review-bench
+```
+
+Harness verify tasks in `.cursor/harness/config.json` map to the same gate.
+
+## In-session project template
+
+The AGENTS template copied into user projects lives under
+`src/canfar_lab/data/agent/project/AGENTS.md`. Edit that file when changing
+what lab users see after `canfar lab agent setup`, not only this root file.
+
+Workspace layout and `/arc` rules (`PYTHONNOUSERSITE`, no `$HOME/.local`
+installs): parent workspace `AGENTS.md` (`~/src/AGENTS.md`).
+
+## Env hygiene
+
+- Prefer `pixi run` / `pixi run python` over bare `python3` when Pixi exists.
+- Never `pip install --user` or install into `~/.local` / `$HOME/.local` (esp. CANFAR `/arc/home`).
+- Headless/batch: `export PYTHONNOUSERSITE=1` and `unset PYTHONPATH`.
+- On CANFAR: code under `$WORK` → `/scratch/src` (session-ephemeral). Prefer
+  `canfar lab sync` / `canfar lab clone <fork> --update` to refresh source; `save`/`resume` are deps only.
+  See `docs/USAGE.md` → Getting code onto jobs; skill `canfar-lab-workflow`.
+- Session images: always `images.canfar.net/astroai/*` — **never** `skaha/*`.
+
+## Code propagation (jobs + sessions)
+
+On CANFAR, code lives under `$WORK` → **`$SCRATCH/src`** (session-ephemeral).
+Workers do not see another pod's `/scratch`. Pick a mode before jobs:
+
+1. **GitHub push → pull** (default): push fork `origin`, then
+   `canfar lab sync` or `canfar lab clone <fork/repo> --update` (or `--ref <sha>`). Prints HEAD SHA.
+2. **`canfar lab save` / `resume`**: lockfiles / env only — **not** source.
+3. **VOSpace tarball** under `vos:$USER/astroai/` (pack deps yourself; no CLI yet).
+4. **2 + 3** for reproducible headless (env snapshot + code blob).
+
+Same-session Ray: `canfar lab run` packages local `working_dir`. Details:
+`docs/USAGE.md` § Code propagation.

canfar_lab-0.7.0/CLAUDE.md

@@ -0,0 +1,2 @@
+@AGENTS.md
+

canfar_lab-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sébastien Fabbro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

canfar_lab-0.7.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: canfar-lab
+Version: 0.7.0
+Summary: In-session workbench and workload CLI extensions for the CANFAR Science Platform
+Project-URL: Homepage, https://github.com/astroai/canfar-lab
+Project-URL: Documentation, https://github.com/astroai/canfar-lab/blob/main/docs/USAGE.md
+Project-URL: Repository, https://github.com/astroai/canfar-lab
+Project-URL: Issues, https://github.com/astroai/canfar-lab/issues
+Project-URL: Platform, https://opencadc.github.io/canfar/
+Author-email: Simon Fabbro <simon.fabbro@nrc-cnrc.gc.ca>
+License: MIT License
+        
+        Copyright (c) 2026 Sébastien Fabbro
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: astroai,astronomy,canfar,science-platform,session
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Requires-Dist: canfar>=1.5.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.16.1
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tomli>=2.5.0; python_version < '3.11'
+Requires-Dist: typer>=0.27.3
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: ruff>=0.17.2; extra == 'dev'
+Requires-Dist: ty>=0.0.91; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# canfar-lab
+
+The **`canfar lab`** commands you run *inside* an AstroAI session on the
+[CANFAR Science Platform](https://www.opencadc.org/canfar/). The same tree is
+the standalone `canfar-lab` binary.
+
+Start and stop sessions with [`canfar`](https://github.com/opencadc/canfar)
+(or the Science Portal). Inside the session, `canfar lab` does three jobs:
+
+1. **Project env** — `init` / `clone` / `save` / `resume` (lockfiles on `/arc`)
+2. **Ray cluster** — `cluster start` / `status` / `run` / `jobs`
+3. **Agents** — `agent setup` / `install` / `verify`
+
+```mermaid
+flowchart LR
+  subgraph laptop [Laptop or portal]
+    Portal[Science Portal]
+    CanfarCLI["canfar login / create"]
+  end
+  subgraph session [AstroAI session]
+    Lab["canfar lab"]
+    Tools["pixi / uv / Jupyter / CADC / Ray"]
+  end
+  Portal --> session
+  CanfarCLI --> session
+  Lab --> Tools
+```
+
+| Name | Meaning |
+|------|---------|
+| **AstroAI** | Product: GitHub [`astroai`](https://github.com/astroai), Harbor `astroai` |
+| **CANFAR** | Host platform: portal, Skaha, `/arc`, auth |
+| **`canfar`** | Platform CLI — sessions and `canfar data` |
+| **`canfar lab` / `canfar-lab`** | This package, inside a session |
+| **`images.canfar.net/astroai/*`** | Session images |
+
+Images: [canfar-containers](https://github.com/astroai/canfar-containers).
+
+## Inside a session
+
+```bash
+canfar lab                      # status banner
+canfar lab init mylab           # or: clone owner/repo
+canfar lab save                    # lockfile snapshot to /arc
+canfar lab resume mylab
+canfar lab status                  # quotas, sessions (not the Ray cluster)
+
+canfar lab cluster start
+canfar lab cluster status
+canfar lab run train.py --cpus 2
+
+canfar lab kernel ensure
+canfar lab agent setup
+```
+
+`canfar lab status` is this session’s CPU/disk/quota. `canfar lab cluster status`
+is whether the Ray cluster is up. `canfar lab cluster stop` tears down workers
+and the manager.
+
+Help: `canfar lab help` · one command: `canfar lab help -c cluster` · cheat sheet:
+[docs/help.md](docs/help.md)
+
+## Install
+
+```bash
+pip install canfar-lab
+canfar-lab --help
+```
+
+Do not pass `--user`. On a CANFAR session that writes `/arc/home/.local`. If the image Python is not writable, `uv pip install --python /opt/canfar canfar-lab`. Upgrade with `pip install -U canfar-lab`. Session images that already include the package put `canfar-lab` on PATH.
+
+## Docs
+
+| Doc | What it is |
+|-----|------------|
+| [docs/help.md](docs/help.md) | Cheat sheet |
+| [docs/USAGE.md](docs/USAGE.md) | Storage, workflows, Ray, agents |
+| [docs/cli.md](docs/cli.md) | Flags and every command |
+| [docs/config.md](docs/config.md) | Optional `~/.astroai/lab/config.yaml` |
+| [docs/concurrency.md](docs/concurrency.md) | Shared home: locks, atomic writes, agent runtime placement |
+| [docs/studio.md](docs/studio.md) | AstroAI Studio: the browser coding portal, its dsh profile, teams, storage split |
+| [docs/desk-sync.md](docs/desk-sync.md) | Desk cockpit and CANFAR ↔ desktop sync (design proposal) |
+| [docs/panel.md](docs/panel.md) | AstroAI Panel / Studio Team review (keys only; models in dsh Settings) |
+
+Data movement is not this CLI. Use **`canfar data`** and `vcp` / `vls`.
+
+## Development
+
+```bash
+./scripts/ci.sh
+pixi run test
+```
+
+[MIT](LICENSE). `canfar` keeps its own license.

canfar_lab-0.7.0/README.md

@@ -0,0 +1,94 @@
+# canfar-lab
+
+The **`canfar lab`** commands you run *inside* an AstroAI session on the
+[CANFAR Science Platform](https://www.opencadc.org/canfar/). The same tree is
+the standalone `canfar-lab` binary.
+
+Start and stop sessions with [`canfar`](https://github.com/opencadc/canfar)
+(or the Science Portal). Inside the session, `canfar lab` does three jobs:
+
+1. **Project env** — `init` / `clone` / `save` / `resume` (lockfiles on `/arc`)
+2. **Ray cluster** — `cluster start` / `status` / `run` / `jobs`
+3. **Agents** — `agent setup` / `install` / `verify`
+
+```mermaid
+flowchart LR
+  subgraph laptop [Laptop or portal]
+    Portal[Science Portal]
+    CanfarCLI["canfar login / create"]
+  end
+  subgraph session [AstroAI session]
+    Lab["canfar lab"]
+    Tools["pixi / uv / Jupyter / CADC / Ray"]
+  end
+  Portal --> session
+  CanfarCLI --> session
+  Lab --> Tools
+```
+
+| Name | Meaning |
+|------|---------|
+| **AstroAI** | Product: GitHub [`astroai`](https://github.com/astroai), Harbor `astroai` |
+| **CANFAR** | Host platform: portal, Skaha, `/arc`, auth |
+| **`canfar`** | Platform CLI — sessions and `canfar data` |
+| **`canfar lab` / `canfar-lab`** | This package, inside a session |
+| **`images.canfar.net/astroai/*`** | Session images |
+
+Images: [canfar-containers](https://github.com/astroai/canfar-containers).
+
+## Inside a session
+
+```bash
+canfar lab                      # status banner
+canfar lab init mylab           # or: clone owner/repo
+canfar lab save                    # lockfile snapshot to /arc
+canfar lab resume mylab
+canfar lab status                  # quotas, sessions (not the Ray cluster)
+
+canfar lab cluster start
+canfar lab cluster status
+canfar lab run train.py --cpus 2
+
+canfar lab kernel ensure
+canfar lab agent setup
+```
+
+`canfar lab status` is this session’s CPU/disk/quota. `canfar lab cluster status`
+is whether the Ray cluster is up. `canfar lab cluster stop` tears down workers
+and the manager.
+
+Help: `canfar lab help` · one command: `canfar lab help -c cluster` · cheat sheet:
+[docs/help.md](docs/help.md)
+
+## Install
+
+```bash
+pip install canfar-lab
+canfar-lab --help
+```
+
+Do not pass `--user`. On a CANFAR session that writes `/arc/home/.local`. If the image Python is not writable, `uv pip install --python /opt/canfar canfar-lab`. Upgrade with `pip install -U canfar-lab`. Session images that already include the package put `canfar-lab` on PATH.
+
+## Docs
+
+| Doc | What it is |
+|-----|------------|
+| [docs/help.md](docs/help.md) | Cheat sheet |
+| [docs/USAGE.md](docs/USAGE.md) | Storage, workflows, Ray, agents |
+| [docs/cli.md](docs/cli.md) | Flags and every command |
+| [docs/config.md](docs/config.md) | Optional `~/.astroai/lab/config.yaml` |
+| [docs/concurrency.md](docs/concurrency.md) | Shared home: locks, atomic writes, agent runtime placement |
+| [docs/studio.md](docs/studio.md) | AstroAI Studio: the browser coding portal, its dsh profile, teams, storage split |
+| [docs/desk-sync.md](docs/desk-sync.md) | Desk cockpit and CANFAR ↔ desktop sync (design proposal) |
+| [docs/panel.md](docs/panel.md) | AstroAI Panel / Studio Team review (keys only; models in dsh Settings) |
+
+Data movement is not this CLI. Use **`canfar data`** and `vcp` / `vls`.
+
+## Development
+
+```bash
+./scripts/ci.sh
+pixi run test
+```
+
+[MIT](LICENSE). `canfar` keeps its own license.