@pragmys/compass 0.0.0-stage → 0.0.1

package/INSTALL.md

@@ -0,0 +1,38 @@
+# Install
+
+Compass is one MCP server. There is no separate skill, plugin or rules file to install: the instructions travel inside the server.
+
+Pin the version in your config. Compass tells you when a newer or a security release exists (`compass_status`) and never updates itself.
+
+Check your client's current documentation before relying on a snippet: MCP configuration formats change.
+
+## Claude Code
+
+```bash
+claude mcp add pragmys-compass -- npx -y @pragmys/compass@VERSION
+```
+
+## Claude Desktop
+
+Install the `.mcpb` bundle from pragmys.com/compass (one click), or add to `claude_desktop_config.json`:
+
+```json
+{ "mcpServers": { "pragmys-compass": { "command": "npx", "args": ["-y", "@pragmys/compass@VERSION"] } } }
+```
+
+## Cursor, Codex and other MCP clients
+
+Add the same command (`npx -y @pragmys/compass@VERSION`) as a stdio MCP server in the client's MCP settings.
+
+## First run
+
+Ask your agent to find jobs, for example "Find backend engineer jobs, and analyse the top 5 in depth". The agent signs you in with a device code on pragmys.com the first time.
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `COMPASS_USAGE=0` | Send no usage record |
+| `COMPASS_REPORT_DIR` | Where HTML reports are written (default: the folder you run from) |
+| `COMPASS_HOME` | Where state and the company index live (default `~/.pragmys-compass`) |
+| `PRAGMYS_TOKEN` | Use this token instead of the stored sign-in (overrides it) |

package/LICENSE

@@ -0,0 +1,59 @@
+Compass by Pragmys: Software Licence
+
+Copyright (c) 2026 Pragmys. All rights reserved.
+
+"Pragmys" and "Compass by Pragmys" are names and marks of Pragmys. Nothing in
+this licence grants any right to use them except to identify the software.
+
+1. Grant. Subject to this licence and the Compass terms of use (TERMS.md),
+   Pragmys grants you a personal, non-exclusive, non-transferable, revocable
+   licence to install and run the unmodified Compass software, in the form in
+   which Pragmys distributes it, on devices you own or control, for your own
+   job search, with your own Pragmys account.
+
+2. Restrictions. You may not, and may not allow anyone else to:
+   a. copy, distribute, sublicense, sell, rent, lease or host the software, or
+      make it available to others as a service;
+   b. modify the software or create derivative works of it;
+   c. decompile, disassemble, reverse engineer or otherwise attempt to derive
+      the source code, algorithms, data files or internal formats of the
+      software, except to the extent this restriction is prohibited by law;
+   d. remove, disable or circumvent any limit, check-in, blocklist, kill
+      switch, version requirement, notice or licence check in the software;
+   e. use the software to build a database of job postings, to resell or
+      redistribute posting content, or to train a model on posting content;
+   f. use the software in violation of law or of the terms of any site it is
+      used with.
+
+3. Ownership. The software, including the source code, the source list, the
+   cleaning and scoring logic, and the documentation, is and remains the
+   property of Pragmys and its licensors. All rights not expressly granted are
+   reserved.
+
+4. Third-party components. The software includes open-source components under
+   their own licences, listed in THIRD_PARTY_NOTICES. Those licences apply to
+   those components and are not changed by this licence.
+
+5. Usage information. The software sends Pragmys a usage record for each run,
+   as described in TERMS.md and shown by the compass_usage_preview tool. You
+   can turn this off with the environment variable COMPASS_USAGE=0.
+
+6. Updates and withdrawal. Pragmys may release updates, may require a minimum
+   version to connect to Pragmys services, and may withdraw support for a
+   version or a source at any time, including in response to a takedown
+   request.
+
+7. Termination. This licence ends automatically if you breach it. On
+   termination you must stop using the software and delete all copies.
+
+8. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE AND NON-INFRINGEMENT. Scores and reports are estimates,
+   not legal, employment or hiring advice.
+
+9. Limitation of liability. TO THE EXTENT PERMITTED BY LAW, PRAGMYS IS NOT
+   LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR
+   ACCOUNT RESTRICTIONS, BLOCKS OR LOST OPPORTUNITIES ARISING FROM USE OF THE
+   SOFTWARE OR OF THE SITES IT IS POINTED AT.
+
+10. Contact. hello@pragmys.com

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# Compass by Pragmys
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Compass finds jobs through your own AI agent and ranks them against the skills you have verified on Pragmys. You say what role you want. Your agent searches and fetches; Compass cleans what it finds, scores it on your device, can run a deeper check on the jobs you pick, and writes a Pragmys-branded HTML report with company names, match %, what you have and what is missing.
+
+Compass is a Pragmys product: free to use with a Pragmys account, closed source, delivered as one signed MCP server. See [LICENSE](LICENSE) and [TERMS.md](TERMS.md).
+
+## What it does
+
+1. **Plan.** `compass_plan` takes the role (and a location only if you give one), returns the sources to read and a private folder for the downloads.
+2. **Find.** Your agent checks in with Compass before each request, fetches public job feeds and company boards, and saves them.
+3. **Score.** `compass_score` cleans the postings (company names, links, duplicates, applicant-directed instructions removed), scores them against your verified skills with the same matcher as the Pragmys extension, and writes the report.
+4. **Deep check.** For the number of jobs you ask for, your agent reads each posting and Compass computes the deeper numbers on your device.
+5. **Finish.** `compass_finish` finalises the report, shows what was sent, and removes the download folder.
+
+## What it does not do
+
+- It does not fetch job sites itself, log in, solve CAPTCHAs or apply. Your agent fetches public feeds; Compass governs the pace and the sources.
+- Pragmys servers do not fetch job sites or receive posting text.
+
+## Sources
+
+Feeds and public job-board APIs only: RemoteOK, Jobicy, Arbeitnow, and Greenhouse, Lever, Ashby and Workable company boards. LinkedIn, Naukri, Indeed, Glassdoor and Wellfound are not supported; use the Pragmys extension on those pages. Some sources are on a blocklist and refused by every tool. `compass_sites` lists what is supported, what each needs, its terms link and the credit it requires.
+
+Compass makes no claim that using any source complies with that source's terms. You are responsible for how you use it.
+
+## Limits
+
+| Rule | Value |
+|---|---|
+| Between requests to a source | 5 to 10 seconds, or the source's stated delay |
+| Pages per source per run / per run | 15 / 40 |
+| Searches per source per day | 5 |
+| Deep checks per run | up to 10 |
+
+## Settings from Pragmys
+
+At status and plan time Compass reads a small settings record from `api.pragmys.com` (cached for an hour; if the call fails the built-in rules apply). Pragmys can use it to switch Compass off, pause a source, block a host (for example after a takedown request), lower the limits above, switch the deep check off, require a minimum version, and show a notice. It never raises a limit above the built-in value, and it carries nothing about you.
+
+## Privacy
+
+- Your Pragmys token is stored in your OS keychain (or a 0600 file) and sent only to the Pragmys API.
+- Compass sends Pragmys one usage record per run: the role you searched, counts per source, timings and refusal codes. Never posting text, links, company names, locations, results, skills or scores. `compass_usage_preview` shows it exactly. Set `COMPASS_USAGE=0` to send nothing.
+- Postings stay on your device and with your own agent and its model provider.
+- Files Compass writes: the HTML report (in the folder you run from, or `COMPASS_REPORT_DIR`), a small state file and a company index in `~/.pragmys-compass/`, and a temporary run folder that is removed when the run finishes.
+
+## Install
+
+See [INSTALL.md](INSTALL.md).
+
+## Takedown
+
+If you operate a site Compass supports and want it removed, email hello@pragmys.com. See [TERMS.md](TERMS.md).

package/SECURITY.md

@@ -0,0 +1,20 @@
+# Security
+
+## Reporting a vulnerability
+
+Email **hello@pragmys.com** with details. Please do not post a security problem publicly. We aim to acknowledge within 2 business days.
+
+## Design
+
+- The Pragmys token is stored in the OS keychain (or a 0600 file if there is none) and sent only to the Pragmys API. It is never printed or logged.
+- The binary holds no secrets. The server enforces authorization: the Compass credential can read only your own skill confidences and send the usage record.
+- Posting text is treated as untrusted. It is cleaned, never executed, instructions inside it are removed and ignored, and tool output does not echo full postings.
+- The usage record is built from counts only; its exact contents are shown by `compass_usage_preview` and can be turned off.
+
+## Network destinations
+
+`api.pragmys.com` (sign-in, your skill confidences, the public skill list, the operator settings record, the usage record) and `pragmys.com` (the signed release manifest, only when you check for an update). Compass itself contacts no job source; your agent does.
+
+## Releases
+
+Binaries are built in CI with provenance attestation and published to npm with provenance; versions are pinned in install snippets. Updates are announced and never applied silently. Where a signed update manifest is published, `compass_update` applies an update only after you confirm and after the download matches the signed checksum; otherwise update through npm.

package/TERMS.md

@@ -0,0 +1,29 @@
+# Compass by Pragmys: terms of use
+
+These terms apply to Compass, a Pragmys product, together with the [LICENSE](LICENSE) and the Pragmys terms of service and privacy policy.
+
+## What you are agreeing to
+
+1. **You run it on your own device, for your own job search,** with your own Pragmys account. Compass does not operate any service that accesses job sites.
+2. **Your agent does the fetching and you are responsible for it.** You must follow each source's terms of service and any instructions it gives (blocks, robots.txt, takedown notices). `compass_sites` lists each source's terms link and the credit it requires. We do not claim that using any source is compliant with its terms.
+3. **No circumvention.** Do not use Compass to get around a block, a login, a CAPTCHA, a rate limit or any access control, and do not remove or raise the limits it applies.
+4. **Personal use.** Do not use Compass to build a database of postings, resell or redistribute posting content, or train models on it.
+5. **Usage information.** Each run sends Pragmys a usage record: the role you searched, whether you gave a location and how many terms, how many deep checks you asked for, request, fetch, keep and drop counts per source, timings, and refusal and failure counts. It never contains posting text, links, company names, location terms, results, skills or scores. It is tied to your Pragmys account and used to run, secure and improve Compass and its source list. Role strings are kept for 90 days and aggregates longer. `compass_usage_preview` shows the exact record; `COMPASS_USAGE=0` turns it off. You can ask for your Compass history to be shown or deleted at hello@pragmys.com.
+6. **Operator settings.** Compass reads settings from Pragmys at status and plan time. Pragmys may use them to switch Compass or a source off, block a host, lower limits, require a minimum version or show a notice, at any time and without a release.
+7. **Posting text** stays on your device and with your own agent and model provider, under their terms. Pragmys does not receive it.
+8. **No warranty.** Compass, its scores and its reports are estimates provided without warranty. They are not legal, employment or hiring advice, and a fit score is not what an employer requires.
+9. **Liability.** To the extent the law allows, Pragmys is not liable for account restrictions, blocks, lost opportunities or any other consequence of using Compass or the sources it is pointed at.
+
+## Takedown and opt-out
+
+If you own or operate a website, or you are an employer or individual named in material this product documents, and you want us to stop supporting access to your site or remove a reference to it:
+
+- Email **hello@pragmys.com**.
+- Include the domain(s) and what you want changed, and a way to verify you control the domain (an email from the domain, or a file at `/.well-known/` on it). You do not need to explain your reasons.
+- We acknowledge within **2 business days** and, for a verified request, remove the site from the supported list and add it to the blocklist within **7 days**.
+- We honour blocks and robots.txt and do not retry after a refusal.
+- Requests about personal data go to the same address.
+
+## Changes
+
+These terms may change with a release; the version that ships with the release you run applies.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,234 @@
+# Third-party notices
+
+Compass by Pragmys includes the open-source components below. Each is used under its own licence.
+
+## @modelcontextprotocol/sdk 1.32.1
+Licence: MIT
+Home: https://modelcontextprotocol.io
+
+```
+MIT License
+
+Copyright (c) 2024 Anthropic, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## ajv 8.20.0
+Licence: MIT
+Home: https://ajv.js.org
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015-2021 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## ajv-formats 3.0.1
+Licence: MIT
+Home: https://github.com/ajv-validator/ajv-formats#readme
+
+```
+MIT License
+
+Copyright (c) 2020 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## fast-deep-equal 3.1.3
+Licence: MIT
+Home: https://github.com/epoberezkin/fast-deep-equal#readme
+
+```
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## fast-uri 3.1.8
+Licence: BSD-3-Clause
+Home: https://github.com/fastify/fast-uri
+
+```
+Copyright (c) 2011-2021, Gary Court until https://github.com/garycourt/uri-js/commit/a1acf730b4bba3f1097c9f52e7d9d3aba8cdcaae
+Copyright (c) 2021-present The Fastify team <https://github.com/fastify/fastify#team>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * The names of any contributors may not be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+                                  *   *   *
+
+The complete list of contributors can be found at:
+- https://github.com/garycourt/uri-js/graphs/contributors
+```
+
+## json-schema-traverse 1.0.0
+Licence: MIT
+Home: https://github.com/epoberezkin/json-schema-traverse#readme
+
+```
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## zod 4.6.7
+Licence: MIT
+Home: https://zod.dev
+
+```
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## zod-to-json-schema 3.25.2
+Licence: ISC
+
+```
+ISC License
+
+Copyright (c) 2020, Stefan Terdell
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
+## Bun runtime (embedded in the compiled binaries)
+Licence: MIT, with bundled components under their own licences, including JavaScriptCore (LGPL-2.1).
+Full text: https://github.com/oven-sh/bun/blob/main/LICENSE.md
+

package/bin/compass.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Launcher for @pragmys/compass. The product ships as a compiled binary in a
+// per-platform package (installed automatically as an optional dependency).
+// This file only finds that binary and runs it with the same stdio.
+'use strict';
+const { spawn } = require('node:child_process');
+const { existsSync } = require('node:fs');
+const { join, dirname } = require('node:path');
+
+const platform = `${process.platform}-${process.arch}`;
+const pkg = `@pragmys/compass-${platform}`;
+const exe = process.platform === 'win32' ? 'compass.exe' : 'compass';
+
+let binary;
+try {
+  binary = join(dirname(require.resolve(`${pkg}/package.json`)), 'bin', exe);
+} catch {
+  /* handled below */
+}
+if (!binary || !existsSync(binary)) {
+  process.stderr.write(
+    `Compass has no build for ${platform}. Supported: darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64.\n` +
+      `If you installed with --no-optional or --omit=optional, reinstall without it.\n`,
+  );
+  process.exit(1);
+}
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => child.kill(sig));
+child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+child.on('error', (e) => { process.stderr.write(`Could not start Compass: ${e.message}\n`); process.exit(1); });

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@pragmys/compass",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Compass by Pragmys: rank jobs your agent finds against your verified evidence. A local MCP server.",
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "pragmys-compass": "bin/compass.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "TERMS.md",
+    "SECURITY.md",
+    "INSTALL.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "optionalDependencies": {
+    "@pragmys/compass-darwin-arm64": "0.0.1",
+    "@pragmys/compass-darwin-x64": "0.0.1",
+    "@pragmys/compass-linux-x64": "0.0.1",
+    "@pragmys/compass-linux-arm64": "0.0.1",
+    "@pragmys/compass-win32-x64": "0.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}