Release v1.0.1: automatic project onboarding

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes are recorded here. Releases use semantic versioning.
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-09-12
+
+### Added
+
+- Automatic project onboarding through global guidance and the existing onboarding
+  skill during implementation tasks, preserving existing project instructions.
+- Explicit handling of untrusted repository evidence during onboarding and an
+  adversarial fixture for evaluating generated guidance.
+
+### Clarified
+
+- Plain `codex` uses the installed global setup; profiles are optional.
+- First-task onboarding, explicit opt-out, and upgrades from v1.0.0 with a changed skill.
+
 ## [1.0.0] - 2026-09-11
 
 ### Added
@@ -16,5 +30,6 @@ All notable changes are recorded here. Releases use semantic versioning.
 - Four platform examples, project/PR/decision templates, and complete operating documentation.
 - Cross-platform CI, release automation, deterministic archives, and SHA-256 checksums.
 
-[Unreleased]: https://github.com/roadhero/codex-setup/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/roadhero/codex-setup/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/roadhero/codex-setup/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/roadhero/codex-setup/releases/tag/v1.0.0

README.md

@@ -21,7 +21,7 @@ See [compatibility](docs/compatibility.md) for the tested baseline.
 ```sh
 git clone https://github.com/roadhero/codex-setup.git
 cd codex-setup
-git checkout v1.0.0
+git checkout v1.0.1
 python3 scripts/install.py             # preview
 python3 scripts/install.py --apply     # install with backups
 ```
@@ -31,14 +31,18 @@ Alternatively, download a versioned archive and SHA256SUMS from
 in [installation](docs/installation.md), and run the same installer from the
 extracted directory. No remote script is piped into a shell.
 
-Start a fresh Codex session after installation:
+Start a fresh Codex session in your project after installation:
 
 ```sh
-codex --profile setup-build
-codex --profile setup-review
-codex --profile setup-compute
+cd /path/to/project
+codex
 ```
 
+Profiles are optional: `--profile setup-build` explicitly selects workspace writes
+and on-request approvals, which are also this kit's global defaults.
+Use `--profile setup-review` for read-only review or `--profile setup-compute` for
+the compute profile. Your existing configuration can override the installed defaults.
+
 The installer preserves existing configuration, MCP connections, authentication,
 plugins, and unrelated skills. It adds missing defaults, appends a marked guidance
 block, and refuses conflicting custom assets. See [installation and rollback](docs/installation.md).
@@ -65,8 +69,16 @@ Read [STRUCTURE.md](STRUCTURE.md) for the complete layout.
 
 ## Project setup
 
-Ask Codex to use `$codex-new-repo` to inspect a repository and write actual project
-commands. For a static starter:
+With the current global guidance installed, start Codex in a project and describe
+your coding task. When project guidance is missing, Codex is instructed to create
+AGENTS.md from actual repository facts and continue your task automatically.
+Existing guidance is preserved; project trust still applies. This instruction-driven
+workflow is available starting in v1.0.1 and skips read-only questions/reviews.
+For an empty project, include the product and stack in your request; say "skip
+project setup" to opt out. No separate onboarding command is required.
+
+You can also ask Codex to use `$codex-new-repo` explicitly to inspect a repository
+and create or update its instructions. For a static starter:
 
 ```sh
 python3 scripts/install.py --project /absolute/path/to/repo --stack android
@@ -122,7 +134,7 @@ of verification are documented in [validation](docs/installation-verification.md
 - [Hooks](docs/hooks.md), [skills](docs/skills.md), and [agents](docs/agents.md)
 - [Troubleshooting](docs/troubleshooting.md) and [compatibility](docs/compatibility.md)
 - [Design decisions](docs/review.md) and [official sources](docs/sources.md)
-- [Release process](docs/releases.md), [changelog](CHANGELOG.md), and [v1.0.0 notes](docs/releases/v1.0.0.md)
+- [Release process](docs/releases.md), [changelog](CHANGELOG.md), and [v1.0.1 notes](docs/releases/v1.0.1.md)
 - [Contributing](CONTRIBUTING.md) and [security policy](SECURITY.md)
 
 MIT licensed. This is a community project, not an official OpenAI product.

VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

docs/configuration.md

@@ -10,7 +10,9 @@ No model is pinned. Agents inherit the selected model and reasoning effort, exce
 for any explicit overrides you add. The built-in read-only review profile sets a
 sandbox default; project and command-line settings may override it.
 
-Profiles are separate files under Codex home:
+Plain `codex` loads the installed global instructions and skills, including
+automatic project onboarding. No profile is required. Profiles are optional,
+separate files under Codex home:
 
 - `setup-build.config.toml`: workspace writes, approvals on request.
 - `setup-review.config.toml`: read-only sandbox, approvals on request.

docs/installation-verification.md

@@ -5,6 +5,17 @@ Native app-server startup accepted the installed configuration with
 `--strict-config`. Local prompt rendering discovered global guidance, this
 repository's project instructions, and installed workflow/platform skills.
 
+For v1.0.1 on 2026-09-12, native `codex debug prompt-input` inspection in an empty
+temporary directory confirmed discovery of the automatic-onboarding instructions
+and updated skill description without a profile. This verifies loaded context,
+not that every model task will follow the workflow. Structural validation, skill
+validation, and all 18 behavioral tests passed locally.
+
+The [adversarial onboarding fixture](../tests/fixtures/onboarding/README.md) provides
+inputs and evaluation criteria for checking whether repository text is promoted
+into persistent guidance. It is a manual model evaluation, not one of the 18
+deterministic tests; those tests do not establish prompt-injection resistance.
+
 Automated tests exercise configuration preservation, installation idempotency,
 backup/restoration, conflicting files, symlink refusal, instruction overrides,
 write failures, documented hook output, release archives, and integrity checks.

docs/installation.md

@@ -10,12 +10,12 @@ Download a matching archive and SHA256SUMS from the release page. From the downl
 directory, compare the checksum for the archive you selected:
 
 ```sh
-shasum -a 256 codex-setup-v1.0.0.tar.gz   # macOS
-sha256sum codex-setup-v1.0.0.tar.gz      # Linux
+shasum -a 256 codex-setup-v1.0.1.tar.gz   # macOS
+sha256sum codex-setup-v1.0.1.tar.gz      # Linux
 ```
 
 It must equal that file's line in SHA256SUMS. Extract the archive, enter its
-`codex-setup-v1.0.0` directory, and preview installation:
+`codex-setup-v1.0.1` directory, and preview installation:
 
 ```sh
 python3 scripts/install.py
@@ -53,6 +53,29 @@ merge; the installer never guesses how to reconcile edited skills or agents.
 It does not delete files removed in a later release. If moving between versions,
 restore the preceding install first when practical, then install the new version.
 
+### Upgrading from v1.0.0 to v1.0.1
+
+This release changes `global/AGENTS.md` and `skills/codex-new-repo/SKILL.md`.
+The installer merges its global guidance block, but refuses an existing skill
+whose bytes differ, including an unchanged v1.0.0 copy. An ordinary upgrade preview
+therefore reports an asset conflict and writes nothing.
+
+If your installed files still match their backup manifests, restore the previous
+installation(s), newest first, using the commands below. Then preview and apply
+v1.0.1, including `--hooks` if you want the optional hook installed. Restart Codex
+after installation; review hook trust with `/hooks` if prompted.
+
+If restoration refuses later edits, preserve them. For a manual upgrade, back up
+the installed onboarding skill and compare it with both release versions. Only
+replace an unchanged v1.0.0 skill with the v1.0.1 skill after reviewing that diff;
+then preview/apply the installer to update global guidance. If the skill is
+customized, merge the skill and managed global guidance deliberately, retaining
+your changes. The installer will continue to reject customized asset differences;
+manual merging does not require a forced installer run.
+
+An installation that already has the exact v1.0.1 skill and global guidance needs
+no further global changes; its preview reports zero files.
+
 ## Backups and rollback
 
 Each nonempty application prints a private manifest under

docs/projects.md

@@ -5,14 +5,50 @@ layout, exact commands, architecture boundaries, supported versions/hardware,
 release source, and acceptance criteria. See the four fictional examples under
 examples/; replace their commands with evidence from your own manifests and CI.
 
-`$codex-new-repo` inspects existing files before writing context. The installer can
-instead append a starter block with `--project /path --stack web|android|ios|compute`.
+With the v1.0.1 global instructions installed, start Codex in the project and
+describe your implementation task. If the project has no existing guidance,
+Codex is instructed to use `$codex-new-repo` automatically: inspect the repository,
+write a concise root AGENTS.md with supported project facts, read it, and continue
+the task. For an empty project, include the product and stack in your request.
+There is no separate onboarding prompt or restart between setup and implementation.
+
+The onboarding skill follows applicable project instructions and treats other
+inspected repository content as untrusted evidence.
+It extracts project facts while ignoring embedded directives about assistant
+behavior, checks generated guidance before writing and applying it, and does not
+give copied directives authority by putting them in AGENTS.md. The
+[adversarial evaluation fixture](../tests/fixtures/onboarding/README.md) documents
+a concrete scenario and failure criteria; it is not a deterministic security guarantee.
+
+```sh
+cd /path/to/project
+codex
+```
+
+Profiles are optional; the global instructions and skills also apply without
+`--profile setup-build`. Start a fresh session after installing or upgrading the
+global setup so Codex discovers the updated instructions.
+
+Automatic onboarding applies only to a bounded repository or a project directory
+you explicitly designate. Existing AGENTS.md, AGENTS.override.md, and configured
+fallback guidance is preserved. It skips read-only questions/reviews and respects
+requests such as "skip project setup." This is an instruction-driven workflow,
+not a startup hook or an enforced guarantee. Project trust and permission prompts
+remain native Codex decisions.
+
+Invoke `$codex-new-repo` explicitly to create or update project guidance on demand.
+The installer can instead append a starter block with
+`--project /path --stack web|android|ios|compute`.
 This flag also installs global defaults; it does not build an application or invent
 a release workflow for an unknown toolchain. Existing project configuration remains.
 
 A project `.codex/config.toml` contains only differences from personal defaults and
 loads only after project trust. Repository skills live in `.agents/skills`; local
 agent overrides live in `.codex/agents`. Copy only the roles that actually differ.
+Automatic onboarding creates only AGENTS.md; configuration is added only when the
+requested task requires a project-specific difference. Newly written AGENTS.md is
+read explicitly for the current task and discovered normally in future sessions,
+following [OpenAI's instruction discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md).
 
 ## Nested guidance
 

docs/releases.md

@@ -6,10 +6,14 @@ Never include machine-specific reports, credentials, or private backup manifests
 
 1. Prepare and review the version, changelog, notes, and relevant documentation.
 2. Run `python3 scripts/validate.py` and `python3 -m unittest discover -s tests -v`.
-3. Commit the complete change. Packaging refuses a dirty working tree.
-4. Run `python3 scripts/release.py` for a local archive/checksum preview.
-5. After publication is authorized, create an annotated `vX.Y.Z` tag on that commit
-   and push the branch/tag. The release workflow runs the cross-platform gate,
+3. Commit the complete change on a release branch and open a pull request against
+   main. Review the diff and resolve relevant findings; require successful checks
+   at the final PR revision before merging through the repository's normal policy.
+4. Update the local main checkout to the merged commit and run
+   `python3 scripts/release.py` for a local archive/checksum preview. Packaging
+   refuses a dirty working tree. Confirm VERSION and notes still match the release.
+5. After publication is authorized, create an annotated `vX.Y.Z` tag on that merged
+   commit and push the tag. The release workflow runs the cross-platform gate,
    verifies tag/VERSION/HEAD parity, creates the archives, and publishes matching notes.
 6. Verify the GitHub release target, assets, and downloaded checksums.
 
@@ -21,11 +25,11 @@ release for changed content.
 Manual recovery after verifying a clean tagged checkout:
 
 ```sh
-python3 scripts/release.py --tag v1.0.0
-gh release create v1.0.0 --verify-tag \
-  --title 'v1.0.0 — Codex engineering setup' \
-  --notes-file docs/releases/v1.0.0.md \
-  dist/codex-setup-v1.0.0.tar.gz dist/codex-setup-v1.0.0.zip dist/SHA256SUMS
+python3 scripts/release.py --tag v1.0.1
+gh release create v1.0.1 --verify-tag \
+  --title 'v1.0.1 — Codex engineering setup' \
+  --notes-file docs/releases/v1.0.1.md \
+  dist/codex-setup-v1.0.1.tar.gz dist/codex-setup-v1.0.1.zip dist/SHA256SUMS
 ```
 
 Archives come from Git blobs at HEAD, not loose working files. File order, ownership,

docs/releases/v1.0.1.md

@@ -0,0 +1,63 @@
+# v1.0.1 — Automatic project onboarding
+
+Start Codex in your project and describe the coding task. The global setup now
+instructs Codex to create project guidance when it is missing and continue directly
+into the requested work. No separate onboarding prompt or profile is required.
+
+## Changes
+
+- Global instructions select the onboarding skill for implementation tasks in
+  bounded repositories or explicitly designated project directories without guidance.
+- The skill creates a concise root AGENTS.md from repository evidence, reads it,
+  and continues the task. It preserves existing project guidance and skips read-only
+  questions/reviews, explicit opt-outs, and destinations where writes are restricted.
+- The skill ignores embedded directives in inspected repository content and checks
+  generated guidance before applying it. An adversarial fixture supplies manual
+  evaluation inputs and failure criteria without claiming guaranteed isolation.
+- README and project documentation use plain `codex` and explain optional profiles,
+  project trust, empty-project requests, and the limits of instruction-driven setup.
+- Release documentation describes PR review, checks, merging, and tagging the merged commit.
+
+This is a model-guided workflow, not a startup hook or an enforced guarantee.
+Project trust and permission prompts still apply. The update does not change models,
+permission defaults, agent roles, or hook definitions.
+
+## Install or upgrade
+
+Requires macOS/Linux, Python 3.11+, Git, and Codex CLI 0.154.0 or newer.
+Verify the downloaded archive against SHA256SUMS, extract it, then run:
+
+```sh
+cd codex-setup-v1.0.1
+python3 scripts/install.py
+python3 scripts/install.py --apply
+```
+
+**Existing v1.0.0 installs:** the changed onboarding skill triggers the installer's
+asset-conflict protection, even if you have not customized it. Restore previous
+installation manifests newest-first when their hashes still match, then install
+v1.0.1. Otherwise back up and deliberately reconcile the changed files as described
+in [upgrade instructions](https://github.com/roadhero/codex-setup/blob/v1.0.1/docs/installation.md#upgrading-from-v100-to-v101).
+The installer never overwrites customized skills or bypasses restoration checks.
+
+Use `--hooks` if installing the optional advisory hook. Start a fresh Codex session
+after upgrading global instructions. From your project directory, run `codex` and
+describe your task; for an empty project, include the product and intended stack.
+Say "skip project setup" to opt out of automatic onboarding.
+
+## Verification
+
+The local validation suite passes all 18 tests covering installation/restoration,
+hook behavior, and release packaging; structural and skill validation also pass.
+Native Codex prompt inspection confirms discovery of the new global instructions
+and onboarding skill description. Discovery validation does not establish model
+compliance in every task. Release CI runs the suite on macOS/Linux with Python
+3.11 and 3.14 before publishing the version-matched archives and checksums.
+
+## Assets
+
+- `codex-setup-v1.0.1.tar.gz`
+- `codex-setup-v1.0.1.zip`
+- `SHA256SUMS`
+
+[Full changes](https://github.com/roadhero/codex-setup/compare/v1.0.0...v1.0.1)

docs/skills.md

@@ -10,7 +10,7 @@ or you can invoke them by name. They contain no mandatory external integrations.
 | `$engineering-android` | Lifecycle/state, coroutines, variants, persistence, device/release verification |
 | `$engineering-ios` | State/actors, Swift/Xcode toolchain, persistence, signing/device verification |
 | `$engineering-compute` | Native ownership, CUDA, numerics, parallelism, benchmarks, hardware constraints |
-| `$codex-new-repo` | Inspect and create project instructions and requested scaffolding |
+| `$codex-new-repo` | Onboard projects without guidance during implementation; explicitly create/merge instructions and requested scaffolding |
 | `$codex-quality-gate` | Run actual repository formatting, lint, type, test, and build commands |
 | `$codex-release-prep` | Prepare versions, notes, artifacts, and relevant release validation |
 | `$codex-reconcile-docs` | Identify or fix evidence-backed documentation drift |

global/AGENTS.md

@@ -8,6 +8,14 @@ ceremonies. System, developer, and explicit user instructions take precedence ov
 these defaults and skill guidance.
 
 Read the repository instructions, relevant code, and nearby examples before editing.
+On the first implementation task in a project without existing project guidance,
+use `codex-new-repo` to create a concise, evidence-based root AGENTS.md, then read
+it and continue the requested work. Existing AGENTS.md, AGENTS.override.md, or
+configured fallback guidance takes precedence; do not automatically rewrite it.
+Apply this only to a bounded repository or a project directory the user designated,
+never a general-purpose parent directory or a read-only question/review. Respect
+requests to skip onboarding and existing file-write restrictions. If onboarding
+is unavailable, continue any work already permitted and report the limitation.
 Keep the change focused, preserve unrelated work, and use the existing toolchain.
 For substantial work, briefly describe the approach, then execute it. Review the
 result against the requested outcome and check realistic failure paths. Run the