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:

  fj --host https://git.example.com auth login
  

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

Common Operations

Issues

fj issue create --title "..." --body "..."
fj issue list
fj issue view <number>
fj issue comment <number> --body "..."

Pull Requests / Changes

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

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:

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.