Issues #5–#11: provider-agnostic auth, expert tools, multi-ref provenance, session naming (v0.2.2)

CLAUDE.md

@@ -58,18 +58,18 @@ Plain **Lit web components** (no React), bundled by esbuild to `out/webview/main
 
 `chronos/extensions/index.ts` is the pi-package entrypoint: it registers tools, the `/select-source` and `/yolo` commands, and lifecycle hooks. Tools live in `chronos/tools/` and share a mutable `SourceContext` (`tools/source-context.ts`) so `change_source` can redirect all source-bound tools at runtime. The system prompt is **rebuilt every turn** by the `before_agent_start` hook from `prompts/system-prompt.md` + the current `SourceContext` — it is never part of the persisted message history.
 
-Key tools: `task`/`task_batch` (spawn persistent vision-expert subagents per page, follow-up-able via `task_id`), `list_pages`, `show_page`/`show_text` (viewer), `change_source`. Expert models are any `provider/model-id` pi has auth for (default `google/gemini-3-flash-preview`).
+Key tools: `task`/`task_batch` (spawn persistent vision-expert subagents per page, follow-up-able via `task_id`; the expert runs a bounded tool loop and can `view_region`/`view_page` to self-zoom), `list_pages`, `show_page`/`show_text` (viewer), `change_source`. Expert models are any `provider/model-id` pi has auth for; no provider is hardcoded — they default to the orchestrator's current model.
 
 ### Important runtime facts
 
 - **pi loads the agent from `dist/`, not the TS source.** The `pi` field points extensions at `./dist/extensions`. After editing anything under `chronos/{extensions,tools,utils,http}/*.ts` you MUST `cd chronos && npm run build` or the change won't take effect. Prompts and skills (`chronos/prompts/`, workspace `skills/`) are read live — no rebuild needed.
 - **Which package pi runs is set in `~/.pi/agent/settings.json` `packages`.** Released use points at the GitHub repo (cloned under `~/.pi/agent/git/`). For local development, point that entry at the absolute path of the `chronos/` dir so sessions run your working copy (after building). Sessions snapshot at startup — restart the session to pick up agent changes.
-- **Runtime pi ≠ build-time pi.** The package builds against the `@mariozechner/pi-coding-agent` peer dep, but the installed `pi` binary may be a renamed fork (`@earendil-works/pi-coding-agent`) at a newer version. When debugging pi behavior, read the binary's actual install, not `chronos/node_modules`.
+- **pi packages were renamed.** `@mariozechner/pi-{coding-agent,ai}` are deprecated (frozen at 0.73.x); the maintained packages are `@earendil-works/pi-{coding-agent,ai}` (same author, a scope rename). Both the pi-package's peer deps and the installed `pi` binary now use `@earendil-works`. **Runtime pi ≠ build-time pi:** the build-time package in `chronos/node_modules` and the globally-installed `pi` binary can still drift in version — when debugging pi behavior, read the binary's actual install, not `chronos/node_modules`. The 0.79 API differs from 0.73 (e.g. `session_switch`/`session_directory` hooks were dropped — `session_start` now carries a `reason`, and `PI_CODING_AGENT_SESSION_DIR` replaces the session-dir hook).
 - **Every `.md` in `chronos/prompts/` becomes a slash command** because pi auto-registers prompt templates. Only `select-source` and `yolo` are real user commands; the rest are tool text / the system prompt. The webview slash-command menu therefore filters out `source: "prompt"` entries with `sourceInfo.origin === "package"` (see `chronos-panel.ts`).
 
 ### Workspace layout (user-facing, created by `Chronos: Init Workspace`)
 
-A Chronos *workspace* (separate from this repo) contains `sources/<name>/png/page_NNNN.png`, `data/` (outputs), `memory/` (`MEMORY.MD` + per-source `.md`, injected into the system prompt), `skills/<name>/SKILL.md`, `sessions/`, and `.chronos/` (`.env` with `GEMINI_API_KEY`, `settings.json` for the `yolo` flag, `session-sources.json` mapping session id → selected source for resume). The workspace `skills/` dir is bridged into pi via `.pi/settings.json` (`{ "skills": ["../skills"] }`).
+A Chronos *workspace* (separate from this repo) contains `sources/<name>/png/page_NNNN.png`, `data/` (outputs), `memory/` (`MEMORY.MD` + per-source `.md`, injected into the system prompt), `skills/<name>/SKILL.md`, `sessions/`, and `.chronos/` (`.env` with provider API keys e.g. `ANTHROPIC_API_KEY`/`GEMINI_API_KEY`, written by the panel's "Log in" flow; `settings.json` for the `yolo` flag; `session-sources.json` mapping session id → selected source for resume; `session-names.json` caching auto-generated session titles). The workspace `skills/` dir is bridged into pi via `.pi/settings.json` (`{ "skills": ["../skills"] }`).
 
 ## Reference
 

DOCS.md

@@ -19,7 +19,7 @@
 │   └── <source-name>.md     # Per-source findings
 ├── sessions/                 # Conversation history (auto-generated)
 └── .chronos/
-    └── .env                  # GEMINI_API_KEY
+    └── .env                  # provider API keys (e.g. ANTHROPIC_API_KEY, GEMINI_API_KEY)
 ```
 
 ## Tools
@@ -40,15 +40,44 @@ Standard file tools (`read`, `write`, `edit`, `grep`, `find`, `ls`) are also ava
 ### Expert models
 
 The `task` and `task_batch` tools accept any model pi has configured auth for, as
-`provider/model-id` (default: `google/gemini-3-flash-preview`), e.g.:
+`provider/model-id`. If you omit it, they default to the model selected in the panel
+header (the orchestrator's current model) — no provider is hardcoded. Examples:
 
+- `anthropic/claude-opus-4-8`
 - `google/gemini-3-flash-preview`
 - `google/gemini-3.1-pro-preview`
-- `anthropic/claude-opus-4-8`
+- `openai/gpt-...`
+
+The model must be vision-capable when a page image is attached. An unknown model name
+errors with the list of available models.
+
+**Choosing a model** (recommendation, not a requirement): a fast/cheap vision model such
+as `google/gemini-3-flash-preview` is a good default for routine pages; reach for a
+stronger one (e.g. `google/gemini-3.1-pro-preview` or `anthropic/claude-opus-4-8`) on
+dense tables, marginalia, or faint/damaged ink. Experts can also zoom in themselves (see
+`view_region` / `view_page` below), which often matters more than raw model size.
+
+Each expert keeps its own conversation (addressed by the `task_id` the tool returns), so you can ask follow-ups without re-sending the page image. These conversations are persisted per session under `.chronos/expert-sessions/`, so `task_id` follow-ups keep working after the agent restarts or a session is resumed. (Stored compactly — page images, including any tool-driven zoom crops, are re-read from disk on restore, not duplicated.)
+
+#### Expert self-direction
+
+Experts aren't limited to the single (optionally pre-cropped) image the orchestrator hands them — they run a bounded agentic loop (capped at 8 tool calls/turn). **By default they are read-only:**
+
+- **`view_region(bbox, [page_id])`** — crop a region of a page at full resolution (dense table, marginal note, faint ink). Omits `page_id` to zoom into the page in view.
+- **`view_page(page_id)`** — load another full page from the same source.
+- **`read_file(path)`** / **`list_dir([path])`** / **`grep(pattern, [path])`** — read and search the workspace (schemas, memory, prior outputs). Scoped to the workspace root.
+
+So you don't have to predict the right crop up front — pass the page and let the expert zoom and cross-reference where it needs to.
+
+#### Granting elevated capabilities (off by default)
 
-An unknown model name errors with the list of available models.
+Experts **cannot run commands or change files** unless the orchestrator passes `grant` on the `task`/`task_batch` call:
 
-Each expert keeps its own conversation (addressed by the `task_id` the tool returns), so you can ask follow-ups without re-sending the page image. These conversations are persisted per session under `.chronos/expert-sessions/`, so `task_id` follow-ups keep working after the agent restarts or a session is resumed. (Stored compactly — page images are re-read from disk on restore, not duplicated.)
+- `grant: ["bash"]` — `bash(command)` (runs in the workspace dir)
+- `grant: ["write"]` — `write_file(path, content)`
+- `grant: ["edit"]` — `edit_file(path, old_text, new_text)`
+
+This path is deliberately gated for oversight and safety: requesting a grant triggers a **user confirmation** before any expert runs (once per `task` call, or once for a whole `task_batch` cohort), and denial aborts the call. Granted file operations are confined to the workspace. Whatever the expert does — every region viewed, file read/written, command run — is surfaced in the expert drawer (the "examined" steps; region/page steps are clickable, elevated actions are flagged), so the work stays auditable. Leave `grant` off unless a task genuinely needs the expert to act on its own.
 
 ### Bounding box cropping
 
@@ -70,9 +99,9 @@ To make each row traceable to its source page, include any of these reserved key
 
 | Key | Type | Meaning |
 |-----|------|---------|
-| `chronos_page` | integer | Page the record was read from (same numbering as `show_page` / `[view p.N]`). |
-| `chronos_bbox` | `[x, y, w, h]` (or `{x,y,w,h}`) | *Optional.* Region on that page, normalized 0–1. |
-| `chronos_source` | string | *Optional.* Workspace-relative source path (e.g. `sources/Frankfurt_1864`) when the row is from a different source than the one in view. |
+| `chronos_page` | integer **or list** | Page the record was read from (same numbering as `show_page` / `[view p.N]`). |
+| `chronos_bbox` | `[x, y, w, h]` / `{x,y,w,h}` **or list** | *Optional.* Region on that page, normalized 0–1. |
+| `chronos_source` | string **or list** | *Optional.* Workspace-relative source path (e.g. `sources/Frankfurt_1864`) when the row is from a different source than the one in view. |
 
 Example (`data/Frankfurt_1864/entries.json`):
 
@@ -83,6 +112,27 @@ Example (`data/Frankfurt_1864/entries.json`):
 ]
 ```
 
+#### Multiple references per row
+
+A row can cite **more than one** source location — a value split across two pages, a figure assembled from several regions, or a fact corroborated by a marginal note. Pass the reserved keys as **parallel lists** and the Data tab renders one citation chip per reference, each linking to its own page/region:
+
+```json
+[
+  {
+    "name": "Anna Weber",
+    "chronos_page": [42, 43],
+    "chronos_bbox": [[0.10, 0.90, 0.80, 0.06], [0.10, 0.04, 0.80, 0.06]]
+  },
+  {
+    "name": "Karl Vogt",
+    "chronos_page": 42,
+    "chronos_bbox": [[0.10, 0.32, 0.80, 0.05], [0.55, 0.32, 0.40, 0.05]]
+  }
+]
+```
+
+The lists align by index. A scalar is treated as a single-element list (so existing single-reference outputs are unchanged), and a length-1 list **broadcasts** — e.g. one `chronos_source` shared across several pages, or several `chronos_bbox` regions on a single `chronos_page` (the second row above). A reference must resolve to a page id.
+
 The keys are a recommendation — outputs without them still appear in the Data tab, just without click-to-source.
 
 ## Skills

README.md

@@ -10,7 +10,7 @@ An AI agent that collaborates with historians to extract structured datasets fro
 
 - [VS Code](https://code.visualstudio.com/) (v1.110+)
 - [Node.js](https://nodejs.org/) (v18+) — required by the underlying `pi` agent the extension installs on first run
-- A [Gemini API key](https://aistudio.google.com/apikey) for the vision model
+- An API key for an AI provider with a vision-capable model (Anthropic, Google, OpenAI, …). You connect it from inside the panel — see [Start the agent](#3-start-the-agent).
 
 ## Installation
 
@@ -29,7 +29,7 @@ If you'd rather install everything by hand:
 
 ```bash
 # 1. Install the pi agent globally
-npm install -g @mariozechner/pi-coding-agent
+npm install -g @earendil-works/pi-coding-agent
 
 # 2. Register the Chronos pi-package
 pi install https://github.com/ai-historian/chronos
@@ -46,7 +46,7 @@ The `.vsix` is published on [GitHub Releases](https://github.com/ai-historian/ch
 
 ### 1. Initialize a workspace
 
-Open VS Code in an empty folder. Press `Ctrl+Shift+P` and run **Chronos: Init Workspace**. This creates the workspace structure and prompts for your Gemini API key.
+Open VS Code in an empty folder. Press `Ctrl+Shift+P` and run **Chronos: Init Workspace**. This creates the workspace structure. (You connect an AI provider in step 3 — no key is needed yet.)
 
 ### 2. Import sources
 
@@ -60,27 +60,37 @@ Converting a large PDF can take a few minutes. Imports are crash-safe: a source
 
 Press `Ctrl+Shift+P` and run **Chronos: Start Agent Session**. The Chronos panel opens — a page viewer on the left and a chat on the right.
 
-On first startup, type `/login` in the chat to log into your AI provider account (e.g. Anthropic, Google). Without this, no models will be available.
+On first startup no AI models are available until you connect a provider. Click **Log in** in the panel header (or run **Chronos: Connect AI Provider**) and choose how to sign in:
+
+- **Anthropic — Claude Pro/Max (subscription):** signs in with your Claude subscription via OAuth in the browser — no API key needed. The credential is stored in pi's `~/.pi/agent/auth.json`.
+- **API key (any provider):** paste a key; Chronos saves it to the workspace `.chronos/.env`.
+
+Either way Chronos reconnects automatically. You can switch or add providers the same way at any time.
 
 Pick a source from the header dropdown (or type `/select-source`) and begin working.
 
 ## Configuration
 
-### Environment variables
+### AI provider & models
 
-Set in `.chronos/.env`:
+Connect a provider with the **Log in** button (above); it stores the key in `.chronos/.env`. You can also edit that file directly — pi reads the standard per-provider variables:
 
 ```
-GEMINI_API_KEY=your-key-here
+ANTHROPIC_API_KEY=...      # Claude
+GEMINI_API_KEY=...         # Google Gemini
+OPENAI_API_KEY=...         # OpenAI
+# OPENROUTER_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, …
 ```
 
+The page-analysis tools (`task` / `task_batch`) default to the model selected in the header, but accept any vision-capable model pi has auth for via a `model: "provider/model-id"` argument. Chronos is provider-agnostic — choose what fits your budget and accuracy needs. As a starting point, a fast/cheap vision model (e.g. `google/gemini-3-flash-preview`) works well for routine pages, and a stronger model (e.g. `google/gemini-3.1-pro-preview` or `anthropic/claude-opus-4-8`) helps on dense or damaged pages.
+
 ### pi options
 
 pi supports many options natively. Common ones:
 
 ```bash
 # Use a specific model
-pi --model gemini-2.5-pro
+pi --model anthropic/claude-opus-4-8
 
 # Continue previous session
 pi -c

chronos-vscode/README.md

@@ -8,17 +8,17 @@ An AI agent that collaborates with historians to extract structured datasets fro
 
 - VS Code v1.110+
 - [Node.js](https://nodejs.org/) v18+ — required by the underlying `pi` agent the extension installs on first run
-- A [Gemini API key](https://aistudio.google.com/apikey) for the vision model
+- An API key for an AI provider with a vision-capable model (Anthropic, Google, OpenAI, …) — you connect it from the panel on first run
 
 ## Installation
 
 Install **Chronos — The AI Historian** from the Extensions view, then run any Chronos command from the Command Palette (`Ctrl+Shift+P`). The first run checks for [`pi`](https://github.com/badlogic/pi-mono) (the agent framework Chronos runs on) and the Chronos pi-package, and offers to install both in a terminal — no manual setup required.
 
 ## Getting started
 
-1. **Chronos: Init Workspace** — open an empty folder and run this to create the workspace structure and set your Gemini API key.
+1. **Chronos: Init Workspace** — open an empty folder and run this to create the workspace structure.
 2. **Chronos: Import Sources** — add PDFs, images (PNG/JPG/TIFF/BMP), or text files. PDFs are converted to page images; imports are crash-safe and resumable.
-3. **Chronos: Start Agent Session** — open the page viewer + chat and begin extracting data.
+3. **Chronos: Start Agent Session** — open the page viewer + chat. Click **Log in** in the header (or run **Chronos: Connect AI Provider**) to connect a provider — sign in with a **Claude Pro/Max subscription** (OAuth) or paste an **API key** for any provider — then begin extracting data.
 
 ## Documentation