@jsonresume/jobs 0.10.0 → 0.12.0

package/README.md

@@ -102,7 +102,7 @@ npx @jsonresume/jobs
 
 The TUI has three main regions:
 
-- **Header** — shows the app title, active search profile name, tab bar (All / Interested / Applied / Maybe / Passed) with live counts, and any active filter pills
+- **Header** — shows the app title, active search profile name, tab bar (All / New / Reviewed / Interested / Applied / Maybe / Passed) with live counts, and any active filter pills
 - **Content area** — job list in list view, or a split-pane layout (40% compact list + 60% job detail) in detail view
 - **Status bar** — context-sensitive keyboard hints, loading/reranking indicators, and toast notifications
 
@@ -118,11 +118,12 @@ The TUI has three main regions:
 - **Export** — press `e` to export your shortlist, applied, and maybe lists to a `job-hunt-YYYY-MM-DD.md` markdown file in the current directory
 - **Toast notifications** — instant feedback on every action (marking, exporting, refreshing)
 - **Help modal** — press `?` for a full keyboard reference organized by section
+- **Dossier research** — press `c` to spawn a Claude Code CLI session that researches the company, role, and generates a comprehensive dossier with fit assessment, talking points, interview prep, and compensation context. Results stream live and are cached server-side so you can revisit them anytime. Supports switching between multiple dossiers without restarting. Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
 - **AI summaries** — press `Space` for a per-job AI summary, or `S` for a batch review of all visible jobs (requires `OPENAI_API_KEY`)
 - **Vim-style navigation** — `j`/`k` to move, `g`/`G` to jump to first/last, `Ctrl+U`/`Ctrl+D` to page up/down
 - **Responsive columns** — job list columns (score, title, company, location, salary) adapt to terminal width on resize
 - **Smart filtering** — passed and dismissed jobs are excluded server-side with 5x over-fetch, so you always get a full set of fresh results
-- **Cached results** — job data is cached locally for 24 hours to minimize API calls; press `R` to force a fresh fetch
+- **Cached results** — job data is cached locally for 2 hours to minimize API calls; press `R` to force a fresh fetch
 
 ### Keyboard Shortcuts
 
@@ -145,6 +146,7 @@ The TUI has three main regions:
 | `f` | Manage filters |
 | `/` | Search profiles |
 | `Space` | AI summary for current job |
+| `c` | Research dossier via Claude Code CLI |
 | `S` | AI batch review of visible jobs |
 | `e` | Export shortlist to markdown |
 | `R` | Force refresh (bypass cache) |
@@ -160,6 +162,7 @@ The TUI has three main regions:
 | `o` | Open HN post in browser |
 | `i` / `x` / `m` / `p` | Mark job state |
 | `Space` | AI summary |
+| `c` | Research dossier |
 | `Esc` / `q` | Back to full list |
 
 #### Filters Panel
@@ -203,6 +206,8 @@ In split-pane detail view, the left pane shows a compact list with just score, t
 | Tab | Shows |
 |-----|-------|
 | All | All jobs from the current search (excludes passed/dismissed) |
+| New | Jobs with no state and no dossier — completely untouched |
+| Reviewed | Jobs with a dossier but no decision yet |
 | Interested | Jobs you marked with `i` |
 | Applied | Jobs you marked with `x` |
 | Maybe | Jobs you marked with `m` |
@@ -262,6 +267,232 @@ npx @jsonresume/jobs help                                # All options
 | `not_interested` | ✗ | Not for you (hidden from future searches) |
 | `dismissed` | 👁 | Hide from results (hidden from future searches) |
 
+## Architecture
+
+![architecture](./architecture.svg)
+
+## API Reference
+
+All endpoints live at `https://registry.jsonresume.org/api/v1`. Authenticated endpoints require a `Bearer` token in the `Authorization` header.
+
+### Authentication
+
+```bash
+# Generate an API key (no auth required)
+curl -s -X POST https://registry.jsonresume.org/api/v1/keys \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"YOUR_GITHUB_USERNAME"}'
+# → { "key": "jr_username_xxxxx", "username": "username" }
+
+# Use in all subsequent requests
+export JSONRESUME_API_KEY="jr_username_xxxxx"
+AUTH="Authorization: Bearer $JSONRESUME_API_KEY"
+```
+
+### GET /api/v1/me
+
+Returns your resume and profile.
+
+```bash
+curl -s -H "$AUTH" https://registry.jsonresume.org/api/v1/me
+# → { "username": "...", "resume": { ... } }
+```
+
+### GET /api/v1/jobs
+
+Get jobs matched to your resume via vector similarity.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `top` | int | 20 | Number of results (max 100) |
+| `days` | int | 30 | How far back to search |
+| `remote` | bool | false | Remote jobs only |
+| `min_salary` | int | 0 | Minimum salary in thousands (e.g. `150` = $150k) |
+| `search` | string | | Keyword filter across all fields |
+| `search_id` | uuid | | Use a saved search profile's embedding |
+| `rerank` | bool | auto | LLM reranking (defaults to true when `search_id` is set) |
+
+```bash
+# Basic search
+curl -s -H "$AUTH" "https://registry.jsonresume.org/api/v1/jobs?top=50&days=30"
+
+# Remote jobs, $150k+, keyword filter
+curl -s -H "$AUTH" "https://registry.jsonresume.org/api/v1/jobs?top=50&remote=true&min_salary=150&search=react"
+
+# Using a search profile with reranking
+curl -s -H "$AUTH" "https://registry.jsonresume.org/api/v1/jobs?top=50&search_id=UUID&rerank=true"
+```
+
+**Response:**
+```json
+{
+  "jobs": [
+    {
+      "id": 237247,
+      "uuid": "...",
+      "title": "Full-Stack Engineer",
+      "company": "Acme Corp",
+      "location": { "city": "San Francisco", "countryCode": "US" },
+      "remote": "Full",
+      "salary": "$180k - $220k",
+      "salary_usd": 180000,
+      "experience": "Senior",
+      "type": "Full-time",
+      "description": "...",
+      "skills": [{ "name": "React" }, { "name": "Node.js" }],
+      "url": "https://news.ycombinator.com/item?id=...",
+      "posted_at": "2026-03-01T...",
+      "similarity": 0.654,
+      "rerank_score": 8,
+      "combined_score": 0.74,
+      "state": "interested",
+      "has_dossier": true
+    }
+  ],
+  "total": 50
+}
+```
+
+### POST /api/v1/jobs
+
+Match jobs against a provided resume — **no auth required**. Useful for local mode or one-off queries.
+
+```bash
+curl -s -X POST https://registry.jsonresume.org/api/v1/jobs \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "resume": { "basics": { "name": "...", "label": "..." }, "skills": [...] },
+    "top": 20,
+    "days": 30,
+    "remote": true
+  }'
+```
+
+### GET /api/v1/jobs/:id
+
+Full details for a single job including raw posting content.
+
+```bash
+curl -s -H "$AUTH" https://registry.jsonresume.org/api/v1/jobs/237247
+```
+
+### PUT /api/v1/jobs/:id
+
+Mark a job's state.
+
+| Body Param | Type | Description |
+|------------|------|-------------|
+| `state` | string | `interested`, `applied`, `maybe`, `not_interested`, or `dismissed` |
+| `feedback` | string | Optional reason/notes |
+
+```bash
+# Mark as interested
+curl -s -X PUT -H "$AUTH" -H 'Content-Type: application/json' \
+  https://registry.jsonresume.org/api/v1/jobs/237247 \
+  -d '{"state":"interested","feedback":"great remote role, strong tech stack"}'
+
+# Mark as applied
+curl -s -X PUT -H "$AUTH" -H 'Content-Type: application/json' \
+  https://registry.jsonresume.org/api/v1/jobs/237247 \
+  -d '{"state":"applied","feedback":"applied via email 2026-03-13"}'
+
+# Pass on a job
+curl -s -X PUT -H "$AUTH" -H 'Content-Type: application/json' \
+  https://registry.jsonresume.org/api/v1/jobs/237247 \
+  -d '{"state":"not_interested","feedback":"salary too low"}'
+```
+
+### GET /api/v1/jobs/:id/dossier
+
+Fetch saved research dossier for a job.
+
+```bash
+curl -s -H "$AUTH" https://registry.jsonresume.org/api/v1/jobs/237247/dossier
+# → { "content": "# Dossier\n\n## Compensation...", "created_at": "..." }
+# → { "content": null } if no dossier exists
+```
+
+### PUT /api/v1/jobs/:id/dossier
+
+Save or update a research dossier.
+
+```bash
+curl -s -X PUT -H "$AUTH" -H 'Content-Type: application/json' \
+  https://registry.jsonresume.org/api/v1/jobs/237247/dossier \
+  -d '{"content":"# Company Research\n\n..."}'
+```
+
+### PUT /api/v1/resume
+
+Update your resume on the registry.
+
+```bash
+curl -s -X PUT -H "$AUTH" -H 'Content-Type: application/json' \
+  https://registry.jsonresume.org/api/v1/resume \
+  -d @resume.json
+# → { "username": "...", "message": "Resume updated" }
+```
+
+### GET /api/v1/searches
+
+List your saved search profiles.
+
+```bash
+curl -s -H "$AUTH" https://registry.jsonresume.org/api/v1/searches
+# → { "searches": [{ "id": "uuid", "name": "Remote React", "prompt": "...", "filters": [...] }] }
+```
+
+### POST /api/v1/searches
+
+Create a new search profile. The server generates a HyDE embedding from your prompt + resume.
+
+```bash
+curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' \
+  https://registry.jsonresume.org/api/v1/searches \
+  -d '{"name":"Remote React","prompt":"remote React roles at climate tech startups"}'
+# → { "search": { "id": "uuid", "name": "Remote React", "prompt": "..." } }
+```
+
+### PUT /api/v1/searches/:id
+
+Update a search profile's name or filters.
+
+```bash
+curl -s -X PUT -H "$AUTH" -H 'Content-Type: application/json' \
+  https://registry.jsonresume.org/api/v1/searches/UUID \
+  -d '{"name":"Updated Name","filters":[{"type":"remote"},{"type":"minSalary","value":"150"}]}'
+```
+
+### DELETE /api/v1/searches/:id
+
+Delete a search profile.
+
+```bash
+curl -s -X DELETE -H "$AUTH" https://registry.jsonresume.org/api/v1/searches/UUID
+# → { "ok": true }
+```
+
+### Example: Automated Job Application Workflow
+
+Use the API to build your own automation — e.g., have Claude in Chrome review your "maybe" jobs and apply:
+
+```bash
+# 1. Get all jobs, filter to "maybe" state
+JOBS=$(curl -s -H "$AUTH" "https://registry.jsonresume.org/api/v1/jobs?top=100" \
+  | jq '[.jobs[] | select(.state == "maybe")]')
+
+# 2. For each, get the full detail + dossier
+for ID in $(echo $JOBS | jq -r '.[].id'); do
+  DETAIL=$(curl -s -H "$AUTH" "https://registry.jsonresume.org/api/v1/jobs/$ID")
+  DOSSIER=$(curl -s -H "$AUTH" "https://registry.jsonresume.org/api/v1/jobs/$ID/dossier")
+  echo "$DETAIL" | jq '{title: .title, company: .company, url: .url}'
+  # ... use the detail + dossier to apply, then mark as applied
+  curl -s -X PUT -H "$AUTH" -H 'Content-Type: application/json' \
+    "https://registry.jsonresume.org/api/v1/jobs/$ID" \
+    -d '{"state":"applied","feedback":"auto-applied via script"}'
+done
+```
+
 ## How Ranking Works
 
 The system uses a five-stage pipeline to match and rank jobs against your resume.
@@ -335,7 +566,7 @@ All local data is stored under `~/.jsonresume/`:
 |------|----------|
 | `~/.jsonresume/config.json` | API key and username (registry mode) |
 | `~/.jsonresume/filters.json` | Saved filter presets per search profile |
-| `~/.jsonresume/cache/` | Cached job results (auto-expires after 24 hours) |
+| `~/.jsonresume/cache/` | Cached job results (auto-expires after 2 hours) |
 | `~/.jsonresume/local-marks.json` | Job marks in local mode |
 
 The export command writes `job-hunt-YYYY-MM-DD.md` to your current working directory.
@@ -363,7 +594,8 @@ The TUI is built with [React Ink](https://github.com/vadimdemedes/ink) v6 using
 | `src/tui/JobDetail.js` | Full job detail view (standalone and split-pane) |
 | `src/tui/StatusBar.js` | Key hints, loading state, toasts |
 | `src/tui/useJobs.js` | Job fetching, caching, tab filtering |
-| `src/tui/useAI.js` | AI summary and batch review integration |
+| `src/tui/useAI.js` | AI summary, dossier research (Claude CLI), batch review |
+| `src/tui/AIPanel.js` | Dossier/AI split-pane panel with scroll and export |
 | `src/tui/useSearches.js` | Search profile CRUD |
 | `src/filters.js` | Persistent filter storage per search profile |
 | `src/export.js` | Markdown export |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonresume/jobs",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Search Hacker News jobs matched against your JSON Resume",
   "bin": {

package/src/api.js

@@ -57,5 +57,13 @@ export function createApiClient({ baseUrl, apiKey }) {
         body: JSON.stringify(updates),
       }),
     deleteSearch: (id) => request(`/searches/${id}`, { method: 'DELETE' }),
+
+    // Dossiers
+    fetchDossier: (id) => request(`/jobs/${id}/dossier`),
+    saveDossier: (id, content) =>
+      request(`/jobs/${id}/dossier`, {
+        method: 'PUT',
+        body: JSON.stringify({ content }),
+      }),
   };
 }

package/src/cache.js

@@ -3,7 +3,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 
 const CACHE_DIR = join(homedir(), '.jsonresume', 'cache');
-const CACHE_TTL = 24 * 60 * 60 * 1000; // 1 day
+const CACHE_TTL = 2 * 60 * 60 * 1000; // 2 hours
 
 function ensureDir() {
   try {
@@ -14,6 +14,7 @@ function ensureDir() {
 function cacheKey(params) {
   const parts = [`jobs_${params.days || 30}_${params.top || 100}`];
   if (params.searchId) parts.push(`s_${params.searchId.slice(0, 8)}`);
+  if (params.mode) parts.push(params.mode);
   return parts.join('_') + '.json';
 }
 

package/src/localApi.js

@@ -10,6 +10,7 @@ export function createLocalApiClient({ baseUrl, resume }) {
   const base = baseUrl || DEFAULT_BASE_URL;
 
   return {
+    mode: 'local',
     fetchJobs: async (params = {}) => {
       const body = {
         resume,
@@ -68,5 +69,9 @@ export function createLocalApiClient({ baseUrl, resume }) {
     deleteSearch: async () => {
       throw new Error('Search profiles require a registry account');
     },
+
+    // Dossiers — local mode stores in memory only
+    fetchDossier: async () => ({ content: null }),
+    saveDossier: async () => ({ saved: true }),
   };
 }

package/src/tui/AIPanel.js

@@ -1,37 +1,140 @@
+import { useState, useEffect, useRef } from 'react';
 import { Box, Text, useInput } from 'ink';
 import Spinner from 'ink-spinner';
 import { h } from './h.js';
 
-export default function AIPanel({ text, loading, error, onDismiss, isActive }) {
+export default function AIPanel({
+  text,
+  loading,
+  error,
+  onDismiss,
+  onExport,
+  onRegenerate,
+  onMark,
+  job,
+  isActive,
+  mode,
+}) {
+  const [scroll, setScroll] = useState(0);
+  const maxRows = Math.max((process.stdout.rows || 30) - 8, 10);
+  const exportMsg = useRef(null);
+
+  // Enable mouse reporting for scroll wheel
+  useEffect(() => {
+    if (!process.stdout.isTTY) return;
+    // Enable mouse wheel reporting (SGR mode)
+    process.stdout.write('\x1b[?1000h\x1b[?1006h');
+    const onData = (data) => {
+      const str = data.toString();
+      // SGR mouse: \x1b[<button;col;row(M|m)
+      const match = str.match(/\x1b\[<(\d+);(\d+);(\d+)([Mm])/);
+      if (match) {
+        const btn = parseInt(match[1], 10);
+        if (btn === 64) setScroll((s) => Math.max(0, s - 3));
+        if (btn === 65) setScroll((s) => s + 3);
+      }
+    };
+    process.stdin.on('data', onData);
+    return () => {
+      process.stdin.removeListener('data', onData);
+      if (process.stdout.isTTY) {
+        process.stdout.write('\x1b[?1000l\x1b[?1006l');
+      }
+    };
+  }, []);
+
   useInput(
-    (_input, key) => {
+    (input, key) => {
       if (key.escape) onDismiss();
+      if (input === 'e' && text && onExport) {
+        const filename = onExport();
+        if (filename) {
+          exportMsg.current = filename;
+          setTimeout(() => {
+            exportMsg.current = null;
+          }, 3000);
+        }
+      }
+      if (input === 'r' && job && onRegenerate && !loading) {
+        onRegenerate(job);
+      }
+      // Mark keys
+      if (job && onMark) {
+        if (input === 'i') onMark(job.id, 'interested');
+        if (input === 'x') onMark(job.id, 'applied');
+        if (input === 'm') onMark(job.id, 'maybe');
+        if (input === 'p') onMark(job.id, 'not_interested');
+      }
+      if (key.upArrow || input === 'k') setScroll((s) => Math.max(0, s - 1));
+      if (key.downArrow || input === 'j') setScroll((s) => s + 1);
+      if (key.pageUp || (key.ctrl && input === 'u'))
+        setScroll((s) => Math.max(0, s - 20));
+      if (key.pageDown || (key.ctrl && input === 'd')) setScroll((s) => s + 20);
+      if (input === 'g') setScroll(0);
+      if (input === 'G' && text) {
+        const lines = text.split('\n');
+        setScroll(Math.max(0, lines.length - maxRows));
+      }
     },
     { isActive }
   );
 
+  const isCover = mode === 'cover';
+  const title = isCover ? '📋 Job Dossier (via Claude Code)' : '🤖 AI Analysis';
+  const color = isCover ? 'green' : 'magenta';
+  const loadingMsg = isCover
+    ? ' Claude is researching… (streaming live)'
+    : ' Thinking...';
+
+  let displayText = text;
+  let totalLines = 0;
+  if (text) {
+    const lines = text.split('\n');
+    totalLines = lines.length;
+    if (loading) {
+      // While streaming, auto-scroll to bottom
+      displayText = lines.slice(Math.max(0, lines.length - maxRows)).join('\n');
+    } else {
+      // When done, allow manual scroll
+      const start = Math.min(scroll, Math.max(0, lines.length - maxRows));
+      displayText = lines.slice(start, start + maxRows).join('\n');
+    }
+  }
+
+  const scrollHint =
+    !loading && totalLines > maxRows
+      ? `j/k scroll · g/G top/bottom · ${scroll + 1}–${Math.min(
+          scroll + maxRows,
+          totalLines
+        )}/${totalLines}`
+      : '';
+
+  const exportHint = text ? ' · e export' : '';
+  const regenHint = isCover && !loading && job ? ' · r regenerate' : '';
+  const statusLine =
+    loading && text
+      ? 'Streaming… ESC to cancel'
+      : loading
+      ? 'ESC to cancel'
+      : scrollHint
+      ? `${scrollHint}${exportHint}${regenHint}  ·  ESC to dismiss`
+      : `ESC to dismiss${exportHint}${regenHint}`;
+
   return h(
     Box,
     {
       flexDirection: 'column',
-      borderStyle: 'double',
-      borderColor: 'magenta',
-      padding: 1,
-      marginX: 2,
+      flexGrow: 1,
+      paddingX: 1,
     },
-    h(Text, { bold: true, color: 'magenta' }, '🤖 AI Analysis'),
+    h(Text, { bold: true, color }, title),
     h(Text, null, ' '),
     loading
-      ? h(
-          Box,
-          null,
-          h(Spinner, { type: 'dots' }),
-          h(Text, null, ' Thinking...')
-        )
+      ? h(Box, null, h(Spinner, { type: 'dots' }), h(Text, null, loadingMsg))
       : null,
     error ? h(Text, { color: 'red' }, `Error: ${error}`) : null,
-    text ? h(Text, { wrap: 'wrap' }, text) : null,
+    displayText ? h(Text, { wrap: 'wrap' }, displayText) : null,
     h(Text, null, ' '),
-    h(Text, { dimColor: true }, 'Press ESC to dismiss')
+    h(Text, { dimColor: true }, statusLine)
   );
 }