Update README and license docs

license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

readme.md

@@ -1,21 +1,103 @@
 # @smarthome.exchange/integrations
 
-TypeScript-native device integrations for smarthome.exchange.
+🔌 TypeScript-native device integrations for smarthome.exchange.
 
-This package owns discovery, configuration flows, vendor clients, mappers, events, and normalized service calls for device ecosystems such as Hue and Wolf Smartset.
+This package owns discovery, configuration flows, vendor clients, mappers, events, normalized service calls, and generated integration descriptors. It keeps device-specific code out of the hub so a runtime can add, remove, publish, or mature integrations without rewriting the canonical home state model.
 
-The package also includes generated native TypeScript port skeletons for every upstream Home Assistant component domain under `ts/integrations/<domain>`. These are not Python wrappers and not a compatibility namespace. They are TypeScript classes that start as `descriptor-only` integrations and are replaced by handwritten clients/mappers/runtime code as each port matures.
+## Issue Reporting and Security
 
-It does not own the canonical device registry, approvals, audit receipts, automations, or persistent home state. Those stay in `@smarthome.exchange/hub`.
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Install
 
 Publishing is restricted to `https://packages.foss.global/` through `publishConfig`.
 
+```bash
+pnpm add @smarthome.exchange/integrations
+```
+
+## Use The Default Registry
+
+```ts
+import { DiscoveryEngine, createDefaultIntegrationRegistry } from '@smarthome.exchange/integrations';
+
+const registry = createDefaultIntegrationRegistry();
+const engine = new DiscoveryEngine(registry);
+
+console.log(registry.get('hue')?.displayName);
+
+const candidates = await engine.runActiveDiscovery({});
+console.log(candidates);
+```
+
+## Public Surface
+
+| Export group | What it gives you |
+| --- | --- |
+| Core classes | `BaseIntegration`, `DescriptorOnlyIntegration`, `DiscoveryDescriptor`, `DiscoveryEngine`, `IntegrationRegistry`, `IntegrationRuntimeManager`, `ConsoleLogger`, `JsonFileConfigStore`. |
+| Core errors | `IntegrationError`, `DiscoveryError`, `AuthenticationError`, `DeviceCommunicationError`. |
+| Core types | Discovery, config-flow, runtime, service-call, entity, logging, and integration status contracts. |
+| Protocol namespaces | `mdns`, `ssdp`, `http`, `mqtt`, `bluetooth`, and `usb` descriptor helpers. |
+| Registry helpers | `integrations` and `createDefaultIntegrationRegistry()`. |
+| Generated metadata | `generatedHomeAssistantPortIntegrations`, `generatedHomeAssistantPortCount`, and `handwrittenHomeAssistantPortDomains`. |
+| Handwritten modules | Hue and Wolf Smartset exports from `ts/integrations/index.ts`. |
+
+## Integration Lifecycle
+
+```ts
+const integration = registry.get('hue');
+
+if (!integration) {
+  throw new Error('Hue integration not found');
+}
+
+const matches = await engine.validateCandidate({
+  id: 'hue:bridge:office',
+  source: 'manual',
+  integrationDomain: 'hue',
+  displayName: 'Office Hue Bridge',
+  confidence: 0.9,
+  metadata: {
+    baseUrl: 'https://192.168.1.20',
+  },
+});
+
+console.log(matches);
+```
+
+The hub uses the same primitives through `discoverIntegrationCandidates()` and `setupIntegration(...)`, then upserts normalized devices into the canonical device registry.
+
+## Home Assistant Port Skeletons
+
+The package includes generated native TypeScript port skeletons for upstream Home Assistant component domains under `ts/integrations/<domain>`. These are not Python wrappers and not a compatibility namespace. They are TypeScript classes that start as `descriptor-only` integrations and get replaced by handwritten clients, mappers, discovery, config-flow, and runtime code as each port matures.
+
+Current generated metadata includes `generatedHomeAssistantPortCount = 1394`. Descriptor-only integrations intentionally throw from `setup()` until a real TypeScript runtime exists.
+
+## Handwritten Integrations
+
+| Integration | Current capability |
+| --- | --- |
+| Hue | Bridge discovery, validation, config flow, light/device/entity mapping, and `light.turn_on` / `light.turn_off` service calls. |
+| Wolf Smartset | Discovery/config/runtime structure is present, currently marked `descriptor-only`. |
+
+The `integrations` array also registers many handwritten domain folders and then fills gaps from the generated Home Assistant descriptors when `createDefaultIntegrationRegistry()` runs.
+
 ## CLI
 
 ```bash
 pnpm cli list
 pnpm cli inspect hue
 pnpm cli discover
+pnpm cli setup hue
+```
+
+When installed as a package, the binary is `shx-integrations`:
+
+```bash
+shx-integrations list
+shx-integrations inspect hue
+shx-integrations discover
+shx-integrations setup hue
 ```
 
 ## Regenerating Home Assistant Port Skeletons
@@ -25,3 +107,38 @@ pnpm generate:ha
 ```
 
 The generator reads `HA_CORE_COMPONENTS_DIR` or `/tmp/opencode/homeassistant-core/homeassistant/components`, preserves handwritten integration folders, and regenerates only folders with the `.generated-by-smarthome-exchange` marker.
+
+## Boundaries
+
+This package does not own canonical device registry state, approvals, audit receipts, automations, dashboards, or persistent home state. Those stay in `@smarthome.exchange/hub`. Integrations normalize vendor reality into shared interface contracts and expose runtime/service primitives for the hub to consume.
+
+## Scripts
+
+```bash
+pnpm cli list
+pnpm generate:ha
+pnpm test
+pnpm build
+pnpm buildDocs
+```
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH\
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.