Data Model & the Workspace

Directory layout

careerrat/
  .careerrat/          ← private, gitignored, canonical data root
    db/                ← canonical SQLite state
    candidate/         ← private compatibility exports
    workspace/         ← private artifacts and compatibility exports
  config/              ← public schemas and example files
  .agents/skills/      ← the 28 skill definitions (public)
  src/                 ← core scripts and CLI (public)
  bin/                 ← the CLI entry point

CAREERRAT_HOME replaces <repo root>/.careerrat as the data root, so candidate/ and workspace/ are created directly inside whatever path you set, not inside another .careerrat/ below it. Set it to keep your data outside the repo tree. An older install that already has top-level candidate/, workspace/, config/, or .internal/ directories at the repo root keeps using those instead, so its data stays where it already is.

.careerrat/candidate/: private compatibility exports

These files are gitignored and never shipped:

File	Contents
`profile.yml`	Identity, location, compensation floor and targets, domain/toolchain
`targeting.yml`	Role buckets, keep/cut signals, excluded companies, degree policy
`evidence.yml`	Accomplishment claims that feed tailored artifacts
`honesty.yml`	Tools confirmed, do-not-claim list, fabrication boundaries
`form-defaults.yml`	Applicant facts and expected-base for portal forms
`modes.yml`	Usage and application posture switches (optional)
`automation.yml`	Browser capability and platform consent switches (optional)
`writing-style.md`	Voice calibration for outbound artifacts
`stories.yml`	STAR+R behavioral story bank
`learnings/<family>.md`	Per-role-family durable lessons (compounding)
`AGENTS.md`	Personalized router generated by `ingest-profile`

.careerrat/workspace/: runtime data

Also gitignored:

Path	Contents
`tracker.json`	Generated compatibility export of canonical application state
`activity.jsonl`	Append-only Activity Pulse feed
`jobs/`	Saved JD bodies (`<slug>.md`)
`tailored/`	Tailored résumés, cover letters, short answers
`comms/`	Full recruiter / hiring thread bodies
`interview-prep/`	Interview packets and debriefs
`research/`	Company intel, comp benchmarks, board-discovery log
`intake/`	Sourced and triaged posting queue
`scan-results/`	Raw board / ATS scan output
`writing-samples/`	Voice-calibration writing samples
`captures/`	Throwaway browser screenshots (never committed)

tracker.json structure

tracker.json is a generated compatibility export and useful inspection snapshot. The app and writing skills use canonical SQLite operations in new workspaces. Its exported top-level shape is:

{
  "meta": {
    "lastUpdatedAt": "2026-06-01T12:00:00Z",
    "lastSweepAt": "...",
    "version": 42
  },
  "applications": [...],
  "sourced": [...],
  "communications": [...],
  "strategyReview": {...}
}

applications[]

Each application row contains:

company, role, url, status — identity and pipeline position
fitScore, fitBucket, roleFit — body-read gate verdict and fit details
compEstimate, compNote — comp intel
interviewAt, nextInterviewAt, interviewNote — scheduled interview state
followUp — follow-up due date and draft
conversations[] — array of calls, interviews, and debriefs (typed by kind)
artifacts — paths to tailored documents, JD body, interview dossier

sourced[]

Roles discovered by search-jobs before the gate runs. Each entry has fitScore, fitBucket, fitBasis, and the saved JD body path. Promoted to applications[] after a KEEP gate verdict.

communications[]

Recruiter and hiring threads. Each has status, messages[], draft, and nextActionDue. The dashboard's Next Steps and CTA queue derives from these fields, not from the Activity Pulse.

The database is the authority

New workspaces use .careerrat/db/careerrat.db as the canonical source of truth. The app, CLI, and skills share its validated write operations. tracker.json and activity.jsonl are regenerated compatibility exports, so do not hand-edit them in a database-backed workspace.

careerrat data status
careerrat data verify
careerrat tracker --verify

Legacy JSON-only workspaces remain supported until the user explicitly imports them. Run careerrat tracker-dev for the live app.

Data Model & the Workspace

On this page