docs(deployment): add os package publish and os package install to the CLI reference

[os-project-manager]

Fixes#8965

content/docs/deployment/cli.mdx carried a #### entry per command across Development, Production, Build & Validate, Schema migrations, Scaffolding, Quality, Authentication and Cloud Environments — but had no entry for the two commands that move a compiled app onto a platform. The only mention of either was a single prose line inside os cloud login.

This became load-bearing when #8910 made publish-and-preview.mdx the page that states how a metadata app reaches a platform, under the instruction "link to the CLI reference, do not restate it". The link was there and landed on a reference that did not cover the two commands the page is about — a reader following it for flag-level detail found nothing.

What this adds

A new ### Packages subsection under ## Commands, with #### os package publish and #### os package install — each a flag table plus one example per mode, matching how os migrate and os cloud login are already covered.

Placement, and why not ### Cloud Environments. The card offered both options. ### Cloud Environments covers os environments * — commands that manage environment records in the cloud control plane. os package install does not touch the cloud at all in air-gapped mode; it POSTs to a running runtime's local install endpoint. Filing it under Cloud Environments would misfile it and split the pair. The two commands pair with each other — publish-to-cloud / install-into-runtime — so they get their own family, consistent with the page's existing task-family grouping. It sits after ### Cloud Environments so both of its prerequisites (the os cloud login credential, and environment ids for --env) are introduced before it.

Flags were read from source, not from the card

Every flag was verified against packages/cli/src/commands/package/publish.ts and .../install.ts. The card's flag list turned out to be install's flags only — it named --runtime / OS_RUNTIME_URL, --email / --password and --confirm-global-uniques, and attributed them to the pair. os package publish has a completely disjoint 23-flag surface built on the cloud identity (--server / OS_CLOUD_URL, --token / OS_CLOUD_API_KEY), none of which the card named.

Flags the card missed, now documented:

• publish: all 23 (--manifest-id, --display-name, --description, --category, --visibility, --org, --env, --install, --seed-sample-data, --pre-release, --submit, --auto-approve, --readme, --readme-file, --icon-url, --icon-file, --homepage-url, --license, --note, --timeout, plus --server / --token / --version) and the positional artifact.
• install: --timeout / OS_CLOUD_TIMEOUT_MS; the -r / -v short forms; --version defaulting to latest; and the OS_RUNTIME_EMAIL / OS_RUNTIME_PASSWORD env spellings the card referred to only as "--email / --password".

Both install modes were confirmed against the source. The mode is chosen by argument shape, and the page states the real rule: a file path when the argument ends in .json, starts with ./, ../ or /, or names something that exists in the working directory — that last clause is a real shadowing hazard and is called out.

The card's identity distinction is documented on both sides, because it is exactly the thing that misleads when restated loosely: publish resolves --token, then $OS_TOKEN, then ~/.objectstack/cloud.json, and deliberately does not fall back to os login's ~/.objectstack/credentials.json; install authenticates as an account on the target runtime.

One claim deliberately narrowed against its own source comment

install.ts comments that the --confirm-global-uniques affirmation is recorded "where os doctor can later show who affirmed it and when." Measured, os doctor does not display who or when — it calls unconfirmedGlobalUniques(...) and uses the attestation only to suppress re-reporting the affirmed constraints. The attestation record itself does carry posture, confirmed, attestedAt and an optional attestedBy.

Rather than copy a comment that over-claims (Prime Directive #10), the page documents the measured behaviour: what is recorded, and that os doctor stops re-reporting the affirmed constraints. Filed separately as a finding — see the report.

Scope

content/docs/deployment/cli.mdx only, purely additive (154 lines, 0 deletions). publish-and-preview.mdx is untouched and keeps the narrative and the choosing rule; #8913's restructure surface (index.mdx + meta.json) is untouched. Docs-only, so skip-changeset.

Verification

Gate union run at final commit 6bc51c9ea, working tree clean at that sha:

check:role-word PASS (43 baselined files, no new occurrences — this file's baseline of 1 is unchanged)
check:docs-audit-scope PASS (178 hand-written docs in sync)
check:doc-anchors PASS (231 internal fragment links resolve)
check:nul-bytes PASS (5947 text files, no raw control bytes)
check:doc-authoring PASS (376 files, no bare metadata literals)

Derived with node scripts/pm/dispatch-gates.mjs content/docs/deployment/cli.mdx, which named check:docs-audit-scope and check:role-word; check:doc-anchors, check:nul-bytes and check:doc-authoring were added from the actual diff (new fragment links, any-edit, new doc prose).

The three CLI tests that pin prose in this file pass — they regex-match text in the os login / os cloud login sections, which this change does not touch:

pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 \
test/cloud-login-json-ndjson.e2e.test.ts test/login-json-ndjson.e2e.test.ts \
test/login-json-noninteractive.e2e.test.ts
Test Files 3 passed (3)
Tests 42 passed (42)

Reverse verification of the anchor gate, from the committed state: breaking one newly-added fragment link to a non-existent heading turned check:doc-anchors red (ELIFECYCLE Command failed with exit code 1); restoring with git checkout HEAD -- ... returned it to green with a clean git status --porcelain. Direction as expected — red — so the gate demonstrably reads the new links rather than passing over them.

Page-path links: the one added, /docs/deployment/publish-and-preview, resolves to content/docs/deployment/publish-and-preview.mdx. lychee is not installed locally, so the Check Documentation Links job is the authority on that half.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 16, 2026 6:34am