#149 Docs: 10 files still say dbt seed / seeds/*.csv; add migrate-first to quickstart + CI grep

[Anonymous]

Originally created by: grynn-in

Summary

F2 (#145), F3 (#144) and [#147] deleted every CSV seed. The documentation still tells users to run dbt seed and to edit seed files that no longer exist — and in two places the instruction is precisely the action that recreates the dual-writer bug those PRs removed.

This is the same class as the konsol.currency_sync comment fixed in [#147], but user-facing and about twenty files wide.

The two that actively recreate a deleted bug

docs/troubleshooting/faq.md:48

Q: How do I change the consolidation group structure?
Edit seeds/consolidation_groups.csv, then dbt seed && dbt build.

seeds/consolidation_groups.csv was deleted in 934d264 (F2). That collision was demonstrated in [#146]: one dbt seed --select consolidation_groups reverted a published ownership change, deleted a whole consolidation group, and made two entities appear under two groups at once. A user following this FAQ recreates the file and the collision.

docs/user-guide/consolidation-guide.md:259

Edit seeds/cash_flow_categories.csv and re-run dbt seed to map a new GL account.

Deleted in 9cd5126 (F3). Cash Flow Category is now a governed doctype with a Publish gate; editing a CSV bypasses the governance F3 built.

Both should point at the owning doctype instead.

Full inventory

Operational / user-facing — should be fixed:

File	Line	Says
README.md	64	dbt deps && dbt seed && dbt build — the repo's front door, and no bench migrate step
docs/getting-started/quickstart.md	33	dbt seed # Load reference data (11 CSV seeds)
docs/getting-started/setup-guide.md	129	dbt seed # Load 11 CSV seeds into epm_gold schema
docs/setup-guide.md	125	dbt seed # Load allocation rules, consolidation groups, etc.
docs/data-dictionary/seeds-reference.md	whole page	"12 CSV seed files loaded into the epm_gold schema via dbt seed"
docs/admin-guide/operations-runbook.md	69, 81	runbook rows for dbt seed / "Run dbt seed to reload"
docs/troubleshooting/faq.md	45, 48	above, plus entity_fiscal_calendars.csv
docs/user-guide/consolidation-guide.md	259	above
docs/user-guide/budgeting-guide.md	123	Run dbt seed && dbt build
docs/user-guide/allocation-guide.md	151	Run dbt seed && dbt build
docs/allocation-guide.md	43	Run dbt seed && dbt build --select gold_allocation_results
docs/developer-guide/extending-dbt-models.md	115	dbt seed --select your_reference_data

Leave alone — historical or conceptual:
docs/prd/* records what was designed at the time. docs/evaluation/cost-comparison-vs-commercial.md and docs/cost-comparison-vs-commercial.md use "seed" conceptually. DBT-HANDOFF.md:82 is an aside about a hand-corrected load.

Also needed: dbt is no longer self-sufficient

Seeds used to guarantee reference data existed as part of the build. Now epm_gold.currencies, spread_profiles, scenario_definitions, entity_fiscal_calendars, budget_annual_input and the epm_staging reference tables exist by DDL but stay empty until konsol migrates and syncs.

deploy.sh gets this right — the configurator (step 3) runs before dbt (step 5). But anyone following the README quickstart, or running dbt standalone against a fresh ClickHouse, gets empty reference tables with no seed to fall back on and no error explaining why.

Every quickstart/setup path needs a bench migrate (or "start konsol first") step before the first dbt build, stated as a prerequisite rather than implied by ordering.

Suggested shape

1. README.md:64 in [#147] — it is the front door and inside that PR's blast radius. Everything else here is separate.
2. Replace "edit the seed CSV" instructions with the owning doctype: Consolidation Group, Cash Flow Category, Entity Fiscal Calendar, ISO Currency, Spread Profile, Scenario, Allocation Rule, Budget Annual Input, Dimension Mapping, Reporting Hierarchy, IC Elimination Rule.
3. Rewrite docs/data-dictionary/seeds-reference.md as a reference-data page keyed by doctype → ClickHouse relation, or delete it.
4. Add the migrate-first prerequisite to every quickstart/setup path.
5. A CI grep asserting no .md outside docs/prd/ says dbt seed or seeds/*.csv would stop this recurring — docs drift is already a known problem here (#137 has been open since 2 July).

Found during review of [#147]. Related: konsol#119, konsol#120, [#146].

[Anonymous]

Originally posted by: grynn-in

Proposed: a CI grep, as the last step of this issue

Scope, as discussed with the session that fixed [#150]:

No .md outside docs/prd/ may contain dbt seed or a path matching seeds/*.csv.

Deliberately exempt:

• docs/prd/* — a PRD records what was designed at the time. Rewriting one to match today's code destroys its value as a record.
• docs/evaluation/cost-comparison-vs-commercial.md and docs/cost-comparison-vs-commercial.md — these use "seed" conceptually ("add hierarchy mapping as a dbt seed"), not as an instruction. If the phrasing survives the sweep it should be reworded rather than exempted, but it is not the grep's job to force that.
• DBT-HANDOFF.md:82 — an aside about a hand-corrected data load, not an instruction.

Sequencing — this must land with or after the sweep, never before. About twenty files still match. A grep merged first turns CI red on every one of them and blocks unrelated work until the sweep finishes. Suggest it goes in the same PR as the last batch of doc fixes, or immediately after.

What it would and would not have caught. Of the three documentation errors this review pass found:

Error	Caught by the grep?
faq.md:48 — edit seeds/consolidation_groups.csv	Yes
consolidation-guide.md:259 — edit seeds/cash_flow_categories.csv	Yes
assert_exchange_rate_currencies_are_iso.sql — comment naming konsol.currency_sync, a module written and deleted in the same PR	No — it names a module, not a seed

So the grep covers the two that do harm and misses the class where a comment names a symbol that no longer exists. That second class is worth a separate thought later — a check that every konsol.<module> named in a dbt comment resolves would have caught it — but it is a different tool and should not hold this one up.

Why it is worth the CI minute. Documentation drift here is not hypothetical or occasional: [#137] has been open since 2 July doing this same catch-up by hand, F2/F3/#147 invalidated twelve files in three days, and two of the surviving instructions were measured to recreate a bug the same PRs had just deleted. A grep converts that from a periodic manual sweep into a merge-time failure.

[Anonymous]

Originally posted by: grynn-in

Rescoped on 12 Sep 2026 after an issue review against main.

[#150] fixed the two harmful instructions (faq and consolidation guide) and the README.

Still to fix, outside docs/prd/:

• admin-guide/operations-runbook.md
• allocation-guide.md
• consolidation-guide.md (top level)
• data-dictionary/seeds-reference.md
• developer-guide/extending-dbt-models.md
• getting-started/quickstart.md
• getting-started/setup-guide.md
• setup-guide.md
• user-guide/allocation-guide.md
• user-guide/budgeting-guide.md

Also add a bench migrate step to the quickstart and setup guides, and a CI grep so it stays fixed.