pathscout 0.3.0__tar.gz

pathscout-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PathScout contributors
+
+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.

pathscout-0.3.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: pathscout
+Version: 0.3.0
+Summary: Local-only role discovery for finding high-fit startup opportunities.
+Author: PathScout contributors
+License: MIT
+Project-URL: Homepage, https://github.com/ckoglmeier/pathscout
+Project-URL: Repository, https://github.com/ckoglmeier/pathscout
+Project-URL: Issues, https://github.com/ckoglmeier/pathscout/issues
+Keywords: job-search,career,role-discovery,local-first
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PathScout
+
+PathScout is a local-only role discovery CLI for finding high-fit startup opportunities before they become obvious job posts.
+
+It fetches broad signals, scores them against a personal fit profile, stores deduped observations in SQLite, and emits a canonical JSON artifact plus a readable Markdown digest.
+
+## What PathScout Is
+
+- A local-only CLI for monitoring companies, careers pages, RSS feeds, portfolio lists, and manual notes.
+- A fit-profile engine for surfacing target roles, hidden-search hypotheses, and weaker watch signals.
+- An explainable findings scanner: every surfaced item includes score, tier, reasons, flags, source metadata, and suppression state.
+
+## What PathScout Is Not
+
+- It is not a hosted marketplace.
+- It is not a recruiting CRM.
+- It is not a general-purpose job board scraper.
+- It does not provide hosted storage, sync, or remote persistence.
+
+## Install
+
+From GitHub:
+
+```bash
+pipx install git+https://github.com/ckoglmeier/pathscout.git
+```
+
+From a local checkout:
+
+```bash
+pipx install .
+```
+
+For development:
+
+```bash
+python3 -m pathscout doctor
+python3 -m pathscout run --dry-run --format both
+```
+
+## Quick Start
+
+```bash
+pathscout start
+pathscout next
+pathscout init
+pathscout setup
+pathscout doctor
+pathscout run --format both
+```
+
+`pathscout start` is a read-only startup checklist. It shows what exists, what is missing, and the next recommended command without creating or editing files.
+
+`pathscout next` prints only the next recommended action. `/next` is also accepted as an alias.
+
+`pathscout setup` is an interactive guided setup flow. It walks through environment, role/function, locations, avoid terms, background, proof points, constraints, and network context in order, saving answers into local JSON files as it goes.
+
+During `init`, PathScout asks two onboarding questions in this order:
+
+1. What is the right environment for you?
+2. What is the right role for you?
+
+For scripted setup, pass answers directly:
+
+```bash
+pathscout init \
+  --environment "Remote AI startups" \
+  --role "Founding Product Lead"
+```
+
+Use `--no-input` to create default sample config without prompts.
+
+Outputs:
+
+- `data/pathscout.sqlite`: local state and dedupe history.
+- `outputs/latest.json`: canonical machine-readable findings artifact.
+- `outputs/latest.md`: human-readable digest rendered from the JSON findings.
+- `outputs/packages/`: optional portable opportunity packages created from findings.
+- `config/profile.json`: personal fit profile.
+- `config/background.sample.json`: tracked example candidate context.
+- `config/background.local.json`: private candidate context and proof points.
+- `config/sources.json`: source adapter configuration.
+- `config/watchlist.json`: curated company list.
+- `config/suppressions.json`: structured ignored findings.
+
+## Configuration
+
+PathScout uses schema-versioned JSON files.
+
+`config/profile.json` is the personal fit model. It contains target roles, stages, domains, excluded domains, location preferences, travel constraints, authority terms, and scoring thresholds.
+
+`config/sources.json` describes inputs. Each source uses this adapter contract:
+
+```json
+{
+  "id": "watchlist_careers",
+  "type": "watchlist_careers",
+  "name": "Watchlist careers pages",
+  "enabled": true,
+  "config": {
+    "path": "config/watchlist.json"
+  }
+}
+```
+
+`id` is stable and scriptable. `name` is display-only. `type` selects the adapter. `config` is adapter-specific.
+
+`config/suppressions.json` stores structured ignores:
+
+```json
+{
+  "schema_version": 1,
+  "suppressions": [
+    {
+      "id": "finding-content-hash",
+      "scope": "finding",
+      "reason": "Not a fit",
+      "expires_at": "2026-12-31",
+      "created_at": "2026-06-29"
+    }
+  ]
+}
+```
+
+Suppressions affect output visibility. They do not delete observations from SQLite.
+
+## Source Types
+
+The v0.2 runner supports standard-library fetches for:
+
+- `manual`: config-entered notes for companies or opportunities you want tracked.
+- `watchlist`: turns every active watchlist company into a hidden-search observation.
+- `watchlist_careers`: probes active watchlist companies' careers pages for posted role evidence.
+- `portfolio`: turns companies from `config/portfolio.json` into relationship-context observations.
+- `web_page`: fetches a single web page.
+- `rss`: fetches an RSS or Atom feed.
+
+`radar_portfolio` remains as a deprecated alias for one release. Use `portfolio` for new config.
+
+## Commands
+
+```bash
+pathscout start
+pathscout next
+pathscout init
+pathscout setup
+pathscout doctor
+pathscout watchlist
+pathscout portfolio
+pathscout review
+pathscout explain <finding-id>
+pathscout notes <finding-id> --add "Question to verify before outreach"
+pathscout thesis <finding-id>
+pathscout package <finding-id>
+pathscout suppress <finding-id> --reason "Not a fit"
+pathscout run --format json
+pathscout run --format markdown
+pathscout run --format both
+```
+
+Useful paths can be overridden:
+
+```bash
+pathscout run \
+  --profile config/profile.json \
+  --sources config/sources.json \
+  --watchlist config/watchlist.json \
+  --suppressions config/suppressions.json \
+  --db data/pathscout.sqlite \
+  --json-out outputs/latest.json \
+  --out outputs/latest.md
+```
+
+## Digest Tiers
+
+- `Act Now`: explicit target role or recruiter-visible mandate with strong fit signals.
+- `Hidden Search Hypothesis`: no role posted, but company signals suggest a likely hiring need.
+- `Watch Signal`: weaker signal, lower-level posting, or incomplete evidence.
+- `Filtered`: captured for history but excluded from the main digest.
+
+## Review And Suppress
+
+Use `review` to scan findings from the latest JSON artifact without opening the file:
+
+```bash
+pathscout review --limit 10
+pathscout review --tier "Act Now"
+```
+
+Use `explain` to inspect why a finding surfaced:
+
+```bash
+pathscout explain <finding-id>
+```
+
+Use `notes` to keep local judgment attached to a finding or company:
+
+```bash
+pathscout notes <finding-id> --add "Ask a former employee whether this team is still founder-led"
+pathscout notes --company "Northstar Robotics"
+```
+
+Use `thesis` to generate a local role-thesis package from a finding. Copy `config/background.sample.json` to `config/background.local.json` first if you want the thesis to include private candidate context:
+
+```bash
+pathscout thesis <finding-id>
+```
+
+Thesis packages are written to `outputs/theses/` and are generated from the same JSON finding objects used by review and Markdown digests. They include the company moment, problem map, proposed function, fit argument, 90-180 day wedge, notes, and evidence gaps. They are thinking artifacts, not generated job descriptions or send-ready outreach.
+
+Use `suppress` to hide a finding from later Markdown digests while keeping the raw observation in SQLite and the finding marked in JSON:
+
+```bash
+pathscout suppress <finding-id> --reason "Not a fit" --expires 2026-12-31
+```
+
+Careers pages are parsed into separate role findings when PathScout can identify role-title rows. If a page does not expose clear role titles, PathScout falls back to one page-level finding.
+
+## Package Exports
+
+Use `package` to create a portable, human-readable and agent-readable opportunity package from a finding in `outputs/latest.json`:
+
+```bash
+pathscout package <finding-id>
+```
+
+Each package includes a manifest, a human Markdown brief, agent instructions, and canonical JSON data under `outputs/packages/`. See `docs/artifacts.md` for the artifact contract.
+
+`config/background.local.json`, legacy `config/background.json`, `data/notes.json`, `outputs/theses/`, and `outputs/packages/` are ignored by default because they may contain private candidate context.
+
+See `DATA_CONTRACT.md` and `docs/source_of_truth.md` for the local-only storage boundary and agent-readable artifact contract. Network source fetches collect evidence for local runs; they are not hosted storage or sync.
+
+## Design Borrowed From
+
+PathScout follows scanner-style findings: stable IDs, evidence, severity-like tiers, reasons, flags, and suppressions.
+
+The config split borrows from dbt-style separation of personal profile from project config. Source IDs follow the pre-commit convention: stable machine IDs plus human names. Suppressions borrow from security scanners: structured ignores with reasons and optional expiration dates.

pathscout-0.3.0/README.md

@@ -0,0 +1,237 @@
+# PathScout
+
+PathScout is a local-only role discovery CLI for finding high-fit startup opportunities before they become obvious job posts.
+
+It fetches broad signals, scores them against a personal fit profile, stores deduped observations in SQLite, and emits a canonical JSON artifact plus a readable Markdown digest.
+
+## What PathScout Is
+
+- A local-only CLI for monitoring companies, careers pages, RSS feeds, portfolio lists, and manual notes.
+- A fit-profile engine for surfacing target roles, hidden-search hypotheses, and weaker watch signals.
+- An explainable findings scanner: every surfaced item includes score, tier, reasons, flags, source metadata, and suppression state.
+
+## What PathScout Is Not
+
+- It is not a hosted marketplace.
+- It is not a recruiting CRM.
+- It is not a general-purpose job board scraper.
+- It does not provide hosted storage, sync, or remote persistence.
+
+## Install
+
+From GitHub:
+
+```bash
+pipx install git+https://github.com/ckoglmeier/pathscout.git
+```
+
+From a local checkout:
+
+```bash
+pipx install .
+```
+
+For development:
+
+```bash
+python3 -m pathscout doctor
+python3 -m pathscout run --dry-run --format both
+```
+
+## Quick Start
+
+```bash
+pathscout start
+pathscout next
+pathscout init
+pathscout setup
+pathscout doctor
+pathscout run --format both
+```
+
+`pathscout start` is a read-only startup checklist. It shows what exists, what is missing, and the next recommended command without creating or editing files.
+
+`pathscout next` prints only the next recommended action. `/next` is also accepted as an alias.
+
+`pathscout setup` is an interactive guided setup flow. It walks through environment, role/function, locations, avoid terms, background, proof points, constraints, and network context in order, saving answers into local JSON files as it goes.
+
+During `init`, PathScout asks two onboarding questions in this order:
+
+1. What is the right environment for you?
+2. What is the right role for you?
+
+For scripted setup, pass answers directly:
+
+```bash
+pathscout init \
+  --environment "Remote AI startups" \
+  --role "Founding Product Lead"
+```
+
+Use `--no-input` to create default sample config without prompts.
+
+Outputs:
+
+- `data/pathscout.sqlite`: local state and dedupe history.
+- `outputs/latest.json`: canonical machine-readable findings artifact.
+- `outputs/latest.md`: human-readable digest rendered from the JSON findings.
+- `outputs/packages/`: optional portable opportunity packages created from findings.
+- `config/profile.json`: personal fit profile.
+- `config/background.sample.json`: tracked example candidate context.
+- `config/background.local.json`: private candidate context and proof points.
+- `config/sources.json`: source adapter configuration.
+- `config/watchlist.json`: curated company list.
+- `config/suppressions.json`: structured ignored findings.
+
+## Configuration
+
+PathScout uses schema-versioned JSON files.
+
+`config/profile.json` is the personal fit model. It contains target roles, stages, domains, excluded domains, location preferences, travel constraints, authority terms, and scoring thresholds.
+
+`config/sources.json` describes inputs. Each source uses this adapter contract:
+
+```json
+{
+  "id": "watchlist_careers",
+  "type": "watchlist_careers",
+  "name": "Watchlist careers pages",
+  "enabled": true,
+  "config": {
+    "path": "config/watchlist.json"
+  }
+}
+```
+
+`id` is stable and scriptable. `name` is display-only. `type` selects the adapter. `config` is adapter-specific.
+
+`config/suppressions.json` stores structured ignores:
+
+```json
+{
+  "schema_version": 1,
+  "suppressions": [
+    {
+      "id": "finding-content-hash",
+      "scope": "finding",
+      "reason": "Not a fit",
+      "expires_at": "2026-12-31",
+      "created_at": "2026-06-29"
+    }
+  ]
+}
+```
+
+Suppressions affect output visibility. They do not delete observations from SQLite.
+
+## Source Types
+
+The v0.2 runner supports standard-library fetches for:
+
+- `manual`: config-entered notes for companies or opportunities you want tracked.
+- `watchlist`: turns every active watchlist company into a hidden-search observation.
+- `watchlist_careers`: probes active watchlist companies' careers pages for posted role evidence.
+- `portfolio`: turns companies from `config/portfolio.json` into relationship-context observations.
+- `web_page`: fetches a single web page.
+- `rss`: fetches an RSS or Atom feed.
+
+`radar_portfolio` remains as a deprecated alias for one release. Use `portfolio` for new config.
+
+## Commands
+
+```bash
+pathscout start
+pathscout next
+pathscout init
+pathscout setup
+pathscout doctor
+pathscout watchlist
+pathscout portfolio
+pathscout review
+pathscout explain <finding-id>
+pathscout notes <finding-id> --add "Question to verify before outreach"
+pathscout thesis <finding-id>
+pathscout package <finding-id>
+pathscout suppress <finding-id> --reason "Not a fit"
+pathscout run --format json
+pathscout run --format markdown
+pathscout run --format both
+```
+
+Useful paths can be overridden:
+
+```bash
+pathscout run \
+  --profile config/profile.json \
+  --sources config/sources.json \
+  --watchlist config/watchlist.json \
+  --suppressions config/suppressions.json \
+  --db data/pathscout.sqlite \
+  --json-out outputs/latest.json \
+  --out outputs/latest.md
+```
+
+## Digest Tiers
+
+- `Act Now`: explicit target role or recruiter-visible mandate with strong fit signals.
+- `Hidden Search Hypothesis`: no role posted, but company signals suggest a likely hiring need.
+- `Watch Signal`: weaker signal, lower-level posting, or incomplete evidence.
+- `Filtered`: captured for history but excluded from the main digest.
+
+## Review And Suppress
+
+Use `review` to scan findings from the latest JSON artifact without opening the file:
+
+```bash
+pathscout review --limit 10
+pathscout review --tier "Act Now"
+```
+
+Use `explain` to inspect why a finding surfaced:
+
+```bash
+pathscout explain <finding-id>
+```
+
+Use `notes` to keep local judgment attached to a finding or company:
+
+```bash
+pathscout notes <finding-id> --add "Ask a former employee whether this team is still founder-led"
+pathscout notes --company "Northstar Robotics"
+```
+
+Use `thesis` to generate a local role-thesis package from a finding. Copy `config/background.sample.json` to `config/background.local.json` first if you want the thesis to include private candidate context:
+
+```bash
+pathscout thesis <finding-id>
+```
+
+Thesis packages are written to `outputs/theses/` and are generated from the same JSON finding objects used by review and Markdown digests. They include the company moment, problem map, proposed function, fit argument, 90-180 day wedge, notes, and evidence gaps. They are thinking artifacts, not generated job descriptions or send-ready outreach.
+
+Use `suppress` to hide a finding from later Markdown digests while keeping the raw observation in SQLite and the finding marked in JSON:
+
+```bash
+pathscout suppress <finding-id> --reason "Not a fit" --expires 2026-12-31
+```
+
+Careers pages are parsed into separate role findings when PathScout can identify role-title rows. If a page does not expose clear role titles, PathScout falls back to one page-level finding.
+
+## Package Exports
+
+Use `package` to create a portable, human-readable and agent-readable opportunity package from a finding in `outputs/latest.json`:
+
+```bash
+pathscout package <finding-id>
+```
+
+Each package includes a manifest, a human Markdown brief, agent instructions, and canonical JSON data under `outputs/packages/`. See `docs/artifacts.md` for the artifact contract.
+
+`config/background.local.json`, legacy `config/background.json`, `data/notes.json`, `outputs/theses/`, and `outputs/packages/` are ignored by default because they may contain private candidate context.
+
+See `DATA_CONTRACT.md` and `docs/source_of_truth.md` for the local-only storage boundary and agent-readable artifact contract. Network source fetches collect evidence for local runs; they are not hosted storage or sync.
+
+## Design Borrowed From
+
+PathScout follows scanner-style findings: stable IDs, evidence, severity-like tiers, reasons, flags, and suppressions.
+
+The config split borrows from dbt-style separation of personal profile from project config. Source IDs follow the pre-commit convention: stable machine IDs plus human names. Suppressions borrow from security scanners: structured ignores with reasons and optional expiration dates.

pathscout-0.3.0/pathscout/__init__.py

@@ -0,0 +1,5 @@
+"""Local-first role discovery radar."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.3.0"

pathscout-0.3.0/pathscout/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+