{
  "markdown": "# Traitprint\n\n**A structured career profile that AI tools can query — and that an AI agent\ncan help you build.**\n\n> Your resume is a lossy snapshot. Your Traitprint is a live, queryable record\n> of your skills, experience, stories, and philosophy — kept on your laptop,\n> shared on your terms.\n\nOne rule holds everywhere: **the vault never asserts a fact you didn't put in\nit.** Lenses re-order and re-weight what's true for a given audience — they\ncannot invent. Agents stage what they extract as proposals *you* approve, and\nthey never fabricate a skill, an ID, or a link. Presentation flexes; facts\ndon't. (This isn't a promise in a README — it's enforced by the schema, the\nproposals channel, and the audit.)\n\nTraitprint ships as **two products**:\n\n- **Traitprint Local** (`pip install traitprint`) — a local-first vault and\n  MCP server. Zero accounts, zero network calls, MIT-licensed. This README is\n  about Local.\n- **Traitprint Cloud** (`pip install 'traitprint[cloud]'`) — the hosted version\n  of exactly this, plus the few features that genuinely need a server: a public\n  profile, a hosted MCP endpoint recruiters' agents can reach, job matching, and\n  cross-device sync. Everything you can do locally, you can still do; cloud only\n  *adds*. See [Traitprint Cloud (opt-in)](#traitprint-cloud-opt-in).\n\n## The vault\n\nThe vault is the whole product: a directory on your machine (default\n`~/.traitprint`) holding a file tree of plain JSON and markdown, versioned as\na git repo — no database, no proprietary format. Structured lists are JSON\n(`profile.json`, `skills.json`, `education.json`); narratives are markdown\nwith YAML frontmatter (`experiences/`, `stories/`, `philosophies/`), so you\n— or an agent — can edit them with any text editor. (Format contract:\n[docs/schema/vault-v1/](docs/schema/vault-v1/). Upgrading from an older\nsingle-file vault? Run `traitprint vault migrate`.) Six kinds of entry make\nup the structure agents read:\n\n| Entry | What it captures | CLI |\n|---|---|---|\n| **Profile** | Name, headline, summary, location | `vault set-profile` |\n| **Skills** | What you can do, with a 1–5 proficiency (familiar → authority) and an O*NET taxonomy link | `vault add-skill` |\n| **Experiences** | Roles you've held — title, company, dates, accomplishments, linked to the skills exercised in the role | `vault add-experience` |\n| **Stories** | STAR-format narratives (Situation, Task, Action, Result), linked to the skills and experience they prove | `vault add-story` |\n| **Philosophies** | Stated beliefs on leadership, collaboration, technical approach, culture, decision-making — each backed by evidence stories | `vault add-philosophy` |\n| **Education** | Institutions, degrees, fields of study | `vault add-education` |\n\nThe payoff is the cross-links: a **skill** is credible because a **story**\ndemonstrates it; a **philosophy** lands because a story shows you living it; a\nstory is grounded because it belongs to a real **experience**. Those links are\nwhat the MCP tools traverse, and what the [coherence audit](#audit-the-vault-for-coherence)\nchecks.\n\n### User layer vs system layer\n\nTraitprint splits cleanly into two layers with different owners:\n\n- **User layer — yours, never touched by upgrades.** Everything in the vault\n  directory: your JSON and markdown entries, git history, and an optional\n  `custom.md` at the vault root. `custom.md` is a free-form instruction file\n  for the agents that wrap traitprint — house rules, output preferences,\n  off-limits topics. The package only ever *reads* it (the MCP prompts append\n  it to every served workflow); it never creates, writes, or deletes it, so\n  your customizations survive every `pip install --upgrade traitprint`.\n- **System layer — ours, replaced on upgrade.** The wheel-shipped CLI, MCP\n  server, and [Agent Skills](skills/). Any edits you make to installed skill\n  files are silently reverted by the next upgrade — put durable instructions\n  in `custom.md` instead.\n\nYour `custom.md` rules win on style and workflow, but they cannot override\nsafety invariants: agents still stage extracted writes through the proposals\nchannel and never invent taxonomy IDs or UUIDs.\n\n## Quickstart\n\n```\npip install traitprint\ntraitprint init\ntraitprint vault set-profile --name \"Your Name\" --headline \"Your Role\"\ntraitprint vault add-skill \"Postgres\" --proficiency 4 --category technical\ntraitprint mcp-serve\n```\n\nAdd some content before running `mcp-serve` — otherwise every MCP query returns\nan empty vault. The fastest way to bootstrap is to point an LLM at your existing\nresume:\n\n```\npip install 'traitprint[import]'\ntraitprint vault import-resume ~/Downloads/resume.pdf   # BYOK: Anthropic / OpenAI / Ollama / OpenRouter\n```\n\nPoint Claude Desktop (or any MCP client) at `traitprint mcp-serve` and any AI\nassistant you use can answer questions about your career: which projects used\nPostgres, what your management philosophy is, the story behind a job change.\nNo account. No cloud. No vendor lock-in. Your vault is a file on your machine.\n\nA fresh `pip install traitprint` **never imports a network client at module\nload**. Only `cloud.py` and `providers/*` import `httpx`, and neither path is\nreachable without the `[cloud]` or `[import]` extras — so the base CLI cannot\nmake a network request. (See [docs/privacy.md](docs/privacy.md) for the full\nthreat model.)\n\n### Claude Desktop MCP config\n\nAdd Traitprint to your Claude Desktop config file\n(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,\n`%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"traitprint\": {\n      \"command\": \"traitprint\",\n      \"args\": [\"mcp-serve\"],\n      \"env\": {\n        \"TRAITPRINT_VAULT_DIR\": \"/Users/you/.traitprint\"\n      }\n    }\n  }\n}\n```\n\n- `command` must resolve on Claude Desktop's `PATH`. If `pip install traitprint`\n  landed in a venv or a user-local `bin/` that Claude Desktop can't see, use the\n  absolute path (e.g. `/Users/you/.local/bin/traitprint` or\n  `/opt/homebrew/bin/traitprint`). Run `which traitprint` to find it.\n- `TRAITPRINT_VAULT_DIR` is optional — omit it to use the default `~/.traitprint`.\n- Restart Claude Desktop after editing the config. The `traitprint` server should\n  appear in the MCP tools list, exposing the query tools and workflow prompts\n  described below.\n\nThe same snippet works for any MCP client that accepts an `mcpServers` block\n(Cursor, Zed, Continue, etc.).\n\n### Bootstrap any agent CLI (`traitprint agents init`)\n\n```\ntraitprint agents init ~/my-project\n```\n\nOne command scaffolds a project directory for agent CLIs: thin entrypoint\nwrappers (`CLAUDE.md`, `QWEN.md`, `.grok/GROK.md`) that all delegate to a\nsingle canonical `AGENTS.md` (Codex CLI, OpenCode, and Kimi CLI read it\nnatively), the bundled [Agent Skills](skills/) copied to `.agents/skills/` and\n`.claude/skills/`, and project-scoped MCP registration for\n`traitprint mcp-serve` (`.mcp.json`, `opencode.json`, `.qwen/settings.json`,\n`.grok/settings.json`) — plus copy-paste snippets for home-directory configs\n(Codex CLI, Kimi CLI). Existing files are never overwritten, and re-running\nis safe.\n\nHonest positioning: if you already use\n`npx skills add DataViking-Tech/traitprint` (skills) or the Gemini CLI\nextension (which this command deliberately skips — `gemini-extension.json`\ncovers it), much of this is covered. `agents init` earns its keep for\npip-only setups without Node and for the per-runtime MCP wiring.\n\n## Working with an AI agent\n\nTraitprint is designed so an AI agent does most of the heavy lifting — both\n*reading* your vault and *helping you fill it out and keep it honest*. The MCP\nserver exposes two kinds of primitive:\n\n**Nine tools** — eight read-only queries plus the `vault_sync`\ncloud-sync trigger (status/push/pull, the CLI's sync-v1 engine). They\nshare the hosted cloud server's response envelope, and every query tool\nexcept `doctor` is served hosted too — but the surfaces are not\nidentical (the hosted server layers proposal and jobs tools on top,\n`vault_sync` stays local, and a few filters differ); the full local ↔\nhosted delta lives in [`AGENTS.md`](AGENTS.md):\n\n| Tool | \"Ask it…\" |\n|---|---|\n| `get_profile_summary` | a one-shot identity primer — headline, bio, top skills; optional `lens` renders it through a positioning lens |\n| `search_skills` | \"what do they know about X?\" — taxonomy- and graph-aware skill search |\n| `find_story` | \"tell me about a time when…\" — STAR narrative retrieval by free-text query, situation, theme, or outcome |\n| `find_bullets` | the resume-bullet inventory — referenceable, story-backed bullet points to select from when tailoring; filter by query, skill, or lens |\n| `get_philosophy` | \"what's their stance on X?\" — filter by topic and/or category |\n| `vault_lens_list` | which positioning lenses exist, and which is the default |\n| `vault_lens_get` | one lens in full — salience map, signature content, overrides |\n| `doctor` | \"where should we start?\" — vault phase + freshness findings, each naming the skill that fixes it (local-only) |\n\n**Eight prompts** — ready-made workflows an agent can pull to drive the vault\nforward, most adapted from the Traitprint Cloud Experience Mining engine (the\nsame Socratic coach and its mining modes); `deepen_story` and\n`improve_profile` are new here. In Claude Desktop they show up in the\nslash-command menu; in an agentic client (Claude Code, Cursor) they pair with\nshell access so the agent can run the CLI directly:\n\n| Prompt | What it does |\n|---|---|\n| `fill_vault` | Socratic interview that writes what it learns to the vault via the CLI. Optional `focus` narrows to one section. |\n| `mine_story_gaps` | STORY OPPORTUNITY mode — mines STAR stories for the skills and roles the audit flags as having none. |\n| `discover_skills` | SKILL DISCOVERY mode — probes for latent skills you have but haven't added yet. |\n| `draft_star_story` | FOCUSED deep dive — turns one raw accomplishment into a crisp, well-linked STAR story. Optional `experience` seeds the topic. |\n| `audit_coherence` | Runs the coherence audit, then applies judgment on consistency, voice, and evidence quality. |\n| `position_lens` | Curates a positioning lens for a target role — salience, signature content, headline/bio overrides — without inventing a fact. |\n| `deepen_story` | CROSS-EXAMINATION mode — hardens one STAR story until it survives follow-up questions: sourced metrics, split attribution, honest outcome. Optional `story` names the target. |\n| `improve_profile` | TRIAGE mode — ranks the whole vault by leverage and surfaces the 1-3 highest-payoff tasks, each with its exact next step. Optional `focus` narrows the ranking. |\n\n### Agent Skills\n\nThe same workflows ship as [SKILL.md Agent Skills](skills/)\n(agentskills.io open standard) for filesystem agents like Claude Code,\nCodex CLI, Gemini CLI, and Cursor — plus three skills with no prompt\ncounterpart: `traitprint-import-resume` (agent-assisted resume import),\n`traitprint-capture-story` (background STAR capture that stages a\nstory proposal whenever a work anecdote surfaces mid-session), and\n`traitprint-agent-vault-sync` (round-trip sync with an external agent\ncareer tool's working directory):\n\n```\nnpx skills add DataViking-Tech/traitprint\n```\n\nThe skills are the canonical text — the MCP prompts serve their bodies\nverbatim, so the two surfaces never drift. A shared CLI cheatsheet lives at\n[`skills/shared/cli-reference.md`](skills/shared/cli-reference.md), and the\nagent operating manual is [`AGENTS.md`](AGENTS.md).\n\nGemini CLI users can install the whole bundle — skills, a\n[`GEMINI.md`](GEMINI.md) context file, and the hosted MCP server — as one\nextension:\n\n```\ngemini extensions install https://github.com/DataViking-Tech/traitprint\n```\n\n### Fill out the vault\n\nHand an agent the `fill_vault` prompt (or just ask it to \"help me build my\nTraitprint\"). The intended loop:\n\n1. The agent reads what's already there (`get_profile_summary`, `search_skills`)\n   so it doesn't re-ask.\n2. It interviews you one topic at a time, pushing for specifics — numbers,\n   dates, what changed — rather than adjectives.\n3. It writes each item with the CLI. Every `add-*` command takes flags for\n   non-interactive use and a `--from-json` batch mode, so an agent can add a\n   dozen items in one pass:\n\n   ```bash\n   traitprint vault add-skill --from-json - <<'JSON'\n   [{\"name\": \"Postgres\", \"proficiency\": 4, \"category\": \"technical\"},\n    {\"name\": \"Incident Response\", \"proficiency\": 3, \"category\": \"soft\"}]\n   JSON\n   ```\n\n4. It links the pieces: a story gets `--skill-id` and `--experience-id`; a\n   philosophy gets `--evidence-id` pointing at a story. Those links are what\n   make later queries return real evidence instead of bare claims.\n\nEvery write auto-commits to the vault's git history, so `vault history`,\n`vault diff`, and `vault rollback` give you (and the agent) a safety net.\n\n### Audit the vault for coherence\n\nA vault full of unsupported claims reads worse than a short, honest one. The\n`audit` command is a deterministic, read-only pass — the same heuristics\nTraitprint Cloud uses, ported to Python so Local and Cloud agree on what\n\"coherent\" means. It scores each STAR story and flags where the narrative\ndoesn't hold together:\n\n```\ntraitprint vault audit\n```\n\n```\n[major] skills: Skill 'Kubernetes' is claimed at 5/5 but no story demonstrates it.\n[major] philosophies: Philosophy 'Bias to ship' cites no evidence story.\n[major] stories: 'The big migration': Result lacks measurable outcomes — add metrics\n[minor] experiences: Experience 'Founding Engineer' has no description...\n\nStory coherence:\n  Polished  (88%) The big migration\n  Draft     (24%) That one outage\n  Overall: 56%\n\nPhilosophy tensions (nuance, not problems):\n  ~ Your philosophy on leadership shows nuance — you value both autonomy and structure…\n\nSummary: 0 critical, 3 major, 1 minor.\n```\n\nWhat it produces:\n\n- **Per-story coherence scores** — each STAR story is graded\n  `Polished` / `Strong` / `Solid` / `Draft` with an evidence level\n  (`demonstrates` / `mentions` / `weak`), checking field substance, active\n  language, measurable results, and the Situation→Task→Action→Result causal\n  chain.\n- **Findings** at `critical` / `major` / `minor` severity — unsupported strong\n  skills, philosophies with no evidence, broken or thin stories, dangling\n  references, orphaned roles, and **contradictions between stories** in the\n  same role (conflicting metrics, or one story claiming leadership while\n  another claims solo IC work).\n- **Philosophy tensions** — when two beliefs in the same category pull in\n  opposite directions, surfaced as *nuance* (context-dependent thinking), never\n  as a bug to fix.\n\nFlags:\n\n- `--json` — the full report (`findings`, `story_scores`, `tensions`,\n  `summary`) for an agent to act on.\n- `--severity critical|major|minor` — minimum level to report.\n- `--strict` — exit non-zero when any critical or major finding remains (handy\n  in CI or a pre-`push` check).\n\nPair it with the `audit_coherence` prompt to go past the mechanical checks: an\nagent reads the findings, then judges the things a script can't — whether your\nheadline, skills, and stories describe the same person, whether the voice is\nconsistent, whether \"results\" are real outcomes.\n\n## Who it's for\n\nTraitprint is useful if you want your career data to be structured, portable,\nand queryable — not locked inside a PDF or a recruiter platform. Three concrete\nexamples:\n\n### 🎯 The job seeker\n\n> \"I'm tired of rewriting my resume for every application, and I want recruiters\n> who use AI tools to actually find me.\"\n\nBuild your vault once — import your resume, then have an agent run `fill_vault`\nand `audit` to round it out. Export tailored resumes with `traitprint export`,\nor (with the cloud extra) `traitprint push` to publish a profile recruiters'\nagents query directly — skills, dates, stories — instead of guessing from\nkeyword-matched PDFs.\n\n### 🧑‍💻 The developer using Claude Desktop / Cursor / any MCP client\n\n> \"I want my AI assistant to know my actual stack, projects, and decisions —\n> not generic advice.\"\n\nRun `traitprint mcp-serve` and add it to your MCP client config. Your assistant\ncan now call `search_skills`, `find_story`, and `get_philosophy` to ground its\nsuggestions in your real history. Ask \"draft a cover letter for this role\" and\nit pulls from the vault, not a hallucinated resume.\n\n### 🧭 The career coach\n\n> \"I work with a dozen clients and I need their career data structured the\n> same way so I can compare, advise, and produce portfolios.\"\n\nUse `traitprint vault import-resume` (BYOK LLM) to pull each client's resume into\na structured vault, then `vault audit` to spot the gaps to coach on. Edit,\nversion, and `export` polished portfolios. Same schema for every client means\ncoaching workflows compose instead of starting from scratch each time.\n\n## What's in the box\n\n- **Local vault** — a plain JSON + markdown file tree on your laptop,\n  versioned with git.\n- **MCP server (stdio)** — nine tools (`get_profile_summary`,\n  `search_skills`, `find_story`, `find_bullets`, `get_philosophy`,\n  `vault_lens_list`, `vault_lens_get`, local-only `doctor`, and the\n  local-only `vault_sync` cloud-sync trigger) and\n  eight workflow prompts\n  (`fill_vault`, `mine_story_gaps`, `discover_skills`, `draft_star_story`,\n  `audit_coherence`, `position_lens`, `deepen_story`, `improve_profile`).\n- **Agent Skills** — the same workflows as SKILL.md skills under\n  [`skills/`](skills/) for Claude Code, Codex CLI, Gemini CLI, Cursor, etc.\n- **CLI** — `traitprint init`, `traitprint vault set-profile`, `add-skill`,\n  `add-experience`, `add-story`, `add-philosophy`, `add-education`, `lens`,\n  `remove`, `show`, `list`, `audit`, `history`, `diff`, `rollback`, `migrate`,\n  `export`, `extract-text`, `import-resume`, `import-story-bank`, the\n  `proposals` group (staged writes the user approves), plus top-level\n  `doctor`, `sync`, and `agents init`.\n- **Coherence audit** — `traitprint vault audit` flags unsupported claims,\n  unbacked philosophies, and broken stories (text, `--json`, or `--strict`).\n- **Resume import** with BYOK LLM (Anthropic, OpenAI, Ollama, OpenRouter) —\n  install with `pip install 'traitprint[import]'`.\n- **Optional cloud sync** — `login`, `logout`, and git-native\n  `traitprint sync` (`push` / `pull` / `status` / `taxonomy`); the legacy\n  whole-vault `push` / `pull` still work but are deprecated in favor of\n  `sync`. Install with `pip install 'traitprint[cloud]'`.\n\n## Local vs Cloud\n\nTraitprint is local-first. The design rule is simple: **a feature belongs in\nlocal unless it can't work locally.** Everything below the line runs on your\nlaptop with no account, no network calls, and no paywall — and cloud is the same\nthing, hosted, plus the handful of features that genuinely need a server.\n\n| Capability | Free forever, no account | Requires traitprint.com account |\n|---|---|---|\n| Create + edit your vault (`init`, `vault add-*`, `remove`) | ✅ | — |\n| MCP query tools + workflow prompts + Agent Skills | ✅ | — |\n| Narrative-coherence audit (`vault audit`) | ✅ | — |\n| Version history, diff, rollback | ✅ | — |\n| Resume import via BYOK LLM | ✅ | — |\n| Export (`json`, `markdown`, `jsonresume`/`json-resume`, `synthpanel-persona`, `career-bundle`) | ✅ | — |\n| MIT-licensed source, fork and self-host | ✅ | — |\n| Public profile at `traitprint.com/profile/you` | — | ✅ |\n| Hosted MCP endpoint reachable by recruiter agents | — | ✅ |\n| Job matching against a shared job index | — | ✅ |\n| Digital-twin chat | — | ✅ |\n| Cross-device sync | — | ✅ |\n\nA fresh install never talks to traitprint.com. Cloud features are opt-in via\n`traitprint login` and `traitprint push`.\n\n**Full details and migration guide:** [docs/why-local.md](docs/why-local.md)\n\n**Privacy commitment (what leaves your machine on `push`, what we store,\nwhat we don't do, how to delete everything):** [docs/privacy.md](docs/privacy.md)\n\n## Traitprint Cloud (opt-in)\n\nWhen you want a public profile, job matching, or a chat-ready twin that\nrecruiters can talk to, install the cloud extras:\n\n```\npip install 'traitprint[cloud]'\ntraitprint login\ntraitprint push\n```\n\n…and you're live at `traitprint.com/profile/you`. Without the `[cloud]`\nextras, `traitprint login` / `logout` / `push` / `pull` print:\n\n```\nError: Cloud sync requires: pip install traitprint[cloud]\n```\n\nBefore uploading, `push` runs the [coherence audit](#audit-the-vault-for-coherence)\nand **blocks on critical findings** — broken stories, dangling references,\ncontradicting roles, anything you'd never want on a public profile. Major and\nminor findings are advisory by default; pass `--strict` to block on major ones\ntoo (full `vault audit --strict` semantics), or `--skip-audit` to bypass the\ncheck entirely.\n\n### Connect from claude.ai / ChatGPT / Gemini CLI\n\nWith a traitprint.com account, your synced vault is reachable from the\nchat apps through the hosted MCP server — paste one URL, approve the\nOAuth consent, done:\n\n```\nhttps://api.traitprint.com/functions/v1/mcp-server\n```\n\n- **claude.ai** — Settings → Connectors → **Add custom connector** →\n  paste the URL. Claude walks you through sign-in and scope consent.\n- **ChatGPT** — Settings → Apps & Connectors → enable Developer mode\n  (Advanced settings), then Connectors → **Create** → paste the URL.\n- **Gemini CLI** —\n  `gemini extensions install https://github.com/DataViking-Tech/traitprint`\n  wires the same server (plus the [Agent Skills](#agent-skills) and a\n  `GEMINI.md` context file); approve the sign-in with `/mcp auth traitprint`.\n\nHeadless clients (CI, scripts, `mcp-remote`) can skip OAuth: generate an\n`sk_` API key in the web app (Settings → API Keys) and send it as\n`Authorization: Bearer sk_…`. Reads return your vault; writes are always\nstaged as proposals you approve — see\n[`docs/distribution-runbook.md`](docs/distribution-runbook.md) for the\nfull surface list.\n\n### Non-interactive auth (CI, agents, Docker)\n\n`traitprint login` accepts three credential sources, in this precedence order:\n\n1. **API token** — `--token <key>` or `TRAITPRINT_API_TOKEN`. Skips email and\n   password entirely. Generate a token in the web portal (Settings → API Keys).\n   Recommended for CI, AI agents, and any non-interactive shell.\n2. **Password env var** — `TRAITPRINT_PASSWORD` (paired with `--email` /\n   `TRAITPRINT_EMAIL`). Only consulted if no token is provided.\n3. **Interactive prompt** — used as a last resort, only when stdin is a TTY.\n\n```bash\n# Recommended: API token via env var (generate an sk_ key in the web app)\nexport TRAITPRINT_API_TOKEN=sk_xxx\ntraitprint login        # one-time: persists token to <vault>/.credentials\ntraitprint sync push\n\n# Or skip login entirely — sync/push/pull also honor TRAITPRINT_API_TOKEN directly\nTRAITPRINT_API_TOKEN=sk_xxx traitprint sync push\n```\n\nAvoid `--password <pw>` on the command line: it lands in shell history and\nprocess listings. Use `TRAITPRINT_PASSWORD` or, better, an API token.\n\n## Contact\n\n- **Bugs and feature requests:** [GitHub Issues](https://github.com/DataViking-Tech/traitprint/issues)\n- **Privacy / data deletion:** `privacy@traitprint.com`\n- **Everything else:** `hello@traitprint.com`\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 23208,
  "sha": "6460fef67257776d85098c81d09f306a3b9d06644d831697bed589a798739462",
  "repo_slug": "dataviking-tech/traitprint",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_dataviking_tech_traitprint_1c74ff91/readme"
}