diff --git a/README.md b/README.md
index a07af64..947db4a 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,8 @@ 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.
+

## Placeholders
@@ -96,6 +98,28 @@ AUDIT_COMMAND
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`.
+
+
+
+## Agent Responsibilities
+
+When applying this kit, an agent should:
+
+- read `manifest.json` first,
+- choose `new-repository.md` or `existing-project.md`,
+- 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,
+- run `git diff --check` before finishing,
+- run the cheapest reliable verification command,
+- poll pushed Gitea workflow runs until success or a concrete blocker.
+

## Gitea API Token
diff --git a/agent-quickstart.md b/agent-quickstart.md
index 486d964..3db9b76 100644
--- a/agent-quickstart.md
+++ b/agent-quickstart.md
@@ -2,6 +2,21 @@
Use this file when you want Codex to apply the repository kit with minimal instructions.
+## Required Agent Behavior
+
+```text
+Read manifest.json first.
+Use its copyMap for file destinations.
+Use new-repository.md or existing-project.md as the task workflow.
+Check git status before editing.
+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.
+Run git diff --check before finishing.
+Run the cheapest reliable verification command, or explain why it could not run.
+```
+
## New Repository Prompt
```text
@@ -10,6 +25,7 @@ Use new-repository.md as the workflow.
Create the smallest useful baseline for this repository.
Detect the stack and replace placeholders with real project values.
Keep commands truthful: do not add commands that cannot run.
+Use manifest.json as the source of truth for copy targets.
Keep the README generator only if it adds value.
When using the README generator, keep the rainbow `{{ template:section-line }}` divider between major sections.
Do not create a release.
@@ -24,6 +40,7 @@ Use existing-project.md as the workflow.
Preserve existing code, README knowledge, CI behavior, and project style.
Add missing Codex agent context, security review, release checklist, and optional README generator files.
Keep commands truthful: do not add commands that cannot run.
+Use manifest.json as the source of truth for copy targets.
When using or adding the README generator, keep the rainbow `{{ template:section-line }}` divider between major sections.
Do not create a release.
Run the cheapest available verification before finishing.
@@ -36,6 +53,10 @@ Is this a fresh repo?
yes -> use new-repository.md
no -> use existing-project.md
+Did you read manifest.json?
+ yes -> use copyMap and placeholders from it
+ no -> read it before editing
+
Does the project already have README structure?
yes -> preserve it; only add blueprint files if useful
no -> add blueprint.md and blueprint.json with the rainbow section-line divider
@@ -52,6 +73,14 @@ Are commands unknown?
yes -> document PENDING in .codex/project.md
no -> wire commands into AGENTS.md and CI
+Did blueprint.md or blueprint.json change?
+ yes -> regenerate or manually update README.md and check the rendered structure
+ no -> leave README.md alone unless content changed
+
+Did release behavior, artifacts, or downloads change?
+ yes -> update docs/release-checklist.md and README downloads/artifacts
+ no -> do not invent release details
+
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
diff --git a/files/AGENTS.md b/files/AGENTS.md
index 11f652d..3584297 100644
--- a/files/AGENTS.md
+++ b/files/AGENTS.md
@@ -6,14 +6,19 @@ PROJECT_NAME: PROJECT_DESCRIPTION
## Repository Rules
+- Start by reading `manifest.json`, then the workflow file that matches the task: `new-repository.md` for fresh repos or `existing-project.md` for retrofit work.
+- Follow the `manifest.json` copy map for source and target paths. Do not invent alternate locations unless the target repository already has an equivalent convention.
- Prefer existing project patterns over new abstractions.
- Keep changes scoped to the user's request.
- Do not commit secrets, `.env` files, private keys, certificates, or tokens.
- Do not rewrite history or run destructive git commands unless explicitly requested.
- Do not create a release unless explicitly requested.
+- Check `git status --short` before editing and before finishing. Preserve unrelated user changes.
+- Replace all applicable placeholders. Remove non-applicable placeholder sections instead of leaving fake values.
- 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.
- 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.
## Commands
@@ -28,6 +33,8 @@ AUDIT_COMMAND
If a command is missing, inspect the project and document the closest safe alternative in `.codex/project.md`.
+Keep `.codex/project.md` and this `AGENTS.md` aligned when commands, artifact paths, or release rules change.
+
## Artifacts
Expected artifact output:
@@ -45,8 +52,17 @@ ARTIFACT_NAME
## Security Notes
- Review `docs/security-review.md` before release work.
+- Fill `docs/security-review.md` with actual checked commands and results when performing release-readiness work.
- Treat generated credentials and config files as sensitive.
- Keep external network calls documented.
- 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.
+- Ensure `.gitignore` covers local config, build outputs, logs, temporary files, and secret material for the detected stack.
+
+## Finish Checklist
+
+- `git diff --check` passes.
+- 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.
+- Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported.
diff --git a/manifest.json b/manifest.json
index 0636ec8..3c92a7f 100644
--- a/manifest.json
+++ b/manifest.json
@@ -2,6 +2,20 @@
"name": "codex-agent-repository-kit",
"version": "1.0.0",
"description": "Universal repository baseline for Codex-assisted projects.",
+ "agentResponsibilities": [
+ "Read manifest.json before copying files.",
+ "Use copyMap target paths unless the repository already has an equivalent convention.",
+ "Check git status before editing and before finishing.",
+ "Preserve unrelated user changes.",
+ "Replace 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.",
+ "Update docs/security-review.md during release-readiness work.",
+ "Update docs/release-checklist.md when release behavior changes.",
+ "Run git diff --check before finishing.",
+ "Run the cheapest reliable verification command or document why it could not run.",
+ "After pushing workflow-triggering commits, poll Gitea workflow runs until success or a concrete blocker."
+ ],
"readmeDivider": {
"templateName": "section-line",
"source": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png",