# 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.