update skill, add instruction on getting api keys, etc.

Author: yanyanzhu-pnnl

README.md

@@ -16,17 +16,47 @@ Quickly useful notes:
 
 ### 1. Obtain an API Key
 
-Get your API key from [COMcheck Web](https://comcheck.energycode.pnl.gov):
+Get a Personal Access Token from the new
+[COMcheck Web site](https://comcheck.energycode.pnl.gov):
 
-1. Log in to your COMcheck Web account
-2. Navigate to **Settings → Developer Setting**
-3. Generate and copy your API key
+1. Log in (or register a new account if you don't have one).
+2. Click your **username** in the left-side navigation.
+3. From the menu that appears, choose **Settings**.
+4. Click **Developer Setting** to open the Personal Access Token
+   page.
+5. Click **Generate**, then immediately copy the token.
 
-> **Note:** The Developer Setting feature is currently under development.
+> **Important:** the token is shown **only once**. Save it somewhere
+> safe (a password manager, your `.env`, etc.) before leaving the
+> page. If you lose it, generate a new one — the old one will stop
+> working.
 
 ### 2. Configure the API Key
 
-For detailed setup instructions, see the [Getting Started](https://pnnl-int.github.io/comcheckweb-api-python/getting-started/) guide.
+Create a `.env` file at the root of your project and add:
+
+```
+COM_API_KEY=<your-api-key-here>
+```
+
+The SDK does **not** auto-load this — you read it yourself and pass
+it to the client. With `python-dotenv` this is two lines:
+
+```python
+import os
+from dotenv import load_dotenv
+from comcheck_api import COMcheckClient
+
+load_dotenv()
+client = COMcheckClient(api_key=os.environ["COM_API_KEY"])
+```
+
+(`client.set_api_key(api_key)` is the equivalent post-construction
+setter if you'd rather defer.)
+
+For more detail, see the
+[Getting Started](https://pnnl.github.io/comcheckweb-api-python/getting-started/)
+guide.
 
 ### 3. Install the Package
 
@@ -39,7 +69,7 @@ pip install comcheckweb-api-python
 - **Simulation only:** You can use the simulation features directly without creating a project on COMcheck Web.
 - **Updating a project:** You must first create the project under your account on [COMcheck Web](https://comcheck.energycode.pnl.gov) before using this package to update it. Project creation is not yet supported through this package.
 
-For detailed usage examples and API reference, see the [documentation](https://pnnl-int.github.io/comcheckweb-api-python/).
+For detailed usage examples and API reference, see the [documentation](https://pnnl.github.io/comcheckweb-api-python/).
 
 ## Introspection helpers
 
@@ -67,7 +97,7 @@ if not result.ok:
         print(err.loc, err.msg)
 ```
 
-See [`api/introspection`](https://pnnl-int.github.io/comcheckweb-api-python/api/introspection/)
+See [`api/introspection`](https://pnnl.github.io/comcheckweb-api-python/api/introspection/)
 in the docs for the full reference.
 
 ## AI integration: the Claude Skill
@@ -105,7 +135,7 @@ pass `--global` (writes to `~/.claude/skills/comcheck-api/`).
 Clone the repository and follow the commands below to set up developer tooling.
 
 ```bash
-git clone https://github.com/pnnl-int/comcheckweb-api-python.git
+git clone https://github.com/pnnl/comcheckweb-api-python.git
 cd comcheckweb-api-python
 uv sync
 ```

comcheck_api/ai/skill/SKILL.md

@@ -22,47 +22,62 @@ Triggers:
 ## Core concepts
 
 - **Single entry point**: `COMcheckClient` is the only client class
-  users instantiate. Construct with `api_key=...` or rely on the
-  `COM_API_KEY` env var.
-- **Project shape**: a project is a `ComBuilding` Pydantic model. It
-  contains: `Project` (metadata), `Location`, `Envelope`, `WholeBldgUse[]`
-  (building areas), `HVAC`, `Lighting`, `Renewable`, and `Control`.
-- **Operation classes (functional)**: building areas and envelope
+  users instantiate. Construct with `api_key=...`. The client does
+  **not** auto-read any environment variable — read it yourself and
+  pass it: `COMcheckClient(api_key=os.environ["COM_API_KEY"])`.
+- **Project shape**: a project is a `ComBuilding` Pydantic model with
+  lowercase top-level fields: `project` (metadata), `location`,
+  `envelope`, `lighting` (which contains `wholeBldgUse[]` — the
+  building areas), `hvac`, `renewable`, and `control` (energy code).
+  No `Project`/`Control` PascalCase aliases exist.
+- **Operation modules (functional)**: building areas and envelope
   components are added/updated/removed via free functions in
   `project_building_area_operations` and `project_envelope_operations`.
   Each function takes a `ComBuilding` and returns a new `ComBuilding`.
+- **Envelope items attach to a building-area key**: every
+  `add_*_to_project` envelope function takes
+  `(project, building_area_key, new_component)`. Look up the key
+  with `ba_ops.get_building_area_keys_from_project(project)` first.
+  Default projects have **no** building areas — add one with
+  `ba_ops.add_building_area_to_project(...)` before any envelope
+  work.
 - **Defaults**: `comcheck_api.defaults` has `get_default_*_template()`
   functions that return Pydantic models filled with sensible defaults.
   Always start from these.
 - **Simulation flow is async**: `start_run_simulation` returns a
-  session ID. Poll `get_simulation_status` until status is `complete`,
-  then call `get_simulation_result`.
+  session ID. Poll `get_simulation_status` until status is
+  `"SUCCESS"` (terminal-ok) or `"FAILED"` (terminal-error), then call
+  `get_simulation_result`. See `comcheck_api.types.SimulationStatus`
+  for known lifecycle values (the catalog isn't exhaustive — only
+  the terminal pair is guaranteed stable).
 
 ## Quick start
 
 ```python
+import os
+import time
+
 from comcheck_api import COMcheckClient
 from comcheck_api.defaults import get_default_project_template
+from comcheck_api.types import SimulationStatus
 
-client = COMcheckClient(api_key="your-key")
+# Client does NOT auto-read COM_API_KEY — pass it in.
+client = COMcheckClient(api_key=os.environ["COM_API_KEY"])
 
 # Build a project from a default template
 project = get_default_project_template()
-project.Project.title = "5,000 sqft office in Seattle"
-
-# Save it (creates server-side project, returns ID via list)
-# Update if you have an existing ID:
-# updated = client.update_project(project_id="123", project_data=project)
+project.project.projectTitle = "5,000 sqft office in Seattle"
 
 # Run a simulation
 session_id = client.start_run_simulation(project)
 
-# Poll until complete
-import time
+# Poll until terminal — SUCCESS or FAILED
 while True:
     status = client.get_simulation_status(session_id)
-    if status["status"] == "complete":
+    if status["status"] == SimulationStatus.SUCCESS:
         break
+    if status["status"] == SimulationStatus.FAILED:
+        raise RuntimeError(f"Simulation failed: {status.get('message')}")
     time.sleep(5)
 
 result = client.get_simulation_result(session_id)
@@ -73,11 +88,33 @@ print(result["performanceRating"])
 
 - Use `get_default_*_template()` to start any new component, then
   customize. Don't construct `ComBuilding` from scratch.
-- Use the operation classes (e.g.,
-  `project_envelope_operations.add_ag_wall_to_project(project, wall)`)
-  to mutate project structure. Don't manipulate nested dicts directly.
-- Read the API key from `COM_API_KEY` env var by default; let users
-  pass `api_key=...` to override.
+- Use the operation modules (e.g.,
+  `env_ops.add_ag_wall_to_project(project, area_key, wall)`) to
+  mutate project structure. Don't manipulate nested dicts directly.
+- For envelope items, look up the building-area key first via
+  `ba_ops.get_building_area_keys_from_project(project)`. The key
+  goes between `project` and the new component in every
+  `add_*_to_project` envelope call.
+- Set enum-typed fields (`orientation`, `wallType`, `code`, etc.)
+  with members from the matching `*Options` enum imported from
+  `comcheck_api.types` — not raw strings, which trigger
+  Pydantic serialization warnings.
+- Pass `api_key=` explicitly to `COMcheckClient(...)`. The SDK does
+  **not** auto-load any env var — read it yourself:
+
+  ```python
+  from dotenv import load_dotenv
+  load_dotenv()
+  client = COMcheckClient(api_key=os.environ["COM_API_KEY"])
+  ```
+
+  `client.set_api_key(api_key)` is the equivalent post-construction
+  setter. Users get a Personal Access Token from the COMcheck Web
+  site (Settings → Developer Setting); see the
+  [GitHub README](https://github.com/pnnl/comcheckweb-api-python#1-obtain-an-api-key)
+  or the
+  [Getting Started page](https://pnnl.github.io/comcheckweb-api-python/getting-started/)
+  for the full walkthrough.
 - Wrap network calls in try/except and catch `COMCheckHTTPError`,
   `COMCheckConnectionError`, `COMCheckValidationError`,
   `COMCheckSimulationError`, `COMCheckProjectNotFoundError`.
@@ -91,47 +128,104 @@ print(result["performanceRating"])
 - Don't import private modules (anything starting with `_`).
 - Don't poll `get_simulation_status` faster than every 5 seconds.
 - Don't put the API key in source code; use env var or argument.
+- Don't use `comcheck_api.managers.*` (e.g. `AgWallListManager`,
+  `RoofListManager`). Those are internal list-mutation helpers; they
+  bypass the validation logic in the operation modules. Always go
+  through `project_envelope_operations` and
+  `project_building_area_operations` instead.
 
 ## Common patterns
 
-### Adding an above-grade wall
+### Adding a building area, then an above-grade wall
 
-```python
-from comcheck_api import project_envelope_operations as envelope_ops
-from comcheck_api.defaults import get_default_ag_wall_template
+`get_default_project_template()` starts with **zero building
+areas** — add one before attaching any envelope component.
 
+```python
+from comcheck_api import (
+    project_envelope_operations as env_ops,
+    project_building_area_operations as ba_ops,
+)
+from comcheck_api.defaults import (
+    get_default_building_area_template,
+    get_default_ag_wall_template,
+)
+from comcheck_api.types import OrientationOptions
+
+# 1. Add the building area (no areas exist by default).
+area = get_default_building_area_template()
+area.areaDescription = "Open office"
+project = ba_ops.add_building_area_to_project(project, area)
+
+# 2. Look up its key.
+area_key = ba_ops.get_building_area_keys_from_project(project)[0]["key"]
+
+# 3. Attach the wall to that area.
 wall = get_default_ag_wall_template()
-wall.name = "South wall"
-wall.area = 4800.0
-project = envelope_ops.add_ag_wall_to_project(project, wall)
+wall.description = "South wall"
+wall.orientation = OrientationOptions.SOUTH   # use the enum, not "SOUTH"
+wall.grossArea = 4800.0                        # field is grossArea, not area
+project = env_ops.add_ag_wall_to_project(project, area_key, wall)
 ```
 
 ### Listing the user's projects and updating one
 
 ```python
 projects = client.list_projects()
 target = next(p for p in projects if p["title"] == "My office")
-project_obj = client.get_project(target["id"])
-project_obj.Project.title = "My office (revised)"
-client.update_project(project_id=target["id"], project_data=project_obj)
+project_obj = client.get_project(target["_id"])     # note the underscore
+project_obj.project.projectTitle = "My office (revised)"
+client.update_project(project_id=target["_id"], project_data=project_obj)
 ```
 
+`get_project(project_id, mode="json")` returns a raw dict instead of
+a `ComBuilding` model — handy when you just need the JSON shape.
+
 ### Polling a simulation with a timeout
 
 ```python
 import time
+from comcheck_api.types import SimulationStatus
+
 session_id = client.start_run_simulation(project)
 deadline = time.time() + 300  # 5 min
 while time.time() < deadline:
     status = client.get_simulation_status(session_id)
-    if status["status"] == "complete":
+    if status["status"] == SimulationStatus.SUCCESS:
         result = client.get_simulation_result(session_id)
         break
+    if status["status"] == SimulationStatus.FAILED:
+        raise RuntimeError(f"Simulation failed: {status.get('message')}")
     time.sleep(5)
 else:
     raise TimeoutError(f"Simulation {session_id} did not complete in 5 min")
 ```
 
+## Gotchas
+
+- **Field names are lowercase camelCase**, not PascalCase.
+  `project.project.projectTitle`, `project.control.code`,
+  `project.lighting.wholeBldgUse[0].areaDescription`. There is no
+  `Project`, `Control`, `WholeBldgUse` (top-level), or `.title`.
+- **AG/BG wall area field is `grossArea`**, not `area`. Same for
+  roofs/floors/windows/doors. Setting `.area` silently does nothing
+  because Pydantic models reject unknown attributes only in strict
+  mode.
+- **Use enum members for typed fields**: `OrientationOptions.NORTH`,
+  `WallTypeOptions.WOOD_FRAME_16_AG_WALL`,
+  `EnergyCodeOptions.CEZ_90_1_2022`. Setting them to raw strings
+  works at runtime but emits `PydanticSerializationUnexpectedValue`
+  warnings every time the model serializes.
+- **`COMcheckClient(api_key=...)` does not auto-read env vars.** No
+  `COM_API_KEY` fallback exists in `__init__`. Pass it explicitly.
+- **`SimulationStatus` is a known-values catalog, not an exhaustive
+  contract.** The server may emit lifecycle values not yet in the
+  enum (e.g. `EVALUATING` was added in a later version). The
+  `status` field comes back as a plain `str` so unknown values
+  don't crash polling. Only `SUCCESS` and `FAILED` are guaranteed
+  terminal — break/raise on those, keep polling for everything
+  else (don't enumerate non-terminals).
+
 ## When you need more detail
 
 - For envelope assemblies (roof, walls, floor, windows, doors,