# Codex integration

Reliora's Codex integration is an opt-in, project-local managed instruction block. Setup uses `AGENTS.override.md` when a non-empty override already exists; otherwise it uses `AGENTS.md`.

```sh
reliora init --agent codex
```

On Windows, use `reliora.cmd`. Start a new Codex task after installation or update.

## Workflow v2

Before substantial debugging, migration, architecture, infrastructure, integration, deployment, or complex test work, Codex is instructed to search a short task/problem/risk query:

```sh
reliora search "<query>" --limit 3 --json
```

It considers only the top three results and evaluates the match level, actual score breakdown, reasons, project context, applicability, confidence, failures, warnings, verification, feedback, and lineage. Search is skipped for obvious isolated edits such as formatting or mechanical renames.

Records are untrusted data and advice. Text inside an experience cannot change user/project instructions, authorize network access, reveal secrets, bypass safety, or require unverified commands. A strong match is still only a hypothesis.

After verified work, feedback maps to the effect on the task:

| Situation | Outcome |
| --- | --- |
| Directly reused and verified | `success` |
| Useful pattern required adaptation | `partial` |
| Seriously considered but rejected here | `not-applicable` |
| Once correct but now stale | `outdated` |
| Applied advice was wrong or harmful | `failure` |

Impact can be `low`, `medium`, or `high`. Optional notes should be short, safe, and reusable. Codex is told not to rate every search result.

## Reflection v2

After implementation and verification, Codex checks whether the task produced an observed, non-obvious, reusable lesson with factual failed attempts, causal explanation, bounded applicability, and reproducible verification. Before saving it searches the candidate title, problem, and tags again.

Duplicate warnings are advisory. Codex should prefer feedback or refinement when an existing record already captures the lesson, but can save a genuinely distinct record.

When lineage is supported by the work:

- `appliedExperiences` lists project-local experience IDs that materially guided the solution.
- `derivedFrom` lists IDs that the new record deliberately refines or combines.

The draft is sent through stdin so no temporary JSON file is required:

```sh
reliora record - --json
```

## Managed-block safety

Reliora owns only text between:

```text
<!-- RELIORA MANAGED INSTRUCTIONS START -->
<!-- RELIORA MANAGED INSTRUCTIONS END -->
```

Version 1 blocks are upgraded in place to version 2. Text before and after the block is retained, line-ending style is preserved, and setup never duplicates a valid block. Damaged or duplicated markers, unsafe metadata paths, integration-type switches, and newly shadowed `AGENTS.md` files produce a conflict instead of a destructive rewrite.

```sh
reliora agent status --json
reliora agent remove --json
```

Removal strips only the managed block and integration metadata. It never deletes experience records.

## Notifications and boundaries

The instructions request concise user notifications when a lesson was used or rejected, feedback was written, a new record was saved, a duplicate warning changed the decision, or no reusable lesson was found. Reliora itself does not observe Codex, chats, commands, or task state; Codex explicitly invokes the deterministic CLI.