{
  "markdown": "# HOKF\n\nHOKF is a small Hugo-based Open Knowledge Framework. It targets\n[Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)\nand publishes canonical Markdown as a searchable static site without a backend,\ndatabase, CMS, or application framework.\n\n## Architecture\n\nThe repository keeps knowledge and presentation separate:\n\n```text\nokf/  ── safe YAML adapter ──>  site/content/  ── Hugo ──>  site/public/\n  canonical source                disposable       HTML       Pagefind index\n```\n\n- `okf/` is the source of truth. It contains the reserved bundle `index.md` and\n  `log.md` plus concept documents.\n- `site/content/` is generated Hugo shadow content. It is ignored by Git and\n  may be deleted and rebuilt at any time.\n- `site/layouts/` and `site/assets/` are the thin, theme-free presentation\n  layer.\n- `.agents/skills/` contains focused local workflows for agents.\n\nThe adapter parses front matter with safe YAML loading, preserves nested and\nproducer-defined metadata, tolerates unknown types, and retains the canonical\ntype as Hugo's native content type. Every other producer-defined field is\nnamespaced under `params.okf` in the generated front matter (for example\n`resource` becomes `params.okf.resource`), so it cannot acquire unintended\nHugo publishing semantics; templates read it back as `.Params.okf.<field>`.\n\n## Quickstart\n\nPrerequisites are Python 3, Hugo 0.163.3 extended, and Node.js 22.22.1. Create\nan isolated Python environment and install the pinned dependencies:\n\n```sh\npython3 -m venv .venv\n. .venv/bin/activate\npython -m pip install --only-binary=:all: -r requirements.txt\nnpm ci --ignore-scripts\n```\n\nValidate and test the canonical bundle:\n\n```sh\npython tools/okf_validate.py --src okf\npython -m unittest discover -s tests -v\n```\n\nGenerate, build, and index the site:\n\n```sh\npython tools/okf_hugo_adapter.py --src okf --dst site/content --clean\nhugo --source site --destination public --cleanDestinationDir\nnpm run pagefind\n```\n\nFor local authoring, generate the shadow content and start Hugo:\n\n```sh\npython tools/okf_hugo_adapter.py --src okf --dst site/content --clean\nhugo server --source site\n```\n\nA plain Hugo preview works before Pagefind runs; the search control reports that\nthe index is unavailable. Run the full build and `npm run pagefind` to exercise\nsearch.\n\nTo verify GitHub Pages project-path links locally:\n\n```sh\nhugo --source site --destination public --cleanDestinationDir \\\n  --baseURL https://example.github.io/hokf/\n```\n\n## Validation behavior\n\nThe validator returns a non-zero status only for objective OKF v0.2 conformance\nerrors: invalid YAML, a missing or empty concept `type`, an invalid declared\n`okf_version`, or invalid reserved documents. `okf_version` itself is optional.\nIt reports everything else as advisory warnings without failing, including\nmalformed optional metadata (`resource`, `tags`, `generated`, `verified`,\n`sources`, `usage_window`, `status`, computation fields), broken links, stale\nor orphaned concepts, inconsistent tags, missing recommended metadata,\nduplicates, and legacy `timestamp`.\n\nUse a deliberate quality gate when needed:\n\n```sh\npython tools/okf_validate.py --src okf --warnings-as-errors\n```\n\n## Repository Agent Skills\n\n- `okf-author` creates and updates canonical OKF v0.2 concepts.\n- `okf-curator` maintains indexes, logs, links, lifecycle, and bundle quality.\n- `okf-hugo-site` builds and troubleshoots Hugo, Pagefind, and Pages.\n- `okf-pr-review` reviews OKF, tooling, presentation, dependency, and workflow\n  changes.\n\nValidate the skills with the pinned reference CLI:\n\n```sh\nnpx --yes skills-ref@0.1.5 validate .agents/skills/okf-author\nnpx --yes skills-ref@0.1.5 validate .agents/skills/okf-curator\nnpx --yes skills-ref@0.1.5 validate .agents/skills/okf-hugo-site\nnpx --yes skills-ref@0.1.5 validate .agents/skills/okf-pr-review\n```\n\n## Publishing\n\n`.github/workflows/pages.yml` validates, tests, generates, builds, and indexes\non pull requests and default-branch pushes. Only a successful push to `main`\nuploads and deploys the static artifact through a separate least-privilege\nGitHub Pages job.\n",
  "bytes": 4151,
  "sha": "d5b351b4eb156da98485e2fc767cdcdd970b86308e49ed2a8edc377770a569bf",
  "repo_slug": "dceoy/hokf",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_dceoy_hokf_okf_index_md_6ae9ee36/readme"
}