hikari-desktop/src/lib/components/docs/DocsTroubleshooting.svelte

<h3 class="text-lg font-semibold text-[var(--text-primary)] mb-4">Troubleshooting</h3>

<div class="space-y-4 text-sm text-[var(--text-secondary)]">
  <div>
    <h4 class="font-medium text-[var(--text-primary)] mb-2">Can't Connect</h4>
    <ul class="space-y-1">
      <li>
        • Check that your API key is entered correctly in Settings (<kbd class="kbd">Ctrl+,</kbd>)
      </li>
      <li>
        • Ensure you have an active internet connection — Hikari needs to reach the Anthropic API
      </li>
      <li>• Try setting an explicit working directory rather than leaving it blank</li>
      <li>• Check the Debug Console (<kbd class="kbd">Ctrl+`</kbd>) for error details</li>
    </ul>
  </div>

  <div>
    <h4 class="font-medium text-[var(--text-primary)] mb-2">
      Hikari Seems Stuck or Stopped Responding
    </h4>
    <ul class="space-y-1">
      <li>
        • Press <kbd class="kbd">Ctrl+C</kbd> (when no text is selected) to interrupt the current process
      </li>
      <li>• If that doesn't work, disconnect and reconnect from the connection bar</li>
      <li>
        • Check the Stats panel for context window usage — if it's near 100%, use
        <strong>Compact Conversation</strong> to free up space
      </li>
    </ul>
  </div>

  <div>
    <h4 class="font-medium text-[var(--text-primary)] mb-2">API Errors or Rate Limits</h4>
    <ul class="space-y-1">
      <li>• Verify your API key is valid at <strong>console.anthropic.com</strong></li>
      <li>• Check that your account has sufficient API credits</li>
      <li>
        • If you hit rate limits frequently, consider switching to a faster/cheaper model in
        Settings
      </li>
      <li>• The Debug Console will show the specific error returned by the API</li>
    </ul>
  </div>

  <div>
    <h4 class="font-medium text-[var(--text-primary)] mb-2">Tool Permissions Blocking Work</h4>
    <ul class="space-y-1">
      <li>
        • When prompted, you can choose <strong>Allow for session</strong> to avoid repeated prompts
      </li>
      <li>• Adjust the permission mode in Settings to auto-approve trusted tools</li>
      <li>
        • If a tool call was denied by mistake, simply ask Hikari to try again — she'll prompt you
        once more
      </li>
    </ul>
  </div>

  <div>
    <h4 class="font-medium text-[var(--text-primary)] mb-2">
      Missing Features or Greyed-Out Buttons
    </h4>
    <ul class="space-y-1">
      <li>• Some features require an active connection — connect to a working directory first</li>
      <li>
        • The File Editor (<kbd class="kbd">Ctrl+E</kbd>) is only available when connected
      </li>
      <li>• The Agent Monitor shows activity only during Task Loop or multi-agent sessions</li>
    </ul>
  </div>

  <div>
    <h4 class="font-medium text-[var(--text-primary)] mb-2">Workspace Trust Prompt</h4>
    <p>
      If you see a trust prompt when connecting, it means Hikari detected hooks, MCP servers, or
      slash commands in your working directory. Review them carefully before clicking
      <strong>Trust &amp; Connect</strong>. See the <strong>Panels &amp; Tools</strong> page for more
      details.
    </p>
  </div>

  <div>
    <h4 class="font-medium text-[var(--text-primary)] mb-2">Context Window Full</h4>
    <p>Watch the context bar in the Stats panel. When it approaches 100%:</p>
    <ul class="space-y-1 mt-2">
      <li>
        • Use <strong>Compact Conversation</strong> from the menu to summarise and compress the history
      </li>
      <li>
        • Use <strong>Start Fresh with Context</strong> to begin a new session that carries over a summary
      </li>
    </ul>
  </div>

  <div>
    <h4 class="font-medium text-[var(--text-primary)] mb-2">Reporting Issues</h4>
    <p>
      If you encounter a bug or unexpected behaviour, please report it on our
      <strong>GitHub issues page</strong>. Include:
    </p>
    <ul class="space-y-1 mt-2">
      <li>• What you were doing when the issue occurred</li>
      <li>• Any error messages from the Debug Console</li>
      <li>• The app version (shown in the About panel)</li>
    </ul>
    <p class="mt-2">
      You can also join our <strong>Discord community</strong> (link in the menu) for real-time support.
    </p>
  </div>
</div>

<style>
  kbd.kbd {
    display: inline-block;
    padding: 0.1rem 0.35rem;
    font-size: 0.75rem;
    font-family: monospace;
    background: var(--bg-secondary);
    border: 1px solid var(--border-color);
    border-radius: 3px;
    color: var(--text-primary);
  }
</style>