codex-agent-repository-kit/README.md

# Codex Agent Repository Kit

Reusable setup kit for new or existing repositories that should be easy for Codex agents, humans, and CI workflows to maintain.

This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quickstart.md`, `new-repository.md`, and `existing-project.md`.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## What This Kit Adds

- `AGENTS.md` and `.codex/project.md` for agent context.
- Optional Gitea workflows for build, security scan, cleanup, dependency check, release dry run, and template compliance.
- Release, security, handoff, changelog, and contribution templates.
- README blueprint templates for projects that want generated README output.
- Stack notes for Node, Electron, Python, Docker, and static-site projects.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Recommended New Repository Setup

1. Create the repository in Gitea.
2. Clone it locally with SSH.
3. Copy this kit into the repository with Codex or manually from `files/`.
4. Replace placeholders with real project values.
5. Add repository secrets for CI publishing.
6. Commit and push the baseline.
7. Let the Gitea workflows report any missing setup.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Runner Policy

This kit assumes these are the only available build runners:

| Runner | Type | Allowed labels |
| --- | --- | --- |
| `global-runner-1` | Gitea global runner | `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` |
| `global-runner-2` | Gitea global runner | `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` |
| `global-runner-3` | Gitea global runner | `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` |

Agents must run project builds, tests, audits, package jobs, installers, dependency setup, and releases on those Gitea Ubuntu runners. They must not run those heavy project commands on the user's local machine.

Do not add Windows or macOS runners. If a project appears to need platform-specific tooling, use an open-source Linux-compatible workaround that runs on the Ubuntu runners.

Lightweight local checks are still acceptable when they do not install dependencies or create build artifacts, for example `git status --short`, `rg`, JSON validation, manifest path checks, API status checks, and `git diff --check`.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## SSH Setup

Generate a key if you do not already have one:

```powershell
ssh-keygen -t ed25519 -C "you@example.com"
```

Start the SSH agent and add the key:

```powershell
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519
```

Show the public key:

```powershell
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
```

Add that public key in Gitea:

```text
Profile -> Settings -> SSH / GPG Keys -> Add Key
```

Clone with SSH:

```bash
git clone ssh://git@git.wilkensxl.de:2222/OWNER/REPOSITORY.git
cd REPOSITORY
```

Optional SSH config:

```text
Host git.wilkensxl.de
  HostName git.wilkensxl.de
  User git
  Port 2222
  IdentityFile ~/.ssh/id_ed25519
```

With that config, this shorter clone URL also works:

```bash
git clone git@git.wilkensxl.de:OWNER/REPOSITORY.git
```

Verify the remote:

```bash
git remote -v
git status --short
```

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Applying The Kit With Codex

For a new repository, start Codex in the target repository and use:

```text
Use the Codex Agent Repository Kit.
Read manifest.json, then use new-repository.md.
Create the smallest useful baseline for this repository.
Replace placeholders with real values from this repository.
Keep commands truthful and do not invent scripts that cannot run.
Do not create a release.
```

For an existing repository:

```text
Use the Codex Agent Repository Kit.
Read manifest.json, then use existing-project.md.
Retrofit the baseline without replacing existing project structure or README knowledge.
Preserve current CI behavior and project style.
Do not create a release.
```

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Manual Copy Map

Use `manifest.json` as the source of truth. Common targets:

| Template | Target |
| --- | --- |
| `files/AGENTS.md` | `AGENTS.md` |
| `files/project.md` | `.codex/project.md` |
| `files/build-gitea.yml` | `.gitea/workflows/build.yml` |
| `files/security-scan-gitea.yml` | `.gitea/workflows/security-scan.yml` |
| `files/repo-cleanup-gitea.yml` | `.gitea/workflows/repo-cleanup.yml` |
| `files/dependency-check-gitea.yml` | `.gitea/workflows/dependency-check.yml` |
| `files/release-dry-run-gitea.yml` | `.gitea/workflows/release-dry-run.yml` |
| `files/template-compliance-gitea.yml` | `.gitea/workflows/template-compliance.yml` |
| `files/SECURITY.md` | `SECURITY.md` |
| `files/CHANGELOG.md` | `CHANGELOG.md` |
| `files/CONTRIBUTING.md` | `CONTRIBUTING.md` |
| `files/release-checklist.md` | `docs/release-checklist.md` |
| `files/security-review.md` | `docs/security-review.md` |
| `files/agent-handoff.md` | `docs/agent-handoff.md` |

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Required Placeholder Values

Replace or remove all placeholders before considering a repository ready:

```text
PROJECT_NAME
PROJECT_DESCRIPTION
REPOSITORY_OWNER
REPOSITORY_NAME
PACKAGE_NAME
ARTIFACT_NAME
ARTIFACT_OUTPUT_DIRECTORY
AUTHOR_NAME
PROJECT_STACK
DOWNLOAD_URL
CI_URL
RELEASES_URL
BUILD_COMMAND
TEST_COMMAND
LINT_COMMAND
AUDIT_COMMAND
README_COMMAND
INSTALL_COMMAND
DEV_COMMAND
PACKAGE_MANAGER
PROJECT_VERSION
COMMIT_OR_VERSION
```

If a value does not apply, remove that section instead of leaving fake data. If a value is genuinely unknown, mark it as `PENDING`.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Token Overview

Use separate tokens for separate jobs.

| Token | Location | Purpose |
| --- | --- | --- |
| `REGISTRY_TOKEN` | Repository secret | CI package publishing from Gitea Actions |
| `GITEA_TOKEN` | Local environment or repository secret | Gitea API access for issues, releases, workflow polling, and repository metadata |

Repository secrets are available to workflows. They are not visible to local Codex sessions. Local Codex API actions need a local environment variable.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Gitea Token Permissions

For both tokens, choose this repository access level:

```text
Repository and Organization Access: All (public, private, and limited)
```

Use separate tokens where possible. A package-only token should not be able to create issues or releases.

### REGISTRY_TOKEN Permissions

Use this token as a repository secret for package publishing from Gitea Actions:

```text
package: Read and Write
repository: Read
user: Read

activitypub: No Access
admin: No Access
issue: No Access
misc: No Access
notification: No Access
organization: No Access
```

These permissions cover generic package uploads while still allowing the workflow to read repository metadata.

### GITEA_TOKEN Permissions

Use this token locally on the PC for Codex API actions, or as a repository secret only when workflows need issue, release, or workflow API access:

```text
issue: Read and Write
package: Read
repository: Read and Write
user: Read

activitypub: No Access
admin: No Access
misc: No Access
notification: No Access
organization: No Access
```

These permissions cover creating and reading issues, creating and reading releases, reading repository metadata, and polling workflow runs where the Gitea API allows it. `package: Read` is enough for API checks; use `package: Read and Write` only if this same token must publish packages.

Use a dedicated bot or automation user when possible.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Setting Local Tokens

Set a local token for Codex or shell-based API work.

Current PowerShell session:

```powershell
$env:GITEA_TOKEN = "paste-token-here"
```

Persist for the current Windows user:

```powershell
setx GITEA_TOKEN "paste-token-here"
```

Open a new terminal after `setx`.

Test repository API access:

```powershell
$headers = @{ Authorization = "token $env:GITEA_TOKEN" }
Invoke-RestMethod `
  -Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
  -Headers $headers
```

Test issue access:

```powershell
Invoke-RestMethod `
  -Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
  -Headers $headers
```

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Setting Repository Secrets

In Gitea:

```text
Repository -> Settings -> Actions -> Secrets -> Add Secret
```

Add:

```text
REGISTRY_TOKEN
```

Use a token with package write access. If you want workflows to create releases or issues too, add a separate secret:

```text
GITEA_TOKEN
```

Keep package publishing and release or issue automation separate when possible. It makes permission reviews easier.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Package Publishing

`files/build-gitea.yml` can publish generic packages when `REGISTRY_TOKEN` is available.

The workflow:

- builds project artifacts,
- copies them to URL-safe filenames,
- uploads immutable versioned packages,
- updates a stable `latest` package path.

The workflow uses:

```text
GITHUB_SERVER_URL
GITHUB_REPOSITORY_OWNER
GITHUB_REPOSITORY
REGISTRY_TOKEN
```

When those values are unavailable, replace `REPOSITORY_OWNER`, `REPOSITORY_NAME`, and related placeholders before use. The default Gitea server is `https://git.wilkensxl.de`.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Agent Follow-up Issues

Agents should create focused tracker issues for real follow-up work that is outside the current scope or can be handled independently by humans or other agents.

An issue should include:

- observed problem,
- impact,
- affected files or commands,
- suggested next steps,
- verification already performed.

Agents must not create issues for vague reminders, duplicate work, or tasks they can safely finish immediately. Sensitive details belong in private channels or `docs/agent-handoff.md`, not public issues.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Release Checklist For A New Repo

Before the first release of a target project:

1. Ensure `AGENTS.md` and `.codex/project.md` match the real project.
2. Replace all placeholders or mark genuinely unknown values as `PENDING`.
3. Configure `REGISTRY_TOKEN` if packages are published.
4. Configure `GITEA_TOKEN` only if workflows need issue or release API access.
5. Verify SSH push access.
6. Run lint, test, build, and audit commands on Gitea Ubuntu runners only.
7. Run lightweight local validation such as `git diff --check`.
8. Confirm release artifacts do not include Codex kit metadata unless explicitly wanted.
9. Push and poll workflows to success or document the blocker.

<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>

## Updating The Kit In A Project

When this kit changes, update target repositories conservatively:

```bash
git status --short
git pull --ff-only
```

Then ask Codex:

```text
Update this repository's Codex Agent Repository Kit files from the latest kit.
Preserve project-specific README content, commands, release rules, and workflow customizations.
Do not overwrite unrelated changes.
```