@sprid/cli 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 0.1.9 - 2026-09-25
+
+- `sprid connect github --repo owner/repo` connects GitHub repository traffic
+  (views, clones, referrers) to an app, so Sprid keeps the history past
+  GitHub's 14 days. Repeat `--repo` or separate with commas.
+- Telemetry now includes an anonymous daily install ping: a random id made on
+  this machine, the surface the skills came through, versions, OS, CI and
+  whether a login exists. No token, account or workspace. The notice is shown
+  again before the first ping; `sprid telemetry off` and `DO_NOT_TRACK=1` stop it.
+
+- `sprid doctor --plugin <skills-root>` also checks the installed Sprid skills
+  against the latest pushed release and prints the update command for the host
+  that installed them (Claude Code, Codex or a skills folder). With
+  `sprid update --auto on`, `--apply-updates` runs that update too.
+- `sprid doctor --json` reports `autoDecided`: whether anyone has answered
+  `--auto on|off` for this installation, so an agent asks once.
+
+## 0.1.8 - 2026-09-25
+
+- `sprid screenshots` draws a device that looks like one: a metal band with side
+  buttons, a thin bezel, and the camera each platform has. `frameImages` in the
+  config swaps in device artwork you hold a licence for (`@sprid/shots` 0.1.2).
+
 ## 0.1.7 - 2026-09-24
 
 - `sprid connect meta-ads --account <slug>` connects the Meta ad account Sprid

package/README.md

@@ -227,6 +227,14 @@ and a failure is ignored. Turn it off with `sprid telemetry off` (saved in
 `~/.sprid/telemetry.json`), or for one shell with `DO_NOT_TRACK=1` or
 `SPRID_TELEMETRY=0`; `help`, `version`, `completion` and `mcp` never send.
 
+Install ping: once a day per surface, signed in or not, one anonymous request to
+`POST /api/installs/ping` carrying a random id created in `~/.sprid/telemetry.json`,
+the surface (`cli`, or `claude`, `codex` or `skills` when `sprid doctor --plugin`
+reports how the skills were installed), the CLI and skills versions, the OS and
+Node versions, whether `CI` is set and whether a login exists. No token, account
+or workspace. It is how an install that never signs in is counted. Same notice,
+same switches.
+
 Credentials stay out of normal output. Build tools can print their own logs; do
 not include secrets in custom build commands.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprid/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "The Sprid command line: connect your app, review results, prepare posts and store screenshots, and release mobile apps.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -38,7 +38,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@sprid/shots": "0.1.1",
+    "@sprid/shots": "0.1.2",
     "@sprid/release": "0.1.2"
   },
   "publishConfig": {

package/src/args.mjs

@@ -9,6 +9,7 @@ export const VALUE_FLAGS = new Set([
   'id', 'request-id',
   "api",
   "auto",
+  "plugin",
   "file",
   "task",
   "payload",

package/src/commands/connect.mjs

@@ -60,6 +60,9 @@ export const SENSOR_SERVICES = [
   "lemonsqueezy",
   "paddle",
   "cloudflare",
+  // Repository traffic: views, clones, referrers. GitHub keeps 14 days; Sprid
+  // copies it daily so the history survives.
+  "github",
 ];
 /** Model / generation keys held per WORKSPACE (BYOK), not per App Profile. */
 export const PROVIDERS = ["anthropic", "openai", "fal", "google", "replicate"];
@@ -79,6 +82,7 @@ export const SENSOR_KEYS = {
   lemonsqueezy: ["lemonSqueezyApiKey"],
   paddle: ["paddleApiKey"],
   cloudflare: ["cloudflareApiToken"],
+  github: ["githubToken"],
 };
 
 const SENSOR_LABEL = {
@@ -95,6 +99,7 @@ const SENSOR_LABEL = {
   lemonsqueezy: "Lemon Squeezy",
   paddle: "Paddle",
   cloudflare: "Cloudflare",
+  github: "GitHub",
 };
 
 const PENDING_POLL_MS = 3000;
@@ -423,6 +428,17 @@ export function sensorPatch(service, flags, cwd, pasted) {
     }
     case "cloudflare":
       return { cloudflareZoneId: need("zone"), secrets: { cloudflareApiToken: secret("token") } };
+    case "github": {
+      // `--repo a/b,c/d` (or the flag repeated). The list REPLACES the one on
+      // the profile, so name every repo. A pasted github.com URL is accepted;
+      // the server normalises and validates each entry again.
+      const raw = [flags.repo].flat().filter((v) => v && v !== true).flatMap((v) => String(v).split(","));
+      const repos = raw.map((r) => r.trim()).filter(Boolean);
+      if (!repos.length) throw new UsageError("sprid connect github needs --repo owner/repo (comma-separate several)");
+      const bad = repos.find((r) => !/^(?:(?:https?:\/\/)?(?:www\.)?github\.com\/)?[A-Za-z0-9-]+\/[A-Za-z0-9._-]+(?:\.git)?\/?$/.test(r));
+      if (bad) throw new UsageError(`--repo takes owner/repo, not "${bad}".`);
+      return { githubRepos: repos, secrets: { githubToken: secret("key") } };
+    }
     default:
       throw new UsageError(`Unknown key type "${service}"`);
   }

package/src/commands/update.mjs

@@ -1,11 +1,12 @@
-import { checkVersion, detectInstallation, autoEnabled, setAuto, performUpdate, installationCommand } from '../updates.mjs';
+import { checkVersion, detectInstallation, autoEnabled, autoDecided, setAuto, performUpdate, installationCommand } from '../updates.mjs';
 import { UsageError } from '../args.mjs';
+import { checkPlugin, updatePlugin } from '../plugin-updates.mjs';
 
 function validate(ctx, allowed) {
   if (ctx.positionals.length) throw new UsageError('Unexpected argument. Use sprid help for update syntax.');
   for (const [key, value] of Object.entries(ctx.flags)) {
     if (!allowed.includes(key)) throw new UsageError(`Unknown option --${key}. No update attempted.`);
-    if (key !== 'auto' && value !== true) throw new UsageError(`--${key} takes no value. No update attempted.`);
+    if (key !== 'auto' && key !== 'plugin' && value !== true) throw new UsageError(`--${key} takes no value. No update attempted.`);
   }
 }
 
@@ -15,7 +16,7 @@ async function report(ctx, force = false) {
     checkVersion({ ...options, current: ctx.version, offline: Boolean(ctx.flags.offline), force }),
     detectInstallation(options),
   ]);
-  return { ...version, installation, auto: autoEnabled(installation, ctx.env),
+  return { ...version, installation, auto: autoEnabled(installation, ctx.env), autoDecided: autoDecided(installation, ctx.env),
     updateCommand: installation.kind === 'unsupported' ? null : `sprid update${version.requiresApproval ? ' --yes' : ''}`,
     install: installationCommand(installation, version.recommended) };
 }
@@ -27,39 +28,57 @@ function output(ctx, result) {
   else if (result.updateAvailable) ctx.warn(`${result.requiresApproval ? 'Potentially breaking update. ' : ''}${result.updateCommand || result.installation.reason}`);
   else if (result.installation.kind === 'unsupported') ctx.print(result.installation.reason);
   if (result.skipped) ctx.print(`Update skipped: ${result.skipped}.`);
+  const plugin = result.plugin;
+  if (plugin?.updated) ctx.print(`Skills updated. ${plugin.reload}`);
+  else if (plugin?.updateAvailable) ctx.warn(`Newer Sprid skills: ${plugin.latest}${plugin.current ? ` (running ${plugin.current})` : ''}. ${plugin.updateCommand ?? plugin.reason}`);
+  else if (plugin) ctx.print(plugin.check === 'verified' ? `Skills ${plugin.current} are current.` : 'Skills version check unavailable.');
 }
 export async function doctor(ctx) {
-  validate(ctx, ['json', 'offline', 'apply-updates']);
+  validate(ctx, ['json', 'offline', 'apply-updates', 'plugin']);
+  if (ctx.flags.plugin === true) throw new UsageError('--plugin needs the skills root, two directories above a SKILL.md.');
   const result = await report(ctx);
+  let plugin;
+  if (ctx.flags.plugin) {
+    const options = { env: ctx.env, ...ctx.updateOptions };
+    plugin = await checkPlugin({ root: ctx.flags.plugin, offline: Boolean(ctx.flags.offline), ...options });
+    // One opt-in keeps all of Sprid current: the CLI and the skills that drive it.
+    if (ctx.flags['apply-updates'] && result.auto && plugin.check === 'verified' && plugin.updateAvailable && plugin.updateCommand) {
+      plugin = { ...plugin, ...await updatePlugin(ctx.flags.plugin, options) };
+    }
+  }
+  // The install ping names the host the skills came through (see telemetry.mjs).
+  if (plugin) ctx.pluginInfo = { host: plugin.host, current: plugin.current };
+  // Every path below reports through say(), so the skills result rides along.
+  const say = plugin ? (c, r) => output(c, { ...r, plugin }) : output;
   // This flag marks an explicit between-jobs boundary. Ordinary commands never install.
   if (ctx.flags['apply-updates'] && result.auto && result.check === 'verified' && result.compatible && result.installation.kind !== 'unsupported') {
-    const { 'apply-updates': _, ...flags } = ctx.flags;
-    return update({ ...ctx, flags: { ...flags, 'auto-run': true } });
+    const { 'apply-updates': _, plugin: _plugin, ...flags } = ctx.flags;
+    return update({ ...ctx, flags: { ...flags, 'auto-run': true } }, say);
   }
-  output(ctx, result);
+  say(ctx, result);
   return 0;
 }
-export async function update(ctx) {
+export async function update(ctx, say = output) {
   validate(ctx, ['json', 'offline', 'auto', 'auto-run', 'check', 'yes']);
   if (ctx.flags.auto !== undefined) {
     if (!['on', 'off'].includes(ctx.flags.auto)) throw new UsageError('Use sprid update --auto on|off.');
     if (ctx.flags['auto-run'] || ctx.flags.check) throw new UsageError('--auto cannot be combined with --auto-run or --check.');
     const installation = await detectInstallation({ env: ctx.env, ...ctx.updateOptions });
     setAuto(installation, ctx.flags.auto === 'on', ctx.env);
-    output(ctx, { configured: ctx.flags.auto === 'on', installation });
+    say(ctx, { configured: ctx.flags.auto === 'on', installation });
     return 0;
   }
   const result = await report(ctx, !ctx.flags.check);
-  if (ctx.flags.check) { output(ctx, result); return 0; }
+  if (ctx.flags.check) { say(ctx, result); return 0; }
   if (ctx.flags['auto-run'] && (!result.auto || !result.compatible || result.check !== 'verified' || result.installation.kind === 'unsupported')) {
-    output(ctx, { ...result, skipped: !result.auto ? 'automatic updates are off' : 'no verified compatible update' }); return 0;
+    say(ctx, { ...result, skipped: !result.auto ? 'automatic updates are off' : 'no verified compatible update' }); return 0;
   }
   if (result.check !== 'verified') throw new Error('Cannot verify the recommended version. No update attempted; retry when the registry is available.');
-  if (!result.updateAvailable) { output(ctx, result); return 0; }
+  if (!result.updateAvailable) { say(ctx, result); return 0; }
   if (result.installation.kind === 'unsupported') throw new UsageError(result.installation.reason);
   if (result.requiresApproval && !ctx.flags.yes) throw new UsageError('Potentially breaking update. Review the release, then run sprid update --yes to approve it.');
   const updated = await performUpdate(result.installation, result.recommended, { env: ctx.env, ...ctx.updateOptions });
-  output(ctx, { ...result, ...updated });
+  say(ctx, { ...result, ...updated });
   return 0;
 }
 

package/src/docs/commands.mjs

@@ -36,9 +36,9 @@ export const COMMAND_GROUPS = [
     ['post', 'sprid post handoff <postId>', 'Print the prompt to paste into an agent: what the post currently is, which verbs to call, and an empty line for the ask. Same string the editor\'s "Hand off to agent" button copies.'],
   ] },
   { title: 'Installation and updates', entries: [
-    ['doctor', 'sprid doctor [--json] [--offline] [--apply-updates]', 'Check the running CLI against the npm latest release. --apply-updates is a between-jobs boundary and installs compatible updates only after explicit opt-in.'],
+    ['doctor', 'sprid doctor [--json] [--offline] [--apply-updates] [--plugin <skills-root>]', 'Check the running CLI against the npm latest release, and with --plugin the installed Sprid skills against the latest pushed. --apply-updates is a between-jobs boundary and installs compatible updates, CLI and skills, only after explicit opt-in (sprid update --auto on).'],
     ['update', 'sprid update [--check] [--yes]', 'Update the running installation and verify its new version. --check only reports; potentially breaking releases require --yes. Project installs use their own package manager and lockfile.'],
-    ['telemetry', 'sprid telemetry [status|on|off]', 'Show or change usage telemetry. When on, each command sends its name, exit code, duration and versions to your Sprid account, never arguments or file contents. DO_NOT_TRACK=1 or SPRID_TELEMETRY=0 turns it off for one shell.'],
+    ['telemetry', 'sprid telemetry [status|on|off]', 'Show or change usage telemetry. When on, the CLI sends an anonymous install id with versions once a day, and when signed in each command sends its name, exit code, duration and versions to your Sprid account, never arguments or file contents. DO_NOT_TRACK=1 or SPRID_TELEMETRY=0 turns it off for one shell.'],
     ['update', 'sprid update --auto on|off', 'Opt this installation into or out of compatible updates at job boundaries. Default off. Agents must have user approval before enabling.'],
   ] },
   { title: 'Store assets and releases', entries: [
@@ -73,6 +73,7 @@ export const COMMAND_GROUPS = [
     ['connect', 'sprid connect google-ads --account <slug> [--ad-account <customer id>]', 'Connect the Google Ads account that promotes YouTube videos. When the Google login reaches several accounts, Sprid lists their ids; run it again with --ad-account.'],
     ['connect', 'sprid connect tiktok-ads --account <slug> [--ad-account <advertiser id>]', 'Connect the TikTok ad account that promotes TikTok posts as Spark Ads. When the login reaches several advertisers, Sprid lists their ids; run it again with --ad-account.'],
     ['connect', 'sprid connect tiktok-comments --account <slug>', 'Let the Inbox read and answer comments on your TikTok posts. Sign in with the TikTok account that publishes them; this is separate from TikTok publishing and from TikTok Ads.'],
+    ['connect', 'sprid connect github --app <slug> --key-from-clipboard --repo <owner/repo>[,<owner/repo>]', 'Read a repository’s views, clones, referrers and stars. GitHub keeps 14 days of traffic, so Sprid copies it daily and the history starts the day you connect. --repo replaces the list, so name every repo.'],
     ['connect', 'sprid connect ga4|plausible|umami --app <slug> --key <file> … [--use]', 'PostHog, Google Analytics, Plausible and Umami all count the same website visits, so Sprid reads one of them and never adds them together. --use makes this one the source the traffic card reports from.'],
     ['pinterest', 'sprid pinterest boards --account <slug> [--channel <id>] [--bookmark <token>]', 'List boards and sections for the exact connected Pinterest channel; a returned bookmark reads the next page.'],
     ['pinterest', 'sprid pinterest create --account <slug> --name <name> [--description <text>] [--privacy public|secret]', 'Create a board in the exact connected Pinterest account. Older connections must reconnect once to grant board creation permission.'],
@@ -155,7 +156,7 @@ export const CLI_NOTES = [
   'Use -w/--workspace <slug|id> for one command, or sprid use to remember your choice.',
   'sprid login stores its token in ~/.sprid/credentials.json. SPRID_PAT overrides it.',
   'SPRID_URL overrides the API address. SPRID_APP_URL overrides the web app address.',
-  'Usage telemetry (command, exit code, duration, versions) goes to your Sprid account when signed in. sprid telemetry off, DO_NOT_TRACK=1 or SPRID_TELEMETRY=0 stops it.',
+  'Usage telemetry: an anonymous daily install id with versions, and when signed in each command, exit code and duration to your Sprid account. sprid telemetry off, DO_NOT_TRACK=1 or SPRID_TELEMETRY=0 stops it.',
 ];
 
 export const COMMAND_EXAMPLES = {

package/src/docs/guides.generated.mjs

@@ -21,7 +21,8 @@ export const GUIDE_GROUPS = [
       "polar",
       "lemonsqueezy",
       "paddle",
-      "cloudflare"
+      "cloudflare",
+      "github"
     ]
   },
   {
@@ -924,6 +925,53 @@ export const GUIDES = [
     "markdown": "# Cloudflare (optional)\n\n**What Sprid does with this:** Read traffic reports for your website.\n\n## You need\n\nAccess to your domain’s Cloudflare account and permission to create a token. Enable **Web Analytics** for visitor reports; basic request counts include bots.\n\n## Click path (dash.cloudflare.com)\n\n1. Open [Cloudflare](https://dash.cloudflare.com) → profile icon → **My Profile → API Tokens**.\n2. **Create Token → Custom token → Get started**, named `Sprid`.\n3. **Permissions**:\n   - **Zone → Analytics → Read**\n   - **Account → Account Analytics → Read**\n4. **Zone Resources → Include → Specific zone**: your domain.\n5. **Account Resources → Include**: your account.\n6. Leave **Client IP Address Filtering** and **TTL** empty. **Continue to summary → Create Token**.\n7. Copy the token and leave it on your clipboard. It is shown once.\n\nFor a connection that survives you leaving the team, create an account-owned token instead under **Manage Account → Account API Tokens**, with the same permissions.\n\n## Zone id\n\nYour domain → **Overview** → **API** card: copy **Zone ID** and **Account ID**. The Zone ID goes in the command; ask your agent to save the Account ID in your Sprid app profile.\n\n## Then run\n\n```\nsprid connect cloudflare --key-from-clipboard --zone 0123456789abcdef0123456789abcdef\n```\n\nUse your own Zone ID. Keep the token out of chat.\n\nSprid reads the token from your clipboard, saves it and clears the clipboard, so it never shows on screen or lands in a file. Working with an agent? Tell it the token is copied and it runs this for you. Typing it yourself, copy the token last: paste the command into your terminal first, then copy the token, then press Enter. If the clipboard still holds the command, Sprid refuses it; copy the token and run it again. Without clipboard access (a remote shell), save the token to a file and pass `--token <file>` instead.\n\n## How to check it worked\n\nRun `sprid status`, then ask your agent: “Check that Sprid can read recent Cloudflare traffic for this domain.” The check names the domain and says whether visitor reports or only request counts are available.\n\n## If it fails\n\n- **Access denied:** **API Tokens → ⋯ → Edit**. Check both Read permissions and the selected domain and account.\n- **Domain not found:** use the Zone ID, not the domain name.\n- **Visitor reports are empty:** enable **Analytics & Logs → Web Analytics** and check the tracking snippet is on your site.\n\n## Investigate with this connection\n\nReads `rum` and `http`. RUM is pinned to the saved account and hostname; beacon traffic is sampled and not verified human.\n\n```sh\nsprid marketing-review capabilities --app <slug> --source cloudflare --json\n```\n\nSee [connected queries](https://sprid.studio/docs/queries).\n\n## Sources\n\n- [Create an API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)\n- [GraphQL Analytics API token permissions](https://developers.cloudflare.com/analytics/graphql-api/getting-started/authentication/api-token-auth/)\n- [Find zone and account ids](https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/)\n- [Verify a token](https://developers.cloudflare.com/api/resources/user/subresources/tokens/methods/verify/)\n",
     "revision": "c34f4dd6420981c8"
   },
+  {
+    "id": "github",
+    "title": "GitHub",
+    "summary": "See how many people view and clone your repository each day, where they came from, which pages they read, and how stars, forks and watchers move.",
+    "command": "sprid connect github --key-from-clipboard --repo your-org/your-repo",
+    "url": "https://sprid.studio/docs/connect/github",
+    "sections": [
+      {
+        "id": "you-need",
+        "title": "You need",
+        "kind": "requirements",
+        "markdown": "A **token that can read traffic** on the repository, and **push access** to it yourself. GitHub shows traffic only to people who can write to a repo, whatever the token says.\n\nChecked against GitHub's permissions reference on 2026-09-25: all four traffic endpoints need the fine-grained permission **Repository permissions → Administration: Read-only**. A classic token needs the `repo` scope."
+      },
+      {
+        "id": "click-path",
+        "title": "Click path",
+        "kind": "steps",
+        "markdown": "1. Open [GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens) and choose **Generate new token**.\n2. Name it `sprid`. Pick an expiry date; Sprid tells you when the token stops working.\n3. **Resource owner:** the account or organization that owns the repo.\n4. **Repository access → Only select repositories**, and pick the repos you want measured.\n5. **Permissions → Repository permissions → Administration → Read-only.** Metadata switches itself to Read-only; leave everything else off.\n6. **Generate token**, copy it and leave it on your clipboard. GitHub shows it once.\n\nIn an organization, an owner may have to approve the token before it works. Until they do, the read fails with the permission message below."
+      },
+      {
+        "id": "then-run",
+        "title": "Then run",
+        "kind": "command",
+        "markdown": "```\nsprid connect github --key-from-clipboard --repo your-org/your-repo\n```\n\nSeveral repos: `--repo your-org/app,your-org/site`. The list replaces the one already saved, so name every repo you want kept. A pasted `github.com` URL works too.\n\nSprid reads the key from your clipboard, saves it and clears the clipboard, so it never shows on screen or lands in a file. Working with an agent? Tell it the token is copied and it runs this for you. Typing it yourself, copy the token last: paste the command into your terminal first, then copy the token, then press Enter. If the clipboard still holds the command, Sprid refuses it; copy the token and run it again. Without clipboard access (a remote shell), save the token to a file and pass `--key <file>` instead."
+      },
+      {
+        "id": "how-to-check-it-worked",
+        "title": "How to check it worked",
+        "kind": "verify",
+        "markdown": "Run `sprid status`. The first read lands within the hour; then ask your agent: “Show this app’s GitHub views and clones for the last 7 days through Sprid.” A saved token confirms setup; only the read confirms access."
+      },
+      {
+        "id": "if-it-fails",
+        "title": "If it fails",
+        "kind": "troubleshooting",
+        "markdown": "- **Rejected the token:** it expired, was revoked or was mistyped. Fine-grained tokens expire on the date you set. Create a new one and run the command again.\n- **Cannot read traffic:** the token is missing **Administration: Read-only**, or you have read access to the repo but not push access. In an organization, check whether the token is waiting for an owner's approval.\n- **Cannot see that repository:** the name is wrong, or the repo is private and not among the token's selected repositories. GitHub answers both the same way.\n- **Rate limited:** another tool is using the same token heavily. Nothing is lost: GitHub still holds 14 days, and tomorrow's read catches up."
+      },
+      {
+        "id": "what-sprid-can-and-cannot-read-here",
+        "title": "What Sprid can and cannot read here",
+        "kind": "detail",
+        "markdown": "Views and clones per day, with GitHub's own daily unique counts; the top 10 referring sites and the top 10 pages over GitHub's 14-day window; stars, forks and watchers.\n\nViews and clones add up across days and repos. Unique visitors do not: someone who cloned on three days is three daily uniques but one unique over the window. So Sprid reports period totals as counts, and shows unique people only as GitHub's own 14-day figure.\n\nA clone is not an install. CI runs, mirrors and bots clone too, and one install can clone more than once. Treat clones as an upper bound that moves with real interest."
+      }
+    ],
+    "markdown": "# GitHub\n\n**What Sprid does with this:** See how many people view and clone your repository each day, where they came from, which pages they read, and how stars, forks and watchers move.\n\nGitHub only keeps traffic for 14 days, then deletes it. Sprid reads the window every day and keeps it, so your history starts the day you connect and never runs out.\n\n## You need\n\nA **token that can read traffic** on the repository, and **push access** to it yourself. GitHub shows traffic only to people who can write to a repo, whatever the token says.\n\nChecked against GitHub's permissions reference on 2026-09-25: all four traffic endpoints need the fine-grained permission **Repository permissions → Administration: Read-only**. A classic token needs the `repo` scope.\n\n## Click path\n\n1. Open [GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens](https://github.com/settings/personal-access-tokens) and choose **Generate new token**.\n2. Name it `sprid`. Pick an expiry date; Sprid tells you when the token stops working.\n3. **Resource owner:** the account or organization that owns the repo.\n4. **Repository access → Only select repositories**, and pick the repos you want measured.\n5. **Permissions → Repository permissions → Administration → Read-only.** Metadata switches itself to Read-only; leave everything else off.\n6. **Generate token**, copy it and leave it on your clipboard. GitHub shows it once.\n\nIn an organization, an owner may have to approve the token before it works. Until they do, the read fails with the permission message below.\n\n## Then run\n\n```\nsprid connect github --key-from-clipboard --repo your-org/your-repo\n```\n\nSeveral repos: `--repo your-org/app,your-org/site`. The list replaces the one already saved, so name every repo you want kept. A pasted `github.com` URL works too.\n\nSprid reads the key from your clipboard, saves it and clears the clipboard, so it never shows on screen or lands in a file. Working with an agent? Tell it the token is copied and it runs this for you. Typing it yourself, copy the token last: paste the command into your terminal first, then copy the token, then press Enter. If the clipboard still holds the command, Sprid refuses it; copy the token and run it again. Without clipboard access (a remote shell), save the token to a file and pass `--key <file>` instead.\n\n## How to check it worked\n\nRun `sprid status`. The first read lands within the hour; then ask your agent: “Show this app’s GitHub views and clones for the last 7 days through Sprid.” A saved token confirms setup; only the read confirms access.\n\n## If it fails\n\n- **Rejected the token:** it expired, was revoked or was mistyped. Fine-grained tokens expire on the date you set. Create a new one and run the command again.\n- **Cannot read traffic:** the token is missing **Administration: Read-only**, or you have read access to the repo but not push access. In an organization, check whether the token is waiting for an owner's approval.\n- **Cannot see that repository:** the name is wrong, or the repo is private and not among the token's selected repositories. GitHub answers both the same way.\n- **Rate limited:** another tool is using the same token heavily. Nothing is lost: GitHub still holds 14 days, and tomorrow's read catches up.\n\n## What Sprid can and cannot read here\n\nViews and clones per day, with GitHub's own daily unique counts; the top 10 referring sites and the top 10 pages over GitHub's 14-day window; stars, forks and watchers.\n\nViews and clones add up across days and repos. Unique visitors do not: someone who cloned on three days is three daily uniques but one unique over the window. So Sprid reports period totals as counts, and shows unique people only as GitHub's own 14-day figure.\n\nA clone is not an install. CI runs, mirrors and bots clone too, and one install can clone more than once. Treat clones as an upper bound that moves with real interest.\n",
+    "revision": "f6e2f390c58af602"
+  },
   {
     "id": "instagram",
     "title": "Instagram",
@@ -1568,8 +1616,8 @@ export const CONTENT_GUIDES = [
     "title": "Check whether a traffic spike is real",
     "summary": "Tells you how to judge a sudden jump in website visitors, and how to remove a scraper from your numbers without removing customers. Read it before you act on a spike or explain one.",
     "url": "https://sprid.studio/docs/traffic",
-    "markdown": "# Check whether a traffic spike is real\n\n**What this guide does:** Tells you how to judge a sudden jump in website\nvisitors, and how to remove a scraper from your numbers without removing\ncustomers. Read it before you act on a spike or explain one.\n\nA spike is not proof of a bot, and a quiet baseline is not proof of people.\nGet it wrong one way and you chase a channel that never existed; the other way\nand you drop real readers from your own numbers. Use the four reads below, in\norder, and keep any rule as narrow as your evidence.\n\nSprid flags candidates. When one day carries at least 35% of a 30-day period\nand runs at ten times the median day, `next` shows **Review that day** with the\ndate, the multiple and that day’s pageviews per visitor against the rest of the\nmonth. It is a prompt, not a verdict: a daily series can’t tell a crawl from a\ngood day.\n\n## Four reads, in order\n\n**1. Find the hours, not the day.** Split the suspect day by hour. Marketing\narrives across a day and decays over several. A scrape is a block: a flat rate\nfor a few hours, then nothing. If the day’s total sits in four consecutive\nhours with ordinary hours either side, it is one client, not an audience.\n\n**2. Divide pageviews by visitors, but don’t trust it alone.** A browser with no\ncookie is a new visitor on every request, so a crawl that reads each page once\nshows a huge visitor count at 1.0 pageviews each. A crawler that hits each URL\nseveral times doesn’t: the September 2026 scrape ran at **1.60 pageviews a\nvisitor against a baseline of 1.44**. A flat 1.0 is suspicious; a healthy ratio\nproves nothing.\n\n**3. Ask for whole groups, not separate dimensions.** `review_traffic` returns\ncompound groups (browser, version, OS, screen, timezone, referrer, country\ntogether), because adding up separate dimension counts double-counts everyone.\nOne group carrying most of a day is the finding. Twelve groups sharing it evenly\nis not, unless they agree on something (below).\n\n**4. Look at which pages were hit.** A crawl walks your sitemap: every locale\nand item, a few hits each. Real discovery is lopsided: a few pages that rank or\nwere linked take most of the traffic.\n\n## What the fingerprint looks like\n\nRead the fields that are hardest to fake:\n\n- **Timezone against geography** is the strongest tell. A browser on\n  `Asia/Shanghai` while its IPs sit in the US, Singapore and Germany is one\n  operator on rented addresses. The addresses rotate; the machine’s clock\n  doesn’t.\n- **An odd viewport** (`800x600`, `1512x982`, `1280x720`) beats the user agent,\n  which is the field they bother to spoof. Expect a plausible current Chrome on\n  macOS with a screen no customer has.\n- **A blend is a signature too.** One wave rotated Chrome 118-120, Edge 119-120\n  and Firefox 120-121 so no browser stood out, all on one viewport, timezone and\n  referrer. What they varied is noise; what they forgot to vary is the rule.\n- **Referrer `$direct`** on everything, with no search or social.\n- **Country is not a tell.** The same wave comes from a dozen countries. A\n  country rule removes customers and keeps the scraper.\n\n## Check the comparison period too\n\nA percentage change has two periods, and nobody looks at the older one. On one\napp in September 2026 the same thirty days read **+252.5%** before review,\n**-62.6%** with only the obvious spike excluded, and **-17.6%** once two earlier\nwaves in the comparison period were excluded too. The middle answer was wrong\nand the most convincing, because it already looked corrected.\n\nSo when you find one wave, look for others before saving anything. Query the\nwhole history for its marker (the timezone, the viewport) by day. Waves have\nedges: 5 to 30 visitors a day in the background and several hundred on wave\ndays tells you where the rule starts and that the rest is ordinary.\n\n## Two more traps\n\n**Raw provider data is not what Sprid counted.** Web visitors already exclude\nevents with no browser, crawler and headless user agents, reported bots, and\nanything marked internal or test. A wave with a null browser never reached your\ntotal, so a raw query including it won’t match the card. Compare like with like\nor you exclude the same traffic twice.\n\n**Bound a rule by how ordinary its conditions are.** `1920x1080` is a real\nscreen many customers use, so a rule on it gets exactly the wave’s dates. A\nviewport nobody has can carry a longer window. The date range is the safety\nmargin for a condition that isn’t distinctive on its own.\n\n## Save the exclusion\n\nPreview, then save. `review_traffic` shows visitor counts before and after for\nthe period **and the one before it**, which is the number you want to see move.\n\n```json\n{\n  \"id\": \"scrape-2026-09-18\",\n  \"reason\": \"Full-site crawl 04:00-08:00 UTC: Asia/Shanghai timezone, 800x600 viewport, direct referrer, IPs across US/SG/DE. 39,958 of the day's 40,476 visitors, every locale and item page hit at most 5 times with no cookie reuse.\",\n  \"start\": \"2026-09-18\",\n  \"end\": \"2026-09-19\",\n  \"enabled\": true,\n  \"conditions\": [\n    { \"field\": \"timezone\", \"value\": \"Asia/Shanghai\" },\n    { \"field\": \"screenWidth\", \"value\": \"800\" },\n    { \"field\": \"screenHeight\", \"value\": \"600\" }\n  ]\n}\n```\n\n- End dates are exclusive and UTC.\n- Conditions in a rule are AND; separate rules are OR.\n- Fields: `browser`, `browserVersion`, `os`, `osVersion`, `screenWidth`,\n  `screenHeight`, `timezone`, `referrer`, `country`. Values are exact strings;\n  a missing property never matches.\n- Write `reason` for someone reading it in a year: the window, the evidence and\n  how much it removes.\n\nSave through `upsert_app_profile` or `PATCH /api/app-profiles/:id` under\n`posthogConfig.trafficExclusions`, keeping the rest of the configuration. Then\n**log the change as an event** with the areas it affects and why, or next\nmonth’s drop in your graph becomes a new mystery.\n\n## What an exclusion doesn’t touch\n\nYour provider’s data is never changed or deleted; Sprid filters when it reads.\nApp activity, registrations and revenue are unaffected, since a scraper doesn’t\nsign up. Raw connected queries and the marketing-review event inventory stay\nunfiltered on purpose, as the evidence to check the rule against. **Restore this\ntraffic** disables a rule and the original numbers come straight back.\n\n## When not to exclude\n\nA spike with a real referrer and lopsided pages is a link that worked: find it\nbefore you filter it. A shared office machine, an uptime probe and a preview\nrenderer all repeat a fingerprint, and none is worth a rule. A group you can’t\nexplain stays in: an unexplained visitor counted is a smaller error than a\ncustomer removed.\n",
-    "revision": "2ee50917e61c94f4"
+    "markdown": "# Check whether a traffic spike is real\n\n**What this guide does:** Tells you how to judge a sudden jump in website\nvisitors, and how to remove a scraper from your numbers without removing\ncustomers. Read it before you act on a spike or explain one.\n\nA spike is not proof of a bot, and a quiet baseline is not proof of people.\nGet it wrong one way and you chase a channel that never existed; the other way\nand you drop real readers from your own numbers. Use the four reads below, in\norder, and keep any rule as narrow as your evidence.\n\nSprid flags candidates. When one day carries at least 35% of a 30-day period\nand runs at ten times the median day, `next` shows **Review that day** with the\ndate, the multiple and that day’s pageviews per visitor against the rest of the\nmonth. Treat it as a reason to look closer: a daily series can’t tell a crawl from a\ngood day.\n\n## Four reads, in order\n\n**1. Find the hours, not the day.** Split the suspect day by hour. Marketing\narrives across a day and decays over several. A scrape is a block: a flat rate\nfor a few hours, then nothing. If the day’s total sits in four consecutive\nhours with ordinary hours either side, it is one client, not an audience.\n\n**2. Divide pageviews by visitors, but don’t trust it alone.** A browser with no\ncookie is a new visitor on every request, so a crawl that reads each page once\nshows a huge visitor count at 1.0 pageviews each. A crawler that hits each URL\nseveral times doesn’t: the September 2026 scrape ran at **1.60 pageviews a\nvisitor against a baseline of 1.44**. A flat 1.0 is suspicious; a healthy ratio\nproves nothing.\n\n**3. Ask for whole groups, not separate dimensions.** `review_traffic` returns\ncompound groups (browser, version, OS, screen, timezone, referrer, country\ntogether), because adding up separate dimension counts double-counts everyone.\nOne group carrying most of a day is the finding. Twelve groups sharing it evenly\nis not, unless they agree on something (below).\n\n**4. Look at which pages were hit.** A crawl walks your sitemap: every locale\nand item, a few hits each. Real discovery is lopsided: a few pages that rank or\nwere linked take most of the traffic.\n\n## What the fingerprint looks like\n\nRead the fields that are hardest to fake:\n\n- **Timezone against geography** is the strongest tell. A browser on\n  `Asia/Shanghai` while its IPs sit in the US, Singapore and Germany is one\n  operator on rented addresses. The addresses rotate; the machine’s clock\n  doesn’t.\n- **An odd viewport** (`800x600`, `1512x982`, `1280x720`) beats the user agent,\n  which is the field they bother to spoof. Expect a plausible current Chrome on\n  macOS with a screen no customer has.\n- **A blend is a signature too.** One wave rotated Chrome 118-120, Edge 119-120\n  and Firefox 120-121 so no browser stood out, all on one viewport, timezone and\n  referrer. What they varied is noise; what they forgot to vary is the rule.\n- **Referrer `$direct`** on everything, with no search or social.\n- **Country is not a tell.** The same wave comes from a dozen countries. A\n  country rule removes customers and keeps the scraper.\n\n## Check the comparison period too\n\nA percentage change has two periods, and nobody looks at the older one. On one\napp in September 2026 the same thirty days read **+252.5%** before review,\n**-62.6%** with only the obvious spike excluded, and **-17.6%** once two earlier\nwaves in the comparison period were excluded too. The middle answer was wrong\nand the most convincing, because it already looked corrected.\n\nSo when you find one wave, look for others before saving anything. Query the\nwhole history for its marker (the timezone, the viewport) by day. Waves have\nedges: 5 to 30 visitors a day in the background and several hundred on wave\ndays tells you where the rule starts and that the rest is ordinary.\n\n## Two more traps\n\n**Raw provider data is not what Sprid counted.** Web visitors already exclude\nevents with no browser, crawler and headless user agents, reported bots, and\nanything marked internal or test. A wave with a null browser never reached your\ntotal, so a raw query including it won’t match the card. Compare like with like\nor you exclude the same traffic twice.\n\n**Bound a rule by how ordinary its conditions are.** `1920x1080` is a real\nscreen many customers use, so a rule on it gets exactly the wave’s dates. A\nviewport nobody has can carry a longer window. The date range is the safety\nmargin for a condition that isn’t distinctive on its own.\n\n## Save the exclusion\n\nPreview, then save. `review_traffic` shows visitor counts before and after for\nthe period **and the one before it**, which is the number you want to see move.\n\n```json\n{\n  \"id\": \"scrape-2026-09-18\",\n  \"reason\": \"Full-site crawl 04:00-08:00 UTC: Asia/Shanghai timezone, 800x600 viewport, direct referrer, IPs across US/SG/DE. 39,958 of the day's 40,476 visitors, every locale and item page hit at most 5 times with no cookie reuse.\",\n  \"start\": \"2026-09-18\",\n  \"end\": \"2026-09-19\",\n  \"enabled\": true,\n  \"conditions\": [\n    { \"field\": \"timezone\", \"value\": \"Asia/Shanghai\" },\n    { \"field\": \"screenWidth\", \"value\": \"800\" },\n    { \"field\": \"screenHeight\", \"value\": \"600\" }\n  ]\n}\n```\n\n- End dates are exclusive and UTC.\n- Conditions in a rule are AND; separate rules are OR.\n- Fields: `browser`, `browserVersion`, `os`, `osVersion`, `screenWidth`,\n  `screenHeight`, `timezone`, `referrer`, `country`. Values are exact strings;\n  a missing property never matches.\n- Write `reason` for someone reading it in a year: the window, the evidence and\n  how much it removes.\n\nSave through `upsert_app_profile` or `PATCH /api/app-profiles/:id` under\n`posthogConfig.trafficExclusions`, keeping the rest of the configuration. Then\n**log the change as an event** with the areas it affects and why, or next\nmonth’s drop in your graph becomes a new mystery.\n\n## What an exclusion doesn’t touch\n\nYour provider’s data is never changed or deleted; Sprid filters when it reads.\nApp activity, registrations and revenue are unaffected, since a scraper doesn’t\nsign up. Raw connected queries and the marketing-review event inventory stay\nunfiltered on purpose, as the evidence to check the rule against. **Restore this\ntraffic** disables a rule and the original numbers come straight back.\n\n## When not to exclude\n\nA spike with a real referrer and lopsided pages is a link that worked: find it\nbefore you filter it. A shared office machine, an uptime probe and a preview\nrenderer all repeat a fingerprint, and none is worth a rule. A group you can’t\nexplain stays in: an unexplained visitor counted is a smaller error than a\ncustomer removed.\n",
+    "revision": "865977c916e965ab"
   },
   {
     "id": "pinterest-content",
@@ -1584,8 +1632,8 @@ export const CONTENT_GUIDES = [
     "title": "Why a post travels",
     "summary": "Explains what Instagram and TikTok actually reward, and turns each mechanic into a rule you can build a post against. Read it before deciding a format, a slide count or a caption length, and when a post that looked good got no reach.",
     "url": "https://sprid.studio/docs/distribution",
-    "markdown": "# Why a post travels\n\n**What this guide does:** Explains what Instagram and TikTok actually reward,\nand turns each mechanic into a rule you can build a post against. Read it before\ndeciding a format, a slide count or a caption length, and when a post that\nlooked good got no reach.\n\nWhether a post is *good* and whether it *travels* are two different questions.\nThis one is about the second. Every rule here exists because of a specific\nmechanic, and if the mechanic changes the rule goes with it - so each is written\nwith its reason attached rather than as a commandment.\n\n**Verified against published sources 2026-08-04.** Platform mechanics decay.\nTreat anything here as a claim about a moving system, re-check it quarterly, and\nprefer your own numbers the moment you have them.\n\n## Instagram\n\n**The three named ranking signals are watch time, sends per reach, and likes per\nreach.** Sends are the heaviest, reported at roughly three to five times the\nweight of a like. Sends per reach is specifically the signal that reaches people\nwho do not follow you, which is the only reach a new account can grow on.\n\n**Feed, Reels, Stories and Explore rank separately** and weight those signals\ndifferently. Feed leans on how close you already are to the viewer; Explore on\nengagement velocity and interest match. A post that does well with your existing\nfollowers is not automatically a post that travels.\n\n**Why carousels, specifically:**\n\n- Every swipe is engagement, and dwell time accumulates across the slides.\n  Carousels are reported at two to three times the reach of a single image for\n  the same content.\n- **The platform re-serves a carousel to people who did not swipe, starting from\n  the second slide.** This is the most actionable mechanic available: slide two\n  gets an independent second chance to be someone's first impression.\n- Carousels out-save single images by a wide margin, and saves compound, because\n  saved posts get resurfaced.\n- Completion - how many people reach the last slide - is what pushes a post out\n  of your followers and into Explore.\n\n**Hashtags do not drive distribution.** The platform's own position is that they\ncategorise rather than distribute. Discovery comes from the words in your\ncaption: captions, alt text, bios and on-screen text are indexed and served into\nin-app search. Keyword-rich captions have been measured at around 30% more reach\nthan hashtag-heavy ones. Keep three to five hashtags as labels and spend the\neffort on the prose.\n\n## TikTok, photo mode\n\n- Ranking is swipe-through rate, dwell time and reverse swipes, with completion\n  rate as the primary signal.\n- Distribution starts with a **small test batch of roughly 200-500 viewers**,\n  mostly followers and people who engage with adjacent content. What that batch\n  does decides everything afterwards. This is why the first hour matters, and\n  why a weak second slide is fatal rather than merely costly.\n- Saves are weighted and photo posts save well. A carousel with fewer views but\n  a high save-and-comment share is doing better than a higher-view post that\n  bounces on slide one.\n- Interest-based distribution means an outlier is possible from your first post.\n  TikTok is spikier; Instagram grinds.\n\n## What follows for how you build a post\n\n| Rule | Because |\n|---|---|\n| **Slide 2 is a second hook.** It delivers on slide 1 *and* opens a new thread, and it has to work cold | the platform re-serves from slide 2; TikTok's test batch dies there |\n| **Seven slides for a narrative format** (hook, five body, closer) | seven to ten is the reported dwell-time sweet spot; under five reads as a short post, over ten causes mid-carousel fatigue |\n| **No slide may be skippable.** If a body slide can be removed without breaking the post, you wrote a list, not an experience | completion is the ranking signal, and a list lets people stop anywhere |\n| **The peak lands in the last third** | a middle peak makes the tail a letdown, and the tail is where completion is won |\n| **Design for the send, not the like.** At least one slide should make someone think of a specific person | sends per reach is the non-follower signal, worth several likes |\n| **The send prompt lives in the caption**, naming one kind of person, never \"share if you relate\" | it belongs where sends are earned, and it keeps the last slide screenshottable |\n| **At least two slides hand over something usable** | recognition earns likes; recognition plus something doable earns saves, and saves compound |\n| **Captions carry the audience's own search phrases, in prose** | captions are indexed; hashtags are not distribution |\n| **Caption length 400-600 characters on Instagram, 150-300 on TikTok**, first line an independent hook under 125 characters | that is where the \"more\" cut falls; past roughly 300 characters TikTok needs a tap and reach drops |\n| **Three to five hashtags, never the generic feed tag** | labels, not reach |\n| **One canvas at 4:5, content clear of the top and bottom edges** | survives the 3:4 grid crop, letterboxes acceptably on TikTok |\n\n## Cadence, and the first hour\n\n**Three to five posts a week, sustained.** Three a week for twelve weeks beats\nseven a week for three. The failure mode is not low quality, it is stopping - and\nthe documented version of it is 34 drafts and 3 published posts.\n\n**The first hour is the test batch.** Being there to answer early comments is the\ncheapest intervention available on either platform; a comment answered in the\nfirst hour is worth more than the same reply a day later.\n\n**Post at a fixed time** your audience is awake for, set once on the account's\nposting schedule rather than decided per post.\n\n**Expect silence for two months.** A new account with no face takes three to six\nmonths to reach a thousand followers on Instagram. Distribution is a power law:\na few posts carry most of the reach. Judging before 90 days is judging noise.\n\n## When something works, fan it out\n\nA post that breaks out is the beginning of the work, not the end.\n\n1. Make five to ten variants of the winner with the structure fixed and **exactly\n   one variable changed** - the hook phrasing, the register, the opening image.\n2. One variable per variant, or the result teaches nothing.\n3. Log which variant won *and* which source line its hook came from. That tells\n   you which well to keep digging.\n4. A losing variant is data. Kill it rather than nursing it.\n\n## What is worth not believing\n\nEverything above is published guidance and platform statements, not our\nmeasurements. Before you treat any of it as settled for **your** audience, these\nare the clean one-variable tests: caption length judged on saves and sends per\nreach; a quiet text card against a photo behind text; a native 9:16 crop against\na letterboxed 4:5; whether a screenshot of your app costs reach or buys installs.\n\nLog the real numbers per post at seven days - views, completion, saves, sends,\ncomments, profile taps. The moment you have your own numbers they outrank every\nsource below.\n\n## Sources\n\n- [Instagram algorithm ranking signals (Buffer)](https://buffer.com/resources/instagram-algorithms/) - watch time, sends per reach, likes per reach, per-surface ranking\n- [The ranking signals that matter (Clixie)](https://www.clixie.ai/blog/instagram-algorithm) - sends weighted three to five times a like\n- [How carousels beat Reels for engagement (Storrito)](https://storrito.com/resources/how-instagram-carousels-beat-reels-for-engagement-in-2026-and-when-to-use-each/) - re-serving from slide 2, reach multiple\n- [Carousel best practices (Adpicto)](https://www.adpicto.com/en/blog/instagram-carousel-best-practices-2026) - slide count, dwell time, saves\n- [Carousel algorithm (TryMyPost)](https://www.trymypost.com/blog/instagram-carousel-algorithm-strategy-2026) - dwell time and completion\n- [Do hashtags still work (Kontentino)](https://www.kontentino.com/q-and-a/instagram-hashtags-reach/) - hashtags do not drive reach\n- [Keywords versus hashtags (Dive Media)](https://www.divemedia.com.au/marketing-tips-and-insights/social-seo-keywords-vs-hashtags) - caption indexing and the reach lift\n- [TikTok photo mode algorithm (ReelBase)](https://reelbase.io/blog/tiktok-photo-mode-algorithm-explained) - photo mode reach against video\n- [TikTok carousel algorithm (PostWaffle)](https://www.postwaffle.com/blog/tiktok-carousel-algorithm) - swipe-through, reverse swipes, test batch size, saves\n",
-    "revision": "6799e74c42287dc5"
+    "markdown": "# Why a post travels\n\n**What this guide does:** Explains what Instagram and TikTok actually reward,\nand turns each mechanic into a rule you can build a post against. Read it before\ndeciding a format, a slide count or a caption length, and when a post that\nlooked good got no reach.\n\nWhether a post is *good* and whether it *travels* are two different questions.\nThis one is about the second. Every rule here exists because of a specific\nmechanic, and if the mechanic changes the rule goes with it, so each one carries\nits reason.\n\n**Verified against published sources 2026-08-04.** Platform mechanics decay.\nTreat anything here as a claim about a moving system, re-check it quarterly, and\nprefer your own numbers the moment you have them.\n\n## Instagram\n\n**The three named ranking signals are watch time, sends per reach, and likes per\nreach.** Sends are the heaviest, reported at roughly three to five times the\nweight of a like. Sends per reach is specifically the signal that reaches people\nwho do not follow you, which is the only reach a new account can grow on.\n\n**Feed, Reels, Stories and Explore rank separately** and weight those signals\ndifferently. Feed leans on how close you already are to the viewer; Explore on\nengagement velocity and interest match. A post that does well with your existing\nfollowers is not automatically a post that travels.\n\n**Why carousels, specifically:**\n\n- Every swipe is engagement, and dwell time accumulates across the slides.\n  Carousels are reported at two to three times the reach of a single image for\n  the same content.\n- **The platform re-serves a carousel to people who did not swipe, starting from\n  the second slide.** This is the most actionable mechanic available: slide two\n  gets an independent second chance to be someone's first impression.\n- Carousels out-save single images by a wide margin, and saves compound, because\n  saved posts get resurfaced.\n- Completion - how many people reach the last slide - is what pushes a post out\n  of your followers and into Explore.\n\n**Hashtags do not drive distribution.** The platform's own position is that they\ncategorise rather than distribute. Discovery comes from the words in your\ncaption: captions, alt text, bios and on-screen text are indexed and served into\nin-app search. Keyword-rich captions have been measured at around 30% more reach\nthan hashtag-heavy ones. Keep three to five hashtags as labels and spend the\neffort on the prose.\n\n## TikTok, photo mode\n\n- Ranking is swipe-through rate, dwell time and reverse swipes, with completion\n  rate as the primary signal.\n- Distribution starts with a **small test batch of roughly 200-500 viewers**,\n  mostly followers and people who engage with adjacent content. What that batch\n  does decides everything afterwards. This is why the first hour matters, and\n  why a weak second slide can end the post’s reach.\n- Saves are weighted and photo posts save well. A carousel with fewer views but\n  a high save-and-comment share is doing better than a higher-view post that\n  bounces on slide one.\n- Interest-based distribution means an outlier is possible from your first post.\n  TikTok is spikier; Instagram grinds.\n\n## What follows for how you build a post\n\n| Rule | Because |\n|---|---|\n| **Slide 2 is a second hook.** It delivers on slide 1 *and* opens a new thread, and it has to work cold | the platform re-serves from slide 2; TikTok's test batch dies there |\n| **Seven slides for a narrative format** (hook, five body, closer) | seven to ten is the reported dwell-time sweet spot; under five reads as a short post, over ten causes mid-carousel fatigue |\n| **No slide may be skippable.** If a body slide can be removed without breaking the post, you wrote a list, and people can stop anywhere in a list | completion is the ranking signal, and a list lets people stop anywhere |\n| **The peak lands in the last third** | a middle peak makes the tail a letdown, and the tail is where completion is won |\n| **Design for sends.** At least one slide should make someone think of a specific person | sends per reach is the non-follower signal, worth several likes |\n| **The send prompt lives in the caption**, naming one kind of person, never \"share if you relate\" | it belongs where sends are earned, and it keeps the last slide screenshottable |\n| **At least two slides hand over something usable** | recognition earns likes; recognition plus something doable earns saves, and saves compound |\n| **Captions carry the audience's own search phrases, in prose** | captions are indexed; hashtags are not distribution |\n| **Caption length 400-600 characters on Instagram, 150-300 on TikTok**, first line an independent hook under 125 characters | that is where the \"more\" cut falls; past roughly 300 characters TikTok needs a tap and reach drops |\n| **Three to five hashtags, never the generic feed tag** | labels, not reach |\n| **One canvas at 4:5, content clear of the top and bottom edges** | survives the 3:4 grid crop, letterboxes acceptably on TikTok |\n\n## Cadence, and the first hour\n\n**Three to five posts a week, sustained.** Three a week for twelve weeks beats\nseven a week for three. The failure mode is not low quality, it is stopping - and\nthe documented version of it is 34 drafts and 3 published posts.\n\n**The first hour is the test batch.** Being there to answer early comments is the\ncheapest intervention available on either platform; a comment answered in the\nfirst hour is worth more than the same reply a day later.\n\n**Post at a fixed time** your audience is awake for, set once on the account's\nposting schedule rather than decided per post.\n\n**Expect silence for two months.** A new account with no face takes three to six\nmonths to reach a thousand followers on Instagram. Distribution is a power law:\na few posts carry most of the reach. Judging before 90 days is judging noise.\n\n## When something works, fan it out\n\nWhen a post breaks out, the work starts: more like it, and the best one promoted.\n\n1. Make five to ten variants of the winner with the structure fixed and **exactly\n   one variable changed** - the hook phrasing, the register, the opening image.\n2. One variable per variant, or the result teaches nothing.\n3. Log which variant won *and* which source line its hook came from. That tells\n   you which well to keep digging.\n4. A losing variant tells you something. Stop it and write down what.\n\n## What is worth not believing\n\nEverything above is published guidance and platform statements, not our\nmeasurements. Before you treat any of it as settled for **your** audience, these\nare the clean one-variable tests: caption length judged on saves and sends per\nreach; a quiet text card against a photo behind text; a native 9:16 crop against\na letterboxed 4:5; whether a screenshot of your app costs reach or buys installs.\n\nLog the real numbers per post at seven days - views, completion, saves, sends,\ncomments, profile taps. The moment you have your own numbers they outrank every\nsource below.\n\n## Sources\n\n- [Instagram algorithm ranking signals (Buffer)](https://buffer.com/resources/instagram-algorithms/) - watch time, sends per reach, likes per reach, per-surface ranking\n- [The ranking signals that matter (Clixie)](https://www.clixie.ai/blog/instagram-algorithm) - sends weighted three to five times a like\n- [How carousels beat Reels for engagement (Storrito)](https://storrito.com/resources/how-instagram-carousels-beat-reels-for-engagement-in-2026-and-when-to-use-each/) - re-serving from slide 2, reach multiple\n- [Carousel best practices (Adpicto)](https://www.adpicto.com/en/blog/instagram-carousel-best-practices-2026) - slide count, dwell time, saves\n- [Carousel algorithm (TryMyPost)](https://www.trymypost.com/blog/instagram-carousel-algorithm-strategy-2026) - dwell time and completion\n- [Do hashtags still work (Kontentino)](https://www.kontentino.com/q-and-a/instagram-hashtags-reach/) - hashtags do not drive reach\n- [Keywords versus hashtags (Dive Media)](https://www.divemedia.com.au/marketing-tips-and-insights/social-seo-keywords-vs-hashtags) - caption indexing and the reach lift\n- [TikTok photo mode algorithm (ReelBase)](https://reelbase.io/blog/tiktok-photo-mode-algorithm-explained) - photo mode reach against video\n- [TikTok carousel algorithm (PostWaffle)](https://www.postwaffle.com/blog/tiktok-carousel-algorithm) - swipe-through, reverse swipes, test batch size, saves\n",
+    "revision": "a00738c55be34d96"
   },
   {
     "id": "ads",

package/src/docs/queries.mjs

@@ -63,7 +63,7 @@ op('lemonsqueezy', 'subscription-invoices', 'Read initial, renewal and update in
 op('paddle', 'transactions', 'Read billed transactions by time, status, customer or subscription.', { ...dates, status: array(choice('Status.', ['draft', 'ready', 'billed', 'paid', 'completed', 'canceled', 'past_due']), 7), customer_id: id('Paddle customer ID.'), subscription_id: id('Paddle subscription ID.'), limit, cursor }, [], { start: '2026-08-01', end: '2026-09-01', status: ['completed'], limit: 100 });
 op('paddle', 'subscriptions', 'Read subscription lifecycles by status or price; optional creation dates filter each returned page locally.', { ...dates, status: array(choice('Status.', ['active', 'canceled', 'past_due', 'paused', 'trialing']), 5), customer_id: id('Paddle customer ID.'), price_id: id('Paddle price ID.'), limit, cursor }, [], { status: ['trialing'], limit: 100 });
 for (const source of Object.keys(QUERY_SOURCES).filter(s => QUERY_SOURCES[s].stored)) {
-  op(source, 'posts', 'Filter stored publishing outcomes with the latest metric snapshot before the exclusive end.', { ...dates, status: choice('Publishing status.', ['published', 'failed', 'missed', 'scheduled', 'pending', 'rendering', 'publishing', 'awaiting_runner']), contentType: choice('Post type.', ['carousel', 'reel']), limit, offset: integer('Zero-based offset.', 100000, 0) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', status: 'published', limit: 100 });
+  op(source, 'posts', 'Filter stored publishing outcomes with the latest metric snapshot before the exclusive end.', { ...dates, status: choice('Publishing status.', ['published', 'failed', 'missed', 'scheduled', 'pending', 'rendering', 'publishing']), contentType: choice('Post type.', ['carousel', 'reel']), limit, offset: integer('Zero-based offset.', 100000, 0) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', status: 'published', limit: 100 });
   op(source, 'comments', 'Read feedback already collected into Sprid’s Inbox, with optional post and reply filters.', { ...dates, postId: integer('Sprid post ID.', 1000000000), replied: { type: 'boolean', description: 'Filter comments by reply state.' }, limit, offset: integer('Zero-based offset.', 100000, 0) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', replied: false, limit: 100 });
 }
 

package/src/plugin-updates.mjs

@@ -0,0 +1,94 @@
+// Is the agent running the latest Sprid skills?
+//
+// The skills ship as a plugin (Claude Code, Codex) or as copied skill folders
+// (`npx skills add`), never through npm, so the CLI's own registry check says
+// nothing about them. A host caches an installed plugin and updates it only when
+// asked, which is how an agent ran month-old skills while three releases sat in
+// the repository. The skills pass their own root with `sprid doctor --plugin`.
+import { readFileSync, realpathSync, existsSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { runProcess, stableVersion, compareVersions, stateDirectory } from './updates.mjs';
+import { writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const PLUGIN_SOURCE = 'https://raw.githubusercontent.com/sprid-studio/plugin/main/package.json';
+const PLUGIN_PACKAGE = 'sprid-plugin';
+const DAY = 86_400_000;
+const read = path => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
+const real = path => { try { return realpathSync(path); } catch { return null; } };
+const safeName = value => /^[A-Za-z0-9._-]{1,100}$/.test(value);
+
+function saveJson(path, data) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  try { writeFileSync(tmp, JSON.stringify(data) + '\n', { mode: 0o600, flag: 'wx' }); renameSync(tmp, path); }
+  finally { rmSync(tmp, { force: true }); }
+}
+
+/** Which host installed the skills, read off the directory the host put them in. */
+export function detectPluginHost(root) {
+  const parts = root.split(sep);
+  const at = (a, b) => parts.findIndex((part, i) => part === a && parts[i + 1] === 'plugins' && parts[i + 2] === 'cache');
+  const claude = at('.claude'), codex = at('.codex');
+  if (claude >= 0 && safeName(parts[claude + 3] ?? '') && safeName(parts[claude + 4] ?? '')) {
+    const marketplace = parts[claude + 3], plugin = parts[claude + 4];
+    return { kind: 'claude', marketplace, reload: 'Run /reload-plugins, or start a new session, to load the new skills.',
+      commands: [['claude', ['plugin', 'marketplace', 'update', marketplace]], ['claude', ['plugin', 'update', `${plugin}@${marketplace}`]]] };
+  }
+  if (codex >= 0 && safeName(parts[codex + 3] ?? '') && safeName(parts[codex + 4] ?? '')) {
+    const marketplace = parts[codex + 3], plugin = parts[codex + 4];
+    return { kind: 'codex', marketplace, reload: 'Start a new Codex thread to load the new skills.',
+      commands: [['codex', ['plugin', 'marketplace', 'upgrade', marketplace]], ['codex', ['plugin', 'add', `${plugin}@${marketplace}`]]] };
+  }
+  if (existsSync(join(root, '.git'))) return { kind: 'unsupported', reason: 'Source checkout. Update it with git.' };
+  return { kind: 'skills', reload: 'Start a new agent session to load the new skills.', commands: [['npx', ['-y', 'skills', 'update', '-y']]] };
+}
+
+/** Registry failure is data, never a reason to block work. Cached for a day, like the CLI check. */
+export async function checkPlugin({ root, env = process.env, fetchImpl = globalThis.fetch, now = Date.now(), offline = false } = {}) {
+  const resolved = real(root);
+  if (!resolved) return { check: 'unavailable', reason: 'The plugin root does not exist.' };
+  const manifest = read(join(resolved, 'package.json'));
+  const current = manifest?.name === PLUGIN_PACKAGE && stableVersion(manifest.version) ? manifest.version : null;
+  const host = detectPluginHost(resolved);
+
+  const path = join(stateDirectory(env), 'plugin-latest.json');
+  const cached = read(path);
+  let record = cached;
+  if (!offline && !(cached && Number.isFinite(cached.checkedAt) && now >= cached.checkedAt && now - cached.checkedAt < DAY)) {
+    try {
+      const res = await fetchImpl(PLUGIN_SOURCE, { redirect: 'error', signal: AbortSignal.timeout(2000), headers: { Accept: 'application/json' } });
+      if (!res.ok) throw new Error('unavailable');
+      const text = await res.text();
+      if (text.length > 65536) throw new Error('too large');
+      const data = JSON.parse(text);
+      if (data.name !== PLUGIN_PACKAGE || !stableVersion(data.version)) throw new Error('invalid');
+      record = { checkedAt: now, version: data.version, available: true };
+    } catch { record = { checkedAt: now, version: stableVersion(cached?.version) ? cached.version : null, available: false }; }
+    try { saveJson(path, record); } catch { /* A read-only home must not prevent checking. */ }
+  }
+  const latest = stableVersion(record?.version) ? record.version : null;
+  const verified = !offline && record?.available === true;
+  // Skill folders copied by `npx skills add` carry no package.json, so their
+  // version is unknown; the update command is still the right advice.
+  const updateAvailable = Boolean(latest && (current ? compareVersions(latest, current) > 0 : host.kind === 'skills'));
+  return {
+    current, latest, check: verified ? 'verified' : 'unavailable', updateAvailable,
+    host: host.kind, ...(host.marketplace ? { marketplace: host.marketplace } : {}),
+    updateCommand: host.commands ? host.commands.map(([cmd, args]) => [cmd, ...args].join(' ')).join(' && ') : null,
+    reload: host.reload ?? null, ...(host.reason ? { reason: host.reason } : {}),
+    source: PLUGIN_SOURCE,
+  };
+}
+
+/** Run the host's own update commands. The host, not Sprid, writes its plugin cache. */
+export async function updatePlugin(root, { env = process.env, runner = runProcess } = {}) {
+  const host = detectPluginHost(real(root) ?? root);
+  if (!host.commands) throw new Error(host.reason || 'Cannot identify how these skills were installed.');
+  for (const [command, args] of host.commands) {
+    try { await runner(command, args, { cwd: env.HOME, env, timeout: 120000 }); }
+    catch { return { updated: false, failed: [command, ...args].join(' ') }; }
+  }
+  return { updated: true, reload: host.reload };
+}

package/src/telemetry.mjs

@@ -1,28 +1,41 @@
-// Usage telemetry: after a command finishes, one small POST to the Sprid API
+// Usage telemetry, two kinds, one switch.
+//
+// Command events: after a command finishes, one small POST to the Sprid API
 // saying which command ran, how it ended and how long it took. What is sent
 // is exactly `commandEvent`'s fields: the command, a subcommand only when it
 // is one this CLI documents, the exit code, an error KIND (an HTTP status or
 // usage/network/other, never the message), the duration, the CLI and Node
 // versions, the OS and whether it ran in CI. Never arguments, file paths,
-// slugs, output or anything read from disk.
+// slugs, output or anything read from disk. It goes to the API the CLI is
+// already signed in to, under the same login; signed out sends none.
+//
+// Install ping: at most once a day per surface, signed in or not, an
+// anonymous POST with exactly `installEvent`'s fields - a random id made on
+// this machine, the surface (cli, or the host the skills were installed
+// through when `doctor --plugin` ran), the CLI and skills versions, OS, Node,
+// CI and whether a login exists. No token, no account, no workspace. It is
+// how installs that never sign in get counted at all.
 //
-// It goes to the API the CLI is already signed in to, under the same login,
-// and nowhere else. Signed out means nothing is sent. Off with
-// `sprid telemetry off`, DO_NOT_TRACK=1 or SPRID_TELEMETRY=0. The first run
-// that could send only prints the notice; nothing leaves before the person
-// has been told.
+// Off with `sprid telemetry off`, DO_NOT_TRACK=1 or SPRID_TELEMETRY=0. The
+// first run that could send only prints the notice; nothing leaves before
+// the person has been told. The notice is versioned: someone told only about
+// command events is told again before the first install ping.
 
+import { randomUUID } from 'node:crypto';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { COMMAND_GROUPS } from './docs/commands.mjs';
 import { UsageError } from './args.mjs';
+import { DEFAULT_API_URL } from './creds.mjs';
 
 const SEND_TIMEOUT_MS = 1000;
 /** Commands that report nothing: they are about the CLI itself, or run for hours. */
 const SILENT = new Set(['help', 'version', 'completion', 'mcp', 'telemetry']);
 
-export const NOTICE = 'Sprid CLI sends usage telemetry to your Sprid account: the command name, exit code and duration, never arguments or file contents. Turn it off with `sprid telemetry off` or DO_NOT_TRACK=1.';
+export const NOTICE = 'Sprid CLI sends usage telemetry: once a day an anonymous install id with the CLI and skills versions, and when you are signed in each command\'s name, exit code and duration. Never arguments or file contents. Turn it off with `sprid telemetry off` or DO_NOT_TRACK=1.';
+/** Bumped when the notice starts covering something new. 1 covered command events only. */
+export const NOTICE_VERSION = 2;
 
 export function settingsPath(env = process.env) {
   return join(env.HOME || homedir(), '.sprid', 'telemetry.json');
@@ -47,7 +60,9 @@ export function telemetryState(env = process.env) {
   if (falsy(env.SPRID_TELEMETRY)) return { enabled: false, reason: 'SPRID_TELEMETRY is off' };
   const settings = readSettings(env);
   if (settings.enabled === false) return { enabled: false, reason: 'turned off with sprid telemetry off' };
-  return { enabled: true, reason: settings.enabled === true ? 'turned on with sprid telemetry on' : 'on by default', noticed: Boolean(settings.noticedAt) };
+  // A notice seen before versioning (noticedAt, no version) covered command events only.
+  const noticeVersion = settings.noticedAt ? (Number(settings.noticeVersion) || 1) : 0;
+  return { enabled: true, reason: settings.enabled === true ? 'turned on with sprid telemetry on' : 'on by default', noticed: noticeVersion >= 1, noticeVersion };
 }
 
 let documented;
@@ -92,34 +107,89 @@ export function commandEvent({ command, words, exitCode, durationMs, error, vers
   };
 }
 
+/** Prints the notice once per notice version and records it. True when it printed, so the run sends nothing. */
+function noticeFirst(ctx, state) {
+  if (state.noticeVersion >= NOTICE_VERSION) return false;
+  ctx.warn(`  ${NOTICE}`);
+  try { writeSettings({ ...readSettings(ctx.env), noticedAt: new Date().toISOString(), noticeVersion: NOTICE_VERSION }, ctx.env); } catch { /* A read-only home only means the notice repeats. */ }
+  return true;
+}
+
+async function post(ctx, url, body, headers = {}) {
+  const res = await ctx.fetch(url, {
+    method: 'POST',
+    redirect: 'error',
+    signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': `sprid/${ctx.version}`, ...headers },
+    body: JSON.stringify(body),
+  });
+  await res.body?.cancel?.().catch?.(() => {});
+  return res.ok;
+}
+
 /**
- * Report one finished command. Never throws and never waits longer than
- * SEND_TIMEOUT_MS: a slow network costs the person at most a second, and a
- * failure costs them nothing.
+ * Report one finished command: the install ping when today's is due, and the
+ * command event when signed in. Never throws and never waits longer than
+ * SEND_TIMEOUT_MS: the two requests run side by side, so a slow network costs
+ * the person at most a second, and a failure costs them nothing.
  */
 export async function reportCommand(ctx, { command, words, exitCode, durationMs, error }) {
   try {
     if (SILENT.has(command)) return false;
     const state = telemetryState(ctx.env);
     if (!state.enabled) return false;
-    let auth;
-    try { auth = ctx.auth(); } catch { return false; }
-    if (!state.noticed) {
-      ctx.warn(`  ${NOTICE}`);
-      try { writeSettings({ ...readSettings(ctx.env), noticedAt: new Date().toISOString() }, ctx.env); } catch { /* A read-only home only means the notice repeats. */ }
-      return false;
+    let auth = null;
+    try { auth = ctx.auth(); } catch { /* Signed out: the install ping still counts this machine. */ }
+    if (noticeFirst(ctx, state)) return false;
+    const sends = [reportInstall(ctx, { signedIn: Boolean(auth) })];
+    if (auth) {
+      const workspaceId = ctx._workspace?.id ?? auth.workspace?.id ?? null;
+      const event = commandEvent({ command, words, exitCode, durationMs, error, version: ctx.version, env: ctx.env, workspaceId });
+      sends.push(post(ctx, `${auth.apiUrl}/api/cli/events`, { events: [event] }, { Authorization: `Bearer ${auth.token}` }).catch(() => false));
     }
-    const workspaceId = ctx._workspace?.id ?? auth.workspace?.id ?? null;
-    const event = commandEvent({ command, words, exitCode, durationMs, error, version: ctx.version, env: ctx.env, workspaceId });
-    const res = await ctx.fetch(`${auth.apiUrl}/api/cli/events`, {
-      method: 'POST',
-      redirect: 'error',
-      signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
-      headers: { 'Content-Type': 'application/json', Accept: 'application/json', Authorization: `Bearer ${auth.token}`, 'User-Agent': `sprid/${ctx.version}` },
-      body: JSON.stringify({ events: [event] }),
-    });
-    await res.body?.cancel?.().catch?.(() => {});
-    return res.ok;
+    const results = await Promise.all(sends);
+    return results.some(Boolean);
+  } catch {
+    return false;
+  }
+}
+
+const today = (now = new Date()) => now.toISOString().slice(0, 10);
+
+/**
+ * The anonymous install ping. `surface` is `cli`, or the host the skills came
+ * through (`claude`, `codex`, `skills`) when `sprid doctor --plugin` reported
+ * one this run, which every Sprid skill does once per session.
+ */
+export function installEvent({ installId, version, plugin = null, signedIn, env = process.env, now = new Date() }) {
+  return {
+    installId,
+    // `unsupported` is a git checkout of the skills: ours, almost always, and kept apart.
+    surface: !plugin?.host ? 'cli' : plugin.host === 'unsupported' ? 'source' : plugin.host,
+    version,
+    pluginVersion: plugin?.current ?? null,
+    platform: process.platform,
+    node: process.version,
+    ci: Boolean(env.CI && !falsy(env.CI)),
+    signedIn: Boolean(signedIn),
+    at: now.toISOString(),
+  };
+}
+
+/** Sends today's ping for this surface if it has not gone yet. Caller has checked consent. */
+export async function reportInstall(ctx, { signedIn, now = new Date() }) {
+  try {
+    const settings = readSettings(ctx.env);
+    const installId = /^[0-9a-f-]{36}$/.test(settings.installId ?? '') ? settings.installId : randomUUID();
+    const event = installEvent({ installId, version: ctx.version, plugin: ctx.pluginInfo ?? null, signedIn, env: ctx.env, now });
+    const pinged = settings.pinged && typeof settings.pinged === 'object' ? settings.pinged : {};
+    if (pinged[event.surface] === today(now)) return false;
+    // Recorded before sending: a failed ping is not retried the same day,
+    // which keeps a machine offline all day from paying a timeout per command.
+    try { writeSettings({ ...settings, installId, pinged: { ...pinged, [event.surface]: today(now) } }, ctx.env); } catch { return false; }
+    let apiUrl = DEFAULT_API_URL;
+    try { apiUrl = ctx.auth().apiUrl; } catch { if (ctx.env.SPRID_URL) apiUrl = ctx.env.SPRID_URL; }
+    return await post(ctx, `${apiUrl}/api/installs/ping`, event);
   } catch {
     return false;
   }
@@ -129,12 +199,13 @@ export async function reportCommand(ctx, { command, words, exitCode, durationMs,
 export async function telemetry(ctx) {
   const action = ctx.positionals[0] ?? 'status';
   if (action === 'on' || action === 'off') {
-    writeSettings({ ...readSettings(ctx.env), enabled: action === 'on', noticedAt: readSettings(ctx.env).noticedAt ?? new Date().toISOString() }, ctx.env);
+    // Choosing on or off is having read what it does, so it counts as the current notice.
+    writeSettings({ ...readSettings(ctx.env), enabled: action === 'on', noticedAt: readSettings(ctx.env).noticedAt ?? new Date().toISOString(), noticeVersion: NOTICE_VERSION }, ctx.env);
   } else if (action !== 'status') {
     throw new UsageError(`Unknown telemetry action "${action}". Use status, on or off.`);
   }
   const state = telemetryState(ctx.env);
   if (ctx.json) ctx.out({ enabled: state.enabled, reason: state.reason, settings: settingsPath(ctx.env) });
-  else ctx.print(`  Telemetry is ${state.enabled ? 'on' : 'off'} (${state.reason}).${state.enabled ? ' Sent: command, exit code, duration, versions, OS. Never arguments or file contents.' : ''}`);
+  else ctx.print(`  Telemetry is ${state.enabled ? 'on' : 'off'} (${state.reason}).${state.enabled ? ' Sent: once a day an anonymous install id with versions and OS; signed in, each command, exit code and duration. Never arguments or file contents.' : ''}`);
   return 0;
 }

package/src/updates.mjs

@@ -110,6 +110,10 @@ function keyFor(installation) { return createHash('sha256').update(installation.
 export function autoEnabled(installation, env = process.env) {
   return read(join(stateDirectory(env), `${keyFor(installation)}.json`))?.auto === true;
 }
+/** Whether anyone has answered on/off for this installation, so an agent asks once. */
+export function autoDecided(installation, env = process.env) {
+  return typeof read(join(stateDirectory(env), `${keyFor(installation)}.json`))?.auto === 'boolean';
+}
 export function setAuto(installation, enabled, env = process.env) {
   if (installation.kind === 'unsupported') throw new Error(installation.reason);
   atomicJson(join(stateDirectory(env), `${keyFor(installation)}.json`), { auto: enabled });