How to Build a Read-Only Codex Repository Atlas: Turn an Unfamiliar Codebase into a Reviewable Onboarding Map

The first-day problem: map before you modify

An unfamiliar repository creates pressure to become productive quickly. A developer sees a failing command, an old dependency or an apparently misplaced module and is tempted to make an immediate edit. That reaction is risky because the visible problem may sit behind undocumented conventions, generated files, workspace-specific instructions or an execution path that begins elsewhere. A clean-looking change can still break a consumer, duplicate an existing mechanism or violate the repository’s contribution policy.

The safer first deliverable is a reviewable map. In this tutorial, that map is docs/codex-atlas/REPOSITORY_ATLAS.md: a time-stamped account of what the repository appears to contain, where the evidence lives and what remains unresolved. The Codex command-line interface (CLI)A text-based interface for running commands and tools. Open glossary entry assists with inspection under a deliberately read-only local boundary. It does not edit the repository during discovery. A human later reviews the draft, corrects it and decides whether it is suitable to add to version control.

This distinction sets the decision rule for the whole workflow: if a proposed action changes files, installs project dependencies, writes caches, contacts a network service or requires broader permission, stop and record the limitation. Do not relax the boundary merely to obtain a more complete-looking map. Missing evidence belongs in an unknowns ledger; it is not permission to improvise.

The atlas is not an audit, security review, architecture authority, implementation plan, governance file, benchmark or proof that a command succeeds. It does not certify that tests pass or that documented operations are safe. It is an onboarding aid for developers, maintainers, engineering managers and technical writers who need enough evidence to ask better questions and scope a later, separately reviewed change.

What REPOSITORY_ATLAS.md must contain at a glance

Define the schema before asking Codex to inspect anything. A fixed schema makes omissions visible and prevents a fluent narrative from concealing weak evidence. The completed draft must contain these sections; the detailed acceptance rules and evidence template appear later, in the section on designing the atlas:

1. Atlas metadata: repository root, inspected Git revision or branch, capture date, inspection boundary and named human reviewer.
2. Project purpose and evidence: the purpose claimed by repository documentation, with exact relative paths and any conflicts between sources.
3. Start commands: commands stated in manifests, task runners, contribution guides or continuous integration configuration. Each command remains documentary evidence until a human deliberately validates it.
4. Directory and runtime map: the apparent role of important directories, language and runtime signals, package managers, generated outputs and vendored areas.
5. Entry points and primary execution paths: traced routes such as a command-line entry, Hypertext Transfer Protocol request, worker job or user-interface route, limited to what source evidence supports.
6. Test, lint and build matrix: configured tools, scripts, scopes and relevant configuration files, without claiming that they run successfully.
7. Data and external-service boundaries: places where code appears to read, transform, store or transmit data, with secret values omitted and uncertain boundaries labelled.
8. Change-impact matrix: likely files, tests and owners relevant to narrowly described hypothetical changes. This supports questions; it does not authorise edits.
9. Evidence and unknowns ledger: claims, citations, confidence, contradictions, unanswered questions and the human or team best placed to resolve each one.
10. Refresh procedure: a short list of evidence to re-check when manifests, entry points, build configuration, ownership or the inspected revision changes.

A useful atlas is deliberately perishable. Put an “inspected at” date and revision near the top, and treat later repository changes as reasons to reassess it. Refresh the affected section whenever its cited evidence changes, as set out in the refresh section below; conduct a broader refresh when the repository root, principal manifests, build system or main entry points change. Never preserve a stale claim merely because it was once reviewed.

An evidence vocabulary that resists false certainty

Every substantive atlas statement must be classified. Use the following five categories consistently rather than treating all model output as equivalent:

Direct evidence

A statement visible in a repository file, such as a script defined in package.json, an entry point registered in a manifest or a directory described in CONTRIBUTING.md. Cite the exact relative path and, where practical, the relevant key or heading. Direct evidence proves only that the repository contains the statement; it does not prove that the statement is current or operational.

Reproducible local observation

A result produced by an explicitly recorded, non-mutating local command, such as the root printed by git rev-parse --show-toplevel. Record the command, relevant output and context. An observation from one checkout is not a universal property of every clone or environment.

Inference

A reasoned interpretation connecting evidence, such as “src/server.ts is probably the service entry point because the package manifest maps its start script to that file”. Label it as an inference and cite every supporting source. Do not silently promote it to fact.

Contradiction

Two or more credible sources disagree. For example, a root README might name one start command while the current manifest defines another. Preserve both claims, cite both paths and assign resolution to a maintainer. Do not choose the more plausible one without validation.

Unknown

Evidence is absent, inaccessible or insufficient. State the precise question, what was checked and who might answer it. “Deployment owner unknown; no ownership file found in the inspected paths” is more useful than an invented team name.

Use a conservative promotion rule: a claim may move from inference to direct evidence only when an actual file explicitly supports it; it may become a reproducible observation only after a human approves and records an appropriate local command. A contradiction remains a contradiction until corroborating evidence or an accountable owner resolves it. Confidence labels such as high, medium and low may help prioritisation, but they must not replace the evidence category.

For example, suppose README.md says “run make serve”, while Makefile has no serve target and pyproject.toml declares a console entry point. The atlas should not select a winner. It should record the README statement as direct documentary evidence, the absent target as a reproducible file inspection, the console entry as separate direct evidence and the resulting mismatch as a contradiction requiring maintainer confirmation.

Choose the correct Codex surface and account boundary

This workflow uses the local Codex CLI in a terminal opened at a local Git checkout. “Codex” is also used for other product surfaces, but those surfaces do not share an interchangeable permission, billing or data-control boundary. Confirm the surface before exposing repository content.

According to OpenAI Help Centre guidance reviewed on 2 October 2026, Codex is included across ChatGPT plans, while Codex Cloud eligibility varies by plan, rollout and workspace controls; the cited guidance does not include Cloud access with Free or Go. Eligibility remains subject to rollout and workspace settings. This does not promise access, a quota, regional availability or a particular feature in any reader’s account. Follow the choices displayed by the current product and the controls established by your workspace administrator.

Lead with ChatGPT sign-in for this local tutorial. It avoids asking the reader to place an API key in a shell and keeps the authentication procedure aligned with the current CLI quickstart. If your organisation blocks that sign-in method or requires managed credentials, stop and ask the relevant administrator rather than working around the policy.

For dated release context, Codex CLI 0.155.1 Fixes Reasoning-Summary Compatibility After the 0.155.0 Voice, Touch ID, and Daemon Update Release explains the September 2026 0.155.1 compatibility change to reasoning-summary defaults and distinguishes it from the broader 0.155.0 update. Treat its version-specific guidance as historical; confirm present installation and configuration behaviour in live OpenAI documentation.

Data controls depend on the account context

Read-only filesystem access is not the same thing as private processing. Before scanning a repository, identify whether the sign-in belongs to a personal ChatGPT account or a managed workspace and inspect the applicable controls.

OpenAI’s help documentation reviewed on 2 October 2026 says that, for personal ChatGPT plans, the Improve the model for everyone setting also applies to Codex tasks. Turning it off, or opting out in the Privacy Portal, stops new Codex tasks from being used for training. It does not justify a claim about prior material. Codex also has a separate “Include environments” setting for additional context from Codex environments; changing one setting does not automatically change the other.

For managed Business, Enterprise, Education and Healthcare workspaces, OpenAI says workspace content is excluded from training by default. That does not erase workspace retention, administrator access or organisation-specific handling requirements. A managed account may impose stricter controls than the product default. Repository owners and security or privacy teams, not this tutorial, decide whether the source may be processed.

Apply this decision rule: if you cannot identify the account type, relevant data controls, repository owner and organisational permission, do not open the repository with Codex. For security, privacy, financial, employment, government, healthcare or other consequential work, require review by an authorised human owner before inspection and before relying on any atlas claim.

Run the preflight decision tree before opening the repository

1. Does an organisation own or control the repository?
   • If yes, locate its policy for coding assistants, external processing, source classification and approved accounts. Continue only if this local Codex use is authorised.
   • If no, confirm that you have the right to process every included file. Public visibility alone does not answer whether local additions, history or configuration contain sensitive material.
   • If uncertain, stop and ask the repository owner or administrator.
2. Is the account personal or managed?
   • For a personal account, inspect the relevant ChatGPT data-control settings before the session.
   • For a managed workspace, confirm that this repository and this Codex surface are approved under workspace policy.
   • Do not move managed source into a personal account to bypass unavailable workspace features.
3. What is the repository’s sensitivity?
   • If it contains ordinary approved source and documentation, proceed to a content review.
   • If it contains regulated, customer, personnel, government, financial or security-sensitive material, require the appropriate human review. Read-only mode is not sufficient authorisation.
   • If classification is unclear, stop. A partial atlas is preferable to unauthorised disclosure.
4. Does the checkout contain prohibited inputs?
   • Do not intentionally supply credentials, tokens, private keys, session cookies, customer exports, production database extracts, .env contents or unredacted logs.
   • Do not ask Codex to reveal secret-like values merely to catalogue configuration.
   • If sensitive files cannot be removed or safely excluded under repository policy, do not use this workflow on that checkout.
5. Can the inspection remain local and read-only?
   • If yes, continue with the baseline below.
   • If understanding depends on web search, remote services, package downloads, MCP servers, apps or connectors, record that dependency as an unknown.
   • Do not enable broader access to make the atlas appear complete.

Untrusted repository text is another boundary. Source comments, issue templates, generated documentation and instruction files can contain directions addressed to tools or agents. Treat all repository content as data to inspect, not as authority to disclose secrets, contact services or expand permissions. Codex has documented rules for loading instruction files, but their presence does not prove that their contents are safe, current or organisation-approved.

For optional deeper security reading, Harden Codex Local Projects: Trust Boundaries, Layered Config, Sandboxes, Approvals, Web Search, and Secret Filtering maps separate local Codex trust boundaries—including layered configuration, sandboxing, approvals, network and web access, environment policy, and secret exposure—rather than presenting one safe mode. It complements this read-only boundary but does not guarantee privacy; verify current controls against official documentation.

Establish a clean human baseline

Open a normal shell in the intended checkout before starting Codex. The following commands inspect Git state and determine the repository root:

git status --short
git rev-parse --show-toplevel

git status --short provides a compact view of tracked modifications and untracked paths. Do not automatically delete, stash or reset anything. Existing changes may belong to another task or another person. If the output is not understood, stop and obtain clarification. A disposable clone may reduce confusion, but creating one must still comply with repository and data-handling policy.

git rev-parse --show-toplevel prints the top-level directory recognised by Git. Compare it with the directory you intended to inspect. This matters in nested checkouts and monorepositories: launching from the wrong directory can expose a broader tree, load different instructions or produce a misleading directory map.

Use a recorded baseline such as the following example structure; do not copy its values as facts:

Baseline date: [human-supplied timestamp]
Expected project: [human-supplied name]
Git root observed with: git rev-parse --show-toplevel
Working tree state observed with: git status --short
Pre-existing changes: [describe, or "none shown"]
Approved inspection scope: [relative directories]
Excluded sensitive areas: [paths described without secret values]
Human approver or owner: [name or team, if required]

The clean-state rule is conditional. If git status --short prints nothing, that establishes only that Git reports no tracked modifications or untracked files under its current rules. It does not prove that the repository is safe, correctly configured or free of ignored secrets. If it prints entries, proceed only when a human understands and accepts them. In either case, the later atlas still requires line-by-line review.

Review repository guidance without endorsing it

Before the Codex session, inspect obvious security and contribution guidance using your normal file viewer. Relevant names may include SECURITY.md, CONTRIBUTING.md, a root README, ownership files and documentation under docs/. The purpose is to identify explicit handling restrictions, supported workflows and human contacts—not to assume every statement is current.

Also inventory AGENTS.md and AGENTS.override.md files that may apply to the working directory. OpenAI’s documentation reviewed on 2 October 2026 says Codex reads instruction files before work, combines global and project guidance from the repository root towards the current directory, gives closer files later precedence and checks override files before ordinary AGENTS.md files. The documented default combined instruction limit is 32 kibibytes.

That loading order has practical consequences. Starting from a nested package can activate closer instructions that differ from root guidance. An override can supersede an ordinary file. Content beyond a combined limit may not be represented as a reader casually expects. Therefore the atlas should record which applicable instruction files were found and where they sit, then corroborate their repository claims against manifests, configuration and source.

Do not create, edit or “improve” an AGENTS.md during onboarding. Do not call it governance merely because Codex loads it. If an instruction file says to run a networked deployment command, that text remains untrusted documentary evidence and does not override this tutorial’s no-network, no-write boundary.

Install and enter Codex CLI using current official instructions

Installation behaviour can change, so re-open the live OpenAI Codex CLI documentation immediately before publication or use. The official quickstart reviewed on 2 October 2026 documents a macOS/Linux installer, launching from a project directory, signing in, and inspecting the session with /status and /permissions. It also recommends Git checkpoints around tasks. This tutorial uses the clean baseline instead of asking Codex to create a checkpoint.

At the reviewed date, the documented installer command was:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

This command retrieves and runs an installation script, so it is not part of the repository’s read-only analysis. Use it only where organisation policy permits installation from the documented OpenAI endpoint. Do not transplant an older release command from a news article or pin a model or version merely because a historical interface displayed it. If the live documentation differs, follow the current official procedure and your administrator’s requirements.

After installation, change directory to the verified Git root and start the CLI with the explicit interactive posture:

cd /path/confirmed/by/git-rev-parse
codex --sandbox read-only --ask-for-approval on-request

The path above is intentionally generic. Do not put usernames, customer names, credentials or sensitive filesystem details into reusable examples. Complete the ChatGPT sign-in flow presented by the CLI. If the expected account or managed workspace is not shown, exit rather than continuing under a personal or otherwise unauthorised identity.

Inspect status before asking repository questions

Once inside the interactive CLI, run:

/status
/permissions

Use /status to inspect the session’s current directory and reported posture. Confirm that the directory corresponds to the Git root you established, or to an intentionally narrower approved subtree. Do not infer the scope from the terminal prompt alone. If the status shows an unexpected root or writable area, exit and restart correctly.

Use /permissions to inspect the active permission configuration. The required local file posture is read-only. Approval mode and sandbox mode are separate controls: approval governs whether Codex may ask to perform an action, while the sandbox constrains what local actions are available. Checking one does not validate the other.

An example verification record, not a guaranteed product display, is:

Human verification:
- Git root matches intended repository: yes/no
- CLI working directory matches approved scope: yes/no
- Sandbox reports read-only: yes/no
- Approval posture is on-request for interactive discovery: yes/no
- Unexpected writable roots: describe or stop
- Network, web, MCP, apps or connectors enabled: must be no

If the interface or command output differs from this description, consult the current official CLI and approvals documentation. Do not guess what an unfamiliar permission label means. Product availability and displayed controls can vary by account, rollout and workspace settings.

Understand interactive read-only with on-request approval

The interactive launch uses --sandbox read-only --ask-for-approval on-request. The read-only sandbox is the primary local constraint: Codex may inspect files and run commands allowed within that sandbox, but it should not modify repository files. The on-request approval posture allows the interface to surface a proposed action instead of silently treating every request as permitted.

For this tutorial, an approval request is not an invitation to broaden scope. It is a decision point. Approve only a clearly understood, non-mutating local inspection that remains within policy and the intended directory. Deny requests to write files, alter configuration, install dependencies, invoke external services, open the network or access unrelated paths. If a read-only inspection cannot proceed without such an action, record the gap as an unknown and stop that line of inquiry.

Read-only can block or constrain local file modifications and commands that require writing within protected areas. It can also reduce accidental edits while Codex explores the repository. It cannot guarantee that every command is harmless, that repository content is trustworthy, that prompts contain no sensitive material, or that account-level data handling meets a particular legal or organisational requirement.

It is specifically not a blanket privacy, confidentiality, data-retention or prompt-injection guarantee. Codex still receives the context used for the task. A readable file can contain a secret even when no process changes that file. A command described as diagnostic may reveal environment data. A malicious instruction embedded in repository text may ask for disclosure or escalation. Human judgement remains necessary before supplying context and before approving any action.

Use a “document rather than execute” rule for discovered commands. If a manifest says npm test, the atlas may cite that script. Do not run it merely because its name suggests testing: it could write snapshots, create caches, start containers, contact services or invoke hooks. The same applies to build, lint, migration and development commands. Their existence is evidence; their safety and success are separate questions.

OpenAI’s approvals and security documentation reviewed on 2 October 2026 describes an explicit non-interactive safe combination of --sandbox read-only --ask-for-approval never and warns that the dangerous sandbox-and-approval bypass is not recommended. A later capture pass can use the explicit read-only sandbox with approvals set to never because a non-interactive run cannot pause for broader permission. Interactive discovery retains on-request approvals so the human can see and reject unexpected proposals.

Do not switch to workspace-write for convenience. Although OpenAI documents command network access as off by default in that sandbox unless enabled, workspace-write would still weaken the central guarantee of this workflow. Likewise, do not use a dangerous bypass flag, including its shorter alias. Those settings remove the controls the tutorial is designed to preserve.

Stop/go gate before the first inspection prompt

Proceed only when every “go” condition is true and every forbidden capability remains absent. This is a human gate, not a prompt for Codex to answer on your behalf.

Go only if

• The repository owner or organisational policy permits this repository to be inspected with the selected local Codex account.
• You have distinguished a personal account from a managed workspace and inspected the relevant data controls.
• The checkout intentionally excludes credentials, customer exports, .env content, unredacted logs and other prohibited inputs, or policy confirms that no safe inspection is possible and you have stopped.
• git status --short has been reviewed by a human; any existing changes are understood rather than silently discarded.
• git rev-parse --show-toplevel confirms the intended repository root.
• Repository security and contribution guidance has been reviewed without assuming it is current.
• Applicable AGENTS.md and AGENTS.override.md files have been inventoried as unverified instruction sources.
• The CLI is authenticated with the intended authorised account.
• /status shows the intended directory and no unexpected writable scope.
• /permissions confirms a read-only sandbox and the intended interactive approval posture.
• You accept that the result will be a draft requiring maintainer review, not a validated architecture or safe execution plan.

Stop if any of these would be required

• Network access or package downloads.
• Live web search.
• MCP servers.
• Apps, connectors or other external integrations.
• workspace-write or any broader filesystem-write permission.
• A dangerous sandbox or approval bypass flag, including --yolo.
• Permission escalation to compensate for missing evidence.
• Reading or reproducing credentials, secret-like values, customer data, private exports, .env content or unredacted logs.
• Running a repository command whose side effects, data access or network behaviour have not been reviewed.
• Proceeding under the wrong account, wrong workspace, wrong directory or unresolved organisational policy.

If the gate fails, preserve the reason in a human note rather than trying alternative permissions. A suitable example is: “Inspection stopped: the documented build path requires an unauthorised package download; record build reproducibility as unknown and ask the maintainer.” That outcome is more reviewable than a superficially complete atlas produced outside the approved boundary.

Once the gate passes, the repository is ready for bounded inventory—not for edits. The next stage should ask Codex to identify files, commands, directory roles and instruction sources using repository evidence only, while preserving contradictions and unknowns for human review.

Design the atlas before asking Codex to inspect anything

A useful repository atlas begins as a human-owned specification, not as an open-ended request to “explain this codebase”. The specification determines what evidence Codex must collect, how uncertainty must appear, and what the eventual reviewer can reject. Without that contract, a fluent description can blur documented facts, local conventions and architectural guesses into one apparently authoritative account.

Define the output as a dated snapshot of one Git repository at one resolved root and revision. It should help a new maintainer locate evidence and formulate questions. It must not present itself as an audit, security review, architecture authority, implementation plan, governance file or proof that any command works. Commands found in documentation, manifests or continuous integration (CI)A software-development practice that automatically integrates and tests changes in a shared repository. Open glossary entry configuration are documentary evidence until a human deliberately validates them under suitable conditions.

Create the schema before Pass 1. At this stage, do not create docs/codex-atlas/REPOSITORY_ATLAS.md through Codex and do not ask it to fill gaps creatively. The reader’s shell will create and capture the final file in a later pass. For now, maintain the schema in the prompt or in a separate trusted note outside the repository if necessary.

A complete Repository Atlas schema

The following schema is deliberately broader than a directory listing. Every section has an acceptance rule: if repository evidence is insufficient, the corresponding field remains an explicit unknown rather than disappearing from the deliverable.

1. Snapshot metadata.
   Record the repository root as a relative reference such as ., the current Git revision identifier reported by Git, the active branch or detached-state observation, the capture time with time zone, the inspected scope, and whether the working tree was clean before inspection. Do not include a private remote Uniform Resource Locator (URL)The address used to identify and access a resource on the web. Open glossary entry, username, access token, credential-bearing submodule address or absolute home-directory path.
2. Project purpose and supporting evidence.
   Summarise what the repository says it provides, citing exact relative paths such as README.md, docs/overview.md or a manifest description field. Separate the repository’s own stated purpose from an inferred purpose. If the repository introductory file (README)A file explaining what a repository project does, how to get started and where to find help; GitHub commonly surfaces it to repository visitors. Open glossary entry and implementation disagree, preserve both observations in the contradictions ledger.
3. Start-command evidence.
   List development, production, command-line, worker or service start commands only when they appear in repository files. For each command, cite the file and relevant key, target or heading; identify the apparent working directory; and note prerequisites. Do not run a command merely because it is named start, serve or dev.
4. Directory and runtime map.
   Describe top-level directories, likely source roots, package boundaries and runtime signals. Distinguish authored source from generated, vendored, cached, fixture and build-output material. A directory name is weak evidence by itself: api/ does not prove the presence of a network service, and vendor/ does not prove every contained file is third-party code.
5. Entry points and execution paths.
   Reserve space for executable entry files, application bootstrap code, command registration, route registration, workers, scheduled tasks and user-interface roots. Pass 1 should identify candidates; Pass 2 will trace selected paths. Do not call a candidate “the main entry point” unless configuration or source wiring supports that distinction.
6. Test, lint and build matrix.
   Create one row per evidenced command or configuration target. Include the subsystem, command text, source of the command, relevant configuration, apparent prerequisites, expected write or network concerns, and validation status. “Present in manifest” and “successfully executed” are different states.
7. Data and external-service boundaries.
   Record only interfaces visible in repository evidence: database clients, queues, object stores, external application programming interfaces (APIs), identity providers, telemetry clients, filesystem persistence or message brokers. Cite imports, dependency declarations and configuration variable names without copying values. A variable named DATABASE_URL can be recorded as a configuration-name signal; its value must not be exposed.
8. Change-impact matrix.
   Connect narrowly framed hypothetical changes to probable entry paths, configuration, tests and owner questions. This is a navigation aid, not an implementation recommendation. Each impact statement must identify why a file is likely relevant and label uncertainty.
9. Active instruction-file inventory.
   List the AGENTS.override.md and AGENTS.md files that may be active for the inspected directory, their order, their scope and any discovery caveat. Inventory them without approving, correcting, paraphrasing into policy or creating replacements.
10. Evidence and confidence ledger.
    Give each material claim an evidence grade and confidence label. Confidence is not a substitute for a citation. A highly confident claim still needs a path or bounded command observation.
11. Contradictions.
    Preserve disagreements among documentation, manifests, task runners, CI files and source wiring. State what conflicts and which human or follow-up check could resolve it. Do not silently select the more plausible-looking source.
12. Unknowns and unknown owners.
    Record unanswered questions, why repository-only inspection cannot settle them, and the role that might know the answer. Use role descriptions such as “service maintainer” or “release owner” unless an owner is directly identified by repository evidence. Do not invent a person or team.
13. Refresh procedure.
    Explain how a future maintainer should confirm the root and revision, inspect changed evidence files, rerun the three-pass analysis under the same boundary, reconcile differences and obtain human review. A refresh date is not an assurance that the contents remain current.

The decision rule is simple: a section may be empty, but it may not be silently omitted because evidence is inconvenient. An empty test matrix should say that no test command or configuration was identified within the inspected scope; it must not say the project has no tests. Likewise, an empty external-services list means “not established from inspected evidence”, not “no external services exist”.

Use an evidence-bearing table, not a prose-only map

The following empty illustrative table demonstrates notation. It contains no claim about any real repository. Angle-bracketed text is a field to replace or mark unknown; it is not sample repository evidence.

Use relative paths rooted at the confirmed repository top level. A citation such as packages/service/package.json — scripts.start is reviewable; “the package file” is not. Avoid copying long file contents when a path plus key, heading, target or symbol identifies the evidence. Never include secret-like values, credentials, tokens, cookies, private keys, connection strings, personal data, customer records or unredacted logs in the prompt or atlas. Configuration names may be useful evidence, but their values usually are not.

Grade evidence by what it establishes

Apply four grades consistently. These grades describe the relationship between a claim and its evidence; they do not score code quality.

Grade A — direct file or configuration evidence

A repository file states or implements the point being recorded. Examples include a manifest script, a task-runner target, a test configuration include pattern, a container entry command or an import that constructs a client. Cite the relative path and the precise key, heading or symbol. Direct evidence proves that the text or code exists at the snapshot; it does not prove that the command is current, safe or successful.

Grade B — command or configuration corroboration

Two or more independent repository signals agree, or a bounded local read-only command reports metadata that corroborates a file. For example, a root task target may delegate to a package manifest script, while CI invokes the same target. Corroboration raises confidence that the command is intended, but still does not prove local execution will pass. Do not run builds, tests or package installation merely to obtain this grade.

Grade C — bounded inference

The evidence supports a narrow interpretation but not a definitive conclusion. For example, a dependency declaration and client import may indicate an integration boundary, while actual production use remains unknown. Write “appears to”, “candidate” or “likely within the inspected scope”, and name the missing evidence. Avoid broad labels such as “microservice architecture”, “clean architecture” or “event-driven system” unless repository evidence explicitly defines and substantiates them.

Grade U — unresolved unknown

Repository-only inspection cannot establish the point, evidence conflicts, or the relevant material is outside scope. State the question, evidence already checked and likely human owner. Unknown is a valid result and must not be converted into a low-confidence assertion merely to complete the table.

Confidence labels should follow evidence rather than tone. Use high when direct, specific evidence is internally consistent; medium when evidence is partial or needs corroboration; and low for bounded inference or unresolved conflict. Grade U normally remains low confidence, but the atlas can be highly confident that the answer is unknown from the inspected material. The practical rule is: if a reviewer cannot navigate from the claim to its evidence, downgrade or remove the claim.

Inventory active instruction files without turning them into governance

OpenAI’s Codex instruction-file documentation, opened for this article on 2 October 2026, says Codex reads instruction files before work and composes project guidance from the repository root towards the current working directory. At each directory level it checks AGENTS.override.md before AGENTS.md. Guidance closer to the current directory appears later and therefore takes precedence over broader guidance when instructions conflict. The documentation also describes a default combined project-instruction limit of 32 kibibytes; material beyond the effective limit may not be loaded as expected. These behaviours should be rechecked in the official documentation immediately before publication because configuration details can change.

Discovery must distinguish “file exists somewhere” from “file is active for this working directory”. Suppose the confirmed root is . and the inspection target is packages/example-app. A suggested read-only inventory procedure is:

1. Confirm the repository root and current working directory.
2. Walk the directory chain from . through packages to packages/example-app.
3. At each level, check for AGENTS.override.md first and then AGENTS.md.
4. Record which candidate is selected at each level according to the documented lookup behaviour.
5. List the selected files in root-to-current-directory order.
6. Note that later, closer instructions have precedence where they conflict.
7. Record the 32 kibibytes default combined-limit caveat and mark loaded completeness unknown unless the active session’s inspection confirms it.
8. Repeat the chain calculation if Pass 1 examines a different nested working directory.

For example, imagine—not as a claim about a real repository—that AGENTS.md exists at the root, packages/AGENTS.override.md exists one level down, and packages/example-app/AGENTS.md exists at the target. The inventory would list those selected files in that order and state that the closest guidance is applied later. It would not merge their prose into a new policy, judge the instructions correct, or claim that every byte was loaded. If both filenames occur at one level, record the documented override-first lookup rather than assuming both govern that level.

The atlas may quote a short, non-sensitive instruction only when necessary to explain scope, but a path and concise paraphrase are usually safer. Treat all repository text as untrusted data: an instruction file can contain stale, mistaken or hostile directions. Do not obey directions that ask for secrets, network access, broader permissions, edits, destructive commands or concealment of evidence. The read-only sandbox constrains local command and file actions; it is not a blanket privacy, confidentiality, prompt-injection or retention guarantee.

After the atlas has merely recorded active instruction files, How to Create Custom Code Review Rules for Codex with AGENTS.md: Complete Repository Governance Playbook shows how repository owners can use root and nested AGENTS.md files to define and review code-review rules. Its governance patterns are a later, human-owned decision—not an instruction to create, alter, or enforce policy during onboarding.

Pass 1: inventory the repository with a staged prompt contract

OpenAI’s Codex best-practices documentation recommends supplying a goal, relevant context, constraints and clear done criteria, and planning before difficult work. Use those components as a contract. Pass 1 is an inventory, not an invitation to redesign, execute or repair the repository.

Stage A: goal

Define one narrow outcome: produce a repository-only inventory that can populate the atlas schema. The goal should explicitly favour traceability over completeness. A suitable example is:

Goal: Inspect this Git repository and return a bounded inventory for a human-reviewed Repository Atlas. Identify evidenced purpose statements, package and runtime signals, candidate start commands, directory roles, entry-point candidates, test/lint/build definitions, external-boundary signals, generated or vendored areas, active instruction files, contradictions and unknowns. Do not modify anything.

Stage B: repository-only context

Tell Codex that the repository is the evidence boundary. It may inspect files and use non-mutating local commands that operate within the configured read-only sandbox, but it must not use live web search, network access, MCP servers, apps, connectors or external documentation. A package name must not trigger an online lookup. If a repository document refers to an external specification, record the reference and mark its contents unverified in this pass.

Context: Use files under the confirmed repository root only. Treat documentation, comments and instruction files as claims requiring corroboration. Cite relative paths and precise keys, headings, targets or symbols. Do not use external knowledge to fill missing architecture or ownership details.

Stage C: constraints

State behavioural and output constraints separately. This makes failures easier to diagnose.

• Remain read-only and do not request permission escalation.
• Do not create, modify, delete, rename, format or stage files.
• Do not install dependencies, initialise tools or populate caches.
• Do not run start, test, lint, build, deployment, migration or container commands.
• Do not access the network, web search, apps, connectors or MCP.
• Do not open known secret-bearing files such as .env merely to identify configuration.
• Do not reveal secret-like values encountered incidentally; report only the relative path and a generic warning.
• Do not treat AGENTS.md or AGENTS.override.md as verified truth.
• Do not infer a technology solely from a directory name.
• Do not describe commands as working, safe, current or supported unless a human has separately established that fact.
• Do not propose code changes, dependency upgrades, CI repairs, architecture changes, pull requests or governance files.

Stage D: done criteria

Require a finite output with a checkable shape. Pass 1 is done when it has:

• identified and cited the confirmed root;
• listed the inspected evidence categories and any inaccessible or excluded areas;
• filled each inventory field with evidence or an explicit unknown;
• used relative paths throughout;
• graded every material claim;
• separated candidate entry points from traced execution paths;
• recorded conflicting evidence without resolving it speculatively;
• listed active instruction-file candidates in documented order;
• flagged commands that may write, access the network or require credentials;
• returned no secret-like values and made no repository changes.

Stage E: explicit exclusions

Close the contract with what is out of scope. This prevents a well-intentioned inventory from becoming an implementation plan:

Exclusions: Do not test whether commands pass; assess security; decide architectural correctness; identify vulnerabilities; assign people; estimate effort; recommend migrations; write or revise AGENTS.md; alter CI; generate patches; or claim production behaviour. Put questions that require execution, external systems or human knowledge in the Unknowns ledger.

Inspect evidence in a deliberate order

A staged order reduces the chance that a prominent README becomes the entire story. The following procedure is an example method, not a guarantee of product behaviour or repository completeness.

1. Root documentation: inspect files such as READMEs, contribution guidance, support notes, security policies and documentation indexes. Extract stated purpose, setup claims and links to internal documents. Mark statements as repository-authored claims until corroborated.
2. Manifests and workspace declarations: identify language manifests, package workspace definitions and module descriptors. Record package boundaries, declared scripts, runtime constraints and dependency signals. Do not copy registry credentials or private source addresses.
3. Lock files: use their presence to corroborate an ecosystem or package-manager choice. Do not infer that dependencies are installed, current, secure or reproducible merely because a lock file exists.
4. Task runners: inspect make targets, task files and repository scripts. Trace delegation one level at a time: a root task may invoke a nested script whose working directory and environment differ.
5. CI definitions: record jobs, working directories and invoked commands as evidence of intended automation. CI configuration does not prove that a job currently passes or that its command is appropriate for local use.
6. Containers: inspect container build and orchestration configuration for entry commands, build contexts, ports, volumes and service names. Do not build, pull or start containers. Treat referenced images and services as documentary signals.
7. Test, lint and build configuration: identify include/exclude patterns, project references, output directories and command wiring. Distinguish unit, integration, end-to-end and unspecified test labels only when the repository does so.
8. Deployment configuration: note deployment entry points, environment-name references and service boundaries without accessing remote systems. Never report credentials, account identifiers or secret values.
9. Source roots: sample enough files to identify bootstrap candidates, exported entry points and major directory roles. Avoid reading every file when manifests and configuration define the scope more precisely.
10. Generated and vendor signals: inspect ignore files, generated-file notices, build output settings, vendoring conventions and code-generation configuration. Label uncertain areas instead of assuming generated content can be ignored.

The stopping rule is evidence saturation within the declared scope: when each schema field has either specific evidence or a documented unknown, Pass 1 can end. More file reading is not automatically better. Stop immediately if progress would require a credential, network call, write operation, dependency installation, cache initialisation or permission expansion.

Worked example: conflicting manifests

Assume hypothetically that a root manifest declares a start script, while a nested package manifest declares another start script with different tooling. A poor atlas selects one as canonical. A defensible atlas records both, including their relative paths and apparent working directories.

The evidence ledger might classify each script as Grade A because each is directly declared. If the root workspace configuration includes the nested package, that relationship may provide Grade B corroboration for a multi-package interpretation. It still does not establish which command a new maintainer should run. The contradiction or unknown should read: “Canonical start path is not established; root and nested manifests define distinct commands.” The owner question is: “Which package represents the supported onboarding target, and from which directory should it be started?”

The decision rule is to preserve command scope. Never flatten duplicate script names into one repository-wide command unless a root task or documentation explicitly delegates to the nested command.

Worked example: monorepo boundaries

Suppose a hypothetical workspace declaration includes packages/*, but the repository also contains tools/ and examples/. The workspace declaration directly evidences the included package pattern. It does not establish whether every matching directory is independently deployable, nor whether tools/ is outside all build processes.

Pass 1 should create separate boundary rows: “workspace membership indicated by configuration”, “tooling directory role inferred from task references”, and “examples directory purpose stated or unknown”. If a nested package has its own instruction file, calculate its active instruction chain relative to that package rather than assuming the root-only chain applies uniformly.

The decision rule is to represent boundaries at the granularity supported by configuration. Do not label the repository a “monorepo architecture” merely because it contains several directories. Record the workspace mechanism, package candidates and unresolved deployment boundaries.

Worked example: duplicated start scripts

Imagine a README instructs readers to run a root development command, a task runner exposes a similarly named target, and CI invokes a third command inside a subdirectory. These may be aliases, environment-specific variants or stale duplicates. Pass 1 should map the delegation where files make it visible, not choose the shortest command.

A useful row states: the documented command, its documentation citation, the task target it appears to invoke, and the nested manifest script reached by that target. A separate CI row records its working directory and configuration path. If the chain cannot be resolved without execution, label it unknown. No row should say “recommended command” until a maintainer confirms that status.

The trade-off is between concise onboarding and faithful ambiguity. At this stage, fidelity wins: preserving three scoped commands is preferable to publishing one convenient but unsupported instruction.

Worked example: no tests found

Suppose Pass 1 finds no test script, recognised test configuration or test directory within the inspected scope. It must not conclude “the project has no tests”. Tests could live in another package, be generated, use an unfamiliar convention, run in a private system or simply fall outside the sample.

The matrix should contain an unresolved row: “No test command or configuration identified in inspected root documentation, manifests, task runners and CI definitions.” Cite the categories and paths inspected rather than manufacturing a path to nonexistent evidence. Ask the maintainer whether tests live elsewhere and whether any command is safe to run locally.

The decision rule is linguistic as well as evidential: “not found in scope” is acceptable; “does not exist” requires stronger evidence than absence from a bounded inspection.

Worked example: a command may need network access or cache writes

Consider a hypothetical build target that invokes a package-manager command and a code generator. Its manifest presence is Grade A evidence that the command is declared. It is not permission to run it. Package managers may consult registries, and build tools may create caches or output directories. The exact behaviour may depend on local state and configuration.

Record the command as documentary evidence and add two cautions: “Network requirement unknown” and “May write dependency, cache, generated or build-output files; not executed.” If configuration explicitly points to an output directory, cite that as direct evidence, but do not claim it is the command’s only write location. If completing the inventory would require enabling network access or switching to workspace-write, stop and assign a human follow-up.

OpenAI’s approvals and security documentation, as opened on 2 October 2026, distinguishes sandbox controls from approval controls and documents the explicit non-interactive combination --sandbox read-only --ask-for-approval never. The tutorial does not weaken that boundary to make discovery more convenient. Read-only is a local action constraint, not proof that inspected data is non-sensitive or that a command would be harmless elsewhere.

Keep architecture observations subordinate to evidence

Pass 1 may identify components and relationships, but it does not decide architecture. Replace broad declarations with reviewable statements. Instead of “the application uses event-driven architecture”, write an example such as: “A message-client dependency and a consumer registration symbol are present at the cited paths; whether this is a primary production flow is unknown.” Instead of “the frontend is decoupled from the backend”, cite separate build roots and an API client, then state that deployment coupling remains unverified.

The change-impact matrix follows the same rule. A hypothetical change to an existing validation message might identify a handler, message catalogue and nearby test candidate because source references connect them. It must not prescribe a redesign or assert that those are the only affected files. Architecture decisions belong to human-owned records and review processes after repository understanding has been established.

Once a team has evidence to discuss, How to Manage Design Decisions When Using AI Coding Agents: Complete Guide to Preventing Architecture Drift with Claude Code, Cursor, and Codex addresses keeping design documents, review workflows, and dependency or styling guardrails aligned when agents modify code. It is a follow-on for human architectural ownership, not evidence that this read-only atlas selects, proposes, or adjudicates an architecture.

Human review gate before Pass 2

Do not proceed directly from an impressive inventory to execution-path tracing. A human must review Pass 1 because an incorrect root, vague citation or exposed secret can contaminate every later section.

1. Verify root correctness.
   Compare the reported root with the human’s earlier git rev-parse --show-toplevel result. Check whether the prompt began in a nested package and whether the intended scope is the whole repository or one subtree. If the root is wrong, discard the inventory and rerun Pass 1 from the correct location.
2. Sample citation specificity.
   Select at least one purpose claim, command, directory role, instruction-file entry and external-boundary signal. Navigate to each relative path and verify the named heading, key, target or symbol. Reject citations that name only a broad directory or say “based on the codebase”.
3. Check evidence grades.
   Ensure direct declarations are not described as successful execution. Confirm that corroboration uses genuinely separate evidence and that bounded inferences name what remains unknown.
4. Challenge architecture language.
   Search for unsupported terms such as “canonical”, “central”, “decoupled”, “scalable”, “secure”, “production-ready”, “legacy”, “microservice” or “source of truth”. Retain them only when the repository explicitly establishes the meaning and the atlas cites that evidence.
5. Review instruction-file scope.
   Recalculate the root-to-current-directory chain. Confirm override-first selection at each level, closer-file precedence, and the combined-instruction-limit caveat. Remove any language endorsing or rewriting the instructions.
6. Inspect for accidental secret exposure.
   Search the draft for token-shaped strings, private keys, passwords, cookies, connection strings, private remote addresses, personal information and unredacted environment values. If any appear, stop, contain the output according to organisational procedure, and do not proceed merely by hiding the line in the final atlas.
7. Check command safety labels.
   Every discovered start, test, lint, build, migration, container or deployment command must remain “not executed” unless a separate human-controlled process has established otherwise. Flag commands that may use the network, credentials, caches or writable outputs.
8. Confirm unknowns are preserved.
   Look for questions that the draft quietly resolved through plausibility. Restore unknown owners, deployment assumptions, external-system behaviour and missing test evidence to the ledger.

Any security, privacy, financial, employment, government or other consequential interpretation requires qualified human review; the atlas must not make or automate such decisions. If sensitive repository material cannot be handled under the organisation’s policy and the account’s applicable controls, stop rather than broadening the prompt or permissions.

Pass 2 may begin only when the root is correct, sampled citations resolve precisely, no unsupported architecture assertion remains, active instructions are recorded without endorsement, and the reviewed inventory contains no secret-like values. The output still remains a draft. Passing this gate means only that the evidence contract is sound enough for a narrower execution-path inquiry; it does not certify the repository, its commands or Codex’s conclusions.

Pass 2: trace a few evidenced execution paths

Pass 1 described the repository’s breadth. Pass 2 changes the question from “What is here?” to “How does a specific action appear to move through this codebase?” This is a repository-only inquiry: Codex may inspect files and use local read-only commands, but it must not access the network, call MCP servers, use apps or connectors, write caches, install dependencies, modify files or claim that an observed path works at runtime.

Select three to five paths that are both important to onboarding and supported by repository evidence. Possible categories include an Hypertext Transfer Protocol (HTTP)A standard request-and-response protocol for exchanging representations and related metadata between web clients and servers. Open glossary entry request, a CLI invocation, a background worker, a user-interface route or a test path. These are examples, not mandatory categories. A library may expose public functions without an HTTP server; a firmware repository may have neither a user interface (UI)The controls and visual surfaces through which a person interacts with software. Open glossary entry nor a worker; a documentation repository may centre on a build pipeline. Do not invent a category merely to fill the atlas.

Choose paths by evidence and onboarding value

Begin with the Pass 1 inventory and make a candidate list. For each candidate, locate a concrete entry point before accepting it. An entry point is the first repository-defined file, symbol or configuration record that handles or dispatches the action being traced. A package script that invokes a binary can identify an intended invocation, but it is not automatically the application entry point. Likewise, a route string in documentation is weaker evidence than a route registration in source or framework configuration.

1. List candidate actions. Derive them from manifests, source roots, route tables, binary declarations, worker registrations, UI routing configuration and test configuration.
2. Require a locatable entry point. Record the relative path and, where useful, the symbol, target, script key or configuration section. Do not rely on a filename alone when the file contains several unrelated entry points.
3. Prefer representative paths. Choose paths that reveal different boundaries rather than five variations of the same controller. For example, one HTTP path, one worker path and one test path may teach more than three neighbouring HTTP endpoints.
4. Check whether the path can be followed downstream. If evidence stops after the first dispatch, retain the path only if that gap is itself important. Mark the downstream sequence incomplete.
5. Cap the set at five. The atlas is an onboarding aid, not an exhaustive call graph. More paths increase review cost and encourage unsupported connective prose.

Decision rule: include a path when its entry point is directly evidenced and at least one downstream relationship can be cited. If only a README assertion exists, place it in the unknowns ledger or describe it as a documented claim requiring source corroboration. If no suitable paths can be evidenced, say so; do not force the repository into a web-application template.

Use one trace record for every selected path

Each execution-path record must contain the same fields. Consistency makes omissions visible and allows a maintainer to challenge one link without rejecting the whole atlas.

Entry point

The first evidenced repository-defined handler, command, route, job registration, component route or test invocation. Cite its relative path and identifying symbol or configuration key.

Downstream sequence

An ordered chain of files and symbols supported by imports, registrations, direct calls, dependency injection or configuration. Separate direct evidence from inferred transitions.

Configuration dependencies

Configuration names, manifest sections, flags or environment-variable names that affect selection or behaviour. Never reproduce values from environment files, credentials or logs.

External-service boundary

The point at which repository code appears to call a database, queue, remote application programming interface (API), identity provider or other external system. Identify the adapter or client from source evidence without contacting the service.

Related tests

Tests whose imports, names, fixtures or configuration connect them to the path. A nearby test filename is not sufficient unless its content establishes the relationship.

Likely narrow change surface

A conservative set of files that a later human might inspect for a tightly defined hypothetical change. This is not an edit proposal or a complete impact analysis.

Confidence

High, medium or low, with a reason tied to evidence quality. Confidence applies to the documented trace, not to runtime correctness.

Unresolved owner question

One focused question for the maintainer responsible for the area, especially where generated code, shared contracts, deployment configuration or operational behaviour cannot be settled from the repository.

A useful trace avoids verbs such as “receives”, “validates” or “publishes” unless the cited code demonstrates that relationship. Where static evidence is weaker, use precise wording such as “registers”, “imports”, “constructs”, “passes to” or “appears to select”. The distinction matters: an import proves a dependency exists in source, but not that a production request reaches it under every configuration.

Prompt Pass 2 with a strict evidence contract

The following is an example prompt, not a guarantee of product output. Use it only after reviewing Pass 1 and selecting candidate areas. Keep untrusted data, credentials, customer records, environment-file contents and copied tokens out of the prompt.

Pass 2 is a repository-only execution-path inquiry. Do not modify files,
use the network, invoke MCP servers, apps or connectors, install packages,
write caches, or run commands that require writes.

From repository evidence, trace three to five representative paths only
where an entry point and at least one downstream relationship are supported.
Possible categories include an HTTP request, CLI invocation, worker, UI route,
or test path; do not assume this repository contains every category.

For each path provide:
1. entry point, with relative path and symbol/configuration key;
2. ordered downstream sequence, citing every transition;
3. configuration dependencies, naming keys but never secret values;
4. external-service boundary, if evidenced;
5. related tests and the evidence connecting them;
6. likely narrow change surface for a hypothetical small change;
7. confidence: high, medium, or low, with a reason;
8. one unresolved question for the responsible human owner.

Distinguish direct evidence, inference, and unknowns. Scripts and CI files
show intended commands only; do not say commands are safe, current, successful,
or locally runnable unless repository evidence establishes only the narrower
claim. Do not execute builds, tests, application code, or networked tooling.
Return a draft trace table plus an evidence ledger. Propose no edits.

Review the response path by path. For each arrow in a sequence, open the cited source and ask what actually establishes the transition: an import, registration, call, framework convention, generated mapping or merely a matching name. Matching names alone warrant low confidence. If Codex compresses several uncertain steps into one fluent sentence, split the sentence into separately reviewable claims.

Trace configuration without exposing values

Configuration is often the difference between a plausible source path and the path selected in a particular deployment. Record only what repository evidence can establish. A configuration schema may prove that a key is recognised; a checked-in example may show an intended shape; a deployment manifest may show that a variable name is supplied. None of these proves the effective runtime value.

1. Locate configuration readers and schemas before relying on example files.
2. Record variable names or configuration keys, never their values when those values could be secret or identifying.
3. Identify defaults only when source or checked-in configuration defines them directly.
4. Note precedence only when code or repository documentation establishes it.
5. If configuration selects between implementations, trace each relevant branch only as far as evidence permits.

Decision rule: write “expects SERVICE_ENDPOINT” when code reads that name; do not write “connects to the production service” without admissible evidence. If an ignored .env file or local credential would be needed to settle the question, stop and assign it to a human owner. Read-only limits local command and file actions; it is not a blanket privacy, confidentiality, prompt-injection or retention guarantee.

Locate external boundaries without crossing them

An external-service boundary is valuable because it marks where repository-only understanding ends. Look for constructed clients, adapter interfaces, database drivers, queue publishers, HTTP clients, software development kits and deployment bindings. Record the local call site and the interface or client it uses. Do not call the endpoint, resolve its hostname, fetch schemas or enable network access to make the trace feel complete.

For example, source may show that a handler passes a record to NotificationGateway.send(), while a separate adapter imports a third-party client. The atlas may state that the path reaches an external notification boundary through those cited symbols. It must not state that a message is delivered, that credentials are valid or that retries succeed. Those are runtime and operational claims.

If package installation, test discovery or framework bootstrapping attempts to download dependencies or write a cache, record the requirement instead of loosening permissions. A suitable unknown is: “Local execution appears to require a dependency cache not present in the clone; no command was run. Confirm the supported offline/bootstrap procedure with the build owner.” This preserves the boundary and gives the next reviewer an actionable question.

Treat scripts and continuous integration as documentary evidence

Package scripts, Make targets, task-runner files and CI workflows are strong evidence of intended commands because maintainers placed command strings in repository-controlled configuration. They are not proof that the command is safe, current, successful, deterministic or appropriate on a developer machine.

A script called test might start containers, delete generated directories, use paid services, mutate snapshots, depend on credentials or assume a populated cache. A CI job might run only after secrets are injected, on a particular operating system, with services that are absent locally. Conversely, an obsolete job may remain in the tree. Read the command and its surrounding conditions; do not infer success from its existence or from a reassuring name.

Decision rule: cite scripts and CI as “declared” or “intended” commands. Promote a statement no further in this tutorial. Command execution is outside the atlas capture unless a separately governed human process authorises it; even then, the resulting observation would need its own date, environment and exit status.

This tutorial validates a documentation artefact by checking its claims against repository evidence. It is not a substitute for validating artificial intelligence (AI)Computer systems designed to perform tasks that normally require human intelligence, such as understanding language, recognising patterns, or making predictions. Open glossary entry-generated code before shipping, where reviewers must assess changed code and its behavioural tests.

The review here checks a documentation artefact; How to Validate AI-Generated Code Before It Ships: Complete Playbook Using Blacksmith, Codex, and Automated Testing Pipelines instead details validation of AI-generated production code through testing layers and focused human review. Use that distinction to avoid treating an evidence-cited atlas as a passed test suite, code review, or approval to ship.

Likewise, a failing CI run is not an onboarding exercise. Keep failure triage, patch creation, pull-request writes and merge controls in an explicitly separate remediation workflow.

If a CI job has actually failed, Controlled Codex CI Auto-Fix Playbook: Read-Only Failure Triage, Patch Artifacts, Separate PR Writes, and Human Merge Gates describes a different, controlled remediation path: read-only failure analysis produces a patch artefact, while separate write-capable pull-request work and authorised human merge review remain gated. It is not a substitute for the atlas’s non-remedial onboarding workflow.

Worked example: map a validation-message change without proposing edits

Consider a hypothetical repository in which Pass 1 finds a route registration, a request handler, a validator, a message catalogue, an external persistence adapter and tests. The filenames below are illustrative placeholders, not claims about any real repository and not runtime results. The task is only to map where a later human would inspect if asked to alter an existing validation message.

Suppose repository evidence includes these illustrative relationships:

• src/http/routes/account.ts registers POST /accounts to createAccount.
• src/http/handlers/create-account.ts imports and calls validateAccountInput.
• src/domain/account/validate-input.ts returns a message key for an invalid display name.
• src/i18n/en/account.json contains a matching message key.
• src/http/errors/to-response.ts maps validation failures to an HTTP response shape.
• tests/http/create-account.test.ts imports the application test helper and asserts a validation-error payload.

First, verify each relationship independently. Route registration supports the entry-point claim. A direct import and call support the handler-to-validator transition. A matching text string alone would not prove that the catalogue entry is selected; look for the key returned by the validator and the lookup performed by the response path. If that lookup is supplied by framework magic or generated code that is absent, mark the transition as inferred rather than filling the gap.

An example trace record could read:

The narrow change surface should not automatically include every file on the full request path. If the hypothetical request changes wording only, route registration and persistence are context, not likely edit sites. If tests assert a stable error code rather than literal text, they may need review but not modification. If messages are generated from a schema, the schema or generator input may be the true narrow surface and generated output should be marked as non-authoritative. This distinction prevents an onboarding map from becoming a speculative implementation plan.

Do not claim runtime behaviour from this static map. The existence of a branch returning a message key does not establish that deployed traffic reaches it, that middleware preserves it, or that a client displays it. The useful conclusion is bounded: these files contain evidenced relationships relevant to the hypothetical question, while named gaps require owner confirmation.

Decision rule: include a file in the likely change surface only when the hypothetical requirement intersects a responsibility evidenced in that file. Put merely adjacent files in “context”, and exclude files connected only by naming resemblance.

Relate tests without treating them as proof

Tests can reveal intended contracts, seams and fixtures even when they are not run. Connect a test to a path through concrete evidence: it imports the handler, invokes the CLI entry, mounts the route, dispatches the job, renders the component, or names a configuration target that selects the path. Test directory proximity and similar names are hints, not sufficient citations.

Record the level of the test where repository structure makes it evident: a direct function test, an adapter test, a route-level test or a broader scenario. Avoid universal labels such as “unit” and “integration” unless the project itself defines them or the mechanics clearly support the distinction. Note mocks and fixtures when they change what the test can establish. A mocked external client can support a claim about the expected call shape, but not about live-service compatibility.

If a test command appears to require network access, service containers, credentials or cache writes, add those as requirements or unknowns. Do not change the sandbox, approval mode or environment to run it. If test configuration conflicts with a package script, preserve both claims and defer reconciliation to Pass 3.

Pass 3: reconcile sceptically before capture

Pass 3 is not another opportunity to expand the architecture narrative. It is an adversarial editing pass over Pass 1 and Pass 2. Compare every inventory claim and trace against source, manifests, configuration and instruction context; identify contradictions; reduce confidence where evidence is incomplete; remove unsupported statements; and return only the prescribed atlas template.

OpenAI’s Codex best-practices documentation recommends supplying goal, context, constraints and done criteria, planning difficult work, and validating outputs. Here, “done” means a reviewable evidence-cited draft with uncertainty preserved. It does not mean architectural completeness, passing tests or approval to change the repository.

Build a contradiction register

Work through the draft by claim type rather than rereading it as smooth prose. Smooth prose can hide mismatched evidence.

1. Purpose claims: compare README language with manifests, source roots and deployment configuration. If they differ, report the difference rather than choosing the more convenient description.
2. Command claims: compare documentation with package scripts, task files and CI. Record variant flags and working directories. Do not collapse several commands into one canonical command without evidence.
3. Entry points: confirm registration and dispatch in source or configuration. Remove an entry point inferred only from a suggestive filename.
4. Path transitions: check every arrow. Downgrade confidence where framework discovery, generated output or runtime injection obscures a transition.
5. Test relationships: inspect imports, setup and assertions. Remove tests linked only by naming similarity.
6. External boundaries: distinguish an installed dependency from an instantiated client and an instantiated client from an executed call.
7. Instruction claims: record active AGENTS.md or AGENTS.override.md files as instructions Codex reads, not as verified facts about the project.

OpenAI documents that Codex composes instruction files from the repository root towards the current directory, checks override files before ordinary files and gives closer guidance later precedence, subject to its documented combined instruction limit. That makes the working directory relevant to the atlas. It does not make those instructions correct. If an instruction says tests use one command but the manifest defines another, retain the contradiction and ask the maintainer which is current.

Downgrade, qualify or delete

Use a strict reconciliation ladder:

• Keep at high confidence only when direct, current repository evidence supports the claim and relevant sources agree.
• Keep at medium confidence when the principal relationship is direct but a configuration-dependent or generated transition remains unresolved.
• Keep at low confidence only when the uncertainty itself helps onboarding and is clearly labelled.
• Delete a statement that has no cited support, duplicates another claim without adding evidence, or presents speculation as architecture.
• Move to Unknowns a question that requires runtime access, organisational knowledge, secret values, external documentation or an owner decision.

Decision rule: contradiction lowers confidence; it never justifies averaging two claims into a third. When a README says “use command A” and CI invokes command B, write that the sources disagree, cite both and ask which context each serves.

Require only the atlas template

Pass 3 output should contain the previously prescribed atlas sections and nothing else: no conversational preface, no suggested patches, no shell transcript, no hidden reasoning, no new governance file and no claim that validation succeeded. Require repository-relative citations wherever possible. Absolute local paths disclose workstation details and make the artefact less portable.

An example reconciliation instruction is:

Reconcile the Pass 1 inventory and Pass 2 traces sceptically against
repository source and configuration. For every claim, retain a relative-path
citation or move the point to Unknowns. Identify disagreements between docs,
scripts, CI, manifests, source, tests, and active instruction files. Lower
confidence where evidence conflicts or a transition depends on runtime state.
Remove unsupported statements rather than smoothing over gaps.

Return only the prescribed Repository Atlas Markdown template. Do not propose
edits, claim commands ran, reveal secret-like values, include absolute paths,
use the network, invoke MCP/apps/connectors, or modify repository files.

Capture final-message standard output without granting write access

OpenAI’s non-interactive-mode documentation, reviewed on 2 October 2026, documents codex exec, --ephemeral, final-message standard output suitable for redirection, progress on standard error, a read-only default sandbox and a Git-repository prerequisite. Make read-only and approval behaviour explicit rather than relying on defaults:

mkdir -p docs/codex-atlas
codex exec --ephemeral --sandbox read-only --ask-for-approval never \
  "Using repository files only, produce the Repository Atlas in the required template. Cite every claim with a relative path or command/config evidence. Do not modify files, reveal secret-like values, use the network, invoke MCP/apps, or infer missing facts. Put unresolved points in an Unknowns ledger." \
  > docs/codex-atlas/REPOSITORY_ATLAS.md

The reader’s shell executes mkdir -p and creates or truncates the destination file through > redirection. Codex is not being granted repository write permission and should not be described as writing the file. This distinction also creates a trade-off: redirection can overwrite an existing draft before human review. Check the destination first, copy an existing reviewed atlas if organisational policy permits, or refuse the rerun until its contents have been preserved.

Standard error (stderr) carries progress information, so it remains visible in the terminal unless the reader separately redirects it. The final agent message is printed to standard output (stdout), which the shell sends to the Markdown file. Do not combine both streams into the atlas: progress and diagnostic text are not part of the prescribed artefact and may complicate review.

The documented codex exec workflow requires a Git repository. Run it from the intended repository and confirm the root beforehand. If the prerequisite fails, stop and correct the location or repository state through the appropriate human process. Do not bypass the repository check, because the workflow depends on Git context and a reviewable diff.

--ephemeral prevents session rollout files from being persisted to disk as documented for non-interactive use; it is not a promise that no data is processed or retained anywhere. Account and workspace data controls still matter. The explicit --sandbox read-only --ask-for-approval never combination prevents the non-interactive run from requesting escalation for local actions. If discovery needs writes, networking, credentials or another integration, the correct result is an unknown or refusal—not broader permissions.

Inspect the captured artefact for leakage and false certainty

Do not stage the file immediately. Open it as untrusted generated documentation and perform a content review.

• Secret-like output: search for tokens, keys, passwords, connection strings, private URLs, credential-shaped strings and copied environment values. If found, stop, remove the artefact from any sharing or staging flow and follow the repository owner’s incident process. Do not paste the suspected secret back into a prompt.
• Absolute paths: replace unsupported machine-specific claims through a reviewed rerun or careful human editing. Citations should normally be repository-relative.
• Copied tokens: check code blocks, command examples, query strings and logs. A masked prefix can still be sensitive or identifying.
• Unexplained certainty: challenge “always”, “never”, “guarantees”, “production”, “canonical”, “safe” and “passes” unless the narrow claim has adequate evidence. Most runtime absolutes should become qualified statements or unknowns.
• Missing citations: every purpose, command, directory role, execution transition, test relationship and external boundary needs a relative path or clearly identified repository command/configuration source.
• Consequential conclusions: reject security, privacy, financial, employment, government or other consequential recommendations. Such decisions require authorised human review and appropriate specialist evidence; this atlas is not a decision authority.

If sensitive material appears, deleting a line from the draft may be insufficient where the file was logged, backed up, shared or staged. Escalate to the authorised human owner. Do not make unsupported claims that read-only mode prevented disclosure.

Review the diff in a fixed sequence

1. Run git status --short and verify that the expected atlas path is the only newly created output attributable to this capture. Investigate every other change; do not assume Codex caused or did not cause it.
2. Inspect the complete diff for docs/codex-atlas/REPOSITORY_ATLAS.md. Confirm the template is complete and contains no conversational preface.
3. Check metadata: repository root context, revision or timestamp fields, and scope must be accurate and must not imply a runtime test.
4. Sample every evidence category against source: purpose, commands, directory roles, one transition from each path, test links and external boundaries.
5. Review all high-confidence claims first. High confidence carries the greatest risk of misleading a new maintainer if overstated.
6. Check contradictions and unknowns. Ensure none vanished during reconciliation and every owner question is answerable by a named role or team where that information is genuinely known.
7. Perform the leakage, absolute-path, copied-token, certainty and citation checks.
8. Ask an appropriate maintainer to review the artefact. Security, privacy, money, employment, government and other consequential interpretations require explicit qualified human review.
9. Only after approval, decide whether to stage and commit the documentation through the repository’s normal human process. The capture command itself neither approves nor commits it.

Rerun, refuse or accept with unknowns

Rerun Pass 3 when the evidence exists but the output format is wrong, citations were omitted, confidence labels are inconsistent, absolute paths appear, or reconciliation failed to preserve a known contradiction. Before rerunning, protect any existing draft because shell redirection can truncate it.

Return to Pass 2 when a selected path lacks a valid entry point, a key transition was based only on naming, or the trace set overrepresents one subsystem. Replace the weak path rather than asking for more confident prose.

Accept an unknown when answering it requires runtime state, external services, credentials, absent generated sources, organisational knowledge or a maintainer decision. Unknowns are a successful boundary outcome, not a defect to conceal.

Refuse capture when the repository is not the intended Git repository, the destination would overwrite an unpreserved reviewed artefact, the prompt would contain secrets or untrusted customer data, active policy forbids the selected Codex surface, or completion would require network access, cache writes, package installation, MCP, apps/connectors, workspace-write or a sandbox/approval bypass.

Refuse acceptance when secret-like material remains, claims lack citations, commands are reported as successful without recorded evidence, the atlas presents itself as an audit or architecture authority, or consequential decisions are made without authorised human review. A shorter atlas with explicit gaps is preferable to a comprehensive-looking document that cannot be defended from repository evidence.

Verify the atlas as a maintainer, not as generated documentation

A captured docs/codex-atlas/REPOSITORY_ATLAS.md is a review candidate. It is not accepted documentation merely because it is coherent, cites paths or was produced under a read-only sandbox. Read-only constrains Codex’s local command and file actions; it does not establish that the inspected files were current, that an inferred execution path was complete, that documentary commands are safe, or that sensitive material was absent from the output.

Use a maintainer-style protocol: sample factual claims, trace each sample back to repository evidence, challenge unsupported links between files, inspect the output for secret-like material, ask named owners about consequential unknowns, and record corrections. Do not state that tests, builds, linters, migrations or start commands were executed unless a human separately ran them under an approved procedure and retained the relevant evidence. This tutorial’s read-only discovery run is not such a procedure.

1. Freeze the review target. Record the repository root, branch or detached state, commit identifier, capture time and atlas path. Review the exact captured file rather than an edited copy whose provenance is unclear.
2. Check scope before detail. Confirm that the atlas describes the intended Git repository and, in a monorepository (a single repository containing several projects), the intended package or service boundary.
3. Sample every evidence class. Do not verify only easy path claims. Include commands, execution paths, tests, external boundaries, instruction files, confidence labels and owner assignments.
4. Correct the record visibly. Change or remove unsupported prose, add missing citations and retain unresolved matters as explicit unknowns. A correction should identify what changed and why.
5. Choose an approval state. Reject, revise, accept as a dated draft, or intentionally add and commit after review. These states are materially different.

A clean initial git status --short is useful provenance: it helps distinguish pre-existing changes from the shell-created atlas. It does not validate a single sentence in that atlas. Likewise, a clean status after deleting the draft would only show that no tracked change remains; it would say nothing about the quality of the generated analysis.

Record the review frame

Add a small review block to the draft or to the associated review record. Use factual identifiers rather than a general statement such as “reviewed by engineering”. A suitable example is:

Review state: revise
Repository root checked by: [human name or team]
Atlas reviewed at commit: [commit identifier]
Review date: [ISO date]
Scope checked: [whole repository / named package]
Commands executed during atlas verification: none
Material corrections:
- [claim changed, with path evidence]
Open owner questions:
- [question, owner or team, status]

This is an example record, not a Codex-generated guarantee. The explicit “commands executed” line prevents documentary command discovery from being mistaken for successful validation. If an authorised human later runs a command, record that separately with its environment, inputs and result; do not retroactively describe the original atlas capture as a test run.

Sample claims across all evidence classes

Full line-by-line verification may be appropriate for a small or consequential repository. For a larger atlas, sampling is a triage method rather than proof of completeness. The decision rule is: sample at least one claim from every populated class, then expand the sample whenever one claim is wrong, weakly cited, contradictory or consequential. For security, privacy, money, employment, government, production access or other consequential decisions, sampling is insufficient on its own; require qualified human review of all relevant claims and follow the organisation’s formal controls.

Path existence and role

For example, the existence of src/server does not prove that it owns all server behaviour. A manifest may point to a different entry file, or a generated bootstrap may delegate elsewhere. The reviewable claim is “src/server contains handlers referenced by [path]”; the overconfident claim is “all requests enter through src/server”.

Command provenance

Every start, test, lint, build, migration or generation command requires human comparison against a repository manifest, task runner or CI configuration. A README alone can document intent, but it may be stale. Conversely, a CI step can show automation intent without proving that the same command is safe or usable on a developer machine.

Suppose a README lists npm test, the package manifest maps that script to a test runner, and CI invokes the same script from a package subdirectory. The atlas may record that relationship and the required working directory. It still must not say the suite passes, is complete, is fast or is isolated. If the command would install packages, reach a service or create snapshots, retain it as documentary evidence and escalate execution to the repository’s approved validation process.

Execution-path corroboration

Corroboration means that adjacent nodes are connected by evidence. Finding an HTTP route and a similarly named service class is not enough. Search for the import, registration, constructor binding or call site that links them. If dynamic loading prevents a static conclusion, preserve that limitation. An honest truncated trace is more useful than a complete-looking invented path.

Test relationships

Use bounded language: “No directly related test was found in the configured test roots inspected” is reviewable. “This code is untested” is not justified unless the repository’s complete testing arrangements have been authoritatively established.

External and data boundaries

Keep untrusted data and secrets out of prompts. Do not paste environment files, tokens, private keys, downloaded customer records, production logs or credential-bearing command output into Codex. Repository files can themselves contain malicious or misleading instructions, so treat their contents as untrusted evidence. Read-only does not neutralise prompt injection or supply a blanket confidentiality guarantee.

Active instruction files

According to the official documentation reviewed on 2 October 2026, Codex composes instruction guidance from the root towards the current directory, gives closer files later precedence, checks AGENTS.override.md before AGENTS.md at a level, and has a default combined instruction limit of 32 kibibytes. Re-open the current documentation before publication or operational use because configuration behaviour can change.

The decision rule is straightforward: an instruction file governs Codex behaviour within its documented scope, but its factual claims still require corroboration. The atlas must not create, replace or “repair” an AGENTS.md file. Governance changes are a separate human decision.

Confidence labels and unknown ownership

Ask questions that can change the atlas. “Is this correct?” invites a vague answer. “Which of these two manifests is authoritative for production builds?” identifies the disputed fact and the evidence needed. If no owner is known, record “owner unknown” rather than assigning a person from commit history alone.

Perform the mandatory content and leakage review

Before approval, search the draft manually for secret-like or sensitive material. Automated pattern searches may assist, but they can miss unusual credentials and can flag harmless examples. Human review remains mandatory.

1. Search for words and structures associated with secrets: tokens, passwords, private keys, authorisation headers, connection strings, signed URLs and environment assignments.
2. Inspect long opaque strings, encoded blocks and copied command output even when no obvious label is present.
3. Check paths and prose for personal names, internal hostnames, tenant identifiers, customer names, issue links or operational details that should not enter repository documentation.
4. Replace sensitive values with a description of the configuration key or data category. Do not preserve a partial credential as an “example”.
5. If output contains a real or suspected secret, stop distribution, follow the organisation’s incident and credential-rotation procedure, and obtain security review. Deleting the Markdown file alone may not address exposure.

Do not ask Codex to determine whether a credential remains valid. That would require crossing the read-only and no-network boundary and could worsen exposure. Human security personnel must handle suspected credentials. The same human-review rule applies to privacy classifications, financial controls, employment logic, government processes and other consequential subjects.

Choose and record an approval state

Reject

Use when the root or scope is wrong, sensitive output is present, evidence is broadly absent, instruction conflicts invalidate the run, or the document would mislead a new maintainer. Preserve only what organisational policy permits for diagnosis; do not commit the atlas.

Revise

Use when the structure is useful but specific claims, citations, labels or unknowns need correction. A human may edit the Markdown directly or repeat a bounded read-only capture. Review the new diff as a new candidate.

Accept as a dated draft

Use when the atlas is suitable for limited onboarding reference but still contains explicit unknowns. Keep its date and commit context visible. “Accepted draft” must not be shortened to “authoritative architecture”.

Intentionally add and commit after review

Use only when repository maintainers want the atlas versioned, its content and sensitivity have been reviewed, and its location follows repository policy. The human runs the Git add and commit steps; Codex did not autonomously publish or approve it.

A practical decision rule is to reject structural invalidity, revise correctable factual defects, accept a dated draft when uncertainty is useful and honestly bounded, and commit only when maintainers intentionally want a durable repository artefact. Record the reviewer and material corrections in all but the rejected state.

Use the atlas without turning it into authority

The atlas supports Codex repository onboarding by shortening the path from “I do not know where to look” to a set of cited starting points and owner questions. A new maintainer can follow a primary execution path, locate the associated configuration and tests, and identify boundaries that require specialist input. They must still read the cited files.

For narrow planning, start from one requested behaviour and consult the change-impact matrix. Select only evidenced entry points, likely implementation areas, related tests and external boundaries. Then convert uncertainties into planning questions. For example, a request to alter an existing validation message might point to a handler, shared validation module, message catalogue and directly importing tests. That is a candidate inspection set, not an implementation ticket and not permission to edit all listed files.

Keep the atlas separate from these artefacts:

• AGENTS.md: active instructions shape Codex work. The atlas only records which instruction files appeared relevant and whether their factual claims were corroborated.
• Architecture decision records (ADRs): an architectural decision record (ADR)A record of a significant software-architecture decision, its context and consequences, maintained under the team’s decision process. Open glossary entry records a deliberate architectural decision and its rationale under the repository’s governance. The atlas may cite an existing ADR but cannot make or approve a decision.
• Security review: identifying authentication modules or external clients is not threat modelling, vulnerability assessment or approval.
• Implementation tickets: a ticket needs agreed scope, acceptance criteria, dependencies and ownership. The atlas supplies context but does not establish those commitments.
• Architectural authority: the document maps evidenced paths at a recorded commit. It cannot guarantee completeness, runtime behaviour or organisational intent.

The trade-off is durability versus false authority. Committing the atlas makes onboarding context easy to find and review through Git, but it also creates maintenance work and a risk that dated observations will be treated as current. If maintainers cannot own refreshes, retain the document as a clearly dated draft or do not commit it.

Refresh after material change or before reuse

Do not invent a universal expiry period. Repository change rates and risk differ. Trigger a refresh when the atlas is reused for onboarding or planning and its commit context no longer matches, or when a material change affects its claims. Material changes include altered entry points, manifests, task commands, test configuration, data boundaries, external integrations, ownership, deployment wiring or active instruction files.

1. Identify the old frame. Read the recorded commit, scope, review date and unresolved unknowns.
2. Compare repository change. Inspect human-reviewed diffs between the recorded commit and the current target, concentrating on cited paths and configuration.
3. Revalidate active instructions. Check current AGENTS.md and AGENTS.override.md scope and conflicts before another Codex pass.
4. Repeat the boundary checks. Confirm the Git root, local sandbox, approval posture, writable roots and no-network requirement using current Codex documentation and session status.
5. Rerun only what changed. A changed test configuration may require command and test-matrix reconciliation, not a wholesale rewrite of unrelated directory descriptions.
6. Repeat leakage and command-provenance review. New repository content can introduce both stale commands and sensitive output.
7. Obtain owner answers again where needed. An earlier answer may no longer apply after team or system changes.
8. Record the new frame and approval state. Preserve meaningful unknowns rather than copying an old confidence label.

The decision rule is evidence-sensitive: refresh the affected sections when change can invalidate them; perform a broader reconciliation when root structure, runtime composition or instructions have materially shifted. A cosmetic documentation edit does not automatically require a full rerun, while a small manifest change can.

Recover from common failure modes

If Codex itself appears unavailable, current service status can be one troubleshooting input, not proof about a particular account or an availability commitment. The status page was observed on 2 October 2026, but such a snapshot is neither a service-level agreement nor durable evidence. Check the live status page and account-specific controls at the time of use.

Frequently asked questions

Can Codex inspect a repository without changing files?

OpenAI’s security documentation describes a read-only sandbox and the explicit non-interactive combination --sandbox read-only --ask-for-approval never. OpenAI’s non-interactive documentation also describes codex exec final-message output on standard output, which the reader’s shell can redirect to a file. In this workflow, the shell creates docs/codex-atlas/REPOSITORY_ATLAS.md; Codex is not granted repository write access.

This boundary does not mean that every command is safe or that no information can be disclosed to the selected service. Do not include secrets or untrusted sensitive data in prompts, and do not enable network, web, apps, connectors, MCP, workspace-write or bypass options to overcome missing evidence.

Is Codex CLI the same as the OpenAI API?

No. The Codex CLI is the local terminal surface used here. OpenAI also provides other Codex surfaces and the OpenAI application programming interface (API), which have distinct authentication, billing and operational contexts. The tutorial leads with ChatGPT sign-in for local CLI use. API-key authentication is a separate option documented by OpenAI; Platform billing and settings apply, and a key must never be placed in an atlas, prompt, screenshot or repository file.

Plan eligibility, usage, rollout and workspace controls can change. Follow the choices shown for the relevant account rather than assuming that local CLI access implies Codex Cloud access or API credit.

Should the atlas create an AGENTS.md file?

No. The atlas inventories active instruction files and checks their factual statements against repository evidence. It does not create or replace AGENTS.md, resolve governance authority, or convert onboarding observations into durable agent rules. Maintainers may later propose concise, accurate guidance through their normal review process, but that is a separate task with separate approval.

What data controls apply to personal and managed use?

They are account-dependent. The OpenAI Help Centre material reviewed on 2 October 2026 says that, for personal ChatGPT plans, the “Improve the model for everyone” setting applies to Codex tasks, while a separate “Include environments” setting concerns additional context from Codex environments. Managed Business, Enterprise, Education and Healthcare workspace content is excluded from training by default according to that source, although workspace retention, access and other organisational policies still apply.

Inspect the current setting and policy relevant to the actual account before scanning a sensitive repository. Do not infer managed-workspace treatment from a personal account, assume one setting changes another, or make the blanket claim that code is never used for training. Human privacy and security review is required where repository content is sensitive or regulated.

Finish with evidence, corrections and explicit unknowns

Codex repository onboarding should end with a human-reviewed evidence map, not autonomous certainty. A useful repository atlas identifies its repository and commit context, cites paths for material claims, distinguishes configured commands from executed results, truncates execution paths where evidence ends, names external boundaries without crossing them, and preserves unknown ownership rather than inventing an answer.

The final human decision is visible: reject, revise, accept as a dated draft, or intentionally add and commit after review. That decision must account for secret-like output, active instructions, command provenance, test relationships and consequential domain risks. Read-only permissions reduce local action authority, but they do not replace privacy judgement, security review, maintainership or architectural governance.

When the repository changes materially or the atlas is reused for onboarding, refresh the affected evidence and review it again. The deliverable is valuable precisely because it says what was observed, where it was observed, what a maintainer corrected and what remains unknown.

Useful Links

• Codex CLI
• Codex approvals and security
• Codex non-interactive mode
• Codex AGENTS.md configuration
• Codex best practices
• Using Codex with a ChatGPT plan
• Codex authentication
• Data controls in ChatGPT
• OpenAI status