gaugeit.js 0.1.0 → 0.1.1

package/docs/ai/index.md

@@ -0,0 +1,73 @@
+# Gaugeit.js AI documentation
+
+This directory is a task-oriented documentation set for coding agents and language
+models working with Gaugeit.js 0.1.1.
+
+## Choose the smallest useful guide
+
+| Task | Read |
+| --- | --- |
+| Modify the Gaugeit.js repository | Root `AGENTS.md`, then `contributor-guide.md` |
+| Generate correct application code | `library-usage.md` |
+| Select or explain options | `options-reference.md` |
+| Produce a complete integration | `integration-recipes.md` |
+| Diagnose broken output or CI | `troubleshooting.md` |
+| Supply one self-contained context file to a model | `ai-full.md` |
+
+Do not load `ai-full.md` automatically when a focused guide is sufficient. It repeats
+the detailed AI documentation in one file and is intentionally much larger than
+`AGENTS.md`.
+
+## Documentation roles
+
+- Root `AGENTS.md` contains concise repository-editing instructions intended for
+  automatic discovery by coding agents.
+- `.github/copilot-instructions.md` contains the essential repository rules for GitHub
+  Copilot.
+- `CLAUDE.md` and `GEMINI.md` import the root instructions for tools that use those
+  filenames.
+- The files in this directory explain usage, options, integrations, contribution
+  architecture, and troubleshooting in enough detail for code generation.
+
+## Authority and conflict resolution
+
+Use this precedence when information conflicts:
+
+1. canonical runtime source in `src/`;
+2. public core declarations in `src/index.d.ts` and React adapter declarations in
+   `adapters/react/Gaugeit.d.ts`;
+3. executable behavior in `tests/`;
+4. package metadata and build scripts;
+5. `README.md`, `docs/api.md`, and architecture documentation;
+6. this AI-oriented documentation.
+
+A difference does not mean the source is automatically correct documentation. Confirm
+the intended contract from tests and release metadata, then update every affected layer.
+
+## Version and package identity
+
+This documentation describes Gaugeit.js `0.1.1`.
+
+- npm package: `gaugeit.js`
+- Composer package: `kasperi/gaugeit-js`
+- browser global from UMD and standalone bundles: `Gaugeit`
+- React component export: `Gaugeit`
+- GitHub repository: `https://github.com/kasperikoski/gaugeit.js`
+
+Use exact package versions in CDN examples. Do not invent package names, import paths,
+global names, or option keys.
+
+## Important distinctions
+
+- UMD requires separate CSS. Standalone injects the canonical CSS automatically.
+- ESM and CommonJS expose the same core API.
+- The React adapter is thin and must be paired with a CSS import.
+- Composer installs prebuilt browser assets; it does not provide a PHP rendering API.
+- `updateOptions()` deep-merges a patch. `replaceOptions()` resets omitted keys to
+  selected type defaults.
+- Radial pointers, linear indicators, and rolling tapes share lifecycle and animation
+  state but use different geometry families.
+- Value animation is application state. Jitter is visual-only.
+- A light may blink or pulse; blink wins when both are enabled. Flicker may coexist
+  with either effect.
+- `readout.visible` does not automatically make title, value, or unit visible.