Vocabulary
Canonical definitions for terms that appear in code, UI copy, agent prompts,
and operator chatter. The goal is to prevent drift: if you read one of these
words in a code comment, in a Svelte template, in an MCP tool description, or
in a status update, it should mean the same thing.
When a definition changes, change it here first and propagate.
Product surface
| Term |
Definition |
| Workspace |
The unit of access and collaboration. Identified by a hard-to-guess slug (/{slug}/dashboard). Anyone with the link can read and edit; sharing the link IS the invitation. No user accounts (see architecture/PRINCIPLES.md §1). |
| Session |
JobCache's name for a Workspace — same concept, same code, same link = identity model; sessionID ≡ workspaceID in the JobCache namespace. The noun marks the product universe (session → JobCache, workspace → CareerVector); "Raider heißt jetzt Twix". See PRODUCT-ENGINE.md. |
| Job |
One row in a workspace's dashboard table. Anchored to a job URL (one entry per URL). Carries facts, judgments, pipeline state, score, custom columns, and any tailored CV/CL output. |
| Job ad |
The external source for a Job — an HTML page on a job board or a company careers site. JobCache (peer product) scrapes/parses these; CareerVector consumes the resolved facts. |
| Posting |
A normalized job ad inside the JobCache corpus. Has a fingerprint, a content hash, and a resolved set of facts (title, organization, location, salary, …). One Posting can underlie multiple Jobs across different workspaces. |
| Role |
An aggregate above Posting — multiple postings for the same logical role (e.g., "Senior Software Engineer at Meridian Data AG, Zürich" → one Role with N Postings over time). Shared via JobCache. |
Document model
| Term |
Definition |
| Node |
The atomic unit of CV/CL content. Recursive: every Node has an id, kind, data, selection, and children[]. Defined in lib/schemas/src/node.schema.ts. |
| Node tree |
A complete CV or CL stored as a recursive Node. cv_profile.<lang>.tree and cl_profile.<lang>.tree hold one per language. Each language tree is complete; there is no cross-language inheritance. |
| Quarry |
The full content pool inside a Node tree — every experience entry, bullet, summary phrase the user has ever written. The LLM SELECTS from the quarry per job; it does not invent. |
| Variant pool |
A wrapper Node (kind: 'variant-pool') whose children[] are alternative top-level sections (or section variants). selection.active[] picks which alternative renders. Inactive children are intentional memory (the quarry remembers what NOT to render today). |
| Tailoring |
Per-job process that produces a tailored_cv and tailored_cl Node tree from the quarry. Mutability tiers (FIXED / HYBRID / OPEN) govern what the LLM can change. See architecture/TREE-OF-CHOICES.md and lib/domain/src/tailor/. |
| DocumentStack |
Legacy v1 shape kept as adapter state inside the Svelte editor for UI ergonomics. Not a second source of truth — the canonical state is the Node tree. |
Pipeline stages
The auto-pipeline runs RADAR → EXTRACT → ENRICH → EVALUATE in order; TAILOR is user-triggered.
| Stage |
What it does |
Inputs |
Outputs |
| RADAR |
Discovers candidate URLs for the workspace's job hunt |
Workspace search profile (when configured) |
A list of URLs added to the dashboard |
| EXTRACT |
Pulls a job ad and parses it into structured fields |
Job URL |
Title, organization, location, salary, language, industry, full description |
| ENRICH |
Adds derived facts |
Extracted job |
Commute estimate, salary estimate (if missing), market-context hints |
| EVALUATE |
Scores the job against user-defined dimensions |
Extracted+enriched job, workspace scoring config |
Per-dimension scores + reasoning |
| TAILOR |
Generates a CV and CL Node tree for the specific job |
Quarry + extracted+evaluated job + user prompt |
tailored_cv, tailored_cl |
Storage tiers
| Term |
Definition |
| D1 |
Cloudflare D1 (SQLite at the edge). Source of truth for workspace records, sub-doc snapshots, and the op log. |
| R2 |
Cloudflare R2 (S3-compatible). Holds binary artifacts (uploaded files, generated PDFs). |
| Sub-doc |
A workspace's content is partitioned into independent Y.Doc sub-docs: settings, layout, order-state, jobs, cv-profile, cl-profile, notes. Each has its own clock and write cadence. |
| CloudKeys.chains |
The provider cascade configuration per workspace. Three-level (L0 default, L1 per-consumer override, L2 per-instance override) capability-keyed map. See architecture/INFRA-AND-VENDORS.md. |
Roles a write can have
These names appear in the actor field on every op log entry, in the cell-origin projection, and in audit reports.
| Term |
Meaning |
| human |
A workspace participant typing via the web UI. actorId = device:<workspaceDeviceId>. |
| agent |
An external AI agent (Claude Code, an MCP runner, a future Hermes worker) acting on behalf of a human. actorId = <agentName>:<provider>:<model>. |
| system |
The app or a service itself: a pipeline-stage LLM call, the Maps commute estimator, a migration script, a cell-origin reconciler. actorId = <provider>:<details>. |
Operational vocabulary
| Term |
Definition |
| Perspective |
A folder at the top of the repo (ui/, mcp/, api/, wiki/, status/, ops/, qa/). Each perspective is a different audience × protocol projection of the same product state. |
| Surface |
Deprecated synonym for "perspective." Pre-migration code used it; the term is being removed (see commits 4fb72ac1 and beyond). |
| Health |
The data shape that any status/operations perspective renders. { checks, metrics, generatedAt } typed by @cv/health. |
| Public projection |
A Health snapshot with public: false items and all details blobs stripped. Produced by projectPublic(snapshot). |
| status |
The public-facing projection of the ops cockpit (projectPublic in @cv/health), zero admin bindings. |
| Quarry tier |
One of FIXED / HYBRID / OPEN — controls what the LLM may change in a Node during tailoring. |
| Cascade |
The provider-fallback chain used for every LLM call. Three levels (L0 / L1 / L2), capability-keyed ('chat', 'route', 'scrape', …). |
| opId |
A nanoid that survives retries, tab reloads, and reconnect replays. Server uses it for dedup so retried writes don't double-apply. |
| Synthetic journey |
An end-to-end Playwright spec using curated fixtures and provider doubles (Lane F). Free, deterministic, runs in CI. |
| Live bounded journey |
An end-to-end spec hitting real AI providers with a hard cost cap (Lane G). Opt-in only; never default CI. See runbooks/LIVE-JOURNEY.md. |
What NOT to use
| Term |
Why it's banned |
| "User" |
Implies user accounts. We have none. Use "workspace participant" or just "the human" (vs the agent). |
| "Snapshot" |
Re-using the word for too many distinct concepts (D1 snapshots, Y.Doc snapshots, Health snapshots, sub-doc snapshots) caused confusion. The Health data is just Health; the persistence layer is workspace_sub_doc; the projection function is projectPublic. |
| "Surface" |
Deprecated; use "perspective." |
| "Tenant" |
We don't multi-tenant. Workspaces are equal peers. |
| "Owner" of a workspace |
There is no owner. Equal access. |