painapple-code 1.0.1__tar.gz → 1.0.2__tar.gz

painapple_code-1.0.2/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+Notable changes are documented here per release. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org/), and the git tag is the single source of truth for the version (the PyPI wheel, the Docker image tag, and `__version__` all derive from it).
+
+## 1.0.1 — 2026-08-31
+
+### Removed
+
+- The two "plain CLI" fallback drivers: the `claude` line-protocol driver (superseded by the wire-identical `claude-sdk` provider) and the `codex` exec driver (`codex exec --json` had no stdin protocol — every prompt rode argv, readable via `ps` by any local account; see SECURITY.md). Saved configs keep working: the legacy provider names alias to `claude-sdk` and `codex-app-server`, and old Codex exec sessions resume natively through the same `$CODEX_HOME` thread store.
+
+### Fixed
+
+- Docs: TLS opt-in now points at the `[tls]` extra instead of a hardcoded dependency pin.
+
+## 1.0.0 — 2026-08-26
+
+First public release.

{painapple_code-1.0.1 → painapple_code-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: painapple-code
-Version: 1.0.1
+Version: 1.0.2
 Summary: Self-hosted remote UI for Claude Code that journals every turn - background AI summaries become shadow-git commits and a queryable DuckDB history
 Author-email: Michał Booth-Wrotkowski <michal@boothw.com>
 License-Expression: AGPL-3.0-or-later
@@ -53,7 +53,7 @@ Dynamic: license-file
 
 # pAInapple Code
 
-A self-hosted web client for [Claude Code](https://github.com/anthropics/claude-code), installable as a PWA. The server **runs on your own machine** and drives Claude Code through the **official Agent SDK**, using **your own Claude subscription**. [OpenAI Codex CLI](https://painapple.ai/guides/engines/) support is experimental.
+A self-hosted web client for [Claude Code](https://github.com/anthropics/claude-code), installable as a PWA. The server **runs on your own machine** and drives Claude Code through the **official Agent SDK**, using **your own Claude subscription**. [OpenAI Codex CLI](https://painapple.ai/guides/providers/) support is experimental.
 Inspired by [code-server](https://github.com/coder/code-server).
 
 [**Auto Journal**](#auto-journal-shadow-git): after every turn, a background fork to a fast model (Haiku by default) summarizes it into a local DuckDB and a shadow-git commit — so the **full history of any topic or file stays searchable**, by you *and* by future Claude sessions.
@@ -66,7 +66,7 @@ Right now it's a PWA, but **desktop and mobile apps are in development**.
 
 ## What it is, and what it isn't
 
-**It is** a thin wrapper around Claude Code — every prompt streams through the official CLI/Agent SDK, and any session started here can be resumed in the plain CLI with `claude --resume <id>`. **It never modifies Claude's system prompt, tool policy, or behavior** — no injected planning steps, no hidden instructions. What it does add to a prompt is the context you attached: the output of `!bang` commands you ran, paths of files you uploaded, and snippets from the comments stash are prepended as plain text. The same wrapper can drive the [OpenAI Codex CLI](https://painapple.ai/guides/engines/), selected per session, resumable with `codex exec resume <id>` — the Codex path is **newer and has had less testing** than the Claude path.
+**It is** a thin wrapper around Claude Code — every prompt streams through the official CLI/Agent SDK, and any session started here can be resumed in the plain CLI with `claude --resume <id>`. **It never modifies Claude's system prompt, tool policy, or behavior** — no injected planning steps, no hidden instructions. What it does add to a prompt is the context you attached: the output of `!bang` commands you ran, paths of files you uploaded, and snippets from the comments stash are prepended as plain text. The same wrapper can drive the [OpenAI Codex CLI](https://painapple.ai/guides/providers/), selected per session, resumable with `codex exec resume <id>` — the Codex path is **newer and has had less testing** than the Claude path.
 
 **It is not** a hosted service. You run it, on your hardware, with your own Claude account.
 
@@ -141,7 +141,7 @@ Search **every prompt you've ever sent**, across all sessions and projects, with
 - **Server:** Linux, macOS, or Windows 11 (Windows 10 is untested, but will probably work)
 - **Direct install:** Python 3.12+ and the [Claude Code CLI](https://github.com/anthropics/claude-code), installed and authenticated. (The Docker image ships Python and Node, and installs the agent CLIs itself on first start.)
 - **Git** on `PATH` — the auto-journal records every turn as a shadow-git commit, and the Git panel shells out to it. **Without git the server still runs, but journals nothing.** (Windows: [Git for Windows](https://git-scm.com/download/win).)
-- **Optional:** Docker or Podman for the sandboxed `--in-docker` mode and named container instances; the [OpenAI Codex CLI](https://github.com/openai/codex) for the Codex engine.
+- **Optional:** Docker or Podman for the sandboxed `--in-docker` mode and named container instances; the [OpenAI Codex CLI](https://github.com/openai/codex) for the Codex provider.
 - **Client:** any modern browser with network access to the server.
 
 ## Quick start
@@ -199,7 +199,9 @@ Git for Windows is worth installing even if you use another git: the optional [h
 
 ### Then what?
 
-The console prints the **app URL with a login token embedded** — open it in any browser on the network, pick a project on the welcome screen, and you're in. Point a phone or tablet at the same URL and install it as a PWA.
+The console prints the **app URL with a login token embedded** — open it in a browser on that machine, pick a project on the welcome screen, and you're in. It's a full PWA, so you can install it as a standalone app: **macOS Safari** → File → *Add to Dock*, **Chrome / Edge** (Windows, Linux, macOS) → the install icon in the address bar.
+
+By default the server binds to `127.0.0.1`, so that URL only works on the machine it runs on. **Reaching it from a phone or tablet is optional and takes a bit more setup**: bind wider with `--host 0.0.0.0` (non-loopback binds auto-enable TLS with a self-signed certificate — you'll accept a one-time browser warning), or put a reverse proxy with a real domain and certificate in front, which is what iOS/iPadOS wants before it will install the PWA properly. Read the [security notes](https://painapple.ai/getting-started/security/) before exposing it beyond your own machine, and the [iPad & mobile guide](https://painapple.ai/guides/ipad-and-mobile/) for the full walkthrough.
 
 In container mode the image is pulled automatically on the first run (`painapple pull` re-fetches it to update or pin a release); state persists in named volumes and your projects are bind-mounted. Running it inside a single project works too, and `--workspace /path` serves any folder without `cd`-ing there.
 
@@ -210,7 +212,7 @@ In container mode the image is pulled automatically on the first run (`painapple
 - **GitHub Codespaces / Dev Containers** — one line in `devcontainer.json` boots every Codespace with pAInapple Code installed, started, and port-forwarded → [Dev Container Feature](https://painapple.ai/getting-started/install-devcontainer/)
 - **From source** — `git clone`, `venv/bin/pip install -e .`, run with `venv/bin/painapple` → [source install](https://painapple.ai/getting-started/install-pip/#from-a-source-checkout)
 
-**Full documentation** — configuration, engines, every feature, and the CLI/API reference — lives at **[painapple.ai](https://painapple.ai/)**.
+**Full documentation** — configuration, providers, every feature, and the CLI/API reference — lives at **[painapple.ai](https://painapple.ai/)**.
 
 ## Authentication
 
@@ -239,7 +241,7 @@ The most common flags:
 | `--workspace` | `.` | Workspace root — the directory holding your projects. You pick the project in-app from the welcome screen (`--cwd` is an alias) |
 | `--instance-name`, `--accent` | — | Label + accent color to distinguish multiple instances |
 | `--tls` | `auto` | Self-signed TLS, auto-enabled on non-loopback binds |
-| `--default-provider` | `claude-sdk` | Default [AI engine](https://painapple.ai/guides/engines/) for new sessions — Claude Code (SDK or classic line protocol) or OpenAI Codex |
+| `--default-provider` | `claude-sdk` | Default [AI provider](https://painapple.ai/guides/providers/) for new sessions — Claude Code (Agent SDK) or OpenAI Codex |
 | `--profile` | — | Run a named profile — several independent deployments (host or docker mode) under one user |
 | `--in-docker` | off | Run the same invocation in a container instead (prebuilt image, cwd mounted) |
 
@@ -283,7 +285,7 @@ This is an MVP — there are tradeoffs.
 2. **Windowing system** — works, but doesn't support multiple instances of the same widget and could use a rethink.
 3. **Code editor** — currently a notepad with syntax highlighting. The plan is a review-driven workflow rather than a VSCode-grade editor; the markdown inline editor is the exception and works well for plan/doc tweaks.
 4. **GUI for OS-level features** (git widget, file explorer) — exists, but I prefer the embedded terminal for `grep`/`sed`/`find`/`du`, so these widgets have not been a priority.
-5. **Codex engine** — functional, but much newer than the Claude path and not yet as thoroughly tested.
+5. **Codex provider** — functional, but much newer than the Claude path and not yet as thoroughly tested.
 
 ## License
 

{painapple_code-1.0.1 → painapple_code-1.0.2}/README.dockerhub.md

@@ -1,6 +1,6 @@
 # pAInapple Code
 
-A self-hosted web UI for [Claude Code](https://github.com/anthropics/claude-code) sessions — a Python server that runs the CLI as a subprocess and serves a vanilla-JS PWA on top. Inspired by [code-server](https://github.com/coder/code-server). It can also drive the [OpenAI Codex CLI](https://painapple.ai/guides/engines/) as a second engine (experimental).
+A self-hosted web UI for [Claude Code](https://github.com/anthropics/claude-code) sessions — a Python server that runs the CLI as a subprocess and serves a vanilla-JS PWA on top. Inspired by [code-server](https://github.com/coder/code-server). It can also drive the [OpenAI Codex CLI](https://painapple.ai/guides/providers/) as a second provider (experimental).
 
 Thanks to the [**Auto Journal**](https://painapple.ai/guides/shadow-git/), you can easily pull up the full history of any topic or file you've already worked on. After each turn finishes, the session is forked in the background to a fast model (Haiku by default) that summarizes the turn — and the summary is stored in a local DuckDB and in the project's shadow git, as the commit message over everything that changed during the turn. It's not just for you: the optional `shadow-git-helper` agent gives Claude the same access, digging through past turns to brief the session with full historical context.
 
@@ -14,7 +14,7 @@ The image ships Python 3.13 and Node 20; the agent CLIs (`@anthropic-ai/claude-c
 
 **pAInapple Code effectively gives whoever holds its password a remote shell on the host.** Claude Code can execute commands, edit files, and reach the network on the user that started the container. The built-in auth is a single-password gate — useful, but not a substitute for proper network controls.
 
-- The default `docker run` example below binds **`127.0.0.1:8765`**. Don't change that to `0.0.0.0` (or a public IP) without putting a reverse proxy with TLS and ideally a VPN / Tailscale / SSH-tunnel layer in front.
+- The default `docker run` example below binds **`127.0.0.1:8765`**. Don't change that to `0.0.0.0` (or a public IP) without putting a reverse proxy with TLS and ideally a VPN or SSH-tunnel layer in front.
 - The auth password is generated on first start but **not printed to the container's logs** (inside the container the bind is non-loopback, so credentials are hidden from stdout by default — `docker logs` persists). Reveal the login URL with `painapple password` (pip CLI), or read it directly: `docker exec painapple-code awk '/^password:/ {print $2}' /home/app/.config/painapple-code/config.yaml`. Open it once — the cookie keeps you logged in afterwards.
 - The terminal widget is a real PTY running as the container user. In `YOLO` permission mode anyone with the password can run arbitrary commands.
 
@@ -159,7 +159,7 @@ docker buildx imagetools inspect wrotek/painapple-code:latest
 
 ## What it is, and what it isn't
 
-**It is** a thin wrapper around Claude Code — every prompt streams through the official CLI/Agent SDK, and any session started here can be resumed in the plain CLI with `claude --resume <id>`. **It never modifies Claude's system prompt, tool policy, or behavior** — no injected planning steps, no hidden instructions. What it does add to a prompt is the context you attached: the output of `!bang` commands you ran, paths of files you uploaded, and snippets from the comments stash are prepended as plain text. The same wrapper can drive the [OpenAI Codex CLI](https://painapple.ai/guides/engines/), selected per session, resumable with `codex exec resume <id>` — the Codex path is **newer and has had less testing** than the Claude path.
+**It is** a thin wrapper around Claude Code — every prompt streams through the official CLI/Agent SDK, and any session started here can be resumed in the plain CLI with `claude --resume <id>`. **It never modifies Claude's system prompt, tool policy, or behavior** — no injected planning steps, no hidden instructions. What it does add to a prompt is the context you attached: the output of `!bang` commands you ran, paths of files you uploaded, and snippets from the comments stash are prepended as plain text. The same wrapper can drive the [OpenAI Codex CLI](https://painapple.ai/guides/providers/), selected per session, resumable with `codex exec resume <id>` — the Codex path is **newer and has had less testing** than the Claude path.
 
 **It is not** a hosted service. You run it, on your hardware, with your own Claude account.
 
@@ -172,7 +172,7 @@ Full list on [GitHub](https://github.com/wrotek/painapple-code):
 - **Shadow Git auto-journal** — after each turn the session forks itself to a fast summarizer model (Haiku by default); its structured write-up becomes the commit message for a per-project shadow git repo holding that turn's file changes, and a queryable DuckDB row.
 - **Multi-session tabs**, real PTY terminal, cost analytics, prompt history search, comments stash, discussion threads.
 - **PWA** — installable on iPad / Android / desktop, offline fallback.
-- **Permission modes** per session: `Ask` (the default — every edit/command waits on an approval card), `Plan` (read-only), `Accept-Edits`, `Don't Ask`, `Auto` (Claude's AI classifier), `YOLO`.
+- **Permission modes** — Claude Code's own modes, picked per session instead of at startup, with its approval prompts rendered as in-chat cards: `Ask` (the default — every edit/command waits on a card), `Plan` (read-only), `Accept-Edits`, `Don't Ask`, `Auto` (Claude's AI classifier), `YOLO`.
 
 ## Source & support
 

{painapple_code-1.0.1 → painapple_code-1.0.2}/README.md

@@ -1,6 +1,6 @@
 # pAInapple Code
 
-A self-hosted web client for [Claude Code](https://github.com/anthropics/claude-code), installable as a PWA. The server **runs on your own machine** and drives Claude Code through the **official Agent SDK**, using **your own Claude subscription**. [OpenAI Codex CLI](https://painapple.ai/guides/engines/) support is experimental.
+A self-hosted web client for [Claude Code](https://github.com/anthropics/claude-code), installable as a PWA. The server **runs on your own machine** and drives Claude Code through the **official Agent SDK**, using **your own Claude subscription**. [OpenAI Codex CLI](https://painapple.ai/guides/providers/) support is experimental.
 Inspired by [code-server](https://github.com/coder/code-server).
 
 [**Auto Journal**](#auto-journal-shadow-git): after every turn, a background fork to a fast model (Haiku by default) summarizes it into a local DuckDB and a shadow-git commit — so the **full history of any topic or file stays searchable**, by you *and* by future Claude sessions.
@@ -13,7 +13,7 @@ Right now it's a PWA, but **desktop and mobile apps are in development**.
 
 ## What it is, and what it isn't
 
-**It is** a thin wrapper around Claude Code — every prompt streams through the official CLI/Agent SDK, and any session started here can be resumed in the plain CLI with `claude --resume <id>`. **It never modifies Claude's system prompt, tool policy, or behavior** — no injected planning steps, no hidden instructions. What it does add to a prompt is the context you attached: the output of `!bang` commands you ran, paths of files you uploaded, and snippets from the comments stash are prepended as plain text. The same wrapper can drive the [OpenAI Codex CLI](https://painapple.ai/guides/engines/), selected per session, resumable with `codex exec resume <id>` — the Codex path is **newer and has had less testing** than the Claude path.
+**It is** a thin wrapper around Claude Code — every prompt streams through the official CLI/Agent SDK, and any session started here can be resumed in the plain CLI with `claude --resume <id>`. **It never modifies Claude's system prompt, tool policy, or behavior** — no injected planning steps, no hidden instructions. What it does add to a prompt is the context you attached: the output of `!bang` commands you ran, paths of files you uploaded, and snippets from the comments stash are prepended as plain text. The same wrapper can drive the [OpenAI Codex CLI](https://painapple.ai/guides/providers/), selected per session, resumable with `codex exec resume <id>` — the Codex path is **newer and has had less testing** than the Claude path.
 
 **It is not** a hosted service. You run it, on your hardware, with your own Claude account.
 
@@ -88,7 +88,7 @@ Search **every prompt you've ever sent**, across all sessions and projects, with
 - **Server:** Linux, macOS, or Windows 11 (Windows 10 is untested, but will probably work)
 - **Direct install:** Python 3.12+ and the [Claude Code CLI](https://github.com/anthropics/claude-code), installed and authenticated. (The Docker image ships Python and Node, and installs the agent CLIs itself on first start.)
 - **Git** on `PATH` — the auto-journal records every turn as a shadow-git commit, and the Git panel shells out to it. **Without git the server still runs, but journals nothing.** (Windows: [Git for Windows](https://git-scm.com/download/win).)
-- **Optional:** Docker or Podman for the sandboxed `--in-docker` mode and named container instances; the [OpenAI Codex CLI](https://github.com/openai/codex) for the Codex engine.
+- **Optional:** Docker or Podman for the sandboxed `--in-docker` mode and named container instances; the [OpenAI Codex CLI](https://github.com/openai/codex) for the Codex provider.
 - **Client:** any modern browser with network access to the server.
 
 ## Quick start
@@ -146,7 +146,9 @@ Git for Windows is worth installing even if you use another git: the optional [h
 
 ### Then what?
 
-The console prints the **app URL with a login token embedded** — open it in any browser on the network, pick a project on the welcome screen, and you're in. Point a phone or tablet at the same URL and install it as a PWA.
+The console prints the **app URL with a login token embedded** — open it in a browser on that machine, pick a project on the welcome screen, and you're in. It's a full PWA, so you can install it as a standalone app: **macOS Safari** → File → *Add to Dock*, **Chrome / Edge** (Windows, Linux, macOS) → the install icon in the address bar.
+
+By default the server binds to `127.0.0.1`, so that URL only works on the machine it runs on. **Reaching it from a phone or tablet is optional and takes a bit more setup**: bind wider with `--host 0.0.0.0` (non-loopback binds auto-enable TLS with a self-signed certificate — you'll accept a one-time browser warning), or put a reverse proxy with a real domain and certificate in front, which is what iOS/iPadOS wants before it will install the PWA properly. Read the [security notes](https://painapple.ai/getting-started/security/) before exposing it beyond your own machine, and the [iPad & mobile guide](https://painapple.ai/guides/ipad-and-mobile/) for the full walkthrough.
 
 In container mode the image is pulled automatically on the first run (`painapple pull` re-fetches it to update or pin a release); state persists in named volumes and your projects are bind-mounted. Running it inside a single project works too, and `--workspace /path` serves any folder without `cd`-ing there.
 
@@ -157,7 +159,7 @@ In container mode the image is pulled automatically on the first run (`painapple
 - **GitHub Codespaces / Dev Containers** — one line in `devcontainer.json` boots every Codespace with pAInapple Code installed, started, and port-forwarded → [Dev Container Feature](https://painapple.ai/getting-started/install-devcontainer/)
 - **From source** — `git clone`, `venv/bin/pip install -e .`, run with `venv/bin/painapple` → [source install](https://painapple.ai/getting-started/install-pip/#from-a-source-checkout)
 
-**Full documentation** — configuration, engines, every feature, and the CLI/API reference — lives at **[painapple.ai](https://painapple.ai/)**.
+**Full documentation** — configuration, providers, every feature, and the CLI/API reference — lives at **[painapple.ai](https://painapple.ai/)**.
 
 ## Authentication
 
@@ -186,7 +188,7 @@ The most common flags:
 | `--workspace` | `.` | Workspace root — the directory holding your projects. You pick the project in-app from the welcome screen (`--cwd` is an alias) |
 | `--instance-name`, `--accent` | — | Label + accent color to distinguish multiple instances |
 | `--tls` | `auto` | Self-signed TLS, auto-enabled on non-loopback binds |
-| `--default-provider` | `claude-sdk` | Default [AI engine](https://painapple.ai/guides/engines/) for new sessions — Claude Code (SDK or classic line protocol) or OpenAI Codex |
+| `--default-provider` | `claude-sdk` | Default [AI provider](https://painapple.ai/guides/providers/) for new sessions — Claude Code (Agent SDK) or OpenAI Codex |
 | `--profile` | — | Run a named profile — several independent deployments (host or docker mode) under one user |
 | `--in-docker` | off | Run the same invocation in a container instead (prebuilt image, cwd mounted) |
 
@@ -230,7 +232,7 @@ This is an MVP — there are tradeoffs.
 2. **Windowing system** — works, but doesn't support multiple instances of the same widget and could use a rethink.
 3. **Code editor** — currently a notepad with syntax highlighting. The plan is a review-driven workflow rather than a VSCode-grade editor; the markdown inline editor is the exception and works well for plan/doc tweaks.
 4. **GUI for OS-level features** (git widget, file explorer) — exists, but I prefer the embedded terminal for `grep`/`sed`/`find`/`du`, so these widgets have not been a priority.
-5. **Codex engine** — functional, but much newer than the Claude path and not yet as thoroughly tested.
+5. **Codex provider** — functional, but much newer than the Claude path and not yet as thoroughly tested.
 
 ## License
 

{painapple_code-1.0.1 → painapple_code-1.0.2}/SECURITY.md

@@ -77,7 +77,7 @@ Auto-journal, or the status-bar pill).
 
 Accepted by design: it is a core feature of the tool, matching how editor
 local-history features behave. Everything stays on your machine — except the
-optional summaries, which are generated by the same agent engine the session
+optional summaries, which are generated by the same agent provider the session
 already uses. Turn off *Rich Commits* to keep the journal local-only.
 
 ### Subprocess tracking is incomplete
@@ -92,26 +92,26 @@ Impact is a resource leak on a machine the user already controls.
 than its own OS user. (This entry is about *tracking* only — for what a
 child process exposes while it runs, see the next item.)
 
-### Prompts never reach `ps` (the `codex` exec engine was removed)
+### Prompts never reach `ps` (the `codex` exec provider was removed)
 
-Historical: the `codex` exec engine (`codex exec --json`, off by default)
+Historical: the `codex` exec provider (`codex exec --json`, off by default)
 accepted its prompt only as a command-line argument — no stdin protocol —
 so on a session bound to it, each turn's prompt and the background summary
 fork's prompt were visible in `ps` and in `/proc/<pid>/cmdline`
 (world-readable on Linux) for as long as the turn ran. The server could not
 route around it; the constraint was the CLI's argument interface.
 
-Resolved by **removing the engine** rather than accepting the risk: every
-registered engine passes prompts over stdio (`claude-sdk` via the SDK
+Resolved by **removing the provider** rather than accepting the risk: every
+registered provider passes prompts over stdio (`claude-sdk` via the SDK
 driver's stdin protocol, `codex-app-server` via JSON-RPC over stdio).
-Sessions persisted with the removed engine names resolve to their
+Sessions persisted with the removed provider names resolve to their
 same-family successor (`codex` → `codex-app-server`, which reads the same
 `$CODEX_HOME` thread store; `claude` → the wire-identical `claude-sdk`).
 
 The `Capabilities.prompt_in_argv` seam survives: a drop-in third-party
-engine that takes prompts in argv must declare it and gets the
-Settings → Engines warning automatically
-(`test_no_registered_engine_puts_prompts_in_argv` keeps the shipped set
+provider that takes prompts in argv must declare it and gets the
+Settings → Providers warning automatically
+(`test_no_registered_provider_puts_prompts_in_argv` keeps the shipped set
 clean). Note that commands you run yourself — the terminal, `!bang`
 commands, `/api/exec` — appear in `ps` like any shell command; only
 *prompts* are guaranteed off the command line.
@@ -186,8 +186,8 @@ mid-transfer, rather than buffering then measuring.
 
 ## Supported versions
 
-This project is pre-1.0 (Beta). Security fixes land on the latest released
-version only; there are no long-term support branches yet.
+Security fixes land on the latest released version only; there are no
+long-term support branches.
 
 | Version | Supported |
 |---------|-----------|

{painapple_code-1.0.1 → painapple_code-1.0.2}/docs-site/features.md

@@ -7,8 +7,8 @@ Everything pAInapple Code and the web client can do, in one place. Each area lin
 | Feature | What it does | Guide |
 |---|---|---|
 | Multi-session tabs | Several concurrent sessions in browser-style tabs; terminals and file previews can sit in the same tab strip | [Sessions & tabs](guides/sessions.md) |
-| AI engines | Pick Claude Code or OpenAI Codex per session — per-engine models, permission vocabularies, effort scales, defaults, and in-app CLI login. Codex support is experimental | [AI engines](guides/engines.md) |
-| Session setup panel | One-tap engine / model / permissions / effort / account pills on every fresh session, gone after the first message | [AI engines](guides/engines.md) |
+| AI providers | Pick Claude Code or OpenAI Codex per session — per-provider models, permission vocabularies, effort scales, defaults, and in-app CLI login. Codex support is experimental | [AI providers](guides/providers.md) |
+| Session setup panel | One-tap provider / model / permissions / effort / account pills on every fresh session, gone after the first message | [AI providers](guides/providers.md) |
 | Streaming chat | Live-rendered markdown, collapsible tool and thinking blocks, syntax highlighting, per-block line-wrap toggle, clickable file references | [Sessions & tabs](guides/sessions.md) |
 | Per-turn summary bar | Context usage, token delta, files changed, tools used, duration, cost, and model after every turn | [Sessions & tabs](guides/sessions.md) |
 | Reconnect & resume | Claude keeps running when the tab disconnects; page refresh reattaches; resume any session in the CLI with `claude --resume` | [Sessions & tabs](guides/sessions.md) |
@@ -25,7 +25,7 @@ Everything pAInapple Code and the web client can do, in one place. Each area lin
 | Bang commands | `!git status` runs locally, shows as a tool block, and rides along as context for your next prompt | [Slash & bang commands](reference/commands.md) |
 | Draft autosave | In-progress messages persist per session across refreshes | [Writing prompts & commands](guides/input-and-commands.md) |
 | Uploads & annotation | Paste/drag images and files; draw markers, arrows, and text on screenshots before sending | [Images & annotation](guides/images-and-annotation.md) |
-| Permission modes | Plan / Ask / Don't Ask / Accept Edits / Auto / YOLO, per session — Codex sessions get sandbox tiers instead | [Permission modes & thinking](guides/permissions-and-thinking.md) |
+| Permission modes | Claude Code's own modes (Plan / Ask / Don't Ask / Accept Edits / Auto / YOLO) selectable per session, with its approval prompts rendered as in-chat cards — Codex sessions get Codex's sandbox tiers instead | [Permission modes & thinking](guides/permissions-and-thinking.md) |
 | Thinking & effort | Extended-thinking budgets and effort cycling, per session | [Permission modes & thinking](guides/permissions-and-thinking.md) |
 
 ## Tool widgets

{painapple_code-1.0.1 → painapple_code-1.0.2}/docs-site/getting-started/install-docker.md

@@ -153,7 +153,7 @@ They land in `/data/npm-global`, on the persistent volume, owned by the unprivil
 | `PAINAPPLE_AGENT_CLIS` | Override the set: space-separated `binary=npm-spec` pairs. Default `claude=@anthropic-ai/claude-code@2 codex=@openai/codex@latest`. Drop one to skip it, or pin an exact version. |
 | `PAINAPPLE_AGENT_CLI_PREFIX` | Install location. Default `/data/npm-global`. |
 
-A CLI already on `PATH` is left alone, checked per binary — so a baked-in `claude` doesn't suppress the `codex` install. A failed install is **not** fatal: the server still starts and serves the UI, terminal, git panel and history; only prompting that engine fails, with an explanation in the container log.
+A CLI already on `PATH` is left alone, checked per binary — so a baked-in `claude` doesn't suppress the `codex` install. A failed install is **not** fatal: the server still starts and serves the UI, terminal, git panel and history; only prompting that provider fails, with an explanation in the container log.
 
 !!! tip "Air-gapped hosts"
     Bake the CLIs into a derived image — the already-on-`PATH` check then leaves them alone:

{painapple_code-1.0.1 → painapple_code-1.0.2}/docs-site/getting-started/requirements.md

@@ -10,7 +10,7 @@ Running the server directly on a host (pip / pipx / source checkout):
 - **[Claude Code CLI](https://github.com/anthropics/claude-code)** installed and authenticated — either a Claude subscription (`claude login`) or an Anthropic API key
 - **Git** on `PATH` — the [auto-journal](../guides/shadow-git.md) records every turn as a commit in a shadow repository, and the Git panel shells out to it for diffs. Without git the server still runs, but it journals nothing and the Git panel stays empty; you'll get a warning in the log at startup.
 - **Network access between client and server** — any modern browser works as a client
-- *Optional:* the **[OpenAI Codex CLI](https://github.com/openai/codex)** if you want sessions on the Codex [engine](../guides/engines.md) — you can even log it in from inside the app. **Codex support is experimental** — newer and less exercised than the Claude path.
+- *Optional:* the **[OpenAI Codex CLI](https://github.com/openai/codex)** if you want sessions on the Codex [provider](../guides/providers.md) — you can even log it in from inside the app. **Codex support is experimental** — newer and less exercised than the Claude path.
 
 ### Server platforms
 
@@ -24,7 +24,7 @@ pAInapple Code runs natively on all three desktop platforms. No WSL required.
 
 #### Windows notes
 
-- **Install the Claude CLI with the native installer**, not npm: `irm https://claude.ai/install.ps1 | iex`. The Agent SDK that the default engine uses refuses to execute npm's `claude.cmd` shim (batch files are a command-injection vector — the same class as CVE-2024-27980), and will tell you so with a link to this fix. If you already logged in via the npm install, your credentials carry over.
+- **Install the Claude CLI with the native installer**, not npm: `irm https://claude.ai/install.ps1 | iex`. The Agent SDK that the default provider uses refuses to execute npm's `claude.cmd` shim (batch files are a command-injection vector — the same class as CVE-2024-27980), and will tell you so with a link to this fix. If you already logged in via the npm install, your credentials carry over.
 - **Get git from [Git for Windows](https://git-scm.com/download/win)**, which is what `winget install Git.Git` installs too. Besides `git.exe` it ships a `bash.exe`, and the optional `shadow-git` / `shadow-query` [helpers](../reference/optional-helpers.md) are shell scripts that run under it — the installer generates a small `.cmd` wrapper so you can still call them by name from PowerShell. (It deliberately does *not* use `C:\Windows\System32\bash.exe`; that one is the WSL launcher, which would look for your data inside the Linux filesystem.)
 - **The terminal tab runs PowerShell** through ConPTY. `pwsh` (PowerShell 7) is preferred when present, otherwise Windows PowerShell; override with `PAINAPPLE_CODE_SHELL`.
 - **`!bang` commands are PowerShell-flavored** on Windows, not `sh`.
@@ -44,7 +44,7 @@ The desktop browser is the primary target, but the UI is mobile-friendly and ins
 
 ## What it is, and what it isn't
 
-**It is** a thin wrapper around Claude Code — every prompt streams through the official **Agent SDK** (the classic `claude -p` line protocol is available as an alternate engine). Sessions you create here can be resumed in the regular CLI with `claude --resume <id>`.
+**It is** a thin wrapper around Claude Code — every prompt streams through the official **Agent SDK**. Sessions you create here can be resumed in the regular CLI with `claude --resume <id>`.
 
 **It is not** an AI agent of its own. It never modifies Claude's system prompt, tool policy, or behavior — no injected planning steps, no hidden instructions, no parallelized work. What it *does* add to a prompt is the context **you** attached: the output of `!bang` commands you ran, paths of files you uploaded, and snippets from the comments stash are prepended as plain text. The one other exception is the optional `shadow-git-helper` agent, which knows how to query the Shadow Git history.
 

{painapple_code-1.0.1 → painapple_code-1.0.2}/docs-site/getting-started/security.md

@@ -6,20 +6,22 @@
 
 ## Permissions
 
-The default engine drives Claude through the official **Agent SDK**, and the default permission mode is **Ask**: reads run freely, but every edit and command pauses the turn on an approve/deny card in the chat — with a preview of the edit or command — until you decide. That's the safe out-of-the-box posture. The more permissive modes are opt-in, per session, and they're also where the app is most fun — which is exactly why the isolation advice below matters.
+**pAInapple Code does not implement permissions. Claude Code does.** The default provider drives Claude through the official **Agent SDK**, and what the app contributes is a per-session way to pick one of [Claude Code's own permission modes](https://code.claude.com/docs/en/permission-modes#available-modes) and a place to answer the CLI's approval prompts. Your existing `settings.json` allow/deny rules apply exactly as they do in the terminal. Don't read the list below as a safety layer this project provides — read it as the mode you are handing to Claude Code.
 
-The permission modes on the default engine (configurable per session via the button next to the input):
+The default mode is **Ask**: reads run freely, but every edit and command pauses the turn on an approve/deny card in the chat — with a preview of the edit or command — until you decide. That's the safe out-of-the-box posture. The more permissive modes are opt-in, per session, and they're also where the app is most fun — which is exactly why the isolation advice below matters.
 
-| Mode | Behavior |
-|------|----------|
-| **Plan** | Read-only |
-| **Ask** *(default)* | Reads auto-allowed; every edit/command waits on an approval card |
-| **Don't Ask** | Auto-deny unless pre-approved by your allow rules |
-| **Accept Edits** | Auto-approve workspace edits plus in-scope file commands like `cp` or `mv`; ask for the rest |
-| **Auto** | Claude's AI classifier gates each tool call |
-| **YOLO** | `bypassPermissions` — full access |
+The modes available on the default provider (set per session via the button next to the input):
 
-Two caveats. First, the approval cards only protect you while you're the one clicking them — in **YOLO** and **Auto** nothing asks, and those are the modes that give Claude the most freedom. Second, the cards exist only on the Claude engine: Codex uses its own sandbox tiers instead. See the [permissions guide](../guides/permissions-and-thinking.md) for the full story, and the [Claude Code permission-modes docs](https://code.claude.com/docs/en/permission-modes#available-modes) for the underlying modes.
+| Mode | CLI mode | Behavior |
+|------|----------|----------|
+| **Plan** | `plan` | Read-only |
+| **Ask** *(default)* | `default` | Reads auto-allowed; every edit/command waits on an approval card |
+| **Don't Ask** | `dontAsk` | Auto-deny unless pre-approved by your allow rules |
+| **Accept Edits** | `acceptEdits` | Auto-approve workspace edits plus in-scope file commands like `cp` or `mv`; ask for the rest |
+| **Auto** | `auto` | Claude's AI classifier gates each tool call |
+| **YOLO** | `bypassPermissions` | Full access |
+
+Three caveats. First, the approval cards only protect you while you're the one clicking them — in **YOLO** and **Auto** nothing asks, and those are the modes that give Claude the most freedom. Second, the cards exist only on the Claude provider: Codex enforces its own sandbox tiers instead. Third — and this is the point of this whole section — the boundary that actually holds is the one *below* the agent: the OS user, the container, the VM. A permission mode is the agent cooperating, not a sandbox. See the [permissions guide](../guides/permissions-and-thinking.md) for the full story.
 
 ## Terminal
 

{painapple_code-1.0.1 → painapple_code-1.0.2}/docs-site/guides/customization.md

@@ -35,14 +35,14 @@ Your overrides are pushed to the server, so they follow you across browsers and
 
 Configures the radial FAB menu (see below): FAB visibility (Always / Mobile / Disabled), behavior options (context-aware action swapping, tooltips, press-drag-release selection, haptic feedback on mobile), which action sits in each slot, and preset switching.
 
-### Engines
+### Providers
 
-Everything about the [AI engines](engines.md) — Claude and Codex — lives here:
+Everything about the [AI providers](providers.md) — Claude and Codex — lives here:
 
-- **Engines list** — enable/disable each engine and pick the default for new sessions (**Make default**).
-- **One sub-tab per enabled engine** — CLI path and detected version, login status with an in-app **Log in** flow, the engine's model catalog (per-model show/hide; Claude's is fully editable), its **New Session Defaults** (model, effort, account), and its auto-journal summarizer model.
+- **Providers list** — enable/disable each provider and pick the default for new sessions (**Make default**).
+- **One sub-tab per enabled provider** — CLI path and detected version, login status with an in-app **Log in** flow, the provider's model catalog (per-model show/hide; Claude's is fully editable), its **New Session Defaults** (model, effort, account), and its auto-journal summarizer model.
 
-Full walkthrough: [AI engines → Settings → Engines](engines.md#settings-engines).
+Full walkthrough: [AI providers → Settings → Providers](providers.md#settings-providers).
 
 ### System
 
@@ -81,7 +81,7 @@ Handy for pinning one terminal or file preview across a set of related sessions.
 
 Some customization is stored server-side, so it follows you to any browser or device that logs into the same server; the rest is per-browser `localStorage`.
 
-**Server-side:** shortcut overrides, quick-action presets, everything on the Engines tab — which engines are enabled, which one is the default for new sessions, each engine's CLI path override, its per-model show/hide list, its editable model catalog (Claude only), its new-session defaults (model, effort, account) and its auto-journal summarizer model — per-project config (extra dirs, Shadow Git, commit sections), global Shadow Git defaults, global extra dirs, and [tab state](sessions.md). **Per-browser:** appearance settings (density, font scale, opacity, tool-block modes), input toggles, and the FAB position/slots.
+**Server-side:** shortcut overrides, quick-action presets, everything on the Providers tab — which providers are enabled, which one is the default for new sessions, each provider's CLI path override, its per-model show/hide list, its editable model catalog (Claude only), its new-session defaults (model, effort, account) and its auto-journal summarizer model — per-project config (extra dirs, Shadow Git, commit sections), global Shadow Git defaults, global extra dirs, and [tab state](sessions.md). **Per-browser:** appearance settings (density, font scale, opacity, tool-block modes), input toggles, and the FAB position/slots.
 
 ## Related
 

{painapple_code-1.0.1 → painapple_code-1.0.2}/docs-site/guides/ipad-and-mobile.md

@@ -8,7 +8,8 @@ Log into the web client from the device's browser first, then install:
 
 - **iOS / iPadOS** — in Safari, tap the share button and choose **Add to Home Screen**.
 - **Android** — Chrome offers **Install app** from the ⋮ menu (or an install banner).
-- **Desktop** — Chrome and Edge show an install icon in the address bar.
+- **macOS** — in Safari 17+, choose **File → Add to Dock**; Chrome and Edge show an install icon in the address bar.
+- **Windows / Linux** — Chrome and Edge show an install icon in the address bar (or **⋮ → Install**).
 
 Why bother, instead of a browser tab:
 
@@ -22,7 +23,7 @@ Why bother, instead of a browser tab:
 Your phone or tablet needs a route to the server — `localhost` won't cut it:
 
 - **Bind beyond loopback** — start the server with `--host 0.0.0.0` (or a LAN IP). Binding a non-loopback host auto-enables TLS with a self-signed certificate; the browser shows a one-time certificate warning you accept on first visit.
-- **Or put a reverse proxy in front** — Caddy/nginx/Tailscale with a real certificate gives you a clean HTTPS origin, which PWAs and service workers prefer.
+- **Or put a reverse proxy in front** — Caddy/nginx with a real certificate gives you a clean HTTPS origin, which PWAs and service workers prefer.
 
 Either way, read [Read this first (security)](../getting-started/security.md) before exposing the server to anything wider than your desk, and [First run & login](../getting-started/first-run.md) for the password flow.
 

painapple_code-1.0.2/docs-site/guides/permissions-and-thinking.md

@@ -0,0 +1,76 @@
+# Permission modes & thinking
+
+Two controls next to the message input decide how much rope Claude gets: the **permission mode** button (what it may do without asking) and the **effort** gauge (how hard it thinks). Both are per-session with a global default.
+
+## Permission modes
+
+**These are Claude Code's own permission modes — pAInapple Code has no permission system of its own.** Picking a mode sets the CLI's `--permission-mode` for that session; Claude Code decides what to allow, deny or ask about, using the same allow/deny rules from your `settings.json` that the terminal CLI uses. Nothing here is a second layer of enforcement on top, and nothing here can make the agent safer than the mode you chose. The authoritative description of what each mode does is the [Claude Code permission-modes documentation](https://code.claude.com/docs/en/permission-modes#available-modes); the table below is a summary of it.
+
+What pAInapple Code adds is the interface: a per-session switcher instead of a startup flag, approval prompts rendered as cards in the chat, and a colored input border so you always know which session is armed and which is read-only. The list of modes comes from the [provider](providers.md) the session runs on — the Claude provider offers these six, and the Codex provider offers Codex's own sandbox tiers instead.
+
+| Mode | CLI mode | What Claude Code does |
+|------|----------|-----------------------|
+| **Plan** | `plan` | Read-only — explore and design, no writes |
+| **Ask** *(default)* | `default` | Reads auto-allowed; every edit and command waits for your approval |
+| **Don't Ask** | `dontAsk` | Auto-deny anything your Claude Code allow rules don't already cover |
+| **Accept Edits** | `acceptEdits` | Auto-approve edits in the workspace (plus in-scope file commands like `mkdir`/`mv`/`cp`); ask for the rest |
+| **Auto** | `auto` | An AI classifier reviews each tool call — reads and in-project edits sail through, riskier operations get blocked |
+| **YOLO** | `bypassPermissions` | Skip all permission checks |
+
+They're listed roughly from most restrictive to most permissive — roughly, because **Don't Ask** sits above **Ask** while actually granting *less* (it auto-denies rather than asking you).
+
+### Interactive permission cards
+
+A card is Claude Code's own approval prompt, drawn in the chat instead of the terminal. On the default SDK provider, when the agent asks, the SDK blocks the turn and hands the request to the app; the card is how you answer it. The elapsed timer freezes, background tabs get a badge plus a click-to-go toast so you notice the wait from another session, and you can deny with an optional note back to Claude, or approve.
+
+The **"always allow"** options on a card are the CLI's own "don't ask again" suggestions — allow this exact command in this project, allow a directory, or switch mode. Pick one and *Claude Code* persists the rule (into your project's `.claude/settings.local.json`, say), in the same file the terminal CLI reads. Rules you already wrote there apply here unchanged, and rules you accept here apply the next time you run `claude` in that project.
+
+The default mode is **Ask** — reads run freely, but every edit and command waits for your approval on a card. Prefer **Accept Edits** to wave edits through and only get carded for commands, **YOLO** or **Auto** to let Claude just work, or **Don't Ask** to auto-deny anything your allow rules don't already cover. **Plan** stays read-only.
+
+!!! note "Other providers"
+    Sessions can also run on OpenAI Codex — see [AI providers](providers.md) for picking one per session (or pinning a server-wide default with `--default-provider`). The same pass-through applies: Codex doesn't use these modes at all, so the button maps to the Codex CLI's own **sandbox tiers** (Read-only / Workspace write / Full access), enforced by Codex.
+
+!!! note "Auto mode is a research preview"
+    Auto is the CLI's `--permission-mode auto`, where a classifier model on Claude Code's side gates each call. It needs a recent CLI and model (Sonnet 4.6+/Opus 4.6+ on the Anthropic API; Team/Enterprise plans need an org owner to enable it). Also, headless auto sessions abort after 3 consecutive classifier blocks (or 20 total) — if Claude keeps getting blocked, the turn ends rather than looping.
+
+!!! warning "Read the security notes before going YOLO"
+    YOLO means Claude can run any command as the server user. That is the intended way to use this app — inside an isolated container or VM. See [Read this first](../getting-started/security.md).
+
+### Per-session, with a default
+
+The one thing the app really does own here is *when* you get to choose. The CLI takes its mode at startup; here it's a per-session setting, saved with the session and restored when you reopen it. On the default SDK provider a mode switch applies **immediately, even mid-turn** — the running provider changes gear in place, so you can flip to Accept Edits while approval cards are stacking up and the rest of the turn follows the new mode (the system log confirms "applied to the running provider"). Whenever the live switch isn't possible, it takes effect on your next message instead, when the server respawns the idle provider process with the new mode. The **Set as default** button in the popup makes the current mode the global default for new sessions (also editable in Settings).
+
+### Plan mode and plan approval
+
+In **Plan** mode Claude explores read-only and ends with a plan. The plan renders as an interactive approval card — approve it and the session drops out of plan mode to execute; reject it and you stay planning. Tabs show a *Plan ready for review* badge while a plan waits. You can also enter plan mode for a single message by typing `/plan ` in the input — see [input modes](input-and-commands.md#input-modes).
+
+Related: when Claude asks a clarifying question mid-turn (AskUserQuestion), pAInapple Code by default stops it so you can answer — see [When Claude asks you a question](sessions.md#when-claude-asks-you-a-question).
+
+## Effort levels
+
+The circular gauge button next to the input controls Claude's effort — how many thinking tokens it spends — on a five-step scale: **low**, **medium**, **high** (the default), **xhigh**, **max**. The conic fill of the gauge shows the level at a glance (a fifth per step, glowing at max). It maps to the CLI's `--effort` flag. The scale is per-[provider](providers.md): Codex sessions render Codex's own reasoning levels (up to `ultra` on recent models), narrowed to what the selected model supports.
+
+- **Click the gauge** (or ++cmd+apostrophe++ / ++ctrl+apostrophe++) to open the level picker. Like permission modes, effort is per-session, with **Set as default** to change the global fallback.
+- **One-shot override:** ++cmd+shift+apostrophe++ / ++ctrl+shift+apostrophe++ arms a temporary level for the *next message only* — first press bumps one level above your persistent setting, further presses cycle through the rest (including below it), and landing back on the persistent level disarms. A badge on the gauge shows the armed level; it clears itself after one send. Perfect for "give this one question the max treatment" without re-configuring.
+
+Changing effort applies on your next message by respawning the idle process (unlike permission mode there's no live-apply here — the provider has no mid-session effort control).
+
+## Token profiles
+
+If you have more than one Claude account (say, a personal Max plan and a work team seat), drop each OAuth token in a plain-text file under `~/.config/painapple-code/tokens/` — the filename becomes the profile name:
+
+```
+~/.config/painapple-code/tokens/
+├── max      # contents: the OAuth token string
+└── work
+```
+
+A profile chip then appears in the status bar next to the model name (it's hidden when the directory is empty). Click it to pick which account the *current session* bills to; the server sets `CLAUDE_CODE_OAUTH_TOKEN` accordingly when it spawns Claude. Each session remembers its profile, and a global default is available.
+
+The killer feature: when a turn ends **rate-limited**, the turn summary bar replaces its context bar with a *Switch token:* strip — one tap on another profile and you keep working on the other account's quota.
+
+## Choosing a model
+
+The model name in the status bar is a selector — click it to switch the session's model. The catalog is the session [provider's](providers.md) own: for Claude it comes from the server's `models.yaml` (editable in **Settings → Providers** or by hand), including `[1m]` variants that run the same model with a 1M-token context window; for Codex it mirrors the Codex CLI's model list. A model switch applies from your next message onward, in the same conversation — on the default SDK provider the warm process changes model in place, so there's no respawn pause on your first message with the new model.
+
+Optionally, a server-wide `fallback_model` key in `~/.painapple-code/config.json` names a model to fall back to automatically when the primary is overloaded or unavailable (the CLI's `--fallback-model`) — the turn completes on the fallback instead of dying with an overload error.

painapple_code-1.0.2/docs-site/guides/providers.md

@@ -0,0 +1,58 @@
+# AI providers (Claude & Codex)
+
+Every session runs on an **provider** — the AI CLI pAInapple Code drives under the hood. The default is Claude Code via the official Agent SDK, but pAInapple Code can also drive the **OpenAI Codex CLI**, and you pick per session: a Claude tab and a Codex tab can sit side by side in the same strip, each with its own models, permission vocabulary, and effort scale.
+
+!!! warning "The Codex path is experimental"
+    Codex support is **newer and has had less testing** than the Claude path — it works, but expect rougher edges. Claude Code via the Agent SDK is the default and the well-trodden route.
+
+## The providers
+
+| Provider | What it is |
+|--------|-----------|
+| **Claude Code** | Claude Code via the Agent SDK — interactive permission cards, live mode/model switching mid-turn. The default. |
+| **Codex** | OpenAI Codex over its persistent app-server protocol — native forking, server-reported context window, graceful interrupt. |
+
+Earlier releases also shipped two "plain CLI" fallback drivers (line-protocol `claude -p`, and Codex `exec` mode — one process per turn). Both were removed: the SDK and app-server drivers supersede them on every axis, and the Codex `exec` mode had a real downside — it could only take the prompt as a command-line argument, which made prompts readable in the process list by other accounts on the same machine. Sessions created on the old drivers keep working; they resume on the matching current provider automatically. Enable or hide providers in **Settings → Providers**.
+
+!!! note "What Codex needs"
+    The Codex provider requires the [Codex CLI](https://github.com/openai/codex) (`@openai/codex`) installed on the *server* and logged in. A provider whose CLI is missing shows up greyed-out with a hint; a CLI that isn't logged in gets a **Log in** button right in Settings (see [below](#logging-in)). The Docker image doesn't bundle Codex, but it doesn't need to: the entrypoint installs it on first start alongside the Claude CLI, onto the `/data` volume. Override the set with `PAINAPPLE_AGENT_CLIS`, or skip it entirely with `PAINAPPLE_SKIP_AGENT_CLI=1`. See [container mode](../getting-started/install-docker.md).
+
+## Picking a provider per session
+
+Provider choice happens **in chat**, while a session is still fresh:
+
+- **Session setup panel** — every new session (project picked, nothing sent yet) shows a card of one-tap pill rows directly above the input: **provider, model, permissions, effort, account**. Tap through your setup and start typing; the panel disappears with your first message.
+- **Status-bar provider chip** — the provider name in the status bar opens the same picker at any time before the first message.
+
+A session **locks to its provider with the first message** — the conversation history lives with that CLI. Picking a different provider on a locked session doesn't fail, though: it opens a **clone tab** in the same working directory running the provider you picked. **Clone** (++cmd+n++) also inherits the source session's provider.
+
+The **default provider** for new sessions is set with the **Make default** button in Settings → Providers (or the `--default-provider` flag / `default_provider` config key — the flag pins the choice and hides the button).
+
+## What changes with the provider
+
+Each provider self-describes its capabilities, and the UI follows:
+
+- **Models** — the model picker shows the *active provider's* catalog. Claude's comes from the server's editable `models.yaml`; Codex's mirrors the Codex CLI's own model list (so it updates when Codex does). Per-provider default models are configured in Settings → Providers.
+- **Permission modes** — the Claude provider speaks Claude's modes (Plan / Ask / Don't Ask / Accept Edits / Auto / YOLO — see [Permission modes](permissions-and-thinking.md)); the Codex provider maps to Codex **sandbox tiers**: Read-only, Workspace write, and Full access.
+- **Effort** — the effort gauge renders each provider's own scale. Claude has five levels (low → max); Codex levels come from its model catalog and can reach `xhigh` / `ultra` on recent models, with the picker narrowing to what the selected model supports.
+- **Cost** — Codex reports tokens only, no dollar figure, so the `$` cost readouts hide on Codex sessions and the turn bar shows token counts.
+- **Continue in the CLI** — the **Continue in CLI** quick action is provider-aware: a Claude session gives you `claude -r <id>`, a Codex session `codex exec resume <id>`.
+- **Auto-journal** — the [Shadow Git journal](shadow-git.md) fork always runs on the session's own provider (only the owner of a conversation can fork it), and each provider has its own journal-summarizer model setting.
+
+## Settings → Providers
+
+**Settings → Providers** (++ctrl+comma++) is the control room:
+
+- **Providers list** — a toggle per provider (the default provider is forced on), and a **Make default** button on every other available provider. Disabling a provider hides it from pickers; sessions already bound to it keep working.
+- **One sub-tab per enabled provider**, all with the same layout:
+    - **CLI status** — the resolved binary path and live `--version`, plus a path-override field per provider CLI.
+    - <a id="logging-in"></a>**Login status** — whether the CLI is authenticated ("Logged in — email · plan" for Claude, exit status for Codex). When it isn't, a **Log in** button opens a terminal tab running the provider's login flow; the row polls and flips green when you finish. Codex uses device-code auth (`codex login --device-auth`) so the flow works even when the server is remote.
+    - **Model catalog** — every model with a show/hide toggle (hidden models disappear from all pickers). Claude's catalog is fully editable (add/edit/delete, restore defaults); Codex's is read-only because the Codex CLI owns it.
+    - **New Session Defaults** — that provider's default model, default effort (its own vocabulary), and default account/token profile where applicable.
+    - **Auto-journal model** — which model writes the [Shadow Git](shadow-git.md) summaries for sessions on this provider.
+
+## Related
+
+- [Permission modes & thinking](permissions-and-thinking.md) — what the modes and effort levels mean.
+- [Sessions & tabs](sessions.md) — cloning, forking, and continuing sessions in the CLI.
+- [Server CLI](../reference/server-cli.md) — `--default-provider` and config keys.

{painapple_code-1.0.1 → painapple_code-1.0.2}/docs-site/guides/sessions.md

@@ -4,7 +4,7 @@ Each tab in pAInapple Code is its own Claude Code session — its own conversati
 
 ## The tab strip
 
-Press ++cmd+t++ / ++ctrl+t++ (or the **+** button) to open a new tab. It lands on the [welcome screen](welcome-screen.md), where you pick a project and type your first prompt. While a session is still empty, a **setup panel** above the input offers one-tap rows for the [AI engine](engines.md), model, permission mode, effort, and account — tune the session, then just start typing. There is no limit on how many sessions you can have open at once — once the tab strip runs out of room it collapses the overflow into a **+N** chip.
+Press ++cmd+t++ / ++ctrl+t++ (or the **+** button) to open a new tab. It lands on the [welcome screen](welcome-screen.md), where you pick a project and type your first prompt. While a session is still empty, a **setup panel** above the input offers one-tap rows for the [AI provider](providers.md), model, permission mode, effort, and account — tune the session, then just start typing. There is no limit on how many sessions you can have open at once — once the tab strip runs out of room it collapses the overflow into a **+N** chip.
 
 Session tabs share one strip with *widget tabs* — terminals, file previews, and scratch editors opened as tabs interleave freely with sessions, so a terminal can sit right between two conversations. Each session tab shows a status dot (lit while Claude or the auto-journal is working), an unread dot for background activity, and a **?** badge when Claude is waiting for [an answer from you](#when-claude-asks-you-a-question).
 
@@ -103,4 +103,4 @@ Every session here is a real CLI session. Grab the ID from the tab context menu
 claude --resume <session-id>
 ```
 
-Easier still, the **Continue in CLI** quick action copies the exact resume command for the session's [engine](engines.md) — `claude -r <id>` for a Claude session, `codex exec resume <id>` for a Codex one.
+Easier still, the **Continue in CLI** quick action copies the exact resume command for the session's [provider](providers.md) — `claude -r <id>` for a Claude session, `codex exec resume <id>` for a Codex one.

{painapple_code-1.0.1 → painapple_code-1.0.2}/docs-site/guides/shadow-git.md

@@ -16,7 +16,7 @@ A few properties worth internalizing:
 
 ## Rich commits: the Haiku auto-journal
 
-On top of the raw commits sits the second layer: **rich commits**. After each turn, the server forks a background summarizer (Haiku by default; the model is configurable per [engine](engines.md) in **Settings → Engines** — the fork runs on the session's own engine, so Codex sessions self-summarize with a Codex model) that reads the **whole turn, not just the diff** — with the running "journey" context of previous turn summaries — and writes a structured commit message: a one-line summary, tags, plus sections like *work done*, *investigation*, *findings*, *decisions*, *problems solved*, *verification*, and *learnings*. You can customize which sections are generated per project.
+On top of the raw commits sits the second layer: **rich commits**. After each turn, the server forks a background summarizer (Haiku by default; the model is configurable per [provider](providers.md) in **Settings → Providers** — the fork runs on the session's own provider, so Codex sessions self-summarize with a Codex model) that reads the **whole turn, not just the diff** — with the running "journey" context of previous turn summaries — and writes a structured commit message: a one-line summary, tags, plus sections like *work done*, *investigation*, *findings*, *decisions*, *problems solved*, *verification*, and *learnings*. You can customize which sections are generated per project.
 
 Everything is parsed and stored in a local DuckDB alongside the git data, so it's queryable: every turn's prompt, cost, tokens, duration, model, files touched, tools used, tags, and all the generated sections.