feat: add Factory Droid client integration

.agents/skills/verify-droid-integration/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: verify-droid-integration
+description: Verify the Factory Droid CLI outbound integration against a live OpenCodex proxy, including every active model, streaming, reasoning, tools, images, and long context.
+---
+
+# Verify Factory Droid integration
+
+Use this skill after changing Droid export, client integration ownership, model metadata, or the
+OpenAI-compatible chat path. It drives the real `droid exec` CLI with a process-only settings file.
+It never writes `~/.factory/settings.json`.
+
+## Launch
+
+Use the user's existing signed-in OpenCodex instance when `curl -fsS
+http://127.0.0.1:10100/healthz` succeeds. The provider credentials live in that instance's
+`OPENCODEX_HOME`, so do not start a second proxy against the same home.
+
+If no proxy is running, start this checkout and keep its PID:
+
+```bash
+bun run src/cli/index.ts start --port 10100
+```
+
+Wait for `http://127.0.0.1:10100/healthz`. Stop only the PID you started.
+
+## Doctor
+
+Run the no-inference pass first:
+
+```bash
+bun .agents/skills/verify-droid-integration/scripts/run.ts --dry-run
+```
+
+It exports the live active catalog through `ocx export --client droid`, checks proxy health and
+Droid version, validates unique generic-provider rows, and asks Droid to resolve every custom model
+ID with `--list-tools`. A failure makes the instance unfit for the paid live pass.
+
+## Drive
+
+Run the full matrix:
+
+```bash
+bun .agents/skills/verify-droid-integration/scripts/run.ts \
+  --concurrency 3 \
+  --timeout-ms 180000 \
+  --long-words 20000
+```
+
+The active model set is frozen from the exported config at run start. Each model gets catalog,
+normal text, stream JSON, reasoning when advertised, Read tool call/result, image Read/OCR when
+advertised, and long-context coverage. Use `--models <csv>` or `--cases <csv>` only for diagnosis;
+the PR proof is the unfiltered run.
+
+## Evidence
+
+Each run writes `.tmp/verify-droid-integration/<timestamp>/`. The directory contains the generated
+settings, export and health evidence, one command/result JSON per model and case, `summary.json`,
+and `failures.json`. The command, exit code, stdout, stderr, timeout state, and duration preserve
+both the action and result. Keep the full directory through review.
+
+Passing means no `fail` or `error` result. `fail` records a completed assertion mismatch; `error`
+records a timeout, nonzero exit, or caught execution exception. `unsupported` is accepted only when
+the exported model lacks the corresponding reasoning or image capability. The generated settings
+must remain free of real keys.
+
+## Cleanup
+
+The helper starts no proxy and changes no persistent Factory settings. Delete diagnostic prompt and
+marker files only by deleting a run directory after its evidence is no longer needed. Do not remove
+the proof directory during verification. If this skill started a proxy, stop that exact PID after
+the final drive. Droid records its own exec sessions in the signed-in user's normal history; the
+helper records their IDs in command output and does not delete unrelated history.
+
+## Helpers
+
+`scripts/run.ts` is executable and self-documenting:
+
+```bash
+bun .agents/skills/verify-droid-integration/scripts/run.ts --help
+```
+
+## Failure recovery
+
+Read `failures.json`, rerun only the affected model and case, and preserve the new run beside the
+original. After a timeout or transport failure, repeat the Doctor pass before another paid request.
+If health is green but Droid remains wedged, end that `droid exec` process and start a fresh run;
+never reuse a failed session.
+
+## Feature map
+
+Read [features/README.md](features/README.md), then maintain it with
+`/maintain-verification-skill` after user-facing integration changes.

.agents/skills/verify-droid-integration/features/README.md

@@ -0,0 +1,12 @@
+# Factory Droid verification feature map
+
+| Feature | Proof |
+| --- | --- |
+| [Catalog export](catalog-export.md) | Active models become stable, keyless Factory custom rows |
+| [Text, stream, and reasoning](text-stream-reasoning.md) | Droid completes normal and stream JSON requests and applies advertised effort |
+| [Tool round trip](tool-roundtrip.md) | The model emits a Read call, receives the result, and uses it |
+| [Image input](image-input.md) | An image-capable model reads pixels through Droid and returns the expected headline |
+| [Long context](long-context.md) | Both boundary markers survive a deterministic long prompt |
+
+The full verifier drives every exported active model. A filtered rerun is diagnostic evidence, not
+a replacement for the complete matrix.

.agents/skills/verify-droid-integration/features/catalog-export.md

@@ -0,0 +1,24 @@
+# Catalog export
+
+## Sub-features
+
+- Live active-model filtering
+- Stable `custom:opencodex:<selector>` IDs
+- Exact generic Chat provider and loopback URL
+- A 16,384-token response ceiling instead of the full context window
+- Context, image, and reasoning metadata
+- Keyless config and per-row ownership
+
+## How to get to it (user POV)
+
+Open **Integrations → Factory Droid**, or run `ocx integration client enable --client droid`.
+For a non-persistent preview, run `ocx export --client droid --out <temp> --force`.
+
+## Driving it with Droid CLI
+
+Run the verifier with `--dry-run`. Inspect `settings.json` and each model's `catalog.json`.
+
+## Gotchas
+
+The export includes hub-approved Fast rows as active selectors. Do not compare it with a raw provider
+count. The inbound Factory bridge in the docs is a separate direction.

.agents/skills/verify-droid-integration/features/image-input.md

@@ -0,0 +1,22 @@
+# Image input
+
+## Sub-features
+
+- Catalog image capability maps to `noImageSupport: false`
+- Droid Read loads the image
+- The routed model reads visible pixels
+
+## How to get to it (user POV)
+
+Select an image-capable OpenCodex custom model and ask Droid to inspect an image file.
+
+## Driving it with Droid CLI
+
+Run `--cases image`. The helper copies `assets/pr-gate-screenshot-required.png` to an opaque random
+filename, asks Droid to read that copy without putting the headline in the prompt, then requires the
+exact pixel-only answer plus a matching Read call and two-part text/image result payload.
+
+## Gotchas
+
+Models exported with `noImageSupport: true` are `unsupported`. Filename or alt-text inference is not
+enough; the expected headline exists only in the image pixels.

.agents/skills/verify-droid-integration/features/long-context.md

@@ -0,0 +1,21 @@
+# Long context
+
+## Sub-features
+
+- Prompt-file ingestion
+- Deterministic context padding
+- Recall of markers at both boundaries
+
+## How to get to it (user POV)
+
+Pass a long prompt file to a selected OpenCodex custom model with `droid exec --file <path>`.
+
+## Driving it with Droid CLI
+
+Run `--cases long-context --long-words 20000`. The helper generates model-specific start and end
+markers and requires both in the exact final response.
+
+## Gotchas
+
+`--long-words` is a deterministic stress size, not an exact tokenizer count. A timeout is a failure,
+not an unsupported result; rerun after Doctor before attributing it to the model.

.agents/skills/verify-droid-integration/features/text-stream-reasoning.md

@@ -0,0 +1,22 @@
+# Text, stream, and reasoning
+
+## Sub-features
+
+- Normal JSON completion
+- Stream JSON lifecycle with a final completion
+- Advertised reasoning-effort selection
+
+## How to get to it (user POV)
+
+Select an `OpenCodex: ...` custom model in Droid, then run a prompt normally or pass
+`--output-format stream-json` and `--reasoning-effort <level>` to `droid exec`.
+
+## Driving it with Droid CLI
+
+Run the full verifier or `--cases text,stream,reasoning`. Proof requires exact marker text, a stream
+`system` event, a `completion` event, and the requested effort in the init event.
+
+## Gotchas
+
+A model with no exported effort ladder is `unsupported` for the reasoning case. A successful final
+line alone does not prove the stream lifecycle.

.agents/skills/verify-droid-integration/features/tool-roundtrip.md

@@ -0,0 +1,23 @@
+# Tool round trip
+
+## Sub-features
+
+- Read tool definition reaches the model
+- Tool call arguments select the marker file
+- Droid returns a successful tool result
+- The final answer includes content from that result
+
+## How to get to it (user POV)
+
+Run Droid in a repository and ask the selected OpenCodex model to read a file.
+
+## Driving it with Droid CLI
+
+Run `--cases tool`. The helper creates a unique marker file inside the evidence directory and
+requires a Read call for that exact path, its matching successful result containing the marker,
+and an exact final completion.
+
+## Gotchas
+
+Prompt compliance without a tool event is a failure. The verifier limits available tools to Read so
+the proof remains read-only.