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

.github/workflows/validate-readme.yml

@@ -0,0 +1,20 @@
+name: Validate README
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - README.md
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  validate-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gravity-ui/readme-validator@v1
+        with:
+          type: package

README.md

@@ -16,11 +16,11 @@ Each plugin renderer is lazy-loaded, so the underlying library code is only down
 
 ## Table of contents
 
-- [Get started](#get-started)
+- [Get started](#getting-started)
 - [Updating charting packages](#updating-charting-packages)
 - [Development](#development)
 
-## Get started
+## Getting started
 
 ### Requirements
 
@@ -206,3 +206,34 @@ npm run test:docker:update
 ### Contributing
 
 Please refer to the [contributing guide](CONTRIBUTING.md) before submitting a pull request.
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## For AI agents
+
+A plugin-dispatching React component that renders charts from multiple Gravity UI charting libraries through one `<ChartKit type="..." data={...} />` API — reach for it when you need a single lazy-loading entry point for mixed chart types, instead of importing each chart library directly.
+
+### When to use
+
+- Rendering more than one charting engine (e.g. `gravity-charts` + `yagr`) behind one consistent component.
+- Lazy-loading chart bundles — each plugin's renderer is `React.lazy`, so a library's code is only fetched when its chart type is actually shown.
+- Bundling charts into a Gravity UI app that wants mobile-friendly tooltips and unified theming out of the box.
+
+### When not to use
+
+- For a single chart type only, import [`@gravity-ui/charts`](https://github.com/gravity-ui/charts) (general) or [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr) (high-performance time-series) directly — the plugin registry is overhead for one engine.
+- To compose a dashboard grid of widgets, use [`@gravity-ui/dashkit`](https://github.com/gravity-ui/dashkit) — ChartKit renders a chart; DashKit arranges many widgets.
+
+### Common pitfalls
+
+- **Rendering `<ChartKit>` before `settings.set({plugins: [...]})`** — the global plugin registry must be populated at app entry; an unregistered `type` throws at render time.
+- **Hallucinated prop `chartType` / `library`** — the dispatch prop is `type` (e.g. `type="gravity-charts"`), and the data is `data`.
+- **Forgetting a container height** — `ChartKit` fills its parent; without an explicit height on the wrapper, the chart collapses to zero.
+- **Expecting plugins to be bundled** — plugin renderers (`@gravity-ui/chartkit/gravity-charts`, `.../yagr`) are lazy; the first render of a type fetches its bundle.
+- **Missing the uikit styles import** — theming depends on `@gravity-ui/uikit/styles/styles.css`; without it, charts render unstyled.
+
+## Documentation for AI agents
+
+Agent-readable documentation for the installed version is located in `node_modules/@gravity-ui/chartkit/build/docs/INDEX.md`.

gulpfile.js

@@ -56,9 +56,36 @@ task('styles-components', () => {
         .pipe(dest(path.resolve(BUILD_DIR)));
 });
 
+// Bundles the AI-facing docs tree (cleaned README + docs/ guides) into build/docs so it
+// ships in the npm tarball.
+task('copy-docs', (done) => {
+    const {buildDocs} = require('@gravity-ui/readme-validator');
+    buildDocs({
+        rootDir: __dirname,
+        outDir: path.join(__dirname, 'build', 'docs'),
+        sources: [
+            {
+                title: 'Guides',
+                kind: 'markdown',
+                baseDir: 'docs',
+                outPrefix: 'guides',
+                nameFromTitle: true,
+            },
+        ],
+    });
+    done();
+});
+
 task(
     'build',
-    series(['clean', 'compile-to-esm', 'copy-js-declarations', 'copy-i18n', 'styles-components']),
+    series([
+        'clean',
+        'compile-to-esm',
+        'copy-js-declarations',
+        'copy-i18n',
+        'styles-components',
+        'copy-docs',
+    ]),
 );
 
 task('default', series(['build']));