Exclude kit metadata from release artifacts

README.md

@@ -234,6 +234,7 @@ Actions artifacts and Gitea packages are separate storage paths.
 - 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-quickstart.md

@@ -17,6 +17,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.
+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.
 ```
@@ -117,6 +118,10 @@ Do package upload URLs include raw build filenames?
   yes -> copy artifacts to URL-safe filenames first, then upload those names
   no  -> continue
 
+Do user-facing release artifacts include Codex kit metadata such as AGENTS.md, .codex/, blueprint files, template workflows, or agent handoff notes?
+  yes -> exclude those files unless the user explicitly asked to ship repository-maintenance files
+  no  -> continue
+
 Is the work interrupted, risky, or multi-session?
   yes -> update docs/agent-handoff.md
   no  -> no handoff file is required

existing-project.md

@@ -118,6 +118,8 @@ If CI already exists:
 
 Treat workflow-run artifacts and Package Registry packages as different outputs. If the project expects user-downloadable packages, confirm there is an explicit package publish step in addition to any `actions/upload-artifact` step. When adding or repairing package publishing, copy build outputs to URL-safe filenames before uploading and verify the final package URL after the workflow succeeds.
 
+Keep Codex kit files tracked in the source repository when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly wants repository-maintenance files shipped. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`.
+
 If CI does not exist:
 
 - add `.gitea/workflows/build.yml` from the template,

files/AGENTS.md

@@ -27,6 +27,7 @@ PROJECT_NAME: PROJECT_DESCRIPTION
 - Repository cleanup automation must be non-destructive. Do not delete branches, packages, releases, or tracked files without explicit user approval.
 - Dependency, compliance, and release dry-run automation must report findings only. Do not auto-update dependencies, auto-open PRs, create tags, publish packages, or create releases without explicit user approval.
 - Gitea Actions artifacts are not Gitea Package Registry packages. If the user expects a package/download entry, add an explicit registry publish step and verify the package URL after the workflow succeeds.
+- Keep Codex kit files in source control when they are useful for agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly asks to ship repository-maintenance files.
 
 ## Commands
 
@@ -69,6 +70,7 @@ ARTIFACT_NAME
 - Prefer local processing for user data.
 - Keep CI publishing secrets in repository or organization secrets, not in tracked files. `REGISTRY_TOKEN` is the default package publishing secret name for the Gitea workflow template.
 - Use URL-safe package filenames when publishing to a registry. Do not put raw artifact names with spaces or punctuation directly into upload URLs.
+- Do not include Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, or agent handoff notes in downloadable release artifacts unless explicitly requested.
 - Ensure `.gitignore` covers local config, build outputs, logs, temporary files, and secret material for the detected stack.
 
 ## Finish Checklist

files/project.md

@@ -66,7 +66,8 @@ Before a release:
 2. verify CI is green,
 3. verify download links,
 4. update README and changelog,
-5. create a tag,
-6. create the release.
+5. verify release artifacts exclude Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflows, and agent handoff notes unless the user explicitly wants those shipped,
+6. create a tag,
+7. create the release.
 
 Do not create releases unless the user explicitly asks for a release.

files/release-checklist.md

@@ -23,6 +23,7 @@
 ## Artifacts
 
 - [ ] Artifacts are uploaded.
+- [ ] User-facing artifacts exclude Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflows, and agent handoff notes unless explicitly requested.
 - [ ] Download links work.
 - [ ] Package registry links work if used.
 - [ ] Installer/portable/archive naming is clear.
@@ -33,4 +34,3 @@
 - [ ] Release notes written.
 - [ ] Release published.
 - [ ] Post-release download smoke test completed.
-

new-repository.md

@@ -163,6 +163,8 @@ upload artifacts
 
 Only publish artifacts to a package registry when the artifact names and credentials are known. `actions/upload-artifact` creates a workflow-run artifact, not a Gitea Package Registry package. If users need a package/download entry, add a separate generic package upload step with `REGISTRY_TOKEN`, copy artifacts to URL-safe filenames before upload, and verify the final package URL after the workflow succeeds.
 
+Keep Codex kit files tracked in the source repository when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly wants repository-maintenance files shipped. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`.
+
 For releasable projects, config tools, apps, or repositories that process user data, secrets, or deployment files, also add `.gitea/workflows/security-scan.yml`. Keep the scheduled workflow conservative and review false positives before silencing checks.
 
 For active repositories, also add `.gitea/workflows/repo-cleanup.yml`. It should report cleanup candidates only; it must not delete files, branches, packages, or releases automatically.