[object Object]

← back to Cli Printing Press

fix(cli): README title, code block spacing, scorer placeholder fix

6798088627346de81a510cc340445e49a7ec05f0 · 2026-04-02 00:01:00 -0700 · Trevin Chow

1. README title: use humanized API name ("Steam Web CLI") instead of
   binary name ("steam-web-pp-cli"). Added humanName template function
   that replaces hyphens with spaces and title-cases.

2. Code block spacing: blank lines between comment/command pairs in
   Output Formats and Cookbook sections for readability.

3. Scorer: removed "your-key-here" from Quick Start blacklist. Auth
   setup examples like `export API_KEY=your-key-here` are legitimate
   — they show the user how to configure credentials, not unfinished
   boilerplate. Only penalize generic placeholders (abc123, USER/tap).

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

Files touched

Diff

commit 6798088627346de81a510cc340445e49a7ec05f0
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Thu Apr 2 00:01:00 2026 -0700

    fix(cli): README title, code block spacing, scorer placeholder fix
    
    1. README title: use humanized API name ("Steam Web CLI") instead of
       binary name ("steam-web-pp-cli"). Added humanName template function
       that replaces hyphens with spaces and title-cases.
    
    2. Code block spacing: blank lines between comment/command pairs in
       Output Formats and Cookbook sections for readability.
    
    3. Scorer: removed "your-key-here" from Quick Start blacklist. Auth
       setup examples like `export API_KEY=your-key-here` are legitimate
       — they show the user how to configure credentials, not unfinished
       boilerplate. Only penalize generic placeholders (abc123, USER/tap).
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 internal/generator/generator.go             |  6 +++++-
 internal/generator/templates/readme.md.tmpl | 16 +++++++++-------
 internal/pipeline/scorecard.go              |  7 +++++--
 3 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/internal/generator/generator.go b/internal/generator/generator.go
index 4343aa15..97d35f4c 100644
--- a/internal/generator/generator.go
+++ b/internal/generator/generator.go
@@ -106,7 +106,11 @@ func New(s *spec.APISpec, outputDir string) *Generator {
 		"currentYear":        func() string { return strconv.Itoa(time.Now().Year()) },
 		"modulePath":         func() string { return naming.CLI(s.Name) },
 		"kebab":              toKebab,
-		"envName":            func(s string) string { return strings.ToUpper(strings.ReplaceAll(s, "-", "_")) },
+		"humanName": func(s string) string {
+			// "steam-web" → "Steam Web", "notion" → "Notion"
+			return cases.Title(language.English).String(strings.ReplaceAll(s, "-", " "))
+		},
+		"envName": func(s string) string { return strings.ToUpper(strings.ReplaceAll(s, "-", "_")) },
 		"firstResource": func(resources map[string]spec.Resource) string {
 			var names []string
 			for name := range resources {
diff --git a/internal/generator/templates/readme.md.tmpl b/internal/generator/templates/readme.md.tmpl
index 43b1577b..53df8e95 100644
--- a/internal/generator/templates/readme.md.tmpl
+++ b/internal/generator/templates/readme.md.tmpl
@@ -1,4 +1,4 @@
-# {{.Name}}-pp-cli
+# {{humanName .Name}} CLI
 
 {{.Description}}
 
@@ -102,20 +102,20 @@ This checks your configuration{{if and (ne .Auth.Type "") (ne .Auth.Type "none")
 ## Output Formats
 
 ```bash
-# Human-readable table (default)
+# Human-readable table (default in terminal, JSON when piped)
 {{.Name}}-pp-cli {{range $name, $_ := .Resources}}{{$name}}{{break}}{{end}} list
 
 # JSON for scripting and agents
 {{.Name}}-pp-cli {{range $name, $_ := .Resources}}{{$name}}{{break}}{{end}} list --json
 
-# Filter specific fields
+# Filter to specific fields
 {{.Name}}-pp-cli {{range $name, $_ := .Resources}}{{$name}}{{break}}{{end}} list --json --select id,name,status
 
-# Plain tab-separated for piping
-{{.Name}}-pp-cli {{range $name, $_ := .Resources}}{{$name}}{{break}}{{end}} list --plain
-
-# Dry run (show request without sending)
+# Dry run — show the request without sending
 {{.Name}}-pp-cli {{range $name, $_ := .Resources}}{{$name}}{{break}}{{end}} list --dry-run
+
+# Agent mode — JSON + compact + no prompts in one flag
+{{.Name}}-pp-cli {{range $name, $_ := .Resources}}{{$name}}{{break}}{{end}} list --agent
 ```
 
 ## Agent Usage
@@ -151,6 +151,8 @@ Common workflows and recipes:
 
 # Sync data locally for offline search
 {{.Name}}-pp-cli sync
+
+# Search synced data
 {{.Name}}-pp-cli search "query"
 
 # Export for backup
diff --git a/internal/pipeline/scorecard.go b/internal/pipeline/scorecard.go
index 7db5d80f..c9382b98 100644
--- a/internal/pipeline/scorecard.go
+++ b/internal/pipeline/scorecard.go
@@ -390,11 +390,14 @@ func scoreREADME(dir string) int {
 			}
 		}
 	}
-	// Quality: Quick Start has no placeholder values
+	// Quality: Quick Start has no obvious placeholder/template values.
+	// "your-key-here" in an export line is a legitimate auth setup example,
+	// not a sign of unfinished boilerplate. Only penalize generic resource
+	// placeholders like "abc123" or unresolved template markers like "USER/tap".
 	qsIdx := strings.Index(content, "Quick Start")
 	if qsIdx >= 0 {
 		qsSection := content[qsIdx:min(qsIdx+500, len(content))]
-		if !strings.Contains(qsSection, "your-key-here") && !strings.Contains(qsSection, "USER/tap") && !strings.Contains(qsSection, "abc123") {
+		if !strings.Contains(qsSection, "USER/tap") && !strings.Contains(qsSection, "abc123") {
 			score += 2
 		}
 	}

← 9ab8aa12 fix(cli): README scorer alias, template placeholder, verify  ·  back to Cli Printing Press  ·  feat(skills): populate README source credits from absorb man 1f9148f0 →