diff --git a/CHANGELOG.md b/CHANGELOG.md
index f5cbc7eaa..ce9b3cb8d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.18.10] - 2026-04-24
+
+### Added
+
+- **`interfaces.Troubleshooter`** optional interface on `ResourceDriver`. Drivers implementing it
+ return structured `[]Diagnostic` (phase, cause, timestamp, log-tail detail) that wfctl renders
+ in CI output on deploy/apply failure. No changes required for drivers that don't implement it;
+ `codes.Unimplemented` is swallowed silently.
+- **`cmd/wfctl/ci_output.go`**: CI-provider detection (GitHub Actions, GitLab CI, Jenkins, CircleCI)
+ with grouped output via provider-native markers (`::group::`, `section_start`, dashed separators).
+- **`cmd/wfctl/ci_output_summary.go`**: Markdown step-summary writer for
+ `$GITHUB_STEP_SUMMARY` (and equivalents) with resource, root cause, phase timings,
+ and collapsible per-diagnostic log tails.
+
+### Changed
+
+- `wfctl ci run --phase deploy` and `wfctl infra apply` automatically invoke
+ `Troubleshooter.Troubleshoot` on any terminal failure (health-check timeout or driver
+ error), render diagnostics, and write the step-summary. Original exit codes and error
+ messages are preserved (observability is additive).
+
+### Not yet
+
+- Generic `IaCProvider.StreamLogs` for real-time log display during builds — deferred to
+ v0.19.0 alongside plugin-manifest split (#42) and provider-agnostic CI summary (#63).
+- AWS, GCP, Azure, tofu Troubleshoot implementations — DO only in v0.7.8; others no-op.
+
## [0.18.9] - 2026-04-24
### Fixed
diff --git a/cmd/wfctl/ci_output.go b/cmd/wfctl/ci_output.go
new file mode 100644
index 000000000..513dc7bd2
--- /dev/null
+++ b/cmd/wfctl/ci_output.go
@@ -0,0 +1,86 @@
+package main
+
+import (
+ "fmt"
+ "io"
+ "os"
+ "time"
+)
+
+// CIGroupEmitter wraps output with CI-provider-specific group markers so
+// long outputs (like diagnostics) render as collapsible sections in the UI.
+type CIGroupEmitter interface {
+ GroupStart(w io.Writer, name string)
+ GroupEnd(w io.Writer)
+ // SummaryPath returns the path to append Markdown summary content, or
+ // "" if this CI provider has no step-summary concept.
+ SummaryPath() string
+}
+
+// detectCIProvider inspects env vars and returns the appropriate emitter.
+func detectCIProvider() CIGroupEmitter {
+ switch {
+ case os.Getenv("GITHUB_ACTIONS") == "true":
+ return githubEmitter{summaryPath: os.Getenv("GITHUB_STEP_SUMMARY")}
+ case os.Getenv("GITLAB_CI") == "true":
+ return &gitlabEmitter{}
+ case os.Getenv("JENKINS_HOME") != "":
+ return jenkinsEmitter{}
+ case os.Getenv("CIRCLECI") == "true":
+ return circleCIEmitter{}
+ default:
+ return plainEmitter{}
+ }
+}
+
+// --- GitHub Actions ---
+
+type githubEmitter struct{ summaryPath string }
+
+func (g githubEmitter) GroupStart(w io.Writer, name string) {
+ fmt.Fprintf(w, "::group::%s\n", name)
+}
+func (g githubEmitter) GroupEnd(w io.Writer) { fmt.Fprintln(w, "::endgroup::") }
+func (g githubEmitter) SummaryPath() string { return g.summaryPath }
+
+// --- GitLab CI ---
+
+// gitlabEmitter stores the section ID generated in GroupStart so that
+// GroupEnd can emit a matching ID — GitLab requires identical IDs on both
+// markers to close the fold correctly.
+type gitlabEmitter struct {
+ sectionID string
+}
+
+func (g *gitlabEmitter) GroupStart(w io.Writer, name string) {
+ g.sectionID = fmt.Sprintf("wfctl_%d", time.Now().UnixNano())
+ fmt.Fprintf(w, "\x1b[0Ksection_start:%d:%s\r\x1b[0K%s\n", time.Now().Unix(), g.sectionID, name)
+}
+func (g *gitlabEmitter) GroupEnd(w io.Writer) {
+ fmt.Fprintf(w, "\x1b[0Ksection_end:%d:%s\r\x1b[0K\n", time.Now().Unix(), g.sectionID)
+}
+func (g *gitlabEmitter) SummaryPath() string { return "" }
+
+// --- Jenkins ---
+
+type jenkinsEmitter struct{}
+
+func (j jenkinsEmitter) GroupStart(w io.Writer, name string) { fmt.Fprintf(w, "\n--- %s ---\n", name) }
+func (j jenkinsEmitter) GroupEnd(w io.Writer) { fmt.Fprintln(w, "--- end ---") }
+func (j jenkinsEmitter) SummaryPath() string { return "" }
+
+// --- CircleCI ---
+
+type circleCIEmitter struct{}
+
+func (c circleCIEmitter) GroupStart(w io.Writer, name string) { fmt.Fprintf(w, "\n--- %s ---\n", name) }
+func (c circleCIEmitter) GroupEnd(w io.Writer) { fmt.Fprintln(w, "--- end ---") }
+func (c circleCIEmitter) SummaryPath() string { return "" }
+
+// --- Plain (default) ---
+
+type plainEmitter struct{}
+
+func (p plainEmitter) GroupStart(w io.Writer, name string) { fmt.Fprintf(w, "\n--- %s ---\n", name) }
+func (p plainEmitter) GroupEnd(w io.Writer) { fmt.Fprintln(w, "--- end ---") }
+func (p plainEmitter) SummaryPath() string { return "" }
diff --git a/cmd/wfctl/ci_output_summary.go b/cmd/wfctl/ci_output_summary.go
new file mode 100644
index 000000000..ffeae1ffb
--- /dev/null
+++ b/cmd/wfctl/ci_output_summary.go
@@ -0,0 +1,77 @@
+package main
+
+import (
+ "fmt"
+ "io"
+ "os"
+ "strings"
+ "time"
+
+ "github.com/GoCodeAlone/workflow/interfaces"
+)
+
+// SummaryInput is the data bundled into a step-summary Markdown block.
+type SummaryInput struct {
+ Operation string // "deploy" | "apply" | "destroy"
+ Env string // e.g. "staging"
+ Resource string // resource display name
+ Outcome string // "SUCCESS" | "FAILED"
+ ConsoleURL string // direct link to provider dashboard
+ Diagnostics []interfaces.Diagnostic
+ Phases []PhaseTiming
+ RootCause string
+}
+
+// PhaseTiming records the name, status, and duration of a deployment phase.
+type PhaseTiming struct {
+ Name string
+ Status string
+ Duration time.Duration
+}
+
+// WriteStepSummary appends Markdown to the CI provider's summary destination.
+// No-ops when the provider has no summary destination (all non-GHA for now).
+func WriteStepSummary(emitter CIGroupEmitter, in SummaryInput) error {
+ path := emitter.SummaryPath()
+ if path == "" {
+ return nil
+ }
+ f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) //nolint:gosec // summary path comes from GITHUB_STEP_SUMMARY env var, not user input
+ if err != nil {
+ return fmt.Errorf("open summary: %w", err)
+ }
+ defer f.Close()
+ return renderSummary(f, in)
+}
+
+func renderSummary(w io.Writer, in SummaryInput) error {
+ var b strings.Builder
+ fmt.Fprintf(&b, "## wfctl: %s %s — %s\n\n", in.Operation, in.Env, in.Outcome)
+ if in.Resource != "" {
+ fmt.Fprintf(&b, "**Resource:** %s\n", in.Resource)
+ }
+ if in.RootCause != "" {
+ fmt.Fprintf(&b, "**Root cause:** `%s`\n", in.RootCause)
+ }
+ if in.ConsoleURL != "" {
+ fmt.Fprintf(&b, "**Console:** %s\n", in.ConsoleURL)
+ }
+ if len(in.Phases) > 0 {
+ b.WriteString("\n### Phase timings\n\n| Phase | Status | Duration |\n|---|---|---|\n")
+ for _, p := range in.Phases {
+ fmt.Fprintf(&b, "| %s | %s | %s |\n", p.Name, p.Status, p.Duration.Round(time.Second))
+ }
+ }
+ if len(in.Diagnostics) > 0 {
+ b.WriteString("\n### Diagnostics\n\n")
+ for _, d := range in.Diagnostics {
+ fmt.Fprintf(&b, "- **[%s]** `%s` — %s\n", d.Phase, d.ID, d.Cause)
+ if d.Detail != "" {
+ fmt.Fprintf(&b, " log tail
\n\n ```\n %s\n ```\n\n log tail
+
+ ```
+ workflow-migrate up: first .: file does not exist
+ Error: exit status 1
+ ```
+
+ pre_deploy log tail (12 lines)
+
+```
+workflow-migrate up: first .: file does not exist
+Error: exit status 1
+```
+
+log tail
\n\n ```\n %s\n ```\n\n