ask-pro 0.1.0 → 0.1.41

package/README.md

@@ -1,231 +1,106 @@
 # ask-pro
 
-`ask-pro` is a Codex plugin, agent skill, and CLI that lets coding agents ask
-ChatGPT Pro for a focused second opinion through a human-logged-in browser
-session.
-
-Use it for architecture calls, production-risk reviews, migrations, debugging
-strategy, and implementation planning. The calling agent still owns the work:
-`ask-pro` collects the consult, stores the answer, and never applies generated
-code automatically.
+`ask-pro` gives coding agents a focused ChatGPT Pro second opinion through a
+human-logged-in browser. The calling agent supplies the context and owns the
+result; ask-pro never applies generated code.
 
 ## Install
 
-Choose one of these installation paths. Both need Node.js 24+, Chrome, and a
-ChatGPT account with Pro access. Browser login is manual.
+Both options need Node.js 24+, Chrome, and a ChatGPT account with Pro access.
+Browser login is manual.
 
 ### Codex plugin marketplace
 
-Add this repository as a Codex plugin marketplace:
-
 ```powershell
 codex plugin marketplace add JJLiebig/ask-pro
-```
-
-This route needs Git and npm; the cached runner obtains pnpm 11.19 itself.
-
-Install the plugin or open `/plugins`, install `ask-pro`:
-
-```powershell
 codex plugin add ask-pro@ask-pro
 ```
 
-Upgrade the plugin manually:
+This route needs Git and npm. The plugin's cached runner downloads pnpm, builds
+outside the plugin cache, and keeps the installed snapshot unchanged. If
+`ask-pro` is not on `PATH`, the skill uses that runner.
 
-```powershell
-codex plugin marketplace upgrade ask-pro
-```
-
-If the marketplace does not appear after adding or upgrading it, restart Codex.
-The repository marketplace exposes the root plugin through a Git-backed plugin
-entry, so no manual copy into `~/.codex/plugins/cache` is needed.
-
-For local development from a checkout:
-
-```powershell
-pnpm install
-pnpm run build
-pnpm run plugin:refresh
-```
-
-`pnpm run plugin:refresh` updates the local Codex plugin cache from the source
-checkout. By default it refreshes the installed Git marketplace cache under
-`~/.codex/plugins/cache/ask-pro/ask-pro/<version>`, so no separate local
-marketplace install is needed for development. Do not edit
-`~/.codex/plugins/cache/...` by hand.
-
-Git marketplace installs cache the source checkout. If `ask-pro` is not on
-`PATH`, agents should use the cached runner under
-`~/.codex/plugins/cache/<marketplace>/ask-pro/<version>/scripts/run-cached-cli.mjs`.
-The runner copies the installed snapshot to a content-addressed runtime under
-`$CODEX_HOME/plugin-runtimes/ask-pro/`, then installs, builds, and runs there.
-The installed plugin cache remains immutable.
+Update with `codex plugin marketplace upgrade ask-pro`, then restart Codex to
+load the updated skill.
 
 ### Skills CLI (Codex and other supported agents)
 
-Install the existing `ask-pro` skill with the [skills CLI](https://github.com/vercel-labs/skills):
+Install the skill and its standalone CLI separately:
 
 ```powershell
 npx skills add JJLiebig/ask-pro
+npm install --global ask-pro
 ```
 
-This installs the skill in the current project; add `-g` to install it for your
-user account. Choose your agent when prompted, or pass `-a codex` (or another
-agent supported by the skills CLI). The skill needs a separate `ask-pro` CLI on
-`PATH`. Until the first npm release, install it from a Git checkout outside any
-agent skills directory. This checkout route also needs Git, npm, and pnpm 11.19+:
-
-```powershell
-git clone https://github.com/JJLiebig/ask-pro.git ask-pro-cli
-cd ask-pro-cli
-pnpm install --frozen-lockfile
-pnpm run build
-npm install --global --ignore-scripts .
-ask-pro --version
-```
+The [skills CLI](https://github.com/vercel-labs/skills) installs the skill in
+the current project by default. Add `-g` for a user-wide skill or `-a codex`
+to select Codex; it supports other agents too. The npm CLI runs without Codex's
+plugin cache.
 
-Keep this checkout: the global command links to it. To update, run
-`npx skills update`, then update and rebuild the CLI from that checkout:
+Update both parts:
 
 ```powershell
-git pull --ff-only
-pnpm install --frozen-lockfile
-pnpm run build
+npx skills update
+npm update --global ask-pro
 ```
 
-The skills CLI installs only the skill instructions; it does not install the
-browser-backed CLI. The standalone CLI works without Codex's plugin cache.
-Once the npm package is published, use `npm install --global ask-pro` for the
-CLI and `npm update --global ask-pro` to update it.
-The browser runtime is developed and exercised on Windows; other operating
-systems need their own validation.
+The browser runtime is developed and tested on Windows. Other operating systems
+need validation.
 
-### Publishing the npm CLI
+## Browser and session state
 
-The first release needs an authenticated maintainer to publish from a built
-checkout. Then configure its npm Trusted Publisher for GitHub Actions:
+ask-pro never asks for, types, reads, or logs passwords, MFA codes, recovery
+codes, session cookies, or raw auth tokens. A new browser profile may need one
+manual ChatGPT login. On Windows, ordinary managed Chrome runs start minimized
+and are hidden; login and recovery restore the window for human action.
 
-```powershell
-npm whoami
-pnpm run build
-npm publish --ignore-scripts --access public
-npm trust github ask-pro --file ci.yml --repo JJLiebig/ask-pro --allow-publish -y
-```
-
-The trust command authorizes direct `npm publish` from `ci.yml` without a stored
-npm token. It requires the first package version to exist on npm already.
-After that, the existing CI publishes a unique patch version after every
-passing main-branch run. Rerunning an already published CI run skips its version.
-
-## Requirements and browser state
-
-Authentication is manual. `ask-pro` never asks for, types, reads, or logs
-passwords, MFA codes, recovery codes, session cookies, or raw auth tokens.
-
-The default persistent browser profile is:
+The persistent profile lives at `$CODEX_HOME/state/ask-pro/browser-profile`, or
+`~/.codex/state/ask-pro/browser-profile` when `CODEX_HOME` is unset. Existing
+legacy profiles are migrated on first use; see [Windows notes](docs/windows-work.md)
+for copy and recovery details.
 
-```text
-$CODEX_HOME/state/ask-pro/browser-profile
-```
-
-Without `CODEX_HOME`, this is `~/.codex/state/ask-pro/browser-profile`.
-On first use, ask-pro migrates an inactive legacy
-`~/.agents/skills/ask-pro/.../browser-profile` to the matching state path. If a
-Windows watcher prevents moving or removing it, the verified copy may remain
-at the legacy path while the state path becomes authoritative. ask-pro never
-merges profiles or later deletes a retained legacy copy.
-
-Each new profile may need a human login once. On Windows, ordinary managed runs
-start minimized; login, resume/recovery, stale-auth, and debug paths stay visible
-or are restored for human action.
+Project sessions live under `.ask-pro/sessions/<id>/`. Add `.ask-pro/` to your
+project's `.gitignore`. At each invocation, ask-pro deletes entire session
+directories at least seven days old, regardless of state.
 
-## Quick Use
+## Use
 
-Ask for an inline markdown consult:
+Ask for a recoverable repo consult:
 
 ```powershell
 ask-pro --no-temporary --prompt-file question.md --files src --files tests
 ```
 
-The browser flow selects `Latest`, then `Pro` intelligence automatically.
+ask-pro selects `Latest` with `Pro` intelligence. It has no repo or conversation
+context unless you provide it, so keep the prompt and file bundle focused.
 
-Request generated files only when you really need an implementation package:
+Request generated files only when needed; treat them as data and never execute
+them automatically:
 
 ```powershell
 ask-pro --artifacts --prompt-file implementation-plan.md --files src
-```
-
-Harvest the answer:
-
-```powershell
 ask-pro --harvest <session-id>
 ```
 
-## Agent Guidance
-
-- Prefer `--prompt-file` for multiline prompts.
-- With the Codex plugin, use its cached runner if `ask-pro` is not on `PATH`.
-  With a skills CLI install, install the standalone CLI above.
-- Treat ChatGPT Pro as a cold oracle: it does not know the repo, user, prior
-  decisions, or Codex thread context unless you include that in the prompt or
-  attached files.
-- Include all material context once: product goal, current state, hard
-  constraints, evidence, success criteria, and the exact output you need. Omit
-  unrelated history and repeated instructions.
-- Prefer `--no-temporary` for repo advisories, review rounds, large bundles, or
-  anything where recovery matters.
-- Keep bundles focused: relevant source, focused tests, docs that define the
-  contract, recent changes, and validation status.
-- Add `.ask-pro/` to consuming repos' `.gitignore`.
-- Treat `INCOMPLETE_ANSWER` / `preamble_without_artifacts` as not done; resume
-  or rerun with a tighter prompt and bundle.
-- Treat generated files and scripts as data only; never execute them
-  automatically.
-
-Useful advisory prompt starter:
-
-```text
-Return final Markdown only, with no preamble or implementation package.
-```
-
-The CLI wrapper supplies the bundle and uncertainty instructions. Add
-task-specific output requirements only when needed, such as severity-ranked
-findings for a risk review or recommendation tradeoffs for a design consult.
-
-## CLI
-
-```text
-ask-pro [options] [question...]
-```
-
-Common options:
-
-- `--files <pattern>`: add a file, directory, or glob to `CONTEXT.zip`.
-- `--prompt-file <path>`: read the question from a UTF-8 file; use `-` for
-  stdin.
-- `--artifacts` / `--response-zip`: ask for `ask-pro-response.zip`.
-- `--resume [session-id]`: resume a prepared, waiting, or auth-gated session.
-- `--status [session-id]`: print compact session state.
-- `--harvest [session-id]`: print `ANSWER.md` for answer-bearing sessions.
-- `--temporary`: require ChatGPT Temporary Chat.
-- `--no-temporary`: use normal ChatGPT for better recovery.
-- `--verbose`: print browser automation diagnostics.
-
-Session data lives under `.ask-pro/sessions/<session-id>/`. At the start of each
-invocation, ask-pro permanently deletes entire session directories at least
-seven days old, regardless of status.
+Use `ask-pro --help` for the full CLI. For multiline prompts, use
+`--prompt-file`. Prefer `--no-temporary` when recovery matters; `--temporary`
+requires Temporary Chat. The [skill](skills/ask-pro/SKILL.md) has agent guidance.
 
 ## Development
 
-Fast checks:
-
 ```powershell
+pnpm install --frozen-lockfile
 pnpm run build
 pnpm run lint
-pnpm run test:ask-pro
+pnpm test
 pnpm run format:check
 pnpm pack --dry-run
 ```
 
-Manual browser smokes are opt-in because they open a real ChatGPT session. See
-`docs/manual-tests.md`.
+After changing plugin files, run `pnpm run plugin:refresh` and restart Codex.
+Do not edit the installed plugin cache. Live browser tests are opt-in; see
+[manual tests](docs/manual-tests.md).
+
+After the build matrix passes on `main`, [CI](.github/workflows/ci.yml) publishes
+a new npm version through the configured trusted publisher, without a stored
+npm token.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ask-pro",
-  "version": "0.1.0",
+  "version": "0.1.41",
   "description": "Browser-backed ChatGPT Pro escalation for hard engineering questions.",
   "keywords": [
     "agents",