@ponythewhite/base-context 1.0.0 → 1.0.1

package/docs/fork-philosophy.md

@@ -28,6 +28,8 @@ Base Context retains that core approach, along with agent messaging, goals, sche
 
 `await rlm(...)` returns an admission handle. Children deliver results through messages or files. This distinction matters: a parent should continue independent work and read results when they arrive, not assume the spawn call contains the answer.
 
+For 1.0.1, we reviewed the 113 commits in Prime Agent 0.9.5 and selected small runtime, provider and packaging fixes rather than merging the release. The [complete selection and exclusions](upstream-0.9.5.md) explain how that choice preserves the fork's architecture.
+
 ## What Base Context changes
 
 | Area | Base Context approach | Important limit |
@@ -62,14 +64,8 @@ Read the [report](../../../benchmarks/python-realworld-30/REPORT.md), [complete
 - **Keep comparisons honest.** Separate design goals from measured outcomes and benchmark revisions from release versions.
 - **Stay open.** Retain MIT licensing and upstream notices. Source and documentation should make the implementation understandable without a hosted service.
 
-## Lineage and acknowledgements
+## Project and license
 
 Base Context is developed by [Synerise](https://synerise.com) and distributed through [BaseModelAI/base-context](https://github.com/BaseModelAI/base-context).
 
-We thank **[Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent)** and **[Prime Intellect](https://www.primeintellect.ai/)** for the agent foundation, the [RLM programming model](https://www.primeintellect.ai/blog/rlm), and the work that made this fork possible.
-
-We thank **Mario Zechner** for **[Pi / pi-mono](https://github.com/badlogic/pi-mono)**, whose agent and terminal UI work is part of that lineage.
-
-We also acknowledge **[PrimeRL](https://github.com/PrimeIntellect-ai/prime-rl)**, Prime Intellect's separate open reinforcement-learning project. It is not a direct dependency of the Base Context CLI. This credit does not imply that Prime Intellect or the upstream authors endorse this fork or its benchmark conclusions.
-
-Base Context remains [MIT licensed](../../../LICENSE). The repository README retains the upstream research citation.
+Base Context is [MIT licensed](../../../LICENSE). Required copyright notices are in [NOTICE](../../../NOTICE).

package/docs/installation.md

@@ -1,111 +1,132 @@
 # Installation, updates, and rollback
 
-The application package is **`@ponythewhite/base-context`**. The executable is **`base-context`**. The repository is [BaseModelAI/base-context](https://github.com/BaseModelAI/base-context). Prime Agent's installers and packages install a different product.
+Install **Synerise base-context** with the installer below. The application package is `@ponythewhite/base-context`; the command is `base-context`.
 
-## Requirements
+## Recommended: the installer
 
-- Node.js `^22.12.0 || >=23.3.0`: Node 22.12 or newer on the 22.x line, or Node 23.3 or newer. Node 22.8–22.11 and 23.0–23.2 are not supported.
-- npm compatible with that Node version.
-- [uv](https://docs.astral.sh/uv/getting-started/installation/) for the managed Python workspace. The default bootstrap installs Python 3.11, the bundled `base-context-runtime`, and its default Python packages.
-- A configured, authorized model provider. Provider inference and first-time dependency setup need network access unless you supply local alternatives.
+On **macOS or Linux**, run this in a terminal:
 
-The Node floor comes from the native SQLite session catalog. It does not change the journal format. Normal session owners rebuild older derived indexes; read-only catalog discovery does not migrate them.
+```bash
+curl -fsSL https://github.com/BaseModelAI/base-context/releases/latest/download/install.sh | bash
+```
+
+**You do not install Node.js, npm, Python, or `uv` first.** The installer:
+
+1. Checks Node.js/npm and asks to install a supported version when needed. Some system package-manager methods need administrator approval.
+2. Installs `uv` if it is missing, downloads managed Python 3.13, and prepares the bundled runtime and Python packages.
+3. Activates the CLI only after that preparation succeeds.
+4. Offers to add the launcher and any standalone Node.js installation to your shell profile. It preserves existing settings.
+5. Prints one exact `export PATH=... && base-context` command. Run it to activate and launch in your **current terminal**. A child installer cannot change its parent shell's PATH. If you accept the profile update, future shells get the PATH automatically.
+
+Use this route **instead of** the npm alternative. No Python virtual-environment activation is needed. Initial setup needs network access and ordinary shell download/archive tools. Missing Node/npm setup needs terminal approval; rerun in a terminal rather than preinstalling everything manually.
 
-## npm installation
+To start work later:
 
 ```bash
-npm install -g @ponythewhite/base-context
-base-context --version
-cd /path/to/project
+cd /path/to/your/project
 base-context
 ```
 
-Make sure your npm global binary directory is on `PATH`. Use a user-owned Node installation rather than adding elevated permissions just for this agent.
+Select a supported provider with `/login`, authenticate with that provider, then select a model with `/model`. You must choose the provider and model. Use that provider's account and authentication. See [provider setup](providers.md).
 
-In the UI, use `/login` and then `/model`. See [provider configuration](providers.md). The fork does not inherit permission to use upstream OAuth clients or subscriptions.
+### Updates and rollback
 
-Update an npm-managed installation with:
+The installer manages a versioned CLI/Python pair beneath `${XDG_DATA_HOME:-$HOME/.local/share}/base-context`. `BASE_CONTEXT_INSTALL_ROOT` selects another root. The stable launcher is `<owned-root>/bin/base-context`. Existing global package-manager installations remain separate and are not overwritten.
 
 ```bash
-npm install -g @ponythewhite/base-context@latest
+base-context update --self
+base-context-install rollback
 ```
 
-The CLI also provides `base-context update`. npm/pnpm/yarn/bun global installations remain externally owned. They do not gain the owned installer's paired CLI/Python rollback.
+Rollback selects the retained previous CLI/Python pair for future launches. It does not stop running processes, revert session data or Node.js, or undo changes made by Python skills. Old and failed version directories are retained.
 
-## Source installation
+To install a specific release, download that release's installer and pass its version:
 
 ```bash
-git clone https://github.com/BaseModelAI/base-context.git
-cd base-context
-npm ci
-npm run build:source
-node packages/coding-agent/dist/bundle/cli.js
+VERSION=1.0.1
+curl -fsSL "https://github.com/BaseModelAI/base-context/releases/download/v${VERSION}/install.sh" -o install-base-context.sh
+sh install-base-context.sh "$VERSION"
 ```
 
-Do not substitute the upstream repository or an old fork-development branch. The source-built CLI starts in the current working directory. To use it in another project:
+The shell resolves the stable npm tag by default; `beta` selects the npm `beta` tag. A positional version or `BASE_CONTEXT_VERSION` bypasses channel discovery. Matching GitHub release assets must exist. `BASE_CONTEXT_DOWNLOAD_BASE_URL` is an installer repository-base override, not the running application's update-manifest setting; leave it unset for normal use.
+
+## npm alternative
+
+Use this only if you already manage Node.js and npm, or if you use Windows. Install supported **Node.js and npm before this route**: Node.js `^22.12.0 || >=23.3.0` (22.12+ on the 22.x line, or 23.3+).
+
+Bash/Zsh:
 
 ```bash
+npm install -g @ponythewhite/base-context
 cd /path/to/project
-node /absolute/path/to/base-context/packages/coding-agent/dist/bundle/cli.js
+BASE_CONTEXT_INSTALL_UV=1 base-context
 ```
 
-Replace `base-context` in other examples with that Node invocation when using a source build. Keep source updates under git and rebuild with `npm ci` and `npm run build:source`; a global npm update does not update your checkout.
+PowerShell:
+
+```powershell
+npm install -g @ponythewhite/base-context
+Set-Location C:\path\to\project
+$env:BASE_CONTEXT_INSTALL_UV = "1"
+base-context
+```
 
-## Python setup
+Make sure the npm global binary directory is on PATH. Use a user-owned Node installation rather than adding administrator permissions just for this agent.
 
-For npm and source installations, the default kernel environment is `~/.base-context/runtime`. It is prepared lazily when the agent first uses Python. Install `uv` first, or explicitly allow bootstrap to install it with `BASE_CONTEXT_INSTALL_UV=1`. Initial preparation can download Python and dependencies.
+**What happens when:** normal `npm install` installs the CLI but skips Python setup. Starting a normal CLI session begins preparing Python in the background when the Python tool is enabled. `BASE_CONTEXT_INSTALL_UV=1` lets this setup install missing `uv`; it then downloads Python and installs the bundled runtime. You do not install Python manually. Later sessions reuse the environment. `base-context --version` does not start Python.
 
-For a manual environment:
+Without that flag, missing `uv` can make the Python tool fail; normal session startup does not offer an installation prompt. The installer route avoids this separate step by finishing Python setup before activation. Advanced npm postinstall bootstrap flags are optional, not required for this route.
 
-- `BASE_CONTEXT_KERNEL_PYTHON` selects an absolute Python executable with a current **`base-context-runtime`** already installed.
-- `BASE_CONTEXT_KERNEL_VENV` selects an absolute manual environment directory.
-- The Python import remains `rlm`; an environment containing only `prime-agent-runtime` is not a substitute.
+Update an npm-managed installation with:
 
-The owned installer below prepares its own release-local default environment before activation. Python skills can later change that environment; it is not immutable. See [Python-backed skills](skills.md#python-backed-skills).
+```bash
+npm install -g @ponythewhite/base-context@latest
+```
 
-## Owned installer and rollback
+`base-context update` also supports package-manager updates. npm/pnpm/yarn/bun installations remain externally owned and do not gain the installer's paired CLI/Python rollback.
 
-Use the versioned, rendered installer from the GitHub release:
+## Source installation
 
 ```bash
-curl -fL https://github.com/BaseModelAI/base-context/releases/download/v1.0.0/install.sh -o install-base-context.sh
-sh install-base-context.sh 1.0.0
+git clone https://github.com/BaseModelAI/base-context.git
+cd base-context
+npm ci
+npm run build:source
+BASE_CONTEXT_INSTALL_UV=1 node packages/coding-agent/dist/bundle/cli.js
 ```
 
-The separate POSIX installer manages versioned CLI/Python pairs. It defaults to `${XDG_DATA_HOME:-$HOME/.local/share}/base-context`; `BASE_CONTEXT_INSTALL_ROOT` chooses another root. Use the installer and assets from a matching Base Context release, not an upstream installer.
-
-The release layout uses the repository base `https://github.com/BaseModelAI/base-context`, with versioned assets under `/releases/download/v<V>/`. Assets include `base-context-<V>.tgz`, the three core tarballs, and `SHA256SUMS`. The shell installer resolves `@ponythewhite/base-context@latest`; its `beta` channel resolves the npm `beta` tag. A positional version such as `sh install.sh v1.0.0`, or `BASE_CONTEXT_VERSION`, bypasses channel discovery. The matching release assets must already exist.
+The source-built CLI starts in the current working directory. To work in another project, change to that directory and run `node /absolute/path/to/base-context/packages/coding-agent/dist/bundle/cli.js`. Keep source updates under git, then rerun `npm ci` and `npm run build:source`. A global npm update does not update your checkout.
 
-When invoking a local copy of the shell installer, set `BASE_CONTEXT_DOWNLOAD_BASE_URL` for that invocation to the repository base. This installer setting is **not** the running application's custom update-manifest setting. Leave it unset for normal application launches to use owned npm updates.
+## Custom Python environments
 
-Preparation must finish before the new CLI/Python pair becomes selected. Follow the installer's PATH instructions, including the separate `base-context-node` directory if it installs standalone Node. The stable launcher is `<owned-root>/bin/base-context`.
+Ordinary installer users can skip this section. npm and source installations normally use `~/.base-context/runtime`; the installer uses a release-local environment. SDK sessions and RLM children normally prepare Python lazily, unlike the normal CLI root session's background prewarm.
 
-After an owned installation:
+For an explicitly managed environment:
 
-```bash
-base-context update --self
-base-context-install rollback
-```
+- `BASE_CONTEXT_KERNEL_PYTHON` selects an absolute Python executable with the current bundled **`base-context-runtime`** installed.
+- `BASE_CONTEXT_KERNEL_VENV` selects an absolute environment directory.
+- The package exposes the Python import `rlm`. This is not a command users need to run to install the CLI.
 
-Rollback selects the retained previous CLI/Python pair for future launches. It does not stop running owners, roll back session data or Node, or undo changes made by running processes. Old and failed version directories are retained; there is no automatic cleanup. The owned installer does not convert or overwrite existing global package-manager installations.
+Saved Python namespaces are not portable across minor versions; native startup rejects an incompatible snapshot. Start a new session when selecting a different Python minor version. Python skills can install additional packages. See [Python-backed skills](skills.md#python-backed-skills).
 
-### Local release packages
+## Local release packages
 
-For unpublished local packages, use the dedicated installer from the matching, freshly built and extracted main package. Supply the three other first-party tarballs explicitly:
+For unpublished packages, use the dedicated installer from the matching, freshly built and extracted main package. Supply all three other first-party archives explicitly:
 
 ```bash
+VERSION=1.0.1
 PACKS=/absolute/path/to/pack
 node /absolute/path/to/extracted-main/package/dist/installer.mjs install \
   /absolute/path/to/new-install-root null \
-  "$PACKS/ponythewhite-base-context-1.0.0.tgz" 1.0.0 \
-  --local-dependency "$PACKS/ponythewhite-base-context-ai-1.0.0.tgz" \
-  --local-dependency "$PACKS/ponythewhite-base-context-tui-1.0.0.tgz" \
-  --local-dependency "$PACKS/ponythewhite-base-context-agent-1.0.0.tgz"
+  "$PACKS/ponythewhite-base-context-${VERSION}.tgz" "$VERSION" \
+  --local-dependency "$PACKS/ponythewhite-base-context-ai-${VERSION}.tgz" \
+  --local-dependency "$PACKS/ponythewhite-base-context-tui-${VERSION}.tgz" \
+  --local-dependency "$PACKS/ponythewhite-base-context-agent-${VERSION}.tgz"
 ```
 
-Substitute the matching release version and actual tarball names. Use `null` only for a new, unselected owned root. Each `--local-dependency` names a local archive containing `package/package.json`. Relative paths use the invocation's original working directory. `tar` must be available. The installer reads package names and configures candidate-local dependencies; it does not scan adjacent files or modify archive contents.
+Use the actual archive names and a matching version. `null` means a new, unselected owned root. Relative paths use the invocation's original working directory. `tar` must be available. The installer reads package names and sets candidate-local dependencies; it does not scan adjacent files or alter archives.
 
-The dedicated entry skips agent/model/auth startup, but npm scripts and Python bootstrap can still download dependencies. This is not an offline install. Extraction alone does not install or activate the package. Old package sets do not acquire this installer option.
+This entry skips agent/model/auth startup, but npm and Python setup can download dependencies. Extraction alone does not install or activate the package.
 
 ## State and configuration
 
@@ -117,17 +138,17 @@ The dedicated entry skips agent/model/auth startup, but npm scripts and Python b
 | `BASE_CONTEXT_SESSION_DIR` | Absolute independent session-storage override |
 | `--session-dir` | Session-directory override with higher precedence |
 
-Do not point writable Base Context state at `.prime`, `.pi`, or `.prime-context`. Do not copy upstream credential files. Use the explicit [offline history import](sessions.md#importing-an-offline-prime-root) if needed.
+Keep writable Base Context state separate from other applications. Use [offline history import](sessions.md#importing-an-offline-prime-root) when needed.
 
 `--offline` or `BASE_CONTEXT_OFFLINE=1` disables startup network operations, including update and package checks. It is not a network sandbox and does not make a remote model available offline.
 
 ## Troubleshooting
 
-- **Unsupported Node:** upgrade Node before installing or rebuilding.
-- **Command not found:** check the npm global binary directory or the owned installer's PATH instructions.
-- **Python bootstrap cannot find uv:** install uv, or opt in with `BASE_CONTEXT_INSTALL_UV=1`.
-- **Manual Python is rejected:** install the current bundled `base-context-runtime` into the selected environment; do not reuse an upstream-only runtime.
-- **No usable model:** configure the actual provider route. A catalog entry is not authentication or subscription permission.
-- **Background service issue:** use `base-context status`, then `base-context doctor`; add `--fix` only when you want repairs.
+- **Missing or unsupported Node:** rerun the installer in a terminal and approve prerequisite setup. npm/source users must install supported Node themselves.
+- **Command not found:** run the installer's exact PATH command, or check your npm global binary directory if using npm.
+- **Python cannot find uv with npm/source:** launch with `BASE_CONTEXT_INSTALL_UV=1` as shown above.
+- **Manual Python is rejected:** install the current bundled runtime into that environment.
+- **No model selected:** use `/login` for your provider and `/model` for an explicit model choice.
+- **Background service issue:** use `base-context status`, then `base-context doctor`; add `--fix` when you want repairs.
 
 See [settings](settings.md), [usage](usage.md), and [development](development.md) for the full references.

package/docs/providers.md

@@ -1,35 +1,39 @@
 # Providers
 
-Base Context resolves providers through their actual API and credential routes. API keys can come from environment variables or the owned auth file. A model catalog entry does not establish subscription entitlement, OAuth-client permission or native context capabilities.
+Choose a supported **provider**, authenticate, then select a **model**. Base Context does not choose a provider or model automatically. Accounts, usage limits, and billing belong to the provider you select.
 
-## Table of Contents
+## First-time setup
 
-- [Subscriptions](#subscriptions)
-- [API Keys](#api-keys)
-- [Auth File](#auth-file)
-- [Cloud Providers](#cloud-providers)
-- [Custom Providers](#custom-providers)
-- [Resolution Order](#resolution-order)
+1. Start `base-context`.
+2. Open `/login` and select a provider. For a supported subscription, follow its browser authorization link. For API-key authentication, enter that provider's key. Bearer and cloud credentials use the provider-specific setup below.
+3. Open `/model` and choose a supported model. The selected provider/model is saved for later sessions.
 
-## Subscriptions
+For command-line selection, list the supported models and name both parts:
 
-Use only the provider/auth routes authorized for your setup. `/login` exposes the available configured routes; a fork does not inherit permission to use upstream OAuth clients. Where writable credential storage is supported, it belongs under `~/.base-context/auth.json` (or `BASE_CONTEXT_HOME`), not Prime's root. Login, refresh and logout behavior follows the selected route's permissions.
+```bash
+base-context model list
+base-context --provider openai --model gpt-5.4
+# Equivalent:
+base-context --model openai/gpt-5.4
+```
 
-Do not copy a Prime credential store or enable an API-key billing fallback to bypass a subscription refusal. The offline migration command excludes credentials.
+An API key alone does not select a model. A missing or unavailable saved model is not silently replaced with another provider. For models outside the built-in list, register the provider/model in [models.json](models.md) first.
 
-### OpenAI Codex
+## Authentication availability
 
-An existing authorized OpenAI Codex subscription can be supplied to an individual SDK instance through an explicitly injected read-only backend. See [SDK authentication](sdk.md#api-keys-and-oauth).
+Use `/login` for supported subscription OAuth or API-key authentication. The built-in subscription routes are **OpenAI Codex (ChatGPT)**, **Anthropic (Claude Pro/Max)**, and **GitHub Copilot**. Open the provider's browser link and complete its authorization steps. Access and usage limits depend on your provider account.
 
-That mode uses the official `openai-codex` / `openai-codex-responses` route. It refuses missing, stale or expired credentials and disables login, refresh, credential writes and API-key fallback. Keep the backend outside tools. This is an instance-scoped permission, not a global OAuth-client approval or an OpenAI endorsement of this fork.
+Credentials are stored in `~/.base-context/auth.json` (`BASE_CONTEXT_HOME` can select another state root). Normal OAuth storage persists credentials and refreshes them when needed. Provider-specific bearer and cloud credentials are described below. Prime integrations are disabled; this does not disable other registered OAuth providers.
 
-### Claude Pro/Max
+### ChatGPT / Codex subscription
 
-Use this route only where the exact client and account are authorized. This guide does not establish Claude subscription access, included usage or billing terms for the fork. An Anthropic API key is a separate credential route.
+1. Open `/login` and choose **OpenAI Codex**.
+2. Open the displayed browser link and sign in with the ChatGPT account that has Codex access. Complete the callback or paste the requested authorization response when prompted.
+3. Open `/model` and explicitly choose an `openai-codex` model available to your account.
 
-### GitHub Copilot
+An OpenAI API key belongs to the separate `openai` provider; it is not required for the Codex subscription route. Anthropic API-key authentication is likewise separate from Claude subscription login. Logging in does not automatically select or replace a model.
 
-If the authorized Copilot login route is available, use the correct github.com or GitHub Enterprise domain. Model availability also depends on the account and enabled models. This guide does not grant the fork access to a Copilot subscription.
+The SDK also offers an optional, explicitly injected read-only Codex backend for existing credentials. Only that mode disables login, refresh, credential writes, and API-key fallback. It does not restrict normal interactive subscription login. See [SDK authentication](sdk.md#api-keys-and-oauth).
 
 ## API Keys
 
@@ -47,7 +51,6 @@ base-context
 | Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
 | Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
 | OpenAI | `OPENAI_API_KEY` | `openai` |
-| Prime Inference | `PRIME_API_KEY` | `prime-inference` |
 | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
 | Google Gemini | `GEMINI_API_KEY` | `google` |
 | Mistral | `MISTRAL_API_KEY` | `mistral` |
@@ -81,7 +84,6 @@ Store credentials in the owned `~/.base-context/auth.json` (`BASE_CONTEXT_HOME`
 {
   "anthropic": { "type": "api_key", "key": "sk-ant-..." },
   "openai": { "type": "api_key", "key": "sk-..." },
-  "prime-inference": { "type": "api_key", "key": "..." },
   "deepseek": { "type": "api_key", "key": "sk-..." },
   "google": { "type": "api_key", "key": "..." },
   "opencode": { "type": "api_key", "key": "..." },
@@ -115,10 +117,6 @@ The `key` field supports three formats:
 
 Writable OAuth storage is used only when the configured route permits it. The read-only existing-Codex subscription mode does not write this file or refresh credentials. Shell-backed API-key entries execute commands; use only trusted local configuration, never unreviewed imported instructions.
 
-### Prime Inference
-
-Prime Inference uses the OpenAI-compatible endpoint at `https://api.pinference.ai/api/v1`. Set `PRIME_API_KEY` or store an API key for `prime-inference` via `/login`.
-
 ## Cloud Providers
 
 ### Azure OpenAI
@@ -159,7 +157,7 @@ Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_
 base-context --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
 ```
 
-Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set `AWS_BEDROCK_FORCE_CACHE=1` to enable cache points:
+Register custom application inference profile IDs in [models.json](models.md) before selecting them. Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set `AWS_BEDROCK_FORCE_CACHE=1` to enable cache points:
 
 ```bash
 export AWS_BEDROCK_FORCE_CACHE=1

package/docs/quickstart.md

@@ -2,17 +2,24 @@
 
 This page gets you to a useful first Base Context session. Base Context is a fork of Prime Agent, which descends from pi-mono; it uses its own command, packages and state.
 
-## Install
+## Install and launch
 
-Use Node.js `^22.12.0 || >=23.3.0` and a compatible npm version:
+On macOS or Linux, use the interactive **Synerise base-context installer**:
+
+```bash
+curl -fsSL https://github.com/BaseModelAI/base-context/releases/latest/download/install.sh | bash
+```
+
+It checks Node.js/npm and offers to install them if needed, installs `uv` when needed, and prepares the agent's Python environment before activation. **Do not install Python or `uv` manually before this command. Do not also run `npm install -g` unless you intentionally want a separate installation.**
+
+Follow the installer's final PATH/activation instruction, then launch:
 
 ```bash
-npm install -g @ponythewhite/base-context
 cd /path/to/project
 base-context
 ```
 
-Install [uv](https://docs.astral.sh/uv/getting-started/installation/) for the managed Python workspace. First use prepares Python 3.11 and the bundled `base-context-runtime`; initial setup can download dependencies.
+The next step is provider login below. The installer prepares the application, not your model-provider account. If you prefer npm or need Windows instructions, use the clearly separate [npm installation route](installation.md#npm-alternative).
 
 ### Build from source
 
@@ -35,7 +42,9 @@ For a source build, replace `base-context` in the examples below with that Node
 
 ## Authenticate
 
-Base Context uses `~/.base-context/auth.json` under its own product root. Do not copy Prime credential stores or assume that upstream OAuth clients are authorized for the fork. Choose an explicitly supported route in the [provider guide](providers.md).
+On first launch, choose a provider, authenticate if needed, then choose one of that provider's models. Existing credentials do not choose a provider or model for you. Cancelling leaves setup incomplete.
+
+Base Context stores credentials entered through `/login` in `~/.base-context/auth.json` and saves your explicit provider/model selection in settings. Later launches reuse that choice. If its credentials need renewal, authenticate the same provider; Base Context does not substitute another model. Environment credentials stay in the environment. See the [provider guide](providers.md) for supported routes.
 
 ### Subscription or Stored API Credentials
 
@@ -45,7 +54,7 @@ Start Base Context and run:
 /login
 ```
 
-Use only the provider/auth routes supported for your setup. A model catalog entry does not establish subscription entitlement or authentication. See [SDK authentication](sdk.md) for explicit subscription configuration.
+After login, choose a model in `/model`. Base Context does not pick a provider or model automatically. A saved selection is reused on later launches. See [SDK authentication](sdk.md) for programmatic setup.
 
 ### API Key
 
@@ -56,17 +65,17 @@ export ANTHROPIC_API_KEY=sk-ant-...
 base-context
 ```
 
-You can also select a supported API-key provider in `/login` to store its credential under `~/.base-context/auth.json`. `BASE_CONTEXT_HOME` changes that product root. Provider variables such as `ANTHROPIC_API_KEY` and `PRIME_API_KEY` keep their real provider names; they are not product-prefix aliases.
+You can also select a supported API-key provider in `/login` to store its credential under `~/.base-context/auth.json`. `BASE_CONTEXT_HOME` changes that product root. Provider variables such as `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` keep their real provider names; they are not product-prefix aliases.
 
 ## First Session
 
-Once Base Context starts, type a request and press Enter:
+Once you have authenticated and selected a model, type a request and press Enter:
 
 ```text
 Summarize this repository and tell me how to run its checks.
 ```
 
-Base Context uses the persistent `ipython` kernel for file operations, project commands, data analysis and installed skills. The owned installer prepares a fresh release-local Python environment before activation. A non-owned source setup bootstraps its default environment under `~/.base-context/runtime` on first use. `BASE_CONTEXT_KERNEL_PYTHON` selects an explicit manual Python executable with a current `base-context-runtime`; the Python import remains `rlm`. An upstream `prime-agent-runtime` environment is not a substitute.
+Base Context uses the persistent `ipython` kernel for file operations, project commands, data analysis and installed skills. The owned installer prepares a fresh release-local Python 3.13 environment before activation. A source launch starts preparing its default environment under `~/.base-context/runtime` in the background. Set `BASE_CONTEXT_INSTALL_UV=1` before launching if `uv` must be installed automatically. `BASE_CONTEXT_KERNEL_PYTHON` selects an explicit manual Python executable with a current `base-context-runtime`; the Python import remains `rlm`. An upstream `prime-agent-runtime` environment is not a substitute.
 
 Base Context runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.
 
@@ -146,7 +155,7 @@ For legacy data, use the [offline migration steps](usage.md#import-an-offline-pr
 For one-shot prompts:
 
 ```bash
-base-context -p "Summarize this codebase"
+base-context --provider anthropic --model claude-sonnet-4-6 -p "Summarize this codebase"
 cat README.md | base-context -p "Summarize this text"
 base-context -p @screenshot.png "What's in this image?"
 ```

package/docs/rlm-runtime.md

@@ -73,16 +73,16 @@ The Python side does not call providers or implement an agent loop.
 
 ## Kernel Lifecycle
 
-The kernel is created lazily on first Python REPL use. Python resolution is:
+SDK and child sessions normally start the kernel lazily on first Python REPL use. The CLI root starts preparing it in the background; saved snapshots can also trigger prewarming. Python resolution is:
 
-1. `BASE_CONTEXT_KERNEL_PYTHON`, when it has a current `base-context-runtime`; otherwise
-2. the managed environment selected by `BASE_CONTEXT_KERNEL_VENV`, an owned release-local environment, or `~/.base-context/runtime`.
+1. An explicit `BASE_CONTEXT_KERNEL_PYTHON` takes precedence and must provide a current `base-context-runtime`. An invalid override reports an error rather than selecting another interpreter.
+2. Without an interpreter override, use the managed environment selected by `BASE_CONTEXT_KERNEL_VENV`, an owned release-local environment, or `~/.base-context/runtime`.
 
-The default managed environment includes Python 3.11, `base-context-runtime`, `dill`, and the default Python packages. Bootstrap uses `uv`; install it first or opt in with `BASE_CONTEXT_INSTALL_UV=1`. The owned installer prepares its release-local default environment before activation. A bootstrap marker detects stale environments. There is no fallback into upstream Prime state. See [installation](installation.md#python-setup).
+The default managed environment includes Python 3.13, `base-context-runtime`, `dill`, and the default Python packages. Bootstrap uses `uv`; install it first or opt in with `BASE_CONTEXT_INSTALL_UV=1`. The owned installer prepares its release-local default environment before activation. A bootstrap marker detects stale environments. There is no fallback into upstream Prime state. See [installation](installation.md#python-setup).
 
 Startup spawns `python -m rlm.repl` and exchanges newline-delimited JSON over stdio: the runtime announces itself with a single `ready` event, then requests and events flow one JSON object per line (see `prime-agent-runtime/src/rlm/repl.md`).
 
-The manager owns the child process and a bounded stderr tail. Shutdown sends a `shutdown` request, waits for the process to exit, and terminates it as a fallback. Persistent sessions may snapshot the kernel namespace into their session artifact directory for revival.
+The manager owns the child process and a bounded stderr tail. Shutdown sends a `shutdown` request, waits for the process to exit, and terminates it as a fallback. Persistent sessions may snapshot the kernel namespace into their session artifact directory for revival. Startup refuses snapshots from a different Python major/minor before restoring them and leaves those files unchanged.
 
 ## Stdio Transport
 
@@ -155,6 +155,14 @@ Unknown options fail instead of being ignored. Model search is bounded to active
 
 Children receive incremented `RLM_DEPTH`, the inherited maximum depth, and their own `RLM_SESSION_DIR`. The default maximum depth is 2, so root sessions may create children and grandchildren; grandchildren may not create another generation unless the limit is configured higher.
 
+## Concurrent Subagent Limit
+
+A root agent and its descendants share one live-subagent cap, independent of the recursion-depth limit. The default is **4**. Running and idle subagents at every depth count; the main/root agent and inactive saved sessions do not. Admission fails when there are no free slots.
+
+[`/agents N`](usage.md#limit-concurrent-subagents) updates the current family cap and saves the global `rlmMaxSubagents` preference for later sessions and restarts. `N` must be a non-negative safe integer; `0` blocks new subagent spawns. `/agents` queries the effective current family value rather than displaying the default.
+
+Lowering the cap never cancels, kills, or passivates existing subagents. It only prevents new admissions while the live count is at or above the cap. Existing running and idle agents retain their state.
+
 ## Independent Delegation
 
 Each direct call admits an independent child and returns its handle immediately:

package/docs/rpc.md

@@ -9,10 +9,10 @@ RPC mode enables headless operation of the coding agent via a JSON protocol over
 ## Starting RPC Mode
 
 ```bash
-base-context --mode rpc --rpc-protocol-version 11 [options]
+base-context --mode rpc --rpc-protocol-version 13 [options]
 ```
 
-`--rpc-protocol-version 11` is required. It declares that the client handles both successful `agent_end` events and refusal-only terminal events as described below. A missing or different marker is rejected before a session starts. The typed RpcClient also verifies protocol 11 and schema revision at least 45 through the existing `get_state` response before use. Hosts below the current canonical-session ownership minimum are refused; an incompatible startup uses the existing process cleanup path. Custom RPC server entry points `runRpcMode` and `runRpcModeWithConnection` require the caller's protocol version as their second argument.
+`--rpc-protocol-version 13` is required. It declares that the client handles both successful `agent_end` events and refusal-only terminal events as described below. A missing or different marker is rejected before a session starts. The typed RpcClient also verifies protocol 13 and schema revision at least 49 through the existing `get_state` response before use. Hosts below the current canonical-session ownership minimum are refused; an incompatible startup uses the existing process cleanup path. Custom RPC server entry points `runRpcMode` and `runRpcModeWithConnection` require the caller's protocol version as their second argument.
 
 This uses the current Base Context daemon protocol marker, not the package version. Updating only the server cannot make an old client understand a new terminal event.
 
@@ -1392,7 +1392,7 @@ import subprocess
 import json
 
 proc = subprocess.Popen(
-    ["base-context", "--mode", "rpc", "--rpc-protocol-version", "11", "--no-session"],
+    ["base-context", "--mode", "rpc", "--rpc-protocol-version", "13", "--no-session"],
     stdin=subprocess.PIPE,
     stdout=subprocess.PIPE,
     text=True
@@ -1433,7 +1433,7 @@ For a complete example of handling the extension UI protocol, see [`examples/rpc
 const { spawn } = require("child_process");
 const { StringDecoder } = require("string_decoder");
 
-const agent = spawn("base-context", ["--mode", "rpc", "--rpc-protocol-version", "11", "--no-session"]);
+const agent = spawn("base-context", ["--mode", "rpc", "--rpc-protocol-version", "13", "--no-session"]);
 
 function attachJsonlReader(stream, onLine) {
     const decoder = new StringDecoder("utf8");

package/docs/sdk.md

@@ -15,7 +15,10 @@ See [examples/sdk/](../examples/sdk/) for working examples from minimal to full
 
 ## Quick Start
 
+Choose a supported provider and model explicitly. This example uses Anthropic; configure `ANTHROPIC_API_KEY` or its saved authentication before running it.
+
 ```typescript
+import { getModel } from "@ponythewhite/base-context-ai";
 import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@ponythewhite/base-context";
 
 // Set up credential storage and model registry
@@ -26,6 +29,7 @@ const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
   authStorage,
   modelRegistry,
+  model: getModel("anthropic", "claude-sonnet-4-5"),
 });
 
 session.subscribe((event) => {
@@ -422,33 +426,38 @@ const { session } = await createAgentSession({
 });
 ```
 
-If no model is provided:
-1. Tries to restore from session (if continuing)
-2. Uses default from settings
-3. Falls back to first available model
+Pass a supported `model` explicitly, or omit it to reuse an explicit selection saved in the session or settings. Pass `model: null` to leave the session unselected without restoring a saved choice. Base Context never chooses the first available model or switches providers because another credential exists.
+
+A supported saved model remains selected when its authentication needs setup. Requests fail before transport until that provider is authenticated. An unavailable saved model produces a diagnostic and requires a new explicit selection.
 
 > See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
 
 ### API Keys and OAuth
 
+`AuthStorage.create()` uses normal writable credential storage. Supported subscription
+providers can log in through `/login` in the CLI, or through `authStorage.login(providerId,
+callbacks)` in an SDK application. Supply the browser/prompt callbacks for the provider
+flow. Normal storage persists credentials and refreshes OAuth tokens when needed.
+Authentication does not select a model; choose one explicitly or reuse a saved choice.
+Prime integrations remain disabled.
 
-For an existing OpenAI Codex subscription, explicitly inject a read-only backend:
+For **optional read-only** use of an existing OpenAI Codex subscription, explicitly inject a backend:
 
 ```typescript
 import { AuthStorage } from "@ponythewhite/base-context";
 
 const authStorage = AuthStorage.fromStorage(readOnlyBackend, {
   existingOpenAICodexSubscription: true,
-  usePrimeCliConfig: false,
 });
 ```
 
 The backend implements `AuthStorageBackend` and supplies only the existing OAuth access
 credential and expiry. File-backed writable storage is rejected in this mode. Missing,
 stale or expired credentials refuse use; login, refresh, storage writes and API-key
-fallback are disabled. This authorizes only this instance's official
-`openai-codex` / `openai-codex-responses` route. It does not globally validate OAuth clients
-or protect against trusted in-process code. Keep the credential backend outside tools.
+fallback are disabled. This mode is limited to this instance's
+`openai-codex` / `openai-codex-responses` route. These restrictions do not apply to normal
+writable OAuth storage, and do not protect against trusted in-process code. Keep the
+credential backend outside tools.
 
 API key resolution priority (handled by AuthStorage):
 1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
@@ -1321,7 +1330,7 @@ const runtime = await createAgentSessionRuntime(createRuntime, {
   sessionManager: await SessionManager.create(process.cwd()),
 });
 
-await runRpcMode(runtime, 11);
+await runRpcMode(runtime, 13);
 ```
 
 See [RPC documentation](rpc.md) for the JSON protocol.
@@ -1331,7 +1340,7 @@ See [RPC documentation](rpc.md) for the JSON protocol.
 For subprocess-based integration without building with the SDK, use the CLI directly:
 
 ```bash
-base-context --mode rpc --rpc-protocol-version 11 --no-session
+base-context --mode rpc --rpc-protocol-version 13 --no-session
 ```
 
 See [RPC documentation](rpc.md) for the JSON protocol.

package/docs/sessions.md

@@ -41,7 +41,6 @@ For native journal storage and the SessionManager API, see [Session Format](sess
 | `/clone` | Duplicate the current active branch into a new session |
 | `/compact [prompt]` | Summarize older context; see [Compaction](compaction.md) |
 | `/export [file]` | Export session to HTML |
-| `/share` | Upload as private GitHub gist with shareable HTML link |
 
 ## Importing an External Session