Expand CLI automation and maintenance workflows

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Install package
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e ".[dev]"
+          python -m pip install -e ".[dev,openai]"
 
       - name: Run tests
         run: python -m pytest

README.md

@@ -410,9 +410,9 @@ Run the current CLI:
 chulk
 ```
 
-The interactive CLI always uses a Hulk-green terminal theme. During interactive turns, Chulk prints compact live progress lines such as memory search, skill selection, model requests, tool calls, command previews, elapsed time, and turn completion. Real terminals also show a small ASCII spinner while the model or a tool is working. Arrow up/down navigates prompt history for the active session when terminal `readline` support is available. The input prompt is intentionally short (`>`) so the transcript does not repeat a heavy label on every line. `chulk --once` remains plain output for scripting.
+The interactive CLI uses color only for a real TTY and honors `NO_COLOR`; use `--color auto|always|never` to override detection. The default `compact` display keeps routine memory, skill, and model bookkeeping out of the transcript while preserving tool calls, permissions, plans, failures, and a one-line end-of-turn summary. `/display verbose` exposes all trace-driven progress and the detailed summary, while `/display quiet` prints only assistant responses and necessary prompts.
 
-At the end of each turn, Chulk prints a compact summary with total time, model request count, tools used, selected memory count, selected skills, context estimate, and the trace path. Use `/context` to inspect the latest prompt section breakdown, `/quiet on` to hide live progress, `/verbose on` to include trace-event names in progress lines, and `/summary off` to hide the summary block.
+Real terminals show a small ASCII spinner while the model or a tool is working. Arrow up/down navigates the active session's prompt history, and Tab completes registered slash commands when terminal `readline` support is available. Unknown slash commands are rejected locally with a suggestion instead of being sent to the model. The prompt remains intentionally short (`>`).
 
 Useful interactive commands:
 
@@ -429,24 +429,56 @@ Useful interactive commands:
 - `/plan`
 - `/approve`
 - `/reject`
-- `/quiet on|off`
-- `/verbose on|off`
-- `/summary on|off`
+- `/display compact|verbose|quiet`
 - `/clear`
-- `/q`
+- `/exit` (`/quit` and `/q` are aliases)
 
-Send a single message and exit:
+Start directly in a persisted conversation:
 
 ```bash
-chulk --once "Hello"
+chulk --resume <conversation_id>
+chulk --continue
 ```
 
+Fresh interactive sessions are persisted only after their first turn, so opening Chulk and immediately exiting does not create an empty conversation or trace.
+
+Run a non-interactive request. Diagnostics go to stderr and stdout contains only the result:
+
+```bash
+chulk exec "Hello"
+chulk exec "Inspect this repository" --json
+```
+
+`chulk --once "Hello"` remains a compatibility alias for plain `chulk exec`. Non-interactive runs deny approval-gated tools instead of waiting for terminal input. Exit code `0` means success, `1` a runtime/provider failure, `2` a configuration or usage failure, and `3` that interactive approval was required.
+
 Inspect local configuration:
 
 ```bash
 chulk --show-config
 ```
 
+Initialize and diagnose a project without making a model request:
+
+```bash
+chulk init --coding-agent
+chulk init --sdk
+chulk init --read-only
+chulk doctor
+chulk doctor --json
+```
+
+`chulk init` creates missing `.chulk/mcp.json`, `.chulk/skills/`, and `.env.example` files and adds runtime paths to `.gitignore`; it does not replace existing files. `chulk doctor` validates configuration, provider credentials, model metadata, runtime writability, MCP auth, and Git ignore coverage without contacting the provider.
+
+Inspect or export a trace without starting an agent:
+
+```bash
+chulk trace inspect traces/<conversation_id>.jsonl
+chulk trace inspect traces/<conversation_id>.jsonl --json
+chulk trace export traces/<conversation_id>.jsonl --format html
+```
+
+Trace exports contain raw runtime data and should be handled as sensitive artifacts.
+
 Run tests:
 
 ```bash
@@ -475,7 +507,7 @@ chulk
 Run a one-shot message:
 
 ```bash
-chulk --once "Hello"
+chulk exec "Hello"
 ```
 
 Built-in tools currently registered at startup:

TODO.md

@@ -1266,19 +1266,19 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 - [ ] Add fatal safety errors that stop the turn immediately.
 - [ ] Add prompt-injection warnings for web, browser, and external document inputs.
 - [ ] Warn when trace or runtime state is created inside a Git-tracked path.
-- [ ] Make `chulk doctor` detect whether `.chulk/`, `traces/`, `chulk/store.sqlite`, and `*.sqlite` are ignored.
+- [x] Make `chulk doctor` detect whether `.chulk/`, `traces/`, `chulk/store.sqlite`, and `*.sqlite` are ignored.
 
 #### Phase E: Trace Productization
 
 - [ ] Treat traces as a public product surface, not only internal logs.
 - [ ] Add a trace schema version to every JSONL event.
 - [ ] Standardize trace event envelope fields: schema version, event/type, conversation id, turn id, timestamp, and payload.
-- [ ] Add a public trace reader: `Trace.from_jsonl(path)`.
-- [ ] Expose typed trace events with event type and timestamp.
-- [ ] Add `chulk trace inspect <path>`.
-- [ ] Add `chulk trace export <path> --format html`.
+- [x] Add a public trace reader: `Trace.from_jsonl(path)`.
+- [x] Expose typed trace events with event type and timestamp.
+- [x] Add `chulk trace inspect <path>`.
+- [x] Add `chulk trace export <path> --format html`.
 - [ ] Add `chulk trace replay <path>`.
-- [ ] Add a minimal HTML trace export.
+- [x] Add a minimal HTML trace export.
 - [ ] Include user request, prompt context, loaded memories, loaded skills, tool calls, tool outputs, permission decisions, final answer, errors, token usage, and cost usage in trace exports.
 - [ ] Log available tools in traces.
 - [ ] Log timing information in traces.
@@ -1310,10 +1310,10 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 - [ ] Add provider capability API exposed publicly as `agent.provider.capabilities` or equivalent.
 - [ ] Add provider health checks.
 - [ ] Add invalid-model diagnostics for missing API keys, bad model names, unavailable endpoints, and unsupported tool schemas.
-- [ ] Add `chulk doctor`.
-- [ ] Add `chulk init`.
-- [ ] Add `chulk init --sdk`, `--coding-agent`, and `--read-only`.
-- [ ] Make `chulk init` create `.chulk/mcp.json`, `.chulk/skills/`, `.env.example`, and update `.gitignore`.
+- [x] Add `chulk doctor`.
+- [x] Add `chulk init`.
+- [x] Add `chulk init --sdk`, `--coding-agent`, and `--read-only`.
+- [x] Make `chulk init` create `.chulk/mcp.json`, `.chulk/skills/`, `.env.example`, and update `.gitignore`.
 - [ ] Split docs by audience under `docs/`: index, quickstart, sdk, cli, tools, permissions, skills, memory, tracing, providers, mcp, safety, and release policy.
 - [ ] Add one end-to-end `examples/repo_review_bot/` killer example.
 - [ ] Include a sample trace export in the repo review example.
@@ -1489,8 +1489,8 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 
 ### Interfaces And Product Surfaces
 
-- [ ] Add non-interactive `chulk exec` for scripts and CI.
-- [ ] Add JSON output mode for automation.
+- [x] Add non-interactive `chulk exec` for scripts and CI.
+- [x] Add JSON output mode for automation.
 - [ ] Add richer Python SDK around `AgentHandle`.
 - [ ] Add JSON-RPC app server.
 - [ ] Add WebSocket event streaming.
@@ -1595,7 +1595,7 @@ Feedback from the SDK/installability review changes the near-term priority. Befo
 - [ ] Add golden tests for tool-use loops.
 - [ ] Add safety red-team prompts.
 - [ ] Add prompt-performance dashboards.
-- [ ] Add `chulk doctor` diagnostics.
+- [x] Add `chulk doctor` diagnostics.
 - [ ] Add config validation command.
 - [ ] Add tool inventory drift checks.
 - [ ] Add release-readiness checklist command.

chulk/cli/__init__.py

@@ -1,17 +1,27 @@
 """Terminal UI helpers for the ChulkHarness CLI."""
 
-from chulk.cli.commands import CLICommandContext, EXIT_COMMANDS, handle_cli_command
+from chulk.cli.commands import (
+    CLI_COMMANDS,
+    CLICommand,
+    CLICommandContext,
+    EXIT_COMMANDS,
+    command_completion_candidates,
+    handle_cli_command,
+)
 from chulk.cli.history import PromptHistory
 from chulk.cli.progress import ProgressReporter, ProgressSettings, Spinner
 from chulk.cli.terminal import TerminalUI
 
 __all__ = [
+    "CLICommand",
     "CLICommandContext",
+    "CLI_COMMANDS",
     "EXIT_COMMANDS",
     "PromptHistory",
     "ProgressReporter",
     "ProgressSettings",
     "Spinner",
     "TerminalUI",
+    "command_completion_candidates",
     "handle_cli_command",
 ]