diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..823ea2e --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,28 @@ +name: Documentation CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Validate versioned information architecture + shell: bash + run: | + set -euo pipefail + test -s README.md + test -s docs/README.md + test -s docs/v1/README.md + grep -Fq '1.0.0-draft' docs/v1/README.md + grep -Fq 'corelink_device_id' docs/v1/README.md + if grep -Fq 'API contract repository also has unpopulated' README.md; then + echo "stale API-contract status returned" >&2 + exit 1 + fi diff --git a/README.md b/README.md index 1d7845e..657237a 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,34 @@ # CoreLink Developer Documentation Developer-facing documentation for using CoreLink safely and consistently. -This repository is intentionally separate from the runtime: it explains the -stable public surface without exposing provider-specific implementation details. +The runtime remains the source of truth for implemented capability; versioned +contracts in [`api-contracts`](https://github.com/CoreLinkPlatform/api-contracts) +define the public API/event boundary. -## Current status +## Documentation versions -This repository is a documentation scaffold. Guides, tutorials and examples -have not been added yet; the API contract repository also has unpopulated -OpenAPI and AsyncAPI specifications. Do not treat this repository as a complete -developer portal today. +- [Documentation index](docs/README.md) +- [v1 documentation](docs/v1/README.md) — targets the current `1.0.0-draft` + public Device and Command contract and canonical event envelope. -## Planned information architecture +CoreLink v1 is not a Stable release. TypeScript and Python clients are +prerelease; Java SDK, CLI, MCP server and mock server remain Scaffold/Planned. +Pages must keep those maturity boundaries visible. -- **Start here:** concepts, authentication and tenant-scoping overview. -- **Guides:** device registration, provisioning, telemetry, commands, digital - twin, events, webhooks and integrations. -- **How-to guides:** common partner and operator workflows. -- **Reference:** links to versioned API and event contracts in `api-contracts`. -- **SDK and tools:** Python, TypeScript and Java SDKs, CLI, mock server and MCP - server. -- **Examples:** runnable, pinned examples that use only documented public APIs. +## Information architecture + +Each documentation version uses the same navigation: + +1. Start here — concepts, authentication and tenant scoping. +2. Guides — task-oriented Device/Command/Event workflows backed by current contracts. +3. How-to — narrow partner/operator procedures with prerequisites and evidence. +4. Reference — immutable contract/schema links; definitions are not copied. +5. SDKs and tools — only clients/tools whose repository maturity is stated. +6. Examples — runnable examples pinned to contract and platform versions. +7. Operations — release, migration, troubleshooting and support boundaries. + +A section may be listed before its content exists, but it must be marked +**Planned** rather than presented as delivered documentation. ## Documentation rules @@ -28,10 +36,12 @@ developer portal today. - Use `corelink_device_id` as the public device identifier. - Document tenant scoping, required roles/scopes, failure responses and idempotency wherever an operation changes state. -- Never document raw upstream Traccar, OpenRemote or Keycloak structures as - public CoreLink contracts. -- Mark planned capabilities clearly; examples must state their contract and - platform version. - -The platform's current architecture and delivery order are maintained in the -[`platform` repository](https://github.com/CoreLinkPlatform/platform). +- Never document raw upstream/provider structures as public CoreLink contracts. +- Link versioned contract definitions instead of maintaining a second schema copy. +- Mark maturity using Scaffold, Experimental, Alpha, Beta, Stable, Deprecated or Planned. +- Examples must state their contract and platform version and must not imply a + production-supported SDK before its release gate passes. + +Product direction and milestone acceptance live in +[`product-planning`](https://github.com/CoreLinkPlatform/product-planning); +implementation evidence stays in each owning repository. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..4752c0b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,25 @@ +# Documentation versions + +| Docs version | Contract target | Status | Entry point | +| --- | --- | --- | --- | +| v1 | `corelink-public-v1.yaml` `1.0.0-draft` | Alpha documentation for a draft public boundary | [v1](v1/README.md) | + +## Versioning policy + +Documentation is versioned by the public CoreLink contract boundary, not by the +website deployment. A version remains **Alpha** while its referenced public +contract is draft/prerelease. + +Breaking public-contract changes require a new major documentation tree. Minor +or patch additions may update the same tree only when the contract compatibility +policy permits them. + +Every version landing page records: + +- exact contract version/tag or immutable commit; +- supported resource surface; +- runtime/SDK maturity; +- known omissions; +- links to compatibility and changelog evidence. + +Do not silently rewrite older version guidance to match a newer contract. diff --git a/docs/v1/README.md b/docs/v1/README.md new file mode 100644 index 0000000..7da70f9 --- /dev/null +++ b/docs/v1/README.md @@ -0,0 +1,62 @@ +# CoreLink v1 developer documentation + +**Maturity: Alpha documentation / draft contract** + +This tree targets the API Contracts repository's immutable +`v1.0.0-draft` baseline. The reviewed public slice currently covers **Device** +and **Command** resources plus a canonical event envelope. Tenant provisioning, +integration callbacks and privileged administration are outside the public v1 +boundary until separately reviewed. + +## Start here + +| Topic | Status | Source | +| --- | --- | --- | +| Public Device + Command API | Alpha / draft | [Public OpenAPI](https://github.com/CoreLinkPlatform/api-contracts/blob/main/openapi/corelink-public-v1.yaml) | +| Event envelope | Alpha / draft | [AsyncAPI](https://github.com/CoreLinkPlatform/api-contracts/blob/main/asyncapi/corelink-events-v1.yaml) | +| Authentication and tenant scope | Planned documentation | Contract security definitions + runtime evidence | +| TypeScript SDK | Prerelease Alpha | [sdk-typescript](https://github.com/CoreLinkPlatform/sdk-typescript) | +| Python SDK | Prerelease Alpha | [sdk-python](https://github.com/CoreLinkPlatform/sdk-python) | +| Java SDK | Scaffold / Planned | [sdk-java](https://github.com/CoreLinkPlatform/sdk-java) | +| CLI | Scaffold / Planned | [cli](https://github.com/CoreLinkPlatform/cli) | +| MCP server | Scaffold / Planned | [mcp-server](https://github.com/CoreLinkPlatform/mcp-server) | +| Mock server | Scaffold / Planned | [mock-server](https://github.com/CoreLinkPlatform/mock-server) | + +## Navigation contract + +### 1. Start here +Concepts, authentication, tenant isolation, canonical identifiers and first +verified API call. Content beyond the linked contract is **Planned**. + +### 2. Guides +Device registration/lifecycle and commands are first because they are in the +current public draft. Telemetry, digital twin, webhooks and integrations remain +**Planned** until their public contracts and runtime parity are evidenced. + +### 3. How-to +Partner/operator procedures will be added only with reproducible prerequisites, +failure handling and test evidence. + +### 4. Reference +Use the versioned files in +[`api-contracts`](https://github.com/CoreLinkPlatform/api-contracts). This +repository explains usage; it does not fork schema definitions. + +### 5. SDKs and tools +TypeScript/Python are generated prerelease clients. Other tool repositories are +not installable supported releases today. + +### 6. Examples +Examples must pin their contract baseline and tested runtime/SDK version. + +### 7. Operations +Release/migration/troubleshooting material must name its owner, rollback or +recovery path, and evidence when applicable. + +## Contract rules carried into docs + +- Public device identity is `corelink_device_id`. +- Provider/connector identifiers are implementation details. +- Every state-changing example must describe tenant scope, authorization, + idempotency and expected problem responses. +- A draft or scaffold is never described as Stable/supported.