[@layout]: ./docs.layout.md

# Packages

Core supplies the CLI and standard site-authoring features. Optional packages add
learning tools, application interfaces, authentication, and deployment support.

Use the packages you need and keep their release versions aligned.

The [workshop tutorial](./start/build-a-site.guide.md) uses Core for layouts, menus, themes, queries, and Markdown components,
and explicitly adds Player for presentation.

---

## Author and present

| Package | Adds |
| --- | --- |
| [@pathmx/email](./email.reference) | Authored transactional email, capture previews, and durable Resend submission. |
| [@pathmx/core](./start/install.guide.md) | CLI, Sources, Blocks, links, rendering, and the standard Plugins. |
| [@pathmx/generate](./authoring/generate.reference) | Generate Sources from Knap templates, JSON or CSV data, and saved recipes. |
| [@pathmx/embed](./authoring/embed.reference) | X posts, YouTube players, and rich cards for public web pages. |
| [@pathmx/player](./learning/player.reference.md) | Focus, Slides, and Player links. |
| [@pathmx/share](./authoring/sources.reference.md#generate-a-share-image) | CLI generation and preview of saved share images. Generation requires Bun and Chromium. |
| [@pathmx/video](./authoring/video.reference.md) | YouTube, Vimeo, Loom, and local video playback. |
| [@pathmx/mermaid](./authoring/mermaid.reference.md) | Mermaid diagrams. |

---

## Connect and discover

| Package | Adds |
| --- | --- |
| [@pathmx/graph](./site/graph.reference.md) | Local Source graphs and backlinks. |
| [@pathmx/search](./site/search.reference.md) | Search across content the reader can access. |
| [@pathmx/webmcp](./extend/webmcp.reference) | Browser agent tools for mounted interactions, with optional exposure controls. |
| [@pathmx/ai](./extend/ai.reference) | Named AI models, tool loops, images, usage metering and durable job outcomes. |
| [@pathmx/agents](./extend/agents.reference) | Agents authored as Markdown Actors, asking with their own permissions and replying in threads. |

---

## Build learning and participation

| Package | Adds |
| --- | --- |
| [@pathmx/completion](./learning/completion.reference.md) | Requirement completion and progress. |
| [@pathmx/auth](./accounts/auth.reference.md) | Authentication and account interfaces. |
| [@pathmx/assessment](./learning/assessment.reference.md) | Markdown-authored assessment features. |
| [@pathmx/uppy](./accounts/attachments.reference.md) | Attachment uploads for Actors. |

---

## Extend and host

| Package | Adds |
| --- | --- |
| [@pathmx/react](./extend/react.reference.md) | React integration for application components. |
| [@pathmx/ui](./site/ui.reference.md) | Shared React interface components. |
| [@pathmx/short](./site/short.reference) | Source-owned short links, redirect parameters, and CLI management. |
| [@pathmx/feed](./site/feeds.reference) | Full-text RSS feeds from authored queries. |
| [@pathmx/analytics](./hosting/analytics.reference) | Public page views, selected Events, and private realtime CLI reports. |
| [@pathmx/deploy](./hosting/deployment.reference) | Shared-Git server deployment, writable Source preservation, and failure reports. |
| [@pathmx/cloudflare](./hosting/cloudflare.guide.md) | Cloudflare publication support. |

---

## Install and activate

`@pathmx/react` and `@pathmx/ui` are libraries: install them with `bun add` and
import them from your code. Feature Plugins and presets require activation.
Cloudflare and configured Completion compositions use the repository entrypoints
shown in their guides. Follow each package's exact setup.

Add a package to your project:

```sh
bun run pmx plugins add player
```

The command installs the dependency and activates it in your root `package.json`:

```json
{
  "pathmx": {
    "plugins": { "@pathmx/player": {} }
  }
}
```

Run `bun run pmx plugins list` to inspect installed packages and their activation status.
Commit `package.json` and the lockfile so collaborators use the same versions.

Each package key activates the package with its options. `{}` selects defaults.
Packages that declare configuration accept a JSON object in that entry. Invalid
options report the package and setting to fix. Adding a package preserves its
existing options. Removing its entry deactivates it without necessarily uninstalling
the dependency.

An explicitly activated package preset may replace a standard Core Plugin when
its feature requires configured integration. Assessment uses this to replace the
standard Input Plugin with its Assessment-aware Input configuration. A repository
Plugin remains the final override layer.

Use repository Plugin files for custom behavior or programmatic composition.
See [Plugin configuration](./extend/plugin-configuration.reference.md) for defining
configurable packages.

See [CLI: Plugins](./cli.reference.md#plugins) for commands and options.

## Related

- [Components](./authoring/components.reference.md)
- [How PathMX runs](./start/runs.guide.md)
- [Release notes](../releases/releases.changelog.md)