Repository Guide

This repository is migrating toward one product job and one temporary compatibility job:

Publish a static OKF Explorer that can load OKF bundles from any public HTTPS URL.
Preserve current exemplar URLs while production bundles move to independent versioned publication units referenced by the registry.

Map Of The Repository

Path	Purpose
`apps/okf-explorer/`	Canonical SvelteKit OKF Explorer. This is the main UI source.
`explorer/`	Dependency-free compatibility Explorer PWA source, published under `legacy/`.
`viewer.html` and `view.html`	Legacy single-file viewer surfaces.
`scripts/build_okf_bundle.py`	Builds the small Markdown-derived `okf-bundle.json`.
`scripts/build_uk_government_api_okf.py`	Builds the UK Government APIs large-corpus pack.
`scripts/build_legislation_okf.py`	Builds the complete work-level legislation.gov.uk pack.
`scripts/check_legislation_okf.py`	Enforces legislation corpus completeness and publication invariants.
`scripts/build_site.py`	Builds the static Pages site in `_site/`.
`scripts/okf_semantic.py`	YAML 1.2/YAML-LD parser, pinned context loader, profile validation and JSON-LD projection.
`scripts/build_okf_registry.py`	Generates Explorer JSON and JSON-LD registries from one YAML-LD source.
`profiles/bundle-wiki/v1/`	Experimental OKF Bundle Wiki profile, context, JSON Schemas and SHACL shapes.
`registry/okf-registry.yamlld`	Single semantic source for the public registry projections.
`constraints/source-constraints.yamlld`	Machine-readable fair-use, access and licensing escalation ledger.
`scripts/evaluate_okf_explorer.mjs`	Runs the 100-question browser evaluation harness.
`uk-government-apis/`	Generated UK Government APIs OKF large-corpus descriptor, shards, selected Markdown records and organisation records.
`legislation/`	Generated UK Legislation descriptor, compressed work/search chunks, ontology, access, type and topic concepts.
`docs/uk-legislation/`	Maintained legislation documentation spine and illustrated manual.
`evaluation/legislation/`	Barrister-oriented AI answer suite, rubric and provenance schema.
`docs/`	Manuals, evaluation docs, conformance notes, the DCAT-AP/OpenAPI standards crosswalk and review history.
`evaluation/okf-explorer/`	UK Government APIs question suite and visual-regression evidence.
`evaluation/gov-ckan/`	GOV.UK CKAN paired exemplar question suite.
`experiments/sharepoint-copilot/`	Deterministic Word-record generators, frozen evaluation controls and redacted aggregate findings for the Microsoft 365 Copilot grounding trial. Raw tenant identifiers, transcripts and attempt evidence stay in the ignored private results directory.
`document/`, `stack/`, `standards/`, `federated/`, `frameworks/`, `research/`, `uk-government/`, `organisations/`, `glossary/`	The local Markdown OKF corpus used by the small bundle.
`okf.config.json`	Small-bundle corpus configuration.
`okf-registry.json` and `okf-registry.jsonld`	Generated registry projections for the Explorer and Linked Data clients.
`CHANGELOG.md`	User-visible change history and validation record.

Publication Pipeline

flowchart LR
  Markdown["Markdown OKF corpus"]
  SmallBuilder["scripts/build_okf_bundle.py"]
  UKBuilder["scripts/build_uk_government_api_okf.py"]
  LegislationBuilder["scripts/build_legislation_okf.py"]
  Svelte["apps/okf-explorer build"]
  Site["scripts/build_site.py"]
  Pages["GitHub Pages"]
  Browser["Reader using OKF Explorer"]

  Markdown --> SmallBuilder --> Site
  UKBuilder --> Site
  LegislationBuilder --> Site
  Svelte --> Site
  Site --> Pages --> Browser

The source of truth for the local small bundle is Markdown. The source of truth for the UK Government APIs exemplar is the generator plus official harvested sources and fixtures. The generated JSON and selected Markdown files under uk-government-apis/ are committed so the exemplar can be browsed and tested without a live server.

For human documentation, build_site.py discovers every local Markdown dependency reachable from docs/ and profiles/, publishes a corresponding HTML page, rewrites links in paragraphs, lists and tables, and gives headings stable fragment identifiers. The build then crawls the generated reading pages. A same-site .md link, missing target or missing fragment fails before Pages upload. Missing scripts, stylesheets and images, duplicate identifiers, and route collisions also fail closed. Canonical Markdown remains in Git, is advertised as an exact-build alternate for machines, and is available to people through GitHub's rendered HTML source view.

The UK Legislation source boundary is the generator plus official Atom/CLML interfaces and cached source responses. Generated compressed work/search chunks are committed; provision trees are resolved from official CLML only when selected. Documentation state and screenshot routes are maintained under docs/uk-legislation/ and docs/assets/uk-legislation-manual/.

Stable Public Entry Points

Root Explorer redirect: https://chris-page-gov.github.io/okf-explorer/
Svelte Explorer: https://chris-page-gov.github.io/okf-explorer/
Legacy compatibility Explorer: https://chris-page-gov.github.io/okf-explorer/legacy/
UK Government APIs descriptor: https://chris-page-gov.github.io/okf-uk-government-apis/okf-explorer.json
UK Government APIs in Explorer: https://chris-page-gov.github.io/okf-explorer/?bundle=https%3A%2F%2Fchris-page-gov.github.io%2Fokf-uk-government-apis%2Fokf-explorer.json&view=reader#overview
UK Legislation descriptor: https://chris-page-gov.github.io/okf-uk-legislation/okf-explorer.json
UK Legislation in Explorer: https://chris-page-gov.github.io/okf-explorer/?bundle=https%3A%2F%2Fchris-page-gov.github.io%2Fokf-uk-legislation%2Fokf-explorer.json&view=reader#overview

Former ai-infrastructure-wiki routes remain available for a deprecation cycle. Human routes redirect while former bundle descriptor routes return the machine-readable okf-moved.v1 contract consumed by Explorer v0.4.0 and later.

Local Validation

First run uv sync --locked. This uses the committed CPython 3.12.11 and dependency lock rather than the host's default Python installation.

Run these before publication work:

uv run --locked python scripts/build_uk_government_api_okf.py --check
uv run --locked python scripts/check_legislation_okf.py
uv run --locked python scripts/build_okf_registry.py --check
uv run --locked python scripts/check_source_constraints.py
uv run --locked python scripts/check_documentation_lockstep.py
uv run --locked python scripts/build_okf_bundle.py --check
uv run --locked python scripts/update_viewer.py --check
uv run --locked python scripts/check_okf.py
uv run --locked python scripts/build_site.py

Large-corpus generators must publish both chunked whole-corpus relationships and data/adjacency/manifest.json. The latter uses fnv1a32-prefix-2 buckets for route-scoped hydration; the Explorer and generators share test vectors so non-ASCII route identifiers remain portable.

If the Explorer app changed:

cd apps/okf-explorer
pnpm check
pnpm test
pnpm build
cd ../..
uv run --locked python scripts/build_site.py

How To Decide What To Read

If the terminology or architecture is new to you, start with OKF Explorer from the beginning. Its coverage map provides a staged route from browser and data basics to every advanced specification used by the implementation.

If you are browsing an existing pack, start with okf-explorer-persona-manual.md.

If you are researching legislation, start with the UK Legislation documentation spine and its illustrated manual.

If you are asking an AI to answer questions from a pack, start with ai-okf-usage.md. For evidence about retrieval from governed Word records in SharePoint, continue to the Microsoft 365 Copilot trial report.

If you are building a new pack, start with okf-bundle-authoring.md and keep explorer-overview-context.md open for the large-corpus descriptor contract. If you need to check a field against an external standard, see okf-standards-crosswalk.md for the DCAT-AP/OpenAPI mapping.

If you are changing the Explorer UI, run the harness described in okf-explorer-evaluation.md and update CHANGELOG.md.