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

# Docs Portal Setup

> DotNetDocs.com setup for AI•Pkg.Core API reference, docs.aipkg.org developer portal structure, OpenAPI spec requirements, and documentation CI/CD pipeline.

AI•Pkg documentation is split into two surfaces:

<CardGroup cols={2}>
  <Card title="AI•Pkg.Core API Reference" icon="cube" href="https://docs.aipkg.org/api/core/">
    Hosted via **DotNetDocs.com** at `docs.aipkg.org/api/core/`. Sourced from XML doc comments. Authoritative reference for library consumers and tool authors.
  </Card>

  <Card title="Developer Portal" icon="book-open" href="https://docs.aipkg.org">
    Hosted at `docs.aipkg.org`. Getting-started guides, CLI reference, spec docs, platform integration guides, and embedded API reference.
  </Card>
</CardGroup>

***

## 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

<Steps>
  <Step title="Enable XML doc generation">
    Add to `AI•Pkg.Core.csproj`:

    ```xml theme={null}
    <PropertyGroup>
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
      <DocumentationFile>AI•Pkg.Core.xml</DocumentationFile>
      <NoWarn>$(NoWarn);CS1591</NoWarn>
    </PropertyGroup>
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configure custom domain">
    Point `docs.aipkg.org/api/core/` → DotNetDocs hosted URL.
  </Step>
</Steps>

### XML Doc Comment Requirements

<Warning>
  100% of public surface members must carry XML doc comments before the 1.0.0 release.
</Warning>

| 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:**

```csharp theme={null}
/// <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:

```http theme={null}
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:**

```csharp theme={null}
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:**

```markdown theme={null}
# 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](../specs/09-registry-api)) 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

<Tabs>
  <Tab title="On AI•Pkg.Core Publish">
    <Steps>
      <Step title="Detect new NuGet publish">
        GitHub Actions workflow detects new NuGet publish.
      </Step>

      <Step title="Trigger DotNetDocs">
        DotNetDocs.com webhook triggered automatically (or via polling).
      </Step>

      <Step title="Deploy new version">
        New API reference deployed at `/api/core/{version}/`; latest pointer updated.
      </Step>
    </Steps>
  </Tab>

  <Tab title="On Server Deploy">
    <Steps>
      <Step title="Fetch OpenAPI spec">
        GitHub Actions fetches `/v3/openapi.json` from staging.
      </Step>

      <Step title="Validate completeness">
        Validates spec completeness (all endpoints documented).
      </Step>

      <Step title="Deploy registry API reference">
        Deploys updated Registry API reference to docs portal.
      </Step>
    </Steps>
  </Tab>

  <Tab title="On Spec Change">
    <Steps>
      <Step title="Render specs">
        GitHub Actions renders spec MDX files to HTML.
      </Step>

      <Step title="Deploy to portal">
        Deploys to corresponding `/format/` pages on docs portal.
      </Step>
    </Steps>

    <Note>
      The specs in `src/AI•Pkg.Docs/specs/` are the authoritative source for format reference pages.
    </Note>
  </Tab>
</Tabs>

***

## 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.