feat: ship version-matched docs and AGENTS.md for AI coding agents - #8774
Merged
Conversation
🦋 Changeset detectedLatest commit: 26b619b The changes in this PR will be included in the next version bump. This PR includes changesets to release 118 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
✅ Deploy Preview for modernjs-byted ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
Author
|
Trimmed the bundle per size review: excluded |
keepview
force-pushed
the
feat/agent-knowledge-supply
branch
from
July 22, 2026 14:27
cfa5452 to
072e915
Compare
Contributor
Rsdoctor Bundle Diff Analysis📊 Quick Summary
Generated by Rsdoctor GitHub Action |
zllkjc
previously approved these changes
Jul 27, 2026
…md in create Part of AI governance M1 (agent knowledge supply): - app-tools: prepublishOnly copies packages/document/docs/en into the tarball as main-doc/docs/en (mirrors @modern-js/main-doc layout), so every project gets offline docs that exactly match the installed version; .npmignore re-includes the bundle; scripts/check-doc-bundle.mjs validates file count, alias-import resolvability and size - create: template ships AGENTS.md (managed marker block pointing agents at the bundled docs, falling back to llms.txt and skills) and CLAUDE.md; --no-agents-md opts out; both files are skipped in --sub mode - create: positional-argument parsing refactored — only --lang/-l consumes a value; fixes boolean flags swallowing the following argument (previously `create --sub my-app` ignored my-app) - create: add rstest test infra with 6 integration tests - docs: ai-coding-agents guide documents the bundled docs and AGENTS.md
Exclude community/, tutorials/ and plugin/ from the bundled docs — agents rarely need them while coding and llms.txt covers them online. Bundle: 356 -> 323 files, 0.79MB -> 0.67MB unpacked (~205KB gzipped transfer). Size limit tightened to 2MB.
The create package's tests spawn bin/run.js, which in dev mode loads src/index.ts via tsx and imports @modern-js/i18n-utils — whose dist is not present in the ut jobs (they only build build:required packages before running rstest). Add @modern-js/i18n-utils to build:required; verified by reproducing the CI failure locally (rm i18n-utils dist → same ERR_MODULE_NOT_FOUND → build:required → 6/6 pass).
…s publish includes it The docs bundle (main-doc/docs/en) was generated only in the prepublishOnly hook. The release pipeline (and the repo's own `release` script) publish with `pnpm publish --ignore-scripts`, which skips prepublishOnly, so the canary and production tarballs shipped without the docs. main-doc is also gitignored, so a fresh CI checkout never has it either. Move the copy into the `build` script (which prepare-build/nx runs during `pnpm install` in CI), and declare main-doc as an nx build output so a cached build restores it too. `--ignore-scripts` only skips lifecycle scripts, not packing files already on disk, and .npmignore re-includes main-doc/**, so the bundle now ships in both canary and production without touching the shared release pipeline. Verified via pnpm pack --ignore-scripts (tarball contains all 323 doc files) and a real npm install into a clean project. Co-Authored-By: Riff
…esting) Agents read the bundle from node_modules/@modern-js/app-tools/main-doc/; the extra docs/en/ segment made that path needlessly long. Copy the docs directly into main-doc/ and update the AGENTS.md pointer, the @site-docs-en/* resolution hint, and check-doc-bundle.mjs accordingly. Bundle content is unchanged (323 files, 0.67MB); check-doc-bundle passes with all imports resolvable. Co-Authored-By: Riff
…ENTS.md Rename the bundled-docs directory from main-doc/ to docs/, so agents read from node_modules/@modern-js/app-tools/docs/ (matching Next.js's dist/docs/ convention, minus the build-dir prefix). Updated copy-main-doc.mjs, the nx build output, .gitignore/.npmignore, check-doc-bundle.mjs and the changeset. Also rewrite the generated AGENTS.md to the minimal, focused style Next.js validated: one core instruction (read the bundled docs before coding) plus a short list of v3 essentials, dropping the verbose MDX-import and skills prose. check-doc-bundle passes: 323 files, 0.67MB, all imports resolvable. Co-Authored-By: Riff
The create test asserted the old bundled-docs path (main-doc/docs/en/), which broke ut-mac/ut-windows after the bundle dir was renamed to docs/. Assert the current path instead. Co-Authored-By: Riff
The zh/en AI-coding-agents guides still pointed at the old main-doc/docs/en/ bundle path. Update both to the renamed docs/ directory to match the app-tools tarball layout. Co-Authored-By: Riff
…s fresh The build target declared docs/ as an output but not the source (packages/document/docs/en/**/*) as an input, so a docs-only change would hit the Nx cache and restore a stale bundle — defeating the "docs match the installed version" guarantee. Add the source glob to the build inputs. Reproduced before/after: touching an en doc now correctly rebuilds the bundle instead of restoring the cached copy. Co-Authored-By: Riff
The branch's lockfile had picked up ~500 lines of unrelated upstream drift (module-federation 3.5.0→3.6.0, postcss peer refreshes) from an install against an older main. Restore the lockfile to main's baseline and re-add only the change this PR needs: the @scripts/rstest-config workspace link for the create importer. Co-Authored-By: Riff
New projects get AGENTS.md/CLAUDE.md from the create template, but existing projects that merely upgrade @modern-js/app-tools got the bundled docs in node_modules with nothing pointing agents at them. Add a `create agents-md` subcommand that brings an existing project up to date, idempotently: - AGENTS.md: create it if missing; if a modernjs-agent-rules marker block is present, refresh only that block in place (fixes stale paths on upgrade) while leaving the user's content outside the markers untouched; if there are no markers, append the block. - CLAUDE.md: create it as `@AGENTS.md` if missing, or add the import to an existing file (Claude Code reads CLAUDE.md, not AGENTS.md). The managed block is read from the create template, so the codemod and scaffolding share one source of truth. Adds 5 integration tests and documents the flow for existing projects in the ai-coding-agents guide. Co-Authored-By: Riff
…for clarity The section had grown into dense prose with implementation details (marker mechanics, idempotency internals). Rewrite it to be scannable and user-focused: what you get out of the box, an "Existing projects" subsection with the command in a code block, and one line on what's safe to edit — dropping the internals users don't need. Co-Authored-By: Riff
…allback The strategy is bundled-docs-first; llms.txt is the online fallback for what the bundle can't cover (other versions, trimmed sections, latest online). Put the bundled docs section first, move llms.txt after it and reframe it as a fallback, and add a one-line overview of the three layers so the page reads top-to-bottom in priority order. Co-Authored-By: Riff
Rework the "Modern.js For AI" page so each capability stands on its own and reads like the rest of the docs: keep the intro a plain overview (drop the layered-strategy wording); split "Bundled docs" and "AGENTS.md / CLAUDE.md" into separate sections (AGENTS.md is project guidance, not just a doc pointer), folding new/existing-project setup into the AGENTS.md section; and describe llms.txt by what it is and when to use it (drop the "primary source" / "fallback" framing). Co-Authored-By: Riff
…xpand llms.txt use cases - Rename the heading to "AGENTS.md" and mention CLAUDE.md inline (it is generated alongside), instead of putting both in the heading. - Restore the markdown link on the llms-full.txt URL so it is clickable. - Add the "outside a project" use case for llms.txt (e.g. before a project exists, or researching Modern.js on its own). Co-Authored-By: Riff
When adding the managed block to an existing AGENTS.md that has no markers, prepend it instead of appending — the "read the docs before you code" rule is the highest-priority instruction and should lead the file, with the user's own content kept below it. Co-Authored-By: Riff
keepview
force-pushed
the
feat/agent-knowledge-supply
branch
from
July 27, 2026 08:34
2599ba6 to
26b619b
Compare
keepview
changed the title
zllkjc
approved these changes
Jul 27, 2026
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
2 participants
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.
What
Ship Modern.js docs that match the installed version inside
@modern-js/app-tools, and point AI coding agents at them viaAGENTS.md— so agents rely on version-accurate docs instead of outdated training data.Changes
docs/in the published tarball (generated at build time, so--ignore-scriptspublishes still include them).AGENTS.md+CLAUDE.md(opt out with--no-agents-md); existing projects can runnpx @modern-js/create agents-mdto add or refresh them idempotently.create(e.g.create --sub my-app).Test
createunit tests pass.pnpm pack --ignore-scripts+ install confirmsnode_modules/@modern-js/app-tools/docs/is populated.