galaxyproject / galaxyproject/foundry-pattern
Sync a shared home for foundation design docs: content/meta/
- Dominant language
- Astro
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
> ℹ️ Filed by Claude (AI assistant) on behalf of @jmchilton — not authored by them personally.
## Sync a shared home for foundation design docs: `content/meta/`
We've been normalizing the two instances' **shared substrate** one surface at a time (glossary → `content/meta/glossary.md`: galaxyproject/foundry#370, jmchilton/statistical-genomics-foundry#99). The **foundation design records** are the next surface — and today they're the odd one out.
### Current state (both instances)
The design docs (`ARCHITECTURE`, `GUIDING_PRINCIPLES`, `MOLD_SPEC`, `COMPILATION_PIPELINE`, `CORPUS`, …) live in a top-level **`docs/`** dir and are surfaced on each site by a **hand-maintained `site/src/lib/design-docs.ts` array** that duplicates each doc's title/summary/category in TypeScript. That array drifts from the files, and the docs sit outside every content collection — unvalidated, un-tag-navigable, and modeled differently from the glossary that already moved to `content/meta/`.
### Proposal
Adopt **`content/meta/`** as the shared home for foundation design records across every instance (glossary already lives there). Concretely, per instance:
- move `docs/*.md` foundation records → `content/meta/.md`;
- give the movable design records a frontmatter contract via the **generic `research` note type** the instances are converging on (GWF dropped `research.subtype` in galaxyproject/foundry#373; SGF is adding a subtype-less generic `research` type to match) — plus the shared lifecycle envelope (`status` / `created` / `revised` / `ai_generated` / `summary`);
- collapse `design-docs.ts` from a source-of-truth array into a **thin renderer over the collection**, so title/summary/category come from frontmatter, not TypeScript.
The **glossary stays special** — hand-curated, alphabetical, validator-skipped — it just gains design-doc neighbors in the same directory.
### Open design question (flag, not blocking)
Do the moved design docs become **validated notes** (generic `research`/meta type + lifecycle frontmatter; the structured target), or **excluded prose** like the glossary (rendered but not in the collection)? Recommendation: **validated** for the movable records (that's the payoff — they join the content model + tag catalog), **excluded** for the glossary only.
### Cross-instance scope
Land the convention for **GWF + SGF**, and bake it into the bootstrap path so **instance #3 (the TDA foundry)** starts here rather than rediscovering `docs/` + a hardcoded array. Each repo files its own implementation issue; this issue owns the shared convention + rationale.
### Relates / depends
- **#12** (cross-instance substrate scan) — add **"design-doc home"** as a tracked substrate surface alongside glossary / content-kinds / tags / license-policy / reference_contract.
- **#13** (per-directory content-type defs + type/tag catalogs) — the `content/meta` records become catalog-visible content once they carry the generic `research` type.
- Per-repo tag/type posture: galaxyproject/foundry#373, galaxyproject/foundry#374, jmchilton/statistical-genomics-foundry#100.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by comparing the foundation records in docs/*.md with the existing glossary in content/meta/ and inspect site/src/lib/design-docs.ts as the current source of truth. Read the related #12 and #13 scope, then define the shared convention and rationale for validated research records, including how the bootstrap path and per-instance implementation issues should use it.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, typescript
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100