dms_tailscalectl/docs/agents/repo-instructions.md

# Repo Instructions — Forgejo

**Primary host**: https://forgejo.jtmorris.net (self-hosted Forgejo)  
**CLI**: `fj` (https://codeberg.org/forgejo-contrib/forgejo-cli)

## CLI Usage

Assume `fj` is installed and authenticated.

### Authentication
- `fj auth login` — interactive login (recommended first time).
- For self-hosted instances, use the `--host` flag when not inside a matching git repo:
  ```bash
  fj --host https://git.example.com auth login
  ```

`fj` will often auto-detect the instance from the current git remote.

### Common Operations

**Issues**
```bash
fj issue create --title "..." --body "..."
fj issue list
fj issue view <number>
fj issue comment <number> --body "..."
```

**Pull Requests / Changes**
```bash
fj pr create
fj pr list
fj pr merge <number>
```

For AGit-style pull requests (no fork required on many Forgejo instances), `fj` supports the normal flow.

**Repository**
```bash
fj repo create ...
fj release create ...
```

### Self-Hosted / Private Instances

When working with a private Forgejo instance that is not the default detected remote, always include `--host`:

```bash
fj --host https://forgejo.jtmorris.net issue create ...
```

Store the base URL in team documentation or your shell aliases if used frequently.

## Work Tracking Approach

- Use the Forgejo issue tracker for most planned work, bugs, and feature requests.
- For quick local exploration or solo spikes, you may use a `.scratch/` directory (see Local section below).
- Link commits and PRs to issues using conventional references (e.g. `Fixes #123`).

## Local / Air-Gapped / No-Remote Mode

Even on a Forgejo-hosted project, you can work fully locally:

- Use `git` normally.
- Track temporary work in `.scratch/<feature-slug>/` as markdown files.
- When ready, push and create issues/PRs via `fj`.

If this project is used in a completely local-only or air-gapped context, refer to the Local template or update this file.

## Notes for Agent Skills

- Prefer `fj` commands when interacting with issues or PRs on this project.
- For self-hosted instances, include `--host` in commands unless the git remote already points at the correct instance.
- `interrogate` and `to-prd` should read this file to know which CLI and host conventions to follow.
- When in doubt about the current instance, check `git remote -v` first.

## Troubleshooting `fj` Failures

If a `fj` command fails on this or any self-hosted Forgejo instance, do not retry with different flags. Diagnose first:

1. `git remote -v` — note the URL form. URL-style remotes with explicit non-default ports (`ssh://git@host:NNNN/...`) cause `fj` to use that same port for HTTPS API calls, producing TLS errors. SCP-style remotes (`git@host:owner/repo.git`) avoid this; route non-default SSH ports via `~/.ssh/config`.
2. `cat ~/.local/share/forgejo-cli/keys.json` — the host key string is what `fj` uses for both auth lookup and API URL. A `:NNNN` suffix here is the most common root cause.
3. `fj whoami` (in-repo) and `fj -H https://<host> whoami` — comparing these tells you whether auth is stored under the bare host or under host-with-port.

`fj`'s syntax also has sharp edges worth noting: `fj issue comment <N> [BODY]` takes the body as a positional argument (not `--body`); there is no `fj issue list` — use `fj issue search "" -s open|closed|all`; and cross-repo issue references use `owner/repo#N`. When in doubt, run `<subcommand> --help` — `fj` is `clap`-based and its help output is reliable.