@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.
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/skills/sortlist-cli/SKILL.md +139 -561
- package/skills/sortlist-cli/references/atlas.md +197 -0
- package/skills/sortlist-cli/references/billing-and-permissions.md +253 -0
- package/skills/sortlist-cli/references/identity-and-accounts.md +118 -0
- package/skills/sortlist-cli/references/outreach.md +126 -0
- package/skills/sortlist-cli/references/signals.md +104 -0
- package/skills/sortlist-cli/scripts/quote-reveals.mjs +182 -0
- package/skills/sortlist-go-to-market/SKILL.md +73 -233
- package/skills/sortlist-go-to-market/references/agency-briefing.md +22 -0
- package/skills/sortlist-go-to-market/references/campaigns.md +114 -0
- package/skills/sortlist-go-to-market/references/context-and-brief.md +92 -0
- package/skills/sortlist-go-to-market/references/prospect-list.md +115 -0
- package/skills/sortlist-go-to-market/references/search-state.md +87 -0
- package/skills/sortlist-go-to-market/references/sourcing.md +194 -0
- package/skills/sortlist-go-to-market/scripts/render-prospect-list.mjs +157 -0
|
@@ -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.
|