@c4a/context 0.7.14-beta.1 → 0.7.15

package/docs/guides/knowledge-updates.md

@@ -194,6 +194,48 @@ 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.
 
+### Preserve established navigation intent
+
+Before placing new knowledge, read the workspace's AGENTS.md, current
+`src/knowledge-map.yaml`, existing overview pages and relevant category/article
+bodies. Reuse any settled directory intent in the current plan. Establish what
+each affected category helps readers do and why adjacent categories are separate;
+do not infer this from labels alone. Read only affected branches and enough
+neighboring content to distinguish them, not the entire library on every update.
+If intent remains ambiguous, state the proposed interpretation in the plan.
+
+Prefer, in order: revise an existing article; add a page to a matching category;
+add a coherent child category; propose a top-level change only when existing
+categories cannot serve a distinct, lasting reader need. Do not create a top-level
+category merely because a source, repository, product, team or batch is new.
+For example, a new assistant's usage guide, frontend integration and runtime
+architecture can belong in existing usage, frontend and backend categories, with
+cross-links for the shared product. Keep them together only when the site's
+established organizing principle supports that choice.
+
+In the work-start report or current plan, briefly state the affected articles'
+intended placements and reused category intent. For proposed top-level additions,
+renames, removals or changes of purpose, show the before/after tree, why reuse is
+insufficient, affected existing pages and reading order. Present that change for
+human review before applying it. This uses the existing report feedback where
+available; do not add a new CLI state, schema field or routine per-article gate.
+Explicit user approval of that concrete structure is sufficient; do not ask again.
+General permission to write knowledge or organize batches is not approval to
+change the site's top-level organization. If the need emerges after report
+approval, update the same plan and ask about that structural change only; continue
+independent work within the approved organization.
+
+Before delivery, compare the resulting map with the approved plan: article
+placement matches its main reader task, titles match the bodies, sibling ordering
+is deliberate, and directories are neither empty nor accidental duplicates.
+Honor the workspace's chosen directory depth and homogeneous sibling convention;
+where it requires directory-only or article-only siblings, do not mix them.
+Use an "Other" group last only for genuinely useful residual content, not to
+avoid classification. Apply supported map adjustments through the current CLI
+flow, retaining article identities and URLs. Record lasting category intent
+briefly in the workspace AGENTS.md or existing organization guide; do not create
+a separate taxonomy ledger or put planning instructions in reader articles.
+
 ### Reader tasks, names and reading order
 
 Read the affected articles' bodies before changing their categories or titles.
@@ -251,8 +293,8 @@ change does not require a prose rewrite or file migration; changing its label do
 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.
+delivered. These are Agent editorial decisions, not new CLI checks or routine per-article
+approval gates. Top-level changes follow the focused review described above.
 
 ## Edit one section or review part of a batch
 
@@ -277,6 +319,12 @@ input without that flag to continue. A preview is not approval and does not make
 a stale revision valid.
 
 Review can approve checked pages while leaving repair pages pending. The HTML
+report shows the current site navigation, candidate changes and expected file
+paths. Unchanged approved pages retain their titles with omitted bodies. Enter
+revision instructions directly in the report; the copied code and following
+instruction lines must be returned together without edits. The CLI binds them to
+the reviewed content and baseline and returns repair commands while leaving
+those pages pending. Changed candidates require a fresh review. The HTML
 review code includes pending positions; managed Review provides the same current
 scope as a JSON template. Send decisions only for pages actually reviewed. Omit
 means a durable exclusion, not repair. Partial approval alone does not build.

package/docs/guides/lark-resources.md

@@ -124,3 +124,41 @@ fixed. Accepted failures remain visible as warnings and unavailable-resource
 notices; they are never represented as downloaded evidence. Review shows
 available previews, references, and warnings so the human or managed policy can
 assess the page with its non-text evidence.
+
+## Image choices for a production task
+
+The work-start report asks once when a task contains more than 30 distinct images
+and has no explicit image policy. The choices are intelligent conversion and
+inclusion (recommended), include all as images with compression, or include none
+with placeholders. Count the whole task, not each capture or writing batch.
+Review reports show the resulting image handling and any fallbacks.
+
+To skip image acquisition while preserving visible source placeholders:
+
+```ts
+captureLark({ source: handbook, resources: { images: "reference-only" } });
+```
+
+To retain static images but exclude GIF files:
+
+```ts
+captureLark({ source: handbook, resources: { gifs: "reference-only" } });
+```
+
+Both fields also accept `bundle`; omitted fields retain normal capture behavior.
+Known GIF metadata avoids downloading; when a source only supplies an opaque
+media token, identification may require downloading the file. Such a GIF is then
+excluded from the snapshot assets and knowledge, rather than decoded or retained.
+Existing evidence is not deleted by changing a policy. Already approved image
+references must be revised through the normal Review flow to change their content.
+
+Inclusion does not mean lossless original-byte delivery. The package optimizer
+preserves animations without decoding every frame or silently flattening them.
+Codec failures and images that cannot fit delivery budgets become visible output
+placeholders with a build warning; approved source bytes remain unchanged.
+Do not rewrite approved prose to repair a codec error or disable pixel safety
+limits. The reading meaning of an image is handled in writing and Review.
+
+Source document links can be retained for viewing under the reader's permissions.
+Temporary signed media links are not durable image hosting. Do not embed access
+tokens in generated pages or claim that excluded images have been interpreted.

package/docs/reference/indexer-provider-protocol.md

@@ -351,8 +351,10 @@ visible-Skill claim nor the Route report authorizes Bundle materialization.
 ## Contract overlay validation
 
 `validate-indexer-contract-overlays` recomputes the complete data-only overlay
-against the exact CLI base and operator contracts. Invalid DSL, executable
-fields, identity redefinition, threshold weakening, digest drift or a partial
+against the current CLI base and operator contracts. Contract versions must match;
+historical base/operator digests are provenance, not compatibility pins. Parser
+release changes and unrelated profile changes do not require rebinding. Invalid DSL, executable
+fields, identity redefinition, threshold weakening, invalid payload integrity or a partial
 Provider identity fails validation. The selected Provider Bundle integrity is
 an exact input, not a self-reported trust assertion.
 

package/index.js

@@ -23838,11 +23838,11 @@ function validateIndexerContractOverlay(input) {
   if (indexerContractOverlayDigest(overlayPayload) !== overlay.overlay_digest) {
     throw new TypeError("contract overlay digest does not match its canonical payload");
   }
-  if (overlay.extends.version !== base.version || overlay.extends.contract_digest !== base.contract_digest) {
-    throw new TypeError("contract overlay is bound to another base contract");
+  if (overlay.extends.version !== base.version) {
+    throw new TypeError("contract overlay requires another base contract version");
   }
-  if (overlay.operator_contract_version !== operators.version || overlay.operator_contract_digest !== operators.contract_digest) {
-    throw new TypeError("contract overlay is bound to another operator contract");
+  if (overlay.operator_contract_version !== operators.version) {
+    throw new TypeError("contract overlay requires another operator contract version");
   }
   const baseProfile = profileById(base, overlay.extends.profile);
   const effectiveProfile = mergeOverlayProfile(baseProfile, overlay);
@@ -31425,6 +31425,12 @@ var captureFile = (definition) => {
 var captureLark = (definition) => {
   const sourceDefinition = bindSourceType(definition.source, "lark", "captureLark source");
   const sourceId = getSourceName(sourceDefinition);
+  for (const key of ["images", "gifs"]) {
+    const value = definition.resources?.[key];
+    if (value !== undefined && value !== "bundle" && value !== "reference-only") {
+      throw new TypeError(`captureLark resources.${key} must be bundle or reference-only`);
+    }
+  }
   const maxBytesPerResource = definition.resources?.maxBytesPerResource ?? 20 * 1024 * 1024;
   const maxTotalBytes = definition.resources?.maxTotalBytes ?? 200 * 1024 * 1024;
   if (!Number.isSafeInteger(maxBytesPerResource) || maxBytesPerResource < 1) {
@@ -31443,6 +31449,8 @@ var captureLark = (definition) => {
     writes: [sourceSnapshotResource(sourceDefinition, "lark")],
     source: sourceDefinition,
     resources: {
+      ...definition.resources?.images === undefined ? {} : { images: definition.resources.images },
+      ...definition.resources?.gifs === undefined ? {} : { gifs: definition.resources.gifs },
       videos: definition.resources?.videos ?? "reference-only",
       maxBytesPerResource,
       maxTotalBytes

package/package.json

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

package/phases.d.ts

@@ -50,6 +50,8 @@ export type CaptureLarkPhaseDefinition = {
     writes: readonly PhaseResourceReference[];
     source: LarkSourceDefinition | LarkSourceReference;
     resources: {
+        images?: "reference-only" | "bundle";
+        gifs?: "reference-only" | "bundle";
         videos: "reference-only" | "bundle";
         maxBytesPerResource: number;
         maxTotalBytes: number;
@@ -76,6 +78,8 @@ export declare const captureFile: (definition: {
 export declare const captureLark: (definition: {
     source: LarkSourceDefinition | LarkSourceReference;
     resources?: {
+        images?: "reference-only" | "bundle";
+        gifs?: "reference-only" | "bundle";
         videos?: "reference-only" | "bundle";
         maxBytesPerResource?: number;
         maxTotalBytes?: number;