# Agent Instructions For This Repository

This file is for Codex agents working on the Codex Agent Repository Kit itself. The public `README.md` is for humans and should stay focused on setup and usage.

## Start Of Task

- Check `git status --short`.
- If the working tree is clean, run `git pull --ff-only` before editing.
- If local changes exist, preserve them and do not overwrite user work.
- Conserve context tokens: use `rg`, targeted file reads, and short summaries instead of loading unrelated files or long logs.

## Runner Policy

- The only supported build runners are the Gitea global runners `global-runner-1`, `global-runner-2`, and `global-runner-3`.
- Use only these Linux runner labels in workflow templates and generated setup instructions: `ubuntu-latest`, `ubuntu-24.04`, and `ubuntu-22.04`.
- Never run project builds, tests, audits, package jobs, installers, dependency bootstraps, or release jobs on the local machine. Use the Gitea Ubuntu runners so the user's machine stays clean.
- Do not introduce Windows or macOS runners. If a project appears to need Windows-specific tooling, document or implement an open-source Linux-compatible workaround that runs on the Ubuntu runners.
- Lightweight local checks are allowed when they do not install dependencies or create build artifacts, for example JSON parsing, manifest path checks, `rg`, `git diff --check`, and API status checks.

## Repository Purpose

This repository ships reusable baseline files for other repositories:

- `files/` contains templates copied into target repositories.
- `agent-quickstart.md`, `new-repository.md`, and `existing-project.md` are agent workflows.
- `manifest.json` is the source of truth for copy targets and placeholders.
- `profiles/` contains stack-specific guidance.

## Editing Rules

- Keep repository owner, repository name, project names, and local paths dynamic. This kit intentionally targets `https://git.wilkensxl.de` and SSH port `2222`, so keep that host/port consistent in user-facing setup and Gitea workflow defaults.
- Keep workflow examples and generated CI defaults on the supported Ubuntu runner labels only.
- If a new placeholder is introduced, update `manifest.json`, the README placeholder list, and placeholder scans in workflow templates.
- Keep `README.md` user-facing. Put agent operating rules in this file or the workflow docs.
- Keep `files/AGENTS.md` generic; it is copied into target repositories and must not describe this repository specifically.
- Do not include secrets, tokens, private data, or sensitive logs in docs, issues, commits, or release notes.

## Follow-up Work

- Create focused tracker issues for real follow-up work that is outside the current scope or can be done independently.
- Do not create issues for work that can be safely completed in the current task.
- If issue creation is unavailable, update `docs/agent-handoff.md` with the blocker and next steps.

## Verification

Before committing:

```powershell
Get-Content manifest.json | ConvertFrom-Json | Out-Null
Get-Content manifest.schema.json | ConvertFrom-Json | Out-Null
Get-Content files\blueprint.json | ConvertFrom-Json | Out-Null
git diff --check
```

Also verify:

- every `manifest.json` copyMap source exists,
- every profile path exists,
- reusable files contain no private instance defaults such as a specific username or private host,
- `README.md` documents every placeholder listed in `manifest.json`.

## Release

- Bump `manifest.json` version.
- Update `CHANGELOG.md`.
- Commit changes.
- Create an annotated tag such as `v1.0.2`.
- Push `main` and tags.
- Create or update the Gitea release when a valid API token is available.