trackly-cli 0.7.2 → 0.8.1

package/README.md

@@ -35,7 +35,7 @@ trackly jobs --function product
 
 ## At a Glance
 
-1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 21 local MCP tools
+1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 36 local MCP tools
 
 ## CLI Commands
 
@@ -54,6 +54,9 @@ trackly companies search "fintech"    # Semantic company search
 trackly search "fintech"              # Alias for semantic company search
 trackly stats                         # Show metrics
 trackly status                        # Alias for stats
+trackly preferences                   # Show discovery preferences and experience limits
+trackly preferences experience product=2 strategy=5  # Replace role-specific limits
+trackly preferences experience clear # Turn role-specific experience filtering off
 trackly apply 1234                    # Mark as applied
 trackly save 1234                     # Save a job
 trackly dismiss 1234                  # Dismiss a job
@@ -78,6 +81,8 @@ trackly agent doctor                 # Verify setup, profile, resume, and compat
 
 Add `--json` to any command for JSON output. Use `--api-key <key>` or `--base-url <url>` as one-off global flags when needed.
 
+`trackly preferences --json` returns only `success`, `experienceFilterV2Available`, and `preferences`. The availability flag controls whether this client may edit role-specific limits; it does not claim that feed or alert enforcement is active. Every update checks that flag and the latest preference revision before writing.
+
 ## MCP Server Setup
 
 ### Hosted (Claude co-work, Claude Desktop, ChatGPT)
@@ -160,6 +165,8 @@ Then use natural language in any of these clients:
 | trackly_search_companies | Semantic company search |
 | trackly_list_companies | List all tracked companies |
 | trackly_get_stats | Job tracker metrics and status counts |
+| trackly_get_preferences | Read bounded discovery preferences, edit availability, and save revision |
+| trackly_update_experience_limits | Atomically replace role-specific limits on a job's stated minimum years |
 | trackly_update_status | Mark jobs as applied, saved, or dismissed |
 | trackly_ask | Natural language job search (20/day) |
 | trackly_get_job_brief | Get network brief for a job (company signal, top contact, actions) |
@@ -170,11 +177,23 @@ Then use natural language in any of these clients:
 | trackly_get_application_profile | Get versioned profile answers and provenance |
 | trackly_get_profile_onboarding | Get schema plus missing questions |
 | trackly_update_application_profile | Save scoped answers with optimistic concurrency |
-| trackly_start_apply_run | Start a manual-submit browser run |
+| trackly_create_apply_batch | Freeze an exact recent-first approved batch |
+| trackly_get_active_apply_batch | Recover the newest unexpired active batch after context loss |
+| trackly_get_apply_batch | Read frozen membership with opaque pagination |
+| trackly_claim_apply_batch | Acquire or renew a batch mutation lease |
+| trackly_checkpoint_apply_batch | Bulk-record redacted inspection checkpoints and human actions |
+| trackly_bind_apply_surface | Bind an initial or recovered browser surface to the existing run and exact requisition URL |
+| trackly_record_apply_surface_evidence | Record current-epoch inventory, missing-tab, close-receipt, and post-close absence evidence |
+| trackly_record_apply_submission_evidence | Record redacted submit-request, success-page, user-confirmation, or provider-receipt evidence |
+| trackly_approve_apply_batch_resume | Approve one exact default resume for the current frozen run set |
+| trackly_certify_apply_batch_truth | Certify final answer and wording fingerprints after every other review-readiness gate |
+| trackly_start_apply_run | Start or reuse a manual-submit browser run |
 | trackly_get_apply_evidence | Get aggregate, value-free beta evidence and release readiness |
 | trackly_get_apply_protocol | Get current workflow and compatibility rules |
 | trackly_report_apply_observation | Send redacted ATS mechanics feedback |
+| trackly_report_apply_observations | Bulk-send up to 20 leased, batch-bound redacted observations |
 | trackly_record_application_outcome | Record review or confirmed submission outcome |
+| trackly_record_application_outcomes | Bulk-record up to 20 leased batch outcomes with per-member conflicts |
 | trackly_prepare_resume | Prepare a private expiring resume file for upload |
 | trackly_verify_prepared_resume | Recheck the confirmed resume immediately before attachment |
 
@@ -188,9 +207,15 @@ trackly login
 
 Opens your browser for Google sign-in. Tokens are stored locally at `~/.trackly/config.json`.
 
+Trackly is currently opening new memberships through a limited, invite-based
+rollout. Existing members can keep using OAuth and API keys normally. If a new
+account is not yet eligible, the CLI returns an invitation-specific message
+instead of suggesting repeated login attempts; request a future seat at
+[usetrackly.app/early-access](https://usetrackly.app/early-access).
+
 ### Option 2: API Key
 
-If OAuth doesn't work (firewalls, headless servers, CI), use an API key instead:
+Existing members can use an API key for firewalls, headless servers, or CI:
 
 1. Sign in at [usetrackly.app](https://usetrackly.app)
 2. Go to **Settings → API Keys → Create**
@@ -236,7 +261,7 @@ trackly config --base-url http://127.0.0.1:3000  # Point at a different backend
 | Job search + filters | Yes | Yes | Yes |
 | Apply/save/dismiss | Yes | Yes | Yes |
 | AI-powered search | Yes (trackly ask) | Yes | Yes |
-| MCP integration | Yes (20 local tools) | -- | -- |
+| MCP integration | Yes (36 local tools) | -- | -- |
 | Browser required | No | Yes | No |
 | Best for | Terminal + AI agents | Visual browsing | Custom integrations |
 
@@ -250,7 +275,7 @@ Install trackly-cli (`npm install -g trackly-cli`), authenticate with `trackly l
 
 **What MCP servers exist for job searching?**
 
-trackly-cli includes a built-in MCP server with 22 tools for job search, company lookup, application tracking, profile onboarding, beta evidence, and manual-submit form preparation. Run `trackly mcp` or use `trackly agent setup --client claude`.
+trackly-cli includes a built-in MCP server with 36 tools for job search, company lookup, discovery preferences, application tracking, frozen-batch orchestration, profile onboarding, beta evidence, and manual-submit form preparation. Run `trackly mcp` or use `trackly agent setup --client claude`.
 
 **How do I use Claude Code for job hunting?**
 

package/bin/trackly

@@ -5,6 +5,7 @@ const {
   DEFAULT_BASE_URL,
   apiRequest,
   clearConfig,
+  createTracklyAccessError,
   getApiKey,
   getAuthMethod,
   getBaseUrl,
@@ -65,6 +66,7 @@ const COMMAND_FLAGS = {
   search: [],
   stats: [],
   status: [],
+  preferences: [],
   apply: [],
   save: [],
   dismiss: [],
@@ -80,15 +82,32 @@ const COMMAND_FLAGS = {
   agent: ['client', 'window-days', 'target-reviewed-runs'],
 };
 const AUTH_HELP_TEXT = `Not authenticated.
-  Option 1: trackly login                        (Google OAuth)
-  Option 2: trackly config --api-key trk_xxx     (get key at usetrackly.app)
-  Option 3: TRACKLY_API_KEY=trk_xxx trackly ...  (environment variable)`;
+  Existing member: trackly login                 (Google OAuth)
+  Existing API key: trackly config --api-key trk_xxx
+  New member: Trackly is in a limited rollout. Request access at
+              https://usetrackly.app/early-access`;
 const STATUS_LABELS = {
   applied: 'applied',
   saved: 'saved',
   dismissed: 'dismissed',
 };
 const WORK_ARRANGEMENT_VALUES = ['remote', 'hybrid', 'in_person', 'unspecified'];
+const JOB_FUNCTIONS = [
+  'product', 'engineering', 'design', 'data', 'marketing', 'sales', 'partnerships',
+  'finance', 'strategy', 'operations', 'people', 'legal', 'support', 'other',
+];
+
+function loginAccessError(code) {
+  return createTracklyAccessError({ code });
+}
+
+function writeLoginProgress(message) {
+  if (isJSON()) {
+    console.error(message);
+  } else {
+    console.log(message);
+  }
+}
 
 function parseArgs(args) {
   const result = { _: [], command: null };
@@ -225,15 +244,20 @@ function formatMaintenanceForHuman(maintenance) {
 
 function setApiErrorExit(error, fallbackMessage, exitCode = 1) {
   const maintenance = maintenanceOutput(error);
-  if (!maintenance) {
-    setErrorExit(error?.error || error?.message || fallbackMessage, exitCode);
-    return;
-  }
-
-  if (isJSON()) {
+  const accessError = createTracklyAccessError(error, error?.status);
+  if (isJSON() && accessError) {
+    printJson({
+      status: accessError.status,
+      code: accessError.code,
+      message: accessError.message,
+      retryable: accessError.retryable,
+    });
+  } else if (maintenance && isJSON()) {
     printJson(maintenance);
-  } else {
+  } else if (maintenance) {
     outputError(formatMaintenanceForHuman(maintenance));
+  } else {
+    outputError(error?.error || error?.message || fallbackMessage);
   }
   process.exitCode = exitCode;
 }
@@ -252,6 +276,39 @@ function parseJobId(value) {
   return id;
 }
 
+function parseExperienceLimits(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error('Provide at least one role limit or `clear` (for example, `product=2 strategy=5`).');
+  }
+  if (values.includes('clear')) {
+    if (values.length !== 1) throw new Error('`clear` cannot be combined with role limits.');
+    return {};
+  }
+
+  const limits = {};
+  for (const value of values) {
+    const match = /^([^=]+)=([^=]+)$/.exec(String(value));
+    if (!match) throw new Error(`Invalid limit "${value}". Use role=years (for example, product=2).`);
+    const jobFunction = match[1].trim().toLowerCase();
+    const rawYears = match[2].trim();
+    if (!JOB_FUNCTIONS.includes(jobFunction)) {
+      throw new Error(`Unknown job function "${jobFunction}". Use: ${JOB_FUNCTIONS.join(', ')}.`);
+    }
+    if (Object.prototype.hasOwnProperty.call(limits, jobFunction)) {
+      throw new Error(`Duplicate limit for ${jobFunction}. Provide each job function once.`);
+    }
+    if (!/^\d+$/.test(rawYears)) {
+      throw new Error(`Limit for ${jobFunction} must be an integer from 0 to 60.`);
+    }
+    const years = Number(rawYears);
+    if (!Number.isInteger(years) || years < 0 || years > 60) {
+      throw new Error(`Limit for ${jobFunction} must be an integer from 0 to 60.`);
+    }
+    limits[jobFunction] = years;
+  }
+  return limits;
+}
+
 // Flags deprecated in the API-docs-plan fixup. Still accepted by parseArgs so old
 // scripts don't ERR_NOT_FOUND, but cmdJobs hard-rejects them with a migration hint
 // — silent no-op would be worse than noise (per PR #13 Codex P1 finding).
@@ -321,11 +378,11 @@ function getPublicConfig() {
 
 // -- Commands --
 
-async function cmdLogin() {
+async function cmdLogin({ openUrl = openExternalUrl } = {}) {
   const baseUrl = getBaseUrl();
   const state = crypto.randomBytes(16).toString('hex');
 
-  console.log(color('cyan', 'Opening browser for Google login...'));
+  writeLoginProgress(color('cyan', 'Opening browser for Google login...'));
 
   let activeServer = null;
 
@@ -348,6 +405,21 @@ async function cmdLogin() {
 
           const token = url.searchParams.get('token');
           const refreshToken = url.searchParams.get('refreshToken');
+          const accessError = loginAccessError(url.searchParams.get('error'));
+          if (accessError) {
+            res.writeHead(403, {
+              'Content-Type': 'text/html',
+              'Referrer-Policy': 'no-referrer',
+              'Cache-Control': 'no-store',
+            });
+            res.end('<html><body><h2>Trackly access is limited right now.</h2><p>Return to your terminal for next steps.</p></body></html>');
+            const loginError = new Error(accessError.message);
+            loginError.code = accessError.code;
+            loginError.status = accessError.status;
+            loginError.retryable = accessError.retryable;
+            settle(loginError);
+            return;
+          }
           if (token) {
             const config = loadConfig();
             const hadApiKey = Boolean(config.apiKey);
@@ -382,9 +454,9 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
 </div>
 </body>
 </html>`);
-            console.log(color('green', 'Login successful!'));
+            writeLoginProgress(color('green', 'Login successful!'));
             if (hadApiKey) {
-              console.log('Switched to OAuth. Stored API key cleared.');
+              writeLoginProgress('Switched to OAuth. Stored API key cleared.');
             }
             settle();
           } else {
@@ -405,10 +477,12 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
 
         const finish = () => {
           if (error) {
-            console.log('\nLogin failed. Try API key auth instead:');
-            console.log('  1. Sign in at https://usetrackly.app');
-            console.log('  2. Go to Settings → API Keys → Create');
-            console.log('  3. Run: trackly config --api-key <your-key>');
+            if (!createTracklyAccessError(error, 403)) {
+              writeLoginProgress('\nLogin failed. Existing members can try API key auth:');
+              writeLoginProgress('  1. Sign in at https://usetrackly.app');
+              writeLoginProgress('  2. Go to Settings → API Keys → Create');
+              writeLoginProgress('  3. Run: trackly config --api-key <your-key>');
+            }
             reject(error);
           } else {
             resolve();
@@ -436,10 +510,10 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
           settle(new Error(`OS assigned an out-of-range callback port (${port}); expected 1024-65535.`));
           return;
         }
-        console.log(color('dim', `Callback server on port ${port}`));
+        writeLoginProgress(color('dim', `Callback server on port ${port}`));
         const loginUrl = `${baseUrl}/auth/google/cli?port=${port}&state=${state}`;
-        if (!openExternalUrl(loginUrl)) {
-          console.log(`Open this URL in your browser:\n${loginUrl}`);
+        if (!openUrl(loginUrl)) {
+          writeLoginProgress(`Open this URL in your browser:\n${loginUrl}`);
         }
       });
 
@@ -461,6 +535,7 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
   process.on('SIGINT', onSigint);
   try {
     await tryLogin();
+    if (isJSON()) printJson({ success: true, authMethod: 'oauth' });
   } finally {
     process.removeListener('SIGINT', onSigint);
   }
@@ -612,6 +687,119 @@ async function cmdStats() {
   }
 }
 
+function renderPreferences(result) {
+  const user = result?.user || {};
+  const preferences = user.preferences || result?.preferences || {};
+  const limits = preferences.experienceLimitsByJobFunction || {};
+
+  console.log(color('bold', 'Discovery preferences'));
+  const selected = Array.isArray(preferences.wantedJobFunctions)
+    ? preferences.wantedJobFunctions
+    : [];
+  console.log(`  Target roles: ${selected.length > 0 ? selected.join(', ') : 'All roles'}`);
+  console.log(`  Experience limits: ${Object.keys(limits).length > 0 ? 'Configured' : 'Not configured'}`);
+  for (const [jobFunction, years] of Object.entries(limits)) {
+    console.log(`    ${jobFunction}: Up to ${years} year${years === 1 ? '' : 's'} required`);
+  }
+  console.log(color('dim', '  Jobs with no stated minimum remain visible.'));
+  console.log(color('dim', '  This confirms what you saved; it does not show whether Trackly is currently applying the limits.'));
+  if (Number.isSafeInteger(preferences.discoveryPreferenceRevision)) {
+    console.log(color('dim', `  Revision: ${preferences.discoveryPreferenceRevision}`));
+  }
+}
+
+function projectPreferenceResponse(result, experienceFilterV2Available = null) {
+  const user = result?.user || {};
+  return {
+    success: result?.success === true,
+    experienceFilterV2Available: experienceFilterV2Available === null
+      ? user.experienceFilterV2Available === true
+      : experienceFilterV2Available === true,
+    preferences: user.preferences || result?.preferences || {},
+  };
+}
+
+function handlePreferenceConflict(error) {
+  const message = 'Preferences changed on another device. Review `trackly preferences`, then run the update again.';
+  if (isJSON()) {
+    printJson({
+      status: error.status,
+      code: error.error,
+      message,
+      preferences: error.preferences,
+      discoveryPreferenceRevision: error.discoveryPreferenceRevision,
+    });
+  } else {
+    outputError(message);
+  }
+  process.exitCode = 1;
+}
+
+async function cmdPreferences(args) {
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
+  const subcommand = args._[0];
+  if (subcommand == null || subcommand === 'show') {
+    if (args._.length > (subcommand === 'show' ? 1 : 0)) {
+      failNow('Usage: trackly preferences [show]');
+    }
+    try {
+      const result = await apiRequest('GET', '/api/jobscout/me');
+      if (isJSON()) return printJson(projectPreferenceResponse(result));
+      renderPreferences(result);
+      return;
+    } catch (error) {
+      setApiErrorExit(error, 'Failed to fetch preferences');
+      return;
+    }
+  }
+
+  if (subcommand !== 'experience') {
+    failNow('Unknown preferences subcommand. Use: trackly preferences [show] | trackly preferences experience <role=years...|clear>');
+  }
+
+  let experienceLimitsByJobFunction;
+  try {
+    experienceLimitsByJobFunction = parseExperienceLimits(args._.slice(1));
+  } catch (error) {
+    failNow(error.message);
+  }
+
+  try {
+    // Read immediately before the write and send the authoritative revision.
+    // The backend rejects a stale value with 409 instead of letting this
+    // process overwrite a newer iOS, web, macOS, CLI, or MCP save.
+    const current = await apiRequest('GET', '/api/jobscout/me');
+    if (current?.user?.experienceFilterV2Available !== true) {
+      failNow('Role-specific experience preferences are not available for this account yet. No changes were saved.');
+    }
+    const expectedPreferenceRevision = current?.user?.preferences?.discoveryPreferenceRevision;
+    if (!Number.isSafeInteger(expectedPreferenceRevision) || expectedPreferenceRevision < 0) {
+      failNow('Trackly did not return a valid preference revision. No changes were saved.');
+    }
+
+    const result = await apiRequest('PUT', '/api/jobscout/preferences', {
+      experienceLimitsByJobFunction,
+      experienceFilterVersion: 2,
+      expectedPreferenceRevision,
+    });
+    if (isJSON()) return printJson(projectPreferenceResponse(result, true));
+    console.log(color(
+      'green',
+      Object.keys(experienceLimitsByJobFunction).length > 0
+        ? 'Role-specific experience limits updated.'
+        : 'Role-specific experience filtering turned off.',
+    ));
+    renderPreferences(result);
+  } catch (error) {
+    if (error?.status === 409 && error?.error === 'preference_revision_conflict') {
+      handlePreferenceConflict(error);
+      return;
+    }
+    setApiErrorExit(error, 'Failed to update experience limits');
+  }
+}
+
 const ACTION_TO_COMMAND = { applied: 'apply', saved: 'save', dismissed: 'dismiss' };
 
 // CLI surface accepts applied|saved|dismissed (legacy human-friendly terms).
@@ -971,6 +1159,8 @@ async function cmdAgent(args) {
     console.log(color('bold', 'Trackly Apply doctor'));
     console.log(`Overall: ${color(report.ok ? 'green' : 'yellow', report.ok ? 'ready' : 'needs attention')}`);
     console.log(`Authenticated: ${report.authenticated ? 'yes' : 'no'}`);
+    console.log(`CLI: ${report.cliVersion}; MCP contract: ${report.mcpContractVersion}`);
+    console.log(`Skill: ${report.skillVersion}; digest: ${report.skillPackIntegrity.expectedDigest || 'unavailable'}`);
     console.log(`Protocol: ${report.protocol?.version || 'unavailable'}; compatible=${report.compatible ? 'yes' : 'no'}`);
     console.log(`Semantic browser + computer use: ${report.browserControl.semanticReady ? 'ready' : 'not verified'}`);
     for (const client of report.clients) {
@@ -1064,6 +1254,8 @@ ${color('bold', 'Commands:')}
   ${color('cyan', 'search <query>')}       Semantic company search
   ${color('cyan', 'stats')}                Show metrics dashboard
   ${color('cyan', 'status')}               Alias for stats
+  ${color('cyan', 'preferences')}          Show discovery preferences
+  ${color('cyan', 'preferences experience')} Replace role limits (role=years; clear turns off)
   ${color('cyan', 'apply <id>')}           Mark job as applied
   ${color('cyan', 'save <id>')}            Save a job
   ${color('cyan', 'dismiss <id>')}         Dismiss a job
@@ -1095,6 +1287,10 @@ ${color('bold', 'Flags:')}
 ${color('bold', 'Filter values:')}
   --function       product, engineering, design, data, marketing, sales, partnerships,
                    finance, strategy, operations, people, legal, support, other (comma-separated)
+  experience limits use the same role values, for example:
+                   trackly preferences experience product=2 strategy=5
+                   When enforcement is active, includes jobs whose stated minimum is up to the limit.
+                   Jobs with no stated minimum remain visible.
   --region         us, non_us, all, or a region tag (europe, canada, remote, ...)
                    Use a comma-separated list of region tags for multiple regions;
                    us/non_us/all cannot be combined.
@@ -1208,6 +1404,9 @@ async function main() {
     case 'status':
       await cmdStats();
       break;
+    case 'preferences':
+      await cmdPreferences(args);
+      break;
     case 'apply':
       await cmdUpdateStatus(args._[0], 'applied');
       break;
@@ -1276,14 +1475,18 @@ if (require.main === module) {
 module.exports = {
   COMMAND_FLAGS,
   UNIVERSAL_FLAGS,
+  cmdLogin,
   formatMaintenanceForHuman,
   getPublicConfig,
   hasJobListFilters,
   levenshtein,
+  loginAccessError,
   main,
   nearestFlag,
   normalizeBaseUrlValue,
   openExternalUrl,
   parseArgs,
+  parseExperienceLimits,
   parseJobId,
+  writeLoginProgress,
 };

package/contracts/trackly-apply-tools.json

@@ -1,22 +1,41 @@
 {
-  "contractVersion": "3.2.0",
+  "contractVersion": "3.3.1",
   "constants": {
     "applyScenarioCodes": ["browser_reclaim", "resume_upload", "resume_parser_recheck", "semantic_boolean_commit", "custom_select_commit", "multi_step_navigation", "free_text_voice", "required_error_sweep", "final_consent", "handoff_reclaim", "critical_contact_integrity", "manual_submit_boundary", "job_identity_match"],
-    "applyBrowserSurfaces": ["codex_in_app", "chrome_extension", "claude_in_chrome"]
+    "applyBrowserSurfaces": ["codex_in_app", "chrome_extension", "claude_in_chrome"],
+    "applyCheckpointActionCodes": ["answer/unknown", "auth/sign_in", "auth/otp", "captcha/before_form", "captcha/at_submit", "artifact/upload_required", "legal/decision_required", "consent/decision_required", "review/manual_submit", "trust/origin_mismatch", "observability/unverifiable_state"],
+    "applyCheckpointPacketPhases": ["first_pass", "delta"],
+    "applySurfaceBindingReasons": ["initial_binding", "recovery_binding"],
+    "applySurfaceEvidenceTypes": ["surface_inventory_reconciled", "surface_missing", "surface_close_attempted", "surface_close_receipt", "surface_post_close_absent", "surface_close_failed"],
+    "applySurfaceOwnershipStates": ["controller_owned", "user_owned", "controller_user_union", "unresolved"],
+    "applySubmissionEvidenceTypes": ["request_accepted", "confirmation_detected", "provider_receipt_detected"],
+    "applySubmissionEvidenceSources": ["submission_request", "success_page", "user_confirmation", "provider_receipt", "post_submit_receipt"]
   },
   "tools": {
-    "trackly_get_apply_queue": "{limit:z.number().int().min(1).max(100).optional()}",
+    "trackly_get_apply_queue": "{limit:z.number().int().min(1).max(100).optional(),cursor:z.string().min(1).max(2048).optional()}",
     "trackly_get_application_profile": "{includeSensitive:z.boolean().optional(),provider:z.string().max(100).optional(),companyId:z.string().max(100).optional()}",
     "trackly_get_profile_onboarding": "{}",
     "trackly_update_application_profile": "{expectedRevision:z.number().int().min(1),source:z.enum(['web','ios','macos','codex','claude','mcp']).optional(),changes:z.array(z.discriminatedUnion('scope',[z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('global'),questionLabel:z.string().max(1000).optional()}),z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('provider'),scopeValue:z.string().min(1).max(200),questionLabel:z.string().max(1000).optional()}),z.object({key:z.string().min(1).max(200),state:z.enum(['unknown','answered','intentionally_blank','declined']),value:z.any().optional(),scope:z.literal('company'),scopeValue:z.string().min(1).max(200),questionLabel:z.string().max(1000).optional()})])).max(100).optional(),education:z.array(z.object({school:z.string().min(1).max(500),degree:z.string().max(500).nullable().optional(),fieldOfStudy:z.string().max(500).nullable().optional(),gpa:z.string().max(50).nullable().optional(),startDate:z.string().max(50).nullable().optional(),endDate:z.string().max(50).nullable().optional()})).max(20).optional(),confirmProfile:z.boolean().optional(),sensitiveStorageConsent:z.boolean().optional()}",
-    "trackly_start_apply_run": "{jobId:z.number().int().min(1),clientName:z.string().max(100).optional()}",
+    "trackly_create_apply_batch": "{limit:z.number().int().min(1).max(100),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_get_active_apply_batch": "{limit:z.number().int().min(1).max(APPLY_BATCH_MAX_MEMBERS).optional(),cursor:z.string().min(1).max(2048).optional(),actionLimit:z.number().int().min(1).max(APPLY_BATCH_MAX_MEMBERS).optional(),actionCursor:z.string().min(1).max(2048).optional()}",
+    "trackly_get_apply_batch": "{batchId:z.number().int().min(1),limit:z.number().int().min(1).max(APPLY_BATCH_MAX_MEMBERS).optional(),cursor:z.string().min(1).max(2048).optional(),actionLimit:z.number().int().min(1).max(APPLY_BATCH_MAX_MEMBERS).optional(),actionCursor:z.string().min(1).max(2048).optional()}",
+    "trackly_claim_apply_batch": "{batchId:z.number().int().min(1),expectedRevision:z.number().int().min(1),leaseOwner:z.string().min(1).max(1024),leaseToken:z.string().min(1).max(1024),leaseDurationMs:z.number().int().min(15000).max(300000)}",
+    "trackly_checkpoint_apply_batch": "{batchId:z.number().int().min(1),leaseToken:z.string().min(1).max(1024),checkpoints:z.array(z.object({memberId:z.number().int().min(1),runId:z.number().int().min(1),expectedMemberVersion:z.number().int().min(1),expectedInspectionEpoch:z.number().int().min(0),inspectionEpoch:z.number().int().min(0),packetPhase:z.enum(APPLY_CHECKPOINT_PACKET_PHASES).optional(),knownFieldsCommitted:z.boolean(),resolvedActionIds:z.array(z.string().regex(/^[1-9][0-9]*$/)).max(APPLY_BATCH_MAX_ACTIONS_PER_CHECKPOINT).optional(),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY),actions:z.array(z.object({actionCode:z.enum(APPLY_CHECKPOINT_ACTION_CODES),continuationAllowed:z.boolean(),fieldFingerprint:z.string().regex(/^[a-f0-9]{64}$/).optional()})).min(1).max(APPLY_BATCH_MAX_ACTIONS_PER_CHECKPOINT)})).min(1).max(APPLY_BATCH_MAX_CHECKPOINTS_PER_REQUEST)}",
+    "trackly_bind_apply_surface": "{batchId:z.number().int().min(1),memberId:z.number().int().min(1),runId:z.number().int().min(1),expectedMemberVersion:z.number().int().min(1),expectedInspectionEpoch:z.number().int().min(0),leaseToken:z.string().min(1).max(1024),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/),browserSurface:z.enum(APPLY_BROWSER_SURFACES),adapterCode:z.string().regex(SAFE_OBSERVATION_CODE),bindingReason:z.enum(APPLY_SURFACE_BINDING_REASONS),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_record_apply_surface_evidence": "{batchId:z.number().int().min(1),memberId:z.number().int().min(1),runId:z.number().int().min(1),expectedMemberVersion:z.number().int().min(1),expectedInspectionEpoch:z.number().int().min(1),leaseToken:z.string().min(1).max(1024),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/),browserSurface:z.enum(APPLY_BROWSER_SURFACES),adapterCode:z.string().regex(SAFE_OBSERVATION_CODE),ownershipState:z.enum(APPLY_SURFACE_OWNERSHIP_STATES),completeInventory:z.boolean(),evidenceType:z.enum(APPLY_SURFACE_EVIDENCE_TYPES),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_record_apply_submission_evidence": "{batchId:z.number().int().min(1),memberId:z.number().int().min(1),runId:z.number().int().min(1),expectedMemberVersion:z.number().int().min(1),expectedInspectionEpoch:z.number().int().min(1),leaseToken:z.string().min(1).max(1024),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/),evidenceType:z.enum(APPLY_SUBMISSION_EVIDENCE_TYPES),evidenceSource:z.enum(APPLY_SUBMISSION_EVIDENCE_SOURCES),evidenceFingerprint:z.string().regex(/^[a-f0-9]{64}$/),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_approve_apply_batch_resume": "{batchId:z.number().int().min(1),leaseToken:z.string().min(1).max(1024),membershipHash:z.string().regex(/^[a-f0-9]{64}$/),profileRevision:z.number().int().min(0),resumeId:z.number().int().min(1),resumeSha256:z.string().regex(/^[a-f0-9]{64}$/),resumeFilename:z.string().min(1).max(255),resumeSizeBytes:z.number().int().min(1),memberRuns:z.array(z.object({memberId:z.number().int().min(1),runId:z.number().int().min(1),memberVersion:z.number().int().min(1),inspectionEpoch:z.number().int().min(0)})).min(1).max(100),expiresAt:z.string().datetime(),idempotencyKey:z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY)}",
+    "trackly_certify_apply_batch_truth": "truthCertificationSchema",
+    "trackly_start_apply_run": "startApplyRunSchema",
     "trackly_get_apply_evidence": "{windowDays:z.number().int().min(1).max(365).optional(),targetReviewedRuns:z.number().int().min(1).max(1000).optional()}",
     "trackly_get_apply_protocol": "{}",
-    "trackly_report_apply_observation": "{runId:z.number().int().min(1),provider:z.string().regex(SAFE_OBSERVATION_CODE),fieldLabel:z.string().min(1).max(1000),observationType:z.string().regex(SAFE_OBSERVATION_CODE),resolutionCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),metadata:z.object({controlType:z.string().regex(SAFE_OBSERVATION_CODE).optional(),required:z.boolean().optional(),errorCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),committed:z.boolean(),scenarioCode:z.enum(APPLY_SCENARIO_CODES),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/).optional(),resumedAfterHandoff:z.boolean().optional()})}",
-    "trackly_record_application_outcome": "{runId:z.number().int().min(1),outcome:z.enum(['review_ready','submitted','failed','blocked']),confirmation:z.string().max(500).optional()}",
+    "trackly_report_apply_observation": "{runId:z.number().int().min(1),batchId:z.number().int().min(1).optional(),memberId:z.number().int().min(1).optional(),inspectionEpoch:z.number().int().min(0).optional(),leaseToken:z.string().min(1).max(1024).optional(),provider:z.string().regex(SAFE_OBSERVATION_CODE),fieldLabel:z.string().min(1).max(1000),observationType:z.string().regex(SAFE_OBSERVATION_CODE),resolutionCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),metadata:z.object({controlType:z.string().regex(SAFE_OBSERVATION_CODE).optional(),required:z.boolean().optional(),errorCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),committed:z.boolean(),scenarioCode:z.enum(APPLY_SCENARIO_CODES),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/).optional(),resumedAfterHandoff:z.boolean().optional()})}",
+    "trackly_report_apply_observations": "{observations:z.array(z.object({runId:z.number().int().min(1),batchId:z.number().int().min(1),memberId:z.number().int().min(1),inspectionEpoch:z.number().int().min(0),leaseToken:z.string().min(1).max(1024),provider:z.string().regex(SAFE_OBSERVATION_CODE),fieldLabel:z.string().min(1).max(1000),observationType:z.string().regex(SAFE_OBSERVATION_CODE),resolutionCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),metadata:z.object({controlType:z.string().regex(SAFE_OBSERVATION_CODE).optional(),required:z.boolean().optional(),errorCode:z.string().regex(SAFE_OBSERVATION_CODE).optional(),committed:z.boolean(),scenarioCode:z.enum(APPLY_SCENARIO_CODES),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/).optional(),resumedAfterHandoff:z.boolean().optional()})})).min(1).max(APPLY_BATCH_MAX_BULK_MUTATIONS)}",
+    "trackly_record_application_outcome": "{runId:z.number().int().min(1),batchId:z.number().int().min(1).optional(),memberId:z.number().int().min(1).optional(),inspectionEpoch:z.number().int().min(0).optional(),leaseToken:z.string().min(1).max(1024).optional(),outcome:z.enum(['review_ready','submitted','failed','blocked']),confirmation:z.enum(['user_confirmation','success_page']).optional()}",
+    "trackly_record_application_outcomes": "{outcomes:z.array(z.object({runId:z.number().int().min(1),batchId:z.number().int().min(1),memberId:z.number().int().min(1),inspectionEpoch:z.number().int().min(0),leaseToken:z.string().min(1).max(1024),outcome:z.enum(['review_ready','submitted','failed','blocked']),confirmation:z.enum(['user_confirmation','success_page']).optional()})).min(1).max(APPLY_BATCH_MAX_BULK_MUTATIONS)}",
     "trackly_prepare_resume": "{runId:z.number().int().min(1),browserSurface:z.enum(APPLY_BROWSER_SURFACES),browserBindingHash:z.string().regex(/^[a-f0-9]{64}$/)}",
     "trackly_verify_prepared_resume": {
-      "local": "{runId:z.number().int().min(1),confirmationId:z.string().min(1).max(200),exactLocalPath:z.string().min(1).max(4096),sha256:z.string().regex(/^[a-f0-9]{64}$/i),sizeBytes:z.number().int().min(1),expiresAt:z.string().datetime()}",
+      "local": "{runId:z.number().int().min(1),resumeId:z.number().int().min(1),confirmationId:z.string().min(1).max(200),exactLocalPath:z.string().min(1).max(4096),sha256:z.string().regex(/^[a-f0-9]{64}$/i),sizeBytes:z.number().int().min(1),expiresAt:z.string().datetime()}",
       "hosted": "{runId:z.number().int().min(1),confirmationId:z.string().min(1).max(200)}"
     }
   }

package/docs/trackly-tools.md

@@ -65,6 +65,11 @@ trackly config --api-key trk_xxxxxxxxxxxxxxxxxxxx
 
 You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
 
+Existing memberships work across the CLI and local MCP server. New memberships
+are invite-only during the limited rollout; access errors link to
+https://usetrackly.app/early-access instead of recommending repeated OAuth or
+API-key creation attempts.
+
 ### Available Tools
 
 - **trackly_search_jobs** — Search/filter jobs.
@@ -82,6 +87,12 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
 - **trackly_search_companies** — Semantic company search
 - **trackly_list_companies** — List all tracked companies with job counts
 - **trackly_get_stats** — Job tracker metrics dashboard
+- **trackly_get_preferences** — Read a bounded preference response containing only `success`, `experienceFilterV2Available`, and the authenticated user's discovery `preferences`, including selected roles, saved role-specific limits, and the revision required for a safe update. Availability authorizes editing; it does not report feed or alert enforcement.
+- **trackly_update_experience_limits** — Atomically replace the complete role-specific experience-limit map.
+  - `experienceLimitsByJobFunction`: object whose keys are the 14 canonical job-function values and whose values are integer years from `0` through `60`. An empty object turns this filter off.
+  - `expectedPreferenceRevision`: non-negative safe integer from the latest `trackly_get_preferences` result. A stale revision is rejected; refetch and reconcile with the user rather than retrying blindly.
+  - The tool checks `experienceFilterV2Available` immediately before writing and refuses without a PUT unless it is exactly `true`.
+  - When server-side enforcement is active, a job remains visible when its stated minimum is less than or equal to that role's limit. Jobs with no stated minimum remain visible.
 - **trackly_update_status** — Mark a job as applied, saved, or dismissed
 - **trackly_ask** — Natural language job search (20/day limit)
 - **trackly_get_job_brief** — Get network brief for a job (company signal, top contact, actions)
@@ -92,15 +103,27 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
 - **trackly_get_application_profile** — Get the versioned, scoped application profile.
 - **trackly_get_profile_onboarding** — Get backend-owned questions plus only missing/unconfirmed answers.
 - **trackly_update_application_profile** — Save explicit answer states with optimistic concurrency and global/provider/company scope.
-- **trackly_start_apply_run** — Start a manual-submit browser run for a queued job.
+- **trackly_create_apply_batch** — Freeze an exact recent-first set of approved jobs with an idempotency key.
+- **trackly_get_active_apply_batch** — Recover the newest unexpired active batch before creating another after chat or browser context loss.
+- **trackly_get_apply_batch** — Page a server-owned frozen batch without reordering or replacing members.
+- **trackly_claim_apply_batch** — Acquire or renew the optimistic browser-mutation lease.
+- **trackly_checkpoint_apply_batch** — Bulk-record up to 20 value-free inspection checkpoints, typed human actions, and per-member conflicts.
+- **trackly_bind_apply_surface** — Bind an initial or recovered browser surface to the existing frozen member/run, increment its inspection epoch, and return the exact stored requisition URL.
+- **trackly_record_apply_surface_evidence** — Record current-epoch, value-free inventory, missing-tab, close-receipt, post-close absence, or close-failure evidence.
+- **trackly_record_apply_submission_evidence** — Record typed, redacted submit-request, success-page, explicit user-confirmation, or provider-receipt evidence without page text or external references.
+- **trackly_approve_apply_batch_resume** — Approve one exact default-resume identity and content hash for the complete current frozen run set.
+- **trackly_certify_apply_batch_truth** — Record an expiring late truthfulness certification over final answer and wording fingerprints after every other review-readiness gate has passed.
+- **trackly_start_apply_run** — Start or reuse a manual-submit browser run with the complete frozen batch/member/lease binding.
 - **trackly_get_apply_evidence** — Get the authenticated user's aggregate beta evidence and release gate without returning profile answers or contact values.
 - **trackly_get_apply_protocol** — Get the current ATS support, browser integrity rules, and compatible skill version.
 - **trackly_report_apply_observation** — Report redacted ATS mechanics and actual scenario coverage without answer values or page text.
+- **trackly_report_apply_observations** — Bulk-report up to 20 leased, current-epoch, batch-bound redacted observations in one request.
 - **trackly_record_application_outcome** — Record review readiness or a confirmed manual submission.
+- **trackly_record_application_outcomes** — Bulk-record up to 20 leased, batch-bound outcomes while returning per-member conflicts explicitly.
 - **trackly_prepare_resume** — Local MCP only: materialize the default resume in a private, expiring mode-0600 cache and return filename, size, SHA-256, exact local path, and visual-confirmation metadata. Hosted MCP returns a manual/local-agent requirement.
 - **trackly_verify_prepared_resume** — Local MCP only: immediately before attachment, recompute the user-confirmed resume hash and size, validate the exact path/run/expiration, and lock the file read-only. Any mismatch requires a fresh preview and confirmation.
 
-Apply contract v3 intentionally gives this verifier different local and hosted schemas: local MCP receives the full proof needed to inspect the private file, while hosted MCP accepts only run and confirmation identifiers and returns the manual/local-agent requirement. Local paths and fingerprints are never sent to the hosted verifier. Version 3.1 also records universal value-free evidence for critical-contact integrity and the manual-submit boundary. Version 3.2 authorizes the exact stored HTTPS origin for jobs Trackly ingested from employer careers sources, without granting redirect, iframe, or hostname-suffix privileges.
+Apply contract v3 intentionally gives this verifier different local and hosted schemas: local MCP receives the full proof needed to inspect the private file, while hosted MCP accepts only run and confirmation identifiers and returns the manual/local-agent requirement. Local paths are never sent remotely. Resume fingerprints are sent only to authenticated Trackly resume approval and truth-certification endpoints, never observations or employer forms. Version 3.1 also records universal value-free evidence for critical-contact integrity and the manual-submit boundary. Version 3.2 authorizes the exact stored HTTPS origin for jobs Trackly ingested from employer careers sources, without granting redirect, iframe, or hostname-suffix privileges. Version 3.3.1 adds active-batch recovery, epoch-bound observations/outcomes, and truth certification for forms with no resume control.
 
 ### Maintenance behavior
 
@@ -114,4 +137,5 @@ REST, refresh, download, CLI, and local/hosted MCP surfaces use canonical `code:
 - "What remote engineering roles are available?"
 - "Show me jobs at Stripe"
 - "Mark job 1234 as applied"
+- "Show my Trackly preferences, then set Product to up to 2 years and Strategy to up to 5 years"
 - "Use Trackly Apply to fill my next saved application and stop before Submit"