# get_overview

get_overview orients an agent in an unfamiliar repo: summary, key modules, entry points, layers, commands, code health, the riskiest files and this week's top actions.

The opening move on any new codebase. One call returns a summary, one row
per package or top-level directory, the entry points, the layers, the build
and test commands, code health, the riskiest files and this week's top
actions, drawn from the [dependency graph](https://docs.repowise.dev/intelligence/dependency-graph)
and [git history](https://docs.repowise.dev/intelligence/git-history). The rest of the tool surface
is on [MCP tools](https://docs.repowise.dev/mcp/overview).

It is compact on purpose. The outline, the onboarding walks, the
ownership map, the code communities, the quarter's actions, the tool surface
and the full index scope are **not** in a default response, and they are not computed unless you ask: each is gated
behind an `include` value. The response's `more` field names them, so
an agent that wants one can see what to ask for.

## When to call

- **First**, before the agent reads any source.
- **Workspace orientation**: pass `repo="all"` to get cross-repo
  topology and contract links.
- **Onboarding a person**: `include=["tour", "outline"]` for the
  page-by-page walk and the wiki tree behind it.

Skip it on later calls in the same session. The map does not change
mid-session.

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `repo` | string | `default repo` | Repository alias, path, or ID. Omit for the default repo. Pass "all" for a workspace-level overview. |
| `include` | string[] |  | Opt-in blocks, any combination of "content", "outline", "tour", "decisions", "graph", "ownership", "components", "changes", "actions", "tools", "scope". An unknown value is named in ignored_arguments. Anything not named here is not computed. |

## Returns by default

| Field | Description |
|---|---|
| `title` | Repo name |
| `content_md` | The overview essay trimmed to its summary section. `content_hint` accompanies it when trimmed, pointing at `include=["content"]` for the full walkthrough |
| `code_health` | Headline score and band, `production_average` (non-test files, when the reading holds tests), hotspot health, worst file, open findings, `code_files` and `files_by_band` |
| `key_modules` | One row per topmost module page (a package or top-level directory), in outline order, up to 12: `name`, `path`, outline `section`, `package` when the page sits inside one, and `pages` beneath it. The prose lives on `get_context(path)` |
| `entry_points` | Up to 15 entry points, with build and CI tooling set aside and each package's together (test fixtures excluded) |
| `commands` | Build, test, lint, dev, format and typecheck commands read from manifests: `"."` for the root, plus each package that names a task the root does not |
| `git_health` | Hotspot count, churn trend and `riskiest_files`: five paths, bug magnets first, then fix mass, then churn |
| `architecture` | Layer names, file counts and `root` (the directory holding most of the layer) in stack order, test layer left out. `dependencies` adds the ten heaviest package-to-package edges with `from`, `to`, `verb` and `weight`; absent in a single-package repo |
| `next_actions` | The first three actions (`id`, `tier`, `title`, a one-line `impact`, `target`) for the week, or the quarter when the week is empty, with each horizon's `total`. The same list as the dashboard's "Do next" and [`repowise next`](https://docs.repowise.dev/cli/other#repowise-next). `next_actions_reason` explains an absent block. `unavailable` names inputs the list was built without and `unavailable_reasons` gives each one's reason; both are absent when every input was read |
| `more` | One sentence naming every `include` block and what it adds |
| `workspace` | *(workspace mode only)* root, default repo hint, cross-repo topology, contract links |

## Opt-in blocks

Named in `include` or absent. Absent means not built, not withheld.

| `include` value | Adds |
|---|---|
| `"content"` | The full overview essay in `content_md` instead of its summary section |
| `"outline"` | `outline`, the stored wiki page tree two rungs deep, plus `outline_hint` on how to read `section` and `descendants` |
| `"tour"` | `guided_tour` and `reading_order`, the onboarding walks, each with its own hint field |
| `"decisions"` | `key_decisions`, the governing decision records. [`get_why`](https://docs.repowise.dev/mcp/get-why) is the richer route |
| `"graph"` | `community_summary`, the top 10 code-community clusters by size |
| `"ownership"` | `knowledge_map`, carrying `top_owners` |
| `"components"` | Declared and derived components with their file counts |
| `"changes"` | Change Records by category and week, and the agent share of changes with its coverage |
| `"actions"` | Both horizons of `next_actions` (week and quarter), with `done_when` and counts by tier |
| `"tools"` | `tool_surface`: which tools this server advertises, the opt-ins, and composition recipes |
| `"scope"` | The whole `_meta.index_scope` object: run mode, provenance, git tier and coverage of the index |

`guided_tour` is the topology-driven walk derived from the import
graph: entry points first, then inward, infrastructure last. It is
persisted on the overview page at generation time, so asking for it
costs a read instead of a traversal.

## Example

```python
get_overview()                              # default repo, compact
get_overview(include=["content", "outline"])
get_overview(include=["tour"])              # onboarding walk
get_overview(include=["components", "changes"])  # components and recent changes
get_overview(include=["actions", "scope"])  # quarter's actions, full index scope
get_overview(repo="frontend")               # one repo in a workspace
get_overview(repo="all")                    # workspace-level view
```

## Things worth knowing

- **The response budget moves when you ask for extras.** A default call
  is fitted to 24,000 characters; a call with a non-empty `include`
  gets 32,000. Reductions carry their counts in `_meta`, and an
  include-gated block that you did not ask for is a projection instead
  of an omission.
- **Churn trend** is computed from a 30-day vs 60-day commit-rate
  ratio: above 1.5x is `"increasing"`, below 0.5x is `"decreasing"`,
  otherwise `"stable"`.
- **`top_owners`** is capped at the top 3 contributors by files owned,
  and emits a display name only, never a contributor email. It answers
  "who do I ask", not "who owns this file"; for that use
  [`get_risk`](https://docs.repowise.dev/mcp/get-risk) or
  `get_context(include=["ownership"])`.
- **Caps are recoverable.** Module pages beyond 12 and entry points
  beyond 15 go to the omission store with a `[repowise#<ref>]` marker,
  not into the void.
- In workspace mode, `repo="all"` queries the repos concurrently, with
  a per-repo timeout. A repo that fails is named in `repos_failed` and
  one whose index is behind in `repos_stale`, while the rest answer.
- In workspace mode, `repo="all"` returns a per-repo dependency graph and
  contract links between services. Each repo row carries `summary` (the
  overview essay's first sentence), `code_files` and `symbol_count`;
  `total_code_files` sums them. It carries no single-repo detail.

> **Note**
>
> If the agent calls `get_overview` and immediately follows up with
> `Grep` or `Read`, your MCP server probably isn't connected. Check
> `.mcp.json` and run `repowise doctor`.