docs: replace bronze-only positioning with full-pipeline layer model - #26
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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):
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-contractclass.concepts/raw-ingested-silveropens 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).og:titleupdated.microsite.spec.tsasserts 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
definition of done for ingested bronzestays in the approved-language list. Both remain true as milestone claims, not product-scope claims.tests/docs36 passed; Playwright content suite 15 passed; link-check suite 11 passed.🤖 Generated with Claude Code