bradleyshep
c12b9a6574
# Description of Changes Fixes stale and missing API guidance in the server skills and core-concepts docs, found by triaging the periodic LLM benchmark (C# and TypeScript both scored 0 passes while all golden answers publish) and cross-referenced against external developer feedback ([SIMPLI FEEDBACK.md](https://github.com/Viivek16/simpli-app/blob/main/FEEDBACK.md)). Key corrections: - **Table accessor casing.** `typescript-server/SKILL.md` and `tables.md` claimed `ctx.db` accessors are the camelCase form of the table name. Since #4263 (2026-02-20) accessors are the literal key passed to `schema({...})`, verbatim. This was the single biggest TS benchmark failure and matches SIMPLI's casing complaint. - **Canonical-first skills.** Both server skills now open with a short complete module and list the full set of imports / column modifiers / attributes. Targets the ~85% of benchmark failures where models emitted the old decorator/attribute API. - **C# gaps.** Fully-qualified `[SpacetimeDB.Index.BTree]` (avoids `System.Index` ambiguity, CS0104); tagged-enum declaration + variant construction (avoids CS8910); scheduled table and reducer kept in one class so `nameof(...)` resolves (CS0103). - **Wrong type name in TS docs.** `ReducerContext` does not exist in TypeScript; models generated it 55x in the benchmark. Skill now names the real type: `ReducerCtx<InferSchema<typeof spacetimedb>>`. - **Rust syntax error.** `Entity { ..existing, name }` does not parse; `..existing` must come last. - **Prefix-scan fix.** A multi-column prefix scan passes the bare leading value, not a shorter array. - **Token/identity guidance.** Corrected the auth notes in three quickstarts and the Unity/Unreal skills: server-issued (not "self-issued") identity, persisting the token keeps identity on reconnect, and the token is non-expiring so production should use an OIDC provider such as SpacetimeAuth. Consistent with the auth doc and FAQ. - Smaller doc touch-ups from SIMPLI feedback: client-binding casing note, reducer-arg array support, RLS how-to. Net: the two server skills are ~74 lines smaller than before. # API and ABI breaking changes None. Docs and skills only. # Expected complexity level and risk 1. Documentation and skill markdown, no code paths touched. The skills ship in the CLI binary (`crates/cli/build.rs`) and sync to `docs/static/.well-known/`, so the only interaction is that these files are embedded at build time. # Testing - [x] Compiled a module exercising the full TypeScript skill surface (builders, modifiers, custom types, indexes, scheduled tables, views, `ReducerCtx` helpers) against `crates/bindings-typescript` at 2.7. The camelCase accessor spelling reproduces the exact CI error. - [x] Traced every C# claim to `crates/bindings-csharp` source or to CI-validated goldens. - [ ] Reviewer: confirm `cd docs && pnpm generate-llms` builds clean (regenerates `llms.md`, fails on broken links). - [ ] Reviewer: sanity-check the next periodic benchmark run shows TS/C# publish failures dropping on the accessor-casing and CS0104/CS8910 tasks.
SpacetimeDB Documentation
This repository contains the markdown files which are used to display documentation on our website. This documentation is built using Docusaurus.
Making Edits
To make changes to our docs, you can open a pull request in this repository. You can typically edit the files directly using the GitHub web interface, but you can also clone our repository and make your edits locally.
Instructions
- Fork our repository
- Clone your fork:
git clone ssh://git@github.com/<username>/SpacetimeDB
cd SpacetimeDB/docs
- Make your edits to the docs that you want to make + test them locally (See Testing Locally)
- Commit your changes:
git add .
git commit -m "A specific description of the changes I made and why"
- Push your changes to your fork as a branch
git checkout -b a-branch-name-that-describes-my-change
git push -u origin a-branch-name-that-describes-my-change
- Go to our GitHub and open a PR that references your branch in your fork on your GitHub
CLI Reference Section
To regenerate the CLI reference section, run pnpm generate-cli-docs.
Docusaurus Documentation
For more information on how to use Docusaurus, see the Docusaurus documentation.
Testing Locally
Installation
- Make sure you have Node.js installed (version 22 or higher is recommended).
- Clone the repository and navigate to the
docsdirectory. - Install the dependencies:
pnpm install - Run the development server:
pnpm dev, which will start a local server and open a browser window. All changes you make to the markdown files will be reflected live in the browser.
Cutting Docs Versions
Use Docusaurus versioning to snapshot the current docs into versioned_docs.
- From
docs/, cut a version:
pnpm docusaurus docs:version <version-name>
Example:
pnpm docusaurus docs:version 1.12.0
This updates:
docs/versions.jsondocs/versioned_docs/version-<version-name>/docs/versioned_sidebars/version-<version-name>-sidebars.json
After cutting, update docs/docusaurus.config.ts as needed:
lastVersionfor the default version at/docsversions.currentlabel/path for prerelease docsversions['<version-name>']label/banner for the stable snapshot
Re-cutting a Version From an Older Commit
If you need a version snapshot from an old commit (instead of current docs/docs), use:
./docs/scripts/get-old-docs.sh <commit> <version-name>
Example:
./docs/scripts/get-old-docs.sh e45cf891c20d87b11976e1d54c04c0e4639dbe81 1.12.0
The script creates a temporary worktree, snapshots docs from that commit, and copies the generated versioned_docs artifacts back into your current branch.
Rewriting Absolute Links to Version-Safe Relative Links
Absolute links like /quickstarts/react can resolve to the default docs version. To keep links inside the current version, rewrite internal links to relative paths.
Dry run:
pnpm --dir docs rewrite-links
Apply changes:
pnpm --dir docs rewrite-links:write
This script rewrites internal absolute links in:
docs/docs(current/prerelease docs)docs/versioned_docs/version-*(all version snapshots)
Adding new pages
All of our directory and file names are prefixed with a five-digit number which determines how they're sorted. We started with the hundreds place as the smallest significant digit, to allow using the tens and ones places to add new pages between. When adding a new page in between two existing pages, choose a number which:
- Doesn't use any more significant figures than it needs to.
- Is approximately halfway between the previous and next page.
For example, if you want to add a new page between 00300-foo and 00400-bar, name it 00350-baz. To add a new page between 00350-baz and 00400-bar, prefer 00370-quux or 00380-quux, rather than 00375-quux, to avoid populating the ones place.
To add a new page after all previous pages, use the smallest multiple of 100 larger than all other pages. For example, if the highest-numbered existing page is 01350-abc, create 01400-def.
Best practices
- Use relative links for linking between documentation pages, as this will ensure that links work correctly with versioning and localization.
License
This documentation repository is licensed under Apache 2.0. See LICENSE.txt for more details