go-api-empty-state-ux

Answer

Root cause: the memory tree/index handlers did os.Stat(memoryDir) and treated any failure — including fs.ErrNotExist — as a routing failure, returning a bare 404 with zero guidance. A fresh workspace is a normal, recoverable state (the user hasn't run hivemind init), not a missing route. The CLI then had nothing to read, so it could only echo controller returned status 404.

Fix pattern (three parts, applies to any empty-state API gap):

1. API: 404 → 200 + empty result + hint,omitempty. Only fs.ErrNotExist maps to the empty state; genuine failures (permissions, corrupt paths) stay 500.

type MemoryIndexResponse struct {
    Entries []MemoryEntry `json:"entries"`
    Hint    string        `json:"hint,omitempty"` // absent on wire when empty
}

func (h *Handler) serveIndex(w http.ResponseWriter, r *http.Request, recursive bool) {
    dir := h.memoryDir()
    info, err := os.Stat(dir)
    switch {
    case errors.Is(err, fs.ErrNotExist):
        // Empty state: 200 + empty result + actionable hint — NOT 404.
        writeJSON(w, http.StatusOK, MemoryIndexResponse{
            Entries: []MemoryEntry{}, // non-nil → JSON "[]", never "null"
            Hint: fmt.Sprintf("no memory tree found at %q — this workspace was created but not initialized. "+
                "Run %q to scaffold the memory tree, then retry.", dir, h.initCmd()),
        })
        return
    case err != nil:
        writeJSON(w, http.StatusInternalServerError, ErrorResponse{Error: err.Error()})
        return
    case !info.IsDir():
        writeJSON(w, http.StatusInternalServerError, ErrorResponse{Error: "memory path is not a directory"})
        return
    }
    writeJSON(w, http.StatusOK, MemoryIndexResponse{Entries: entries}) // no hint
}

Two subtle traps the tests caught: loadEntries must start with entries := []MemoryEntry{} (not var entries []MemoryEntry) so an initialized-but-empty tree also emits []; and the hint,omitempty tag guarantees populated payloads stay byte-identical to the pre-fix format, so old clients are unaffected.

2. CLI: decode the body, route hint → stderr, data → stdout. Never stop at the status code.

body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
var m memoryResponse
_ = json.Unmarshal(body, &m) // tolerate non-JSON error bodies

if m.Hint != "" {
    fmt.Fprintln(cfg.stderr, "hivemind: "+m.Hint) // guidance off the data channel
}
if resp.StatusCode < 200 || resp.StatusCode > 299 {
    return fmt.Errorf("server returned %s", resp.Status) // still non-zero for scripts
}
m.Hint = "" // stderr-only; never serialize into stdout data
json.NewEncoder(cfg.stdout).Encode(m)

This also degrades gracefully against a half-upgraded fleet: if a legacy server returns 404 with a hint, the hint still reaches stderr and the exit code stays non-zero (automation fails loudly, humans get guidance).

3. Docs: workspace create ≠ init.

```markdown