{% extends "base.html" %}

{% block title %}Help — karyab{% endblock %}

{% block content %}
<h1>Help &amp; setup</h1>
<p>Everything you need to install karyab, pick a ranker backend, register the MCP
server, and wire up LinkedIn job alerts via email.</p>

<h2>1. Requirements</h2>
<ul>
  <li><strong>Python 3.11+</strong></li>
  <li>A <strong>container runtime</strong> for the web UI — <strong>podman</strong>
      recommended, or docker.</li>
</ul>

<h2>2. Install karyab</h2>
<p>Install with <a href="https://pipx.pypa.io/">pipx</a>:</p>
<pre><code>pipx install karyab</code></pre>
<p>Optional extras:</p>
<ul>
  <li><code>karyab[mcp]</code> — the MCP server (for Claude Code / opencode).</li>
  <li><code>karyab[rank]</code> — the Anthropic ranker backend.</li>
  <li><code>karyab[ui]</code> — the web UI.</li>
</ul>
<pre><code>pipx install "karyab[mcp,rank,ui]"</code></pre>

<h2>3. Container runtime</h2>
<p>The web UI runs in a container. Install <strong>podman</strong> (recommended):</p>
<ul>
  <li>Debian / Ubuntu: <code>sudo apt install -y podman</code></li>
  <li>Fedora / RHEL: <code>sudo dnf install -y podman</code></li>
  <li>macOS: <code>brew install podman</code>, then
      <code>podman machine init &amp;&amp; podman machine start</code></li>
</ul>
<p>docker is an alternative. Once a runtime is available, start the UI:</p>
<pre><code>karyab start</code></pre>

<h2>4. Ranker backends</h2>
<p>The ranker scores jobs against your profile. Pick a backend with
<code>[ranker] backend = …</code> in <code>~/.config/karyab/config.toml</code>.</p>

<h3>manual</h3>
<p>No API key. Rank jobs from Claude Code or opencode via the karyab MCP tools.</p>
<pre><code>[ranker]
backend = "manual"</code></pre>

<h3>claude_cli</h3>
<p>Use a locally installed Claude Code CLI.</p>
<ul>
  <li>Install: <code>npm i -g @anthropic-ai/claude-code</code></li>
  <li>Authenticate: run <code>claude</code>, then <code>/login</code>.</li>
</ul>
<pre><code>[ranker]
backend = "claude_cli"</code></pre>

<h3>opencode</h3>
<p>Use the <a href="https://opencode.ai/">opencode</a> CLI.</p>
<ul>
  <li>Install: <code>curl -fsSL https://opencode.ai/install | bash</code>
      (or <code>npm i -g opencode-ai</code>).</li>
  <li>Needs <code>ANTHROPIC_API_KEY</code> (or run <code>opencode auth login</code>).</li>
</ul>
<pre><code>[ranker]
backend = "opencode"

[ranker.opencode]
bin = "opencode"
model = "anthropic/claude-sonnet-4-5"</code></pre>

<h3>anthropic</h3>
<p>Call the Anthropic API directly. Get an API key from
<a href="https://console.anthropic.com">https://console.anthropic.com</a> and put it in
<code>~/.config/karyab/secrets.toml</code>:</p>
<pre><code>[anthropic]
api_key = "sk-ant-…"</code></pre>
<pre><code>[ranker]
backend = "anthropic"</code></pre>

<h3>ollama</h3>
<p>Run a local or cloud model via <a href="https://ollama.com">ollama</a>.</p>
<ul>
  <li>Install: <code>curl -fsSL https://ollama.com/install.sh | sh</code></li>
  <li>Local model: <code>ollama pull llama3.1</code></li>
</ul>
<p><strong>Cloud models</strong> (e.g. <code>minimax-m3:cloud</code>): create an account at
<a href="https://ollama.com">https://ollama.com</a>, run <code>ollama signin</code>, then:</p>
<pre><code>[ranker.ollama]
score_model = "minimax-m3:cloud"
host = "http://localhost:11434"
num_predict = 4096</code></pre>
<p>Reasoning models need a high <code>num_predict</code> cap.</p>
<p>For the <strong>web-UI</strong> ranker specifically, put the ollama settings under
<code>[ranker.ui]</code> (an overlay) so the UI uses ollama while the host MCP can stay
on Claude:</p>
<pre><code>[ranker.ui]
backend = "ollama"

[ranker.ui.ollama]
score_model = "minimax-m3:cloud"
host = "http://localhost:11434"
num_predict = 4096</code></pre>
<p>(opencode can also target a model like minimax via its provider config — see
<a href="https://opencode.ai/docs/">https://opencode.ai/docs/</a>.)</p>

<h2>5. MCP setup</h2>
<p>Register the karyab MCP server with Claude Code and/or opencode:</p>
<pre><code>karyab mcp-setup --target claude|opencode|both</code></pre>

<h2>6. Email integration (LinkedIn job alerts → karyab)</h2>
<p>karyab reads LinkedIn job-alert emails from a mailbox folder and parses them into
jobs. There is <strong>no LinkedIn scraping</strong> — alerts arrive via email only.</p>

<h3>Authentication</h3>
<ul>
  <li><strong>Outlook / Microsoft</strong> uses OAuth device-code. Run
      <code>karyab email-auth</code> (or click <strong>Set up email</strong> on the
      <a href="/config">Config</a> page) and follow the URL + code.</li>
  <li><strong>Gmail</strong> uses an app password stored in
      <code>~/.config/karyab/secrets.toml</code>.</li>
</ul>

<h3><code>[sources.email]</code> keys</h3>
<ul>
  <li><code>imap_host</code> — <code>outlook.office365.com</code> for Outlook OAuth, or
      <code>imap.gmail.com</code> for Gmail.</li>
  <li><code>auth</code> — <code>oauth</code> or <code>basic</code>.</li>
  <li><code>username</code> — the mailbox address.</li>
  <li><code>folder</code> — the IMAP folder to read.</li>
  <li><code>oauth_client_id</code> / <code>oauth_authority</code> — optional; default to
      the Thunderbird public client / consumer login.</li>
</ul>

<h3>LinkedIn alerts → folder flow</h3>
<ol>
  <li>In LinkedIn, create a <strong>Job Alert</strong> delivered by <strong>email</strong>
      to your address
      (<a href="https://www.linkedin.com/help/linkedin/answer/a511275">job alerts</a>).</li>
  <li>In your mail client, create a <strong>rule / filter</strong> that moves
      "LinkedIn Job Alerts" sender emails into a dedicated folder, e.g.
      <code>Inbox/LinkedIn Job Alerts</code>
      (<a href="https://support.microsoft.com/office/manage-email-messages-by-using-rules-c24f5dea-9465-4df4-ad17-a50704d66c59">Outlook rules</a>;
      <a href="https://support.google.com/mail/answer/6579">Gmail filters</a>).</li>
  <li>Set <code>[sources.email] folder</code> to that folder.</li>
  <li>Run <code>karyab fetch</code> (or use the UI <strong>Fetch</strong>) to read and
      parse those alerts into jobs.</li>
</ol>
{% endblock %}