# Neotask Construct for agents

Launch state: **Live**. Agents can register at /auth.md, exchange the identity assertion for a short-lived access token, and call the production Agent API.

Neotask Construct is the catalog of plugins and skills for Neotask agents. A package is `name` or `@org/name` in lowercase. Each release is signed, published on a `stable` or `beta` channel and checked before it can be installed. People browse the catalog at [https://construct.neotask.ai](https://construct.neotask.ai); the website shows install commands but installs nothing itself.

An agent finds and installs packages in one of two ways, both under the same signed-in, claimed Neotask account:

- **The CLI**, on a computer with the Neotask runner installed. The runner verifies and installs the release.
- **The Agent API**, with a bearer token for `https://neotask.ai/api/agent`. The agent resolves an install, verifies the signed release itself and reports the result.

Construct operations require a claimed registration. An unclaimed agent receives `claim_required`: relay the claim handoff to its human and retry after the claim completes. Read `GET /api/agent/v1/capabilities` first; it reports whether each Construct operation is available to the current credential.

## Install with the CLI

```sh
neotask construct search <text> --json
neotask construct info <package> --json
neotask construct versions <package> --json
neotask construct install <package> --json
neotask construct list --json
neotask construct update --all --json
neotask construct remove <package> --json
```

- `search` takes `--family plugin` or `--family skill`, `--limit` (1 to 100) and `--cursor` for the next page.
- `install <package[@version]>` takes `--channel stable|beta`, `--org <slug>` to scope a bare name, `--force` to reinstall, and `--agent <id>` to install a skill for one runner agent.
- `update` takes one installed package or `--all`. `remove` (alias `uninstall`) deletes only what Construct installed.
- `report <package> --reason <reason> --details <text>` reports a problem package; the reasons are malware, security, credential_theft, impersonation, spam, license, broken and other.

Install and update verify the signed release before anything is written. A refusal keeps Construct's error `code`. `nextAction.type` `sign_in` means run `neotask login` or finish the claim, then retry; `upgrade_gateway` means the release needs a newer Neotask. The [CLI guide](https://neotask.ai/docs/cli.md) covers installation and sign-in, and the [command reference](https://neotask.ai/docs/cli/commands.md) lists every option.

## Install through the Agent API

- [Search Construct packages](https://neotask.ai/docs/api/search-construct-packages.md): `GET /api/agent/v1/construct/packages/search`, scope `neotask:construct:read`
- [Read a Construct package](https://neotask.ai/docs/api/get-construct-package.md): `GET /api/agent/v1/construct/packages/{ref}`, scope `neotask:construct:read`
- [List Construct package versions](https://neotask.ai/docs/api/list-construct-package-versions.md): `GET /api/agent/v1/construct/packages/{ref}/versions`, scope `neotask:construct:read`
- [Read Construct release readiness](https://neotask.ai/docs/api/get-construct-release-readiness.md): `GET /api/agent/v1/construct/packages/{ref}/release-readiness`, scope `neotask:construct:read`
- [Match installed content to a release](https://neotask.ai/docs/api/match-construct-content.md): `POST /api/agent/v1/construct/packages/{ref}/content-match`, scope `neotask:construct:install`
- [Resolve a Construct install](https://neotask.ai/docs/api/resolve-construct-artifact.md): `GET /api/agent/v1/construct/resolve`, scope `neotask:construct:install`
- [Read the signed grant manifest](https://neotask.ai/docs/api/get-construct-grant-manifest.md): `GET /api/agent/v1/construct/entitlements/manifest`, scope `neotask:construct:install`
- [Report a Construct install](https://neotask.ai/docs/api/report-construct-install.md): `POST /api/agent/v1/construct/installs`, scope `neotask:construct:install`
- [Report a Construct package](https://neotask.ai/docs/api/report-construct-package.md): `POST /api/agent/v1/construct/reports`, scope `neotask:construct:feedback`

1. Search, then read the package and its versions. Choose a release that release readiness reports as installable on your channel.
2. Resolve the install. The response names the selected release, its signed release manifest and a download capability that expires after 60 seconds. Download promptly and never share or log the capability.
3. Verify the signed release manifest against the pinned release keys, and the download against it, before you write any file. The signed grant manifest lists this installation's effective grants.
4. Report the install, update or removal with a stable `Idempotency-Key`, so a retry is recorded once.

Never fall back to an unsigned, modified or cached artifact when resolve, download or verification fails. Honor `Retry-After` on `rate_limited`, and retry `unavailable` later with backoff. Use `POST /api/agent/v1/construct/reports` to report a package that is malicious or broken. Each operation page lists its request, response and errors; [OpenAPI](https://neotask.ai/openapi.json) has the schemas.

## Browse the public catalog

The Construct API at `https://neotask.ai/api/construct/v1` serves its public catalog without a credential. These routes are for discovery only and grant no install access:

- `GET /public/packages?q=&family=&category=&official=&sort=&limit=&cursor=`: Search and list catalog packages
- `GET /public/packages/{ref}`: Package detail
- `GET /public/packages/{ref}/versions`: Releases, newest first
- `GET /public/packages/{ref}/versions/{version}`: Release detail
- `GET /public/packages/{ref}/release-readiness`: Whether a release can be installed
- `GET /public/categories`: Catalog categories
- `GET /public/featured`: Featured collections
- `GET /public/publishers/{handle}`: Publisher profile
- `GET /public/publishers/{handle}/packages`: A publisher's catalog packages
- `GET /public/catalog-snapshot`: The signed catalog snapshot

The [Construct API OpenAPI document](https://neotask.ai/api/construct/v1/openapi.json) describes the Construct routes and their error envelope; clients branch on the error `code`. Routes marked `siteAccess` belong to signed-in people on the Construct website and do not accept an agent bearer token. Agents use the Agent API operations above instead. Package authors publish from their repository's GitHub Actions workflow through the `/ci` routes, not with an agent token.