docs: make the upgrade, AI and help pages follow their public sources

[objectstack-fleet]

Fixes #297

Three docs pages gave instructions that fail. This PR rewrites them to follow public sources. Each corrected sentence is listed below with the public source line it now follows. No sentence cites or quotes a private repository.

Sources used

• objectstack: objectstack-ai/objectstack at 753e7a1c (its origin/main on 2026-10-06). The repository is public, and every file cited is a content doc, the CHANGELOG, or a package README.
• this repo: objectstack-ai/objectos at the base 3b17984.
• npm, measured 2026-10-06 from this container:
  • npm view @objectstack/service-ai version returned 10.3.0, last modified 2026-06-23.
  • npm view @objectstack/cli version returned 17.6.0.
  • npm view @objectstack/service-feed version returned 9.7.0.
  • Every other package named on the changed pages returned 17.6.0.

1. operate/upgrade.mdx now follows deploy/docker.mdx

The page is now the Docker page's procedure as a checklist, plus three cross-references to sentences that already exist in this repo.

Before	After	Source
frontmatter: "Upgrade ObjectOS and application artifacts safely."	"Upgrade or roll back ObjectOS Self-Managed by changing the image digest it pins, after backing up the database."	this repo deploy/docker.mdx:152-166
Version table, image row: rollback by "Previous container tag"	"On ObjectOS Self-Managed, the image you run is pinned by digest, never by a tag, so an upgrade is a change of digest and a rollback is the previous one."	deploy/docker.mdx:6, :26, :39 ("Keep the previous digest too. That is what a rollback is.")
"For Docker Compose:" docker compose -f docker/docker-compose.yml pull / up -d	Upgrade steps 1–4, worded as the Docker page words them. Step 4 names the readiness endpoint.	deploy/docker.mdx:154-163; /api/v1/ready from :121
(no backup step)	Step 2: "Back up the database. Schema migrations are forward: rolling the image back does not roll the schema back."	deploy/docker.mdx:159-160
"Rollback ObjectOS: pin the previous image tag in your Compose file (or deployment manifest), then re-apply it." docker compose -f docker/docker-compose.yml up -d objectos	"Keep the previous digest: that is what a rollback is. To roll back, restore the previous digest and repeat step 3 — valid as long as the version you are leaving made no incompatible schema change (the release notes say when it did)."	deploy/docker.mdx:39, :164-166
"For Kubernetes, update the image tag and let the deployment roll."	"upgrading is the same change of image digest, with the migration Job running to completion before the new replicas serve"	deploy/kubernetes.mdx:81-82
(none)	Air-gapped: "verify the new digest outside, transfer it in, change the pinned digest, restart. Keep the previous digest: inside an air-gapped network it may be the only copy you have to roll back to."	deploy/air-gapped.mdx:97-99. air-gapped.mdx:121 already called this page "the procedures the steps above summarise".
Artifact row, "Upgrade artifact" (file-backed cp … docker/artifacts/objectstack.json + docker compose … restart objectos; cloud-connected pointer steps), "Rollback artifact"	"The app itself, when it is delivered as a published artifact, versions independently of the image — see Deployment → How the app gets in. Treat published artifacts as immutable: if you overwrite one in place, you lose the ability to roll back cleanly even when the database backup is perfect."	deploy/kubernetes.mdx:84-86; operate/backup.mdx:107, :116-117

Deleted with no replacement. These claims are not in the Docker procedure. Step 1 of that procedure covers the compatibility check.

• "Do not mutate artifacts in place. Publish a new artifact and switch the runtime to it." This is superseded by the backup.mdx sentence above.
• Cloud-connected mode: "Publish the new artifact to the control plane. Move the current project/environment pointer to the new version. Let ObjectOS refetch after cache expiry or restart to force reload."
• "Compatibility checks":
  • "confirm the artifact was built against a compatible ObjectStack version";
  • "confirm required capabilities are available in the ObjectOS image";
  • "confirm database migrations or schema sync behavior are understood";
  • "run authentication and permission smoke tests";
  • "verify rollback does not require destructive data changes".

2. configure/ai.mdx no longer installs @objectstack/service-ai

Removed.

• The @objectstack/service-ai row of the layer table.
• import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai' and its kernel.use(new AIServicePlugin(…)) block.
• The pnpm add @ai-sdk/* "peer deps" step.
• The kernel.getService('ai') example, typed with IAIService.
• The source link that returned 404, …/packages/services/service-ai.

Rewritten. Each sentence follows the source on its row.

After	Source
"ObjectOS adds an in-product AI runtime — the ask data-query assistant, the build authoring assistant, and the /api/v1/ai/* chat endpoints — on top of AI primitives that ship in the open-source ObjectStack framework: the MCP server, the Knowledge Protocol and its adapters, and the embedder."	objectstack content/docs/ai/index.mdx:16-22
"On a Self-Managed deployment, a licence is what unlocks the in-product AI. A single-organization deployment without one runs with Community behaviour — the open MCP server, bring your own AI — and with one, the AI Builder and "ask your data" are unlocked on your own infrastructure."	this repo deploy/docker.mdx:74-77
Table "What is configured where". Chat provider: the ai settings namespace, Setup → Configuration → AI & Embedder, or OS_AI_*, which ships in ObjectOS. Embeddings and Knowledge/RAG: the open packages. MCP: on by default at /api/v1/mcp, and OS_MCP_SERVER_ENABLED=false turns it off.	objectstack content/docs/ui/setup-app.mdx:55; content/docs/deployment/environment-variables.mdx:162-168, :179; content/docs/ai/knowledge-rag.mdx:12; this repo configure/mcp.mdx:6-15
"There is no AI package to install or register. @objectstack/service-ai left the open ObjectStack distribution in 11.0; the AI runtime it provides ships with ObjectOS, not with the open-source framework."	objectstack CHANGELOG.md:1726, :1734-1737; content/docs/api/client-sdk.mdx:182 ("the surface service-ai (Cloud/EE) mounts"); environment-variables.mdx:163-164; npm 10.3.0
"The provider, model and credentials are settings in the ai namespace, so they resolve like every other setting: an environment variable wins over the value stored in Setup, and locks it." This replaces "In Setup you can paste these as runtime settings instead — they go through the same precedence (env > settings) but live editing means no restart."	objectstack environment-variables.mdx:179, :183, :206-210; this repo configure/system-settings.mdx:25-42
OS_AI_* variable table: OS_AI_PROVIDER and its values, plus the OpenAI, Anthropic, Google, gateway and preset-provider rows. The preset rows are spelled OS_AI_ + provider + _API_KEY / _MODEL.	objectstack environment-variables.mdx:179-190
The example that locks a third-party OpenAI-compatible provider	objectstack environment-variables.mdx:217-225
"OPENAI_BASE_URL is not a platform-level variable."	objectstack environment-variables.mdx:231-234
"When no provider is set": the boot-time order is AI_GATEWAY_MODEL, then OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, then MemoryLLMAdapter echo. The upstream names are not renamed. OS_AI_MODEL overrides the model id. After boot, the runtime swaps the adapter from the ai namespace. This replaces the old provider env-var table and "rebuilds the adapter live when an operator edits … so no restart is needed".	objectstack environment-variables.mdx:172-177, :192-203, :227-229. Step 1 of the source list, an explicit AIServicePlugin({ adapter }), is left out because it is the removed package.
"Calling it": the routes under /api/v1/ai/* (chat, completion, models, conversations) and the @objectstack/client ai namespace: ai.chat, ai.chatStream, ai.complete, ai.models, ai.conversations. This replaces "Conversations are persisted as ai_conversations / ai_messages records … (POST /api/v1/ai/chat, POST /api/v1/ai/conversations)" and complete(), streamChat(), embed(), listModels().	objectstack content/docs/api/plugin-endpoints.mdx:7, :105-117; client-sdk.mdx:182, :379-392
Embedders: "works against any endpoint that speaks the OpenAI POST /v1/embeddings shape: OpenAI, Azure OpenAI, DashScope, Zhipu BigModel, SiliconFlow, Doubao, MiniMax, Ollama, or your own gateway."	packages/plugins/embedder-openai/README.md:3-15
The embedder example now passes apiKey and adds "apiKey is required". The old example said "apiKey from OPENAI_API_KEY env if omitted", which fails: the README marks apiKey required, and the constructor throws.	embedder-openai/README.md:41-47, :106
"No knowledge adapter in the open framework consumes an embedder yet: @objectstack/knowledge-memory and @objectstack/knowledge-ragflow take no embedder option." This replaces "Or pick at runtime from Setup → Configuration → AI → Embedder. Switch providers without restart; existing vectors stay searchable (you can re-index in the background)."	embedder-openai/README.md:94-96
Knowledge: "The knowledge service declares knowledge sources and filters what comes back by permission; an adapter plugin does the retrieval itself."	objectstack content/docs/ai/knowledge-rag.mdx:9
Adapter table: memory is for dev and tests, not production, with no persistence. RAGFlow does chunking, embedding, hybrid retrieval and reranking.	packages/plugins/knowledge-memory/README.md:5; packages/plugins/knowledge-ragflow/README.md:5
The wiring example now uses the README's sources: [...] shape instead of { defaultTopK: 10 } with no sources. It is labelled "In the open framework".	knowledge-ragflow/README.md:14-35
"The RAGFlow adapter does not create datasets …"	knowledge-ragflow/README.md:39
"Every hit that carries a source record is re-checked against the caller's permissions …" and "Exposing retrieval to the in-product chat as the search_knowledge tool is part of the ObjectOS runtime." These replace "Indexed knowledge bases become first-class objects — query them from flows, surface them in your apps, attach them to AI assistants as retrieval context."	knowledge-rag.mdx:65-68, :76
MCP: "Every ObjectOS deployment already serves the MCP at /api/v1/mcp — on by default, no plugin to install — and can serve it over stdio as well", with a link to Connect AI Tools (MCP).	this repo configure/mcp.mdx:6-9, :98-101
"Tools are not opted into per option: the plugin bridges the AI tool registry, the metadata service and the data engine when it starts. Every call runs under the calling user's permissions." This replaces "The server bridges the AI service's tool registry, including universal tools such as list_objects, describe_object, query_records, get_record, and aggregate_data." The open MCP aggregate tool is aggregate_records. The current tool list lives on configure/mcp.mdx.	packages/mcp/README.md:13, :70-72; objectstack content/docs/ai/natural-language-queries.mdx:15-22, :31-33

The MCPServerPlugin code block is kept unchanged, because @objectstack/mcp is at 17.6.0 and packages/mcp/README.md:59-62 documents transport and autoStart.

Deleted because no public source documents them (open question 2):

• "All three are optional, all three are provider-agnostic, and all three can be reconfigured at runtime from Setup → Configuration without a restart."
• "No mandatory cloud dependency. Use Ollama for chat + Ollama embedder + memory knowledge — entirely air-gapped." knowledge-memory/README.md:5 says the memory adapter is "Not for production".
• "Live swappable. Change provider in Setup; new requests use the new provider on next call. No restart."
• "Per-tenant config. Each Environment has its own AI settings. Tenant A on OpenAI, tenant B on Anthropic — same runtime." The public ai settings manifest declares scope: 'global' (objectstack packages/services/service-settings/src/manifests/ai.manifest.ts:29).
• "Audit log entries. Every conversation, tool call, and embedder request can be audited (@objectstack/plugin-audit)."
• "Cost-aware. Token counts and provider IDs flow through to the audit log for chargeback / cost analysis."

3. reference/runtime-capabilities.mdx

Before	After	Source
`ai` → `@objectstack/service-ai`	`ai` → "Not a framework package: the AI runtime ships with ObjectOS (AI Service)"	objectstack CHANGELOG.md:1734-1737; content/docs/api/client-sdk.mdx:182; environment-variables.mdx:163-164; npm 10.3.0
`feed` → `@objectstack/service-feed` ("Comments, reactions, subscriptions, activity feed")	row removed	objectstack content/docs/references/data/feed.mdx:11-12 ("The service-feed backend was retired … sys_comment / sys_activity are the canonical record-collaboration/timeline backend"); npm 9.7.0

The feed row is a bounded in-place fix the card did not name. It is the same defect, a package that no longer ships, on the same table and in the card's file surface. It is named here as the contract for that exemption requires.

4. Help links: GitHub Discussions is off on this repo

has_discussions is false on objectstack-ai/objectos. README.md:23-24 names the issue tracker as the public channel. Line numbers in this section are the base's.

Page	Before	After
resources/faq.mdx:218	"A: GitHub Discussions, the community Discord, or …"	"A: GitHub Issues, the community Discord, or …"
resources/support.mdx:10	"Have a "how do I" question → GitHub Discussions — community + maintainers"	"→ GitHub Issues — the public issue tracker for ObjectOS"
resources/support.mdx:16	"Want a paid feature implemented → Open a Discussion → tag with funding"	"→ sales@objectstack.ai — see Commercial support & services". Source: same page, :58 "Custom plugins / capabilities built to your spec" and :61 "Contact sales@objectstack.ai". No funding label exists on this repo.
resources/support.mdx:43	Response-expectations row "GitHub Discussions — Community-driven; maintainers chime in regularly"	row removed

The card named support.mdx:10 only. :16 and :43 point at the same disabled feature on the same page, so they are fixed here as the same defect.

Locale siblings: ruling A of #256, decided per page

English page	Changed assertion	Siblings
operate/upgrade	Rollback by tag reversed to rollback by digest. The Compose and artifact instructions are removed.	Deleted: upgrade.{de,es,fr,ja,ko,zh-Hans,zh-Hant}.mdx. Each still says docker compose -f docker/docker-compose.yml pull, and its rollback cell says previous container tag ("Vorheriger Container-Tag", "上一个容器标签", …).
configure/ai	The service-ai install/import and the no-restart, per-tenant and audit claims are removed.	Deleted: ai.{de,es,fr,ja,ko,zh-Hans,zh-Hant}.mdx. Each still carries import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai'; (zh-Hans and zh-Hant: import { ServiceAI } from '@objectstack/service-ai';) and the 404 source link.
reference/runtime-capabilities	The ai package is reversed and the feed row removed.	Deleted: runtime-capabilities.{de,es,fr,ja,ko,zh-Hans,zh-Hant}.mdx. Each still has the rows `ai` → `@objectstack/service-ai` and `feed` → `@objectstack/service-feed`.
resources/faq	Link fix only	none exist
resources/support	Link fix only	already deleted by #302 (#296), so nothing is double-deleted

zh-Hant was pruned by gen-zh-hant.mjs, which reported "3 stray file(s) removed". It was not deleted by hand. The routes of the deleted siblings now serve the current English page. The crawl below shows 40 of 40 locale × page URLs answering 200.

Verification

All of this ran on the final commit 39e6653, base 3b17984.

Gate	Verdict line
node apps/docs/scripts/gen-zh-hant.mjs --check	✓ zh-Hant: 61 generated file(s) match the zh-Hans sources byte for byte.
pnpm turbo run type-check --continue	Tasks: 1 successful, 1 total · Cached: 0 cached (cache miss)
NEXT_PRIVATE_STANDALONE=true pnpm turbo run build	✓ Compiled successfully · ✓ Generating static pages … (1052/1052) · Tasks: 1 successful (cache miss)
node .github/scripts/check-locale-surface.mjs	✓ every advertised URL has a source file and every source file is advertised; …
node .github/scripts/check-positioning.mjs	✓ positioning: 3 copies equal the constant; the brand is right in 659 pages and 2 llms bodies; no stale sentence in 79 English sources …
node .github/scripts/check-search-locales.mjs	✓ search locales: all 8 locales answer 200, …
pnpm turbo run test --force	✓ 10 self-test(s) passed · Tasks: 1 successful (the first, unforced run replayed the cache, so it was re-run)
node .github/scripts/check-translations.mjs	✓ translations gate passed
ownership, with the workflow argv: git diff --name-status --no-renames BASE...HEAD, --actor objectstack-fleet[bot]	with the variable unset: inert pass. With TRANSLATION_BOT_LOGIN set: ✓ 26 file(s) changed: 21 translation artifact(s) deleted, none added or modified.
check-translation-output.mjs --files (PR-scoped) and --self-test	✓ translation output gate passed (98 pre-existing finding(s) reported)
check-node-floor.mjs and --self-test; scripts/pm/check-half-states.mjs --self-test	exit 0

Link and anchor crawl. The crawl covered the built site under next start: the 5 changed pages × 8 locales, links inside the article body.

• Pages: 40 of 40 answered 200.
• Internal links: 624 checked, 0 broken.
• #fragment anchors: 344 checked, 0 broken. This includes #commercial-support--services, #upgrade-and-rollback, #rolling-upgrades-change-the-digest and #artifact-versioning.
• External links:
  • The objectstack package folders now linked (embedder-openai, service-knowledge, knowledge-ragflow, mcp) answered 200, as did github.com/objectstack-ai/objectos/issues.
  • discord.gg, modelcontextprotocol.io, status.objectstack.ai and www.objectos.ai were refused by this container's egress proxy: NOT MEASURED.

Screenshots. Each changed page was captured at 1440 and 390 wide, plus /zh-Hans/docs/configure/ai.

• Pages: upgrade, ai, runtime-capabilities, faq, support.
• No page scrolls horizontally: scrollWidth equals clientWidth at both widths.
• No page errors.
• At 390, the wide tables scroll inside their own container, as tables do elsewhere on the site.

Not run locally, left to CI:

• the Worker packaging (opennextjs-cloudflare build --skipNextBuild);
• the Worker size budget;
• the local-preview smoke check.

Acceptance notes

These were seen in passing. None is fixed here, and none is filed.

• reference/runtime-capabilities.mdx:41-45 says a missing capability package is logged and skipped. objectstack content/docs/deployment/cli.mdx:521 says the open CLI fails fast on the same condition. What ObjectOS itself does is not publicly documented, so the sentence is unchanged. No carrier.
• Three pages point at configure/ai for content it never documented, before or after this PR. No carrier.
  • build/automation/flows.mdx:307 (an ai_call action);
  • reference/security.mdx:278 (a redact config);
  • build/ai-builder.mdx:183 (Doubao as a chat provider, which is not in the public OS_AI_PROVIDER list).
• resources/support.mdx:15 says "Watch … → Releases", but this repo has 0 releases. No carrier.
• AGENTS.md:69 "62 of 79 pages" drifts with every ruling-A deletion. This is a governed file. No carrier.

Open questions

1. Gap: the ObjectOS-side embedder and knowledge settings are not publicly documented. Public sources name the Setup entries AI & Embedder and Knowledge (objectstack setup-app.mdx:55), but not what they hold. The page now says where the chat provider is configured, and shows the open-framework wiring for embedder and knowledge, labelled as such.

   • A: ship as is.
   • B: the maintainer publishes the ObjectOS fields, and a follow-up documents them.
   • C: drop the framework code from this ObjectOS page and link to the objectstack docs.

   Recommendation: A now, then B. A makes no unsourced claim, and C removes sourced, working content.

2. The six claims removed from configure/ai.mdx for lack of a public source (listed above).

   • A: leave them out until a public source exists.
   • B: restore any the maintainer confirms, with a public source line.

   Recommendation: A. The per-tenant claim is contradicted by the public scope: 'global' manifest.

---

Generated by Claude Code