# Package Registry

The package registry lets admins browse and install packages from an external
JSON index — a lightweight alternative to manually uploading `.pkg` files.

## Registry JSON Format

The registry is a static JSON file matching the `RegistryResponse` struct:

```json
{
  "packages": [
    {
      "id": "notes",
      "title": "Notes",
      "version": "0.8.0",
      "description": "Markdown notes with backlinks and graph view",
      "author": "switchboard",
      "type": "extension",
      "tier": "core",
      "download_url": "https://cdn.example.com/pkg/notes.pkg",
      "size": 48200,
      "updated_at": "2026-03-20T00:00:00Z"
    }
  ]
}
```

### Required Fields

| Field          | Description                                    |
|----------------|------------------------------------------------|
| `id`           | Package identifier (matches `manifest.json`)   |
| `title`        | Display name                                   |
| `version`      | Semver version string                          |
| `description`  | Short description                              |
| `download_url` | HTTPS URL to the `.pkg` file (must be HTTPS)   |

### Optional Fields

| Field        | Description                              |
|--------------|------------------------------------------|
| `author`     | Package author                           |
| `type`       | `extension` or `library`                 |
| `tier`       | `core`, `official`, or `community`       |
| `size`       | File size in bytes                       |
| `updated_at` | ISO 8601 timestamp of last update        |

## Configuring the Registry URL

### Via Admin UI

Navigate to **Admin > Settings > Package Registry** and enter the registry URL.

### Via API

```bash
curl -X PUT /api/v1/admin/settings/package_registry \
  -H "Content-Type: application/json" \
  -d '{"value": {"url": "https://cdn.example.com/pkg/registry.json"}}'
```

## Generating a Registry

Use `scripts/generate-registry.sh` to build a `registry.json` from a
directory of `.pkg` files:

```bash
# Default: reads dist/, uses placeholder base URL
./scripts/generate-registry.sh

# Custom directory and base URL
./scripts/generate-registry.sh ./my-packages https://cdn.example.com/pkg > registry.json
```

Requirements: `jq`, `unzip`, and `stat` (GNU or BSD).

## Self-Hosting

Any HTTPS-capable file server works. Upload your `.pkg` files and the
generated `registry.json` to the same directory, then point the admin
setting to the `registry.json` URL.

Example with a static file server:

```
/var/www/packages/
  registry.json
  notes.pkg
  chat.pkg
  chat-core.pkg
```

The registry is fetched and cached for 5 minutes on each browse request.