feat(logs): NAME-first form + failure triage folded into logs

Rolls the failure-triage story into the existing logs command so
there's no separate DLQ vocabulary to learn.

New forms:
  buttons BUTTONNAME logs                    — past runs (JSON default)
  buttons BUTTONNAME logs --failed           — just failures
  buttons BUTTONNAME logs --limit 10         — how many
  buttons BUTTONNAME logs --follow           — press + stream live (TUI)
  buttons drawer DRAWERNAME logs             — past runs for this drawer
  buttons logs                               — recent failures across
                                               every button + drawer

The verb-first `buttons logs NAME` still works as an alias so
existing scripts don't break. Implementation reuses the package
flag vars so both forms populate the same variables.

NAME-first routing:
- `buttons NAME logs ...` is rewritten to `buttons logs NAME ...`
  in Execute() before Cobra sees it, so Cobra routes to logsCmd
  with all flags parsed correctly.
- `buttons drawer NAME logs` is handled by drawerCmd's existing
  manual NAME-first dispatch; --failed + --limit registered on
  drawerCmd so they parse there too.

Replaces removed DLQ functionality with:
  buttons logs --json          (workspace failures)
  buttons NAME logs --failed   (per-target failures)

No new commands. No new packages. Same agent capability, fewer
verbs to remember.

Updated CLAUDE.md "Stage 2 plumbing" section to describe the
logs-based triage flow. SKILL.md + CLI docs regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bobakemamian

.agents/skills/buttons/SKILL.md

@@ -197,9 +197,14 @@ buttons delete [flags]
 Manage drawer workflows (chains of buttons)
 
 ```
-buttons drawer
+buttons drawer [flags]
 ```
 
+| Flag | Type | Description |
+|------|------|-------------|
+| `--failed` | bool | only return runs that failed (for `NAME logs`) |
+| `--limit` | int | max runs to return (for `NAME logs`) |
+
 ### `buttons history`
 
 Show run history
@@ -234,15 +239,18 @@ buttons list
 
 ### `buttons logs`
 
-Press a button and watch its output stream live
+View a button's past runs, or press and stream live
 
 ```
 buttons logs [flags]
 ```
 
 | Flag | Type | Description |
 |------|------|-------------|
-| `--arg` | stringArray | argument as key=value (repeatable; validated against the button spec) |
+| `--arg` | stringArray | argument as key=value (with --follow, passed through to the press) |
+| `--failed` | bool | only return runs that failed |
+| `-f, --follow` | bool | press the button and stream live output in a TUI |
+| `--limit` | int | max runs to return |
 
 ### `buttons press`
 

cmd/drawer.go

@@ -102,13 +102,22 @@ Usage:
 			return drawerRemove(name)
 		case "summary":
 			return drawerShowSummary(name)
+		case "logs":
+			return drawerLogs(name, vargs)
 		default:
 			return drawerUnknownVerb(name, verb)
 		}
 	},
 }
 
 func init() {
+	// Register the logs flags on drawerCmd as well so
+	// `buttons drawer NAME logs --failed --limit 50` parses. The
+	// flag variables are package-level (declared in cmd/logs.go)
+	// so the drawerLogs handler sees the right values regardless
+	// of which command registered them.
+	drawerCmd.Flags().BoolVar(&logsFailed, "failed", false, "only return runs that failed (for `NAME logs`)")
+	drawerCmd.Flags().IntVar(&logsLimit, "limit", 20, "max runs to return (for `NAME logs`)")
 	rootCmd.AddCommand(drawerCmd)
 }
 
@@ -384,6 +393,49 @@ func drawerSchema() error {
 	return err
 }
 
+// drawerLogs returns past runs for a specific drawer. Shares the
+// same flags as `buttons NAME logs` (--failed, --limit). The TUI
+// live-follow mode isn't wired for drawers in stage 2 — drawers
+// are sequential orchestration and per-button `buttons NAME logs
+// --follow` covers the live-press case at the step level.
+func drawerLogs(name string, vargs []string) error {
+	n := logsLimit
+	if n <= 0 {
+		n = 20
+	}
+	runs, err := drawer.ListRuns(name, n)
+	if err != nil {
+		return handleDrawerError(err)
+	}
+	if logsFailed {
+		kept := runs[:0]
+		for _, r := range runs {
+			if r.Status != "ok" {
+				kept = append(kept, r)
+			}
+		}
+		runs = kept
+	}
+	if jsonOutput {
+		return config.WriteJSON(runs)
+	}
+	if len(runs) == 0 {
+		fmt.Fprintf(os.Stderr, "no runs for drawer %s yet\n", name)
+		return nil
+	}
+	for _, r := range runs {
+		status := r.Status
+		if r.ErrorType != "" {
+			status = r.Status + " · " + r.ErrorType
+		}
+		fmt.Printf("%s  %s  %dms\n", r.StartedAt.Local().Format("2006-01-02 15:04:05"), status, r.DurationMs)
+	}
+	// vargs would be used if we later added step-filters; silence
+	// the unused warning without losing the parameter.
+	_ = vargs
+	return nil
+}
+
 // drawerShowSummary prints the drawer introspection view — topology,
 // inputs, recent runs, validation state. Used by bare
 // `buttons drawer NAME` and by the `--summary` flag on mutations.

cmd/logs.go

@@ -7,49 +7,52 @@ import (
 
 	"github.com/autonoco/buttons/internal/button"
 	"github.com/autonoco/buttons/internal/config"
+	"github.com/autonoco/buttons/internal/drawer"
+	"github.com/autonoco/buttons/internal/history"
 	"github.com/autonoco/buttons/internal/tui"
 )
 
 var logsArgs []string
+var logsFailed bool
+var logsLimit int
+var logsFollow bool
 
 var logsCmd = &cobra.Command{
 	Use:   "logs [name]",
-	Short: "Press a button and watch its output stream live",
-	Long: `Press a button in a full-screen viewer that tails every line of
-stdout / stderr as the child writes it.
-
-The viewer stays open after the press completes so you can scroll
-the output at leisure. Press esc or q to dismiss; ctrl+c cancels an
-in-flight press (the child's process group is killed).
-
-Scope is one press. If the button takes required args, pass them with
---arg key=value the same way 'buttons press' does.
-
-Only shell and code buttons stream today. HTTP and prompt buttons
-still use 'buttons press' for now — their execution is request /
-response, not a long-running process.
-
-Examples:
-  buttons logs deploy
-  buttons logs deploy --arg env=staging
-  buttons logs etl --arg file=/tmp/x.csv`,
-	Args: exactArgs(1),
+	Short: "View a button's past runs, or press and stream live",
+	Long: `View a button's run history. Preferred form is name-first to
+match the rest of the CLI:
+
+  buttons BUTTONNAME logs           — past runs for this button
+  buttons BUTTONNAME logs --follow  — press + stream live
+  buttons BUTTONNAME logs --failed  — just failures
+  buttons drawer DRAWERNAME logs    — past runs for this drawer
+
+The verb-first form (buttons logs NAME) still works as an alias.
+buttons logs (no name) dumps recent failures across every button
+and drawer — same shape as summary.recent_failures.`,
+	Args: cobra.MaximumNArgs(1),
 	RunE: runLogs,
 }
 
 func runLogs(cmd *cobra.Command, args []string) error {
-	if jsonOutput {
-		_ = config.WriteJSONError("NOT_APPLICABLE", "logs is an interactive TUI; --json is not supported")
-		return errSilent
+	// Workspace-level: no name → recent failures across everything.
+	if len(args) == 0 {
+		return logsWorkspaceFailures()
 	}
-	if config.IsNonTTY() {
-		// Piped / CI — the TUI can't render. Tell the user to use
-		// 'buttons press --json' instead of dropping into a broken state.
-		fmt.Fprintln(cmd.ErrOrStderr(), "logs requires a TTY. For programmatic output, use: buttons press --json")
-		return errSilent
+
+	// Per-button: if --follow AND TTY AND not --json, drop into the
+	// live-stream TUI. Otherwise return the structured past-runs
+	// view — this is the agent path and also the default non-TTY
+	// path. Failures live in history, so `buttons NAME logs --failed`
+	// is the triage call.
+	if logsFollow && !jsonOutput && !config.IsNonTTY() {
+		return runLogsTUI(cmd, args[0])
 	}
+	return logsButtonJSON(args[0])
+}
 
-	name := args[0]
+func runLogsTUI(cmd *cobra.Command, name string) error {
 	svc := button.NewService()
 
 	btn, err := svc.Get(name)
@@ -109,7 +112,124 @@ func runtimeLabel(btn *button.Button) string {
 	return btn.Runtime
 }
 
+// logsButtonJSON prints past runs for one button. Honors --failed
+// (filter to non-ok) and --limit (default 20). Used by agents for
+// triage — a single call shows the last N runs with full structured
+// errors, args, and stderr, so drill-in doesn't need a second command.
+func logsButtonJSON(name string) error {
+	n := logsLimit
+	if n <= 0 {
+		n = 20
+	}
+	runs, err := history.List(name, n)
+	if err != nil {
+		return handleServiceError(err)
+	}
+	if logsFailed {
+		kept := runs[:0]
+		for _, r := range runs {
+			if r.Status != "ok" {
+				kept = append(kept, r)
+			}
+		}
+		runs = kept
+	}
+	return config.WriteJSON(runs)
+}
+
+// logsWorkspaceFailures aggregates recent failures across every
+// button + drawer so agents can triage in one tool call. Same bucket
+// that `buttons summary --json` surfaces under recent_failures, but
+// this command is the "show me what broke" direct path.
+func logsWorkspaceFailures() error {
+	n := logsLimit
+	if n <= 0 {
+		n = 20
+	}
+
+	type failure struct {
+		Target     string `json:"target"`
+		RunID      string `json:"run_id,omitempty"`
+		StartedAt  any    `json:"started_at"`
+		Status     string `json:"status"`
+		ExitCode   int    `json:"exit_code,omitempty"`
+		ErrorType  string `json:"error_type,omitempty"`
+		Stderr     string `json:"stderr,omitempty"`
+		FailedStep string `json:"failed_step,omitempty"`
+	}
+
+	out := []failure{}
+
+	// Button runs.
+	allButtonRuns, _ := history.ListAll(n * 4) // overfetch; filter below
+	for _, r := range allButtonRuns {
+		if r.Status == "ok" {
+			continue
+		}
+		out = append(out, failure{
+			Target:    "button/" + r.ButtonName,
+			StartedAt: r.StartedAt,
+			Status:    r.Status,
+			ExitCode:  r.ExitCode,
+			ErrorType: r.ErrorType,
+			Stderr:    truncateForSummary(r.Stderr, 400),
+		})
+		if len(out) >= n {
+			break
+		}
+	}
+
+	// Drawer runs — scan each drawer's history.
+	if len(out) < n {
+		dsvc := drawer.NewService()
+		drawers, _ := dsvc.List()
+		for _, d := range drawers {
+			runs, _ := drawer.ListRuns(d.Name, n)
+			for _, r := range runs {
+				if r.Status == "ok" {
+					continue
+				}
+				out = append(out, failure{
+					Target:     "drawer/" + d.Name,
+					RunID:      r.RunID,
+					StartedAt:  r.StartedAt,
+					Status:     r.Status,
+					ErrorType:  r.ErrorType,
+					FailedStep: lastFailedStep(r),
+				})
+				if len(out) >= n {
+					break
+				}
+			}
+			if len(out) >= n {
+				break
+			}
+		}
+	}
+
+	return config.WriteJSON(out)
+}
+
+func lastFailedStep(r drawer.Run) string {
+	for i := len(r.Steps) - 1; i >= 0; i-- {
+		if r.Steps[i].Status != "ok" {
+			return r.Steps[i].ID
+		}
+	}
+	return ""
+}
+
+func truncateForSummary(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "…"
+}
+
 func init() {
-	logsCmd.Flags().StringArrayVar(&logsArgs, "arg", nil, "argument as key=value (repeatable; validated against the button spec)")
+	logsCmd.Flags().StringArrayVar(&logsArgs, "arg", nil, "argument as key=value (with --follow, passed through to the press)")
+	logsCmd.Flags().BoolVar(&logsFailed, "failed", false, "only return runs that failed")
+	logsCmd.Flags().IntVar(&logsLimit, "limit", 20, "max runs to return")
+	logsCmd.Flags().BoolVarP(&logsFollow, "follow", "f", false, "press the button and stream live output in a TUI")
 	rootCmd.AddCommand(logsCmd)
 }

cmd/root.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/autonoco/buttons/internal/button"
 	"github.com/autonoco/buttons/internal/config"
@@ -35,6 +36,15 @@ var rootCmd = &cobra.Command{
 		return config.EnsureDataDir()
 	},
 	RunE: func(cmd *cobra.Command, args []string) error {
+		// NAME-first verb form matching `buttons drawer NAME add/...`
+		//
+		//   buttons BUTTONNAME logs [--follow] [--failed] [--limit N]
+		//
+		// Routes through the existing logs command so every flag
+		// keeps working.
+		if len(args) >= 2 && args[1] == "logs" {
+			return runLogs(cmd, []string{args[0]})
+		}
 		// If a positional arg was passed and it isn't a subcommand,
 		// fall back to per-button detail — preserves existing
 		// `buttons <name>` shorthand.
@@ -51,6 +61,26 @@ var rootCmd = &cobra.Command{
 func Root() *cobra.Command { return rootCmd }
 
 func Execute() {
+	// NAME-first rewriting. Cobra routes by subcommand name in arg
+	// position 1, so `buttons BUTTONNAME logs ...` doesn't reach
+	// logsCmd naturally. We rewrite it to `buttons logs BUTTONNAME
+	// ...` before Cobra sees it. Same pattern intentionally NOT
+	// applied to `buttons drawer NAME logs` because drawerCmd
+	// already does its own NAME-first dispatch internally.
+	if len(os.Args) >= 3 && os.Args[2] == "logs" && !strings.HasPrefix(os.Args[1], "-") {
+		switch os.Args[1] {
+		case "drawer", "create", "press", "list", "delete", "rm", "remove",
+			"batteries", "board", "config", "history", "init", "logs",
+			"smash", "store", "summary", "tail", "update", "version":
+			// Already a subcommand; don't rewrite.
+		default:
+			rewritten := make([]string, 0, len(os.Args))
+			rewritten = append(rewritten, os.Args[0], "logs", os.Args[1])
+			rewritten = append(rewritten, os.Args[3:]...)
+			os.Args = rewritten
+		}
+	}
+
 	if err := rootCmd.Execute(); err != nil {
 		if !errors.Is(err, errSilent) {
 			fmt.Fprintln(os.Stderr, err)

docs/cli/buttons.md

@@ -35,7 +35,7 @@ buttons [flags]
 * [buttons history](buttons_history.md)	 - Show run history
 * [buttons init](buttons_init.md)	 - Initialize a project-local .buttons directory
 * [buttons list](buttons_list.md)	 - List all buttons
-* [buttons logs](buttons_logs.md)	 - Press a button and watch its output stream live
+* [buttons logs](buttons_logs.md)	 - View a button's past runs, or press and stream live
 * [buttons press](buttons_press.md)	 - Run a button
 * [buttons smash](buttons_smash.md)	 - Run multiple buttons in parallel
 * [buttons store](buttons_store.md)	 - Marketplace (search/install/import/publish)

docs/cli/buttons_drawer.md

@@ -30,7 +30,9 @@ buttons drawer [flags]
 ### Options
 
 ```
-  -h, --help   help for drawer
+      --failed NAME logs   only return runs that failed (for NAME logs)
+  -h, --help               help for drawer
+      --limit NAME logs    max runs to return (for NAME logs) (default 20)
 ```
 
 ### Options inherited from parent commands