Phase 4: Agent context, doctor command, CLAUDE.md, README by padak · Pull Request #5 · keboola/cli

padak · 2026-02-26T12:21:20Z

Summary

Comprehensive kbagent context with agent instructions, examples, workflows, exit codes, and environment variables
Full kbagent doctor with 4 health checks (config file existence/permissions, JSON validity, per-project API connectivity with response time, CLI version)
CLAUDE.md with build/run/test instructions, project structure overview, and coding conventions
README.md with full documentation: installation, quick start, all commands, JSON format, exit codes, architecture

Implementation Details

`commands/context.py`

Outputs curated text block useful for any AI agent (Claude, Codex, Gemini)
All commands with copy-pasteable examples
Tips section: always use --json, how to parse output, common workflows
Exit codes table and environment variables reference
JSON mode returns structured data with version and context text

`commands/doctor.py`

Check 1: Config file exists at expected path with correct permissions (0600)
Check 2: Config file is valid JSON and parseable into AppConfig
Check 3: For each configured project, verify token via API call with response time measurement
Check 4: CLI version information
Rich panel output with colored PASS/FAIL/WARN/SKIP indicators
JSON mode returns structured checks array with summary statistics

`CLAUDE.md`

Build: uv pip install -e ".[dev]"
Run: kbagent --help / uv run kbagent --help
Test: uv run pytest tests/ -v
Project structure, 3-layer architecture, coding conventions

`README.md`

Installation, quick start, all commands documented with examples
JSON output format, exit codes, environment variables
Configuration file location and format
Architecture overview

Tests Added (22 new tests)

TestContext (5 tests): key phrases, JSON output, all commands mentioned, exit codes, workflows
TestDoctor (8 tests): no config file, valid config, JSON structure, human output, connectivity mock success/failure, version check, invalid JSON config
TestNoColor (3 tests): flag accepted, works with project list, works with doctor
TestExitCodes (6 tests): auth error (3), network error (4), config error (5) across project and config commands

Acceptance Criteria

🤖 Generated with Claude Code

- Replace context.py stub with comprehensive agent instructions including all commands with copy-pasteable examples, tips for AI agents, common workflows, exit codes table, and environment variables - Replace doctor.py stub with full health check: config file existence and permissions (0600), config JSON validity, per-project API connectivity with response time, and CLI version - Create CLAUDE.md with build/run/test instructions, project structure, and coding conventions - Replace minimal README.md with full documentation: installation, quick start, all commands, JSON output format, exit codes, architecture - Add 22 new tests: context output (5), doctor checks (8), --no-color flag (3), exit codes (6) - All 173 tests pass Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ss tracker Lays the documentation foundation for the Agent Studio Phase 1 effort: - docs/agents-v2.md — Playbook-first PRD that supersedes the heavyweight Team/Role/WorkItem v1. Closes every blocking finding from docs/agents-review.md: budget caps in MVP, scoped per-run JWTs, stable API contract, body_hash + 5s undo on external_send, untrusted-content wrapping, expires_at + scope on approvals. - docs/agent-studio-design-system.md — canonical NERD UI spec, single source of truth for visual contract. Light mode primary, dark secondary. Reference implementation runs at http://127.0.0.1:8001/ via `kbagent serve --ui`. - docs/mockups/ — 6 light primary screens (conditioning approach via Playwright reference + nano-banana edit mode) + 6 dark secondary backups. README documents the regen workflow. - docs/agent-studio-progress.md — persistent cross-session tracker for the Phase 1 build. New chat sessions can pick up from this file. Customer-validated workflow (product-cost-allocation Solution) drove five v2 updates: - §9.3 xlsx-renderer added to first-party tools - §18 6th Solution product-cost-allocation (Finance Ops) with full spec - §21 Phase 2 promoted basic view scoping (created_by + allowed_users) - §21 Phase 1 acceptance criterion now includes the controller-handoff scenario - §24 Open Q #5 split (view scoping = Phase 2 done, approval routing still Phase 5+) - §26 Appendix E "Deployment Patterns" added (local / single-server shared-team / future SaaS)

…, dedup Thermo-nuclear review follow-ups (behavior-preserving): - #1/#6: move inline nfpm loop -> build/package/linux/build_packages.sh and the zip+sha256 -> build/package/zip_binary.sh (explicit per-OS archiver); workflow is now pure orchestration. - #2: .github/actions/setup-build composite (uv + optional Node) replaces the repeated setup preamble in pypi/freeze. - #3: index.sh deb/rpm/apk collapsed into a publish_repo() helper + per-format indexers. - #5: sign.sh parses the Azure token with jq instead of a sed regex. - #7: nfpm.yaml notes it's rendered via envsubst. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The big one (#2, upgraded): the diff sides' wire shape was WRONG in the implementation and in the test fixtures that defined it. Verified against connection (ConfigurationVersionResponse + ConfigurationDiffData OA schemas, now recorded in the notes wire-truth table): each side is {version, isDeleted, diff: {name, description, changeDescription, isDisabled, configuration, rows}} -- content NESTED under diff, version/deletion as side metadata. The classification and both take modes now read the envelope; the flat-side code would have been dead on arrival against the live API. #1: resolve_conflict no longer takes branch_id -- it derives the branch from the MR itself (branches.branchFromId), so the conflict-set guard and the branch being written to can never disagree; a caller-supplied id could point the REPLACing rebase at an unrelated dev branch the guard never checked. A published/canceled MR (null branchFromId) is refused readably. #3: take=theirs of a deleted side collapses to the delete resolution, symmetric with ours ('production deleted it, dev changed it' is a live conflict shape). #4: deletion surfaces as top-level ours_deleted/theirs_deleted booleans on get_config_diff (None = side never existed) -- it is side metadata, not a content path. #5: a 'both' row where the sides agree on the identical value carries agreed: true -- agreement, not a conflict hotspot. #2 (message half): a take side missing required envelope keys is reported as a backend contract violation pointing at the resolved-body workaround, not as caller error. #6: wire ids compared via _same_id / int-coerced (find_merge_request_for_ branch, merge()'s was_active) -- a string-serialized branchFromId can no longer silently defeat the post-merge cleanup. #7: the feature pre-flight raises FeatureNotEnabledError carrying the new ErrorCode.FEATURE_NOT_ENABLED (value matches the string SearchService already emits; categorized 'configuration' like PAYG_NOT_AVAILABLE). #8: ConfigError imported from ..errors like every other service; the isDefault scan hoisted to services.base.find_default_branch_id and the copies in config/sync/workspace services migrated (lib.py keeps its own loop -- the SDK facade does not import the services layer); verify_token is skipped when the server already serialized viewer (the polyfill's cost dies with the polyfill); list --state validates against the closed vocabulary instead of returning a silent count: 0 on a typo. #9: test imports hoisted (no mid-file noqa), mocks spec'd at the L3 seam (KeboolaClient + MergeRequests -- a renamed L3 method now fails the tests), and regression tests added for every finding (82 tests total). Doc drift: layer2/layer3 references updated to BRANCHES_MERGE_REQUESTS_ FEATURE, the layer3 open nit closed, tokens.py line ref fixed. Review: tasks/pr-703-review.md (2026-08-27). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

padak merged commit 5248439 into main Feb 26, 2026

padak deleted the phase-4-context-doctor branch March 2, 2026 23:05

padak mentioned this pull request Apr 10, 2026

feat: add storage create-bucket, create-table, upload-table #100

Merged

ottomansky mentioned this pull request May 3, 2026

feat(0.28.0): manage-token default-deny — env var ignored without --allow-env-manage-token #239

Closed

8 tasks

ottomansky mentioned this pull request Jun 3, 2026

feat(semantic-layer): add reference-data commands (Chart of Accounts in the metastore) #379

Merged

padak mentioned this pull request Aug 23, 2026

serve: expose auth register-projects over REST (POST /auth/register-projects) #677

Merged

Navigation Menu

Uh oh!

Phase 4: Agent context, doctor command, CLAUDE.md, README - #5

Phase 4: Agent context, doctor command, CLAUDE.md, README#5
padak merged 1 commit into
mainfrom
phase-4-context-doctor

padak commented Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

padak commented Feb 26, 2026

Summary

Implementation Details

commands/context.py

commands/doctor.py

CLAUDE.md

README.md

Tests Added (22 new tests)

Acceptance Criteria

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

`commands/context.py`

`commands/doctor.py`

`CLAUDE.md`

`README.md`