@sortlist/cli 0.60.0 → 0.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,197 @@
1
+ # Atlas: searches, places and reveals
2
+
3
+ Read this for organization/contact searches and data reveals. Command help and the current schema
4
+ override these examples when the backend changes. For cost calculation and approval, use
5
+ [billing-and-permissions.md](billing-and-permissions.md).
6
+
7
+ ## Search lifecycle
8
+
9
+ `find-organizations` and `find-contacts` submit a search mutation. The mutation acknowledges receipt;
10
+ the page arrives through a subscription, repeatedly while `FILLING`, then `COMPLETE`. Pass `--wait`
11
+ for a new search. Specify a unique, meaningful `--external-id` so recovery context is available even
12
+ if no result arrives. This correlates results; it is not a general idempotency guarantee for finds.
13
+
14
+ After inspecting current help and schema, a preview can look like:
15
+
16
+ ```bash
17
+ sl atlas find-organizations --company <slug> --external-id <task>-orgs-1 \
18
+ --filter '{"domain":{"in":["acme.com"]}}' --page '{"first":5}' \
19
+ --reveal none --wait --fields id,domain
20
+
21
+ sl atlas find-contacts --company <slug> --external-id <task>-contacts-1 \
22
+ --organization-filter '{"domain":{"in":["acme.com"]}}' --page '{"first":5}' \
23
+ --reveal none --wait --fields id,jobTitle,jobLevel,organization.node.domain
24
+ ```
25
+
26
+ The `in` example is a database filter. A single `domain.eq` may initiate an external organization
27
+ lookup when no fresh record exists. Contacts may call providers to fill a page even without reveals.
28
+ Do not call either pattern provider-free without a verified server contract.
29
+
30
+ The payload is usually shaped as:
31
+
32
+ ```json
33
+ {
34
+ "externalId": "task-contacts-1",
35
+ "status": "COMPLETE",
36
+ "contacts": {
37
+ "edges": [{"node": {}, "reveals": [], "credits": {}}],
38
+ "pageInfo": {"hasNextPage": false, "endCursor": null},
39
+ "credits": {"held": 0, "used": 0, "byDimension": []}
40
+ }
41
+ }
42
+ ```
43
+
44
+ `organizations` replaces `contacts` for organization searches. Inspect the actual metadata rather
45
+ than assuming it is identical on every endpoint. `--fields` selects record fields while the CLI
46
+ includes connection metadata and edge reports when the schema provides them.
47
+
48
+ ## Partial results and continuation
49
+
50
+ Save caller, company, external ID, filters, requested dimensions, fields, page arguments, status,
51
+ cursor and the latest page. Mark `FILLING` rows as provisional. Exit 5 can mean an accepted request
52
+ with no page yet, or a partial page that may still change.
53
+
54
+ Never resubmit `find-*` just to wait longer. `--wait` subscribes and then submits the mutation;
55
+ without `page.after`, this starts a new search even if the same external ID is reused. Use
56
+ `sl operations` and help to find a result read or subscription available to this identity. If one
57
+ exists, select only allowed fields and follow its actual timeout/stream semantics. A subscription
58
+ with `--once` may return the first provisional event, so inspect status. If no recovery command is
59
+ exposed, say that recovery is unavailable through this CLI and keep the request unresolved instead
60
+ of fabricating a resume command or silently starting over.
61
+
62
+ For a **completed** page with `hasNextPage: true`, use its actual `endCursor` to request the next
63
+ page in the same search. Page sizes are currently 1 to 20, with 20 the default. `page.after` keeps
64
+ the original filter, organization filter and sort; changing those flags does not refine that search.
65
+ A search currently lives one hour and lists at most 1,000 records. Use current help for limits.
66
+ **Never pass `--total-count` to an Atlas command:** counting every match is too slow. A returned
67
+ counter may describe records listed so far, not every possible match. Report the rows actually
68
+ obtained and whether more pages follow, never a market total inferred from that counter.
69
+
70
+ The CLI's next-page hint omits some original flags. Preserve the intended `--company`, allowed
71
+ `--fields` and `--reveal none`, or the approved explicit dimensions, on continuation. Another page
72
+ of reveals can incur additional charges and must stay within the approved scope and ceiling.
73
+
74
+ ## Fields and fit
75
+
76
+ An organization is keyed by its primary domain; names, descriptions, firmographics, websites,
77
+ locations and reach data may be locked by reveal dimensions. Contacts belong to an organization.
78
+ Common readable preview fields include ID, job title and level; names, email, LinkedIn and phone
79
+ can require reveals. Use `sl schema inspect` on the actual output type before selecting unfamiliar
80
+ fields. Presence in a schema does not establish that the caller owns or can read a value.
81
+
82
+ A find applies the requested filter with no hidden quality floor. State any required presence,
83
+ confidence or reachability explicitly. `reachableBy` filters channel availability without revealing
84
+ the value: contact channels include `EMAIL_ADDRESS`, `LINKEDIN_URL`, `PHONE_NUMBER`; organization
85
+ channels can include `WEBSITE`. Inspect the current enum and operator types first. Available email
86
+ does not by itself prove current employment, role suitability or permitted outreach.
87
+
88
+ Check commercial fit before buying reach data. A semantic industry match can return an agency
89
+ serving the target sector instead of a company selling the requested product. A `Manager` level
90
+ does not turn a salesperson into a marketing decision maker. Preserve the user's geography and
91
+ seniority; explain a proposed relaxation instead of silently applying it. When covering named
92
+ accounts, measure accepted roles per account and deduplicate company aliases rather than presenting
93
+ several domains of one company as diverse coverage.
94
+
95
+ ### Reuse previews, then deepen gaps
96
+
97
+ Find and validate organizations before searching their people. First inspect contacts already
98
+ returned with those organizations or supplied in the task dataset. A useful observed role does not
99
+ need a second search merely because it came from a preview. Record coverage per validated account,
100
+ then deepen the accounts still short of the requested useful roles.
101
+
102
+ Organization contact previews currently contain at most ten people. They are not every employee,
103
+ a relevance-ranked shortlist or proof that the account has no suitable role. Where returned metadata
104
+ shows more contacts, inspect a small account-scoped contact page before declaring a gap. When a
105
+ precise title filter leaves too few candidates, a small page without that title filter, sorted by
106
+ `JOB_TITLE_DISTANCE` toward the intended responsibility with `direction: ASC`, can expose useful
107
+ existing roles. Keep the original acceptance criteria when reviewing this broader candidate pool.
108
+ For example, after checking current help and schema:
109
+
110
+ ```bash
111
+ sl atlas find-contacts --company <slug> --external-id <task>-gap-1 \
112
+ --organization-filter '{"id":{"in":["<validated organization id>"]}}' \
113
+ --sort '[{"field":"JOB_TITLE_DISTANCE","query":"facilities maintenance physical site prevention","direction":"ASC"}]' \
114
+ --page '{"first":5}' --reveal none --wait --fields id,jobTitle,jobFunction,organization.node.id
115
+ ```
116
+
117
+ Choose a small page appropriate to the known stock and task, for example five or ten. Do not request
118
+ twenty just to fill a default, repeatedly search an already covered account, or require a channel
119
+ the user does not need. No-reveal and account scoping do not enforce a cache-only mode or prove a
120
+ particular latency or provider cost. Preserve the search state and explain unresolved gaps; use
121
+ the go-to-market [sourcing reference](../../sortlist-go-to-market/references/sourcing.md) when
122
+ building a shortlist across accounts.
123
+
124
+ ## Filters and sorting
125
+
126
+ Use the input types named by command help; inspect nested types when needed. Common shapes:
127
+
128
+ - Strings: `eq`, `in`, `notEq`, `notIn`, `presence`, `blank`. Numbers: `eq`, `gt`, `gteq`, `lt`,
129
+ `lteq`. Range filters such as company size use `overlaps`, `containedBy`, `contains`. Do not assume
130
+ every output field is a legal filter: for example, annual revenue may be readable but not filterable.
131
+ - `allowBlank: true` intentionally includes missing values. Avoid it when absence would violate a
132
+ hard requirement and label accepted unknowns separately.
133
+ - `domain` normalizes scheme, `www.` and path; names normalize case, accents, punctuation and legal
134
+ forms; LinkedIn URLs compare vanity slugs; email addresses are trimmed and lowercased. These
135
+ remain exact matches after normalization.
136
+ - Semantic inputs such as organization `description`/`industry` and contact `jobTitle` take a list
137
+ of `{"queries":[...],"match":"INCLUDED_STRICT"}` entries. Queries inside an entry are OR;
138
+ multiple entries are AND. `INCLUDED_LOOSE` widens and `EXCLUDED_*` removes. Strict remains
139
+ semantic matching, not literal title equality. Use related terms and translations, one concept per
140
+ query, then inspect the returned business or role evidence.
141
+ - Organization size example: `"companySize":{"overlaps":[11,200]}`; `[1000]` represents 1,000+.
142
+ - For distance sorts (`INDUSTRY_DISTANCE`, `DESCRIPTION_DISTANCE`, contact `JOB_TITLE_DISTANCE`),
143
+ pass `"direction":"ASC"` explicitly. Descending distance puts less similar results first.
144
+
145
+ One-record filters can use organization domain, or contact ID, LinkedIn URL or email. A name match
146
+ should be constrained to the intended organization. A missing fresh contact may trigger identification
147
+ work; it is not just a database read.
148
+
149
+ ## Places
150
+
151
+ Atlas geography uses Mercator IDs in `divisionIds`, not free-text place names. Resolve the place
152
+ using an available Mercator command, then filter Atlas:
153
+
154
+ ```bash
155
+ sl mercator resolve-by-code --code BE --code-type COUNTRY_ISO --fields id,name
156
+ sl mercator resolve-locations --query "Brabant wallon" --within <belgium-id> \
157
+ --first 5 --fields id,name,shortName,subtype,adminLevel
158
+ ```
159
+
160
+ Use the intended company context on commands that require it. Disambiguate with `--within`, a
161
+ subtype filter such as `'{"in":["LOCALITY"]}'`, or `--exact-only true` when a wrong fuzzy match
162
+ is unacceptable. Verify the returned name and subdivision level before using its ID. For example,
163
+ Brabant wallon is a county; Wavre is a locality. `sl mercator location-subtypes` shows available levels.
164
+ A division matches its descendants, so a county includes its localities; several accepted divisions
165
+ can share one `in` list. If this identity cannot access Mercator, use an already verified ID only
166
+ when its meaning is known or explain the missing capability; do not substitute a guessed ID.
167
+
168
+ | Requirement | Atlas filter location |
169
+ | --- | --- |
170
+ | Organizations with an address in the place | `find-organizations --filter '{"divisionIds":{"in":["<id>"]}}'` |
171
+ | Contacts themselves located in the place | `find-contacts --filter '{"divisionIds":{"in":["<id>"]}}'` |
172
+ | Contacts working at an organization in the place | `find-contacts --organization-filter '{"divisionIds":{"in":["<id>"]}}'` |
173
+
174
+ An organization address does not prove headquarters or a person's responsibility for that site.
175
+ Do not add contact residence as a proxy for a requested Belgium/Benelux business remit; an appropriate
176
+ regional decision maker can live abroad.
177
+
178
+ ## Reveal only selected dimensions
179
+
180
+ Finds default to no reveal. Use `--reveal none` explicitly for previews. Locked fields can be null;
181
+ owned dimensions may be readable, so no-reveal is not a substitute for excluding forbidden fields.
182
+ After approval, use named dimensions such as `contactIdentity,contactEmailAddress` or their full
183
+ enum spellings. Inspect `RevealDimension` instead of guessing an organization dimension.
184
+ `--reveal` applies to every row on the page, including selected nested organization dimensions.
185
+ Narrow the filter to the chosen record IDs and bound the page before revealing.
186
+
187
+ | Reveal status | Interpretation |
188
+ | --- | --- |
189
+ | `LOCKED` | Not requested or owned by this company; locked values remain null. |
190
+ | `REVEALED` | A dimension was revealed and recorded by this response; count one reveal unit. |
191
+ | `OWNED` | Already available to this company until `ownedUntil`; no new reveal unit for the reread. |
192
+ | `UNAVAILABLE` | Atlas has no value for the dimension; not a successful reveal. |
193
+ | `FAILED` | The provider lookup did not complete; do not silently start another search to retry. |
194
+
195
+ Email and phone reveals can initiate missing-value lookups and keep the page filling until those
196
+ lookups settle. Never turn the unit counter into customer billing credits without the current
197
+ dimension price. Keep source/provider cost distinct from both quantities.
@@ -0,0 +1,253 @@
1
+ # Billing, approval and spend reports
2
+
3
+ Read before a quote, paid data reveal, watcher, Outreach action or subscription change. Keep the
4
+ requested output, caller and payer explicit. Prices come from the [price list](#prices) below,
5
+ or from a price list command when `sl operations` shows one for this identity.
6
+
7
+ ## Separate the counters
8
+
9
+ | Quantity | Meaning | What it proves |
10
+ | --- | --- | --- |
11
+ | Atlas `credits.held` | Reveal-unit ceiling for the requested page/dimensions | Reservation in dimension units, not necessarily billing credits held on the company balance. |
12
+ | Atlas `credits.used` | Number of newly revealed record/dimension pairs on a page | Observed reveal units, not the weighted debit. |
13
+ | Atlas `credits.byDimension[].used` | Newly revealed units grouped by dimension | Input to the weighted price calculation. |
14
+ | Customer billing credits | Units multiplied by the applicable price, or the price of a lead/action | Needs the price list or an authoritative transaction record. |
15
+ | Provider costs | External search, identification, email/phone lookup and other upstream work | Not established by zero reveal units or a no-reveal flag. |
16
+
17
+ One page can hold 20 reveal units for ten identities and ten emails while its maximum customer
18
+ debit is much higher than 20 credits. An `OWNED` dimension contributes no new reveal unit while
19
+ its ownership window remains valid. `UNAVAILABLE` and `FAILED` are not successful reveals. Do not
20
+ promise a full expiry window unless returned `ownedUntil` values support it; different records can
21
+ have different dates.
22
+
23
+ ## Prices
24
+
25
+ What each paid item costs a company, in customer credits, as of 10 November 2026. Prices can
26
+ change: a quote names this list and its date, and the debit follows the price in force when the
27
+ work runs. If `sl operations --search price` shows a price list command for this identity, read it
28
+ and prefer its figures. A plan or a balance does not change a price.
29
+
30
+ | Atlas reveal dimension | Credits per record revealed |
31
+ | --- | --- |
32
+ | `CONTACT_IDENTITY` | 2 |
33
+ | `CONTACT_LINKEDIN_URL` | 5 |
34
+ | `CONTACT_EMAIL_ADDRESS` | 40 |
35
+ | `CONTACT_PHONE_NUMBER` | 150 |
36
+ | `ORGANIZATION_IDENTITY` | 1 |
37
+ | `ORGANIZATION_WEBSITE` | 1 |
38
+ | `ORGANIZATION_LINKEDIN_URL` | 2 |
39
+ | `ORGANIZATION_ADDRESS` | 2 |
40
+ | `ORGANIZATION_FIRMOGRAPHICS` | 5 |
41
+ | `ORGANIZATION_EMAIL_ADDRESS` | 5 |
42
+ | `ORGANIZATION_PHONE_NUMBER` | 10 |
43
+
44
+ | Outreach LinkedIn action | Credits per action |
45
+ | --- | --- |
46
+ | `linkedinSendMessage` | 5 |
47
+ | `linkedinInvite` | 5 |
48
+ | `linkedinVisit` | 2 |
49
+ | `linkedinLookupProfile` | 2 |
50
+ | `linkedinCancelInvitation` | 1 |
51
+
52
+ Email actions are not charged.
53
+
54
+ | Credits per delivered Signals lead | Watcher definition slugs |
55
+ | --- | --- |
56
+ | 20 | `company-followers`, `company-page-engagement`, `linkedin-reactions`, `competitor-social-reactions`, `influencer-engagement`, `social-mentions`, `dormant-linkedin-poster`, `job-offers`, `republished-job-offers`, `google-business-listing`, `company-registration` |
57
+ | 50 | `job-changes`, `employee-departure`, `department-growth`, `company-growth`, `recruitment-campaign`, `event-attendees`, `tech-adoption`, `tech-displacement`, `ai-adoption`, `public-tenders`, `public-contract-award`, `competitor-customers`, `competitor-customer-care`, `competitor-relationships` |
58
+ | 100 | `fundraising`, `mergers-acquisitions`, `forecasted-funding`, `forecasted-acquisition`, `forecasted-growth`, `forecasted-ipo`, `radar`, `radar-website` |
59
+
60
+ An item missing from these tables has no known price: say so, treat the ceiling as unknown and
61
+ ask before running it. Never invent a price, use raw GraphQL to look one up, or elevate just to
62
+ read billing.
63
+
64
+ When a price cannot be established, report the uncertainty. Do not call an estimate a guaranteed
65
+ maximum or execute paid work against an unknown ceiling. Continue with already available data or
66
+ a no-reveal preview within the user's constraints, and prepare the exact paid command and the
67
+ missing pricing question if needed. A request for "spend no more than X" does not make an unknown
68
+ price safe.
69
+
70
+ For Atlas, calculate conservatively over every possibly new dimension on every selected record:
71
+
72
+ ```text
73
+ maximum customer credits = sum(maximum new units for dimension d × listed price of d)
74
+ calculated customer credits = sum(observed new units for dimension d × listed price of d)
75
+ ```
76
+
77
+ Include dimensions on nested organizations when requested, every page and any separately billed
78
+ action. Do not assume all selected records are owned unless the same company and window have been
79
+ verified. Reduce the ceiling only for ownership established on that basis. Avoid a broad paid search
80
+ that can select more or different people than the approved set.
81
+
82
+ Arithmetic examples at the listed prices:
83
+
84
+ - If identity is 2 credits and email is 40, ten of each cost at most
85
+ `10 × 2 + 10 × 40 = 420` customer credits, for 20 reveal units.
86
+ - If the response records 11 identity units and 8 email units at those rates,
87
+ `11 × 2 + 8 × 40 = 342` customer credits, for 19 reveal units.
88
+
89
+ For Signals, use the current definition's price per delivered lead and the approved caps, time
90
+ window and stop mechanism. A daily cap is not a lifetime budget. For Outreach, use the current rate
91
+ for each action type, including profile lookups. If a backend cap cannot guarantee the monetary
92
+ ceiling or automatic stop, explain that limitation instead of promising a hard limit.
93
+
94
+ ### Offline reveal calculator
95
+
96
+ Use the dependency-free helper bundled next to this reference:
97
+
98
+ ```bash
99
+ node <skill-directory>/scripts/quote-reveals.mjs --input quote.json
100
+ ```
101
+
102
+ `--input -` reads JSON from standard input. Import `quoteReveals(input)` from the same module for
103
+ in-process use. It returns a new object without modifying the input, making network calls, writing
104
+ files, authorizing execution or performing reveals. Output goes to stdout; invalid input produces
105
+ a nonzero exit and a short error without echoing the input. Use opaque IDs, not names or channels.
106
+
107
+ Input is a normalized local manifest, **not a new Atlas API request or endpoint**. Obtain current
108
+ dimension names from the actual CLI schema and supply rates established above. The helper cannot
109
+ verify a source, entitlement, price freshness or an operator's attestation by itself. An old
110
+ `verifiedAt` without an expiry does not prove that a rate is current. Check pricing again when the
111
+ quote will be used; set `validUntil` when the authoritative source provides a validity window.
112
+
113
+ An example manifest at the listed price, which is not an approval:
114
+
115
+ ```json
116
+ {
117
+ "company": "example-company",
118
+ "environment": "production",
119
+ "asOf": "2026-11-10T12:00:00Z",
120
+ "ids": ["contact-1", "contact-2"],
121
+ "dimensions": ["CONTACT_IDENTITY"],
122
+ "tariff": {
123
+ "company": "example-company",
124
+ "environment": "production",
125
+ "verified": true,
126
+ "source": "sortlist-cli price list, 2026-11-10",
127
+ "verifiedAt": "2026-11-10T11:00:00Z",
128
+ "rates": { "CONTACT_IDENTITY": "2" }
129
+ }
130
+ }
131
+ ```
132
+
133
+ Required fields are the exact selected `ids`, exact `dimensions`, payer `company`, `environment`,
134
+ UTC ISO `asOf`, and `tariff`. The tariff must match company/environment, be attested with
135
+ `verified: true`, name its source (an HTTP(S) URL without credentials, or a short label such as
136
+ `sortlist-cli price list, 2026-11-10`) and verification timestamp, and provide every requested
137
+ rate. Optional `tariff.validUntil` must be after `asOf`. The helper rejects future verification
138
+ dates, malformed dates, missing/negative/nonfinite rates, duplicate IDs or dimensions and mixed
139
+ contact/organization dimensions. Quote organizations separately with their own selected IDs,
140
+ including nested organizations when needed; do not treat contact IDs as organization IDs.
141
+ Selected record IDs and observation search/page IDs support opaque base64 characters (`+`, `/`,
142
+ `=`), with no trimming, whitespace or control characters. Company/environment slugs remain strict.
143
+
144
+ Rates are exact decimal strings with up to nine fractional places, or nonnegative safe integer
145
+ numbers. Decimal JSON numbers are rejected: use `"0.1"`, not `0.1`. Credit results are decimal strings,
146
+ calculated using integer arithmetic. Prices are supplied inputs, never product-price constants.
147
+
148
+ Optional `ownership` contains unique records shaped as
149
+ `{ "id": "contact-1", "dimension": "CONTACT_IDENTITY", "status": "OWNED", "company": "example-company", "environment": "production", "ownedUntil": "2026-11-11T12:00:00Z" }`.
150
+ Only a matching payer/environment with an expiry strictly after `asOf` reduces the ceiling.
151
+ Expired, unknown or other-company ownership does not. `LOCKED`, `REVEALED`, `UNAVAILABLE` and
152
+ `FAILED` are accepted statuses but do not establish current ownership. Neither unavailability nor
153
+ a failed lookup guarantees that a future request cannot succeed and incur a new reveal.
154
+
155
+ Optional `observedPages` contains normalized observations with `company`, `environment`,
156
+ `searchId`, stable local `pageId`, `state` (`FILLING` or `COMPLETE`) and a `reveals` array of
157
+ `{ "id": "contact-1", "dimension": "CONTACT_IDENTITY", "status": "REVEALED" }` records.
158
+ These observations must be bound to the same selected IDs, dimensions and payer. Use a stable page
159
+ label within its search, not a credential or raw continuation token. A final snapshot replaces a
160
+ provisional one; replaying the same final page is not counted twice. Conflicting final snapshots,
161
+ duplicate records within a snapshot or a new reveal contradicting proven ownership are rejected
162
+ for reconciliation. Distinct selected record/dimension pairs are counted once across pages;
163
+ `repeatedObservedPairs` exposes overlap across distinct pages for investigation. This arithmetic
164
+ does not certify that repeated calls could never have produced additional billing transactions.
165
+
166
+ Output includes the exact selection, `byDimension`, `maximumNewUnits`, weighted
167
+ `maximumCustomerCredits`, and, when observations are supplied, `observedNewUnits` and
168
+ `calculatedCustomerCredits`. No observations means the observed figures are `null`, not zero.
169
+ `allObservedPagesComplete` describes only supplied pages, not completion of all pagination or the
170
+ market. `observedSpendProvisional: true` explicitly marks calculations containing `FILLING` pages
171
+ as provisional, not settled spend. `authoritativeLedgerDebit` is always `null` and
172
+ `executionAuthorized` is always `false`: the helper neither reads a ledger nor grants permission.
173
+ The ceiling covers only these selected reveal dimensions, not separately billed provider work,
174
+ Signals leads or Outreach actions. Apply the verified charging contract to any additional costs.
175
+
176
+ Only allowlisted metadata is returned. Contact fields, credentials and extra fields are omitted;
177
+ source URL credentials are rejected and source query strings/fragments are omitted. Supply a stable
178
+ documentation URL or the price list label, without secrets. Do not persist this manifest or its output outside the approved
179
+ workspace. After a bounded approval, recheck its selection, dimensions, payer, current prices,
180
+ ownership and remaining budget before each lot without asking again for each page.
181
+
182
+ ## Provider work and no-reveal searches
183
+
184
+ Atlas can search external providers to fill a contact page, identify a missing person, or refresh
185
+ an organization selected by exact domain. Email/phone reveals can trigger missing-value lookups.
186
+ No-reveal searches request no new reveal dimensions; they do not guarantee zero upstream cost.
187
+ Do not label a run "stock only", "no provider calls" or "zero total cost" without an exposed,
188
+ verified server mode that enforces it. An organization `domain.in` database filter does not prove
189
+ that all other commands in a workflow avoid providers.
190
+
191
+ Ordinary no-reveal sourcing is within a user's search request; do not require a new technical
192
+ approval merely because Sortlist may pay a provider internally. If the user explicitly forbids
193
+ all provider calls or all costs, keep that stronger boundary. Use already captured artifacts or a
194
+ verified no-provider mode; otherwise explain why a live search cannot satisfy it.
195
+
196
+ ## What approval must cover
197
+
198
+ An existing explicit instruction can authorize a concrete action. Do not ask again merely because
199
+ this reference was loaded or a call is part of an already approved bounded plan. When the task lacks
200
+ necessary authorization, prepare a reviewable command or plan before asking. Use the host's question
201
+ tool if it supports the decision; otherwise ask in prose and wait. Do not require unsupported
202
+ `preview` or multi-select fields from a particular host.
203
+
204
+ A paid-call proposal names:
205
+
206
+ - The selected records or a precise selection rule, the exact dimensions/actions and the acting company.
207
+ - The verified maximum customer credits and its pricing source/date; state any remaining uncertainty.
208
+ - The command or plan to execute, plus useful cheaper alternatives and an option to keep existing data.
209
+ - For ongoing work, the duration, lead/action caps, total spending limit, owner of the stop and the
210
+ mechanism that actually triggers it. Do not imply that a chat alone runs a timer.
211
+
212
+ For a reveal quote, explain the ceiling in ordinary customer language: already-owned data is
213
+ excluded from new units while ownership is valid, and unavailable or failed dimensions do not
214
+ produce successful reveal units. The actual consumption can therefore be below the ceiling;
215
+ the quote is not a completed debit or a promise that every requested field will be available.
216
+ Keep this explanation brief rather than making the customer interpret internal status codes.
217
+
218
+ A bounded approval can cover several calls, pages or retries only when its scope and budget cover
219
+ them and retrying cannot duplicate an accepted effect. Do not treat a timeout as failure: reconcile
220
+ the accepted request first. Another person, reveal dimension, channel, message step, higher ceiling
221
+ or longer duration requires a new decision. A lower actual cost due to ownership does not.
222
+
223
+ Writes outside an existing specific authorization require a reviewable proposal too. For irreversible
224
+ or high-impact changes, name the effect: delete a company/application, remove a member, revoke a
225
+ credential, change/cancel a subscription. A general sourcing or campaign request does not authorize
226
+ those administrative changes. Account connections and messages require the intended owner's or
227
+ sender's authorization. Specific Hermes effects are in
228
+ [identity-and-accounts.md](identity-and-accounts.md).
229
+
230
+ ## Report observed spend without overclaiming
231
+
232
+ Use page reports for reveal units and per-dimension counts. Repeated `FILLING`/`COMPLETE` snapshots,
233
+ replayed subscriptions and rereads are not independent spend records; do not add them together.
234
+ Keep distinct search/page identity and use the final report when available. A partial response
235
+ does not prove final accounting.
236
+
237
+ Prefer an authoritative billing debit when the CLI exposes it. Otherwise label the weighted result
238
+ as calculated from the named rate, not as a verified ledger debit. A before/after company balance
239
+ can include other concurrent activity; do not attribute its whole change to this task. No readable
240
+ ledger means final account debit is unverified, not zero.
241
+
242
+ At the listed prices, a truthful report is:
243
+
244
+ ```text
245
+ Atlas: 19 new reveal units (11 identity, 8 email), company acme.
246
+ Calculated debit: 342 customer credits at the quoted rates; final ledger debit unverified.
247
+ 6 records already owned; 3 emails unavailable. Ownership dates: use returned ownedUntil values.
248
+ ```
249
+
250
+ For a preview, say "0 reveal units observed" when the returned reports show zero. State zero
251
+ customer credits only when the current charging contract or billing evidence supports that claim;
252
+ never convert this into a claim of zero provider cost. Do not turn credits into money without an
253
+ applicable verified monetary rate.
@@ -0,0 +1,118 @@
1
+ # Identity, permissions and Hermes accounts
2
+
3
+ Read for login/elevation, application identity, company administration, invitations, credentials
4
+ and subscriptions. Inspect command help and actual operations before constructing a call.
5
+
6
+ ## Login and elevation
7
+
8
+ Use `sl login --no-browser` in a background process, give the user the verification URL and code
9
+ it prints, then continue when the command confirms completion. The owner approves in their own
10
+ browser; do not request their password, token or cookies, and do not ask them to run a command the
11
+ agent can run. `sl logout --no-browser` clears local credentials without opening the sign-out page.
12
+ `sl logout --elevated` drops only an elevation. Avoid logging out a working session unnecessarily.
13
+
14
+ Read `sl login --help` for the permission options actually available. Requested scopes are not
15
+ guaranteed grants. The account must hold a permission; requesting it cannot grant it. Check `sl whoami`
16
+ and `sl operations`. An account without Signals/Outreach rights can still have an Atlas sourcing
17
+ workflow. Do not turn missing internal permissions into a promise that an external customer can
18
+ obtain an elevation. Do not request broad write access for ordinary reads. Elevate only for a
19
+ user-requested action that requires it, with the owner's authorization. Prefer the least access
20
+ that covers the task and offer to drop a temporary elevation after it is done. Honor its reported
21
+ expiry rather than assuming it refreshes. Refresh the schema after a changed login if discovery is stale.
22
+
23
+ ## Application identity
24
+
25
+ An application acts for its own company and has no user scopes by default. Reveals are charged to
26
+ that company and attributed to the application when usage reporting supports it. Atlas's metered
27
+ find operations support application workflows. The CLI itself does not guarantee access to every
28
+ other service; verify with the actual token. In particular, do not assume Mercator is available
29
+ because an application can search Atlas, or Signals/Outreach because their commands exist for a user.
30
+ Hermes management refuses application tokens: use the person's identity for management.
31
+
32
+ Act as an application only for an application task the user requested:
33
+
34
+ ```bash
35
+ sl hermes applications --fields name,slug,company.slug
36
+ sl use application <company>/<application-slug>
37
+ sl whoami
38
+ sl use me
39
+ ```
40
+
41
+ The company-qualified slug avoids ambiguity across companies. An application ID also works.
42
+ `sl use application` creates and immediately revokes a temporary session credential after exchanging
43
+ it; the stored bearer token lasts about one token lifetime and is not refreshed. Repeating the
44
+ command obtains another lifetime. It changes shared CLI identity, so restore the previous identity
45
+ after a temporary switch and tell the user. `sl use me` clears an application session, but an identity
46
+ provided by `SORTLIST_CLIENT_ID`/`SORTLIST_CLIENT_SECRET` remains active until those variables are
47
+ unset. Do not print or modify credential variables to diagnose them.
48
+
49
+ If managing while an application session is active, switch to the person, perform only the
50
+ authorized management work, and restore the requested application context afterward if needed.
51
+ Never create a permanent application credential merely to read ordinary user data.
52
+
53
+ ## Company context and billing reads
54
+
55
+ `sl whoami` reports the effective caller, company and, when readable, billing. `sl use company`
56
+ without an argument lists membership, current/personal markers, and billing. Missing billing is
57
+ unknown, not proof of a zero balance or no plan. Inspect output before asserting who paid; the
58
+ current session cannot establish the payer for a historical call made under another context.
59
+
60
+ Use per-call `--company <slug|id>` for the task rather than persistent selection. `sl use company
61
+ --personal` clears a saved company selection. Elevation does not change company precedence.
62
+
63
+ Example reads, subject to the caller's membership and current schema:
64
+
65
+ ```bash
66
+ sl hermes company --slug <slug> --fields id,slug,billingCustomer.creditBalance
67
+ sl hermes company --slug <slug> --fields billingCustomer.activeSubscription.plan
68
+ sl hermes application --id <application-id> --fields credentials.id,credentials.name
69
+ ```
70
+
71
+ A plan or balance is not a unit price. Use [billing-and-permissions.md](billing-and-permissions.md)
72
+ for quotes, bounded authorization and reports. Billing ledger or reveal history may have no exposed
73
+ CLI command; discover rather than invent one, then state the visibility limit.
74
+
75
+ ## Hermes operations and effects
76
+
77
+ `sl operations --search hermes` is the current command inventory. Typical areas are company reads,
78
+ members and invitations; applications and their credentials; and subscription/portal management.
79
+ Legacy top-level Hermes aliases may work but prefer grouped `sl hermes ...` names.
80
+
81
+ Read help, prepare the exact change and obtain any authorization missing from the user's request:
82
+
83
+ | Operation | Effect to surface before execution |
84
+ | --- | --- |
85
+ | `create-company`, `delete-company` | Creates or deletes a company; deletion is high impact and cannot be treated as cleanup of a search. |
86
+ | `create-application`, `delete-application` | Registers or removes an application. Confirm the exact company/application. |
87
+ | `create-company-invitation` | The code grants the redeemer the company's documented membership powers, including application/credential management. Confirm the intended recipient. |
88
+ | `accept-company-invitation` | Joins another company and consumes a code. Read `company-invitation-preview` first; never consume a code meant for someone else. |
89
+ | `revoke-company-invitation` | Revokes an invitation; confirm the target. |
90
+ | `remove-company-member` | Removes membership and can revoke credentials the member created; explain the current documented effect. |
91
+ | `create-application-credential` | Produces a client ID and a secret shown once. |
92
+ | `revoke-application-credential` | Prevents new tokens from that credential; do not promise already-issued tokens disappear unless the server documents it. |
93
+ | `change-company-subscription` | Can immediately charge a prorated upgrade; verify the current quote and effect. |
94
+ | `cancel-company-subscription` | Can end access immediately and forfeit the remaining period; verify the current effect. |
95
+ | `create-company-billing-portal-session` | Returns a billing management URL for the user to open themselves. |
96
+
97
+ Never disclose invitation codes beyond the intended user. Return a newly created secret only to
98
+ the authorized user for storage and never place it in a file, shared log or later repeat. Record
99
+ non-secret credential IDs for management instead. `sl token` prints a bearer token; do not echo
100
+ it to the conversation, write it to a file or pass it to another client. If subscribing has no
101
+ CLI command, give the relevant portal path without creating a substitute API call.
102
+
103
+ ## Environment and reproducibility
104
+
105
+ Configuration is shared with the user's terminal. Inspect the existing endpoint before changing
106
+ anything, preserve temporary context and report its restoration. Source/dev builds expose
107
+ `sl config use-local`, `use-staging`, `use-production`; installed builds may not. Never assume these
108
+ commands exist or fall back to rewriting configuration files by hand. `--endpoint` is advertised
109
+ by root help, but endpoint override alone does not reconfigure the separate token endpoint; verify
110
+ the authentication environment too. An application token request can otherwise target the wrong
111
+ Hermes endpoint.
112
+
113
+ For an audit or reproducible demo, record the CLI version, skill revision/source, endpoint and
114
+ schema refresh time without secrets. The published CLI can auto-update minor/patch versions;
115
+ installed skills are copies and may lag the package. Do not invent a no-update flag or claim a
116
+ frozen run without an actually supported mechanism. A test's strict no-network rule also applies
117
+ to discovery: CLI startup can introspect the endpoint and check npm, so inspect provided artifacts
118
+ or source instead of running a nominally local command in that situation.