galaxyproject / galaxyproject/foundry-pattern
Publish a self-documenting kind catalog in every Foundry
- Dominant language
- Astro
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Goal
Make every Foundry self-documenting by publishing a local kind catalog from its own committed `kinds.generated.json`.
The current [cross-instance catalog](https://galaxyproject.github.io/foundry-pattern/pattern/kind-catalog/) is valuable comparison evidence, but it has to explain several Foundries at once. A local catalog should answer a different question: **what does this kind mean in this Foundry?**
## Reader surface
Each Foundry should expose:
- `/kinds/` — a compact inventory grouped by declared `layer`;
- `/kinds//` — a deep-linkable reference page for one kind.
The index should remain dense reference data: title, identifier, summary, shape, locations, field counts, companions, and links into the live corpus.
A detail page should render:
- definition, layer, shape, and content location;
- a locally derived browse link and note count;
- required and optional metadata tables;
- the directory/companion contract, including open-set semantics;
- the schema-validated `example.md` as escaped source;
- the rendered `kind.md` rationale;
- manifest source/provenance.
## Ownership boundary
| Concern | Owner |
| --- | --- |
| Manifest wire format | `@galaxy-foundry/kind-manifest` |
| Loading `kind.md` and `example.md` | `@galaxy-foundry/kind-schema/docs` |
| Catalog index/detail components | `@galaxy-foundry/site-kit` |
| Routes, corpus counts, collection links, Markdown rendering, theme | Each Foundry |
| Cross-instance comparison | `foundry-pattern` |
The local pages must consume the generated manifest rather than introduce a second kind registry. Corpus counts and site URLs do not belong in the manifest. Examples render as source rather than as fake live notes.
No manifest format change is required: the current format already carries `doc`, `example`, `locations`, fields, shape, and companions.
## Rollout
### 1. foundry-lib
- Add a shared `loadKindExamples` beside `loadKindDocs`.
- Add reusable `KindCatalog.astro` and `KindReference.astro` site-kit components.
- Export resolved presentation prop types; routes and corpus discovery remain instance-owned.
- Add role-based catalog theme tokens and style-gap checks.
- Add shared specimens for flat/directory kinds, required/optional fields, closed/open companion sets, long schemas, and present/absent examples.
- Extend the upstream minimum/designed gallery proof and publish a release.
### 2. bio-topo-foundry
Use as the first adopter because all current kinds already publish docs and examples.
- Replace its local example loader with the shared helper.
- Add `/kinds/` and `/kinds/[kind]`.
- Derive corpus links/counts locally.
- Add gallery renderer coverage, navigation, search, and built-output checks.
### 3. Galaxy Workflow Foundry
Use as the complexity test.
- Emit its already-validated `example.md` files into the manifest.
- Adopt the routes/components.
- Prove dense field tables, many companions, multiple locations, and the open research companion set.
- Add gallery and built-output coverage.
### 4. Statistical Genomics Foundry
Use as the vocabulary-divergence test.
- Emit examples into the manifest and adopt the routes/components.
- Preserve the real distinction that its `research` reference kind spans several note kinds.
- Add gallery and built-output coverage.
### 5. foundry-pattern capstone
Once canonical local URLs exist:
- keep the pattern page as the cross-instance comparison surface;
- simplify it toward a compact matrix;
- retain missing-kind, shape, required-field, and companion-layout comparisons;
- link each instance/kind cell to the canonical local detail page;
- add local kind-catalog acceptance to the standing-up checklist.
## Acceptance
- Every manifest kind has exactly one local detail route.
- Every generated manifest includes `kind.md` and validated `example.md` content.
- No Foundry maintains a parallel kind-name array for this surface.
- Detail documentation is searchable; example source is excluded from search excerpts.
- Every new site-kit component is represented in the shared specimens and every adopting Foundry's component gallery.
- Dark/light and narrow/wide visual acceptance, style-gap checks, built-route checks, and link checks pass.
Relates to #13, which established per-kind directories and the cross-instance generated catalog.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading the committed kinds.generated.json manifest and the existing loadKindDocs helper in foundry-lib, then review the KindCatalog.astro and KindReference.astro ownership described here. Done means every manifest kind has a local index and detail route, validated examples are shown as source, and the listed gallery, built-route, visual, and link checks pass across adopting Foundries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json, markdown
- Domain
- documentation, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100