@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 +18 -0
- package/package.json +1 -1
- package/skills/sortlist-cli/SKILL.md +8 -1
- package/skills/sortlist-cli/references/billing-and-permissions.md +5 -0
- package/skills/sortlist-cli/references/identity-and-accounts.md +7 -0
- package/skills/sortlist-cli/references/value-and-growth.md +163 -0
- package/skills/sortlist-go-to-market/SKILL.md +6 -0
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
|
@@ -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
|
|
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.
|