OKF docs: access & contributing¶

LBS Foundry's documentation follows the Open Knowledge Format (OKF): every doc is plain Markdown with YAML frontmatter, kept in git, and surfaced three ways — a browsable site, a self-contained bundle, and a machine-readable manifest. This page covers how to get the docs and how to add to them. For the full conventions (types, naming, frontmatter schema) see Documentation Conventions.

Get access¶

The documentation site¶

The docs are published as a Cloudflare Worker (foundry-docs), separate from the Foundry web app:

Environment	URL
Staging	https://docs.foundry.luckbox.dev/
Production	https://docs.foundry.luckbox.live/

Search, navigation, and Mermaid diagrams all render in-browser.

Access control: the site is gated by Cloudflare Access (Zero Trust). Once a policy is in place you authenticate with your approved identity (email one-time PIN or SSO) before the site loads. While access is still being configured the site may be reachable without a login — treat the content as internal/proprietary regardless.

The bundle (offline / portable copy)¶

A self-contained copy of the whole doc set is published to Cloudflare R2 and served by the same Worker:

Latest: GET /bundle/latest/docs-bundle.tgz
Pinned to a build: GET /bundle/<git-sha>/docs-bundle.tgz

The tarball contains docs/ (every page, with all relative links intact), the code-adjacent READMEs under their src/ paths, and index.json (the manifest) at its root. Build it locally with pnpm docs:bundle (writes dist/docs-bundle/).

The manifest (for tools and agents)¶

A machine-readable index of every document is served at GET /manifest.json (and lives at the bundle root):

{
  "schema": "okf-docs-manifest/1",
  "version": "<git-sha>",
  "count": 135,
  "documents": [
    { "path": "docs/architecture/event-sourcing.md", "section": "architecture",
      "sectionLabel": "Architecture", "type": "concept",
      "title": "Event Sourcing Architecture", "description": "...",
      "status": "current", "updated": "2026-05-01", "tags": ["..."] }
  ]
}

Use it to enumerate docs by type/section/tags, check freshness via updated, or feed an agent the set without scraping the site.

Add to it¶

Adding a doc is a frontmatter-driven, mostly-automated flow:

Place the file under the right docs/<section>/... folder (nest in sub-folders freely — the index and site nav mirror the folder hierarchy). Use kebab-case filenames.
Add frontmatter — type, title, description, status, updated are required; tags and audience are optional. See Documentation Conventions for the type taxonomy and rules.

Regenerate and validate:

pnpm docs:index   # rebuild docs/README.md from frontmatter
pnpm docs:check   # validate frontmatter, index freshness, and links (CI runs this too)

Commit the doc and the regenerated docs/README.md.

That's it. On merge to main, CI rebuilds the site (docs/SUMMARY.md nav is generated from the same source), repackages the bundle + manifest, and redeploys — so a new doc shows up in the site nav, the index, the bundle, and the manifest automatically.

Docs that live next to code¶

A README that belongs beside its component (e.g. a model predictor under src/Models/) stays in place and is surfaced in the index/bundle by adding it to the EXTERNAL list in tools/docs/docs-index.mjs. On the site, links to such files (and to source, the SDK, or the dated superpowers/ snapshots) point at GitHub, since the site is built from docs/ only. See Documentation Conventions.