The words this engine uses

Who this is for: whoever writes anything a person reads here — a setting's label, a manual page, a fix line the doctor prints, a tool description a client renders. You need: nothing; this is offline prose and a generated table. Not here: what each setting does (engine-config-surface.md is the per-key reference), or how a component declares settings of its own (writing-a-connector.md).

There were three vocabularies at once. A field could be called Reading model in one place and the model that does the reading in another; the same fact — a value the environment supplies and the page cannot change — was one phrase on a chip and a different phrase in a summary; and half the labels were questions while the other half were noun phrases. Nothing was wrong in any one string. What was wrong is that there was no answer to "what is this called", so every new field invented one.

The manual had the same problem one level up. A person who learned a word on the configuration page met a different word for it in a page of this manual, and an agent reading a tool description met a third.

So the words are declared, and this page is the standard they are declared by. It is generated from revetly.configcopy — the glossary, the banned words, the rival spellings, the US forms, the product terms, the button verbs and the exceptions are that module's tuples. tests/test_config_copy.py holds every label, summary, value word, button, chip and heading on the configuration page to the rules below, and the house lint holds the manual, both READMEs, the templates a scaffolded instance receives, the sentences the doctor prints and the descriptions the MCP surface serves to the machine-checkable half of them. It runs in make check, over this repository's own docs/ and README.

Regenerate this page with:

revetly config --write-copy-standard docs/writing.md

What a rule can and cannot check

Some of what follows a program can decide. A retired spelling, an exclamation mark, a US form, a heading that is a question: each of those is a match or it is not, and the lint fails a build on it.

The rest is judgement. Whether a sentence carries one idea, whether the mechanism is named rather than gestured at, whether the tone is plain: nothing below pretends those are tests. They are stated because a standard that only says what a regular expression can catch teaches the wrong lesson about what good writing here is.

Where each string lives

What one option is called lives on that option — label, summary and reads_as on the Option record in revetly/configspec.py for the engine's own hundred and fifteen, and in each component's SettingsDeclaration for the fifty-two a connector or a verifier declares. A component ships its own settings and cannot reach a table in the engine, so its words travel with it.

Everything else the configuration page says lives in revetly/configcopy.py — the headline, the level headings, the chips, the buttons, the placeholder. A page that hard-codes a sentence is a page whose words cannot be checked.

A generated page is fixed at its source. The table in connector-contract.md, the table in engine-config-surface.md and the block below are rendered from declarations. Editing one of those blocks by hand fails the build; when a generated block carries a word this standard refuses, the fix is the declaration it came from, and then the command that regenerates the page.

Two exceptions are named in the page's own test with their reason, and there are no others: the engine-owned [auth.grants.*] and [auth.tokens.*] tables carry no option record at all, so there is nothing to hold to a standard; and [connectors.todoist] write_project is five words rather than four, because its label has to say both whose project is meant and what it is for.

The hard cases

Most labels write themselves once the glossary exists. A handful did not, and the owner ruled on each by name rather than leaving it to whoever wrote the next one:

• [llm] provider is LLM provider, and [embedding] provider is Embedding provider — naming which half of the vocabulary each answers, rather than the shorter Provider that would say nothing about which one an instance running two providers is looking at.
• [llm] small_model is LLM high-volume model, beside LLM model. The industry's own word for the seat is small model; the label says why somebody would reach for it — volume, cost — rather than what it is called by other people, because that is the question the person answering the field actually has.
• The doctor keeps its real names. A fix line names the key, the file and the variable somebody has to edit. A card never does, because a reader of the page has not opened the file; a person reading a fix line is about to.
• Four retired spellings survive in prose. connector, ingest, the pass and sink are retired on a card and kept in a paragraph, each for the reason in the table below. A manual that will not say revetly ingest cannot explain the command.

Where this holds

One vocabulary, several surfaces. Each rule below says which of these it reaches.

• labels — every option's label, on the configuration page
• summaries — every option's one-sentence summary
• value words — the word a value in a closed set renders as
• buttons, chips and headings — the page's buttons, chips, headline and headings
• prose — the manual under docs/, README.md, the handout README.txt, and the CLAUDE.md and README a scaffolded instance receives
• printed sentences — every sentence revetly doctor, revetly check and revetly init print, each check's fix line, and each provider's and connector's probe
• served descriptions — the tool, prompt and resource descriptions the MCP surface serves

The glossary

Twenty terms. Nothing written here uses a domain word outside this list, and nothing uses a spelling one of them retires.

Term	Means	Replaces
LLM	the model that reads an artifact and extracts facts from it	who does the reading, reading model, reads your sources
embedding	the vector model that turns text into something searchable	who does the searching, the searching half, search model, search address, search key
extraction	the LLM step that turns one artifact into entities, links and statements	read closely, read decisions too, goes through the model
read pass	one run over the sources that puts new artifacts into the graph	the pass, ingest
artifact	one of what Revetly holds — a backlog item, note, commit or document	things, what is saved
source	a system or folder a read pass reads from	what this project reads, connector
project	one namespaced body of work inside an instance	—
instance	one installed Revetly with its own configuration and graph	—
namespace	the stamp every artifact of a project carries	name stamped on what is saved, shared space
records	the backlog items, conversation notes and delivery records Revetly writes itself	saved discussions
classification	a source-declared sensitivity level: public, internal, confidential, restricted	keep private, sensitive
provider	the vendor an LLM or embedding call goes to	who does the reading, who does the searching, sink
endpoint	the base URL a service is called at	search address, where that address is
API key	the credential that pays for provider calls	the key that pays, key seat
backfill	a priced pass over history older than the read floor	how much history, a historical pass
watch	the unattended schedule that keeps read passes running	check for new work, on its own
telemetry	usage data a component sends to its own vendor	phone home, ping its vendor
override	a value that outranks the one set here — from the environment, or a project restating an instance setting	set outside this page, done differently here
token	a bearer credential at a served endpoint, or a personal access token at a source	way in, ways in
withhold	keep an artifact body out of every provider call	kept from the provider, never leaves

The rules

Labels

Reach. every option's label, on the configuration page.

1. One to four words.
2. Sentence case: the first character upper, and no other word capitalised unless it is a product name or an acronym from the lists below.
3. No trailing period, and no question mark or exclamation mark anywhere.
4. Never begins with an interrogative — who, what, where, when, which, how, why, whether, may, can, does, is, are. A label is a noun phrase, not a question the page asks.
5. Holds no pronoun as a whole word.
6. Holds no banned word.
7. Names no identifier: no environment variable, no file name, no TOML table, no shell command. The real name appears in exactly one place, which is All settings.
8. Holds no retired spelling from the glossary.
9. Unique within one subject and topic for the engine's own options, and within one table for a component's.
10. A declared pair differs by exactly its distinguishing token and is otherwise identical.

Summaries

Reach. every option's one-sentence summary.

1. Exactly one sentence: one terminal period, at the end. A semicolon or a dash may join two clauses.
2. Present tense: no will, would, was, were, has been or going to.
3. No second person.
4. The same identifier, banned-word and glossary rules as a label.
5. Names the unit where the option has one.
6. Fifteen words or fewer. A warning and not a failure — a handful genuinely need sixteen, and a build that fails on one is a build nobody trusts.

Value words

Reach. the word a value in a closed set renders as.

1. Every value in a closed set has a word; no value renders as its token.
2. Four words or fewer, sentence case, no terminal period.
3. Two options sharing one closed set share its words character for character.

Buttons, chips and headings

Reach. the page's buttons, chips, headline and headings.

1. A button begins with a verb from the list below and holds no terminal punctuation.
2. A chip is four words or fewer.
3. A heading is four words or fewer.
4. The headline is the only string on the page that is a whole sentence and ends in a period.

Prose

Reach. the manual under docs/, README.md, the handout README.txt, and the CLAUDE.md and README a scaffolded instance receives.

1. Sentence case in a heading: the first character upper, and no other word capitalised unless it is a product name, an acronym or a term somebody else owns.
2. No exclamation mark, anywhere.
3. No question-shaped heading. A heading ending in a question mark, or beginning with an auxiliary English fronts only to ask, is a question. What doctor says is a noun clause and is a heading.
4. No rhetorical question in a paragraph: a question a reader cannot answer is a sentence pretending to be a conversation.
5. One idea per sentence. A sentence over thirty words is reported as a warning and nothing fails — a rule with three clauses is one sentence or three fragments, and a build that refuses a long sentence is a build somebody routes around by splitting one in the wrong place.
6. The mechanism named, not a figure of speech. A component does not phone home, it sends telemetry; a body is not sealed, it is withheld.
7. No first person plural. The reader runs the instance, and we puts a company in the room they did not ask about.
8. A file name, a variable, a table or a command appears in a code span and never in running prose where a plain word says it. The engine reads the doc root rather than the engine reads [docs] roots, unless naming the key is the point of the sentence.
9. UK spelling, by the list of US forms below. A product's own term keeps the product's spelling — an artifact is Revetly's own, an Azure DevOps organization is Azure DevOps's, and a company that is not either of those is an organisation.
10. The glossary's one term per concept, no retired spelling and no banned word — with four real names exempt, listed below.
11. Plain, precise, and addressed to whoever runs the instance. No marketing, and no claim the engine does not make.

Sentences the engine prints

Reach. every sentence revetly doctor, revetly check and revetly init print, each check's fix line, and each provider's and connector's probe.

1. The glossary's terms, no retired spelling, no banned word, no rival spelling and UK spelling — the same words as everything else.
2. The real name stays and the plain word goes beside it. The doctor names the key, the file and the variable somebody has to edit, because a fix line that will not say what to edit is not a fix.
3. A fix line says what to do, not what went wrong: the detail already said that.
4. No exclamation mark, and no question the reader cannot answer.
5. The long form stays. A doctor that abbreviates is a doctor somebody has to decode at the moment they are least able to.

Served descriptions

Reach. the tool, prompt and resource descriptions the MCP surface serves.

1. The glossary's terms, no retired spelling, no banned word, no rival spelling and UK spelling.
2. An argument name, a tool name and a resource URI are the real names and are spelled exactly as the surface serves them.
3. Every surface-wide convention stays where it is — what a read marks as inferred, the history floor, a withheld body, stated before inferred. A description is the only documentation a client has.
4. No exclamation mark, and no first person plural.
5. The whole model-visible surface has a character budget, held by tests/test_folded_surface.py. Saying it once and well is how a description stays under it.

The lists

Banned words. thing, things, stuff, everyday, closely, phone home, sealed, stamped, elsewhere, instead, anyway, differently

Product names. Neo4j, Docker, GitHub, Git, OpenAI, Anthropic, OpenRouter, Cloudflare, Todoist, Azure DevOps, Graphiti, Revetly, CONTEXT, Streamable HTTP, Claude, Claude Code

Acronyms. LLM, API, REST, URL, JWKS, OIDC, PKCE, JWT, MCP, USD, JSON, RSA, PSS, SHA

Button verbs. Show, Hide, Add, Remove, Change, Test, Search, Save, Discard, Apply, Open, Close, Continue, Back, Price, Run, Cancel, Keep

Rival spellings. ingest pass, ingestion, embedder, api key, held back, phone-home, artefact

US forms, and what replaces them. analyze → analyse, analyzed → analysed, authorization → authorisation, authorizations → authorisations, authorize → authorise, authorized → authorised, behavior → behaviour, behaviors → behaviours, canceled → cancelled, catalog → catalogue, catalogs → catalogues, center → centre, centered → centred, color → colour, colors → colours, commoditize → commoditise, customize → customise, defense → defence, episodization → episodisation, favor → favour, fulfill → fulfil, generalize → generalise, gray → grey, initialize → initialise, initialized → initialised, labeled → labelled, labeling → labelling, license → licence, licenses → licences, maximize → maximise, minimize → minimise, modeling → modelling, neighbor → neighbour, normalize → normalise, normalized → normalised, optimize → optimise, organization → organisation, organizations → organisations, organize → organise, prioritize → prioritise, prioritized → prioritised, realize → realise, recognize → recognise, recognized → recognised, serialization → serialisation, serialize → serialise, serialized → serialised, standardize → standardise, summarize → summarise, summarized → summarised, synchronize → synchronise, traveled → travelled, visualize → visualise

Terms somebody else owns

A product's own spelling outranks the UK rule, because a word a reader cannot find in the product has helped nobody.

Term	Owner	Why
organization	Azure DevOps	Azure DevOps names its top-level container an organization, and it is the key an instance sets. A company is an organisation; the Azure DevOps container is not
authorization server	OAuth 2.0	the specification's own term for what this engine trusts, and what every issuer's documentation calls it
Authorization	HTTP	the header's name, spelled the way a request spells it
dialog	MCP	an elicitation dialog is what the client renders and what the protocol's own writing calls it
dialogs	MCP	the plural of the same
Business Source License	MariaDB	the licence's own name; docs/licensing.md quotes its defined terms and cannot respell them
Change License	MariaDB	a defined term of the Business Source License
Change Date	MariaDB	a defined term of the Business Source License, and the date one version of this engine converts on
Apache License	the Apache Software Foundation	the licence's own name
Licensed Work	MariaDB	a defined term of the Business Source License
artifact	Revetly	the glossary's own term, and the spelling of the id, the graph node and every tool argument

Real names the page retires and prose keeps

Each is retired on a card and kept everywhere else, for the reason beside it.

Word	Kept because
connector	the engine's own extension point: a class somebody writes and registers. A card says source because a reader of the page has not written one; the manual that explains how to write one cannot avoid the word
ingest	the name of a command — revetly ingest. A card says read pass for what it does; prose naming the command has to spell it the way somebody types it
the pass	an ordinary back-reference in a paragraph that has already said read pass. On a card there is no earlier sentence to refer back to, so the page spells it in full
sink	the wedge's word for a destination, surviving only in this project's own superseded thinking, which is not rewritten

Rival spellings, and the term that replaces each

Term	Refused	Why
read pass	ingest pass	half the command name and half the term
read pass	ingestion	a noun for which the engine has no gesture
embedding	embedder	the vendor's word for the component; the glossary's word is the call it makes
API key	api key	the acronym is capitalised, on a card and in a paragraph alike
withhold	held back	a phrase that does not say what is kept, or from what
telemetry	phone-home	a figure of speech where the mechanism has a name
artifact	artefact	the product's own term, spelled the way the id, the API and the graph spell it — the one place the UK rule gives way

Sentence length. Over 30 words is reported as a warning and fails nothing.

What is quoted, and what is exempt

A fenced block, an indented block, a code span and anything between double quotation marks are somebody else's words — a vendor's error sentence, a command as typed, a question as asked. The spelling and naming rules do not reach inside any of them. Every other exception is one file, named here with its reason.

File	Not held, because
CHANGELOG.md	history. What a release said it did is the record of that release, and rewriting it would make the record describe a decision taken afterwards
docs/NEXT-STEPS.md	superseded: the roadmap for the wedge, kept for the reasoning in it and shipped to nobody
docs/wedge-pitch.md	superseded: internal positioning for the wedge
docs/customer-discovery.md	superseded: an interview script, quoting the questions as they were asked
docs/requirements-workbench-spec-v2.md	superseded: the build spec for the wedge, now one optional sink
docs/live-loop-spec.md	an agreed spec for a slice, written before it was built and dated
docs/revetly-2.0-context-fabric.md	this project's thinking about the product as a working concept, dated and still moving — not documentation of what a recipient installed
docs/architecture.md	how the engine and Graphiti split the graph, for whoever changes the engine; it names modules and Cypher as the code spells them
docs/glossary.md	this project's measurement vocabulary, for whoever runs the benchmark or the change gate; shipped to nobody
docs/adr/0001-benchmarked-per-job-on-own-workload.md	an architecture decision record, dated and shipped to nobody
docs/adr/0002-exact-match-slots-no-llm-judge.md	an architecture decision record, dated and shipped to nobody
docs/research/memory-tool-benchmarks-2026-10.md	dated research notes quoting other tools' published numbers as they stated them
docs/research/persona-value-estimates-2026-10.md	dated estimates of value per persona, with the measurements they rest on

What the page says

Headline. Configured and running. · One answer still needed. · {n} answers still needed. · Revetly will not start on these settings.

Page headings. This instance · Projects · Instance settings · All settings ({n}), with technical names

Project card regions. Namespace and identity · Sources · Records folders · Approved item store · Item types and parents · Imports and exports · Overrides

Instance sections. LLM and embedding · Extraction and spend · Search and ranking · Sensitivity and withholding · Watch and retries · Git and records · Connections · Authentication and approval · Ports, updates and containers · Project defaults

Instance card lines. Neo4j: connected · Neo4j: not reachable · Neo4j: not tested · LLM and embedding: {provider} · LLM: {llm} · Embedding: {embedding} · Endpoint: answering at {address} · Endpoint: nothing answering · Endpoint: {address}, not tested · Git credentials: {names} · Git credentials: {names} and {n} more · Watch loop: running · Watch loop: not running · Watch loop: off · Last tick

Buttons. Show {n} more · Show · Hide · Add project · Add your first project · Add source · Remove source · Add connection · Add override · Remove override · Change · Change folders · Test · Test connection · Test credential · Remove · Save · Discard · Price a pass · Run a pass · Show issue types · Save issue types

Field chips. Required · Required, not set · Changed from default

Provenance chips. Fixed at startup · Environment override · Saved, not applied · Saved and in use · Never validated · Applies to every project

Controls. Advanced settings · Search settings · Changed from default · Required · No overrides · {n} more with Advanced settings

How a how-to guide is written

One goal per page, the configuration page path first and the command line beside it. The register is Cloudflare's developer documentation. revetly.guidespec states every rule below and tests/test_howto.py runs them over every page under docs/howto/.

The sections

In this order, and no others. Before you start, Configuration page, Command line, Troubleshooting (optional), Next steps.

A page: tutorial page is one path rather than two: Before you start, an H2 per stage numbered in its own heading (## 1. Load the engine), then Troubleshooting and Next steps.

The retired shape is refused by name: ## Steps, ## Check, ## If not, ## Why and a You see: line.

The steps

Numbered from 1 without gaps, in each section separately. One instruction per step, ending in a full stop — or a colon where a block follows. A second sentence clarifies and never acts, so it opens with one of Replace, If, Leave, Wait, Revetly.

A page step opens with one of: Open, Go to, On, In, Select, Enter, Choose, Tick, Untick, Turn on, Turn off, Type, Reload, Wait, Read, Copy, Paste, Leave.

Navigation is written Go to **A** > **B**. A command step carries an sh block, a block typed into a file, or the name of a gesture in a code span.

The words a guide does not use

On top of the lists above: click, navigate, enable, disable, press, hit, tap, button. Link text is never here, this page, read more, click here — it is the target page's own title.

A step that edits a file

A step whose block is toml, env, yaml, yml, ini, json names that file in a code span in its own sentence: revetly.toml, .env, docker-compose.yml, .mcp.json, claude_desktop_config.json, or a [projects.<KEY>] table for revetly.toml.

The block's first line is a comment naming the same file (# revetly.toml). json has no comments, so it keeps the sentence rule and skips the comment rule.

The sentence says where the file lives the first time the page names it: at the project root, beside it.

Placeholders

<UPPER_SNAKE_CASE> in code, blocks and spans alike. A <lower-case> or <Mixed Case> placeholder is refused. Every distinct placeholder is introduced once by Replace `<X>` with …, in its own step or the one before.

Results

A You should see … line sits under the step as its own paragraph. It carries exactly one bold span — a string the page paints — or exactly one code span, a sentence the terminal prints.

A ```txt output block does the same under a command step. Every line of it is a sentence this engine prints, a doctor line, or a line carrying a placeholder.

At most one result line per step, and at least one step in each path carries a result.

Bold

Bold is one of three and never a fourth. A control after a UI verb (configcopy.known_controls()). A string in a You should see line: a control, or a sentence this engine prints. The failure phrase opening a Troubleshooting bullet.

Callouts

:::note (Note), :::tip (Tip), :::caution (Warning). Each opens a line of its own, with an optional [Title], holds one paragraph, and is closed by :::. At most 1 on a page besides the not-on-page note, and at most one link inside one.

Where the page does not do it

The guide keeps its Configuration page heading and carries one :::note reading exactly one of two sentences. Where the page will gain the gesture:

This is not on the configuration page yet. Use the command line below.

Where the page is not the place for it — installing, scaffolding, wiring a client, the authoring gestures, updating, snapshotting, moving:

This is done from the command line, not on the configuration page.

Each is one constant in configcopy, so it reads the same on every such page; the day the page gains a gesture, the first note is deleted and nothing else changes.

Lengths

Before you start: 1 to 3 bullets, each a link, at most 1 a plain condition. Troubleshooting: at most 2 bullets, each opening with the failure in bold and ending in a full stop, then at most 2 sentences of fix. Next steps: 1 or 2 links, no prose. The intro is at most 2 sentences. A sentence over 20 words warns and fails nothing.