diff --git a/README.md b/README.md
index 58780de..40b0116 100644
--- a/README.md
+++ b/README.md
@@ -65,7 +65,29 @@ codex plugin marketplace add /path/to/reliquary
 codex plugin add g4b_ai@reliquary
 ```
 
-A project can mirror the checked-in `.codex/config.toml` shape to prefer Codex-native marketplace and plugin declarations.
+Or declaratively in a project's `.codex/config.toml`:
+
+```toml
+[marketplaces.reliquary]
+source_type = "git"
+source = "git@git.g4b.org:dirigence/reliquary.git"
+
+[plugins."g4b_ai@reliquary"]
+enabled = true
+```
+
+From a local clone:
+
+```toml
+[marketplaces.reliquary]
+source_type = "local"
+source = "/path/to/reliquary"
+
+[plugins."g4b_ai@reliquary"]
+enabled = true
+```
+
+Codex project config is read only for trusted projects. Codex does not currently have a direct `settings.local.json` equivalent; use user-level `~/.codex/config.toml`, profiles, or an intentionally gitignored local workflow for machine-private settings.
 
 ## ✂️ Grab pieces independently
 
diff --git a/docs/codex-project-config.md b/docs/codex-project-config.md
new file mode 100644
index 0000000..9ae12da
--- /dev/null
+++ b/docs/codex-project-config.md
@@ -0,0 +1,70 @@
+# Codex Project Configuration
+
+Codex uses TOML configuration. User-level defaults live in:
+
+```text
+~/.codex/config.toml
+```
+
+Project-level defaults can live in:
+
+```text
+.codex/config.toml
+```
+
+Codex loads project `.codex/` layers only for trusted projects. This means a checked-in project config is useful for shared defaults, but Codex may ignore it until the user has trusted the workspace.
+
+## Declarative Plugin Setup
+
+To use the Reliquary marketplace from a project without running the interactive plugin commands, add this to the project's `.codex/config.toml`:
+
+```toml
+[marketplaces.reliquary]
+source_type = "git"
+source = "git@git.g4b.org:dirigence/reliquary.git"
+
+[plugins."g4b_ai@reliquary"]
+enabled = true
+```
+
+For a local clone:
+
+```toml
+[marketplaces.reliquary]
+source_type = "local"
+source = "/path/to/reliquary"
+
+[plugins."g4b_ai@reliquary"]
+enabled = true
+```
+
+Add more plugin blocks as needed:
+
+```toml
+[plugins."gitea@reliquary"]
+enabled = true
+
+[plugins."project-uv@reliquary"]
+enabled = true
+
+[plugins."dioxus@reliquary"]
+enabled = true
+```
+
+The `workpad` skill is part of `g4b_ai`; there is no standalone `workpad@reliquary` plugin.
+
+## Local-Only Settings
+
+Claude supports `.claude/settings.local.json` for uncommitted machine-local overrides. Codex does not currently expose an exact project-file equivalent such as `.codex/config.local.toml`.
+
+Use one of these instead:
+
+- Put personal settings in `~/.codex/config.toml`.
+- Use a Codex profile file under `~/.codex/<profile-name>.config.toml` and launch Codex with `--profile <profile-name>`.
+- Keep project-specific local notes in `AGENTS.override.md` if they are instructions rather than config.
+- If a team deliberately wants local project config files, choose a repo convention and gitignore it, but remember Codex will not auto-merge arbitrary filenames unless Codex adds support for them.
+
+## References
+
+- OpenAI Codex config basics: https://developers.openai.com/codex/config-basic
+- OpenAI Codex config reference: https://developers.openai.com/codex/config-reference