Fix new-user friction: doctor diagnostics, reasoning_effort validation, quickstart, docs - #11
Merged
Merged
Conversation
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KhxqgzVNZB1P82smfaM2Lo
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KhxqgzVNZB1P82smfaM2Lo
The doctor reported a generic "no usable key" even when a profile had a key but was missing MODEL_PROVIDER/MODEL; it now surfaces the specific ProviderConfigError per profile. load_provider_profile now rejects an invalid REASONING_EFFORT (e.g. 'minimal') for openai up front, instead of letting every agent/forum/distill call 400 with the error buried in the runtime sidecar DB. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XvzJBrjK196FnT8cG3hVFf
TASKS_PATH was a hardcoded assignment while PROFILE/EXPERIMENT_NAME were
overridable, so 'TASKS_PATH=... bash scripts/quickstart.sh' silently ran the
bundled demo. Make it ${TASKS_PATH:-...} and document the knob.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XvzJBrjK196FnT8cG3hVFf
0 cross-task posts is expected when the cross-task forum is off, at gen 1, or when none were produced — it fired as a scary WARNING on clean runs. Downgrade to INFO and clarify the message. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XvzJBrjK196FnT8cG3hVFf
…tput details Add a note on why the demo doesn't show steps 3-5 (single generation, forums off, all-solved -> early stop). Expand step 3 into per-task and cross-task forums. Move the verbose sample-output/artifacts/DB-check block into a collapsible details block. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XvzJBrjK196FnT8cG3hVFf
Enable pymdownx.details (collapsible blocks); promote Getting started to a single nav link and move Contributing to its own top-level entry. Render the landing tagline emphasis with <strong> (raw HTML block didn't process **). Drop 'benchmark' from the KSI definition and remove the --improvement-strategy FAQ. Remove the TB2 Verifier Trust Boundary (architecture) and Removed compatibility flags (experiments) sections. Pin the header title to the site name so it doesn't swap to the section on scroll. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XvzJBrjK196FnT8cG3hVFf
…n guides - CONTRIBUTING: cd ksi -> cd KSI (clone creates KSI/, errors on case-sensitive FS) - CONTRIBUTING/extending: brand product name as KSI in prose/headings (code/import/path references to `ksi` left unchanged) - improvement_strategies: behaviour -> behavior for spelling consistency Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improvements to the first-time-user experience, grounded in friction hit while following the getting-started docs end to end.
Code fixes
MODEL_PROVIDER/MODEL. It now shows the specificProviderConfigErrorper profile (e.g..env.openai: Missing MODEL_PROVIDER).REASONING_EFFORTis validated at profile load — an invalid value (e.g.minimal) previously 400'd every agent/forum/distill call with the error buried in the runtime sidecar DB. It's now rejected up front against{none, low, medium, high, xhigh}.quickstart.shhonorsTASKS_PATH— it was a hardcoded assignment whilePROFILE/EXPERIMENT_NAMEwere overridable, soTASKS_PATH=... bash scripts/quickstart.shsilently ran the bundled demo. Now${TASKS_PATH:-...}and documented.New tests cover the doctor reason surfacing and the reasoning-effort validation.
Docs
pymdownx.details; promoted Getting started to a single link and moved Contributing to its own top-level entry (was nested under Getting started).<strong>(the raw-HTML block wasn't processing bold markdown).--improvement-strategyQ and A.Verification
uv run pyteston the affected suites (providers, doctor, cli, distill): 232 passeduv run ruff checkon changed Python: cleanmkdocs build --strict: clean🤖 Generated with Claude Code
https://claude.ai/code/session_01XvzJBrjK196FnT8cG3hVFf