Repository navigation
📝 docs(spec): point spec links at open-knowledge-format repo - #206
Conversation
The OKF spec moved to GoogleCloudPlatform/open-knowledge-format; the former copy at knowledge-catalog/okf/SPEC.md is now a frozen snapshot that no longer tracks upstream. Repoint every live spec URL (prose and the AGENTS.md version-check curl) to the new repo: blob: github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md raw: raw.githubusercontent.com/GoogleCloudPlatform/open-knowledge-format/main/SPEC.md Note the path change: SPEC.md now lives at the repo root, not okf/. Also widen the AGENTS.md stale-mirror warning so it names the frozen knowledge-catalog copy as a stale source alongside the older openknowledge-sh mirror. Dated docs/specs/2026-08-* records keep their historical knowledge-catalog citations by design. No Go behavior change. Closes #184
cwest
left a comment
There was a problem hiding this comment.
No changes needed. Every live spec link now points at GoogleCloudPlatform/open-knowledge-format with SPEC.md at the repo root, and I confirmed all three rewritten URL shapes return 200 and the version-check curl prints Version 0.2. The residual knowledge-catalog references are exactly the ones that should stay: the widened stale-copy warning in AGENTS.md and the four dated spec records under docs/specs/, which document state at authoring time rather than a live pointer. No anchor fragments were rewritten, so nothing to re-resolve. Checks are green and no Go behavior changed.
One mechanical step before this can land: the branch is behind main (a sibling merged ahead of it on strict protection). Rebase onto current main and force-push with lease; since the diff is unchanged the re-check is CI-only.
Why
Issue #184. The OKF spec moved to its own repo,
GoogleCloudPlatform/open-knowledge-format. The former home atknowledge-catalog/okf/SPEC.mdis now a frozen snapshot that no longertracks upstream, yet AGENTS.md still named it as the authority — including the
version-check curl in the conformance gate. Anyone citing the frozen copy pins to
whatever it held at freeze time.
What
Repoint every live spec URL from the frozen
knowledge-catalog/okf/SPEC.mdto the new repo. Note the path change:
SPEC.mdnow lives at the repo root,not under
okf/.https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.mdhttps://raw.githubusercontent.com/GoogleCloudPlatform/open-knowledge-format/main/SPEC.mdFiles touched (6):
AGENTS.md— the authoritative blob+raw block, the version-check curl, and thestale-mirror warning (now names the frozen knowledge-catalog copy as a stale
source alongside the older
openknowledge-shmirror).README.md— three spec links.CONTRIBUTING.md— one spec link.docs/README.md— one spec link.site/public/llms.txt— spec link + the "owned by Google (…)" repo prose.site/src/pages/index.astro— three spec links + the "maintained by Google in"link text, and the footer repo-root link relabeled
open-knowledge-format.Deliberately left as-is (historical records)
Four dated spec records keep their
knowledge-catalogcitations by design — theydocument the state at authoring time, not a live pointer:
docs/specs/2026-08-02-v02-provenance-reader.mddocs/specs/2026-08-02-okfctl-api-v02.mddocs/specs/2026-08-02-migrate-v01-to-v02.mddocs/specs/2026-08-03-okfctl-api-search.mdPrior-art references to
openknowledge-sh/openknowledgeindocs/PRD.mdanddocs/adr/0001-build-in-go.mdare about a different (community) tool, not thespec URL, and are out of scope. No
#anchorfragments appear in any rewrittenURL, so no anchor resolution was required.
Verification
AGENTS.md version-check curl, run verbatim:
HTTP status for every rewritten URL shape:
Residual
knowledge-cataloggrep (--exclude-dir=.worktrees --exclude-dir=node_modules):only the 4 historical spec records above + the new stale-copy warning line in
AGENTS.md. No live pointer remains.
Site build:
cd site && npm ci && npm run build→Complete!, 11 pages built.Prose CI (both gates, run CI-exact, before/after):
README.md CONTRIBUTING.md docs/**):RESULT: CLEANsite/dist/**/*.html):RESULT: CLEANdashes; the only
—hits are inside fenced code blocks and the style rule'sown backtick-quoted example, both exempt).
Zero Go behavior change:
git diff --name-onlytouches no.gofiles;gofmt -l .empty;go vet ./...clean.Closes #184