[josephfarina]

Exact decision needed

How integration component docs are found and checked, and how a command may fail on warnings:

1. spec:AST-039 FR4 and architecture:cli-surface INV24: a component descriptor's name is the runtime export it documents, so a doc beside a file named otherwise (or named in kebab case) is found by that export, and each full entry its import exports is a component under its own name. A name recorded this way never takes an unscoped lookup that Core, a legacy docs package, or a component named after its source answers.
2. spec:AST-039 FR12: astryx doctor integration components compares each documented prop table with the props of the export it describes.
3. spec:AST-039 FR13: astryx doctor integration validate checks each descriptor against the type @astryxdesign/cli/authoring publishes for its kind in an integration, adding an integration type where integrations may author more than Core's type allows, without widening Core's.
4. spec:AST-039 FR14: astryx integration check [--strict] runs every integration check in one command, so a package can gate its own build on its docs staying in sync.
5. architecture:cli-surface INV32 and DEC-4: a warning fails a command only under --strict, which reports the same findings as errors, and a command offers --strict only through a record that names it.

Existing authority searched

• spec:AST-039 (draft): FR4 derives identity from the shared stem and says nothing about a descriptor naming another export or about family members. No requirement covers prop tables, descriptor types, or a single CI command.
• architecture:cli-surface (current): INV24 makes the descriptor the sole per-item metadata authority without saying which runtime export a component descriptor's name binds. INV8 makes exit codes independent of the output mode, INV17 owns what integration verify proves, and DEC-1 makes doctor fail on a broken configured integration. Nothing states what a warning does to an exit code.
• Every command on main was checked: none exits non-zero on a warning-severity finding alone (doctor documents "warnings are allowed"; the doctor integration subcommands, integration verify, upgrade, component and gap-report exit 1 on errors only). A check mode such as theme build --check reports what it exists to detect as an error. So INV32 requires no change to a released command.
• Open PRs touching the same records: spec(cli-surface): agent docs reach every agent from the project's own files #7539 (INV31, DEC-2) and spec(cli-surface): INV30, how a host's package set serves the CLI #7412 (INV30) add other cli-surface invariants; spec(AST-081): global mode, so the CLI answers in any folder and a project's own release answers inside it #7601 and spec: AST-060 integration package init #6963 edit cli-surface elsewhere; no open PR edits AST-039.

Decision

The records state it in full. In short:

• FR4. When the same-stem source has no runtime export named after the stem, the descriptor's name MAY name another runtime export of that source, and discovery records the component under that name. Each full entry a component descriptor lists in components is a component under its own name when the module the descriptor's import names exports it. Every surface lists, finds, and verifies these components by those names; a source that exports its stem keeps the stem. When the pack lifecycle writes the file a family's import names, integration verify compares that family's members as discovery lists them after the pack. A name recorded only this way never takes an unscoped lookup that Core, a legacy docs package, or a component named after its source answers: that lookup returns that owner's component unless a declared replacement claims the name, a lookup scoped to the package returns the package's component, and Doctor reports the shared name, so no exact lookup that resolves today resolves differently. The stem of a descriptor recorded under another name yields the same way to Core and to a file-named component. An exact name, including a recorded one, beats Core's keyword fallback (a guess, not an owner). architecture:cli-surface INV24 states the rule in the current record.
• FR12. Warnings for a documented prop the code lacks, a prop the package's own source declares that the table omits, a required flag the code contradicts, and a type that does not match under the documented loose comparison. A type the comparison cannot judge is listed as unchecked, never reported as a match or a mismatch. Without the project's TypeScript, the command says the comparison was skipped and why, and never reports a pass.
• FR13. Warnings for every unknown field, missing required field, and value outside its field's type, including fields the compiler reaches only once an earlier unknown field is gone. A value the loader accepts and the CLI reads satisfies the type published for integrations. Where an integration may author more than Core's type allows (any template category), an additional integration type is published (IntegrationTemplateDoc, in feat(cli): check each authored doc against its published authoring type #7664: every TemplateDoc field, with category as any string); Core's TemplateDoc is unchanged, so no consumer's compile changes. Without TypeScript, it says the descriptors were not type-checked.
• FR14. It checks the integration package in the current folder and takes no package argument; an app checks an installed integration with the doctor integration subcommands. Default: exit 1 exactly when one of the four checks would. --strict: also exit 1 on any warning and on any check or comparison that did not run, reported as errors from the same findings; an item a comparison lists as unchecked does not fail it. A new check or a new failure code joins only in a minor release that names it; a name a patch adds to Core or the CLI (a component, template, or topic) can still conflict with a package's own name. Each doctor integration subcommand stays unchanged.
• INV32 / DEC-4. Without --strict, a command never exits 1 for a finding it reports as a warning. --strict reads exactly the data the default run reports and adds no check. Another command gains --strict only through a change to the record.

Rejected alternatives

• FR4: requiring source files to carry the export's name (forces renames of public source paths); a manifest map from file to name (a central catalog, which FR11 forbids).
• FR12/FR13: relying on each package's own tsc setup (packages without one get nothing, and .doc.mjs files are often outside it); stricter loader parsers (would hide docs that load today).
• FR14/INV32: failing on warnings by default (a CLI upgrade turns green builds red); a separate gate command or flag name for each case.

Claim scope and non-goals

• Core component discovery and every existing doctor integration subcommand, exit code and JSON shape are outside these claims.
• No existing warning becomes an error, and no released command changes its exit behavior.
• The records do not prescribe how CI is wired; FR14 only promises a command a package can call from its own build.

Evidence and implementation relationship

• Implementation: feat(cli): a component doc can name a differently named export of the file beside it #7659 (FR4: export names and the owner rule) and feat(cli): integration family members are components under their own names #7674 (FR4: family members, stacked on feat(cli): a component doc can name a differently named export of the file beside it #7659); feat(cli): read a package's TypeScript project the way tsc reads it #7681, feat(cli): compare documented component props with the TypeScript source #7663, feat(cli): doctor integration components compares documented props with the code #7676, feat(cli): read two written TypeScript types as one when they differ only in how they are written #7684 and feat(cli): doctor integration components judges documented prop types against the code #7667 (FR12: reading the package's TypeScript project, the table comparison, doctor integration components running it with the Core test, reading two written types as one when they differ only in how they are written, then prop types); feat(cli): check each authored doc against its published authoring type #7664 and feat(cli): doctor integration validate checks each doc against its published authoring type #7673 (FR13: the check, then doctor integration validate running it, with the Core test); fix(cli): doc links to a component, page, or block resolve #7668 (doc links to components, pages and blocks resolve); feat(cli): integration check runs every source check for a package's build, with --strict #7665 (FR14, INV32, DEC-4). feat(cli): integration check runs every source check for a package's build, with --strict #7665 merges last, after a rebase that adds the other PRs' fields and failure codes, and ships in the same release as feat(cli): read a package's TypeScript project the way tsc reads it #7681, feat(cli): compare documented component props with the TypeScript source #7663, feat(cli): doctor integration components compares documented props with the code #7676, feat(cli): read two written TypeScript types as one when they differ only in how they are written #7684, feat(cli): doctor integration components judges documented prop types against the code #7667, feat(cli): check each authored doc against its published authoring type #7664 and feat(cli): doctor integration validate checks each doc against its published authoring type #7673.
• Measured on Core main: the prop comparison finds 137 drifts across 63 components, held by a shrink-only list; the type check finds 348 findings, all in translations, held the same way.
• Measured on a real 32-doc integration package: 3 components documented beside differently named files and 8 family members become reachable (29 → 40 entries, integration verify packable 40/40); integration check --strict reports 8 findings in about 4 seconds.

Writing rubric results

• R1 narration: none; every added sentence states what the system does.
• R2 research in the record: none; measurements live in this description only.
• R3 evidence naming a change: none; verification rows name test files and behaviors.
• R4 rejected alternatives over one line or outside a decision: one, in DEC-4, as a single Rejected: sentence.
• R5 pull request or issue references remaining: none.
• R6 ruled open questions still listing options: none added.

Scope

• This PR contains specification records only.
• It records observable behavior and preserves equivalent internal implementations.
• Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
• Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
• It records one intentional durable decision, not a rescue for a separable tagalong.
• The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
• Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
• Public text and artifacts contain no internal Meta context.

Overlaps: #7412 and #6779 also add a row to cli-surface's verification table after INV29; a merge keeps both rows. #7539 already conflicts with main in the same table.

Validation

• pnpm check:knowledge
• Prettier on docs/specs/AST-039/spec.md
• git diff --check

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Oct 18, 2026 6:40am UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🔄 In progress (for maintainers only)	Oct 18, 2026, 7:24 PM UTC

[github-actions]

PR Analysis Report

Preview availability: Storybook and Sandbox are not both ready on the exact-head Vercel preview.

No new or modified components detected.

Bundle Size Summary

No component packages changed.

Accessibility Audit

Status: No accessibility violations detected.

Visual Regression

40 of 478 shot(s) changed.

A change here is a question, not a failure: check whether the after is the
picture you intended. Record that review on the PR. Baseline maintenance is an
explicit dispatch of CI; this report never rewrites the baseline or adds a release gate.

component	story	theme	mode	pixels
Selector	Indicator Space Bottom Sheet Narrow End RTL	neutral	light	754,077
Selector	Indicator Space Bottom Sheet Wide Start	neutral	light	740,188
Chat	Full AI Chat	probe	light	230,823
Chat	Full AI Chat	probe	dark	229,805
RichTextEditor	Markdown parity: side by side	probe	dark	94,866
RichTextEditor	Markdown parity: side by side	probe	light	89,762
Collapsible	Dividers	probe	dark	66,445
Collapsible	Dividers	probe	light	66,445
Chat	Default	neutral	dark	36,304
Chat	Default	neutral	light	35,767
Chat	Empty State	probe	light	23,531
Chat	Empty State	probe	dark	22,622
ChatAutoScroll	Scroll Behavior Comparison	neutral	dark	15,378
ChatAutoScroll	Scroll Behavior Comparison	neutral	light	14,107
Chat	With Attachments	probe	light	13,406
Chat	With Attachments	probe	dark	11,232
ProgressBar	With Target Mark	probe	dark	7,895
ProgressBar	With Target Mark	probe	light	7,895
Markdown	Default	neutral	dark	7,573
Markdown	Default	neutral	light	7,566

and 20 more.

---

_{Generated by PR Enrichment workflow | View full report}

[josephfarina]

/approve-spec db3ef54