Clarify token permissions in README

Target Wilkens Gitea defaults
Release 1.0.3
2026-05-15 14:54:31 +02:00 · 2026-05-15 04:42:55 +02:00 · 2026-05-15 04:28:50 +02:00 · 2026-05-15 04:23:44 +02:00
11 changed files with 115 additions and 33 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,7 +20,7 @@ This repository ships reusable baseline files for other repositories:

 ## Editing Rules

- Keep the kit universal. Do not hard-code private hosts, usernames, project names, or local paths in reusable templates.
+- 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.
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,23 @@

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

+<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.
@@ -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.

+<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.
@@ -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.

+<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:
@@ -52,10 +58,26 @@ Profile -> Settings -> SSH / GPG Keys -> Add Key
 Clone with SSH:

 ```bash
-git clone git@git.example.com:OWNER/REPOSITORY.git
+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
@@ -63,6 +85,8 @@ 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:
@@ -86,6 +110,8 @@ 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:
@@ -107,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` |

+<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:
@@ -124,7 +152,6 @@ PROJECT_STACK
 DOWNLOAD_URL
 CI_URL
 RELEASES_URL
-GITEA_SERVER_URL
 BUILD_COMMAND
 TEST_COMMAND
 LINT_COMMAND
@@ -139,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`.

+<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.
@@ -150,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.

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

@@ -169,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.

+<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.
@@ -202,7 +256,7 @@ Test repository API access:
 ```powershell
 $headers = @{ Authorization = "token $env:GITEA_TOKEN" }
 Invoke-RestMethod `
-  -Uri "GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
+  -Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
  -Headers $headers
 ```

@@ -210,10 +264,12 @@ Test issue access:

 ```powershell
 Invoke-RestMethod `
-  -Uri "GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
+  -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:
@@ -236,6 +292,8 @@ 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.
@@ -256,7 +314,9 @@ GITHUB_REPOSITORY
 REGISTRY_TOKEN
 ```

-When those values are unavailable, replace `GITEA_SERVER_URL`, `REPOSITORY_OWNER`, and related placeholders before use.
+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

@@ -272,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.

+<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:
@@ -286,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.

+<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:
--- a/docs/agent-handoff.md
+++ b/docs/agent-handoff.md
@@ -1,37 +1,40 @@
 # Agent Handoff

-Use this file for current repository follow-ups when tracker issues cannot be created.
+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 now includes guidance for creating focused tracker issues for actionable follow-up work.
+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.1`.
+- 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 | Blocked: Gitea API returned `invalid username, password or token` |
+| Issue creation test | Passed: created issue #1 |
+| Release API test | Passed: created release entry for `v1.0.2` |

 ## Open Questions

- Whether the local `GITEA_TOKEN` should be refreshed for future issue/release automation.
+- None at this time.

 ## Next Steps

- Create a focused tracker issue for adding a reusable follow-up issue template once issue API access is available.
+- Use issue #1 to track adding a reusable follow-up issue template.

 ## Follow-up Issues

 | Issue | Status |
 | --- | --- |
-| Add reusable issue template for agent follow-ups | Pending issue tracker access |
+| #1 Add reusable issue template for agent follow-ups | Open |

 ## Risks

- Issue automation cannot be fully validated until a valid token is available.
+- No known token blocker remains after the refreshed token test.
--- a/existing-project.md
+++ b/existing-project.md
@@ -181,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,
--- a/files/blueprint.json
+++ b/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": {
--- a/files/build-gitea.yml
+++ b/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"
--- a/files/release-dry-run-gitea.yml
+++ b/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
--- a/files/template-compliance-gitea.yml
+++ b/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
--- a/manifest.json
+++ b/manifest.json
@@ -1,6 +1,6 @@
 {
  "name": "codex-agent-repository-kit",
-  "version": "1.0.2",
+  "version": "1.0.5",
  "description": "Universal repository baseline for Codex-assisted projects.",
  "agentResponsibilities": [
    "Read manifest.json before copying files.",
@@ -195,7 +195,6 @@
    "DOWNLOAD_URL",
    "CI_URL",
    "RELEASES_URL",
-    "GITEA_SERVER_URL",
    "BUILD_COMMAND",
    "TEST_COMMAND",
    "LINT_COMMAND",
--- a/new-repository.md
+++ b/new-repository.md
@@ -95,7 +95,6 @@ PROJECT_STACK
 DOWNLOAD_URL
 CI_URL
 RELEASES_URL
-GITEA_SERVER_URL
 BUILD_COMMAND
 TEST_COMMAND
 LINT_COMMAND
@@ -197,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.
Author	SHA1	Message	Date
MrSphay	a4245a1563	Clarify token permissions in README	2026-05-15 14:54:31 +02:00
MrSphay	5ba44fcb03	Target Wilkens Gitea defaults	2026-05-15 04:42:55 +02:00
MrSphay	a14ed9a6d9	Release 1.0.3	2026-05-15 04:28:50 +02:00
MrSphay	719bc8cca5	Update handoff after Gitea token test	2026-05-15 04:23:44 +02:00