trackly-cli 0.20.0 → 0.21.0

package/README.md

@@ -121,7 +121,7 @@ trackly agent setup --client codex    # or claude / both
 trackly agent doctor
 ```
 
-For an existing MCP configuration or a Cloud harness, use `trackly agent setup --client both --skills-only`. This installs the same checksummed skill for both native clients without invoking their MCP commands or changing authentication. CLI 0.20.0 carries universal skill 4.9.0; its policy revision is the same numeric version, superseding the personal revisions. The policy accepts a documented `markHandoff()` guarantee with awaited calls, exact current tab checks, and revalidation on later turns. These observations are never reported as returned persistence receipts. Browser capabilities and manual Submit remain separate requirements; installation does not make a Linux browser supported. The separately installed `trackly:trackly-apply` plugin is updated through its plugin manager; plugin 1.1.0 carries the same browser and profile lookup policies. This setup command does not patch plugin caches.
+For an existing MCP configuration or a Cloud harness, use `trackly agent setup --client both --skills-only`. This installs the same checksummed skill for both native clients without invoking their MCP commands or changing authentication. CLI 0.20.1 carries universal skill 4.9.1; its policy revision is the same numeric version, superseding the personal revisions. The policy accepts a documented `markHandoff()` guarantee with awaited calls, exact current tab checks, and revalidation on later turns. These observations are never reported as returned persistence receipts. Browser capabilities and manual Submit remain separate requirements; installation does not make a Linux browser supported. The separately installed `trackly:trackly-apply` plugin is updated through its plugin manager; plugin 1.1.1 carries the same browser and profile lookup policies. This setup command does not patch plugin caches.
 
 The skill uses the profile and default resume in your Trackly account, asks only missing questions, fills user-approved saved jobs, and always stops before Submit. “Fill the next N” continues through the original recent-first Check Later snapshot until N unauthenticated forms are durably ready for your manual review; authentication walls and exclusions are reported separately and do not consume the target. An explicit “inspect the next N records” request still uses one fixed immutable batch. Support is fetched from Trackly at the start of every run: Greenhouse is full, Ashby and Lever are best effort, and 27 additional named ATS/provider classes use constrained guided mode. Employer-hosted unknown forms run only when Trackly binds them to a verified company domain. LinkedIn-hosted forms and unverified origins remain manual-only; a separately stored external application URL is evaluated under its own ATS and origin policy.
 
@@ -175,6 +175,30 @@ Then use natural language in any of these clients:
 - "What remote engineering roles are available?"
 - "Mark job 1234 as applied"
 
+### Search filters and updates
+
+`trackly_search_jobs` supports multiple roles and regions, US states and Canadian
+provinces, internship education levels, favorite companies, posting windows,
+annual USD salary floors, incremental sync, work arrangement, sponsorship and
+pipeline status. [Exact values and examples](docs/trackly-tools.md#available-tools).
+Search returns 20 jobs by default; request up to 100 and use `offset` to page.
+
+For sponsorship, “exclude no” keeps yes **and not mentioned**. Use `exclude_no`;
+`only_yes` excludes jobs with unknown sponsorship. Ask the user when intent is
+ambiguous. Salary floors also keep unknown and non-comparable salaries visible.
+Unsupported industry/specialization/literal-search controls are rejected.
+
+For a local server without a global package install, run `npx -y trackly-cli mcp`.
+For Codex, use `codex mcp add trackly -- npx -y trackly-cli mcp`; Cursor and
+Windsurf can use `"command": "npx", "args": ["-y", "trackly-cli", "mcp"]`.
+Authenticate with `npx -y trackly-cli login` first, or configure `TRACKLY_API_KEY`.
+
+Existing global installs require `npm install --global trackly-cli@latest`.
+Restart the MCP process/client and refresh tool discovery after updating.
+For native skills and marketplace plugin updates, follow the
+[release and update guide](docs/release-verification.md#existing-public-users).
+Hosted and local releases are separate: the current client schema is authoritative.
+
 ## MCP Tools Reference
 
 The local stdio server (`trackly mcp`) registers the 58 tools below. Four are
@@ -185,7 +209,7 @@ The hosted server omits those four and adds `trackly_chat`, for 55 hosted tools.
 
 | Tool | Description |
 |------|-------------|
-| trackly_search_jobs | Search and filter jobs by function, company, region, employment type, work arrangement, visa sponsorship, and status |
+| trackly_search_jobs | Search by roles, regions, states/provinces, internship level, favorites, recency, annual USD salary floor, sponsorship, work arrangement, and pipeline status |
 | trackly_get_job | Get full details for a specific job |
 | trackly_search_companies | Semantic company search |
 | trackly_list_companies | List all tracked companies |

package/bin/trackly

@@ -885,7 +885,7 @@ async function cmdAsk(args) {
     if (result.jobsUrl) {
       // Path allowlist: /ask can return any string for jobsUrl. normalizeEndpoint already
       // blocks cross-origin fetches (baseUrl mismatch), but a compromised backend could
-      // still emit a same-origin path like `/api/admin/secret-dump`. Restrict to the two
+      // still emit an unrelated privileged same-origin path. Restrict to the two
       // legitimate handlers that /ask is designed to route to.
       const JOBS_URL_ALLOWLIST = /^\/api\/(v1|jobscout)\/jobs(\?|$)/;
       if (!JOBS_URL_ALLOWLIST.test(result.jobsUrl)) {

package/docs/plans/2026-08-05-001-trackly-apply-durable-recovery-reconciliation-plan.md

@@ -16,7 +16,7 @@ execution: code
 
 - **Objective:** Make Trackly Apply recover the exact interrupted jobs, preserve cumulative completion, reconcile every member in a submitted handoff, and fail closed around browser cleanup and resume upload.
 - **Authority:** The backend owns membership, lifecycle, completion credit, idempotency, and current state. The browser harness owns live DOM evidence and local tab identity. The user owns Submit, credentials, verification challenges, and ambiguous answers.
-- **Execution profile:** Deep, cross-repository reliability work in `close-ai` and `trackly-cli`. Use fresh worktrees from current `origin/main`; keep base checkouts read-only.
+- **Execution profile:** Deep, cross-repository reliability work in the private backend and `trackly-cli`. Use fresh worktrees from current `origin/main`; keep base checkouts read-only.
 - **Stop conditions:** Stop browser mutation on unexpected recovery membership, stale inspection authority, ambiguous submission state, incomplete tab inventories, unproven attachment state, or incompatible protocol versions.
 - **Tail ownership:** Merge and deploy the backend first. Then publish and install the compatible CLI and skill. Finish with no-submit fixtures and a manually submitted dogfood recovery flow.
 
@@ -168,7 +168,7 @@ None of these receipts implies another.
 
 ### Success Criteria
 
-- The faithful Postgres sequence from the August 5 incident passes without projection contradictions.
+- The faithful database sequence from the August 5 incident passes without projection contradictions.
 - Exact recovery never mutates `saved_at`, never substitutes newer jobs, and never uses old-epoch evidence.
 - Every grouped submission report produces one result per handoff member.
 - No finalizer call receives an empty or partial keep set when expected tabs exist.
@@ -208,7 +208,7 @@ None of these receipts implies another.
 ### Key Technical Decisions
 
 - KTD1. **Persist completion credit in an append-only achievement ledger.** (session-settled: user-approved — chosen over concurrent unsubmitted inventory: once a job is ready or submitted it remains part of the requested total.) Create one value-free credit per `(execution_id, user_id, frozen_job_id)`, constrained to reviewed sources such as `review_ready` and `submitted_repair`. Insert the credit in the same transaction as the durable outcome. Expose `achievementCount` as the raw unique effective-credit count and compute target-facing `completed = LEAST(achievementCount, target)`. Credits are the sole target-achievement input; current ready/submitted counts remain operator projections. Do not add mutable columns to immutable execution candidates. A credit later proven to originate from invalid evidence may be neutralized only by an append-only compensating revocation through an audited internal repair operation; later submission or lifecycle change is never a revocation reason. Governs R1-R3.
-- KTD2. **Characterize the live state sequence before changing accounting.** Current unit tests already cover `ready + submitted`, so implementation begins with a Postgres-backed checkpoint, certification, bulk-outcome, submission, and progress-read reproduction. A passing unit calculator test is not sufficient evidence. Governs R1-R3, R8.
+- KTD2. **Characterize the live state sequence before changing accounting.** Current unit tests already cover `ready + submitted`, so implementation begins with a database-backed checkpoint, certification, bulk-outcome, submission, and progress-read reproduction. A passing unit calculator test is not sufficient evidence. Governs R1-R3, R8.
 - KTD3. **Model exact recovery as a new execution mode over stable source candidates.** The original August 5 decision used `recover_exact_members` with `sourceExecutionId`, exact execution-candidate IDs proven inside the source snapshot hash, optimistic revision, and idempotency key. It persisted `source_execution_id`, `source_candidate_id`, and the attempt-specific `source_member_id` when present; identity assertion was atomic, eligibility could be partial (superseded—see the shipped-contract addendum immediately below), and the server created no substitutes. Governs R4-R7.
 
   **Shipped-contract addendum (2026-08-13):** Backend implementation and adversarial review superseded partial eligibility with an atomic all-or-nothing eligibility check. If any confirmed candidate is no longer eligible, the server creates no recovery execution and no substitutes. AE4 and U4 below reflect this shipped contract while the original decision remains recorded here.
@@ -221,7 +221,7 @@ None of these receipts implies another.
 - KTD10. **Reuse resume approval only with exact lineage.** A recovery may reuse execution-scoped content approval only when the backend proves the same resume hash, profile revision, snapshot lineage, and unexpired approval. Every run still performs immediate local file verification. Otherwise the user approves the resume again. Governs R16, R22.
 - KTD11. **Ship additive coordinated versions.** Expected releases are Apply protocol 3.6.0, MCP contract 3.7.0, skill 4.5.0, and CLI 0.14.0. Recompute versions and migration maximum immediately before implementation. Older active work keeps its published recovery path. Governs R20-R22.
 - KTD12. **Persist request-key idempotency for outcomes.** Single and bulk outcomes require an idempotency key. Atomically store operation type, canonical payload hash, and exact item results; exact retries return those saved results. Current-state inference remains a bounded repair fallback, not the primary replay mechanism. Governs R8-R12.
-- KTD13. **Retain recovery identity beyond operational expiry.** Add `recoverable_until`, computed by PostgreSQL from `expires_at` plus 30 calendar days. The stored value is immutable and cannot be extended. Daily purge may delete source execution data only after that boundary. Record only value-free interruption-to-resume duration metrics. Purge for the new mode remains feature-flagged until dogfood/private-beta evidence is reviewed and the product owner approves the 30-day recovery SLO; until then, retain the additive recovery manifest under normal account-retention rules. Governs R4-R7, R23.
+- KTD13. **Retain recovery identity beyond operational expiry.** Add `recoverable_until`, computed by the database from `expires_at` plus 30 calendar days. The stored value is immutable and cannot be extended. Daily purge may delete source execution data only after that boundary. Record only value-free interruption-to-resume duration metrics. Purge for the new mode remains feature-flagged until dogfood/private-beta evidence is reviewed and the product owner approves the 30-day recovery SLO; until then, retain the additive recovery manifest under normal account-retention rules. Governs R4-R7, R23.
 
 ### High-Level Technical Design
 
@@ -285,7 +285,7 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 | Recovery reuses stale browser evidence | Increment inspection epoch and require fresh binding, identity, contact, and review evidence. |
 | A group phrase marks the wrong jobs submitted | Resolve it to an exact handoff receipt; inspect every staged member; ask only about unresolved members. |
 | Provider strategy becomes remote executable browser code | Publish bounded declarative strategy enums and semantic evidence requirements only. |
-| Completion credit and current ready counts drift | Update/read them under the same owner lock and assert invariants in Postgres integration tests. |
+| Completion credit and current ready counts drift | Update/read them under the same owner lock and assert invariants in database integration tests. |
 | Operational expiry destroys exact recovery identity | Separate execution expiry from bounded recovery retention and purge only after `recoverable_until`. |
 | Old clients misread the new execution mode | Roll out compatible readers first; they must recognize or safely reject `recover_exact_members` before writes are enabled. |
 | Local tab helper creates a false sense of visibility | Return set-safety only; keep user-visible presentation as a separate receipt. |
@@ -300,8 +300,8 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 
 - **Goal:** Reproduce the production accounting and review-replay failure before changing persistent state.
 - **Requirements:** R1-R3, R8, AE1-AE2.
-- **Repositories:** `close-ai`.
-- **Files:** `src/services/application-profile/__tests__/apply-execution-service.test.ts`, `src/services/application-profile/__tests__/service.test.ts`, and a Postgres integration test beside the existing application-profile integration fixtures.
+- **Repositories:** the private backend.
+- **Files:** backend execution-service tests, backend application-profile tests, and a database integration test beside the existing application-profile integration fixtures.
 - **Approach:** Exercise real execution, batch, member, run, evidence, and attestation rows through checkpoint, truth certification, bulk review outcome, one submission, and progress read. Assert both current counts and cumulative status. Preserve the existing pure calculator test as a smaller unit check.
 - **Test scenarios:** Exact duplicate review intent; stale epoch; one of two submitted; both submitted; ambiguous transport followed by refetch; concurrent submit and advance.
 - **Verification:** At least one characterization fails on pre-fix code for the same durable state mismatch observed in the incident.
@@ -311,19 +311,19 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 - **Goal:** Make target achievement durable and independent from later lifecycle or attestation projection changes.
 - **Requirements:** R1-R3, R13, AE1.
 - **Dependencies:** U1.
-- **Repositories:** `close-ai`.
-- **Files:** next sequential migration, migration runner/test if required by index strategy, `src/services/application-profile/batch-service.ts`, `src/services/application-profile/service.ts`, application-profile service tests.
+- **Repositories:** the private backend.
+- **Files:** next sequential migration, migration runner/test if required by index strategy, backend batch service, backend application-profile service, application-profile service tests.
 - **Approach:** Create a separate append-only achievement ledger rather than weakening immutable candidate rows. Insert one owner-bound credit with `ON CONFLICT DO NOTHING` only after durable review outcome or authorized submission repair, in the same transaction as execution status. Expose raw `achievementCount`, compute target-facing `completed = LEAST(achievementCount, target)`, and retain current `durablyReviewReady` and `submitted` for operator detail. Make credit the sole target-achievement input. Before migration, produce a dry-run report grouped by provable source predicate and ambiguous exclusion reason. Backfill every provable submitted row with authorized evidence, or review-ready row with an `awaiting_manual_submit` run and matching active truth attestation for the certified epoch/set; do not discard valid historical overflow above target.
 - **Test scenarios:** Credit set once; submission preserves credit; sibling submission does not reduce total; profile/attestation changes do not erase credit; concurrent writers cannot double-credit; account/execution deletion cascades correctly; ambiguous legacy rows remain uncredited; valid historical overflow remains visible; invalid-evidence revocation is append-only, audited, and cannot be triggered by ordinary lifecycle change.
-- **Verification:** AE1 passes in pure and Postgres-backed tests, and an advance after target achievement produces no child wave. Before historical writes, a migration-owner review must approve per-predicate counts, sampled source evidence, and ambiguous-exclusion totals; any sample mismatch ships prospective crediting only and defers backfill.
+- **Verification:** AE1 passes in pure and database-backed tests, and an advance after target achievement produces no child wave. Before historical writes, a migration-owner review must approve per-predicate counts, sampled source evidence, and ambiguous-exclusion totals; any sample mismatch ships prospective crediting only and defers backfill.
 
 ### U3. Make review outcomes replay-safe and projections explicit
 
 - **Goal:** Return existing durable milestones for exact replay and make historical/current state legible.
 - **Requirements:** R8-R9, R13, AE2.
 - **Dependencies:** U1-U2.
-- **Repositories:** `close-ai`.
-- **Files:** `src/services/application-profile/service.ts`, `src/routes/trackly-apply.ts`, route/runtime tests, service tests, batch projection tests.
+- **Repositories:** the private backend.
+- **Files:** backend application-profile service, backend Apply HTTP routes, route/runtime tests, service tests, batch projection tests.
 - **Approach:** Require an idempotency key for single and bulk outcomes. Extract a transaction-aware outcome writer, acquire the orchestration-owner lock, process bulk items in canonical member order with per-item savepoints, and persist the canonical request hash plus every item result in the same outer transaction. Return results in original request order; exact retries return `transition=replayed` from the stored result journal. Preserve partial bulk successes. State inference remains a bounded fallback for repairs created before request idempotency. Create a first-class execution-owned handoff receipt only after the ordered ready set is durable. Add explicit historical and current projection fields without mutating old rows.
 - **Test scenarios:** Exact replay; mismatched epoch; mismatched member; partial bulk replay/commit/conflict; old batch with current submitted run; repeated request after lost transport response.
 - **Verification:** Identical replay performs no version/event mutation and returns `awaiting_manual_submit`; historical views cannot be mistaken for actionable current state.
@@ -333,8 +333,8 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 - **Goal:** Reauthorize only explicitly requested eligible jobs after an expired or terminal execution.
 - **Requirements:** R4-R7, R13, R23, AE3-AE4, AE8.
 - **Dependencies:** U2-U3.
-- **Repositories:** `close-ai`.
-- **Files:** `src/services/application-profile/apply-execution-contract.ts`, `src/services/application-profile/batch-service.ts`, `src/services/application-profile/service.ts`, `src/routes/trackly-apply.ts`, `src/mcp/server.ts`, execution service/route/MCP contract tests.
+- **Repositories:** the private backend.
+- **Files:** backend execution contract, backend batch service, backend application-profile service, backend Apply HTTP routes, backend hosted MCP registry, execution service/route/MCP contract tests.
 - **Approach:** Add an authenticated discovery read returning only the user's recoverable execution IDs, snapshot hashes, stable candidate IDs, bounded lifecycle/eligibility codes, and expiry. It must not return profile values, browser data, or local paths. After explicit exact-set confirmation, create recovery with source execution, stable execution-candidate list, source snapshot hash, and idempotency key. Validate ownership and no competing mutable execution under the documented lock order. Evaluate eligibility for the entire asserted source set before creation; if any confirmed candidate is ineligible, fail atomically without creating an execution or substituting another candidate. When all are eligible, preserve source execution/candidate/member lineage, create one immutable non-replenishing recovery execution for the exact confirmed set, and require fresh epochs and browser bindings. Separate operational expiry from a bounded recovery-retention boundary so the nightly purge cannot erase eligible identity mid-window.
 - **Test scenarios:** Complete local context loss followed by discovery; cross-user discovery rejection; explicit exact-set confirmation; newer queue candidates present; saved timestamps unchanged; wholly eligible set; mixed eligible/applied/inactive set rejected with no execution; duplicate IDs; changed requisition; foreign user; concurrent identical recovery; concurrent different recovery; old evidence rejected; second interruption; recovery immediately before and after operational expiry; recovery after daily purge but before `recoverable_until`; rejection after retention expiry.
 - **Verification:** AE3-AE4 pass; AE4 explicitly proves that an ineligible confirmed member yields zero recovery executions, and every execution created by an eligible case has a response membership hash that exactly matches the full asserted source set.
@@ -344,7 +344,7 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 - **Goal:** Make exact recovery and handoff receipts safely callable from hosted and local agents.
 - **Requirements:** R7, R9-R10, R19-R22.
 - **Dependencies:** U3-U4.
-- **Repositories:** `close-ai`, then `trackly-cli`.
+- **Repositories:** the private backend, then `trackly-cli`.
 - **Files:** backend protocol route and hosted MCP schemas; `mcp/apply-tools.js`, contract history/fixture, `docs/trackly-tools.md`, MCP schema and hosted-contract tests, package changelog/version files.
 - **Approach:** First ship compatible readers that recognize or safely reject `recover_exact_members`; only then enable writes behind a feature flag. Advertise protocol capability and additive versions. Add public recovery-discovery and exact-recovery tools and result schemas. Include requested-set hash, stable candidate eligibility, fresh-epoch requirements, cumulative `completed`, handoff receipt, and persisted transition result. Keep local-only helpers out of hosted parity expectations through the existing documented exception pattern.
 - **Test scenarios:** Compatible and incompatible clients; hosted/local public-schema equality; cross-user rejection; replay response; missing capability; older active execution recovery.
@@ -355,7 +355,7 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 - **Goal:** Reconcile every job in the exact staged handoff after the user reports submission.
 - **Requirements:** R9-R13, R19, R21-R22, AE5.
 - **Dependencies:** U3, U5.
-- **Repositories:** `close-ai`, `trackly-cli`.
+- **Repositories:** the private backend, `trackly-cli`.
 - **Files:** backend ATS capability/protocol definitions; `skills/trackly-apply/SKILL.md`; `skills/trackly-apply/references/ats-playbook.md`, `review-handoff.md`, `batch-orchestration.md`, `form-integrity.md`; prompt-resource and contract tests.
 - **Approach:** Publish bounded provider strategy enums. Define the local `DetectedSubmission` boundary and require the skill to resolve group language to a handoff receipt, inspect each member's live DOM, classify each as `detected`, `user_confirmed`, `unresolved`, or `contradictory`, record positive evidence through the existing backend writer, preserve unmatched members, and ask once only for unresolved submission authority. URL/title remain identity and navigation signals only.
 - **Test scenarios:** Greenhouse redirect; Ashby unchanged route/banner; Lever redirect and same-route confirmation; one of two succeeds; both succeed quickly; explicit user confirmation preserves stronger stored evidence; contradictory “already applied” state.
@@ -377,7 +377,7 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 - **Goal:** Make recovery state and the next human/agent action obvious while completing cross-repository release gates.
 - **Requirements:** R7, R19-R22.
 - **Dependencies:** U1-U7.
-- **Repositories:** `close-ai`, `trackly-cli`.
+- **Repositories:** the private backend, `trackly-cli`.
 - **Files:** `skills/trackly-apply/references/review-handoff.md`, browser lifecycle/recovery references, MCP prompt resources, changelogs, release notes, doctor/consumer tests.
 - **Approach:** Add deterministic normal-review, recovery, visibility-unverified, upload-manual, and post-submission templates. Each recovery template shows tab, form, and authority receipts separately. Deploy/migrate backend, verify live protocol, publish/install CLI and canonical skill, run doctor, then dogfood exact recovery and grouped reconciliation without agent submission.
 - **Test scenarios:** Restart with blank forms; restored tab with expired authority; unresolved auth member; upload unavailable; one staged member unresolved; no active work; older compatible active execution.
@@ -389,11 +389,11 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 
 | Gate | Repository | Command or check | Required result |
 |---|---|---|---|
-| Type safety | `close-ai` | `npm run typecheck` | No TypeScript errors. |
-| Build | `close-ai` | `npm run build` | Production bundle succeeds. |
-| Lint | `close-ai` | `npm run lint` | No lint errors in changed code. |
-| Targeted Apply tests | `close-ai` | Run the application-profile service, execution, route, MCP-contract, migration, and new Postgres integration test files with Vitest | Every lifecycle and concurrency scenario passes. |
-| Full backend suite | `close-ai` | `npm test` | Full suite passes. |
+| Type safety | the private backend | `npm run typecheck` | No TypeScript errors. |
+| Build | the private backend | `npm run build` | Production bundle succeeds. |
+| Lint | the private backend | `npm run lint` | No lint errors in changed code. |
+| Targeted Apply tests | the private backend | Run the application-profile service, execution, route, MCP-contract, migration, and new database integration test files with Vitest | Every lifecycle and concurrency scenario passes. |
+| Full backend suite | the private backend | `npm test` | Full suite passes. |
 | CLI tests | `trackly-cli` | `npm test` | Full Node test suite passes. |
 | CLI contract fixture | `trackly-cli` | `npm run test:contract-fixture` | Skill and MCP contract assertions pass. |
 | Hosted/local parity | `trackly-cli` | `npm run test:hosted-contract` | Public tool schemas match the deployed backend; only documented local helpers differ. |
@@ -449,10 +449,10 @@ The backend owns durable identity, membership, milestones, and reconciliation. T
 
 ### Current implementation anchors
 
-- `close-ai:src/services/application-profile/batch-service.ts` owns parent executions, immutable child waves, access dispositions, and the pure progress calculator.
-- `close-ai:src/services/application-profile/service.ts` reconstructs progress, records outcomes, applies evidence repair, and updates current job state.
-- `close-ai:src/routes/trackly-apply.ts` owns authenticated HTTP contracts.
-- `close-ai:src/mcp/server.ts` owns hosted MCP schemas and prompt resources.
+- backend batch service owns parent executions, immutable child waves, access dispositions, and the pure progress calculator.
+- backend application-profile service reconstructs progress, records outcomes, applies evidence repair, and updates current job state.
+- backend Apply HTTP routes own authenticated HTTP contracts.
+- backend hosted MCP registry owns hosted MCP schemas and prompt resources.
 - `trackly-cli:mcp/apply-tools.js` owns local/hosted HTTP wrappers and local-only helpers.
 - `trackly-cli:skills/trackly-apply/` owns reusable browser mechanics.
 

package/docs/release-verification.md

@@ -0,0 +1,107 @@
+# Trackly release verification
+
+This checklist is mandatory for every Trackly CLI upgrade. A release makes the
+current Trackly tools available in its public packages and deployed MCP surfaces;
+installation verification proves that the named environments are using it.
+Release closeout requires both. Keep publication, installation and authenticated
+browser readiness as separate states.
+
+## Before publication
+
+- Record the intended npm CLI version, MCP contract version, native Apply skill
+  version, plugin version, plugin adaptation lock and any required harness pins.
+  These identifiers belong to different packages and need not share a number.
+- Run the repository CI checks: tests, dependency audit and audit policy, checked-in
+  hosted contract, plugin submission preflight and package smoke test.
+- When tools or schemas change, compare the final backend candidate with
+  the test:hosted-contract npm script and TRACKLY_BACKEND_DIR set to its checkout.
+  Verify complete tool names and input schemas, including the reviewed differences
+  between local MCP, hosted MCP and the plugin facade. Equal tool counts alone
+  do not establish parity; distinct facade allowlists must remain intact.
+- Coordinate the CLI and backend owners and update cloud installer pins and their
+  captured tool-contract fixtures through the normal reviewed PR workflow.
+
+## Published artifacts and live tools
+
+- Verify the exact merged commit, GitHub release, npm latest version, published
+  tarball integrity and provenance attestations. Check successful npm and MCP
+  Registry publication steps rather than relying only on a release tag.
+- Inspect the published tarball, rather than only the source checkout. Verify
+  CLI/server versions, dependency declarations against the source lock, MCP code
+  and native skill contents. Boot
+  the published MCP server and obtain the full paginated tools/list inventory.
+  Compare tool names and input schemas against the intended release contract.
+- Check the production hosted MCP and plugin facade with approved existing
+  authentication. Verify their complete discoverable tools and schemas and the
+  deployed backend contract. Source fixtures and unauthenticated HTTP challenges
+  do not prove authenticated live discovery. Do not run application mutations or
+  paid AI calls as release probes.
+- Verify the plugin manifest and adaptation lock against the installed package.
+  A newer Git marketplace package does not prove that a separately reviewed
+  plugin catalog or connector listing has been updated. Record its actual
+  submission, approval and publication state independently.
+
+## Installation matrix
+
+Record a fresh receipt for each target below. Include its account and environment
+identity, timestamp with time zone, npm package/CLI version, supported Node
+runtime, actual MCP server version, complete tool names and schema digest, native
+skill version and file hashes, installed plugin version and lock hashes, and any
+applicable harness version. Keep credentials and profile answers out of receipts.
+
+| Target | Required evidence |
+| --- | --- |
+| M1 | Verify the actual application account and its installed package, native skills, plugin and MCP discovery; an SSH login to another account is insufficient. |
+| M4 | Verify the installed package, native skills, plugin manager result and MCP discovery. |
+| Conductor Cloud image | Verify the successful active build, exact merged installer source, pinned package/plugin versions and MCP schema checks. |
+| Conductor retained homes | Verify each in-scope retained home separately; rebuilding the shared image does not update them. Enumerate any dormant or archived homes left unverified. |
+| Current Codex Cloud | Verify the signed-in account, actual helper outputs, saved and published environment revision, then installation and MCP discovery in a restored workspace. A setup-chat success alone is insufficient. |
+
+Use the client plugin manager to update installed plugins; never patch versioned
+plugin caches. Verify all applicable clients that consume the package. Where a
+client supports native skills instead of this plugin format, record that
+difference and verify the native skill. A genuinely unsupported plugin manager,
+missing authentication or unreachable environment is an explicit verification
+gap, not a passing result. Preserve unrelated settings and report intentional
+configuration changes separately from configuration preservation checks.
+
+## Existing public users
+
+An existing global npm install remains at its installed version until updated.
+The supported local update sequence is:
+
+~~~sh
+npm install --global trackly-cli@latest
+trackly --version
+trackly agent setup --client both --skills-only
+trackly agent doctor
+~~~
+
+The skills-only setup preserves existing MCP registration and authentication.
+Users with one client can select codex or claude. Restart the configured local
+MCP server or its client after updating, refresh discovery, and verify the new
+server version and tools. A running old process keeps the old tool implementation.
+Check the actual Node runtime against the package engines requirement.
+
+For the official Git marketplace plugin, use the documented Codex plugin manager:
+
+~~~sh
+# Register the official marketplace once, if it is not already configured.
+codex plugin marketplace add trackly-app/trackly-cli --ref main
+codex plugin marketplace upgrade trackly-cli
+codex plugin add trackly@trackly-cli --json
+~~~
+
+Verify the returned installed version and package hashes, then reload the client.
+Other plugin catalogs follow their own supported update and approval lifecycle.
+Hosted MCP users receive the deployed server implementation; reconnect or refresh
+client discovery after a tool change and verify the intended authenticated surface.
+
+## Closeout
+
+Attach the release version set, published artifact evidence, live tool-contract
+checks, installation matrix, changed-configuration checks and remaining gaps to
+the release record. Every applicable row must pass before claiming global parity.
+When only package publication is verified, report publication; when installations
+are verified but live discovery is unavailable, report that narrower result.
+An upgrade remains incomplete until required verification gaps are resolved.

package/docs/solutions/integration-issues/analytics-must-preserve-strict-mcp-schemas.md

@@ -0,0 +1,39 @@
+---
+title: Analytics instrumentation must preserve strict MCP schemas
+category: integration-issues
+module: MCP analytics
+component: observability
+date: 2026-10-19
+problem_type: integration_issue
+severity: medium
+symptoms:
+  - Unsupported search arguments reached the handler without an MCP validation error
+  - Unknown controls disappeared when optional analytics context was installed
+root_cause: missing_validation
+resolution_type: code_fix
+applies_when:
+  - Adding fields to registered MCP tool schemas
+  - Wrapping tools with optional analytics context
+tags: [mcp, analytics, zod, strict-schema, sdk]
+---
+
+The MCP SDK's registered-tool `update({ paramsSchema })` shape API rebuilds an
+object schema. With SDK 1.32.1 this loses the strict/catchall policy of a real Zod
+object. An unsupported search control can therefore disappear before the
+handler, leaving a successful response to a different request.
+
+Extend an existing object schema with its own `extend` method and update the
+callback separately. Preserve the shape-based path only for SDK-created empty
+Mini schemas that do not expose `extend`. Strip the optional analytics context
+before calling the business handler, while retaining all original validation.
+
+The regression must use a real MCP client and linked server transport with
+analytics enabled. A schema-only assertion before instrumentation cannot expose
+this defect. Send an unknown argument and assert an MCP error plus zero handler
+calls. Also check that valid calls, optional context, strict/catchall policies,
+and tools without input fields remain compatible.
+
+Verification: `node --test test/mcp-analytics.test.js test/mcp-schema.test.js`
+and `npm test`. The real transport regression failed with the old instrumentation
+and passed after the fix. Keyword telemetry continues to retain length only;
+this change does not permit raw query or context storage.

package/docs/solutions/integration-issues/backend-owned-sensitive-answer-deletion-guard.md

@@ -40,7 +40,7 @@ Adding more checks to every caller would not close the version-skew hole. Compat
 
 ## Solution
 
-Move the mandatory challenge-and-confirm invariant to the backend operation that performs the deletion, then keep MCP callers as thin protocol adapters. The backend implementation is outside this repository; internal/private [close-ai PR #1296](https://github.com/trackly-app/close-ai/pull/1296) and public [trackly-cli PR #90](https://github.com/trackly-app/trackly-cli/pull/90) record the service-authoritative design.
+Move the mandatory challenge-and-confirm invariant to the backend operation that performs the deletion, then keep MCP callers as thin protocol adapters. The backend implementation is recorded in private repositories; public [trackly-cli PR #90](https://github.com/trackly-app/trackly-cli/pull/90) documents the service-authoritative design.
 
 The current CLI publishes `sensitiveRevocationConfirmToken` in the tool schema and forwards the complete request to the application-profile endpoint:
 
@@ -67,7 +67,7 @@ Every backend-classified agent caller, including stale CLI and MCP versions, mus
 
 The separation also removes semantic duplication. The backend owns the authoritative deletion decision, confirmation validity, revision binding, archive behavior, and mutation. MCP owns discoverability and transport: publish the token field, explain the two-step interaction, preserve the full request, and relay the service response.
 
-Internal/private [close-ai issue #1314](https://github.com/trackly-app/close-ai/issues/1314) remains administratively open, but current backend main appears to satisfy its scoped-inventory acceptance criteria through merged internal/private [close-ai PR #1369](https://github.com/trackly-app/close-ai/pull/1369): the service inventories sensitive and restricted rows across scopes, serializes scope identity into `affectedKeys`, and uses the same user-and-sensitivity predicate for archival and deletion. Close the issue only after confirming the fix is deployed and behaviorally verified; an open tracker alone is not evidence of a current functional gap.
+Private backend tracking records indicate that the scoped-inventory work remains administratively open, but current backend main appears to satisfy its acceptance criteria: the service inventories sensitive and restricted rows across scopes, serializes scope identity into `affectedKeys`, and uses the same user-and-sensitivity predicate for archival and deletion. Close the issue only after confirming the fix is deployed and behaviorally verified; an open tracker alone is not evidence of a current functional gap.
 
 ## Prevention
 
@@ -83,6 +83,6 @@ Internal/private [close-ai issue #1314](https://github.com/trackly-app/close-ai/
 
 - [trackly-cli PR #89](https://github.com/trackly-app/trackly-cli/pull/89) — initial caller-owned guard, retained as the superseded attempt
 - [trackly-cli PR #90](https://github.com/trackly-app/trackly-cli/pull/90) — thin caller relay and service-authoritative correction
-- Internal/private [close-ai PR #1296](https://github.com/trackly-app/close-ai/pull/1296) — backend enforcement recorded by the coordinated fix
-- Internal/private [close-ai issue #1314](https://github.com/trackly-app/close-ai/issues/1314) and [close-ai PR #1369](https://github.com/trackly-app/close-ai/pull/1369) — tracker still open; current main contains the scoped-inventory fix pending deployment/behavior confirmation
+- Private backend records document enforcement in the coordinated fix
+- Private scoped-inventory tracking remains open pending deployment and behavior confirmation
 - [Durable exact recovery after browser state loss](durable-exact-recovery-after-browser-state-loss.md) — related Trackly Apply authority-boundary learning

package/docs/solutions/integration-issues/durable-exact-recovery-after-browser-state-loss.md

@@ -78,7 +78,7 @@ Verification: all 19 skill files matched the release manifest; the CLI suite
 passed 721 tests with 20 skipped; the installer test proved no MCP client command
 or configuration write; the Cloud fixture rejected failed skill installation.
 
-The coordinated durable recovery work shipped through [trackly-cli PR #100](https://github.com/trackly-app/trackly-cli/pull/100), which enforces exact-set discovery and response validation in the CLI/MCP/skill layer, and [close-ai PR #1391](https://github.com/trackly-app/close-ai/pull/1391), whose backend implementation owns atomic all-or-nothing recovery creation.
+The coordinated durable recovery work shipped through [trackly-cli PR #100](https://github.com/trackly-app/trackly-cli/pull/100), which enforces exact-set discovery and response validation in the CLI/MCP/skill layer, and a coordinated private backend change, which owns atomic all-or-nothing recovery creation.
 
 ### 1. Discover a bounded, value-free recovery menu
 
@@ -143,5 +143,5 @@ Inspection epochs close stale-evidence reuse. Field provenance protects user cor
 ## Related Issues
 
 - [Trackly CLI PR #100](https://github.com/trackly-app/trackly-cli/pull/100) — CLI, MCP, and skill-side durable exact recovery contract.
-- [Close AI PR #1391](https://github.com/trackly-app/close-ai/pull/1391) — backend durable recovery lineage and exact-member control plane.
+- Private backend release records document durable recovery lineage and the exact-member control plane.
 - [Durable recovery implementation plan](../../plans/2026-08-05-001-trackly-apply-durable-recovery-reconciliation-plan.md) — historical design record aligned with the released all-or-nothing recovery contract.

package/docs/solutions/integration-issues/openai-mcp-discovery-probe-oauth-scope-failure.md

@@ -37,7 +37,7 @@ The OpenAI Platform could authenticate to Trackly but could not complete its man
 
 OpenAI's current MCP client probes legacy servers with the exact JSON-RPC method `server/discover` before falling back to the initialization-based protocol. Trackly's strict scope gateway treated every unknown method as a scoped operation and returned HTTP 403, so the client interpreted a compatibility probe as an OAuth authorization failure.
 
-The backend fix in `trackly-app/close-ai#1515` added only `server/discover` to the immutable scope-free protocol-method set. It did not add a tool or grant access to user data. The existing legacy SDK then returns JSON-RPC `-32601 Method not found`, which is the compatibility signal the OpenAI client needs to fall back to `initialize` and `tools/list`.
+The coordinated backend compatibility fix added only `server/discover` to the immutable scope-free protocol-method set. It did not add a tool or grant access to user data. The existing legacy SDK then returns JSON-RPC `-32601 Method not found`, which is the compatibility signal the OpenAI client needs to fall back to `initialize` and `tools/list`.
 
 The CLI contract alignment in `trackly-app/trackly-cli#106` records the exact backend source and merge provenance, locks the scope-free set and middleware behavior, and verifies the hosted catalog without broadening tool scopes. The coordinated verifier also checks the published Apply schemas, including `truthCertificationInputSchema`, in `scripts/verify-hosted-contract.js`.
 
@@ -55,5 +55,5 @@ HTTP 401/403 communicates an authentication or authorization failure, so a dual-
 
 ## Related Issues
 
-- `trackly-app/close-ai#1515` — backend compatibility fix.
+- Private backend release records document the compatibility fix.
 - `trackly-app/trackly-cli#106` — packaged contract and verifier alignment.

package/docs/trackly-tools.md

@@ -74,17 +74,32 @@ API-key creation attempts.
 
 - **get_more_tools** — Report what the agent wanted to do when no Trackly tool fit, so Trackly can improve its MCP surface. The tool is always available; report delivery is best-effort and occurs only when usage analytics are enabled.
 - **trackly_search_jobs** — Search/filter jobs.
-  - `function` (14 values): `product`, `engineering`, `design`, `data`, `marketing`, `sales`, `partnerships`, `finance`, `strategy`, `operations`, `people`, `legal`, `support`, `other`
-  - `locationFilter`: pass ONE of
+  - `function` (one value) or `jobFunctions` (nonempty array, OR; use one spelling only). The 14 values are: `product`, `engineering`, `design`, `data`, `marketing`, `sales`, `partnerships`, `finance`, `strategy`, `operations`, `people`, `legal`, `support`, `other`
+  - `region`: nonempty array of `us`, `europe`, `latam`, `middle_east`, `asia`, `africa`, `canada`, `oceania`, `remote`, `unknown`, combined with OR. Use instead of `locationFilter`; unlike its legacy list form, this supports US plus other regions.
+  - `usStates`: nonempty array of US codes `AL`, `AK`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DC`, `DE`, `FL`, `GA`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MI`, `MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY`, `PR`, `REMOTE`.
+  - `caProvinces`: nonempty array of `AB`, `BC`, `MB`, `NB`, `NL`, `NS`, `NT`, `NU`, `ON`, `PE`, `QC`, `SK`, `YT`, `REMOTE`. Geographic children follow the backend location rollout: parent-scoped OR applies under canonical enforcement; legacy compatibility remains before that. `REMOTE` alongside codes also includes remote jobs.
+  - `internshipLevels`: nonempty array of `undergraduate`, `graduate`, `mba`, `not_specified`, combined with OR. Applies to internships when `jobModality=internship` or `all`; full-time jobs remain unaffected. Set `jobModality` explicitly when you want internships; education levels do not change your saved/default modality.
+  - `favoriteCompaniesOnly` (boolean): restrict to your favorited companies; `false` explicitly disables it.
+  - `postedWithinDays`: `0`, `1`, `3`, `7`, `14`, `30`; `0` disables the saved posting window. Uses the backend discovery-date policy; omitted uses saved/default preferences.
+  - `salaryFloorUsd`: integer `0`–`1000000`. Excludes comparable listed annual-USD minimums below this floor. Unknown, hourly and non-USD salaries remain visible; this is not a guaranteed salary threshold. `0` disables the floor; omitted uses saved/default preferences.
+  - `since`: ISO-8601 date or timestamp within the past 90 days, never in the future. Filters when Trackly first saw a job, rather than the employer posting date. Prefer a timestamp with timezone for incremental sync. Other saved filters still apply: use `postedWithinDays:0` and `salaryFloorUsd:0` to disable those saved constraints.
+  - `locationFilter`: compatibility alias; use instead of `region`. Pass ONE of
     - a single scalar: `us`, `non_us`, `all`, or a region tag (`europe`, `latam`, `middle_east`, `asia`, `africa`, `canada`, `oceania`, `remote`, `unknown`), OR
     - an array of region tags for multi-region (e.g. `["europe", "canada"]`). The array form excludes `us` — combining `us` with other tags in an array causes the backend to silently drop the others. To get "not US" use the scalar `non_us` alone.
   - `jobModality`: `full_time`, `internship`, `all` — employment type, NOT work arrangement.
   - `workArrangements`: one or more of `remote`, `hybrid`, `in_person`, `unspecified`. This is an independent axis and combines with region, employment type, and function filters.
-  - `remote` (boolean): filter to remote jobs only. Maps to `usStates=REMOTE`.
+  - `remote` (boolean): filter to remote jobs only. Maps to `usStates=REMOTE`. Do not combine `remote=true` with geographic child arrays; use their `REMOTE` token for alternatives. Do not combine a parent region with `remote=true` or only `REMOTE` children: that backend form overrides the parent. Use `workArrangements:["remote"]` plus your region for remote work within that geography.
   - `status`: your application pipeline state. Values: `new`, `applied_confirmed`, `check_later`, `not_interested`, `all`.
   - `sort`: `newest` (default) or `match` (highest match score first; requires a resume on file). Backend rejects the deprecated values `oldest` and `company` with HTTP 400.
-  - `sponsorship`: `all` (default), `exclude_no`, `only_yes`. `exclude_no` hides jobs with a reliable explicit "does not sponsor" statement (~13% of active US jobs); `only_yes` keeps only jobs with a reliable explicit "sponsors" statement (~2%). Most postings never state a policy either way, so `only_yes` is a very narrow slice.
-  - `keywords`, `companyId`, `limit`, `offset`.
+  - `sponsorship`: `all` (no restriction), `exclude_no` (keep yes **and unknown/not mentioned**, exclude reliable explicit no), `only_yes` (reliable explicit yes only). “Not no” means `exclude_no`, never `only_yes`; ask when intent is ambiguous. Filtering requires `status=new`, which is defaulted when omitted; other pipeline views ignore this filter.
+  - `keywords`: legacy keyword search, maximum 500 characters. Title/company/location matching is supported; description recall depends on the backend provider. This is not guaranteed full-catalog literal, phrase or exclusion search.
+  - `companyId`: positive integer from company search.
+  - `limit`: integer `1`–`100`, MCP default `20`; `offset`: non-negative safe integer, default `0`. Keep all filters and sort unchanged while paging. The live catalog may change between calls.
+  - Unsupported keys are rejected before HTTP, including when usage analytics is enabled. Industry, specialization and literal-search controls are not exposed until their backend contract is deployed.
+
+Example: `{"jobFunctions":["finance","partnerships"],"region":["us","europe"],"sponsorship":"exclude_no","postedWithinDays":7,"limit":20}`.
+The local package and hosted service have separate release lifecycles. Refresh the client's tool discovery after upgrading or reconnecting and use only parameters its current schema advertises.
+
 - **trackly_get_job** — Get full job details by ID
 - **trackly_search_companies** — Semantic company search
 - **trackly_list_companies** — List all tracked companies with job counts

package/lib/agent.js

@@ -8,7 +8,7 @@ const { spawnSync } = require('node:child_process');
 const { apiRequest, downloadFile, getConfigPaths, hasAuth, maintenanceOutput } = require('./client');
 const { version: PACKAGE_VERSION } = require('../package.json');
 const { contractVersion: MCP_CONTRACT_VERSION } = require('../contracts/trackly-apply-tools.json');
-const SKILL_VERSION = '4.9.0';
+const SKILL_VERSION = '4.9.1';
 const SKILL_POLICY_REVISION = SKILL_VERSION;
 const CLI_USER_AGENT = `trackly-cli/${PACKAGE_VERSION}`;
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;

package/mcp/analytics.js

@@ -615,11 +615,14 @@ function addOptionalContextToTools(server) {
     if (Object.hasOwn(shape, 'context')) continue;
 
     const originalHandler = tool.handler;
+    const schema = tool.inputSchema;
+    const context = z.string().optional().describe(CONTEXT_DESCRIPTION);
+    // SDK update(paramsSchema) rebuilds objects and drops strict/catchall rules.
+    // Retain real object schemas; SDK-created empty Mini schemas need the shape API.
+    const paramsSchema = typeof schema.extend === 'function' ? null : { ...shape, context };
+    if (paramsSchema === null) tool.inputSchema = schema.extend({ context });
     tool.update({
-      paramsSchema: {
-        ...shape,
-        context: z.string().optional().describe(CONTEXT_DESCRIPTION),
-      },
+      ...(paramsSchema === null ? {} : { paramsSchema }),
       callback: (args, extra) => {
         if (!args || typeof args !== 'object' || !Object.hasOwn(args, 'context')) {
           return originalHandler(args, extra);

package/mcp/apply-tools.js

@@ -791,7 +791,7 @@ const startApplyRunSchema = z.object({
   }
 });
 
-const APPLY_RELIABILITY_PROMPT = 'Protocol 3.7 / skill 4.9.0 reliability gate: recover active work first. Consume the exact proposedWave and frozen accessKnowledge receipts before opening any browser. Rank OPEN ahead of neutral VARIES/UNKNOWN, then fresh ACCOUNT WALL; never auto-select an active user deferment. Historical OPEN never authorizes fill_form; freshLiveProbeRequired remains true. When nextAction is access_review, including ordinary OPEN or neutral proposals, display the exact accessProposal and accessProposal.approvalHash. If the proposal has nonempty members, obtain explicit approval for those exact ordered jobIds and call the hash-bound approval continuation. If the proposal has zero members because all remaining candidates are deferred or exact recovery is blocked by a user deferment, surface the deferred count and stable deferment IDs, offer clear-deferment only for explicitly returned IDs, stop, or expiry, and never send an empty approval. List or create deferments only at job, company, or provider scope through the jobId-bound tools; provider scope applies across companies until explicitly cleared. Do not open a browser or report the queue exhausted. Retain the latest explicit target as hard, prove genuine applicant fields before counting access, obtain approval for the exact accessible jobs before form mutation, fill all deterministic fields before one true-gap question packet, and validate each value-free phase checkpoint. Every checkpoint action must use its canonical continuationAllowed value; review/manual_submit, captcha/at_submit, trust/origin_mismatch, and observability/unverifiable_state require false. Fail closed on a rejected checkpoint. After full local context loss, list recoverable executions, show only stable job identity, obtain explicit confirmation of the exact candidate set, and call exact-member recovery without substitutions. An active personal deferment blocks exact recovery until cleared. Treat recovered tab presence, form state, and mutation authority as three separate facts; reacquire a fresh browser binding and inspection epoch before mutation. Before resolving broad submission statements, list active review handoffs for the execution; use only an explicit receipt or the sole returned active receipt, classify every member as detected, user_confirmed, unresolved, or contradictory, and claim that exact handoff before writing outcomes. Use provider-specific positive success evidence; an unchanged URL or title is never negative evidence. Validate an exact expected browser keep set locally before finalization. For resume uploads, negotiate the browser surface capabilities, identify the semantic control, arm the chooser before clicking, attach the immediately verified file, prove the user-facing filename committed, and recheck parser-modified fields. Use compact snapshots and server-provided mutability. Preserve user-edited and unknown non-empty fields. Never reopen parked work without explicit user resumption. Never click Submit.';
+const APPLY_RELIABILITY_PROMPT = 'Protocol 3.7 / skill 4.9.1 reliability gate: recover active work first. Consume the exact proposedWave and frozen accessKnowledge receipts before opening any browser. Rank OPEN ahead of neutral VARIES/UNKNOWN, then fresh ACCOUNT WALL; never auto-select an active user deferment. Historical OPEN never authorizes fill_form; freshLiveProbeRequired remains true. When nextAction is access_review, including ordinary OPEN or neutral proposals, display the exact accessProposal and accessProposal.approvalHash. If the proposal has nonempty members, obtain explicit approval for those exact ordered jobIds and call the hash-bound approval continuation. If the proposal has zero members because all remaining candidates are deferred or exact recovery is blocked by a user deferment, surface the deferred count and stable deferment IDs, offer clear-deferment only for explicitly returned IDs, stop, or expiry, and never send an empty approval. List or create deferments only at job, company, or provider scope through the jobId-bound tools; provider scope applies across companies until explicitly cleared. Do not open a browser or report the queue exhausted. Retain the latest explicit target as hard, prove genuine applicant fields before counting access, obtain approval for the exact accessible jobs before form mutation, fill all deterministic fields before one true-gap question packet, and validate each value-free phase checkpoint. Every checkpoint action must use its canonical continuationAllowed value; review/manual_submit, captcha/at_submit, trust/origin_mismatch, and observability/unverifiable_state require false. Fail closed on a rejected checkpoint. After full local context loss, list recoverable executions, show only stable job identity, obtain explicit confirmation of the exact candidate set, and call exact-member recovery without substitutions. An active personal deferment blocks exact recovery until cleared. Treat recovered tab presence, form state, and mutation authority as three separate facts; reacquire a fresh browser binding and inspection epoch before mutation. Before resolving broad submission statements, list active review handoffs for the execution; use only an explicit receipt or the sole returned active receipt, classify every member as detected, user_confirmed, unresolved, or contradictory, and claim that exact handoff before writing outcomes. Use provider-specific positive success evidence; an unchanged URL or title is never negative evidence. Validate an exact expected browser keep set locally before finalization. For resume uploads, negotiate the browser surface capabilities, identify the semantic control, arm the chooser before clicking, attach the immediately verified file, prove the user-facing filename committed, and recheck parser-modified fields. Use compact snapshots and server-provided mutability. Preserve user-edited and unknown non-empty fields. Never reopen parked work without explicit user resumption. Never click Submit.';
 
 function registerApplyTools(
   server,
@@ -1973,7 +1973,7 @@ function registerApplyTools(
       content: { type: 'text', text: APPLY_RELIABILITY_PROMPT },
     }, {
       role: 'user',
-      content: { type: 'text', text: 'Before generating questions or filling controls, run the skill 4.9.0 deterministic answer resolver and profile lookup gate. Request the current contextual projection for every visible canonical key; compact omissions are not unknown answers. Commit compatible known answers before questions and run scripts/validate-profile-lookup.js on value-free accounting. Redacted or unavailable lookups are access problems, not missing facts; optional unknown demographics may remain blank; live consent stays separate. Classify every visible answer as exact_profile, safe_derivation, supported_draft, missing_fact, live_consent, or forbidden_inference; validate the control type; fill only the first three; and ask only currently visible unresolved needs. Treat the current profile revision as reusable authority, never transcript, screenshot, parser, autocomplete, or cached values. Accessible-first is a hard scheduler invariant: park known authentication, account-creation, OTP, and pre-form-CAPTCHA work without starting a draft while an accessible candidate remains. Curated OPEN and recent accessibility never change allowedOperations to fill_form.' },
+      content: { type: 'text', text: 'Before generating questions or filling controls, run the skill 4.9.1 deterministic answer resolver and profile lookup gate. Request the current contextual projection for every visible canonical key; compact omissions are not unknown answers. Commit compatible known answers before questions and run scripts/validate-profile-lookup.js on value-free accounting. Redacted or unavailable lookups are access problems, not missing facts; optional unknown demographics may remain blank; live consent stays separate. Classify every visible answer as exact_profile, safe_derivation, supported_draft, missing_fact, live_consent, or forbidden_inference; validate the control type; fill only the first three; and ask only currently visible unresolved needs. Treat the current profile revision as reusable authority, never transcript, screenshot, parser, autocomplete, or cached values. Accessible-first is a hard scheduler invariant: park known authentication, account-creation, OTP, and pre-form-CAPTCHA work without starting a draft while an accessible candidate remains. Curated OPEN and recent accessibility never change allowedOperations to fill_form.' },
     }, {
       role: 'user',
       content: { type: 'text', text: 'Only active=true identifies resumable execution work. Active=false and preserved=true is terminal read-only reconciliation evidence.' },
@@ -1981,7 +1981,7 @@ function registerApplyTools(
       role: 'user',
       content: {
         type: 'text',
-        text: `Protocol 3.7.0 reliability gate for new work: require MCP contract ${APPLY_CONTRACT.contractVersion} and skill 4.9.0. Consume the exact proposedWave with frozen accessKnowledge before opening any browser; same-key advance replay returns identical member IDs, order, and rationale. When nextAction is access_review, including ordinary OPEN or neutral proposals, display the exact access-review receipt and do not report exhaustion. For a nonempty proposal, obtain explicit approval for the unchanged ordered job IDs and server approval hash before probing. For an all-deferred or recovery-blocked proposal with zero members, show the deferred count and stable job/company/provider deferment IDs, offer clear-deferment only for explicitly returned IDs, stop, or expiry, and never send an empty approval. Defer or clear only through jobId-scoped job, company, or provider tools; provider scope applies across companies until explicitly cleared. Never submit provider names, URLs, or raw chat. After complete local context loss, list bounded recovery candidates, obtain explicit confirmation of the exact set, and recover only that set. An active personal deferment blocks exact recovery until cleared. Treat tab recovery, form-state recovery, and mutation authority as independent. List active handoff receipts for the execution before resolving grouped submission statements; use the named receipt or the sole returned active receipt, classify every member, and claim that receipt before recording outcomes. Validate tab keep sets and resume upload stages locally. Never send raw browser values or click Submit.`,
+        text: `Protocol 3.7.0 reliability gate for new work: require MCP contract ${APPLY_CONTRACT.contractVersion} and skill 4.9.1. Consume the exact proposedWave with frozen accessKnowledge before opening any browser; same-key advance replay returns identical member IDs, order, and rationale. When nextAction is access_review, including ordinary OPEN or neutral proposals, display the exact access-review receipt and do not report exhaustion. For a nonempty proposal, obtain explicit approval for the unchanged ordered job IDs and server approval hash before probing. For an all-deferred or recovery-blocked proposal with zero members, show the deferred count and stable job/company/provider deferment IDs, offer clear-deferment only for explicitly returned IDs, stop, or expiry, and never send an empty approval. Defer or clear only through jobId-scoped job, company, or provider tools; provider scope applies across companies until explicitly cleared. Never submit provider names, URLs, or raw chat. After complete local context loss, list bounded recovery candidates, obtain explicit confirmation of the exact set, and recover only that set. An active personal deferment blocks exact recovery until cleared. Treat tab recovery, form-state recovery, and mutation authority as independent. List active handoff receipts for the execution before resolving grouped submission statements; use the named receipt or the sole returned active receipt, classify every member, and claim that receipt before recording outcomes. Validate tab keep sets and resume upload stages locally. Never send raw browser values or click Submit.`,
       },
     }, {
       role: 'user',
@@ -1999,7 +1999,7 @@ function registerApplyTools(
       role: 'user',
       content: {
         type: 'text',
-        text: 'Browser preservation clarification: The following conditional rules supersede any unconditional complete-inventory wording earlier in this prompt. For the session-finalizer path, require complete controller and user inventories, build the non-empty keep list, and run the finalizer once. For the documented per-tab durable-handoff path, do not require unavailable inventories; preserve each ledger-mapped live tab with an exact persistence receipt. If no mapped live application tabs remain, skip both finalization and per-tab handoff. For reachability and visibility on the per-tab path, an exact current tab-bound user-visible handoff receipt is valid alternative proof. A user-confirmed direct tab closure may retire its ledger entry only after either complete-union absence or an exact current tab-bound user-side closure/absence receipt. Agent-initiated closure still requires the full close-proof gate. Policy 4.9.0 also accepts the documented markHandoff path described in the installed skill references/handoff-compatibility.md; this path supersedes earlier receipt-only readiness requirements. Before form mutation, verify that the runtime documentation promises to keep the tab across normal turn cleanup and that every mapped application tab is available. Bind each exact job/run/tab, await its markHandoff(), and check the controller inventory and user inventory where exposed; failed calls or missing tabs block mutation. Before ending every turn, await markHandoff() for every mapped live application tab, then check the controller inventory and user inventory where exposed. Failed marks or missing tabs block the handoff. Report incomplete inventories as unverified, never as closure proof. On the next turn, reclaim each exact tab, recheck identity and required fields, and re-mark before any later handoff. markHandoff returns Promise<void>; successful completion and inventory checks are observations, not a native persistence receipt or proof that draft state survives a crash. Never label mark-only evidence durable_handoff_receipt or change validators to manufacture receipt proof. Keep manual Submit, visible form verification, and the installed skill platform capability requirements.',
+        text: 'Browser preservation clarification: The following conditional rules supersede any unconditional complete-inventory wording earlier in this prompt. For the session-finalizer path, require complete controller and user inventories, build the non-empty keep list, and run the finalizer once. For the documented per-tab durable-handoff path, do not require unavailable inventories; preserve each ledger-mapped live tab with an exact persistence receipt. If no mapped live application tabs remain, skip both finalization and per-tab handoff. For reachability and visibility on the per-tab path, an exact current tab-bound user-visible handoff receipt is valid alternative proof. A user-confirmed direct tab closure may retire its ledger entry only after either complete-union absence or an exact current tab-bound user-side closure/absence receipt. Agent-initiated closure still requires the full close-proof gate. Policy 4.9.1 also accepts the documented markHandoff path described in the installed skill references/handoff-compatibility.md; this path supersedes earlier receipt-only readiness requirements. Before form mutation, verify that the runtime documentation promises to keep the tab across normal turn cleanup and that every mapped application tab is available. Bind each exact job/run/tab, await its markHandoff(), and check the controller inventory and user inventory where exposed; failed calls or missing tabs block mutation. Before ending every turn, await markHandoff() for every mapped live application tab, then check the controller inventory and user inventory where exposed. Failed marks or missing tabs block the handoff. Report incomplete inventories as unverified, never as closure proof. On the next turn, reclaim each exact tab, recheck identity and required fields, and re-mark before any later handoff. markHandoff returns Promise<void>; successful completion and inventory checks are observations, not a native persistence receipt or proof that draft state survives a crash. Never label mark-only evidence durable_handoff_receipt or change validators to manufacture receipt proof. Keep manual Submit, visible form verification, and the installed skill platform capability requirements.',
       },
     }, {
       role: 'user',

package/mcp/server.js

@@ -52,6 +52,14 @@ const JOB_MODALITIES = ['full_time', 'internship', 'all'];
 // Independent from geography and employment type. Matches the backend's
 // workArrangements query contract and job_postings constraint.
 const WORK_ARRANGEMENTS = ['remote', 'hybrid', 'in_person', 'unspecified'];
+const US_STATES = [
+  'AL', 'AK', 'AZ', 'AR', 'CA', 'CO', 'CT', 'DC', 'DE', 'FL', 'GA', 'HI', 'ID',
+  'IL', 'IN', 'IA', 'KS', 'KY', 'LA', 'ME', 'MD', 'MA', 'MI', 'MN', 'MS', 'MO',
+  'MT', 'NE', 'NV', 'NH', 'NJ', 'NM', 'NY', 'NC', 'ND', 'OH', 'OK', 'OR', 'PA',
+  'RI', 'SC', 'SD', 'TN', 'TX', 'UT', 'VT', 'VA', 'WA', 'WV', 'WI', 'WY', 'PR', 'REMOTE',
+];
+const CA_PROVINCES = ['AB', 'BC', 'MB', 'NB', 'NL', 'NS', 'NT', 'NU', 'ON', 'PE', 'QC', 'SK', 'YT', 'REMOTE'];
+const INTERNSHIP_LEVELS = ['undergraduate', 'graduate', 'mba', 'not_specified'];
 
 const MCP_MISSING_CAPABILITY_VALUES = [
   'search', 'inspect', 'compare', 'rank', 'recommend', 'track', 'update', 'apply',
@@ -254,12 +262,21 @@ function createServer() {
     version: PACKAGE_VERSION,
   });
 
-  server.tool(
+  server.registerTool(
     'trackly_search_jobs',
-    'Search and filter job postings. Returns matching jobs with title, company, location, and structured fields. Use companyId to filter jobs at a specific company (get companyId from trackly_search_companies first). Work arrangement is independent from region and employment type: use workArrangements for remote, hybrid, in-person, or unspecified classifications.',
-    {
+    { description: 'Search and filter job postings. Returns one matching page with title, company, location, structured fields and backend pagination. Use jobFunctions for multiple roles, region for multiple regions, and usStates/caProvinces for geographic detail. Work arrangement is independent from geography and employment type. Unknown sponsorship and non-comparable salary data stay visible with exclude_no and salaryFloorUsd. Never invent industry, specialization, exclusion or literal-search controls; ask when sponsorship intent is ambiguous.',
+    inputSchema: z.object({
       function: z.enum(JOB_FUNCTIONS).optional().describe('Job function filter. One of: ' + JOB_FUNCTIONS.join(', ')),
-      companyId: z.number().optional().describe('Filter jobs by company ID (get from trackly_search_companies)'),
+      jobFunctions: z.array(z.enum(JOB_FUNCTIONS)).min(1).max(14).optional().describe('Multiple job functions, combined with OR. Use instead of function. Omit both to request all 14 functions.'),
+      companyId: z.number().int().positive().optional().describe('Filter jobs by company ID (get from trackly_search_companies)'),
+      region: z.array(z.enum(REGION_TAGS)).min(1).max(10).optional().describe('Region tags combined with OR, including us. Use instead of locationFilter; this avoids its legacy mixed-US list limitation. Geographic child behavior follows the backend location rollout.'),
+      usStates: z.array(z.enum(US_STATES)).min(1).max(53).optional().describe('US state codes, DC, PR, or REMOTE. Multiple values select alternatives. REMOTE alongside codes also includes remote jobs. Under canonical location enforcement children select their parent; legacy rollout keeps compatibility behavior. Do not combine with remote=true.'),
+      caProvinces: z.array(z.enum(CA_PROVINCES)).min(1).max(14).optional().describe('Canadian province/territory codes or REMOTE. Multiple values select alternatives. REMOTE alongside codes also includes remote jobs. Parent-scoped OR requires canonical location enforcement. Do not combine with remote=true.'),
+      internshipLevels: z.array(z.enum(INTERNSHIP_LEVELS)).min(1).max(4).optional().describe('Internship education levels, combined with OR: undergraduate, graduate, mba, not_specified. Applies to internships in jobModality=internship or all; full-time jobs remain unaffected. This does not change the saved/default modality: set jobModality explicitly when you want internships.'),
+      favoriteCompaniesOnly: z.boolean().optional().describe('true limits results to your favorited companies; false explicitly disables this restriction.'),
+      postedWithinDays: z.union([z.literal(0), z.literal(1), z.literal(3), z.literal(7), z.literal(14), z.literal(30)]).optional().describe('Posting-recency window in days: 1, 3, 7, 14, or 30; 0 disables the saved window. Uses the backend discovery-date policy; not an incremental-sync cursor. Omit to use the saved/default window.'),
+      salaryFloorUsd: z.number().int().min(0).max(1_000_000).optional().describe('Annual USD minimum salary floor. Excludes comparable listed annual-USD minimums below this amount; unknown, hourly and non-USD salaries remain visible. 0 disables the floor; omitted uses saved/default preferences. This is not a guaranteed salary threshold.'),
+      since: z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/).optional().describe('Incremental sync: jobs first seen by Trackly since this ISO-8601 date/timestamp, not employer posting dates. Must be within the past 90 days and not in the future; backend validates the range. Prefer a timestamp with timezone. Other saved filters still apply; use postedWithinDays=0 and salaryFloorUsd=0 to disable those saved constraints.'),
       locationFilter: z.union([
         z.enum(['us', 'non_us', 'all']),
         z.enum(REGION_TAGS),
@@ -273,19 +290,34 @@ function createServer() {
       workArrangements: z.array(z.enum(WORK_ARRANGEMENTS)).min(1).max(4).optional().describe(
         'Work arrangement filter, independent from geography and employment type. Values: remote, hybrid, in_person, unspecified. Multiple values use OR semantics.'
       ),
-      remote: z.boolean().optional().describe('Filter to remote jobs only (maps to usStates=REMOTE).'),
+      remote: z.boolean().optional().describe('Filter to global remote-only jobs (maps to usStates=REMOTE). Do not combine with region/locationFilter or geographic child arrays. For remote work within a region, use workArrangements=["remote"] with region instead.'),
       status: z.enum(STATUS_VALUES).optional().describe(
         'Filter by YOUR application pipeline state. Not a generic job-posting status. Values: ' + STATUS_VALUES.join(', ')
       ),
       sort: z.enum(SORT_VALUES).optional().describe('Sort order: newest (default) or match (highest match score first; requires resume). Backend rejects legacy oldest/company with HTTP 400.'),
       sponsorship: z.enum(SPONSORSHIP_VALUES).optional().describe(
-        "Visa sponsorship filter. 'exclude_no' hides jobs with a reliable explicit \"does not sponsor\" statement (~13% of active US jobs); 'only_yes' keeps only jobs with a reliable explicit \"sponsors\" statement (~2% — most postings never state a policy either way). Default 'all' shows every job. Applies only to the discovery view: when you pass a filtering mode without `status`, status defaults to 'new' (the backend ignores the filter on tracked/pipeline views)."
+        "Visa sponsorship: all applies no filter; exclude_no removes reliable explicit no statements and keeps yes plus unknown/not mentioned; only_yes requires reliable explicit yes and excludes unknown. 'Not no' means exclude_no, never only_yes. Ask when intent is ambiguous. Filtering requires status=new (defaulted when omitted); the backend ignores sponsorship on other pipeline views."
       ),
-      limit: z.number().max(50).optional().describe('Max results (default 20, max 50)'),
-      offset: z.number().min(0).optional().describe('Pagination offset'),
-      keywords: z.string().max(500).optional().describe('Keyword search in title, company, or description'),
-    },
+      limit: z.number().int().min(1).max(100).optional().describe('Page size, integer 1-100; MCP default 20 for concise agent results. Request up to the full API limit of 100 when needed.'),
+      offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional().describe('Pagination offset, non-negative integer. Keep filters and sort unchanged when paging; live catalog changes can move rows.'),
+      keywords: z.string().max(500).optional().describe('Legacy keyword search. Title/company/location matches are supported; description recall depends on the backend provider. Not a guaranteed full-catalog literal/phrase/exclusion search.'),
+    }).strict() },
     wrapTool(async (params) => {
+      if (params.function !== undefined && params.jobFunctions !== undefined) {
+        throw new Error('Use either function or jobFunctions, not both.');
+      }
+      if (params.region !== undefined && params.locationFilter !== undefined) {
+        throw new Error('Use either region or locationFilter, not both.');
+      }
+      if (params.remote === true && (params.usStates !== undefined || params.caProvinces !== undefined)) {
+        throw new Error('Use remote=true alone for remote-only jobs, or include REMOTE in the geographic arrays for alternatives.');
+      }
+      const hasParentLocation = params.region !== undefined || params.locationFilter !== undefined;
+      const childLocations = [...(params.usStates ?? []), ...(params.caProvinces ?? [])];
+      const remoteOnlyChildren = childLocations.length > 0 && childLocations.every((value) => value === 'REMOTE');
+      if (hasParentLocation && (params.remote === true || remoteOnlyChildren)) {
+        throw new Error('REMOTE-only location overrides the parent region. Use workArrangements=["remote"] with region or locationFilter for remote work within that geography.');
+      }
       const qs = new URLSearchParams();
       // When `function` isn't specified, request ALL canonical functions so the
       // backend takes the all-roles short-circuit (granola-followup-app
@@ -296,6 +328,13 @@ function createServer() {
       // Health (id=3350) — both had non-PM-only job sets and search_jobs
       // returned total=0 without an explicit function filter.
       qs.set('jobFunction', params.function !== undefined ? params.function : JOB_FUNCTIONS.join(','));
+      if (params.jobFunctions !== undefined) qs.set('jobFunction', params.jobFunctions.join(','));
+      for (const key of ['region', 'usStates', 'caProvinces', 'internshipLevels']) {
+        if (params[key] !== undefined) qs.set(key, params[key].join(','));
+      }
+      for (const key of ['favoriteCompaniesOnly', 'postedWithinDays', 'salaryFloorUsd', 'since']) {
+        if (params[key] !== undefined) qs.set(key, String(params[key]));
+      }
       if (params.companyId !== undefined) qs.set('companyId', String(params.companyId));
       if (params.locationFilter !== undefined) {
         const value = Array.isArray(params.locationFilter)
@@ -318,7 +357,7 @@ function createServer() {
           qs.set('status', 'new');
         }
       }
-      if (params.limit !== undefined) qs.set('limit', String(params.limit));
+      qs.set('limit', String(params.limit ?? 20));
       if (params.offset !== undefined) qs.set('offset', String(params.offset));
       if (params.keywords !== undefined) qs.set('search', params.keywords);
       return apiRequest('GET', `/api/jobscout/jobs?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
@@ -462,7 +501,7 @@ function createServer() {
       if (askResult.jobsUrl) {
         // Path allowlist: /ask returns a jobsUrl string. normalizeEndpoint already blocks
         // cross-origin fetches, but a compromised backend could emit a same-origin path
-        // like `/api/admin/secret-dump`. Only follow the two handlers /ask is designed to
+        // outside the job API. Only follow the two handlers /ask is designed to
         // route to. Mirrors the same guard in bin/trackly:cmdAsk.
         const JOBS_URL_ALLOWLIST = /^\/api\/(v1|jobscout)\/jobs(\?|$)/;
         if (JOBS_URL_ALLOWLIST.test(askResult.jobsUrl)) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "trackly-cli",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "trackly-cli",
-      "version": "0.20.0",
+      "version": "0.21.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.32.1",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "trackly-cli",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "mcpName": "io.github.trackly-app/trackly",
-  "description": "AI job search CLI + hosted MCP server with OAuth. 250K+ jobs, 5,400+ companies, 40+ ATS. Works with Claude, ChatGPT, Cursor, Windsurf, Codex via hosted streamable-http or local stdio.",
+  "description": "Search 250K+ jobs across 5,400+ companies with the Trackly CLI and MCP server for Claude, ChatGPT, Codex and Cursor. Filter by role, location, salary and sponsorship; track jobs and prepare applications.",
   "bin": {
     "trackly": "./bin/trackly"
   },
@@ -52,7 +52,12 @@
     "job-application",
     "job-hunting",
     "career",
-    "terminal"
+    "terminal",
+    "codex",
+    "job-search-mcp",
+    "visa-sponsorship",
+    "internships",
+    "remote-jobs"
   ],
   "author": "Kevin Astuhuaman <hello@usetrackly.app>",
   "license": "MIT",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.trackly-app/trackly",
   "title": "Trackly CLI",
-  "description": "Job search for Claude, ChatGPT, Cursor. 250K+ jobs, 5,400+ companies. OAuth or stdio.",
+  "description": "Search 250K+ jobs, 5,400+ companies. MCP for Claude, ChatGPT, Codex and Cursor.",
   "repository": {
     "url": "https://github.com/trackly-app/trackly-cli",
     "source": "github"
@@ -17,12 +17,12 @@
       ]
     }
   ],
-  "version": "0.20.0",
+  "version": "0.21.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.20.0",
+      "version": "0.21.0",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {

package/skills/trackly-apply/SKILL.md

@@ -9,7 +9,7 @@ Use Trackly as the source of truth for profile answers, documents, queue decisio
 
 ## Skill version
 
-Skill version: `4.9.0`. Before browser readiness read [references/handoff-compatibility.md](references/handoff-compatibility.md). This policy takes precedence over returned-persistence-receipt or finalizer requirements elsewhere when using the documented markHandoff path. Other review and safety gates remain unchanged.
+Skill version: `4.9.1`. Before browser readiness read [references/handoff-compatibility.md](references/handoff-compatibility.md). This policy takes precedence over returned-persistence-receipt or finalizer requirements elsewhere when using the documented markHandoff path. Other review and safety gates remain unchanged.
 
 ## Non-negotiable rules
 
@@ -39,7 +39,7 @@ value-free phase receipt with `scripts/validate-phase-checkpoint.js` before
 claiming that phase complete.
 Read [references/legal-clarifications.md](references/legal-clarifications.md) when a form asks for a legal, regulatory, consent, or employer-relationship decision.
 
-1. Call `trackly_get_apply_protocol`. Skill 4.9.0 requires protocol 3.7.0 or newer for new reliability work. Protocol 3.2 remains valid only for an already-active explicit legacy single run; an already-active explicit 3.2 single run may finish through its legacy path. Preserve the protocol's documented recovery paths for already-active older work. Require `compatibleSkillMajor: 4` and `compatibleSkillMinimumVersion` no newer than this installed skill. Reject an older or incompatible version for new work and report that the backend must finish updating or `trackly agent setup` must update the skill. Protocol 3.2 added exact-origin trust for jobs Trackly ingested directly from employer careers sources; do not recreate the retired ownership-timestamp gate in the client.
+1. Call `trackly_get_apply_protocol`. Skill 4.9.1 requires protocol 3.7.0 or newer for new reliability work. Protocol 3.2 remains valid only for an already-active explicit legacy single run; an already-active explicit 3.2 single run may finish through its legacy path. Preserve the protocol's documented recovery paths for already-active older work. Require `compatibleSkillMajor: 4` and `compatibleSkillMinimumVersion` no newer than this installed skill. Reject an older or incompatible version for new work and report that the backend must finish updating or `trackly agent setup` must update the skill. Protocol 3.2 added exact-origin trust for jobs Trackly ingested directly from employer careers sources; do not recreate the retired ownership-timestamp gate in the client.
 2. Call `trackly_get_profile_onboarding` or fetch both the profile schema and application profile. When present, render `schema.screens` in ascending `order` as one grouped question packet per screen. Within a screen, preserve category `order` and then field `order`; use each field's user-facing `rationale` when the user asks why it is needed. Ask only unknown or confirmation-needed fields and honor `consistencyRules` before submitting profile changes, resolving contradictions with the user instead of guessing. When `schema.screens` is absent on a legacy backend, fall back to the existing category-based onboarding behavior. Treat `completeness.percent` as required onboarding readiness only. Use `coverage.missingReusableKeys` to explain reusable optional gaps, while `coverage.contextualKeys` are intentionally asked only on the relevant employer form. Do not claim that 100% required completeness answers every possible application question.
 3. Save answers with `trackly_update_application_profile`:
    - Use `answered`, `intentionally_blank`, `declined`, or `unknown` exactly.
@@ -85,7 +85,7 @@ Read [references/legal-clarifications.md](references/legal-clarifications.md) wh
    - For each fixed batch member, preserve an explicit job ID -> application run ID -> browser tab mapping. Complete the full start -> conditional resume preparation/confirmation/verification when an upload control exists -> form completion -> `review_ready` lifecycle for every member. A review-ready run does not block the next member. Never submit any of them.
 6. When the selected job or current fixed batch member has no `runId`, call `trackly_start_apply_run` with the complete `batchId`, `memberId`, `expectedMemberVersion`, `expectedInspectionEpoch`, and `leaseToken` returned by Trackly. This is the sanctioned idempotent lookup for a recovered member whose `runId` is absent; call it with the exact recovered binding and Trackly will reuse the bound active run. When the member already has a `runId`, do not call `trackly_start_apply_run` in this or any subsequent start step: reuse that exact run and bind or recover its browser surface through `trackly_bind_apply_surface` as required. Never create a replacement run because browser control was interrupted.
    - If a bound start returns a transport failure, a non-access HTTP 5xx response, or an error explicitly marked `retryable: true`, preserve the frozen member and browser state. Refetch the active batch, renew its lease, and retry the same complete binding once. Classify the retry response independently with these same rules: route canonical `maintenance_mode` or legacy `planned_maintenance` directly through **Resume after maintenance**; surface controlled-access/request errors marked `retryable: false` and every other HTTP 4xx response unchanged; only a second transport failure, non-access HTTP 5xx response, or explicitly retryable error becomes `backend_run_start_unavailable`. Route maintenance on either attempt without consuming or relabeling the retry, and never relabel a permanent retry response as an outage. For `backend_run_start_unavailable`, continue other members and report a Trackly control-plane failure. Do not call `trackly_checkpoint_apply_batch` for this condition because start failure has not produced the required run ID. The unchanged frozen member is the durable resume point. Never switch that frozen member to an unbound legacy run or blame the employer form.
-   - Require `run.protocolVersion` to be 3.1.0 or newer and to share protocol major 3 with the fetched protocol. A new reliability execution member requires 3.7.0 or newer; already-active older work may use only the recovery path published by its fetched protocol. Never continue a pre-evidence 3.0.x run under skill 4.9.0. Preserve that run instead of starting a replacement, record it `blocked` with a value-free protocol-upgrade reason when possible, and tell the user the saved job can be retried only after the stale run is cleared through Trackly's supported lifecycle. Stop and refetch the protocol and active execution or batch if support level, execution mode, provider, required scenarios, authorized origin policy, member version, or inspection epoch changes after run creation.
+   - Require `run.protocolVersion` to be 3.1.0 or newer and to share protocol major 3 with the fetched protocol. A new reliability execution member requires 3.7.0 or newer; already-active older work may use only the recovery path published by its fetched protocol. Never continue a pre-evidence 3.0.x run under skill 4.9.1. Preserve that run instead of starting a replacement, record it `blocked` with a value-free protocol-upgrade reason when possible, and tell the user the saved job can be retried only after the stale run is cleared through Trackly's supported lifecycle. Stop and refetch the protocol and active execution or batch if support level, execution mode, provider, required scenarios, authorized origin policy, member version, or inspection epoch changes after run creation.
    - In guided mode, inspect the page before preparing any resume bytes. Confirm the employer, role, HTTPS origin, reachable review path, semantic controls, whether an attachment control exists, and absence of a credential, verification, CAPTCHA, or submit-only wall. A missing file input is not itself a blocker; skip the resume path when the application has no attachment control. Any other failed precondition is an execution blocker, not permission to improvise.
 7. Pass the browser readiness gate before preparing resume bytes:
    - Use semantic browser control through Codex in-app browser controls, Chrome MCP/extension browser control, or Claude in Chrome.

package/skills/trackly-apply/references/answer-resolution.md

@@ -36,7 +36,9 @@ an observation.
 
 Inventory all visible questions first. Map their canonical keys against the current schema, including optional diversity fields. Fetch one current contextual application profile with sensitive values when existing storage consent permits, supplying the actual provider, company ID and jurisdiction. Reuse this fetch for the packet; do not ask from an incomplete compact projection. If required values are redacted or unavailable, report the access limitation and recover it instead of calling the answer unknown.
 
-For each visible control, retain a value-free receipt with its fingerprint, whether schema and relevant profile projection were fetched, resolved state (`answered`, `unknown`, `redacted`, `unavailable`, or `live_consent`), required flag, intended disposition (`fill`, `preserve`, `ask`, `defer_optional`, or `blocked`), and committed flag. Run `node scripts/validate-profile-lookup.js receipt.json` before presenting a packet. This validator checks local accounting; it does not call Trackly or prove a fetch happened. Retain actual lookup and committed-control evidence locally. Answered compatible fields must be filled and verified or preserve a user edit; they cannot appear in the questions. Optional unknown demographics may stay blank without interrupting the user. Required unknown facts and genuinely live decisions can be asked together after known answers commit. An unavailable profile lookup is a lookup problem, never evidence that the user has no saved answer.
+For each visible control, retain a value-free receipt with its fingerprint, whether schema and relevant profile projection were fetched, resolved state (`answered`, `unknown`, `redacted`, `unavailable`, or `live_consent`), required flag, intended disposition (`fill`, `preserve`, `ask`, `defer_optional`, or `blocked`), and committed flag. Run `node "<skill-dir>/scripts/validate-profile-lookup.js" receipt.json` before presenting a packet. This validator checks local accounting; it does not call Trackly or prove a fetch happened. Retain actual lookup and committed-control evidence locally. Answered compatible fields must be filled and verified or preserve a user edit; they cannot appear in the questions. Optional unknown demographics may stay blank without interrupting the user. Required unknown facts and genuinely live decisions can be asked together after known answers commit. An unavailable profile lookup is a lookup problem, never evidence that the user has no saved answer.
+Resolve `<skill-dir>` to the loaded skill’s absolute directory before invoking the command, regardless of the application repository working directory. Include explicit `workMode` (`accessible_execution` or `fixed_inspection`) in the value-free lookup receipt. `profileRevision` must be a positive safe integer for accessible execution; fixed inspection also permits zero. Missing or unknown work mode fails closed.
+
 
 For diversity surveys check the schema's gender identity, transgender, sexual orientation, ethnicity, age range, disability, veteran and any other visible concepts. Match supported option synonyms, such as Hispanic/Latino to Hispanic/Latine, without inventing identity. A negative disability or veteran answer excludes that option; it does not prove “None of the above” for a multi-select community question that also asks about parenthood, immigration or neurodiversity. Leave unsupported optional options unselected.
 

package/skills/trackly-apply/references/handoff-compatibility.md

@@ -1,4 +1,4 @@
-# Browser handoff compatibility — 4.9.0
+# Browser handoff compatibility — 4.9.1
 
 This preservation-only policy supersedes contradictory returned-receipt and finalizer requirements in this skill. All backend, submission, resume, origin, ownership, form integrity, and actual visibility gates remain unchanged. Never fabricate evidence.
 

package/skills/trackly-apply/scripts/validate-phase-checkpoint.js

@@ -419,8 +419,9 @@ function validateSelection(receipt, expectedContext) {
     const normalized = receipt.approvedJobIds.filter((id) => Number.isSafeInteger(id) && id > 0);
     if (normalized.length !== receipt.approvedJobIds.length) errors.push('approvedJobIds must contain positive safe integers');
     if (new Set(normalized).size !== normalized.length) errors.push('approvedJobIds must be unique');
-    if (receipt.approvedJobIds.length === 0 && receipt.queueExhausted !== true) {
-      errors.push('approvedJobIds may be empty only when queueExhausted is true');
+    if (receipt.approvedJobIds.length === 0
+        && (receipt.workMode !== 'accessible_execution' || receipt.queueExhausted !== true)) {
+      errors.push('approvedJobIds may be empty only for accessible_execution when queueExhausted is true');
     }
   }
   requireTrue(errors, receipt, 'approvalRecorded');

package/skills/trackly-apply/scripts/validate-profile-lookup.js

@@ -3,8 +3,9 @@
 const fs = require('node:fs');
 function validate(receipt) {
   const errors = [];
-  if (!receipt || !Number.isSafeInteger(receipt.profileRevision) || receipt.profileRevision < 1 || !Array.isArray(receipt.controls) || !receipt.controls.length) return ['invalid_receipt'];
-  if (Object.keys(receipt).some(k => !['profileRevision', 'controls'].includes(k))) errors.push('unexpected_receipt_fields');
+  if (!receipt || !Number.isSafeInteger(receipt.profileRevision) || receipt.profileRevision < (receipt.workMode === 'fixed_inspection' ? 0 : 1) || !Array.isArray(receipt.controls) || !receipt.controls.length) return ['invalid_receipt'];
+  if (Object.keys(receipt).some(k => !['workMode', 'profileRevision', 'controls'].includes(k))) errors.push('unexpected_receipt_fields');
+  if (!['accessible_execution', 'fixed_inspection'].includes(receipt.workMode)) errors.push('invalid_work_mode');
   const seen = new Set();
   for (const c of receipt.controls) {
     if (!c || typeof c !== 'object' || Array.isArray(c)) { errors.push('invalid_control'); continue; }