diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index e69de29..602fe74 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,29 @@ +# CoreLink Code of Conduct + +CoreLink Platform is developed in a professional, technical community. Participation in repositories, issues, pull requests, discussions, reviews, and project spaces requires respectful and constructive behavior. + +## Expected behavior + +- Focus criticism on ideas, code, interfaces, evidence, and outcomes rather than people. +- Use clear, professional language and assume good-faith technical disagreement unless evidence shows otherwise. +- Respect privacy, security boundaries, customer confidentiality, and contributor consent. +- Give actionable review feedback and distinguish blocking defects from preferences. +- Correct mistakes transparently and update stale claims when repository evidence changes. + +## Unacceptable behavior + +Harassment, threats, discrimination, sexualized conduct, doxxing, deliberate disclosure of private information, sustained personal attacks, spam, and attempts to bypass security or authorization controls are not acceptable. + +## Scope + +This policy applies to CoreLink-managed GitHub spaces and to project-related interactions where a participant is representing CoreLink. + +## Reporting + +For conduct concerns, use a private channel available to the CoreLink maintainers rather than a public issue when disclosure could harm a participant. Security vulnerabilities must follow `SECURITY.md` and must not be reported through public issues. + +## Enforcement + +Maintainers may edit or remove inappropriate content, restrict participation, close conversations, or escalate repeated/severe incidents. Enforcement decisions should be proportionate, documented where appropriate, and avoid exposing private reporter information. + +This project may adopt a more formal community enforcement process as the contributor community grows. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5041d48..03cb6a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,87 +1,60 @@ # Contributing to CoreLink Platform -Thank you for your interest in contributing to CoreLink Platform. - -This document describes the contribution process shared by public repositories in the CoreLinkPlatform organization. +Thank you for contributing to CoreLink Platform. CoreLink is managed as one product with multiple implementation and release boundaries. ## Before contributing -Before opening a pull request: - 1. Search existing issues and pull requests. 2. Confirm that the change belongs in the selected repository. -3. Open an issue before implementing major features or public API changes. -4. Avoid exposing private infrastructure, internal hostnames, customer information, credentials, or implementation-specific provider details. +3. For material product, architecture, security, or public-contract changes, link the relevant Product Epic or open a design issue first. +4. Do not expose private infrastructure, internal hostnames, customer information, credentials, or implementation-specific provider details in public surfaces. +5. Update documentation whenever behavior, compatibility, maturity, or supported operations change. ## Repository responsibilities -- `api-contracts`: API, event, webhook, and schema contracts -- `developer-docs`: tutorials, guides, concepts, and API documentation -- `sdk-typescript`: TypeScript, Node.js, React, and Next.js SDKs -- `sdk-python`: Python SDK -- `sdk-java`: Java and Spring integrations -- `examples`: runnable integration examples -- `cli`: CoreLink command-line interface -- `mcp-server`: Model Context Protocol integrations -- `mock-server`: API simulation and local development +- `platform`: private CoreLink runtime and operational implementation. +- `Console`: hosted SaaS console. The capitalized name is an existing naming exception retained to avoid release/link churn. +- `api-contracts`: public/admin/internal API, event, webhook, and schema contracts. +- `developer-docs`: tutorials, guides, concepts, reference, and developer operations documentation. +- `sdk-typescript`: TypeScript client. +- `sdk-python`: Python client. +- `sdk-java`: future Java/Spring client; currently Scaffold. +- `cli`: future developer/operator CLI; currently Scaffold. +- `mcp-server`: future MCP integration boundary; currently Scaffold. +- `mock-server`: future contract-driven local/CI simulation; currently Scaffold. +- `website`: public product website and developer discovery surface. +- `product-planning`: product hierarchy, cross-repository Epics, milestone gates, risks, and acceptance decisions. +- `.github`: organization governance, community health, maturity, contribution, security, and shared templates. + +The archived `demo-repository` is not an active product boundary. There is currently no standalone `examples` repository; runnable examples belong in the repository that owns them or in `developer-docs` until an examples repository is deliberately created. ## Public terminology -Public interfaces must use capability-oriented and implementation-independent terminology. - -Use terms such as: - -- Device Registry -- Device Gateway -- Fleet Engine -- IoT Runtime -- Telemetry Pipeline -- Command Gateway -- Provisioning Engine -- Digital Twin Service -- Integration Adapter -- Identity Provider - -Do not expose internal provider, vendor, product, infrastructure, or deployment names in: - -- public APIs; -- schemas; -- SDK types; -- package names; -- examples; -- documentation; -- error codes; -- telemetry fields; -- MCP tools and resources. +Public interfaces must be capability-oriented and implementation-independent. Prefer CoreLink-owned concepts such as Device Registry, Device Gateway, Telemetry Pipeline, Command Gateway, Provisioning Engine, Integration Adapter, and Identity Provider. + +Do not expose provider-specific models, credentials, identifiers, package names, error codes, or payload fields as CoreLink public contracts. ## API and schema changes -Changes to public contracts must: +Public-contract changes must: -- preserve stable operation identifiers; -- include request and response examples; -- define error responses; -- document authentication and authorization requirements; -- include compatibility impact; -- update the changelog; -- pass contract linting and breaking-change checks. +- preserve stable operation identifiers where compatibility requires it; +- include request/response examples; +- define error responses and auth requirements; +- document compatibility impact; +- update the changelog/version metadata; +- pass contract linting and breaking-change checks; +- reconcile affected SDKs, docs, Console behavior, mock/MCP/CLI consumers, and release notes. -Breaking changes require an approved proposal and a versioning plan. +Breaking changes require an approved versioning and migration decision. ## Pull requests -Pull requests should: - -- address one logical change; -- include tests where applicable; -- update documentation; -- avoid unrelated formatting changes; -- use clear commit messages; -- include compatibility and security considerations. +Pull requests should address one logical change, include tests where applicable, update documentation, avoid unrelated formatting churn, identify compatibility/security implications, and link the owning Issue/Epic when one exists. ## Commit style -Use concise imperative commit messages: +Use concise imperative Conventional Commit-style messages where practical: ```text feat: add device command schema @@ -90,10 +63,14 @@ docs: document client credentials flow chore: update contract validation workflow ``` -## Development status +## Maturity and support claims + +Use the organization maturity vocabulary: **Scaffold, Experimental, Alpha, Beta, Stable, Deprecated, Planned**. A merged feature, generated package, public repository, or release tag does not by itself establish Stable support. Check `REPOSITORY_MATURITY.md` and the owning repository's release evidence. + +## Security -The project is under active development. APIs and SDKs may change until the first stable release. +Security vulnerabilities must follow `SECURITY.md` and must not be disclosed in public issues or pull requests. ## License -By contributing, you agree that your contributions will be licensed under the license declared by the target repository. \ No newline at end of file +By contributing, you agree that contributions are governed by the license declared by the target repository. Public visibility does not imply an open-source license. \ No newline at end of file diff --git a/README.md b/README.md index 7aed507..88bb3e3 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,28 @@ # CoreLink GitHub Community Health -Repository-wide community-health and contribution assets for CoreLink -repositories. +Organization-wide governance and community-health assets for CoreLink repositories. ## Contents -- `CONTRIBUTING.md`: contribution expectations. -- `CODE_OF_CONDUCT.md`: community behavior policy. -- `SECURITY.md`: vulnerability-reporting policy. -- `GOVERNANCE.md`: project governance. -- `ISSUE_TEMPLATE/`: organization-wide bug, feature, implementation, Product Epic and documentation forms. -- `PULL_REQUEST_TEMPLATE.md`: pull-request checklist. -- `profile/README.md`: organization profile shown on GitHub. -- `REPOSITORY_MATURITY.md`: reconciled repository roles and maturity claims. +- `CONTRIBUTING.md` — contribution expectations and repository responsibility map. +- `CODE_OF_CONDUCT.md` — community behavior and enforcement baseline. +- `SECURITY.md` — private vulnerability-reporting policy. +- `SUPPORT.md` — support routing and maturity expectations. +- `GOVERNANCE.md` — project decision model. +- `RELEASE_POLICY.md` — shared maturity, provenance, compatibility and release rules. +- `ISSUE_TEMPLATE/` — organization-wide issue forms. +- `PULL_REQUEST_TEMPLATE.md` — pull-request checklist. +- `profile/README.md` — organization profile shown on GitHub. +- `REPOSITORY_MATURITY.md` — reconciled active-repository roles and maturity claims. -## Usage +## Source-of-truth boundaries -GitHub applies these files automatically only when this repository is named -`.github` at the organization level. If it is intentionally named `github` in -local development, copy or sync the reviewed files to the organization's -special `.github` repository before relying on GitHub to display or enforce -them. +- Product hierarchy, Epics, milestone gates, risks and acceptance decisions: `product-planning`. +- Organization policy and maturity: `.github`. +- Machine-readable API/event contracts and compatibility: `api-contracts`. +- Human-facing developer guidance: `developer-docs`. +- Repository-specific implementation/deployment details: the owning repository. -Product Epics are owned by `product-planning`; executable Features/Tasks stay in the repository that implements them and link to exactly one primary Product Epic. Repository-local templates may narrow these defaults but must preserve that hierarchy.\n\nPlatform changes must also follow the architecture rules in the `platform` -repository, including tenant isolation, upstream-adapter boundaries, audit and -documentation review. +Product Epics are owned by `product-planning`; executable Features/Tasks stay in the repository that implements them and link to a primary Product Epic. Repository-local templates may narrow these defaults but must preserve that hierarchy. + +Platform changes must also follow architecture, tenant-isolation, adapter-boundary, audit and evidence rules documented by the `platform` repository. \ No newline at end of file diff --git a/RELEASE_POLICY.md b/RELEASE_POLICY.md new file mode 100644 index 0000000..a6ae18b --- /dev/null +++ b/RELEASE_POLICY.md @@ -0,0 +1,42 @@ +# CoreLink Release Policy + +CoreLink is one product with multiple release boundaries. Runtime, contracts, Console, SDKs, tools, documentation, and the website may have separate artifacts, but supported claims must reconcile through one product maturity model. + +## Maturity + +Use: **Scaffold, Experimental, Alpha, Beta, Stable, Deprecated, Planned**. + +A tag or package publication does not by itself establish support. Supported releases require the owning repository's release gate plus compatible contract, security, documentation, and operational evidence. + +## Version provenance + +Released artifacts should identify immutable source and dependency revisions. Generated SDKs and contract consumers must identify the exact contract tag/revision used. Branch names are not release provenance. + +## Release contents + +Where applicable, a release should include: + +- version/tag and immutable commit SHA; +- maturity classification; +- compatible contract/runtime/tool versions; +- release notes and known limitations; +- build/package provenance and SBOM when supported by the release workflow; +- deployment/install instructions; +- migration and rollback guidance; +- security/support implications. + +## Breaking changes + +Breaking public-contract changes require an explicit major-version/migration decision. Consumer releases must not silently drift from normative contracts. + +## Pre-release channels + +Alpha/Beta/RC artifacts must be labeled as prerelease and must not be described as Stable. Scaffold repositories must not publish installation instructions that imply a supported artifact exists. + +## Product acceptance + +Engineering completion, CI success, deployment success, and Product Acceptance are distinct. Product milestone acceptance remains owned by `product-planning` and must be backed by retained evidence appropriate to that milestone. + +## Cross-repository reconciliation + +A release or maturity change should update affected compatibility matrices, developer docs, repository README/status text, organization maturity/profile, and website claims in the same change set or link explicit follow-up work. \ No newline at end of file diff --git a/REPOSITORY_MATURITY.md b/REPOSITORY_MATURITY.md index 7468c28..a222e37 100644 --- a/REPOSITORY_MATURITY.md +++ b/REPOSITORY_MATURITY.md @@ -1,67 +1,56 @@ # CoreLink repository maturity inventory -**Last reconciled: 2026-08-06** +**Last reconciled: 2026-08-29** -CoreLink is one product delivered through multiple repositories. This inventory -records repository role and maturity; it is not a second product roadmap. -Product goals, milestones and cross-repository Epics remain authoritative in -[`product-planning`](https://github.com/CoreLinkPlatform/product-planning). +CoreLink is one product delivered through multiple repositories. This inventory records repository role and maturity; it is not a second product roadmap. Product goals, milestones, cross-repository Epics, and acceptance decisions remain authoritative in [`product-planning`](https://github.com/CoreLinkPlatform/product-planning). -Maturity words follow the shared CoreLink vocabulary: **Scaffold**, -**Experimental**, **Alpha**, **Beta**, **Stable**, **Deprecated**, and -**Planned**. Repository visibility or the presence of source code does not make -a capability Stable or commercially supported. +Maturity vocabulary: **Scaffold, Experimental, Alpha, Beta, Stable, Deprecated, Planned**. Repository visibility, source-code volume, a merged PR, or a release tag does not by itself establish Stable/commercial support. -## Current inventory +## Active repository inventory -| Repository | Product role | Current maturity | What that means now | +| Repository | Product role | Current maturity | Current meaning | | --- | --- | --- | --- | -| [`platform`](https://github.com/CoreLinkPlatform/platform) | Core runtime | Implemented foundation / pre-release | Substantial tenancy, identity, device, command and event foundations exist; product acceptance gates are still open. | -| [`api-contracts`](https://github.com/CoreLinkPlatform/api-contracts) | Public/admin/internal API and event contracts | Alpha · `1.0.0-draft` public boundary | Device + Command public slice and canonical event envelope are reviewable; draft is not a Stable v1 release. | -| [`developer-docs`](https://github.com/CoreLinkPlatform/developer-docs) | Versioned developer documentation | Alpha | v1 information architecture and contract-backed quickstart target the draft public boundary. | -| [`sdk-typescript`](https://github.com/CoreLinkPlatform/sdk-typescript) | TypeScript client | Prerelease Alpha | Generated client exists; no production-supported package release is claimed. | -| [`sdk-python`](https://github.com/CoreLinkPlatform/sdk-python) | Python client | Prerelease Alpha | Generated client exists; no production-supported package release is claimed. | -| [`sdk-java`](https://github.com/CoreLinkPlatform/sdk-java) | Java client | Scaffold · Planned | No supported Java package exists yet. | +| [`platform`](https://github.com/CoreLinkPlatform/platform) | Core runtime | Alpha / implemented foundation | Substantial tenancy, identity, device, command, telemetry/event, commercial and operational foundations exist; hosted-alpha and product acceptance gates remain active. | +| [`Console`](https://github.com/CoreLinkPlatform/Console) | Hosted SaaS console | Alpha | Deployable asset-first Console exists with OIDC/BFF, operational views and release packaging. Live acceptance still depends on supported runtime read models and hosted-alpha evidence. | +| [`api-contracts`](https://github.com/CoreLinkPlatform/api-contracts) | Public/admin/internal API and event contracts | Alpha · `1.0.0-draft` public boundary | Device + Command public slice and canonical event envelope are reviewable; broader v1 contract work is ongoing. | +| [`developer-docs`](https://github.com/CoreLinkPlatform/developer-docs) | Versioned developer documentation | Alpha | Versioned v1 IA exists; quickstart and broader guides are being reconciled with supported contract/runtime maturity. | +| [`sdk-typescript`](https://github.com/CoreLinkPlatform/sdk-typescript) | TypeScript client | Prerelease Alpha | Generated client exists; supported publication/conformance gates are still open. | +| [`sdk-python`](https://github.com/CoreLinkPlatform/sdk-python) | Python client | Prerelease Alpha | Generated client exists; supported publication/conformance and license-policy gates are still open. | +| [`sdk-java`](https://github.com/CoreLinkPlatform/sdk-java) | Java client | Scaffold · Planned | No supported Java source/package/build baseline exists yet. | | [`cli`](https://github.com/CoreLinkPlatform/cli) | Developer/operator CLI | Scaffold · Planned | No installable supported CLI exists yet. | -| [`mock-server`](https://github.com/CoreLinkPlatform/mock-server) | Local/CI API simulation | Scaffold · Planned | No supported mock-server package/runtime exists yet. | -| [`mcp-server`](https://github.com/CoreLinkPlatform/mcp-server) | Agent/MCP integration | Scaffold · Planned | No supported MCP server/tool surface exists yet. | -| [`website`](https://github.com/CoreLinkPlatform/website) | Public product website | Active public surface / pre-release claims | Claims must mirror this inventory and retained repository/release evidence. | -| [`product-planning`](https://github.com/CoreLinkPlatform/product-planning) | Product governance | Source of truth | Owns product hierarchy, milestones, decisions and cross-repository acceptance. | -| [`.github`](https://github.com/CoreLinkPlatform/.github) | Organization governance/community health | Source of truth | Owns organization defaults, profile, contribution/security policy and shared Issue forms. | +| [`mock-server`](https://github.com/CoreLinkPlatform/mock-server) | Local/CI contract simulation | Scaffold · Planned | No supported mock runtime/package exists yet; it must consume reviewed versioned contracts. | +| [`mcp-server`](https://github.com/CoreLinkPlatform/mcp-server) | Agent/MCP integration | Scaffold · Planned | No supported MCP package/tool surface exists yet; security and read-only boundaries are backlog-gated. | +| [`website`](https://github.com/CoreLinkPlatform/website) | Public product website | Active public surface / Alpha claims | GitHub Pages is the supported production path; public claims must mirror this inventory and retained evidence. | +| [`product-planning`](https://github.com/CoreLinkPlatform/product-planning) | Product governance | Source of truth | Owns product hierarchy, milestone gates, risks, cross-repository Epics and acceptance decisions. | +| [`.github`](https://github.com/CoreLinkPlatform/.github) | Organization governance/community health | Source of truth | Owns organization profile, maturity, contribution/security/support/release policy and shared templates. | -The former `examples` link is intentionally absent: no accessible -`CoreLinkPlatform/examples` repository was found during this reconciliation. -Examples must not be advertised as a runnable product resource until a real, -versioned repository and acceptance evidence exist. +**Active repositories: 13.** The archived `demo-repository` is excluded from active-product coverage. -## Capability boundary represented publicly +`Console` is the canonical existing frontend repository name. Its capitalized name is retained as a documented naming exception to avoid breaking existing links, packages, release automation, and deployment references. -Today the public developer boundary is intentionally narrower than the internal -runtime foundation: +There is currently no standalone `CoreLinkPlatform/examples` repository. Runnable examples must not be advertised as a separate repository until one is deliberately created, versioned, and accepted. + +## Public capability boundary + +The public developer boundary remains intentionally narrower than the private runtime foundation: - public API contract: Device + Command on `1.0.0-draft`; - public event contract: canonical event envelope; - TypeScript/Python clients: prerelease Alpha; +- Console: Alpha hosted application, with runtime read-model gaps documented by the Console repository; - Java/CLI/mock/MCP: Scaffold/Planned; -- telemetry, digital twin, media, white-label and broader integration claims - require their own contract/runtime/release evidence before being presented as - Stable supported public capability. +- telemetry/location, partner operations, usage/billing, automation/media and other surfaces require version-identifiable contract/runtime/release evidence before Stable support claims. ## Ownership and review -- Product Council/product planning owns milestone and product-maturity decisions. -- Each repository owns implementation evidence and its repository README. -- The website and organization profile may summarize maturity but must link back - to the owning repository/contract instead of becoming independent roadmaps. -- A repository owner changing a public maturity claim must update affected docs, - website/profile copy and retained release evidence in the same product change - or link follow-up work explicitly. -- Exceptions are recorded as product decisions in `product-planning`; they are - not hidden in marketing copy or repository-local status text. +- Product planning owns milestone and product-maturity decisions. +- Each implementation repository owns implementation evidence, local development/deployment documentation, and its repository README. +- `api-contracts` owns normative machine-readable API/event schemas and compatibility policy. +- `developer-docs` owns human-facing tutorials, concepts, guides, examples, and developer troubleshooting. +- `website` and the organization profile summarize maturity but must link to authoritative sources rather than becoming independent roadmaps. +- A maturity change must reconcile affected docs, website/profile copy, package metadata, compatibility matrices, and release evidence. +- Exceptions are explicit product/governance decisions, not hidden marketing or repository-local wording. ## Reconciliation cadence -Review this inventory at every product milestone gate and whenever a repository -enters or leaves Scaffold/Experimental/Alpha/Beta/Stable/Deprecated status. -A release tag alone is insufficient: contract compatibility, runtime evidence, -documentation and the owning repository's acceptance gate must agree. +Review this inventory at every product milestone gate and whenever a repository enters or leaves Scaffold/Experimental/Alpha/Beta/Stable/Deprecated status, or when an active repository is created/archived. Contract compatibility, runtime evidence, documentation, and owning-repository acceptance must agree. \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md index ae73fe2..d808fc5 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,57 +2,51 @@ ## Reporting a vulnerability -Do not report security vulnerabilities through public GitHub issues, discussions, or pull requests. +Do **not** report security vulnerabilities through public GitHub issues, discussions, pull requests, or comments. -Report suspected vulnerabilities privately by email +Use GitHub's private vulnerability reporting / Security Advisory flow on the affected CoreLink repository when that private reporting option is available. If a repository does not expose a private reporting flow, contact a CoreLink maintainer through an existing private organizational channel and identify the affected repository so a private advisory can be opened. Include, where possible: -- affected repository and version; -- vulnerability description; -- reproduction steps; +- affected repository and version or commit; +- vulnerability description and security boundary affected; +- minimal reproduction steps; - expected and actual behavior; - potential impact; -- suggested mitigation; -- relevant logs or screenshots with sensitive information removed. +- suggested mitigation, if known; +- sanitized logs or screenshots. -Do not include: +Do not include unnecessary secrets, access tokens, client secrets, private keys, customer data, production credentials, or personally identifiable information. -- access tokens; -- client secrets; -- private keys; -- customer data; -- production credentials; -- unnecessary personally identifiable information. -- Response process +## Response process -## We aim to: +We aim to: -acknowledge reports within 5 business days; -investigate and assess severity; -coordinate remediation and disclosure; -publish security advisories when appropriate. +- acknowledge a private report within 5 business days; +- investigate impact and affected versions; +- coordinate remediation and disclosure; +- publish a GitHub Security Advisory when appropriate; +- update supported release and mitigation guidance. -These targets are not contractual service-level guarantees. +These targets are operational goals, not contractual service-level guarantees. ## Supported versions -Until the first stable release, only the latest published preview version is evaluated for security updates. - -After stable releases begin, supported versions will be listed here. +Until the first Stable release, only the latest published preview release is evaluated for security updates unless a release note explicitly states otherwise. Stable-version support windows will be documented when Stable releases begin. ## Scope Security reports may include: -authentication and authorization bypass; -tenant isolation failures; -credential exposure; -command execution vulnerabilities; -webhook signature bypass; -request forgery; -unsafe SDK behavior; -dependency vulnerabilities with demonstrated impact; -MCP tool authorization or data-exposure issues. - -General support requests and feature requests should use the repository issue tracker. \ No newline at end of file +- authentication or authorization bypass; +- tenant-isolation or RLS failures; +- credential or secret exposure; +- command-execution vulnerabilities; +- webhook signature or replay-control bypass; +- request forgery or unsafe callback behavior; +- unsafe SDK/CLI credential handling; +- dependency vulnerabilities with demonstrated product impact; +- MCP authorization, consent, or data-exposure failures; +- release/supply-chain provenance weaknesses with exploitable impact. + +General support requests, implementation questions, and feature requests should use the appropriate repository issue tracker or `SUPPORT.md`. \ No newline at end of file diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..5bc6bf8 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,24 @@ +# CoreLink Support + +CoreLink is currently an Alpha/pre-release product. Support expectations depend on the maturity of the affected repository or release. + +## Where to ask + +- Bugs in a specific repository: open an Issue in that repository with reproducible, sanitized evidence. +- Public API/schema questions: use `api-contracts`. +- Developer documentation problems: use `developer-docs`. +- Console behavior: use `Console`. +- Product-scope, roadmap, or cross-repository questions: use the relevant Product Epic in `product-planning` when access permits. +- Security vulnerabilities: follow `SECURITY.md`; never disclose them in public support issues. + +## What to include + +Provide the repository, version/tag/commit, environment type, expected and actual behavior, minimal reproduction, relevant correlation/request identifiers, and sanitized logs. Do not post credentials, customer data, private infrastructure details, or access tokens. + +## Support maturity + +Scaffold and Planned repositories have no supported runtime/package surface. Alpha and prerelease artifacts may change and should not be treated as Stable compatibility commitments. Stable support windows will be published when Stable releases begin. + +## Commercial support + +Public repository support does not create a contractual SLA. Customer/design-partner support, response targets, and operational escalation paths are governed by the applicable private agreement and release acceptance boundary. \ No newline at end of file diff --git a/profile/README.md b/profile/README.md index ccf0ea9..929aa7c 100644 --- a/profile/README.md +++ b/profile/README.md @@ -4,16 +4,13 @@ ### زیرساخت اتصال و یکپارچه‌سازی محصولات هوشمند -CoreLink یک محصول واحد با چند مرز پیاده‌سازی است: قراردادهای عمومی، runtime، -SDKها، مستندات و ابزارها با یک مدل maturity مشترک تکامل پیدا می‌کنند. +CoreLink یک محصول واحد با چند مرز پیاده‌سازی و انتشار است: runtime، Console، قراردادهای عمومی، SDKها، مستندات و ابزارها با یک مدل maturity مشترک تکامل پیدا می‌کنند. [Developer Documentation](https://github.com/CoreLinkPlatform/developer-docs) -· -[API Contracts](https://github.com/CoreLinkPlatform/api-contracts) -· -[Product Website](https://corelinkplatform.ir) -· -[Repository Maturity](../REPOSITORY_MATURITY.md) +· [API Contracts](https://github.com/CoreLinkPlatform/api-contracts) +· [CoreLink Console](https://github.com/CoreLinkPlatform/Console) +· [Product Website](https://corelinkplatform.ir) +· [Repository Maturity](../REPOSITORY_MATURITY.md) @@ -21,76 +18,61 @@ SDKها، مستندات و ابزارها با یک مدل maturity مشترک ## وضعیت فعلی محصول -CoreLink هنوز یک انتشار Stable v1 نیست. مرز عمومی فعلی به‌صورت شفاف محدود است: +CoreLink هنوز Stable v1 نیست. -- **API Contracts:** Alpha، با baseline فعلی `1.0.0-draft` برای Device و - Command و canonical event envelope. -- **TypeScript SDK:** Prerelease Alpha. -- **Python SDK:** Prerelease Alpha. +- **Runtime:** Alpha / implemented foundation؛ hosted-alpha و acceptance evidence در حال تکمیل است. +- **Console:** Alpha؛ اپلیکیشن SaaS قابل deploy با OIDC/BFF و جریان‌های عملیاتی، با چند read-model gap مستندشده در runtime. +- **API Contracts:** Alpha، baseline عمومی فعلی `1.0.0-draft`. +- **TypeScript / Python SDKs:** Prerelease Alpha. - **Java SDK / CLI / Mock Server / MCP Server:** Scaffold · Planned. -- **Core runtime:** foundation پیاده‌سازی‌شده دارد، اما تکمیل engineering - foundation به‌تنهایی معادل پذیرش محصول یا انتشار Stable نیست. -[موجودی کامل maturity ریپوها](../REPOSITORY_MATURITY.md) مرجع این خلاصه است. +[موجودی کامل maturity](../REPOSITORY_MATURITY.md) مرجع این خلاصه است. ## CoreLink چه مسئله‌ای را حل می‌کند؟ -CoreLink برای ساخت محصولات متصل طراحی شده است: دستگاه و integration در مرز -زیرساخت جذب می‌شوند و applicationها با شناسه‌ها، قراردادها و رفتارهای -CoreLink-owned کار می‌کنند. +CoreLink برای ساخت و بهره‌برداری محصولات متصل طراحی شده است. دستگاه‌ها و providerها در مرز زیرساخت جذب می‌شوند و applicationها با شناسه‌ها، قراردادها و رفتارهای CoreLink-owned کار می‌کنند. -جهت محصول شامل device lifecycle، commands، telemetry/state، events، -integrations و تجربه‌های white-label است؛ اما هر مورد فقط وقتی «قابلیت پشتیبانی -شده» محسوب می‌شود که contract، runtime، مستندات و release evidence همان maturity -را تأیید کنند. +جهت محصول شامل device lifecycle، commands، telemetry/location/state، events/webhooks، integrations، commercial controls و تجربه‌های white-label است؛ اما هر مورد فقط وقتی «پشتیبانی‌شده» محسوب می‌شود که contract، runtime، documentation و release/acceptance evidence همان maturity را تأیید کنند. ## از کجا شروع کنیم؟ | منبع | وضعیت | کاربرد فعلی | | --- | --- | --- | -| [Developer docs](https://github.com/CoreLinkPlatform/developer-docs) | Alpha | مستندات نسخه‌دار و quickstart مبتنی بر contract | -| [API contracts](https://github.com/CoreLinkPlatform/api-contracts) | Alpha · `1.0.0-draft` | مرز عمومی Device + Command و event envelope | -| [TypeScript SDK](https://github.com/CoreLinkPlatform/sdk-typescript) | Prerelease Alpha | کلاینت generated؛ هنوز release پایدار نیست | -| [Python SDK](https://github.com/CoreLinkPlatform/sdk-python) | Prerelease Alpha | کلاینت generated؛ هنوز release پایدار نیست | -| [Java SDK](https://github.com/CoreLinkPlatform/sdk-java) | Scaffold · Planned | مسیر توسعه آینده؛ package پشتیبانی‌شده ندارد | -| [CLI](https://github.com/CoreLinkPlatform/cli) | Scaffold · Planned | ابزار برنامه‌ریزی‌شده؛ installable release ندارد | -| [Mock Server](https://github.com/CoreLinkPlatform/mock-server) | Scaffold · Planned | شبیه‌ساز برنامه‌ریزی‌شده | -| [MCP Server](https://github.com/CoreLinkPlatform/mcp-server) | Scaffold · Planned | سطح agent/MCP برنامه‌ریزی‌شده | +| [Developer docs](https://github.com/CoreLinkPlatform/developer-docs) | Alpha | مستندات نسخه‌دار، quickstart و راهنماهای توسعه‌دهنده | +| [API contracts](https://github.com/CoreLinkPlatform/api-contracts) | Alpha · `1.0.0-draft` | مرز machine-readable عمومی/admin/internal و event schemas | +| [Console](https://github.com/CoreLinkPlatform/Console) | Alpha | تجربه hosted SaaS برای tenant/assets/telemetry/alerts/usage/integrations | +| [TypeScript SDK](https://github.com/CoreLinkPlatform/sdk-typescript) | Prerelease Alpha | generated client؛ هنوز Stable package نیست | +| [Python SDK](https://github.com/CoreLinkPlatform/sdk-python) | Prerelease Alpha | generated client؛ هنوز Stable package نیست | +| [Java SDK](https://github.com/CoreLinkPlatform/sdk-java) | Scaffold · Planned | package پشتیبانی‌شده ندارد | +| [CLI](https://github.com/CoreLinkPlatform/cli) | Scaffold · Planned | installable release ندارد | +| [Mock Server](https://github.com/CoreLinkPlatform/mock-server) | Scaffold · Planned | contract-driven simulation در backlog | +| [MCP Server](https://github.com/CoreLinkPlatform/mcp-server) | Scaffold · Planned | سطح MCP امن و tenant-scoped در backlog | ## قرارداد عمومی امروز -برای integration جدید، قرارداد عمومی منبع حقیقت است؛ نه ساختار provider یا -جزئیات داخلی runtime. +برای integration جدید، قرارداد عمومی منبع حقیقت است؛ نه ساختار provider یا جزئیات داخلی runtime. - شناسه عمومی دستگاه: `corelink_device_id`; - tenant scope در مسیرهای عمومی صریح است; -- authentication فعلی قرارداد عمومی: Bearer JWT; +- authentication قرارداد عمومی: Bearer JWT; - Command create نیازمند `Idempotency-Key` است; - provider/connector identifiers جزئیات پیاده‌سازی‌اند. -Quickstart و referenceهای نسخه‌دار در -[`developer-docs`](https://github.com/CoreLinkPlatform/developer-docs) قرار -دارند. +Quickstart و referenceهای نسخه‌دار در [`developer-docs`](https://github.com/CoreLinkPlatform/developer-docs) قرار دارند. ## یک محصول، چند repository -Product hierarchy، milestone gates و تصمیم‌های cross-repository در -[`product-planning`](https://github.com/CoreLinkPlatform/product-planning) -مدیریت می‌شوند. هر repository فقط implementation/evidence مرز خودش را نگه -می‌دارد. +Product hierarchy، milestone gates و تصمیم‌های cross-repository در [`product-planning`](https://github.com/CoreLinkPlatform/product-planning) مدیریت می‌شوند. هر repository implementation/evidence مرز خودش را نگه می‌دارد. -وضعیت یک repository را از public بودن، تعداد فایل‌ها یا وجود یک scaffold نتیجه -نمی‌گیریم. واژگان مشترک maturity عبارت‌اند از **Scaffold, Experimental, Alpha, -Beta, Stable, Deprecated, Planned**. +واژگان maturity مشترک: **Scaffold, Experimental, Alpha, Beta, Stable, Deprecated, Planned**. ## اعتماد، امنیت و مشارکت -- آسیب‌پذیری امنیتی را طبق [Security Policy](../SECURITY.md) گزارش کنید. -- تغییرات کد و مستندات باید [Contribution Guide](../CONTRIBUTING.md) را رعایت کنند. -- Issueهای اجرایی از [organization Issue forms](../ISSUE_TEMPLATE/) استفاده - می‌کنند و به Product Epic مربوط لینک می‌شوند. -- وضعیت محصول یا package را قبل از استفاده production از repository مالک و - [maturity inventory](../REPOSITORY_MATURITY.md) بررسی کنید. +- [Security Policy](../SECURITY.md) +- [Support Policy](../SUPPORT.md) +- [Contribution Guide](../CONTRIBUTING.md) +- [Release Policy](../RELEASE_POLICY.md) +- [Repository Maturity](../REPOSITORY_MATURITY.md) ---