From cdc3fe5871e23cb82bb24e009e63a6dce52ee6f2 Mon Sep 17 00:00:00 2001 From: Sethuraman Date: Sat, 15 Aug 2026 11:50:47 +0530 Subject: [PATCH 1/2] docs: add board pack schema changelog --- docs/BOARD_PACK.md | 104 +++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 3 +- web/README.md | 59 +------------------------ 3 files changed, 107 insertions(+), 59 deletions(-) create mode 100644 docs/BOARD_PACK.md diff --git a/docs/BOARD_PACK.md b/docs/BOARD_PACK.md new file mode 100644 index 0000000..0216e63 --- /dev/null +++ b/docs/BOARD_PACK.md @@ -0,0 +1,104 @@ +\# CareerOps Board Pack Schema + + + +The CareerOps board pack (`CareerOps\_board\_pack.json`) is the portable format for + +career data that can be exported and imported between CareerOps installations. + + + +The current board pack schema version is \*\*5\*\*. + + + +Schema migrations are implemented in + +`web/lib/board-pack.mjs` by `migrateV1toV2`, `migrateV2toV3`, + +`migrateV3toV4`, and `migrateV4toV5`. + + + +\## Schema changelog + + + +| Version | Changes | + +| --- | --- | + +| \*\*v1\*\* | Initial board pack format. | + +| \*\*v1 → v2\*\* | Added `accomplishments` and `portfolio`. Added `profile.resume\_struct`. Added doctrine flags including `no\_auto\_apply`, `no\_invented\_facts`, `resume\_struct\_canonical`, and `memory\_provenance`. | + +| \*\*v2 → v3\*\* | Added `no\_auto\_send`, `stories`, and `outcomes`. Added `sent\_at` to roles and materials. Added `display\_name` to materials and reports. | + +| \*\*v3 → v4\*\* | Added `interview\_events`. Added structured offer fields to outcomes: `base`, `bonus`, `equity\_notes`, `remote`, `deadline`, and `currency`. | + +| \*\*v4 → v5\*\* | Added profile target-band fields: `target\_band\_min`, `target\_band\_max`, and `target\_band\_currency`. Added role compensation fields `comp\_range` and `comp\_raw`. Added `contacts`. | + + + +\## Export and import + + + +Board packs are created by `buildBoardPack` and read through + +`importBoardPack` in `web/lib/board-pack.mjs`. + + + +`migrateBoardPack` upgrades older packs through each migration until they reach + +the current schema version. + + + +\## Secrets and doctrine + + + +Board packs do \*\*not\*\* export or import API keys, passwords, or other secret + +credentials. Profile sanitization explicitly removes credential fields before + +export/import. + + + +The board pack also preserves the project's contribution doctrine, including: + + + +\- No automatic application sending. + +\- No invented facts or experience. + +\- Canonical structured resume data. + +\- Memory provenance. + +\- No automatic sending. + + + +The board pack format is for portable career data, not private deployment + +secrets or credentials. + + + +\## Current version + + + +\*\*Schema version: 5\*\* + + + +The current version is defined by `BOARD\_PACK\_SCHEMA\_VERSION` in + +`web/lib/board-pack.mjs`. + diff --git a/docs/README.md b/docs/README.md index 3087311..f236324 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ Product homepage: see the root [README](../README.md). - [ARCHITECTURE.md](ARCHITECTURE.md) — surfaces, public vs private - [LOCAL_FIRST.md](LOCAL_FIRST.md) — ownership, self-host, export +- [BOARD_PACK.md](BOARD_PACK.md) — board pack schema changelog and import/export guidance - [PRIVACY.md](PRIVACY.md) — evidence, secrets, vault - [SECURITY.md](../SECURITY.md) — vulnerability reporting - [supabase/README.md](../supabase/README.md) — schema, migrations, credential vault @@ -23,4 +24,4 @@ Product homepage: see the root [README](../README.md). - [PLUGINS.md](PLUGINS.md) — extension registry (hooks, not a browser extension) - [CHAINS.md](CHAINS.md) — human-gated mode chains (`run-chain`) -Model cards: Hugging Face `telivity/CareerOps-4B*`. +Model cards: Hugging Face `telivity/CareerOps-4B*`. \ No newline at end of file diff --git a/web/README.md b/web/README.md index 5400bfc..15bab9f 100644 --- a/web/README.md +++ b/web/README.md @@ -5,61 +5,4 @@ Static SPA for the job-search dashboard. ## Configure ```bash -cp config.example.js config.js -``` - -Set: - -- `supabaseUrl` — your Supabase project URL -- `supabaseAnonKey` — anon or publishable key (safe for browser; protect data with RLS) -- `donateUrl` — optional -- `analyticsId` — optional Google Analytics Measurement ID (for example `G-XXXXXXXXXX`). Leave empty to disable analytics. - -`config.js` is gitignored in the public repo. - -### Google Analytics (optional) - -To enable Google Analytics on your deployment, set `analyticsId` in `web/config.js`. - -If `analyticsId` is left empty, no Google Analytics script is loaded. - -## Deploy - -From repo root: - -```bash -./scripts/deploy-web.sh -``` - -Or from this folder: `npx vercel deploy --prod` - -## Schema - -Point the app at a Supabase project that has the CareerOps tables (`mt_roles`, `mt_profiles`, `mt_reports`, `mt_accomplishments`, `mt_portfolio_items`, `mt_outcomes`, `mt_interview_events`, `mt_contacts`, …) and auth. Apply `supabase/schema.sql` or Phase 1–3 migrations under `supabase/migrations/`. Use your own project — do not reuse someone else’s demo credentials. - -SPA table/bucket cheat-sheet (client-derived): [SCHEMA.md](SCHEMA.md). - -Pure Career OS helpers used by the SPA live in `lib/` (bullet memory, cadence, ranking, resume sync, board pack, portfolio, advisor, career durability, interview events, offer compare, version timeline, contacts CRM, ATS comp, salary compare, enrich inbox) and are covered by `npm run test:career-os`. - -### Export / import - -- **Board pack** (`CareerOps_board_pack.json`) — skill modes + Settings import (upsert). Schema v5 adds contacts, posted `comp_range`/`comp_raw`, and profile target band. API keys never exported or imported. -- **Full JSON** / **CSV** — Settings → Your data. - -## Edge functions - -> **Source note:** `web/ui/state.mjs` and `web/ui/settings.mjs` call these by name via `sb.functions.invoke(...)`. Reference implementations for most live under [`supabase/functions/`](../supabase/functions/README.md) — deploy those (or your own equivalents) against your Supabase project. **`fetch-jd` and `humanize` are not in this public repo**; self-hosters must supply those (or skip the UI features that call them). Wire the project via `web/config.js`. - -| Function | When the UI calls it | Required for a board-only install? | -|---|---|---| -| `run-search-mt` | User clicks **Run job search** (or the onboarding "Run my first search") — scans configured company career boards for matching roles. | **Optional.** Board CRUD works without it; you can add roles manually via **＋ Add role**. | -| `fetch-jd` | Auto-loads a job description from a posting URL — when opening a role's drawer/panel, on ATS "liveness" checks for a card, and after adding a role via LinkedIn/URL search. | **Optional.** You can paste the JD manually via "Edit / paste" instead. | -| `resume-match` | User clicks **Check my match** to score a resume against a JD. | **Optional if** a BYO OpenAI-compatible key is set in Settings (the match runs client-side instead). **Required** for match scoring otherwise. Claude/Kimi keys on file still go through this function. | -| `resume-rewrite` | **Tailor resume**, cover letter, and single-bullet rewrite actions. | Same as above — optional with a BYO OpenAI-compat key, otherwise required for AI tailoring. | -| `chat` | Advise / in-app assistant follow-ups. | Same bypass logic — optional with a BYO OpenAI-compat key, otherwise required for chat/advisor. | -| `ai-free` | Settings screen, to show remaining free-tier daily uses. | **Optional** — cosmetic for the SPA usage display; free-tier LLM serving is configured server-side. | -| `humanize` | **Humanize wording** button. | **Optional** — only used if the user has connected an ai-text-humanizer.com account. | -| `upsert_provider_secret` | Settings save path when storing Claude / Kimi / humanizer secrets. | **Optional.** Without it, Settings falls back to plaintext profile columns for self-host. | -| `clear_provider_secret` | Settings when removing a stored provider secret. | **Optional.** Same plaintext fallback as above. | - -**Minimal viable install:** none of the 9 functions are strictly required. Core board operations (add/drag/tag roles, verdicts, outcomes, notes) call Supabase tables directly (`sb.from('mt_roles')`, etc.), not Edge Functions. Search and JD auto-fetch need `run-search-mt` / `fetch-jd`; AI scoring/tailoring/chat need the rest (or a BYO OpenAI-compat key to skip those three client-side); secret vault helpers are only needed if you want encrypted Settings storage instead of plaintext profile columns. +cp config.example.js config.js \ No newline at end of file From a6c9671de8aa0870036275ec5a72365649ead75d Mon Sep 17 00:00:00 2001 From: Sethuraman Date: Sat, 15 Aug 2026 14:34:27 +0530 Subject: [PATCH 2/2] docs: address board pack review feedback --- docs/BOARD_PACK.md | 94 +++++++++++----------------------------------- web/README.md | 61 +++++++++++++++++++++++++++++- 2 files changed, 81 insertions(+), 74 deletions(-) diff --git a/docs/BOARD_PACK.md b/docs/BOARD_PACK.md index 0216e63..712a0af 100644 --- a/docs/BOARD_PACK.md +++ b/docs/BOARD_PACK.md @@ -1,104 +1,52 @@ -\# CareerOps Board Pack Schema - - - -The CareerOps board pack (`CareerOps\_board\_pack.json`) is the portable format for +# CareerOps Board Pack Schema +The CareerOps board pack (`CareerOps_board_pack.json`) is the portable format for career data that can be exported and imported between CareerOps installations. - - -The current board pack schema version is \*\*5\*\*. - - +The current board pack schema version is **5**. Schema migrations are implemented in - `web/lib/board-pack.mjs` by `migrateV1toV2`, `migrateV2toV3`, - `migrateV3toV4`, and `migrateV4toV5`. - - -\## Schema changelog - - +## Schema changelog | Version | Changes | - | --- | --- | +| **v1** | Initial board pack format. | +| **v1 → v2** | Added `accomplishments` and `portfolio`. Added `profile.resume_struct`. Added doctrine flags including `no_auto_apply`, `no_invented_facts`, `resume_struct_canonical`, and `memory_provenance`. | +| **v2 → v3** | Added `no_auto_send`, `stories`, and `outcomes`. Added `sent_at` to roles and materials. Added `display_name` to materials and reports. | +| **v3 → v4** | Added `interview_events`. Added structured offer fields to outcomes: `base`, `bonus`, `equity_notes`, `remote`, `deadline`, and `currency`. | +| **v4 → v5** | Added profile target-band fields: `target_band_min`, `target_band_max`, and `target_band_currency`. Added role compensation fields `comp_range` and `comp_raw`. Added `contacts`. | -| \*\*v1\*\* | Initial board pack format. | - -| \*\*v1 → v2\*\* | Added `accomplishments` and `portfolio`. Added `profile.resume\_struct`. Added doctrine flags including `no\_auto\_apply`, `no\_invented\_facts`, `resume\_struct\_canonical`, and `memory\_provenance`. | - -| \*\*v2 → v3\*\* | Added `no\_auto\_send`, `stories`, and `outcomes`. Added `sent\_at` to roles and materials. Added `display\_name` to materials and reports. | - -| \*\*v3 → v4\*\* | Added `interview\_events`. Added structured offer fields to outcomes: `base`, `bonus`, `equity\_notes`, `remote`, `deadline`, and `currency`. | - -| \*\*v4 → v5\*\* | Added profile target-band fields: `target\_band\_min`, `target\_band\_max`, and `target\_band\_currency`. Added role compensation fields `comp\_range` and `comp\_raw`. Added `contacts`. | - - - -\## Export and import - - +## Export and import Board packs are created by `buildBoardPack` and read through - `importBoardPack` in `web/lib/board-pack.mjs`. - - `migrateBoardPack` upgrades older packs through each migration until they reach - the current schema version. +## Secrets and doctrine - -\## Secrets and doctrine - - - -Board packs do \*\*not\*\* export or import API keys, passwords, or other secret - +Board packs do **not** export or import API keys, passwords, or other secret credentials. Profile sanitization explicitly removes credential fields before - export/import. - - The board pack also preserves the project's contribution doctrine, including: - - -\- No automatic application sending. - -\- No invented facts or experience. - -\- Canonical structured resume data. - -\- Memory provenance. - -\- No automatic sending. - - +- No automatic application sending. +- No invented facts or experience. +- Canonical structured resume data. +- Memory provenance. +- No automatic sending. The board pack format is for portable career data, not private deployment - secrets or credentials. +## Current version +**Schema version: 5** -\## Current version - - - -\*\*Schema version: 5\*\* - - - -The current version is defined by `BOARD\_PACK\_SCHEMA\_VERSION` in - -`web/lib/board-pack.mjs`. - +The current version is defined by `BOARD_PACK_SCHEMA_VERSION` in +`web/lib/board-pack.mjs`. \ No newline at end of file diff --git a/web/README.md b/web/README.md index 15bab9f..e4dc05e 100644 --- a/web/README.md +++ b/web/README.md @@ -5,4 +5,63 @@ Static SPA for the job-search dashboard. ## Configure ```bash -cp config.example.js config.js \ No newline at end of file +cp config.example.js config.js +``` + +Set: + + +- `supabaseUrl` — your Supabase project URL +- `supabaseAnonKey` — anon or publishable key (safe for browser; protect data with RLS) +- `donateUrl` — optional +- `analyticsId` — optional Google Analytics Measurement ID (for example `G-XXXXXXXXXX`). Leave empty to disable analytics. + +`config.js` is gitignored in the public repo. + +### Google Analytics (optional) + +To enable Google Analytics on your deployment, set `analyticsId` in `web/config.js`. + +If `analyticsId` is left empty, no Google Analytics script is loaded. + +## Deploy + +From repo root: + +```bash +./scripts/deploy-web.sh +``` + +Or from this folder: `npx vercel deploy --prod` + +## Schema + +Point the app at a Supabase project that has the CareerOps tables (`mt_roles`, `mt_profiles`, `mt_reports`, `mt_accomplishments`, `mt_portfolio_items`, `mt_outcomes`, `mt_interview_events`, `mt_contacts`, …) and auth. Apply `supabase/schema.sql` or Phase 1–3 migrations under `supabase/migrations/`. Use your own project — do not reuse someone else’s demo credentials. + +SPA table/bucket cheat-sheet (client-derived): [SCHEMA.md](SCHEMA.md). + +Pure Career OS helpers used by the SPA live in `lib/` (bullet memory, cadence, ranking, resume sync, board pack, portfolio, advisor, career durability, interview events, offer compare, version timeline, contacts CRM, ATS comp, salary compare, enrich inbox) and are covered by `npm run test:career-os`. + +### Export / import + +- **Board pack** (`CareerOps_board_pack.json`) — skill modes + Settings import (upsert). Schema v5 adds contacts, posted `comp_range`/`comp_raw`, and profile target band. API keys never exported or imported. +- See the [Board Pack schema changelog](../docs/BOARD_PACK.md) for the v1 → v5 schema details. +- **Full JSON** / **CSV** — Settings → Your data. + +## Edge functions + +> **Source note:** `web/ui/state.mjs` and `web/ui/settings.mjs` call these by name via `sb.functions.invoke(...)`. Reference implementations for most live under [`supabase/functions/`](../supabase/functions/README.md) — deploy those (or your own equivalents) against your Supabase project. **`fetch-jd` and `humanize` are not in this public repo**; self-hosters must supply those (or skip the UI features that call them). Wire the project via `web/config.js`. + +| Function | When the UI calls it | Required for a board-only install? | +|---|---|---| +| `run-search-mt` | User clicks **Run job search** (or the onboarding "Run my first search") — scans configured company career boards for matching roles. | **Optional.** Board CRUD works without it; you can add roles manually via **＋ Add role**. | +| `fetch-jd` | Auto-loads a job description from a posting URL — when opening a role's drawer/panel, on ATS "liveness" checks for a card, and after adding a role via LinkedIn/URL search. | **Optional.** You can paste the JD manually via "Edit / paste" instead. | +| `resume-match` | User clicks **Check my match** to score a resume against a JD. | **Optional if** a BYO OpenAI-compatible key is set in Settings (the match runs client-side instead). **Required** for match scoring otherwise. Claude/Kimi keys on file still go through this function. | +| `resume-rewrite` | **Tailor resume**, cover letter, and single-bullet rewrite actions. | Same as above — optional with a BYO OpenAI-compat key, otherwise required for AI tailoring. | +| `chat` | Advise / in-app assistant follow-ups. | Same bypass logic — optional with a BYO OpenAI-compat key, otherwise required for chat/advisor. | +| `ai-free` | Settings screen, to show remaining free-tier daily uses. | **Optional** — cosmetic for the SPA usage display; free-tier LLM serving is configured server-side. | +| `humanize` | **Humanize wording** button. | **Optional** — only used if the user has connected an ai-text-humanizer.com account. | +| `upsert_provider_secret` | Settings save path when storing Claude / Kimi / humanizer secrets. | **Optional.** Without it, Settings falls back to plaintext profile columns for self-host. | +| `clear_provider_secret` | Settings when removing a stored provider secret. | **Optional.** Same plaintext fallback as above. | + +**Minimal viable install:** none of the 9 functions are strictly required. Core board operations (add/drag/tag roles, verdicts, outcomes, notes) call Supabase tables directly (`sb.from('mt_roles')`, etc.), not Edge Functions. Search and JD auto-fetch need `run-search-mt` / `fetch-jd`; AI scoring/tailoring/chat need the rest (or a BYO OpenAI-compat key to skip those three client-side); secret vault helpers are only needed if you want encrypted Settings storage instead of plaintext profile columns.