WORK-464
ID:WORK-464Status:done

Authoring docs for distributables (template, theme, plugin, preset-pack)

The docs ACs across SPEC-109, SPEC-111, and SPEC-116 — authoring guides for each distributable, each create-refrakt --type kind with a worked example.

Priority:mediumComplexity:simpleMilestone:v0.25.0Source:SPEC-116
main View source

Criteria completion

Criteria completion: 4 of 4 (100%) checked; history from Jun 23 to Jun 240%25%50%75%100%Jun 23Jun 24

Relationships

Implements 1
Related 8
Branches 4
main current done
claude/milestone-v0-28-0-llvtfa donechangeset-release/main doneclaude/v0.25.0-impl-3 doneclaude/v0.25.0-workitems ready
History 3
  1. ac87cf4
    • ☑ A template-authoring guide covers the manifest, the framework × purpose model, scaffold-copy semantics, the `asset:` scheme, and bundling a sandbox
    • ☑ A theme-authoring update covers the framework-agnostic default + `--target` ({% ref "ADR-024" /%})
    • ☑ A plugin-authoring pointer + a preset-pack guide cover the `scope` vocabulary, the JSON carrier + `$schema`, the dual preset/tint role, and compatibility (`tunedFor`) semantics
    • ☑ Each `create-refrakt --type` kind is documented with a worked example, and the {% ref "ADR-023" /%} peerDeps/compat convention is explained
    by bjornolofandersson
  2. dede57e
    Created (ready)by bjornolofandersson
  3. a6bdcba
    Content editedby Claude
    plan(v0.25.0): accept specs/ADRs and decompose into 21 work items

Acceptance Criteria

  • A template-authoring guide covers the manifest, the framework × purpose model, scaffold-copy semantics, the asset: scheme, and bundling a sandbox
  • A theme-authoring update covers the framework-agnostic default + --target (ADR-024)
  • A plugin-authoring pointer + a preset-pack guide cover the scope vocabulary, the JSON carrier + $schema, the dual preset/tint role, and compatibility (tunedFor) semantics
  • Each create-refrakt --type kind is documented with a worked example, and the ADR-023 peerDeps/compat convention is explained

Approach

Extend site/content/extend/* (theme-authoring, plugin-authoring) and add a template-authoring + preset-pack-authoring guide. Land after the formats exist so examples are accurate.

Dependencies

  • WORK-449 — plugin scaffold
  • WORK-450 — theme scaffold default
  • WORK-451 — template format
  • WORK-456 — preset-pack format

References

  • SPEC-109; SPEC-111; SPEC-116; site/content/extend/*

Resolution

Completed: 2026-06-24

Branch: claude/v0.25.0-impl-3

What was done

  • New site/content/extend/distributing/ section: index.md (four-layer overview, the create-refrakt --type kinds with worked examples, the ADR-023 peerDeps/compat convention, and the install commands), templates.md (manifest, framework×purpose model, scaffold-copy semantics, the asset: scheme, bundled sandboxes, theme-portability), preset-packs.md (scope vocabulary, JSON carrier + $schema, tunedFor compatibility, the dual preset/tint role).
  • Theme-authoring overview.md: a "Framework-agnostic by default (ADR-024)" section covering the default + --target svelte opt-in.
  • Plugin-authoring authoring.md: a "Scaffolding a plugin" note.
  • Updated the sandbox config doc (sites.md) to sandbox.dir (ADR-022) — also closes WORK-463's docs criterion.