diff --git a/CHANGELOG.md b/CHANGELOG.md
index 432cb24..a408b99 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,12 @@
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.
diff --git a/README.md b/README.md
index 77829e3..85b7cab 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,8 @@ Reusable setup kit for new or existing repositories that should be easy for Code
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.
@@ -12,6 +14,8 @@ This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quicks
- 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.
@@ -22,6 +26,8 @@ This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quicks
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:
@@ -79,6 +85,8 @@ git remote -v
git status --short
```
+
+
## Applying The Kit With Codex
For a new repository, start Codex in the target repository and use:
@@ -102,6 +110,8 @@ 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:
@@ -123,6 +133,8 @@ Use `manifest.json` as the source of truth. Common targets:
| `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:
@@ -154,6 +166,8 @@ 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.
@@ -165,15 +179,44 @@ Use separate tokens for separate jobs.
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:
+For both tokens, choose this repository access level:
```text
Repository and Organization Access: All (public, private, and limited)
+```
-issue: Read and Write
+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
@@ -184,16 +227,12 @@ 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.
+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.
+
+
## Setting Local Tokens
Set a local token for Codex or shell-based API work.
@@ -229,6 +268,8 @@ Invoke-RestMethod `
-Headers $headers
```
+
+
## Setting Repository Secrets
In Gitea:
@@ -251,6 +292,8 @@ 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.
@@ -273,6 +316,8 @@ 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`.
+
+
## 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.
@@ -287,6 +332,8 @@ An issue should include:
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:
@@ -301,6 +348,8 @@ Before the first release of a target project:
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:
diff --git a/manifest.json b/manifest.json
index 31ae029..707b30f 100644
--- a/manifest.json
+++ b/manifest.json
@@ -1,6 +1,6 @@
{
"name": "codex-agent-repository-kit",
- "version": "1.0.4",
+ "version": "1.0.5",
"description": "Universal repository baseline for Codex-assisted projects.",
"agentResponsibilities": [
"Read manifest.json before copying files.",