Clarify token permissions in README

AGENTS.md

@@ -0,0 +1,60 @@
+# 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.
+
+## 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.
+- 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.

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to the Codex Agent Repository Kit are documented here.
 
+## 1.0.5 - 2026-05-15
+
+- Restored the rainbow section divider theme in the human-facing `README.md`.
+- Added separate minimal permission guidance for `REGISTRY_TOKEN` and `GITEA_TOKEN`.
+- Clarified where package-only and API-capable tokens should be used.
+
+## 1.0.4 - 2026-05-15
+
+- Set the documented Gitea host to `git.wilkensxl.de` instead of a generic URL placeholder.
+- Documented SSH clone URLs for port `2222` and optional SSH config.
+- Restored Gitea workflow and README badge defaults for the intended Gitea instance while keeping repository owner and repository name dynamic.
+
+## 1.0.3 - 2026-05-15
+
+- Updated repository handoff notes after verifying the refreshed local `GITEA_TOKEN`.
+- Confirmed live issue creation and Gitea release API access for this repository.
+
+## 1.0.2 - 2026-05-15
+
+- Split the repository documentation into a human-facing setup `README.md` and a repository-specific agent instruction file in `AGENTS.md`.
+- Expanded the human README with full new-repository setup guidance, SSH setup, Gitea token permissions, local token configuration, repository secrets, package publishing, and release checks.
+- Documented the recommended Gitea token permission matrix shown in the token UI.
+
+## 1.0.1 - 2026-05-15
+
+- Added agent guidance to create focused tracker issues for actionable follow-up work that is outside the current scope or independently parallelizable.
+- Added safeguards against creating vague, duplicate, or sensitive public issues.
+- Updated handoff guidance to use `docs/agent-handoff.md` when no issue tracker is available or the details are too sensitive for public issues.
+
 ## 1.0.0 - 2026-05-15
 
 - Added universal repository baseline templates for Codex-assisted projects.

README.md

@@ -1,66 +1,122 @@
 # Codex Agent Repository Kit
 
-Reusable baseline files for repositories that should be easy for Codex agents to inspect, modify, build, review, and release.
+Reusable setup kit for new or existing repositories that should be easy for Codex agents, humans, and CI workflows to maintain.
 
-The kit has three entry points:
+This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quickstart.md`, `new-repository.md`, and `existing-project.md`.
-
-- `agent-quickstart.md`: shortest prompts and decision tree for Codex agents.
-- `new-repository.md`: agent workflow for a fresh repository.
-- `existing-project.md`: agent workflow for upgrading an existing repository.
-
-The files are intentionally universal. They do not assume Electron, React, Node, or any single stack. Node examples are included only because many Codex projects use them.
 
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
-## README Section Divider
+## What This Kit Adds
 
-Generated README files should use the shared rainbow section divider between major sections.
+- `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.
 
-The divider is configured in `files/blueprint.json` as the `section-line` template:
+<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
-```md
+## Recommended New Repository Setup
-{{ template:section-line }}
+
+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>
+
+## SSH Setup
+
+Generate a key if you do not already have one:
+
+```powershell
+ssh-keygen -t ed25519 -C "you@example.com"
 ```
 
-When a project uses the README blueprint workflow, keep this divider in `blueprint.md` between major sections. Do not replace it with plain `---` unless the target platform cannot render inline images.
+Start the SSH agent and add the key:
 
-<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
+```powershell
+Start-Service ssh-agent
+ssh-add $env:USERPROFILE\.ssh\id_ed25519
+```
 
-## Agent Goal
+Show the public key:
 
-Give every repository the same predictable anchor points:
+```powershell
+Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
+```
+
+Add that public key in Gitea:
 
 ```text
-.
+Profile -> Settings -> SSH / GPG Keys -> Add Key
-|-- AGENTS.md
-|-- .codex/
-|   `-- project.md
-|-- .gitea/
-|   `-- workflows/
-|       |-- security-scan.yml
-|       |-- repo-cleanup.yml
-|       |-- dependency-check.yml
-|       |-- release-dry-run.yml
-|       |-- build.yml
-|       `-- template-compliance.yml
-|-- docs/
-|   |-- release-checklist.md
-|   `-- security-review.md
-|-- blueprint.md
-|-- blueprint.json
-|-- README.md
-|-- SECURITY.md
-|-- CHANGELOG.md
-`-- .gitignore
 ```
 
-Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `README.md`, `SECURITY.md`, and `CHANGELOG.md` may be enough. For an app or releasable tool, add the runner, release checklist, useful scheduled checks, and README blueprint workflow.
+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>
 
-## Copy Map
+## Applying The Kit With Codex
 
-| Template | Destination |
+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` |
@@ -70,30 +126,18 @@ Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `R
 | `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/release-checklist.md` | `docs/release-checklist.md` |
-| `files/security-review.md` | `docs/security-review.md` |
-| `files/blueprint.md` | `blueprint.md` |
-| `files/blueprint.json` | `blueprint.json` |
 | `files/SECURITY.md` | `SECURITY.md` |
 | `files/CHANGELOG.md` | `CHANGELOG.md` |
 | `files/CONTRIBUTING.md` | `CONTRIBUTING.md` |
-| `files/gitignore.template` | `.gitignore` |
+| `files/release-checklist.md` | `docs/release-checklist.md` |
+| `files/security-review.md` | `docs/security-review.md` |
 | `files/agent-handoff.md` | `docs/agent-handoff.md` |
-| `files/release-notes.md` | `docs/release-notes.md` |
-
-Start with `agent-quickstart.md` when using this kit through Codex.
-
-`manifest.json` contains the same copy map in a machine-readable format for agents.
-
-Agents should read `manifest.json` before copying files. It is the source of truth for target paths, required files, optional files, and placeholder names.
-
-`manifest.schema.json` documents the manifest shape. Stack-specific profile notes live in `profiles/`.
 
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
-## Placeholders
+## Required Placeholder Values
 
-Replace these after copying:
+Replace or remove all placeholders before considering a repository ready:
 
 ```text
 PROJECT_NAME
@@ -108,7 +152,6 @@ PROJECT_STACK
 DOWNLOAD_URL
 CI_URL
 RELEASES_URL
-GITEA_SERVER_URL
 BUILD_COMMAND
 TEST_COMMAND
 LINT_COMMAND
@@ -121,155 +164,205 @@ PROJECT_VERSION
 COMMIT_OR_VERSION
 ```
 
-If a placeholder does not apply, remove it instead of inventing fake information.
+If a value does not apply, remove that section instead of leaving fake data. If a value is genuinely unknown, mark it as `PENDING`.
-
-Agents must not leave unresolved placeholders in copied files unless the value is genuinely unknown and marked as `PENDING`.
-
-Agents must derive `REPOSITORY_OWNER` and `REPOSITORY_NAME` from the target repository remote URL or `GITHUB_REPOSITORY`. Do not reuse the owner from this repository kit's own remote.
 
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
-## Agent Responsibilities
+## Token Overview
 
-When applying this kit, an agent should:
+Use separate tokens for separate jobs.
 
-- read `manifest.json` first,
+| Token | Location | Purpose |
-- choose `new-repository.md` or `existing-project.md`,
+| --- | --- | --- |
-- read matching `profiles/*.md` guidance after detecting the stack,
+| `REGISTRY_TOKEN` | Repository secret | CI package publishing from Gitea Actions |
-- conserve context tokens by searching first, reading only relevant files, summarizing large outputs, and avoiding generated folders, dependency folders, build outputs, or full logs unless directly relevant,
+| `GITEA_TOKEN` | Local environment or repository secret | Gitea API access for issues, releases, workflow polling, and repository metadata |
-- at the start of each user-requested task, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean,
+
-- check `git status --short` before editing,
+Repository secrets are available to workflows. They are not visible to local Codex sessions. Local Codex API actions need a local environment variable.
-- preserve unrelated user changes,
-- use the manifest copy map for target paths,
-- replace applicable placeholders,
-- remove non-applicable placeholder sections,
-- keep `AGENTS.md` and `.codex/project.md` aligned,
-- update `README.md` whenever README blueprint files change,
-- update security and release docs when release behavior changes,
-- add or preserve scheduled security automation for releasable projects,
-- add or preserve scheduled repository cleanup checks for active projects,
-- add dependency, release dry-run, and template compliance checks when they fit the project,
-- update `docs/agent-handoff.md` when work is interrupted, risky, or multi-session,
-- run `git diff --check` before finishing,
-- run the cheapest reliable verification command,
-- poll pushed Gitea workflow runs until success or a concrete blocker.
 
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
-## Scheduled Security Automation
+## Gitea Token Permissions
 
-`files/security-scan-gitea.yml` provides an optional weekly Gitea workflow for releasable projects.
+For both tokens, choose this repository access level:
-
-It checks:
-
-- stack-specific dependency vulnerabilities,
-- suspicious code patterns,
-- committed secrets or local config files,
-- AI instruction-injection indicators.
-
-The workflow is intentionally conservative. If it fails, an agent should inspect the matches and decide whether they are real risks, documentation examples, or test fixtures. Do not silence the workflow without documenting why.
-
-<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
-
-## Scheduled Repository Cleanup
-
-`files/repo-cleanup-gitea.yml` provides an optional weekly Gitea workflow for active repositories.
-
-It reports:
-
-- generated files or dependency folders that were accidentally tracked,
-- large tracked files that may belong in release artifacts or package storage,
-- secret-prone local config files,
-- stale remote branch candidates.
-
-The workflow is intentionally non-destructive. It must not delete files, branches, packages, or releases. Agents should treat failures as maintenance reports, document intentional exceptions, and only remove repository data after explicit user approval.
-
-<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
-
-## Dependency Automation
-
-`files/dependency-check-gitea.yml` provides a weekly dependency health report.
-
-It detects common stacks and reports:
-
-- security audit results,
-- outdated Node, Python, Rust, and Go dependencies,
-- Docker base image references that should be reviewed manually.
-
-The workflow does not update lockfiles, create pull requests, or publish packages. Agents should use the report as a starting point for focused dependency update branches.
-
-<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
-
-## Release Dry Run
-
-`files/release-dry-run-gitea.yml` checks whether a project looks ready to release without creating a release.
-
-It checks release documents, unresolved placeholders, stack-specific build/test commands where they can be detected, and likely artifact directories. It must not create tags, releases, packages, or uploaded artifacts.
-
-<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
-
-## Template Compliance
-
-`files/template-compliance-gitea.yml` checks whether a repository still follows the Codex kit baseline.
-
-It verifies required agent context files, unresolved placeholders, README divider usage for generated READMEs, and recommended workflow presence. Treat failures as maintenance guidance, not as a reason to overwrite project-specific documentation blindly.
-
-<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
-
-## Gitea API Token
-
-When working with private Gitea repositories, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine.
-
-Use `GITEA_TOKEN` only for read-oriented Gitea API checks unless the user explicitly asks for a write action. Typical safe checks include repository metadata, workflow run status, and package-read visibility. Never print the token, commit it, or copy it into workflow files.
-
-Example status endpoint:
 
 ```text
-GET GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
+Repository and Organization Access: All (public, private, and limited)
-Authorization: token GITEA_TOKEN
 ```
 
-`REGISTRY_TOKEN` is still the intended secret name for CI package publishing inside `.gitea/workflows/build.yml`.
+Use separate tokens where possible. A package-only token should not be able to create issues or releases.
 
-<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
+### REGISTRY_TOKEN Permissions
 
-## Gitea Workflow Loop
+Use this token as a repository secret for package publishing from Gitea Actions:
-
-After pushing commits that trigger a Gitea workflow, Codex agents must keep checking the resulting workflow run before finishing. Poll the run until it reaches a terminal state. If it succeeds, report the successful run. If it fails or is cancelled, inspect the failing job/logs, fix the issue when it is in scope, commit, push, and repeat the check loop for the next run. A fixed failure is not a stopping point; the loop continues after the follow-up push until a workflow succeeds or a concrete out-of-scope blocker is reached. Do not stop after a single in-progress status when the user asked the agent to continue the loop.
-
-## Gitea Artifacts And Packages
-
-Actions artifacts and Gitea packages are separate storage paths.
-
-- `actions/upload-artifact` makes a workflow-run artifact. It does not create an entry in the Gitea Package Registry.
-- Use `actions/upload-artifact@v3` for Gitea/Act compatibility unless the target runner is known to support newer artifact actions.
-- To publish a downloadable package, upload it separately to the generic package registry with `curl --upload-file` and a CI secret such as `REGISTRY_TOKEN`.
-- Do not place raw build artifact names directly into package URLs. Build tools often emit names with spaces, parentheses, or platform-specific punctuation. Copy artifacts to temporary package files with URL-safe names before uploading.
-- Keep Codex kit files in source control when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless explicitly requested. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`.
-- For user-facing downloads, publish both an immutable version such as `PROJECT_VERSION-SHORT_SHA` and a stable `latest` package when the repository owner wants a moving download link.
-- After publishing, verify the actual package URL with an authenticated `HEAD` or lightweight download check. A green build does not always prove the package is visible where users expect it.
-
-<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
-
-## Agent Prompt For A New Repo
 
 ```text
-Use templates/codex-project/new-repository.md.
+package: Read and Write
-Create the Codex repository baseline for this project.
+repository: Read
-Adapt placeholders to this repository.
+user: Read
-Keep the existing stack choices minimal and do not add unnecessary frameworks.
+
-Do not create a release.
+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>
 
-## Agent Prompt For An Existing Repo
+## Setting Repository Secrets
+
+In Gitea:
 
 ```text
-Use templates/codex-project/existing-project.md.
+Repository -> Settings -> Actions -> Secrets -> Add Secret
-Retrofit the Codex repository baseline.
+```
-Preserve existing project style and README knowledge.
+
-Add only the files and commands that fit this repo.
+Add:
-Do not restructure application code unless required.
+
-Do not create a release.
+```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 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.
+
+<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.
 ```

agent-quickstart.md

@@ -20,6 +20,7 @@ Preserve unrelated user changes.
 Replace all applicable placeholders and remove non-applicable placeholder sections.
 Keep AGENTS.md and .codex/project.md aligned with real commands and artifact paths.
 Update README.md whenever blueprint.md or blueprint.json changes.
+Create tracker issues for real, actionable follow-ups that are outside the current scope or independently parallelizable; use docs/agent-handoff.md when no issue tracker is available.
 Exclude Codex kit metadata from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless explicitly requested.
 Run git diff --check before finishing.
 Run the cheapest reliable verification command, or explain why it could not run.
@@ -137,6 +138,14 @@ Is the work interrupted, risky, or multi-session?
   yes -> update docs/agent-handoff.md
   no  -> no handoff file is required
 
+Did you find real follow-up work outside the current scope?
+  yes -> create focused tracker issues for independent work; include impact, affected files, next steps, and verification
+  no  -> do not create placeholder issues
+
+Could the issue expose secrets, private data, or sensitive logs?
+  yes -> do not put sensitive details in a public issue; summarize safely and keep details private or in handoff notes
+  no  -> continue
+
 Is this a private Gitea repo with Actions?
   yes -> if GITEA_TOKEN is set locally, use it for read-only API checks of repository and workflow-run status
   no  -> use public web/API checks when available

docs/agent-handoff.md

@@ -0,0 +1,40 @@
+# Agent Handoff
+
+Use this file for current repository follow-ups when tracker issues cannot be created or when a compact session summary is useful.
+
+## Current State
+
+The kit includes guidance for creating focused tracker issues for actionable follow-up work. The local `GITEA_TOKEN` has been refreshed and verified.
+
+## Changes Made
+
+- Added issue creation guidance to the agent rules, quickstart, README, new/existing repository workflows, and manifest.
+- Added handoff guidance for cases where issue creation is unavailable or too sensitive.
+- Updated the kit version to `1.0.2`.
+- Created a live follow-up issue after token access was restored.
+- Created the Gitea release entry for `v1.0.2`.
+
+## Verification
+
+| Check | Result |
+| --- | --- |
+| Issue creation test | Passed: created issue #1 |
+| Release API test | Passed: created release entry for `v1.0.2` |
+
+## Open Questions
+
+- None at this time.
+
+## Next Steps
+
+- Use issue #1 to track adding a reusable follow-up issue template.
+
+## Follow-up Issues
+
+| Issue | Status |
+| --- | --- |
+| #1 Add reusable issue template for agent follow-ups | Open |
+
+## Risks
+
+- No known token blocker remains after the refreshed token test.

existing-project.md

@@ -146,6 +146,8 @@ For releasable projects, add `.gitea/workflows/release-dry-run.yml` unless equiv
 
 For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml` unless equivalent agent-context checks already exist. Preserve documented project-specific exceptions.
 
+When retrofit work reveals real follow-up work that is outside the current scope or can be worked on independently, create focused tracker issues so humans or other agents can pick them up later or in parallel. Each issue should include the observed problem, impact, affected files or commands, suggested next steps, and verification already performed. Do not create issues for work you can safely finish in the current task, and never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md`.
+
 ### 6. Security Review
 
 Fill `docs/security-review.md` with known facts.
@@ -179,7 +181,7 @@ Before final response:
 
 - run `git diff --check`,
 - run the smallest reliable verification command,
-- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories, use a locally set `GITEA_TOKEN` and `GITEA_SERVER_URL` for read-only API status checks when available,
+- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories on `https://git.wilkensxl.de`, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
 - if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
 - list files changed,
 - mention any skipped checks,

files/AGENTS.md

@@ -20,6 +20,8 @@ PROJECT_NAME: PROJECT_DESCRIPTION
 - Replace all applicable placeholders. Remove non-applicable placeholder sections instead of leaving fake values.
 - Derive `REPOSITORY_OWNER` and `REPOSITORY_NAME` from the target repository remote or `GITHUB_REPOSITORY`. Never reuse the owner from this template repository.
 - If `GITEA_TOKEN` is available locally, use it only for read-only Gitea API checks such as private repository metadata, package-read visibility, and Actions run status. Never print, commit, or store the token.
+- When you find a real, actionable follow-up that is outside the current scope or can be worked on independently, create a tracker issue so humans or other agents can pick it up later or in parallel. Do not create issues for work you can safely finish in the current task. If no issue tracker is available, update `docs/agent-handoff.md` instead.
+- Keep issues scoped and actionable: include the observed problem, impact, affected files or commands, suggested next steps, and any verification already performed. Never include secrets, tokens, private data, or sensitive logs in public issues.
 - After pushing commits that trigger a Gitea workflow, poll the workflow run until it succeeds. If it fails or is cancelled, inspect the failing job/logs, fix the issue when in scope, push again, and repeat the workflow check loop. Fixing and pushing a workflow failure is not a stopping point.
 - When the project uses `blueprint.md` and `blueprint.json` for README generation, keep the rainbow `{{ template:section-line }}` divider between major README sections. Do not replace it with plain `---` unless the target renderer cannot display inline images.
 - If README blueprint files are changed, regenerate or update `README.md` in the same change and verify the generated output renders reasonably.
@@ -81,5 +83,6 @@ ARTIFACT_NAME
 - The cheapest reliable verification command has been run, or the reason it could not be run is documented.
 - README, changelog, security review, and release checklist are updated when the change touches release behavior.
 - `docs/agent-handoff.md` is updated when work is interrupted, risky, or spans multiple sessions.
+- Independent follow-up work has tracker issues, or `docs/agent-handoff.md` explains why issues could not be created.
 - Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported.
 

files/CONTRIBUTING.md

@@ -7,6 +7,7 @@
 - Do not commit secrets, generated credentials, local `.env` files, or private keys.
 - Do not create releases unless explicitly requested.
 - Preserve unrelated user changes.
+- Create focused issues for real follow-up work that is outside the current change or can be worked on independently. Do not put secrets, tokens, private data, or sensitive logs in public issues.
 
 ## Before Committing
 
@@ -45,4 +46,3 @@ docs/release-checklist.md
 docs/security-review.md
 README.md
 ```
-

files/agent-handoff.md

@@ -2,6 +2,8 @@
 
 Use this file when a task spans multiple sessions, has unresolved follow-up work, or changes release behavior.
 
+Prefer focused tracker issues for independent follow-up work when an issue tracker is available. Use this handoff file when issues cannot be created, when the context is too sensitive for a public issue, or when a task needs a compact session summary.
+
 ## Current State
 
 ```text
@@ -29,7 +31,12 @@ PENDING
 
 - PENDING
 
+## Follow-up Issues
+
+| Issue | Status |
+| --- | --- |
+| PENDING | PENDING |
+
 ## Risks
 
 - PENDING
-

files/blueprint.json

@@ -6,12 +6,12 @@
     {
       "alt": "Build",
       "img": "https://img.shields.io/badge/build-Gitea%20Runner-2563eb",
-      "url": "CI_URL"
+      "url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/actions"
     },
     {
       "alt": "Version",
       "img": "https://img.shields.io/badge/version-0.1.0-111827",
-      "url": "RELEASES_URL"
+      "url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/releases"
     }
   ],
   "headingPrefix": {

files/build-gitea.yml

@@ -58,7 +58,7 @@ jobs:
           if [ -z "${repository_owner}" ] || [ "${repository_owner}" = "${GITHUB_REPOSITORY}" ]; then
             repository_owner="REPOSITORY_OWNER"
           fi
-          gitea_server="${GITHUB_SERVER_URL:-GITEA_SERVER_URL}"
+          gitea_server="${GITHUB_SERVER_URL:-https://git.wilkensxl.de}"
           gitea_server="${gitea_server%/}"
           package_dir="package-registry"
           latest_url="${gitea_server}/api/packages/${repository_owner}/generic/${package_name}/latest"

files/release-dry-run-gitea.yml

@@ -34,7 +34,7 @@ jobs:
           done
 
           placeholder_paths=(README.md AGENTS.md .codex docs .gitea)
-          placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|CI_URL|RELEASES_URL|GITEA_SERVER_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|COMMIT_OR_VERSION'
+          placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|CI_URL|RELEASES_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|COMMIT_OR_VERSION'
 
           for path in "${placeholder_paths[@]}"; do
             [ -e "$path" ] || continue

files/template-compliance-gitea.yml

@@ -54,7 +54,7 @@ jobs:
         run: |
           found=0
           paths=(AGENTS.md README.md SECURITY.md CHANGELOG.md .codex docs .gitea blueprint.md blueprint.json)
-          pattern='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'
+          pattern='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'
 
           for path in "${paths[@]}"; do
             [ -e "$path" ] || continue

manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-repository-kit",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "description": "Universal repository baseline for Codex-assisted projects.",
   "agentResponsibilities": [
     "Read manifest.json before copying files.",
@@ -14,6 +14,7 @@
     "Update README.md whenever blueprint.md or blueprint.json changes.",
     "Update docs/security-review.md during release-readiness work.",
     "Update docs/release-checklist.md when release behavior changes.",
+    "Create focused tracker issues for real follow-up work that is outside the current scope or independently parallelizable, and use docs/agent-handoff.md when no issue tracker is available.",
     "Add or preserve non-destructive scheduled repository cleanup checks for active projects.",
     "Add or preserve dependency, release dry-run, and template compliance checks when they fit the project.",
     "Run git diff --check before finishing.",
@@ -194,7 +195,6 @@
     "DOWNLOAD_URL",
     "CI_URL",
     "RELEASES_URL",
-    "GITEA_SERVER_URL",
     "BUILD_COMMAND",
     "TEST_COMMAND",
     "LINT_COMMAND",

new-repository.md

@@ -95,7 +95,6 @@ PROJECT_STACK
 DOWNLOAD_URL
 CI_URL
 RELEASES_URL
-GITEA_SERVER_URL
 BUILD_COMMAND
 TEST_COMMAND
 LINT_COMMAND
@@ -188,6 +187,8 @@ For releasable projects, add `.gitea/workflows/release-dry-run.yml`. It should v
 
 For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml`. It should verify agent context and template hygiene without overwriting project-specific conventions.
 
+When the setup reveals real follow-up work that is outside the current scope or can be worked on independently, create focused tracker issues so humans or other agents can pick them up later or in parallel. Each issue should include the observed problem, impact, affected files or commands, suggested next steps, and verification already performed. Do not create issues for work you can safely finish in the current task, and never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md`.
+
 ### 7. Finish
 
 Before final response:
@@ -195,7 +196,7 @@ Before final response:
 - run formatting or validation if available,
 - run the cheapest reliable verification command,
 - check `git diff --check`,
-- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories, use a locally set `GITEA_TOKEN` and `GITEA_SERVER_URL` for read-only API status checks when available,
+- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories on `https://git.wilkensxl.de`, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
 - if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
 - summarize changed files,
 - do not create a release unless explicitly requested.