# tangled — setup

The `tangled` skill has no scripts of its own; it points the agent at [`tg`](https://github.com/alyraffauf/tg), a command-line client for [Tangled](https://tangled.org), the git forge built on atproto. This file covers installing, logging in, and the configuration knobs worth knowing; `SKILL.md` covers how to drive it, and assumes it already works. Both are written against `tg` 0.9.0.

## Install

```bash
mise use -g "go:github.com/alyraffauf/tg/cmd/tg@latest"

# or, without a Go toolchain
brew tap alyraffauf/tap && brew trust alyraffauf/tap && brew install alyraffauf/tap/tg
nix profile add github:alyraffauf/tg

type -P tg && tg --version
```

mise resolves this through its Go backend (`go:github.com/alyraffauf/tg/cmd/tg`), so it builds from source and needs no tap. If a fresh shell cannot find `tg`, check that mise's activation runs there (`mise doctor`, or source `~/.bashrc`).

## Log in

```bash
tg auth login spencergilbert.dev    # OAuth: browser, loopback callback on 127.0.0.1
tg auth status                      # handle, DID, and session state
tg auth list                        # every stored account, with its login method
```

`tg auth login` authenticates against the account's atproto PDS, not Tangled itself. OAuth is the default and binds a loopback callback (RFC 8252), so it needs a browser on the same machine as the command.

## Headless and remote hosts

```bash
# App password on stdin keeps it out of the process list and out of shell history
op read 'op://Private/Pi/tangled-app-password' | tg auth login spencergilbert.dev --password-stdin

# No keyring at all: --insecure stores one account in plaintext
tg auth login spencergilbert.dev xxxx-xxxx-xxxx-xxxx --insecure
```

Sessions live in the OS keyring — macOS Keychain, Secret Service (GNOME Keyring or KWallet) on Linux — and are read lazily, so a broken keyring only shows up on the first command that needs a session.

- **Install and log in on the machine where `tg` runs.** A login made locally is invisible to pi on a remote host, in a container, or on a runner; without a browser there, log in with an app password.
- **No D-Bus session bus** (containers, CI runners): start `gnome-keyring-daemon` or `kwalletd`, or point at the running bus with `export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id -u)/bus"`. Otherwise use `--insecure`.
- **`--insecure` requires an app password** — it does not support OAuth — and stores a single account at `~/.local/share/tg/credentials.json` (`0700` directory, `0600` file), overwritten by the next login.
- Create the app password in the PDS account settings (for Bluesky-hosted accounts: Settings → App Passwords), not on Tangled.

## Multiple accounts

Logging in adds or replaces that account and makes it the default.

```bash
tg auth switch other.example.com              # change the default
tg issue create ... --account other.example.com   # one-command override (or TG_ACCOUNT)
tg auth logout                                # removes the selected account; --all removes every one
```

An issue or PR lives in its author's repo, so only the account that opened it can edit, label, close, or add rounds to it. Those commands do take `-R`, but naming someone else's repository does not grant write access — log in as the author, or the write fails upstream.

## Configuration

`~/.config/tg/config.toml` (`--config` or `TG_CONFIG` relocates it), with `TG_`-prefixed environment variables and then flags layered on top. The file is optional; defaults are shown.

```toml
appview = "https://api.tangled.org"   # read API (Bobbin)
ssh-port = 22                         # port for an explicitly pinned knot's direct remotes
protocol = "ssh"                      # clone URL scheme: ssh or https
# account = "spencergilbert.dev"
# foster-knot = "knot1.tangled.sh"    # read-only host for legacy ticket records
# knot = "knot1.tangled.sh"           # pin repo creation instead of verified discovery
```

| Key | Environment | Flag |
| --- | --- | --- |
| `appview` | `TG_APPVIEW` | `--appview` |
| `account` | `TG_ACCOUNT` | `--account` |
| `foster-knot` | `TG_FOSTER_KNOT` | `--foster-knot` |
| `knot` | `TG_KNOT` | `tg repo create --knot` |
| `ssh-port` | `TG_SSH_PORT` | — |
| `protocol` | `TG_PROTOCOL` | — |

Leave `knot` unset unless discovery is ambiguous: with no `knot`, `tg repo create` reads the account's knot registrations, verifies them, and needs exactly one to succeed. It errors and lists the candidates when several verify.

`foster-knot` exists for repositories migrated from the older social model: the appview serves their tickets, but the authoritative record lives on the foster knot that accepted them, so `tg issue view` and `tg pr view` read the body and CID from there when the repository's own knot is not the one holding them. Set it only for such a repository; on a native one it is ignored.

## Remotes

`tg repo clone` writes a remote that survives handle changes, renames, and transfers: the repository DID behind the `tangled.org` proxy (`git@tangled.org:did:plc:...`), or a direct remote on an explicitly pinned knot. When it cannot resolve the DID during a clone it falls back to a `handle/repo` remote and prints the resolution error as a warning.

Both forms resolve when `tg` infers the repository from inside a checkout, so most commands need no `handle/repo`: it reads every remote, `origin` first, and for a custom knot host it verifies that host against the repository record before accepting the remote. Name the repository explicitly when `origin` is a fork, when the checkout has no Tangled remote, or when several remotes compete — otherwise the first one that resolves wins, which for a fork is your fork.

HTTPS pushes use `tg` as a credential helper, which mints a short-lived knot token per push and stores nothing:

```bash
git config --global credential."https://tangled.org".helper "!tg auth git-credential"
git remote set-url origin https://tangled.org/<repo-did>
```

## Troubleshooting

- **`no Git remote matches a Tangled repository record: ...; pass the repository as handle/repo`** — no remote in the checkout resolves, or the ones that looked Tangled failed verification (a custom knot host that disagrees with the record). Give the repository explicitly instead: `tg pr list handle/repo`, or `-R handle/repo`.
- **`Error: accepts 1 arg(s), received 2`** — the repository is a flag on that subcommand, not a second positional. Record commands (`pr view|diff|comment|checkout|merge|update`, `issue view|comment|close|reopen|edit`) and every `pipeline` command except `list`/`status` take `-R`.
- **`source commit ... is not the published tip of ...` / `confirm published source branch ...: retry once the source repository is available in the Git mirror`** — the branch is not pushed, or the mirror has not caught up. `git push`, wait, retry; `tg` never pushes.
- **`fork pull requests require --base; pass the target remote branch, for example --base upstream/main`** — a fork PR needs all three of `-R <target>`, `--source-repo <fork>`, and `-B <target remote branch>` after fetching the target.
- **`base targets "main" but ticket targets "master"`** — `pr update -B` has to select the branch the PR already targets, not a new one.
- **`target branch ... is published at ..., but local base ... cannot provide that commit`** — fetch the target remote before creating the PR.
- **`unknown label "..."` / `ambiguous label "..."`** — apply only names from the repository's `labels[]` in `tg repo view --json`, and only ones that appear once.
- **`ticket changed since the expected CID; read it before retrying` / `read it before merging`** — someone moved the record between your read and your write. Re-read and re-apply; never retry blind, and never repeat a write that reported a dropped connection without checking first.
- **`pull request is recorded as merged; its state cannot change`** — `completed` is terminal; reopen is not available for a merged PR.
- **`fatal: not a git repository`** — `tg` shells out to `git` to infer the repository. Run it inside a checkout, or name the repository.
- **A command that never returns** — it is waiting on `$EDITOR` or streaming logs. Pass `--body`/`--body-file`/`--title`, or bound `tg pipeline logs` with `timeout`.
- **`handle syntax didn't validate via regex`** — handles are domains (`alice.example.com`), never bare names.
- **Keyring error, or a hang mentioning D-Bus** — no session bus in that shell; see [Headless and remote hosts](#headless-and-remote-hosts).
- **`authenticated: false`, or writes landing on the wrong account** — `tg auth status` and `tg auth list` in the same shell; log in there, or pass `--account`. Edits to an issue or PR also need the account that authored it.
- **A write that reported success but reads back missing, or `attestations` errors on a later write** — the knot accepted the record and attestation is still pending: `tg auth attestations list`, then `tg auth attestations retry`. Do not repeat the original write.
- **A workflow stuck `blocked`, or `pipeline logs` exiting non-zero on a failed run** — blocked workflows wait for `tg pipeline approve <id>`; the non-zero exit is the pipeline's own failure, not a `tg` bug.
- **`tg repo delete` refuses to run** — it requires `--yes`, which is the prompt's job to ask for, not the agent's.

## Credits

Inspired by [alyraffauf/tg `SKILL.md`](https://github.com/alyraffauf/tg/blob/main/SKILL.md) (GPL-3.0) — its command recipes and published-commit round model carried over; rewritten in this package's house style with explicit repository targeting, record-key addressing, CID-guarded writes, non-interactive and output-projection habits, label handling, and approval before writes.
