okf-site-kit

name	okf-site-kit
description	Turn any Open Knowledge Format (OKF v0.1) bundle into a beautiful, browsable static website. Use when the user wants to publish, browse, view, share, or "make a site from" an OKF bundle / knowledge folder / agent-readable markdown wiki — e.g. "generate a site from my knowledge bundle", "make this OKF browsable", "publish the team knowledge to GitHub Pages". Ships a stdlib generator that reads the bundle (concepts with YAML frontmatter, reserved index.md/log.md, nested directories, non-markdown assets) and emits a complete Astro + Starlight project: hero landing page with section cards, one page per concept with an OKF metadata panel (type badge, tags, resource, timestamp, producer keys), rewritten internal links, changelog from log.md, full-text search, and light/dark theming. Tolerates every bundle dialect found in the wild — Google's sample bundles, spec-canonical bundles, and producer-extended bundles — reporting conformance warnings instead of failing.
license	MIT
compatibility	Requires python3 (stdlib only) to inspect bundles and generate the project; Node.js 18+ with npm to build/preview the emitted Astro + Starlight site (network needed only for npm install).
x-spec-version	1
metadata	{"author":"dhanesh","version":"1.1.0","tags":"okf,static-site,astro,starlight,knowledge-base,documentation,site-generator"}

okf-site-kit

Generate a browsable website from an Open Knowledge Format bundle. OKF (Google's open spec for agent-readable knowledge) deliberately ships no required tooling — a bundle is just markdown with YAML frontmatter — which means "browsable" is left to consumers. This skill is that consumer: assets/okf_site.py (stdlib-only) reads any OKF bundle and emits a complete Astro + Starlight static-site project with search, navigation, and OKF-aware presentation. The bundle stays the canonical knowledge; the site is a generated view of it, regenerated whenever the bundle changes.

Ground rules

• The bundle is read-only. The generator never mutates the source bundle. When the scan finds problems worth fixing at the source (missing type, broken links), surface them to the user and fix the bundle only if they ask.
• Tolerance over rejection. Per the OKF spec's consumer rules, unknown types, extra frontmatter keys, missing optional files, and broken links must degrade gracefully. The generator renders everything it can and prints WARN: lines for the rest — pass the warnings on, don't suppress them.
• Spec tracking. The generator targets OKF v0.1. If the spec has moved (check references/okf-spec.md for the URL and update rule), update the generator before emitting a stale dialect.

Workflow

1. Locate and inspect the bundle. The bundle root is the directory whose index.md (or concept tree) the user means — for bundles made by the feynman-walkthrough skill it's the knowledge root (e.g. docs/knowledge/). Run python3 assets/okf_site.py inspect <bundle> and read the report: concept count and routes, declared okf_version, and conformance warnings. Relay warnings that the user can act on (concepts missing type, files without frontmatter).
2. Generate the site. python3 assets/okf_site.py generate <bundle> --out <dir> with flags from references/parameters.md: --title (defaults to the root index's H1), --tagline, --base /<repo> + --site https://<user>.github.io + --deploy-workflow when the target is GitHub Pages. The output is a self-contained project — nothing in it references the skill.
3. Build and verify. cd <dir> && npm install && npm run build must complete with zero errors; treat generator lines about unresolved links as content issues to report. Where a browser is available, and check the two pages that prove the generation: the homepage (hero, one card per section, working links) and one concept page (type badge, tags, metadata panel, rewritten links, table of contents). Fix and regenerate until clean.