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

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

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

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

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

```bash
npx -y @principal-ai/principal-view-cli trail view <trail-id-or-url>
npx -y @principal-ai/principal-view-cli tour view <tour-id-or-url>
```

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

```bash
npx -y @principal-ai/principal-view-cli trail fetch <trail-id-or-url>
```

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

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