feat: add CLI and web interface

.github/pull_request_template.md

@@ -55,6 +55,28 @@
 
 </details>
 
+## 🗂️ Environment Manifest Checklist
+<!-- For RL Environment PRs only — the manifest powers the Environments Hub web UI -->
+- [ ] Environment directory is under `environments/community/` (or appropriate category subfolder)
+- [ ] `README.md` is present with a `#` heading (used as the display name) and a short description paragraph below it
+- [ ] At least one `.py` file exists in the environment directory (required for discovery)
+- [ ] Ran `python scripts/build_env_manifest.py` from the repo root to rebuild the manifest
+- [ ] Committed the updated `web/public/environments.json` and the new `web/public/env-data/<slug>.json` file(s)
+- [ ] Committed the copied environment files under `web/public/env-files/<slug>/`
+
+---
+
+## 🌐 Web Checklist
+<!-- For PRs that touch anything under web/ — delete this section otherwise -->
+- [ ] `cd web && npm run build` completes with no errors
+- [ ] `cd web && npm run lint` passes (ESLint clean)
+- [ ] `cd web && npx tsc --noEmit` reports no type errors
+- [ ] UI tested in both light and dark mode
+- [ ] UI tested at mobile (< 768px) and desktop (≥ 1280px) widths
+- [ ] No hardcoded `localhost` URLs or dev-only values left in code
+- [ ] If adding/modifying environments: ran `python scripts/build_env_manifest.py` to rebuild `web/public/environments.json`
+- [ ] New environment variables documented (added to `web/.env.example` or equivalent)
+
 ---
 
 ## ✅ Developer & Reviewer Checklist

.github/workflows/deploy-web.yml

@@ -0,0 +1,112 @@
+name: Deploy Web Hub
+
+on:
+  push:
+    branches:
+      - main
+      - endpoint
+    paths:
+      - ".github/workflows/deploy-web.yml"
+      - "scripts/build_env_manifest.py"
+      - "web/**"
+      - "environments/**/README.md"
+      - "environments/**/*.py"
+      - "environments/**/*.md"
+      - "environments/**/*.json"
+      - "environments/**/*.toml"
+      - "environments/**/*.yaml"
+      - "environments/**/*.yml"
+      - "environments/**/*.txt"
+      - "environments/**/*.ts"
+      - "environments/**/*.tsx"
+      - "environments/**/*.js"
+      - "environments/**/*.css"
+      - "environments/**/*.html"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      base_path: ${{ steps.base-path.outputs.base_path }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Compute base path
+        id: base-path
+        shell: bash
+        run: |
+          owner="${GITHUB_REPOSITORY%%/*}"
+          repo="${GITHUB_REPOSITORY#*/}"
+          if [ "$repo" = "${owner}.github.io" ]; then
+            echo "base_path=" >> "$GITHUB_OUTPUT"
+          else
+            echo "base_path=/$repo" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install web dependencies
+        working-directory: web
+        run: npm ci
+
+      - name: Generate static environment data
+        run: python scripts/build_env_manifest.py
+
+      - name: Hide local API routes for Pages export
+        working-directory: web
+        shell: bash
+        run: |
+          if [ -d app/api ]; then
+            mkdir -p ../.pages-build-cache
+            mv app/api ../.pages-build-cache/app-api
+          fi
+
+      - name: Build static site
+        working-directory: web
+        env:
+          STATIC_EXPORT: "true"
+          PAGES_BASE_PATH: ${{ steps.base-path.outputs.base_path }}
+          NEXT_PUBLIC_BASE_PATH: ${{ steps.base-path.outputs.base_path }}
+          NEXT_PUBLIC_GITHUB_REPO: ${{ github.repository }}
+          NEXT_PUBLIC_GITHUB_REF: ${{ github.sha }}
+        run: npm run build
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: web/out
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -16,8 +16,8 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
+/lib/
+/lib64/
 parts/
 sdist/
 var/
@@ -175,6 +175,10 @@ cython_debug/
 # data
 *.json
 *.jsonl
+!web/public/environments.json
+!web/package.json
+!web/package-lock.json
+!web/tsconfig.json
 
 # wandb
 wandb

.pre-commit-config.yaml

@@ -36,3 +36,4 @@ repos:
     hooks:
     -   id: codespell
         args: ["--skip", "*.csv,*.html", "-L", "te,ans,sems,lsat,anc,strokin,lod,nam,ques,unparseable,rouge,oll,managin,expressio,re-declare"]
+        exclude: 'package-lock\.json'

CONTRIBUTING.md

@@ -119,6 +119,42 @@ pre-commit run --all-files
 ```
 This command will automatically fix formatting issues found by `black` and `isort`. However, you may need to manually address any linting errors reported by `flake8`.
 
+## Environments Hub (Web + CLI)
+
+The project includes an **Environments Hub**: a Next.js web app for browsing environments and a CLI for installing them locally.
+
+*   **Web app** (`web/`): Lists environments from a manifest, shows detail pages, and exposes APIs for listing files and downloading environments (per-file or as a zip). Run from repo root with the manifest and `environments/` folder available:
+```bash
+cd web && npm install && npm run dev
+```
+Set `ENVIRONMENTS_MANIFEST_PATH` and `ENVIRONMENTS_PATH` if the defaults (`web/public/environments.json` and `../environments`) do not apply.
+*   **Manifest**: The web app reads `web/public/environments.json`. Rebuild it after adding or changing environments under `environments/`:
+```bash
+python scripts/build_env_manifest.py
+```
+(Optional: pass an output path, e.g. `python scripts/build_env_manifest.py web/public/environments.json`.)
+*   **CLI** (`atropos`): Install, list, or delete cached environments. It talks to the web app API (list files, then download each file with progress). Example:
+```bash
+pip install -e .
+atropos install answer_format_environment --base-url http://localhost:3000
+atropos list
+atropos delete answer_format_environment --yes
+```
+Default base URL is `http://localhost:3000`; override with `ATROPOS_BASE_URL` or `--base-url`.
+
+When contributing a new environment under `environments/community/`, ensure it has a `README.md` and at least one `.py` file so the manifest builder will include it. See [web/README.md](web/README.md) for more detail.
+
+After adding or changing an environment, **rebuild the static manifest** and commit the output:
+```bash
+python scripts/build_env_manifest.py
+```
+This script writes three things that must be committed with your PR:
+- `web/public/environments.json` — the full index of all environments
+- `web/public/env-data/<slug>.json` — per-environment detail (name, description, file list)
+- `web/public/env-files/<slug>/` — static copies of the environment's files for download
+
+The script derives each environment's display name and description from the first `#` heading and the first non-heading paragraph in its `README.md`, so make sure your README follows that format.
+
 ## License for Contributions
 Any contributions you make will be under the MIT License. In short, when you submit code changes, your submissions are understood to be under the same [MIT License](LICENSE) that covers the project. Feel free to contact the maintainers if that's a concern.
 
@@ -127,6 +163,14 @@ Any contributions you make will be under the MIT License. In short, when you sub
 Since Atropos is focused on reinforcement learning environments, we encourage contributions of new training environments. However, please adhere to the following guidelines:
 
 *   **Directory Structure**: Please create your new environment within the `environments/community/` subdirectory. This helps us organize incoming contributions and allows for a streamlined initial review process before full testing and integration.
+*   **Required files**: Your environment directory must contain:
+    *   `README.md` — with a `# Title` heading (used as the display name in the hub) and a short description paragraph immediately below it
+    *   At least one `.py` file — required for the manifest builder to recognise the directory as an environment
+*   **Rebuild the manifest**: After adding your environment, run the manifest builder from the repo root and commit its output alongside your code:
+    ```bash
+    python scripts/build_env_manifest.py
+    ```
+    The files to commit are `web/public/environments.json`, `web/public/env-data/<your-slug>.json`, and `web/public/env-files/<your-slug>/`. Without this step your environment will not appear in the Environments Hub.
 *   **Import Style**: We prefer that you treat your environment's directory as the package root for imports. For example, if your environment resides in `environments/community/my_new_env/` and you need to import `SomeClass` (assuming it's in a `some_file_in_my_env.py` file at the root of your `my_new_env` directory or accessible via your Python path setup), you should be able to use a direct import like:
     ```python
     from some_file_in_my_env import SomeClass