chore(graph): LLM-ready README validation + docs in npm tarball

[dgaponov]

Part of AI/LLM-ready documentation for Gravity UI. This PR brings the LLM-ready README contract + docs-in-npm bundling to this package.

What's included

1. README validation workflow

• Adds .github/workflows/validate-readme.yml using gravity-ui/readme-validator@v1 (mirrors uikit's workflow). Runs on PRs touching README.md and component READMEs.

2. LLM-ready README

• Adds a ## For AI agents block (positioning + When to use / When not to use with pointers to neighbor packages + Common pitfalls / hallucination traps).
• Fills any missing required sections (## Install, ## Usage, ## License) so the README passes gravity-readme --package.
• For component packages: component READMEs are fixed to the component contract (one-sentence description, ## Properties, code example).

3. Docs in the npm tarball (buildDocs)

• Adds scripts/build-docs.mjs calling buildDocs() from @gravity-ui/readme-validator — at build time it copies the cleaned README + guides into <outDir>/docs/ so an agent in a consumer project reads docs matching the installed version from node_modules/<pkg>/<out>/docs/.
• Wired into the build pipeline (gulp copy-docs task / appended to the build npm script).
• @gravity-ui/readme-validator added to devDependencies.

4. Docs pointer

• Appends a ## Documentation for AI agents section pointing at the bundled node_modules/<pkg>/<out>/docs/INDEX.md.

Verification

• gravity-readme --package README.md → ✓ (0 errors).
• npm pack --dry-run confirms the generated docs tree ships in the tarball.

Notes

• No runtime/code changes — docs and build-pipeline only.
• The ## For AI agents block is the last human-facing section; the docs pointer sits after it (it correctly closes the agent block for the validator).

Repo-specific: renamed ## Examples → ## Usage; docs/ guides bundled to build/docs (26 files).

Summary by Sourcery

Add AI/LLM-ready documentation support and README validation for the graph package, including bundling versioned docs into the npm build output.

New Features:

• Provide an AI-focused "For AI agents" and documentation pointer sections in the main README to guide automated consumers.

Enhancements:

• Rename the README "Examples" section to "Usage" and add a missing License section to align with the standard package README contract.
• Generate AI-facing documentation into build/docs via a new build-docs script wired into the existing build and publish pipelines.

Build:

• Introduce a build-docs script that uses @gravity-ui/readme-validator to produce a docs tree included in the npm tarball.
• Add @gravity-ui/readme-validator as a development dependency and adjust build scripts to emit docs alongside compiled assets.

CI:

• Add a validate-readme GitHub Actions workflow to check the package and component READMEs on relevant pull requests.

Chores:

• Tidy devDependencies in package.json, ensuring concurrently is listed once and removing an unused web-worker entry from the duplicated section.

[sourcery-ai]

Reviewer's Guide

Adds AI/LLM-ready README content and validation, plus a docs build step that bundles cleaned documentation into the npm tarball, with no runtime code changes.

File-Level Changes

Change	Details	Files
Make the README LLM-ready and compliant with the package validator contract.	Rename the ## Examples section to ## Usage to satisfy required sections. Add a ## License section referencing the MIT license and LICENSE file. Append a ## For AI agents block describing the package, usage conditions, non-usage cases, and common pitfalls for AI tooling. Add a ## Documentation for AI agents section that points AI agents to the installed docs at node_modules/@gravity-ui/graph/build/docs/INDEX.md.	README.md
Integrate docs building into the build pipeline so AI-facing docs ship in the npm tarball.	Add a build:docs npm script that runs node scripts/build-docs.mjs. Append npm run build:docs to both build and build:publish scripts to generate docs on every build. Create scripts/build-docs.mjs that calls buildDocs() from @gravity-ui/readme-validator to copy and structure README and docs/ guides into build/docs. Ensure guides under docs/ are bundled into build/docs (26 files, per description).	package.json scripts/build-docs.mjs
Introduce README validation CI to enforce the LLM-ready documentation contract.	Add .github/workflows/validate-readme.yml that runs gravity-ui/readme-validator@v1 for the package README (type: package). Add a second job in the workflow to validate component READMEs (type: component, paths src/components/*/README.md). Configure the workflow to trigger on pull requests that touch the main README or component READMEs, plus manual dispatch.	.github/workflows/validate-readme.yml
Add tooling dependency required for README validation and docs building, and tidy devDependencies ordering.	Add @gravity-ui/readme-validator as a devDependency to support gravity-readme and buildDocs. Move concurrently from the bottom of devDependencies into the main sorted block (no functional change). Remove the duplicate concurrently entry and keep web-worker as a devDependency.	package.json package-lock.json

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• The hardcoded path in ## Documentation for AI agents (node_modules/@gravity-ui/graph/build/docs/INDEX.md) should stay in sync with buildDocs’s outDir and INDEX naming; consider deriving or documenting this contract in one place to avoid future drift.
• The README validation workflow only watches src/components/*/README.md; if new components are added in nested or differently structured directories, the glob may need to be adjusted to ensure their READMEs are validated as well.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The hardcoded path in `## Documentation for AI agents` (`node_modules/@gravity-ui/graph/build/docs/INDEX.md`) should stay in sync with `buildDocs`’s `outDir` and INDEX naming; consider deriving or documenting this contract in one place to avoid future drift.
- The README validation workflow only watches `src/components/*/README.md`; if new components are added in nested or differently structured directories, the glob may need to be adjusted to ensure their READMEs are validated as well.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gravity-ui-bot]

Preview is ready.