galaxyproject / galaxyproject/foundry-pattern

Publish a self-documenting kind catalog in every Foundry

Open
#61 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

## 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.