diff --git a/README.md b/README.md
index cfe441f..eca032a 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +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.
-- [30-minute v1 quickstart](docs/v1/quickstart.md) — bearer auth, tenant scope,
-  Device creation/read and idempotent Command submission using the public contract.
+- [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)
diff --git a/docs/README.md b/docs/README.md
index 31e4903..85eaa7f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,24 +2,21 @@
 
 | Docs version | Contract target | Status | Entry point |
 | --- | --- | --- | --- |
-| v1 | `corelink-public-v1.yaml` `1.0.0-draft` | Alpha docs + contract-backed quickstart | [v1](v1/README.md) · [30-minute quickstart](v1/quickstart.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.
\ No newline at end of file
diff --git a/docs/v1/README.md b/docs/v1/README.md
index a454644..1e30df8 100644
--- a/docs/v1/README.md
+++ b/docs/v1/README.md
@@ -1,64 +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 | Alpha quickstart | [30-minute quickstart](quickstart.md) + contract security definitions |
-| 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
-Begin with the [30-minute v1 quickstart](quickstart.md) for bearer authentication,
-tenant scoping, Device and Command calls, idempotency, failure handling and a
-repeatable acceptance record. Content beyond the linked Device/Command 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.
\ No newline at end of file
diff --git a/docs/v1/concepts/architecture.md b/docs/v1/concepts/architecture.md
new file mode 100644
index 0000000..693153f
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/v1/concepts/tenancy-authentication.md b/docs/v1/concepts/tenancy-authentication.md
new file mode 100644
index 0000000..c8ed2dc
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/v1/guides/devices-and-commands.md b/docs/v1/guides/devices-and-commands.md
new file mode 100644
index 0000000..d3a6992
--- /dev/null
+++ b/docs/v1/guides/devices-and-commands.md
@@ -0,0 +1,38 @@
+# Devices and commands
+
+**Maturity:** Alpha documentation / `1.0.0-draft`
+
+Device and Command are the currently reviewed public v1 resource slice. Use the [30-minute quickstart](../quickstart.md) for complete curl examples.
+
+## Device identity
+
+Use `corelink_device_id` from CoreLink responses as the public device identity. Do not persist a provider's device ID as the application's CoreLink resource key.
+
+A device model/capability boundary determines which operations are valid for a device. Applications should not infer supported commands from provider type or UI availability.
+
+## Listing and reading devices
+
+Device reads are tenant-scoped and paginated where defined by the OpenAPI contract. Preserve explicit tenant context and use the contract's pagination fields rather than assuming an unbounded collection.
+
+## Creating devices
+
+Device creation requires an allowed `device_model_id` and valid tenant authorization. Treat validation/conflict responses as state that needs reconciliation; do not generate provider records directly to bypass CoreLink lifecycle checks.
+
+## Commands
+
+Command submission is asynchronous. HTTP `201` means CoreLink accepted the command record; it does **not** prove execution on the physical device.
+
+Command create requires `Idempotency-Key`. When retrying the same logical submission, reuse the same idempotency key. Use a new key for a new logical command.
+
+Possible command states in the current contract include queued/dispatching/sent/acknowledged/succeeded/failed/timed-out/cancelled states. Consumers should display and reconcile the state returned by CoreLink rather than synthesizing a success state from the initial POST.
+
+## Error and retry behavior
+
+- Do not automatically retry `400`, `401`, `403` or `404`.
+- Reconcile `409` rather than blindly resubmitting.
+- Retrying a command POST requires the original idempotency key.
+- Preserve `correlation_id` from problem responses for diagnosis.
+
+## Provider boundary
+
+Applications must not call provider command APIs directly as a fallback for unsupported CoreLink operations. Missing capability belongs in the CoreLink contract/runtime backlog, not in an application-specific bypass.
\ No newline at end of file
diff --git a/docs/v1/guides/telemetry-location-events.md b/docs/v1/guides/telemetry-location-events.md
new file mode 100644
index 0000000..80bb99f
--- /dev/null
+++ b/docs/v1/guides/telemetry-location-events.md
@@ -0,0 +1,33 @@
+# Telemetry, location, and events
+
+**Maturity:** contract/runtime work in progress; do not treat this page as a Stable public API reference.
+
+CoreLink's product direction includes canonical telemetry observations, positions, latest state/history, events, retry/replay and delivery semantics. The private runtime has substantial implementation foundations, but broader public v1 contract slices are still gated by API-02/API-04 and runtime acceptance work.
+
+## Canonical model principles
+
+- normalize provider payloads into CoreLink-owned observation/position/event models;
+- preserve canonical CoreLink device/tenant identity;
+- define duplicate and out-of-order behavior deterministically;
+- keep provider payloads out of public consumer contracts unless explicitly modeled;
+- retain timestamps/source metadata needed to distinguish observation time from ingestion/processing time;
+- apply tenant-safe retention, replay and history behavior.
+
+## Latest state versus history
+
+A latest-state projection is not a substitute for history. Clients should use the contract-defined resource suited to the task once the corresponding public contract is accepted. They should not reconstruct authoritative history from UI snapshots or provider-specific data.
+
+## Events
+
+The current contracts include a canonical event envelope, but supported event catalogs, delivery/replay behavior and webhook semantics require their own version-identifiable contract/runtime evidence.
+
+## Implementation status rule
+
+Examples for telemetry/location/events may be documented as draft when they identify the exact draft contract/revision. They must not be advertised as supported Beta/Stable journeys until the corresponding API-02/API-04 and runtime/conformance gates are accepted.
+
+## Related work
+
+- `api-contracts` API-02: Assets/bindings/telemetry/location/alerts public v1 expansion.
+- `api-contracts` API-04: canonical AsyncAPI event/webhook schemas.
+- `platform` PLAT-04/05: telemetry/history and event ordering/replay evidence.
+- `developer-docs` DOCS-03: publish runnable supported guides when those inputs are version-identifiable.
\ No newline at end of file
diff --git a/docs/v1/guides/webhooks-and-partner-operations.md b/docs/v1/guides/webhooks-and-partner-operations.md
new file mode 100644
index 0000000..c21a00d
--- /dev/null
+++ b/docs/v1/guides/webhooks-and-partner-operations.md
@@ -0,0 +1,37 @@
+# Webhooks and partner operations
+
+**Maturity:** Planned/Alpha contract expansion; supported claims require API-03/API-04 and runtime acceptance.
+
+CoreLink's partner boundary is intended to provide least-privilege machine credentials, webhook subscriptions/delivery, usage/entitlement visibility and supported operations for Console/partner integrations. These surfaces are broader than the current Device/Command public draft.
+
+## Security principles
+
+- credentials are tenant-scoped and least privilege;
+- secrets are displayed/stored only where lifecycle semantics explicitly allow it;
+- rotation and revocation must be auditable;
+- webhook payloads use canonical CoreLink identifiers;
+- signatures, timestamp/replay policy and retry behavior must be versioned;
+- cross-tenant and insufficient-scope operations fail closed.
+
+## Webhook consumer requirements
+
+When the supported webhook contract is published, consumers should:
+
+1. verify the documented signature before processing;
+2. enforce replay/timestamp rules;
+3. make handlers idempotent;
+4. return only the documented success response after durable acceptance;
+5. retain CoreLink correlation/delivery identifiers for diagnosis;
+6. avoid logging secrets or full sensitive payloads unnecessarily.
+
+## Retry and replay
+
+Delivery retry/replay semantics are contract behavior, not an invitation for consumers to infer schedules from implementation. Do not build production assumptions from an internal provider's retry policy.
+
+## Usage and entitlements
+
+Usage, plan and entitlement surfaces may be visible in the CoreLink Console as implementation evolves. Public developer integrations must use versioned CoreLink contracts rather than reading billing/runtime tables or copying Console-internal payloads.
+
+## Promotion rule
+
+This guide can describe the intended safe integration boundary while the contract is draft. Concrete endpoints, signature algorithms, fields and supported retry schedules belong here only after their normative API-03/API-04 source is published and linked.
\ No newline at end of file
diff --git a/docs/v1/operations/errors-retries-idempotency.md b/docs/v1/operations/errors-retries-idempotency.md
new file mode 100644
index 0000000..f3a5bd2
--- /dev/null
+++ b/docs/v1/operations/errors-retries-idempotency.md
@@ -0,0 +1,33 @@
+# Errors, retries, and idempotency
+
+**Maturity:** Alpha documentation; exact responses remain defined by the versioned contract.
+
+## Problem responses
+
+Public API errors use the contract-defined problem response shape. Preserve `correlation_id` or equivalent diagnostic identifiers when escalating failures. Do not include bearer tokens or secrets in tickets/log extracts.
+
+## Status-code handling
+
+General client behavior for the current public slice:
+
+- `400` — request is invalid; fix the request rather than retrying blindly.
+- `401` — authentication is missing/invalid; refresh or replace credentials through the approved auth flow.
+- `403` — actor is not authorized for the tenant/operation; do not try different tenant IDs as a workaround.
+- `404` — resource is not available in the authorized scope; do not infer cross-tenant existence.
+- `409` — state/idempotency conflict; reconcile before another write.
+- `429` — only follow a retry policy when the active contract/environment documents it.
+- `5xx` — may be transient, but retry only operations that are safe/idempotent under the documented contract.
+
+## Command idempotency
+
+Command creation requires `Idempotency-Key`. Reuse the same key when retrying the same logical command; use a new key for a new logical command.
+
+A timeout does not prove that a write failed. Before creating a new logical write, use the contract's reconciliation/read path when available.
+
+## Backoff
+
+Clients should use bounded retry/backoff, preserve request/correlation context, and stop on deterministic authorization/validation failures. Do not build retry schedules from provider behavior unless CoreLink exposes that schedule as part of its contract.
+
+## Observability
+
+Log safe identifiers needed for support: CoreLink tenant/resource IDs, operation name, HTTP status, request/correlation identifier, client version and contract/runtime revision. Avoid raw credentials, unnecessary payload bodies and sensitive metadata.
\ No newline at end of file
diff --git a/docs/v1/operations/troubleshooting.md b/docs/v1/operations/troubleshooting.md
new file mode 100644
index 0000000..8cad42b
--- /dev/null
+++ b/docs/v1/operations/troubleshooting.md
@@ -0,0 +1,40 @@
+# Developer troubleshooting
+
+Use this checklist before opening an issue. It separates credential/tenant problems, contract mismatches and environment failures.
+
+## 1. Record the baseline
+
+Capture safely:
+
+- repository/client version or commit;
+- API contract version/revision;
+- target environment type (local/sandbox/hosted alpha, not secrets/host internals);
+- CoreLink tenant/resource IDs needed to reproduce;
+- HTTP status and `correlation_id`;
+- timestamp/time zone.
+
+## 2. Check environment health
+
+If the environment exposes the documented readiness endpoint, verify it before debugging application code. A dependency/readiness failure should be resolved as an environment problem; do not assume an API write succeeded or failed solely from readiness state.
+
+## 3. Check authentication and tenant scope
+
+- `401`: verify token validity/expiry and approved credential source.
+- `403`: verify membership/scope/role; do not alter tenant IDs to probe access.
+- repeated `404`: verify the canonical CoreLink resource ID and authorized tenant.
+
+## 4. Check contract/client compatibility
+
+Confirm that examples, SDK generated code and runtime target the same version-identifiable contract boundary. A generated SDK can be newer/older than an environment; generation alone is not parity evidence.
+
+## 5. Check write reconciliation
+
+For commands or other idempotent writes, preserve the original idempotency key during retries. After a network timeout, read/reconcile state before generating a second logical operation.
+
+## 6. Console-specific issues
+
+Determine whether the UI is running in demo or live mode. Demo data is not live acceptance evidence. For live asset/geofence collection behavior, check the Console's `API-COMPATIBILITY.md` because canonical read-model gaps may be explicitly listed.
+
+## 7. Report safely
+
+Open an issue in the owning repository with minimal reproduction and sanitized evidence. Security vulnerabilities must follow the organization's private `SECURITY.md` process rather than a public issue.
\ No newline at end of file
diff --git a/docs/v1/reference/compatibility.md b/docs/v1/reference/compatibility.md
new file mode 100644
index 0000000..235c9e6
--- /dev/null
+++ b/docs/v1/reference/compatibility.md
@@ -0,0 +1,34 @@
+# Compatibility reference
+
+Normative compatibility policy and the machine-readable contract matrix live in [`api-contracts/docs`](https://github.com/CoreLinkPlatform/api-contracts/tree/main/docs). This page explains how developers should interpret that information.
+
+## Current public baseline
+
+- Public OpenAPI: `corelink-public-v1.yaml`, `1.0.0-draft`.
+- Current reviewed public slice: Device + Command.
+- Event contract: canonical event envelope, with broader event/webhook acceptance still in progress.
+- TypeScript/Python: generated prerelease Alpha consumers.
+- Java/CLI/mock/MCP: Scaffold/Planned.
+- Console: Alpha application; its repository documents runtime/API compatibility and known read-model gaps.
+
+## Compatibility dimensions
+
+A useful compatibility claim names all relevant boundaries:
+
+1. contract revision/tag;
+2. runtime release/SHA;
+3. SDK/tool version when used;
+4. mock/sandbox revision for conformance when applicable;
+5. documentation version/maturity.
+
+## Draft versus supported
+
+An immutable draft tag is useful for reproducibility but is not a Stable support claim. A consumer may implement against a draft as long as its maturity is explicit.
+
+## Breaking changes
+
+Breaking public changes require a new major contract/migration decision. Generated clients should be regenerated from the new contract rather than patched manually.
+
+## Console compatibility
+
+Console fallbacks for APIs that are not yet available must remain documented implementation details. A UI working in demo/fallback mode does not prove that the corresponding public API is accepted.
\ No newline at end of file
diff --git a/docs/v1/reference/maturity.md b/docs/v1/reference/maturity.md
new file mode 100644
index 0000000..4920b45
--- /dev/null
+++ b/docs/v1/reference/maturity.md
@@ -0,0 +1,30 @@
+# CoreLink maturity vocabulary
+
+CoreLink uses shared maturity terms so repositories, docs, website copy and release notes do not turn implementation progress into unsupported product claims.
+
+| Maturity | Meaning |
+| --- | --- |
+| Planned | Scope exists in product/backlog decisions but implementation may not exist. |
+| Scaffold | Repository/structure exists but there is no supported executable/package surface. |
+| Experimental | Implementation exists for exploration; compatibility/support may be intentionally weak. |
+| Alpha | Usable implementation or contract exists, but scope/compatibility/acceptance can still change materially. |
+| Beta | Supported target scope is substantially defined and validated, with remaining release-readiness limits explicit. |
+| Stable | Versioned support, compatibility, documentation, security and release/operational gates are accepted. |
+| Deprecated | Previously available behavior is being retired under a documented migration/removal policy. |
+
+## Evidence rule
+
+The following are **not sufficient by themselves** to promote maturity:
+
+- public repository visibility;
+- a generated SDK;
+- a merged PR;
+- green CI;
+- a Docker image or package;
+- a Git tag;
+- a successful deployment;
+- a UI demo.
+
+Promotion must reconcile the owning repository's acceptance gate with relevant contract, runtime/conformance, security, documentation, release and product evidence.
+
+The organization-level current inventory is maintained in `CoreLinkPlatform/.github/REPOSITORY_MATURITY.md`.
\ No newline at end of file
diff --git a/docs/v1/sdks/python.md b/docs/v1/sdks/python.md
new file mode 100644
index 0000000..4b9a177
--- /dev/null
+++ b/docs/v1/sdks/python.md
@@ -0,0 +1,37 @@
+# Python SDK
+
+**Maturity:** Prerelease Alpha
+
+The `sdk-python` repository contains a generated Python client for the current draft public contract. It is not yet a Stable production-supported package, and public license/support policy must be resolved before supported publication.
+
+## Contract provenance
+
+Check `.corelink-contract.json`, `CODEGEN.md`, package metadata and release notes before use. A supported package must identify immutable contract provenance.
+
+## Current use
+
+For prerelease integration work:
+
+- build/install using the repository's documented environment;
+- configure base URL and bearer authentication through the generated client surface;
+- keep tenant context explicit;
+- follow OpenAPI-defined validation, idempotency and problem-response semantics;
+- pin the client revision in reproducible environments.
+
+Generated names may change while the SDK and contract are prerelease, so this guide does not invent a stable convenience layer.
+
+## Do not
+
+- hand-maintain generated schema/model files;
+- assume package generation proves runtime parity;
+- log bearer tokens or customer data in debug output;
+- bypass tenant-scoped APIs with direct data-store/provider access;
+- describe the package as Stable until PY-03 license/release/conformance gates pass.
+
+## Regeneration
+
+Use `sdk-python/CODEGEN.md`. Modify normative schemas in `api-contracts`, then regenerate and review the client diff.
+
+## Compatibility
+
+Supported Beta/Stable claims require the SDK, contract and accepted mock/sandbox/runtime revisions to be version-identifiable and conformance-tested.
\ No newline at end of file
diff --git a/docs/v1/sdks/typescript.md b/docs/v1/sdks/typescript.md
new file mode 100644
index 0000000..88562f0
--- /dev/null
+++ b/docs/v1/sdks/typescript.md
@@ -0,0 +1,36 @@
+# TypeScript SDK
+
+**Maturity:** Prerelease Alpha
+
+The `sdk-typescript` repository contains a generated client for the current draft public contract. It is not yet a Stable production-supported package.
+
+## Contract provenance
+
+Before using a generated SDK build, check its `.corelink-contract.json`, README and release metadata. Supported publication must eventually reference an immutable contract tag/revision rather than a development branch.
+
+## Current use
+
+For contract exploration and early integration work:
+
+1. inspect the SDK repository's package metadata and generated source;
+2. install/build only using the repository's documented prerelease workflow;
+3. configure the generated client's base URL/authentication using the generated API surface rather than copying private runtime code;
+4. keep tenant IDs explicit in tenant-scoped operations;
+5. preserve idempotency and problem-response behavior defined by the OpenAPI source.
+
+Exact generated method/type names may change while the contract/client remains prerelease, so this guide intentionally does not freeze a hand-written wrapper API that is not part of the generated release.
+
+## Do not
+
+- treat a generated client as evidence that the runtime supports every generated operation;
+- hand-edit generated `src/` files to change schemas;
+- expose provider-specific identifiers as application resource IDs;
+- claim Stable npm support before TS-03 release/conformance gates pass.
+
+## Regeneration
+
+Use `sdk-typescript/CODEGEN.md`. Contract changes belong in `api-contracts`; regenerate the client and review the generated diff.
+
+## Compatibility
+
+Runtime-contract-SDK compatibility must be demonstrated against an accepted mock/sandbox or runtime revision before supported Beta/Stable claims.
\ No newline at end of file
diff --git a/docs/v1/tools/developer-tools.md b/docs/v1/tools/developer-tools.md
new file mode 100644
index 0000000..c3e7c03
--- /dev/null
+++ b/docs/v1/tools/developer-tools.md
@@ -0,0 +1,32 @@
+# Developer tools: Java, CLI, mock server, and MCP
+
+These repositories are part of the CoreLink Developer Platform roadmap, but their current maturity is **Scaffold / Planned** unless a later release explicitly says otherwise.
+
+## Java SDK
+
+`CoreLinkPlatform/sdk-java` currently has no supported Java source/build/package baseline. Do not add dependency coordinates copied from an issue or planned design. JAVA-01/02/03 own generation, ergonomics and signed release/conformance work.
+
+## CLI
+
+`CoreLinkPlatform/cli` currently has no installable supported command. Documentation may describe intended authentication, tenant context and command boundaries, but must not show fake installation commands or imply an executable exists.
+
+## Mock server
+
+`CoreLinkPlatform/mock-server` is planned as a deterministic contract-driven local/CI runtime. The OpenAPI/AsyncAPI sources are **not empty**; the scaffold must consume reviewed versioned contracts from `api-contracts`. MOCK-01/02/03 own implementation, scenarios and packaged conformance.
+
+## MCP server
+
+`CoreLinkPlatform/mcp-server` is planned as an AI/MCP integration boundary. MCP-01 defines authorization/tenant/consent/audit requirements; MCP-02 owns read-only tools; state-changing MCP-03 work is separately gated; MCP-04 owns package/conformance.
+
+An MCP tool must not bypass public CoreLink authorization by calling internal/provider interfaces with elevated credentials.
+
+## Documentation rule
+
+A scaffold page should answer:
+
+- why the repository exists;
+- what is and is not implemented;
+- which contract/security decisions gate it;
+- where executable backlog lives.
+
+Installation and supported usage instructions are added only when a real artifact exists.
\ No newline at end of file