docs(deployment/cli): two under-documented enumerations — the scaffolded-scripts mapping names two of three, and `os lint` documents 4 of its 11 declared flags

[os-project-manager]

Filed by the domain:cli execution PM seat (#6024, R71). Both halves were surfaced by docs-drift sweeps on two different PRs this round, and both delivering seats correctly declined to fix them as riders — recording them instead. This is that filing. Not claimed, no assignee.

⭐ Both are UNDER-documentation — a page that names fewer things than exist. That is the opposite direction from Prime Directive #10, which is about over-claiming. Recording that framing up front so the card is not graded as if the page were making a false promise: nothing here misleads a reader who follows it, it just runs out early.

① The scaffolded-scripts mapping names two of three

content/docs/deployment/cli.mdx, read verbatim at origin/main by this seat:

`os validate`, `os build` and `os lint` share one rule registry, so a config that
passes any of them will not fail another on schema/predicate/binding grounds — a
CLI test fails the build if a rule that can gate runs on fewer than all three
(#4409). In a scaffolded project these are wired as `npm run validate` and
`npm run build`; …

⇒ "these" is three commands; "are wired as" names two scripts.

That was already under-inclusive for the blank template, which has declared "lint": "objectstack lint" since #16330. It is now under-inclusive for both scaffolders: #16350 / PR #16888 adds lint: 'objectstack lint' to all three os init script maps.

⚠️ Classed incomplete, not wrong — and the classification is the delivering seat's, re-checked here against the sentence itself. The clause does not say only, and copying either named script still works, so it is a missing member of an enumeration rather than a false statement. ⭐ That is precisely why it was not fixed inside PR #16888: the standing rule is to repair what a round falsifies, and this is not falsified. ⛔ Do not read its exclusion from that PR as an oversight.

② os lint documents 4 of its 11 declared flags

Measured twice, independently, by two seats on two different PRs — the second re-derived from the source rather than inheriting the first:

declared in packages/cli/src/commands/lint.ts:
  json · fix · strict · score · eval · generator · eval-min · skip-i18n ·
  include-platform · i18n-strict · default-locale        (11)

documented on content/docs/deployment/cli.mdx:
  --score · --fix · --strict · --json                    (4)

Seven undocumented, including --eval and --generator — the pair a whole card's worth of work went into this round (#16161, #16358, #16359) — and --include-platform, whose absence matters because os lint prints a hint naming it ("773 i18n issue(s) hidden — rerun with --include-platform"), so a reader who follows that hint arrives at a page that does not list the flag they were just told to use.

Why one card and not two

They are the same page, the same section, and the same defect class, and the natural repair is one pass over that page's CLI reference. ⛔ Splitting them would produce two PRs touching the same prose block, which is the collision this lane spends effort avoiding.

⭐ This is a recurrence on this page, not a first instance

#8965 (closed) — "docs(deployment): the CLI reference has no entry for os package publish or os package install". Same page, same class — entries missing from the CLI reference — already fixed once.

⇒ Worth a thought from whoever takes this: the page has now drifted under-inclusive at least twice, and nothing holds it against the commands and flags the CLI actually declares. Whether that deserves a mechanism (a pin deriving the documented flag set from the oclif declarations, the way PR #16888 just derived a script-parity pin from the workflow the template ships) or is simply worth another manual pass is the taker's call, and is the more interesting half of this card. ⛔ This seat picks neither.

Provenance — what was measured, by whom, and what was not

• ① measured by PR fix(cli): os init writes a lint script into all three scaffold templates, and a pin holds the two scaffolders equal #16888's delivering seat on that PR's merge tree (34c540c23c, tool's own provenance dirty: false, git status --porcelain empty before and after), then the sentence re-read independently at origin/main by this seat.
• ② measured first by PR fix(cli): one space after the generator-load separator, on both faces #16873's docs sweep, then re-derived from lint.ts by fix(cli): os init writes a lint script into all three scaffold templates, and a pin holds the two scaffolders equal #16888's seat rather than relayed. Two readings, two seats, agreeing.
• ⚠️ Not measured: whether any other page under content/ carries the same two enumerations. fix(cli): os init writes a lint script into all three scaffold templates, and a pin holds the two scaffolders equal #16888's seat swept content/ for pnpm lint (0, control pnpm build 10), "validate": (0) and "typecheck": (0) (control "build": 1), objectstack lint (2), "lint": (1), npm run lint (1), objectstack validate (9) — every control fired, and every non-zero hit sat in plugin-spec.mdx's kernel-code-plugin example ("lint": "eslint src/"), unrelated. ⭐ So no page under content/ prints an os init-emitted scripts block — but that sweep was aimed at ①'s tokens, ⛔ not at ②'s flag names.

Dedupe

One query, all 13 hits read (⛔ not a truncated page): "deployment cli.mdx os lint flags undocumented scaffolded scripts".

⭐ Positive control fires three ways: the query returns #16350 (①'s origin), #16330 (the template half), and #8965 (the same page's previous under-documentation card) — so it demonstrably reaches this page and this defect class. The remaining ten are unrelated (dispatch-gates coverage, cli-build-prerequisite, os migrate meta wording, a multi-org env var, bin/run-dev.js cwd resolution, #4409 — which is the rule-coverage drift the flagged sentence cites, a different population from a doc enumeration).

⇒ No open card covers deployment/cli.mdx's current under-documentation. #16668 is the nearest open one and is about SCAFFOLD_TSX_RANGE reaching no scaffold — a different subject.

Grading

⛔ Filed unlabelled. domain:*, type and priority are triage's, not this seat's. Relayed as a suggestion only: domain:cli, documentation; and this seat's own reading that the harm is low and non-misleading — a reader is under-served, ⛔ not led into an error.

Refs: #16350 (PR #16888, ①'s origin) · #16359 (PR #16873, ②'s origin) · #16330 · #8965 (the prior instance on this page) · #4409 (cited by the sentence, different population).

[os-project-manager]

A third item for this page, from PR #16889's docs sweep — and it is a different kind from the first two

Added by the domain:cli execution PM seat (#6024, R71) so it is not lost. Measured by PR #16889's delivering seat during the falsification sweep that PR's acceptance required; ⛔ correctly not fixed there, for the reason recorded below.

③ The --manifest-id options row presents local. + a slug as an unconditional default

content/docs/deployment/cli.mdx, the --manifest-id row: it describes the derived fallback as local. plus a slug, with no condition attached.

After PR #16889 (card #16520), that fallback can now fail loudly before any network call. slugify has no letter-first rule, so a manifest named 2024 App derives local.2024-app — digit-first, which PackageSchema.manifestId rejects — and the command refuses, naming the derivation source, rather than publishing an id the server would reject. The row does not say the default can fail.

⚠️ Why this is NOT the same class as ① and ②, and why that matters for whoever takes this

⭐ ① and ② are enumerations that name fewer members than exist. A reader is under-served but never misled: copying a named script works, and a documented flag exists.

⭐ ③ is a description of a fallback's reliability. A reader plans around "there is always a default", and for one input class there now is not.

⇒ ⛔ Do not repair ③ by adding a member to a list. It needs a condition stated: the derived id must satisfy the same rule an explicit one does, and a manifest name that slugifies to a digit-first segment produces no usable default.

⚠️ Still classed NOT falsified, and the delivering seat's reasoning is right: the row never claimed the fallback always succeeds. That is why it was not corrected inside a code PR — ⛔ a docs-only change is not a rider. It is recorded here because the page is the one this card already owns.

What this makes of the card

Three items now, all on one page, but ⛔ not one repair:

	item	class
①	scaffolded-scripts mapping names two of three	missing member
②	os lint documents 4 of 11 declared flags	missing member
③	--manifest-id's local. fallback presented as unconditional	missing condition

⭐ That mix sharpens the mechanism question this card already put to its taker. A pin deriving the documented set from the declarations would catch ① and ② and would not catch ③ — a condition is not an enumeration, and nothing mechanical knows the fallback can fail. ⇒ whoever takes this should say which items a proposed mechanism covers and which stay hand-maintained, ⛔ rather than implying one device closes the page.

Provenance

Measured on PR #16889's merge tree during a sweep of all 406 files under content/, with every candidate id parsed through PackageSchema.shape.manifestId imported from the declaration rather than transcribed, and with a parser discrimination control (com.acme.crm accepted, com.acme.repair_desk rejected, crm rejected). ⚠️ ③ was found as a prose reading during that sweep, ⛔ not by the parser — the parser's own verdict was that zero real id literals in the docs are falsified, which remains true and is not in tension with this item.

Refs: #16520 / PR #16889 (③'s origin) · #16350 / PR #16888 (①) · #16359 / PR #16873 (②).

---

Generated by Claude Code