Skip to main content

Discovery

Discovery is where ACE builds its understanding of your project. You will find it at Knowledge → Discovery in the sidebar. The page header sums it up: "What ACE knows about this project — code, stack and structure. Agents are grounded from the same model you see here."

Everything downstream depends on what happens here. The Learn area (Learning Paths, Book mode, Diagrams, AGENTS.md) and the Chat assistant are both grounded on the model that Discovery produces. If you have not run Discovery, ACE has nothing to reason from.

What are the steps, and in what order?​

There is one mandatory step and several optional ones, and they have a strict order:

  1. Map code (mandatory): the only step you must do. It requires nothing but a connected repository.
  2. Synthesize your architecture (recommended, not required): turns the mapped code (and any confirmed infrastructure) into a narrative and a relationship diagram. You can do this right after mapping code, even with no cloud infrastructure at all.
  3. Discover infra (optional, only if your app is hosted in the cloud): requires a connected cloud account and a saved scan scope (regions). This produces a raw inventory of candidate and confirmed resources.
  4. Investigate (optional, and only meaningful after step 3): requires that an infra census has already completed for the provider you are investigating. It cross-references that inventory with your mapped code and writes the Infra Map (with a diagram) plus new relationship data.

You can technically click "Discover infra," "Configure scope," or "Investigate" before ever mapping code (the buttons are not disabled by that), but they will fail immediately if a cloud account is not connected, and Investigate will fail with a message telling you to run an infra census first if one has not completed. Mapping code is the only step the page truly gates on.

The page itself is organized into four tabs: Codebase, Architecture, Infrastructure, and Runs.

In this section​

What do I need before I start?​

You need at least one repository connected to the project. If none is connected, Discovery shows a checklist screen instead of any data:

  • "ACE doesn't know this project yet", with the explanation: "Map the code to give agents real grounding on stack and structure — no cloud credentials needed. Public repositories work out of the box; private ones use the project's GitHub connection."
  • A checklist of three items: "Project selected", the number of repositories registered (or "No repositories registered" with a "Connect a repository →" link to the Repositories page), and whether GitHub is connected (or "GitHub not connected — required to map private repos" with a "Connect GitHub →" link to the Integrations page).
  • If you have repositories but no GitHub connection, a warning appears: "Heads up: without a GitHub connection, only public repos will map — private ones will fail to clone."
  • A "Map code" button at the bottom (labelled for example "Map code (2 repos, a few minutes)"), disabled until at least one repository is registered.

Connecting a repository or a cloud account (GitHub, AWS/GCP/Azure) happens on the Repositories and Integrations pages, covered in a different guide. Here, Discovery only checks whether that connection already exists.

How this connects to the rest of the platform​

Everything Discovery produces (the codebase map, the infrastructure inventory, the Infra Map, and the synthesized architecture narrative) is the material that powers Learn: Learning Paths, Book mode, Diagrams, and AGENTS.md are all generated from these same artifacts, and the Chat assistant reasons from them directly. Confirmed infrastructure resources with a health check also appear on the Monitoring dashboard (Operations section), which is why confirming, removing, or toggling monitoring here immediately affects what you will see being watched there.

Where to find it​

Left sidebar → Knowledge → Discovery, or go straight to /knowledge/discovery. It is a per-project view, scoped to whichever project you currently have selected in the sidebar.

Who can do this?​

You need discovery:read to see this page at all. Every action button (Map code, Synthesize, Discover infra, Configure scope, Investigate, confirming or discarding resources, editing health checks) needs discovery:manage, and additionally the project itself must still be mutable (not archived, provisioning, or degraded). Without discovery:manage, every action button on the page is replaced by a "Read only" label; you can still view (but not change) anything.

On this page