Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
docs: add GitHub Companion documentation, star button on docs page
Salman Qureshi54f95d7a0d36
diff --git a/docs/docs.html b/docs/docs.htmlindex b303747b..9ad9f387 100644--- a/docs/docs.html+++ b/docs/docs.html@@ -220,6 +220,50 @@width: 100%;}}++ .github-btn {+ display: inline-flex;+ align-items: center;+ gap: 6px;+ background: rgba(255,255,255,0.06);+ border: 1px solid var(--border);+ color: var(--gray) !important;+ padding: 4px 12px 4px 10px;+ border-radius: 6px;+ font-size: 0.85em;+ font-weight: 500;+ text-decoration: none !important;+ transition: all 0.2s;+ }++ .github-btn:hover {+ border-color: #444;+ color: var(--white) !important;+ background: rgba(255,255,255,0.1);+ }++ .github-btn svg {+ flex-shrink: 0;+ }++ .github-btn-text {+ font-size: 0.95em;+ font-weight: 600;+ }++ .github-btn-count {+ display: inline-flex;+ align-items: center;+ background: rgba(255,255,255,0.06);+ border-left: 1px solid var(--border);+ margin-left: 2px;+ margin-right: -6px;+ padding: 3px 8px;+ border-radius: 0 5px 5px 0;+ font-weight: 600;+ min-width: 20px;+ text-align: center;+ }</style></head>@@ -230,8 +274,11 @@<div class="nav-links" id="navLinks"><a href="index.html">Home</a><a href="docs.html" style="color: var(--cyan);">Docs</a>- <a href="https://github.com/cosmicstack-labs/mercury-agent" class="nav-cta" target="_blank"- rel="noopener">GitHub</a>+ <a href="https://github.com/cosmicstack-labs/mercury-agent" class="github-btn" target="_blank" rel="noopener">+ <svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" style="vertical-align:-2px;"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>+ <span class="github-btn-text">Star</span>+ <span class="github-btn-count" id="ghStars"></span>+ </a></div><button class="nav-toggle" id="navToggle" aria-label="Menu">☰</button></div>@@ -252,6 +299,8 @@<a href="#daemon">Background Mode</a><a href="#service">System Service</a><a href="#platform-guide">Platform Guide</a>+ <div class="sidebar-heading">Integrations</div>+ <a href="#github-companion">GitHub Companion</a><div class="sidebar-heading">Reference</div><a href="#tools">Built-in Tools</a><a href="#configuration">Configuration</a>@@ -640,6 +689,115 @@</div></div>+ <h2 id="github-companion">GitHub Companion</h2>+ <p>Mercury can act as your GitHub companion — creating pull requests, reviewing PRs, managing issues, and making+ co-authored commits — all through natural conversation. When configured, five GitHub tools are registered+ alongside Mercury's built-in toolset, letting you manage repositories without leaving the terminal.</p>++ <div class="callout">+ <div class="callout-title">Conditional availability</div>+ <p>GitHub tools <strong>only appear when <code>GITHUB_TOKEN</code> is configured</strong> via+ <code>mercury doctor</code>. Without a token, these tools are not registered and won't be available in+ conversation.</p>+ </div>++ <h3>Setup</h3>+ <p>Run <code>mercury doctor</code> and fill in the three GitHub fields:</p>+ <div class="terminal-inline">+ <code>mercury doctor</code>+ </div>+ <ul>+ <li><strong>GitHub username</strong> — your GitHub username (used for commit attribution)</li>+ <li><strong>GitHub email</strong> — the email tied to your GitHub account</li>+ <li><strong>GitHub PAT</strong> — a fine-grained Personal Access Token with repo scope</li>+ </ul>+ <p>Press <strong>Enter</strong> on any field to keep its current value. When the PAT is set, you'll see:</p>+ <div class="terminal-inline">+ <code>✓ GitHub tools registered (5)</code>+ </div>++ <h3>Creating a Fine-Grained PAT</h3>+ <ol>+ <li>Go to <a href="https://github.com/settings/personal-access-tokens/new" target="_blank"+ rel="noopener">github.com/settings/personal-access-tokens/new</a></li>+ <li>Give it a name (e.g. <code>mercury-agent</code>) and set an expiration</li>+ <li>Under <strong>Repository access</strong>, select <strong>All repositories</strong> or choose specific+ repos</li>+ <li>Under <strong>Permissions → Repository permissions</strong>, grant:+ <ul>+ <li><strong>Contents</strong> — Read and write (for commits)</li>+ <li><strong>Pull requests</strong> — Read and write</li>+ <li><strong>Issues</strong> — Read and write</li>+ </ul>+ </li>+ <li>Click <strong>Generate token</strong> and copy it immediately</li>+ </ol>++ <h3>GitHub Tools</h3>+ <table class="cmd-table">+ <thead>+ <tr>+ <th>Tool</th>+ <th>What it does</th>+ </tr>+ </thead>+ <tbody>+ <tr>+ <td>create_pr</td>+ <td>Create a pull request with title, body, head branch, and base branch</td>+ </tr>+ <tr>+ <td>review_pr</td>+ <td>Fetch a PR diff, review the changes, and post review comments</td>+ </tr>+ <tr>+ <td>list_issues</td>+ <td>List and filter issues in a repository (open, closed, by label, by assignee)</td>+ </tr>+ <tr>+ <td>create_issue</td>+ <td>Create a new issue with title, body, labels, and assignees</td>+ </tr>+ <tr>+ <td>github_api</td>+ <td>Raw GitHub API access — an escape hatch for any endpoint not covered above</td>+ </tr>+ </tbody>+ </table>++ <h3>Co-Authored Commits</h3>+ <p>When Mercury commits code using <code>git_commit</code>, it automatically appends a+ <code>Co-authored-by: Mercury <[email protected]></code> trailer. This means Mercury's avatar+ appears alongside yours in GitHub's commit history — giving credit where it's due.</p>++ <h3>Example: Create a PR</h3>+ <div class="terminal-window" style="max-width: 680px; margin: 20px 0;">+ <div class="terminal-bar">+ <span class="terminal-dot red"></span>+ <span class="terminal-dot yellow"></span>+ <span class="terminal-dot green"></span>+ <span class="terminal-title">mercury</span>+ </div>+ <div class="terminal-body" style="min-height: auto; padding: 16px 24px;">+ <p style="margin:0;color:var(--gray);">You: <span style="color:var(--white);">create a PR for this change</span></p>+ <p style="margin:0;color:var(--gray-dim); font-style:italic;"> [Using: git_status, git_diff, git_log]</p>+ <p style="margin:0;color:var(--gray-dim); font-style:italic;"> [Using: create_pr]</p>+ <p style="margin:0;color:var(--green);"> PR #42 created: "Add GitHub Companion docs section"</p>+ <p style="margin:0;color:var(--cyan);">Mercury:</p>+ <p style="margin:0;color:var(--white);"> Done! I've created PR #42 — "Add GitHub Companion docs section"</p>+ <p style="margin:0;color:var(--gray);"> targeting <code>main</code> from <code>feature/github-companion-docs</code>.</p>+ <p style="margin:0;color:var(--gray);"> The PR includes the new section, sidebar link, and nav button update.</p>+ </div>+ </div>++ <h3>Security</h3>+ <div class="callout" style="border-left-color: var(--yellow);">+ <div class="callout-title" style="color: var(--yellow);">PAT storage</div>+ <p>Your GitHub PAT is stored in <code>~/.mercury/mercury.yaml</code> alongside your other configuration. It is+ never sent to any external service — only to the GitHub API directly from your machine. Treat this file like+ any other credential: don't commit it, don't share it, and rotate the token if you suspect it's compromised.</p>+ </div>+<h2 id="tools">Built-in Tools</h2><p>Mercury has 21 built-in tools it can use during conversations. These are not CLI commands — the agent decideswhen to call them.</p>@@ -958,6 +1116,17 @@sidebarLinks.forEach(l => l.classList.remove('active'));if (current) current.link.classList.add('active');}, { passive: true });++ fetch('https://api.github.com/repos/cosmicstack-labs/mercury-agent')+ .then(function (r) { return r.json(); })+ .then(function (data) {+ var el = document.getElementById('ghStars');+ if (el && data.stargazers_count != null) {+ var n = data.stargazers_count;+ el.textContent = n >= 1000 ? (n / 1000).toFixed(1).replace(/\.0$/, '') + 'k' : n;+ }+ })+ .catch(function () {});</script></body>