codexkit 1.0.0

package/.codex/agents/shipper.toml

@@ -0,0 +1,69 @@
+# Shipper Agent — Release preparation and PR workflow
+# Codexkit shipper agent definition
+
+description = "Prepares and validates code for shipping — PR prep, changelog, final verification."
+model = "gpt-5.3-codex"
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+You are Codex in shipper mode. Your role is to prepare code for release.
+
+## Context Loading
+
+At session start, read these project context docs:
+- `.codex/context/current-priorities.md` — what matters now
+- `.codex/context/conventions.md` — coding norms and patterns
+After significant work, update:
+- `.codex/context/worklog.md` — append session progress
+
+# Shipper Agent
+
+**Purpose**: Release engineer — you verify, package, and ship.
+
+## Identity
+
+You are a shipping specialist. You ensure code is verified, documented,
+and ready for merge. You are the last gate before production.
+
+## Ship Checklist
+
+1. **Verify** — Run full verification suite (typecheck, lint, test, build)
+2. **Diff Review** — Review all staged changes for completeness
+3. **Changelog** — Update changelog/release notes if applicable
+4. **PR Prep** — Write clear PR title, description, and labels
+5. **Final Check** — Confirm no unintended files, no secrets, clean diff
+
+## Constraints
+
+- Never skip verification — run all checks before declaring ready
+- Never force push to main/master
+- Never bypass git hooks
+- Stage only files you modified (never git add . or git add -A)
+- Ask before destructive operations
+
+## PR Description Format
+
+```
+## Summary
+[1-2 sentences: what and why]
+
+## Changes
+- [bullet list of concrete changes]
+
+## Testing
+- [how this was verified]
+
+## Checklist
+- [ ] Tests pass
+- [ ] Types check
+- [ ] Lint clean
+- [ ] No secrets exposed
+```
+
+## Beads Integration
+
+If using beads workflow:
+1. br show <id> — verify bead state before shipping
+2. Complete all work and verification
+3. br close <id> --reason "..." — only after user approval
+"""

package/.codex/agents/vision.toml

@@ -0,0 +1,69 @@
+# Vision Agent — UI/UX analysis and accessibility specialist
+# Codexkit vision agent definition
+
+description = "Visual analysis specialist for UI/UX review, accessibility audits, design consistency, and grounded inspiration scouting."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are Codex in vision mode. Your role is to analyze visual/UI quality and scout grounded design direction when asked.
+
+## Context Loading
+
+At session start, read these project context docs:
+- `.codex/context/current-priorities.md` — what matters now
+- `.codex/context/conventions.md` — coding norms and patterns
+- `.codex/context/architecture.md` — system boundaries
+- `.codex/context/decision-log.md` — past decisions (check before proposing changes)
+
+# Vision Agent
+
+**Purpose**: Visual critic and inspiration scout — you see what others miss, and you can connect local UI patterns to strong external references.
+
+## Identity
+
+You are a read-only visual analysis specialist. You output actionable visual findings
+and prioritized recommendations. You do NOT write production code.
+
+## Constraints
+
+- Read-only: you may read files, analyze screenshots, and inspect UI code
+- Never edit, write, commit, push, or delete
+- Always provide concrete, actionable feedback
+- Reference WCAG guidelines when discussing accessibility
+
+## Analysis Process
+
+1. **Scope** — Understand what's being reviewed (screenshot, component, page)
+2. **Visual Hierarchy** — Layout, spacing, typography, color contrast
+3. **Accessibility** — WCAG 2.1 AA compliance, keyboard navigation, screen readers
+4. **Consistency** — Design system adherence, pattern consistency
+5. **Inspiration Fit** — When doing reference scouting, tie external examples back to local patterns
+6. **Responsiveness** — Mobile, tablet, desktop behavior
+7. **Report** — Structured findings with severity and fix suggestions or reference rationale
+
+## Severity Levels
+
+| Level | Meaning | Example |
+|-------|---------|---------|
+| 🔴 Critical | Accessibility violation, unusable UI | Missing alt text, no keyboard nav |
+| 🟠 Major | Poor UX, inconsistent design | Wrong spacing, broken layout |
+| 🟡 Minor | Visual polish, small inconsistency | Slightly off color, minor alignment |
+| 🔵 Nit | Suggestion, preference | Font weight, subtle shadow |
+
+## Output Format
+
+For each finding:
+- **Element**: What component/area
+- **Severity**: 🔴/🟠/🟡/🔵
+- **Issue**: What's wrong
+- **Fix**: Concrete suggestion with CSS/HTML if applicable
+- **Standard**: WCAG reference if accessibility-related
+
+For inspiration scouting tasks:
+- **Reference**: title + verified URL
+- **Why it fits**: match to local product/patterns
+- **Borrow**: what to adapt
+- **Avoid**: what not to copy blindly
+"""

package/.codex/config.toml

@@ -0,0 +1,146 @@
+# Codexkit — Project Configuration
+# Target: OpenAI Codex CLI (@openai/codex)
+#
+# Usage:
+#   codex --profile <name>       # Switch profiles
+#   codex --profile default      # Default daily driver
+#
+# Layers (lowest → highest priority):
+#   1. This file (.codex/config.toml)
+#   2. ~/.codex/config.toml (user-level)
+#   3. CLI flags (--model, --sandbox, etc.)
+# ─── Profiles ───────────────────────────────────────────────────────
+#
+# 6 presets: default, explore, plan, build, review, ship
+#
+# | Profile   | Model          | Sandbox         | Approval   |
+# |-----------|----------------|-----------------|------------|
+# | default   | gpt-5.3-codex  | workspace-write | on-request |
+# | explore   | gpt-5.3-codex  | read-only       | never      |
+# | plan      | gpt-5.4        | read-only       | never      |
+# | build     | gpt-5.3-codex  | workspace-write | on-request |
+# | review    | gpt-5.4        | read-only       | never      |
+# | ship      | gpt-5.3-codex  | workspace-write | on-request |
+
+[profiles.default]
+model = "gpt-5.3-codex"
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+
+[profiles.explore]
+model = "gpt-5.3-codex"
+sandbox_mode = "read-only"
+approval_policy = "never"
+
+[profiles.plan]
+model = "gpt-5.4"
+sandbox_mode = "read-only"
+approval_policy = "never"
+
+[profiles.build]
+model = "gpt-5.3-codex"
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+
+[profiles.review]
+model = "gpt-5.4"
+sandbox_mode = "read-only"
+approval_policy = "never"
+
+[profiles.ship]
+model = "gpt-5.3-codex"
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+
+# ─── Agents ─────────────────────────────────────────────────────────
+#
+# Multi-agent roles. Each role has a .toml config in .codex/agents/.
+# Built-in roles (default, explorer, worker) are always available.
+# See: https://developers.openai.com/codex/config-advanced/#agent-roles
+
+[agents]
+max_threads = 6
+max_depth = 1
+
+[agents.planner]
+description = "Plans implementation approach with goal-backward decomposition before coding begins."
+config_file = "./agents/planner.toml"
+
+[agents.reviewer]
+description = "Reviews code quality, correctness, security, and test coverage."
+config_file = "./agents/reviewer.toml"
+
+[agents.shipper]
+description = "Prepares and validates code for shipping — PR prep, changelog, final verification."
+config_file = "./agents/shipper.toml"
+
+[agents.scout]
+description = "Research specialist for library docs, API references, and external patterns."
+config_file = "./agents/scout.toml"
+
+[agents.vision]
+description = "Visual analysis specialist for UI/UX review, accessibility audits, and design consistency."
+config_file = "./agents/vision.toml"
+
+[agents.debugger]
+description = "Bug investigation specialist — finds root causes through systematic hypothesis testing."
+config_file = "./agents/debugger.toml"
+
+[agents.refactorer]
+description = "Safe refactoring specialist — improves code structure while preserving behavior."
+config_file = "./agents/refactorer.toml"
+
+[agents.builder]
+description = "Primary implementation agent — writes production code with verification and deviation rules."
+config_file = "./agents/builder.toml"
+
+[agents.runner]
+description = "Lightweight shell, git, and filesystem operations for scoped execution tasks."
+config_file = "./agents/runner.toml"
+
+[agents.general]
+description = "Small, well-defined implementation subtasks with limited scope."
+config_file = "./agents/general.toml"
+
+[agents.painter]
+description = "Image generation and visual asset planning specialist."
+config_file = "./agents/painter.toml"
+
+# ─── Hooks ──────────────────────────────────────────────────────────
+#
+# Codex CLI supports: AfterAgent, AfterToolUse
+# Format: [[hooks]] array-of-tables with event + command keys.
+# See: https://developers.openai.com/codex/config-reference/
+
+[[hooks]]
+event = "AfterAgent"
+command = ".codex/hooks/after_agent.sh"
+
+[[hooks]]
+event = "AfterToolUse"
+command = ".codex/hooks/after_tool_use.sh"
+# ── MCP Servers ───────────────────────────────────────────
+# Only project-specific MCPs go here. User-level MCPs (context7, exa, ref)
+# should be configured in ~/.codex/config.toml to avoid merge conflicts.
+# See .codex/mcp/README.md for setup instructions.
+
+[mcp_servers.tilth]
+command = "npx"
+args = ["-y", "tilth", "--mcp", "--edit"]
+startup_timeout_sec = 30.0
+tool_timeout_sec = 60.0
+# ─── History ────────────────────────────────────────────────────────
+
+[history]
+persistence = "save-all"
+# max_bytes = 10485760  # 10MB limit
+
+# ─── Feature Flags ─────────────────────────────────────────────────
+
+[features]
+multi_agent = true
+# memories = true
+# Experimental / watchlist only:
+# - enable only after public Codex docs make the feature stable enough for your workflow
+# - do not treat it as a replacement for `.codex/context/` or `.codex/memory/`
+# - keep repo-visible docs as the canonical source of truth even if native memory matures

package/.codex/context/architecture.md

@@ -0,0 +1,66 @@
+# Architecture
+
+> System boundaries, key modules, and data flow.
+
+---
+
+## System Overview
+
+Codexkit is a professional configuration framework for OpenAI Codex CLI. It provides curated profiles, agents, skills, prompts, context management, hooks, and MCP integrations as a pure configuration kit — no custom runtime, no build step.
+
+## Key Modules
+
+| Module    | Responsibility                              | Key Files                                 |
+| --------- | ------------------------------------------- | ----------------------------------------- |
+| Config    | Runtime behavior (model, sandbox, approval) | `.codex/config.toml`                      |
+| Agents    | Custom agent role definitions               | `.codex/agents/*.toml`                    |
+| Skills    | Reusable procedure playbooks                | `.codex/skills/*/SKILL.md` |
+| Prompts   | Workflow command templates                  | `.codex/prompts/*.md`                     |
+| Context   | Curated project knowledge                   | `.codex/context/*.md`                     |
+| Hooks     | Lifecycle automation                        | `.codex/hooks/*.sh`                       |
+| MCP       | External tool integrations                  | `.codex/mcp/*.toml.example`               |
+| Templates | Installation templates                      | `templates/global/`, `templates/project/` |
+
+## Data Flow
+
+```
+Session Start → Codex loads AGENTS.md + config.toml → reads .codex/context/ + .codex/memory/project/
+    ↓
+Agent Turn → implements task → AfterToolUse hook fires
+    ↓
+Turn Complete → AfterAgent hook fires → appends to worklog
+    ↓
+Session End → manual /prompts:handoff → saves progress to context docs + memory state
+```
+
+## External Dependencies
+
+| Dependency       | Purpose                   | Required |
+| ---------------- | ------------------------- | -------- |
+| Codex CLI        | Runtime agent engine      | Yes      |
+| Git              | Version control, hooks    | Yes      |
+| Shell (bash/zsh) | Hook scripts              | Yes      |
+| MCP servers      | External tools (optional) | No       |
+| beads_rust (br)  | Task tracking (optional)  | No       |
+
+## Boundaries
+
+### What Codexkit Owns
+
+- Agent role definitions and instructions
+- Skill playbooks and procedures
+- Prompt workflow templates
+- Context document templates
+- Hook automation scripts
+- Installation and upgrade scripts
+
+### What Codexkit Does NOT Own
+
+- Codex CLI runtime behavior (that's OpenAI's)
+- Model selection/availability (provider-dependent)
+- Sandbox enforcement (OS-level, Codex manages)
+- MCP server implementations (third-party)
+
+---
+
+_Last updated: 2026-03-11_

package/.codex/context/conventions.md

@@ -0,0 +1,98 @@
+# Conventions
+
+> Coding norms and repo patterns. Read before writing code.
+
+---
+
+## Language & Framework
+
+- **Primary language**: Markdown, TOML, Shell (Bash)
+- **Framework**: None — pure configuration kit
+- **Runtime**: OpenAI Codex CLI (Rust-based)
+- **Package manager**: N/A (distributed via git clone + shell scripts)
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---|---|---|
+| Files (general) | kebab-case | `install-global.sh` |
+| Agent configs | kebab-case.toml | `planner.toml` |
+| Skills | kebab-case directory | `repo-orientation/SKILL.md` |
+| Prompts | kebab-case.md | `review-codebase.md` |
+| Context docs | kebab-case.md | `current-priorities.md` |
+| Hook scripts | snake_case.sh | `session_start.sh` |
+| Constants (shell) | UPPER_SNAKE_CASE | `MAX_THREADS=6` |
+
+## File Organization
+
+```
+codexkit/
+├── AGENTS.md              # Root-level operating rules
+├── CLAUDE.md              # Project intelligence
+├── .codex/                # All Codex configuration
+│   ├── config.toml        # Single config file
+│   ├── agents/            # One .toml per role
+│   ├── skills/            # One directory per skill
+│   ├── prompts/           # One .md per workflow
+│   ├── context/           # Curated knowledge docs
+│   ├── hooks/             # Lifecycle shell scripts
+│   ├── scripts/           # Hook helper utilities
+│   └── mcp/               # MCP config examples
+├── templates/             # Installation templates
+├── install/               # Installation scripts
+├── docs/                  # User documentation
+└── tests/                 # Validation tests
+```
+
+### Rules
+- One agent definition per TOML file
+- One skill per directory (SKILL.md required)
+- `.codex/skills/` is the canonical skill inventory; install-time bridges must not become a second source of truth
+- One prompt per markdown file
+- Context docs are curated, not auto-generated
+- Hook scripts must be executable (`chmod +x`)
+
+## Skill Format
+
+```markdown
+---
+name: skill-name
+description: >
+  When to use and when NOT to use.
+---
+
+# Skill Name
+
+## When to Use
+## When NOT to Use
+## Procedure
+## Anti-Patterns
+```
+
+## Agent Format
+
+```toml
+description = "One-line purpose"
+model = "gpt-5.x"
+model_reasoning_effort = "high|medium|low"
+sandbox_mode = "read-only|workspace-write"
+developer_instructions = """..."""
+```
+
+## Git Conventions
+
+- **Branch naming**: `feat/`, `fix/`, `chore/`, `docs/`
+- **Commit format**: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`)
+- **PR requirements**: Smoke tests pass, structure validated
+
+## Shell Script Style
+
+- Use `#!/usr/bin/env bash`
+- `set -euo pipefail` at top of every script
+- Quote all variables: `"${VAR}"`
+- Use functions for reusable logic
+- Add `# Description:` comment at top
+
+---
+
+*Last updated: 2026-03-11*

package/.codex/context/current-priorities.md

@@ -0,0 +1,33 @@
+# Current Priorities
+
+> What matters right now. Read at session start.
+
+---
+
+## Active Work
+- Keep shipped prompts, skills, installers, and docs in sync.
+- Preserve safe public packaging for release artifacts.
+- Maintain install, validation, and workflow confidence through release gates.
+
+## Phase Status Snapshot
+- Core scaffold delivered.
+- Agent and workflow inventory shipped.
+- Context and memory conventions established.
+- Current emphasis: release readiness and operational consistency.
+
+## Blockers
+
+- None currently blocking.
+
+## Near-Term Milestones
+- Keep the packaged CLI install path healthy.
+- Keep release documentation accurate.
+- Keep validation and integration coverage current.
+
+## Context for New Sessions
+
+New sessions should prioritize release confidence, install correctness, and documentation consistency over speculative expansion.
+
+---
+
+*Last updated: 2026-03-14*

package/.codex/context/decision-log.md

@@ -0,0 +1,93 @@
+# Decision Log
+
+> ADR-lite architecture decision records. Check before proposing changes.
+
+---
+
+## Decisions
+
+### DLOG-001: Use TOML for all configuration
+
+- **Date**: 2026-03-01
+- **Status**: accepted
+- **Context**: Needed a configuration format for Codex CLI settings. Options: JSON, YAML, TOML.
+- **Decision**: Use TOML exclusively. It's Codex CLI's native format, human-readable, supports comments.
+- **Consequences**: All config in `.codex/config.toml`. Agent definitions in `.toml` files.
+
+### DLOG-002: Skills use SKILL.md with YAML frontmatter
+
+- **Date**: 2026-03-01
+- **Status**: accepted, partially superseded by DLOG-009
+- **Context**: Skills need metadata for discovery + content for procedures.
+- **Decision**: Follow the Codex standard: each skill is a directory with `SKILL.md` YAML frontmatter.
+- **Consequences**: The `SKILL.md` format remains stable even though later install flows may optionally create local discovery bridges.
+
+### DLOG-003: Context-based memory instead of database
+
+- **Date**: 2026-03-01
+- **Status**: accepted
+- **Context**: Codex CLI has no plugin system or persistent memory. Need cross-session persistence.
+- **Decision**: Use curated markdown files in `.codex/context/` for memory. Handoff/resume prompts manage session state.
+- **Consequences**: Canonical memory remains git-tracked markdown. Token budget must stay < 4,000. Any local index must remain derived and disposable, never the source of truth.
+
+### DLOG-010: Allow derived local retrieval indexes as disposable accelerators
+
+- **Date**: 2026-03-15
+- **Status**: accepted
+- **Context**: The file-based memory model works, but repo-local retrieval becomes weaker as durable notes grow. A lightweight local index can improve recall without replacing markdown truth.
+- **Decision**: Permit derived local retrieval artifacts such as SQLite/FTS or JSONL indexes under `.codex/memory/.index/`, provided they are rebuilt from repo-visible markdown and treated as disposable accelerators only.
+- **Consequences**: Repo-visible markdown remains canonical. Local retrieval can improve speed and ranking, but deleting the derived index must never lose durable knowledge.
+
+### DLOG-004: Store skills directly in .agents/skills
+
+- **Date**: 2026-03-01
+- **Status**: superseded by DLOG-009
+- **Context**: Codex discovers skills at `.agents/skills/`.
+- **Decision**: Store all skills directly in `.agents/skills/` per Codex CLI convention (no symlink).
+- **Consequences**: Skill discovery is native and predictable; no symlink maintenance required.
+
+### DLOG-009: Use `.codex/skills/` as canonical inventory with install-time discovery bridge only
+
+- **Date**: 2026-03-12
+- **Status**: accepted
+- **Context**: Codexkit now ships a larger skill inventory with optional `mcp.json` and `references/`. Keeping the curated inventory alongside the rest of project configuration in `.codex/` simplifies install, manifest generation, and documentation.
+- **Decision**: Store shipped skills canonically in `.codex/skills/`. If a target project needs `.agents/skills` for discovery, create that bridge during install only.
+- **Consequences**: The repository no longer ships `.agents/skills/` as a mirrored tree. This supersedes DLOG-004's storage location while preserving optional discovery compatibility in installed projects.
+
+### DLOG-005: Shell-based hooks over complex automation
+
+- **Date**: 2026-03-01
+- **Status**: accepted
+- **Context**: Need lifecycle automation (session start, commit, etc.).
+- **Decision**: Simple bash scripts. No Node.js, no Python, no complex dependencies.
+- **Consequences**: Hooks are lightweight, portable, easy to debug. Limited to what bash can do.
+
+### DLOG-006: Pure configuration kit — no build step
+
+- **Date**: 2026-03-01
+- **Status**: accepted
+- **Context**: Should Codexkit be an npm package, a compiled binary, or a config kit?
+- **Decision**: Pure configuration files distributed via git clone + shell scripts. No build step.
+- **Consequences**: Simple distribution. No compilation needed. Users clone and run install scripts.
+
+### DLOG-007: Six profiles as default workflow modes
+
+- **Date**: 2026-03-01
+- **Status**: accepted
+- **Context**: Users need quick mode-switching for different tasks.
+- **Decision**: Six profiles: default, explore, plan, build, review, ship.
+- **Consequences**: Each profile configures model, sandbox, and approval policy. Users switch with `codex --profile <name>`.
+
+---
+
+### DLOG-008: Workspace-write sandbox as default
+
+- **Date**: 2026-03-01
+- **Status**: accepted
+- **Context**: Codex CLI supports three sandbox modes: read-only, workspace-write, danger-full-access. macOS uses Apple Seatbelt, Linux uses Landlock + seccomp. Need a safe default that allows productive work.
+- **Decision**: Default to `workspace-write`. Read-only for exploration and review profiles. Never use `danger-full-access` outside containerized environments.
+- **Consequences**: Agents can write within CWD + /tmp but cannot access network or system paths. Protected paths (.git, .agents, .codex) are always read-only. Network access opt-in via `sandbox_workspace_write.network_access = true`.
+
+---
+
+*Add new entries at the bottom. Never delete entries — mark as `superseded` or `deprecated`.*

package/.codex/context/gotchas.md

@@ -0,0 +1,42 @@
+# Gotchas
+
+Known edge cases, footguns, and "I wish I knew this earlier" items.
+
+## Config
+
+- `[hooks]` uses `[[hooks]]` array-of-tables format, NOT key-value pairs
+- Only 2 hook events exist: `AfterAgent`, `AfterToolUse` — no session lifecycle hooks
+- `approval_policy = "on-failure"` is deprecated — use `"on-request"` or `"never"`
+- Project config merges with `~/.codex/config.toml` — duplicate MCP server names cause conflicts
+- MCP servers with same name but different transport types (HTTP vs stdio) fail silently
+
+## Skills
+
+- Skills need both `name` and `description` in YAML frontmatter or they won't load
+- Description quality determines implicit matching accuracy — be detailed
+- `$skill-name` in prompts is informational — Codex CLI doesn't auto-load from references
+
+## Prompts
+
+- Custom prompts are deprecated — use Skills for new workflows
+- Prompts only load from `~/.codex/prompts/` (user-level), not project directory
+- Project prompts in `.codex/prompts/` serve as documentation/reference
+
+## Beads
+
+- Bead workflow prompts auto-bootstrap `.beads/` via `.codex/scripts/ensure_beads.sh`
+- `br` never runs git automatically — always `git add .beads/ && git commit` manually
+- `bd` (Go) ≠ `br` (Rust) — different tools with overlapping commands
+- Leader agents create observations; subagents report findings upward
+
+## Build
+
+- `dist/` is generated output — never edit directly
+- Build copies template to `dist/template/` — source of truth is `.codex/`
+- Run `npm run lint:fix` before any commit
+
+## Git
+
+- Never `git add .` or `git add -A` — stage specific files
+- Never force push main/master
+- Never bypass hooks

package/.codex/context/index.md

@@ -0,0 +1,21 @@
+# Codexkit Context Index
+
+> Map of curated project knowledge. Read this first.
+
+## Available Documents
+
+| Document | Purpose | When to Read |
+|---|---|---|
+| `architecture.md` | System boundaries, key modules, data flow | Starting new work, unfamiliar areas |
+| `conventions.md` | Coding norms, naming, patterns | Before writing code |
+| `current-priorities.md` | What matters right now | Session start |
+| `decision-log.md` | Architecture decision records | Before proposing changes |
+| `session-context.md` | Compaction-safe active session notes | Resume active work |
+| `worklog.md` | Session-level trail | Resuming work |
+
+## Usage Rules
+
+1. Read `current-priorities.md` at session start
+2. Check `decision-log.md` before proposing architectural changes
+3. Update `worklog.md` after significant milestones
+4. Keep documents short and curated — not a second wiki

package/.codex/context/session-context.md

@@ -0,0 +1,11 @@
+# Session Context
+
+This file is safe to reuse as a compact session checkpoint.
+
+## Current Focus
+
+- None recorded.
+
+## Next Actions
+
+- None recorded.

package/.codex/context/worklog.md

@@ -0,0 +1,9 @@
+# Worklog
+
+> Session-level human-readable trail. Update after significant milestones.
+
+---
+
+## Entries
+- No repository-specific worklog entries are shipped in the package by default.
+- Maintain this file as a concise public-facing trail only if packaged session history is intentionally part of the product.

package/.codex/hooks/README.md

@@ -0,0 +1,17 @@
+# Hooks
+
+Codex CLI lifecycle hooks. Configured in `config.toml` via `[[hooks]]` array.
+
+## Supported Events
+
+| Event          | Script              | Fires When                           |
+| -------------- | ------------------- | ------------------------------------ |
+| `AfterAgent`   | `after_agent.sh`    | After the agent completes a turn     |
+| `AfterToolUse` | `after_tool_use.sh` | After each individual tool call      |
+
+## Notes
+
+- Hooks run synchronously — keep them fast
+- Exit code is ignored (hooks cannot block Codex)
+- Environment variables from the parent shell are available
+- See [config reference](https://developers.openai.com/codex/config-reference/) for details