# Principal AI<br>*Guided, human-authored trails through codebases.*

A **trail** is a walkthrough pinned to specific files and line ranges; a<br>**topic** bundles related trails; a **repo catalog** lists everything<br>Principal knows about one repository.

## Fetch any page as an agent<br>Every shareable page content-negotiates on the `Accept` header: a browser<br>gets the interactive app; a programmatic caller gets Markdown (default) or<br>JSON (`Accept: application/json`) at the same URL.

- `https://app.principal-ade.com/{owner}/{repo}` — repo catalog (published trails + tours)<br>- `https://app.principal-ade.com/trail/{id}` — a single trail (markers pinned to files/lines)<br>- `https://app.principal-ade.com/topic/{id}` — a topic (a curated bundle of trails)

## Open a trail or tour locally<br>Fetching the Markdown above tells you what a trail *says*. To open one in<br>the interactive viewer — 3D File City, source side-by-side — use the<br>Principal CLI. The argument is the bare id or the full `/trail/` (or<br>`/tour/`) URL from any page above:

```bash<br>npx -y @principal-ai/principal-view-cli trail view<br>npx -y @principal-ai/principal-view-cli tour view<br>```

The viewer GUI ships macOS arm64 prebuilds only. On other platforms — or a<br>headless/CI agent — fetch the trail JSON instead of opening the viewer:

```bash<br>npx -y @principal-ai/principal-view-cli trail fetch<br>```

Private or gated repos: the same CLI resolves your GitHub token (via the<br>`gh` CLI or a git credential helper) and calls these APIs with a `Bearer`<br>token, so it returns anything your GitHub account can read.

Explore (interactive): https://app.principal-ade.com/<br>JSON: https://app.principal-ade.com/api/home