affinity-sdk 1.28.0__tar.gz → 2.0.0__tar.gz

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/.github/workflows/ci.yml

@@ -224,6 +224,9 @@ jobs:
             echo "Skipping traceability mapping (docs/internal not present in repo checkout)."
           fi
 
+      - name: API coverage ledger matches the pinned specs
+        run: python tools/api_coverage.py --check
+
       - name: MCP commands registry is valid
         run: |
           # Verify registry file exists and is valid JSON with expected structure

affinity_sdk-2.0.0/.github/workflows/cowork-replay.yml

@@ -0,0 +1,33 @@
+name: Cowork plugin tests (replay)
+
+# Replays the recorded cowork-harness runs of the xaffinity-cli plugin (tests/cowork). No token,
+# Docker or model: it re-checks the recorded runs, and fails when the plugin, a scenario or a
+# session changed since recording (re-record with tests/cowork/record.sh) or when a cassette
+# holds data the privacy scan flags.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  HARNESS: cowork-harness@4.7.1  # the version that recorded the cassettes
+
+jobs:
+  replay:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Lint scenarios
+        run: npx --yes "$HARNESS" lint tests/cowork/scenarios/
+      - name: Replay cassettes
+        run: npx --yes "$HARNESS" replay tests/cowork/cassettes/ --output-format json | jq -e '.ok'
+      - name: Verify cassettes (staleness and privacy)
+        working-directory: tests/cowork
+        run: npx --yes "$HARNESS" verify-cassettes cassettes/ --allow-patterns-file privacy-allow.txt

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/.github/workflows/plugin-build.yml

@@ -40,6 +40,19 @@ jobs:
         # Uses the full mcp-bash installed above; the vendored runtime has no validate.
         run: ./mcp/xaffinity-mcp.sh validate
 
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install the CLI from this checkout
+        run: python -m pip install -e ".[cli]"
+
+      - name: MCP tool tests (dry runs; no key, API unreachable)
+        env:
+          AFFINITY_V1_BASE_URL: http://127.0.0.1:9
+          AFFINITY_V2_BASE_URL: http://127.0.0.1:9/v2
+        run: ./mcp/test/run.sh
+
       - name: Build MCP plugin ZIP
         run: make -C mcp plugin
 

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/.gitignore

@@ -68,3 +68,6 @@ dormant_founders.json
 docs/superpowers/
 
 uv.lock
+
+# cowork-harness test image build output
+tests/cowork/image/dist/

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/.pre-commit-config.yaml

@@ -9,8 +9,11 @@ repos:
       - id: check-toml
       - id: check-yaml
       - id: end-of-file-fixer
+        exclude: ^tests/cowork/cassettes/  # recorded byte-for-byte
       - id: mixed-line-ending
+        exclude: ^tests/cowork/cassettes/  # recorded byte-for-byte
       - id: trailing-whitespace
+        exclude: ^tests/cowork/cassettes/  # recorded byte-for-byte
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.15.0

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/CHANGELOG.md

@@ -7,12 +7,186 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-10-12
+
+### Highlights
+
+**SDK 2.0 moves to Affinity's V2 API wherever V2 can do the job.** Webhooks, reminders, note
+writes, list get/create, file reads (new `files.get_v2`/`list_v2`) and the rate-limit endpoint
+now use V2; the CLI gains `xaffinity webhook ls|get|create|update|delete`. V1 stays only where
+V2 can't do it, and for person create/delete, opportunity rename/delete and adding to a list,
+which the V2 spec documents but the API didn't serve when tested. **Breaking:** webhook and
+reminder models change shape, note writes return `NoteV2`, `add_opportunity()` is removed, and
+operations added in newer Affinity API versions refuse a client pinned to an older one
+(`ApiVersionTooOldError`). See the [Migrating to 2.0](https://yaniv-golan.github.io/affinity-sdk/latest/guides/migrating-to-2/)
+guide.
+
+### Changed (breaking)
+
+- **Webhooks use the V2 API** (`/v2/webhooks`, Affinity API 2026-07-15 or later, beta).
+  `WebhookSubscription` is now `Webhook`: `webhook_url` → `url`, `disabled` →
+  `status` (`WebhookStatus.ACTIVE`/`DISABLED`), `created_by` → `creator` (`PersonRef`), plus
+  `created_at`/`updated_at`. `WebhookCreate(url=…, subscriptions=[…])` requires `subscriptions`
+  (`[]` = every event type). `WebhookUpdate` takes `url`, `subscriptions`, `status` and sends
+  only what is set. `list()` returns one page (`ids`, created/updated ranges, `limit`,
+  `cursor`); `iter()` returns every webhook. `update()` returns the webhook as read back (two
+  requests); `delete()` returns `None`. 1.x field names raise `ValidationError` instead of being
+  ignored. Without permission to manage all webhooks, the API lists, reads and changes only the
+  caller's own webhooks. A client pinned to API version 2024-01-01 gets
+  `ApiVersionTooOldError`.
+- **Reminders use the V2 API** (`/v2/reminders`; `get`/`delete` need API 2026-07-15, `update`
+  2026-09-17). `Reminder` has the V2 shape: `creator`, `owner`, `completer`, `person` are
+  `PersonRef` (id only; look names up separately), `company`/`opportunity` are
+  `CompanyRef`/`OpportunityRef`, recurrence is `recurrence` (`period_days`, `reset_type`; the
+  read-only `reset_type`/`reminder_days` properties still work), plus `updated_at`.
+  `ReminderType`, `ReminderResetType` and `ReminderStatus` are string enums with the V2 values
+  (member names unchanged; the 1.x integers are still accepted); `ReminderResetType.MEETING` is
+  now an alias of `EVENT`. `list()` takes `limit` (1-100), `cursor`, `ids` and created/updated
+  ranges instead of `page_size`/`page_token`, and returns reminders soonest-due first.
+  `update()` sends only the fields that are set (`clear_content=True` removes the content) and
+  returns the reminder as read back. `list_batch()` is on the sync client too, and fetches up to
+  50 entities per request. Kept on V1 where V2 can't do it: changing a reminder's type, and updating or deleting a
+  reminder you didn't create and don't own (V2 refuses; the SDK retries through V1). A reminder
+  must be attached to one person, company or opportunity (both APIs require it; the SDK now
+  says so before sending).
+- **Note writes use the V2 API** (`notes.create`, `update`, `delete`; reads are unchanged).
+  `create()` and `update()` return `NoteV2` (`content.html`, `creator`; `update()` reads the note
+  back with its attachments, two requests). V2 stores notes as HTML: plain text (the default
+  `type`) is escaped and wrapped in paragraphs, and `NoteUpdate` takes `type` too (plain text
+  unless set to `HTML`, whatever the note was before). With `type=NoteType.HTML`, `<b>`/`<i>`
+  become `<strong>`/`<em>`, and what the API rejects (style/class attributes, img, pre, code,
+  blockquote, mention spans, non-http(s)/mailto links) raises `ValueError` naming the allowed
+  tags. A reply (`parent_id`) with persons/companies/opportunities raises instead of ignoring
+  them; `AI_NOTETAKER`/`EMAIL_DERIVED` can't be created. `NoteUpdate` can replace a note's
+  persons, companies and opportunities (`[]` clears). Changing the text of a note that
+  @mentions people is refused by the API; the error now says so. `NoteV2` and `NoteContent`
+  are exported from `affinity.models`.
+- **`rate_limits.refresh()` reads `GET /v2/rate-limit`** (API 2026-07-15+), falling back to
+  response headers as before (now also when the client is pinned to an older API version).
+  `RateLimitSnapshot` is unchanged; `RateLimits` also reads the V2 names (`callerPerMinute`,
+  `orgPerMonth`).
+- **Lists: `get()` and `create()` use the V2 API.** `get()` no longer fills `fields` (use
+  `get_fields()`) or `additional_permissions`; it sets `created_at`. `get_size()` still reads
+  the size from V1 (V2 has none). `create()` makes the caller the owner; a public list needs the
+  "Share accessible Lists globally" permission. A list created with `owner_id` or
+  `additional_permissions` still goes through V1.
+- **`entries(list_id).add_opportunity()` is removed.** Opportunities can't be added to a list
+  as entries: create them on their list with `opportunities.create(OpportunityCreate(list_id=...))`.
+- Person create/delete, opportunity rename/delete and adding to a list stay on V1: the V2 spec
+  documents them, but Affinity didn't serve them when tested (2026-10-12).
+
+### Added
+
+- **`files.get_v2()`, `files.list_v2()`, `files.iter_v2()`** (V2, Affinity API 2026-09-17+):
+  a file's metadata with a download URL that expires after 60 seconds, and every file visible to
+  you across the organization, newest first (filter by created date and uploader). `FileV2`
+  model. `files.get/list/iter` stay on V1: only V1 lists one entity's files.
+- **CLI `webhook ls|get|create|update|delete`.** `create` takes `--url` and `--event`
+  (repeatable) or `--all-events`; `update` takes `--url`, `--event`/`--all-events`, `--status
+  active|disabled`. `create`, `update` and `delete` ask for confirmation (`--yes` in scripts),
+  since a webhook sends CRM events to an outside URL. Rows include `allEvents`.
+- **CLI `list get <id>`** no longer prints `.data.list.fields` (the fields are in `.data.fields`
+  as before), `additionalPermissions` is always `[]`, and `createdAt` is added; `list create
+  --owner-id` creates the list through V1.
+- **CLI `reminder create/update --reminder-days`** help now says what it is: the days between a
+  recurring reminder's due dates.
+- **CLI `note update --type plain-text|html`**; `note create --type` is now plain-text or html
+  (Affinity creates the other kinds itself). `note create`/`update` output keeps the `note get`
+  keys (`type` is `html`; content is the stored HTML). The duplicate-note warning still finds
+  an earlier copy: V1 shows notes stored as HTML in a markdown form, which the check allows for.
+- **CLI `reminder update --clear-content`**; `reminder ls --page-size` is now at most 100, and
+  rows include `updatedAt`; `--reset-type event` (`meeting` still accepted, printed as `event`).
+- **MCP:** the webhook commands are in the command registry; `webhook create`/`update`/`delete`
+  go through the same user confirmation as deletes, and the confirmation says why (events sent
+  to an outside URL).
+
+### Fixed
+
+- `Person.company_ids` and `Opportunity.company_ids` are now read from V1 responses
+  (`organization_ids`), e.g. from `persons.create()` with companies, `persons.update()`,
+  `opportunities.update()` and `get_details()`; they were always empty.
+
+### Docs
+
+- New **API coverage** reference page: every Affinity API operation (V2 and V1) and how the SDK
+  supports it — the SDK call, an equivalent operation, or the planned release — with beta
+  operations and the minimum API version marked.
+
+### Internal
+
+- `tools/api_coverage.py` and the ledger `tools/api_coverage.json` (CI: `--check`): every
+  operation in the pinned V2 snapshots and the new V1 snapshot (`tools/api_coverage_v1_snapshot.json`,
+  59 operations) has exactly one row. `tests/test_api_coverage.py` runs each supported row's call,
+  sync and async, against a recording HTTP layer and checks the method, path and API version it
+  requests.
+
+### Plugins
+
+- **SDK plugin**: 1.7.1 → 2.0.0 (matches SDK 2.0) — skill: note writes go through V2 (HTML, the
+  allowed tags), and `add_opportunity()` is gone (create the opportunity on its list).
+- **CLI plugin**: 1.13.6 → 2.0.0 (matches CLI 2.0; no content change).
+- **MCP**: 1.32.2 → 2.0.0 (requires CLI 2.0.0; see `mcp/CHANGELOG.md`).
+- **CLI plugin**: 1.13.5 → 1.13.6 — skill: the Cowork install line adds
+  `--no-warn-script-location` (pip's "not on PATH" warning was noise; the skill adds the folder to
+  PATH in each call), and the Cowork key paths (`--env-file`, `AFFINITY_API_KEY_FILE`) are quoted,
+  so connected folders with spaces in their names work.
+- **CLI plugin**: 1.13.4 → 1.13.5 — no `clis` credential declaration. In local Cowork it routed
+  every `xaffinity` call through Desktop's CLI credential broker, which isn't enabled yet and
+  refuses the call ("cli-wrapper: plugin oauth disabled"), so the CLI never ran whatever key the
+  VM had. Cowork's plugin settings no longer show an Affinity API Key field. The VM has no
+  `xaffinity` of its own, so the skill now installs it when it's missing (`pip install --user`,
+  about 10s, once per task) and puts `~/.local/bin` on PATH in each call; the CLI then reads the
+  key as the skill describes (a connected folder's `.env` with `--env-file`, or a key file).
+- **CLI plugin**: 1.13.3 → 1.13.4 — in local Cowork the plugin's hooks run on the host Mac, not
+  in the VM where the CLI runs, so the key check saw the Mac's key (or none) and could deny every
+  data command even with a key set in Cowork. There the hooks now do nothing; a missing key
+  shows up as the CLI's own error. Cloud Cowork and Claude Code keep the check. The `.env` read
+  guard's message no longer claims the key is in the environment.
+
+## [1.29.0] - 2026-10-11
+
+### Highlights
+
+**`field history-bulk` works on global fields.** A global field's changes (a company or person
+field shown on a list) belong to the company or person, not to the list entry, so reading them
+per entry returned nothing, with no warning. They are now read per company/person, or
+field-wide when the field's history is small, and each row carries the company's entry on the
+list.
+
+### Fixed
+
+- `field history-bulk` on a global field returned no rows. It now reads per company or person
+  (one call each; entries sharing one are read once, with a warning) and fills `listEntryId`
+  with the entry on the list. With `--all` on 100+ of them it reads the field's org-wide history
+  instead when that fits in one call; a forced `--strategy field` reads up to 200,000 changes and
+  otherwise stops with an error. Rows include changes from before the company joined the list.
+- `field history-bulk` with a field that isn't on the list, or an enriched field, gave empty
+  results; both are usage errors now. So is a global field with `--list-entry-ids`, which can't
+  map entries to companies.
+- `field history --list-entry-id` on a global field returned nothing; it now says the field is
+  global and to use `--company-id` / `--person-id`.
+- `config check-key`: when the key comes from a `.env` outside the current directory (e.g.
+  `--env-file` with a Cowork connected folder, where each shell call starts above it), the
+  suggested `pattern` names it with `--env-file <path>`, so later commands find it too.
+
+### Changed
+
+- `field history-bulk` reads field-wide 10,000 changes per call (was 500): fewer calls for list
+  fields too. The dry run reports `fieldKind` (`list` / `global`) and, for a global field,
+  `entities`.
+
+### Plugins
+
+- **CLI plugin**: 1.13.2 → 1.13.3 — skill: `history-bulk` on global fields; Cowork keys in a
+  connected folder need `--env-file /sessions/<id>/mnt/<folder>/.env` (each shell call starts
+  in the session root), and the check-key `pattern` carries it.
+
 ## [1.28.0] - 2026-10-11
 
 ### Highlights
 
-**Read the API key from 1Password.** `AFFINITY_API_KEY_FILE` (and `--api-key-file`) accept a
-`.env` file and a named pipe, so a 1Password Environments locally mounted `.env` works directly:
+**Read the API key from 1Password Environments.** `AFFINITY_API_KEY_FILE` (and `--api-key-file`)
+accept a `.env` file and a named pipe, so an Environment's locally mounted `.env` file works directly:
 the CLI waits for 1Password to supply the key after you approve the read, and the key never
 touches the disk.
 
@@ -23,7 +197,7 @@ touches the disk.
   error. A named pipe is read when its writer supplies the content, waiting up to 30 seconds,
   with a message naming 1Password if nothing arrives. `config check-key` reports a named pipe as
   configured without reading it, and skips its API-version probe for it (reading would prompt).
-  Tested with a 1Password Environments mount: approval and unlock prompts, repeated and
+  Tested with a real 1Password Environments locally mounted `.env` file: approval and unlock prompts, repeated and
   concurrent reads.
 
 ### Changed
@@ -40,7 +214,7 @@ touches the disk.
 - **CLI plugin**: 1.13.0 → 1.13.1 — skill describes the current CLI only (no per-version notes);
   one upgrade hint at install.
 - **CLI plugin**: 1.13.1 → 1.13.2 — skill: `AFFINITY_API_KEY_FILE` reads `.env` files and
-  1Password mounted `.env`s; forced `--strategy field` never falls back.
+  1Password Environments locally mounted `.env` files; forced `--strategy field` never falls back.
 - **SDK plugin**: 1.7.0 → 1.7.1 — skill: API version pinning, note/file/semantic company search,
   hidden values; new `references/services.md` organised by question (field history, org-wide
   activity, notes V2 and replies, transcripts, relationships, merges, dropdown options, uploads).

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 1.28.0
+Version: 2.0.0
 Summary: A modern, strongly-typed Python SDK for the Affinity CRM API
 Project-URL: Homepage, https://github.com/yaniv-golan/affinity-sdk
 Project-URL: Documentation, https://yaniv-golan.github.io/affinity-sdk/latest/
@@ -373,8 +373,8 @@ with Affinity(api_key="your-key") as client:
 ```python
 from datetime import datetime, timedelta
 from affinity import Affinity
-from affinity.models import ReminderCreate
-from affinity.types import PersonId, ReminderResetType, ReminderType, UserId
+from affinity.models import ReminderCreate, ReminderUpdate
+from affinity.types import PersonId, ReminderResetType, ReminderStatus, ReminderType, UserId
 
 with Affinity(api_key="your-key") as client:
     # Get current user
@@ -402,6 +402,14 @@ with Affinity(api_key="your-key") as client:
             person_id=PersonId(123),
         )
     )
+
+    # Complete it (a recurring reminder moves to its next due date)
+    client.reminders.update(recurring.id, ReminderUpdate(is_completed=True))
+
+    # Overdue reminders for many people, one request per 50 people
+    overdue = client.reminders.list_batch(
+        person_ids=[PersonId(123), PersonId(456)], status=ReminderStatus.OVERDUE
+    )
 ```
 
 ### Files
@@ -456,13 +464,13 @@ with Affinity(api_key="your-key") as client:
 ```python
 from affinity import Affinity
 from affinity.models import WebhookCreate, WebhookUpdate
-from affinity.types import WebhookEvent
+from affinity.types import WebhookEvent, WebhookStatus
 
 with Affinity(api_key="your-key") as client:
-    # Create a webhook subscription
+    # Create a webhook (subscriptions is required; [] means every event type)
     webhook = client.webhooks.create(
         WebhookCreate(
-            webhook_url="https://your-server.com/webhook",
+            url="https://your-server.com/webhook",
             subscriptions=[
                 WebhookEvent.LIST_ENTRY_CREATED,
                 WebhookEvent.LIST_ENTRY_DELETED,
@@ -471,14 +479,12 @@ with Affinity(api_key="your-key") as client:
         )
     )
 
-    # List all webhooks (max 3 per instance)
-    webhooks = client.webhooks.list()
+    # All webhooks you can see (all of them if you may manage all webhooks)
+    for hook in client.webhooks.iter():
+        print(hook.id, hook.url, hook.status)
 
-    # Disable a webhook
-    client.webhooks.update(
-        webhook.id,
-        WebhookUpdate(disabled=True)
-    )
+    # Pause a webhook (returns it as read back)
+    client.webhooks.update(webhook.id, WebhookUpdate(status=WebhookStatus.DISABLED))
 ```
 
 ### Rate Limits
@@ -545,9 +551,9 @@ those to V2 is planned.
 | List Entries (write) | Create | ✅ | V1 |
 | Field Values (read) | ✅ | ✅ | V2 |
 | Field Values (write) | ✅ | ✅ | V2 (list entries), V1 (companies/persons) |
-| Notes | ✅ | ✅ | V1 |
-| Reminders | ✅ | ✅ | V1 |
-| Webhooks | ✅ | ✅ | V1 |
+| Notes | ✅ | ✅ | V1 reads; V2 writes |
+| Reminders | ✅ | ✅ | V2 (V1 for type changes, and when V2 refuses a non-owner) |
+| Webhooks | ✅ | ✅ | V2 |
 | Interactions | Read-only | ✅ | V1 |
 | Entity Files | Read-only | ✅ | V1 |
 | Relationship Strengths | ✅ | ✅ | V1 |
@@ -697,7 +703,7 @@ async def main():
 asyncio.run(main())
 ```
 
-Async support mirrors the sync client surface area (including V1-only services like notes/reminders/webhooks/files).
+Async support mirrors the sync client surface area (including the V1 services like notes and files).
 
 See `docs/public/guides/sync-vs-async.md` for more details.
 

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/README.md

@@ -312,8 +312,8 @@ with Affinity(api_key="your-key") as client:
 ```python
 from datetime import datetime, timedelta
 from affinity import Affinity
-from affinity.models import ReminderCreate
-from affinity.types import PersonId, ReminderResetType, ReminderType, UserId
+from affinity.models import ReminderCreate, ReminderUpdate
+from affinity.types import PersonId, ReminderResetType, ReminderStatus, ReminderType, UserId
 
 with Affinity(api_key="your-key") as client:
     # Get current user
@@ -341,6 +341,14 @@ with Affinity(api_key="your-key") as client:
             person_id=PersonId(123),
         )
     )
+
+    # Complete it (a recurring reminder moves to its next due date)
+    client.reminders.update(recurring.id, ReminderUpdate(is_completed=True))
+
+    # Overdue reminders for many people, one request per 50 people
+    overdue = client.reminders.list_batch(
+        person_ids=[PersonId(123), PersonId(456)], status=ReminderStatus.OVERDUE
+    )
 ```
 
 ### Files
@@ -395,13 +403,13 @@ with Affinity(api_key="your-key") as client:
 ```python
 from affinity import Affinity
 from affinity.models import WebhookCreate, WebhookUpdate
-from affinity.types import WebhookEvent
+from affinity.types import WebhookEvent, WebhookStatus
 
 with Affinity(api_key="your-key") as client:
-    # Create a webhook subscription
+    # Create a webhook (subscriptions is required; [] means every event type)
     webhook = client.webhooks.create(
         WebhookCreate(
-            webhook_url="https://your-server.com/webhook",
+            url="https://your-server.com/webhook",
             subscriptions=[
                 WebhookEvent.LIST_ENTRY_CREATED,
                 WebhookEvent.LIST_ENTRY_DELETED,
@@ -410,14 +418,12 @@ with Affinity(api_key="your-key") as client:
         )
     )
 
-    # List all webhooks (max 3 per instance)
-    webhooks = client.webhooks.list()
+    # All webhooks you can see (all of them if you may manage all webhooks)
+    for hook in client.webhooks.iter():
+        print(hook.id, hook.url, hook.status)
 
-    # Disable a webhook
-    client.webhooks.update(
-        webhook.id,
-        WebhookUpdate(disabled=True)
-    )
+    # Pause a webhook (returns it as read back)
+    client.webhooks.update(webhook.id, WebhookUpdate(status=WebhookStatus.DISABLED))
 ```
 
 ### Rate Limits
@@ -484,9 +490,9 @@ those to V2 is planned.
 | List Entries (write) | Create | ✅ | V1 |
 | Field Values (read) | ✅ | ✅ | V2 |
 | Field Values (write) | ✅ | ✅ | V2 (list entries), V1 (companies/persons) |
-| Notes | ✅ | ✅ | V1 |
-| Reminders | ✅ | ✅ | V1 |
-| Webhooks | ✅ | ✅ | V1 |
+| Notes | ✅ | ✅ | V1 reads; V2 writes |
+| Reminders | ✅ | ✅ | V2 (V1 for type changes, and when V2 refuses a non-owner) |
+| Webhooks | ✅ | ✅ | V2 |
 | Interactions | Read-only | ✅ | V1 |
 | Entity Files | Read-only | ✅ | V1 |
 | Relationship Strengths | ✅ | ✅ | V1 |
@@ -636,7 +642,7 @@ async def main():
 asyncio.run(main())
 ```
 
-Async support mirrors the sync client surface area (including V1-only services like notes/reminders/webhooks/files).
+Async support mirrors the sync client surface area (including the V1 services like notes and files).
 
 See `docs/public/guides/sync-vs-async.md` for more details.
 

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/affinity/_internal/keyfile.py

@@ -59,7 +59,8 @@ _ENV_LINE = re.compile(r"^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*(.*)$")
 
 
 def _read_fifo(path: Path, timeout: float) -> str:
-    """Read a named pipe whose writer may appear later (e.g. a 1Password mounted .env).
+    """Read a named pipe whose writer may appear later (e.g. a 1Password Environments locally
+    mounted .env file).
 
     Opened non-blocking so a missing writer can't hang the process: reads return nothing until
     a writer has written, and end once it closes.
@@ -80,7 +81,8 @@ def _read_fifo(path: Path, timeout: float) -> str:
             if time.monotonic() > deadline:
                 raise ValueError(
                     f"Timed out after {timeout:g}s waiting for {path} (a named pipe). If it is "
-                    "a 1Password mounted .env: is 1Password running, and was the read approved?"
+                    "a 1Password Environments locally mounted .env file: is 1Password running, and "
+                    "was the read approved?"
                 )
             if not chunk:
                 time.sleep(0.05)

{affinity_sdk-1.28.0 → affinity_sdk-2.0.0}/affinity/cli/commands/config_cmds.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import getpass
 import os
 import re
+import shlex
 import stat
 import sys
 from contextlib import suppress
@@ -126,8 +127,8 @@ def _find_existing_key(ctx: CLIContext) -> tuple[bool, str | None]:
     if file_path_env:
         try:
             file_path = Path(file_path_env).expanduser()
-            # A named pipe (e.g. a 1Password mounted .env) is not read here: reading it asks
-            # 1Password for approval. Its existence is the evidence.
+            # A named pipe (e.g. a 1Password Environments locally mounted .env file) is not read
+            # here: reading it asks 1Password for approval. Its existence is the evidence.
             if file_path.exists() and stat.S_ISFIFO(file_path.stat().st_mode):
                 return True, "file"
             if file_path.is_file() and file_path.read_text(encoding="utf-8").strip():
@@ -212,7 +213,16 @@ def check_key(ctx: CLIContext) -> None:
         pattern: str | None = None
         if key_found:
             if source == "dotenv":
-                pattern = "xaffinity --dotenv --readonly <command> --json"
+                env_file = Path(ctx.env_file).resolve()
+                if env_file == (Path.cwd() / ".env").resolve():
+                    pattern = "xaffinity --dotenv --readonly <command> --json"
+                else:
+                    # Not in the current directory (e.g. Cowork, where each shell call starts
+                    # above the connected folder): name it, or later commands won't find it
+                    pattern = (
+                        f"xaffinity --dotenv --env-file {shlex.quote(str(env_file))} "
+                        "--readonly <command> --json"
+                    )
             else:
                 pattern = "xaffinity --readonly <command> --json"
 
@@ -248,7 +258,8 @@ def _probe_key_default_api_version(ctx: CLIContext, source: str | None) -> str |
 
     One unversioned V2 request with a short timeout and no retries. Never raises, never
     runs AFFINITY_API_KEY_COMMAND (check-key deliberately doesn't), never reads stdin and
-    never reads a named pipe (a 1Password mounted .env would prompt the user).
+    never reads a named pipe (a 1Password Environments locally mounted .env file would
+    prompt the user).
     """
     if (
         source == "command"