CareerVector Repository Operating Contract

This document is the orientation sheet a new contributor (human or agent) should read after CLAUDE.md. It explains how the repository is laid out, which files are load-bearing, and which conventions are not negotiable.

Repo orientation

The repo is named after CareerVector but contains more than one product. Top-level peers are CareerVector's perspectives, plus the JobCache peer product, plus shared libraries and tools:

ui/ — SvelteKit app, the human-facing perspective.
mcp/ — MCP server, the AI-agent perspective on the same workspace data.
relay/cf/, relay/deno/, relay/shared/ — realtime relays.
lib/ — internal libraries (@cv/domain, @cv/schemas, @cv/mutations, @cv/workspace-client, @cv/health, @cv/importer).
jobcache/ — peer product: shared ad/role ingestion + fact cache, kept separable at the top level so it can rebrand or relocate.
experiments/ — active R&D; nothing here is production.
wiki/ — the wiki perspective and the canonical knowledge graph content.
tools/quality/ — Rust quality gate/ledger/policy core.
infra/, jobcache/infra/, migrations/, scripts/ — operational surfaces.

Reading CLAUDE.md followed by this file plus wiki/content/onboarding/ should be enough to find your way; further depth comes from the wiki's Atlas tab.

Operating contract

The repository behaves like a small monorepo with a strong set of self-imposed rules. These are not stylistic preferences; they exist because violating them has historically caused outages, quota burns, or graph drift:

Direct commits to main. No feature branches, no PRs. Agents must not propose alternative workflows.
No AI attribution in commit trailers. Legal reasons. Drop Co-Authored-By lines.
No user accounts, ever. Link = identity. Authentication has been stashed and is not coming back without a deliberate product decision.
Zero-budget defaults. Free tier of Cloudflare, Deno Deploy, Koyeb. Adding a paid service or a new vendor needs explicit justification.
Browser verification. UI-visible changes require real-browser verification before they are considered done.
Graph claims are source of truth. Frontmatter on Markdown and @graph blocks in source are the canonical record of what idea a file or document grounds. Drift between code and the graph is treated as a bug.
Working memory is shared. The wiki/content/working-memory/ coordination scratchpad is the agent-to-agent channel; live decisions land there before they reach Canon.

Cover `.agent/` discipline

Each top-level project may carry a .agent/AGENT.md file with project-local instructions for AI agents — directory map, current state, hard rules, hand-off notes. The repo-level .agent/AGENT.md is the authoritative entry point; sub-project .agent/AGENT.md files in places like jobcache/.agent/ extend it locally rather than replacing it.

The convention is: a .agent/ directory makes the project legible to an agent the same way a README.md makes it legible to a human. Both should exist, and both should agree.

Infra stack

CareerVector's infrastructure is described as code in infra/ (and jobcache/infra/) using Pulumi (TypeScript) with state in Pulumi Cloud. The stack is intentionally narrow:

Edge / app hosting: Cloudflare Workers (ui, relay/cf, wiki, mcp, api), Deno Deploy (relay fallback), Koyeb (Typst compile service).
State: Cloudflare D1 (workspace + sub-doc snapshots), CockroachDB Cloud (jobcache hot DB), Backblaze B2 (JSON-LD snapshots).
Observability: Axiom (events + captured errors), local /metrics pull endpoints, Cloudflare Analytics.
Coordination: Upstash QStash (standby), Google Maps Directions (commute calc), Vercel AI SDK providers for LLM calls.

Every binding, secret, and DNS record is reproducible from a Pulumi up. Manual configuration in vendor dashboards is treated as drift and migrated back into code.

How this doc relates to the rest

This is onboarding 04, sitting next to:

01 — north star.
02 — current architecture.
03 — hot paths.
04 — this doc: how the repo behaves, not how the product behaves.