pi-oracle 0.6.16 → 0.7.0

package/CHANGELOG.md

@@ -2,8 +2,38 @@
 
 ## Unreleased
 
+## 0.7.0 - 2026-05-17
+
+### Added
+- added Grok Heavy as a second oracle provider, with `provider: "grok"`, Grok-only `mode: "heavy"`, `/oracle-auth grok`, separate Grok auth seed profiles, and provider defaults in oracle config
+- added provider-aware `oracle_preflight` support, including explicit Grok checks and follow-up readiness checks that use the prior job's provider
+- added Grok web worker support for auth readiness, Heavy selection, archive upload, prompt submission, response extraction, and same-thread follow-ups
+
+### Changed
+- documented provider selection, Grok's 200 MiB upload ceiling, ChatGPT's 250 MiB ceiling, and same-provider-only follow-up behavior in README, design docs, and prompt templates
+- updated oracle job summaries to report Grok provider/mode selections, not only ChatGPT presets
+
+### Fixed
+- preserved Cloudflare continuity cookies for current ChatGPT verification flows and removed Chromium singleton artifacts when cloning runtime profiles
+- tightened Grok/X cookie import to an explicit auth-cookie allowlist and made Grok jobs fail clearly if a completed response never produces a stable conversation URL
+- improved ChatGPT response extraction fallback behavior when the UI no longer exposes the old `ChatGPT said:` heading structure
+
+### Validation
+- verified Grok Heavy live submission and same-thread Grok follow-up using isolated local-extension `pi` sessions
+- verified a final ChatGPT `instant` live smoke using an isolated local-extension `pi` session before release
+
+## 0.6.17 - 2026-05-10
+
 ### Changed
 - made `/oracle-auth` success and failure output easier to scan, with compact source summaries and source-specific troubleshooting for configured Chromium cookie sources
+- tightened README quickstart/command wording around preflight-first `/oracle` behavior, context-rich archive selection, cleanup retention, and preset defaults
+- added the resolved oracle model preset snapshot to `oracle_submit` queued/dispatched output so agents can see what preset will run
+- clarified `oracle_preflight` output so users can see that it validates the persisted pi session, local config, and ChatGPT auth seed created by `oracle_auth`
+- made direct `scripts/oracle-sanity.ts` execution fail fast unless isolated oracle state/jobs dirs are provided, preventing accidental sanity-job leakage into live oracle pollers
+
+### Fixed
+- stopped worker/auth readiness checks from treating ChatGPT's public logged-out composer shell as an authenticated ready state, and made stale-auth failures name the visible login controls instead of reporting a misleading partial-login state
+- made plain `instant` model selection robust against the current ChatGPT model menu by recognizing closed Instant chips and falling back to the top-level model menu when the configure sheet is unavailable
 
 ## 0.6.16 - 2026-05-07
 

package/README.md

@@ -1,62 +1,118 @@
 # pi-oracle
 
-`pi-oracle` is a `pi` package that lets the agent hand off difficult, long-running tasks to ChatGPT.com through the web app instead of the API.
+`pi-oracle` lets a `pi` agent send hard, long-running work to ChatGPT.com or Grok through the web app, with repo archives, background execution, saved results, and a best-effort wake-up back into `pi` when the answer is ready.
 
-Use it when you want:
-- your real ChatGPT account
-- web-model behavior instead of API usage
-- large repo/context uploads
-- async background execution
-- durable saved responses/artifacts plus best-effort wake-ups back into `pi`
+> Status: experimental public beta. Validated primarily on macOS with Google Chrome/Chromium and `pi` 0.65.0+. Normal oracle jobs run in an isolated browser profile, not your active browser window.
 
-Normal oracle jobs run in an isolated browser profile, not your active browser window.
+## What a successful run looks like
 
-> Status: experimental public beta. Validated primarily on macOS with Google Chrome and `pi` 0.65.0+.
+```text
+You: /oracle Review the pending changes. Include the whole repo unless a narrower archive is clearly better.
+
+pi-oracle:
+  1. preflights local session/auth readiness
+  2. builds a context-rich `.tar.zst` repo archive
+  3. starts an isolated provider web runtime in the background
+  4. uploads the archive and prompt to the selected provider
+  5. saves the response/artifacts under /tmp/oracle-<job-id>/
+  6. sends a best-effort wake-up back to the matching pi session
+
+Later: /oracle-read <job-id>
+```
+
+What you are seeing: the local `pi` agent keeps control of context selection and safety checks, while the selected web provider handles the expensive second-opinion work asynchronously. If the wake-up is missed, the result still lives on disk and can be read by job id.
+
+## Who this is for
+
+Use `pi-oracle` if you use `pi` and want a larger asynchronous reviewer, planner, or analyst that can use your real ChatGPT or Grok web account instead of an API model.
+
+It is most useful for:
+
+- maintainers reviewing broad repo changes before shipping
+- agents that need a slower second opinion without blocking the main `pi` turn
+- migration, architecture, or failure-mode analysis that benefits from a large archive
+- follow-up questions that should continue the same provider thread later
+
+Do not use it for:
+
+- short local coding tasks that `pi` can handle directly
+- projects that must never be uploaded to ChatGPT.com, Grok, or another configured web provider
+- non-macOS environments or machines without the required local browser/tooling
+
+## Problem it solves
+
+A normal coding-agent turn is the wrong shape for some work: the task may need a large repo snapshot, a slower web model, a real ChatGPT/Grok subscription, artifact downloads, or a durable result that arrives after the active turn ends.
 
-## When to use it
+`pi-oracle` makes that workflow explicit and recoverable instead of asking the main agent to manually drive provider chat UIs in your real browser window.
 
-Use `pi-oracle` for:
-- big code reviews of a repo or pending changes
-- architectural or migration analysis that benefits from a large uploaded archive
-- long-running prompts that may take minutes to finish
-- follow-up questions in the same ChatGPT thread later
+## What it does
 
-Do not reach for it first for:
-- normal short coding tasks that `pi` can handle directly
-- workflows that must never upload project archives to ChatGPT.com
-- environments outside the current supported setup
+| Problem | Capability | Proof in this repo |
+| --- | --- | --- |
+| Hard tasks need more context than a quick turn should gather. | `/oracle` prompts the agent to preflight, choose a context-rich archive, and submit it to the selected provider web app. | [`prompts/oracle.md`](prompts/oracle.md), `oracle_submit`, archive tests in `scripts/oracle-sanity-*` |
+| Browser automation should not steal focus or mutate your active profile. | Jobs clone an authenticated seed profile into per-job isolated runtime profiles. | [`docs/ORACLE_DESIGN.md`](docs/ORACLE_DESIGN.md), [`extensions/oracle/lib/runtime.ts`](extensions/oracle/lib/runtime.ts) |
+| Long jobs need durability. | Job state, responses, logs, and artifacts persist under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`. | [`extensions/oracle/lib/jobs.ts`](extensions/oracle/lib/jobs.ts), `/oracle-read`, `/oracle-status` |
+| Provider auth can expire or drift. | `/oracle-auth [chatgpt|grok]` refreshes the isolated auth seed from a configured local Chromium profile, with recovery guidance. | [`extensions/oracle/lib/auth.ts`](extensions/oracle/lib/auth.ts), [`docs/ORACLE_RECOVERY_DRILL.md`](docs/ORACLE_RECOVERY_DRILL.md) |
+| Agents need a simple API, not UI-driving instructions. | The package exposes agent-facing tools: `oracle_preflight`, `oracle_submit`, `oracle_read`, `oracle_auth`, and `oracle_cancel`. | [`extensions/oracle/lib/tools.ts`](extensions/oracle/lib/tools.ts) |
 
-## Install
+## Fastest way to see it work
 
-npm:
+### 1. Install
+
+From npm:
 
 ```bash
 pi install npm:pi-oracle
 ```
 
-GitHub:
+Or from GitHub:
 
 ```bash
 pi install https://github.com/fitchmultz/pi-oracle
 ```
 
-## Quickstart
+### 2. Check requirements
+
+You need:
+
+- macOS
+- Node.js 22 or newer
+- `pi` 0.65.0 or newer
+- Google Chrome or another Chromium-family browser
+- ChatGPT or Grok already signed in to the configured local browser profile for the provider you plan to use
+- `agent-browser`, `tar`, and `zstd` available on the machine
+- a normal persisted `pi` session, not `pi --no-session`
+
+### 3. Sync provider auth once
+
+```text
+/oracle-auth
+```
 
-1. Start a normal persisted `pi` session. Do not use `pi --no-session` for oracle.
-2. Make sure ChatGPT already works in your configured local browser profile.
-3. Make sure these are installed: Google Chrome, `agent-browser`, `tar`, and `zstd`.
-4. Optional: create `~/.pi/agent/extensions/oracle.json` if you want non-default settings.
-5. Run `/oracle-auth`.
-6. Run `/oracle Review the current pending changes. Include the whole repo unless a narrower archive is clearly better.`
-7. Wait for the one-time best-effort wake-up, or check `/oracle-status`.
+This reads cookies for the configured default provider from your local browser profile and writes an isolated oracle seed profile. Use `/oracle-auth grok` to force-refresh the Grok seed when your default provider is still ChatGPT. It should not automate your active browser window for normal jobs.
 
-The `/oracle` prompt now runs an early oracle preflight before it gathers repo context, so missing persisted-session or local auth/config blockers fail before the agent spends time reading files.
+### 4. Submit a tiny job
 
-For explicitly narrow requests, `/oracle` should still prefer a context-rich relevant archive up to the 250 MB ceiling, including nearby tests, docs, config, and adjacent modules when that can improve answer quality. Reserve tightly minimal archives for an explicit user request for a tight archive, privacy-sensitive material, or size-constrained cases. It should also omit `preset` and use the configured default model unless the task clearly needs a different one.
+```text
+/oracle Read README.md and package.json. Tell me in five bullets what this package does and who should not use it.
+```
 
-If a local archive still exceeds the 250 MB limit after default exclusions and automatic whole-repo pruning, the agent should treat that as a retryable archive-selection failure: shrink the archive automatically, retry with a smaller relevant slice, and explain what it cut only if it still cannot fit after the allowed retry budget.
+Expected result:
 
-If you miss the one-time wake-up, the result is still saved durably in the oracle job directory and can be read later.
+- The `/oracle` prompt now runs an early oracle preflight before expensive repo reading or archive creation.
+- The agent chooses a context-rich relevant archive up to the selected provider's upload ceiling, not the smallest possible one-file slice when nearby context helps.
+- `oracle_submit` creates or queues a job.
+- If local packing is too large, the prompt treats that as a retryable archive-selection failure and narrows automatically before surfacing the problem.
+- The job uploads a repo archive to the selected provider, capped at 250 MiB for ChatGPT or 200 MiB for Grok after default exclusions/pruning.
+- The response is saved under `/tmp/oracle-<job-id>/response.md` by default.
+- The matching `pi` session gets one best-effort wake-up when the job finishes.
+
+If the wake-up does not arrive, run:
+
+```text
+/oracle-status
+/oracle-read <job-id>
+```
 
 ## Example requests
 
@@ -73,53 +129,62 @@ If you miss the one-time wake-up, the result is still saved durably in the oracl
 ```
 
 ```text
-/oracle-followup <job-id> Tighten the migration plan around rollback risk, and include the most relevant surrounding files/docs as long as the archive stays comfortably within the limit.
+/oracle-followup <job-id> Tighten the migration plan around rollback risk, and include the most relevant surrounding files/docs as long as the archive stays comfortably within the 250 MiB limit.
 ```
 
-After a job finishes, use `/oracle-followup <job-id> <request>` to continue the same ChatGPT thread without hand-writing the low-level `followUpJobId` tool parameter.
-
-## High-level flow
+## How it works
 
 ```mermaid
 flowchart LR
     A["/oracle request"] --> B["Agent preflights, then gathers a context-rich relevant repo slice"]
-    B --> C["oracle_submit builds archive"]
-    C --> D["Detached worker starts isolated ChatGPT runtime"]
-    D --> E["Archive + prompt sent to ChatGPT.com"]
-    E --> F["Response/artifacts saved under oracle job dir"]
-    F --> G["One-time best-effort wake-up to matching pi session"]
+    B --> C["Agent chooses context-rich archive inputs"]
+    C --> D["oracle_submit builds .tar.zst archive"]
+    D --> E["Detached worker clones isolated auth seed profile"]
+    E --> F["Selected provider receives archive + prompt"]
+    F --> G["Response/artifacts saved under oracle job dir"]
+    G --> H["Best-effort wake-up to matching pi session"]
 ```
 
-If concurrency is full, the job is queued and starts automatically later.
+Key design choices:
+
+- **Prompt templates own context gathering.** `/oracle` and `/oracle-followup` tell the agent how to preflight, gather context, choose archive inputs, and then stop after dispatch.
+- **Tools own execution.** `oracle_submit` builds the archive, admits or queues the job, starts the worker, and returns immediately.
+- **Auth uses a seed profile.** `/oracle-auth` imports cookies into an isolated seed profile; each job clones that seed into its own temporary runtime profile.
+- **Follow-ups preserve provider thread state.** `/oracle-followup <job-id> ...` resolves the prior job's saved provider URL and submits the next prompt with `followUpJobId`.
+- **Wake-up is best effort, storage is durable.** A missed wake-up does not lose the result.
 
-## What the package adds
+## Commands and tools
 
 User-facing commands:
-- `/oracle <request>` — prompt template that tells the agent to gather context and dispatch an oracle job
-- `/oracle-followup <job-id> <request>` — prompt template that continues an earlier oracle job in the same ChatGPT thread
-- `/oracle-auth` — sync ChatGPT cookies from your configured local browser profile into the isolated oracle auth profile
-- `/oracle-read [job-id]` — inspect job status plus the saved response preview
-- `/oracle-status [job-id]` — inspect job status and list recent job ids when no explicit id is given
-- `/oracle-cancel <job-id>` — cancel a queued or active job by id
-- `/oracle-clean <job-id|all>` — remove temp files for terminal jobs; recently woken terminal jobs may stay retained briefly and return a retry-after hint
+
+- `/oracle <request>` — prepare context and dispatch a ChatGPT or Grok web oracle job
+- `/oracle-followup <job-id> <request>` — continue an earlier oracle job in the same provider thread
+- `/oracle-auth [chatgpt|grok]` — sync provider cookies into the isolated oracle auth seed profile
+- `/oracle-read [job-id]` — inspect job status and saved response preview
+- `/oracle-status [job-id]` — inspect a job or list recent job ids when no explicit id is given
+- `/oracle-cancel <job-id>` — cancel a queued or active job
+- `/oracle-clean <job-id|all>` — remove temp files for terminal jobs; recently woken terminal jobs may stay retained briefly, and a blocked cleanup returns the next eligible cleanup time
 
 Agent-facing tools:
+
 - `oracle_preflight`
 - `oracle_auth`
 - `oracle_submit`
 - `oracle_read`
 - `oracle_cancel`
 
-## Minimal config
+## Configuration
 
-Most users can start with the packaged defaults and only set the browser profile if needed.
+Most users can start with defaults. Set an agent-level config only when you need a non-default provider, mode, preset, or browser profile.
 
 `~/.pi/agent/extensions/oracle.json`
 
 ```json
 {
   "defaults": {
-    "preset": "<preset id from ORACLE_SUBMIT_PRESETS>"
+    "provider": "chatgpt",
+    "preset": "<preset id from ORACLE_SUBMIT_PRESETS>",
+    "grokMode": "heavy"
   },
   "auth": {
     "chromeProfile": "Default"
@@ -128,22 +193,26 @@ Most users can start with the packaged defaults and only set the browser profile
 ```
 
 Notes:
+
+- `defaults.provider` is the default web provider: `chatgpt` or `grok`.
 - `defaults.preset` is the default ChatGPT model preset for oracle jobs.
-- The canonical preset ids live in `extensions/oracle/lib/config.ts`.
-- If the packaged default is fine, you can omit `defaults.preset` entirely.
-- You usually do not need to set browser paths unless auto-detection fails.
+- `defaults.grokMode` is the default Grok mode. Only `heavy` is supported today.
+- The canonical preset ids and provider modes live in [`extensions/oracle/lib/config.ts`](extensions/oracle/lib/config.ts).
+- If the packaged default is fine, omit `defaults`.
+- When an agent is unsure which oracle preset fits, it should omit `preset` and use the configured default model instead of asking by default. If the prompt says to use Grok, it should pass `provider: "grok"` to `oracle_submit`.
+- You usually do not need browser paths unless auto-detection fails.
 
 ### Custom Chromium cookie sources
 
-Most Chrome-compatible browsers should work through the default cookie importer. Use this alternate path only for a Chromium-family browser that is not one of `@steipete/sweet-cookie`'s built-in Chrome/Brave/Arc/Chromium targets or otherwise cannot import cookies without dependency patching.
+Use this only for a Chromium-family browser that the default cookie importer cannot read.
 
 Before running `/oracle-auth` with this path:
 
-1. Log into ChatGPT in the target browser profile.
+1. Log into ChatGPT or Grok in the target browser profile, depending on `defaults.provider`.
 2. Fully quit the browser so its `Cookies` database is stable.
 3. Find the profile `Cookies` SQLite DB path.
 4. Find the browser's macOS Keychain safe-storage item account and service name.
-5. Configure all of `browser.executablePath`, `auth.chromeCookiePath`, and `auth.chromiumKeychain` in the agent-level config at `~/.pi/agent/extensions/oracle.json`.
+5. Configure all of `browser.executablePath`, `auth.chromeCookiePath`, and `auth.chromiumKeychain` in `~/.pi/agent/extensions/oracle.json`.
 
 Example Helium config:
 
@@ -164,11 +233,18 @@ Example Helium config:
 }
 ```
 
-`auth.chromeCookiePath` remains the cookie database path for backward compatibility. `auth.chromiumKeychain` must be paired with `auth.chromeCookiePath`; partial config is rejected so oracle does not silently fall back to a different browser source. When both are present, `/oracle-auth` uses pi-oracle's repo-owned generic Chromium cookie reader instead of patching `@steipete/sweet-cookie` internals.
+`auth.chromeCookiePath` must be paired with `auth.chromiumKeychain`; partial config is rejected so oracle does not silently fall back to another browser source.
 
-If macOS prompts for Keychain access during `/oracle-auth`, allow access for the configured browser safe-storage item. If auth still fails after cookies are synced, the cookie DB may be stale, from the wrong profile, or for an account that is logged out; reopen the configured browser profile, confirm ChatGPT works there, quit the browser, and rerun `/oracle-auth`.
+## Available providers and presets
 
-## Available presets
+| Provider | Mode / preset | Upload ceiling |
+| --- | --- | --- |
+| ChatGPT | Presets below | 250 MiB |
+| Grok | `heavy` only | 200 MiB |
+
+Grok accepts the same `.tar.zst` archives that pi-oracle builds. Manual testing against `https://grok.com` found a 200 MiB file is accepted and a 200 MiB + 1 byte file is rejected, so pi-oracle caps Grok archives at 200 MiB.
+
+## Available ChatGPT presets
 
 | Preset id | Description |
 | --- | --- |
@@ -181,63 +257,60 @@ If macOS prompts for Keychain access during `/oracle-auth`, allow access for the
 | `instant` | Instant |
 | `instant_auto_switch` | Instant - Auto-switch to Thinking Enabled |
 
-`oracle_submit` accepts either the canonical preset id or the matching human-readable preset label; common space/hyphen variants are normalized automatically at submit time. Keep `defaults.preset` in config on the canonical preset id.
+For ChatGPT, `oracle_submit` accepts canonical preset ids or a matching human-readable preset label. Keep config values on canonical ids. For Grok, use `provider: "grok"`; only Heavy is supported today.
 
-Other useful settings:
-- `browser.runMode`
-- `browser.args`
-- `browser.authSeedProfileDir`
-- `browser.runtimeProfilesDir`
-- `cleanup.completeJobRetentionMs`
-- `cleanup.failedJobRetentionMs`
+## Outputs and cleanup
 
-Project config should only override safe, non-privileged settings.
+- Jobs persist response text, metadata, logs, and artifacts under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default.
+- Jobs can queue automatically when runtime capacity is full.
+- Completion delivery into `pi` is one-time best-effort wake-up based.
+- `/oracle-read [job-id]` and `oracle_read({ jobId })` inspect saved output later.
+- `/oracle-clean` removes terminal job temp files, but can briefly refuse cleanup after a wake-up so the follow-up turn can still read the saved paths.
 
-## What happens to outputs
+## Privacy and local data
 
-- Jobs persist their response and any artifacts under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default.
-- Jobs can queue automatically if runtime capacity is full.
-- Completion delivery into `pi` is one-time best-effort wake-up based; duplicate poller scans are deduped in job state.
-- If you miss the wake-up, use `/oracle-read [job-id]` to inspect the saved response preview.
-- `/oracle-status [job-id]` still shows saved job metadata and lists recent job ids when you omit the id.
-- Agent callers can use `oracle_read({ jobId })`.
-- If a prior oracle run failed because ChatGPT login was required or the worker explicitly said to rerun `/oracle-auth`, agent callers can run `oracle_auth({})` once and then retry the submission once.
-- `/oracle-clean` can still refuse a terminal job briefly after a wake-up send so saved response/artifact paths survive the follow-up turn; when that guard applies, it returns the next eligible cleanup time.
+This extension is local-first, but it handles sensitive local and project data:
 
-## Requirements
+- `/oracle-auth` reads provider cookies from the configured local browser profile. Use `/oracle-auth grok` for Grok when ChatGPT remains the default provider.
+- `oracle_submit` uploads selected project archives to the selected provider web app.
+- Responses, logs, and artifacts are written to the configured oracle jobs directory.
 
-- macOS
-- Node.js 22 or newer
-- Google Chrome or another Chromium-family browser installed
-- ChatGPT already signed into the configured local browser profile
-- `pi` 0.65.0 or newer
-- `agent-browser` available on the machine
-- `tar` and `zstd` available
+Review the code and design docs before using it with private or regulated material.
+
+## Current limits
+
+- Experimental public beta, validated primarily on macOS.
+- Provider UI, auth, model controls, and artifact download behavior can drift.
+- Archive uploads are capped at 250 MiB for ChatGPT and 200 MiB for Grok after default exclusions and automatic whole-repo pruning.
+- A real ChatGPT or Grok web session is required for the provider you use.
+- The README currently uses command-level proof and design docs; no public screenshot or demo GIF is checked into the repo.
+- Production hardening should keep focusing on UI drift detection, auth recovery, artifact capture, and environment diagnostics.
 
 ## Troubleshooting
 
 ### `/oracle-auth` fails or says login is required
 
-- Make sure ChatGPT works in the same local browser profile you configured.
+- Make sure the selected provider works in the same local browser profile you configured.
 - For custom Chromium cookie sources, confirm `auth.chromeCookiePath` points at that profile's `Cookies` DB and `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service.
 - Re-run `/oracle-auth`.
-- If ChatGPT is half-logged-in or challenge flow state looks weird, finish the login/challenge in the headed auth browser and retry.
+- Agent callers can use `oracle_auth({})` once before retrying a stale-auth oracle submission.
+- If the provider is half-logged-in or challenge flow state looks weird, finish the login/challenge in the headed auth browser and retry.
 
 ### Custom Chromium auth says cookies synced but the session is rejected
 
-This usually means the cookie import worked but the source cookies are not the active ChatGPT session you expected.
+This usually means the cookie import worked but the source cookies are not the active provider session you expected.
 
 1. Open the configured browser profile.
-2. Confirm ChatGPT works there without logging in again.
+2. Confirm the selected provider works there without logging in again.
 3. Quit the browser fully so its `Cookies` DB is stable.
 4. Confirm `auth.chromeCookiePath` points at that exact profile's `Cookies` DB.
 5. Confirm `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service for that DB.
 6. Re-run `/oracle-auth`.
 
-### You hit a challenge / verification page
+### You hit a challenge or verification page
 
 - Solve it in the auth/bootstrap browser if prompted.
-- Then re-run `/oracle-auth` before submitting jobs again.
+- Re-run `/oracle-auth` before submitting jobs again.
 
 ### You see "Oracle requires a persisted pi session"
 
@@ -247,19 +320,19 @@ This usually means the cookie import worked but the source cookies are not the a
 ### A job finished but no wake-up arrived
 
 - Use `/oracle-read [job-id]` to inspect the saved response preview.
-- Use `/oracle-status [job-id]` when you want status metadata or need help finding a job id.
-- Agent callers can use `oracle_read({ jobId })` if they need tool output in the current turn.
+- Use `/oracle-status` if you need help finding a recent job id.
+- Agent callers can use `oracle_read({ jobId })`.
 - Results are still saved on disk even if the reminder turn does not land.
 
 ### `/oracle-clean` refuses a terminal job right after completion
 
 - This can happen during the short post-send retention grace window after a wake-up was sent.
-- The command now returns a `Retry after ...` timestamp when that guard is active.
-- Wait until that time, then rerun `/oracle-clean [job-id|all]`.
+- The command returns a `Retry after ...` timestamp when that guard is active.
+- Wait until that time, then rerun `/oracle-clean <job-id|all>`.
 
 ### `agent-browser`, `tar`, or `zstd` is missing
 
-- Install the missing local dependency and rerun the command.
+Install the missing local dependency and rerun the command.
 
 ### Auto-detection picked the wrong browser profile
 
@@ -269,25 +342,11 @@ This usually means the cookie import worked but the source cookies are not the a
 
 ### You want more details about a failed run
 
-- Inspect the job directory under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`.
-- The worker log and captured diagnostics are stored there.
+Inspect the job directory under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`. The worker log and captured diagnostics are stored there.
 
-## Detailed docs
+## Verification
 
-- `docs/ORACLE_DESIGN.md` — architecture, lifecycle, queueing, persistence, presets, and recovery behavior
-- `docs/ORACLE_RECOVERY_DRILL.md` — safe expired-auth recovery validation drill
-- `docs/ORACLE_ISOLATED_PI_VALIDATION.md` — repeatable isolated `pi` session smoke test for local-extension validation
-
-## Privacy / local data
-
-This extension is local-first, but it does read and persist local data:
-- `/oracle-auth` reads ChatGPT cookies from the configured local browser profile
-- job archives are uploaded to ChatGPT.com
-- responses and artifacts are written under the configured oracle jobs dir
-
-Review the code and design docs before using it with sensitive material.
-
-## Validation helpers
+Useful local checks:
 
 ```bash
 npm run check:oracle-extension
@@ -295,21 +354,32 @@ npm run typecheck
 npm run typecheck:worker-helpers
 npm run sanity:oracle
 npm run pack:check
-# conventional local gate
 npm test
-# or all at once
 npm run verify:oracle
 ```
 
-`npm publish` is also guarded locally via `prepublishOnly` and will run `npm run verify:oracle` before publishing.
+`npm publish` is guarded by `prepublishOnly`, which runs `npm run verify:oracle`.
+
+For end-to-end local-extension smoke testing, use [`docs/ORACLE_ISOLATED_PI_VALIDATION.md`](docs/ORACLE_ISOLATED_PI_VALIDATION.md). That workflow launches isolated `pi` sessions against this checkout and uses `instant` or `thinking_light`, as required by the project validation policy.
 
-## Beta caveats
+## Project map
 
-The highest-risk areas to monitor are:
-- ChatGPT UI drift
-- auth/bootstrap drift
-- artifact download behavior
-- local environment assumptions
+| Path | Purpose |
+| --- | --- |
+| [`extensions/oracle/index.ts`](extensions/oracle/index.ts) | Extension entrypoint |
+| `extensions/oracle/lib/` | Commands, tools, config, jobs, queueing, runtime, poller |
+| `extensions/oracle/worker/` | Detached provider web worker and UI/auth helpers |
+| `extensions/oracle/shared/` | Shared process, state, job, and observability helpers |
+| [`prompts/oracle.md`](prompts/oracle.md) | `/oracle` prompt-template workflow |
+| [`prompts/oracle-followup.md`](prompts/oracle-followup.md) | `/oracle-followup` prompt-template workflow |
+| `scripts/oracle-sanity-*` | Local sanity and archive-safety checks |
+| [`docs/ORACLE_DESIGN.md`](docs/ORACLE_DESIGN.md) | Architecture, lifecycle, queueing, persistence, recovery behavior |
+| [`docs/ORACLE_ISOLATED_PI_VALIDATION.md`](docs/ORACLE_ISOLATED_PI_VALIDATION.md) | Repeatable isolated `pi` validation workflow |
+| [`docs/ORACLE_RECOVERY_DRILL.md`](docs/ORACLE_RECOVERY_DRILL.md) | Safe expired-auth recovery drill |
+
+## Next action
+
+Install the package, run `/oracle-auth`, then submit the tiny README/package review job above. If you are evaluating the design before running it, start with [`docs/ORACLE_DESIGN.md`](docs/ORACLE_DESIGN.md).
 
 ## License