refactor: address adversarial widget architecture review

apps/docs/docs/advanced/development/widgets-and-integrations.mdx

@@ -8,8 +8,8 @@ tags:
 sidebar_position: 2
 ---
 
-Homarr keeps feature registration explicit and typed. There is no generator or generated registry to run after a
-change. A new feature is available when its typed metadata and lazy loader are registered.
+Homarr keeps feature registration explicit and typed. Feature registration has no generator or generated registry.
+A new feature is available when its typed metadata and lazy loader are registered.
 
 ## Add a widget
 
@@ -46,10 +46,24 @@ Keep the HTTP client and its capability-specific types in `packages/integrations
    implementation out of the initial server bundle and makes the registration easy to find.
 3. Implement only the interfaces required by the widgets that use the service.
 4. Add canonical documentation in `apps/docs/docs/integrations/<slug>/`. Its `index.ts` must satisfy
-   `IntegrationDefinition` so invalid metadata fails type checking.
+   `IntegrationDefinition` so invalid metadata fails type checking without widening the object. Use a type-only import
+   and `satisfies IntegrationDefinition`; do not cast the object.
 
 Beszel is a compact example with several widgets sharing one integration client.
 
+## Write user documentation
+
+Write for technically capable self-hosters. Keep each page short and operational.
+
+- Start with one sentence describing what the integration or widget adds to Homarr.
+- Include prerequisites, credentials, permissions, destructive actions, and non-obvious limits only when they matter.
+- Use numbered steps only when order matters. Prefer the exact UI labels a user must select.
+- Do not add marketing, implementation history, architecture internals, or explanations of basic self-hosting concepts.
+- End when the user can configure and verify the feature; do not repeat the same information in a summary.
+
+The usual page needs only an introduction and a `Configuration` section. Add `Notes` or `Troubleshooting` only for
+real caveats.
+
 ## Data and errors
 
 - TanStack Query owns browser caching and refresh behavior. Redis owns shared server response caching.

apps/docs/docs/management/api/index.mdx

@@ -110,6 +110,9 @@ The OpenAPI and MCP APIs include board management endpoints for common automatio
 - Set desktop and mobile home boards for the current user
 - Configure global board defaults such as public home boards and status behavior
 
+Creating, duplicating, or reconfiguring a widget validates its integration selection on the server. The caller needs
+use access for each newly linked integration; unchanged links remain editable through normal board permissions.
+
 Board layout responses identify each layout with a `mobile`, `base`, or `custom` role. Mobile and Base are protected. Layout-saving clients must preserve existing roles, keep Mobile at breakpoint `0`, keep Base as the highest breakpoint, and use unique custom breakpoints between them. The layout save operation returns the canonical saved layouts, including server-generated IDs for new custom layouts. A non-Base layout can be regenerated from Base with the protected reset operation.
 
 Use the interactive API reference to inspect the exact request body for each endpoint under the `boards` and `settings` tags.