@timurtekb/tekjobs 0.37.1 → 0.38.1

package/app/dist/index.html

@@ -8,7 +8,7 @@
     <link rel="icon" href="/brand/tekjobs-avatar-192.png" type="image/png" sizes="192x192" />
     <link rel="apple-touch-icon" href="/brand/tekjobs-avatar-192.png" />
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@500;600&family=Hanken+Grotesk:wght@400;500;600&family=Azeret+Mono:wght@400;500&display=swap" data-zengin="fonts" />
-    <script type="module" crossorigin src="/assets/index-C77iGKNO.js"></script>
+    <script type="module" crossorigin src="/assets/index-tl8a2c_d.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CR3ppGJT.css">
   </head>
   <body>

package/app/server/mcp.mjs

@@ -48,9 +48,9 @@ export const TOOLS = [
   { name: 'set_criteria', description: 'Replace the criteria JSON block. Pass the full JSON as a string; it is validated before writing.', inputSchema: { type: 'object', properties: { raw: { type: 'string' } }, required: ['raw'] } },
   { name: 'list_companies', description: 'The company watchlist rows (name, ats, slug, tier, status) with each board\'s health: state (failed, zero, stale, never, ok), last success, last attempt, last error.', inputSchema: { type: 'object', properties: {} } },
   { name: 'list_feeds', description: 'The aggregator feeds: whether each is on under the criteria\'s openSources, and how it did on the last scan.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'onboarding_status', description: 'What the onboarding still needs: profile folder, resume, profile note, criteria, first scan. Call this first in a new setup.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'onboarding_status', description: 'What the onboarding still needs, in two groups: `steps` for search ready (profile folder, resume, profile note, criteria, first scan; `complete` when all done) and `writing` for writing ready (resume of record note, Positioning, Voice; `writingReady` when all done). Call this first in a new setup, and once more at the end to report both.', inputSchema: { type: 'object', properties: {} } },
   { name: 'onboarding_materials', description: 'Start the onboarding interview. Returns the resume text, the current profile note, the current criteria JSON, and the interview script to follow step by step. Follow the script; it ends with save_profile, set_criteria and a scan.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'save_profile', description: 'Write Profile/Profile.md in full (markdown with the standard headings). The previous version is kept beside it.', inputSchema: { type: 'object', properties: { markdown: { type: 'string' } }, required: ['markdown'] } },
+  { name: 'save_profile', description: 'Write one profile note in full: Profile/Profile.md by default (markdown with the standard headings), or note=positioning for Profile/Positioning.md (which story leads, the evidence rule, what must never be claimed) or note=voice for Profile/Voice.md (writing rules and one letter they would send). The previous version is kept beside it.', inputSchema: { type: 'object', properties: { markdown: { type: 'string' }, note: { type: 'string', enum: ['profile', 'positioning', 'voice'], description: 'which note; default profile' } }, required: ['markdown'] } },
   { name: 'fetch_link', description: 'Fetch a public page the user gave you (portfolio, GitHub, personal site) as plain text, to fold into the profile. http(s) only; never use it on LinkedIn profile pages.', inputSchema: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] } },
   { name: 'import_resume', description: 'Import a resume file from a local path (PDF, DOCX, Markdown, text): copies it into Profile/ and extracts its text for the interview.', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] } },
   { name: 'add_job', description: 'Add postings the person found themselves, from links (LinkedIn job pages, a company careers page, a Greenhouse/Lever/Ashby posting). Each link is read once, scored with the current criteria, and written as a job note unless the scan already has it or a note with the same company and title exists. A LinkedIn link is opened as a signed-out visitor; if it names the company\'s own apply page on a known board, that page is imported and the LinkedIn link is recorded as where it was seen. Returns one result per link. Up to 25 links.', inputSchema: { type: 'object', properties: { urls: { type: 'array', items: { type: 'string' } } }, required: ['urls'] } },
@@ -63,7 +63,7 @@ export async function call(name, a = {}) {
   switch (name) {
     case 'onboarding_status': return store.onboardingStatus();
     case 'onboarding_materials': return store.onboardingMaterials();
-    case 'save_profile': return store.saveProfile(a.markdown);
+    case 'save_profile': return store.saveProfile(a.markdown, undefined, { note: a.note || 'profile' });
     case 'fetch_link': return store.fetchLink(a.url);
     case 'import_resume': return store.importResume(a.path);
     case 'search_jobs': { const r = store.searchJobs({ q: a.q, location: a.location || '', status: a.status, band: a.band, kind: a.kind, source: a.source, company: a.company, payMin: a.payMin, payMax: a.payMax, payKnown: a.payKnown === true, postedDays: a.postedDays, foundDays: a.foundDays, maxScore: a.maxScore, remoteOnly: a.remote === true, minScore: a.minScore, limit: a.limit || 50 }); return { total: r.total, rows: r.rows.map((j) => ({ id: j.id, score: j.score, company: j.company, title: j.title, location: j.location, pay: j.salary, band: j.payBand, status: j.status, posted: j.posted, url: j.url })) }; }

package/app/server/store.mjs

@@ -1079,7 +1079,8 @@ export function profileSummary() {
     { label: 'Resume files', state: resumes.files.length ? `${resumes.files.length} file${resumes.files.length === 1 ? '' : 's'}${resumes.files.some((f) => f.current) ? ', one is the source' : ''}` : 'no folder yet', level: resumes.files.length ? 'ok' : 'info', where: resumes.dir || '' },
     docState('Profile/Positioning.md', 'Positioning'),
     docState('Profile/Voice.md', 'Voice'),
-    docState('Profile/Snippets.md', 'Snippets (copy panel)'),
+    // The copy panel works from defaults drawn from the profile until the note exists, so its absence is information, not a gap.
+    (() => { const d = docState('Profile/Snippets.md', 'Snippets (copy panel)'); return d.level === 'missing' ? { ...d, level: 'info', state: 'defaults from the profile until you edit it' } : d; })(),
   ];
   // What would trip a reader.
   const attention = [];

package/cli.mjs

@@ -208,8 +208,13 @@ async function main() {
 }
 function printStatus(s) {
   console.log(`\nOnboarding for ${s.dir}:`);
+  console.log('  Search');
   for (const st of s.steps) console.log(`  ${st.done ? '✓' : '·'} ${st.label}${st.done ? '' : `   → ${st.how}`}`);
-  console.log(s.complete ? '\nAll set. The daily scan takes it from here.' : '\nNext: the first unchecked line above.');
+  console.log('  Application writing');
+  for (const st of s.writing || []) console.log(`  ${st.done ? '✓' : '·'} ${st.label}${st.done ? '' : `   → ${st.how}`}`);
+  const search = s.complete ? 'Search ready: the daily scan takes it from here.' : 'Search: not yet; the first unchecked line above is next.';
+  const writing = s.writingReady ? 'Writing ready: drafts read the resume of record, Positioning and Voice.' : 'Writing: not yet; drafts fall back to the imported resume text until the notes above exist.';
+  console.log(`\n${search}\n${writing}`);
 }
 function run(bin, args) { const p = spawn(bin, args, { stdio: 'inherit', env: process.env }); p.on('close', (c) => process.exit(c ?? 0)); }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurtekb/tekjobs",
-  "version": "0.37.1",
+  "version": "0.38.1",
   "description": "A local-first job-search machine: watches hundreds of company job boards, scores every posting against your profile, and files matches into a folder of markdown notes you own. Bring your own LLM through MCP.",
   "type": "module",
   "license": "MIT",

package/run.mjs

@@ -195,7 +195,7 @@ const logLines = [
   `- Criteria: ${criteriaLabel}`,
   // Who started it: the morning task (run.cmd / run.sh), the app, an agent over MCP, or someone at the CLI.
   `- Via: ${process.env.TEKJOBS_RUN_VIA || 'cli'}`,
-  ...extras.map(([n, r]) => `- ${n}: ${r.ok ? `${r.jobs.length} postings${r.thread ? ` (${r.thread})` : ''}` : `failed: ${r.error}`}`),
+  ...extras.map(([n, r]) => `- ${n}: ${r.skipped ? `skipped (${r.skipped})` : r.ok ? `${r.jobs.length} postings${r.thread ? ` (${r.thread})` : ''}` : `failed: ${r.error}`}`),
   ...(failed.length ? [`- Failed slugs: ${failed.map((f) => `${f.name} (${f.ats}:${f.slug} — ${f.error})`).join('; ')}`] : []),
   ...(written.length ? ['', '### New matches', ...written.map(({ job }) => `- **${job.scored.score}** ${job.company} — [${job.title}](${job.url}) · ${job.location || 'n/a'}`)] : []),
   ...(closed.length ? ['', '### Closed since last run', ...closed.map((c) => `- ${c.company} — ${c.title}`)] : []),

package/scraper/health.mjs

@@ -19,10 +19,12 @@ const require_dir = (file) => file.replace(/[\\/][^\\/]*$/, '');
 /** Fold one fetch result into a source's record. `r` is the fetcher's own answer: ok, jobs, error, emptyBoard. */
 export function record(prev = {}, r, now = new Date().toISOString()) {
   const jobs = r.ok ? r.jobs.length : null;
+  // Skipped (an optional source with nothing to read): the attempt is noted, nothing else moves.
+  if (r.skipped) return { ...prev, lastAttempt: now, lastError: '', failStreak: 0, skipped: r.skipped };
   if (!r.ok) return { ...prev, lastAttempt: now, lastError: r.error || 'failed', failStreak: (prev.failStreak || 0) + 1 };
   return {
     ...prev,
-    lastAttempt: now, lastOk: now, lastError: '', failStreak: 0,
+    lastAttempt: now, lastOk: now, lastError: '', failStreak: 0, skipped: '',
     lastJobs: jobs, lastOkJobs: jobs,
     zeroStreak: jobs === 0 ? (prev.zeroStreak || 0) + 1 : 0,
     everJobs: Math.max(prev.everJobs || 0, jobs),
@@ -42,6 +44,7 @@ export function healthState(h, statusCell = '', now = Date.now()) {
     return statusCell ? 'ok' : 'never';
   }
   if (h.lastError && (!h.lastOk || h.lastAttempt >= h.lastOk)) return 'failed';
+  if (h.skipped && (!h.lastOk || h.lastAttempt > h.lastOk)) return 'never';
   if (!h.lastOk || now - Date.parse(h.lastOk) > STALE_DAYS * 864e5) return 'stale';
   if (h.lastOkJobs === 0) return 'zero';
   return 'ok';

package/scraper/profile.mjs

@@ -3,7 +3,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { P, VAULT, rememberProfileDir, loadCriteria } from './config.mjs';
+import { P, VAULT, rememberProfileDir, loadCriteria, profileSettings, writeProfileSettings } from './config.mjs';
+import { RESUME_NOTE, LEGACY_RESUME_NOTES } from './resume-sync.mjs';
 import { extractText } from './resume.mjs';
 
 const STARTER = fileURLToPath(new URL('./starter/', import.meta.url));
@@ -59,7 +60,20 @@ export async function importResume(file, dir = VAULT) {
   if (path.resolve(file) !== path.resolve(dest)) fs.copyFileSync(file, dest);
   const md = `---\ntype: resume-source\nimported: ${today()}\noriginal: ${JSON.stringify(path.basename(file))}\n---\n# Resume, as imported\n\n> Text extracted from the original by \`tekjobs resume\`. The interview reads this; the polished resume drafts live in their own notes.\n\n${text}\n`;
   fs.writeFileSync(path.join(profileDir, 'Resume - Source.md'), md);
-  return { original: dest, source: path.join(profileDir, 'Resume - Source.md'), chars: text.length };
+  // The same import establishes the resume of record (Profile/Resume.md) when the profile has none, in the shape
+  // `tekjobs resume sync` writes, and remembers the imported file as the source so a later sync re-reads it. A
+  // record that already exists is left alone: replacing it is what `resume sync <file>` is for, and it says so.
+  const recordRel = [RESUME_NOTE, ...LEGACY_RESUME_NOTES].find((rel) => fs.existsSync(path.join(dir, rel)));
+  let record = recordRel || '';
+  let recordCreated = false;
+  if (!recordRel) {
+    const note = ['---', 'type: resume', 'status: current', `source: ${JSON.stringify(dest)}`, 'source_kind: file', `synced: ${today()}`, '---',
+      `> **Resume of record, created from the import on ${today()} by \`tekjobs resume\`.** Application drafts read this note and only claim what it says. To replace it, import again with \`tekjobs resume sync <file>\` or pick a file on the Profile page.`, '', text.trim(), ''].join('\n');
+    fs.writeFileSync(path.join(dir, RESUME_NOTE), note);
+    record = RESUME_NOTE; recordCreated = true;
+  }
+  if (path.resolve(dir) === VAULT && !profileSettings().resumeSource) writeProfileSettings({ resumeSource: dest });
+  return { original: dest, source: path.join(profileDir, 'Resume - Source.md'), chars: text.length, record: path.join(dir, record), recordCreated };
 }
 
 /** What the onboarding still needs. Drives the CLI, the app's Onboarding screen and the MCP status tool. */
@@ -71,6 +85,8 @@ export function onboardingStatus(dir = VAULT) {
   let criteria = null; let criteriaFilled = false;
   try { criteria = loadCriteria(); criteriaFilled = Object.keys(criteria.titleTerms || {}).length > 0; } catch { /* absent or invalid */ }
   const jobs = exists('Jobs') ? fs.readdirSync(path.join(dir, 'Jobs')).filter((f) => f.endsWith('.md')).length : 0;
+  // Two contracts. "Search ready" is the five steps the scan needs; "writing ready" is what the application drafts
+  // need on top, so a person is never told the setup is complete and then shown a Profile page full of warnings.
   const steps = [
     { id: 'folder', label: 'Profile folder exists', done: exists('Targets/Search Criteria.md') && exists('Targets/Companies.md'), how: 'tekjobs init [dir]' },
     { id: 'resume', label: 'Resume imported', done: exists('Profile/Resume - Source.md') || (exists('Profile') && fs.readdirSync(path.join(dir, 'Profile')).some((f) => /^Resume.*\.md$/i.test(f))), how: 'tekjobs resume <file.pdf|docx|md>' },
@@ -78,7 +94,12 @@ export function onboardingStatus(dir = VAULT) {
     { id: 'criteria', label: 'Search criteria filled (title terms set)', done: criteriaFilled, how: 'The interview writes them; or edit Targets/Search Criteria.md.' },
     { id: 'scan', label: 'First scan has run', done: jobs > 0, how: 'tekjobs scan, or the Runs screen.' },
   ];
-  return { dir, steps, complete: steps.every((s) => s.done), jobs, profilePath: path.join(dir, 'Profile', 'Profile.md') };
+  const writing = [
+    { id: 'record', label: 'Resume of record note (Profile/Resume.md)', done: [RESUME_NOTE, ...LEGACY_RESUME_NOTES].some(exists), how: 'tekjobs resume <file> creates it from the import; tekjobs resume sync <url|file> replaces it later.' },
+    { id: 'positioning', label: 'Positioning note: which story leads, the evidence rule, what is never claimed', done: exists('Profile/Positioning.md'), how: 'The interview writes it (save_profile with note=positioning); or write Profile/Positioning.md yourself.' },
+    { id: 'voice', label: 'Voice note: how you write, with one letter you would send', done: exists('Profile/Voice.md'), how: 'The interview writes it (save_profile with note=voice); or write Profile/Voice.md yourself.' },
+  ];
+  return { dir, steps, complete: steps.every((s) => s.done), writing, writingReady: writing.every((s) => s.done), jobs, profilePath: path.join(dir, 'Profile', 'Profile.md') };
 }
 
 /** Everything the interviewing LLM needs in one call: resume text, current notes, and the script to follow. */
@@ -95,16 +116,24 @@ export function onboardingMaterials(dir = VAULT) {
   };
 }
 
-export function saveProfile(markdown, dir = VAULT) {
-  if (!markdown || markdown.trim().length < 100) throw Object.assign(new Error('Profile is too short to save; write the full note.'), { status: 400 });
-  let md = markdown.replace(/^status: draft$/m, 'status: interviewed');
-  if (!/^---\n/.test(md)) md = `---\ntype: profile\nupdated: ${today()}\nstatus: interviewed\n---\n${md}`;
+const PROFILE_NOTES = {
+  profile: { file: 'Profile.md', type: 'profile', min: 100 },
+  positioning: { file: 'Positioning.md', type: 'positioning', min: 80 },
+  voice: { file: 'Voice.md', type: 'voice', min: 60 },
+};
+/** Write one of the profile notes in full: Profile.md by default, or Positioning.md / Voice.md with `note`. The previous version is kept beside it. */
+export function saveProfile(markdown, dir = VAULT, { note = 'profile' } = {}) {
+  const spec = PROFILE_NOTES[note];
+  if (!spec) throw Object.assign(new Error(`note must be one of ${Object.keys(PROFILE_NOTES).join(', ')}`), { status: 400 });
+  if (!markdown || markdown.trim().length < spec.min) throw Object.assign(new Error(`${spec.file} is too short to save; write the full note.`), { status: 400 });
+  let md = note === 'profile' ? markdown.replace(/^status: draft$/m, 'status: interviewed') : markdown;
+  if (!/^---\n/.test(md)) md = `---\ntype: ${spec.type}\nupdated: ${today()}${note === 'profile' ? '\nstatus: interviewed' : ''}\n---\n${md}`;
   md = md.replace(/^updated: .*$/m, `updated: ${today()}`);
-  const file = path.join(dir, 'Profile', 'Profile.md');
+  const file = path.join(dir, 'Profile', spec.file);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  if (fs.existsSync(file)) fs.copyFileSync(file, path.join(dir, 'Profile', `Profile.before-${today()}.md`));
+  if (fs.existsSync(file)) fs.copyFileSync(file, path.join(dir, 'Profile', `${spec.file.replace(/\.md$/, '')}.before-${today()}.md`));
   fs.writeFileSync(file, md);
-  return { saved: file };
+  return { saved: file, note };
 }
 
 /** Fetch a public page (portfolio, GitHub, LinkedIn export is a file, not a URL) as text for the interview to summarize. */
@@ -132,7 +161,9 @@ const INTERVIEW_SCRIPT = `You are onboarding a job seeker into TekJobs. Goal: wr
    - Company stage or size preference, if any.
    - Links: portfolio, GitHub, personal site. Fetch each with fetch_link and fold what you learn into the profile. LinkedIn: ask for their data-export ZIP contents or a pasted summary; never scrape a LinkedIn page.
    - Earliest start date.
+   - How they write: two or three rules in their own words, and words they refuse to use. And anything that must never be claimed about them (a title they did not hold, work they did not do).
 3. Write Profile/Profile.md using the existing note's headings (Basics · What you are, in three sentences · Target roles table with tiers A/B · Constraints & preferences · Proof points · Documents). Proof points are one line each, with numbers. Call save_profile with the full markdown.
+3b. Write the two notes the application drafts read, from the same answers, and save each with save_profile: note=positioning for Profile/Positioning.md (headings: Which story leads · The evidence rule · What must never be claimed; the evidence rule is that every claim traces to a line of the resume), and note=voice for Profile/Voice.md (headings: Rules · A letter I would send; the letter is under 120 words, in their voice, using only facts from the resume). Show both to the user before saving and change what they object to.
 4. Build the criteria from the current JSON (keep every key). Set:
    - titleTerms: exact lowercase substrings that appear in real job titles for the target roles, weighted 40 for exact-fit titles down to ~20 for adjacent ones. Include common variants ("front-end", "frontend", "front end").
    - titleExclude: add the user's hard exclusions as lowercase substrings (titles and words in titles; abbreviations like "sr." and "dir." are spelled out before matching).
@@ -142,7 +173,7 @@ const INTERVIEW_SCRIPT = `You are onboarding a job seeker into TekJobs. Goal: wr
    - location.requireRemote true only if the user said remote only; add their metro to bayAreaTerms with bayAreaBoost 12 if hybrid there is acceptable.
    Call set_criteria with the full JSON string. It is validated before writing.
 5. Call run_scan with dry=true and poll scan_status every few seconds until running is false (two to three minutes; the scan runs on its own, so if this session ends first, the next one can pick up with scan_status). If you cannot poll between turns, pass wait=240 to run_scan and it answers when the scan is done. A dry run writes no notes, so do not use search_jobs yet: call scan_preview limit=15 and show the user the top matches with score, pay band and one reason each. Ask whether the list looks right. Adjust the criteria once if it does not (set_criteria, then another dry run_scan and scan_preview). When it does, call run_scan with dry=false and poll scan_status until it finishes; that run writes the notes, and search_jobs and the app's Today page work from then on.
-6. Finish by telling the user where things live: Profile/Profile.md, Targets/Search Criteria.md, Jobs/. Remind them the daily scan runs on its own from here.`;
+6. Finish by telling the user where things live: Profile/Profile.md, Positioning.md, Voice.md, Targets/Search Criteria.md, Jobs/. Call onboarding_status once more and say plainly which of the two it reports: search ready, and writing ready. Remind them the daily scan runs on its own from here.`;
 
 function criteriaNote(json) {
   return `---
@@ -196,7 +227,9 @@ function readme(dir) {
 This folder is your job search: profile, resume, criteria, watchlist, one note per matched job, and logs. It is plain markdown. Open it in Obsidian or any editor; the TekJobs app and its MCP server read and write the same files.
 
 - \`Profile/Profile.md\` — who you are and what you want (written by the onboarding interview)
-- \`Profile/Resume - Source.md\` — your resume as text
+- \`Profile/Resume - Source.md\` — your resume as text, as imported
+- \`Profile/Resume.md\` — the resume of record: what every draft is allowed to claim (created by the import; \`tekjobs resume sync\` replaces it)
+- \`Profile/Positioning.md\` and \`Profile/Voice.md\` — how the story is told and how you write; the interview writes them
 - \`Targets/Search Criteria.md\` — how postings are scored (JSON block)
 - \`Targets/Companies.md\` — which boards are watched
 - \`Jobs/\` — one note per match; change \`status:\` to move it through the pipeline

package/scraper/sources-email.mjs

@@ -219,11 +219,13 @@ export function jobsFromEmail(raw, file = '') {
 export async function fetchEmailInbox(criteria = {}) {
   const cfg = criteria.email || {};
   const dir = cfg.dir || (criteria._inbox ?? '');
-  if (!dir) return { ok: false, jobs: [], error: 'no inbox folder configured' };
-  if (!fs.existsSync(dir)) return { ok: false, jobs: [], error: `no folder at ${dir} — create it and save alert emails into it as .eml` };
+  // The inbox is optional. Nothing to read is a skip, not a failure: a first run with an empty Inbox/ is healthy,
+  // and a healthy run must not be reported as partial.
+  if (!dir) return { ok: true, jobs: [], skipped: 'no inbox folder configured' };
+  if (!fs.existsSync(dir)) return { ok: true, jobs: [], skipped: `no Inbox folder yet (${dir}); save alert emails into it as .eml to use it` };
 
   const files = fs.readdirSync(dir).filter((f) => /\.(eml|txt|mht|mhtml)$/i.test(f));
-  if (!files.length) return { ok: false, jobs: [], error: `no .eml files in ${dir}` };
+  if (!files.length) return { ok: true, jobs: [], skipped: `no .eml files in ${dir}` };
 
   const all = [];
   const failures = [];
@@ -237,6 +239,7 @@ export async function fetchEmailInbox(criteria = {}) {
   }
   const byUrl = new Map();
   for (const j of all) if (!byUrl.has(j.url)) byUrl.set(j.url, j);
-  if (!byUrl.size) return { ok: false, jobs: [], error: failures.length ? `no jobs found; ${failures[0]}` : `no job links found in ${files.length} message(s)` };
+  if (!byUrl.size && failures.length) return { ok: false, jobs: [], error: `no jobs found; ${failures[0]}` };
+  if (!byUrl.size) return { ok: true, jobs: [], skipped: `no job links found in ${files.length} message(s)` };
   return { ok: true, jobs: [...byUrl.values()] };
 }