Secrets live only in .env (gitignored); gitleaks runs on every commit.

Models are swappable at runtime — no rebuild. Open the in-app Configuration dialog and set Main agent / Subagents to a <provider>:<model> string (e.g. anthropic:claude-sonnet-4.6); leave blank to use the defaults. Settings persist in your browser's local storage.

Recommended: Claude Sonnet 4.x, GPT-5.x, or Gemini 3.x — e.g. anthropic:claude-sonnet-4.6, openai:gpt-5.4, google_genai:gemini-3.5-flash.

Run it for free or fully local:

• Tavily and LlamaCloud both include a generous monthly free tier — plenty for local use.
• Google AI Studio offers a free tier for Gemini flash / lite models.
• Fully local — point OPENAI_API_BASE at LM Studio or Ollama (both expose an OpenAI-compatible API) and fill your local model in the UI.

Output quality tracks the model you pick — smaller local models trade some quality for zero cost.

• Code edits hot-reload in both containers — just save the file.
• Add a frontend dep: pnpm --dir frontend add <pkg> → docker compose restart frontend
• Add a backend dep: uv add <pkg> → docker compose up -d --build backend
• Change .env: docker compose restart <service>
• Stop: docker compose down (add -v to wipe the DB & Redis volumes)

1. Intake — the agent asks for your CV, the JD (file, URL, or pasted text), your prep timeline, and any extra context.
2. Process documents — uploads are parsed to markdown via LlamaParse (parse_document); JD URLs are pulled via Tavily (extract_jd). Results land in /processed/, alongside a persisted intake note.
3. Research — the hiring-recon subagent gathers company + role intel and a match analysis → /research/<resume>/<jd>.md.
4. Tailor & coach (parallel) — resume-tailor rewrites the CV as a rendercv YAML and renders a PDF; interview-coach writes a structured prep doc (self-intro + per-round STAR stories).
5. Battlecard — the main agent assembles a one-page-per-round JSON and renders it to a day-of PDF via WeasyPrint.
6. Multi-turn updates — ask for changes in chat; the owning agent reads the existing file, preserves everything you didn't name, and re-renders.

The full procedure (file layout, update routing, source-of-truth conventions) lives in backend/app/career_agent/README.md. Per-feature design docs are in docs/prd/.

The agent's behavior is configured by files, not hardcoded — making it easy to read, diff, and extend:

Subagents only receive the tools they opt into in YAML — tool whitelisting keeps interview-coach, for example, from inheriting the main agent's full toolset.

A single CompositeBackend gives the agent one virtual filesystem while routing each path prefix to the right physical store — Postgres for text artifacts, disk for binaries and render outputs, and a shell backend that translates virtual paths to real ones before running commands like rendercv render.

flowchart LR
    Agent["Agent filesystem tools<br/>read_file · write_file · edit_file<br/>ls · glob · grep · execute"]
    CB{{"CompositeBackend<br/>routes virtual paths"}}
    Agent --> CB
    subgraph Shell["VirtualPathShellBackend · default route"]
        SH["rewrites /virtual/path → on-disk path<br/>before subprocess.run<br/>(e.g. rendercv render /tailored_resume/...)"]
    end
    subgraph Store["StoreBackend · Postgres + pgvector"]
        ST["/memory/ · /processed/ · /research/<br/>/interview_coach/<br/>/large_tool_results/ · /workspace/"]
    end
    subgraph Disk["FilesystemBackend · disk (binaries + renders)"]
        DK["/upload/ · /tailored_resume/<br/>/render_intermediate/<br/>/interview_battlecard/"]
    end
    CB -->|default| Shell
    CB -->|KV routes| Store
    CB -->|binary + PDF routes| Disk
    Sem["Semantic memory · AGENTS.md"] -. loaded into system prompt .-> Agent
    Proc["Procedural memory · skills/*/SKILL.md"] -. loaded on demand .-> Agent
    Work["Working memory · LangGraph thread"] -. drives .-> Agent
    Store --- Epi["Episodic memory · persisted artifacts<br/>(incl. /memory/ auto-memory)"]
    Disk --- Epi

Mapped to memory types:

• Working memory — the live LangGraph conversation thread.
• Semantic memory — AGENTS.md, always in the system prompt.
• Procedural memory — skills/*/SKILL.md, loaded on demand.
• Episodic memory — persisted artifacts in Postgres + disk, including auto-memory: standing preferences saved to the /memory/ route and auto-applied across sessions.

Because NextRole runs on the LangGraph Agent Server, the career_agent assistant is also reachable by other tools and agents — no extra code:

• MCP — exposed as Model Context Protocol tools at /mcp (Streamable HTTP), usable by any MCP-compliant client. → docs
• A2A — Google's Agent2Agent protocol at /a2a/{assistant_id} (JSON-RPC 2.0; message/send + message/stream). → docs
• The full server API is browsable at the /docs endpoint of your deployment.

Set LANGCHAIN_API_KEY and LANGCHAIN_TRACING_V2=true in .env, and every run — each LLM call, tool call, and nested subagent — is traced at smith.langchain.com under the LANGCHAIN_PROJECT you configure. Optional, but invaluable for debugging the multi-agent flow.