# Pub

Recommend AXM extensions from a Pub (Dart, Flutter) package and target Pub packages from an extension.

AXM reads Dart extension metadata from a top-level `agentExtensions` key in
`pubspec.yaml`. This is the [two-way linking](/docs/package-ecosystems/overview)
model applied to the Pub ecosystem. The same convention covers plain Dart
packages and Flutter packages.

## Recommend extensions from a package

Add an `agentExtensions` list to `pubspec.yaml`. Each entry is an extension
reference (`@owner/<type>/<name>`):

```yaml
# pubspec.yaml
name: agentxm_example_tinyflags
version: 0.1.0

agentExtensions:
  - { ref: "@examples/packs/dart-pub-tinyflags" }
```

Pub preserves unknown top-level keys, so the `agentExtensions` list travels with
your published package.

Keep recommendations **identity-only** — omit `versionRange`. AXM resolves the
reference to the newest matching extension version and pins it in the user's
`axm.lock`. Prefer recommending a single **pack** so you keep one stable
reference while its contents evolve.

Add a semver `versionRange` only when your package genuinely pairs with a
bounded major line of the extension:

```yaml
agentExtensions:
  - { ref: "@examples/packs/dart-pub-tinyflags", versionRange: "^1.0.0" }
```

## Target Pub packages from an extension

On the extension manifest (`skill.json`, `pack.json`, `subagent.json`, …), add a
`packages` array with a Pub [purl](https://github.com/package-url/purl-spec):

```jsonc
// pack.json
{
  "packages": [{ "purl": "pkg:pub/agentxm_example_tinyflags" }],
}
```

Use the package name as published to pub.dev as the purl name.

### Version ranges

Default to identity-only. Add a [VERS](https://github.com/package-url/vers-spec)
`versionRange` with the `pub` scheme only when the extension depends on package
APIs introduced or removed in a known range:

```jsonc
{
  "packages": [
    {
      "purl": "pkg:pub/agentxm_example_tinyflags",
      "versionRange": "vers:pub/>=0.1.0|<1.0.0",
    },
  ],
}
```

## Official status

When the Pub package recommends an extension through the AgentXM Registry
**and** that extension names the package as a companion via its purl, AXM
derives **official** status for the pair — no extra flag. See
[Official extensions](/docs/package-ecosystems/overview#official-extensions).

## Reference fixture

The
[`dart-pub-lib`](https://github.com/agentxm/polyglot-examples/tree/main/dart-pub-lib)
and
[`dart-pub-app`](https://github.com/agentxm/polyglot-examples/tree/main/dart-pub-app)
directories in `polyglot-examples` are the working fixtures for everything
above. The package publishes a TinyFlags companion pack and recommends it from
the `agentExtensions` key in `pubspec.yaml`; the pack and each skill declare the
package's `pkg:pub` purl as an identity-only companion package.