galaxyproject / galaxyproject/foundry-pattern

Sync a shared home for foundation design docs: content/meta/

Open
#14 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.