Skip to content

docs: replace bronze-only positioning with full-pipeline layer model - #26

Merged
easel merged 2 commits into
mainfrom
docs/full-pipeline-positioning
Sep 16, 2026
Merged

easel merged 2 commits into
mainfrom
docs/full-pipeline-positioning

Conversation

@easel

@easel easel commented Sep 16, 2026

Copy link
Copy Markdown
Collaborator

What changed

The microsite, user guides, and HELIX governance docs described tablespec as stopping at ingested bronze, with silver and gold work "downstream" and outside the product. That was never the product intent. tablespec compiles UMF specs for every layer; it covers ingested bronze most completely only because a source contract can be finished without business judgment.

This PR rewrites that positioning everywhere it appeared (21 files, docs and site only, no library code):

  • Homepage – headline is now One UMF. Every runtime artifact. (an already-approved headline pattern). Kicker, lede, step three, the comparison-table intro, and the closing CTA no longer place silver outside the product. The hero blueprint marks both the ingested and silver nodes as compiled contracts via a shared .ts-node-contract class.
  • Concept page – concepts/raw-ingested-silver opens with the layer model instead of "silver begins after the source-table contract". The silver section states where those decisions are declared (their own UMF spec) and what they compile to (gold SQL plans, dbt models, Lakeflow datasets).
  • Metadata – FAQ JSON-LD question "Where does silver begin?" becomes "Does tablespec stop at bronze?" with the answer no. Site description, page description, and og:title updated.
  • Governance – brand-voice principle 3 is now "Layers over buzzwords" with an explicit rule against scoping copy to one layer; the old phrase is added to Say This, Not That. Product vision, FEAT-026, FEAT-030, DESIGN.md, VOICE.md quick spine, and US-038 (story + AC5) rewritten to match.
  • Guides – happy-path, bootstrap, worked example, and validation scope no longer say silver work "remains downstream".
  • Tests – microsite.spec.ts asserts the new headline and the shared contract selector, and adds a step that fails if the "begins after the source-table contract" wording returns. Homepage desktop/mobile snapshots re-baselined on Linux.

Why

Surfaced while reviewing a DDD integration proposal: the bronze-only claims would have been cited to reject cross-source features (glossary, context map, conformance) that are in scope. The separation-of-concerns idea in the old copy is kept: silver decisions are declared in their own specs and compiled by the same step, never folded into ingestion.

Reviewer notes

  • ADR-007 and ADR-014 still mention the bronze boundary. They are dated decision records and were left as-is.
  • The PRD summary still calls the ingested contract "bronze completion" and definition of done for ingested bronze stays in the approved-language list. Both remain true as milestone claims, not product-scope claims.
  • Verification: tests/docs 36 passed; Playwright content suite 15 passed; link-check suite 11 passed.

🤖 Generated with Claude Code

easel and others added 2 commits September 15, 2026 21:52
The microsite, guides, and governance docs described tablespec as stopping
at ingested bronze, with silver work "downstream" and outside the product.
That was never the product intent: tablespec compiles UMF specs for every
layer, and covers ingested bronze most completely only because a source
contract needs no business judgment to finish.

- Homepage: headline becomes "One UMF. Every runtime artifact."; kicker,
  lede, step three, comparison intro, and closing CTA no longer place silver
  outside the product. Hero blueprint marks both ingested and silver nodes
  as compiled contracts (shared .ts-node-contract class).
- Concept page: raw-ingested-silver opens with the layer model; silver
  section says where decisions are declared and what they compile to.
- Metadata: FAQ JSON-LD "Where does silver begin?" becomes "Does tablespec
  stop at bronze?"; site/page descriptions and og:title updated.
- Governance: brand-voice principle 3 is now "Layers over buzzwords" with
  a rule against scoping copy to one layer; old phrase added to Say This,
  Not That; product vision, FEAT-026, FEAT-030, DESIGN.md, VOICE.md, and
  US-038-AC5 rewritten to match.
- Guides: happy-path, bootstrap, worked example, and validation scope no
  longer say silver work "remains downstream".
- Tests: microsite.spec asserts the new headline, the shared contract
  selector, and fails if "begins after the source-table contract" returns.
  Homepage desktop/mobile snapshots re-baselined on Linux.

Dated ADRs (ADR-007, ADR-014) are left as historical records.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Resolves binary conflicts on the two homepage screenshot baselines by
regenerating them from the merged content (main had refreshed them for
its own copy changes; this branch for the new headline). happy-path.md
auto-merged with both sides' edits intact.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@easel
easel merged commit d9aed03 into main Sep 16, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant