Document Codeberg development flow

.codex/skills/codeberg-development-flow/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: codeberg-development-flow
+description: Use when working in this repository on development flow, remotes, Codeberg or Forgejo CLI operations, commit signing, mirroring to GitHub, npm trusted publishing, release validation, or publishing @peezy.tech/codex-flows.
+---
+
+# Codeberg Development Flow
+
+## Overview
+
+Use Codeberg as the primary development forge and GitHub only as the npm trusted-publishing mirror.
+
+## Core Rules
+
+- Treat `origin` as Codeberg: `git@codeberg.org:peezy-tech/codex-flows.git`.
+- Treat `github` as the GitHub mirror: `https://github.com/peezy-tech/codex-flows.git`.
+- Push normal development to Codeberg first.
+- Push to GitHub only when the release workflow must publish to npm.
+- Do not add npm tokens to the repo or GitHub secrets. GitHub publishes through trusted publishing.
+- Use package name `@peezy.tech/codex-flows`, not `@peezy-tech/codex-flows`.
+
+## Setup Checks
+
+When asked to set up or verify the repo, check:
+
+```bash
+git remote -v
+ssh -T git@codeberg.org
+fj auth list
+gpg --list-secret-keys --keyid-format=long
+```
+
+Expected local key files:
+
+```text
+~/.ssh/id_ed25519_codeberg.pub
+~/.config/codeberg-keys/matamune-codeberg-gpg.asc
+```
+
+## Release Workflow
+
+Before release, run:
+
+```bash
+bun run --filter @peezy.tech/codex-flows release:check
+bun run check:types
+bun run test
+git diff --check
+```
+
+Then:
+
+1. Bump `packages/codex-client/package.json`.
+2. Commit.
+3. Push to Codeberg: `git push origin main`.
+4. Push to GitHub mirror: `git push github main`.
+5. Run GitHub workflow `.github/workflows/publish-codex-flows.yml` with `confirm_package=@peezy.tech/codex-flows`.
+6. Verify `npm dist-tag ls @peezy.tech/codex-flows`.
+
+## References
+
+- Read `references/development-flow.md` for exact setup and command details.

.codex/skills/codeberg-development-flow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codeberg Development Flow"
+  short_description: "Codeberg-first development and releases."
+  default_prompt: "Use the Codeberg-first development flow for remotes, commits, Forgejo CLI, mirrors, and npm releases."

.codex/skills/codeberg-development-flow/references/development-flow.md

@@ -0,0 +1,71 @@
+# Codeberg Development Flow Reference
+
+## Remotes
+
+```bash
+git remote -v
+# origin  git@codeberg.org:peezy-tech/codex-flows.git
+# github  https://github.com/peezy-tech/codex-flows.git
+```
+
+Use Codeberg for day-to-day pushes:
+
+```bash
+git push origin main
+```
+
+Use GitHub only to run npm trusted publishing:
+
+```bash
+git push github main
+gh workflow run publish-codex-flows.yml --repo peezy-tech/codex-flows --ref main -f confirm_package='@peezy.tech/codex-flows'
+```
+
+## Keys
+
+SSH public key:
+
+```text
+~/.ssh/id_ed25519_codeberg.pub
+```
+
+GPG public key:
+
+```text
+~/.config/codeberg-keys/matamune-codeberg-gpg.asc
+```
+
+Git signing is expected:
+
+```bash
+git config --global commit.gpgsign true
+git config --global user.signingkey E3B0D5FB2E5CF11FAFB2EA113BB8E7D3B968A324
+```
+
+## Forgejo CLI
+
+`forgejo-cli` is installed as `fj`.
+
+After a Codeberg application token exists:
+
+```bash
+fj auth add-key <codeberg-username> <token>
+fj auth use-ssh true
+fj auth list
+```
+
+## Package Release Gate
+
+```bash
+bun run --filter @peezy.tech/codex-flows release:check
+bun run check:types
+bun run test
+git diff --check
+```
+
+Verify npm after GitHub Actions publishing:
+
+```bash
+npm dist-tag ls @peezy.tech/codex-flows
+npm view @peezy.tech/codex-flows version repository --json
+```

README.md

@@ -61,11 +61,16 @@ bun run test
 
 `bun run test` currently runs the `@peezy.tech/codex-flows` transport tests.
 
+## Development Flow
+
+Development happens on Codeberg. GitHub is kept as a release mirror for npm trusted publishing.
+
+See [docs/development-flow.md](docs/development-flow.md) for remotes, key setup, Forgejo CLI setup, and the release procedure.
+
 ## Publishing
 
-The public home for this monorepo is `peezy-tech/codex-flows`. When seeding that
+The public development home for this monorepo is `codeberg.org/peezy-tech/codex-flows`.
-repo, copy this working tree without `.git`, initialize a fresh git history, and
+The GitHub mirror at `peezy-tech/codex-flows` exists for npm trusted publishing.
-push it to the new public GitHub repo.
 
 `@peezy.tech/codex-flows` is published from `packages/codex-client`.
 

docs/development-flow.md

@@ -0,0 +1,85 @@
+# Development Flow
+
+This monorepo is developed on Codeberg and mirrored to GitHub only for npm trusted publishing.
+
+## Remotes
+
+Use Codeberg as the normal development remote:
+
+```bash
+git remote -v
+# origin  git@codeberg.org:peezy-tech/codex-flows.git
+# github  https://github.com/peezy-tech/codex-flows.git
+```
+
+Push ordinary development to Codeberg:
+
+```bash
+git push origin main
+```
+
+Push to GitHub only when a release needs the trusted publishing workflow:
+
+```bash
+git push github main
+```
+
+## Machine Keys
+
+This machine uses a dedicated Codeberg SSH key:
+
+```text
+~/.ssh/id_ed25519_codeberg.pub
+```
+
+The public GPG key for commit verification is exported here:
+
+```text
+~/.config/codeberg-keys/matamune-codeberg-gpg.asc
+```
+
+Upload both public keys to the Codeberg account before pushing over SSH or expecting verified commits.
+
+## Forgejo CLI
+
+`forgejo-cli` is installed as `fj`.
+
+Authenticate with Codeberg after creating an application token:
+
+```bash
+fj auth add-key <codeberg-username> <token>
+fj auth use-ssh true
+fj auth list
+```
+
+If browser login is available, this may also work:
+
+```bash
+fj auth login
+fj auth use-ssh true
+```
+
+## Releases
+
+Release package: `@peezy.tech/codex-flows`
+
+Before publishing:
+
+```bash
+bun run --filter @peezy.tech/codex-flows release:check
+bun run check:types
+bun run test
+git diff --check
+```
+
+To publish through GitHub trusted publishing:
+
+1. Bump `packages/codex-client/package.json`.
+2. Commit and push to Codeberg.
+3. Push the same commit to GitHub.
+4. Run `.github/workflows/publish-codex-flows.yml` on GitHub with confirmation input `@peezy.tech/codex-flows`.
+5. Verify npm:
+
+```bash
+npm dist-tag ls @peezy.tech/codex-flows
+```