# Teddy Extension Guide (v0.5)

This guide shows how third-party WordPress plugins register capabilities with Teddy **without modifying Teddy core**.

## Prerequisites

- Teddy plugin active
- PHP 8.2+
- For **developer codegen tools** (`dev.*`): Settings → Features → **Enable extension SDK** = ON
- Tool registration via `teddy_boot` works whenever Teddy is active (SDK helpers are always loaded)

## Quick start: register a tool

```php
<?php
add_action( 'teddy_boot', function () {
    \Bean\Teddy\register_tool( new MyPlugin\Teddy\ListAppointmentsTool() );
});
```

Your tool must implement `Bean\Teddy\Domain\Tool\ToolInterface`:

| Method | Notes |
|--------|--------|
| `name()` | Dotted name: `myplugin.appointment.list` |
| `description()` | Shown to the AI model |
| `input_schema()` | JSON Schema for arguments |
| `required_capability()` | WordPress capability |
| `is_dangerous()` | `true` → requires approval / dry-run |
| `execute()` | Runs after full safety lifecycle |
| `dry_run()` | Preview for dangerous tools |

Extension tools go through the **same lifecycle** as core tools (permission → validate → audit → execute). There is no bypass.

## Register a knowledge resource

```php
add_action( 'teddy_boot', function () {
    \Bean\Teddy\register_resource( new class implements \Bean\Teddy\Domain\Knowledge\KnowledgeResourceInterface {
        public function key(): string { return 'myplugin.appointments'; }
        public function label(): string { return 'Appointments'; }
        public function search( string $query, array $args = array() ): array {
            return array(); // list of title/url/excerpt hits
        }
    } );
});
```

## Register a workflow

```php
add_action( 'teddy_boot', function () {
    \Bean\Teddy\register_workflow(
        new \Bean\Teddy\Domain\Workflow\WorkflowDefinition(
            'myplugin.publish_appointment',
            'Publish appointment listing',
            array( /* steps */ )
        )
    );
});
```

## Register a prompt or AI action

```php
\Bean\Teddy\register_prompt( $my_prompt_template );
\Bean\Teddy\register_ai_action( 'myplugin.summarize_day', $callable_or_class );
```

## Global helpers

| Function | Purpose |
|----------|---------|
| `teddy()` | SDK facade |
| `register_tool( ToolInterface $tool )` | Register a domain tool |
| `register_workflow( WorkflowDefinition $def )` | Register a workflow |
| `register_prompt( PromptTemplateInterface $tpl )` | Register a prompt template |
| `register_resource( KnowledgeResourceInterface $resource )` | Register a knowledge source |
| `register_ai_action( string $key, callable\|string $handler )` | Register a custom AI action handler |

## Object API

```php
$teddy = \Bean\Teddy\teddy();
$teddy->tools()->register( $tool );
$teddy->workflows()->register( $definition );
$teddy->prompts()->register( $template );
$teddy->resources()->register( $resource );
$teddy->actions()->register( 'myplugin.key', $handler );
```

## Hooks

| Hook | When |
|------|------|
| `teddy_boot` | Teddy container + SDK ready |
| `teddy_register_extensions` | After `teddy_boot`, for registrations |
| `teddy_register_domain_tools` | Internal — core tool registration |

## Listing tools (REST)

`GET /wp-json/teddy/v1/domain-tools` returns each tool with:

```json
{
  "name": "demo.ping",
  "origin": "extension",
  "plugin": "teddy-demo-extension"
}
```

Core tools show `"origin": "core", "plugin": "teddy"`.

## Developer tools (SDK enabled)

When `enable_extension_sdk` is on, Teddy registers code-generation tools (preview only):

- `dev.cpt.create`
- `dev.taxonomy.create`
- `dev.rest_endpoint.create`

These return PHP snippets for review — they do **not** execute generated code.

## Demo plugin

See `examples/demo-extension/teddy-demo-extension.php`. Copy it to `wp-content/plugins/` and activate alongside Teddy.

Exit criterion: that demo registers `demo.ping` with **zero Teddy core edits**.

## Naming rules

- Tool names must contain a dot: `vendor.action`
- Do not reuse core tool names (`post.create`, `wc.product.list`, …)
- Dangerous tools must implement meaningful `dry_run()` previews

## Related docs

- Architecture: `docs/02-system-architecture-prompt.md` §4.4
- Roadmap: `docs/04-roadmap-prompt.md` v0.5
- Module: `docs/modules/sdk/README.md`