diff --git a/AGENTS.md b/AGENTS.md
index 9da9ecd1a..762929497 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,47 +1,92 @@
-# Ralph Agent Instructions
+# Ralph Codex Workbench
 
-## Overview
+This repo is the upstream Ralph source plus a local Codex adaptation workbench.
 
-Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context.
+Use it for two things:
 
-## Commands
+- understanding the original Ralph behavior from `CLAUDE.md`, `ralph.sh`,
+  `skills/prd/SKILL.md`, and `skills/ralph/SKILL.md`
+- building and validating the Codex-native adaptation without losing fidelity to the
+  original one-story loop
 
-```bash
-# Run the flowchart dev server
-cd flowchart && npm run dev
+## Read order
 
-# Build the flowchart
-cd flowchart && npm run build
+1. Read `README.md`.
+2. Read:
+   - `CLAUDE.md`
+   - `skills/prd/SKILL.md`
+   - `skills/ralph/SKILL.md`
+   - `ralph.sh`
+   - `prd.json.example`
+3. Read:
+   - `docs/product/README.md`
+   - `docs/product/01_prd.md`
+   - `docs/product/02_hld.md`
+   - `docs/product/03_lld.md`
+4. For current adaptation state and handoff context, read:
+   - `docs/issues/0000-discovery-journal.md`
+   - `docs/issues/0001-upstream-behavior-audit.md`
 
-# Run Ralph with Amp (default)
-./ralph.sh [max_iterations]
+## Local Codex skills
 
-# Run Ralph with Claude Code
-./ralph.sh --tool claude [max_iterations]
-```
+Use the installed local Codex skills instead of re-deriving the workflow from scratch
+every time:
 
-## Key Files
+- `ralph-prd`
+- `ralph-loop`
 
-- `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`)
-- `prompt.md` - Instructions given to each AMP instance
--  `CLAUDE.md` - Instructions given to each Claude Code instance
-- `prd.json.example` - Example PRD format
-- `flowchart/` - Interactive React Flow diagram explaining how Ralph works
+These are the Codex-native equivalents of:
 
-## Flowchart
+- upstream `skills/prd/SKILL.md`
+- upstream `CLAUDE.md` plus `skills/ralph/SKILL.md`
 
-The `flowchart/` directory contains an interactive visualization built with React Flow. It's designed for presentations - click through to reveal each step with animations.
+## Core behavior to preserve
 
-To run locally:
-```bash
-cd flowchart
-npm install
-npm run dev
-```
+- one story per iteration
+- `prd.json` is the task ledger
+- `progress.txt` is append-only memory
+- reusable patterns belong at the top of `progress.txt`
+- nearby `AGENTS.md` files should capture genuinely reusable local knowledge
+- commit only after checks pass
+- output `COMPLETE` only when all stories pass
 
-## Patterns
+## Doc routing
 
-- Each iteration spawns a fresh AI instance (Amp or Claude Code) with clean context
-- Memory persists via git history, `progress.txt`, and `prd.json`
-- Stories should be small enough to complete in one context window
-- Always update AGENTS.md with discovered patterns for future iterations
+- `docs/product/`
+  - Codex adaptation specs
+- `docs/issues/`
+  - behavior mismatches, discoveries, and the UTC handoff journal
+- `docs/tests/`
+  - validation procedures and adaptation checks
+- `docs/tasks/`
+  - bounded adaptation work items
+- `docs/tasks/done/`
+  - completed work records
+- `docs/gaps/`
+  - unresolved runtime or product gaps, especially the future standalone Codex runner
+
+## Handoff discipline
+
+After each meaningful work loop, append a UTC entry to:
+
+- `docs/issues/0000-discovery-journal.md`
+
+Minimum fields:
+
+- `utc_timestamp`
+- `focus`
+- `what_was_done`
+- `files_or_areas_touched`
+- `what_changed_in_understanding`
+- `next_step`
+
+## Important constraints
+
+- Keep the upstream file contract unchanged in the first pass:
+  - `prd.json`
+  - `progress.txt`
+  - `tasks/prd-<feature>.md`
+- The Codex adaptation should stay faithful to Ralph, not become a generic autonomous
+  agent framework.
+- There is no confirmed local `codex` CLI/runtime contract here yet, so the standalone
+  loop runner remains a documented future gap rather than an implemented shell loop.
diff --git a/docs/gaps/0001-codex-runner-gap.md b/docs/gaps/0001-codex-runner-gap.md
new file mode 100644
index 000000000..1eb32c9ed
--- /dev/null
+++ b/docs/gaps/0001-codex-runner-gap.md
@@ -0,0 +1,25 @@
+# Codex Runner Gap
+
+## Missing piece
+
+Ralph’s upstream `ralph.sh` repeatedly spawns `amp` or `claude` non-interactively.
+
+There is no confirmed local `codex` CLI/runtime contract available in this environment
+to replace that behavior 1:1 yet.
+
+## What is already solved
+
+- Codex-native PRD generation skill
+- Codex-native one-story loop skill
+- repo-local Codex workbench documentation
+
+## What remains for future work
+
+- define the invocation contract for a standalone Codex runner
+- decide how the runner executes repeated isolated iterations
+- preserve:
+  - max-iteration limit
+  - branch discipline
+  - progress logging
+  - story completion updates
+  - `COMPLETE` stop condition
diff --git a/docs/gaps/README.md b/docs/gaps/README.md
new file mode 100644
index 000000000..82cf2a5f4
--- /dev/null
+++ b/docs/gaps/README.md
@@ -0,0 +1,13 @@
+# Gaps
+
+Use this folder for:
+
+- missing runtime pieces
+- unresolved product or workflow questions
+- future work that should not be silently improvised
+
+When a gap is resolved, move the result into:
+
+- `docs/product/`
+- `docs/issues/`
+- or `docs/tasks/done/`
diff --git a/docs/issues/0000-discovery-journal.md b/docs/issues/0000-discovery-journal.md
new file mode 100644
index 000000000..a91c5603f
--- /dev/null
+++ b/docs/issues/0000-discovery-journal.md
@@ -0,0 +1,53 @@
+# Ralph Codex Adaptation Journal
+
+## 2026-04-08T11:04:42Z
+
+### Focus
+
+Clone the upstream Ralph repo and turn it into a documented Codex adaptation workbench
+with local skills and an explicit future-runner gap.
+
+### What was done
+
+- cloned `snarktank/ralph` into `/home/shetautnetjerheru/ralph`
+- inspected upstream:
+  - `README.md`
+  - `CLAUDE.md`
+  - `skills/prd/SKILL.md`
+  - `skills/ralph/SKILL.md`
+  - `ralph.sh`
+  - `prd.json.example`
+- created local Codex skills:
+  - `~/.codex/skills/ralph-prd/SKILL.md`
+  - `~/.codex/skills/ralph-loop/SKILL.md`
+- turned the cloned repo into a Codex workbench with:
+  - root `AGENTS.md`
+  - `docs/product/`
+  - `docs/issues/`
+  - `docs/tests/`
+  - `docs/tasks/`
+  - `docs/gaps/`
+
+### Files or areas touched
+
+- `AGENTS.md`
+- `docs/product/*`
+- `docs/issues/*`
+- `docs/tests/*`
+- `docs/tasks/*`
+- `docs/gaps/*`
+- `~/.codex/skills/ralph-prd/SKILL.md`
+- `~/.codex/skills/ralph-loop/SKILL.md`
+
+### What changed in understanding
+
+The key translation boundary is now clear:
+
+- Codex can preserve Ralph’s one-story workflow as a skill/workbench model today
+- the standalone autonomous runner is a separate runtime problem because there is no
+  local `codex` CLI/runtime contract available here yet
+
+### Next step
+
+Validate the local Codex skills against the upstream files line by line and record any
+behavior drift in `docs/issues/0001-upstream-behavior-audit.md`.
diff --git a/docs/issues/0001-upstream-behavior-audit.md b/docs/issues/0001-upstream-behavior-audit.md
new file mode 100644
index 000000000..6397f6cd1
--- /dev/null
+++ b/docs/issues/0001-upstream-behavior-audit.md
@@ -0,0 +1,24 @@
+# Upstream Behavior Audit
+
+This note tracks how the Codex adaptation maps to upstream Ralph behavior.
+
+## Preserved directly
+
+- one story per iteration
+- `prd.json` as the execution ledger
+- `progress.txt` as append-only memory
+- codebase-pattern consolidation at the top of `progress.txt`
+- nearby `AGENTS.md` updates for reusable local knowledge
+- stop with `COMPLETE` only when all stories pass
+
+## Adapted for Codex
+
+- upstream `CLAUDE.md` is translated into the `ralph-loop` skill rather than used as a
+  raw prompt file
+- upstream PRD generation is translated into the `ralph-prd` skill
+- the standalone shell runner is documented as a future gap rather than implemented
+
+## Current known gap
+
+- no local non-interactive `codex` runtime contract exists here, so `ralph.sh` cannot
+  be replaced 1:1 yet
diff --git a/docs/issues/README.md b/docs/issues/README.md
new file mode 100644
index 000000000..b9b963204
--- /dev/null
+++ b/docs/issues/README.md
@@ -0,0 +1,12 @@
+# Issues and Journal
+
+Use this folder for:
+
+- upstream-to-Codex behavior mismatches
+- adaptation discoveries
+- workflow caveats
+- the UTC handoff journal
+
+Canonical handoff log:
+
+- `0000-discovery-journal.md`
diff --git a/docs/product/01_prd.md b/docs/product/01_prd.md
new file mode 100644
index 000000000..d7fdd1040
--- /dev/null
+++ b/docs/product/01_prd.md
@@ -0,0 +1,46 @@
+# Ralph Codex Adaptation PRD
+
+## Product
+
+Create a Codex-native adaptation of Ralph that preserves the one-story autonomous loop
+discipline and the original file contract.
+
+## Purpose
+
+The adaptation should:
+
+- preserve Ralph’s one-story-per-iteration model
+- preserve `prd.json` as the execution ledger
+- preserve `progress.txt` as append-only memory
+- preserve nearby `AGENTS.md` updates as reusable repo knowledge
+- let Codex users run the Ralph workflow without depending on Claude-specific prompts
+
+## Users
+
+- Codex users running Ralph-style iterative development
+- repo owners who want a PRD-to-loop workflow in Codex
+- future implementers of a standalone Codex runner
+
+## Required capabilities
+
+- PRD generation into `tasks/prd-<feature>.md`
+- PRD-to-`prd.json` conversion
+- one-story loop discipline against `prd.json`
+- progress and pattern logging in `progress.txt`
+- nearby `AGENTS.md` learning capture
+- branch/check/commit discipline
+
+## Non-goals for this pass
+
+- replacing Ralph’s file contract
+- inventing a different task ledger
+- implementing a standalone Codex CLI runner before a runtime contract exists
+- turning Ralph into a generic autonomous framework
+
+## Success criteria
+
+- local Codex skills exist for PRD generation and the one-story loop
+- the cloned Ralph repo documents the Codex adaptation clearly
+- every major behavior from the upstream Claude/Amp workflow is either:
+  - implemented as a local Codex skill/workflow
+  - or recorded as an explicit future runner gap
diff --git a/docs/product/02_hld.md b/docs/product/02_hld.md
new file mode 100644
index 000000000..df7d6f922
--- /dev/null
+++ b/docs/product/02_hld.md
@@ -0,0 +1,62 @@
+# Ralph Codex Adaptation HLD
+
+## System role
+
+The Codex adaptation is a workflow translation layer over Ralph’s existing model.
+
+It keeps Ralph’s core state surfaces:
+
+- `tasks/prd-<feature>.md`
+- `prd.json`
+- `progress.txt`
+- nearby `AGENTS.md`
+
+## Main subsystems
+
+### PRD authoring
+
+- local skill: `ralph-prd`
+- generates markdown PRDs in `tasks/`
+
+### Execution loop
+
+- local skill: `ralph-loop`
+- reads `prd.json`
+- chooses one pending story
+- implements only that story
+- runs checks
+- updates progress and story state
+
+### Progress memory
+
+- `progress.txt` remains append-only
+- `Codebase Patterns` stays near the top and accumulates reusable knowledge
+
+### Local knowledge capture
+
+- nearby `AGENTS.md` files capture durable local conventions and gotchas
+
+### Future standalone runner
+
+- a later runtime wrapper can drive repeated Codex iterations
+- it should orchestrate `ralph-loop`, not redefine the workflow
+
+## Data flow
+
+1. create markdown PRD
+2. convert PRD into `prd.json`
+3. start one iteration
+4. read `prd.json` and `progress.txt`
+5. select highest-priority incomplete story
+6. implement exactly one story
+7. run checks
+8. if passing, commit and mark story complete
+9. append progress
+10. repeat until `COMPLETE`
+
+## Invariants
+
+- one story at a time
+- no completion on failed checks
+- file contract remains unchanged
+- reusable knowledge goes into `progress.txt` and nearby `AGENTS.md`
diff --git a/docs/product/03_lld.md b/docs/product/03_lld.md
new file mode 100644
index 000000000..725fa57f4
--- /dev/null
+++ b/docs/product/03_lld.md
@@ -0,0 +1,49 @@
+# Ralph Codex Adaptation LLD
+
+## Local skills
+
+### `ralph-prd`
+
+Responsibilities:
+
+- ask only essential clarifying questions
+- generate a markdown PRD
+- keep stories small and verifiable
+- write to `tasks/prd-<feature>.md`
+
+### `ralph-loop`
+
+Responsibilities:
+
+- read `prd.json`
+- read `progress.txt`
+- ensure branch alignment with `branchName`
+- pick highest-priority `passes: false` story
+- implement exactly one story
+- run repo checks
+- update nearby `AGENTS.md` if reusable learnings were found
+- commit with `feat: [Story ID] - [Story Title]`
+- set `passes: true`
+- append progress
+- emit `COMPLETE` only when all stories pass
+
+## Future standalone runner spec
+
+The later runner should:
+
+- accept target repo path and max iterations
+- repeatedly invoke the Ralph loop behavior
+- stop on `COMPLETE`
+- stop on max-iteration exhaustion
+- preserve the same `prd.json` and `progress.txt` contract
+
+Because no local `codex` CLI/runtime contract is available here, the runner is a future
+runtime concern rather than a current implementation target.
+
+## Validation targets
+
+- story sizing rules match upstream Ralph
+- `prd.json` shape stays compatible with `prd.json.example`
+- progress append format stays stable
+- codebase pattern consolidation behavior is preserved
+- nearby `AGENTS.md` update policy matches upstream `CLAUDE.md`
diff --git a/docs/product/04_sources_crosswalk.md b/docs/product/04_sources_crosswalk.md
new file mode 100644
index 000000000..bd2e0b2f3
--- /dev/null
+++ b/docs/product/04_sources_crosswalk.md
@@ -0,0 +1,25 @@
+# Ralph Codex Sources Crosswalk
+
+## Upstream sources -> Codex adaptation
+
+- `CLAUDE.md`
+  - execution-loop behavior and progress discipline
+- `skills/prd/SKILL.md`
+  - PRD generation behavior
+- `skills/ralph/SKILL.md`
+  - PRD-to-`prd.json` conversion rules and story sizing
+- `ralph.sh`
+  - outer iteration model and stop condition
+- `prd.json.example`
+  - execution-ledger shape
+
+## Local outputs
+
+- local skill `ralph-prd`
+  - upstream PRD behavior translated for Codex
+- local skill `ralph-loop`
+  - upstream Claude loop behavior translated for Codex
+- `docs/product/*`
+  - implementation-facing Codex adaptation spec
+- `docs/gaps/0001-codex-runner-gap.md`
+  - future standalone runner specification gap
diff --git a/docs/product/README.md b/docs/product/README.md
new file mode 100644
index 000000000..0f3c0f328
--- /dev/null
+++ b/docs/product/README.md
@@ -0,0 +1,36 @@
+# Ralph Codex Adaptation Docs
+
+This folder is the implementation-facing spec layer for the local Codex adaptation of
+Ralph.
+
+## What this folder is for
+
+Use these docs to understand how Ralph’s upstream Claude/Amp workflow is being
+translated into Codex:
+
+- `01_prd.md`
+- `02_hld.md`
+- `03_lld.md`
+- `04_sources_crosswalk.md`
+
+## What this folder is not
+
+This is not the upstream source of truth.
+
+Upstream behavior still comes from:
+
+- `CLAUDE.md`
+- `ralph.sh`
+- `skills/prd/SKILL.md`
+- `skills/ralph/SKILL.md`
+- `prd.json.example`
+
+## Current adaptation boundary
+
+The current pass delivers:
+
+- local Codex skills
+- repo-local Codex workflow guidance
+- a documented future standalone runner spec gap
+
+It does not yet deliver a runnable non-interactive Codex loop runner.
diff --git a/docs/tasks/README.md b/docs/tasks/README.md
new file mode 100644
index 000000000..2280d366b
--- /dev/null
+++ b/docs/tasks/README.md
@@ -0,0 +1,9 @@
+# Tasks
+
+Use this folder for bounded adaptation work items.
+
+- active work items live here
+- completed work items move to `done/`
+- if a task reveals a product/runtime hole, add or update a gap doc
+- if a task reveals behavioral drift, update `docs/issues/`
+- append a UTC journal entry after meaningful progress
diff --git a/docs/tasks/done/0001-initial-codex-adaptation.md b/docs/tasks/done/0001-initial-codex-adaptation.md
new file mode 100644
index 000000000..6c924d94a
--- /dev/null
+++ b/docs/tasks/done/0001-initial-codex-adaptation.md
@@ -0,0 +1,16 @@
+# Initial Codex Adaptation
+
+## Goal
+
+Create the first Codex-native Ralph adaptation layer.
+
+## Acceptance criteria
+
+- clone the upstream repo locally
+- create Codex skills for PRD creation and one-story execution
+- add a repo-local Codex workbench structure
+- document the future standalone runner gap
+
+## Current status
+
+Completed.
diff --git a/docs/tasks/done/README.md b/docs/tasks/done/README.md
new file mode 100644
index 000000000..757167655
--- /dev/null
+++ b/docs/tasks/done/README.md
@@ -0,0 +1,3 @@
+# Done Tasks
+
+Completed adaptation work records live here.
diff --git a/docs/tests/0001-codex-skill-validation.md b/docs/tests/0001-codex-skill-validation.md
new file mode 100644
index 000000000..f3abdb5d3
--- /dev/null
+++ b/docs/tests/0001-codex-skill-validation.md
@@ -0,0 +1,18 @@
+# Codex Skill Validation
+
+Validate the Codex adaptation against upstream Ralph behavior.
+
+## Checkpoints
+
+- `ralph-prd` preserves:
+  - right-sized story guidance
+  - verifiable acceptance criteria
+  - markdown PRD output in `tasks/`
+- `ralph-loop` preserves:
+  - one story per iteration
+  - branch alignment with `branchName`
+  - progress append discipline
+  - nearby `AGENTS.md` update policy
+  - `COMPLETE` stop condition
+- `prd.json.example` remains the file-shape reference
+- `docs/gaps/0001-codex-runner-gap.md` clearly states what is not implemented yet
diff --git a/docs/tests/README.md b/docs/tests/README.md
new file mode 100644
index 000000000..90a5e4492
--- /dev/null
+++ b/docs/tests/README.md
@@ -0,0 +1,8 @@
+# Tests and Validation Notes
+
+Use this folder for:
+
+- adaptation fidelity checks
+- repeatable validation procedures
+- skill-vs-upstream comparisons
+- future runner validation notes