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

.github/workflows/pages-preview.yml

@@ -83,8 +83,33 @@ jobs:
     timeout-minutes: 15
     environment:
       name: preview
-      url: ${{ steps.pages.outputs.pages-deployment-alias-url }}
+      deployment: false
     steps:
+      - name: Create the exact pull-request deployment
+        id: deployment
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }}
+        with:
+          script: |
+            const { data: deployment } = await github.rest.repos.createDeployment({
+              ...context.repo,
+              ref: process.env.PREVIEW_HEAD_SHA,
+              environment: 'preview',
+              auto_merge: false,
+              required_contexts: [],
+              transient_environment: true,
+              production_environment: false,
+              description: 'Cloudflare Pages pull-request preview',
+            })
+            core.setOutput('deployment_id', String(deployment.id))
+            await github.rest.repos.createDeploymentStatus({
+              ...context.repo,
+              deployment_id: deployment.id,
+              state: 'in_progress',
+              log_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            })
+
       - name: Mark the pull-request preview pending
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
@@ -159,6 +184,24 @@ jobs:
           CLOUDFLARE_PAGES_DEPLOYMENT_URL: ${{ steps.pages.outputs.pages-deployment-alias-url }}
           INKCRE_PAGES_SMOKE_MODE: preview
 
+      - name: Report the exact pull-request deployment
+        if: ${{ always() && steps.deployment.outputs.deployment_id != '' }}
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          DEPLOYMENT_ID: ${{ steps.deployment.outputs.deployment_id }}
+          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.createDeploymentStatus({
+              ...context.repo,
+              deployment_id: Number(process.env.DEPLOYMENT_ID),
+              state: succeeded ? 'success' : 'failure',
+              log_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+              ...(process.env.PREVIEW_URL ? { environment_url: process.env.PREVIEW_URL } : {}),
+            })
+
       - name: Report the preview result on the pull-request commit
         if: ${{ always() }}
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0

10-prd/_drivers/business-and-service-objectives.md

@@ -1,6 +1,6 @@
 # Business And Service Objectives
 
-- business objective: provide one product that can collect information, organize it into a reusable base, and expose ways to use it later.
+- business objective: help people put information to use by collecting it so people and connected tools can find and use it, and by improving collected information when that helps.
 - service objective: keep collection, info-base authority, organization, and application responsibilities distinct even when one service implements multiple parts.
 - service objective: allow extensions to add capability without forking core ownership boundaries.
-- success rationale: reusable information should remain available across runtimes and downstream workflows instead of being trapped in collection-specific flows.
+- success rationale: value is realized when people or connected tools can find and use collected information; it should remain available across runtimes and downstream workflows instead of being trapped in collection-specific flows.

10-prd/_drivers/market-and-user-pressures.md

@@ -1,7 +1,7 @@
 # Market And User Pressures
 
-- market pressure: information captured in external systems loses value when it cannot be collected and reused in one durable base.
+- market pressure: information saved across external systems loses value when people cannot find or use it again when needed.
 - user pressure: people need information to be gathered automatically instead of relying on repeated manual copy or one-off retrieval.
 - user pressure: once collected, information must remain reusable for later retrieval, indexing, and downstream use.
 - user pressure: thoughts and small pieces of surrounding information should be capturable from familiar memo clients with little friction, wherever the person happens to be.
-- urgency and tradeoff: the product optimizes for reusable information memory rather than source-specific ad hoc extraction.
+- urgency and tradeoff: the product optimizes for putting collected information to use rather than treating capture, storage, or source-specific extraction as the outcome.

10-prd/_drivers/operational-realities.md

@@ -4,4 +4,4 @@
 - runtime reality: a block may carry inline content or an opaque pointer to actual bytes stored elsewhere.
 - existing system limitation: storage-backed content access may be deferred, so consumers need one hydration contract rather than interpreting block pointers directly.
 - runtime reality: collection may be a tracked pull run, an event-driven record, or an extension-owned protocol request; only run-oriented collection requires a Job lifecycle.
-- product boundary: an InKCre deployment is one owner context. Runtime clients are peer nodes, while users or accounts named by an external protocol remain protocol-bound projections rather than InKCre tenants.
+- product boundary: an InKCre deployment is one owner context. Runtime participants are Peer nodes, while users or accounts named by an external protocol remain protocol-bound projections rather than InKCre tenants.

10-prd/glossary.md

@@ -52,12 +52,12 @@
 
 - canonical business meaning: a user-facing application through which a person interacts with InKCre or a compatible product protocol.
 - user-visible or business lifecycle language: the app or interface a person uses.
-- notes on ambiguity with framework terms: technical architecture uses `peer` for runtime nodes; product, marketing, landing, and other non-technical material may continue to say client where that is what a person experiences.
+- notes on ambiguity with framework terms: use `client` only for an actual application or a protocol-native client role; it is not a product-facing synonym for an InKCre runtime Peer.
 
 ## peer
 
 - canonical business meaning: one running node that participates in a deployment around the shared info-base and may provide or consume capabilities.
-- user-visible or business lifecycle language: normally hidden behind the product's clients and deployment.
+- user-visible or business lifecycle language: the named runtime shown when a person manages where InKCre capabilities run.
 - notes on ambiguity with framework terms: peer equality describes shared authority and participation, not identical execution ability; one interaction may still have caller/provider or client/server roles.
 
 ## job

20-product-tdd/peer-database-runtime-contract.md

@@ -62,6 +62,19 @@ reset must converge to the same result.
 checked-in identifiers and is not a production-data source. Artifact-owned catalogs are
 reconciled independently from development seed.
 
+## Peer Runtime Identity
+
+One Peer row keeps its stable identity and Human-owned display name separately from facts published
+by the running application. `application_version` is the exact release version of the application
+currently running that Peer. It is not a browser version, Peer protocol version, or Extension Host
+SDK compatibility version.
+
+The application writes `application_version` when it registers and refreshes it after an upgrade.
+Registration may also refresh other runtime-owned facts such as the configuration schema, but it
+must not overwrite a display name that a person changed. Historical rows may have no application
+version; consumers keep them usable and present the version as unknown until that Peer registers
+again.
+
 `reset-dev` requires both an explicit destructive confirmation and a database-owned
 development identity. It refuses production, preview, and unknown databases.
 

20-product-tdd/semantic-retrieval-and-peer-capabilities.md

@@ -97,9 +97,9 @@ business facade
 - Runtime Peers are equal participants around shared database authority but may implement
   different executable capabilities. Caller/provider or client/server describes one
   interaction edge, not a fixed deployment hierarchy.
-- One Peer row owns a validated full capability-advertisement snapshot and one lease expiry.
-  Each advertisement contains an exact capability ID plus an inbound interface whose exact
-  protocol ID owns its parameter schema.
+- One Peer row owns its runtime application version, a validated full
+  capability-advertisement snapshot, and one lease expiry. Each advertisement contains an exact
+  capability ID plus an inbound interface whose exact protocol ID owns its parameter schema.
 - Discovery exposes support and Peer liveness. Readiness is internal to the business service
   and never becomes advertisement metadata. Lease evaluation uses database time; the lease
   owner chooses its TTL because always-on and scale-to-zero deployments differ.

20-product-tdd/system-state-and-authority.md

@@ -65,6 +65,8 @@ Record durable ownership of authoritative state across units and distinguish it
 
 - One InKCre deployment is one owner context; the product does not currently define tenants,
   terminal users, or per-row user ownership.
-- Technical runtime participants are Peers. User-facing applications may still be called
-  clients. Identities named by an external source or compatibility protocol
-  keep their native boundary meaning and must not silently become shared-system principals.
+- Technical runtime participants are Peers and are presented as Peers wherever a person manages
+  their identity, configuration, liveness, or capabilities. `Client` remains valid only for an
+  actual application or protocol-native role. Identities named by an external source or
+  compatibility protocol keep their native boundary meaning and must not silently become
+  shared-system principals.

website/.vitepress/config.mts

@@ -2,7 +2,7 @@ import { defineConfig, type HeadConfig } from 'vitepress'
 import { canonicalOrigin, defaultLanguage } from '../scripts/site-contract.mjs'
 
 const description =
-  'Public documentation for InKCre, an actively developed system for reusable information.'
+  'InKCre collects information from the tools you use so you can find it and put it to use.'
 
 export default defineConfig({
   srcDir: 'content',
@@ -48,6 +48,7 @@ export default defineConfig({
     )
   },
   themeConfig: {
+    logo: '/images/inkcre-mark.svg',
     nav: [
       { text: 'Getting Started', link: '/getting-started' },
       { text: 'Developer', link: '/developer/' },
@@ -56,47 +57,64 @@ export default defineConfig({
     ],
     sidebar: {
       '/': [
-        { text: 'Getting Started', link: '/getting-started' },
         {
           text: 'User Guide',
           items: [
-            { text: 'Connect to Your Instance', link: '/guide/connect' },
-            { text: 'CLI / Agent Connection', link: '/guide/connect-cli' },
-            { text: 'Prepare an Extension', link: '/guide/extensions' },
-            { text: 'Collect Your First Source', link: '/guide/first-source' },
-            { text: 'Find What You Saved', link: '/guide/search' },
-            { text: 'Schedule Collection and Indexing', link: '/guide/schedules' },
             {
-              text: 'Connect More Sources',
-              link: '/guide/sources',
+              text: 'Getting Started',
+              link: '/getting-started',
               items: [
-                { text: 'RSS and Atom', link: '/guide/sources/rss' },
-                { text: 'GitHub Stars and Lists', link: '/guide/sources/github' },
-                { text: 'Email over IMAP', link: '/guide/sources/mail' },
-                { text: 'Telegram Inbox', link: '/guide/sources/telegram' },
-                { text: 'Twitter / X Bookmarks', link: '/guide/sources/twitter' },
-                { text: 'Memos-Compatible Capture', link: '/guide/sources/memos' },
+                { text: 'Connect the Web App', link: '/guide/connect' },
+                { text: 'Choose Your First Source', link: '/guide/first-source' },
+                { text: 'Prepare an Extension', link: '/guide/extensions' },
                 { text: 'Run a Collection', link: '/guide/collect' },
+                { text: 'Find What You Saved', link: '/guide/search' },
               ],
             },
             {
-              text: 'Use Your Information',
+              text: 'Collection',
+              link: '/guide/sources',
+              items: [
+                {
+                  text: 'Connect More Sources',
+                  link: '/guide/sources',
+                  items: [
+                    { text: 'RSS and Atom', link: '/guide/sources/rss' },
+                    { text: 'GitHub Stars and Lists', link: '/guide/sources/github' },
+                    { text: 'Email over IMAP', link: '/guide/sources/mail' },
+                    { text: 'Telegram Inbox', link: '/guide/sources/telegram' },
+                    { text: 'Twitter / X Bookmarks', link: '/guide/sources/twitter' },
+                    { text: 'Memos-Compatible Capture', link: '/guide/sources/memos' },
+                  ],
+                },
+                { text: 'Schedule Collection', link: '/guide/schedules' },
+              ],
+            },
+            {
+              text: 'Organization',
+              items: [{ text: 'Organize Your Information', link: '/guide/organization' }],
+            },
+            {
+              text: 'Application / Use',
               link: '/guide/daily-use',
-              items: [{ text: 'Sinks: ChatGPT via MCP', link: '/guide/sinks/chatgpt' }],
+              items: [
+                { text: 'Browse and Use Your Information', link: '/guide/daily-use' },
+                { text: 'CLI / Agent Connection', link: '/guide/connect-cli' },
+                { text: 'ChatGPT via MCP', link: '/guide/sinks/chatgpt' },
+              ],
+            },
+            {
+              text: 'Self-Hosted',
+              link: '/self-hosted/',
+              items: [
+                { text: 'Render and Neon', link: '/self-hosted/render-neon' },
+                { text: 'Heroku and Neon', link: '/self-hosted/heroku-neon' },
+                { text: 'Custom Self-Hosting', link: '/self-hosted/custom' },
+              ],
             },
             { text: 'Troubleshooting', link: '/guide/troubleshooting' },
           ],
         },
-        {
-          text: 'Self-Hosted',
-          items: [
-            { text: 'Overview', link: '/self-hosted/' },
-            { text: 'Getting Started', link: '/self-hosted/getting-started' },
-            { text: 'Render and Neon', link: '/self-hosted/render-neon' },
-            { text: 'Heroku and Neon', link: '/self-hosted/heroku-neon' },
-            { text: 'Advanced', link: '/self-hosted/advanced' },
-          ],
-        },
       ],
       '/developer/': [
         {