Getting Started
Installation
Install the browser SDK first, then add the server package only if you want hybrid fallback inference.
Need the shortest path?
Use Quick Start when you want the smallest working route → scan → graph → run flow first.
Something feels off?
Inspect scan output, graph state, active route/context, and dispatch in a practical order.
Need the full surface?
Browse all runtime methods, hooks, extension points, and lifecycle APIs.
Start with the browser runtime only. Keep AI disabled until scan, graph, local resolution, and DOM execution work cleanly in your app.
Cinder is browser-first. The fastest path is to install the client SDK, tag one real page, prove the local-first flow, and only then decide whether you need fallback.
Using a coding agent? Skip ahead
Paste this to your agent - it installs the SDK, tags your real app, and configures it on its own, with no further input from you:
Install usecinder in this project (npm install usecinder), then fetch https://usecinder.dev/get-started/prompt.md and follow it completely.See Agent Onboarding for exactly what that does. Otherwise, keep reading for the manual path.
Install the browser SDK
The main browser package is usecinder (the exported singleton is still called Cinder - only the npm package name is usecinder).
npm install usecinderOptional packages
None of these are required for the local-first path - add them only when you need what they do.
| Package | Install when you want | More |
|---|---|---|
@usecinder/embeddings | Tier 2: a free, client-side model that recovers typos/paraphrases before any network call | Tier 2: Embeddings |
@cinder/relay | Tier 3: hosted, metered AI fallback - the only way to add tier-3 fallback | Relay Overview |
@usecinder/cli (dev-only) | Crawl your real app and audit every page for tagging gaps | CLI Overview |
npm install @cinder/relayBrowser-first initialization
Use a local-first config for the first integration:
import { Cinder } from 'usecinder';
await Cinder.init({
semantic: {
scanOnInit: false,
observeMutations: true,
},
ai: {
enabled: false,
mode: 'local',
endpoint: '',
apiKey: '',
},
});Why start this way
- it proves the product core first
- it keeps failure modes easier to inspect
- it prevents fallback from hiding tagging or graph problems
- it makes route/context scoping easier to debug
What the first page should look like
Your first page should be intentionally small:
- one tagged route
- one tagged context
- one tagged action, field, filter, or output
- standard DOM behavior where possible
If the first page is too large, it becomes harder to tell whether a problem comes from tags, graph shape, app timing, custom controls, or unsupported assumptions.
What to do immediately after init
After the runtime is ready:
- add semantic tags to a real page
- call
await Cinder.scan(document) - inspect
Cinder.graph() - execute a first command with
await Cinder.run(...)
await Cinder.scan(document);
console.log(Cinder.lastScan());
console.log(Cinder.graph());
const result = await Cinder.run('open reports', document);
console.log(result.intent, result.dispatch, result.reflex);When to enable fallback
Enable fallback only after the local path is already working for your common commands. Tier-3 AI fallback requires a Relay project - create one, then point ai.endpoint at it:
await Cinder.init({
semantic: {
scanOnInit: false,
observeMutations: true,
},
ai: {
enabled: true,
mode: 'hybrid',
endpoint: 'https://your-relay-host/v1/relay/infer',
apiKey: 'ck_your_relay_project_api_key',
provider: 'custom',
timeoutMs: 10000,
},
});The browser runtime still stays primary. Fallback exists for unknown or weak local understanding, not as the default execution path.
Next steps
Quick Start
Go from install to first scan, graph snapshot, and working command with the minimum useful setup.
Semantic Tags
Learn how to choose stable route/context/action/output keys that help local resolution instead of hurting it.
Tagging a Page
See a practical page shape for routes, contexts, fields, filters, actions, and outputs.
Continue reading