Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: add a standalone style guide (#50742)

Miranda Limonczenko8fa75be01b81
diff --git a/apps/docs/WORD_LIST.md b/apps/docs/WORD_LIST.md
index 38b2bc1b4ad..4b4fa46fe1b 100644
--- a/apps/docs/WORD_LIST.md
+++ b/apps/docs/WORD_LIST.md
@@ -1,955 +1,3 @@
# Supabase documentation word list
-Use this list when you write or review Supabase documentation. It records preferred
-spelling, capitalization, and usage for terms that commonly appear in developer
-documentation.
-
-This list supplements [CONTRIBUTING.md](./CONTRIBUTING.md). If the two documents
-conflict, follow `CONTRIBUTING.md`. Match literal code, API names, UI labels, and
-third-party product names even when they differ from this guidance, and format them
-as code or UI text as appropriate.
-
-The `/write-the-docs` and `/edit-the-docs` agent skills apply this list as you draft.
-
-Every rule here still requires judgment: rewrite the sentence instead of applying a
-replacement that changes its meaning.
-
-## Numbers and symbols
-
-### `+`
-
-Don't use `+` to mean _or later_.
-
-- **Recommended**: Postgres 15 or later
-- **Not recommended**: Postgres 15+
-
-### `&`
-
-Use _and_ instead of `&` in prose, headings, navigation, and tables of contents.
-Keep `&` when it is part of a UI label, code, or a space-constrained table or
-diagram label.
-
-## A
-
-### abbreviations
-
-Spell out an unfamiliar abbreviation on first use. Don't expand familiar technical
-abbreviations such as API, CPU, HTML, HTTP, or SQL unless the audience needs it.
-
-Use `for example` instead of `e.g.` when practical. If space is constrained, write
-`e.g.` with both periods. Use `that is` instead of `i.e.`.
-
-### abort
-
-Use _stop_, _exit_, _cancel_, or _end_ in general prose. Use `abort` when it is the
-name of a command, signal, API, or operation.
-
-### above
-
-Don't use _above_ to refer to a location in a document or UI. Link to or name the
-section or control. For versions, use _later_.
-
-### access
-
-When possible, use a more specific verb such as _view_, _find_, _edit_, _open_, or
-_use_. Keep _access_ when it accurately describes authorization or connectivity.
-
-### admin
-
-Use _administrator_ in prose. Use _admin_ when it is part of a product name, API,
-role, command, or UI label.
-
-### AI
-
-You can use _AI_ without spelling out _artificial intelligence_ when the audience
-is familiar with the term.
-
-### allowlist and denylist
-
-Use _allowlist_ and _denylist_ as nouns. Prefer a precise verb that describes the
-action instead of using either term as a verb.
-
-- **Recommended**: Allow requests from the IP address.
-- **Recommended**: Add the IP address to the allowlist.
-- **Not recommended**: Allowlist the IP address.
-
-Don't use _blacklist_ or _whitelist_.
-When a literal code item contains one of them, format the item as code and explain
-what it does.
-
-### allows you to
-
-Use _lets you_, or make the reader the subject of the sentence.
-
-- **Recommended**: You can query the table.
-- **Recommended**: The API lets you query the table.
-- **Not recommended**: The API allows you to query the table.
-
-### alpha and beta
-
-Use lowercase when describing a release stage. Preserve capitalization when it is
-part of an official product name.
-
-### among and between
-
-Use _between_ for distinct items, even when there are more than two. Use _among_
-for members of a group or items that aren't distinct.
-
-### and/or
-
-Rewrite to use _and_, _or_, or explicitly state that either or both apply.
-
-### API
-
-Use _API_ for a web API or a language-specific API. Don't use _API_ to mean an
-individual method, function, class, or endpoint.
-
-### app and application
-
-Use _app_ for web and mobile software intended for end users. Use _application_
-when it is part of an established term, such as _application programming
-interface_, or when the distinction is technically useful.
-
-### as and since
-
-Use _because_ when you mean causation. _As_ and _since_ can be mistaken for
-references to time.
-
-### authentication and authorization
-
-Authentication verifies an identity. Authorization determines what an
-authenticated identity can access or do. Don't use the terms interchangeably.
-
-Avoid _authN_ and _authZ_ in prose. Use _authentication_ and _authorization_.
-
-### auto-
-
-Follow the spelling established by the relevant technology. Common closed forms
-include _autoscaling_, _autofill_, and _autogenerate_. Don't invent a hyphenated
-variation when an established form exists.
-
-## B
-
-### backend
-
-Write _backend_, not _back-end_ or _back end_.
-
-### base64
-
-Use _base64_ in general prose. Use the capitalization required by a formal name or
-literal code item.
-
-### below
-
-Don't use _below_ to refer to a location in a document or UI. Link to or name the
-section or control. For versions, use _earlier_.
-
-### black-box, gray-box, and white-box
-
-Prefer a description of what the monitoring or testing method can observe. If the
-established term is necessary, define it on first use.
-
-### boolean
-
-Use the spelling and capitalization of the programming-language type when
-referring to code. Use lowercase _boolean_ for the abstract data type and uppercase
-_Boolean_ for Boolean logic.
-
-### button
-
-Use _button_ only for an element that is actually a button. In desktop
-instructions, users _click_ a button. Preserve the exact button label and format
-it in bold.
-
-## C
-
-### can, may, might, must, and should
-
-- Use _can_ for ability, permission, or an optional action.
-- Use _might_ for possibility or an uncertain outcome.
-- Reserve _may_ for policy or legal guidance when possible.
-- Use _must_ or _need to_ for a requirement.
-- Avoid ambiguous _should_. State whether an action is required, recommended, or
- optional.
-
-### checkboxes
-
-Users _select_ and _clear_ checkboxes. Don't use _check_, _uncheck_, or _deselect_
-for these actions.
-
-### click
-
-Use _click_ for buttons, links, and other controls in a desktop interface. Don't
-write _click on_. Use _tap_ when the environment is specifically a touch
-interface.
-
-### click here
-
-Don't use _click here_ or _here_ as link text. Describe the destination or action.
-
-### client
-
-In API documentation, a _client_ is usually an app that sends requests. Don't use
-_client_ as an abbreviation for _client library_ when that could be ambiguous.
-
-Use _concurrent connections_, not _concurrent clients_, when discussing database
-connections.
-
-### codebase
-
-Write _codebase_, not _code base_.
-
-### command-line interface
-
-Name the specific interface, such as _Supabase CLI_. Use _CLI_ after the name is
-clear.
-
-### config
-
-Use _configuration_ in general prose. Keep _config_ when referring to a literal
-file, command, property, or established technical name.
-
-### console and dashboard
-
-Use the product's official name. Don't use _console_ and _dashboard_
-interchangeably, and don't call a UI a dashboard unless it presents a dashboard.
-Use _Supabase Dashboard_ for the Supabase product.
-
-### currently
-
-Avoid _currently_ when the sentence describes the product's present behavior.
-State the behavior directly.
-
-## D
-
-### data
-
-Treat _data_ as a singular mass noun: _the data is_ and _less data_.
-
-### data center
-
-Write _data center_, not _datacenter_.
-
-### data source
-
-Use _data source_ in prose. Preserve `datasource` when it is a code item or
-official product term.
-
-### data type
-
-Write _data type_, not _datatype_.
-
-### deprecate
-
-Use _deprecated_ when use is discouraged, usually because support will end. Don't
-use it to mean _removed_, _deleted_, or _unavailable_.
-
-### dialog
-
-Use _dialog_ for a UI element that presents information or asks for input. Don't
-use _dialogue_ or _popup_.
-
-### directory and folder
-
-Use _directory_ in command-line contexts and _folder_ in graphical interfaces.
-Match the product UI when it uses a specific term.
-
-### disable
-
-Use _disable_ or _turn off_ for an available feature or option. Don't use
-_disabled_ to mean that something is broken or unavailable.
-
-### display
-
-_Display_ is a transitive verb and requires an object.
-
-- **Recommended**: The Dashboard displays the query results.
-- **Recommended**: The query results appear.
-- **Not recommended**: The query results display.
-
-### docs
-
-Use _documentation_ in prose. Use _docs_ in informal contributor instructions,
-repository paths, URLs, or established product names.
-
-### dropdown
-
-Prefer the specific control name, such as _list_ or _menu_. Use _dropdown_ only
-when the distinction matters, and don't use _drop-down_.
-
-### dummy
-
-Don't use _dummy_ for placeholders or sample values. Use _placeholder_, _sample_,
-or a name that describes the value's role. For the statistical concept commonly
-called a dummy variable, use _indicator variable_ or another established,
-context-appropriate term.
-
-## E
-
-### easy, quick, and simple
-
-Avoid claiming that a task is _easy_, _quick_, or _simple_. These words can be
-subjective and usually add no information. Don't use _easy_, _easily_, _quickly_,
-_simple_, or _simply_.
-
-### email
-
-Write _email_, not _e-mail_. Don't use _email_ as a verb; use _send email_.
-
-### enable
-
-Use _enable_ or _turn on_ consistently for activating a feature. When describing
-capability, prefer _lets you_ over _enables you_.
-
-### endpoint
-
-Write _endpoint_, not _end point_. Don't use _endpoint_ when the more specific
-term is _function_, _method_, or _route_.
-
-### enter
-
-Use _enter_ for adding text to a field. Use _type_ only when the physical act of
-typing matters.
-
-### etc.
-
-Avoid _etc._, _and so on_, and _and more_. Introduce a non-exhaustive list with
-_including_, _such as_, or _for example_.
-
-### execute
-
-Use _run_ when it has the same meaning. Keep _execute_ when it is the precise
-technical term, such as an execute permission or query execution plan.
-
-### extract
-
-Use _extract_ instead of _unarchive_, _uncompress_, _untar_, or _unzip_ in prose.
-Preserve literal command names.
-
-## F
-
-### fail over and failover
-
-Use _fail over_ as a verb. Use _failover_ as a noun or adjective.
-
-### filename
-
-Write _filename_, not _file name_.
-
-### file system
-
-Write _file system_, not _filesystem_, unless the latter is part of a code item or
-official name.
-
-### fill in and fill out
-
-Users _fill in_ individual fields and _fill out_ an entire form.
-
-### first person
-
-Address the reader as _you_. Don't use singular first person (_I_, _me_, _my_, or
-_mine_).
-
-Use _we_ only when it clearly refers to Supabase, not when it means the writer and
-reader together.
-
-### foo, bar, and baz
-
-Use meaningful placeholder names that help explain the example. Keep conventional
-placeholder names only when the convention itself is relevant.
-
-### frontend
-
-Write _frontend_, not _front-end_ or _front end_.
-
-## H
-
-### hardcode and hardcoded
-
-Write _hardcode_ and _hardcoded_ without a hyphen.
-
-### health and healthy
-
-When possible, state the observable condition, such as _responding_, _available_,
-or _passing its health check_. Don't use _healthy_ when it could be ambiguous or
-anthropomorphic.
-
-### higher and lower
-
-For version ranges, use _later_ and _earlier_, not _higher_ and _lower_.
-
-### hover
-
-Use _hold the pointer over_ when the reader must wait for the interface to react.
-Use _point to_ when no waiting is required.
-
-### HTTPS
-
-Write _HTTPS_, not _HTTPs_.
-
-## I
-
-### ID
-
-Write _ID_, not _Id_ or _id_, except when matching code. Use _identifier_ when it
-is clearer.
-
-### impact
-
-Use _impact_ as a noun. Prefer _affect_ as the verb.
-
-- **Recommended**: The change affects performance.
-- **Not recommended**: The change impacts performance.
-
-### index
-
-Use _indexes_ as the plural in database documentation. Use _indices_ only in
-domains where it is the established term.
-
-### ingest
-
-Use _import_, _load_, or _copy_ for simple data movement. Use _ingest_ when the
-operation also performs substantial processing.
-
-### in order to
-
-Use _to_ unless _in order to_ is necessary to prevent ambiguity.
-
-### inline
-
-Write _inline_, not _in-line_.
-
-### internet
-
-Use lowercase _internet_ except at the beginning of a sentence.
-
-## J
-
-### just
-
-Remove _just_ when it is filler. If it means _only_ or _previously_, use the more
-specific word.
-
-## K
-
-### key
-
-Don't use _key_ to mean _important_. When referring to a technical key, identify
-the kind of key on first use.
-
-### key-value pair
-
-Write _key-value pair_, not _key/value pair_ or _key value pair_.
-
-### kill
-
-Use _stop_, _exit_, _cancel_, or _end_ in general prose. Preserve _kill_ for
-literal commands, signals, and established technical operations.
-
-## L
-
-### later and earlier
-
-Use _later_ and _earlier_ for version ranges.
-
-- **Recommended**: Version 2.2 or later
-- **Not recommended**: Version 2.2 or higher
-
-### latest, new, and soon
-
-Avoid time-relative descriptions that become stale. Provide a version, date, or
-specific product state instead.
-
-### leverage
-
-Use _use_ or a more specific verb instead of _leverage_.
-
-### lifecycle
-
-Write _lifecycle_, not _life cycle_ or _life-cycle_.
-
-### login and log in
-
-Don't use _login_ or _log in_ in prose. Use _sign in_. See
-[sign in and sign-in](#sign-in-and-sign-in).
-
-## M
-
-### marketing language
-
-Describe measurable behavior instead of making promotional claims. Don't use:
-
-- _best in class_ and _best-in-class_
-- _cutting edge_ and _cutting-edge_
-- _effortlessly_
-- _game changer_ and _game-changer_
-- _hassle free_ and _hassle-free_
-- _powerful_
-- _seamlessly_
-
-### master and slave
-
-Don't use _master_ and _slave_ together. Prefer terms that describe the
-relationship accurately, such as _primary and replica_, _controller and worker_,
-or _publisher and subscriber_.
-
-When a literal code item uses either term, format it as code, explain it, and use
-the preferred term afterward.
-
-### media type
-
-Use _media type_ rather than _MIME type_. Use _content type_ when referring to the
-`Content-Type` HTTP header or when it prevents ambiguity.
-
-### microservices
-
-Write _microservices_, not _micro-services_.
-
-### might
-
-Use _might_ for possibility or an uncertain outcome.
-
-### must
-
-Use _must_ or _need to_ for a requirement. Don't use _must_ for a recommendation.
-
-## N
-
-### native
-
-Use a more precise term when possible, such as _built-in_,
-_platform-specific_, or _compiled_. Don't use _native_ to describe people.
-
-### numbers
-
-Spell out zero through nine. Use numerals for 10 and greater. Use numerals
-regardless for versions, technical quantities, step and page numbers, prices, and
-percentages, and throughout a sentence that mixes a number under 10 with a larger
-one.
-
-- **Recommended**: four options, 24 hours, version 3, 128 bits, step 2, 40%
-- **Not recommended**: 4 options, twenty-four hours
-
-Spell out ordinals. Group digits in large numbers with commas, counting left from
-the decimal point. Write fractions as decimals where practical. Use a hyphen with
-no spaces for a range.
-
-- **Recommended**: first, forty-third, 1,532,784 bytes, 0.75, 2012-2016
-- **Not recommended**: 1st, 1532784 bytes, three-quarters, 2012 - 2016
-
-Omit a count of steps or items unless the count helps the reader plan. Name the
-action or link the heading rather than citing a step or section number.
-
-- **Recommended**: To connect to your database:
-- **Recommended**: After you create the project, copy the project URL.
-
-### numbers in product versions
-
-Write an explicit comparison, such as _version 3.0 or later_. Don't use _newer_,
-_older_, _higher_, _lower_, or a trailing `+`.
-
-## O
-
-### OAuth 2.0
-
-Write _OAuth 2.0_, not _OAuth2_, _OAuth 2_, or _Oauth_.
-
-### obviously and of course
-
-Remove these phrases. They can sound dismissive and don't help the reader.
-
-### once
-
-Use _after_ if that is what you mean. Use _once_ only to mean one time.
-
-### on-premises
-
-Write _on-premises_, not _on-premise_, _on premise_, or _on prem_.
-
-## P
-
-### performant
-
-Use a measurable or specific description, such as _lower latency_, _uses less
-memory_, or _handles more concurrent connections_.
-
-### persist
-
-Avoid using _persist_ as a transitive verb.
-
-- **Recommended**: Store the session.
-- **Recommended**: Make the session persistent.
-- **Not recommended**: Persist the session.
-
-### plain text and plaintext
-
-Use _plain text_ in general contexts. Use _plaintext_ in cryptography.
-
-### please
-
-Don't use _please_ in normal instructions. Use it only when asking permission,
-apologizing for an inconvenience, or requesting an action that primarily benefits
-Supabase.
-
-### plugin
-
-Use _plugin_ as a noun and _plug in_ as a verb.
-
-### popup
-
-Use the specific UI element, such as _dialog_, _menu_, or _window_. Don't use
-_popup_ or _pop-up_ as a generic noun.
-
-### Postgres
-
-Use _Postgres_, not _PostgreSQL_, outside code and literal third-party names.
-
-### powered by
-
-Don't use _powered by_. Prefer _with_, _by_, or _through_, depending on the
-relationship.
-
-### prior to and subsequent to
-
-Use _before_ and _after_.
-
-## R
-
-### read-only
-
-Always hyphenate _read-only_.
-
-### Realtime
-
-Capitalize _Realtime_ when referring to the Supabase product. Use lowercase
-_real-time_ as an adjective with its ordinary meaning.
-
-### repository
-
-Prefer _repository_ in documentation prose. _Repo_ is acceptable in informal
-contributor instructions and when space is constrained.
-
-### retry
-
-Use _retry_ as a verb or noun. Write around _retriable_, _retryable_, _triable_,
-and _tryable_ when practical.
-
-### run time and runtime
-
-Use _runtime_ for an execution environment. Use _run time_ for the time when a
-program runs or the duration of a run.
-
-## S
-
-### sanity check
-
-Use _preliminary check_, _confidence check_, or a description of what the check
-validates.
-
-### screenshot
-
-Use _screenshot_ as a noun. Use _take a screenshot_, not _screenshot_ as a verb.
-Redact secrets and personal information from screenshots.
-
-### select
-
-Use _select_ for choosing an item, selecting text, or marking a checkbox. Preserve
-the exact UI label in bold.
-
-### sensitive and confidential
-
-_Sensitive data_ is data whose disclosure might cause harm. _Confidential data_ is
-protected against unauthorized access. Use the term that describes the relevant
-risk or control.
-
-### setup and set up
-
-Use _setup_ as a noun or adjective and _set up_ as a verb.
-
-- **Recommended**: Complete the setup to set up authentication.
-- **Not recommended**: Setup authentication.
-
-### sign in and sign-in
-
-Use _sign in_, _sign out_, and _sign up_ as verbs. Use the hyphenated forms
-_sign-in_, _sign-out_, and _sign-up_ as nouns or adjectives. Match the product UI
-labels **Sign in**, **Sign out**, and **Sign up**.
-
-Keep _login_, _log in_, _logout_, _log out_, and `logOut` when quoting
-third-party UI or when they are part of code, routes, URL slugs, CLI commands, or
-established feature names such as _social login_.
-
-### singular they
-
-Use _they_, _them_, and _their_ as gender-neutral singular pronouns. Don't use
-_s/he_, _he/she_, _(s)he_, or _him/her_.
-
-### slang abbreviations
-
-Don't use internet slang in documentation, such as _tl;dr_, _ymmv_, _rtfm_, _imo_,
-or _fwiw_.
-
-### spin up
-
-Use _create_ or _start_ unless you are literally describing a spinning disk.
-
-### SQL
-
-Write _a SQL query_, not _an SQL query_. Use lowercase SQL keywords in code
-examples unless uppercase is required by the surrounding convention.
-
-### SSH
-
-Don't use _SSH_ or `ssh` as a verb.
-
-- **Recommended**: Connect to the server by using SSH.
-- **Recommended**: Use the `ssh` command.
-- **Not recommended**: SSH into the server.
-
-### startup and start up
-
-Use _startup_ as a noun or adjective and _start up_ as a verb.
-
-### Supabase
-
-Capitalize _Supabase_ outside code. Use _Supabase Platform_ with both words
-capitalized. Match literal package names, commands, URLs, and code.
-
-## T
-
-### table name
-
-Write _table name_ as two words. Format a specific table name as code.
-
-### target
-
-Avoid using _target_ as a verb for people. Use _intended for_, _designed for_, or
-another description of the audience.
-
-### terminate
-
-Use _stop_, _exit_, _cancel_, or _end_ unless _terminate_ has a specific technical
-meaning in the documented context.
-
-### third party and third-party
-
-Use _third party_ as a noun and _third-party_ as an adjective. Don't abbreviate
-either form with `3rd`.
-
-### this and that
-
-Add a noun after _this_ or _that_ when the reference could be unclear.
-
-- **Recommended**: This setting controls connection pooling.
-- **Not recommended**: This controls connection pooling.
-
-### timeout and time out
-
-Use _timeout_ as a noun or adjective and _time out_ as a verb.
-
-### timestamp
-
-Write _timestamp_, not _time stamp_.
-
-### time zone and time-zone
-
-Use _time zone_ as a noun and _time-zone_ as an adjective.
-
-### toggles
-
-Users _enable_ and _disable_ features with toggles. Match and bold the visible
-label. Don't instruct the reader to _click the toggle_ when the intended state can
-be stated directly.
-
-## U
-
-### UI
-
-Use the specific interface or page name when possible. Use _UI_ only when
-discussing a user interface as a general concept.
-
-Match visible UI labels exactly and format them in bold. Describe the element with
-the correct noun when it improves clarity, such as _the **Connect** button_ or
-_the **Database password** field_.
-
-### URL
-
-Use _URL_, not _web address_, when writing for developers. Use descriptive link
-text rather than exposing a URL unless the URL itself is the subject.
-
-### user
-
-Address the reader as _you_. Use _user_ for a person who uses the software that
-the reader is building or administering.
-
-### utilize
-
-Use _use_, not _utilize_ or _utilise_. Use _utilization_ only when referring to the
-measured proportion of a resource in use.
-
-## V
-
-### vague verbs
-
-Describe the concrete action:
-
-- _view and resolve errors_ instead of _handle errors_
-- _create, edit, or delete tables_ instead of _manage tables_
-- _query and update data_ instead of _work with data_
-
-Choose a different precise verb if the suggested replacement doesn't match the
-actual operation.
-
-### vCPU
-
-Use _vCPU_ (plural _vCPUs_) for the CPU resources of Supabase compute sizes.
-Don't describe Supabase compute in _cores_.
-
-_Core_ remains correct for hardware the reader owns or manages, such as
-self-hosting requirements or a migration VM, and in general CPU discussion.
-
-- Recommended: The 16XL compute size has 64 vCPUs.
-- Recommended: Run the migration from a VM with 8 CPU cores.
-- Not recommended: The 16XL compute size has 64 cores.
-
-### versus
-
-Write _versus_ in prose, not _vs._ Use `vs` only when it is part of a literal name
-or when space is constrained.
-
-## W
-
-### web
-
-Use lowercase _web_. Use the capitalization established by formal names such as
-_WebAssembly_.
-
-### we
-
-Don't use _we_ to mean the writer and reader together. Use _you_ for the reader.
-_We_ is acceptable when it unambiguously means Supabase.
-
-### while
-
-Use _while_ for events that occur at the same time. Use _although_ or _whereas_
-for contrast. Use _while_, not _whilst_.
-
-### will and would
-
-Use present tense for current product behavior. Use _will_ for an actual future
-event, not a predictable result. Replace _would_ with _can_ when describing
-capability.
-
-### workload
-
-Use a more specific term, such as _app_, _service_, _database_, or _job_, when the
-meaning is known. If _workload_ is the established technical term, define its
-scope on first use.
-
-## Y
-
-### you
-
-Address the reader as _you_. Use _user_ only for a person who uses the software
-that the reader is developing or administering.
-
-## Phrase groups
-
-The alphabetical entries explain the intent behind each rule. This section collects
-the full term lists in one place, grouped by the problem they cause.
-
-### Filler
-
-Don't use _actually_, _easily_, _easy_, _just_, _let's_, _obviously_,
-_of course_, _please_, _quickly_, _simple_, _simply_, or _that's it_. Remove the term or state the intended meaning directly.
-_please_ is the exception: keep it when asking permission, apologizing for an
-inconvenience, or requesting an action that primarily benefits Supabase.
-
-### Marketing language
-
-Don't use _best in class_, _best-in-class_, _cutting edge_,
-_cutting-edge_, _effortlessly_, _game changer_, _game-changer_, _hassle free_,
-_hassle-free_, _powerful_, or _seamlessly_. Describe specific behavior or
-measurable results instead.
-
-### Vague verbs
-
-Use _view and resolve errors_ for _handle errors_, _create, edit, or delete tables_
-for _manage tables_, and _query and update data_ for _work with data_. Use a
-different precise replacement when none of these match the operation.
-
-### Apologies
-
-Don't use _oops_ or _sorry_. State what happened directly. Apologize
-only when an apology is genuinely useful to the reader.
-
-### First person
-
-Don't use _I_, _I'm_, _me_, _my_, or _mine_. Address the
-reader as _you_ and use an explicit noun for other actors.
-
-### Gender-neutral pronouns
-
-Don't use _s/he_, _he/she_, _(s)he_, or _him/her_. Use the
-singular _they_ or rewrite the sentence.
-
-### Inclusive language
-
-Don't use these terms:
-
-- _mankind_: use _humankind_ or _people_
-- _manmade_: use _manufactured_, _artificial_, or _synthetic_
-- _middleman_: use _intermediary_
-- _blacklist_: use _denylist_ or a more precise term
-- _whitelist_: use _allowlist_ or a more precise term
-
-### Abbreviations
-
-Write _e.g._ with both periods, not _eg._ or _eg_. Replace _i.e._, _ie._, and
-_ie_ with _that is_. Prefer _for example_ and _that is_ in prose when space
-allows.
-
-### Powered by
-
-Don't use _powered by_. Use _with_, _by_, or _through_, depending on the
-relationship.
-
-### Preferred usage
-
-Use:
-
-- _Postgres_ for _PostgreSQL_
-- _concurrent connections_ for _concurrent clients_
-- _use_ for _utilize_ and _utilise_
-- _uses_ for _utilizes_ and _utilises_
-- _using_ for _utilizing_ and _utilising_
-
-### Direct, concise language
-
-Don't use these phrases:
-
-- _aforementioned_: name the item
-- _amongst_: use _among_
-- _endeavor_ or _endeavour_: use _try_
-- _facilitate_: use _help_ or describe the action
-- _for the purpose of_: use _to_
-- _in order to_: use _to_
-- _leverage_: use _use_ or a more precise verb
-- _prior to_: use _before_
-- _subsequent to_: use _after_
-- _whilst_: use _while_
-
-### Internet slang
-
-Don't use _tl;dr_, _ymmv_, _rtfm_, _imo_, or _fwiw_. Write out the
-meaning or remove the aside.
-
-## Attribution
-
-Portions of this word list are modifications based on work created and shared by
-Google and used according to the terms of the
-[Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).
-See the
-[Google developer documentation style guide word list](https://developers.google.com/style/word-list)
-for the original work. Supabase-specific guidance and adaptations are maintained
-in this repository.
+This file moved to [`style-guide/WORD_LIST.md`](./style-guide/WORD_LIST.md).
diff --git a/apps/docs/style-guide/01-voice-and-tone.md b/apps/docs/style-guide/01-voice-and-tone.md
new file mode 100644
index 00000000000..2c9ccfebf2f
--- /dev/null
+++ b/apps/docs/style-guide/01-voice-and-tone.md
@@ -0,0 +1,241 @@
+# Voice and tone
+
+Our voice and tone are clean and straightforward. Elegant prose is succinct: it brings a
+reader to understanding without spending extra words.
+
+Apply this document to every sentence you write, whether you're drafting a page or
+changing one line on an existing one.
+
+It covers the sentence level. For how a page divides into sections, see
+[`03-page-structure.md`](./03-page-structure.md). For which component renders a piece of
+information, see [`02-elements.md`](./02-elements.md).
+
+| If you're deciding | Read |
+| ---------------------------------------- | ----------------------------------------------- |
+| How to mentally frame how you write | [Audience](#audience) |
+| How to write sharper and more succinctly | [Brevity](#brevity) |
+| How to write consistently and correctly | [Sentence construction](#sentence-construction) |
+
+## Audience
+
+### Write for the reader
+
+The reader is a developer with a job to do, arriving mid-task from a search result
+rather than from the top of the page. Their Postgres experience ranges from none to
+deep, and they may be evaluating Supabase or already running it in production. Think
+about the task they came to complete. Tell them what, and only what, they need to know
+to finish it.
+
+### Write for a massive global audience
+
+Many readers have a native language that isn't English. Conversational, direct English
+is easier to understand, localize, and read aloud.
+
+### Write for a human and an LLM at once
+
+Both read our pages. Some principles overlap while others don't. For a human, be kind
+and respect their free will. For an LLM, you may need to nudge it to choose the best
+practice. Use clean procedures and lots of code examples to make the best path the
+easiest choice.
+
+### Write like you talk
+
+Many readers who use English as an additional language learn conversational rather than
+academic English. Use words and sentences that sound natural when spoken. Read your
+writing out loud to find the clearest phrasing.
+
+### Avoid idioms and colloquialisms
+
+A phrase like `piece of cake` is often specific to a region or culture.
+
+### Don't use ableist language
+
+Words that use disability as a metaphor for something bad exclude the readers they
+describe.
+
+### Address the reader as `you`
+
+Don't use `we` to refer to the reader. Use `we` only to refer to the Supabase team.
+
+## Brevity
+
+### Prefer short, direct sentences
+
+Express one relationship at a time and avoid unnecessary compound structures. Each
+sentence gets easier to understand, localize, and interpret consistently.
+
+Aim for fewer than 26 words per sentence. Past that, a reader has to hold too much at
+once, and a listener using a screen reader has no way to scan back.
+
+### Omit needless words
+
+Cut every word that does no work. The replacements below recur often enough to be worth
+memorizing.
+
+| Wordy | Direct |
+| ------------------------------ | -------- |
+| the question as to whether | whether |
+| is able to, has the ability to | can |
+| in the event that | if |
+| at this point in time | now |
+| make a decision about | decide |
+| provides support for | supports |
+
+### Cut repeated points
+
+If you can remove a sentence without losing information, remove it. Watch for a section
+that restates what an earlier section established, and for three phrasings of one idea:
+`It's free`, `You won't be billed`, `No charge`.
+
+### Use the positive form
+
+State what something does. A positive sentence is shorter and tells the reader what to
+do next. Double negatives and nested exceptions are the hardest version of this to read.
+
+- **Recommended**: `You can continue without a path.`
+- **Not recommended**: `A missing path won't prevent you from continuing.`
+
+- **Recommended**: `Use an admonition when a reader might otherwise miss information that affects their outcome.`
+- **Not recommended**: `Don't use an admonition unless a reader might otherwise miss information that affects their outcome.`
+
+### Cut mannered prose
+
+Some sentences exist to sound composed. They carry nothing, and these three are the
+common shapes:
+
+- **Antithesis.** `X, not Y`, where Y is the negation of X. The negative half feels
+ balanced and adds no information, and the sentence after it usually explains the point
+ properly anyway. Delete the half after the comma and check whether anything was lost.
+- **Rhythm for its own sake.** Three examples where two would do, or a clause added to
+ balance a sentence.
+- **The aphoristic closer.** A final sentence that restates the paragraph in a
+ tidier shape. The paragraph already said it.
+
+Contrast is worth keeping when both halves are real and the reader needs the comparison.
+A recommended and not-recommended pair qualifies, as does a concrete substitution like
+`select` rather than `SELECT`.
+
+- **Recommended**: `Write alt text that describes the image. A topic name is what the nearby heading already says.`
+- **Not recommended**: `Write alt text that describes the image, not the topic.`
+
+### Be specific and concrete
+
+A vague verb makes the reader guess at the operation. Name the operation instead.
+
+- **Recommended**: `Create, edit, and delete tables in the Table Editor.`
+- **Not recommended**: `Manage your tables in the Table Editor.`
+
+[`WORD_LIST.md`](./WORD_LIST.md) lists the vague verbs that come up most often. The
+principle extends past that list: if a verb could describe five different operations,
+it's the wrong verb.
+
+### Keep coordinate ideas parallel
+
+List items and procedure steps are coordinate ideas, so give them the same grammatical
+form. A step list that mixes imperatives with descriptions reads as though the steps do
+different kinds of work.
+
+- **Recommended**: `Install the CLI`, `Start the local stack`, `Apply the migration`
+- **Not recommended**: `Install the CLI`, `The local stack starts next`, `Applying the migration`
+
+### Put the emphatic words at the end of the sentence
+
+The end of a sentence is where a reader's attention lands, so put the consequence there
+rather than in the middle.
+
+- **Recommended**: `A table with Row Level Security enabled and no policy returns no rows to every client.`
+- **Not recommended**: `Every client gets no rows back from a table that has Row Level Security enabled and no policy, which is worth knowing.`
+
+## Sentence construction
+
+### Cover one topic in each paragraph
+
+Start a new paragraph when the topic changes, or when you move between [information
+types](./03-page-structure.md). Short paragraphs are fine.
+
+Break up a dense paragraph rather than leaving it whole. A wall of text is hard to scan.
+It is harder still for a reader who is listening to it, or who has trouble keeping their
+place. When one paragraph carries several points, split it, or turn the points into a
+list.
+
+### Use complete sentences by default
+
+They identify the actor and the action, which reduces ambiguity for readers,
+translators, and agents. Use sentence fragments only where they improve scanning, such
+as headings, labels, or short list items.
+
+### Don't rely on a heading to carry meaning
+
+Headings guide the reader's eye and organize the page, but the content beneath one has
+to stand on its own. The first sentence can restate the heading, even if that sounds
+redundant. Readers skim headings and then return to the section that interests them, so
+the opening sentence is what confirms they're in the right place.
+
+### Keep important information out of parentheses
+
+Some readers skip anything parenthesized, so a step they need can't live there.
+
+Reach for parentheses when the content is brief and genuinely supplementary:
+
+- Introducing an acronym after spelling it out: `full-text search (FTS)`
+- Marking an item `(Optional)`
+- A short example inside a step: ``Enter a six-digit hex number (for example, `228B22`), and then select **OK**.``
+
+Rewrite as a separate sentence when the aside grows past a few words, or when it carries
+something the reader has to act on:
+
+- **Recommended**: ``Enter a six-digit hex number, and then select **OK**. For example, for forest green, enter `228B22`.``
+- **Not recommended**: ``Enter a six-digit hex number (for example, if you want the color forest green, enter `228B22`), and then select **OK**.``
+
+Don't use parentheses for optional plurals. Write `one or more tables`, not `table(s)`.
+Parentheses required by Markdown links or code syntax aren't prose parentheticals.
+
+### Don't bound an aside with dashes where a direct sentence reads better
+
+A pair of dashes interrupts the sentence the same way parentheses do, and the
+interruption is usually a second sentence trying to escape. Google allows a dash in
+place of parentheses; Supabase docs prefer the separate sentence.
+
+- **Recommended**: `Don't add steps to reach a minimum. The range organizes information; it isn't a required length.`
+- **Not recommended**: `Don't add steps to reach a minimum — the range organizes information, it isn't a required length.`
+
+### Put the condition before the instruction
+
+When an action only applies in some cases, name the case first. A reader who sees the
+condition up front can skip the whole sentence. A reader who meets it at the end has
+already read the instruction for nothing.
+
+- **Recommended**: `To delete the entire document, click **Delete**.`
+- **Not recommended**: `Click **Delete** if you want to delete the entire document.`
+- **Recommended**: `For more information, see [Row Level Security](/docs/guides/database/postgres/row-level-security).`
+- **Not recommended**: `See [Row Level Security](/docs/guides/database/postgres/row-level-security) for more information.`
+
+The same order applies to a procedure step that branches. Put the `if` first, so a
+reader can pass over a step that isn't theirs.
+
+### Don't refer to the position of something on the page
+
+`Above`, `below`, and `the right-hand side` assume a reader who sees the page laid out
+the way you do. Position also changes with screen size and breaks when content moves.
+
+- **Recommended**: `In the preceding diagram, the client calls the pooler.`
+- **Not recommended**: `In the diagram above, the client calls the pooler.`
+
+#### Spell out an abbreviation on first use
+
+The exception is an abbreviation as familiar as `API` or `SQL`. Write full-text search
+(FTS) once, then use `FTS`. A screen reader may read an unfamiliar abbreviation as a
+word.
+
+### Use the Oxford comma
+
+Write `functions, tables, and indexes`.
+
+### Use American English
+
+Write `color, organize, center, and artifact`.
+
+### Use the present tense
+
+Write `the AI assistant answers your question` rather than `the AI assistant will answer
+your question`.
diff --git a/apps/docs/style-guide/02-elements.md b/apps/docs/style-guide/02-elements.md
new file mode 100644
index 00000000000..ea9085ba8f5
--- /dev/null
+++ b/apps/docs/style-guide/02-elements.md
@@ -0,0 +1,463 @@
+# Choose your components
+
+Once you know what kind of information you have, this is the catalog of forms it can
+take. Each entry leads with when the component is warranted, then its syntax.
+
+"Component" means the MDX components the docs app provides, such as `<Admonition>` and
+`<Tabs>`. "Element" means a plain Markdown construct, such as a list or a heading.
+
+| If you're deciding | Read |
+| -------------------------------------------------------- | --------------------------------------------- |
+| Which form the information should take | [Choosing a component](#choosing-a-component) |
+| How to handle admonitions, emphasis, headings, and lists | [Text](#text) |
+| How to write steps, code, and tabs | [Steps and code](#steps-and-code) |
+| How to show structured data or a diagram | [Data and diagrams](#data-and-diagrams) |
+| How to add an image or a video | [Media](#media) |
+| How to link out or list related pages | [Navigation](#navigation) |
+| Which constructs to leave out | [Don't use these](#dont-use-these) |
+
+## Choosing a component
+
+Start from the information type, per [`03-page-structure.md`](./03-page-structure.md).
+
+| You have | Reach for |
+| ------------------------------------------------- | -------------------------------------------------- |
+| Actions the reader performs in order | A [procedure](#procedures) |
+| A stage-by-stage explanation | Prose, or a when/then [table](#tables) |
+| The parts of something | A [table](#tables) or a [diagram](#diagrams) |
+| A warning or a rule the reader must not miss | An [admonition](#admonitions) |
+| A definition or an idea | Prose, a [list](#lists), or a [diagram](#diagrams) |
+| Alternative instructions per platform or language | [Tabs](#tabs) |
+| A curated set of links on an index page | A [content listing](#content-listings) |
+
+When a phrase fits more than one category, pick the most specific one.
+
+## Text
+
+### Admonitions
+
+#### Use an admonition for information a reader might otherwise miss
+
+Reach for one when missing the information would change the outcome of the task. Use
+one to separate helpful but optional guidance from the main flow. Don't
+use one for information that belongs in the main explanation or procedure. They
+highlight important information and get less effective when overused, so don't stack
+them or use them as decoration.
+
+#### Begin every admonition with its impact and purpose: the "so what."
+
+Use the first sentence to tell the reader why the information matters: what could
+happen, what changes, or what benefit they gain. Add background or instructions after
+the impact is clear.
+
+- **Recommended**: `Deleting this project permanently removes its database and backups. Export any data that you want to keep before you continue.`
+- **Not recommended**: `Before you continue, there are a few things that you should know about project deletion.`
+
+#### Don't restate an admonition in the body text
+
+An admonition and the paragraph next to it should cover distinct points. A risk stated
+twice reads as an editing mistake and trains readers to skip the box.
+
+Choose the `type` that matches the severity:
+
+| Type | Use for |
+| ------------- | ------------------------------------------------------------------- |
+| `danger` | Data loss, exposed data, or another severe, hard-to-reverse outcome |
+| `deprecation` | A deprecated feature or behavior |
+| `caution` | Bugs, failed operations, or unexpected results, short of `danger` |
+| `note` | A prerequisite, constraint, or clarification that carries no risk |
+
+For `danger` and `caution`, state the consequence first, then how to avoid it. For
+`deprecation`, state how the change affects the reader, then the migration path. When a
+note is essential to completing a step, put it in the procedure instead of an
+admonition.
+
+Structure an admonition with these props:
+
+- `title` (optional): a short callout title. Don't put Markdown or HTML headings
+ inside an admonition. If the content needs a heading to structure the page, move the
+ heading and its section outside the admonition.
+- `children`: rich body content such as paragraphs, lists, links, and code.
+- `actions` (optional): standalone calls to action, kept separate from the body.
+ Contextual links and interactive examples stay in the body when they're part of the
+ explanation.
+
+```mdx
+<Admonition type="note" title="Optional title" actions={<Button>Continue</Button>}>
+
+Your content here
+
+</Admonition>
+```
+
+### Emphasis
+
+#### Use bold, italics, and code for distinct purposes
+
+Don't use them interchangeably or to add visual emphasis alone.
+
+| Format | Use for |
+| --------- | --------------------------------------------------------------- |
+| **Bold** | A UI label, a term the reader must not miss, or an inline label |
+| _Italics_ | A new term on first definition, or a title |
+| `Code` | Anything typed, copied, or read literally by the system |
+
+Bold covers the controls a reader interacts with, such as buttons, menu items, and
+field names: `Click **Save**.` It also marks a term they can't afford to skip, as in
+`**Never** commit your service role key.` The third case is the label opening a
+paragraph or list item, as in `**Recommended**:`.
+
+Use italics sparingly, and never for a UI label or for general emphasis. A title set in
+italics by convention, such as a book or a third-party product, is the other case.
+
+Code covers filenames, paths, commands, flags, environment variables, function and
+parameter names, configuration keys, and literal values.
+
+A command name is `code`, not **bold**, even though the reader also interacts with it.
+
+Don't format for emphasis beyond these three. Screen readers announce text
+modifications, so a sentence carrying several kinds of formatting is read aloud with the
+formatting narrated between the words.
+
+#### Name a control by its label
+
+An icon has no accessible name a reader can match against what you wrote. Write `Click
+**Notifications**` rather than `Click the bell icon`.
+
+### Headings
+
+#### Format headings in sentence case
+
+Capitalize the first word and any proper nouns, and lowercase everything else: `Set up
+authentication` rather than `Set Up Authentication`.
+
+A heading can't carry meaning on its own. See
+[`01-voice-and-tone.md`](./01-voice-and-tone.md).
+
+Headings are also anchor targets. Other pages, `apps/www`, and Studio all deep-link into
+guide anchors, so renaming a heading breaks those links. Moving a section or changing
+its level preserves the anchor; only renaming breaks it.
+
+### Lists
+
+#### Choose the list type by whether order matters
+
+Use an ordered list for steps taken in sequence, and an unordered list when order
+doesn't matter. Use Arabic numerals (`1`, `2`, `3`) for ordered lists and dashes (`-`)
+for unordered lists.
+
+#### Prefer a paragraph to a single-item list
+
+A list of one signals content that was meant to grow and didn't. Exceptions: layout
+consistency across sibling sections, or an item that needs the visual separation.
+
+#### Don't nest lists more than two deep
+
+```md
+1. List item
+2. List item
+ 1. List item
+ 2. List item
+3. List item
+ - List item
+ - List item
+ <!-- DON'T ADD ANOTHER LEVEL OF NESTING -->
+ - Overly nested list item
+```
+
+### Don't use these
+
+#### Blockquotes
+
+Use an admonition when the content needs emphasis, or prose when it doesn't.
+
+#### Footnotes
+
+Put the information in the sentence, or in a linked section when it's substantial enough
+to need one.
+
+## Steps and code
+
+### Procedures
+
+#### Use a procedure when a human or an agent must perform actions to reach an outcome
+
+The format makes that expectation explicit.
+
+Write sequential actions as an ordered list. **Begin each step with an imperative verb,
+and include one action or a closely related set of actions per step.** Give the reader
+enough context to know where to act.
+
+For how many steps to present at once and when to split a procedure into phases, see
+chunking in [`03-page-structure.md`](./03-page-structure.md).
+
+An apparent one-step procedure can become two steps when there's a real orientation
+action:
+
+1. Open a terminal in your project directory.
+2. Run `supabase start`.
+
+The first step establishes the operating context for both readers and agents. Don't add
+a redundant orientation step to a genuinely atomic instruction. Write `Click **Save**.`
+rather than adding `Locate the **Save** button` as a separate step.
+
+### Code blocks
+
+#### Keep code lines short so the reader doesn't scroll
+
+Split long shell commands with `\`.
+
+JavaScript and TypeScript in code blocks are formatted by Prettier, and your pull
+request is blocked from merging if the Prettier check fails. Run `pnpm format` from the
+repository root, or set up automatic formatting in your editor.
+
+#### Prefer lowercase for SQL
+
+Write `select * from table` rather than `SELECT * FROM table`.
+
+Optionally specify a filename after the language specifier:
+
+````md
+```ts environment.ts
+
+```
+````
+
+Optionally highlight lines with `mark=${lineNumber}`:
+
+````md
+```js mark=12:13
+
+```
+````
+
+### Tabs
+
+#### Use tabs for alternative instructions across platforms or languages
+
+The same task, done differently depending on the reader's stack. Don't use tabs for
+sequential content or to hide information the reader needs either way.
+
+The optional `queryGroup` prop lets a reader link directly to a tab, such as
+`/docs/my-page?packagemanager=npm`.
+
+```mdx
+<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="packagemanager">
+<TabPanel id="npm" label="npm">
+
+// ...
+
+</TabPanel>
+<TabPanel id="yarn" label="Yarn">
+
+// ...
+
+</TabPanel>
+</Tabs>
+```
+
+## Data and diagrams
+
+### Tables
+
+#### Use a table when each row shares the same set of attributes
+
+A part and its description, a type and when to use it, an if and a then. A table with
+one populated column is a list.
+
+Keep cells short. When a cell needs more than a sentence or two, the content probably
+belongs in prose with the table reduced to a summary.
+
+#### Introduce a table in the sentence before it
+
+Not every screen reader announces that a table is coming. A reader can land in the first
+cell with no idea what the rows hold.
+
+#### Don't merge cells
+
+A merged cell breaks the row-and-column relationship a screen reader uses to read a
+table, so the reader loses track of which heading applies. If the content needs merged
+cells, it needs two tables.
+
+### Diagrams
+
+#### Use a diagram to support the prose
+
+A rendered diagram reaches fewer readers than the sentence next to it, so the text near
+it has to carry the takeaway on its own. A reader using a screen reader, a reader on a
+slow connection, and an agent reading the markdown export all depend on that sentence.
+
+#### Every diagram needs `accTitle` and `accDescr`
+
+Mermaid renders them into the SVG as `<title>` and `aria-labelledby`, which is what a
+screen reader announces. Without them the diagram is an unlabeled graphic. `accTitle` is
+one line naming what the diagram shows; `accDescr` describes the content, and takes a
+braced block when it runs past one line. See the [Mermaid accessibility
+options](https://mermaid.js.org/config/accessibility.html).
+
+Write a fenced code block with `mermaid` as the language. The MDX renderer routes these
+through the shared `Mermaid` component, so theming follows light and dark mode
+automatically. For the full syntax, see the [Mermaid diagram
+reference](https://mermaid.js.org/intro/syntax-reference.html).
+
+````mdx
+```mermaid
+sequenceDiagram accTitle: Sign-in token exchange accDescr { A user clicks Sign in. The
+browser requests authorization from Supabase, and Supabase returns a token to the
+browser. }
+
+participant User participant Browser participant Supabase
+
+User->>Browser: Clicks "Sign in" Browser->>Supabase: Request authorization
+Supabase->>Browser: Return token
+```
+````
+
+- Put a standard Mermaid keyword, such as `sequenceDiagram`, `flowchart`, or
+ `erDiagram`, on the first line. `flowchart` accepts a direction such as `LR` or `TD`.
+- Write `accDescr` for someone who can't see the diagram. Name the nodes and the
+ relationships between them. Restating the title tells that reader nothing.
+- Keep each diagram focused on a single flow or concept. Split a dense diagram into
+ smaller ones.
+- Wrap node labels containing special characters in double quotes, including `*`, `/`,
+ spaces, and punctuation: `A["content/**/*.md"]`.
+- Don't hardcode colors. The component themes the diagram for both modes.
+
+A diagram whose content can't survive being described in `accDescr` and the surrounding
+prose is carrying too much. Split it, or replace it with a table.
+
+## Media
+
+### Images
+
+#### Use an image when the reader needs to recognize something on screen
+
+A dashboard control that's hard to describe in words is the usual case. Upload images to
+`apps/docs/public/img`.
+
+Use `.svg` for vector illustrations and `.png` for screenshots and other non-vector
+graphics. Supported browsers receive `.webp` versions automatically.
+
+#### Redact sensitive information
+
+Remove API keys and any other secret visible in a screenshot before you upload it.
+
+#### Write alt text that describes the image
+
+A topic name is what the nearby heading already says. Describe what a reader who can't
+see it would need: the labeled parts, the relationships between them, and any values it
+carries.
+
+#### Every image needs an `alt` attribute
+
+Give a decorative image an empty one, `alt=""`, so a screen reader skips it rather than
+reading a filename.
+
+#### Never put new information only in an image
+
+Whatever the image shows has to also exist in the text, because a reader who can't see
+it has no other source.
+
+#### Don't use an image of text, code, or terminal output
+
+Use real text, which can be read aloud, searched, copied, and translated.
+
+### Videos
+
+#### Include a video as a table of contents video
+
+Don't place a video in the main text. Define it in the page frontmatter:
+
+```yaml
+---
+tocVideo: 'rzglqRdZUQE'
+---
+```
+
+## Navigation
+
+### Links
+
+#### Link selectively
+
+Every link is a decision the reader has to make, so a page dense with them costs more
+attention than it saves. When a term needs one sentence of explanation, write the
+sentence instead of sending the reader away. Link the same destination once per page,
+unless the page is long enough that a reader is unlikely to have seen the first one.
+
+#### Write link text that describes the destination
+
+Use the target's title, or a phrase that names what the reader gets. The text has to
+make sense read on its own, because assistive technology can list every link on a page
+out of context.
+
+- **Recommended**: `For more information about policies, see [Row Level Security](/docs/guides/database/postgres/row-level-security).`
+- **Not recommended**: `For more information about policies, [click here](/docs/guides/database/postgres/row-level-security).`
+- **Not recommended**: `See [this guide](/docs/guides/database/postgres/row-level-security).`
+
+#### Put the identifying words first, and keep the text short
+
+Use the shortest span that still describes the destination: `see the [reference
+section](/link)` rather than `[see the reference section](/link)`.
+
+#### Never use a bare URL as link text
+
+Name the thing instead.
+
+- **Recommended**: `[HTTP/1.1 RFC](https://www.rfc-editor.org/rfc/rfc2616)`
+- **Not recommended**: `[https://www.rfc-editor.org/rfc/rfc2616](https://www.rfc-editor.org/rfc/rfc2616)`
+
+#### Introduce a link with `see`, and say what the reader will find
+
+Write `For more information about X, see Y` rather than `For more information on X, see
+Y`. The `about` clause is what tells a reader whether the link is worth following.
+
+#### Keep sentence punctuation outside the link
+
+Write `see [Test your code](/link).` rather than `see [Test your code.](/link)`.
+
+#### Say when a link does something the reader won't expect
+
+A download, a new tab, or a jump within the page should be named in the link text or the
+sentence around it.
+
+#### Say when a link leaves Supabase docs
+
+Name the destination in the sentence rather than relying on an icon: `see the Postgres
+documentation on [row security
+policies](https://www.postgresql.org/docs/current/ddl-rowsecurity.html)`.
+
+#### Don't include the `https://supabase.com` origin
+
+For pages on `supabase.com`, link with a path. Use a `/docs/...` path for a page in
+Supabase docs, such as `[getting started](/docs/guides/getting-started)`. Use a
+site-root path for a page outside docs, such as `[open the Supabase
+Dashboard](/dashboard)`.
+
+#### Link to a section with its anchor
+
+Within a page, name the section: `see the [Links](#links) section of this document`.
+Across pages, append the anchor to the path:
+`[Chunking](./03-page-structure.md#chunking)`. Anchors come from heading text, so
+renaming a heading breaks every link to it. See [Headings](#headings).
+
+For when to cross-reference a section rather than repeat it, see [Navigation and
+glue](./03-page-structure.md#navigation-and-glue).
+
+### Content listings
+
+#### Use a content listing on an overview or index page
+
+A content listing holds a curated set of links, such as "Get started", "Next steps",
+"Examples", or "Resources". Place the component inline in the guide MDX:
+
+```mdx
+<ContentListings id="storage-get-started" />
+```
+
+Use a partial only when the block is reused or gated with `$Show` at the partial level.
+For an individual item that depends on a feature flag, set `feature` on the item rather
+than wrapping the whole listing.
+
+For the data file, ID uniqueness rules, and the test command, see
+[CONTRIBUTING.md](../CONTRIBUTING.md).
diff --git a/apps/docs/style-guide/03-page-structure.md b/apps/docs/style-guide/03-page-structure.md
new file mode 100644
index 00000000000..7e7ae1d0bd8
--- /dev/null
+++ b/apps/docs/style-guide/03-page-structure.md
@@ -0,0 +1,317 @@
+# How to structure a page
+
+A well-structured document drastically reduces cognitive load. This document breaks down
+how to segment information so it can be found at the right time and place.
+
+_Chunking_ is a major principle of effective technical writing. Break things up. If
+there are too many chunks, group the chunks, and maybe break up some more. We want to
+avoid a "too long, didn't read" situation.
+
+Apply this document when you add a page or move content around on an existing one.
+
+| If you're deciding | Read |
+| ------------------------------------------------------ | ------------------------------------------------------------- |
+| Which document type to write, and how big it should be | [Document types](#document-types) |
+| Which reader question a chunk answers | [Information types](#information-types) |
+| How to order sections on the page | [Grouping sections](#grouping-sections) |
+| How many items belong in one group | [Chunking](#chunking) |
+| How to open a long page and connect its sections | [Navigation and glue](#navigation-and-glue) |
+| How to keep a page from going stale | [Write timeless documentation](#write-timeless-documentation) |
+| What to leave out of the repo | [Keep internal context out](#keep-internal-context-out) |
+
+## Document types
+
+Supabase docs contain five types of document. Decide which one you need before you start
+writing.
+
+| Type | Purpose | Contains | Doesn't contain | Example |
+| --------------- | --------------------------- | ----------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------- |
+| Explainer | Learn a topic | What it is, why, and when to use it | Instructions | [Auth architecture](/docs/guides/auth/architecture) |
+| Tutorial | Finish a multi-feature goal | Procedures plus the reasoning | — | [Build a Next.js app](/docs/guides/getting-started/tutorials/with-nextjs) |
+| Guide | Finish one task | Procedures in sequence | Background; link to an explainer | [Passwordless logins](/docs/guides/auth/auth-email-passwordless) |
+| Reference | Look something up | Parameters, return types, samples | Context and use cases | [JavaScript client](/docs/reference/javascript/introduction) |
+| Troubleshooting | Resolve one error | The symptom, the cause, the fix | Feature overviews | [Too many channels](/docs/guides/troubleshooting/realtime-too-many-channels-error) |
+
+Reference content is generated from spec files rather than hand-authored. See
+[CONTRIBUTING.md](../CONTRIBUTING.md) for the reference pipeline.
+
+Troubleshooting entries live in `content/troubleshooting/` and use TOML frontmatter.
+Some sync from GitHub discussions, so check whether an entry exists before writing one.
+
+### Open a guide with a value statement
+
+Name what the reader can do and why it matters to them. That's what tells a reader or an
+agent whether the page matches their goal.
+
+- **Recommended**: `Restrict access to a shared table with Row Level Security. To learn how a policy is evaluated, see [Row Level Security](...).`
+- **Not recommended**: Several paragraphs about how Row Level Security works before stating what the reader can do.
+
+Keep procedures focused on what the reader must do. Move substantial background into a
+separate section or an explainer and cross-reference the authoritative explanation
+rather than repeating it. This keeps the action path scannable and maintains one source
+of truth.
+
+### Topic size
+
+Each type above is one unit of work for the reader. An explainer covers one topic. A
+guide covers one targeted task. A tutorial covers one multi-feature goal. A reference
+page covers one thing the reader looks up.
+
+#### One unit per page
+
+Enabling Row Level Security is one guide. Writing policies is a second, and designing a
+multi-tenant schema is a third. A reader who lands on the page from search should be
+able to finish what they came for. Link to the related pages.
+
+#### Keep a short piece inside its parent
+
+A fact or a principle is often one sentence. Put it in the section it qualifies. A
+heading whose only job is to point somewhere else is a link.
+
+#### Give the next unit its own page
+
+Split when a section has grown its own subsections and shares little with the rest of
+the page beyond the subject word. The new page takes the second task or the second
+concept, and this page links to it.
+
+[Chunking](#chunking) limits how many items sit in one group. Topic size limits what
+those items are about. A procedure can have six steps and still cover two tasks.
+
+- **Recommended**: A passwordless email login guide with `Send a one-time password` and `Verify the code`.
+- **Not recommended**: An `Authentication` page that also covers passwords, OAuth, and session storage.
+
+## Information types
+
+The [Information
+Mapping](https://support.informationmapping.com/hc/en-us/articles/213446789-Present-your-information-in-a-clear-and-consistent-way)
+method names six types of information. Each answers a different reader question, and
+each has a form that suits it.
+
+| Type | Answers | Present with | Build it per |
+| --------- | ------------------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Procedure | How do I do it? | Numbered steps, or an if/then table | [Procedures](./02-elements.md#procedures), [Tables](./02-elements.md#tables) |
+| Process | What is happening? How does it work? | A stage-by-stage description, or a when/then table | [Tables](./02-elements.md#tables), [Diagrams](./02-elements.md#diagrams) |
+| Structure | What are its parts? | A part and description table, or a labeled diagram | [Tables](./02-elements.md#tables), [Diagrams](./02-elements.md#diagrams) |
+| Principle | What should I do or not do? | Text, a list, or an admonition | [Lists](./02-elements.md#lists), [Admonitions](./02-elements.md#admonitions) |
+| Concept | What is it? | Text, a list, or a diagram | [Lists](./02-elements.md#lists), [Diagrams](./02-elements.md#diagrams) |
+| Fact | What are the facts? | Text, a list, or a table | [Lists](./02-elements.md#lists), [Tables](./02-elements.md#tables) |
+
+### Classify the content
+
+1. Split the content into chunks. One chunk is one thing you're telling the reader.
+2. For each chunk, ask which reader question it answers, and read its type off the
+ table above.
+3. Build each chunk in the form its `Present with` column names. A chunk already in a
+ different form is a defect. Fix it.
+4. Group the chunks by type, per [Grouping sections](#grouping-sections).
+
+[Example](#example) below works one paragraph through these steps.
+
+### Separating the types
+
+#### Separate a procedure, a process, a structure, or a concept
+
+Each usually reads better in its own section. Procedure and process get blended most
+often, because both answer a question about how, and a reader following steps can't act
+on the process sentences.
+
+#### Keep context out of the action path
+
+A concept or a process tends to work better before the procedure or after it than
+threaded through the steps.
+
+#### Let a principle or a fact ride along
+
+Either is often a single sentence, so it can sit in the section it qualifies rather than
+getting one of its own. A fact about timing fits in the step it describes, and a
+principle can close the concept paragraph that motivates it.
+
+#### Look again at a long paragraph
+
+Past three or four sentences, it has often picked up a second kind of information. Label
+each sentence and see where the labels change.
+
+#### Leave connective prose alone
+
+An introduction, a transition, an outcome, and a navigation outline describe the page
+rather than the product, so none of this applies to them.
+
+### Example
+
+Not recommended, because one paragraph blends a concept, a procedure, and a structure:
+
+```md
+Row Level Security is a Postgres feature that restricts which rows a user can read
+or write, and it's the main way to secure a table that several users share. Enable
+it by running `alter table profiles enable row level security`, which takes effect
+immediately. Be careful, because a table with Row Level Security enabled and no
+policy returns no rows to every client, so write a policy before you deploy. The
+`using` clause of a policy accepts any expression that returns a boolean.
+```
+
+Recommended, with each type in the presentation that suits it:
+
+```md
+## Row Level Security
+
+Row Level Security restricts which rows a user can read or write. It's the main way
+to secure a table that several users share.
+
+### Enable Row Level Security
+
+1. Run `alter table profiles enable row level security`. The change takes effect
+ immediately.
+2. Write a policy that grants the access your app needs.
+
+<Admonition type="caution">
+
+A table with Row Level Security enabled and no policy returns no rows to `anon` or
+`authenticated`. Write a policy before you deploy.
+
+</Admonition>
+
+### Policy reference
+
+The `using` clause accepts any expression that returns a boolean.
+```
+
+## Grouping sections
+
+Information types apply at the page level too. Group sections of related types together,
+and keep the procedure group unbroken so context doesn't interrupt the action path.
+
+### Classify a section by what the reader is doing in it
+
+On a page about tables every section is about tables, so subject matter tells you
+nothing. A reader opens a section on schemas to understand something, so it's context.
+
+### Split a section that serves two types
+
+Filing it under the larger half buries the other one. Give the new half a heading, keep
+the heading text of the half that stays, and cross-reference the two.
+
+One order that works: a short concept opener, then procedures, then concept and process,
+then structure and fact.
+
+```text
+## What is a table? <- concept opener
+## Creating and managing tables <- procedures
+### Creating tables
+### Securing your tables
+### Loading data
+## How tables are organized <- concept and process
+### Primary keys
+### Relationships between tables
+### Schemas
+## Reference <- structure and fact
+### Data types
+```
+
+### Chunking
+
+Apply the [Information Mapping chunking
+principle](https://informationmapping.com/blogs/news/writing-for-the-web-the-magical-number-seven-plus-or-minus-two):
+present 5 ± 1 related items at a time. That gives readers a manageable chunk of four to
+six. Aim for the lower end when the task is complex or unfamiliar.
+
+Information Mapping gives 7 ± 2 as the general limit and 5 ± 1 for content read on a
+screen. Screen reading is less accurate than the same content on paper. Supabase docs
+are read on a screen, so 5 ± 1 applies.
+
+If a procedure has more than six steps, group related steps into named phases or smaller
+procedures. Don't add steps to reach a minimum. The range organizes information.
+
+The same limit applies to sections in a group. A page with ten top-level headings needs
+grouping. Reordering them changes nothing.
+
+Headings and lists are the other half of chunking. A long stretch of prose with no
+heading gives a reader no way in and no way to skip. A reader navigating by heading has
+nothing to navigate. Where a paragraph has grown past its one topic, a heading or a list
+usually serves better than a longer paragraph.
+
+A lookup surface is the exception. When a reader arrives to find one entry rather than
+to read the page, the entries carry their own order: alphabetical, or the order of an
+API. Grouping them into fives would hide what they came for.
+
+A reference document is the same case. A reader opens this style guide to find one rule.
+Its sections are a list to scan, not a sequence to hold in memory.
+
+For how to format the steps inside a procedure, see
+[`02-elements.md`](./02-elements.md).
+
+## Navigation and glue
+
+### Begin a long guide with a short outline of its major section groups
+
+Link to each group and say when a reader should use it. Don't add section navigation to
+a short guide when its headings already fit on one screen.
+
+```md
+Connect your app to Postgres through a connection pooler, a direct connection, or a
+Supabase client library.
+
+- [Choose a connection method](#choose-a-connection-method) compares the options and
+ their trade-offs. Start here if you aren't sure which one fits your app.
+- [Connect your app](#connect-your-app) has the steps for each method.
+- [Connection parameters](#connection-parameters) lists every parameter and its
+ default.
+```
+
+Each link says what the reader gets from that group, so someone who already knows which
+method they want goes straight to the procedures.
+
+### Connect contextual sections to their procedures
+
+Do this when the relationship helps readers navigate. Add a brief introduction to each
+section group, a transition when the information type changes, and an outcome after a
+procedure. Add links selectively rather than linking every adjacent section.
+
+- Group introduction: `The following sections cover each connection method in turn. Every method needs your project reference, which you find on the project settings page.`
+- Transition where the type changes: `Those are the mechanics of opening a connection. To understand why a pooled connection behaves differently under load, see [Connection pooling](...).`
+- Outcome after a procedure: `Your app now connects through the pooler. Queries that used to fail at the connection limit queue instead.`
+
+## Write timeless documentation
+
+Document the product as it is now. Language that fixes a page to a moment goes stale,
+and a reader can't tell whether `currently` was written last week or three years ago.
+
+### Avoid words that anchor a sentence to a point in time
+
+| Avoid | Avoid | Avoid |
+| ------------------ | --------------------- | --------------------- |
+| as of this writing | existing | now |
+| currently | future, in the future | old, older |
+| does not yet | latest | presently, at present |
+| eventually | new, newer | soon |
+
+[`WORD_LIST.md`](./WORD_LIST.md) has entries for the two that come up most,
+[currently](./WORD_LIST.md#currently) and [latest, new, and
+soon](./WORD_LIST.md#latest-new-and-soon).
+
+- **Recommended**: `The emulator supports the following filters.`
+- **Not recommended**: `The emulator now supports the following filters.`
+
+### Don't promise a feature that hasn't shipped
+
+`Coming soon`, `will be available`, and `once finalized` all decay into inaccuracy, and
+a reader can't act on any of them. When a phased rollout is real, state the criteria
+that decide who has it: `Available to organizations on Pro and Enterprise plans`.
+
+### Don't ship a placeholder page
+
+A page saying `This is a placeholder` or `More details coming soon` promises content on
+no schedule. Wait until the page is worth reading, or ship the smaller thing that's true
+today. When navigation structure forces a page to exist, link out to resources that are
+complete.
+
+### Exceptions
+
+Changelog, release notes, and blog content are time-sensitive by nature, and referencing
+the future is their job. Procedural content can use a time word for a state change the
+reader causes: `The table now appears in the editor.`
+
+## Keep internal context out
+
+Supabase docs are open source. Keep planning notes, unshipped features, business intent,
+and references to ticketing systems out of the repo. Put review-time context in the pull
+request description and product context in the team's project-management tool.
diff --git a/apps/docs/style-guide/README.md b/apps/docs/style-guide/README.md
new file mode 100644
index 00000000000..adb16c9d031
--- /dev/null
+++ b/apps/docs/style-guide/README.md
@@ -0,0 +1,64 @@
+# Supabase documentation style guide
+
+Welcome to the documentation style guide. This is a living document that
+serves as the evolving source of truth for:
+
+- Our Supabase voice and our audience
+- The structure of our technical documents
+- How we consistently talk about our product
+
+This guide is for everyone who is writing to help Supabase users. It
+can be used by anyone who writes for Supabase, no matter your role or whether you are an employee or open
+source contributor.
+
+The style guide is also for both humans and LLMs: our [SKILLS](../CONTRIBUTING.md#write-the-docs-skills)
+use the style guide, but the style guide is also human-readable and friendly. Much of this guide is dedicated to removing AI smells such as verbosity and overused
+asides.
+
+We encourage you to contribute to the style guide so that we write the best
+documentation for Supabase. If something consistently bothers you, it may bother others as
+well. That could be an inconsistently used term or an unnecessarily verbose writing
+pattern. Open a style guide PR and start the discussion.
+
+## Navigation
+
+The files in the style guide are numbered in the order of content size. It starts with
+the smallest piece, at the word level, then progresses to the sentence, the element,
+and the whole page. `WORD_LIST` is unnumbered and a master document for our word
+consistency decisions.
+
+| File | Covers |
+| ------------------------------------------------ | -------------------------------------------------- |
+| [`WORD_LIST.md`](./WORD_LIST.md) | Terminology, spelling, capitalization |
+| [`01-voice-and-tone.md`](./01-voice-and-tone.md) | Person, tense, sentence length, brevity |
+| [`02-elements.md`](./02-elements.md) | Admonitions, code blocks, procedures, tabs, images |
+| [`03-page-structure.md`](./03-page-structure.md) | Document type, section grouping, chunking |
+
+## Before you open a pull request
+
+Always run [`WORD_LIST.md`](./WORD_LIST.md) against the finished page. We removed any
+linter and instead entrust you to use the word list.
+
+You can run `/review-the-docs` for a local self-review, and `/test-the-docs` if the page
+contains runnable snippets.
+
+### If you drafted with an agent
+
+Run a critic pass. Open a
+subagent with a clean context, holding only the relevant guide files and the draft
+text, and give it this instruction:
+
+> Referencing the docs style guide, cite every rule violation in the draft. Quote
+> the offending phrase and cite the rule it breaks as `file#anchor`, for example
+> `03-page-structure.md#chunking`. Derive the anchor from the heading itself, and
+> ignore headings inside fenced code blocks, which are examples rather than rules.
+> Then resolve.
+
+Each citation has to resolve to a real heading in the guide. One that doesn't is an invented rule, so check the citations before you act on them.
+
+## References
+
+- For spelling, see [Merriam-Webster.com](https://merriam-webster.com)
+- For accessible writing, see [Google's accessibility guidance](https://developers.google.com/style/accessibility)
+- For gaps, see [Google developer documentation style guide](https://developers.google.com/style)
+- For an additional developer guide reference, see [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
diff --git a/apps/docs/style-guide/WORD_LIST.md b/apps/docs/style-guide/WORD_LIST.md
new file mode 100644
index 00000000000..ae05cb3ecf6
--- /dev/null
+++ b/apps/docs/style-guide/WORD_LIST.md
@@ -0,0 +1,989 @@
+# Word list
+
+Preferred spelling, capitalization, and usage for terms in Supabase docs including Supabase
+product names. Use your best judgement when applying these rules. They are not intended
+to be strict, one-size-fits-all solutions and can evolve with your input. Feel free
+to contribute to this list as you write your documentation.
+
+This list is part of the [style guide](./README.md). It is the source of truth for all
+documentation consistency.
+
+## Use with an AI agent
+
+To apply this word list with an agent, you can use one of our skills. For more information, see [Write the docs skills](../CONTRIBUTING.md#write-the-docs-skills).
+
+**For agents:** Work in two passes rather than reading this file end to end.
+
+1. Mechanical pass. Read [Phrase groups](#phrase-groups). It collects every literal
+ term list in one place, so you can match it against the page in a single read.
+2. Judgment pass. Run `grep '^### ' WORD_LIST.md` for the term index, then read only
+ the entries that match words on the page. Most entries carry a condition, so read
+ the entry before you change a word.
+
+After you draft, run the mechanical pass again in a fresh context to prevent drift.
+
+## Numbers and symbols
+
+### `+`
+
+Don't use `+` to mean _or later_.
+
+- **Recommended**: Postgres 15 or later
+- **Not recommended**: Postgres 15+
+
+### `&`
+
+Use _and_ instead of `&` in prose, headings, navigation, and tables of contents.
+Keep `&` when it is part of a UI label, code, or a space-constrained table or
+diagram label.
+
+## A
+
+### abbreviations
+
+Spell out an unfamiliar abbreviation on first use. Don't expand familiar technical
+abbreviations such as API, CPU, HTML, HTTP, or SQL unless the audience needs it.
+
+Use `for example` instead of `e.g.` when practical. If space is constrained, write
+`e.g.` with both periods. Use `that is` instead of `i.e.`.
+
+### abort
+
+Use _stop_, _exit_, _cancel_, or _end_ in general prose. Use `abort` when it is the
+name of a command, signal, API, or operation.
+
+### above
+
+Don't use _above_ to refer to a location in a document or UI. Link to or name the
+section or control. For versions, use _later_.
+
+### access
+
+When possible, use a more specific verb such as _view_, _find_, _edit_, _open_, or
+_use_. Keep _access_ when it accurately describes authorization or connectivity.
+
+### admin
+
+Use _administrator_ in prose. Use _admin_ when it is part of a product name, API,
+role, command, or UI label.
+
+### agent
+
+Use _agent_ for a system that uses a model and tools to take actions, such as
+following a procedure or drafting a page. Lowercase _agent_ unless it is a product
+name.
+
+Use _AI agent_ the first time _agent_ could mean a person or an HTTP user agent.
+After that, use _agent_.
+
+Use _LLM_ for the model itself. See [LLM](#llm).
+
+### AI
+
+You can use _AI_ without spelling out _artificial intelligence_ when the audience
+is familiar with the term. For the model, see [LLM](#llm). For a system that uses
+a model and tools to act, see [agent](#agent).
+
+### allowlist and denylist
+
+Use _allowlist_ and _denylist_ as nouns. Prefer a precise verb that describes the
+action instead of using either term as a verb.
+
+- **Recommended**: Allow requests from the IP address.
+- **Recommended**: Add the IP address to the allowlist.
+- **Not recommended**: Allowlist the IP address.
+
+Don't use _blacklist_ or _whitelist_.
+When a literal code item contains one of them, format the item as code and explain
+what it does.
+
+### allows you to
+
+Use _lets you_, or make the reader the subject of the sentence.
+
+- **Recommended**: You can query the table.
+- **Recommended**: The API lets you query the table.
+- **Not recommended**: The API allows you to query the table.
+
+### alpha and beta
+
+Use lowercase when describing a release stage. Preserve capitalization when it is
+part of an official product name.
+
+### among and between
+
+Use _between_ for distinct items, even when there are more than two. Use _among_
+for members of a group or items that aren't distinct.
+
+### and/or
+
+Rewrite to use _and_, _or_, or explicitly state that either or both apply.
+
+### API
+
+Use _API_ for a web API or a language-specific API. Don't use _API_ to mean an
+individual method, function, class, or endpoint.
+
+### app and application
+
+Use _app_ for web and mobile software intended for end users. Use _application_
+when it is part of an established term, such as _application programming
+interface_, or when the distinction is technically useful.
+
+### as and since
+
+Use _because_ when you mean causation. _As_ and _since_ can be mistaken for
+references to time.
+
+### authentication and authorization
+
+Authentication verifies an identity. Authorization determines what an
+authenticated identity can access or do. Don't use the terms interchangeably.
+
+Avoid _authN_ and _authZ_ in prose. Use _authentication_ and _authorization_.
+
+### auto-
+
+Follow the spelling established by the relevant technology. Common closed forms
+include _autoscaling_, _autofill_, and _autogenerate_. Don't invent a hyphenated
+variation when an established form exists.
+
+## B
+
+### backend
+
+Write _backend_, not _back-end_ or _back end_.
+
+### base64
+
+Use _base64_ in general prose. Use the capitalization required by a formal name or
+literal code item.
+
+### below
+
+Don't use _below_ to refer to a location in a document or UI. Link to or name the
+section or control. For versions, use _earlier_.
+
+### black-box, gray-box, and white-box
+
+Prefer a description of what the monitoring or testing method can observe. If the
+established term is necessary, define it on first use.
+
+### boolean
+
+Use the spelling and capitalization of the programming-language type when
+referring to code. Use lowercase _boolean_ for the abstract data type and uppercase
+_Boolean_ for Boolean logic.
+
+### button
+
+Use _button_ only for an element that is actually a button. In desktop
+instructions, users _click_ a button. Preserve the exact button label and format
+it in bold.
+
+## C
+
+### can, may, might, must, and should
+
+- Use _can_ for ability, permission, or an optional action.
+- Use _might_ for possibility or an uncertain outcome.
+- Reserve _may_ for policy or legal guidance when possible.
+- Use _must_ or _need to_ for a requirement.
+- Avoid ambiguous _should_. State whether an action is required, recommended, or
+ optional.
+
+### checkboxes
+
+Users _select_ and _clear_ checkboxes. Don't use _check_, _uncheck_, or _deselect_
+for these actions.
+
+### click
+
+Use _click_ for buttons, links, and other controls in a desktop interface. Don't
+write _click on_. Use _tap_ when the environment is specifically a touch
+interface.
+
+### click here
+
+Don't use _click here_ or _here_ as link text. Describe the destination or action.
+
+### client
+
+In API documentation, a _client_ is usually an app that sends requests. Don't use
+_client_ as an abbreviation for _client library_ when that could be ambiguous.
+
+Use _concurrent connections_, not _concurrent clients_, when discussing database
+connections.
+
+### codebase
+
+Write _codebase_, not _code base_.
+
+### command-line interface
+
+Name the specific interface, such as _Supabase CLI_. Use _CLI_ after the name is
+clear.
+
+### config
+
+Use _configuration_ in general prose. Keep _config_ when referring to a literal
+file, command, property, or established technical name.
+
+### console and dashboard
+
+Use the product's official name. Don't use _console_ and _dashboard_
+interchangeably, and don't call a UI a dashboard unless it presents a dashboard.
+Use _Supabase Dashboard_ for the Supabase product.
+
+### currently
+
+Avoid _currently_ when the sentence describes the product's present behavior.
+State the behavior directly. See
+[Write timeless documentation](./03-page-structure.md#write-timeless-documentation).
+
+## D
+
+### data
+
+Treat _data_ as a singular mass noun: _the data is_ and _less data_.
+
+### data center
+
+Write _data center_, not _datacenter_.
+
+### data source
+
+Use _data source_ in prose. Preserve `datasource` when it is a code item or
+official product term.
+
+### data type
+
+Write _data type_, not _datatype_.
+
+### deprecate
+
+Use _deprecated_ when use is discouraged, usually because support will end. Don't
+use it to mean _removed_, _deleted_, or _unavailable_.
+
+### dialog
+
+Use _dialog_ for a UI element that presents information or asks for input. Don't
+use _dialogue_ or _popup_.
+
+### directory and folder
+
+Use _directory_ in command-line contexts and _folder_ in graphical interfaces.
+Match the product UI when it uses a specific term.
+
+### disable
+
+Use _disable_ or _turn off_ for an available feature or option. Don't use
+_disabled_ to mean that something is broken or unavailable.
+
+### display
+
+_Display_ is a transitive verb and requires an object.
+
+- **Recommended**: The Dashboard displays the query results.
+- **Recommended**: The query results appear.
+- **Not recommended**: The query results display.
+
+### docs
+
+Use _documentation_ in prose. Use _docs_ in informal contributor instructions,
+repository paths, URLs, or established product names.
+
+### dropdown
+
+Prefer the specific control name, such as _list_ or _menu_. Use _dropdown_ only
+when the distinction matters, and don't use _drop-down_.
+
+### dummy
+
+Don't use _dummy_ for placeholders or sample values. Use _placeholder_, _sample_,
+or a name that describes the value's role. For the statistical concept commonly
+called a dummy variable, use _indicator variable_ or another established,
+context-appropriate term.
+
+## E
+
+### easy, quick, and simple
+
+Avoid claiming that a task is _easy_, _quick_, or _simple_. These words can be
+subjective and usually add no information. Don't use _easy_, _easily_, _quickly_,
+_simple_, or _simply_.
+
+### email
+
+Write _email_, not _e-mail_. Don't use _email_ as a verb; use _send email_.
+
+### enable
+
+Use _enable_ or _turn on_ consistently for activating a feature. When describing
+capability, prefer _lets you_ over _enables you_.
+
+### endpoint
+
+Write _endpoint_, not _end point_. Don't use _endpoint_ when the more specific
+term is _function_, _method_, or _route_.
+
+### enter
+
+Use _enter_ for adding text to a field. Use _type_ only when the physical act of
+typing matters.
+
+### etc.
+
+Avoid _etc._, _and so on_, and _and more_. Introduce a non-exhaustive list with
+_including_, _such as_, or _for example_.
+
+### execute
+
+Use _run_ when it has the same meaning. Keep _execute_ when it is the precise
+technical term, such as an execute permission or query execution plan.
+
+### extract
+
+Use _extract_ instead of _unarchive_, _uncompress_, _untar_, or _unzip_ in prose.
+Preserve literal command names.
+
+## F
+
+### fail over and failover
+
+Use _fail over_ as a verb. Use _failover_ as a noun or adjective.
+
+### filename
+
+Write _filename_, not _file name_.
+
+### file system
+
+Write _file system_, not _filesystem_, unless the latter is part of a code item or
+official name.
+
+### fill in and fill out
+
+Users _fill in_ individual fields and _fill out_ an entire form.
+
+### first person
+
+Address the reader as _you_. Don't use singular first person (_I_, _me_, _my_, or
+_mine_).
+
+Use _we_ only when it clearly refers to Supabase, not when it means the writer and
+reader together.
+
+### foo, bar, and baz
+
+Use meaningful placeholder names that help explain the example. Keep conventional
+placeholder names only when the convention itself is relevant.
+
+### frontend
+
+Write _frontend_, not _front-end_ or _front end_.
+
+## H
+
+### hardcode and hardcoded
+
+Write _hardcode_ and _hardcoded_ without a hyphen.
+
+### health and healthy
+
+When possible, state the observable condition, such as _responding_, _available_,
+or _passing its health check_. Don't use _healthy_ when it could be ambiguous or
+anthropomorphic.
+
+### higher and lower
+
+For version ranges, use _later_ and _earlier_, not _higher_ and _lower_.
+
+### hover
+
+Use _hold the pointer over_ when the reader must wait for the interface to react.
+Use _point to_ when no waiting is required.
+
+### HTTPS
+
+Write _HTTPS_, not _HTTPs_.
+
+## I
+
+### ID
+
+Write _ID_, not _Id_ or _id_, except when matching code. Use _identifier_ when it
+is clearer.
+
+### impact
+
+Use _impact_ as a noun. Prefer _affect_ as the verb.
+
+- **Recommended**: The change affects performance.
+- **Not recommended**: The change impacts performance.
+
+### index
+
+Use _indexes_ as the plural in database documentation. Use _indices_ only in
+domains where it is the established term.
+
+### ingest
+
+Use _import_, _load_, or _copy_ for simple data movement. Use _ingest_ when the
+operation also performs substantial processing.
+
+### in order to
+
+Use _to_ unless _in order to_ is necessary to prevent ambiguity.
+
+### inline
+
+Write _inline_, not _in-line_.
+
+### internet
+
+Use lowercase _internet_ except at the beginning of a sentence.
+
+## J
+
+### just
+
+Remove _just_ when it is filler. If it means _only_ or _previously_, use the more
+specific word.
+
+## K
+
+### key
+
+Don't use _key_ to mean _important_. When referring to a technical key, identify
+the kind of key on first use.
+
+### key-value pair
+
+Write _key-value pair_, not _key/value pair_ or _key value pair_.
+
+### kill
+
+Use _stop_, _exit_, _cancel_, or _end_ in general prose. Preserve _kill_ for
+literal commands, signals, and established technical operations.
+
+## L
+
+### later and earlier
+
+Use _later_ and _earlier_ for version ranges.
+
+- **Recommended**: Version 2.2 or later
+- **Not recommended**: Version 2.2 or higher
+
+### latest, new, and soon
+
+Avoid time-relative descriptions that become stale. Provide a version, date, or
+specific product state instead. See
+[Write timeless documentation](./03-page-structure.md#write-timeless-documentation)
+for the full list of words that fix a page to a moment.
+
+### leverage
+
+Use _use_ or a more specific verb instead of _leverage_.
+
+### lifecycle
+
+Write _lifecycle_, not _life cycle_ or _life-cycle_.
+
+### LLM
+
+Use _LLM_ for the model that reads or generates text. When a page introduces the
+term, spell it out once as _large language model (LLM)_, then use _LLM_.
+
+Use _agent_ for a system that takes actions with tools. See [agent](#agent).
+
+### login and log in
+
+Don't use _login_ or _log in_ in prose. Use _sign in_. See
+[sign in and sign-in](#sign-in-and-sign-in).
+
+## M
+
+### marketing language
+
+Describe measurable behavior instead of making promotional claims. Don't use:
+
+- _best in class_ and _best-in-class_
+- _cutting edge_ and _cutting-edge_
+- _effortlessly_
+- _game changer_ and _game-changer_
+- _hassle free_ and _hassle-free_
+- _powerful_
+- _seamlessly_
+
+### master and slave
+
+Don't use _master_ and _slave_ together. Prefer terms that describe the
+relationship accurately, such as _primary and replica_, _controller and worker_,
+or _publisher and subscriber_.
+
+When a literal code item uses either term, format it as code, explain it, and use
+the preferred term afterward.
+
+### media type
+
+Use _media type_ rather than _MIME type_. Use _content type_ when referring to the
+`Content-Type` HTTP header or when it prevents ambiguity.
+
+### microservices
+
+Write _microservices_, not _micro-services_.
+
+### might
+
+Use _might_ for possibility or an uncertain outcome.
+
+### must
+
+Use _must_ or _need to_ for a requirement. Don't use _must_ for a recommendation.
+
+## N
+
+### native
+
+Use a more precise term when possible, such as _built-in_,
+_platform-specific_, or _compiled_. Don't use _native_ to describe people.
+
+### numbers
+
+Spell out zero through nine. Use numerals for 10 and greater. Use numerals
+regardless for versions, technical quantities, step and page numbers, prices, and
+percentages, and throughout a sentence that mixes a number under 10 with a larger
+one.
+
+- **Recommended**: four options, 24 hours, version 3, 128 bits, step 2, 40%
+- **Not recommended**: 4 options, twenty-four hours
+
+Spell out ordinals. Group digits in large numbers with commas, counting left from
+the decimal point. Write fractions as decimals where practical. Use a hyphen with
+no spaces for a range.
+
+- **Recommended**: first, forty-third, 1,532,784 bytes, 0.75, 2012-2016
+- **Not recommended**: 1st, 1532784 bytes, three-quarters, 2012 - 2016
+
+Omit a count of steps or items unless the count helps the reader plan. Name the
+action or link the heading rather than citing a step or section number.
+
+- **Recommended**: To connect to your database:
+- **Recommended**: After you create the project, copy the project URL.
+
+### numbers in product versions
+
+Write an explicit comparison, such as _version 3.0 or later_. Don't use _newer_,
+_older_, _higher_, _lower_, or a trailing `+`.
+
+## O
+
+### OAuth 2.0
+
+Write _OAuth 2.0_, not _OAuth2_, _OAuth 2_, or _Oauth_.
+
+### obviously and of course
+
+Remove these phrases. They can sound dismissive and don't help the reader.
+
+### once
+
+Use _after_ if that is what you mean. Use _once_ only to mean one time.
+
+### on-premises
+
+Write _on-premises_, not _on-premise_, _on premise_, or _on prem_.
+
+## P
+
+### performant
+
+Use a measurable or specific description, such as _lower latency_, _uses less
+memory_, or _handles more concurrent connections_.
+
+### persist
+
+Avoid using _persist_ as a transitive verb.
+
+- **Recommended**: Store the session.
+- **Recommended**: Make the session persistent.
+- **Not recommended**: Persist the session.
+
+### plain text and plaintext
+
+Use _plain text_ in general contexts. Use _plaintext_ in cryptography.
+
+### please
+
+Don't use _please_ in normal instructions. Use it only when asking permission,
+apologizing for an inconvenience, or requesting an action that primarily benefits
+Supabase.
+
+### plugin
+
+Use _plugin_ as a noun and _plug in_ as a verb.
+
+### popup
+
+Use the specific UI element, such as _dialog_, _menu_, or _window_. Don't use
+_popup_ or _pop-up_ as a generic noun.
+
+### Postgres
+
+Use _Postgres_, not _PostgreSQL_, outside code and literal third-party names.
+
+### powered by
+
+Don't use _powered by_. Prefer _with_, _by_, or _through_, depending on the
+relationship.
+
+### prior to and subsequent to
+
+Use _before_ and _after_.
+
+## R
+
+### read-only
+
+Always hyphenate _read-only_.
+
+### Realtime
+
+Capitalize _Realtime_ when referring to the Supabase product. Use lowercase
+_real-time_ as an adjective with its ordinary meaning.
+
+### repository
+
+Prefer _repository_ in documentation prose. _Repo_ is acceptable in informal
+contributor instructions and when space is constrained.
+
+### retry
+
+Use _retry_ as a verb or noun. Write around _retriable_, _retryable_, _triable_,
+and _tryable_ when practical.
+
+### run time and runtime
+
+Use _runtime_ for an execution environment. Use _run time_ for the time when a
+program runs or the duration of a run.
+
+## S
+
+### sanity check
+
+Use _preliminary check_, _confidence check_, or a description of what the check
+validates.
+
+### screenshot
+
+Use _screenshot_ as a noun. Use _take a screenshot_, not _screenshot_ as a verb.
+Redact secrets and personal information from screenshots.
+
+### select
+
+Use _select_ for choosing an item, selecting text, or marking a checkbox. Preserve
+the exact UI label in bold.
+
+### sensitive and confidential
+
+_Sensitive data_ is data whose disclosure might cause harm. _Confidential data_ is
+protected against unauthorized access. Use the term that describes the relevant
+risk or control.
+
+### setup and set up
+
+Use _setup_ as a noun or adjective and _set up_ as a verb.
+
+- **Recommended**: Complete the setup to set up authentication.
+- **Not recommended**: Setup authentication.
+
+### sign in and sign-in
+
+Use _sign in_, _sign out_, and _sign up_ as verbs. Use the hyphenated forms
+_sign-in_, _sign-out_, and _sign-up_ as nouns or adjectives. Match the product UI
+labels **Sign in**, **Sign out**, and **Sign up**.
+
+Keep _login_, _log in_, _logout_, _log out_, and `logOut` when quoting
+third-party UI or when they are part of code, routes, URL slugs, CLI commands, or
+established feature names such as _social login_.
+
+### singular they
+
+Use _they_, _them_, and _their_ as gender-neutral singular pronouns. Don't use
+_s/he_, _he/she_, _(s)he_, or _him/her_.
+
+### slang abbreviations
+
+Don't use internet slang in documentation, such as _tl;dr_, _ymmv_, _rtfm_, _imo_,
+or _fwiw_.
+
+### spin up
+
+Use _create_ or _start_ unless you are literally describing a spinning disk.
+
+### SQL
+
+Write _a SQL query_, not _an SQL query_. Use lowercase SQL keywords in code
+examples unless uppercase is required by the surrounding convention.
+
+### SSH
+
+Don't use _SSH_ or `ssh` as a verb.
+
+- **Recommended**: Connect to the server by using SSH.
+- **Recommended**: Use the `ssh` command.
+- **Not recommended**: SSH into the server.
+
+### startup and start up
+
+Use _startup_ as a noun or adjective and _start up_ as a verb.
+
+### Supabase
+
+Capitalize _Supabase_ outside code. Use _Supabase Platform_ with both words
+capitalized. Match literal package names, commands, URLs, and code.
+
+## T
+
+### table name
+
+Write _table name_ as two words. Format a specific table name as code.
+
+### target
+
+Avoid using _target_ as a verb for people. Use _intended for_, _designed for_, or
+another description of the audience.
+
+### terminate
+
+Use _stop_, _exit_, _cancel_, or _end_ unless _terminate_ has a specific technical
+meaning in the documented context.
+
+### third party and third-party
+
+Use _third party_ as a noun and _third-party_ as an adjective. Don't abbreviate
+either form with `3rd`.
+
+### this and that
+
+Add a noun after _this_ or _that_ when the reference could be unclear.
+
+- **Recommended**: This setting controls connection pooling.
+- **Not recommended**: This controls connection pooling.
+
+### timeout and time out
+
+Use _timeout_ as a noun or adjective and _time out_ as a verb.
+
+### timestamp
+
+Write _timestamp_, not _time stamp_.
+
+### time zone and time-zone
+
+Use _time zone_ as a noun and _time-zone_ as an adjective.
+
+### toggles
+
+Users _enable_ and _disable_ features with toggles. Match and bold the visible
+label. Don't instruct the reader to _click the toggle_ when the intended state can
+be stated directly.
+
+## U
+
+### UI
+
+Use the specific interface or page name when possible. Use _UI_ only when
+discussing a user interface as a general concept.
+
+Match visible UI labels exactly and format them in bold. Describe the element with
+the correct noun when it improves clarity, such as _the **Connect** button_ or
+_the **Database password** field_.
+
+### URL
+
+Use _URL_, not _web address_, when writing for developers. Use descriptive link
+text rather than exposing a URL unless the URL itself is the subject.
+
+### user
+
+Address the reader as _you_. Use _user_ for a person who uses the software that
+the reader is building or administering.
+
+### utilize
+
+Use _use_, not _utilize_ or _utilise_. Use _utilization_ only when referring to the
+measured proportion of a resource in use.
+
+## V
+
+### vague verbs
+
+Describe the concrete action:
+
+- _view and resolve errors_ instead of _handle errors_
+- _create, edit, or delete tables_ instead of _manage tables_
+- _query and update data_ instead of _work with data_
+
+Choose a different precise verb if the suggested replacement doesn't match the
+actual operation.
+
+### vCPU
+
+Use _vCPU_ (plural _vCPUs_) for the CPU resources of Supabase compute sizes.
+Don't describe Supabase compute in _cores_.
+
+_Core_ remains correct for hardware the reader owns or manages, such as
+self-hosting requirements or a migration VM, and in general CPU discussion.
+
+- Recommended: The 16XL compute size has 64 vCPUs.
+- Recommended: Run the migration from a VM with 8 CPU cores.
+- Not recommended: The 16XL compute size has 64 cores.
+
+### versus
+
+Write _versus_ in prose, not _vs._ Use `vs` only when it is part of a literal name
+or when space is constrained.
+
+## W
+
+### web
+
+Use lowercase _web_. Use the capitalization established by formal names such as
+_WebAssembly_.
+
+### we
+
+Don't use _we_ to mean the writer and reader together. Use _you_ for the reader.
+_We_ is acceptable when it unambiguously means Supabase.
+
+### while
+
+Use _while_ for events that occur at the same time. Use _although_ or _whereas_
+for contrast. Use _while_, not _whilst_.
+
+### will and would
+
+Use present tense for current product behavior. Use _will_ for an actual future
+event, not a predictable result. Replace _would_ with _can_ when describing
+capability.
+
+### workload
+
+Use a more specific term, such as _app_, _service_, _database_, or _job_, when the
+meaning is known. If _workload_ is the established technical term, define its
+scope on first use.
+
+## Y
+
+### you
+
+Address the reader as _you_. Use _user_ only for a person who uses the software
+that the reader is developing or administering.
+
+## Phrase groups
+
+The alphabetical entries explain the intent behind each rule. This section collects
+the full term lists in one place, grouped by the problem they cause.
+
+Every heading here is prefixed with `Group:`, so `### Group:` selects the whole set.
+Where a group entry and its alphabetical entry differ, the alphabetical entry governs.
+
+### Group: Filler
+
+Don't use _actually_, _easily_, _easy_, _just_, _let's_, _obviously_,
+_of course_, _please_, _quickly_, _simple_, _simply_, or _that's it_. Remove the term or state the intended meaning directly.
+_please_ is the exception: keep it when asking permission, apologizing for an
+inconvenience, or requesting an action that primarily benefits Supabase.
+
+### Group: Marketing language
+
+Don't use _best in class_, _best-in-class_, _cutting edge_,
+_cutting-edge_, _effortlessly_, _game changer_, _game-changer_, _hassle free_,
+_hassle-free_, _powerful_, or _seamlessly_. Describe specific behavior or
+measurable results instead.
+
+### Group: Vague verbs
+
+Use _view and resolve errors_ for _handle errors_, _create, edit, or delete tables_
+for _manage tables_, and _query and update data_ for _work with data_. Use a
+different precise replacement when none of these match the operation.
+
+### Group: Apologies
+
+Don't use _oops_ or _sorry_. State what happened directly. Apologize
+only when an apology is genuinely useful to the reader.
+
+### Group: First person
+
+Don't use _I_, _I'm_, _me_, _my_, or _mine_. Address the
+reader as _you_ and use an explicit noun for other actors. Use _we_ only when it
+clearly refers to Supabase. See [first person](#first-person) for the full rule.
+
+### Group: Gender-neutral pronouns
+
+Don't use _s/he_, _he/she_, _(s)he_, or _him/her_. Use the
+singular _they_ or rewrite the sentence.
+
+### Group: Inclusive language
+
+Don't use these terms:
+
+- _mankind_: use _humankind_ or _people_
+- _manmade_: use _manufactured_, _artificial_, or _synthetic_
+- _middleman_: use _intermediary_
+- _blacklist_: use _denylist_ or a more precise term
+- _whitelist_: use _allowlist_ or a more precise term
+
+### Group: Abbreviations
+
+Write _e.g._ with both periods, not _eg._ or _eg_. Replace _i.e._, _ie._, and
+_ie_ with _that is_. Prefer _for example_ and _that is_ in prose when space
+allows. See [abbreviations](#abbreviations) for when to spell one out on first use.
+
+### Group: Powered by
+
+Don't use _powered by_. Use _with_, _by_, or _through_, depending on the
+relationship.
+
+### Group: Preferred usage
+
+Use:
+
+- _Postgres_ for _PostgreSQL_
+- _concurrent connections_ for _concurrent clients_
+- _use_ for _utilize_ and _utilise_
+- _uses_ for _utilizes_ and _utilises_
+- _using_ for _utilizing_ and _utilising_
+
+### Group: Direct, concise language
+
+Don't use these phrases:
+
+- _aforementioned_: name the item
+- _amongst_: use _among_
+- _endeavor_ or _endeavour_: use _try_
+- _facilitate_: use _help_ or describe the action
+- _for the purpose of_: use _to_
+- _in order to_: use _to_
+- _leverage_: use _use_ or a more precise verb
+- _prior to_: use _before_
+- _subsequent to_: use _after_
+- _whilst_: use _while_
+
+### Group: Internet slang
+
+Don't use _tl;dr_, _ymmv_, _rtfm_, _imo_, or _fwiw_. Write out the
+meaning or remove the aside.
+
+## Attribution
+
+Portions of this word list are modifications based on work created and shared by
+Google and used according to the terms of the
+[Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).
+See the
+[Google developer documentation style guide word list](https://developers.google.com/style/word-list)
+for the original work. Supabase-specific guidance and adaptations are maintained
+in this repository.