@c4a/context-cli 0.7.12 → 0.7.14-beta.1

package/indexers/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "protocol": "context.indexer.cli-release-manifest/v1",
   "package": "@c4a/context-cli",
-  "version": "0.7.12",
+  "version": "0.7.14-beta.1",
   "issuer": "context4ai/context",
   "bundles": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.7.12",
+  "version": "0.7.14-beta.1",
   "type": "module",
   "description": "Local runtime and Agent integration for traceable knowledge production",
   "license": "MIT",
@@ -24,17 +24,17 @@
   },
   "dependencies": {
     "@c4a/agent-graph": "0.3.0",
-    "@c4a/context": "0.7.12",
-    "@c4a/extract": "0.7.12",
-    "@c4a/extract-contract": "0.7.12",
-    "@c4a/extract-go": "0.7.12",
-    "@c4a/extract-mdx": "0.7.12",
-    "@c4a/extract-proto": "0.7.12",
-    "@c4a/extract-rush": "0.7.12",
-    "@c4a/extract-sql": "0.7.12",
-    "@c4a/extract-style": "0.7.12",
-    "@c4a/extract-thrift": "0.7.12",
-    "@c4a/extract-ts": "0.7.12",
+    "@c4a/context": "0.7.14-beta.1",
+    "@c4a/extract": "0.7.14-beta.1",
+    "@c4a/extract-contract": "0.7.14-beta.1",
+    "@c4a/extract-go": "0.7.14-beta.1",
+    "@c4a/extract-mdx": "0.7.14-beta.1",
+    "@c4a/extract-proto": "0.7.14-beta.1",
+    "@c4a/extract-rush": "0.7.14-beta.1",
+    "@c4a/extract-sql": "0.7.14-beta.1",
+    "@c4a/extract-style": "0.7.14-beta.1",
+    "@c4a/extract-thrift": "0.7.14-beta.1",
+    "@c4a/extract-ts": "0.7.14-beta.1",
     "commander": "^11.0.0",
     "fast-xml-parser": "^5.10.1",
     "handlebars": "^4.7.8",

package/parserEntryWorker.js

@@ -4545,7 +4545,18 @@ var init_packageSite = __esm(() => {
     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();
 });
 

package/plugins/VERSION

@@ -1 +1 @@
-0.7.12
+0.7.14-beta.1

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
-  "version": "0.7.12",
+  "version": "0.7.14-beta.1",
   "author": {
     "name": "c4a"
   },

package/plugins/claude/commands/context-inspect-search.md

@@ -135,6 +135,24 @@ inferences and unavailable evidence. If source versions differ, describe the
 difference before deciding that a knowledge page is wrong. Do not dump runtime
 ids, long raw excerpts or a mandatory audit report into every answer.
 
+
+## 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.
+
 ## Suggest improvements and hand off
 
 When evidence supports a correction or worthwhile addition, briefly describe:

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "c4a",
-  "version": "0.7.12",
+  "version": "0.7.14-beta.1",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": { "name": "c4a" },
   "homepage": "https://github.com/context4ai/c4a",
@@ -10,7 +10,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.12",
+    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.14-beta.1",
     "longDescription": "Create a Context workspace and use agent-guided next steps to register sources, run extraction, review candidates, build package outputs, and verify health without silently mutating source repositories.",
     "developerName": "c4a",
     "category": "Productivity",

package/plugins/codex/skills/context-inspect-search/SKILL.md

@@ -135,6 +135,24 @@ inferences and unavailable evidence. If source versions differ, describe the
 difference before deciding that a knowledge page is wrong. Do not dump runtime
 ids, long raw excerpts or a mandatory audit report into every answer.
 
+
+## 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.
+
 ## Suggest improvements and hand off
 
 When evidence supports a correction or worthwhile addition, briefly describe:

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "displayName": "C4A Context",
-  "version": "0.7.12",
+  "version": "0.7.14-beta.1",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": {
     "name": "Context4AI",

package/plugins/cursor/commands/c4a-context-inspect-search.md

@@ -133,6 +133,24 @@ inferences and unavailable evidence. If source versions differ, describe the
 difference before deciding that a knowledge page is wrong. Do not dump runtime
 ids, long raw excerpts or a mandatory audit report into every answer.
 
+
+## 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.
+
 ## Suggest improvements and hand off
 
 When evidence supports a correction or worthwhile addition, briefly describe:

package/plugins/skills/context-inspect-search/SKILL.md

@@ -135,6 +135,24 @@ inferences and unavailable evidence. If source versions differ, describe the
 difference before deciding that a knowledge page is wrong. Do not dump runtime
 ids, long raw excerpts or a mandatory audit report into every answer.
 
+
+## 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.
+
 ## Suggest improvements and hand off
 
 When evidence supports a correction or worthwhile addition, briefly describe:

package/providers/context/graphs/workspace.yaml

@@ -135,7 +135,7 @@ nodes:
     reasonCode: route.capture.pending-target
     action: actions/capture-next.yaml
     satisfiedBy:
-      - path: capture.complete
+      - path: capture.route_satisfied
         equals: true
     resources:
       required:
@@ -224,6 +224,7 @@ nodes:
         - resources/views/package-current.yaml
       recommended:
         - resources/manuals/guides/package-outputs.md
+        - resources/manuals/guides/page-customization.md
         - resources/manuals/reference/package-templates.md
         - resources/manuals/reference/template-variables.md
 
@@ -241,6 +242,7 @@ nodes:
         - resources/views/package-current.yaml
       recommended:
         - resources/manuals/guides/package-outputs.md
+        - resources/manuals/guides/page-customization.md
         - resources/manuals/reference/project-api.md
         - resources/manuals/reference/package-templates.md
         - resources/manuals/reference/template-variables.md

package/providers/context/manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent-graph.bundle.v1",
   "provider": {
     "id": "c4a/context",
-    "version": "0.7.12"
+    "version": "0.7.14-beta.1"
   },
   "providerManifest": "provider.yaml",
   "graphs": [
@@ -14,7 +14,7 @@
     {
       "id": "workspace",
       "path": "graphs/workspace.yaml",
-      "digest": "sha256:43eba7c45070fc2fec9c1f86af8e6190c49ebef8b729cb444701011dca8780be"
+      "digest": "sha256:2904eb61889037ffdcdf878c807187f9acf807a9409111ee4de4c5b703b15d5d"
     }
   ],
   "actions": [
@@ -188,17 +188,22 @@
     {
       "id": "context.sdk.package-outputs",
       "path": "resources/manuals/guides/package-outputs.md",
-      "digest": "sha256:a8c66facc2ad175324796e2478d6ca50e0c83b5d49eec0251d8548c3717a062b"
+      "digest": "sha256:2238be400ef56fba3e894f58f246aa9bf16d287e6522782ad6cdf44ee7004e24"
     },
     {
       "id": "context.sdk.package-templates",
       "path": "resources/manuals/reference/package-templates.md",
       "digest": "sha256:8d512d232ea5157717eca73357a213ab2449d83cf98bec217621aff79eda0216"
     },
+    {
+      "id": "context.sdk.page-customization",
+      "path": "resources/manuals/guides/page-customization.md",
+      "digest": "sha256:57695bbbe3223c3c695029747856baae9e230059848e8f37506f908e843f9b0e"
+    },
     {
       "id": "context.sdk.project-api",
       "path": "resources/manuals/reference/project-api.md",
-      "digest": "sha256:6225dc08f1a4362eee72e0fba4d8639d20d535818766d8a6b181396ebbb94f3f"
+      "digest": "sha256:a65131d5cd351d8353f5028303ab1d75447f5d0c09496fd8ec83bb5d76adfd78"
     },
     {
       "id": "context.sdk.template-variables",
@@ -278,12 +283,12 @@
     {
       "id": "procedure.close-and-build",
       "path": "resources/procedures/close-and-build.md",
-      "digest": "sha256:c2f39abc2867e73a529ded2e475276738f62a4b61811b7792a49d6e358865a74"
+      "digest": "sha256:4025f98f95ac0c1818d2be3d6c33e556bd462b0510fd88227587d490ae01aa4c"
     },
     {
       "id": "procedure.document-capture",
       "path": "resources/procedures/document-capture.md",
-      "digest": "sha256:46a8231e92fcb19db7918938970ace8b4e4c22153fa8cbf0bb8100275bfbbfcf"
+      "digest": "sha256:f09100425c2b89a126c35c4490b0644519a4eee214114f2f0f52b6ea20467a04"
     },
     {
       "id": "procedure.homogeneous-source-review",
@@ -293,7 +298,7 @@
     {
       "id": "procedure.knowledge-maintenance",
       "path": "resources/procedures/knowledge-maintenance.md",
-      "digest": "sha256:42fc008c8b25df86b7a1e26d521003bc8e3a69cf16948365e93c41f896c0c315"
+      "digest": "sha256:f2cc36cb2425cf0ac96a2ea4f114ed5ce872c3711b82bdc25fdc71e42a2849b7"
     },
     {
       "id": "procedure.knowledge-review",
@@ -303,7 +308,7 @@
     {
       "id": "procedure.knowledge-updates",
       "path": "resources/procedures/knowledge-updates.md",
-      "digest": "sha256:f26726fc3264337200608e73f9ac20397016d6e3319ae8def6bf2a768630ae96"
+      "digest": "sha256:f43943fdf9265e5181c2e8cf3753d981fc9f59a44ee11b5beac404ec481344ea"
     },
     {
       "id": "procedure.note",
@@ -328,7 +333,7 @@
     {
       "id": "procedure.production-stage-files",
       "path": "resources/procedures/production-stage-files.md",
-      "digest": "sha256:c5ff9e138ecd3f90d04ac834a82b2764f583da105ca23e3e07dfb816349d6c32"
+      "digest": "sha256:d093acf81a07b85cfe2a78e71f7ab301fa8c72e3edac3f5de990b1ff7eaf12f0"
     },
     {
       "id": "procedure.project-configuration",
@@ -561,11 +566,11 @@
     },
     {
       "path": "graphs/workspace.yaml",
-      "digest": "sha256:43eba7c45070fc2fec9c1f86af8e6190c49ebef8b729cb444701011dca8780be"
+      "digest": "sha256:2904eb61889037ffdcdf878c807187f9acf807a9409111ee4de4c5b703b15d5d"
     },
     {
       "path": "provider.yaml",
-      "digest": "sha256:9916bad3dd3172994e821c3e8b9e28fedeb1f833edaa5182512f18f43901bd4e"
+      "digest": "sha256:820cc81bd72613211c7f1a48406bc881f6f4baf09ef415e635aa8da01aa08f0a"
     },
     {
       "path": "resources/contracts/indexer-provider-guide.yaml",
@@ -621,7 +626,7 @@
     },
     {
       "path": "resources/manuals/guides/knowledge-updates.md",
-      "digest": "sha256:18f9088eaab56ed92b5c131136de7f5527ece738a6bef3a605608d220f62ec28"
+      "digest": "sha256:fe8c9e4dbe7413bce3c2007bf230f1312fca31de69d434d0c41171a27e1a68f5"
     },
     {
       "path": "resources/manuals/guides/lark-resources.md",
@@ -637,7 +642,11 @@
     },
     {
       "path": "resources/manuals/guides/package-outputs.md",
-      "digest": "sha256:a8c66facc2ad175324796e2478d6ca50e0c83b5d49eec0251d8548c3717a062b"
+      "digest": "sha256:2238be400ef56fba3e894f58f246aa9bf16d287e6522782ad6cdf44ee7004e24"
+    },
+    {
+      "path": "resources/manuals/guides/page-customization.md",
+      "digest": "sha256:57695bbbe3223c3c695029747856baae9e230059848e8f37506f908e843f9b0e"
     },
     {
       "path": "resources/manuals/guides/sessions.md",
@@ -665,7 +674,7 @@
     },
     {
       "path": "resources/manuals/reference/project-api.md",
-      "digest": "sha256:6225dc08f1a4362eee72e0fba4d8639d20d535818766d8a6b181396ebbb94f3f"
+      "digest": "sha256:a65131d5cd351d8353f5028303ab1d75447f5d0c09496fd8ec83bb5d76adfd78"
     },
     {
       "path": "resources/manuals/reference/template-variables.md",
@@ -677,11 +686,11 @@
     },
     {
       "path": "resources/procedures/close-and-build.md",
-      "digest": "sha256:c2f39abc2867e73a529ded2e475276738f62a4b61811b7792a49d6e358865a74"
+      "digest": "sha256:4025f98f95ac0c1818d2be3d6c33e556bd462b0510fd88227587d490ae01aa4c"
     },
     {
       "path": "resources/procedures/document-capture.md",
-      "digest": "sha256:46a8231e92fcb19db7918938970ace8b4e4c22153fa8cbf0bb8100275bfbbfcf"
+      "digest": "sha256:f09100425c2b89a126c35c4490b0644519a4eee214114f2f0f52b6ea20467a04"
     },
     {
       "path": "resources/procedures/homogeneous-source-review.md",
@@ -689,7 +698,7 @@
     },
     {
       "path": "resources/procedures/knowledge-maintenance.md",
-      "digest": "sha256:42fc008c8b25df86b7a1e26d521003bc8e3a69cf16948365e93c41f896c0c315"
+      "digest": "sha256:f2cc36cb2425cf0ac96a2ea4f114ed5ce872c3711b82bdc25fdc71e42a2849b7"
     },
     {
       "path": "resources/procedures/knowledge-review.md",
@@ -697,7 +706,7 @@
     },
     {
       "path": "resources/procedures/knowledge-updates.md",
-      "digest": "sha256:f26726fc3264337200608e73f9ac20397016d6e3319ae8def6bf2a768630ae96"
+      "digest": "sha256:f43943fdf9265e5181c2e8cf3753d981fc9f59a44ee11b5beac404ec481344ea"
     },
     {
       "path": "resources/procedures/note.md",
@@ -717,7 +726,7 @@
     },
     {
       "path": "resources/procedures/production-stage-files.md",
-      "digest": "sha256:c5ff9e138ecd3f90d04ac834a82b2764f583da105ca23e3e07dfb816349d6c32"
+      "digest": "sha256:d093acf81a07b85cfe2a78e71f7ab301fa8c72e3edac3f5de990b1ff7eaf12f0"
     },
     {
       "path": "resources/procedures/project-configuration.md",
@@ -833,7 +842,7 @@
     },
     {
       "path": "skills/record-workspace-version/SKILL.md",
-      "digest": "sha256:c0e7415b362123deddcc1af61374cd50e5069e3b6db1dda516a21671734a1b1f"
+      "digest": "sha256:695b6b384a94743de08451f447bc8a135b6a7446dfab8e9b52ae16de54fd2903"
     },
     {
       "path": "skills/recover-workspace/SKILL.md",
@@ -853,12 +862,12 @@
     },
     {
       "path": "skills/work-production-stage/SKILL.md",
-      "digest": "sha256:d2ba49a86ba49f312a0e7b817164a8d41596aa18f7e20b41036d90946760a5ce"
+      "digest": "sha256:5bb250f42d5d28243daca30427b5fd9db52127460862748fc36935f0e0d0f754"
     }
   ],
   "graphDependencies": {
     "indexer": [],
     "workspace": []
   },
-  "digest": "sha256:e459da141751e9328d5d1b284f07abb54ae60c939eb964784cb94e5571170b03"
+  "digest": "sha256:0ce9bbc43630874ad90cf5663348b2c6f96dcdf7dd911f5e6b33c71154a3ea9e"
 }

package/providers/context/provider.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.12
+version: 0.7.14-beta.1
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

package/providers/context/resources/manuals/guides/knowledge-updates.md

@@ -107,12 +107,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
@@ -149,19 +148,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
@@ -197,6 +200,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/providers/context/resources/manuals/guides/package-outputs.md

@@ -31,6 +31,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,
@@ -482,3 +486,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.