WORK-174
ID:WORK-174Status:draft

Site docs — configuration section

Document the unified refrakt.config.json at site/content/docs/configuration/. Cover the three valid shapes (flat / singular site / plural sites), each section (plugins, plan, site/sites), the multi-site workflow, and the migration story for existing flat-shape configs.

Priority:mediumComplexity:moderateMilestone:v0.11.0Source:ADR-010
main View source

Criteria completion

Criteria completion: 0 of 5 (0%) checked; tracking started on May 1, no incremental history yet0%25%50%75%100%May 1May 11

Tracking started May 1 — check back for trends.

Relationships

Implements 1
Related 4
Branches 2
main current draft
claude/v0.11.0-config-foundation doneclaude/mcp-cli-wrapper-design-LsEXZ draft
History 3
  1. ce8fb3c
    Created (draft)by bjornolofandersson
  2. 5127eee
    Content editedby Claude
    plan(v0.11.0): drop plan.specsDir, expand WORK-166 to all five adapters
  3. 2b1f874
    Content editedby Claude
    plan(v0.11.0): scaffold milestone and 17 work items

Acceptance Criteria

  • New site/content/docs/configuration/ directory with at least these pages:
    • overview.md — what refrakt.config.json is, when to create one, the optional-by-default principle
    • plugins.md — declaring plugins, the difference between plugins and site.packages, fallback to dependency scanning
    • plan.md — plan.dir and interaction with plan init
    • sites.md — single-site (site) vs multi-site (sites), the --site flag, picking sites in vite.config.ts
    • migration.md — moving from flat shape to nested, using refrakt config migrate
    • schema.md — pointer to the JSON Schema, editor setup
  • Examples in each page use real, valid JSON
  • Cross-references to ADR-010 and SPEC-043 where relevant
  • Pages registered in the docs nav (whatever mechanism the site currently uses)
  • Existing site/content/docs/ content that mentions refrakt.config.json audited and updated to reflect the new shape (or noted as transitional)

Approach

  1. Read existing docs structure under site/content/docs/ to match conventions for page-level frontmatter and cross-referencing.

  2. Audit existing pages with grep -r 'refrakt.config' site/content/docs/ to find every snippet that needs updating.

  3. Write new pages from the most-used to the least-used: overview → sites → plugins → plan → migration → schema.

  4. Confirm the docs build cleanly with cd site && npm run build.

Dependencies

  • WORK-159 — config schema must be stable
  • WORK-171 — for the migration-command page
  • WORK-172 — own-repo migration provides realistic examples

References

  • ADR-010 — Unified root-level refrakt config
  • site/content/docs/ — existing docs structure to mirror