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

package/providers/context/resources/manuals/guides/page-customization.md

@@ -0,0 +1,93 @@
+---
+id: context.sdk.page-customization
+kind: procedure
+mediaType: text/markdown
+---
+
+# 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/providers/context/resources/manuals/reference/project-api.md

@@ -193,6 +193,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/providers/context/resources/procedures/close-and-build.md

@@ -13,17 +13,15 @@ Pass `actor` explicitly when the conversation identifies the triggering user,
 including a known Lark display name. If Git has no name and the conversation
 does not identify the user, leave it absent and mention that in the delivery
 summary; do not infer identity from paths, logins or source authors. Amending
-an unbuilt entry preserves its actor unless an explicit replacement is supplied.
+an unpublished entry preserves its actor unless an explicit replacement is supplied.
 Record after Close and package/template approval, before the final build, so the
 selected outputs are built with the new version once. Build records hashes without
 increasing versions. Never count temporary progress or a build retry as a change.
 
-For formal repairs before a successful build, use `version inspect`'s
-`reusable_version` when present. Submit the same version and a complete updated
-changelog covering the original work plus repairs, not a repair-only replacement.
-The CLI updates the pending entry in place. A successful build or publication
-seals that version; subsequent changes require an increase. Do not delete build
-or publication receipts to reopen history.
+For formal repairs, inspect the current diff and check the publication target
+before reusing an untagged version. An unpublished preview can amend its current
+entry with the complete iteration's changes. Published content requires an
+increasing version. A successful local build does not seal a version.
 
 Successful delivery clears completed task drafts. Do not empty `.tmp` or call
 `task resume` as a finalization step. Retain registered repository checkouts,
@@ -34,14 +32,11 @@ Website rendering must preserve literal code and template examples. Do not revis
 valid source-grounded JSX or template syntax merely to avoid Vue interpolation;
 report a rendering defect if the website compiler cannot display it literally.
 
-Before an authorized external publication, run `context version publish-check
---format json`. If `needs_version` is true, inspect with `context version inspect
---publish --format json`, record a patch changelog using a `dist` trigger, and
-rebuild. Do not increment again if the workspace version already changed.
-If `unchanged` is true, there is no new delivery. Only after a successful external
-publication, use `context version published --hash <checked-hash> --receipt
-<successful-publication-reference> --format json`. Failure does not advance that
-baseline. These commands do not upload, publish or grant publishing authority.
+Before an authorized external publication, use the installed distribution skill
+or tool to read that target's current remote version and confirm the complete
+build directory. Reconcile its version with package.json and changelog.yaml.
+Building a preview does not publish or seal a version. Record the successful
+remote receipt per target; commit/tag only when separately authorized.
 
 Close deterministically reconciles approved Markdown and current relationship
 inputs into `knowledge/structure.yaml`. It compacts repeated machine fields out

package/providers/context/resources/procedures/document-capture.md

@@ -41,7 +41,7 @@ successful module as completion of the whole batch.
 The CLI owns normalization, snapshot identity, hashes, manifests, and
 idempotency. For Lark sources it also owns embedded-resource download,
 structured export, completeness reporting, and link projection. Required
-resource failures block the next phase; reference-only resources remain
+resource failures block work that depends on that material; reference-only resources remain
 explicit in the report. Never hand-write or repair captured snapshots or their
 asset links. If a selected local
 boundary is a documentation site rather than plain Markdown, use the
@@ -56,3 +56,9 @@ response. Once selected, the same identity is used for the document body and
 all embedded resources. If `docs +fetch` lacks the required `--doc-format`
 capability, follow the returned `lark-cli update` recovery and rerun the same
 Route command; do not replace the capture with a hand-written export.
+
+An active production stage can continue planning and writing articles whose sources
+are available while another capture remains pending. Keep unresolved sources in
+`pending_scopes`; do not cite their unavailable snapshots. The Route returns to
+pending capture after the active production/review work, before delivery completes.
+This does not mark failed captures as complete or waive source-read authorization.

package/providers/context/resources/procedures/knowledge-maintenance.md

@@ -7,9 +7,9 @@ mediaType: text/markdown
 # Maintain knowledge while production continues
 
 Use `context task maintain --input <file|-> --format json` to register multiple
-approved pages or an approved-output rebuild. The machine-readable input is
-[maintenance input](../../schemas/knowledge-maintenance-input.schema.json). This accepts a request; it does
-not discard the current task or immediately rewrite a page.
+approved pages or an approved-output rebuild. Read the input schema with
+`context task maintain --schema --format json`. Registration saves a request;
+it does not discard the current task or immediately rewrite a page.
 
 ```yaml
 id: clarify-existing-guides
@@ -66,3 +66,5 @@ route. If status says `target-still-in-production`, the original task still owns
 an unfinished page of that subject: let that writer settle before revising its
 latest approved text. After completion, read the
 new Route to resume production. Never resubmit an accepted old batch.
+
+After Review and Close, a revision with remaining targets continues authoring without an intermediate package build. Build the configured outputs after the final revision batch; Close alone does not mark the maintenance request delivered.

package/providers/context/resources/procedures/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/procedures/production-stage-files.md

@@ -10,6 +10,12 @@ The stage entry links CLI-owned requirements, planned skill guidance and task
 directories. Read relevant source text before writing; a skeleton is navigation,
 not semantic evidence. Skill names guide work, not article ownership or versions.
 
+Use the [reader organization guidance](knowledge-updates.md#reader-tasks-names-and-reading-order)
+for article names, placement and manually arranged navigation. Check the draft's
+main reader task against its planned title and group; adjust through the existing
+plan, revision or knowledge-map flow when needed. A navigation change alone does
+not call for rewriting valid prose.
+
 Restore repository checkouts only when needed for the current investigation or
 article. Independent notes/documents can proceed while unavailable code remains
 an explicit gap. For a required repository, read the

package/providers/context/skills/record-workspace-version/SKILL.md

@@ -30,6 +30,12 @@ document, navigation, repair, dist, other. Describe what actually triggered the
 iteration, not merely the CLI command. Never include raw private transcripts,
 credentials, local absolute paths or private account IDs in public history.
 
+Before amending the current version, check the target platform and Git tags.
+A local build is not publication. Use an increasing version for published content.
+Git comparison supports `version inspect --base <commit-or-tag>`; include the
+same `base_ref` in the record input when selected. Missing `.tmp` checkpoints do
+not require recreating historical receipts.
+
 Increment minor for added modules/material that expands knowledge coverage;
 increment patch for repairs, existing-module updates, navigation or persistent
 work-status changes. Major increases require an explicit user instruction.

package/providers/context/skills/work-production-stage/SKILL.md

@@ -6,6 +6,11 @@ description: Investigate or write within the current Context production director
 Use only the current Route's stage and authorized materials. Explain decisions
 in the user's conversation language.
 
+When planning or revising article placement, titles or reading order, read
+[reader organization guidance](../../resources/procedures/knowledge-updates.md#reader-tasks-names-and-reading-order).
+Apply it to the affected topics within the user's scope; it adds no production
+stage or permission gate.
+
 For investigation, use the supplied directory and its submission schema. Start
 with code skeletons and document outlines; selectively read original material
 where needed to decide reader topics, source grouping and writing batches.