feat(ADR-0046): seed Setup & Studio package docs so the docs hub isn't empty#1845
Merged
Conversation
…t empty
A bare install shipped no first-party `doc` metadata, so `/_console/docs`
opened empty and ADR-0046 had no reference implementation. Seed one short
overview per built-in app, registered inline on each app package's
`manifest.register({ docs })` (the TS-first path DocSchema blesses) so they
group under Setup and Studio in the hub.
- @objectstack/setup: setup_overview (users/auth, roles & permissions, sharing)
- @objectstack/studio: studio_overview (metadata-first, draft/overlay
precedence per ADR-0005/0033, publish vs deploy)
Documents the invisible concepts only (HotCRM principle), links to
https://docs.objectstack.ai for depth. No framework change needed — code
packages register docs inline, not via os build flat-file collection.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
This was referenced Jun 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
ADR-0046 added
docmetadata + the in-product docs hub (/_console/docs), but no first-party package shipped anydoc— a fresh install opened the hub completely empty, and the feature had zero reference implementation. This seeds a deliberately minimal first version: one short overview per built-in app (Setup, Studio), so the hub is non-empty out of the box and there's a worked example to copy.What
@objectstack/setupregisterssetup_overview— for admins: users & authentication, the roles & permissions model, record visibility (sharing).@objectstack/studioregistersstudio_overview— for builders: the metadata-first model, the invisible draft/overlay precedence rule (ADR-0005/ADR-0033), publish vs deploy.Both follow the HotCRM principle — document the invisible business logic, not what the UI already shows — and link to https://docs.objectstack.ai for depth. Plain CommonMark + GFM, no MDX/images (ADR-0046 §3.4).
Mechanism (the experiment's finding)
These are TS-first code packages built by
tsup, not user apps built byos build, so they do not go through the flatsrc/docs/*.mdcollection + lint. The docs are declared inline asDocitems on each package'smanifest.register({ docs })call — the pathDocSchemaexplicitly blesses for TS-first stacks. They register under their owning package id, so the hub groups them under Setup / Studio. No framework change was needed.Verification
DocSchema-valid doc under its package id.GET /api/v1/meta/docreturns both docs (correct label/description/packageId); detail route returns full Markdown./docsportal: both render grouped under SETUP and STUDIO, Markdown (bold/italic/inline-code/autolinks) renders correctly. Screenshots captured during review.Diff is tiny: 2 new doc files + 2 one-block edits to each app's
index.ts+ a changeset.🤖 Generated with Claude Code