Skip to content

docs: retire "Console" as the end-user surface name; keep Setup for administration - #100

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-79-retire-console-name
Aug 18, 2026
Merged

docs: retire "Console" as the end-user surface name; keep Setup for administration#100
os-zhuang merged 1 commit into
mainfrom
claude/issue-79-retire-console-name

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

Fixes#79
Fixes#89

Verified on adbcafc.

The line I drew

The card names three jobs the word does. Deciding 180 occurrences one at a
time needs a test that is mechanical enough to review, so I used this one:

Is the word naming a place the reader goes, or a thing the product ships?

  • A place, end-user or builder — the surface has no name. Drop the noun and
    rewrite so the sentence keeps its subject. "Open Console, start the AI
    Builder"
    becomes "Open ObjectOS, start the AI Builder"; "a view is how a
    user sees records in Console"
    becomes "a view is how a user sees records".
  • A place, administrationSetup. This was mostly ratification, not
    introduction: the corpus already spells navigation Setup → Configuration → … on ~30 lines, gates it on setup.access, and calls it the Setup app at
    /apps/setup.
  • A thing the product ships — a URL, a plugin id (Console UI), a line the
    CLI prints, a box in an architecture diagram, a component named in the
    licence text. Unchanged, because those are identifiers a reader matches
    against their own terminal, config, or plugin list.

Where build/ landed

The PM's measurement put 57 of 160 occurrences in build/, a section the card
does not classify. Applying the test above, almost all of them are the first
kind — a builder creating an object does it in ObjectOS, exactly as an end
user opens a record — so the noun is dropped. The exceptions the PM predicted
are real and were kept or reshaped rather than renamed:

OccurrenceCall
architecture.mdx "REST API, Console UI, permissions, jobs"Kept. Naming the runtime's shipped components; ConsoleUI is a real plugin id in objectstack.
quickstart.mdx plugin list "…, Console UI, Account UI, Console UI, …"Kept. A list of plugin identifiers.
system-settings.mdx settings-model row naming Console UI as the rendererKept. A layer in the settings model, alongside sys_setting and Resolver.
license.mdx "the protocol, kernel, CLI, production runtime, Console" / "the Console and Account UIs"Kept. Enumerating Apache-2.0 deliverables, not places.
"install apps via the Console marketplace"Kept — it is CLI output inside a fence.
"the Console's generic action runtime" (changelog)Reshaped, not kept: the subject is the approvals inbox, which is a place. Now "the approvals inbox renders them through its generic action runtime".
"Console views" (many)Dropped, not kept: attributive use of the place noun. "REST endpoints, Console views, audit log entries" → "REST endpoints, generated views, audit log entries".

Code fences: a bright line

Nothing inside a code fence changed. All nine in-fence occurrences are
byte-identical to origin/main. That rule is mechanical and one grep verifies
it, which is worth more than case-by-case judgement inside blocks a reader
copies and runs.

Worth flagging: only five of the nine are output the product prints
(quickstart.mdx lines 40/46/48/151/153). The other four are authored content
that happens to live in a fence — two ASCII diagram lines in
build/marketplace.mdx, one in reference/field-types.mdx, and a # comment
in a bash block in reference/cli.mdx. They are left unchanged under the
card's instruction, but the stated rationale for that instruction (terminal
output a reader compares) does not cover them. reference/cli.mdx is where
this shows: the fenced comment still reads # API only (no Console/Account)
while the flag table three screens down now reads Disable the UI and Account
portals
. One line, one follow-up, maintainer's call.

The gap in the card's own measurement

The card counted Console, case-sensitively. The corpus also carries 20
lowercase console
occurrences doing the same job — "the console home",
"wherever you are in the console", "the whole console follows immediately",
"Tour the console as an everyday user". Thirteen of them are in use/,
the section measured at 6.

Leaving them would have left two spellings of the same surface live in the
corpus, which the card forbids. Fifteen were retired with the rest; five stay,
all category three: /console/f/… form URLs in build/interface/forms.mdx,
and the OS_OBS_EXPORTER=console config value in two pages.

#89 — the glossary

The two ### Console entries are one collapsed pair, and the entry bodies
survived intact even though the headings did not. What they were
distinguishing is legible from the bodies
: platform administration (users,
roles, permission sets, audit log, sessions, API keys, system settings) versus
working in the apps (browse, create, edit records, configure views, install
apps). Two more pieces of evidence agree — the second entry sits in the
alphabetical slot afterSharing Rule, so it was never a C-word; and the
damage repeats elsewhere in the corpus with the same shape (quickstart.mdx
prints two identical Console: banner lines and lists two Console UI
plugins).

Under the decision that collapses to: one Setup entry, and no entry at all
for the end-user surface. Both were rewritten accordingly, and Setup moved to
its alphabetical position between Record Share and Sharing Rule.

On the URL. The triage asked that the address come from routing rather than
from either glossary sentence. It does: objectstack@origin/main defines
CONSOLE_PATH = '/_console' in packages/cli/src/utils/console.ts and defaults
uiBasePath to /_console in packages/spec/src/system/auth-config.zod.ts,
and the CLI banner prints exactly one Console: line. So the duplicated URL was
not a wrong URL — there is one UI at /_console/, and what was wrong was
presenting two areas of it as two separately-named surfaces. The glossary now
says Setup lives at /apps/setup inside the UI served at /_console/, which is
what configure/index.mdx and configure/users.mdx already said.

Surface claimed "four" entry points and listed three distinct ones with
/_console/ repeated. I removed the numeral rather than asserting "three":
three is what this corpus can support, four is a claim nothing supports, and
inventing a fourth URL is out of scope.

Verification

CheckResult
turbo run type-check --forcecache bypass, force executing 5f6f0dc855a640b1 · 1 successful
turbo run build --forcecache bypass, force executing 002d42ca7ee9a0e6 · 1 successful, 79 English pages + 256 translations prerendered
check-translation-ownership.mjsexit 0 — 0 translation artifacts touched, 48 other files
check-translations.mjs (freshness)exit 0, gate passed — stale reported, not blocking, as designed
check-translation-output.mjs --self-testexit 0 — 20 cases, every rule demonstrated able to fail
check-translation-output.mjs --filesexit 0 — 116 pre-existing findings reported, none in files this PR touches
Rendered HTML read/docs/use, /docs/use/notifications, /docs/configure, /docs/configure/permissions/permission-sets, /docs/build/marketplace, /docs/build/interface/actions, /docs/quickstart, /docs/resources/glossary
Anchors6 headings renamed; a repo-wide grep for every old slug and for glossary# returns nothing. No internal link points at a renamed anchor.

The rendered-text scan is the real proof of the fence rule: across those eight
pages the only surviving Console in rendered output is in quickstart's two
banner blocks, its plugin list, and marketplace's ASCII diagram.

Category-3 count

The card asks that _console come out unchanged. Reporting it honestly, because
it does not, and the reason matters:

ScopeBeforeAfter
_console, English pages1715
_console, English pages outside resources/glossary.mdx1313
_console, all .mdx including locales113111
Console, English pages16016
in-fence Console99, byte-identical

Every /_consolestring in the corpus is untouched — the diff shows only
surrounding prose changing on those lines. The two-occurrence delta is entirely
inside resources/glossary.mdx and is exactly what #89 asked for: the deleted
duplicate entry took its /_console/ with it, and de-duplicating Surface
removed the repeated one. Those two instructions cannot both hold; I kept the
one that names a defect and reported the other rather than leaving the defect in
place.

Scope held

Not split. configure/** alone would have left the administration surface
spelled Setup there and Console in build/, use/, reference/,
operate/, resources/ and the root pages — two spellings of one surface,
which the card forbids. 47 files, but each hunk is one or two lines.

Untouched, as instructed: the /_console URL everywhere; the recipient-kind
wording in record-access.mdx and the share row in actions.mdx (#91);
packages/console; every locale sibling. objectui and objectstack UI copy
are separate cards in their own repos.


Generated by Claude Code

…dministration
The word was doing three different jobs across 47 English pages. Each
occurrence got a per-occurrence call, never a global replace:
- a place the reader goes, end-user or builder -> the surface has no
name; the noun is dropped and the sentence rewritten so it keeps its
subject ("Open the record", "Open ObjectOS").
- a place the reader goes, administration -> Setup, the name the corpus
already used on 18 pages (Setup -> Configuration -> ..., setup.access,
the Setup app at /apps/setup).
- a thing the product ships -- a URL, a plugin id (Console UI), a line
the CLI prints, a box in an architecture diagram -> unchanged.
Nothing inside a code fence changed: all nine in-fence occurrences are
byte-identical, and every /_console string in the corpus is untouched.
The sweep also covers 15 lowercase "console" occurrences that a
case-sensitive grep misses -- 13 of them in use/, the section the card
measured at 6.
Also resolves the glossary defect recorded as #89:
two `### Console` entries each saying "Distinct from Console", both
claiming /_console/, and a `Surface` entry listing "four" entry points
with /_console/ twice. The administration entry is re-authored as one
`Setup` entry in alphabetical position; the end-user surface gets no
name and therefore no entry; `Surface` drops the unsupportable count and
the duplicate.
docs/TRANSLATION.md drops Console from the never-translate glossary and
keeps Setup.
English only. Locale siblings are left alone and report stale, per
AGENTS.md; the freshness gate passes.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPxtTxoxTUnjNdTbiEaRa
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants

@os-zhuang@claude