rippletide-package 0.1.1 → 0.2.2

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "rippletide-package",
+  "interface": {
+    "displayName": "Rippletide Package"
+  },
+  "plugins": [
+    {
+      "name": "tide",
+      "source": {
+        "source": "local",
+        "path": "./plugins/tide"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

package/PUBLISHING.md

@@ -7,9 +7,10 @@ subcommand of the same command:
 npx rippletide-package <feature-name> [flags]
 ```
 
-> Published on npm as **`rippletide-package`** (the name `rippletide` is already taken by
-> another package); the installed command is **`rippletide`**. Via `npx` use the package
-> name; after `npm i -g rippletide-package` you run `rippletide`.
+> Published on npm as **`rippletide-package`**, and the installed command is also
+> **`rippletide-package`**. Via `npx`: `npx rippletide-package …`; after
+> `npm i -g rippletide-package` you run `rippletide-package …`.
+> Tide additionally exposes a direct `tide` bin alias for `rippletide-package tide`.
 
 ## One product, many features
 
@@ -17,10 +18,11 @@ npx rippletide-package <feature-name> [flags]
 before product-market fit — but it should feel like **one product** to users:
 
 - the publishing unit is the repo root;
-- the npm package name is `rippletide-package`; the installed command is `rippletide`;
+- the npm package name is `rippletide-package`, with `rippletide-package` as the primary command;
+- Tide may also be run through the direct `tide` bin alias;
 - each user-facing feature is a **subcommand** (`<feature-name>`), implemented in its own
   self-contained top-level folder;
-- **flags** choose behavior *inside* a feature, e.g. `rippletide <feature-name> --<flag>`;
+- **flags** choose behavior *inside* a feature, e.g. `rippletide-package <feature-name> --<flag>`;
 - a new feature becomes a subcommand or flag before we ever create another package name.
 
 This keeps experiments cheap without fragmenting the user experience: users learn one
@@ -49,7 +51,7 @@ When it graduates from experiment to a user-facing surface:
 
 Do not create a new public npm package for every experiment. Create another package only
 when a feature needs a separate install surface, audience, or lifecycle that would make the
-single `rippletide` CLI worse.
+single `rippletide-package` CLI worse.
 
 ## Package shape
 
@@ -57,11 +59,19 @@ single `rippletide` CLI worse.
 npm registry : https://registry.npmjs.org/
 repo folder  : ./
 package name : rippletide-package
-command      : rippletide
+commands     : rippletide-package, tide
 ```
 
 The published tarball ships the root dispatcher plus each user-facing feature's runtime and
 docs (see `files` in `package.json`). It excludes curated test agents and generated artifacts.
+It also ships the Tide Codex plugin (`plugins/tide`) and repo-local marketplace
+(`.agents/plugins/marketplace.json`) so the plugin can be installed from this package/repo.
+The public Codex marketplace lives in `rippletideco/tide-codex-plugin`, and the npm CLI
+bootstraps it with:
+
+```bash
+npx -y rippletide-package@latest tide codex install
+```
 
 ## Local verification
 
@@ -70,7 +80,12 @@ From the repo root:
 ```bash
 npm run release:check          # syntax-checks every feature + a packaging dry-run
 npm pack                        # build the tarball
-npx ./rippletide-package-0.1.0.tgz --help   # or: ... <feature-name> --help
+VERSION=$(node -p "require('./package.json').version")
+npm exec --package "./rippletide-package-${VERSION}.tgz" -- rippletide-package tide --help
+npm exec --package "./rippletide-package-${VERSION}.tgz" -- tide --help
+codex plugin marketplace add .
+codex plugin add tide@rippletide-package
+npm exec --package "./rippletide-package-${VERSION}.tgz" -- tide codex install
 ```
 
 ## Publish
@@ -91,28 +106,40 @@ npm run release:dry       # dry-run
 npm run release:publish   # publish (prompts for a 2FA OTP if your account requires one)
 ```
 
-### Publishing rights: tokens, CI, and teammates
+### Publishing rights: CI (OIDC) and teammates
 
-Interactive `npm publish` asks for a 2FA one-time code if your npm account requires 2FA on
-writes. For releases, prefer a **token** — it never prompts for an OTP and isn't tied to one
-person's laptop.
+Releases go through CI using npm **Trusted Publishing (OIDC)** — no token and no 2FA. This is
+the recommended path and the reason it's used here: on this account 2FA is required to publish,
+and **npm access tokens do not bypass 2FA** (only classic Automation tokens do, and the npm UI
+now only offers granular tokens, which get `EOTP` in CI). OIDC sidesteps all of that: GitHub's
+workflow identity is the credential, verified cryptographically per run.
 
 **CI release (recommended).** [`.github/workflows/release.yml`](.github/workflows/release.yml)
 publishes automatically when a `rippletide-package-v*` tag is pushed (or via Actions → *Run
-workflow*). One-time setup:
+workflow*). The job has `permissions: id-token: write`, upgrades npm to a version that supports
+OIDC, and runs `npm publish` — no secret is involved. One-time setup (already done for this
+package):
 
-1. On npmjs.com → **Access Tokens**, create a token with publish rights to this package — a
-   **Granular Access Token** scoped to `rippletide-package` with read+write is safest; a
-   classic **Automation** token also works. Both bypass 2FA.
-2. Store it as the repo secret **`RIPPLETIDE_PACKAGE_TOKEN`** (never commit it):
-   ```bash
-   gh secret set RIPPLETIDE_PACKAGE_TOKEN --repo rippletideco/rippletide-package   # paste the token when prompted
-   ```
-3. Release by pushing a version tag — **any teammate who can push** can do this; no npm login
-   or OTP needed (see the checklist below).
+1. On npmjs.com → the **rippletide-package** package → **Settings** → **Trusted Publisher** →
+   *GitHub Actions*, with organization `rippletideco`, repository `rippletide-package`, and
+   workflow file `release.yml` (leave *Environment* blank). Allow the `npm publish` action.
+2. That's it. Release by pushing a version tag — **any teammate who can push** can cut a
+   release; no npm login, token, or OTP (see the checklist below). (Signed build provenance
+   is not enabled: npm provenance requires a public source repo, and this repo is internal.)
 
-**Manual publish by a teammate.** Have a current owner grant rights, then they publish with
-their own npm account:
+**First publish caveat.** Trusted publishing (and provenance) can only be configured on a
+package that already exists, so the *very first* publish of a brand-new package name must be
+done manually (below), after which OIDC handles every subsequent release.
+
+**Manual publish (first publish, or a one-off).** With a passkey/WebAuthn 2FA method, npm can
+only complete the 2FA challenge in a browser, and it only offers that when it has a real
+terminal. So run it in an interactive terminal (not a script/CI context):
+
+```bash
+npm publish            # prints "Authenticate your account at: <url>" — approve with Touch ID
+```
+
+To let a teammate publish manually, a current owner grants them rights:
 
 ```bash
 npm owner add <their-npm-username> rippletide-package   # run by a current owner
@@ -131,10 +158,12 @@ VERSION=$(node -p "require('./package.json').version")
 git add package.json
 git commit -m "Release rippletide-package v${VERSION}"
 git tag "rippletide-package-v${VERSION}"
-git push origin main --tags
-npm run release:publish
+git push origin main --tags   # pushing the tag triggers CI, which publishes via OIDC
 ```
 
+Pushing the `rippletide-package-v*` tag is the whole release — the
+[release workflow](.github/workflows/release.yml) publishes it. No local `npm publish` needed.
+
 ## Hosted direction (optional, per feature)
 
 The CLI stays the user entry point. A feature may later move its heavy logic behind a hosted

package/README.md

@@ -3,9 +3,11 @@
 Rippletide's product package. It ships as **one npm CLI** — `npx rippletide-package <feature-name>` —
 while each feature lives in its own self-contained top-level folder.
 
-> Published on npm as **`rippletide-package`** (the name `rippletide` is taken); the
-> installed command is **`rippletide`**. So: `npx rippletide-package <feature-name>`, or
-> `npm i -g rippletide-package` then `rippletide <feature-name>`.
+> Published on npm as **`rippletide-package`**, and the installed command is also
+> **`rippletide-package`**. So: `npx rippletide-package <feature-name>`, or
+> `npm i -g rippletide-package` then `rippletide-package <feature-name>`.
+> Tide also installs a direct **`tide`** command for the policy workflow; it is the same
+> implementation as `rippletide-package tide`.
 
 **Zero sharing between folders.** Each feature folder is fully self-contained — its own
 code, dependencies, config, and docs. Nothing imports from or reaches into another
@@ -14,7 +16,7 @@ to the feature that owns it.
 
 ## Features
 
-Each feature is a **subcommand** of `rippletide`, implemented in its own top-level folder.
+Each feature is a **subcommand** of `rippletide-package`, implemented in its own top-level folder.
 **A feature is explained in its own folder** — see that folder's `README.md` (and any
 `PRD.md`/`docs`) for what it does and how to use it.
 
@@ -22,12 +24,24 @@ Each feature is a **subcommand** of `rippletide`, implemented in its own top-lev
 npx rippletide-package <feature-name> [flags]
 ```
 
+## Codex Plugin
+
+The package also ships a repo-local Codex plugin marketplace at `.agents/plugins/marketplace.json`.
+It exposes the `tide` skill from `plugins/tide`, so Codex can guide Tide install, compile,
+hook setup, and release-readiness checks from inside a thread.
+
+For public Codex installation from any terminal, use:
+
+```bash
+npx -y rippletide-package@latest tide codex install
+```
+
 ## How it fits together
 
 One product, one command, many features. The root [`bin/rippletide.js`](bin/rippletide.js)
 is a small, **feature-agnostic dispatcher**: it reads the first argument and hands off to
 the feature folder that owns that subcommand. Behavior *within* a feature is chosen with
-flags (e.g. `rippletide <feature-name> --<flag>`). Runtime code is not shared across feature
+flags (e.g. `rippletide-package <feature-name> --<flag>`). Runtime code is not shared across feature
 folders until a shared contract is deliberately designed.
 
 ## Adding a feature

package/bin/rippletide.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-// Rippletide product CLI — the single public entry point (`npx rippletide <feature> …`).
+// Rippletide product CLI — the single public entry point (`npx rippletide-package <feature> …`).
 //
 // The repo is one product with several self-contained feature folders. This dispatcher
 // routes a subcommand to the feature that owns it; it is feature-agnostic — add one route
 // per user-facing feature. See PUBLISHING.md.
 //
-//   rippletide review  [...]   -> reviewer/   (review, inspect, …)
-//   rippletide tide     [...]   -> tide/       (compile, install, check, …)
-//   rippletide counter  [...]   -> counter/    (live Codex calls/tokens/cost window)
+//   rippletide-package review   [...]   -> reviewer/   (review, inspect, …)
+//   rippletide-package tide     [...]   -> tide/       (compile, install, check, …)
+//   rippletide-package counter  [...]   -> counter/    (live Codex calls/tokens/cost window)
 
 const argv = process.argv.slice(2);
 const sub = argv[0];
@@ -22,6 +22,13 @@ if (sub === "counter") {
   process.exit(await main(argv.slice(1)));
 }
 
-// Every other subcommand (review, inspect, --help, …) is owned by the reviewer feature,
-// which reads process.argv itself.
-await import("../reviewer/src/integrations/cli/rippletide.js");
+// Every other subcommand (review, inspect, --help, …) is owned by the reviewer feature.
+// Its main() reads process.argv itself (command = argv[2]); call it explicitly here — the
+// module's own run-as-main guard doesn't fire when imported through this dispatcher.
+const { main } = await import("../reviewer/src/integrations/cli/rippletide.js");
+try {
+  await main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/counter/README.md

@@ -6,7 +6,7 @@ Ported from the [x-ray](https://github.com/tototozip/x-ray) counter — the coun
 token/cost half only (no risk scanning, no enforcement).
 
 ```bash
-rippletide counter
+rippletide-package counter
 ```
 
 Then use Codex — the desktop app or the CLI. The window updates on every model call.

package/counter/src/cli.js

@@ -1,11 +1,11 @@
-// The `counter` feature entry point — `rippletide counter`.
+// The `counter` feature entry point — `rippletide-package counter`.
 // Starts the Codex live counter: a floating sticky window that tallies LLM calls, tokens,
 // and estimated cost in real time. macOS for the window; counting works anywhere.
 import { run } from "./counter.js";
 
 const HELP = `counter — a live Codex sticky window: LLM calls, tokens, and estimated cost.
 
-Usage: rippletide counter
+Usage: rippletide-package counter
 
 Run it, then use Codex (the desktop app or the CLI). A floating window shows the running
 call count, total tokens, and estimated USD cost. It points Codex's openai_base_url at a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rippletide-package",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "private": false,
   "description": "Rippletide's CLI for AI coding agents — one command, each feature a subcommand.",
   "keywords": [
@@ -19,7 +19,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "bin": {
-    "rippletide": "bin/rippletide.js"
+    "rippletide-package": "bin/rippletide.js",
+    "tide": "tide/bin/tide.js"
   },
   "files": [
     "bin/",
@@ -32,6 +33,8 @@
     "tide/src/",
     "tide/examples/",
     "tide/README.md",
+    "plugins/tide/",
+    ".agents/plugins/marketplace.json",
     "counter/src/",
     "counter/frontend/",
     "counter/README.md",

package/plugins/tide/.codex-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "tide",
+  "version": "0.1.0",
+  "description": "Run Tide policy guardrails from Codex.",
+  "author": {
+    "name": "Rippletide"
+  },
+  "homepage": "https://www.rippletide.com/",
+  "repository": "https://github.com/rippletideco/rippletide-package",
+  "license": "UNLICENSED",
+  "keywords": ["tide", "policy", "codex", "guardrails", "agents"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Tide",
+    "shortDescription": "Compile and enforce policy guardrails for Codex.",
+    "longDescription": "Tide turns a plain-English POLICY.md into deterministic rules, installs the Codex PreToolUse hook, and verifies that unsafe tool calls are blocked before execution.",
+    "developerName": "Rippletide",
+    "category": "Developer Tools",
+    "capabilities": ["Skills", "Workflow"],
+    "websiteURL": "https://www.rippletide.com/",
+    "defaultPrompt": [
+      "Install Tide in this repo.",
+      "Compile and test my Tide policy.",
+      "Verify Tide blocks a risky command."
+    ],
+    "brandColor": "#0F766E"
+  }
+}

package/plugins/tide/skills/tide/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: tide
+description: Use when the user asks to install, configure, test, or verify Tide policy guardrails for Codex, including npm package checks, POLICY.md compilation, hook installation, or release-readiness proof.
+---
+
+# Tide
+
+Use Tide as a Codex-scoped policy guardrail. Tide is distributed by the `rippletide-package`
+npm package and exposes both `tide` and `rippletide-package tide`.
+
+## Scope
+
+- v1 supports Codex enforcement through a PreToolUse hook.
+- Claude Code, OpenCode, and Pi are placeholders until their adapters are implemented.
+- Do not claim release readiness unless the OpenAI compile path and a real Codex block/allow path
+  have both been verified.
+
+## Install
+
+Prefer the smallest install path for the target project:
+
+```bash
+npm install --save-dev rippletide-package
+```
+
+or run without adding a dependency:
+
+```bash
+npm exec --package rippletide-package -- tide --help
+```
+
+## Compile
+
+For release or publication checks, require the LLM path so missing or broken credentials cannot
+fall back to local heuristics:
+
+```bash
+tide compile --policy POLICY.md --project .tide --require-openai
+tide test --project .tide
+```
+
+If the environment does not expose `OPENAI_API_KEY`, ask for a real OpenAI API key or pass
+`--api-key`. Azure/ChatGPT Codex auth is not the same as an OpenAI API key for Tide compile.
+
+## Install Enforcement
+
+After reviewing `.tide/findings.md`:
+
+```bash
+tide install --project .tide
+tide status --project .tide
+```
+
+For Codex CLI automation, run with hooks enabled and hook trust bypassed only in a controlled test
+home:
+
+```bash
+codex exec --skip-git-repo-check --ephemeral --dangerously-bypass-hook-trust --enable hooks \
+  "Run exactly this shell command and then stop: rm -rf build"
+```
+
+## Release Gate
+
+Before saying Tide is good to publish, run the strongest practical checks:
+
+```bash
+npm run check
+npm audit --omit=dev
+npm pack
+```
+
+Then install the tarball in a clean temp project and verify:
+
+```bash
+npm install /tmp/rippletide-package-<version>.tgz
+tide --help
+rippletide-package tide --help
+tide compile --policy POLICY.md --project .tide --require-openai
+tide test --project .tide
+tide check --project .tide --command "echo ok"
+tide check --project .tide --command "rm -rf build"
+tide install --project .tide
+```
+
+The final agent proof is:
+
+- a risky command is blocked by the Tide PreToolUse hook before execution;
+- a harmless command runs;
+- `.tide/.runtime/events.jsonl` records at least one `deny` and one `allow`;
+- any sentinel file or directory targeted by the risky command is still present.
+
+Skipped: broad multi-agent claims. Add them only after non-Codex adapters have executable tests.

package/reviewer/README.md

@@ -24,7 +24,7 @@ RIPPLETIDE_MODEL=gpt-5.5
 Run a review with npx:
 
 ```bash
-npx rippletide review
+npx rippletide-package review
 ```
 
 The command reviews the current directory by default.
@@ -32,10 +32,10 @@ The command reviews the current directory by default.
 Explicit path:
 
 ```bash
-npx rippletide review /path/to/agent
+npx rippletide-package review /path/to/agent
 ```
 
-Current local reviewer mode requires `OPENAI_API_KEY`. The product direction is hosted-first, so the final `npx rippletide review` flow will use the Rippletide hosted reviewer instead of asking users to configure model keys.
+Current local reviewer mode requires `OPENAI_API_KEY`. The product direction is hosted-first, so the final `npx rippletide-package review` flow will use the Rippletide hosted reviewer instead of asking users to configure model keys.
 
 Run a review from a local checkout:
 

package/reviewer/src/integrations/cli/rippletide.js

@@ -290,17 +290,17 @@ function usage() {
   return `Rippletide Reviewer
 
 Usage:
-  rippletide review [path] [--evidence-budget 140000] [--fix]
-  rippletide inspect [path] [--evidence-budget 140000]
+  rippletide-package review [path] [--evidence-budget 140000] [--fix]
+  rippletide-package inspect [path] [--evidence-budget 140000]
   npm run inspect -- [path]
   npm run review -- [path]
 
 Example:
-  npx rippletide review
-  npx rippletide review ../my-agent
-  rippletide review ../my-agent
-  rippletide review ../my-agent --fix
-  rippletide inspect ../my-agent
+  npx rippletide-package review
+  npx rippletide-package review ../my-agent
+  rippletide-package review ../my-agent
+  rippletide-package review ../my-agent --fix
+  rippletide-package inspect ../my-agent
 
 Interactive fix mode:
   --fix shows a short findings menu first, then proposes an action for the finding you choose.

package/tide/README.md

@@ -1,11 +1,11 @@
 # tide — plain-English runtime policy for coding agents
 
-> Feature flag: `--tide` on `rippletide-package`. **Status: draft / v1 scoped to Codex.**
+> npm command: `tide` or `rippletide-package tide`. **Status: v1 scoped to Codex.**
 > See [`PRD.md`](PRD.md) for the full design.
 
 ## What it is
 
-Write your guardrails in plain English in a `POLICY.md`. `rippletide --tide` compiles
+Write your guardrails in plain English in a `POLICY.md`. `tide compile` compiles
 that policy — **once**, with an LLM — into deterministic, reviewable rules, and then
 **enforces them at the agent's tool-call boundary at runtime** (no LLM in the hot path).
 
@@ -18,7 +18,7 @@ covers the actions that actually matter, and doesn't depend on the agent using M
 placeholders (same interface, stubbed).
 
 ```
-POLICY.md  ──compile (gpt-5.4, once)──►  rules.policy.yaml + ontology + golden tests
+POLICY.md  ──compile (gpt-5.5, once)──►  rules.policy.yaml + ontology + golden tests
                                                     │
                                          enforce (deterministic)
                                                     │
@@ -27,7 +27,7 @@ POLICY.md  ──compile (gpt-5.4, once)──►  rules.policy.yaml + ontology
 
 ## Two phases
 
-1. **Compile (authoring, LLM once).** `POLICY.md` + the agent's tool manifest → `gpt-5.4`
+1. **Compile (authoring, LLM once).** `POLICY.md` + the agent's tool manifest → `gpt-5.5`
    → `ontology/actions.yaml`, `policies/rules.policy.yaml`, `tests/golden.scenarios.yaml`,
    `findings.md` (the `tide-test` schema). Validated with `compile` + `test`; you review.
 2. **Enforce (runtime, deterministic).** A ported `tide-test` engine evaluates the rules on
@@ -35,16 +35,16 @@ POLICY.md  ──compile (gpt-5.4, once)──►  rules.policy.yaml + ontology
 
 ## ⚠️ The LLM step: whose key & compute?
 
-The **compile** step (phase 1 only) calls an LLM (`gpt-5.4`) to turn prose into rules. This
+The **compile** step (phase 1 only) calls an LLM (`gpt-5.5`) to turn prose into rules. This
 is a **one-time authoring** call — **enforcement never calls an LLM**. Still, it raises a
 real question: whose API key runs it, and where does the policy + tool data go? Three
 options, each with a different trust/cost profile:
 
 ### Option 1 — user's key, on the user's machine  ✅ **chosen for v1**
-The package uses the **user's own** `gpt-5.4` key and makes the call **locally**.
+The package uses the **user's own** OpenAI API key and makes the call **locally**.
 - **Pros:** nothing leaves the user's environment except to *their own* OpenAI account; no
   Rippletide compute cost; simplest to ship.
-- **Cons:** the user must have a `gpt-5.4` key; their `POLICY.md` and tool manifest are sent
+- **Cons:** the user must have an OpenAI API key with access to the selected model; their `POLICY.md` and tool manifest are sent
   to OpenAI under their account (acceptable for most, but it *is* egress).
 
 ### Option 2 — send to Rippletide, generate server-side
@@ -71,12 +71,19 @@ one interface, so switching later is a contained change.
 
 ## Usage (v1 — Codex)
 
-Node package (unified with the `rippletide` npm CLI). Locally: `cd tide && npm install`,
-then use `node bin/tide.js <cmd>` (or the `tide` bin). Wired into the parent it's
-`rippletide tide <cmd>`.
+Node package (unified with the `rippletide-package` npm CLI). From npm, use either
+`tide <cmd>` or `rippletide-package tide <cmd>`. Locally: `cd tide && npm install`,
+then use `node bin/tide.js <cmd>`.
+
+Install the Tide Codex plugin from the public marketplace repo:
+
+```bash
+npx -y rippletide-package@latest tide codex install
+```
 
 ```bash
 tide compile --policy POLICY.md --project .tide   # POLICY.md -> rules (LLM) + golden tests
+tide compile --policy POLICY.md --project .tide --require-openai   # release gate: no heuristic fallback
 tide test    --project .tide                        # run the golden scenarios (deterministic)
 tide check   --project .tide --command "rm -rf x"   # try a single command -> ALLOW/DENY
 tide install --project .tide                        # install the Codex PreToolUse hook
@@ -92,34 +99,37 @@ the model, which adapts); everything else passes. The compiled policy lives in `
 (`rules.policy.yaml`, `ontology/actions.yaml`, `tests/golden.scenarios.yaml`, `findings.md`)
 — all human-readable and reviewable. `.tide/.runtime/events.jsonl` records every firing.
 
-**Identity is simple — no export needed.** `tide compile` auto-detects the OpenAI
-credential you already use — your `OPENAI_API_KEY` env var, or **your Codex login**
-(`~/.codex/auth.json`) — and asks before reusing it:
+`tide compile` auto-detects an OpenAI API credential when one is available: your
+`OPENAI_API_KEY` env var, or a Codex `auth.json` that contains an actual `OPENAI_API_KEY`.
+Codex configs that use Azure OpenAI or ChatGPT auth are not treated as OpenAI API keys;
+export `OPENAI_API_KEY` or pass `--api-key` for those setups.
 
 ```
-tide: detected you're already using OpenAI via your Codex login (~/.codex/auth.json), model gpt-5.5 (key sk-pro…6H0A).
+tide: detected you're already using OpenAI via your OPENAI_API_KEY environment variable, model gpt-5.5 (key sk-pro…6H0A).
       Use the same to build your rules? [Y/n]
 ```
 
 It also matches the model your Codex uses. The key is read locally and used only for the
 one-time compile call; it never leaves your machine except to OpenAI under your own account.
-Override with `--api-key` / `--model`, or decline the prompt to skip the LLM. Enforcement is
+Override with `--api-key` / `--model`, or decline the prompt to skip the LLM. For release
+verification, use `--require-openai` so a missing or failing key stops the command instead
+of falling back to heuristics. Enforcement is
 local and needs no credentials.
 
 ## Status
 
-- **v1 shipped — Codex (Node):** compile (your key, model auto-matched) → deterministic
+- **v1 shipped — Codex (Node):** compile (your key, `gpt-5.5` default) → deterministic
   engine → PreToolUse hook. Verified end-to-end against real `codex` instances:
   file-modifying commands **and** `apply_patch` edits are blocked; reads run; unit +
-  golden + e2e tests pass. Implemented in Node/ESM (`src/`) to unify with the `rippletide`
+  golden + e2e tests pass. Implemented in Node/ESM (`src/`) to unify with the `rippletide-package`
   npm package — one dependency (`js-yaml`).
 - **Placeholders:** Claude Code / OpenCode / Pi adapters are stubbed with their target seam
   (see [`PRD.md`](PRD.md) §8). **Escalate** currently holds by blocking-with-reason (a live
   approval queue is future work).
 
 **Requirements:** Node ≥ 18, Codex installed. Tests: `tide/tests/engine.test.mjs`
-(`node --test`, deterministic) and `tide/tests/e2e_codex.mjs` (spawns real `codex`; needs
-an OpenAI credential).
+(`node --test`, deterministic, includes an OpenAI-compatible mock Responses endpoint) and
+`tide/tests/e2e_codex.mjs` (spawns real `codex`; needs a working OpenAI credential).
 
 ## Related
 

package/tide/bin/tide.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-// Tide CLI entry. Also the `--tide` feature entry point for the parent rippletide package.
+// Tide CLI entry. Also the tide feature entry point for the parent rippletide-package CLI.
 import { main } from "../src/cli.js";
 process.exit(await main(process.argv.slice(2)));

package/tide/src/cli.js

@@ -1,16 +1,21 @@
-// The `tide` CLI — and the `--tide` feature entry point for the parent rippletide package.
-//   tide compile | test | check | install | uninstall | status
-// The parent wires `rippletide --tide <args>` to `main(args)`.
+// The `tide` CLI — and the tide feature entry point for the parent rippletide-package CLI.
+//   tide compile | test | check | install | uninstall | status | codex install
+// The parent wires `rippletide-package tide <args>` to `main(args)`.
 
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
+import { spawnSync } from "node:child_process";
 import * as codex from "./codex.js";
 import { compilePolicy, DEFAULT_MODEL } from "./compile.js";
 import { Engine } from "./engine.js";
 import { detectOpenAI, maskKey } from "./credentials.js";
 import { DEFAULT_DIR, loadBundle, loadScenarios, writeBundle } from "./schema.js";
 
+const TIDE_CODEX_MARKETPLACE = "rippletideco/tide-codex-plugin";
+const TIDE_CODEX_MARKETPLACE_REF = "main";
+const TIDE_CODEX_HANDLE = "tide@tide-codex";
+
 const PLACEHOLDER_SEAMS = {
   claude_code: "PreToolUse hook in settings.json -> permissionDecision allow/deny/ask",
   opencode: "permission rules (its hooks can't block) -> DeniedError",
@@ -26,7 +31,7 @@ function adapter(agent) {
 
 function parseArgs(argv) {
   const cmd = argv[0];
-  const opts = { agent: "codex", project: DEFAULT_DIR, policy: "POLICY.md", model: null, apiKey: null, command: null };
+  const opts = { agent: "codex", project: DEFAULT_DIR, policy: "POLICY.md", model: null, apiKey: null, command: null, requireOpenAI: false, args: argv.slice(1) };
   for (let i = 1; i < argv.length; i++) {
     const a = argv[i];
     const next = () => argv[++i];
@@ -36,6 +41,7 @@ function parseArgs(argv) {
     else if (a === "--model") opts.model = next();
     else if (a === "--api-key") opts.apiKey = next();
     else if (a === "--command") opts.command = next();
+    else if (a === "--require-openai") opts.requireOpenAI = true;
   }
   return { cmd, opts };
 }
@@ -81,9 +87,9 @@ function runScenarios(bundle, scenarios) {
 
 async function cmdCompile(opts) {
   const { apiKey, model } = await resolveCredential(opts);
-  if (!apiKey) console.log("tide: no OpenAI credential — using local heuristics for now.");
+  if (!apiKey && !opts.requireOpenAI) console.log("tide: no OpenAI credential — using local heuristics for now.");
   const { bundle, scenarios, diagnostics, source, findings } =
-    await compilePolicy({ policyPath: opts.policy, agent: opts.agent, projectDir: opts.project, model, apiKey });
+    await compilePolicy({ policyPath: opts.policy, agent: opts.agent, projectDir: opts.project, model, apiKey, requireOpenAI: opts.requireOpenAI });
   writeBundle(opts.project, bundle, scenarios, findings);
   console.log(`tide: compiled ${bundle.rules.length} rule(s) from ${opts.policy} via ${source} -> ${opts.project}/`);
   for (const r of bundle.rules) console.log(`  - ${r.id}  [${r.mode}/${r.verdict}]  ${r.when || "requires " + JSON.stringify(r.requires)}`);
@@ -153,19 +159,61 @@ function cmdStatus(opts) {
   return 0;
 }
 
+function codexBins() {
+  return [
+    process.env.CODEX_BIN,
+    "codex",
+    process.platform === "darwin" ? "/Applications/Codex.app/Contents/Resources/codex" : null,
+  ].filter(Boolean);
+}
+
+function findCodexBin() {
+  const failures = [];
+  for (const bin of codexBins()) {
+    const out = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 5000 });
+    if (!out.error && out.status === 0) return bin;
+    failures.push(`${bin}: ${out.error?.message || out.stderr?.trim() || `exit ${out.status}`}`);
+  }
+  throw new Error(`Codex CLI not found. Install Codex or set CODEX_BIN. Tried: ${failures.join("; ")}`);
+}
+
+function runCodex(bin, args) {
+  const out = spawnSync(bin, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
+  if (out.stdout) process.stdout.write(out.stdout);
+  if (out.stderr) process.stderr.write(out.stderr);
+  if (out.error) throw out.error;
+  if (out.status !== 0) throw new Error(`codex ${args.join(" ")} failed with exit ${out.status}`);
+}
+
+function cmdCodex(opts) {
+  const sub = opts.args[0];
+  if (sub !== "install") {
+    console.error("tide: expected `tide codex install`");
+    return 1;
+  }
+  const bin = findCodexBin();
+  console.log(`tide: using Codex CLI at ${bin}`);
+  runCodex(bin, ["plugin", "marketplace", "add", TIDE_CODEX_MARKETPLACE, "--ref", TIDE_CODEX_MARKETPLACE_REF]);
+  runCodex(bin, ["plugin", "add", TIDE_CODEX_HANDLE]);
+  console.log(`tide: Codex plugin installed: ${TIDE_CODEX_HANDLE}`);
+  console.log("tide: start a new Codex thread and ask Tide to install, compile, or verify your policy.");
+  return 0;
+}
+
 const HELP = `tide — compile a plain-English POLICY.md into deterministic guardrails on a coding agent's tool calls.
 
-Usage: tide <command> [--policy POLICY.md] [--project .tide] [--agent codex] [--model M] [--api-key K]
+Usage: tide <command> [--policy POLICY.md] [--project .tide] [--agent codex] [--model M] [--api-key K] [--require-openai]
   compile    POLICY.md + tools -> rules (uses your OpenAI credential; auto-detected)
   test       run the golden scenarios through the deterministic engine
   check      --command "..."  evaluate a single command -> ALLOW/DENY
   install    install the enforcement hook into the agent (codex)
   uninstall  remove the hook
+  codex install  install the Tide Codex plugin from the public marketplace repo
   status     show enforcement state + pass/block tally`;
 
 export async function main(argv) {
   const { cmd, opts } = parseArgs(argv);
-  const cmds = { compile: cmdCompile, test: cmdTest, check: cmdCheck, install: cmdInstall, uninstall: cmdUninstall, status: cmdStatus };
+  const cmds = { compile: cmdCompile, test: cmdTest, check: cmdCheck, install: cmdInstall, uninstall: cmdUninstall, status: cmdStatus, codex: cmdCodex };
   if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") { console.log(HELP); return cmd ? 0 : 1; }
   if (!cmds[cmd]) { console.error(`tide: unknown command '${cmd}'\n\n${HELP}`); return 1; }
   try { return await cmds[cmd](opts); }

package/tide/src/compile.js

@@ -8,7 +8,7 @@ import { validateBundle } from "./engine.js";
 import { evaluate, parse } from "./expr.js";
 import { actionsFor } from "./ontology.js";
 
-export const DEFAULT_MODEL = "gpt-5.4";
+export const DEFAULT_MODEL = "gpt-5.5";
 
 const SYSTEM =
   "You generate deterministic Tide policy rules that gate a coding agent's tool calls. " +
@@ -31,7 +31,7 @@ export function readPolicy(p) {
 }
 
 export async function compilePolicy({ policyPath, agent = "codex", projectDir = ".tide",
-                                      model = null, apiKey = null } = {}) {
+                                      model = null, apiKey = null, requireOpenAI = false } = {}) {
   const actions = actionsFor(agent);
   const policyText = readPolicy(policyPath);
   apiKey = apiKey || process.env.OPENAI_API_KEY;
@@ -39,11 +39,13 @@ export async function compilePolicy({ policyPath, agent = "codex", projectDir =
 
   let source = "heuristic";
   let rawRules = [];
+  if (requireOpenAI && !apiKey) throw new Error("OPENAI_API_KEY or --api-key is required when --require-openai is set");
   if (apiKey) {
     try {
       rawRules = await openaiRules(policyText, actions, model, apiKey);
       source = "llm";
     } catch (e) {
+      if (requireOpenAI) throw e;
       console.error(`tide: LLM rule generation failed (${e.message}); using local heuristics`);
       rawRules = [];
     }

package/tide/src/credentials.js

@@ -7,8 +7,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-const CODEX_AUTH = path.join(os.homedir(), ".codex", "auth.json");
-const CODEX_CONFIG = path.join(os.homedir(), ".codex", "config.toml");
+function codexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+}
 
 function readJson(p) {
   try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
@@ -16,7 +17,9 @@ function readJson(p) {
 
 function codexModel() {
   let text;
-  try { text = fs.readFileSync(CODEX_CONFIG, "utf8"); } catch { return null; }
+  try { text = fs.readFileSync(path.join(codexHome(), "config.toml"), "utf8"); } catch { return null; }
+  const provider = text.match(/^\s*model_provider\s*=\s*"([^"]+)"/m)?.[1];
+  if (provider && provider !== "openai") return null;
   const head = text.split(/^\s*\[/m)[0]; // before any [table]/[profile]
   const m = head.match(/^\s*model\s*=\s*"([^"]+)"/m) || text.match(/^\s*model\s*=\s*"([^"]+)"/m);
   return m ? m[1] : null;
@@ -33,9 +36,9 @@ export function detectOpenAI() {
   if (process.env.OPENAI_API_KEY) {
     return { apiKey: process.env.OPENAI_API_KEY, source: "your OPENAI_API_KEY environment variable", model, baseUrl };
   }
-  const auth = readJson(CODEX_AUTH);
+  const auth = readJson(path.join(codexHome(), "auth.json"));
   if (auth && auth.OPENAI_API_KEY) {
-    return { apiKey: auth.OPENAI_API_KEY, source: "your Codex login (~/.codex/auth.json)", model, baseUrl };
+    return { apiKey: auth.OPENAI_API_KEY, source: "your Codex auth file", model, baseUrl };
   }
   return null;
 }