hci-atrium 0.6.0 → 0.6.1

package/GUIDE.md

@@ -90,10 +90,11 @@ client = Atrium()   # defaults to the deployed instance (or ATRIUM_BASE_URL)
 same instance).
 
 **API keys (CI / headless / a fixed identity).** A key looks like `atr_...` and is minted in the
-Atrium web app under a project's *Settings → API keys*. Two shapes:
+Atrium web app under a project's *Capabilities → API keys*. Two shapes:
 
-- **Project-scoped key** — acts as that project; every call is scoped to it automatically, no
-  `project=` needed. The right shape for a study app that only ever writes to one project.
+- **Project-scoped key** — acts as that project; library and session calls are scoped to it
+  automatically, no `project=` needed (the surveys namespace is the exception — see below). The
+  right shape for a study app that only ever writes to one project.
 - **Account-wide key** — acts as your user across every project you can see.
 
 Pass it as `Atrium(api_key="atr_...")` or set `ATRIUM_API_KEY` — either skips the browser flow
@@ -106,6 +107,45 @@ me.key_project_id                       # set when a project-scoped key is in us
 me.effective_project_id                 # the project data ops target (scoped key, else your Personal project)
 ```
 
+### Set up your project for coding agents
+
+If you build with a coding agent, give it a standing pointer to this guide instead of letting it
+guess the API. Create an `AGENTS.md` at your project root:
+
+```markdown
+This project uses the hci-atrium SDK. Before writing Atrium code, run
+`atrium guide` and follow it — it is the authoritative API reference
+(`uv run atrium guide` in Python projects, `pnpm exec atrium guide` in
+TypeScript projects).
+
+Instance: https://atrium.example.edu — the SDK reads `ATRIUM_BASE_URL` from the
+process environment; no `.env` file is loaded for you, so export it or run via
+`uv run --env-file .env`.
+Credential: a project-scoped key as `ATRIUM_API_KEY`, set the same way. It
+confines every call to this project — library and session calls need no
+`project=` — but the surveys namespace still takes `project=` / `--project`.
+```
+
+The instance and credential lines carry their weight: this guide documents the API, not *your*
+deployment — without them an agent doesn't know which instance to point at or which credential you
+set up.
+
+Then add a `CLAUDE.md` beside it, for tools that read that name instead:
+
+```markdown
+This project's coding-agent context lives in [`AGENTS.md`](AGENTS.md). Read it
+before writing code. `AGENTS.md` is the canonical source — keep this file in sync.
+```
+
+**Agent that can't run commands?** Materialize the guide into the repo and point at the file:
+
+```sh
+uv run atrium guide > atrium-guide.md      # or: pnpm exec atrium guide > atrium-guide.md
+```
+
+The `AGENTS.md` line then becomes "read `atrium-guide.md` before writing Atrium code". Re-run it
+after upgrading the SDK — the printed guide ships with the installed version.
+
 ### Projects & scope
 
 A **project** is identified by a `p_...` short id (e.g. `p_4mD2qX`) — a base58, URL-safe id that
@@ -120,8 +160,10 @@ photos.library.search("rain")                                 # every call on `p
 ```
 
 `client.project(id)` / `client.collection(id)` return a scoped view that shares the same
-authenticated session (cheap — no re-auth). A project-scoped API key scopes everything
-automatically; you never need `project=` with one.
+authenticated session (cheap — no re-auth). A project-scoped API key confines access to its
+project automatically, so library and session calls need no `project=`. Namespaces that address a
+project *by reference* are the exception: `client.surveys.*` (and `atrium survey pull/push`) still
+want an explicit `project=` / `--project`, or a client scoped with `Atrium(project="p_…")`.
 
 ### The CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hci-atrium",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "TypeScript SDK for the Atrium framework — multimodal asset library, semantic + cross-modal search, and capability routing.",
   "type": "module",
   "license": "MIT",