Skip to content

Bundle Pages and Supplementary Data

Jump to bottom
Chris Sweet edited this page Jul 14, 2026 · 3 revisions

type: decision up: "Knowledge-Bundles-Overview" related:

Bundle Pages and Supplementary Data

Where supplementary material (datasets, images, demos, downloadable files) belongs for a repo that is primarily a knowledge bundle, and how a GitHub Pages site relates to the wiki bundle and the federation Card.

Question

For a repo whose primary purpose is to be a consumable knowledge bundle, where should supplementary material live, and should the bundle advertise it through the federation Card?

Context

Three storage surfaces are in play, and they are not interchangeable:

Surface What it is Read by the ask path?
Wiki sub-repo (wiki/<repo>.wiki/) the bundle: Markdown + frontmatter Yes (cloned and read as text)
Main project repo code, scripts/, docs/, Pages source No
GitHub Pages (served from the main repo) a public website No

The bundle's value proposition is a portable, clone-and-reason artifact. The ask primitive (see Team-Workflow) clones the wiki repo and runs an LLM over its Markdown, so retrieval is text-first. llm-wiki.md notes LLMs cannot consume inline images in one pass. GitHub wikis can hold committed image/binary files (they clone with the bundle), but those files are invisible to the text-first read path unless the LLM explicitly opens them.

Options considered

  • A. Everything in the wiki sub-repo (images, data, files all committed to the bundle).
    • Pros: one artifact; renders on GitHub wiki; clones with the bundle.
    • Cons: bloats the repo that is cloned on every SessionStart and every ask; puts load-bearing content in forms (images, binaries) the retrieval path cannot read; slows every consumer.
  • B. Text-first bundle + GitHub Pages for supplementary, with a pointer from the bundle (chosen).
    • Pros: keeps the bundle lean and fully retrievable; Pages is the right surface for visuals, datasets, and interactive demos; humans get a rich front door; the KG and source: edges can still point at it.
    • Cons: two surfaces to maintain; the pointer must be kept current; Pages cannot yet be surfaced through the Card (see Current federation mechanism).
  • C. No Pages; supplementary as repo/release assets only.
    • Pros: no website to maintain.
    • Cons: no good human front door; interactive demos have nowhere to live; discovery is worse.

Decision

Adopt Option B as a conditional best practice, gated on two predicates:

  1. the repo is primarily a knowledge bundle (its reason to exist is to be consumed and shared), and
  2. it lives in a github.io / Pages environment.

When both hold: publish a Pages site from the main repo for supplementary data, images, and demos; keep the wiki bundle text-first, with everything load-bearing expressed as Markdown/frontmatter; commit at most small, captioned images to the wiki (never load-bearing, always described in prose so the ask path gets the content); and advertise the Pages URL to humans. For normal working-memory repos (not primarily bundles), this is optional and left to the user and the application, consistent with the template's "everything optional and modular" ethos.

The existence of a federation Card is the trigger: a repo with a Card is, by construction, meant to be discovered and ask-ed, so it is bundle-primary by that marker.

Placement of the supplementary link. For a KB repo, the supplementary-information link (the Pages site) belongs on the wiki Home page (Home_<repo>.md). This is the canonical placement because the federation Card's home_url resolves to Home (see Current federation mechanism), so a human arriving via the Card reaches the supplementary site in one click. Until the site is published, the Home entry names the intended URL and is marked as pending rather than left as a live-looking dead link. For this bundle the site is now live at https://la3d-llm-agents.github.io/llm-wiki-KB/ (GitHub Pages, served from the main repo's main:/docs).

Current federation mechanism (verified 2026-07-14)

Surfacing the Pages URL through the Card is not supported today and would require an upstream change. The federation index builder scripts/build-index.py (project(), lines 175-193 in LA3D-LLM-Agents/la3d-llm-agents.github.io) hard-derives home_url, card_url, and wiki_clone_url from owner/name; a Card cannot override them. It projects only these Card-authored fields: id, description, topics (x-llm-wiki.topics or top-level topics), capabilities, and endpoints (x-llm-wiki.endpoints). There is no resource field and no site/pages URL read or projected.

Consequences for the interim:

  • home_url always resolves to the wiki Home page (.../wiki/Home_<repo>), not a Pages site.
  • The supported interim path is therefore: link the Pages site from the wiki Home page body (and optionally record it as a source:/resource: frontmatter pointer for future tooling), so a human arriving via home_url reaches the site in one click.
  • To advertise Pages directly in the index, build-index.py would need a new projected field, most naturally an OKF-aligned resource: (or x-llm-wiki.home_page) read in project().

Rejected alternatives

  • Embedding load-bearing knowledge in images, PDFs, or the Pages site. The ask path cannot retrieve it; the answer degrades. Load-bearing content stays as bundle text.
  • Bloating the wiki repo with binaries/datasets. It is cloned on every consume; keep it lean.
  • Overloading endpoints (the one dict that passes through) to carry a website URL. endpoints is semantically for agent reachability (mailbox inbox/channels), not a site; overloading it misleads consumers.

Revisit triggers

  • build-index.py gains a resource:/home_page projection (then advertise Pages through the Card directly, and record the decision as partially superseded).
  • OKF resource: support lands in the template (then prefer it as the canonical pointer field; see Knowledge-Bundles-Overview).
  • Per-bundle Pages proves too heavy to maintain in practice (then fall back to repo/release assets, Option C).

See also

Clone this wiki locally