Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wazoo.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Worlds documentation follows strict editorial guidelines to optimize for developer momentum, technical authority, and zero fluff. Note that “zero fluff” does not mean “zero character.” Clarity is prioritized, but project flavor (such as the memory metaphor) is essential for intuition.

​
File conventions

  • Match existing naming patterns in the directory
  • Use kebab-case (getting-started.mdx) for new files or inconsistent directories

​
Architecture & structural integrity

  • Quality over Quantity: Prioritize concision and ruthless word economy. Every word must earn its keep. Strip stylistic adjectives (e.g., “facts” not “logical facts”) and reduce verbose transitional phrases (e.g., “switch to” not “transition cleanly into using”). If a sentence delivers the same technical weight in fewer words, it must be rewritten.
    • Bad: “By combining these logical, structured facts with a search index, your agent can use semantic search to instantly find the right item, and then transition cleanly into using the RDF graph to reason about everything connected to it.”
    • Good: “By combining facts with a search index, agents can use semantic search to instantly find the right item, and then switch to reasoning over the RDF graph.”
  • Standard Terminology:
    • Worlds API / Platform: The product and interface names.
    • world / worlds (lowercase): Specific knowledge graph instances.
    • engine / context engine: Functional descriptions of the technical processing layer.
    • Verified facts: Technical descriptions of graph state.
    • Memory: Conceptual analogy permitted for developer intuition.
  • Actionable Documentation: Publish pages only when they provide actionable technical value.

​
Writing standards

​
Voice and structure

  • Second-person active voice: Use “you” (“You can write…” not “Developers can write…”).
  • Positive Phrasing: State what to do, not what to avoid.
  • Prescriptive Guidance: Use definitive verbs like must, requires, or use.
  • Timeless Documentation: Write as if the reader is viewing the docs years from now.
  • Global & Inclusive Language: Omit idioms, slang, and exclusionary terms.
  • Sentence-case headings: Use “Getting started” (not “Getting Started”). Keep headings concise; avoid colons.
  • Sentence-case code titles: Use “Expandable example”.
  • Lead with context: Explain what something is before how to use it.
  • Prerequisites first: Place prerequisites at the start of procedural content.
  • Keep markers in body: Keep contextual markers (like dates) in the body text.
  • Contextual examples: Ensure examples remain self-contained.

​
What to avoid

  • Zero Marketing Adjectives: Avoid words like “powerful”, “seamless”, “robust”, or “cutting-edge”.
  • Filler phrases: Omit transitional cliches like “at its core”, “it’s important to note”, or “in order to”.
  • Punctuation cliches: Do not use em dashes (—) as a crutch to connect thoughts.
  • Excessive conjunctions: Omit “moreover”, “furthermore”, or “additionally”.
  • Editorializing words: Omit “obviously”, “simply”, “just”, or “easily”.
  • Generic fluff: Omit generic introductions and concluding summaries.
  • Imaginative phrasing: Avoid anthropomorphic language to describe AI (e.g., avoid “brain”, use “model”). Exception: High-utility metaphors like Memory are permitted to aid developer intuition, though technical descriptions should prioritize terms like Worlds API and Verified facts.
  • Idioms and metaphors: Avoid phrases that obscure precision (e.g., “heavy lifting”).
  • Single-model references: Discuss general capabilities future-proofed by lists (e.g., “Gemini, Claude, or ChatGPT”).

​
Formatting

  • Parentheses: Use sparingly for direct definitions (acronyms).
  • Language tags: All code blocks must have explicit language tags.
  • Alt text: All images and media must have descriptive alt text.
  • Link text: Use descriptive text for links.
  • No styling: Do not use bold or italics in body text. Use meaningful headings and code blocks instead.
  • No decorative emojis: No decorative formatting or emoji.
  • Lists: Use unordered bullets by default. Use ordered lists only for sequences or step-by-step procedures. When a list item defines a term or feature, use a colon to separate the term from its description.
    • Good: “API: Programming interface for worlds.”
    • Bad: “API. Programming interface for worlds.”

​
Code examples

  • Source-Truth Alignment: Method signatures and properties must mirror TypeScript definitions.
  • Keep it simple: Keep examples practical and concise.
  • Realistic values: Use realistic values (avoid “foo” or “bar”). Relational facts should use canonical project examples like user:person and wazoo:organization.
  • Tested code: Verify code works before including it.
  • Import consistency: Group type imports above value imports. When importing from the same path, the import type declaration must appear first.

​
Development standards

​
Exports and namespaces

  • SDK entry points: Use export * in mod.ts files to re-export all public members from submodules.
  • Rationale: This ensures maximum maintainability and reduces manual export management for comprehensive SDK entry points.

​
Imports

  • Import grouping: Group by module source path (e.g., ai, @wazoo/worlds-sdk).
  • Import separation: Mandate separate import type and import declarations per source.
  • Import ordering: When importing from the same path, the import type declaration must appear immediately BEFORE the import (value) declaration.
    • Good: 
      import type { Tool } from "ai";
import { tool } from "ai";
import type { World } from "@wazoo/worlds-sdk";
import { LocalWorlds } from "@wazoo/worlds-sdk";
    • Bad: 
      import { type World, LocalWorlds } from "@wazoo/worlds-sdk";
  • Tree-shaking optimization: Use the most specific module entry points (e.g., import { ulid } from "@std/ulid/ulid").
  • Import path strategy: Use aliases (#/, @/) for cross-package imports. Local relative paths (./) are permitted for files within the same directory or subdirectories. Never use parent relative paths (../).

​
Documentation (JSDoc)

  • Identifier-first descriptions: Descriptions must start with the exact name of the identifier. Use multiline format for readability.
    • Good: 
      /**
 * signOutAction signs out the current user session.
 */
    • Bad: /** Signs out the current user session. */

​
HTTP routes and path parameters

  • Path names match fields: Use the same segment names in routes, OpenAPI, and tests as in your TypeScript properties (for example :slug and {slug}, not :world or {world}, when the resource key is slug).

​
Clean code

  • Early returns: Use guard clauses to handle error conditions early, keeping the primary logic at the shallowest possible indentation level.
  • Focused functions: Functions must have a single responsibility. Decompose functions that are excessively large or handle multiple concerns.
  • Semantic naming: Use precise names for all identifiers. Avoid generic terms like data or res when a domain-specific noun is available.
  • Spelled-out locals: Use full words in variable names, not abbreviations (for example resolvedSource not r, inputNamespace not ns). When a natural name collides with another binding in scope, add a short suffix (for example requestUrl, parsedBody) instead of shortening the word.
  • Immutability: Prefer const over let. Avoid reassigning variables to store different states of the same data.

​
Verification

  • Precommit verification: Always run the relevant precommit task (deno task precommit or npm run precommit:console) before finalizing a commit.

​
Sources and citations