✨ feat(cli): add --tag filtering and metadata to list-command-examples

- Add --tag flag for filtering catalog by fixture category
- Add tags and summary fields to manifest entries
- Enforce non-empty tags and summary at parse time
- Update docs to describe new filtering and metadata

Author: cocosip

README.md

@@ -85,7 +85,7 @@ They are not MCP tools and are not the normal end-user interaction path.
 - `codex-mem audit-follow-imports [--target-profile all|artifacts|state|retry|health] [...]`
   Reports the same hygiene targets without deleting them. `--target-profile` can enable common audit target sets before you add path, age, fail-if-matched, or `--summary-only` controls.
 - `codex-mem list-command-examples`
-  Prints the embedded import/follow example-manifest catalog shipped with the binary so operators and maintainers can discover the checked-in sample outputs without browsing the source tree. Add `--json` for a machine-readable catalog, `--command <name>` to filter to one command family, or `--format text|json` to keep only one example-output format.
+  Prints the embedded import/follow example-manifest catalog shipped with the binary so operators and maintainers can discover the checked-in sample outputs without browsing the source tree. Catalog entries now carry stable `tags` plus a short summary. Add `--json` for a machine-readable catalog, `--command <name>` to filter to one command family, `--format text|json` to keep only one example-output format, or `--tag <name>` to browse one fixture category such as `audit-only` or `target-profile`.
 - `codex-mem migrate`
   Opens the configured SQLite database and applies embedded migrations.
 - `codex-mem serve`

docs/go/maintainer/dev-kickoff.md

@@ -58,6 +58,7 @@ Current standing decisions worth preserving:
 - configuration loading uses `viper`
 - SQLite uses `modernc.org/sqlite`
 - `modelcontextprotocol/go-sdk` is the only MCP runtime path
+- do not point `GOCACHE` into the repository workspace; if a cache override is needed for local verification, use a temp directory outside the project tree
 
 ## Recommended Next Coding Slice
 

docs/go/maintainer/development-tracker.md

@@ -151,6 +151,34 @@ Immediate next tasks:
 
 ### 2026-03-18 Session Update
 
+- Completed: Tightened command-example manifest parsing so each entry must now carry non-empty `tags` and `summary` metadata, not just the required command/name/format/path fields. Parser coverage now explicitly rejects missing metadata alongside malformed or empty tag lists, so the embedded example catalog contract is enforced at parse time instead of only by higher-level tests.
+- In progress: none.
+- Blockers: none.
+- Next step: keep this operator-catalog line focused on correctness and low-maintenance guarantees unless a clearly necessary usability gap shows up.
+
+### 2026-03-18 Session Update
+
+- Completed: Hardened the embedded command-example catalog tests so every JSON-visible example entry must carry non-empty `tags` and `summary` metadata, and tightened manifest tag parsing to trim whitespace, dedupe repeated tags, and reject empty tag slots in hand-edited `tags=` values.
+- In progress: none.
+- Blockers: none.
+- Next step: keep future operator-catalog changes focused on data quality and maintenance safety unless a clearly useful discovery feature is needed.
+
+### 2026-03-18 Session Update
+
+- Completed: Added `--tag` filtering plus embedded `tags` and `summary` metadata to `list-command-examples`. The manifest now classifies fixtures with stable labels such as `audit-only`, `target-profile`, `filtered`, `dry-run`, and input-shape tags, while also carrying a short human-readable purpose string for each example. Text and JSON output share the same command/format/tag filter pipeline, and sync/runtime coverage verifies the richer manifest format plus tag-based filtering.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether the current tags-plus-summary catalog is enough, or whether operators would benefit from one more discovery aid such as sorting or another filter dimension.
+
+### 2026-03-18 Session Update
+
+- Completed: Recorded a maintainer workflow constraint that `GOCACHE` must not point into the repository workspace. If a local cache override is needed for Go verification on this machine, it should use a temporary directory outside the project tree so the working tree does not accumulate cache artifacts.
+- In progress: none.
+- Blockers: none.
+- Next step: continue the current operator-facing extension work without reintroducing repo-local Go cache state.
+
+### 2026-03-18 Session Update
+
 - Completed: Added `--format` filtering to `list-command-examples`, including repeated and comma-separated format selectors. Text and JSON output now share the same embedded-manifest filtering path across command and format filters, runtime coverage verifies mixed command+format filtering plus argument rejection, and operator docs now show how to browse only text or JSON fixtures.
 - In progress: none.
 - Blockers: none.

docs/go/operator/import-ingestion.md

@@ -342,6 +342,15 @@ If you only want one output format while browsing the catalog, filter it the sam
 codex-mem.exe list-command-examples --format json
 ```
 
+Each catalog row now also includes stable tags plus a short summary so you can tell similar fixtures apart without opening the files first.
+
+If you only want one fixture category, use tags from the embedded catalog metadata:
+
+```powershell
+codex-mem.exe list-command-examples --tag audit-only
+codex-mem.exe list-command-examples --tag target-profile --format json
+```
+
 If a deliberate output change makes those fixtures drift, refresh the ingest fixtures from the repository root through the test-only maintainer helper:
 
 ```powershell

internal/app/command_example_manifest.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"path"
 	"slices"
+	"strconv"
 	"strings"
 
 	_ "embed"
@@ -21,13 +22,16 @@ type listCommandExamplesOptions struct {
 	JSON     bool
 	Commands []string
 	Formats  []string
+	Tags     []string
 }
 
 type commandExampleManifestEntry struct {
 	Command      string `json:"command"`
 	Name         string `json:"name"`
 	RelativePath string `json:"path"`
 	Format       string `json:"format"`
+	Tags         []string `json:"tags,omitempty"`
+	Summary      string   `json:"summary,omitempty"`
 }
 
 type commandExampleManifestReport struct {
@@ -65,6 +69,16 @@ func parseListCommandExamplesOptions(args []string) (listCommandExamplesOptions,
 				return listCommandExamplesOptions{}, err
 			}
 			options.Formats = appendUniqueStrings(options.Formats, values...)
+		case "--tag":
+			index++
+			if index >= len(args) {
+				return listCommandExamplesOptions{}, fmt.Errorf("list-command-examples --tag requires a value")
+			}
+			values, err := parseListCommandExampleTags(args[index])
+			if err != nil {
+				return listCommandExamplesOptions{}, err
+			}
+			options.Tags = appendUniqueStrings(options.Tags, values...)
 		default:
 			return listCommandExamplesOptions{}, fmt.Errorf("unknown list-command-examples flag %q", arg)
 		}
@@ -84,6 +98,10 @@ func parseListCommandExampleFormats(raw string) ([]string, error) {
 	return parseListCommandExamplesCSVFlag(raw, "--format", "format")
 }
 
+func parseListCommandExampleTags(raw string) ([]string, error) {
+	return parseListCommandExamplesCSVFlag(raw, "--tag", "tag")
+}
+
 func parseListCommandExamplesCSVFlag(raw string, flag string, label string) ([]string, error) {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
@@ -144,20 +162,40 @@ func parseCommandExampleManifest(raw string) (commandExampleManifestReport, erro
 }
 
 func parseCommandExampleManifestEntry(line string) (commandExampleManifestEntry, error) {
-	fields := strings.Fields(line)
+	fields, err := splitCommandExampleManifestFields(line)
+	if err != nil {
+		return commandExampleManifestEntry{}, err
+	}
 	entry := commandExampleManifestEntry{}
 	for _, field := range fields {
 		key, value, ok := strings.Cut(field, "=")
 		if !ok {
 			return commandExampleManifestEntry{}, fmt.Errorf("invalid command example manifest field %q", field)
 		}
+		if strings.HasPrefix(value, `"`) {
+			unquoted, err := strconv.Unquote(value)
+			if err != nil {
+				return commandExampleManifestEntry{}, fmt.Errorf("invalid quoted command example manifest value %q: %w", value, err)
+			}
+			value = unquoted
+		}
 		switch key {
 		case "command":
 			entry.Command = value
 		case "example":
 			entry.Name = value
 		case "format":
 			entry.Format = value
+		case "tags":
+			if value != "" {
+				tags, err := parseCommandExampleManifestTags(value)
+				if err != nil {
+					return commandExampleManifestEntry{}, err
+				}
+				entry.Tags = appendUniqueStrings(entry.Tags, tags...)
+			}
+		case "summary":
+			entry.Summary = value
 		case "path":
 			entry.RelativePath = value
 		default:
@@ -167,9 +205,67 @@ func parseCommandExampleManifestEntry(line string) (commandExampleManifestEntry,
 	if entry.Command == "" || entry.Name == "" || entry.Format == "" || entry.RelativePath == "" {
 		return commandExampleManifestEntry{}, fmt.Errorf("incomplete command example manifest entry %q", line)
 	}
+	if len(entry.Tags) == 0 {
+		return commandExampleManifestEntry{}, fmt.Errorf("command example manifest entry %q is missing tags", line)
+	}
+	if strings.TrimSpace(entry.Summary) == "" {
+		return commandExampleManifestEntry{}, fmt.Errorf("command example manifest entry %q is missing summary", line)
+	}
 	return entry, nil
 }
 
+func parseCommandExampleManifestTags(raw string) ([]string, error) {
+	parts := strings.Split(raw, ",")
+	tags := make([]string, 0, len(parts))
+	for _, part := range parts {
+		tag := strings.TrimSpace(part)
+		if tag == "" {
+			return nil, fmt.Errorf("invalid command example manifest tags value %q", raw)
+		}
+		tags = appendUniqueStrings(tags, tag)
+	}
+	return tags, nil
+}
+
+func splitCommandExampleManifestFields(line string) ([]string, error) {
+	fields := make([]string, 0, 8)
+	var current strings.Builder
+	inQuotes := false
+	escaped := false
+	for _, r := range line {
+		switch {
+		case inQuotes:
+			current.WriteRune(r)
+			switch {
+			case escaped:
+				escaped = false
+			case r == '\\':
+				escaped = true
+			case r == '"':
+				inQuotes = false
+			}
+		case r == '"':
+			inQuotes = true
+			current.WriteRune(r)
+		case r == ' ' || r == '\t':
+			if current.Len() == 0 {
+				continue
+			}
+			fields = append(fields, current.String())
+			current.Reset()
+		default:
+			current.WriteRune(r)
+		}
+	}
+	if inQuotes {
+		return nil, fmt.Errorf("unterminated quoted command example manifest field in %q", line)
+	}
+	if current.Len() > 0 {
+		fields = append(fields, current.String())
+	}
+	return fields, nil
+}
+
 func formatCommandExampleManifestJSON(report commandExampleManifestReport) (string, error) {
 	return marshalIndented(report)
 }
@@ -179,10 +275,12 @@ func formatCommandExampleManifest(report commandExampleManifestReport) string {
 	lines = append(lines, "command example manifest "+report.Version)
 	for _, entry := range report.Examples {
 		lines = append(lines, fmt.Sprintf(
-			"command=%s example=%s format=%s path=%s",
+			"command=%s example=%s format=%s tags=%s summary=%s path=%s",
 			entry.Command,
 			entry.Name,
 			entry.Format,
+			strings.Join(entry.Tags, ","),
+			strconv.Quote(entry.Summary),
 			entry.RelativePath,
 		))
 	}
@@ -206,13 +304,15 @@ func commandExampleManifestEntriesForReport(entries []commandExampleManifestEntr
 			Name:         entry.Name,
 			RelativePath: path.Join(commandExampleDirName, entry.RelativePath),
 			Format:       entry.Format,
+			Tags:         slices.Clone(entry.Tags),
+			Summary:      entry.Summary,
 		})
 	}
 	return reportEntries
 }
 
-func filterCommandExampleManifestReport(report commandExampleManifestReport, commands []string, formats []string) (commandExampleManifestReport, error) {
-	if len(commands) == 0 && len(formats) == 0 {
+func filterCommandExampleManifestReport(report commandExampleManifestReport, commands []string, formats []string, tags []string) (commandExampleManifestReport, error) {
+	if len(commands) == 0 && len(formats) == 0 && len(tags) == 0 {
 		return report, nil
 	}
 
@@ -224,13 +324,21 @@ func filterCommandExampleManifestReport(report commandExampleManifestReport, com
 	for _, format := range formats {
 		allowedFormats[strings.TrimSpace(format)] = struct{}{}
 	}
+	allowedTags := make(map[string]struct{}, len(tags))
+	for _, tag := range tags {
+		allowedTags[strings.TrimSpace(tag)] = struct{}{}
+	}
 
 	seenCommands := make(map[string]struct{}, len(report.Examples))
 	seenFormats := make(map[string]struct{}, len(report.Examples))
+	seenTags := make(map[string]struct{}, len(report.Examples))
 	filtered := make([]commandExampleManifestEntry, 0, len(report.Examples))
 	for _, entry := range report.Examples {
 		seenCommands[entry.Command] = struct{}{}
 		seenFormats[entry.Format] = struct{}{}
+		for _, tag := range entry.Tags {
+			seenTags[tag] = struct{}{}
+		}
 		if len(allowedCommands) > 0 {
 			if _, ok := allowedCommands[entry.Command]; !ok {
 				continue
@@ -241,6 +349,18 @@ func filterCommandExampleManifestReport(report commandExampleManifestReport, com
 				continue
 			}
 		}
+		if len(allowedTags) > 0 {
+			matchedTag := false
+			for _, tag := range entry.Tags {
+				if _, ok := allowedTags[tag]; ok {
+					matchedTag = true
+					break
+				}
+			}
+			if !matchedTag {
+				continue
+			}
+		}
 		filtered = append(filtered, entry)
 	}
 
@@ -264,6 +384,16 @@ func filterCommandExampleManifestReport(report commandExampleManifestReport, com
 		return commandExampleManifestReport{}, fmt.Errorf("unknown list-command-examples format filter %q", strings.Join(unknownFormats, ","))
 	}
 
+	unknownTags := make([]string, 0)
+	for _, tag := range tags {
+		if _, ok := seenTags[tag]; !ok && !slices.Contains(unknownTags, tag) {
+			unknownTags = append(unknownTags, tag)
+		}
+	}
+	if len(unknownTags) > 0 {
+		return commandExampleManifestReport{}, fmt.Errorf("unknown list-command-examples tag filter %q", strings.Join(unknownTags, ","))
+	}
+
 	return commandExampleManifestReport{
 		Version:      report.Version,
 		ExampleCount: len(filtered),