Skip to main content
AI•Pkg documentation is split into two surfaces:

AI•Pkg.Core API Reference

Hosted via DotNetDocs.com at docs.aipkg.org/api/core/. Sourced from XML doc comments. Authoritative reference for library consumers and tool authors.

Developer Portal

Hosted at docs.aipkg.org. Getting-started guides, CLI reference, spec docs, platform integration guides, and embedded API reference.

​
DotNetDocs.com for AI•Pkg.Core

​
What is DotNetDocs.com

DotNetDocs.com is a hosted documentation service for .NET libraries. It ingests compiled XML documentation files (generated by <GenerateDocumentationFile>true</GenerateDocumentationFile>) and produces a navigable API reference site — analogous to docs.rs for Rust.

​
Setup

1

Enable XML doc generation

Add to AI•Pkg.Core.csproj:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <DocumentationFile>AI•Pkg.Core.xml</DocumentationFile>
  <NoWarn>$(NoWarn);CS1591</NoWarn>
</PropertyGroup>
2

Register on DotNetDocs.com

Register AI•Pkg.Core, linking to the NuGet package ID AI•Pkg.Core. DotNetDocs automatically pulls the latest published package and regenerates the docs on each new version.
3

Configure custom domain

Point docs.aipkg.org/api/core/ → DotNetDocs hosted URL.

​
XML Doc Comment Requirements

100% of public surface members must carry XML doc comments before the 1.0.0 release.
Member TypeRequired Tags
Class / struct / record<summary>, <remarks> (if non-trivial)
Public property<summary>, <value> (if not obvious)
Public method<summary>, <param> for each param, <returns> if not void, <exception> for documented throws
Public constructor<summary>, <param> for each param
Enum<summary> on type, <summary> on each member
Example: 
/// <summary>
/// Resolves AI Platform Moniker (APM) fallback chains and compatibility
/// for the AI•Pkg platform targeting system.
/// </summary>
/// <remarks>
/// Use this service to determine which <c>apm/</c> directories in an
/// <c>.aipkg</c> archive apply to a given target platform, and to check
/// whether a package's declared <c>targets</c> are compatible with the
/// installer's target.
/// </remarks>
public sealed class PlatformCompatibilityService
{
    /// <summary>
    /// Returns the ordered fallback chain for the given APM moniker.
    /// </summary>
    /// <param name="moniker">
    ///   The target APM moniker (e.g., <c>"claude-code"</c>).
    /// </param>
    /// <returns>
    ///   An ordered list of source paths, from most specific to least specific,
    ///   ending with <c>"shared"</c>.
    ///   For example: <c>["apm/claude-code", "apm/claude", "apm/ai", "shared"]</c>.
    /// </returns>
    /// <exception cref="ArgumentNullException">
    ///   Thrown when <paramref name="moniker"/> is null.
    /// </exception>
    public IReadOnlyList<string> GetFallbackChain(string moniker) { ... }
}

​
Versioned Docs

DotNetDocs hosts docs per NuGet package version. The docs.aipkg.org/api/core/ URL always points to the latest stable version. Previous versions are accessible via /api/core/{version}/.

​
Developer Portal: docs.aipkg.org

​
Site Structure

docs.aipkg.org/
├── /                           ← Landing / overview
├── /quickstart                 ← 5-minute getting-started guide
├── /format/
│   ├── /archive                ← .aipkg archive layout (from Package Format spec)
│   ├── /manifest               ← .aispec schema reference (from Metadata Schema spec)
│   └── /platforms              ← APM moniker reference (from Platform Targeting spec)
├── /cli/                       ← aipkg CLI reference (from SDK Interface spec)
│   ├── /pack
│   ├── /push
│   ├── /install
│   ├── /restore
│   ├── /verify
│   └── /...
├── /platforms/                 ← Per-platform integration guides
│   ├── /claude-code
│   ├── /copilot
│   ├── /cursor
│   └── /...
├── /api/
│   ├── /v3                     ← Registry API reference (OpenAPI-generated)
│   └── /core/                  ← AI•Pkg.Core .NET API (DotNetDocs)
├── /guides/
│   ├── /creating-a-skill-package
│   ├── /publishing-an-mcp-server
│   ├── /multi-platform-packages
│   └── /ci-cd-publishing
└── /contributing/

​
Registry API Reference

The Registry API reference at /api/v3/ is generated from an OpenAPI specification published by the server: 
GET https://aipkg.org/v3/openapi.json
Generated using Microsoft.AspNetCore.OpenApi (built into ASP.NET Core 10). The docs portal fetches this spec and renders it using Scalar UI (or Swagger UI). Server configuration: 
builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer<AipkgOpenApiTransformer>();
});

app.MapOpenApi("/v3/openapi.json");
Every Minimal API endpoint must declare:
  • .WithName() — operation ID
  • .WithSummary() — one-line description
  • .WithDescription() — detailed description
  • .WithTags() — grouping
  • .Produces<T>() — response type annotations

​
Per-Platform Integration Guides

Each platform guide covers:
  1. Install path — where files land after aipkg install
  2. File formats — what file types the platform accepts
  3. Directory layout — expected structure within the install path
  4. Example package — a minimal working .aispec and package layout
  5. Known limitations — what the platform doesn’t support yet
Example structure for the Claude Code guide: 
# Claude Code Integration

## Install Path
Packages targeting `claude-code` install to `.claude/` relative to the
project root (or `~/.claude/` for global installs).

## Supported File Types
- **Skills:** `.md` files in `.claude/skills/`
- **Commands:** `.md` files in `.claude/commands/`
- **Agents:** `.md` files in `.claude/agents/`
- **Hooks:** executable scripts configured in `.claude/settings.json`
- **MCP Servers:** entries in `.claude/mcp.json`

​
OpenAPI Spec Requirements

Every Registry API endpoint (see Registry API spec) must be represented with:
  • Correct HTTP method and path
  • All path parameters documented with types and examples
  • All query parameters documented with types, defaults, and examples
  • All request body schemas
  • All response schemas with examples
  • Error response schemas: 400, 401, 403, 404, 409, 413, 429, 500
  • Authentication scheme: ApiKey header (X-NuGet-ApiKey retained for CLI compatibility)

​
Documentation CI/CD

1

Detect new NuGet publish

GitHub Actions workflow detects new NuGet publish.
2

Trigger DotNetDocs

DotNetDocs.com webhook triggered automatically (or via polling).
3

Deploy new version

New API reference deployed at /api/core/{version}/; latest pointer updated.

​
Contribution Workflow

The docs portal source lives in a separate repository (aipkg-docs). Contributions via PR. The API reference (DotNetDocs, OpenAPI) is auto-generated and must not be manually edited. Broken link checks and spell checks run on every PR via CI.