ID:WORK-542Status:done
Backfill the missing descriptions in refrakt.config.schema.json
Only 10 of 22 SiteConfig fields carry a description. These have none:
Priority:highComplexity:moderateMilestone:v0.33.0Source:SPEC-126
Criteria completion
Tracking started Sep 10 — check back for trends.
Relationships
Implements 1
Branches 3
Why this is its own work item
It has standalone value independent of the generated reference: schema description fields are what editors show on hover, so a user hovering baseUrl in VS Code currently gets nothing. Filling them fixes the editor experience whether or not SPEC-126's generator ever lands.
It is also the bulk of the generator work. WORK-544 is small once this is done, and large if it is not — separating them keeps that visible rather than hidden inside a "write a generator" estimate.
Acceptance Criteria
- Every property in
refrakt.config.schema.jsonhas adescription, at both the top level and inside every definition - The prose reads as user-facing documentation, not implementation notes
sites.mdandoverview.mdare not left contradicting the schema — where prose moved, the page keeps its narrative and drops the duplicated sentenceconfig-schema.test.tsasserts every property carries a non-emptydescription
Approach
Lift the existing prose from sites.md's field tables rather than writing new copy — it is already good, and rewriting invites drift between what the table said and what the schema now says.
Two things to watch:
Write for the reader, not the implementer. SPEC-126 D2 notes that several existing descriptions read like implementation notes. These become both the editor hover text and the generated reference body, so they are user-facing prose now.
$ref properties inherit from their target. highlight, sandbox, runes, and theme take their description from the definition they point at — HighlightConfig.description already carries the whole "use theme.presets instead" paragraph. Do not duplicate it onto the property.
The new assertion is what stops this regressing: without it, the next added field arrives description-less and nothing says so.
Blocked by
- WORK-541 — not strictly, but the drift test reads the interface path, so landing the split first avoids editing the same test twice.
Resolution
Completed: 2026-09-10
Branch: claude/content-author-docs-org-vps1un
What was done
packages/transform/refrakt.config.schema.json — 20 descriptions added, so every non-$ref property at the top level and in every definition now carries one. Prose lifted from sites.md's field tables and plugins.md's conflict-resolution section rather than newly written, so the schema and the pages say the same thing.
$ref properties are left alone deliberately: they inherit from the definition they point at, and a second copy would be a second thing to keep in sync.
packages/transform/test/config-schema.test.ts — new gives every property a description assertion, exempting $ref properties and naming the offenders by Definition.property when it fails.
Notes
- Standalone value regardless of the generator: these are the strings an editor shows on hover, so hovering
baseUrlin VS Code now says something. - Verified the new assertion bites: removing
SiteConfig.baseUrl's description failed the test naming exactly that field. - Two false starts worth recording. Round-tripping the file through
json.dumpsreformatted every compact one-liner — 254 insertions for 20 additions — so the edit is textual instead, and the diff is 20 lines changed. Then a naive "does this object start with a description?" check produced a duplicatedescriptionkey on top-levelcontentDir, which already had one in a later position.JSON.parseaccepts duplicates silently (last wins), so the test passed and only reading the diff caught it. The final pass scans each property's balanced object text before inserting. - Top-level
contentDirkept its existing "Legacy shorthand" description; the new prose went toSiteConfig.contentDir, which is the field a user writes. - Full suite 4264 passing.