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.

README Section Divider

Generated README files should use the shared rainbow section divider between major sections.

The divider is configured in files/blueprint.json as the section-line template:

{{ template:section-line }}

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.

Agent Goal

Give every repository the same predictable anchor points:

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

Copy Map

Template	Destination
`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/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/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/.

Placeholders

Replace these after copying:

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 placeholder does not apply, remove it instead of inventing fake information.

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.

Agent Responsibilities

When applying this kit, an agent should:

read manifest.json first,
choose new-repository.md or existing-project.md,
read matching profiles/*.md guidance after detecting the stack,
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,
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,
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.

Scheduled Security Automation

files/security-scan-gitea.yml provides an optional weekly Gitea workflow for releasable projects.

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.

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.

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.

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.

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.

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:

GET GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
Authorization: token GITEA_TOKEN

REGISTRY_TOKEN is still the intended secret name for CI package publishing inside .gitea/workflows/build.yml.

Gitea Workflow Loop

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.

Agent Prompt For A New Repo

Use templates/codex-project/new-repository.md.
Create the Codex repository baseline for this project.
Adapt placeholders to this repository.
Keep the existing stack choices minimal and do not add unnecessary frameworks.
Do not create a release.

Agent Prompt For An Existing Repo

Use templates/codex-project/existing-project.md.
Retrofit the Codex repository baseline.
Preserve existing project style and README knowledge.
Add only the files and commands that fit this repo.
Do not restructure application code unless required.
Do not create a release.