Absolute links (§5.1) don't resolve correctly in non-OKF-aware renderers

[jeromeetienne]

§5.1 defines /-prefixed links as relative to the bundle root. link. That's a
valid layer on top of markdown — CommonMark specifies link syntax, not
resolution — so the files stay valid markdown. The concern is resolution
in any viewer that isn't OKF-aware.

A browser resolves /tables/customers.md against the host origin; GitHub
resolves it against the repo root. Neither is the bundle root once the
bundle is nested in a larger repo — which §3 explicitly allows ("a
subdirectory within a larger repository"). In those cases the absolute
links mislink or 404.

This cuts against the zero-tooling portability goal: the text is still
readable with cat, but the links only resolve correctly in an
OKF-aware consumer (or when the bundle happens to sit at the serving
root).

The relative form in §5.2 (./other.md) resolves correctly in every
renderer; it only breaks when files move. So §5.1 trades
renderer-portability for move-stability — yet it's the "recommended"
form.

Questions:

• Is this tradeoff intentional?
• Should the spec note that §5.1 links require an OKF-aware resolver, or
  recommend §5.2 for bundles meant to be browsed raw?

[MuhammadHasbiAshshiddieqy]

Worth noting that this tradeoff isn't just theoretical — the repo's own reference implementation is internally split on it, which is probably the strongest argument that §5.1 needs a decision:

• The enrichment agent prompt does the opposite of the §5.1 recommendation. okf/src/reference_agent/prompts/reference_instruction.md instructs: "Use file-relative paths only. Never start a link with / (that breaks GitHub rendering)" — explicitly the §5.2 form, explicitly citing the renderer-portability concern raised here.
• The shipped concept docs follow the prompt, not the spec. Every cross-link in okf/bundles/*/tables/*.md etc. is relative (../datasets/..., ../references/...). Zero /-prefixed links in the actual concept files.
• But the generated viewer emits the §5.1 form. The /-prefixed absolute links only appear in okf/bundles/*/viz.html.

So today: spec recommends absolute → agent forbids absolute → viewer emits absolute. The reference enrichment path has effectively already chosen §5.2 for exactly the reason in this issue.

Two coherent resolutions:

1. Soften §5.1's "recommended" — keep absolute links as a supported form requiring an OKF-aware resolver, but recommend §5.2 (relative) for bundles meant to be browsed raw. This matches what the agent already does.
2. Keep §5.1 as recommended and instead fix the agent prompt to emit absolute links — but that re-introduces the GitHub-rendering breakage the prompt was written to avoid.

(1) seems more consistent with the zero-tooling portability goal. Happy to send a PR for whichever direction the maintainers prefer — for the prompt/spec text, and to make the viewer's link handling consistent with the choice.

[jeromeetienne]

@MuhammadHasbiAshshiddieqy ohh please let me do the pr. I'm looking for a new gig and such a thing would look good on my resume