Docs Portal Setup

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

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>

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.

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 Type	Required 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:

Install path — where files land after aipkg install
File formats — what file types the platform accepts
Directory layout — expected structure within the install path
Example package — a minimal working .aispec and package layout
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

On AI•Pkg.Core Publish
On Server Deploy
On Spec Change

Detect new NuGet publish

GitHub Actions workflow detects new NuGet publish.

Trigger DotNetDocs

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

Deploy new version

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

Fetch OpenAPI spec

GitHub Actions fetches /v3/openapi.json from staging.

Validate completeness

Validates spec completeness (all endpoints documented).

Deploy registry API reference

Deploys updated Registry API reference to docs portal.

Render specs

GitHub Actions renders spec MDX files to HTML.

Deploy to portal

Deploys to corresponding /format/ pages on docs portal.

The specs in src/AI•Pkg.Docs/specs/ are the authoritative source for format reference pages.

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.

Getting Started

Specifications

Implementation Plan

Legacy (NuGetGallery)

Specs

Docs Portal Setup

AI•Pkg.Core API Reference

Developer Portal

DotNetDocs.com for `AI•Pkg.Core`

What is DotNetDocs.com

Setup

XML Doc Comment Requirements

Versioned Docs

Developer Portal: docs.aipkg.org

Site Structure

Registry API Reference

Per-Platform Integration Guides

OpenAPI Spec Requirements

Documentation CI/CD

Contribution Workflow

AI•Pkg.Core API Reference

Developer Portal

​DotNetDocs.com for AI•Pkg.Core

​What is DotNetDocs.com

​Setup

​XML Doc Comment Requirements

​Versioned Docs

​Developer Portal: docs.aipkg.org

​Site Structure

​Registry API Reference

​Per-Platform Integration Guides

​OpenAPI Spec Requirements

​Documentation CI/CD

​Contribution Workflow

DotNetDocs.com for `AI•Pkg.Core`

What is DotNetDocs.com

Setup

XML Doc Comment Requirements

Versioned Docs

Developer Portal: docs.aipkg.org

Site Structure

Registry API Reference

Per-Platform Integration Guides

OpenAPI Spec Requirements

Documentation CI/CD

Contribution Workflow