feat: complete eval checklist follow-ups and timeline tooling

Author: smcronin

README.md

@@ -109,6 +109,7 @@ uspto search --reel-frame "012345/0001"
 
 # Auto-paginate all results (up to 10,000)
 uspto search --examiner "RILEY" --all -f ndjson
+uspto search --assignee "Tesla" --granted --all -f csv > tesla_all.csv
 
 # Count matches only (lightweight sizing call for agents)
 uspto search --assignee "Tesla" --granted-after 2023-01-01 --count-only -f json -q
@@ -127,6 +128,7 @@ uspto search --filter "applicationTypeLabelName=Utility" --facets applicationTyp
 - Uses `POST /search` when `--filter`, `--facets`, date ranges, or `--granted/--pending` are present.
 - Uses `GET /search` for simple query-only cases.
 - For `--download`, it uses `POST /search/download` when those advanced parameters are present; otherwise `GET /search/download`.
+- `--all -f csv` performs client-side page concatenation for CSV export UX (useful when you need paged search semantics instead of `--download csv`).
 
 **All search flags:**
 `--title`, `--inventor`, `--assignee`, `--examiner`, `--applicant`, `--assignor`,
@@ -186,15 +188,29 @@ uspto app associated-docs <appNumber>  # Associated XML document metadata
 uspto app download <appNumber> [index|documentIdentifier] # Download a specific document PDF
 uspto app download-all <appNumber>     # Download all document PDFs
 
-# Grant XML extraction (for granted patents)
+# Patent XML extraction (grant + pgpub fallback)
 uspto app abstract <appNumber>         # Patent abstract
 uspto app claims <appNumber>           # Structured claims text
 uspto app citations <appNumber>        # Prior art citations
 uspto app description <appNumber>      # Full specification text
 uspto app fulltext <appNumber>         # Everything: meta + abstract + claims + citations + description
 ```
 
-The grant XML commands (`abstract`, `claims`, `citations`, `description`, `fulltext`) parse the official patent grant XML to extract structured data. `fulltext` is the most comprehensive single-command view of a granted patent.
+The XML commands (`abstract`, `claims`, `citations`, `description`, `fulltext`) parse official patent XML to extract structured data. They prefer grant XML and fall back to pgpub XML for pending applications when available. `fulltext` is the most comprehensive single-command view.
+For pending applications, these commands automatically fall back to pgpub XML when available.
+For older patents (especially pre-2010), citation completeness can vary depending on legacy XML structure and source data availability.
+
+Document code filters (`app docs --codes`, `app dl --codes`, `app dl-all --codes`) support aliases:
+- `rejection` -> `CTNF,CTFR`
+- `allowance` -> `NOA`
+- `claims` -> `CLM`
+- `specification` / `spec` -> `SPEC`
+- `abstract` -> `ABST`
+- `drawings` -> `DRWR`
+- `ids` -> `IDS`
+
+Assignment note:
+- `app assign` can legitimately return `[]` for direct-company filings where no post-filing assignment recordation exists in the assignment dataset.
 
 ### Compound Commands
 
@@ -206,8 +222,14 @@ uspto summary 16123456
 # Recursive family tree (follows parent/child continuity chains)
 uspto family 16123456 --depth 3
 uspto family 16123456 --depth 3 --with-dates
+
+# Prosecution timeline (metadata + transactions + key docs in one view)
+uspto prosecution-timeline 16123456
+uspto prosecution-timeline 16123456 --codes rejection,allowance,CLM -f json -q
 ```
 
+`family` JSON includes relationship-aware `allApplicationNumbers` entries so CON/DIV/CIP links are explicit in the flat member list.
+
 ### PTAB (Patent Trial and Appeal Board)
 
 14 subcommands for trials, decisions, appeals, and interferences:
@@ -254,6 +276,8 @@ uspto petition search --facets decisionTypeCodeDescriptionText -f json -q
 uspto petition get <recordId> --include-documents
 ```
 
+Dataset note: decision search data is currently dominated by `DENIED` records; `--decision GRANTED` may return no results depending on dataset coverage.
+
 ### Bulk Data
 
 ```bash

cmd/app.go

@@ -475,6 +475,58 @@ func filterEmpty(parts ...string) []string {
 	return out
 }
 
+var documentCodeAliases = map[string][]string{
+	"rejection":           {"CTNF", "CTFR"},
+	"office-action":       {"CTNF", "CTFR"},
+	"non-final-rejection": {"CTNF"},
+	"final-rejection":     {"CTFR"},
+	"allowance":           {"NOA"},
+	"notice-of-allowance": {"NOA"},
+	"claims":              {"CLM"},
+	"specification":       {"SPEC"},
+	"spec":                {"SPEC"},
+	"abstract":            {"ABST"},
+	"drawings":            {"DRWR"},
+	"ids":                 {"IDS"},
+}
+
+func normalizeDocumentCodes(raw string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return ""
+	}
+
+	var out []string
+	seen := make(map[string]bool)
+
+	tokens := strings.Split(raw, ",")
+	for _, tok := range tokens {
+		t := strings.TrimSpace(tok)
+		if t == "" {
+			continue
+		}
+		key := strings.ToLower(strings.ReplaceAll(strings.ReplaceAll(t, "_", "-"), " ", "-"))
+		if expanded, ok := documentCodeAliases[key]; ok {
+			for _, code := range expanded {
+				c := strings.ToUpper(strings.TrimSpace(code))
+				if c != "" && !seen[c] {
+					seen[c] = true
+					out = append(out, c)
+				}
+			}
+			continue
+		}
+
+		c := strings.ToUpper(t)
+		if !seen[c] {
+			seen[c] = true
+			out = append(out, c)
+		}
+	}
+
+	return strings.Join(out, ",")
+}
+
 func sortDocumentsByDateExpr(docs []types.Document, expr string) ([]types.Document, error) {
 	expr = strings.TrimSpace(expr)
 	if expr == "" {
@@ -682,7 +734,7 @@ var appDocsCmd = &cobra.Command{
 		}
 
 		opts := types.DocumentOptions{
-			DocumentCodes:    appDocsCodesFlag,
+			DocumentCodes:    normalizeDocumentCodes(appDocsCodesFlag),
 			OfficialDateFrom: appDocsFromFlag,
 			OfficialDateTo:   appDocsToFlag,
 		}
@@ -1068,7 +1120,7 @@ the output file path (defaults to a generated filename).`,
 
 		// List documents to find the target.
 		docOpts := types.DocumentOptions{
-			DocumentCodes: appDownloadCodesFlag,
+			DocumentCodes: normalizeDocumentCodes(appDownloadCodesFlag),
 		}
 		docResp, err := api.DefaultClient.GetDocuments(context.Background(), appNumber, docOpts)
 		if err != nil {
@@ -1167,7 +1219,7 @@ Progress is shown on stderr.`,
 
 		// List all documents.
 		docOpts := types.DocumentOptions{
-			DocumentCodes:    appDownloadAllCodesFlag,
+			DocumentCodes:    normalizeDocumentCodes(appDownloadAllCodesFlag),
 			OfficialDateFrom: appDownloadAllFromFlag,
 			OfficialDateTo:   appDownloadAllToFlag,
 		}
@@ -1312,7 +1364,7 @@ func init() {
 	appCmd.AddCommand(appDownloadAllCmd)
 
 	// docs flags
-	appDocsCmd.Flags().StringVar(&appDocsCodesFlag, "codes", "", "Comma-separated document codes to filter by")
+	appDocsCmd.Flags().StringVar(&appDocsCodesFlag, "codes", "", "Comma-separated document codes/aliases to filter by (e.g., CTNF,NOA or rejection,allowance)")
 	appDocsCmd.Flags().StringVar(&appDocsFromFlag, "from", "", "Filter documents from this date (YYYY-MM-DD)")
 	appDocsCmd.Flags().StringVar(&appDocsToFlag, "to", "", "Filter documents to this date (YYYY-MM-DD)")
 	appDocsCmd.Flags().StringVar(&appDocsSortFlag, "sort", "", "Client-side sort for documents (date:asc or date:desc)")
@@ -1322,11 +1374,11 @@ func init() {
 
 	// download flags
 	appDownloadCmd.Flags().StringVarP(&appDownloadOutputFlag, "output", "o", "", "Output file path (default: auto-generated)")
-	appDownloadCmd.Flags().StringVar(&appDownloadCodesFlag, "codes", "", "Filter documents by codes before selecting")
+	appDownloadCmd.Flags().StringVar(&appDownloadCodesFlag, "codes", "", "Filter documents by codes/aliases before selecting")
 
 	// download-all flags
 	appDownloadAllCmd.Flags().StringVarP(&appDownloadAllOutputFlag, "output", "o", "", "Output directory (default: current directory)")
-	appDownloadAllCmd.Flags().StringVar(&appDownloadAllCodesFlag, "codes", "", "Comma-separated document codes to filter by")
+	appDownloadAllCmd.Flags().StringVar(&appDownloadAllCodesFlag, "codes", "", "Comma-separated document codes/aliases to filter by")
 	appDownloadAllCmd.Flags().StringVar(&appDownloadAllFromFlag, "from", "", "Filter documents from this date (YYYY-MM-DD)")
 	appDownloadAllCmd.Flags().StringVar(&appDownloadAllToFlag, "to", "", "Filter documents to this date (YYYY-MM-DD)")
 }

cmd/app_test.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"strings"
 	"testing"
 
 	"github.com/smcronin/uspto-cli/internal/types"
@@ -84,3 +85,13 @@ func TestSelectPrimaryAttorney(t *testing.T) {
 		t.Fatalf("primary name = %q, want Jane Doe", got["name"])
 	}
 }
+
+func TestNormalizeDocumentCodes(t *testing.T) {
+	got := normalizeDocumentCodes("rejection,allowance,clm,Spec,office-action,CTFR")
+	wantParts := []string{"CTNF", "CTFR", "NOA", "CLM", "SPEC"}
+	for _, part := range wantParts {
+		if !strings.Contains(got, part) {
+			t.Fatalf("normalizeDocumentCodes() = %q, want to contain %q", got, part)
+		}
+	}
+}

cmd/family.go

@@ -26,12 +26,18 @@ type FamilyNode struct {
 	Children          []FamilyNode `json:"children,omitempty"`
 }
 
+// FamilyApplicationRef is a deduplicated family member with relationship label.
+type FamilyApplicationRef struct {
+	ApplicationNumber string `json:"applicationNumber"`
+	Relationship      string `json:"relationship"`
+}
+
 // FamilyResult is the top-level output for the family command.
 type FamilyResult struct {
-	Root                  string     `json:"root"`
-	Tree                  FamilyNode `json:"tree"`
-	AllApplicationNumbers []string   `json:"allApplicationNumbers"`
-	TotalMembers          int        `json:"totalMembers"`
+	Root                  string                 `json:"root"`
+	Tree                  FamilyNode             `json:"tree"`
+	AllApplicationNumbers []FamilyApplicationRef `json:"allApplicationNumbers"`
+	TotalMembers          int                    `json:"totalMembers"`
 }
 
 // ---------------------------------------------------------------------------
@@ -98,18 +104,25 @@ func runFamily(cmd *cobra.Command, args []string) error {
 
 	ctx := context.Background()
 	client := api.DefaultClient
-	visited := make(map[string]bool)
+	visited := make(map[string]string)
 
 	progress(fmt.Sprintf("Building family tree for %s (depth %d)...", appNumber, flagFamilyDepth))
 
 	tree := buildFamilyNode(ctx, client, appNumber, "", flagFamilyDepth, visited)
 
-	// Collect all unique application numbers.
-	allApps := make([]string, 0, len(visited))
+	// Collect all unique application numbers and their relationship labels.
+	allAppNums := make([]string, 0, len(visited))
 	for app := range visited {
-		allApps = append(allApps, app)
+		allAppNums = append(allAppNums, app)
+	}
+	sortStrings(allAppNums)
+	allApps := make([]FamilyApplicationRef, 0, len(allAppNums))
+	for _, app := range allAppNums {
+		allApps = append(allApps, FamilyApplicationRef{
+			ApplicationNumber: app,
+			Relationship:      visited[app],
+		})
 	}
-	sortStrings(allApps)
 
 	result := FamilyResult{
 		Root:                  appNumber,
@@ -138,14 +151,21 @@ func runFamily(cmd *cobra.Command, args []string) error {
 // buildFamilyNode recursively builds a FamilyNode by fetching continuity
 // and metadata for the given application number. It uses the visited set
 // to avoid cycles and redundant API calls.
-func buildFamilyNode(ctx context.Context, client *api.Client, appNumber, relationship string, depth int, visited map[string]bool) FamilyNode {
+func buildFamilyNode(ctx context.Context, client *api.Client, appNumber, relationship string, depth int, visited map[string]string) FamilyNode {
 	node := FamilyNode{
 		ApplicationNumber: appNumber,
 		Relationship:      relationship,
 	}
 
-	// Mark as visited immediately to prevent cycles.
-	visited[appNumber] = true
+	// Mark as visited immediately to prevent cycles. Keep the first discovered
+	// relationship label for deduplicated allApplicationNumbers output.
+	if _, exists := visited[appNumber]; !exists {
+		rel := strings.TrimSpace(strings.ToUpper(relationship))
+		if rel == "" {
+			rel = "ROOT"
+		}
+		visited[appNumber] = rel
+	}
 
 	// Fetch metadata for this application.
 	progress(fmt.Sprintf("  Fetching metadata for %s...", appNumber))
@@ -192,7 +212,7 @@ func buildFamilyNode(ctx context.Context, client *api.Client, appNumber, relatio
 	var related []relatedApp
 
 	for _, p := range fw.ParentContinuityBag {
-		if p.ParentApplicationNumberText != "" && !visited[p.ParentApplicationNumberText] {
+		if p.ParentApplicationNumberText != "" && visited[p.ParentApplicationNumberText] == "" {
 			related = append(related, relatedApp{
 				appNumber:    p.ParentApplicationNumberText,
 				relationship: parentRelationship(p.ClaimParentageTypeCode),
@@ -201,7 +221,7 @@ func buildFamilyNode(ctx context.Context, client *api.Client, appNumber, relatio
 	}
 
 	for _, c := range fw.ChildContinuityBag {
-		if c.ChildApplicationNumberText != "" && !visited[c.ChildApplicationNumberText] {
+		if c.ChildApplicationNumberText != "" && visited[c.ChildApplicationNumberText] == "" {
 			related = append(related, relatedApp{
 				appNumber:    c.ChildApplicationNumberText,
 				relationship: childRelationship(c.ClaimParentageTypeCode),
@@ -217,7 +237,7 @@ func buildFamilyNode(ctx context.Context, client *api.Client, appNumber, relatio
 	// because an earlier sibling's subtree may have already visited an app
 	// that was in our related list.
 	for _, rel := range related {
-		if visited[rel.appNumber] {
+		if visited[rel.appNumber] != "" {
 			continue
 		}
 		childNode := buildFamilyNode(ctx, client, rel.appNumber, rel.relationship, depth-1, visited)
@@ -267,7 +287,7 @@ func writeFamilyTree(result FamilyResult) {
 	fmt.Fprintln(os.Stdout)
 	fmt.Fprintln(os.Stdout, "All application numbers:")
 	for _, app := range result.AllApplicationNumbers {
-		fmt.Fprintf(os.Stdout, "  %s\n", app)
+		fmt.Fprintf(os.Stdout, "  %s (%s)\n", app.ApplicationNumber, app.Relationship)
 	}
 }
 
@@ -359,6 +379,6 @@ func writeKeyValueFamily(result FamilyResult) {
 	fmt.Fprintln(os.Stdout)
 	fmt.Fprintln(os.Stdout, "Applications:")
 	for _, app := range result.AllApplicationNumbers {
-		fmt.Fprintf(os.Stdout, "  %s\n", app)
+		fmt.Fprintf(os.Stdout, "  %s (%s)\n", app.ApplicationNumber, app.Relationship)
 	}
 }

cmd/family_test.go

@@ -0,0 +1,24 @@
+package cmd
+
+import "testing"
+
+func TestRelationshipNormalization(t *testing.T) {
+	tests := []struct {
+		in   string
+		want string
+	}{
+		{in: "con", want: "CON"},
+		{in: " div ", want: "DIV"},
+		{in: "cip", want: "CIP"},
+		{in: "pro", want: "PRO"},
+		{in: "", want: "PARENT"},
+	}
+	for _, tc := range tests {
+		if got := parentRelationship(tc.in); got != tc.want {
+			t.Fatalf("parentRelationship(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+	if got := childRelationship(""); got != "CHILD" {
+		t.Fatalf("childRelationship(\"\") = %q, want CHILD", got)
+	}
+}