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

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

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

## 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 git@git.example.com:OWNER/REPOSITORY.git
cd REPOSITORY
```

Verify the remote:

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

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

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

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

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

## Gitea Token Permissions

For the token permission screen shown in Gitea, choose:

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

issue: Read and Write
package: Read and Write
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,
- uploading package registry files,
- reading repository metadata,
- polling workflow runs where the Gitea API allows it.

Use a dedicated bot or automation user when possible.

## 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 "GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
  -Headers $headers
```

Test issue access:

```powershell
Invoke-RestMethod `
  -Uri "GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
  -Headers $headers
```

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

## 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 `GITEA_SERVER_URL`, `REPOSITORY_OWNER`, and related placeholders before use.

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

## 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 that exist.
7. Run `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.

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