Skip to content
Codex
Documentation GitHub
Development Guides

Voice Guide

Last Updated: April 2026 Scope: Codex prose, ADR prose, in-product copy that names the agent or references the world model.

This guide defines how the Inklings documentation refers to the product, the agent, and the worldbuilder — and the cross-link conventions the Codex follows. It is the style companion to the Getting Started orientation page and to the systems/world/* surface.

The rules below exist because Inklings has a small vocabulary that means specific things. Treating the vocabulary sloppily is how product docs drift into generic-agent-framework prose. That prose is not what we are building.

The core vocabulary

World

A world is the authored body of content in a single workspace. One workspace is one world. The word “workspace” is the technical container; “world” is the epistemic content of that container — the canonical, candidate, and private layers plus their connective tissue (provenance, derivation, deviation, revision).

Use “world” when the topic is the content or its epistemic state. Use “workspace” when the topic is the container, its SQLite file, its sync partition, its participant list, or its settings surface.

Never use them interchangeably. A sentence like “the workspace contradicts itself” is wrong; a world can contradict itself, a workspace is a file.

Worldbuilder

A worldbuilder is the human author. Not “user.” “User” is generic product-speak that blurs the distinction between someone who opens the app and someone who is authoring a world — the latter is the audience every Codex page is written for.

When writing Codex prose, default to “worldbuilder.” Use “user” only when the topic is OS-level or account-level (a “user account,” a “user keychain,” a “multi-user” scenario). Marketing copy is not bound by this rule, but the Codex is.

World Agent

The World Agent is the resident participant inside a world. Capitalize both words when referring to it by role: “the World Agent,” “the World Agent’s memory,” “when the World Agent submits a write.”

Lowercase “agent” is acceptable when:

  • You have already introduced “the World Agent” in the same section and are continuing to refer to it (“the agent,” “the agent’s tool call”).
  • You are talking about a generic agent concept from another system (e.g., “LangGraph is an agent framework”) — in that case you are not naming our agent, so don’t capitalize.

Do not use:

  • “Inklings” as a name for the agent. Inklings is the product. When the product and the agent need to be distinguished in the same sentence, call them “Inklings” and “the World Agent.”
  • “the assistant” or “the AI”. Both erase the resident-inhabitant framing.
  • “the bot”. Never.
  • “copilot”. This is a different category of product.

In-product copy that addresses the worldbuilder (status strings, tooltips, settings labels) follows the same rules. “The World Agent is indexing…” is correct. “Inklings is indexing…” is acceptable when it refers to the product as a whole doing something (e.g., downloading the embedding model). “The AI is indexing…” is not.

Zones

The three zones are private, candidate, and canonical. Lowercase in prose. Capitalize only when quoting an enum variant or a type name in code (Zone::Canonical). Never abbreviate them. Never invent synonyms (“draft,” “proposed,” “accepted”) in prose — they lose the link to the type system.

Origin and lifecycle

The two stored provenance axes. Always lowercase in prose. When citing their values, match the type-system casing in code and the prose convention in text:

  • Code: Origin::Human, Origin::Agent, Origin::Import; Lifecycle::Draft, Lifecycle::Candidate, Lifecycle::Canonical, Lifecycle::Retracted.
  • Prose: “human origin,” “agent origin,” “draft lifecycle,” “canonical lifecycle.”

Weight and standing

The two derived signals. Lowercase in prose. Never describe either as “stored” or “persisted” — it is a correctness error. They are computed from origin, lifecycle, derivation links, and deviation records; see provenance.

Submit boundary

Always two words, lowercase, no hyphen (“submit boundary” not “submit-boundary” in prose; the hyphenated form is for filenames and URLs). Refer to the mechanism as “the submit boundary,” the individual write construct as “a WorldWrite,” and the act of going through it as “routing through the submit boundary” or “submitting.”

Do not describe the submit boundary as a “layer” or a “middleware.” It is a domain invariant; those other words imply something architectural can live above or below it, which is exactly what the invariant forbids.

Deviation and derivation

  • A deviation is a recorded conflict between new content and existing canonical content. It is a record type, not a validation error. Never write “deviation error.”
  • A derivation link is a stored relation between content items. “Derivation” (the noun) refers to the relation; “derived from” (prepositional phrase) is how prose usually names an instance.

Retroactive revision

Always use the full phrase the first time it appears in a section. Subsequent references in the same section may shorten to “revision” if no ambiguity arises. Never shorten to “retcon” in Codex prose — that is informal and loses the technical meaning.

Tone

The Codex reader is “someone new, but intelligent.” The prose should read that way:

  • Direct. Lead with the assertion; support it after. Avoid “in order to” when “to” works. Avoid “it should be noted that” entirely.
  • No sales voice. The Codex is not a marketing surface. Don’t use “seamlessly,” “unlock,” “delight,” or “powerful.” If the prose reads like a product page, it is wrong for the Codex.
  • No generic-agent-framework register. Avoid “harness,” “pipeline,” “orchestration layer” as general nouns unless naming a specific component that actually carries that noun as part of its defined vocabulary (e.g., the Context Pipeline, if it is a named component). “The agent orchestrates tools” is vague; “the World Agent dispatches tool calls through MCP” is specific.
  • Short paragraphs. System docs tend toward long paragraphs that re-state things. Cut the restatement.

The Codex has a small set of link patterns. Follow them.

  • Within Codex content: absolute Starlight slugs, e.g. /systems/world/provenance/, /architecture/domain-rules/, /guides/voice-guide/. Trailing slash included. Never use a relative ../ path across top-level sections; relative paths are brittle once pages move.
  • To an ADR: /adr/NNN-slug/ (the NNN is zero-padded to three digits). Example: /adr/017-submit-boundary-invariant/.
  • To a spec in e2e-specs/: /e2e-specs/agent-lifecycle/ etc. These pages are pulled from tests/e2e/specs/ via the codex loader; treat them as first-class Codex pages for link purposes.
  • To a guide in docs/guides/: /guides/<slug>/. The slug is the filename without .md.
  • To external repo files (CONTRIBUTING.md, scripts, tools): full GitHub URL on main, not a relative path from the Codex content directory. The Codex is published as a static site; relative repo paths do not resolve.

Decisions

The world-model decisions file (inklings-world-decisions.md) lives in the planning workspace, not in the Codex. Do not link to it from Codex pages. Reference a decision by number in prose when needed:

This follows decision D31: skills are workspace-scoped portable tools, not world content.

The authoritative published location for decisions is the relevant ADR plus the Codex page that implements the decision. If no ADR covers a decision yet, cite the Codex page directly and omit the D-number.

Worked example

Every systems/world/* primitive page links to the matching anchor in systems/world/worked-example. Use a dedicated “Worked example” section near the end of the primitive page with a single-paragraph lead-in and one link. Do not inline worked-example fragments in primitive pages.

ADRs

When a Codex page cites an ADR, do it inline in prose with a Starlight-slug link:

The submit boundary is the single write-time invariant; see ADR-017.

Each ADR has a “Referenced by” section at the end listing the Codex pages that cite it. When landing or updating a Codex page that cites an ADR, add the Codex page to that section. ADR lifecycle — supersession, deletion, and status — is governed by docs/ADR/README.md; do not restate those rules here or in Codex pages.

Linear epics

In Codex page headers, Reference-epic links use full Linear URLs (https://linear.app/overlund-media/issue/INK-###). Do not shorten to bare INK-### in the header; the short form is fine in inline prose where the link is not the main point.

Examples

Good

The World Agent reads the page, proposes a continuation, and submits the write. The submit boundary stamps Origin::Agent and Lifecycle::Candidate before the write lands. The candidate is visible to the worldbuilder immediately, but is not counted against canonical content.

Direct. Names the agent by role. Uses stored axes at their type-system values. Keeps the submit boundary as a mechanism, not a layer.

When a worldbuilder promotes a candidate block to canonical and the new wording contradicts an existing canonical claim, a deviation record is written. The deviation is not a validation error and does not block the promotion; it is a stored record that the revision queue and the World Agent both consult when deciding how to surface the conflict.

Explicit about the record-type framing. Avoids “error.” Ties back to revision and the agent without overclaiming.

Bad

Inklings uses AI to help you manage your notes. The assistant seamlessly integrates with your workspace to provide powerful search and intelligent suggestions.

Marketing voice. “AI” erases the World Agent. “Seamlessly” and “powerful” are banned words. “Notes” is the wrong noun; this is not a notes app.

The agent harness starts up and connects to the workspace database. On a deviation error, the harness logs and continues.

“Agent harness” is retired naming (the Rust harness is gone; the runtime is the LangGraph sidecar — see agent-core-system). “Deviation error” miscategorizes deviation as a validation failure.

When in doubt

If a phrasing choice is not covered here and it might matter, default to whichever form matches the existing prose in systems/world/index.mdx and systems/world/world-agent.mdx. Those two pages set the voice the rest of the Codex follows. If a choice conflicts with those pages, the pages are correct and this guide should be updated.

Was this page helpful?