# Adopting files already in your repository

A game that started before agh already has art, audio and text in its repository. Adopting brings those files into agh, so the inventory and the AI disclosure count them, without moving anything. Admins and developers adopt, since adopted files count as published.

## What adopting does

- agh lists the image, audio and model files on the project's branch (`png`, `jpg`, `webp`, `gif`, `svg`, `bmp`, `tga`, `psd`, `wav`, `ogg`, `mp3`, `flac`, `opus`, `m4a`, `aiff`, `fbx`, `glb`, `gltf`), and (beta) its writing and strings files. Hidden folders such as `.godot/` and `.github/` are left out.
- Each file you pick becomes an asset that is **published** from the start. It skips requesting, claiming and review. Its record says it was adopted, with the repository, branch and Git blob id it came from.
- agh copies the file, so it can show it in the Library, hand it out as a reference, and replace it later through a revision like any other asset.
- An image's size and metadata are read the same way they are for a delivery. If the metadata says AI was involved, the AI disclosure flags it.
- Once the last file is adopted, agh updates `.agh/provenance.yaml` in its pull request. The adopted files are already on the branch, so that is the only file in it.

## Strings and writing (beta)

This part is beta and may change.

- Strings files (`po`, `pot`, `xlf`, `xliff`, `arb`) and writing (`ink`, `yarn`) are always listed.
- `json`, `csv`, `md` and `txt` are listed across the whole branch only when their path names a language, since most such files aren't text for players. A language counts in the file name (`i18n/en.json`, `i18n/en-us.json`, `ui/menu.fr.json`) or a folder (`locale/fr/menu.po`). Name a folder, such as `agh adopt localization`, and every such file in it is listed.
- Files at the same path in other languages are linked as translations of the one in English (`en`, else `en-US`, else another English). `i18n/en.json` becomes `i18n`, and `i18n/fr.json` becomes `i18n.fr`, a translation of it. Translations are adopted after their source, and each records the source file it was made from.
- A strings file agh can't read, or one with no strings in it (such as `config/fr.json` holding `{"volume": 3}`), is skipped with a reason.

### Untracking a file adopted by mistake

If a file isn't really text for players, untrack it. Its asset record goes, the file stays in the repository, and the path joins the project's ignored list, so scans mark it ignored and adopting skips it.

```text
agh untrack config.fr                   # by asset id
agh untrack config/fr/settings.json     # or by path, even one agh never adopted
agh untrack --undo config/fr/settings.json
```

Only adopted assets can be untracked; one made through agh is removed with `agh remove`. A source with translations is untracked together with them. MCP: `untrack_files` (beta).

## How provenance is decided

agh doesn't guess how a file was made. For each file, the first of these that says wins:

1. What you give for that file.
2. What the repository's own `.agh/provenance.yaml` says about its path, if it has one. That covers a file written by hand before agh, or by another agh server.
3. What you give for the whole adoption, such as `--provenance human --made-by "Jane Doe"`.
4. Otherwise `unknown`.

Files with unknown provenance are listed under **Check before you fill in the disclosure** in the AI disclosure report. Record each one with `agh mark <id> --provenance ... --made-by ...` (an agent uses `set_provenance`) as you find out, and the burn-down shows the unknowns going away.

`.agh/provenance.yaml` lists what agh tracks. Once you adopt, any entry in a hand-written file for a file you didn't adopt is dropped the next time agh writes it. So adopt everything the file lists, or copy what it says first.

## On the web page

Open **Publish** and scroll to **Already in the repository**. Type a folder, such as `art/cards`, or leave it empty for the whole branch, and choose **Scan**. Untick anything you don't want, pick the provenance and **Made by** for files nothing else describes, and choose **Adopt selected**.

## From the CLI

```text
agh adopt art/cards --dry-run           # what's there that agh doesn't track yet, and the ids it would get
agh adopt art/cards                     # adopt them
agh adopt audio/music --provenance human --made-by "Jane Doe"
```

Ids come from the path: `art/cards/Ember Wolf.png` becomes `art.cards.ember_wolf`. A file whose id is taken gets `_2`, and so on. Rename ids you want shaped differently by adopting through the API with an `id` for each file.

## From an agent

The MCP tools `scan_repository` and `adopt_files` do the same. An agent should leave provenance `unknown` unless you tell it how the files were made.

## Git LFS

Files in Git LFS are adopted like any other: agh reads their content from the repository's LFS storage, which counts toward its owner's LFS bandwidth on GitHub. A pointer whose content the LFS storage doesn't have is skipped with a reason.

## Assets already on Roblox

A Roblox game's images, audio and models live on Roblox, not in the repository. **Already on Roblox** on the Publish page, and `agh adopt-roblox`, adopt them by Roblox asset id. See "Adopting assets already on Roblox" in `agh guide roblox`.

## Not yet

- A scan lists a file in Git LFS at the size of its pointer, not of its content.
- Files in other formats aren't found by a scan, nor are `json`, `csv`, `md` and `txt` files whose path names no language, unless you scan their folder. Adopt one through the API with its `kind`.
- A repository too large for GitHub to list at once is listed in part; scan one folder at a time.