@c4a/context 0.7.12 → 0.7.14-beta.1

package/README.md

@@ -116,6 +116,7 @@ a source alone does not start indexing.
 - [Project API](./docs/reference/project-api.md)
 - [Indexer Provider Protocol](./docs/reference/indexer-provider-protocol.md)
 - [Package Outputs](./docs/guides/package-outputs.md)
+- [Page content customization](./docs/guides/page-customization.md) — homepage slots, custom pages and floating chat widgets.
 - [Package Templates](./docs/reference/package-templates.md)
 
 - [Update existing knowledge](./docs/guides/knowledge-updates.md)

package/README.zh-CN.md

@@ -107,6 +107,7 @@ knowledge/architecture/product-guides/component-input-fields.md
 - [项目 API](./docs/reference/project-api.md)
 - [Indexer Provider 协议](./docs/reference/indexer-provider-protocol.md)
 - [知识包输出](./docs/guides/package-outputs.md)
+- [页面内容定制](./docs/guides/page-customization.md)：首页插槽、自定义页面与浮动聊天组件。
 - [知识包模板](./docs/reference/package-templates.md)
 
 - [更新已有知识](./docs/guides/knowledge-updates.md)

package/docs/README.md

@@ -22,6 +22,7 @@ preload the whole manual set.
 
 | Current need | Read |
 |---|---|
+| Customize website pages, homepage slots or a floating chat widget | [Page Content Customization](./guides/page-customization.md) |
 | Understand the whole knowledge-project shape | [Getting Started](./getting-started.md) |
 | Know what the Agent may decide or change | [Agent Guide](./guides/agent-guide.md) and [Agent Dialogue](./guides/agent-dialogue.md) |
 | Configure sources, capture, Indexers, or packages | [Project API](./reference/project-api.md) |

package/docs/README.zh-CN.md

@@ -26,6 +26,7 @@
 | 选择代码提取方式 | [Code Extractor Selection](./reference/code-extractors.md) |
 | 选择 Agent 知识包或 LLM 文档 | [Package Outputs](./guides/package-outputs.md) |
 | 自定义包文件和索引 | [Package Templates](./reference/package-templates.md) 和 [Template Variables](./reference/template-variables.md) |
+| 定制网站页面、首页区域和右下角聊天浮层 | [页面内容定制](./guides/page-customization.md) |
 | 保留飞书图片和内嵌资源 | [Lark Resource Materialization](./guides/lark-resources.md) |
 
 默认提供 Code、Markdown、Note、Sessions 四类 Indexer。安装和技能开关由 Host 管理；

package/docs/guides/knowledge-updates.md

@@ -101,12 +101,11 @@ configuration/template approval, before the final build. The record response
 returns the next workspace Route, so no extra status call is needed. Build retries
 reuse the recorded version when formal content is unchanged. If build preparation
 or rendering fails and formal corrections are needed, `version inspect` returns
-`reusable_version` for the current entry only while it has no successful build or
-publication receipt. Submit that same version with the complete iteration's title,
-changes and triggers, including the repair; this replaces the pending changelog
-entry rather than appending another version. Do not submit only the repair and
-lose the original delivery description. Once built or published, the version is
-sealed and further formal changes require an increase. Intermediate batches
+`reusable_version` for an untagged current entry. Before amending, read the
+publication target's remote version using the distribution skill. An unpublished
+preview may reuse its version with the complete iteration's title, changes and
+triggers; preserve the original delivery description. Published content requires
+an increasing version. A local build alone does not seal a version. Intermediate batches
 do not each receive a version.
 
 The workspace AGENTS.md and version-writing instructions require each entry's
@@ -143,19 +142,23 @@ are `initial`, `note`, `sessions`, `mr`, `module`, `document`, `navigation`,
 `repair`, `dist`, and `other`. Agent-written fields describe the actual diff and
 conversation; they must not expose credentials, raw transcripts or private IDs.
 
-The CLI writes `changelog.yaml`, generated `CHANGELOG.md`, `package.json` and the
-`.context-version.json` content baseline together. Keep these formal files with
-the workspace; do not hand-edit generated baselines. Git-managed and unignored
-new files are compared (without Git, non-runtime workspace files are compared).
-Version metadata itself, `dist`, `.tmp` and dependencies do not cause changes.
-
-Successful builds record version and per-package hashes in `.context-builds.json`.
-They do not increase versions. Before publishing, `context version publish-check
---format json` compares against `.context-published.json`. A same-version changed
-output requires a patch using `version inspect --publish` and a `dist` trigger,
-then a rebuild. Record `version published --hash <checked-hash> --receipt
-<successful-publication-reference> --format json` only after external success.
-No command commits, tags or uploads automatically.
+The CLI updates `package.json`, `changelog.yaml` and generated `CHANGELOG.md` together.
+`context version inspect --base <commit-or-tag> --format json` compares the actual
+workspace files with Git, including untracked files. Without an explicit base it
+uses the current version's `v<version>` tag when available, otherwise HEAD; HEAD
+is not proof of publication. Review article bodies, assets, structure, navigation
+and templates, not structure alone. Without Git, inspection reports local files.
+A disposable `.tmp` checkpoint suppresses repeated recording in an uncommitted
+iteration. Losing it does not lose knowledge or prove a new publication.
+
+There are no root-level Context version/build/publication receipts to maintain.
+Build freshness uses the existing local package cache. The CLI does not seal a
+version merely because a preview was built. Before reusing a version, check the
+actual publication target and Git tags; a published version requires an increase.
+Publication belongs to the installed distribution tool. Record remote receipts
+in its configuration or the existing work summary, separately for each target.
+A successful authorized commit/tag identifies the delivered source; never create
+one automatically, and never treat Git success as platform publication success.
 
 Website history is available at `changelog.html`: cards are newest first, the
 latest three expanded and older cards collapsed. The History button beside the
@@ -191,6 +194,66 @@ coverage by mechanically placing every new page under an unrelated catch-all.
 Build reports missing bindings for the Agent to resolve; it does not classify
 content. Moving a menu entry does not change the article URL.
 
+### Reader tasks, names and reading order
+
+Read the affected articles' bodies before changing their categories or titles.
+Titles and outlines help locate material; they do not settle its main reader task.
+During initial planning, keep names and placement provisional until the relevant
+material supports them. Classify by the question the page primarily answers and
+its intended reader, rather than its collection, source path or isolated words:
+
+| Main reader task | Organizing emphasis |
+| --- | --- |
+| Understand a business process | Participants, rules, decisions and lifecycle |
+| Understand an implementation | Components, data changes, calls and failure handling |
+| Integrate or use a capability | Prerequisites, setup, contracts and usage |
+| Diagnose or recover from a problem | Symptoms, checks, causes, actions and verification |
+
+These distinctions guide placement, not a required set of top-level directories.
+A page explaining retry scheduling and persistence belongs with its implementation;
+a page explaining how to recover a stalled worker serves troubleshooting. The word
+"retry" alone decides neither. Choose a primary home for a mixed page and link
+related tasks without duplicating the same overview across categories.
+
+Give each directory a concrete shared subject or reader task. At every parent,
+keep its children either all directories or all articles. Place an overview in
+the appropriate article group when the parent contains directories. Avoid empty
+category scaffolding and chains of single-article directories that add no useful
+choice. A residual "Other" group, when warranted, comes last; it must not absorb
+articles whose purpose fits an existing group. Do not invent a fixed depth,
+number of categories or page quota to make the tree look uniform.
+
+Keep directory and article titles concise and specific to their actual subject.
+Name the object and useful task, rather than enumerating every section heading.
+For example, prefer "Client authentication" to "Client tokens, configuration,
+requests, refresh and errors" when those sections all explain authentication.
+Retain a platform or product name only when it distinguishes otherwise ambiguous
+topics. Keep an existing accurate title when it already works; a necessary
+technical name need not be shortened just to meet a word count.
+
+The Agent manually arranges siblings for reading: a useful overview, prerequisites,
+the main tasks or process sequence, then later maintenance and reference material
+where applicable. Use a numbered list or ordered outline to review that proposal,
+then assign explicit, distinct `order` values among siblings in the knowledge-map
+adjustment, for example 10, 20 and 30. The list is an editing plan; persisted
+`order` values determine navigation. Reordering YAML/JSON entries or changing the
+plan's list order alone does not change the site. Paths, internal keys, alphabetical
+order and source-file order are not substitutes for a reader sequence. Keep order
+numbers out of titles. This navigation order is separate from the order in which
+workers write their drafts.
+
+For a long or compound page, inspect its content before suggesting a split or
+merge. Keep one coherent task together, and separate independently useful tasks
+only when their supported content warrants it. A long title or many headings
+alone is insufficient. Preserve useful detail and links, and retain article IDs,
+paths and unaffected sections when the reader task is unchanged. A navigation-only
+change does not require a prose rewrite or file migration; changing its label does
+not silently rename the approved article. Needed title or content revisions use
+the existing revision and Review flow. Splits and merges use ordinary article
+tasks, link repair and any explicit retirement after replacement content is
+delivered. These are Agent editorial decisions, not new CLI checks or approval
+gates.
+
 ## Edit one section or review part of a batch
 
 The current approved-revision Route accepts either full `markdown` or explicit

package/docs/guides/package-outputs.md

@@ -25,6 +25,10 @@ change that silently enables websites for existing packages.
 
 ### Static documentation website
 
+For business pages, homepage slots and a bottom-right chat/bot widget, read
+[Page Content Customization](./page-customization.md). Presentation sources live
+under `src/site/`; keep generated knowledge separate.
+
 To include the default browser-readable site, enable `site` on the same
 package. The normal `context build` produces both the Agent KB and a standalone
 `dist/<base>-site/` directory containing `index.html`, article HTML,
@@ -476,3 +480,24 @@ Only approved selected content is exported. A map or article change invalidates
 both website and LLMS outputs; failure preserves the previous staged package.
 Standalone `llmsPackage()` uses the same map organization and supplies the full
 text and raw article files alongside its template-rendered `llms.txt` index.
+
+## Links to a deployed website
+
+After a website has been built and deployed, record its complete public root:
+
+```bash
+context package site-url <package-name> https://example.com/docs/
+```
+
+This command adds optional `site_url` to the existing `context.site-output/v1`
+map, in both the website and knowledge package. It normalizes a trailing slash,
+rejects credentials/query/fragment, and never contacts the URL. The address
+includes the deployment subpath; resolve `pages[].site_path` against it without
+adding `base` again. Rebuilds preserve the address from the previous website
+map and distribute the refreshed mapping with the package. Deleting dist also
+deletes this optional delivery metadata: record it again from the deployment
+result instead of guessing a hostname. No new workspace configuration is needed.
+
+The address is an access hint, not proof of publication or content freshness.
+Query Skills use it only to append related links in the final summary, with no
+network probes or version checks. Packages without the map work as before.

package/docs/guides/page-customization.md

@@ -0,0 +1,87 @@
+# Page content customization
+
+Keep trusted website code in `src/site/`. It is presentation code, not captured
+material or approved knowledge. Configure it in the existing `kbPackage.site`:
+
+```ts
+site: {
+  title: "Engineering handbook",
+  extensions: {
+    root: "src/site",
+    slots: {
+      banner: "components/Banner.vue",
+      floating: "components/Chat.vue",
+    },
+    pages: { support: "pages/support.md" },
+  },
+}
+```
+
+Paths are relative to `root`. The directory can contain Vue components, CSS,
+Markdown and imported assets. Use relative imports within this directory;
+declare external dependencies in the workspace package manifest. Do not put
+credentials or private configuration in frontend files. Hidden files,
+`node_modules` and `dist` are not copied; symlinks are rejected.
+
+## Homepage and floating slots
+
+| Slot | Default | Customization |
+| --- | --- | --- |
+| `banner` | Existing homepage hero and actions | Replace with a component |
+| `knowledge` | Knowledge-map card group | Replace with a component |
+| `resources` | Resource card group | Replace with a component |
+| `footer` | Existing homepage footer | Replace with a component |
+| `floating` | Empty | Client-only component fixed at the bottom right on all pages |
+
+Omit a slot to retain its default; set it to `false` to hide it. A component
+replaces only its slot, not the global navigation, language switch or article
+provenance. Components can use VitePress `useData()` and `useRoute()` for theme,
+page and route information. Import scoped CSS from components for local styling.
+
+The floating component owns its button, chat/bot panel and open/close behavior.
+Keep its panel within the viewport and preserve keyboard focus and close controls.
+Load expensive chat SDKs when opened. Its component import is client-only, but
+other components must support static rendering: use `onMounted` for browser APIs.
+The static website supplies no chat backend or secret storage; use an authorized
+business service for authentication and requests. A service failure must not
+prevent reading the handbook.
+
+## Custom pages and navigation
+
+Each `pages` key becomes `/custom/<key>.html` under the configured site base.
+A page is trusted Markdown and may import Vue components, for example:
+
+```md
+# Support
+
+<script setup>
+import SupportPanel from '../components/SupportPanel.vue'
+</script>
+
+<SupportPanel />
+```
+
+Place it using the existing knowledge-map entry structure, with
+`target: { artifact_ref: "site:support" }`. Set `parent`, `title` and `order`
+as for other directory entries; do not create a second menu configuration.
+The `site:` namespace is reserved for website pages; do not use `section_key`
+on these targets. Undeclared targets fail website building with a diagnostic.
+Pages without directory entries remain directly accessible. Multiple entries
+can reference one page without duplicating content.
+
+These pages are website-only: they are not approved articles and do not enter
+the knowledge package or LLM Docs. Update formal articles through the existing
+knowledge revision workflow, not through a custom page that shadows their URLs.
+
+## Build and delivery
+
+Use the existing package build after editing configuration or presentation files;
+site customization does not require capture, Indexer planning or a new review
+gate. Existing authorization for building and deployment still applies.
+Extension files and workspace dependency manifests participate in build
+fingerprints. Build errors preserve previous outputs. Never edit the generated
+`.tmp` website or `dist` as the source of customization.
+
+Preview the homepage, custom pages and floating panel on desktop and mobile,
+including a non-root `site.base`, dark mode and keyboard navigation. Publish only
+the resulting website directory, not the source tree or workspace credentials.

package/docs/reference/project-api.md

@@ -187,6 +187,12 @@ or repository links. Knowledge map is projected from
 `src/knowledge-map.yaml` independently of KB directories; see
 [Package Outputs](../guides/package-outputs.md#optional-static-documentation-website).
 
+`site.extensions` optionally names a trusted `src/site` root, homepage and floating
+`slots`, and custom Markdown `pages`. Place custom pages in the same knowledge map
+with `target.artifact_ref: "site:<page-key>"`. See
+[Page content customization](../guides/page-customization.md) for the configuration
+and the boundary between presentation code and approved knowledge.
+
 ## Knowledge requirements and Indexer Skills
 
 When `src/indexers.yaml` is absent, the configuration Route supplies its schema.

package/index.js

@@ -10917,7 +10917,18 @@ var packageSiteSchema = exports_external.object({
   description: exports_external.string().optional(),
   lang: exports_external.string().min(1).default("en-US"),
   base: exports_external.string().regex(/^\/(?:[a-zA-Z0-9_-]+\/)*$/, "Use / or a slash-delimited deployment path, such as /docs/").default("/"),
-  home: packageSiteHomeSchema.optional()
+  home: packageSiteHomeSchema.optional(),
+  extensions: exports_external.object({
+    root: exports_external.string().regex(/^src\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]+$/).default("src/site"),
+    slots: exports_external.object({
+      banner: exports_external.union([exports_external.string().min(1), exports_external.literal(false)]).optional(),
+      knowledge: exports_external.union([exports_external.string().min(1), exports_external.literal(false)]).optional(),
+      resources: exports_external.union([exports_external.string().min(1), exports_external.literal(false)]).optional(),
+      footer: exports_external.union([exports_external.string().min(1), exports_external.literal(false)]).optional(),
+      floating: exports_external.union([exports_external.string().min(1), exports_external.literal(false)]).optional()
+    }).strict().optional(),
+    pages: exports_external.record(exports_external.string().regex(/^[a-zA-Z0-9_-]+$/), exports_external.string().min(1)).optional()
+  }).strict().optional()
 }).strict();
 function normalizePackageSite(value) {
   return value === undefined ? undefined : packageSiteSchema.parse(value);

package/indexerToolSnapshot.d.ts

@@ -132,12 +132,6 @@ export declare const indexerToolSnapshotSchema: z.ZodEffects<z.ZodObject<{
     }>;
     snapshot_digest: z.ZodString;
 }, "strict", z.ZodTypeAny, {
-    source: {
-        source_ref: string;
-        module_ref: string | null;
-        input_digest: string;
-    };
-    protocol: "context.indexer.tool-snapshot/v1";
     pages: {
         page_ref: string;
         cursor_in: string | null;
@@ -145,6 +139,12 @@ export declare const indexerToolSnapshotSchema: z.ZodEffects<z.ZodObject<{
         item_count: number;
         response_digest: string;
     }[];
+    source: {
+        source_ref: string;
+        module_ref: string | null;
+        input_digest: string;
+    };
+    protocol: "context.indexer.tool-snapshot/v1";
     location: {
         site: string;
         region: string | null;
@@ -177,12 +177,6 @@ export declare const indexerToolSnapshotSchema: z.ZodEffects<z.ZodObject<{
     };
     snapshot_digest: string;
 }, {
-    source: {
-        source_ref: string;
-        module_ref: string | null;
-        input_digest: string;
-    };
-    protocol: "context.indexer.tool-snapshot/v1";
     pages: {
         page_ref: string;
         cursor_in: string | null;
@@ -190,6 +184,12 @@ export declare const indexerToolSnapshotSchema: z.ZodEffects<z.ZodObject<{
         item_count: number;
         response_digest: string;
     }[];
+    source: {
+        source_ref: string;
+        module_ref: string | null;
+        input_digest: string;
+    };
+    protocol: "context.indexer.tool-snapshot/v1";
     location: {
         site: string;
         region: string | null;
@@ -222,12 +222,6 @@ export declare const indexerToolSnapshotSchema: z.ZodEffects<z.ZodObject<{
     };
     snapshot_digest: string;
 }>, {
-    source: {
-        source_ref: string;
-        module_ref: string | null;
-        input_digest: string;
-    };
-    protocol: "context.indexer.tool-snapshot/v1";
     pages: {
         page_ref: string;
         cursor_in: string | null;
@@ -235,6 +229,12 @@ export declare const indexerToolSnapshotSchema: z.ZodEffects<z.ZodObject<{
         item_count: number;
         response_digest: string;
     }[];
+    source: {
+        source_ref: string;
+        module_ref: string | null;
+        input_digest: string;
+    };
+    protocol: "context.indexer.tool-snapshot/v1";
     location: {
         site: string;
         region: string | null;
@@ -267,12 +267,6 @@ export declare const indexerToolSnapshotSchema: z.ZodEffects<z.ZodObject<{
     };
     snapshot_digest: string;
 }, {
-    source: {
-        source_ref: string;
-        module_ref: string | null;
-        input_digest: string;
-    };
-    protocol: "context.indexer.tool-snapshot/v1";
     pages: {
         page_ref: string;
         cursor_in: string | null;
@@ -280,6 +274,12 @@ export declare const indexerToolSnapshotSchema: z.ZodEffects<z.ZodObject<{
         item_count: number;
         response_digest: string;
     }[];
+    source: {
+        source_ref: string;
+        module_ref: string | null;
+        input_digest: string;
+    };
+    protocol: "context.indexer.tool-snapshot/v1";
     location: {
         site: string;
         region: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.7.12",
+  "version": "0.7.14-beta.1",
   "type": "module",
   "description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
   "license": "MIT",

package/packageSite.d.ts

@@ -93,6 +93,50 @@ export declare const packageSiteSchema: z.ZodObject<{
             featured?: boolean | undefined;
         }[] | undefined;
     }>>;
+    /** Trusted presentation code, relative to the workspace; never captured knowledge. */
+    extensions: z.ZodOptional<z.ZodObject<{
+        root: z.ZodDefault<z.ZodString>;
+        slots: z.ZodOptional<z.ZodObject<{
+            banner: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<false>]>>;
+            knowledge: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<false>]>>;
+            resources: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<false>]>>;
+            footer: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<false>]>>;
+            floating: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<false>]>>;
+        }, "strict", z.ZodTypeAny, {
+            resources?: string | false | undefined;
+            banner?: string | false | undefined;
+            knowledge?: string | false | undefined;
+            footer?: string | false | undefined;
+            floating?: string | false | undefined;
+        }, {
+            resources?: string | false | undefined;
+            banner?: string | false | undefined;
+            knowledge?: string | false | undefined;
+            footer?: string | false | undefined;
+            floating?: string | false | undefined;
+        }>>;
+        pages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        root: string;
+        slots?: {
+            resources?: string | false | undefined;
+            banner?: string | false | undefined;
+            knowledge?: string | false | undefined;
+            footer?: string | false | undefined;
+            floating?: string | false | undefined;
+        } | undefined;
+        pages?: Record<string, string> | undefined;
+    }, {
+        root?: string | undefined;
+        slots?: {
+            resources?: string | false | undefined;
+            banner?: string | false | undefined;
+            knowledge?: string | false | undefined;
+            footer?: string | false | undefined;
+            floating?: string | false | undefined;
+        } | undefined;
+        pages?: Record<string, string> | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     lang: string;
     base: string;
@@ -116,6 +160,17 @@ export declare const packageSiteSchema: z.ZodObject<{
             featured?: boolean | undefined;
         }[] | undefined;
     } | undefined;
+    extensions?: {
+        root: string;
+        slots?: {
+            resources?: string | false | undefined;
+            banner?: string | false | undefined;
+            knowledge?: string | false | undefined;
+            footer?: string | false | undefined;
+            floating?: string | false | undefined;
+        } | undefined;
+        pages?: Record<string, string> | undefined;
+    } | undefined;
 }, {
     title?: string | undefined;
     description?: string | undefined;
@@ -139,6 +194,17 @@ export declare const packageSiteSchema: z.ZodObject<{
             featured?: boolean | undefined;
         }[] | undefined;
     } | undefined;
+    extensions?: {
+        root?: string | undefined;
+        slots?: {
+            resources?: string | false | undefined;
+            banner?: string | false | undefined;
+            knowledge?: string | false | undefined;
+            footer?: string | false | undefined;
+            floating?: string | false | undefined;
+        } | undefined;
+        pages?: Record<string, string> | undefined;
+    } | undefined;
 }>;
 export type PackageSiteDefinition = z.input<typeof packageSiteSchema>;
 export declare function normalizePackageSite(value: PackageSiteDefinition | undefined): {
@@ -164,4 +230,15 @@ export declare function normalizePackageSite(value: PackageSiteDefinition | unde
             featured?: boolean | undefined;
         }[] | undefined;
     } | undefined;
+    extensions?: {
+        root: string;
+        slots?: {
+            resources?: string | false | undefined;
+            banner?: string | false | undefined;
+            knowledge?: string | false | undefined;
+            footer?: string | false | undefined;
+            floating?: string | false | undefined;
+        } | undefined;
+        pages?: Record<string, string> | undefined;
+    } | undefined;
 } | undefined;

package/templates/package-templates/kb/skills/knowledge-query/SKILL.md

@@ -133,3 +133,20 @@ Update the description, routing table, and package-boundary guidance to match
 the actual package. If the generic behavior is intentionally sufficient,
 explicitly accept the unchanged default during Context package-template review.
 --}}
+
+## Website links in the final summary
+
+After answering from the pages actually read, optionally append one or more
+related document links in the final summary. Read `context-site-map.json` from
+the selected package (or its sibling website output in a workspace). Match the
+read page to `pages[].package_path` or `approved_path`; use its `title` and resolve
+`site_path` relative to `site_url`. The URL already includes the deployment base
+path: do not prepend `base` again. Only cite matched articles, deduplicate links,
+and do not invent section anchors.
+
+This is a local formatting step, not retrieval or validation. Do not probe URLs,
+make HTTP/HEAD requests, open a browser, inspect a deployment platform, or check
+remote versions to add links. Never build, publish or update metadata for this
+purpose. If the map, URL or matching page is absent or malformed, keep the local
+citation and continue silently. A configured URL does not prove that the site
+contains the current local revision; do not claim online verification.

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/SKILL.md

@@ -97,3 +97,16 @@ node <当前 knowledge-query Skill 目录>/scripts/search.mjs --query '<关键
 
 这是可直接工作的通用查询 Skill。正式发布前，如果知识包存在专用术语、常见用户意图、推荐入口、已知边界或固定任务流程，作者应修改 description、路由表和包边界说明；如果通用行为已经足够，应在 Context 的包模板 Review 中明确接受未修改模板。
 --}}
+
+## 总结中的网站文档链接
+
+完成正文检索和回答后，仅在最终总结中按需附上一篇或多篇实际读取过的相关文档链接。
+从当前知识包读取 `context-site-map.json`，按命中文章的包内路径匹配
+`pages[].package_path`，使用 `title` 作链接文字，将 `site_path` 相对
+`site_url` 拼接。`site_url` 已包含站点子路径，不再重复拼接 `base`。
+同一文章只列一次，不凭标题推测页面地址或章节锚点。
+
+这是本地引用格式化，不是检索前置步骤：不要为地址发起 HTTP/HEAD 请求、打开浏览器、
+查询部署平台或远端版本，也不触发构建、发布或元数据修改。映射、地址或匹配项缺失、
+格式不正确时沿用本地引用即可，不阻塞回答，不要求用户补配置。
+记录的链接不证明线上内容与本地版本一致，不声称已验证网站。