# Convoro — building themes & extensions with AI

Convoro is AI-friendly by design. This file (and https://convoro.co/api/ai/spec.json) is everything an AI model needs to scaffold a correct Convoro extension or theme. Full docs: https://convoro.co/docs/extensions.html

## What Convoro is
Convoro is a Laravel + Inertia/Vue community platform. Extensions are public GitHub repos linked into the catalog; themes restyle via CSS design tokens. No zip uploads, no Composer required for the basic path.

## Extension manifest (extension.json at repo root)
Required: id, name.
- `id`: unique, folder-safe (e.g. acme-hello)
- `name`: display name
- `version`: semver, e.g. 1.0.0
- `description`: short description
- `author`: author name
- `convoro`: version constraint, e.g. ">=0.1.0" (*, ^, ~, comparators supported)
- `type`: extension | theme
- `namespace`: PSR-4 root for src/, e.g. "Acme\\Hello\\"
- `provider`: FQCN of a Laravel ServiceProvider in src/ (optional)
- `migrations`: dir of Laravel migrations, run on enable (optional)
- `permissions`: array of {key,label,category,baseline} merged into the group editor
- `settings`: array of {key,label,type,default,help,options} rendered as a settings form
- `assets`: { "forum": "assets/forum.js", "admin": "assets/admin.js" } — prebuilt ESM, injected for enabled extensions
- `admin_url`: path to an admin management page (optional)
Settings field types: https://convoro.co/api/ai/spec.json → manifest.settings_field_types.

## Backend (optional service provider)
Extend Illuminate\Support\ServiceProvider. boot() registers routes/events (cacheable). Read settings: ExtensionManager::setting('id','key',$default). Permissions: $user->hasPermission('key').

## Frontend — window.Convoro
Register UI into named slots with a prebuilt ESM file (assets.forum / assets.admin):
window.Convoro.registerSlot(name, { mount(el, ctx){…} | html | component, order, ext })
Slots:
- `header:end` — forum header, right side
- `forum:footer` — below every forum page
- `forum:sidebar` — right rail on the community index (widgets)
- `topic:below` — under the opening post; ctx = { topicId, slug }

## Theme tokens (use these CSS vars, never Tailwind names; dark mode overrides them)
- `--c-primary` — brand color (space-separated RGB, use rgb(var(--c-primary)))
- `--c-surface` — card background
- `--c-surface-2` — subtle background
- `--c-text` — primary text (Tailwind: text-ink)
- `--c-text-2` — secondary text (text-ink-2)
- `--c-muted` — muted text (text-ink-muted)
- `--c-border` — borders (border-line)
- `--c-radius` — corner radius
- `--c-avatar-radius` — avatar shape

## Publishing
1. Put the extension in a PUBLIC GitHub repo with extension.json at the root.
2. Cut a GitHub release (tag) per version — Convoro installs the latest release, falling back to the default branch.
3. Link the repo in the Convoro catalog (Admin → Store → Publish from GitHub, or submit to convoro.co).
4. It appears in every site's Admin → Marketplace catalog; one-click install pulls the release archive from GitHub.

## Minimal widget example
window.Convoro.registerSlot('forum:sidebar', { ext:'acme-hello', mount(el){ el.innerHTML = '<div style="color:rgb(var(--c-text))">Hello</div>'; } });