Skip to content

feat: add llms.txt support#37

Open
wellkilo wants to merge 1 commit into
walkinglabs:mainfrom
wellkilo:feature/add-llms-txt-support
Open

feat: add llms.txt support#37
wellkilo wants to merge 1 commit into
walkinglabs:mainfrom
wellkilo:feature/add-llms-txt-support

Conversation

@wellkilo
Copy link
Copy Markdown

@wellkilo wellkilo commented Jun 4, 2026

PR: Add /llms.txt and /llms-full.txt (closes #34)

Closes #34.

What this PR does

Adds an llmstxt.org-compliant llms.txt (curated index) and an llms-full.txt (expanded one-shot context bundle) so LLM-powered tools — coding agents, IDE chat plugins, doc-aware search — can ingest the course without crawling the whole VitePress site.

Both files are authored at the repo root (the spec-required location) and copied into docs/public/ so VitePress serves them at the site root. A tiny generator script keeps the two copies in sync, and a CI workflow fails the build if they drift.

Files

Path Kind Purpose
llms.txt new Curated index, H1 + blockquote + sections per spec. Lists README, 12 lectures, 6 projects, harness-creator skill, resources, 13 locale READMEs (under ## Optional).
llms-full.txt new Long-form bundle: inlines repo structure, the five-subsystem definition, one-paragraph summaries for L01–L12, the project arc, the harness-creator reference card, and the canonical session lifecycle.
docs/public/llms.txt new (generated) Served at https://walkinglabs.github.io/learn-harness-engineering/llms.txt.
docs/public/llms-full.txt new (generated) Served at https://walkinglabs.github.io/learn-harness-engineering/llms-full.txt.
scripts/build-llms-txt.mjs new Sync script (Node built-ins only). --check mode used by CI.
package.json edit Add llms:build / llms:check scripts; chain llms:build into docs:build.
.github/workflows/llms-txt-check.yml new CI guard — prevents the two copies from drifting.
README.md edit Add a short "For AI assistants (llms.txt)" section after the Skills section.

Why this matters

  • The repo is a high-visibility course (7.6k★) about how LLMs consume repositories — shipping an llms.txt is on-brand and lowers the friction for agents that want to reference the course mid-task.
  • The spec is intentionally tiny (one markdown file, fixed shape). Cost-to-maintain is near zero, and the CI guard makes drift impossible.
  • Putting the file in docs/public/ (not only at the repo root) ensures both github.com/.../llms.txt and the hosted site URL work — most agents check the site URL.

How I verified

  • Ran node scripts/build-llms-txt.mjs locally — both files land in docs/public/ with matching byte counts.
  • Re-ran with --check against a freshly synced tree — exit 0; mutated one file and re-ran — exit 1 with a clear drift message.
  • Manually validated llms.txt against the llmstxt.org spec (H1, blockquote summary, sections of markdown lists, ## Optional section semantics).
  • Locale READMEs and lecture/project paths cross-checked against the docs/.vitepress/config.mts sidebar tree.

Out of scope (intentionally deferred)

  • Auto-generating llms-full.txt from lecture frontmatter. Doable, but adds a parser and risks summary drift. Current approach is a hand-curated bundle whose only sync requirement is "copy two files to docs/public/" — caught by CI.
  • Per-locale llms.txt. The spec is silent on i18n; the English bundle already points at every locale README under ## Optional. Happy to add if maintainers want it.
  • Inlining lectures 09 / 10. Tracked separately by 9,10两章没有内容 #2; llms-full.txt notes their tracked status.

Reviewer checklist

  • npm run llms:build produces no diff after running it twice in a row.
  • npm run docs:build still succeeds end-to-end (the new step is llms:build running before vitepress build docs).
  • After deploy, the URLs below return 200 with Content-Type: text/plain or text/markdown:
    • https://walkinglabs.github.io/learn-harness-engineering/llms.txt
    • https://walkinglabs.github.io/learn-harness-engineering/llms-full.txt

Add canonical llms.txt and llms-full.txt files for AI assistant consumption.

Publish synchronized copies through docs/public so the VitePress site serves both files at the site root.

Add llms:build and llms:check scripts plus a GitHub Actions guard to keep generated copies in sync.

Change-Id: I60d48a27634df5ac783b882022ed81c78e9e7af6
Verification: npm run llms:check && npm run docs:build.
@wellkilo
Copy link
Copy Markdown
Author

wellkilo commented Jun 5, 2026

@sanbuphy I have resolved issue #34 and would appreciate a code review. Thanks!

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.

Add llms.txt

1 participant