@salesforce/graphiti 10.10.2

package/AGENT_GUIDE.md

@@ -0,0 +1,424 @@
+# Graphiti Agent Guide (v2)
+
+Graphiti is a CLI for building and executing Salesforce GraphQL queries by navigating the schema like a filesystem. A **session** holds the current navigation path and query projection.
+
+## Quick Start
+
+```bash
+graphiti agent-guide                    # print this guide (for agents)
+graphiti connect <org>                  # download schema (one-time per org)
+graphiti new <org> --name myQuery       # create a session
+graphiti use myQuery                    # set it as active (persists)
+graphiti cd uiapi/query/Case/edges/node
+graphiti select Id Subject.value:subject Status.value:status
+graphiti set uiapi/query/Case first=10
+graphiti check                          # validate
+graphiti run                            # execute
+```
+
+## Session Resolution
+
+All session commands target the **active session** implicitly. Resolution order:
+
+1. `--session <id>` / `-s <id>` flag (highest priority)
+2. `GRAPHITI_SESSION` env var
+3. `~/.graphiti/active` file (set by `graphiti use`)
+
+```bash
+graphiti use myQuery                    # sets active session
+graphiti select Id                      # targets myQuery implicitly
+graphiti -s other select Id             # targets "other" for this command only
+GRAPHITI_SESSION=other graphiti ls      # env var override
+```
+
+## JSON / Agent Mode
+
+Every command supports `--json` for structured JSON output. Set `GRAPHITI_AGENT=1` for all commands:
+
+```bash
+graphiti show --json                    # single command JSON
+GRAPHITI_AGENT=1 graphiti ls            # all output is JSON
+```
+
+Exit codes: 0=success, 1=user error, 2=validation failure, 3=execution failure, 4=auth failure.
+
+---
+
+## Session Management
+
+```bash
+graphiti new <org> [--mutation] [--aggregate] [--name <n>] [--force]
+graphiti use <session-id-or-name>
+graphiti sessions                       # list all sessions
+graphiti sessions rm <id-or-name>       # delete a session
+graphiti sessions prune --older-than 7d # prune old sessions
+graphiti clone [name]                   # duplicate current session
+graphiti reset                          # clear all state in current session
+```
+
+---
+
+## Navigation
+
+The schema is a tree rooted at `/`. Navigate with `cd`, inspect with `ls`.
+
+```bash
+pwd                                     # print current path
+cd uiapi/query/Account                  # absolute path (query/ prefix auto-added)
+cd edges/node                           # relative path
+cd @args                                # enter arguments directory
+cd @args/where                          # enter a specific argument
+cd /variables                           # jump to variables
+cd ..                                   # go up one level
+cd /                                    # go to root
+ls                                      # list fields (20 by default)
+ls -l                                   # long listing with metadata (shows [required] on args)
+ls -a                                   # show all fields
+ls --search Name                        # filter by name (CamelCase prefix match)
+ls Name Owner Status                    # peek inside multiple directories
+```
+
+### Shell-safe fragment syntax
+
+Union/interface types use `on:TypeName` instead of `[TypeName]` to avoid shell quoting:
+
+```bash
+cd Owner/on:User
+select Owner.on:User.Name.value:ownerName
+```
+
+---
+
+## Building the Projection
+
+Select leaf fields with **absolute or relative paths**. Dot-path syntax with inline aliases:
+
+```bash
+select Id                                       # plain leaf
+select Name.value:name                          # dot-path with alias
+select Id Subject.value:subject Status.value    # multiple fields
+select uiapi/query/Case/edges/node/Id           # absolute path (no cd needed)
+select ls                                       # list all selected fields
+drop <alias-or-path>                            # remove by alias or path
+drop ownerName
+drop $filter                                    # remove a variable
+```
+
+**Agent best practice**: Use absolute paths to avoid interleaving `cd` with `select`:
+
+```bash
+graphiti select \
+  uiapi/query/Case/edges/node/Id \
+  uiapi/query/Case/edges/node/Subject.value:subject \
+  uiapi/query/Case/edges/node/Status.value:status
+```
+
+### @optional Directive (Field-Level Security)
+
+Salesforce field-level security (FLS) can cause fields to be absent from the response at runtime. The `@optional` directive tells the API to return `null` instead of erroring when FLS blocks a field. **This should be the standard way to request fields** so FLS issues are handled gracefully.
+
+Apply at selection time with `--optional`:
+
+```bash
+select --optional Subject.value:subject Status.value:status
+```
+
+Or toggle on already-selected fields:
+
+```bash
+optional Subject Status                  # add @optional
+optional --remove Subject                # remove @optional
+```
+
+The `@optional` directive appears in the rendered query:
+
+```graphql
+query {
+  uiapi {
+    query {
+      Case {
+        edges {
+          node {
+            Subject @optional {
+              value
+            }
+            Status @optional {
+              value
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+In `ls` output, fields with `@optional` are marked with `?`:
+
+```
+* Id
+?*Subject/
+?*Status/
+```
+
+In `select ls`, `@optional` fields are tagged:
+
+```
+  Subject.value → subject @optional
+  Status.value → status @optional
+```
+
+In `codegen` output, `@optional` fields become optional TypeScript properties with `| undefined`:
+
+```typescript
+Subject?: { value: string | null } | null | undefined;
+Status?: { value: CaseStatus | null } | null | undefined;
+```
+
+---
+
+## Arguments (set / unset)
+
+Use **inline key=value syntax** for efficiency:
+
+```bash
+set first=10                                    # set on current field
+set uiapi/query/Case first=10 scope=MINE        # with absolute field path
+set where='{"Status":{"eq":"New"}}'             # JSON value
+set uiapi/query/Case/edges/node/CaseComments first=50 orderBy='[{"CreatedDate":{"order":"DESC"}}]'
+unset first                                     # remove an argument
+unset where/Name/like                           # remove nested arg
+```
+
+Legacy pair syntax still works:
+
+```bash
+set @args/first 10
+set @args/where/Name/like "Acme%"
+```
+
+### Pagination shorthand (`cursor`)
+
+Add `cursor` to any `set` command to enable cursor-based pagination in one step:
+
+```bash
+set uiapi/query/Case first=10 cursor
+# Equivalent to:
+#   set uiapi/query/Case first=10
+#   var $after uiapi/query/Case/@args/after
+#   select uiapi/query/Case/pageInfo/hasNextPage uiapi/query/Case/pageInfo/endCursor
+```
+
+This defines `$after: String`, binds it to the connection's `after` arg, and auto-selects `pageInfo { hasNextPage endCursor }` so pagination loops work out of the box.
+
+### ObjectInfo Guardrails
+
+When setting arguments, the CLI warns immediately about:
+
+- **Invalid picklist values**: `Warning: "Invalid" is not a known picklist value for Status. Valid values: New, On Hold, ...`
+- **Non-filterable fields in where**: `Warning: Description is not filterable per ObjectInfo.`
+- **Non-sortable fields in orderBy**: `Warning: Description is not sortable per ObjectInfo.`
+- **Create-only fields in update mutations**: `Warning: ParentId is create-only (not updateable).`
+
+---
+
+## Variables (var)
+
+Variables make arguments parameterisable:
+
+```bash
+var $filter @args/where                         # auto-infer type and bind
+var $limit @args/first 10                       # with default value
+var $caseId uiapi/query/Case/@args/where/Id/eq   # bind to a deep arg path
+set $filter '{"Name":{"like":"Acme%"}}'         # set runtime value
+run --var caseId=500SG00001KZliXYAT             # ad-hoc override at execution
+```
+
+---
+
+## Aliases (multiple queries in one request)
+
+```bash
+cd uiapi/query
+alias newCases Case
+set newCases/@args/where '{"Status":{"eq":"New"}}'
+set newCases/@args/first 10
+select newCases/edges/node/Id newCases/edges/node/Subject/value
+
+alias myCases Case
+set myCases/@args/scope MINE
+set myCases/@args/first 20
+select myCases/edges/node/Id myCases/edges/node/Status/value
+```
+
+---
+
+## Review & Execute
+
+```bash
+show                                    # full session snapshot
+show --json                             # JSON output (most important for agents)
+check                                   # validate against schema + Salesforce semantics
+run                                     # execute against the org
+run --dry-run                           # preview without executing
+run --var caseId=500xxx                 # ad-hoc variable override
+describe Case                           # inspect SObject with ObjectInfo metadata
+codegen                                 # generate client types (default: TypeScript)
+codegen --language typescript           # explicit language selection
+codegen -l ts --out types.ts --name CaseDetail
+```
+
+Supported `--language` values: `typescript` (alias `ts`). Additional languages
+may be added over time; run `graphiti codegen --help` to see the current list.
+
+### Semantic Validation (check)
+
+Beyond GraphQL schema validation, `check` also warns about:
+
+- Connection fields without `first` set (optional but recommended for predictable pagination)
+- Non-filterable fields in `where` clauses
+- Non-sortable fields in `orderBy` clauses
+- Empty selection sets on connections
+- Missing required fields in mutation inputs
+
+---
+
+## Command Chaining
+
+Run multiple commands in a single invocation (session loaded once):
+
+```bash
+graphiti chain -s cases "cd uiapi/query/Case; set first=10; select edges/node/Id; check"
+graphiti chain -s cases --json "select Id; set first=10; check"  # JSON array output
+```
+
+---
+
+## Describe (SObject Inspection)
+
+```bash
+graphiti describe Case                  # by name
+graphiti describe                       # auto-detect from current navigation
+```
+
+Shows: fields with labels, picklist values, reference targets, required/auto/create-only/filterable/sortable tags, child relationships, filter/orderBy examples.
+
+---
+
+## Key Workflows
+
+### 1. Query with absolute paths (agent-optimized, no cd needed)
+
+```bash
+graphiti new vscodeOrg --name caseDetail && graphiti use caseDetail
+graphiti select \
+  uiapi/query/Case/edges/node/Id \
+  uiapi/query/Case/edges/node/Subject.value:subject \
+  uiapi/query/Case/edges/node/Status.value:status
+graphiti set uiapi/query/Case first=1 where='{"Id":{"eq":"$caseId"}}'
+graphiti var $caseId uiapi/query/Case/@args/where/Id/eq
+graphiti check && graphiti run --var caseId=500SG00001KZliXYAT
+```
+
+### 2. Query with navigation (human-friendly)
+
+```bash
+graphiti new vscodeOrg --name accounts && graphiti use accounts
+graphiti cd uiapi/query/Account/edges/node
+graphiti ls -l Name AnnualRevenue Industry Phone Owner
+graphiti select Id Name.value:name AnnualRevenue.value:revenue Industry.value:industry
+graphiti set uiapi/query/Account first=10
+graphiti set uiapi/query/Account where='{"AnnualRevenue":{"gt":10000}}'
+graphiti check && graphiti run
+```
+
+### 3. Create a record (mutation)
+
+```bash
+graphiti new vscodeOrg --mutation --name createOpp && graphiti use createOpp
+graphiti cd uiapi/OpportunityCreate/Record
+graphiti select Id Name.value:name StageName.value:stage
+graphiti cd uiapi/OpportunityCreate/@args
+graphiti var $input input
+graphiti set $input '{"Opportunity":{"Name":"New Deal","CloseDate":"2026-06-30","StageName":"Prospecting"}}'
+graphiti check && graphiti run
+```
+
+### 4. Aggregate query (count/group)
+
+```bash
+graphiti new vscodeOrg --aggregate --name orderCounts && graphiti use orderCounts
+graphiti select \
+  uiapi/aggregate/Order/edges/node/aggregate/Status/value:status \
+  uiapi/aggregate/Order/edges/node/aggregate/Id/count/value:orderCount
+graphiti set uiapi/aggregate/Order 'groupBy={"Status":{"group":true}}'
+graphiti check && graphiti run
+```
+
+Aggregate queries use `uiapi/aggregate/<SObject>` instead of `uiapi/query/<SObject>`. Fields live under `edges/node/aggregate/<Field>` and expose `value`, `count`, `countDistinct`, and `grouping`. Use `groupBy` to group results.
+
+### 5. Chained commands (fastest)
+
+```bash
+graphiti new vscodeOrg --name caseDetail
+graphiti chain -s caseDetail 'select uiapi/query/Case/edges/node/Id uiapi/query/Case/edges/node/Subject.value:subject; set uiapi/query/Case first=1 where={"Id":{"eq":"$caseId"}}; var $caseId uiapi/query/Case/@args/where/Id/eq; check; run --var caseId=500SG00001KZliXYAT'
+```
+
+---
+
+## Tips
+
+- `show --json` is the single most important command for agents — one call gives everything.
+- `ls -l` shows ObjectInfo metadata: labels, picklist values, reference targets, filterable/sortable.
+- `describe Case` shows a complete SObject view with field metadata and examples.
+- `codegen` generates client types for the session. `--language typescript` (default, alias `ts`) produces TypeScript with picklist unions from ObjectInfo. Pass `--language <lang>` to target additional languages as they are added.
+- Use absolute paths with `select` and `set` to avoid interleaving `cd` calls.
+- `select ls` lists all currently selected fields — useful for debugging.
+- `undo` reverts the last mutation (cd, select, drop, set, var, alias, reset).
+- Pass `-q` / `--quiet` to `select` to suppress confirmation messages in scripts.
+- Salesforce wraps field values in typed objects (`StringValue`, `PicklistValue`, etc.). Use dot-path: `select Name.value:name`.
+- `on:TypeName` is the shell-safe alternative to `[TypeName]` for fragments.
+
+## Common Pitfalls
+
+### Shell variable expansion with `$`
+
+When using `where.Field=$varName`, **always single-quote** the argument to prevent the shell from expanding `$varName` to an empty string:
+
+```bash
+# WRONG — shell expands $status to empty string:
+graphiti set uiapi/query/Case where.Status=$status
+
+# CORRECT — single quotes prevent expansion:
+graphiti set uiapi/query/Case 'where.Status=$status'
+```
+
+The CLI will warn if it detects an empty where value (likely from shell expansion).
+
+### Mutation payloads don't include relationships
+
+Mutation create/update payloads only return the flat record fields. You cannot select related objects (e.g., `Account/Name`) from a mutation result. Use a follow-up query with the returned `Id` to fetch related data.
+
+### User scope limitation
+
+The `User` SObject only supports `scope=EVERYTHING`, not `scope=MINE`. To get the current user, use `where.Id=$userId` and pass the user's ID at runtime.
+
+### Parallel agent builds
+
+When multiple agents build queries concurrently, the global active session causes cross-contamination. Each `new` command changes the active session, so another agent's `select`/`set` commands silently target the wrong session.
+
+**Always use `-s` when running in parallel:**
+
+```bash
+# WRONG — agents race on the active session:
+graphiti new vscodeOrg --name query-a --force
+graphiti select uiapi/query/Case/edges/node/Id  # may target query-b!
+
+# CORRECT — explicit session targeting:
+graphiti new vscodeOrg --name query-a --force
+graphiti -s query-a select uiapi/query/Case/edges/node/Id
+graphiti -s query-a set uiapi/query/Case first=10
+graphiti -s query-a check --codegen
+```
+
+For sequential single-agent workflows, the active session is safe to use implicitly.