## Summary
- Fix TypeScript view examples to use `ctx.sender` as a property,
matching the server SDK `ViewCtx` API.
- Update the architecture overview TypeScript view snippet to use
`players.rowType` and `undefined` for optional view returns.
- Clarify shared `ViewContext` prose so it does not imply every language
uses a callable `ctx.sender()` API.
- Improve docs agent-readiness metadata:
- publish `/docs/robots.txt` with a docs sitemap directive and
Content-Signal policy
- add Markdown alternate links for the existing `/docs/llms.txt` and
`/docs/llms-full.txt` outputs
- generate `/.well-known/agent-skills`-style discovery metadata under
`/docs/.well-known/agent-skills/` from the repo's existing `skills/`
source files during docs builds
## Validation
- `pnpm --dir docs build`
- `pnpm --dir docs typecheck`
- Verified the docs build emits `robots.txt` and
`.well-known/agent-skills/index.json`.
- Verified generated Agent Skills SHA-256 digests match the emitted
`SKILL.md` artifacts.
## Notes
The Cloudflare agent-readiness scan for `spacetimedb.com` still depends
on the root/marketing host exposing root-level files such as
`/robots.txt`, `/sitemap.xml`, and
`/.well-known/agent-skills/index.json`. This PR makes the docs origin
produce the corresponding docs-scoped artifacts at `/docs/...`; the root
host can route or mirror these if we want the exact `spacetimedb.com`
scan to pick them up.
---------
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: rain <rain@rain.local>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
# Description of Changes
LLM benchmark infrastructure improvements and new benchmark tasks.
**Runner & scoring:**
- Add retry logic with backoff for LLM API calls (rate limits,
502/503/504, timeouts)
- Fix `generation_duration_ms` to only time the successful attempt, not
retries+sleep delays
- Add `--dry-run` flag to run benchmarks without saving results
- Add OpenRouter client as unified fallback when direct vendor keys
aren't set
- Add web search mode via OpenRouter `:online` suffix
- Extract shared OpenAI-compatible response types into `oa_compat.rs`
- Add `ReducerCallBothScorer` for calling reducers on both golden and
LLM databases
- Set `max_tokens` on OpenRouter and Meta clients to prevent silent
truncation
**Model routing:**
- Add `ModelRoute` with display name, vendor, API model, and OpenRouter
model ID
- Support ad-hoc model IDs via `--models vendor:model` without static
registration
- Add model name normalization (OpenRouter IDs, case variants →
canonical display names)
**Context modes:**
- Add `guidelines`, `cursor_rules`, `search`, `no_context` modes with
`is_empty_context_mode()` helper
- Add mode-specific prompt preambles
- Consolidate mode alias normalization (`none`/`no_guidelines` →
`no_context`)
**CI workflows:**
- Add `llm-benchmark-periodic.yml` for scheduled nightly runs with
per-language failure tracking
- **Note**: The periodic workflow requires `OPENROUTER_API_KEY`,
`LLM_BENCHMARK_UPLOAD_URL`, and `LLM_BENCHMARK_API_KEY` as GitHub
secrets.
- Add `llm-benchmark-validate-goldens.yml` for validating golden answers
still compile
**Results & summary:**
- Add `cmd_status` to show incomplete benchmark combinations with rerun
commands
- Add `cmd_analyze` for LLM-powered failure analysis
- Split `normalize_details_file` from `write_summary_from_details_file`
- Derive task categories from filesystem for summary generation
- Add timestamp tracking (`started_at`/`finished_at`) and token usage
**New benchmark tasks:**
- 30 new tasks across auth, data_modeling, queries, basics, and schema
categories
- Updated/fixed existing task prompts and golden answers
# API and ABI breaking changes
None. Internal tooling only.
# Expected complexity level and risk
2 — Changes are scoped to the LLM benchmark CLI tool
(`xtask-llm-benchmark`) and CI workflows. No impact on SpacetimeDB core.
# Testing
- [x] `cargo check -p xtask-llm-benchmark` — zero errors, zero warnings
- [x] Dry run: `llm_benchmark run --lang typescript --modes no_context
--tasks t_001 --models openai:gpt-5-mini --dry-run` — ran end-to-end,
confirmed no results saved to disk
- [ ] Verify periodic workflow runs successfully on next scheduled
trigger
---------
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
# Description of Changes
- Update docs to new designs
<!-- Please describe your change, mention any related tickets, and so on
here. -->
# Screenshots
<img width="1505" height="853" alt="Demo1"
src="https://github.com/user-attachments/assets/227e07d9-8e3b-464f-ad0b-eb39f3f34c63"
/>
<img width="1505" height="854" alt="Demo2"
src="https://github.com/user-attachments/assets/8fdc9418-e41b-477f-a9a2-bc0e075f80ea"
/>
<img width="1508" height="860" alt="Demo3"
src="https://github.com/user-attachments/assets/ad2eed7b-a592-4822-b5d0-165d3d61f30e"
/>
<img width="1501" height="854" alt="Demo4"
src="https://github.com/user-attachments/assets/2ab770d6-005e-44db-ace0-ad09fcced383"
/>
# API and ABI breaking changes
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
# Expected complexity level and risk
2
<!--
How complicated do you think these changes are? Grade on a scale from 1
to 5,
where 1 is a trivial change, and 5 is a deep-reaching and complex
change.
This complexity rating applies not only to the complexity apparent in
the diff,
but also to its interactions with existing and future code.
If you answered more than a 2, explain what is complex about the PR,
and what other components it interacts with in potentially concerning
ways. -->
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] Tested the docs with updated designs
- [ ] <!-- maybe a test you want a reviewer to do, so they can check it
off when they're satisfied. -->
---------
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
# Description of Changes
- Rename `Spacerace` to `Referrals` for docs nav item to align with
updated naming
<!-- Please describe your change, mention any related tickets, and so on
here. -->
# Screenshots
- After:
<img width="1510" height="49" alt="image"
src="https://github.com/user-attachments/assets/3bdbe6ec-8a51-4686-9292-28c38b6d14d9"
/>
- Before:
<img width="1460" height="47" alt="image"
src="https://github.com/user-attachments/assets/5c70b0ef-d5fc-42fa-9dc9-5fd4f034d415"
/>
# API and ABI breaking changes
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
# Expected complexity level and risk
1
<!--
How complicated do you think these changes are? Grade on a scale from 1
to 5,
where 1 is a trivial change, and 5 is a deep-reaching and complex
change.
This complexity rating applies not only to the complexity apparent in
the diff,
but also to its interactions with existing and future code.
If you answered more than a 2, explain what is complex about the PR,
and what other components it interacts with in potentially concerning
ways. -->
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] Docs displays correctly
# Description of Changes
<!-- Please describe your change, mention any related tickets, and so on
here. -->
- Right now if you go to the docs https://spacetimedb.com/docs/ and you
click on spacerace in the upper right it will 404. This PR fixes this
issue.
# API and ABI breaking changes
None
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
# Expected complexity level and risk
1 - just a docs update
<!--
How complicated do you think these changes are? Grade on a scale from 1
to 5,
where 1 is a trivial change, and 5 is a deep-reaching and complex
change.
This complexity rating applies not only to the complexity apparent in
the diff,
but also to its interactions with existing and future code.
If you answered more than a 2, explain what is complex about the PR,
and what other components it interacts with in potentially concerning
ways. -->
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
```
cd docs
npm install
npm run dev
```
- [x] spacerace button works in docs
# Description of Changes
Docs will now go to version 2.0.0 by default, and there is a banner with
a link to the newer docs if someone is viewing the v1 docs.
# Expected complexity level and risk
1. Biggest risk here is breaking links.
# Testing
I tested this locally, and checked that links are working.
There is also a broken link checker in the CI.
# Description of Changes
This change cuts a version of the docs from 1.12.0
(e45cf891c2), and saves it under
`docs/versioned_docs/version-1.12.0`.
If you go to the docs page, it will redirect to the 1.12.0 docs, which
has a banner at the top for trying the prerelease docs:
<img width="1027" height="283" alt="Screenshot 2026-02-20 at 12 07
39 PM"
src="https://github.com/user-attachments/assets/8ff3d622-b693-469a-980a-01c34d0506b8"
/>
If you select the prelease docs, there is a warning banner at the top:
<img width="886" height="299" alt="Screenshot 2026-02-20 at 12 08 52 PM"
src="https://github.com/user-attachments/assets/5508a635-765e-40cc-ad2a-cbbed7f779dd"
/>
# Expected complexity level and risk
This only changes docs.
# Testing
I've testing by running this locally.
# Description of Changes
Major documentation overhaul focusing on tables, column types, and
indexes.
**Quickstart Guides:**
- Updated React, TypeScript, Rust, and C# quickstarts with table/reducer
examples
- Fixed CLI syntax (positional `--database` argument)
- Improved template consistency across languages
**Tables Documentation:**
- Added "Why Tables" section explaining table-oriented design philosophy
(tables as fundamental unit, system tables, data-oriented design
principles)
- Added "Physical and Logical Independence" section explaining how
subscription queries use the relational model independently of physical
storage
- Added brief sections linking to related pages (Visibility,
Constraints, Schedule Tables)
- Renamed "Scheduled Tables" to "Schedule Tables" throughout (tables
store schedules; reducers are scheduled)
**Column Types:**
- Split into dedicated page with unified type reference table
- Added "Representing Collections" section (Vec/Array vs table
tradeoffs)
- Added "Binary Data and Files" section for Vec<u8> storage patterns
- Added "Type Performance" section (smaller types, fixed-size types,
column ordering for alignment)
- Added complete example struct demonstrating all type categories
- Renamed "Structured" category to "Composite"
**Indexes:**
- Complete rewrite with textbook-style documentation
- Added "When to Use Indexes" guidance
- Documented single-column and multi-column index syntax (field-level
and table-level)
- Comprehensive range query examples with correct TypeScript `Range`
class syntax
- Explained multi-column index prefix matching semantics
- Added index-accelerated deletion examples
- Included index design guidelines
**Styling:**
- Added CSS for table border radius and row separators
- Created Check component for green checkmarks in tables
# API and ABI breaking changes
None. Documentation only.
# Expected complexity level and risk
1 - Documentation changes only, no code changes.
# Testing
- [ ] Verify docs build without errors
- [ ] Review rendered pages for formatting issues
- [ ] Confirm code examples are syntactically correct
---------
Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: John Detter <4099508+jdetter@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
# Description of Changes
This PR does several small things:
1. It removes the explicit `h1` tags on every page, and either uses the
side bar title directly, or puts it in the frontmatter
2. It merges what are currently called quickstarts into a single Chat
App Tutorial
3. It creates new quickstarts which just use `spacetime dev --template`
to get you up and running quickly
4. It adds a "The Zen of SpacetimeDB" page much like the Zen of Python
which goes over the 5 key principles of SpacetimeDB
5. It reorders all Tabs groups so that the ordering is `TypeScript`,
`C#`, `Rust`, `Unreal`, `C++`, `Blueprints` (order of decreasing
popularity).
6. It improves the sidebar navigation by having categories act as
overview pages, and also fixes the breadcrumbs
7. It fixes various small typos and issues
8. Closes#3610 and adds cursor rules files generally
9. It fixes general styling on the docs page by bring it inline with the
UI design:
Old:
<img width="1678" height="958" alt="image"
src="https://github.com/user-attachments/assets/f36efee6-b81a-4463-a179-da68b3a7152e"
/>
New:
<img width="1678" height="957" alt="image"
src="https://github.com/user-attachments/assets/f430f77d-0663-47f2-9727-45cbfe10e4c7"
/>
https://github.com/user-attachments/assets/adc5a78a-ada8-45b5-8078-a45cb81477a3
# API and ABI breaking changes
This PR does NOT change any old links. It does add new pages though.
# Expected complexity level and risk
3 - it's a large change. I manually tested the TypeScript Chat App
Tutorial but I have not gone through the Rust and C# quickstarts.
However, we have testing on the quickstarts and this is text only so can
be carefully reviewed.
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] Ran through each step of the Chat App TypeScript tutorial to
ensure it is working
- [x] Ran and tested the styles and the functionality of the side bar
---------
Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: spacetimedb-bot <spacetimedb-bot@users.noreply.github.com>
Co-authored-by: clockworklabs-bot <clockworklabs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
# Description of Changes
The `.png` logo image has been replaced by a `.svg` and needed to be
updated.
# API and ABI breaking changes
Not applicable
# Expected complexity level and risk
0.000001
# Testing
Run `pnpm dev` and check that the logo is correctly displayed in the top
left corner
# Description of Changes
This PR is the first in a series of PRs which are an effort the
reorganize the docs and make it easier for people to get started using
SpacetimeDB.
This PR:
1. Renames all folders to be `kebab-case`. This is because `docIds` are
set based on folder and file names, and there is no way to override that
within a file (all you can change with `id: my-id` is the last component
of the id. Because we want to be able to access docs in react components
we need stable predictable ids.
- This also necessitates setting up a few `_category_.json` files so
that the categories do not show up as kebab case in the sidebar.
2. Adds a few React components with images so it's clearer on how to get
started
3. Reorganizes the quickstarts to be at the top of the side bar and
simplifies the server and client into a single document named for the
language
4. Sets up redirections so the old links to the old documents now point
to the new documents
5. Copies the entirety of `typography.css` from the website into this
repo for the purpose of keeping them identical
6. Makes minor fixes and improvements to the contents of the docs
In a future PR, I intend to:
1. Add a tutorial section to the docs which will include two tutorials:
Blackholio and Chat
2. Turn the chat quickstart documents into the Chat tutorial and
consolidate it into a single file with different language switchers (if
this is feasible)
3. Create a new quickstart section, which has a quickstart guide for
each platform that we support so far, namely:
- Vanilla TypeScript
- Vanilla JavaScript
- Vanilla Rust
- Vanilla C#
- React
- Unity
- Unreal
4. Update the quickstart guides to do the following (in the future I
will add more platforms with this scheme):
- Use `spacetime dev --template <framework-template>` to create a new
project for the given framework
- Insert data into the database
- Add a new `reducer` to the template
- Add a new `table` to the template
- Add a new `view` to the template
- Call the reducer from the client
- Subscribe to the `view` from the template
5. Break up the current per language module reference files into files
about SpacetimeDB concepts with a `TabGroup` for each language, namely:
- Modules
- Tables
- Reducers
- Procedures
- Code generation
- DbConnection (and the SDK API)
- Auth
- etc.
The idea being that we should explain our platform by concept, not by
language. This will also allow us to reuse a lot of prose that is
repeated in the different language documents.
# API and ABI breaking changes
None
# Expected complexity level and risk
1
# Testing
- [x] Tested the documents locally to ensure that they render properly
---------
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
Following discussions about having our Inkeep's API key being public, I
added a comment to all the places where we use it saying that this is OK
and a link to the documentation.
As per Inkeep's documentation:
> When you embed your AI assistant in websites where the user is not
authenticated, like in your public docs, help center, or marketing site,
the web browser is considered a "public client". Since many of these
clients often don't have a backend, the most practical way to use the AI
assistant is for UI components to talk directly to the Inkeep service.
While it is up to your company's own policies and best practices, in
these scenarios, the Inkeep API key is generally ok to be included in
the source code of your web page that is exposed in the browser. This is
similar to how [Algolia's search
service](https://support.algolia.com/hc/en-us/articles/18966776061329-Can-the-search-API-key-be-public)
or [Sentry's error
logging](https://forum.sentry.io/t/how-does-sentry-prevent-spammers/8188)
works.
https://docs.inkeep.com/cloud/ui-components/public-api-keys#public-clients
# API and ABI breaking changes
None
# Expected complexity level and risk
1
# Testing
Ran the docs locally to ensure that the comment isn't visible on the
markdown pages
# Description of Changes
Inkeep's API key for the search bar is the staging one instead of
production, therefore requests made are failing due to an incorrect
referrer.
I've fixed this on `docs/release` quickly after we migrated the new docs
but haven't made a PR to add it to master, due to this the change was
lost on `docs/release` in the last docs release.
I just cherry-picked the commit that I had on my local branch
# API and ABI breaking changes
None.
# Expected complexity level and risk
1
# Testing
Cherry-pick of a commit that was already deployed
# Description of Changes
The GitHub edit links were disabled in the new docs, this reenables
them.
# API and ABI breaking changes
None
# Expected complexity level and risk
1
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] Tested locally that this works.
## Description of Changes
- Migrate the documentation site to **Docusaurus**.
- Add a **GitHub Action workflow** that runs `pnpm build` on pull
requests targeting `master`.
This command checks for broken links and images and ensures the site
builds correctly.
- Add a **GitHub Action workflow** to publish the docs automatically
when a merge occurs on the `docs/release` branch.
**Important**: The workflows haven't been tested yet due to the fact
that they need to be merged first before being able to run. It's a
fairly basic workflow I don't expect this to block anyone but anyways I
will make another PR with the complete changes when I can actually run
it.
---
## API and ABI Breaking Changes
No breaking changes for **SpacetimeDB** users.
Documentation contributors should experience minimal disruption —
content is still written in Markdown.
---
## Expected Complexity Level and Risk
**Complexity:** 3/5
**Reasons:**
1. Several adjustments were made to fit Docusaurus conventions:
- Replaced our custom `:::server-rust` blocks with [Docusaurus `<Tabs/>`
components](https://docusaurus.io/docs/markdown-features/tabs).
- Converted “Note” callouts using
[admonitions](https://docusaurus.io/docs/markdown-features/admonitions)
instead of Markdown blockquotes.
- Updated all images (including Unity tutorial ones, which were
previously commented out).
- Moved images from the DO bucket into the repository at
`docs/static/images`.
2. Customized Docusaurus CSS and one component to apply our theme and
color palette.
---
## Testing
Tested locally.
---
## Review Notes
This PR involves many file changes — a full code review is likely not
productive.
Instead, please focus on verifying that the **documentation content**
was migrated correctly:
- Review sections you’re familiar with to confirm accuracy.
- Ensure formatting, links, and images render as expected.
You can follow the updated **README** for instructions on running
Docusaurus locally.
---------
Signed-off-by: Julien Lavocat <JulienLavocat@users.noreply.github.com>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: = <cloutiertyler@gmail.com>
clockwork-labs-bot