Replace stale scaffold with versioned developer docs IA

.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

README.md

@@ -1,37 +1,47 @@
 # 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
 
 - Write both Persian and English for architecture and operational material.
 - 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.

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.

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.