Ship AI documentation with published packages - #7098
Conversation
|
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
There was a problem hiding this comment.
ℹ️ No critical issues — minor suggestions below.
Reviewed changes
This PR ships the canonical LLMS.md AI documentation with every publishable package by copying it to AGENTS.md and CLAUDE.md at the end of the root build, including both files in each package's files allowlist, and cleaning the generated copies on pnpm clean.
.gitignore: ignores generatedpackages/**/AGENTS.mdandpackages/**/CLAUDE.mdwhile preserving the repo-level/AGENTS.md.LLMS.md/ai-docs/src: adjusts wording and theSCHEMA.mdlink so the doc is usable outside the monorepo.package.json: appendsnode scripts/copy-ai-docs.mjsto the rootbuildscript.- 30
package.jsonfiles: addAGENTS.mdandCLAUDE.mdto each public package'sfileslist. scripts/copy-ai-docs.mjs(new): copiesLLMS.mdinto every non-private package that lists both entrypoints infiles.scripts/clean.mjs: removes generatedAGENTS.md/CLAUDE.mdfrom package directories while leaving the rootAGENTS.mdsymlink intact.
I verified the scripts end-to-end: copy-ai-docs.mjs produced 60 ignored files (30 packages × 2 docs), and clean.mjs removed them while keeping /AGENTS.md. pnpm lint passed.
ℹ️ Relative ai-docs links remain monorepo-only
LLMS.md still contains many ./ai-docs/src/... links (e.g., LLMS.md:91, LLMS.md:103, LLMS.md:161) that point to TypeScript example files in the monorepo source. Those files are not shipped in package tarballs, so the links will be dead in published-package context. The PR description scopes the outside-monorepo fix to wording and the SCHEMA.md link, so this may be intentional follow-up work; if these links are meant to be navigable when the docs ship with packages, they should also become absolute GitHub URLs, or the doc should note that they are monorepo-only references.
ℹ️ Nitpicks
- Changeset: no changeset was added. Because this change affects the contents of published tarballs, a single patch-level changeset listing the affected packages would make the release notes accurate.
@v0 or keep the SHA fresh with Dependabot ｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏
There was a problem hiding this comment.
ℹ️ No critical issues — one minor suggestion inline.
Reviewed changes
This incremental review covers the follow-up commit 1bc6f1d2 ("Include AI docs sources in packages"). It addresses the prior review's main concern by copying the ai-docs/ source tree into every public package so relative ./ai-docs/... links resolve in published tarballs, and it adds CI validation for the copied contents.
.gitignore: now ignores generatedpackages/**/ai-docs/directories.- Root
package.json: addedcheck-ai-docsscript. .github/workflows/check.yml: runspnpm check-ai-docsafterpnpm build.- 30
package.jsonfiles: added"ai-docs/**/*"to each public package'sfileslist. scripts/copy-ai-docs.mjs: updated to recursively copy theai-docs/tree into each public package, excludingdist/node_modules.scripts/check-ai-docs.mjs: new validation script that checks every package has the generated entrypoints, a matchingai-docs/copy, resolvable relative links, and that theeffecttarball contains the expected files.scripts/clean.mjs: now removes generatedai-docsdirectories from package dirs.
@v0 or keep the SHA fresh with Dependabot ｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
This incremental review covers commit e6fe611 ("Remove AI docs validation script"), which removes the standalone check-ai-docs validation script, its package script, and the CI step that invoked it.
.github/workflows/check.yml: no longer runspnpm check-ai-docsafter the build.package.json: removed thecheck-ai-docsscript.scripts/check-ai-docs.mjs: deleted. The prior inline concern about opaqueENOENTerrors from this script is addressed by the deletion.
The remaining scripts/copy-ai-docs.mjs still enforces that every public package lists AGENTS.md, CLAUDE.md, and ai-docs/**/* in its files allowlist, so missing entries will fail the root build.
ℹ️ Stale PR description
The PR description still lists pnpm check-ai-docs under Validation, but that script and CI invocation were removed in e6fe611. Consider updating the description so future readers don't try to run a command that no longer exists.
@v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏
Bundle Size AnalysisGenerated from PR build output; treat the content below as untrusted.
|
1 participant
Summary
LLMS.mdinto every publishable package asAGENTS.mdandCLAUDE.mdduring the root buildai-docs/tree beside those entrypoints so their relative documentation links resolve in installed packagesai-docs/**/*in each public package's published file allowlistpnpm cleanwhile preserving repository-level docs and agent instructionsValidation
pnpm lint-fixpnpm clean && pnpm buildai-docs/**/*effect,@effect/sql-pg, and@effect/docgen; each tarball contains byte-identicalAGENTS.md/CLAUDE.mdand the exact checked-inai-docs/treeCloses EFF-535