HYPERFLEET-761 - docs: align with documentation standards

CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to the HyperFleet API specification will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- CONTRIBUTING.md with development guidelines and workflow
+- CHANGELOG.md following Keep a Changelog format
+- CLAUDE.md with AI agent context and validation workflow
+
+### Changed
+- Improved README.md structure to align with HyperFleet documentation standards
+
+## [1.0.2] - 2026-01-13
+
+### Added
+- GitHub Actions workflow for automated releases
+- Standard schema component naming convention for provider schemas
+- Generation field to NodePool models
+
+### Changed
+- Standardized TypeSpec schema definitions with enums and validation enhancements
+- Refactored to support oapi-codegen compatibility
+- Updated OWNERS file to not block approval by bot
+
+### Fixed
+- Release GitHub Action to install tsp compiler
+
+## [1.0.0] - 2025-11-25
+
+First official stable release of the HyperFleet API specification.
+
+### Added
+- Complete CRUD operations for clusters, nodepools, and statuses
+- Status tracking and reporting with comprehensive history management
+- Core API variant with generic cluster spec
+- GCP API variant with GCP-specific cluster spec
+- Kubernetes-style timestamp conventions
+- List-based pagination for resource collections
+- Separate public and internal status endpoints
+- Interactive API documentation
+
+### Architecture
+- Simple CRUD operations only (no business logic)
+- Separation of concerns: API layer focuses on data persistence; orchestration logic handled by external components
+
+<!-- Links -->
+[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.0...v1.0.2
+[1.0.0]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/tag/v1.0.0

CLAUDE.md

@@ -0,0 +1,265 @@
+# HyperFleet API Spec - AI Agent Context
+
+This repository generates OpenAPI specifications from TypeSpec definitions. It supports multiple provider variants (core, GCP) using a shared codebase with provider-specific type aliases.
+
+## Quick Reference
+
+**Build commands:**
+```bash
+npm run build:core           # Generate core OpenAPI spec
+npm run build:gcp           # Generate GCP OpenAPI spec
+npm run build:all           # Generate all variants with Swagger
+```
+
+**Validation workflow:**
+```bash
+npm install                 # Install dependencies
+npm run build:core         # Build and verify compilation
+npm run build:gcp          # Build GCP variant
+ls -l schemas/*/openapi.yaml  # Confirm outputs exist
+```
+
+## Key Concepts
+
+### Provider Variants via Aliases
+
+The repo uses a single `main.tsp` but generates different specs per provider:
+
+```typescript
+// aliases-core.tsp
+alias ClusterSpec = Record<unknown>;  // Generic
+
+// aliases-gcp.tsp
+alias ClusterSpec = GCPClusterSpec;   // Provider-specific
+```
+
+The `aliases.tsp` symlink determines which provider types are active. The `build-schema.sh` script automatically re-links this during builds.
+
+**When adding new models:**
+- Shared models → `models/`
+- Provider-specific → `models-{provider}/`
+- Always update alias files if you introduce provider-specific types
+
+### Public vs Internal APIs
+
+Status endpoints are split:
+- `services/statuses.tsp` - GET operations (external clients)
+- `services/statuses-internal.tsp` - POST operations (internal adapters only)
+
+The split allows generating different API contracts per audience. Only `statuses.tsp` is imported by default.
+
+## Code Style
+
+### TypeSpec Conventions
+
+**Imports first, namespace second:**
+```typescript
+import "@typespec/http";
+import "../models/common/model.tsp";
+
+namespace HyperFleet;
+```
+
+**Use decorators for HTTP semantics:**
+```typescript
+@route("/clusters")
+interface Clusters {
+  @get list(): Cluster[] | Error;
+  @post create(@body cluster: ClusterInput): Cluster | Error;
+}
+```
+
+**Model naming:**
+- Resources: `Cluster`, `NodePool` (singular)
+- Inputs: `ClusterInput`, `NodePoolInput`
+- Provider-specific: `GCPClusterSpec`, `AWSClusterSpec`
+
+### File Organization
+
+```
+models/{resource}/
+  ├── model.tsp          # Shared model definitions
+  └── interfaces.tsp     # Optional: shared interfaces
+
+models-{provider}/{resource}/
+  └── model.tsp          # Provider-specific models
+
+services/
+  └── {resource}.tsp     # Service endpoints
+```
+
+## Boundaries
+
+**DO NOT:**
+- Modify generated files in `schemas/` or `tsp-output/` directly
+- Add dependencies without checking TypeSpec version compatibility
+- Auto-generate documentation - it degrades agent performance per research
+- Use `--swagger` flag unless you need OpenAPI 2.0 for legacy tools
+- Commit `node_modules/` or build artifacts
+
+**DO:**
+- Run `npm run build:all` before committing schema changes
+- Test both provider variants when modifying shared models
+- Keep TypeSpec files focused (one resource per service file)
+- Use semantic versioning for releases (see RELEASING.md)
+
+## Common Tasks
+
+### Add a new endpoint to existing service
+
+```typescript
+// services/clusters.tsp
+namespace HyperFleet;
+
+@route("/clusters")
+interface Clusters {
+  // ... existing endpoints ...
+
+  @get
+  @route("/{id}/health")
+  getHealth(@path id: string): HealthStatus | Error;
+}
+```
+
+### Add a new resource
+
+1. Create model:
+```typescript
+// models/health/model.tsp
+import "@typespec/http";
+
+model HealthStatus {
+  id: string;
+  state: "healthy" | "degraded" | "critical";
+  lastChecked: utcDateTime;
+}
+```
+
+2. Create service:
+```typescript
+// services/health.tsp
+import "@typespec/http";
+import "../models/health/model.tsp";
+import "../models/common/model.tsp";
+
+namespace HyperFleet;
+
+@route("/health")
+interface Health {
+  @get check(): HealthStatus | Error;
+}
+```
+
+3. Import in `main.tsp`:
+```typescript
+import "./services/health.tsp";
+```
+
+4. Build: `npm run build:core`
+
+### Add provider-specific fields
+
+```typescript
+// models-gcp/cluster/model.tsp
+model GCPClusterSpec {
+  projectId: string;
+  region: string;
+  network?: GCPNetwork;
+}
+
+model GCPNetwork {
+  vpcId: string;
+  subnetId: string;
+}
+```
+
+Update alias:
+```typescript
+// aliases-gcp.tsp
+import "./models-gcp/cluster/model.tsp";
+alias ClusterSpec = GCPClusterSpec;
+```
+
+Build: `npm run build:gcp`
+
+## Validation Checklist
+
+Before submitting changes:
+
+- [ ] Dependencies installed: `npm install`
+- [ ] Core variant builds: `npm run build:core`
+- [ ] GCP variant builds: `npm run build:gcp`
+- [ ] Schema files generated: `ls schemas/*/openapi.yaml`
+- [ ] No TypeSpec compilation errors (check output)
+- [ ] Changes committed including schema updates
+- [ ] PR description references related issue
+
+## Build System Details
+
+**The build-schema.sh script:**
+1. Validates provider parameter (core, gcp, etc.)
+2. Re-links `aliases.tsp` → `aliases-{provider}.tsp`
+3. Runs `tsp compile main.tsp`
+4. Copies output to `schemas/{provider}/openapi.yaml`
+5. (Optional) Converts to OpenAPI 2.0 with `--swagger` flag
+
+**Output locations:**
+- TypeSpec: `tsp-output/schema/openapi.yaml` (temporary)
+- Final: `schemas/{provider}/openapi.yaml` (committed)
+
+## VS Code Extension Notes
+
+The TypeSpec extension may show false errors:
+- Non-active provider models appear undefined (expected)
+- Duplicate type warnings from multiple alias files (expected)
+
+Both the CLI and "Emit from TypeSpec" command work correctly despite warnings.
+
+## Dependencies
+
+All TypeSpec libraries use version `^1.6.0` for consistency:
+- `@typespec/compiler` - Core compiler
+- `@typespec/http` - HTTP semantics
+- `@typespec/openapi` - OpenAPI decorators
+- `@typespec/openapi3` - OpenAPI 3.0 emitter
+- `@typespec/rest` - REST conventions
+- `@typespec/versioning` - API versioning support
+
+**Adding new TypeSpec libraries:**
+```bash
+npm install --save-dev @typespec/library-name@^1.6.0
+```
+
+Match the version range to existing dependencies.
+
+## Release Process
+
+Quick reference (see RELEASING.md for details):
+
+```bash
+# 1. Build schemas
+npm run build:all
+
+# 2. Commit and tag
+git add schemas/
+git commit -m "chore: update schemas for vX.Y.Z"
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+
+# 3. Push tag
+git push upstream vX.Y.Z
+
+# 4. Create GitHub Release with schema assets
+gh release create vX.Y.Z \
+  --repo openshift-hyperfleet/hyperfleet-api-spec \
+  --title "vX.Y.Z" \
+  schemas/core/openapi.yaml#core-openapi.yaml \
+  schemas/gcp/openapi.yaml#gcp-openapi.yaml
+```
+
+## Architecture Context
+
+This repository is part of the HyperFleet project. For broader context:
+- Architecture repo: https://github.com/openshift-hyperfleet/architecture
+- Main API implementation: https://github.com/openshift-hyperfleet/hyperfleet-api
+
+The API implementation consumes the generated OpenAPI specs for validation and documentation.