job-iq 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,45 @@
1
+ name: ci
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+
7
+ jobs:
8
+ test:
9
+ name: ${{ matrix.os }} / py${{ matrix.python }}
10
+ runs-on: ${{ matrix.os }}
11
+ strategy:
12
+ fail-fast: false
13
+ matrix:
14
+ os: [ubuntu-latest, macos-latest, windows-latest]
15
+ python: ["3.11", "3.12", "3.13", "3.14"]
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - name: Install uv and the matrix Python
20
+ uses: astral-sh/setup-uv@v5
21
+ with:
22
+ python-version: ${{ matrix.python }}
23
+
24
+ - name: Sync dependencies
25
+ run: uv sync --group dev
26
+
27
+ - name: Lint
28
+ run: uv run ruff check .
29
+
30
+ - name: Format check
31
+ run: uv run ruff format --check .
32
+
33
+ - name: Tests
34
+ run: uv run pytest
35
+
36
+ - name: Build the wheel
37
+ run: uv build
38
+
39
+ # Pinned filename on purpose: the smoke test must use the artifact, not the
40
+ # source tree. Bump this when the version bumps.
41
+ - name: Install the wheel in an isolated environment and import it
42
+ run: >-
43
+ uv run --no-project
44
+ --with dist/job_iq-0.1.0-py3-none-any.whl
45
+ python -c "import job_iq; print(job_iq.__version__)"
@@ -0,0 +1,23 @@
1
+ # Virtual environments and local state
2
+ .venv/
3
+ .local/
4
+
5
+ # Build artefacts
6
+ dist/
7
+ build/
8
+ *.egg-info/
9
+
10
+ # Databases (D14: dev DB lives at .local/job-iq.db)
11
+ *.db
12
+ *.db-wal
13
+ *.db-shm
14
+
15
+ # Tool caches
16
+ __pycache__/
17
+ *.py[cod]
18
+ .pytest_cache/
19
+ .ruff_cache/
20
+
21
+ # Editor / OS noise
22
+ .DS_Store
23
+ Thumbs.db
job_iq-0.1.0/AGENTS.md ADDED
@@ -0,0 +1,43 @@
1
+ # Ground truth for this repository
2
+
3
+ Applies to **any agent working here**, regardless of which MCP client or coding tool you are. Named `AGENTS.md` deliberately: no vendor names, no per-client files (DESIGN D15).
4
+
5
+ ## What this is
6
+
7
+ A local stdio MCP server that remembers job listings and reports what is new and eligible. SQLite, one file, no UI, no network calls.
8
+
9
+ ## Current target: v0
10
+
11
+ **Read `docs/PLAN.md` → "v0 — build this now" before writing any code.** That section is the only spec that matters right now.
12
+
13
+ In v0 terms:
14
+
15
+ - One file, `job_iq_v0.py`, at the repo root. Do not modify `src/`, `pyproject.toml`, or `migrations/`.
16
+ - Database at `.local/job-iq.db` beside the code, override `JOB_IQ_DB`. **No `platformdirs`, no `%APPDATA%`, no per-OS path logic.**
17
+ - Three tables: `jobs`, `dismissed`, `settings`. No migrations framework — `CREATE TABLE IF NOT EXISTS`.
18
+ - No HTTP listener, no web UI, no setup link, no token. Rules are defaults in the code, overridden through the `config` tool into `settings`.
19
+ - Four tools: `remember_jobs`, `digest`, `dismiss`, `config`.
20
+ - No config file read at runtime. SQLite is the only writable store (D2).
21
+ - Any stdio MCP client can launch it. Nothing in it may be client-specific.
22
+
23
+ ## What is parked
24
+
25
+ `DESIGN.md`, and most of `PLAN.md`, describe v1: a loopback settings UI, `platformdirs` storage, migrations, a fifteen-table schema, phase gates. **Do not build that now.** Those documents remain as design record; they are not instructions. Where they disagree with `PLAN.md`'s v0 section, v0 wins.
26
+
27
+ `docs/old_session.md` is a raw design transcript, not specification. Superseded decisions live there.
28
+
29
+ ## Read in this order
30
+
31
+ 1. `docs/PLAN.md` → the v0 section. The spec.
32
+ 2. `docs/STATUS.md` → what actually exists and was verified.
33
+ 3. `docs/ARCHITECTURE.md` → how it fits together (v0 section first).
34
+ 4. `docs/DESIGN.md` → decisions and rationale, for when a question comes up.
35
+
36
+ ## Rules
37
+
38
+ - Build only what the v0 spec lists. If something is missing, say so in one line and stop.
39
+ - Never write to stdout. stdout is the MCP wire; logging to stderr.
40
+ - SQLite is the only writable store.
41
+ - Pin `mcp==2.3.0`. API: `from mcp.server import MCPServer`, `MCPServer(name=..., version=..., instructions=...)`, `.run("stdio")`. There is no `FastMCP` and no module-level `mcp.run()` — see `src/job_iq/server.py`.
42
+ - Do not add: a CLI, a scheduler, a daemon, a web UI, a second database, auto-apply, fit scores, embeddings, `platformdirs`, migrations.
43
+ - No new documents. Fix the code, not the prose.
job_iq-0.1.0/CLAUDE.md ADDED
@@ -0,0 +1,5 @@
1
+ # Moved
2
+
3
+ The ground-truth file for this repository is [AGENTS.md](AGENTS.md).
4
+
5
+ This file exists only because some hosts and coding tools read this specific filename and nothing else. It carries no content of its own, so there is nothing here to drift out of date or contradict the real file. If you are a human reading this: the name was a mistake, and `AGENTS.md` is the host-neutral one (DESIGN D15).
job_iq-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,54 @@
1
+ Metadata-Version: 2.5
2
+ Name: job-iq
3
+ Version: 0.1.0
4
+ Summary: A local, single-user tool that remembers a job search.
5
+ Requires-Python: >=3.11
6
+ Requires-Dist: mcp==2.3.0
7
+ Requires-Dist: platformdirs>=4.2
8
+ Requires-Dist: starlette>=0.40
9
+ Requires-Dist: uvicorn>=0.30
10
+ Description-Content-Type: text/markdown
11
+
12
+ # job-iq
13
+
14
+ A local memory for a job search. Your AI client finds the jobs; job-iq remembers them, and tells you which ones are new and eligible.
15
+
16
+ ## What it does
17
+
18
+ You search for jobs the way you already do. job-iq stores what was found in a small database next to itself, records what you ruled out and why, and gives you a short digest of what is new. Because it remembers, a job you rejected last month does not come back this month, and the job feed's 14-day window stops being your memory limit.
19
+
20
+ Not an auto-applier, not a scraper, not a website, not a ranking engine. It never contacts anyone.
21
+
22
+ ## Running it
23
+
24
+ It is a single file that any MCP client can launch. There is nothing to install and nothing to configure in a browser.
25
+
26
+ Claude Desktop, `claude_desktop_config.json`:
27
+
28
+ ```json
29
+ {"mcpServers": {"job-iq": {"command": "uv", "args": ["run", "--project", "D:\\path\\to\\job-iq", "python", "job_iq_v0.py"]}}}
30
+ ```
31
+
32
+ Cursor and other stdio clients take the same command in their own config block. The launch command is the only thing that differs between clients.
33
+
34
+ ## Using it
35
+
36
+ 1. Ask your client to search startup.jobs for roles you want.
37
+ 2. Tell it to remember the results. They are stored in `.local/job-iq.db` beside `job_iq_v0.py`.
38
+ 3. Ask for a digest. You get up to six roles that are new, pass your rules, and do not require travel — plus a count of what was excluded and why.
39
+ 4. When you rule something out, say so. When you apply, say so. Both are recorded, and neither comes back.
40
+
41
+ ## Rules it applies
42
+
43
+ Defaults live in the code and can be changed by asking:
44
+
45
+ - which role slugs to search
46
+ - which countries count, and whether "no country listed" counts
47
+ - your pay floor
48
+ - the words that mean a job requires travel
49
+
50
+ Ask "what's my config" to see them; ask "set my floor to 100000" to change one. Changes go into the database, not a config file.
51
+
52
+ ## Status
53
+
54
+ **v0, being built.** What exists and what was verified is in [docs/STATUS.md](docs/STATUS.md). The design record for the larger product is in [docs/DESIGN.md](docs/DESIGN.md) and is parked; the v0 spec is in [docs/PLAN.md](docs/PLAN.md).
job_iq-0.1.0/README.md ADDED
@@ -0,0 +1,43 @@
1
+ # job-iq
2
+
3
+ A local memory for a job search. Your AI client finds the jobs; job-iq remembers them, and tells you which ones are new and eligible.
4
+
5
+ ## What it does
6
+
7
+ You search for jobs the way you already do. job-iq stores what was found in a small database next to itself, records what you ruled out and why, and gives you a short digest of what is new. Because it remembers, a job you rejected last month does not come back this month, and the job feed's 14-day window stops being your memory limit.
8
+
9
+ Not an auto-applier, not a scraper, not a website, not a ranking engine. It never contacts anyone.
10
+
11
+ ## Running it
12
+
13
+ It is a single file that any MCP client can launch. There is nothing to install and nothing to configure in a browser.
14
+
15
+ Claude Desktop, `claude_desktop_config.json`:
16
+
17
+ ```json
18
+ {"mcpServers": {"job-iq": {"command": "uv", "args": ["run", "--project", "D:\\path\\to\\job-iq", "python", "job_iq_v0.py"]}}}
19
+ ```
20
+
21
+ Cursor and other stdio clients take the same command in their own config block. The launch command is the only thing that differs between clients.
22
+
23
+ ## Using it
24
+
25
+ 1. Ask your client to search startup.jobs for roles you want.
26
+ 2. Tell it to remember the results. They are stored in `.local/job-iq.db` beside `job_iq_v0.py`.
27
+ 3. Ask for a digest. You get up to six roles that are new, pass your rules, and do not require travel — plus a count of what was excluded and why.
28
+ 4. When you rule something out, say so. When you apply, say so. Both are recorded, and neither comes back.
29
+
30
+ ## Rules it applies
31
+
32
+ Defaults live in the code and can be changed by asking:
33
+
34
+ - which role slugs to search
35
+ - which countries count, and whether "no country listed" counts
36
+ - your pay floor
37
+ - the words that mean a job requires travel
38
+
39
+ Ask "what's my config" to see them; ask "set my floor to 100000" to change one. Changes go into the database, not a config file.
40
+
41
+ ## Status
42
+
43
+ **v0, being built.** What exists and what was verified is in [docs/STATUS.md](docs/STATUS.md). The design record for the larger product is in [docs/DESIGN.md](docs/DESIGN.md) and is parked; the v0 spec is in [docs/PLAN.md](docs/PLAN.md).
@@ -0,0 +1,68 @@
1
+ # job-iq — how the software works
2
+
3
+ **Current target: v0.** One file, two tables plus settings, no HTTP listener, database beside the code. The full v0 spec lives in `docs/PLAN.md` under "v0 — build this now"; this page explains how the pieces fit.
4
+
5
+ ## v0 — what runs
6
+
7
+ ```
8
+ user
9
+ │ types in chat
10
+ ▼
11
+ ┌──────────────┐ spawns, speaks MCP over stdio ┌────────────────────────┐
12
+ │ any MCP │ ──────────────────────────────────▶│ job_iq_v0.py │
13
+ │ client │◀────────────────────────────────── │ · MCP server (stdio) │
14
+ │ (Claude │ JSON-RPC on stdin/stdout │ · sqlite3 │
15
+ │ Desktop, │ └───────────┬────────────┘
16
+ │ Cursor, …) │ │
17
+ └──────────────┘ ┌───────────▼────────────┐
18
+ │ also connects to │ .local/job-iq.db │
19
+ ▼ │ jobs, dismissed, │
20
+ ┌──────────────┐ the client fetches; │ settings │
21
+ │ startup.jobs │ job-iq remembers └────────────────────────┘
22
+ │ MCP │
23
+ └──────────────┘
24
+ ```
25
+
26
+ Four facts that matter:
27
+
28
+ 1. **job-iq does not fetch jobs.** The client calls startup.jobs, then hands listings to `remember_jobs`.
29
+ 2. **job-iq opens no port and has no web UI in v0.** There is nothing to configure in a browser. Rules are defaults in the code, overridden through the `config` tool, stored in the `settings` table.
30
+ 3. **The database sits beside the code** — `.local/job-iq.db` next to `job_iq_v0.py`, override `JOB_IQ_DB`. No `platformdirs`, no `%APPDATA%`, no per-OS path logic in v0.
31
+ 4. **Any stdio MCP client can use it**, because nothing in it is client-specific. Each client needs its own config block naming the launch command; the server does not care which one launched it.
32
+
33
+ ## Sequence A — remembering listings
34
+
35
+ 1. The user asks for jobs. The client calls `startup.jobs.search_jobs`.
36
+ 2. The skill tells the model to call `job-iq.remember_jobs` with the listings.
37
+ 3. job-iq validates each row, upserts on `source_job_id`, and returns how many were new.
38
+ 4. If a row carries a `description`, job-iq scans it against the travel vocabulary and stores `travel_flag` as `1` (matched), `0` (scanned, no match) or `NULL` (no description supplied, not scanned).
39
+ 5. `last_ingest_at` is written to `settings` on every call, including one that stored nothing.
40
+
41
+ Re-running the same listings creates no duplicates. That is the test.
42
+
43
+ ## Sequence B — a digest
44
+
45
+ 1. The user asks for a digest.
46
+ 2. job-iq selects jobs seen in the last N days (default 7) that are not dismissed, not marked applied, not `travel_flag = 1`, whose country is allowed, and whose salary clears the floor when a number can be read out of the string.
47
+ 3. Jobs with `travel_flag IS NULL` are listed as **unscanned**, never as eligible.
48
+ 4. Output is a table of at most 6 rows plus a footer counting what was excluded and why.
49
+ 5. Every job the user does not see is accounted for by a dismissal row or by the footer count.
50
+
51
+ ## Sequence C — dismissing or applying
52
+
53
+ 1. The user says a job is out, or that they applied.
54
+ 2. The model calls `dismiss(job_id, reason)`, using reason `applied` for an application.
55
+ 3. One row, one table. A repeat call is a no-op.
56
+
57
+ ## v1 — parked, not current
58
+
59
+ The larger design exists and is recorded, but it is **not** what anyone should build now: a loopback settings UI on `127.0.0.1` with a token and `Host`-header check, `platformdirs`-based storage with Roaming on Windows, `PRAGMA user_version` migrations, a fifteen-table schema, and a phase-gated build. That is product work for strangers installing from PyPI. It resumes only when v0 works and the author says so.
60
+
61
+ None of it may leak into v0: no listener, no `platformdirs`, no migrations framework, no UI dependencies (`fastapi`, `uvicorn`, `jinja2`, `htmx`).
62
+
63
+ ## Invariants
64
+
65
+ - **stdout is the wire.** Nothing but MCP frames on it; logging goes to stderr.
66
+ - **One writable store.** SQLite only. No config file read at runtime.
67
+ - **job-iq never contacts an employer, never applies, never sends email.**
68
+ - **No client-specific code.** No host detection, no vendor-named files the package depends on.
@@ -0,0 +1,195 @@
1
+ # job-iq — design record
2
+
3
+ Status: Phase 0 complete — the package builds and serves MCP over stdio. Phase 1 not started. Phase-by-phase progress and evidence: `docs/STATUS.md`.
4
+ This file is the authoritative record of what was decided and why. It exists so a future session does not re-open settled questions.
5
+
6
+ ## How to read this
7
+
8
+ - **SETTLED** decisions are not to be reopened without a *new constraint* — new information, not a preference.
9
+ - Each decision records the alternative that was rejected, so the argument does not repeat.
10
+ - Where this file contradicts an earlier design draft, the earlier draft was wrong. The corrections log at the bottom says why.
11
+
12
+ ## What job-iq is
13
+
14
+ A local, single-user tool that remembers a job search. It stores every listing it is given, records why each was kept or dropped, and produces a short digest of what is new and eligible. It is built for the author first and shared second.
15
+
16
+ **Not:** a scraper farm, an auto-applier, a ranking engine, a SaaS, a multi-tenant service.
17
+
18
+ ## Non-goals for v1
19
+
20
+ - No auto-apply, no form filling, no contacting employers.
21
+ - No embeddings, no fit scores, no ML ranking.
22
+ - No multi-source ingestion.
23
+ - No CLI, no Docker, no long-running daemon, no internal scheduler.
24
+ - No web deployment. The HTTP server is loopback-only and short-lived.
25
+
26
+ ## Decisions
27
+
28
+ ## Scope change — v0 first
29
+
30
+ The v0 spec in `docs/PLAN.md` supersedes this document wherever they conflict.
31
+
32
+ For v0: one file, three tables, database beside the code, defaults in code with overrides in a `settings` table, no HTTP listener, no `platformdirs`.
33
+
34
+ Specifically superseded **for v0 only**:
35
+
36
+ - **D1** — no second transport. No listener, no settings UI, no token.
37
+ - **D14** — no `platformdirs`, no `%APPDATA%`, no per-OS path logic. The database sits next to the file; `JOB_IQ_DB` overrides.
38
+ - **D18's Roaming clause** — not applicable until v1 packaging.
39
+ - **D3** — defaults in code, overrides in `settings`. The shipped-versus-user split is not needed yet.
40
+
41
+ Still in force for v0: **D2** (SQLite is the only writable store), **D12** (reasons are rows, though v0 keeps them as free text in `dismissed.reason`), **D13** (no prediction), **D15** (no per-client code or vendor-named files), **D16** (travel is deterministic, tri-state, set at ingest), **D17** (an application is recorded only because the user said so — in v0 it is `dismiss(job_id, "applied")`).
42
+
43
+ ### D1 — One process, two transports — SETTLED
44
+
45
+ A stdio MCP server plus a loopback HTTP admin UI on an ephemeral port, in the same process, sharing one SQLite handle. FastAPI + Jinja2 + htmx v4, server-rendered, no build step.
46
+
47
+ **Why:** a configuration UI needs a browser, and a stdio server cannot open one by itself. Same process means one write path.
48
+ **Rejected:** HTML forms returned in chat (host-specific, so configuration works on some clients and dead-ends on others); a separate daemon process (another lifecycle to manage, another thing to break on Windows).
49
+
50
+ ### D2 — The database is the only writable store — SETTLED
51
+
52
+ Configuration and policy live in rows. A `policy.md` may be generated as an export for humans; it is never read as input.
53
+
54
+ **Why:** two writable surfaces diverge. Sooner or later the file and the DB disagree and nobody knows which is true. This is the same failure that produced a duplicated exclusion and a missing application in the author's manual handoff file.
55
+ **Rejected:** markdown with YAML front-matter as the source of truth — correct for one person's private repo, wrong for a package strangers install, where users would be editing YAML to configure software and upgrades could clobber it.
56
+
57
+ ### D3 — Tool defaults ship; user facts start empty — SETTLED
58
+
59
+ The package seeds search mechanics, dedupe rules, output defaults, the travel grep vocabulary and the reason vocabulary. User facts — resume path, positioning, target roles, countries, comp band, hard constraints — are empty until the user fills them in.
60
+
61
+ **Why:** the author's current handoff file mixes the two. A distributed tool cannot ship anyone's personal facts.
62
+
63
+ ### D4 — First run blocks tool calls — SETTLED
64
+
65
+ If the profile is empty, every *work* tool raises `ToolError` — in `mcp==2.3.0` that is `mcp.server.mcpserver.exceptions.ToolError`, verified against the installed SDK. `open_settings` is the one exception: it is non-blocking by design (D5). In MCP v2 a raising tool does not throw at the client: it returns a normal result with `is_error=True` and the message in `content`, where the model reads it and hands the user the link. The message contains the URL on its own line as a bare string.
66
+
67
+ One active setup session at a time: the *same* URL is returned on every blocked call until setup completes or the token TTL (10 minutes) expires. Returning a fresh token per call would invalidate the link the user already clicked.
68
+
69
+ **Rejected:** soft warning instead of blocking (users ignore warnings, then wonder why nothing works); a token per call (breaks the link).
70
+
71
+ ### D5 — Second door: `open_settings` — SETTLED
72
+
73
+ An ordinary MCP tool, always available, returning the same UI URL and spinning the listener on demand. Non-blocking: it returns the link and nothing else fails meanwhile.
74
+
75
+ **Why:** closing the listener after first-run setup otherwise leaves no way to change anything.
76
+
77
+ ### D6 — The UI configures; it does not do the job — SETTLED
78
+
79
+ The UI writes settings only. Assessments, ingestion and digest generation are called by the agent through MCP tools, never through the UI.
80
+
81
+ **The HTTP listener is the settings surface and nothing else.** What it actually serves:
82
+
83
+ - full HTML pages rendered by Jinja2;
84
+ - HTML fragments for htmx swaps, plus the htmx response headers those swaps use (`HX-Redirect`, `HX-Trigger` and friends);
85
+ - the static assets that makes possible: one vendored htmx JS file and a stylesheet. Server-rendered, no build step (D1);
86
+ - form `POST`s (url-encoded / multipart), cookies carrying the setup session, and redirects;
87
+ - static assets and fragments are gated by the same single-use token as the pages (D7), and no route mutates state on `GET`.
88
+
89
+ What it never speaks: MCP/JSON-RPC. There is no tool endpoint, no `tools/call` route, and an MCP host cannot point at it. The tool surface is stdio-only in v1 (D1, D15). "Not MCP" is the invariant; "HTML plus its assets" is merely how a server-rendered UI is delivered.
90
+
91
+ ### D7 — Loopback security — SETTLED
92
+
93
+ Bind `127.0.0.1` only. Ephemeral port. One token per setup session: minted when the listener starts, carried in the URL, required on every request (query string, or the session cookie it sets), 10-minute TTL, invalidated when setup completes. While a session is live every blocked call returns the *same* URL (D4); after the TTL a new token is minted and the old URL dies. Reject any request whose `Host` header is not `127.0.0.1:<port>` or `localhost:<port>` — the DNS-rebinding defence, not optional. No state-changing GETs. Close the listener once setup completes or the TTL expires.
94
+
95
+ ### D8 — No CLI — SETTLED
96
+
97
+ **Rejected:** a `job-iq configure` CLI. Non-technical users will not use it, so it cannot be the primary path, and a fallback nobody exercises ships broken. Every job it would have done is covered by the UI plus `export_settings`/`import_settings`.
98
+ **Still undecided, not blocking:** a `--import-settings <path>` startup flag on the MCP process itself. It is a flag, not a CLI, and it is the only remaining answer to "the UI cannot start."
99
+
100
+ ### D9 — Settings are read per call — SETTLED
101
+
102
+ No in-process caching. The UI writes settings from a different request context, and a stale copy is how someone changes their comp floor and watches the tool ignore it.
103
+
104
+ ### D10 — v1 ingestion is agent-mediated, coordinated by a skill — SETTLED
105
+
106
+ The user's client connects to the startup.jobs MCP directly *and* to job-iq. Sequence: search startup.jobs → `job-iq.ingest_jobs` → `job-iq.render_digest`. The skill encodes sequence, payload shape and prohibitions (never paraphrase a title, never invent a salary, pass ids and minimal fields rather than whole descriptions). Every startup.jobs call in that sequence is made by the agent, under the skill's instruction; job-iq performs no network I/O in v1 and holds no credential.
107
+
108
+ **Why:** one-line install, no API key, no credential step, works with any MCP the host already has.
109
+ **Cost accepted:** fidelity depends on the model; the ingest payload becomes a public contract and must be strictly validated; ingestion cannot run unattended.
110
+ **Rejected for v1:** a direct REST adapter (needs a free API key, one more setup step, and a new-user install should be one line); an MCP client inside job-iq (config duplication with the client, and it means executing third-party packages on a stranger's machine).
111
+ **Deferred:** REST adapter in v1.1 for determinism and unattended runs; MCP-client mode for users who prefer it.
112
+
113
+ ### D11 — No internal scheduler — SETTLED
114
+
115
+ Ingestion is **staleness-triggered**: tools check `last_ingest_at` and refresh inline when it is older than the configured threshold (default 12h). Scheduled runs are external — the author drives twice-weekly digests with a DSH scheduled task.
116
+
117
+ **Why:** MCP servers are launched by clients, not clocks. Any internal scheduler is a daemon by another name, and it needs a CLI entry point that D8 removed.
118
+ **Rejected:** cron, Task Scheduler and launchd integrations in v1; APScheduler inside the server.
119
+
120
+ ### D12 — Drop reasons are a table, not a hardcoded enum — SETTLED
121
+
122
+ `reason_vocabulary(code, label, suppresses, requires_note)`, seeded with defaults, editable in the UI. A separate `reason_note` carries free text.
123
+
124
+ **Why:** this dissolves the "closed list or free text" question without a decision. Adding a reason is a row, not a migration, and `suppresses` lets `authorization` and `travel_required` hide a job permanently while `stack_mismatch` only records.
125
+
126
+ ### D13 — Expand for memory, not prediction — SETTLED
127
+
128
+ v1 tables exist so nothing is forgotten. `companies`, `contacts`, `company_facts` and `job_snapshots` are deferred until real data justifies them.
129
+
130
+ **Rejected:** embeddings, fit scoring, any column that predicts rather than records. A deterministic rule plus a written reason beats a number nobody can explain six months later.
131
+
132
+ ### D14 — Database location — SETTLED
133
+
134
+ Installed default: `platformdirs` (`%APPDATA%` on Windows, `~/Library/Application Support` on macOS, `$XDG_DATA_HOME` on Linux). Development override: `JOB_IQ_DB` environment variable pointing at `.local/job-iq.db` inside this repo, which is gitignored.
135
+
136
+ **Why:** `uvx` runs from a cache directory that is replaced on upgrade, so a DB stored there is deleted on a version bump.
137
+
138
+ ### D15 — Any MCP host, over stdio — SETTLED
139
+
140
+ job-iq is an MCP server, not a plugin for a particular app. The contract is the MCP protocol over stdio: **any host that can launch a local stdio server can use it.** No per-host code, no per-host behaviour, no allowlist. The installation line differs only in each host's own config syntax, which is a README formatting problem, not a compatibility one.
141
+
142
+ **What compatibility actually requires, and is therefore the work:**
143
+ - Conform to the SDK's protocol version (`mcp==2.3.0`), and depend on nothing host-specific for rendering.
144
+ - First-run blocking returns `ToolError` with the URL in the message *content* (D4) — the one place a bad host assumption could hide.
145
+ - Nothing on stdout, ever (Hard rules). A host that parses JSON-RPC strictly must still work.
146
+
147
+ **Testing is a sample, not a supported set.** Verify on at least two independent hosts per phase — the author's are Claude Desktop, ChatGPT Desktop, Pi, VS Code Copilot and DSH, but they are examples, not a matrix. Passing on one host and failing on another is a bug in job-iq, not a compatibility gap, and gets fixed in job-iq.
148
+
149
+ **The one real boundary is transport, not clients.** A host that cannot launch a local process (ChatGPT web, hosted chat) would need an **MCP-level** HTTP transport. v1 has none, and the loopback listener is not one — it is the settings UI (D6): HTML pages, htmx fragments and their static assets, gated by a single-use token and closed after setup or TTL. It must never carry MCP. If an MCP-over-HTTP transport is ever wanted it is a separate endpoint with its own threat model in v1.1 — never a per-host special case, and never an extra route on the settings listener.
150
+
151
+ **Consequence:** the README shows config snippets for whatever hosts the reader uses, and Phase 1's exit criterion is observed on two independent hosts.
152
+
153
+ ### D16 — travel_flag is deterministic, set at ingest, and tri-state — SETTLED
154
+
155
+ The startup.jobs listing payload has no travel field, so travel is the one thing the schema must encode that the source does not. `jobs.travel_flag` is computed **by job-iq, at ingest, by scanning the description body** against the travel grep vocabulary held in `settings` — never by the model, because a model-decided boolean is neither deterministic nor auditable.
156
+
157
+ Three states, never two: `1` matched, `0` scanned and did not match, `NULL` not scanned yet. `NULL` must never be read as "no travel". A silent false negative here is the exact failure that nearly lost TraceGains, and an unattended run will make that mistake every time.
158
+
159
+ **The body comes from the agent, never from job-iq.** In v1 job-iq makes no network call at all: it has no startup.jobs client, no API access, no key (D10). The skill tells the agent to call startup.jobs' `get_job` for the ids that are new and pass the body to job-iq, where the scan happens deterministically against the vocabulary in `settings`. D10's "minimal fields, not whole descriptions" still governs the search → ingest payload — dumping fifty bodies per run is exactly the waste it forbids — while the detail pass is bounded to new ids, which is the only place the body is needed.
160
+
161
+ **Rejected:** asking the model to set `travel_flag` from its reading of the posting (non-deterministic, unauditable); defaulting unmatched to `0` (turns "not checked" into "no travel", which is the failure above); job-iq fetching postings itself in v1 (that is the adapter's job in Phase 3b, and it would break the no-key install).
162
+
163
+ ### D17 — Applications are written on the user's instruction — SETTLED
164
+
165
+ `mark_applied(job_id, applied_at?, channel?)` upserts `applications` on `job_id` and appends an `applied` row to `events`. The agent calls it only when the user says they applied. The digest excludes anything with an application row.
166
+
167
+ **Why:** the earlier rule ("nothing writes `applications` in v1") existed to stop an agent inventing state. That concern was about *inference*, not instruction: a user saying "I applied to Moxie" is an instruction, and without a write path the application list stays manual, which is the thing this tool exists to end.
168
+ **Rejected:** inferring applications from the user's browsing or email (unreliable, and a privacy surface); overloading `assess` with a magic reason code (conflates a judgement with a fact).
169
+
170
+ ### D18 — Runtime state, the audit trail, and the Windows path — SETTLED
171
+
172
+ - **`last_ingest_at` is runtime state**, stored as the `settings` key `runtime.last_ingest_at`, written by every `ingest_jobs` call including one that stored nothing. It is *not* derived from `MAX(jobs.last_seen_at)`, because an empty ingest would then look stale forever and the tool would nag on every read. The `runtime.` prefix keeps state visibly distinct from shipped defaults sharing the table.
173
+ - **A settings change appends a `settings_changed` row to `events`** (`job_id` NULL, payload naming the changed keys). There is **no `settings_history` table in v1**; one log beats two, and `events` already exists.
174
+ - **Windows location is `%APPDATA%\job-iq\`, which is Roaming.** Phase 1 must call `platformdirs.user_data_dir("job-iq", roaming=True)` and `user_log_dir("job-iq", roaming=True)`. The platformdirs default (`AppData\Local`) disagrees with the README, with D14's `%APPDATA%`, and with `logging_config.log_directory()`, which already resolves to Roaming.
175
+
176
+ ## Corrections log
177
+
178
+ - **"An MCP server cannot call another MCP server."** Wrong as stated. The protocol gives the *server role* no client channel, but one process can hold both roles at once — the MCP proxy/gateway/aggregator pattern. D10 chooses agent-mediated ingestion for simplicity, not because a client inside job-iq is impossible.
179
+ - **Policy in markdown.** Reversed for D2 once the target changed from one private repo to a package others install.
180
+ - **CLI-first.** Reversed for D8.
181
+ - **"Two transports" read as two MCP transports.** Wrong. D1's second transport is a browser talking HTML to a settings form, not MCP over HTTP. The HTTP listener exists to configure settings and does nothing else; the tool surface is stdio-only. Conflating the two is how a settings page quietly becomes a second attack surface.
182
+ - **Target clients as a supported list.** Wrong for D15. An MCP server's contract is the protocol: any host that launches a stdio server works. Named hosts are test samples; a failure on one is a bug in job-iq, not a compatibility gap.
183
+
184
+ ## Hard rules
185
+
186
+ - **stdout is the wire.** The SDK diverts *flushed* stdout to stderr while serving, but unbuffered or import-time `print()` still corrupts the stream. Logging module only, handlers flushing to stderr.
187
+ - **One write path.** UI, MCP tools and any future adapter all go through the same repository functions.
188
+ - **WAL and foreign keys.** `PRAGMA journal_mode=WAL` and `PRAGMA foreign_keys=ON` at connect.
189
+ - **No secrets in logs.** No API keys, no resume contents, no job descriptions beyond what a digest needs.
190
+ - **Pin `mcp==2.3.0`.** Pre-stable; v1→v2 already renamed the server class (`MCPServer`, not `FastMCP`).
191
+
192
+ ## Open questions
193
+
194
+ - `--import-settings <path>` startup flag: yes or no. Deferrable, non-blocking.
195
+ - Digest shape: hardcoded default or a `settings` row. Recommendation from the design session: a `settings` row `digest_max_rows = 6` plus a column list, rather than hardcoded. The column set observed in use: `Title | Company | Location | Salary | URL | Why it fits`. 3–6 rows.