Restructure docs in deployment order, migrate to OKF v0.2, and publish for AI agents - #6
Merged
Merged
Conversation
Expose the OKF v0.2 bundle the way the UNM CARC documentation does, so agents and harnesses consume the source rather than scraping HTML. Machine-readable surface - scripts/gen_llms_txt.py builds docs/llms.txt (a linked outline of all 101 content pages, built from the nav, each entry naming the page, its Markdown twin, and its raw GitHub source) and docs/llms-full.txt (the whole corpus with frontmatter, links made absolute). - scripts/postbuild_agent_surface.py runs after the build: it mirrors every page's Markdown at its URL + index.md, adds a "View this page as Markdown" button, a "Machine-readable versions" line, and okf:* meta tags (type, status, trust tier, provenance) to every page, and writes robots.txt. It is idempotent. - scripts/okf_validate.py checks OKF conformance; scripts/okf_common.py holds the shared helpers. All read site settings from zensical.toml. - The footer links llms.txt, llms-full.txt, and the agent guide. About section - docs/about/ai-agents.md: entry points, the raw-source fallback for sandboxes that cannot reach docs.cyverse.org, how to read the OKF trust signals, and the placeholder and deprecation warnings. - docs/about/contributing.md: the frontmatter contract, verification, and the local build and validation commands. - about.md moves to about/overview.md under a new about/ listing. Repository and CI - AGENTS.md documents the bundle, layout, commands, and editing rules for coding agents; CLAUDE.md points at it (and is no longer ignored). - CI validates OKF conformance, fails if the committed llms.txt indexes have drifted, and trial-builds pull requests; only main deploys, now through the agent-surface step. Fixes found while wiring this up - Theme features were a [project.theme.features] table, which Zensical ignores, so navigation tabs and the edit and view-source buttons never rendered; they are now a list, which the Markdown button also needs. - site_url pointed at cyverse.github.io/docs rather than the docs.cyverse.org domain in CNAME, which every absolute URL in the generated files depends on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two commits. The first is the existing, previously unmerged
claude/cyverse-docs-okf-migration-yz97f0migration; the second adds the agent surface on top, following the conventions of the UNM CARC documentation.1. OKF v0.2 migration and restructure (
a717da4)Every concept page gains YAML frontmatter (
type,description,tags,status, provenance); every directory gains anindex.mdlisting;docs/log.mdrecords bundle history. The tree is reordered to follow a real deployment:architecture/,platform/,deployment/(planning, then phases 01–07 by dependency),operations/,api/,development/,references/. Adds the end-to-enddeployment/from-scratch.mdrunbook and previously undocumented steps (HAProxy, iRODS provider, iCAT, migrations, cert-manager, Harbor, Argo, OpenLDAP, OpenSearch, NATS, bootstrap, verification, troubleshooting). See that commit message for the deduplication and correction details.2. Publish the bundle for AI agents (
b852516)docs/llms.txt: linked outline of all 101 content pages, built from the nav; each entry names the HTML page, its Markdown twin, and its raw GitHub source.docs/llms-full.txt: the whole corpus in one file (~482 KB, ~123k tokens), frontmatter included, links absolute.scripts/postbuild_agent_surface.py(idempotent): serves every page's Markdown at its URL +index.md; adds a "View this page as Markdown" button, a "Machine-readable versions" line, andokf:*meta tags to every page; writesrobots.txt.about.mdmoves toabout/overview.md.AGENTS.mdfor coding agents;CLAUDE.mdpoints at it and is no longer gitignored.llms.txtindexes have drifted, and trial-builds PRs. Onlymaindeploys.Two fixes found while wiring this up
[project.theme.features]table, which Zensical ignores, so navigation tabs and the edit/view-source buttons were not rendering. Now a list.site_urlpointed atcyverse.github.io/docsrather than thedocs.cyverse.orgdomain inCNAME; every absolute URL in the generated files depends on it.Verified locally
okf_validate.py: 0 errors, 0 warnings across 122 files.zensical build --clean: no issues. Agent surface applied twice with no diff on the second run.site/CNAMEsurvives the build (the deploy usesforce_orphan).Note for reviewers
Pushes to
mainpublish straight to docs.cyverse.org, and this changes every page's URL. Worth a look at the built site before merging.🤖 Generated with Claude Code