> ## 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.

# Style Guide

> Documentation formatting and structural guidelines

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:*
    ```typescript theme={null}
    import type { Tool } from "ai";
    import { tool } from "ai";
    import type { World } from "@wazoo/worlds-sdk";
    import { LocalWorlds } from "@wazoo/worlds-sdk";
    ```
  * *Bad:*
    ```typescript theme={null}
    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:*
    ```typescript theme={null}
    /**
     * 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

* [Mintlify documentation best practices](https://mintlify.com/docs)
* [Google developer documentation style guide: Active voice](https://developers.google.com/tech-writing/one/active-voice)