@sortlist/cli 0.65.0 → 0.66.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/README.md CHANGED
@@ -55,6 +55,24 @@ A skill already installed and identical is left alone; one that differs is refus
55
55
  session afterwards: skills are read when a session starts. Then describe your business ("I sell X to
56
56
  Y, find me customers"), or type `/sortlist-go-to-market`.
57
57
 
58
+ ## Use Sortlist from an MCP client
59
+
60
+ An MCP client reaches the same operations without `sl` through the Sortlist connector, a remote MCP
61
+ server at `https://mcp.sortlist.com/mcp`. Add that URL as a remote (Streamable HTTP) server in your
62
+ client.
63
+
64
+ The client then asks you to sign in with your Sortlist account, and every call acts as you, for your
65
+ personal company unless it names another one with `company`, as with `sl`.
66
+
67
+ - Finds are free. A find still filling after about three minutes hands back a reference, which
68
+ `atlas_find_result` reads once the search is done, without searching again.
69
+ - Paid tools end in `_reveal` and take `maxCredits`, the most the call may charge: a call that would
70
+ charge more is refused before anything is spent. Confirm a paid tool call before your client runs it.
71
+ - The tools follow your account's scopes: Signals and Outreach appear only when your account holds
72
+ their scopes.
73
+ - A LinkedIn account is connected through the link `outreach_authenticate_outbound_channel_account`
74
+ returns: open it in your browser and sign in to LinkedIn there.
75
+
58
76
  ## Companies and credits
59
77
 
60
78
  Everything you reveal, every lead a watcher delivers and every LinkedIn action is charged to the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sortlist/cli",
3
- "version": "0.65.0",
3
+ "version": "0.66.0",
4
4
  "description": "Sortlist platform CLI — GraphQL federation client",
5
5
  "repository": {
6
6
  "type": "git",
@@ -110,6 +110,9 @@ missing first page.
110
110
 
111
111
  ## Costs and permission
112
112
 
113
+ The same rules apply when the Sortlist connector (`https://mcp.sortlist.com/mcp`) runs the call
114
+ instead of `sl`: its `_reveal` tools take `maxCredits` as the approved ceiling.
115
+
113
116
  Read [billing-and-permissions.md](references/billing-and-permissions.md) before quoting a paid
114
117
  operation, revealing data, changing billing, or reporting spend. Three quantities differ:
115
118
 
@@ -143,6 +146,10 @@ units separately from verified or estimated billing credits and mark incomplete
143
146
  scheduler. A plan for a future action is not evidence that it is scheduled.
144
147
  - For Hermes company membership, invitations, applications, credentials and subscriptions, read
145
148
  [identity-and-accounts.md](references/identity-and-accounts.md). Keep secrets out of files and logs.
149
+ - When credits or a verified plan limit affect the task, or the user asks about referrals or a useful
150
+ handoff, read [value and growth](references/value-and-growth.md). Preserve the work, offer a relevant
151
+ available way forward and retain the user's choice. A referral reward needs an actual program;
152
+ company access and email access do not authorize inviting outside friends.
146
153
 
147
154
  ## Errors
148
155
 
@@ -153,7 +160,7 @@ units separately from verified or estimated billing credits and mark incomplete
153
160
  | Company/token refused (exit 4) | Verify caller, membership and intended `--company`; do not retry against another payer silently. |
154
161
  | `INVALID_INTERACTION`, expired `after` | The previous search cannot be paginated; consider a new search explicitly within scope and budget. |
155
162
  | Subscription timeout or still filling (exit 5) | Preserve context and use the recovery rules above. |
156
- | `INSUFFICIENT_CREDITS` | Stop paid work, report the payer and balance if readable, and revise scope or funding with the user. |
163
+ | `INSUFFICIENT_CREDITS` | Stop paid work, preserve the selection, report the payer and readable shortfall, and use the value-and-growth guidance for a useful scope or funding choice. |
157
164
  | Endpoint unreachable (exit 3) | Check endpoint and connectivity; do not switch environments to make an error disappear. |
158
165
 
159
166
  Exit 1 covers GraphQL or business errors. `SL_DEBUG=1` prints queries, variables and responses;
@@ -50,6 +50,11 @@ a no-reveal preview within the user's constraints, and prepare the exact paid co
50
50
  missing pricing question if needed. A request for "spend no more than X" does not make an unknown
51
51
  price safe.
52
52
 
53
+ If the next scoped lot exceeds the readable balance or a verified plan limit, preserve the work and
54
+ use [value and growth](value-and-growth.md) to offer a useful smaller scope or an actually available
55
+ funding route. Pending referral rewards are not spendable balance; a credit shortfall is not
56
+ permission to send invitations, buy credits or change a subscription.
57
+
53
58
  For Atlas, calculate conservatively over every possibly new dimension on every selected record:
54
59
 
55
60
  ```text
@@ -94,6 +94,13 @@ Read help, prepare the exact change and obtain any authorization missing from th
94
94
  | `cancel-company-subscription` | Can end access immediately and forfeit the remaining period; verify the current effect. |
95
95
  | `create-company-billing-portal-session` | Returns a billing management URL for the user to open themselves. |
96
96
 
97
+ Company invitations are access grants, not a referral or credit-reward mechanism. For a requested
98
+ collaboration, ensure the available access fits the intended recipient; an email label may not bind
99
+ the invitation to that address, and a created code is not proof of an email sent. Use
100
+ [value and growth](value-and-growth.md) for an actual referral program or a private handoff that
101
+ does not require broader membership. A billing portal link does not establish an available checkout
102
+ or top-up; discover its actual capabilities before offering one.
103
+
97
104
  Never disclose invitation codes beyond the intended user. Return a newly created secret only to
98
105
  the authorized user for storage and never place it in a file, shared log or later repeat. Record
99
106
  non-secret credential IDs for management instead. `sl token` prints a bearer token; do not echo
@@ -0,0 +1,163 @@
1
+ # Help the customer get more value
2
+
3
+ Read when an observed credit or plan limit affects the task, the user asks about plans or referrals,
4
+ or their requested handoff or recurring work creates a useful collaboration or return path.
5
+ Ordinary searches and refinements need no commercial suggestion. Deliver the useful result first;
6
+ when a limit intervenes, preserve the work and explain the smallest decision that unlocks progress.
7
+
8
+ ## Choose a helpful moment
9
+
10
+ Use the customer's next objective and observed account state, rather than a generic sales prompt.
11
+ Keep technical checks behind the conversation. Match the customer's language.
12
+
13
+ | Observed moment | Useful action | Growth opportunity, when supported |
14
+ | --- | --- | --- |
15
+ | The next approved lot costs more than the readable balance | Save the selection and quote. Show the balance, cost and shortfall; reuse owned data or offer a useful smaller lot. | Offer an eligible referral program or a verified funding route if it solves the timing and shortfall. |
16
+ | A first usable result is ready and the user has named a colleague who should act on it | Prepare a private, concise handoff explaining the selection, reasons and next action. | Offer the appropriate collaboration access only if it fits that person's role. An external example can use a reusable method or synthetic data instead. |
17
+ | The user wants the same job again | Retain a reusable brief and exclusions in supported task state; give a short way to resume. | A requested recurring flow may justify an available watcher or plan, with its actual caps and cost. Saving a recipe does not start monitoring. |
18
+ | A verified plan limit repeatedly prevents the requested volume or feature | Compare the current plan with the smallest available option that covers the observed need. | Explain the incremental benefit and total price; a top-up or smaller run may fit better than a new subscription. |
19
+ | The user asks to recommend the product or earn credits | Read the actual referral terms and eligibility, then prepare a useful invitation for people the user chooses. | Give the returned referral link and track supported outcomes, rather than asking the user to describe the program. |
20
+ | The user comes back with a prior list or unfinished task | Reuse the brief, selection, owned fields and last decision. | Resume toward the next useful outcome without repeating onboarding, repurchasing data or repeating a declined offer. |
21
+
22
+ A small balance alone is not an urgent limit. Compare it with the next scoped quote; if it covers
23
+ the task, continue. Missing balance is unknown, not zero. An access or scope error is not evidence
24
+ that buying a plan grants permission. Use [billing](billing-and-permissions.md) and
25
+ [identity](identity-and-accounts.md) for actual reads, prices and permissions.
26
+ Keep credits and offers scoped to the actual company, environment and product; do not assume
27
+ credits transfer between products. Respect the returned balance contract: a balance already net
28
+ of open reservations must not have those reservations subtracted again.
29
+
30
+ Offer at most one relevant commercial suggestion per task, alongside an honest way to continue
31
+ with existing data, reduce scope or stop. Answer explicit follow-up questions normally. Keep a
32
+ declined suggestion suppressed for the same objective until the user asks or material facts change;
33
+ another page or a new chat is not by itself a reason to repeat it. Reuse a supplied preference for
34
+ no upgrade or referral suggestions. A technical error or poor result calls for a fix, not a pitch.
35
+ If no relevant, available option improves the outcome, leave the suggestion out.
36
+
37
+ ## Credit recovery without losing momentum
38
+
39
+ Keep the result already earned usable. Give the customer a simple choice with concrete consequences,
40
+ for example: "Your list is saved. The next step needs 80 credits; you have 60. We can unlock a useful
41
+ smaller group now or keep the full selection ready for later." These numbers are illustrative;
42
+ use the actual selection, ownership, price and balance before making such a claim. Do not spend
43
+ or alter the selected records to fit a budget without an existing authorization covering that change.
44
+
45
+ When a referral offer is actually available, relate it to the job: "This program awards credits
46
+ after an eligible friend completes the stated step. It can help with a later batch; it will not
47
+ unlock today's batch immediately." Only say this if the program's actual timing supports it.
48
+ Show the reward and condition plainly. Never suggest that sending an invitation itself refills a
49
+ balance unless that is the verified rule, or count pending rewards as spendable credits.
50
+
51
+ For an available plan or credit purchase, compare the right unit: one-off versus recurring need,
52
+ credits required, included allowance, renewal, expiry, immediate/prorated charge and cancellation
53
+ effect where relevant. Use returned catalog/quote information or official terms actually available
54
+ to the user. Do not invent a top-up, discount, trial, checkout URL or monetary conversion from the
55
+ unit-price table. A billing portal may manage cards and invoices without supporting a purchase.
56
+ If the needed commercial route is unavailable, retain the work and explain that specific limit.
57
+ Check a readable upcoming renewal or already scheduled plan change before proposing another change;
58
+ an expected future allowance is not credit available now.
59
+
60
+ ## Referral is separate from company access
61
+
62
+ Check discovery and available first-party program information before offering a reward. Establish:
63
+
64
+ - The active program and this account's eligibility, including whether existing users qualify.
65
+ - Who receives which reward, in what units, and the qualifying action, delay, caps and expiry.
66
+ - The official referral link or supported invitation action and the new user's intended destination.
67
+ - Which status and reward records the available tools can actually read.
68
+
69
+ If the program or essential terms cannot be verified, omit the reward offer and use an available
70
+ alternative. Do not invent `sl referral` commands or make the customer supply a nonexistent tariff
71
+ or program. A user-requested recommendation can still have a prepared message without a reward claim.
72
+ Do not substitute an administrative credit grant for a referral program.
73
+
74
+ An invitation to join the paying company is **not** a referral. Company membership can grant
75
+ application and credential management access. The invitation email may be a label rather than an
76
+ enforced recipient restriction, and creating a code does not prove email delivery. Never use
77
+ `create-company-invitation` to invite outside friends for credits. For a requested teammate,
78
+ verify the intended company, recipient and access effect through the
79
+ [membership workflow](identity-and-accounts.md#hermes-operations-and-effects). If the available role
80
+ is broader than the requested collaboration, offer a private handoff instead of granting that access.
81
+
82
+ Having email access or Atlas contact details is not permission to recruit those people. Use people
83
+ the user names or a recipient-selection task they explicitly request. Do not mine an inbox, address
84
+ book or prospect list to build a referral audience. Prepare recipient, sender, channel, destination
85
+ and exact message before any missing sending authorization. Reuse an existing specific approval;
86
+ a generic desire for more credits does not authorize sending. Keep the choice personal and useful,
87
+ with no automatic follow-up sequence or claimed mutual relationship.
88
+
89
+ Make the invitation useful to the recipient: one relevant outcome they can try and the genuine
90
+ referral benefit, if any. Share the reusable method or synthetic example, not the inviter's private
91
+ prospects, customer context or paid data. Keep the account invitation or referral link out of a
92
+ public export unless the user has specifically chosen that publication.
93
+
94
+ ## Track the outcome that actually happened
95
+
96
+ Use existing authorized task state for conversational continuity. If durable state is unavailable,
97
+ use the current conversation and disclose that limit when it matters. Do not create an analytics
98
+ endpoint, external upload, tracking pixel, scheduled poll or hidden follow-up. Product telemetry
99
+ requires an existing documented collection mechanism; a skill instruction does not implement one.
100
+ When saving a reusable brief, return a supported private attachment/link or a short copyable recipe
101
+ so the customer can take it to another chat. Explain when resumption needs that artifact; a saved
102
+ local file alone is not evidence that a different chat can retrieve it automatically.
103
+
104
+ A small local record can retain the acting company/environment, objective key, moment, offer kind,
105
+ terms reference/date, last decision and time, plus non-secret invitation/referral/subscription IDs
106
+ when returned. Reuse these IDs for deduplication and reconciliation after an uncertain response.
107
+ Store the next useful action and its scope so a return does not restart onboarding. Keep recipient
108
+ addresses in the authorized send workflow rather than copying them into analytics. Never store
109
+ invitation codes, signed access URLs, credentials or raw inbox/prospect content in growth state.
110
+
111
+ Distinguish events and the evidence needed for each; these are event concepts, not API field names:
112
+
113
+ | Stage | Evidence |
114
+ | --- | --- |
115
+ | Relevant suggestion shown | The host actually rendered the offer, tied to a real task moment. |
116
+ | Accepted, declined or dismissed | The customer's actual choice; a question left unanswered is pending. |
117
+ | Invitation/link prepared, created or delivered | The respective draft, creation response or delivery confirmation. These are separate outcomes. |
118
+ | Recipient joined | A readable acceptance/membership event, not the existence of a code or a sent email. |
119
+ | Referred user activated | The program's qualifying action recorded by its authoritative service, not a guessed link click. |
120
+ | Reward credited | A program reward/transaction record tied to the referral and beneficiary. A balance increase alone cannot attribute it. |
121
+ | Plan changed | The confirmed resulting subscription, including its effective date. A checkout link or intent is not a purchase. |
122
+
123
+ Deduplicate by returned event or conversion ID within its program, company and environment; one
124
+ referral can qualify, activate and pay a reward without becoming three new users. Without a readable
125
+ event source, report the later stage as unknown, not zero or successful. Reconcile an uncertain send
126
+ or accepted write before retrying; do not create another invitation merely to refresh its status.
127
+ Check supported status when the user asks or the task legitimately resumes, not in an invented
128
+ background monitor. Report a pending reward and a spendable reward separately.
129
+
130
+ For product measurement, separate eligible moments, suggestions shown, choices, delivered invites,
131
+ new-user activations, verified rewards and confirmed plan changes. Compare completion of the original
132
+ customer task and declines as well as conversions; an invitation count alone does not prove growth.
133
+ Never fabricate time saved, revenue, conversion uplift or attribution from a conversation transcript.
134
+
135
+ ## Keep the conversation light
136
+
137
+ Use a useful result followed by one short, optional, contextual question when a choice is needed.
138
+ Use the host's question tool when suitable, with the real costs and consequences from the available
139
+ evidence. Avoid a menu of products after every answer, manufactured urgency or a promotional
140
+ watermark in a private deliverable. Lead with the feasible action, not a diagnostic checklist.
141
+ In the main reply, give the result, the next-step cost/shortfall if relevant and one useful choice.
142
+ Keep accounting internals and the full discovery record in supporting detail. For a referral, show
143
+ the reward, qualifying action and timing, with material limits accessible through its official
144
+ terms or a supported details view before the customer commits. Do not turn every eligibility check
145
+ into a separate paragraph. When an option is unavailable, explain it once and keep the useful draft
146
+ or saved result prominent; do not repeat every action that did not happen.
147
+
148
+ For example, using illustrative figures only: "Ta sélection est prête. Il manque 20 crédits pour
149
+ les 40 noms, ou on peut commencer par 30. Ton parrainage éligible peut aussi apporter 120 crédits
150
+ après la première recherche d'un nouvel utilisateur, sous 24 heures. Je peux préparer le message
151
+ pour une personne de ton choix." Include the actual terms link and costs in the supported decision
152
+ view; preparing that message does not send it. Do not copy these figures into a real quote.
153
+
154
+ Other examples to adapt, only when their prerequisites hold:
155
+
156
+ - **First result and named handoff:** "The shortlist is ready, with a reason for each priority. I can
157
+ prepare a private summary for the colleague you mentioned." Preparing it does not send it.
158
+ - **Recurring job:** "Your criteria and exclusions are saved here. Next time, say 'continue this list'."
159
+ Say this only after the host has actually retained them; it is not an automatic refresh promise.
160
+ - **Right-sized plan:** "At your stated monthly volume, this available option covers the gap for the
161
+ quoted recurring price. For this one job, keeping the smaller batch is also sufficient."
162
+ - **Verified referral:** "You can earn the stated credits when an eligible friend completes the
163
+ program's qualifying step. I can prepare a short invitation for someone you choose."
@@ -75,3 +75,9 @@ Lead with useful results, with detail and evidence available in the deliverable.
75
75
  coverage gaps in ordinary language. Report costs and any running watchers or pending actions only
76
76
  when relevant and supported by the actual responses. A small preview is an intermediate result when
77
77
  the user asked for a substantial prospect list, not completion of that request.
78
+
79
+ When a real credit/plan limit intervenes, or a requested handoff, recurring job or referral creates
80
+ a useful next step, read [value and growth](../sortlist-cli/references/value-and-growth.md).
81
+ Help the customer preserve and reuse their result, collaborate with the intended person or choose
82
+ an available plan that fits their need. Ordinary delivery needs no promotional ending; honor a
83
+ declined offer and keep referrals separate from company membership and prospect outreach.