# Example Addon Template

A minimal but complete Kindred Create addon that demonstrates all major SDK integration points. Copy this directory into `mods/`, rename it, and start building.

## File Structure

```
example-addon/
├── package.xml              Addon manifest with <kindred> extensions
├── Init.py                  Console-mode bootstrap (runs in all modes)
├── InitGui.py               GUI bootstrap — deferred registration
└── example_addon/
    ├── __init__.py           Python package marker
    ├── commands.py           FreeCAD command via kindred_sdk.register_command()
    └── panel.py              Dock panel widget factory
```

## What This Template Demonstrates

| Feature | File | SDK function |
|---------|------|-------------|
| Addon manifest with version bounds and dependencies | `package.xml` | — |
| Console bootstrap | `Init.py` | — |
| Deferred GUI initialization with `QTimer.singleShot` | `InitGui.py` | — |
| Command registration | `commands.py` | `kindred_sdk.register_command()` |
| Injecting commands into existing contexts | `InitGui.py` | `kindred_sdk.inject_commands()` |
| Dock panel registration | `InitGui.py`, `panel.py` | `kindred_sdk.register_dock_panel()` |
| Context lifecycle hooks | `InitGui.py` | `kindred_sdk.on_context_enter()` |
| Event bus subscription | `InitGui.py` | `kindred_sdk.on()` |

## Installation (for testing)

1. Copy or symlink this directory into the `mods/` folder at the repository root:

   ```bash
   cp -r docs/examples/example-addon mods/example-addon
   ```

2. Launch Kindred Create:

   ```bash
   pixi run freecad
   ```

3. Open the Python console (View > Panels > Python console) and verify:

   ```
   example-addon: console init
   ```

4. The "Example Panel" dock widget should appear on the right after ~2 seconds.

5. To test the command, create a Part Design Body and look for "Hello World" in the Part Design toolbar.

## Customizing

1. **Rename** — change `example-addon` and `example_addon` to your addon's name in all files
2. **Update `package.xml`** — set your name, description, repository URL, and load priority
3. **Add commands** — create more functions in `commands.py` and register them
4. **Add contexts** — use `kindred_sdk.register_context()` for custom editing modes
5. **Add overlays** — use `kindred_sdk.register_overlay()` for conditional toolbars
6. **Theme colors** — use `kindred_sdk.get_theme_tokens()` for Catppuccin Mocha palette access

## Common Pitfalls

- **Missing `<workbench>` tag** — `InitGui.py` will not be loaded without it, even if you don't register a workbench
- **Import at module level** — avoid importing `kindred_sdk` or `PySide6` at the top of `InitGui.py`; use deferred imports inside functions to avoid load-order issues
- **Blocking startup** — keep each `QTimer.singleShot` callback fast; do heavy work in background threads
- **Forgetting `<dependency>sdk</dependency>`** — your addon may load before the SDK if you omit this

## Further Reading

- [Writing an Addon](../../src/development/writing-an-addon.md) — full tutorial
- [Package.xml Schema](../../src/development/package-xml-schema.md) — manifest reference
- [KCSDK Python API](../../src/reference/kcsdk-python.md) — complete API reference