Plugin SDK Documentation Plan

Status

Tutorial section: COMPLETE

All 14 tutorial steps are written and published on launch-0.80.0.

Advanced section: COMPLETE

All 6 advanced topics are written:

  1. [x] Collection Semantics - Set vs Array vs EntitySet
  2. [x] Embedded Types - Plain classes vs SubResources
  3. [x] Values - Opaque (secrets) and SetOnce (immutability)
  4. [x] Resolvables - Late-binding cross-resource references
  5. [x] Parent-Child Resources - Tiered discovery and ordering
  6. [x] Discovery Filters - Excluding resources from discovery

What's Next

Plugin SDK Reference

Placeholder files exist, need content:

  1. [ ] Plugin Interface - Full ResourcePlugin interface spec
  2. [ ] Schema - Resource, ResourceHint, FieldHint annotations

Documentation Structure

docs/plugin-sdk/
├── index.md                          # ✅ Overview
├── tutorial/
│   ├── index.md                      # ✅ Introduction
│   ├── 01-scaffold.md                # ✅ Project setup
│   ├── 02-schema.md                  # ✅ PKL schema
│   ├── 03-target.md                  # ✅ Target configuration
│   ├── 04-configuration.md           # ✅ RateLimit, LabelConfig
│   ├── 05-create.md                  # ✅ Create operation
│   ├── 06-read.md                    # ✅ Read operation
│   ├── 07-update.md                  # ✅ Update operation
│   ├── 08-delete.md                  # ✅ Delete operation
│   ├── 09-list.md                    # ✅ Discovery/List
│   ├── 10-error-handling.md          # ✅ OperationErrorCode
│   ├── 11-conformance-ci.md          # ✅ Conformance tests
│   ├── 12-ci-setup.md                # ✅ GitHub Actions
│   ├── 13-local-testing.md           # ✅ Local testing workflow
│   └── 14-real-world-plugins.md      # ✅ Plugin examples
├── advanced/
│   ├── collection-semantics.md       # ✅ Set/Array/EntitySet
│   ├── embedded-types.md             # ✅ Plain classes vs SubResource
│   ├── values.md                     # ✅ Opaque and SetOnce
│   ├── resolvables.md                # ✅ Cross-resource references
│   ├── parent-child-resources.md     # ✅ Tiered discovery
│   └── discovery-filters.md          # ✅ MatchFilter/FilterCondition
└── reference/
    ├── plugin-interface.md           # TODO
    └── schema.md                     # TODO

LLM-Friendly Documentation Principles

  1. Self-contained pages - No "see above" or cross-page dependencies
  2. Complete, runnable examples - Not snippets, full working code
  3. Explicit everything - State defaults, define terms
  4. Consistent structure - Same patterns across all pages
  5. Define before use - No forward references to unexplained concepts