← back to Cli Printing Press

fix(cli): GraphQL type dedup, usageErr emission, and FTS5 manual sync (#149)

92074e672957b2d448fbee65cdc71aad705391c8 · 2026-04-11 00:38:25 -0400 · Matt Van Horn

* fix(cli): GraphQL type dedup, usageErr emission, and FTS5 manual sync

Three bugs from the Linear retro that affect future generations:

1. buildTypeDef now deduplicates fields by name, preventing
   "After redeclared" vet errors on large GraphQL schemas.
2. usageErr is always emitted in helpers.go.tmpl, fixing compile
   failures when promoted commands exist without HasMultiPositional.
3. FTS5 manual sync path uses explicit rowids instead of
   DELETE WHERE column=?, which is incompatible with modernc.org/sqlite.

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

* fix(skills): add workspace PII redaction rules to printing-press and publish skills

Live dogfood testing surfaces workspace-specific data (org names, member
emails) that must not appear in public artifacts. Added redaction rules to
secret-protection.md and a mandatory scrub step before PR description
construction in the publish skill.

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

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Files touched

• A docs/plans/2026-04-08-001-fix-graphql-dedup-fts5-plan.md
• A docs/plans/2026-04-08-002-fix-private-data-redaction-plan.md
• A docs/retros/2026-04-08-linear-retro.md
• M internal/generator/templates/store.go.tmpl
• M internal/graphql/parser.go
• M internal/graphql/parser_test.go
• M skills/printing-press-publish/SKILL.md
• M skills/printing-press/references/secret-protection.md

Diff

commit 92074e672957b2d448fbee65cdc71aad705391c8
Author: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date:   Sat Apr 11 00:38:25 2026 -0400

    fix(cli): GraphQL type dedup, usageErr emission, and FTS5 manual sync (#149)
    
    * fix(cli): GraphQL type dedup, usageErr emission, and FTS5 manual sync
    
    Three bugs from the Linear retro that affect future generations:
    
    1. buildTypeDef now deduplicates fields by name, preventing
       "After redeclared" vet errors on large GraphQL schemas.
    2. usageErr is always emitted in helpers.go.tmpl, fixing compile
       failures when promoted commands exist without HasMultiPositional.
    3. FTS5 manual sync path uses explicit rowids instead of
       DELETE WHERE column=?, which is incompatible with modernc.org/sqlite.
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
    
    * fix(skills): add workspace PII redaction rules to printing-press and publish skills
    
    Live dogfood testing surfaces workspace-specific data (org names, member
    emails) that must not appear in public artifacts. Added redaction rules to
    secret-protection.md and a mandatory scrub step before PR description
    construction in the publish skill.
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
    
    ---------
    
    Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
    Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../2026-04-08-001-fix-graphql-dedup-fts5-plan.md  | 184 +++++++++++++++++++
 ...26-04-08-002-fix-private-data-redaction-plan.md |  95 ++++++++++
 docs/retros/2026-04-08-linear-retro.md             | 196 +++++++++++++++++++++
 internal/generator/templates/store.go.tmpl         |  48 +++--
 internal/graphql/parser.go                         |   5 +
 internal/graphql/parser_test.go                    |  55 ++++++
 skills/printing-press-publish/SKILL.md             |   7 +
 .../printing-press/references/secret-protection.md |  22 +++
 8 files changed, 596 insertions(+), 16 deletions(-)

diff --git a/docs/plans/2026-04-08-001-fix-graphql-dedup-fts5-plan.md b/docs/plans/2026-04-08-001-fix-graphql-dedup-fts5-plan.md
new file mode 100644
index 00000000..13402373
--- /dev/null
+++ b/docs/plans/2026-04-08-001-fix-graphql-dedup-fts5-plan.md
@@ -0,0 +1,184 @@
+---
+title: "fix: GraphQL type dedup, usageErr emission, and FTS5 manual sync"
+type: fix
+status: completed
+date: 2026-04-08
+origin: docs/retros/2026-04-08-linear-retro.md
+---
+
+# fix: GraphQL type dedup, usageErr emission, and FTS5 manual sync
+
+## Overview
+
+Three bugs surfaced during the Linear (GraphQL) CLI generation that affect every future generation. Two cause compile failures on GraphQL APIs, and one causes FTS5 search to fail silently on any API where FTS fields aren't extracted table columns.
+
+## Problem Frame
+
+When generating a CLI from Linear's 43k-line GraphQL schema:
+1. `go vet` failed because the types.go template emitted duplicate struct fields (pagination args like `after`, `before`, `first` appeared multiple times on entity types)
+2. `go build` failed because promoted commands reference `usageErr()` which is conditionally emitted in helpers.go based on `HasMultiPositional` - a flag that is false for most GraphQL APIs
+3. During live testing, FTS5 search failed with "no such column: id" because the manual FTS sync fallback in store.go.tmpl uses `DELETE FROM fts WHERE id = ?`, which is incompatible with modernc.org/sqlite's FTS5 implementation
+
+All three are generator-level bugs that will recur on every future generation unless fixed in the machine.
+
+## Requirements Trace
+
+- R1. GraphQL SDL parsing must produce Go types without duplicate struct fields
+- R2. Generated CLIs must compile without manual intervention regardless of `HasMultiPositional` state
+- R3. FTS5 search must work correctly in the manual (non-trigger) fallback path using modernc.org/sqlite
+
+## Scope Boundaries
+
+- Does not include the broader GraphQL template system (sync, client, promoted examples) - that is WU-3 in the retro
+- Does not redesign the store schema or FTS architecture
+- Does not add new GraphQL-specific templates
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `internal/graphql/parser.go:574-587` - `buildTypeDef()` collects fields without dedup
+- `internal/generator/templates/helpers.go.tmpl:97-98` - `usageErr` behind `{{if .HasMultiPositional}}`
+- `internal/generator/templates/command_promoted.go.tmpl` - calls `usageErr` unconditionally
+- `internal/generator/generator.go` - `HasMultiPositional` set when positionalCount >= 2
+- `internal/generator/templates/store.go.tmpl:312-324` - manual FTS fallback with broken DELETE
+- `internal/generator/schema_builder.go:85-88` - `FTS5Triggers` only true when all FTS fields are extracted columns
+- `internal/generator/templates/store.go.tmpl:91-113` - trigger-based FTS (already correct)
+
+### Key Insight: FTS5 Trigger Path Already Works
+
+The generator already has two FTS5 paths:
+1. **Trigger-based** (`FTS5Triggers=true`): Content-linked FTS5 with AFTER INSERT/UPDATE/DELETE triggers. This path works correctly.
+2. **Manual** (`FTS5Triggers=false`): Direct DELETE/INSERT in Upsert methods. This path has the modernc.org/sqlite bug.
+
+The trigger path is used when all FTS fields are extracted columns. The manual path is used when FTS fields live inside the JSON data column. The bug only affects the manual path.
+
+## Key Technical Decisions
+
+- **Dedup in parser, not template**: Deduplication belongs in `buildTypeDef()` because the parser knows the semantic context. The template should not need to reason about duplicates.
+- **Always emit usageErr**: The function is 1 line and harmless if unused. Removing the conditional is simpler and more robust than computing when it's needed.
+- **Fix manual FTS delete syntax**: Use the FTS5-specific delete command (`INSERT INTO fts(fts, ...) VALUES('delete', ...)`) instead of the standard SQL DELETE which doesn't work on FTS5 virtual tables in modernc.org/sqlite.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Q: Should we switch all FTS to trigger-based?** No. The manual path exists for a reason - when FTS fields aren't extracted columns (they're inside the JSON data blob). Both paths should work. Fix the manual path's SQL syntax.
+- **Q: Is `HasMultiPositional` used elsewhere?** It gates `usageErr` only. Removing the guard has no other side effects.
+
+### Deferred to Implementation
+
+- Exact row-tracking mechanism for the FTS5 manual delete. The implementer needs to verify whether modernc.org/sqlite supports the `INSERT INTO fts(fts, rowid, ...) VALUES('delete', ...)` syntax or needs another approach.
+
+## Implementation Units
+
+- [ ] **Unit 1: Deduplicate fields in buildTypeDef**
+
+**Goal:** Prevent duplicate struct fields in generated types.go for GraphQL APIs
+
+**Requirements:** R1
+
+**Dependencies:** None
+
+**Files:**
+- Modify: `internal/graphql/parser.go`
+- Test: `internal/graphql/parser_test.go`
+
+**Approach:**
+- In `buildTypeDef()`, track seen field names with a `map[string]bool`
+- Skip fields whose name has already been seen (first-wins)
+- Also apply the same dedup to `addSupportTypes()` which recursively builds types through the same `buildTypeDef` function (already covered)
+
+**Patterns to follow:**
+- Existing `buildTypeDef` structure at line 574
+
+**Test scenarios:**
+- Happy path: Parse a schema with unique fields per type -> all fields present in output
+- Edge case: Parse a schema where a type has `after` field in both entity fields and pagination args -> only one `After` field in the Go struct
+- Edge case: Parse Linear's full schema.graphql -> verify no TypeDef has duplicate field names (use a loop over all types)
+- Regression: Existing `TestParseSDLContent` still passes
+
+**Verification:**
+- `go test ./internal/graphql/...` passes
+- Generate from Linear schema -> `go vet ./...` succeeds without types redeclaration errors
+
+- [ ] **Unit 2: Always emit usageErr in helpers.go**
+
+**Goal:** Ensure promoted commands compile regardless of HasMultiPositional state
+
+**Requirements:** R2
+
+**Dependencies:** None (can be done in parallel with Unit 1)
+
+**Files:**
+- Modify: `internal/generator/templates/helpers.go.tmpl`
+- Test: `internal/generator/generator_test.go`
+
+**Approach:**
+- Remove the `{{if .HasMultiPositional}}` / `{{end}}` guard around the `usageErr` function definition
+- The function becomes unconditionally emitted alongside `notFoundErr`, `authErr`, `apiErr`, etc.
+
+**Patterns to follow:**
+- `notFoundErr`, `authErr`, `apiErr`, `configErr`, `rateLimitErr` are all emitted unconditionally on the lines immediately below
+
+**Test scenarios:**
+- Happy path: Generate from a spec with no multi-positional endpoints -> helpers.go contains `usageErr` function
+- Happy path: Generate from a spec with multi-positional endpoints -> helpers.go still contains `usageErr` (no regression)
+- Integration: Generate from a spec with promoted commands -> `go build` succeeds
+
+**Verification:**
+- `go test ./internal/generator/...` passes
+- Generate any CLI with promoted commands -> grep helpers.go for `func usageErr` -> present
+
+- [ ] **Unit 3: Fix FTS5 manual sync for modernc.org/sqlite**
+
+**Goal:** Make the manual FTS fallback path work correctly with the pure-Go SQLite driver
+
+**Requirements:** R3
+
+**Dependencies:** None (can be done in parallel with Units 1-2)
+
+**Files:**
+- Modify: `internal/generator/templates/store.go.tmpl`
+- Modify: `internal/generator/templates/store.go.tmpl` (also the `upsertGenericResourceTx` section around line 147-160 which has the same pattern for `resources_fts`)
+
+**Approach:**
+- Replace `DELETE FROM {{.Name}}_fts WHERE id = ?` with the FTS5 delete command. Two options to evaluate during implementation:
+  - Option A: `INSERT INTO {{.Name}}_fts({{.Name}}_fts, id, fields...) VALUES('delete', ?, fields...)` - requires knowing the old field values
+  - Option B: Drop and rebuild the FTS entry using `DELETE FROM {{.Name}}_fts WHERE rowid = (SELECT rowid FROM {{.Name}} WHERE id = ?)` - only works if the content table has the same rowid
+  - Option C: Switch the manual path to also use content-linked FTS (`content='tablename'`) with explicit rebuild commands rather than triggers. This avoids the DELETE problem entirely by using `INSERT INTO fts(fts) VALUES('rebuild')` after each upsert batch.
+- Apply the same fix to `upsertGenericResourceTx` for the `resources_fts` table
+- The trigger-based path (FTS5Triggers=true) is already correct and should not be changed
+
+**Patterns to follow:**
+- The trigger-based FTS path at lines 91-113 of store.go.tmpl shows the correct modernc.org/sqlite-compatible approach
+
+**Test scenarios:**
+- Happy path: Generate a CLI with FTS-enabled tables where FTS fields are NOT extracted columns (manual path) -> sync data -> `Search()` returns results
+- Happy path: Generate a CLI with FTS-enabled tables where FTS fields ARE extracted columns (trigger path) -> sync data -> `Search()` still works (no regression)
+- Error path: Verify no "no such column" or "SQL logic error" warnings during sync with FTS enabled
+- Edge case: Upsert the same entity twice -> FTS index has exactly one entry (not duplicated)
+
+**Verification:**
+- Generate a test CLI -> sync sample data -> SearchIssues returns expected results
+- No FTS-related warnings in stderr during sync
+
+## System-Wide Impact
+
+- **Interaction graph:** These fixes affect the generator output only. No changes to the printing-press binary's runtime behavior, CLI commands, or skill instructions.
+- **Error propagation:** Unit 1 and 2 fix compile-time errors. Unit 3 fixes a runtime search failure. All are isolated to generated CLI code.
+- **Unchanged invariants:** The trigger-based FTS path (FTS5Triggers=true) is not modified. REST API generation is not modified. The store schema structure is not modified.
+
+## Risks & Dependencies
+
+| Risk | Mitigation |
+|------|------------|
+| FTS5 delete syntax varies between SQLite implementations | Test with modernc.org/sqlite specifically; the trigger path is already proven |
+| Removing usageErr guard might cause dead-code warnings | usageErr is referenced by all promoted commands, so it will never be dead code when promoted commands exist |
+| Field dedup might drop a legitimately needed field | First-wins strategy preserves the primary field; pagination args (after, before, first, last) are always secondary |
+
+## Sources & References
+
+- **Origin document:** [docs/retros/2026-04-08-linear-retro.md](docs/retros/2026-04-08-linear-retro.md)
+- Related code: `internal/graphql/parser.go`, `internal/generator/templates/helpers.go.tmpl`, `internal/generator/templates/store.go.tmpl`
+- modernc.org/sqlite FTS5 behavior: content-linked tables with triggers are the recommended approach
diff --git a/docs/plans/2026-04-08-002-fix-private-data-redaction-plan.md b/docs/plans/2026-04-08-002-fix-private-data-redaction-plan.md
new file mode 100644
index 00000000..5caf2345
--- /dev/null
+++ b/docs/plans/2026-04-08-002-fix-private-data-redaction-plan.md
@@ -0,0 +1,95 @@
+---
+title: "fix: Redact private workspace/org data from public artifacts"
+type: fix
+status: active
+date: 2026-04-08
+---
+
+# fix: Redact private workspace/org data from public artifacts
+
+## Overview
+
+During the Linear CLI publish, the PR description included the user's private workspace name ("Esper Labs") in the live test results. The README and generated code were clean, but the skill's Phase 5 (dogfood testing) and Phase 6 (publish) create public-facing text that can leak private information. The printing-press and publish skills need explicit redaction rules.
+
+## Problem Frame
+
+The printing-press skill instructs Claude to run live dogfood tests and report results. Those results naturally include workspace-specific data (org names, team names, user emails, member names). When this data flows into PR descriptions or manuscripts that get published to a public repo, it becomes a privacy leak.
+
+Three surfaces can leak:
+1. PR descriptions created by the publish skill (confirmed leak)
+2. Manuscripts archived and published alongside the CLI (.manuscripts/ in the library repo)
+3. Acceptance reports and shipcheck proofs written during the session
+
+## Requirements Trace
+
+- R1. PR descriptions must never contain workspace names, org names, user emails, or team member names
+- R2. Manuscripts published to the library repo must be redacted
+- R3. The main printing-press skill must instruct Claude to redact before archiving
+- R4. The publish skill must instruct Claude to redact before creating/updating PRs
+
+## Scope Boundaries
+
+- Does not add automated scanning (that's a separate tooling improvement)
+- Does not change generated CLI code (the README template is already clean)
+- Skill-level instruction changes only
+
+## Key Technical Decisions
+
+- **Instruction-level fix, not code-level**: The leak happens in Claude-authored text (PR descriptions, test reports), not in generated code. The fix is explicit redaction instructions in the skills.
+- **Redact at two points**: (1) when writing acceptance/shipcheck proofs, (2) when creating PR descriptions. Belt and suspenders.
+
+## Implementation Units
+
+- [ ] **Unit 1: Add redaction rules to printing-press skill Phase 5**
+
+**Goal:** Prevent private workspace data from appearing in acceptance reports and manuscripts
+
+**Requirements:** R1, R2, R3
+
+**Dependencies:** None
+
+**Files:**
+- Modify: `skills/printing-press/SKILL.md` (Phase 5 dogfood section)
+
+**Approach:**
+- Add a cardinal rule to the Phase 5 section: "When reporting live test results, NEVER include workspace names, organization names, team member names, or user email addresses. Use generic descriptions instead: 'the workspace' not 'Esper Labs', 'team members' not 'patrick@esperlabs.ai', '5 overloaded members' not their names."
+- Apply to acceptance report format, shipcheck proof, and any stderr output captured in manuscripts
+- Add to the existing Secret & PII Protection section as a new category alongside API keys
+
+**Test expectation:** none - skill instruction change, verified by human review of next generation
+
+**Verification:**
+- Next CLI generation's acceptance report contains no workspace-specific names
+- Manuscripts archived to library repo contain no private data
+
+- [ ] **Unit 2: Add redaction rules to publish skill PR descriptions**
+
+**Goal:** Prevent private workspace data from appearing in public PR descriptions
+
+**Requirements:** R1, R4
+
+**Dependencies:** None (parallel with Unit 1)
+
+**Files:**
+- Modify: `skills/printing-press-publish/SKILL.md` (Step 8 PR description section)
+
+**Approach:**
+- Add instruction before the PR description template: "Before constructing the PR body, scan any live test results or acceptance data for workspace names, org names, team member names, and email addresses. Replace with generic descriptions. The PR is public."
+- Add to the PR description template a reminder comment: `<!-- REDACT: Remove all workspace-specific names, emails, and team member identities before publishing -->`
+
+**Test expectation:** none - skill instruction change, verified by human review of next publish
+
+**Verification:**
+- Next publish PR description contains no workspace-specific data
+
+## Risks & Dependencies
+
+| Risk | Mitigation |
+|------|------------|
+| Claude may still leak data despite instructions | The secret-protection.md reference already handles API keys; extending it to cover PII makes the pattern consistent |
+| Manuscripts may contain data from before the fix | Only affects future generations; existing manuscripts in the library repo should be audited manually |
+
+## Sources & References
+
+- Evidence: PR #23 in mvanhorn/printing-press-library contained "Esper Labs workspace" in live test results
+- Related: `skills/printing-press/references/secret-protection.md` (existing secret scanning rules)
diff --git a/docs/retros/2026-04-08-linear-retro.md b/docs/retros/2026-04-08-linear-retro.md
new file mode 100644
index 00000000..b4221da5
--- /dev/null
+++ b/docs/retros/2026-04-08-linear-retro.md
@@ -0,0 +1,196 @@
+# Printing Press Retro: Linear
+
+## Session Stats
+- API: Linear (GraphQL)
+- Spec source: Official GraphQL SDL from github.com/linear/linear (43,505 lines)
+- Scorecard: 90/100 (Grade A)
+- Verify pass rate: 97%
+- Fix loops: 1 shipcheck loop, 1 live-test fix loop
+- Manual code edits: 6 (GraphQL client, sync command, 6 transcendence commands, types dedup, usageErr, FTS5 fix)
+- Features built from scratch: 8 (GraphQL client layer, sync, today, stale, bottleneck, similar, workload, velocity)
+- Codex delegations: 1 success (store enhancement), 0 failures
+
+## Findings
+
+### 1. GraphQL types.go emits duplicate struct fields (Bug)
+- **What happened:** The GraphQL SDL parser produces types where pagination arguments (after, before, first, last) appear as fields on entity types. The types.go template emits all fields without deduplication, causing `go vet` to fail with "After redeclared."
+- **Root cause:** `internal/graphql/parser.go` `buildTypeDef()` collects all fields from the parsed GraphQL type including inherited/mixed-in pagination fields. `internal/generator/templates/types.go.tmpl` iterates `$typeDef.Fields` without checking for duplicate field names.
+- **Cross-API check:** Affects every GraphQL API. GitHub's schema (30k+ lines) and Shopify's schema have the same Connection pattern with pagination args.
+- **Frequency:** Every GraphQL API
+- **Fallback if machine doesn't fix it:** Claude has to run a Python dedup script post-generation. Catches it when `go vet` fails, but the fix is fragile (regex-based text manipulation).
+- **Worth a machine fix?** Yes. Every GraphQL generation will hit this.
+- **Inherent or fixable:** Fixable. Either deduplicate in the parser (`buildTypeDef`) or in the template.
+- **Durable fix:** In `buildTypeDef()`, track seen field names and skip duplicates:
+  ```go
+  seen := map[string]bool{}
+  for _, field := range typ.Fields {
+      if seen[field.Name] { continue }
+      seen[field.Name] = true
+      fields = append(fields, ...)
+  }
+  ```
+- **Test:** Parse Linear's schema.graphql -> verify no Go struct has duplicate fields. Parse a minimal SDL with pagination args -> verify dedup.
+- **Evidence:** `go vet` failed on generated types.go with "After redeclared" at line 95.
+
+### 2. usageErr conditionally emitted but unconditionally referenced (Bug)
+- **What happened:** Generated promoted commands call `usageErr()` but the function is only emitted in helpers.go when `.HasMultiPositional` is true. For GraphQL APIs where promoted commands all have positional ID args, the function is missing.
+- **Root cause:** `internal/generator/templates/helpers.go.tmpl` line 97-98 wraps `usageErr` in `{{if .HasMultiPositional}}`. `internal/generator/templates/command_promoted.go.tmpl` calls `usageErr` unconditionally.
+- **Cross-API check:** Affects any API where promoted commands have positional args but `.HasMultiPositional` is false. This includes most GraphQL APIs and REST APIs with simple ID-based gets.
+- **Frequency:** Most APIs (any with promoted commands that have positional params)
+- **Fallback if machine doesn't fix it:** Claude adds `usageErr` manually. The CLI won't compile without it, so it's always caught, but it's wasted effort every time.
+- **Worth a machine fix?** Yes. Simple template fix.
+- **Inherent or fixable:** Fixable. Remove the conditional or always emit `usageErr`.
+- **Durable fix:** Remove the `{{if .HasMultiPositional}}` guard from `usageErr` in helpers.go.tmpl. The function is tiny and harmless even if unused (the dead-code checker won't flag it because promoted commands use it).
+- **Test:** Generate any API with promoted commands -> verify `go build` succeeds without manual patching.
+- **Evidence:** Build failed with "undefined: usageErr" across all promoted_*.go files.
+
+### 3. GraphQL sync command must be hand-written (Missing scaffolding)
+- **What happened:** The generator produces a sync.go template for REST APIs but the generated sync doesn't work for GraphQL. The sync command sends GET requests to `/graphql` instead of POST requests with GraphQL queries. The entire sync command (internal/cli/sync.go) and GraphQL client layer (internal/client/graphql.go, queries.go) had to be written from scratch.
+- **Root cause:** The generator's sync.go.tmpl and client.go.tmpl are REST-oriented. GraphQL APIs need: (1) a POST-based query executor, (2) query strings with variables, (3) Connection-pattern pagination handling. None of this exists in the templates.
+- **Cross-API check:** Affects every GraphQL API. GitHub, Shopify, and Linear all use the same query/mutation/connection pattern.
+- **Frequency:** GraphQL subclass (growing: many modern APIs are GraphQL-first)
+- **Fallback if machine doesn't fix it:** Claude writes ~200 lines of GraphQL client code and ~150 lines of sync code from scratch. The quality is good but it's the most labor-intensive part of the generation. Takes ~30% of Phase 3 time.
+- **Worth a machine fix?** Yes. GraphQL is a major API category.
+- **Inherent or fixable:** Fixable. The GraphQL parser already converts SDL to an APISpec with `method: GET, path: /graphql`. Instead, the generator should detect GraphQL specs and emit GraphQL-specific templates.
+- **Durable fix:**
+  1. Add `IsGraphQL bool` to the generator's template context (derived from `spec.BaseURL` containing `/graphql` or spec source being `.graphql`)
+  2. Create `graphql_client.go.tmpl` that emits a `Query()`, `Mutate()`, and `PaginatedQuery()` method on the Client
+  3. Create `graphql_sync.go.tmpl` that generates sync functions using `PaginatedQuery` for each resource's list endpoint
+  4. When `IsGraphQL`, use these templates instead of the REST variants
+  - **Condition:** Spec source is GraphQL SDL or spec base URL ends in `/graphql`
+  - **Guard:** REST APIs continue using existing templates unchanged
+  - **Frequency estimate:** ~15-20% of APIs the printing press targets (GitHub, Linear, Shopify, Contentful, Hasura, etc.)
+- **Test:** Generate from Linear schema.graphql -> sync command works without manual editing. Generate from Stripe OpenAPI -> sync still uses REST client (negative test).
+- **Evidence:** Entire GraphQL client layer (graphql.go, queries.go) and sync.go written from scratch in Phase 3.
+
+### 4. Promoted commands from GraphQL lack examples (Template gap)
+- **What happened:** All 40+ promoted commands generated from the GraphQL schema had no `Example:` field in their cobra command definition. Dogfood reported 2/10 example coverage.
+- **Root cause:** The `command_promoted.go.tmpl` generates examples using the endpoint's operationId or path, but for GraphQL all paths are `/graphql` with no meaningful path segments to derive examples from.
+- **Cross-API check:** GraphQL-specific. REST APIs with meaningful paths produce better examples.
+- **Frequency:** GraphQL subclass
+- **Fallback if machine doesn't fix it:** Polish worker adds examples post-generation. Reliable but adds 2-3 minutes per run.
+- **Worth a machine fix?** Yes, but lower priority than the sync/client issue.
+- **Inherent or fixable:** Fixable. For GraphQL promoted commands, derive examples from the entity name and positional args:
+  ```
+  Example: "  linear-pp-cli issues <issue-id>\n  linear-pp-cli issues <issue-id> --json"
+  ```
+- **Durable fix:** In `command_promoted.go.tmpl`, when the entity has a positional ID param, generate a default example pattern: `<cli-name> <resource> <example-id> [--json] [--select field1,field2]`.
+- **Test:** Generate from GraphQL schema -> promoted commands have non-empty Example fields.
+- **Evidence:** Dogfood reported 2/10 example coverage; polish worker had to add examples to 7 promoted commands.
+
+### 5. FTS5 content-linked triggers fail with modernc.org/sqlite (Bug)
+- **What happened:** The store created by Codex used `DELETE FROM issues_fts WHERE id = ?` to manage FTS5 entries. This syntax doesn't work with modernc.org/sqlite for FTS5 virtual tables. Had to switch to content-linked FTS5 with triggers.
+- **Root cause:** The store.go template (and Codex's enhancement) used a standard SQL DELETE on the FTS5 table, but FTS5 tables in modernc.org/sqlite require either the special `INSERT INTO fts(fts, ...) VALUES('delete', ...)` syntax or content-linked triggers.
+- **Cross-API check:** Affects every API that uses FTS5 in the store (which is every printed CLI).
+- **Frequency:** Every API
+- **Fallback if machine doesn't fix it:** Claude discovers this during live testing and rewrites the FTS management code. The error is clear but the fix is non-trivial (content-linked triggers with proper column references).
+- **Worth a machine fix?** Yes. Critical path - FTS5 is core to the CLI's value proposition.
+- **Inherent or fixable:** Fixable. The store.go template should use content-linked FTS5 from the start.
+- **Durable fix:** Update `store.go.tmpl` to:
+  1. Create FTS5 tables with `content='<table>', content_rowid='rowid'`
+  2. Create AFTER INSERT/UPDATE/DELETE triggers that maintain the FTS index
+  3. Remove manual FTS INSERT/DELETE from Upsert methods
+  4. Only create FTS triggers for tables that have searchable text columns
+- **Test:** Generate any CLI -> sync data -> `SearchIssues()` returns results. No "no such column" errors in FTS operations.
+- **Evidence:** Sync produced hundreds of "warning: issue FTS cleanup failed: SQL logic error: no such column: id" messages until FTS was rewritten with triggers.
+
+### 6. GraphQL query complexity not validated before sync (Recurring friction)
+- **What happened:** The initial TeamsQuery fetched nested members, states, labels, and cycles. Linear's API rejected it with "Query too complex" (complexity limit exceeded). Had to simplify the query by removing nested fields.
+- **Root cause:** No query complexity budgeting. The GraphQL query constants were hand-written without knowing the API's complexity limits.
+- **Cross-API check:** Every GraphQL API has complexity limits. GitHub's is 5,000 points, Linear's appears to be around 1,000.
+- **Frequency:** Every GraphQL API
+- **Fallback if machine doesn't fix it:** Claude discovers during sync testing and manually simplifies queries. Usually caught on first sync attempt, but requires understanding each API's complexity model.
+- **Worth a machine fix?** Worth documenting but hard to automate. Complexity limits vary wildly between APIs.
+- **Inherent or fixable:** Partially inherent. Could mitigate by generating conservative queries (flat fields only, no nested connections) as defaults, with opt-in deeper fetches.
+- **Durable fix:** When generating GraphQL sync queries, default to flat field selection (no nested connections beyond 1 level). Add a `--depth` flag to sync that controls nesting level. Skill instruction: "For GraphQL APIs, start with shallow queries and deepen only if the API allows it."
+- **Test:** Generate from Linear schema -> default sync queries succeed without complexity errors.
+- **Evidence:** TeamsQuery returned HTTP 400 "Query too complex" on first sync attempt.
+
+### 7. GraphQL field names don't match API schema (Assumption mismatch)
+- **What happened:** The CyclesQuery referenced `completedScopeCount` which doesn't exist on Linear's Cycle type. The field was `completedScopeHistory` or similar. Had to discover the correct field name during live testing.
+- **Root cause:** The GraphQL query constants were hand-written based on research assumptions, not derived from the actual schema. The generator's parsed spec had the correct field names but the sync queries were written separately.
+- **Cross-API check:** Happens whenever sync queries are hand-written rather than derived from the parsed schema.
+- **Frequency:** GraphQL subclass (when queries are manually authored)
+- **Fallback if machine doesn't fix it:** Claude discovers during sync and fixes. Always caught on first API call, but wastes a retry cycle.
+- **Worth a machine fix?** Yes, as part of the GraphQL template system (finding #3). If queries are generated from the parsed schema, field names will always be correct.
+- **Inherent or fixable:** Fixable. Part of the GraphQL sync template solution - generate queries from the parsed schema rather than hand-writing them.
+- **Durable fix:** Same as finding #3 - the sync template should derive field selections from the parsed schema's type definitions. The parser already has all field names.
+- **Test:** Generate from any GraphQL schema -> all sync queries reference valid field names. Run sync -> no "Cannot query field" errors.
+- **Evidence:** CyclesQuery returned "Cannot query field 'completedScopeCount' on type 'Cycle'" during live sync.
+
+## Prioritized Improvements
+
+### Do Now
+| # | Fix | Component | Frequency | Fallback Reliability | Complexity | Guards |
+|---|-----|-----------|-----------|---------------------|------------|--------|
+| 1 | Deduplicate struct fields in types.go for GraphQL | graphql/parser.go | Every GraphQL API | Always caught (go vet) but manual fix | small | None needed |
+| 2 | Always emit usageErr in helpers.go | generator/templates/helpers.go.tmpl | Most APIs | Always caught (build fails) but manual fix | small | None needed |
+| 5 | Fix FTS5 to use content-linked triggers | generator/templates/store.go.tmpl | Every API | Caught during live test, non-trivial fix | medium | None needed |
+
+### Do Next (needs design/planning)
+| # | Fix | Component | Frequency | Fallback Reliability | Complexity | Guards |
+|---|-----|-----------|-----------|---------------------|------------|--------|
+| 3 | GraphQL-specific sync/client templates | generator/templates/ | GraphQL subclass (~15-20%) | Claude writes ~350 lines from scratch | large | Only activate for GraphQL specs |
+| 4 | Generate examples for GraphQL promoted commands | generator/templates/command_promoted.go.tmpl | GraphQL subclass | Polish worker fixes, reliable | small | GraphQL path detection |
+| 6 | Conservative default query depth for GraphQL sync | generator/templates/ | Every GraphQL API | Claude simplifies manually, reliable | small | GraphQL only |
+
+### Skip
+| # | Fix | Why unlikely to recur |
+|---|-----|----------------------|
+| 7 | Field name validation in sync queries | Subsumed by finding #3 - generated queries from schema will have correct field names automatically |
+
+## Work Units
+
+### WU-1: GraphQL type deduplication and usageErr fix (findings #1, #2)
+- **Goal:** Fix two compilation failures that affect every GraphQL generation
+- **Target files:**
+  - `internal/graphql/parser.go` (buildTypeDef - add field deduplication)
+  - `internal/generator/templates/helpers.go.tmpl` (remove conditional around usageErr)
+- **Acceptance criteria:**
+  - Parse Linear's 43k-line schema.graphql -> no duplicate fields in any generated struct
+  - Generate from any spec with promoted commands -> `go build` succeeds without manual usageErr addition
+  - Generate from a REST API spec -> no regression (usageErr present and unused is harmless)
+- **Scope boundary:** Does not include the broader GraphQL template system (WU-3)
+- **Complexity:** small (2 files, straightforward fixes)
+
+### WU-2: FTS5 content-linked triggers in store template (finding #5)
+- **Goal:** Generated store uses content-linked FTS5 tables with triggers instead of manual FTS management
+- **Target files:**
+  - `internal/generator/templates/store.go.tmpl` (FTS table creation and trigger generation)
+  - `internal/generator/templates/sync.go.tmpl` (remove manual FTS INSERT/DELETE if present)
+- **Acceptance criteria:**
+  - Generate any CLI -> sync data -> SearchIssues returns results without FTS errors
+  - Generate any CLI -> no "no such column" warnings during sync
+  - FTS triggers only created for tables with searchable text columns (not all tables)
+- **Scope boundary:** Does not redesign the store schema - just fixes FTS management
+- **Complexity:** medium (1-2 template files, need to identify which tables get FTS)
+
+### WU-3: GraphQL generation pipeline (findings #3, #4, #6, #7)
+- **Goal:** The generator emits working GraphQL client, sync, and promoted command examples for GraphQL APIs
+- **Target files:**
+  - `internal/generator/generator.go` (detect GraphQL and set IsGraphQL flag)
+  - `internal/generator/templates/` (new: graphql_client.go.tmpl, graphql_sync.go.tmpl)
+  - `internal/generator/templates/command_promoted.go.tmpl` (example generation for GraphQL)
+  - `internal/graphql/parser.go` (expose field selections for query generation)
+- **Acceptance criteria:**
+  - Generate from Linear schema.graphql -> working sync without manual code
+  - Generate from Linear schema.graphql -> promoted commands have examples
+  - Generate from Linear schema.graphql -> sync queries don't exceed complexity limits
+  - Generate from Stripe OpenAPI -> no regression, REST templates still used (negative test)
+- **Scope boundary:** Does not include GraphQL mutation support in commands (CREATE/UPDATE still need manual wiring). Focused on read path: sync, list, get.
+- **Dependencies:** WU-1 must be complete first (dedup fix needed for types.go)
+- **Complexity:** large (new template files, parser enhancements, generator logic changes)
+
+## Anti-patterns
+
+- **Hand-writing GraphQL queries separately from the parsed schema.** The parser has all field names and types, but queries were written as string constants referencing field names from memory/research. This caused field name mismatches (completedScopeCount). Queries should be derived from the parsed schema.
+- **Creating FTS5 tables for every entity regardless of whether it has text fields.** Codex created FTS5 tables with triggers for teams, cycles, and workflow_states - none of which have meaningful searchable text. FTS should only be created for entities with string fields like title, description, content.
+
+## What the Machine Got Right
+
+- **GraphQL SDL parser.** The parser correctly detected Linear's 98+ entity types, identified Connection patterns for pagination, classified mutations by action type (create/update/delete), and derived the correct API name and auth defaults. This is solid work.
+- **knownGraphQLDefaults.** Having Linear-specific defaults (base URL, auth header, env var name) baked into the parser eliminated auth configuration friction entirely.
+- **Promoted command generation.** The 40+ promoted commands from GraphQL types were structurally correct - correct Use/Short descriptions, positional ID args, output formatting. The only gap was examples.
+- **Store template.** The generic resource store with JSON data columns plus entity-specific typed columns is a good pattern. It survived Codex enhancement and live testing without fundamental issues.
+- **Quality gates.** The 7-gate validation caught both compile errors (types dedup, usageErr) immediately. Without gates, these would have surfaced much later.
+- **Scorecard dimensions.** 90/100 on first generation is strong. Output Modes, Auth, Agent Native, and Local Cache all scored 10/10 without manual work.
diff --git a/internal/generator/templates/store.go.tmpl b/internal/generator/templates/store.go.tmpl
index 86179fa1..101b3242 100644
--- a/internal/generator/templates/store.go.tmpl
+++ b/internal/generator/templates/store.go.tmpl
@@ -144,17 +144,18 @@ func (s *Store) upsertGenericResourceTx(tx *sql.Tx, resourceType, id string, dat
 		return err
 	}
 
-	_, err = tx.Exec(`DELETE FROM resources_fts WHERE id = ?`, id)
-	if err != nil {
+	ftsRowid := ftsRowID(id)
+	// Use explicit rowid for FTS5 compatibility with modernc.org/sqlite.
+	// Standard DELETE WHERE column=? may not work on FTS5 virtual tables.
+	if _, err = tx.Exec(`DELETE FROM resources_fts WHERE rowid = ?`, ftsRowid); err != nil {
 		fmt.Fprintf(os.Stderr, "warning: FTS index cleanup failed: %v\n", err)
 	}
 
-	_, err = tx.Exec(
-		`INSERT INTO resources_fts (id, resource_type, content)
-		 VALUES (?, ?, ?)`,
-		id, resourceType, string(data),
-	)
-	if err != nil {
+	if _, err = tx.Exec(
+		`INSERT INTO resources_fts (rowid, id, resource_type, content)
+		 VALUES (?, ?, ?, ?)`,
+		ftsRowid, id, resourceType, string(data),
+	); err != nil {
 		// FTS insert failure is non-fatal
 		fmt.Fprintf(os.Stderr, "warning: FTS index update failed: %v\n", err)
 	}
@@ -252,6 +253,17 @@ func extractObjectID(obj map[string]any) string {
 	return ""
 }
 
+// ftsRowID derives a deterministic rowid from a string ID for use with FTS5.
+// modernc.org/sqlite's FTS5 implementation may not support DELETE WHERE column=?
+// on virtual tables, so we use explicit rowids and DELETE WHERE rowid=? instead.
+func ftsRowID(id string) int64 {
+	var h uint64
+	for _, c := range id {
+		h = h*31 + uint64(c)
+	}
+	return int64(h & 0x7FFFFFFFFFFFFFFF) // ensure positive
+}
+
 func lookupFieldValue(obj map[string]any, snakeKey string) any {
 	if v, ok := obj[snakeKey]; ok {
 		return v
@@ -311,11 +323,13 @@ func (s *Store) Upsert{{pascal .Name}}(data json.RawMessage) error {
 	}
 {{- if and .FTS5 (not .FTS5Triggers)}}
 
-	// Standalone FTS: manually sync since content-sync triggers aren't used
-	// (FTS fields are inside the JSON data column, not extracted table columns)
-	_, _ = tx.Exec(`DELETE FROM {{.Name}}_fts WHERE id = ?`, id)
+	// Standalone FTS: manually sync since content-sync triggers aren't used.
+	// Use explicit rowid for FTS5 compatibility with modernc.org/sqlite.
+	ftsRowid := ftsRowID(id)
+	_, _ = tx.Exec(`DELETE FROM {{.Name}}_fts WHERE rowid = ?`, ftsRowid)
 	_, _ = tx.Exec(
-		`INSERT INTO {{.Name}}_fts (id, {{safeJoin .FTS5Fields ", "}}) VALUES (?{{- range .FTS5Fields}}, ?{{- end}})`,
+		`INSERT INTO {{.Name}}_fts (rowid, id, {{safeJoin .FTS5Fields ", "}}) VALUES (?{{- range .FTS5Fields}}, ?{{- end}}, ?)`,
+		ftsRowid,
 		id,
 {{- range .FTS5Fields}}
 		lookupFieldValue(obj, "{{.}}"),
@@ -357,13 +371,15 @@ func (s *Store) UpsertBatch(resourceType string, items []json.RawMessage) error
 			return fmt.Errorf("upserting %s/%s: %w", resourceType, id, err)
 		}
 
-		// Update FTS index (non-fatal — matches upsertGenericResourceTx pattern)
-		if _, ftsErr := tx.Exec(`DELETE FROM resources_fts WHERE id = ?`, id); ftsErr != nil {
+		// Update FTS index (non-fatal — matches upsertGenericResourceTx pattern).
+		// Use explicit rowid for FTS5 compatibility with modernc.org/sqlite.
+		ftsRowid := ftsRowID(id)
+		if _, ftsErr := tx.Exec(`DELETE FROM resources_fts WHERE rowid = ?`, ftsRowid); ftsErr != nil {
 			fmt.Fprintf(os.Stderr, "warning: FTS index cleanup failed for %s/%s: %v\n", resourceType, id, ftsErr)
 		}
 		if _, ftsErr := tx.Exec(
-			`INSERT INTO resources_fts (id, resource_type, content) VALUES (?, ?, ?)`,
-			id, resourceType, string(item),
+			`INSERT INTO resources_fts (rowid, id, resource_type, content) VALUES (?, ?, ?, ?)`,
+			ftsRowid, id, resourceType, string(item),
 		); ftsErr != nil {
 			fmt.Fprintf(os.Stderr, "warning: FTS index update failed for %s/%s: %v\n", resourceType, id, ftsErr)
 		}
diff --git a/internal/graphql/parser.go b/internal/graphql/parser.go
index 64859559..c0957d90 100644
--- a/internal/graphql/parser.go
+++ b/internal/graphql/parser.go
@@ -573,7 +573,12 @@ func shouldExposeType(name, kind string) bool {
 
 func buildTypeDef(typ gqlType, enumMap map[string][]string) spec.TypeDef {
 	fields := make([]spec.TypeField, 0, len(typ.Fields))
+	seen := make(map[string]bool, len(typ.Fields))
 	for _, field := range typ.Fields {
+		if seen[field.Name] {
+			continue
+		}
+		seen[field.Name] = true
 		fieldType, _, _ := mapGraphQLType(field.Type)
 		if enumValues := enumMap[unwrapType(field.Type)]; len(enumValues) > 0 && fieldType == "string" {
 			fieldType = "string"
diff --git a/internal/graphql/parser_test.go b/internal/graphql/parser_test.go
index 0263db5b..a214ccbb 100644
--- a/internal/graphql/parser_test.go
+++ b/internal/graphql/parser_test.go
@@ -164,6 +164,61 @@ func TestParseSDLContent(t *testing.T) {
 	assert.NotContains(t, parsed.Types, "IssuePayload")
 }
 
+func TestBuildTypeDefDeduplicatesFields(t *testing.T) {
+	// Schema where a type has duplicate field names (e.g., pagination args
+	// mixed in with entity fields, as happens in large GraphQL schemas like Linear's).
+	sdl := `
+type Query {
+  things(first: Int, after: String): ThingConnection!
+}
+
+type ThingConnection {
+  nodes: [Thing!]!
+  pageInfo: PageInfo!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  endCursor: String
+}
+
+type Thing {
+  id: ID!
+  name: String!
+  after: String
+  before: String
+  first: Int
+  after: String
+  before: String
+}
+`
+	parsed, err := ParseSDLBytes("test-dedup.graphql", []byte(sdl))
+	require.NoError(t, err)
+
+	thingType, ok := parsed.Types["Thing"]
+	require.True(t, ok, "Thing type should be present")
+
+	// Verify no duplicate field names
+	seen := map[string]int{}
+	for _, field := range thingType.Fields {
+		seen[field.Name]++
+	}
+	for name, count := range seen {
+		assert.Equal(t, 1, count, "field %q appears %d times, expected 1", name, count)
+	}
+
+	// Verify all unique fields are present
+	fieldNames := make([]string, 0, len(thingType.Fields))
+	for _, f := range thingType.Fields {
+		fieldNames = append(fieldNames, f.Name)
+	}
+	assert.Contains(t, fieldNames, "id")
+	assert.Contains(t, fieldNames, "name")
+	assert.Contains(t, fieldNames, "after")
+	assert.Contains(t, fieldNames, "before")
+	assert.Contains(t, fieldNames, "first")
+}
+
 func paramNames(params []spec.Param) []string {
 	names := make([]string, 0, len(params))
 	for _, param := range params {
diff --git a/skills/printing-press-publish/SKILL.md b/skills/printing-press-publish/SKILL.md
index c83429aa..5fac9fa2 100644
--- a/skills/printing-press-publish/SKILL.md
+++ b/skills/printing-press-publish/SKILL.md
@@ -681,6 +681,13 @@ Build the PR description from:
 - The validation results from Step 4
 - A Gaps section listing any missing manifest fields
 
+**MANDATORY: Before constructing the PR body, scrub all workspace PII.** The library
+repo is public. Scan any live test results, acceptance data, or manuscript excerpts
+for organization names, team member names, and email addresses. Replace with generic
+descriptions ("the workspace", "5 team members", "12 users"). Team keys (e.g., "ESP")
+are OK but org names (e.g., "Acme Corp") are not. See `references/secret-protection.md`
+in the printing-press skill for the full policy.
+
 **PR description template:**
 
 ```markdown
diff --git a/skills/printing-press/references/secret-protection.md b/skills/printing-press/references/secret-protection.md
index 45ea678d..d8209416 100644
--- a/skills/printing-press/references/secret-protection.md
+++ b/skills/printing-press/references/secret-protection.md
@@ -89,6 +89,28 @@ When the user provides an API key (Phase 0 API Key Gate or inline):
 - When writing live smoke results to proofs, write the test outcomes (PASS/FAIL)
   but never the request URLs that contain the key in query params
 
+## Workspace & organization PII redaction
+
+Live dogfood testing (Phase 5) naturally surfaces workspace-specific data: organization
+names, team names, team member names, and email addresses. This data must NEVER appear
+in any public artifact: acceptance reports, shipcheck proofs, manuscripts archived to
+the library repo, PR descriptions, or READMEs.
+
+**When reporting live test results, use generic descriptions:**
+- "the workspace" not the actual org name
+- "5 overloaded members" not their names or emails
+- "12 users synced" not "synced matt@company.com, patrick@company.com"
+- "team ESP" is OK (team keys are structural, not PII) but "Esper Labs" is not
+
+**Before archiving manuscripts (Phase 5.6):** Scan acceptance reports and shipcheck
+proofs for organization names, email addresses, and full names. The exact-value scan
+for API keys (above) catches secrets; this step catches PII that the user's live
+workspace naturally produces.
+
+**Before creating publish PRs:** The publish skill constructs PR descriptions from
+manuscripts and test results. Any live test data quoted in the PR body must be
+scrubbed of workspace PII. The library repo is public.
+
 ## Session state cleanup
 
 Session state files (`session-state.json`) contain browser cookies and auth tokens.

← 911dc290 feat(cli): printing press improvements from agent-capture re  ·  back to Cli Printing Press  ·  chore(main): release 1.3.0 (#155) d0ef71bf →