Global configuration mode design spec by DavertMik · Pull Request #107 · testomatio/explorbot

DavertMik · 2026-08-03T12:49:59Z

Summary

Design spec for global configuration mode: explorbot init --global sets up AI config once in ~/.explorbot, and every explored site gets a persistent subfolder under ~/.explorbot/sites/<host>/ with knowledge, experience, and output.

Key decisions (spec only, no implementation yet):

Config ladder in core ConfigParser: project config → ~/.explorbot/config.js (global mode) → EXPLORBOT_* env config. A config file wins wholesale over env vars, as documented today. All boats (prima, api-tester, doc-collector) inherit with zero boat changes.
Full project semantics in global mode: experience read+write on, Historian on — learning accumulates per site across runs from any directory.
Auto-registration: first visit to a URL creates sites/<host>/ with site.json; later runs can use bare references like app.example.com/login; new explorbot sites command lists registered sites.
init --global is an interactive Ink wizard (provider → API key → optional validation), with --provider as the non-interactive escape for agents.
Cross-platform via os.homedir() only; amends the prima spec's state/<host> layout to sites/<host>.

Review notes

This implements the "Config-Free Operation" direction already committed in the prima boat spec (2026-08-01-prima-boat-design.md), generalized to the whole tool.

🤖 Generated with Claude Code

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-08-03T13:08:39Z

Explorbot Self-Regression

Commit a88022a · run

Scenario	Result	Attempts	Duration
basic (native)	PASS	1/3	8m
experience: control	OK — failed as expected	1/1	1m
experience: seeded	PASS	1/3	2m

Attempt details

basic (native) attempt 1 — PASS: login evidence: PASS (post-login plan=true, post-login research=true); research: PASS (files=6, wellFormed=true, keywords=6/3); scenarios: PASS (tests=6/5, features=4/3); tests passed: PASS (5 passed, 0 failed (reporter: 5 passed, 0 failed))
experience: control attempt 1 — PASS: control: OK — failed as expected (0 passed, 1 failed)
experience: seeded attempt 1 — PASS: seeded: PASS (1 passed, 0 failed)

Session analysis — basic (native):

Session Analysis

Explored the Issues list page functionality including creation, search, status filtering, label filtering, and empty-state handling. All core flows work correctly.

Coverage

Pages: /issues
Features: Issue creation, search filtering, status filtering, label filtering, empty state display

What works

Issue creation — ET-1 Create new issue from toolbar
Search by title — ET-2 Search for existing issue by title
Status filtering — ET-3 Filter issues by status
Label filtering — ET-4 Filter issues by label
Empty state for no results — ET-5 Search for non-existent issue

Execution Issues

ET-4 Filter issues by label — multiple click attempts to reset dropdown, required retry loops

…stalled Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Explorbot can be configured once per machine in ~/.explorbot instead of per project. Global config is a rung in the core ConfigParser lookup, so core commands and the boats inherit it. - `~/.explorbot/config.js` is tried after the project config paths and before EXPLORBOT_* env vars; a config file still wins wholesale - `~/.explorbot/.env` loads before the cwd .env, so a project key wins - Global mode resolves dirs to `~/.explorbot/sites/<host>/` with full project semantics: experience on, Historian on, reports in the site - Sites auto-register with site.json on first visit and update lastRunAt; later runs reference them by bare host. `explorbot sites` lists them - `explorbot init` opens a Local/Global chooser in a terminal; `--global` runs the setup wizard, `--provider`/`--api-key` skip it for agents - Model roles accept 'provider/model-id' strings, so the global config needs no provider imports it cannot resolve from ~/.explorbot - api-tester derives its site from the endpoint host Implements docs/superpowers/specs/2026-08-03-global-config-design.md Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

DenysKuchma · 2026-08-05T10:26:52Z

+            Enter the API key for {provider} <Text dimColor>(stored as {envKey})</Text>
+          </Text>
+          <Box borderStyle="single" borderColor="blue" paddingX={1}>
+            <InputReadline value={apiKey} onChange={setApiKey} onSubmit={() => setStep('validate')} placeholder={process.env[envKey] ? 'leave empty to keep the key from your environment' : 'paste the key'} isActive showPrompt={false} />


The API key is rendered as plain text.
InputReadline displays value directly, the secret remains visible in the terminal and may be captured in terminal recordings

DenysKuchma · 2026-08-05T10:27:32Z

+
+  if (raw.startsWith('http://') || raw.startsWith('https://')) {
+    const url = new URL(raw);
+    return { baseUrl: url.origin, path: `${url.pathname}${url.search}` };


Absolute targets drop the URL fragment
Add support for hash-based SPAs

Unify prima's ~/.explorbot/state/<host> with the site registry, address PR review comments, and give every boat the same missing-configuration hint. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

- rename prima's ~/.explorbot/state/<host> to sites/<host> so config-free and global runs share one site folder, and move its artifacts under output/ - keep the URL fragment when resolving a site target, for hash-routed apps - mask the API key while it is typed into the global setup wizard - one missing-configuration message for the CLI and every boat, offering init --global, init, or EXPLORBOT_* variables - agent docs start from the global installation, env vars are the fallback Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

A machine-wide installation must not override what a single command asks for, so env-var mode is tried before ~/.explorbot/config.*. A project config still wins over both. Precedence, highest first: --config, project config, EXPLORBOT_*, global. Also takes the env-mode URL from an absolute command target, so EXPLORBOT_AI_PROVIDER=groq explorbot explore https://app.example.com no longer demands EXPLORBOT_URL as well. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

DenysKuchma · 2026-08-06T21:51:40Z

Commit 7cc52eb added a self-referential symlink at node_modules because the .gitignore pattern used a trailing slash, which matches directories only and let a symlink of the same name through. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

DavertMik and others added 2 commits July 22, 2026 01:22

chore: update .claude skills

aed9610

Add global configuration mode design spec

166c772

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

DavertMik temporarily deployed to regression August 3, 2026 12:50 — with GitHub Actions Inactive

Spec: plain init offers Local/Global chooser, Global disabled once in…

5f9101c

…stalled Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

DavertMik had a problem deploying to regression August 4, 2026 10:25 — with GitHub Actions Failure

DavertMik and others added 2 commits August 5, 2026 02:02

Merge branch 'main' of github.com:testomatio/explorbot

4c012cb

DavertMik temporarily deployed to regression August 4, 2026 23:44 — with GitHub Actions Inactive

DenysKuchma requested changes Aug 5, 2026

View reviewed changes

DavertMik and others added 4 commits August 5, 2026 23:13

Merge branch 'main' of github.com:testomatio/explorbot

f03fb95

Merge branch 'main' of github.com:testomatio/explorbot

f6afd6e

Merge origin/main into docs/global-config-spec

f9b5393

Unify prima's ~/.explorbot/state/<host> with the site registry, address PR review comments, and give every boat the same missing-configuration hint. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

DavertMik temporarily deployed to regression August 6, 2026 12:24 — with GitHub Actions Inactive

DavertMik and others added 3 commits August 6, 2026 21:50

added poolside as provider

965e820

Merge branch 'main' into docs/global-config-spec

58692a4

DenysKuchma requested changes Aug 6, 2026

View reviewed changes

Comment thread node_modules Outdated

DenysKuchma Aug 6, 2026

Copy link
Copy Markdown

Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?????

DavertMik merged commit 003f2c2 into main Aug 6, 2026

DavertMik deleted the docs/global-config-spec branch August 6, 2026 22:35

Navigation Menu

Uh oh!

Global configuration mode design spec - #107

Global configuration mode design spec#107
DavertMik merged 13 commits into
mainfrom
docs/global-config-spec

DavertMik commented Aug 3, 2026

Uh oh!

github-actions Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

DenysKuchma Aug 5, 2026

Uh oh!

DenysKuchma Aug 5, 2026

Uh oh!

DenysKuchma Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

DavertMik commented Aug 3, 2026

Summary

Review notes

Uh oh!

github-actions Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explorbot Self-Regression

Attempt details

Session Analysis

Coverage

What works

Execution Issues

Uh oh!

DenysKuchma Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

DenysKuchma Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

DenysKuchma Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Aug 3, 2026 •

edited

Loading