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.

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