Guide new administrators from sign-in to a first Session

[SaladDay]

What

A new administrator can get from install to a first Session in Web without confusion.

• Sign-in shows the documented ~/.oac/core/oac core-key --show instead of a long docker compose … exec command. The zh copy says "Core 密钥".

• Settings → Models and credentials shows whether each Harness is ready. One rule, harnessReady (enabled and has a model configuration), is shared with Getting started. Each Harness shows one of:

  • Ready (就绪);
  • Model provider not set, with Set as the primary button;
  • Disabled, with View startup settings.

  Before this change a Harness showed a green "Enabled" while its model service was unset.

• Settings → Workspace storage shows the adapter and tenant capacity, in byte units. The configuration ID and raw parameters are under a closed Configuration details disclosure.

• Settings → Service and deployment:

  • The public address and API base URL stay at the top. The installation ID and source commit are under a closed Installation details disclosure.
  • Core now reports each startup setting under the OAC_* variable that sets it (OAC_LOG_LEVEL, OAC_HARNESSES, …), and drops the unused changeable field. The OpenAPI document, agents-client types and projection, admin API contract and fixture follow.
  • Web shows that variable as the row label, in code style, with no label map. Values: arrays joined, booleans On/Off, other values as is.
  • The section help that restated "edit .env, run oac apply" is replaced by one How to change a setting link to the configuration guide's process settings section.

• Resource empty states (Agents, Environment templates, Skills, Files, Vaults, Agent metrics) use one new ApiEmptyState:

  • It shows "No … yet" / "还没有…" and one sentence saying applications create these through the Agents API.
  • It links to the matching section of the API guide.
  • A single docsUrl helper builds these links (https://openagentcore.dev, with zh/ for Chinese). It also replaces the hard-coded github.io link in Workspace storage.

• Projects and keys has an Active/Archived filter with counts. Active is the default, and filtering happens client side. The Status column is dropped from the list, because each view now holds only one status.

• Glossary on the touched journey:

  • zh "key" becomes "密钥" (Projects and keys, navigation, tour, Getting started, key errors, Agent metrics, model provider fields).
  • zh "执行框架"/"执行引擎" become "Harness"; EN lowercase "harness" becomes "Harness" in Models, errors, Overview and the Agents subtitle.
  • zh "会话" becomes "Session" on the Models page.

• Docs:

  • PRODUCT.md and DESIGN.md are updated.
  • install, configuration, console-api-usage and nodes are updated in EN and zh.
  • Every contract and doc that named a dotted setting (core.harnesses, core.execution_concurrency, …) now names its OAC_* variable: admin-api, core-metrics, sessions-events, vaults, harness-onboarding, model-execution, public-agent-api, operations, configuration, and the harness-catalog generator (regenerated).
  • The zh source_hash values are refreshed.

• Deleted, because nothing produced or read them anymore:

  • InstallationSetting.changeable;
  • the startup label map and the Harness-name value mapping;
  • empty-state descriptions;
  • the unused system.sandbox strings;
  • startup.fixed, startup.noRestart, startup.help and startup.reference;
  • keys.list.status;
  • the startup-settings code CSS.

Why

Walking the install guide on a fresh console showed several problems:

• A green "Enabled" sat next to "未设置" on the model page.
• Storage showed a UUID and raw JSON.
• Service showed raw dotted keys that appear nowhere an operator edits.
• Empty resource pages gave no hint where resources come from.
• Archived projects were mixed in with active ones.

Design notes

• Each setting's name has one home: the OAC_* variable, which Core reports and the configuration guide documents. Web adds no names of its own.
• Readiness is derived from the existing CoreHarness.enabled and model_configuration by one function, used by the Models page and Getting started.
• The only new UI state is the Projects list view (active | archived).
• On narrow screens a variable name wraps only after an underscore.

Verification

• Go: go test -run TestInstallation ./services/core/internal/api, go test ./services/core/internal/processconfig, go vet ./....
• make check-openapi (no drift), make check-harness-catalog, make check-docs, make check-names, pnpm --dir website check-translations.
• pnpm --filter @oac/web typecheck, pnpm --filter @oac/agents-client typecheck.
• vitest: agents-client admin-client.test.ts; web i18n parity, OverviewPage, sandbox-page-ownership, agent-metrics, workspace-storage-view, and earlier console-ui, KeyFlowDialogs, getting-started and provider-observations.
• Playwright against a local fixture, with bundled Chromium: access, projects, public-url, resources, system, unified-settings and metrics, 26/26 passed. Earlier, monitoring. Tests cover the Projects filter, resource empty states and guide links, the storage and installation disclosures, and the OAC_* startup rows.
• An independent review of the first commit, with its findings fixed.
• Screenshots in zh and en at 1440 px and 390 px.

Skipped checks

• Full make check (focused checks only).
• make check-website (the VitePress build's link check): the docs edits add no new links.
• The full Go test suites of the touched packages beyond the named tests; the remaining Playwright specs.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}