docs(onboarding): 帮助用户开始使用 InKCre

.github/workflows/pages-preview.yml

@@ -78,12 +78,28 @@ jobs:
     permissions:
       contents: read
       deployments: write
+      statuses: write
     runs-on: ubuntu-latest
     timeout-minutes: 15
     environment:
       name: preview
       url: ${{ steps.pages.outputs.pages-deployment-alias-url }}
     steps:
+      - name: Mark the pull-request preview pending
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }}
+        with:
+          script: |
+            await github.rest.repos.createCommitStatus({
+              ...context.repo,
+              sha: process.env.PREVIEW_HEAD_SHA,
+              context: 'docs preview',
+              state: 'pending',
+              description: '正在构建并部署预览',
+              target_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            })
+
       - name: Checkout the trusted preview controller
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -142,3 +158,24 @@ jobs:
           CLOUDFLARE_PAGES_DEPLOYMENT_ID: ${{ steps.pages.outputs.pages-deployment-id }}
           CLOUDFLARE_PAGES_DEPLOYMENT_URL: ${{ steps.pages.outputs.pages-deployment-alias-url }}
           INKCRE_PAGES_SMOKE_MODE: preview
+
+      - name: Report the preview result on the pull-request commit
+        if: ${{ always() }}
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }}
+          PREVIEW_RESULT: ${{ job.status }}
+          PREVIEW_URL: ${{ steps.pages.outputs.pages-deployment-alias-url }}
+        with:
+          script: |
+            const succeeded = process.env.PREVIEW_RESULT === 'success'
+            await github.rest.repos.createCommitStatus({
+              ...context.repo,
+              sha: process.env.PREVIEW_HEAD_SHA,
+              context: 'docs preview',
+              state: succeeded ? 'success' : 'error',
+              description: succeeded ? '预览已就绪，点击查看' : '预览失败或取消，点击查看日志',
+              target_url: succeeded
+                ? process.env.PREVIEW_URL
+                : `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            })

20-product-tdd/cross-unit-contracts.md

@@ -25,6 +25,14 @@ Record durable data and behavior contracts that span more than one unit reposito
 - `running` means the current runtime has actually started that extension and applied its runtime side effects.
 - Starting or stopping an extension is not a pure flag flip; it changes runtime capabilities and API surface for that client.
 
+## Extension Documentation Hosting Contract
+
+- Author-built static documentation, exact Release/scope identity, conditional whole-site
+  corrections, snapshot-origin isolation, and consumer discovery follow the
+  [Extension Documentation Hosting Contract](extension-documentation-hosting.md).
+- Registry owns hosting and executable API details; authors own site content and structure.
+  Documentation does not become an installable Distribution or alter Host lifecycle authority.
+
 ## Info-Base Ownership Contract
 
 - Collection, organization, application, graph authority, resolver/storage composition, and

20-product-tdd/extension-documentation-hosting.md

@@ -0,0 +1,113 @@
+# Extension Documentation Hosting
+
+## Purpose And Ownership
+
+This contract defines how Extension authors, Registry, developer tooling, and consuming Hosts
+exchange hosted documentation. Registry owns the executable HTTP contract and hosting mechanics;
+this document owns the boundaries that those implementations must preserve.
+
+Authors build a static site with their chosen tools. Registry accepts and serves the resulting
+files without running builds, interpreting document structure, or rewriting HTML and JavaScript.
+Navigation, search, localization, themes, and interface-specific instructions belong to the
+author's site. Documentation is not an executable Extension Distribution and cannot make a Release
+installable by itself.
+
+## Identity And Document Ownership
+
+A documentation set belongs to one Extension name, one exact Release version, and one scope:
+
+| Scope | Meaning | First-party source owner |
+| --- | --- | --- |
+| `global` | Extension-wide concepts, workflows, and limits across channels | `core-py` |
+| `python` | Python Distribution operation and configuration | The Python producer in `core-py` |
+| `module-federation` | Web Distribution interfaces and behavior | The MF producer in `client-web` |
+
+These are separate, optional sites, not inheritance or override layers. Registry does not merge
+them. A channel-specific set requires the corresponding Distribution association on that Release;
+global documentation does not require a Web Distribution. Web, CLI, and Agent instructions are
+reader interfaces, not additional Distribution channels.
+
+First-party sites share a template maintained in `InKCre/docs`, with producer repositories using
+an explicit template revision. This does not require ecosystem authors to adopt that template or
+its static-site generator. The main documentation site owns application onboarding, self-hosting,
+and cross-Extension guidance; detailed Extension instructions retain one source owner rather than
+being copied into each consuming site.
+
+## Discovery And Consumption
+
+Registry exposes documentation discovery separately from Release installation metadata. Consumers
+ask their configured Registry for the exact installed Release and receive the available scopes,
+stable entry addresses, current content identities, update times, and publication provenance.
+Adding documentation must not invalidate existing strict Release consumers.
+
+An absent scope is genuinely absent. Consumers may explicitly offer global documentation instead
+of a missing channel site, but must not silently substitute another scope or version. Page paths
+inside a site remain an agreement between its author and consumers, not Registry-defined content
+semantics. Consumers follow Registry-provided entry addresses rather than constructing content
+hostnames or assuming documentation shares the management origin.
+
+## Publication And Corrections
+
+Publishing a set uploads a complete static bundle and identifies its entry file. Registry validates
+the bundle's paths, entry, file types, and resource bounds; it does not accept server-side execution
+or author-defined server configuration. Detailed archive, routing, MIME, and error contracts belong
+to Registry's executable API and local documentation.
+
+Namespace publication authority also controls that namespace's documentation. Creating a set
+requires a conditional create; replacing it requires the observed current entity tag. Only after
+all files are available may Registry atomically move that set's entry to the new snapshot. A failed
+upload or conflicting replacement leaves the previous entry intact. Clients resolve uncertain
+responses by retrying the same saved publication candidate. Its snapshot identity also identifies
+that publication: once committed, the exact same target, content, provenance, and original write
+precondition return the original commit receipt without changing the current-set pointer. Reusing
+the identity for a different committed request is a conflict. A receipt confirms a historical commit,
+not that its snapshot is still current; another publication may already have superseded it.
+
+Clients may make bounded best-effort retries, but hosting does not guarantee eventual delivery.
+When a receipt cannot be obtained, the outcome remains unknown and the candidate must remain
+available for a later retry. Clients do not refresh the write precondition, generate a replacement
+identity, or infer failure merely because a response was lost. Authentication and Release lifecycle
+rules also apply when confirming an earlier commit.
+
+Documentation can be corrected without a new Extension Release. There is no separate documentation
+semantic version, automatic inheritance between Releases, or many-to-many applicability mapping.
+Updating one scope does not update another or mutate Python/MF artifacts. Snapshot content is
+immutable; its identity serves integrity and resource consistency, not a second author-managed
+version scheme.
+
+Previously published snapshots remain available while their owning Release permits public reads,
+so an already opened page can finish loading its original resources. Each public snapshot remains
+bound to its exact Release and scope even when underlying byte storage is deduplicated.
+
+## Static Content Boundary
+
+Each snapshot is served at the root of its own content origin, separate from Registry management
+and from other snapshots. A stable Release/scope entry selects the current snapshot; navigation and
+assets within that site continue to use that snapshot. This prevents mixed-version assets and
+separates script, browser storage, and Service Worker authority. Separate URL directories on one
+origin do not satisfy this boundary.
+
+Content origins do not expose publication APIs or receive Registry publication credentials or
+shared authentication cookies. Registry controls response headers and MIME handling; uploaded
+files cannot supply server headers or override host routing. Registry UI must not execute author
+content within its management origin, and links to hosted sites sever opener access.
+
+The serving topology must support root-relative static assets without rewriting the author's build.
+When an author needs an absolute hostname during a build, tooling may reserve an opaque snapshot
+address before computing the final content digest. An address can never be rebound to different
+bytes. Concrete domain, DNS, TLS, and storage deployment choices remain Registry-owned.
+
+## Release Lifecycle
+
+Documentation may be prepared alongside a preparing Release, but preparing content is not public.
+Published Releases expose their documentation normally. Yanked Releases retain exact-version
+documentation, and Registry entry surfaces identify that withdrawal; documentation corrections do
+not restore the Release's recommendation or installability.
+
+Blocked Releases expose neither discovery, stable entries, nor current or historical snapshot
+files. Publishers cannot bypass a block by correcting documentation. Lifecycle checks apply before
+cache revalidation, and private object storage must not offer an unguarded public bypass.
+
+These rules govern new network responses, not copies already downloaded by a reader or stored by
+an author's Service Worker. Hosting does not promise remote deletion of offline content. First-party
+templates do not enable offline Service Workers.