# AGENTS

## Learned User Preferences

- Wants a TypeScript Clarizen client with SDK-style API: `new Clarizen(url, apiToken)` and namespaced methods (e.g. `clarizen.data.entityQuery(...)`).
- Wants session authentication via `authentication.login(user, pass)` that returns an API session for subsequent calls, not only static API tokens.
- May describe requirements in Portuguese as well as English.
- Wants full Clarizen API typings from `https://api.clarizen.com/V2.0/services/types/`, including nested types (`Condition`, `Expression`, `Operator`, etc.) — not generic `JsonObject` shortcuts for documented fields.
- When adding types, follow nested type links from the API docs and model every referenced type, not only top-level operation params.
- When extending the SDK, cross-check the Planview Adaptive Work REST API Guide (V2) with live `api.clarizen.com` docs; apply guide content only when it adds value beyond the live schema pages.
- Wants automatic retry (3 attempts) on all Clarizen HTTP calls except when the API returns `SessionTimeout`.

## Learned Workspace Facts

- ARCO monorepo (RivusLab): `clarizen-lib/` is the Clarizen SDK; sibling apps consume `@arco/clarizen-lib` via npm workspaces or `file:../clarizen-lib`.
- TypeScript package `@arco/clarizen-lib`: Clarizen / Planview Adaptive Work REST API V2.0 client.
- Clarizen V2.0 REST on `api.clarizen.com` is the Planview Adaptive Work API (Clarizen host, same V2.0 surface).
- Target API surface: `https://api.clarizen.com/V2.0/services/`; operations grouped in namespaces (`data`, `authentication`, `metadata`, etc.).
- Type schemas at `https://api.clarizen.com/V2.0/services/types/` drive request/response TypeScript types (e.g. EntityQuery `where` is `Condition`, sort is `orders` not `orderBy`).
- Secondary reference: Planview Adaptive Work REST API Guide V2 at https://success.planview.com/Planview_AdaptiveWork/API/REST_API_Guide_Version_2
- HTTP auth: `Authorization: ApiKey {token}` for API keys; `Authorization: Session {sessionId}` after login.
- All SDK HTTP traffic goes through `HttpClient.request`; retries are centralized there (3 attempts, no retry on `SessionTimeout`).
- Multi-tenant session login: `loginWithDiscovery` calls `authentication.getServerDefinition`, sets `baseUrl` from `serverLocation`, then `authentication.login`.
- `Clarizen.createForLogin(baseUrl?)` builds a client without prior auth for the discovery/login flow.
- Entity CRUD is exposed as `clarizen.objects` (REST under `/V2.0/services/data/objects/{typeName}/...`).
- API TypeScript types are generated from crawled schema (`npm run scrape:types` → `src/generated/clarizen-schema.json`, `npm run generate:types` → `src/clarizen-api-types.ts`).
- Planview guide notes live in `docs/references/planview-rest-api-v2.md`.
- Org metadata catalog: `listEntities` + `describeMetadata` with `flags: ["fields", "relations"]`; `clarizen.metadata.fetchCatalog()` at runtime; `npm run scrape:metadata` → `src/generated/metadata-catalog.json` + `metadata-types.ts`. Filter out names containing `C_` or `R_` (custom fields/relations/entities).