docs: build out CoreLink v1 developer documentation

.github/workflows/documentation.yml

@@ -20,8 +20,12 @@ jobs:
           test -s README.md
           test -s docs/README.md
           test -s docs/v1/README.md
+          test -s docs/v1/quickstart.md
           grep -Fq '1.0.0-draft' docs/v1/README.md
           grep -Fq 'corelink_device_id' docs/v1/README.md
+          grep -Fq 'Authorization: Bearer $CORELINK_ACCESS_TOKEN' docs/v1/quickstart.md
+          grep -Fq 'Idempotency-Key: $CORELINK_IDEMPOTENCY_KEY' docs/v1/quickstart.md
+          grep -Fq '/api/v1/tenants/$CORELINK_TENANT_ID/devices' docs/v1/quickstart.md
           if grep -Fq 'API contract repository also has unpopulated' README.md; then
             echo "stale API-contract status returned" >&2
             exit 1

README.md

@@ -1,47 +1,49 @@
 # CoreLink Developer Documentation
 
-Developer-facing documentation for using CoreLink safely and consistently.
-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.
+Developer-facing documentation for using CoreLink safely and consistently. Versioned contracts in [`api-contracts`](https://github.com/CoreLinkPlatform/api-contracts) define normative public API/event boundaries; this repository explains how developers use them without creating a second schema source of truth.
 
-## Documentation versions
+## Start here
 
-- [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.
+- [Documentation versions](docs/README.md)
+- [CoreLink v1 documentation](docs/v1/README.md)
+- [30-minute v1 quickstart](docs/v1/quickstart.md)
+- [Architecture](docs/v1/concepts/architecture.md)
+- [Authentication and tenant context](docs/v1/concepts/tenancy-authentication.md)
+- [Compatibility](docs/v1/reference/compatibility.md)
+- [Maturity vocabulary](docs/v1/reference/maturity.md)
 
-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.
+CoreLink v1 is not Stable. The public Device/Command contract is `1.0.0-draft`; TypeScript/Python clients are prerelease Alpha; Console is Alpha; Java SDK, CLI, MCP server and mock server remain Scaffold/Planned.
 
-## Information architecture
+## Documentation model
 
-Each documentation version uses the same navigation:
+Each version can contain:
 
-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.
+1. **Start here / Concepts** — architecture, authentication, tenancy and canonical identifiers.
+2. **Guides** — task-oriented workflows, with maturity visible on every contract-gated surface.
+3. **Reference** — links to normative versioned contracts and compatibility policy.
+4. **SDKs and tools** — usage/status that reflects the owning repository's real maturity.
+5. **Operations** — errors, retries, idempotency, troubleshooting, migration and support boundaries.
 
-A section may be listed before its content exists, but it must be marked
-**Planned** rather than presented as delivered documentation.
+Content may describe planned/draft architecture before a supported release only when that maturity is explicit and no invented endpoint/package/command is presented as available.
 
 ## 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/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.
+- Use `corelink_device_id` and other canonical CoreLink identifiers on public surfaces.
+- Document tenant scoping, authorization, failures and idempotency for state-changing operations.
+- Never promote raw provider IDs, credentials or payload models into public CoreLink contracts.
+- Link versioned contract definitions instead of copying schemas into prose.
+- Use **Scaffold, Experimental, Alpha, Beta, Stable, Deprecated, Planned** consistently.
+- Examples must identify their contract/runtime/SDK maturity.
+- Browser guidance should prefer server-side session/BFF token handling where practical; do not normalize access tokens in browser storage.
+- Security-sensitive reports follow the organization private reporting policy rather than public documentation issues.
+
+## Bilingual documentation
+
+English is the normative developer-doc language for the current v1 tree. Persian translations may be published for architecture/operations and user-facing onboarding when they can be kept version-aligned and pass the bilingual documentation checks defined by DOCS-05. A translation must link to the same contract revision and may not carry a different maturity claim.
+
+## Ownership
+
+- Product direction and milestone acceptance: [`product-planning`](https://github.com/CoreLinkPlatform/product-planning)
+- Organization maturity/security/support/release policy: [`.github`](https://github.com/CoreLinkPlatform/.github)
+- Normative API/event schemas: [`api-contracts`](https://github.com/CoreLinkPlatform/api-contracts)
+- Implementation/deployment details: the owning repository (`platform`, `Console`, SDK/tool repositories, website)

docs/README.md

@@ -2,24 +2,21 @@
 
 | 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) |
+| v1 | `corelink-public-v1.yaml` `1.0.0-draft` | Alpha docs; Device/Command quickstart plus maturity-aware concepts/guides | [v1](v1/README.md) · [30-minute quickstart](v1/quickstart.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.
+Documentation is versioned by the public CoreLink contract boundary, not by website deployment or repository release cadence. A documentation version remains Alpha while its referenced public contract/runtime/tool surfaces remain 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.
+Breaking public-contract changes require a new major documentation tree and migration guidance. Compatible additions may extend the same tree only when contract compatibility policy permits them.
 
 Every version landing page records:
 
-- exact contract version/tag or immutable commit;
+- exact contract version/tag or immutable revision;
 - supported resource surface;
-- runtime/SDK maturity;
-- known omissions;
-- links to compatibility and changelog evidence.
+- runtime/SDK/tool maturity;
+- known omissions and contract-gated sections;
+- compatibility and maturity references;
+- operational/error/troubleshooting guidance appropriate to that boundary.
 
-Do not silently rewrite older version guidance to match a newer contract.
+Do not silently rewrite older version guidance to match a newer incompatible contract.

docs/v1/README.md

@@ -1,62 +1,61 @@
 # CoreLink v1 developer documentation
 
-**Maturity: Alpha documentation / draft contract**
+**Maturity: Alpha documentation / `1.0.0-draft` public 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.
+This tree targets the current public contract baseline. The reviewed public slice covers **Device** and **Command** resources plus a canonical event envelope. Broader telemetry/location, partner/webhook and developer-tool surfaces remain maturity-gated and are labeled explicitly below.
 
 ## 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) |
+1. [30-minute quickstart](quickstart.md) — bearer authentication, tenant scope, Device read/create and idempotent Command submission.
+2. [Architecture](concepts/architecture.md) — CoreLink-owned public boundary and provider independence.
+3. [Authentication and tenant context](concepts/tenancy-authentication.md) — auth, tenant scope and safe credential handling.
+
+## Guides
+
+- [Devices and commands](guides/devices-and-commands.md) — **Alpha / current draft public slice**.
+- [Telemetry, location and events](guides/telemetry-location-events.md) — **work in progress; API/runtime gates remain open**.
+- [Webhooks and partner operations](guides/webhooks-and-partner-operations.md) — **Planned/Alpha expansion; exact public endpoints/signatures remain contract-gated**.
 
-## Navigation contract
+## SDKs
 
-### 1. Start here
-Concepts, authentication, tenant isolation, canonical identifiers and first
-verified API call. Content beyond the linked contract is **Planned**.
+- [TypeScript SDK](sdks/typescript.md) — **Prerelease Alpha**.
+- [Python SDK](sdks/python.md) — **Prerelease Alpha**.
+- Java SDK is **Scaffold/Planned**; see [developer tool maturity](tools/developer-tools.md).
 
-### 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.
+## Developer tools
 
-### 3. How-to
-Partner/operator procedures will be added only with reproducible prerequisites,
-failure handling and test evidence.
+[Java SDK, CLI, mock server and MCP status](tools/developer-tools.md) documents current Scaffold/Planned boundaries and the backlog gates required before installation/support instructions are valid.
 
-### 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.
+## Operations
 
-### 5. SDKs and tools
-TypeScript/Python are generated prerelease clients. Other tool repositories are
-not installable supported releases today.
+- [Errors, retries and idempotency](operations/errors-retries-idempotency.md)
+- [Troubleshooting](operations/troubleshooting.md)
 
-### 6. Examples
-Examples must pin their contract baseline and tested runtime/SDK version.
+## Reference
 
-### 7. Operations
-Release/migration/troubleshooting material must name its owner, rollback or
-recovery path, and evidence when applicable.
+- [Compatibility](reference/compatibility.md)
+- [Maturity vocabulary](reference/maturity.md)
+- Normative contract compatibility/terminology: [`api-contracts/docs`](https://github.com/CoreLinkPlatform/api-contracts/tree/main/docs)
+
+## Current surface matrix
+
+| Surface | Current maturity | Authoritative source |
+| --- | --- | --- |
+| Public Device + Command API | Alpha / `1.0.0-draft` | [Public OpenAPI](https://github.com/CoreLinkPlatform/api-contracts/blob/main/openapi/corelink-public-v1.yaml) |
+| Canonical event envelope | Alpha / draft | [AsyncAPI](https://github.com/CoreLinkPlatform/api-contracts/blob/main/asyncapi/corelink-events-v1.yaml) |
+| TypeScript SDK | Prerelease Alpha | [sdk-typescript](https://github.com/CoreLinkPlatform/sdk-typescript) |
+| Python SDK | Prerelease Alpha | [sdk-python](https://github.com/CoreLinkPlatform/sdk-python) |
+| CoreLink Console | Alpha | [Console](https://github.com/CoreLinkPlatform/Console) |
+| 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) |
 
-## Contract rules carried into docs
+## Documentation contract
 
 - 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.
+- Provider/connector identifiers are implementation details, not public resource identities.
+- State-changing examples document tenant scope, authorization, idempotency and expected failures.
+- Normative schemas are linked from `api-contracts`, not forked into prose.
+- Draft/scaffold content is never described as Stable.
+- Implementation, deployment and Product Acceptance are distinct evidence states.

docs/v1/concepts/architecture.md

@@ -0,0 +1,47 @@
+# CoreLink architecture for developers
+
+**Maturity:** Alpha documentation
+
+CoreLink exposes a provider-neutral product boundary in front of device/connectivity engines, identity infrastructure, data stores, and integration providers. Application code should depend on CoreLink contracts rather than provider-specific APIs or identifiers.
+
+## Product boundary
+
+```text
+Application / Console / SDK / CLI / MCP
+                 |
+                 v
+        CoreLink public contracts
+                 |
+      +----------+-----------+
+      |                      |
+  Core runtime          Event/Webhook boundary
+      |
+  Integration adapters
+      |
+  Device/connectivity providers
+```
+
+The public boundary is intentionally narrower than the private runtime implementation. A capability being implemented internally does not make it a supported public API.
+
+## Canonical identity
+
+Public resources use CoreLink-owned identifiers. For the current Device contract the public identifier is `corelink_device_id`. Provider IDs may be stored internally for adapter reconciliation but are not public resource identities.
+
+## Tenant boundary
+
+Public operations are tenant-scoped. Tenant identity in a path is not an authorization bypass: the authenticated actor must also be authorized for that tenant and operation. Applications must treat `401` and `403` as authorization failures, not as signals to try another tenant identifier.
+
+## Contract-first consumers
+
+- `api-contracts` is the normative source for OpenAPI, AsyncAPI and schemas.
+- `developer-docs` explains how to use those contracts.
+- generated SDKs must identify immutable contract provenance.
+- Console, CLI, mock and MCP consumers must not create private alternative public schemas.
+
+## Provider independence
+
+Provider-specific behavior belongs behind Integration Adapter boundaries. Public docs, SDK types, error codes, examples, MCP tools and Console domain models should use CoreLink terminology unless a provider detail is explicitly part of an operator-only implementation document.
+
+## Evidence before claims
+
+CoreLink distinguishes implementation, deployment and Product Acceptance. A merged PR or green CI job is implementation evidence; supported maturity additionally requires the relevant contract, security, runtime/conformance, documentation and release gates.

docs/v1/concepts/tenancy-authentication.md

@@ -0,0 +1,37 @@
+# Authentication and tenant context
+
+**Maturity:** Alpha documentation / `1.0.0-draft` public contract
+
+The current public contract authenticates API requests with a Bearer JWT. It does not define a public self-service token-issuance endpoint, so client applications must obtain credentials through the approved environment/onboarding path rather than inventing an OAuth flow.
+
+## Request boundary
+
+For authenticated API operations:
+
+```http
+Authorization: Bearer <access-token>
+```
+
+Tenant-scoped resource paths also contain a tenant identifier. The path value selects a resource scope; authorization still comes from the authenticated actor, claims/scopes, membership and server-side policy.
+
+## Rules for clients
+
+- Never persist access tokens in source control, screenshots, issue bodies or application logs.
+- Browser applications should prefer a server-side session/BFF design so CoreLink access tokens do not live in browser storage.
+- Do not retry `401` or `403` with guessed tenant IDs or alternative credentials.
+- Use least-privilege credentials for machine integrations.
+- Treat credential rotation/revocation as normal lifecycle behavior.
+
+## Failure semantics
+
+- `401`: authentication is missing, invalid or no longer accepted.
+- `403`: authentication succeeded but the actor is not allowed to perform the requested tenant-scoped operation.
+- `404`: do not assume a resource exists in another tenant; tenant-safe APIs may intentionally avoid leaking existence.
+
+## Service and partner credentials
+
+Partner/service credential lifecycle is broader than the currently reviewed public Device/Command slice. Documentation may describe the security principles now, but installation or support claims for additional credential APIs must wait for their version-identifiable contract/runtime acceptance.
+
+## Console boundary
+
+The CoreLink Console uses an OIDC/Auth.js session and a server-side BFF so browser code does not store CoreLink bearer tokens. That architecture is an implementation reference, not a requirement that every non-browser consumer use Auth.js.