CoreLink Developer Documentation

Documentation Docs: v1 Contract: 1.0.0-draft Maturity: Pre-Stable

Developer-facing documentation for using CoreLink safely and consistently. Versioned contracts in 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
• CoreLink v1 documentation
• 30-minute v1 quickstart
• Architecture
• Authentication and tenant context
• Compatibility
• Maturity vocabulary

CoreLink v1 is not Stable. The public Device/Command contract is 1.0.0-draft; TypeScript/Python clients are prerelease Alpha with immutable tagged-contract regeneration evidence; Java has an Experimental generated Java 17+ baseline but no supported public artifact; Console is Alpha; CLI, MCP server and mock server remain Scaffold/Planned. Control is a private operator surface and is not part of the public developer API contract.

Each version can contain:

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.

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.

• 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.

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.

• Product direction and milestone acceptance: product-planning
• Organization maturity/security/support/release policy: .github
• Normative API/event schemas: api-contracts
• Implementation/deployment details: the owning repository (platform, Console, Control, SDK/tool repositories, website)