Skip to content

📝 docs(spec): point spec links at open-knowledge-format repo - #206

Merged
cwest merged 2 commits into
mainfrom
wt/t_4f5f0c1d-docs-spec-s-point-every-spec-link-at-goo
Oct 28, 2026
Merged

cwest merged 2 commits into
mainfrom
wt/t_4f5f0c1d-docs-spec-s-point-every-spec-link-at-goo

Conversation

@cwest

@cwest cwest commented Oct 28, 2026

Copy link
Copy Markdown
Owner

Why

Issue #184. The OKF spec moved to its own repo,
GoogleCloudPlatform/open-knowledge-format. The former home at
knowledge-catalog/okf/SPEC.md is now a frozen snapshot that no longer
tracks 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.md
to the new repo. Note the path change: SPEC.md now lives at the repo root,
not under okf/.

  • blob: https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md
  • raw: https://raw.githubusercontent.com/GoogleCloudPlatform/open-knowledge-format/main/SPEC.md

Files touched (6):

  • AGENTS.md — the authoritative blob+raw block, the version-check curl, and the
    stale-mirror warning (now names the frozen knowledge-catalog copy as a stale
    source alongside the older openknowledge-sh mirror).
  • 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-catalog citations by design — they
document the state at authoring time, not a live pointer:

  • docs/specs/2026-08-02-v02-provenance-reader.md
  • docs/specs/2026-08-02-okfctl-api-v02.md
  • docs/specs/2026-08-02-migrate-v01-to-v02.md
  • docs/specs/2026-08-03-okfctl-api-search.md

Prior-art references to openknowledge-sh/openknowledge in docs/PRD.md and
docs/adr/0001-build-in-go.md are about a different (community) tool, not the
spec URL, and are out of scope. No #anchor fragments appear in any rewritten
URL, so no anchor resolution was required.

Verification

AGENTS.md version-check curl, run verbatim:

$ curl -sL https://raw.githubusercontent.com/GoogleCloudPlatform/open-knowledge-format/main/SPEC.md | head -5
# Open Knowledge Format (OKF)

**Version 0.2**

OKF is an open, human- and agent-friendly format for representing

HTTP status for every rewritten URL shape:

https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md        -> HTTP/2 200
https://raw.githubusercontent.com/GoogleCloudPlatform/open-knowledge-format/main/SPEC.md -> HTTP/2 200
https://github.com/GoogleCloudPlatform/open-knowledge-format                          -> HTTP/2 200

Residual knowledge-catalog grep (--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):

  • Markdown prose gate (README.md CONTRIBUTING.md docs/**): RESULT: CLEAN
  • Site HTML prose gate (site/dist/**/*.html): RESULT: CLEAN
  • Spaced em-dash drift: 0 in prose (my new AGENTS.md prose uses closed-up em
    dashes; the only — hits are inside fenced code blocks and the style rule's
    own backtick-quoted example, both exempt).

Zero Go behavior change: git diff --name-only touches no .go files;
gofmt -l . empty; go vet ./... clean.

Closes #184

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 cwest left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@cwest
cwest marked this pull request as ready for review October 28, 2026 21:21
@cwest
cwest merged commit ec80df0 into main Oct 28, 2026
10 checks passed
@cwest
cwest deleted the wt/t_4f5f0c1d-docs-spec-s-point-every-spec-link-at-goo branch October 28, 2026 21:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

🐛 fix(docs): point spec links at open-knowledge-format

1 participant