Overview

Mental model, import surfaces, and install checklist for plugin authors.

Author guide — edit docs/.vitepress/plugin-sdk-guides/overview.md, then pnpm docs:generate.

Audience: authors of sova-* crates and in-app plugins. App users start at Plugins.

Mental model: a plugin is a typed unit that installs into App — usually middleware, shared state, routes, and optionally startup/shutdown, background services, CLI, and health checks.

Two import surfaces

Who	Import from
App main	sova::{App, …} crate root
Plugin crate	sova_core::extend::{…} (+ root types like App, Request, Plugin)

extend is the plugin-author surface: named middleware helpers, route introspection, HTML inject, logging hooks, SDK metadata. Prefer it over reaching into private modules.

Typical install body

1. Read config (config_doc unset-fill and/or env)
2. Soft-install missing deps (has_plugin → install) or hard-declare requires
3. app.state(…) shared handles
4. app.use_middleware(named(…)) / with_leaked / with_state
5. Optionally routes, on_startup / on_shutdown, service, register_check, register_cli

Scaffold

cargo sovax generate plugin my-thing

Where to go next

Topic	Page
Plugin / id / meta / SDK versions	Plugin trait
MW helpers	Middleware
State, markers, soft deps	State & dependencies
Toml / env	Config
Startup, workers	Lifecycle & services
Ready probes + CLI	Checks & CLI
Routes + OpenAPI meta	Routes & introspection
Extractors, EventBus, Problem+	Extractors & Problem+
Typed events	Events
HTML inject / log skip / DevTools hooks	HTML & log hooks
Failures	Errors
Real recipes from in-tree plugins	Recipes
Full extend table	extend API
Tests	Testing