> For the complete documentation index, see [llms.txt](https://pharaoh.so/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pharaoh.so/docs/use-pharaoh/troubleshooting.md).

# Scope and troubleshooting

## Check the connection

1. Open [setup](https://mcp.pharaoh.so/setup). Confirm the repository is live and its map is ready.
2. Ask your AI whether it has Pharaoh tools, then ask it to call `get_codebase_map` for that repository. Tool names can be requested in ordinary chat.
3. If tools are absent, check the connection settings for your [client](/docs/readme.md). Complete GitHub sign-in. If needed, start a new conversation after connecting.
4. If a query reports an access or mapping error, use its message and the setup status to identify the failing step. Reinstalling locally is unnecessary for a hosted account connector.

For Claude Code in WSL, check the existing account connector before changing environments. The session's Connectors menu and actual tool availability may differ. If controls remain unavailable, check for app updates and follow [Claude's WSL troubleshooting](https://code.claude.com/docs/en/desktop-wsl#if-the-terminal-or-connectors-are-unavailable).

## What the map covers

Pharaoh parses TypeScript, JavaScript and Python. Analysis uses the last mapped commit on the default branch. Pushes queue a refresh; the map's “Last refreshed” time describes the completed map, not local disk state. You can request a refresh through `pharaoh_account` or view status in setup.

Unmerged branches, local edits and worktrees are outside this map. PR Guard separately analyzes pull-request changes; that does not make the interactive map a local workspace view.

Calls and entry points are detected statically. Runtime dispatch, reflection and framework configuration can leave gaps. Current entry rules include recognized framework handlers, entry-file conventions, decorator registrations, package entry declarations, and direct Node/tsx commands in start, serve and dev scripts. Chained commands can be recognized; arbitrary delegated package scripts are not followed.

Wrangler-configured Worker handlers and Vite HTML module-script entries are not currently inferred from those configuration files. GitHub Actions schedules are not modeled as cron jobs. Cron impact refers to detected in-code registrations such as node-cron and CronJob.

## Read analysis results correctly

* Blast radius follows production callers and excludes test-file callers. Hops are the shortest detected call path, within the requested depth of one to five.
* “Without direct test links” means static analysis found no direct test relationship. It is not a runtime coverage measurement and does not rule out indirect tests.
* Entry-point counts describe detected function roots, not the number of executables you can launch.
* Hot-file counts are commits touching the path in the last 90 days of mapped Git history. Renames are treated as deletion/addition. Unavailable older last-modified dates remain unknown.
* Unused-code results depend on detected reachability and reference evidence. Check runtime loading and configuration before deleting code. You can check a method by `Class.method`; a bare method name can match more than one class.

## Prompts and visible output

Pharaoh publishes MCP prompt playbooks. They appear only in clients that support MCP prompt discovery; the terminal installer also adds the Pharaoh plugin commands. Ask for a tool by name when you want a specific query.

Some clients collapse raw tool output. Ask the AI to show the returned modules, file counts, callers and limits as a plain table. A hidden ASCII panel does not mean the query failed.

## Declare an entry the detector cannot infer

Use `.pharaoh.yml` in the repository root:

```yaml
pr_guard:
  entry_points:
    - "src/handlers/**/*.ts"
  not_test:
    - "src/__mocks__/**"
  allowed_orphans:
    - "src/plugins/**:registerPlugin"
```

`entry_points` marks matching files' exports as roots. `not_test` treats matching files as production code. `allowed_orphans` excludes intended unused exports from dead-code findings; use `path/glob:functionName` or `path/glob:*`. Patterns use `*` for one path segment and `**` for multiple segments. Refresh after the configuration reaches the default branch.