Vyasa Extension Refactor Audit and Execution Plan

Architecture Decision FrameworkURL copied

Design Decisions From The Architecture SkillURL copied

1. The extension layer must be a deep module.

Interface:

Hidden implementation:

• FastHTML route details
  • runtime field layout
  • asset collection
  • config merge
  • capability validation
  • conflict detection
  • storage namespace path construction
  • page-need asset filtering

This gives leverage because extension authors learn one interface instead of core internals.

2. VyasaExtensionApp is the seam, not ExtensionRuntime.

Current modules mutate runtime directly. That makes the interface as complex as the implementation. Extensions should only see VyasaExtensionApp.

3. Markdown must become a pipeline module, not a feature owner.

Markdown owns:

• block parsing sequence
  • inline parsing sequence
  • registry lookup
  • unknown fence behavior
  • final HTML assembly

Markdown does not own:

• Mermaid rendering
  • D2 rendering
  • Cytograph rendering
  • Cryptograph rendering
  • Tasks rendering
  • Slides behavior
  • Tabs behavior
  • Wikilink behavior if wikilinks become optional

4. Theme variants are not modules.

A theme variant has no meaningful interface beyond data. The deep module is the theme selector extension. Theme folders are data adapters selected by id.

5. Static assets must follow module ownership.

If an extension owns behavior, it owns the CSS and JavaScript that implement that behavior. Shared shell CSS/JS should only contain truly global shell behavior.

6. Route behavior must be registered at extension seams.

A route extension should register route prefixes, assets, storage, and page actions together. Scattering route HTML in core and storage in an extension is shallow because maintainers must know both places.

7. Search is a feature extension with core hooks.

Core can expose content snapshots and request context. Search ranking, indexing, pages, and HTTP JSON endpoints should be owned by the default search extension.

8. Tree rendering is core only until feature decoration begins.

The content tree itself is a core content projection. Bookmark markers, annotation markers, search highlights, task counts, and file-type actions are extension row decorators.

9. Agent support should not stay in core unless it is mandatory.

If the agent behavior is optional, it should become an extension because it crosses a true external dependency. The interface should be a provider port with production and test adapters.

10. Auth/RBAC is core policy, but admin UI is an extension.

Request authentication and authorization checks are core because many routes depend on them. Admin pages, invitations UI, and account management pages are optional route/layout behavior and should be extension-owned.