@c4a/context 0.7.10 → 0.7.11

package/docs/guides/knowledge-updates.md

@@ -18,6 +18,25 @@ actual behavior, a confirmed decision, and a proposal that is not implemented.
 
 ## Keep planning local to the change
 
+Before starting production, compare the proposed content with the workspace's
+reader purpose. For clearly unrelated anecdotes or personal rankings, briefly
+recommend leaving them out of the formal manual or saving them separately because
+they can dilute useful retrieval. Attribution alone does not make content relevant.
+This is advice, not a CLI gate: honor the user's informed choice without repeated
+objections, while preserving subjective attribution and normal Review.
+
+Registered repositories are not prerequisites for every new request. Restore only
+sources needed to investigate or write the current task, including unchanged code
+when its implementation needs checking. Notes, document-only work, wording edits
+and navigation changes do not require unrelated checkouts. Retained article
+references alone do not require restoring every referenced repository. Missing
+material remains a gap; it must not be treated as investigated or permanently
+excluded. Independent available material can proceed through planning and delivery.
+For required code, use `context source recovery-plan <registered-name> --format json`.
+Reuse a valid local checkout or obtain clone authorization for the returned pinned
+version, then submit the decision using the returned recovery command and schema.
+Do not restore all registered sources merely because a checkout is missing.
+
 For one or two documents or a clearly bounded module, retain the useful planning
 decision: add or revise which articles, and place them where readers expect them.
 Do not expand this into a whole-workspace taxonomy, full navigation redesign or
@@ -32,6 +51,14 @@ known-task input to combine preparation and task creation. It still prepares
 navigation and retains report confirmation; it is not a bypass for new source
 authorization. Planning depth is an Agent judgment, not an additional CLI gate.
 
+For broad work, distinguish the whole requested outcome, the current batch and
+remaining capability families or document tasks. Entry-first knowledge should
+locate a checked file/symbol or source section and a concrete next step; a module
+name alone is not problem coverage. When merging or revising, preserve useful
+existing detail rather than replacing it with lookup advice. Review checks the
+promised reader task; task completion and navigation binding only describe the
+declared articles, not semantic coverage of all source material.
+
 ## First-task intake budget
 
 Before registration and capture, the Agent uses the user's task instructions and
@@ -422,11 +449,61 @@ knowledge structure and packages.
 
 To move an approved page, use `context revise "<old path>" --move-to "<new path>"
 --instruction "<requested move and content changes>" --format json`. The new
-path stays in the same collection. The revision retains the page identity,
+path may use another supported knowledge collection. The revision retains the page identity,
 rebases outgoing links and updates incoming Markdown links at approval. A new
 subject name alone only needs a title/content revision; do not create duplicate
-pages. Retirement is a content decision: explain the inapplicable material and
-supported replacement before changing its page and referring navigation.
+pages. Changing a website group alone does not require moving or reclassifying an article.
+
+### Restructure existing knowledge
+
+Read the affected approved articles and current sources before deciding what to
+keep, deepen, split, merge, retain as history or retire. Reuse the current plan
+and remaining scope; a new article plan does not prove old content was preserved.
+Work by reader task, not source or menu count.
+
+For a split or merge, first approve destination content, then revise the original
+and incoming links. Preserve useful details until their destination is available.
+Same-page fragments use ordinary revision edits; cross-page work uses new/revision
+tasks and explicit retirement. Finish each coherent batch's content and navigation
+before delivery; inspect both new content and the old articles' disposition.
+
+Preview approved-page retirement with `context task retire --input <file> --format json`:
+
+```yaml
+reason: These reader tasks are now covered by the approved guide.
+targets:
+  - path: architecture/old-guide.md
+    replacement: sop/current-guide.md
+```
+
+`replacement` is optional and must already be approved, outside the retirement set.
+Use several targets for a batch. Read affected files and blockers, then execute
+the returned digest-bound apply command within the user's authorization; do not
+ask for another confirmation when that retirement is already authorized.
+`context task retire --schema --format yaml` describes the input.
+
+Retirement removes selected Markdown and structure entries together, updates
+page-level incoming Markdown links to explicit replacements, and rebinds page
+navigation or removes retired navigation targets while retaining groups.
+Repair fragment links explicitly first: the CLI cannot infer where a split moved
+a paragraph. Without a replacement, repair incoming links before applying.
+Finish active drafts/revisions first; unfinished production targeting a selected
+page must be finished or amended rather than discarded.
+
+Follow status and the normal close/version/build flow before delivery. Sources
+and shared assets are not deleted. The response provides a temporary restore
+input for the existing rollback preview, including exact previous article,
+structure and modified navigation/link bytes. Retain that input or a Git baseline
+if restoration is needed after temporary cleanup. Retry an interrupted apply
+with the same input and digest; never delete runtime files to recover. Later
+conflicting edits require inspection instead of blind rollback.
+
+Historical pages with continuing reader value should normally retain their
+applicable version. Source read failure, shorter new text or a changed menu is
+not sufficient reason to retire an article.
+Retirement does not narrow the registered production scope. If the user also
+excludes the underlying topic from future work, record that through the existing
+requirements/exclusion flow rather than assuming file removal changes the goal.
 
 ### Adjust inputs while a local update is unfinished
 

package/docs/guides/package-outputs.md

@@ -40,13 +40,51 @@ prefixes only, not filesystem output paths.
 kbPackage({
   name: "project-kb",
   template: "src/package-templates/kb",
-  site: { title: "Project knowledge", lang: "en-US", base: "/" },
+  site: {
+    title: "Project knowledge",
+    lang: "en-US",
+    base: "/",
+    home: {
+      title: "Project knowledge",
+      slogan: "Find the context behind the work",
+      description: "Browse the approved knowledge map and supporting resources.",
+      resources: [{
+        title: "Project workspace",
+        description: "Open the repository that maintains this knowledge.",
+        href: "https://example.com/project",
+        featured: true,
+      }],
+    },
+  },
 });
 ```
 
 `site` is opt-in; omission keeps the existing KB-only output. Optional fields
 are `title` (defaults to the package name), `description`, `lang` (defaults to
 `en-US`), and `base` (defaults to `/`; use `/docs/` when hosted under that path).
+`home` optionally customizes the landing-page `title`, `slogan`, `description`
+and action buttons. Its `resources` list adds only configured repository,
+service or support cards; each item requires a safe `href`, a copyable
+`command`, or both. Set `featured: true` on a linked resource to also place it
+between the Browse knowledge and LLM Docs hero actions. Do not add placeholders
+for unknown destinations.
+
+Configure resources from confirmed project settings, repository remotes or
+successful publication receipts. If a service has not been created or its URL is
+unknown, omit the resource object; empty strings are not placeholders. Missing
+optional resources do not block building the site or authorize creating services.
+After an authorized deployment succeeds, add its returned destination to the
+existing resource list, avoiding duplicates. Rebuild when this changes the
+configuration; updating the hosted site still requires publication authorization.
+
+The homepage uses the first-level knowledge map as a complete site map. Each
+section card previews a bounded number of page links and retains a link to the
+full section, so large knowledge bases remain scannable without hiding top-level
+coverage. LLM Docs and Changelog remain dedicated generated resources. On wide
+screens the homepage content aligns with article content while preserving the
+sidebar rail; on narrow screens it uses the available width. Motion is limited
+to short card entrance and hover feedback and is disabled when the reader asks
+the operating system to reduce motion.
 The website uses a full-width VitePress theme with system fonts, compact navigation,
 a wide reading area and a smaller article outline. It starts in
 light mode regardless of the operating system; an explicit reader choice is

package/docs/reference/project-api.md

@@ -148,7 +148,22 @@ kbPackage({
   name: "component-kb",
   template: "src/package-templates/kb",
   select: { collections: ["codeindex", "architecture"] },
-  site: { title: "Component knowledge", lang: "en-US", base: "/" },
+  site: {
+    title: "Component knowledge",
+    lang: "en-US",
+    base: "/",
+    home: {
+      title: "Component knowledge",
+      slogan: "Build with the public contract in view",
+      description: "Browse components, usage guidance and implementation boundaries.",
+      resources: [{
+        title: "Project workspace",
+        description: "Open the repository that maintains this knowledge.",
+        href: "https://example.com/project",
+        featured: true,
+      }],
+    },
+  },
 });
 
 llmsPackage({
@@ -164,7 +179,11 @@ may be rebuilt; it is not an authoring source.
 `kbPackage.site` optionally adds a VitePress website at `dist/<base>-site/` in
 the same build, beside the KB directory. `<base>` removes one trailing `-kb`
 from the package name, if present. Omit it for KB-only output. It accepts `title`, `description`,
-`lang` and a deployment `base` path. Knowledge map is projected from
+`lang`, a deployment `base` path, and an optional `home` presentation. `home`
+accepts `title`, `slogan`, `description`, hero `actions`, and `resources` shown
+below the generated site map. Each resource needs an `href`, a copyable
+`command`, or both. Omit unknown resources; the builder never invents service
+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).
 

package/index.js

@@ -10889,11 +10889,35 @@ var coerce = {
 };
 var NEVER = INVALID;
 // src/packageSite.ts
+var siteHrefSchema = exports_external.string().trim().min(1).refine((value) => /^(?:https?:\/\/|mailto:|\/(?!\/)|#)/u.test(value), "Use an https URL, mailto URL, root-relative path, or page anchor");
+var packageSiteHomeActionSchema = exports_external.object({
+  text: exports_external.string().trim().min(1),
+  link: siteHrefSchema,
+  theme: exports_external.enum(["brand", "alt"]).optional()
+}).strict();
+var packageSiteHomeResourceSchema = exports_external.object({
+  title: exports_external.string().trim().min(1),
+  description: exports_external.string().trim().min(1).optional(),
+  href: siteHrefSchema.optional(),
+  action: exports_external.string().trim().min(1).optional(),
+  command: exports_external.string().trim().min(1).optional(),
+  featured: exports_external.boolean().optional()
+}).strict().refine((value) => value.href !== undefined || value.command !== undefined, {
+  message: "A homepage resource requires href or command"
+});
+var packageSiteHomeSchema = exports_external.object({
+  title: exports_external.string().trim().min(1).optional(),
+  slogan: exports_external.string().trim().min(1).optional(),
+  description: exports_external.string().trim().min(1).optional(),
+  actions: exports_external.array(packageSiteHomeActionSchema).optional(),
+  resources: exports_external.array(packageSiteHomeResourceSchema).optional()
+}).strict();
 var packageSiteSchema = exports_external.object({
   title: exports_external.string().trim().min(1).optional(),
   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("/")
+  base: exports_external.string().regex(/^\/(?:[a-zA-Z0-9_-]+\/)*$/, "Use / or a slash-delimited deployment path, such as /docs/").default("/"),
+  home: packageSiteHomeSchema.optional()
 }).strict();
 function normalizePackageSite(value) {
   return value === undefined ? undefined : packageSiteSchema.parse(value);

package/indexerArtifactPolicy.d.ts

@@ -10,11 +10,11 @@ export declare const indexerArtifactPolicyEligibilitySchema: z.ZodObject<{
         path: z.ZodString;
         value: z.ZodType<IndexerJson, z.ZodTypeDef, IndexerJson>;
     }, "strict", z.ZodTypeAny, {
-        value: IndexerJson;
         path: string;
-    }, {
         value: IndexerJson;
+    }, {
         path: string;
+        value: IndexerJson;
     }>, "many">;
     provider_supported_variants: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
     eligible_variants: z.ZodArray<z.ZodObject<{
@@ -71,8 +71,8 @@ export declare const indexerArtifactPolicyEligibilitySchema: z.ZodObject<{
     profile_id: string;
     profile_contract_digest: string;
     canonical_facts: {
-        value: IndexerJson;
         path: string;
+        value: IndexerJson;
     }[];
     provider_supported_variants: string[];
     eligible_variants: {
@@ -94,8 +94,8 @@ export declare const indexerArtifactPolicyEligibilitySchema: z.ZodObject<{
     profile_id: string;
     profile_contract_digest: string;
     canonical_facts: {
-        value: IndexerJson;
         path: string;
+        value: IndexerJson;
     }[];
     provider_supported_variants: string[];
     eligible_variants: {

package/indexerControlledProgram.d.ts

@@ -5131,6 +5131,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 }>;
                 primary_execution_fingerprint: z.ZodString;
             }, "strict", z.ZodTypeAny, {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -5142,13 +5149,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -5158,6 +5158,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                     fingerprint_digest: string;
                 };
             }, {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -5169,13 +5176,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -5185,6 +5185,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                     fingerprint_digest: string;
                 };
             }>, {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -5196,13 +5203,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -5212,6 +5212,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                     fingerprint_digest: string;
                 };
             }, {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -5223,13 +5230,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -5250,6 +5250,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
             metric_set_digest: string;
             dependency_view_digest: string | null;
             primary_execution_projection: {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -5261,13 +5268,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -5287,6 +5287,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
             metric_set_digest: string;
             dependency_view_digest: string | null;
             primary_execution_projection: {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -5298,13 +5305,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -5576,6 +5576,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
             metric_set_digest: string;
             dependency_view_digest: string | null;
             primary_execution_projection: {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -5587,13 +5594,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -5818,6 +5818,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
             metric_set_digest: string;
             dependency_view_digest: string | null;
             primary_execution_projection: {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -5829,13 +5836,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -6121,6 +6121,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
             metric_set_digest: string;
             dependency_view_digest: string | null;
             primary_execution_projection: {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -6132,13 +6139,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;
@@ -6423,6 +6423,13 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
             metric_set_digest: string;
             dependency_view_digest: string | null;
             primary_execution_projection: {
+                resources: {
+                    ref: string;
+                    kind: string;
+                    digest: string;
+                    layer_ref: string;
+                    phase: "primary" | "pre-authority";
+                }[];
                 protocol: "context.indexer.primary-execution-projection/v1";
                 indexer_id: string;
                 program_digest: string | null;
@@ -6434,13 +6441,6 @@ export declare const indexerControlledProgramRequestSchema: z.ZodObject<{
                 template_set_digest: string;
                 config_digest: string;
                 cli_contract_digest: string;
-                resources: {
-                    ref: string;
-                    kind: string;
-                    digest: string;
-                    layer_ref: string;
-                    phase: "primary" | "pre-authority";
-                }[];
                 shared_artifact_fingerprint: {
                     protocol: "context.indexer.shared-artifact-fingerprint/v1";
                     indexer_id: string;