> ## Documentation Index
> Fetch the complete documentation index at: https://aipkg.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Targeting

> AI Platform Monikers (APMs) — the hierarchical string identifiers that describe AI platforms, their fallback resolution graph, install paths, and compatibility rules.

AI Platform Monikers (APMs) are hierarchical string identifiers that describe AI platforms and tools that can consume AI•Pkg packages. They serve the same purpose as Target Framework Monikers (TFMs) in NuGet: they allow a single package to ship platform-specific content and allow the installer to select the most appropriate files for the current environment.

***

## Moniker Syntax

APMs are lowercase alphanumeric strings with hyphens. The hierarchy is encoded in the moniker string itself — a parent is a prefix of its child, separated by `-`:

```
ai
ai-{platform}
ai-{platform}-{variant}
```

<Note>
  The root moniker is `ai`. Every moniker implicitly has `ai` as its ultimate ancestor.
</Note>

***

## Canonical Moniker Table

| Moniker          | Display Name          | Parent    | Install Path           | Versioning                                        |
| ---------------- | --------------------- | --------- | ---------------------- | ------------------------------------------------- |
| `ai`             | All AI Platforms      | —         | *(root fallback only)* | Stable                                            |
| `claude`         | Claude (all)          | `ai`      | *(parent group only)*  | Stable                                            |
| `claude-code`    | Claude Code           | `claude`  | `.claude/`             | See [Platform Versioning](07-platform-versioning) |
| `claude-desktop` | Claude Desktop        | `claude`  | See below              | See [Platform Versioning](07-platform-versioning) |
| `copilot`        | GitHub Copilot (all)  | `ai`      | *(parent group only)*  | Stable                                            |
| `copilot-vscode` | Copilot in VS Code    | `copilot` | `.github/`             | See [Platform Versioning](07-platform-versioning) |
| `copilot-github` | Copilot on GitHub.com | `copilot` | `.github/`             | Stable                                            |
| `cursor`         | Cursor                | `ai`      | `.cursor/`             | Stable                                            |
| `windsurf`       | Windsurf              | `ai`      | `.windsurf/`           | Stable                                            |
| `continue`       | Continue              | `ai`      | `.continue/`           | Stable                                            |
| `opencode`       | OpenCode              | `ai`      | `.opencode/`           | Stable                                            |
| `aider`          | Aider                 | `ai`      | `.aider/`              | Stable                                            |
| `cline`          | Cline                 | `ai`      | `.cline/`              | Stable                                            |
| `zed`            | Zed AI                | `ai`      | `.zed/`                | Stable                                            |

### Claude Desktop Install Paths

Claude Desktop uses OS-specific config directories:

| OS      | Path                                    |
| ------- | --------------------------------------- |
| macOS   | `~/Library/Application Support/Claude/` |
| Windows | `%APPDATA%\Claude\`                     |
| Linux   | `~/.config/claude/`                     |

***

## Fallback Graph

The fallback graph defines which platform directories the installer checks, ordered from most specific to most general:

```
claude-code     →  claude  →  lib/shared
claude-desktop  →  claude  →  lib/shared
copilot-vscode  →  copilot →  lib/shared
copilot-github  →  copilot →  lib/shared
cursor          →  lib/shared
windsurf        →  lib/shared
continue        →  lib/shared
opencode        →  lib/shared
aider           →  lib/shared
cline           →  lib/shared
zed             →  lib/shared
```

Each step in the chain maps to a directory inside `lib/`. For example, `claude-code` maps to `lib/claude-code/`, `claude` maps to `lib/claude/`, and the terminal step always maps to `lib/shared/`.

### Resolution Algorithm

Given a target APM `T`, build the chain:

<Steps>
  <Step title="Start with T">
    Begin the chain with `[T]`.
  </Step>

  <Step title="Walk to parent">
    Find the parent of `T` in the canonical table. If a parent exists, append it to the chain and repeat until no parent remains.
  </Step>

  <Step title="Append shared">
    Append `lib/shared` (always last).
  </Step>
</Steps>

For file resolution, iterate the chain from **end to start** (least specific first), applying each `lib/{entry}/` directory's files. The last write wins, so most-specific files override less-specific ones.

***

## Package Compatibility

A package is compatible with a target APM if any of the following are true:

1. The package's `targets` array in `.aispec` includes the **target APM** exactly, OR
2. The package's `targets` array includes a **parent** of the target APM (e.g., a package targeting `claude` is compatible with `claude-code`), OR
3. The package's `targets` array is **empty or contains only `ai`** (universal package).

<Note>
  Compatibility checking is performed by `PlatformCompatibilityService` in `AI•Pkg.Core`. See [SDK Interface](10-sdk-interface) for the API surface.
</Note>

***

## Moniker Normalization

APMs are always lowercased. During ingestion and search, the server normalizes APM values:

* Convert to lowercase
* Strip leading/trailing whitespace
* Reject any characters outside `[a-z0-9-]`
* Reject monikers longer than 64 characters

***

## Unknown Monikers

A package may declare a dependency on or include files for a moniker not in the canonical table. Installers must:

* **Warn** (not error) when encountering an unknown moniker in `targets[]`
* **Silently skip** unknown `lib/{unknown-moniker}/` directories during installation
* **Not fail validation** solely due to an unknown moniker (forward compatibility)

<Info>
  The registry server logs unknown monikers for monitoring purposes.
</Info>

***

## Moniker Registration

New monikers are added to the canonical table by opening a PR to the AI•Pkg spec repository. Requirements for a new moniker:

1. Must have a public, documented plugin/extension system
2. Must have a clearly defined install path
3. Must be lower-kebab-case
4. Must not conflict with an existing moniker or be a prefix of one

***

## APM in Search Queries

The search endpoint accepts an `apm` query parameter that filters results to packages compatible with the specified platform:

```http theme={null}
GET /v3/search?q=mcp&apm=claude-code
```

The server expands `claude-code` to `[claude-code, claude]` using the fallback graph, then returns packages whose `targets` array intersects with the expanded set (plus universal packages targeting `lib/shared/`).

***

## APM Stability Guarantees

| Moniker                                       | Stability                                |
| --------------------------------------------- | ---------------------------------------- |
| `claude`, `claude-code`, `claude-desktop`     | Stable                                   |
| `copilot`, `copilot-vscode`, `copilot-github` | Stable                                   |
| `cursor`, `windsurf`, `continue`              | Stable                                   |
| `opencode`, `aider`, `cline`, `zed`           | Stable                                   |
| Any other moniker                             | Provisional until canonical registration |

<Note>
  Stable monikers will not be removed or renamed. If a platform is discontinued, its moniker is deprecated (marked in the registry) but not deleted. For how platforms evolve over time and how breaking changes in host platforms are handled, see [Platform Versioning](07-platform-versioning).
</Note>

***

## Example: Multi-Platform Package Layout

A package that ships different skill files for Claude Code vs Copilot but shares a common prompt:

```
my-tool.1.0.0.aipkg
├── my-tool.aispec
└── lib/
    ├── shared/
    │   └── prompts/
    │       └── base-prompt.md          ← All platforms
    ├── claude-code/
    │   └── skills/
    │       └── my-tool.md              ← Claude Code only
    └── copilot/
        └── instructions/
            └── my-tool.md              ← All Copilot variants
```

<Tabs>
  <Tab title="claude-code install">
    * `base-prompt.md` is installed (from `lib/shared/`)
    * `skills/my-tool.md` is installed (from `lib/claude-code/`)
    * `instructions/my-tool.md` is **not** installed (wrong platform)
  </Tab>

  <Tab title="copilot-vscode install">
    * `base-prompt.md` is installed (from `lib/shared/`)
    * `instructions/my-tool.md` is installed (from `lib/copilot/` via parent fallback)
    * `skills/my-tool.md` is **not** installed (wrong platform)
  </Tab>
</Tabs>