@c4a/context-cli 0.6.2 → 0.6.3

package/providers/context/graphs/workspace.yaml

@@ -107,6 +107,23 @@ nodes:
         - resources/dialogue/structure-confirmation.md
         - resources/views/structure-current.yaml
 
+  - id: resume-align-next
+    kind: action
+    reasonCode: route.structure.pending-target
+    action: actions/align-next.yaml
+    satisfiedBy:
+      - path: resume.structure_refresh_required
+        exists: false
+    resources:
+      required:
+        - resources/procedures/prose-align.md
+        - resources/views/structure-current.yaml
+      recommended:
+        - resources/semantic/align/structure-planning.md
+        - resources/semantic/align/gates.md
+        - resources/semantic/align/density-profile.md
+        - resources/semantic/align/candidate-resolution.md
+
   - id: apply-structure-confirmation
     kind: action
     reasonCode: route.structure.confirm
@@ -133,6 +150,18 @@ nodes:
         - resources/views/structure-current.yaml
         - resources/semantic/compile/index.md
 
+  - id: resolve-review-identities
+    kind: action
+    reasonCode: route.review.identity-conflict
+    action: actions/reconcile-review-identities.yaml
+    satisfiedBy:
+      - path: review.identity_conflicts_present
+        exists: false
+    resources:
+      required:
+        - resources/procedures/knowledge-review.md
+        - resources/views/review-current.yaml
+
   - id: resume-review-current-batch
     kind: gate
     reasonCode: route.review.decision-required
@@ -186,15 +215,23 @@ nodes:
         - resources/procedures/source-capture-detailed.md
 
   - id: ensure-repository-sources
-    kind: action
+    kind: gate
     reasonCode: route.source.repository-not-ready
-    action: actions/ensure-repository-sources.yaml
+    inspectionAction: actions/inspect-repository-recovery.yaml
+    resolutionAction: actions/restore-repository-sources.yaml
+    gate:
+      id: repository-source-recovery
+      prompt: Choose how to restore each missing registered repository checkout.
+      authority: context.repository-restore
+      delegatable: false
     satisfiedBy:
       - path: sources.repositories_ready
         equals: true
     resources:
       required:
-        - resources/procedures/source-boundary.md
+        - resources/procedures/repository-source-recovery.md
+        - resources/dialogue/human-gates.md
+        - resources/dialogue/repository-source-recovery.md
         - resources/views/source-current.yaml
 
   - id: configure-document-capture
@@ -211,6 +248,7 @@ nodes:
       recommended:
         - resources/procedures/document-capture.md
         - resources/views/source-current.yaml
+        - resources/manuals/guides/lark-resources.md
 
   - id: authorize-document-capture
     kind: gate
@@ -231,6 +269,7 @@ nodes:
         - resources/views/source-current.yaml
       recommended:
         - resources/procedures/source-capture-detailed.md
+        - resources/manuals/guides/lark-resources.md
 
   - id: capture-next
     kind: action
@@ -242,9 +281,10 @@ nodes:
     resources:
       required:
         - resources/procedures/document-capture.md
-        - resources/views/source-current.yaml
+        - resources/views/source-boundary.yaml
       recommended:
         - resources/procedures/source-capture-detailed.md
+        - resources/manuals/guides/lark-resources.md
 
   - id: choose-extraction-scope
     kind: gate
@@ -290,7 +330,7 @@ nodes:
     resources:
       required:
         - resources/procedures/code-extraction.md
-        - resources/views/source-current.yaml
+        - resources/views/source-boundary.yaml
 
   - id: classify-document
     kind: gate
@@ -469,10 +509,12 @@ edges:
   - { from: choose-evidence-maintenance, to: maintain-evidence, kind: gatedBy }
   - { from: maintain-evidence, to: close-approved-knowledge }
   - { from: close-approved-knowledge, to: resume-prose-lifecycle }
-  - { from: resume-prose-lifecycle, to: confirm-structure }
+  - { from: resume-prose-lifecycle, to: resume-align-next }
+  - { from: resume-align-next, to: confirm-structure }
   - { from: confirm-structure, to: apply-structure-confirmation, kind: gatedBy }
   - { from: apply-structure-confirmation, to: compile-next }
-  - { from: compile-next, to: resume-review-current-batch }
+  - { from: compile-next, to: resolve-review-identities }
+  - { from: resolve-review-identities, to: resume-review-current-batch }
   - { from: resume-review-current-batch, to: apply-resumed-review, kind: gatedBy }
   - { from: apply-resumed-review, to: choose-source-boundary }
   - { from: choose-source-boundary, to: ensure-repository-sources, kind: gatedBy }

package/providers/context/manifest.json

@@ -2,14 +2,14 @@
   "schema": "agent-graph.bundle.v1",
   "provider": {
     "id": "c4a/context",
-    "version": "0.6.2"
+    "version": "0.6.3"
   },
   "providerManifest": "provider.yaml",
   "graphs": [
     {
       "id": "workspace",
       "path": "graphs/workspace.yaml",
-      "digest": "sha256:4b344cb9ecc03990f2a2f35aca372949917510f5957c4760fe69a651368eddbc"
+      "digest": "sha256:98b74bb6a59a9024978209e70c2519bd3608ea77b7576326685576184947898f"
     }
   ],
   "actions": [
@@ -73,11 +73,6 @@
       "path": "actions/configure-prose-lifecycle.yaml",
       "digest": "sha256:226d20be637455b3ffba4a115dd0437d3330354d8a73b8e5313b3af303d53bcc"
     },
-    {
-      "id": "ensure-repository-sources",
-      "path": "actions/ensure-repository-sources.yaml",
-      "digest": "sha256:00205debd0e58065f04520b1543c3e5dffc0da63cf42ffff4370757e59557791"
-    },
     {
       "id": "extract-next",
       "path": "actions/extract-next.yaml",
@@ -88,6 +83,11 @@
       "path": "actions/inspect-document-classification.yaml",
       "digest": "sha256:973889832e3adfba4fa019b3dfadda35fe22536c44ef97efba2299e6cdd65786"
     },
+    {
+      "id": "inspect-repository-recovery",
+      "path": "actions/inspect-repository-recovery.yaml",
+      "digest": "sha256:6890fc2fb95823753beb7684066ddaac0b02e377c5fe3f568ac75286e00c9e88"
+    },
     {
       "id": "inspect-review",
       "path": "actions/inspect-review.yaml",
@@ -108,6 +108,11 @@
       "path": "actions/materialize-context-view.yaml",
       "digest": "sha256:0ed6b73b6a31324575fd10fb8f2067c8381609ab272a031b326080506105d115"
     },
+    {
+      "id": "reconcile-review-identities",
+      "path": "actions/reconcile-review-identities.yaml",
+      "digest": "sha256:aac95cc46ab8a872bdd1cc53cf64e3bbde8cf8dc2d6e9ac2da82bb378fcfe09a"
+    },
     {
       "id": "register-source-batch",
       "path": "actions/register-source-batch.yaml",
@@ -121,12 +126,17 @@
     {
       "id": "repair-verification",
       "path": "actions/repair-verification.yaml",
-      "digest": "sha256:ab78ad85d3d001e7897bbb3f952f1489753d58a222b7aaefecb41d189a806375"
+      "digest": "sha256:835789670d5a3ee0b140820c79a26b925b8df374a4a93f598055dfcb06498cc7"
     },
     {
       "id": "repair-workspace-state",
       "path": "actions/repair-workspace-state.yaml",
       "digest": "sha256:67296adf5336a7f746e250dc23676972282f88410fb6a6edc41a929e15d1856b"
+    },
+    {
+      "id": "restore-repository-sources",
+      "path": "actions/restore-repository-sources.yaml",
+      "digest": "sha256:8e44f0dc15ac9b0eea8af62dcefd315d7c03a52dab1cda373537d275ae7383dc"
     }
   ],
   "resources": [
@@ -140,10 +150,15 @@
       "path": "resources/views/review-current.yaml",
       "digest": "sha256:264b6f7de5cce9034e5e0a344bf29341421467bfb1ef96c298d4936ee99d13f5"
     },
+    {
+      "id": "context.sdk.lark-resources",
+      "path": "resources/manuals/guides/lark-resources.md",
+      "digest": "sha256:a179bb8bf7d8185bb6f3033ef692dd15fa5b702c91525e7c272d3025d3bb7c52"
+    },
     {
       "id": "context.sdk.package-outputs",
       "path": "resources/manuals/guides/package-outputs.md",
-      "digest": "sha256:df6236373c23ffde93283b0999450250d90fa1e961185f83b9060a6ba56400fc"
+      "digest": "sha256:32337aae19ba17ec01fc6da04a40cec9aab4ba4ee7561d8073e600d601b560ae"
     },
     {
       "id": "context.sdk.package-templates",
@@ -153,7 +168,7 @@
     {
       "id": "context.sdk.project-api",
       "path": "resources/manuals/reference/project-api.md",
-      "digest": "sha256:9ab0be26aeccea79f561c7ecd01636beb97b7088ea1ddb141c3cbc96af758508"
+      "digest": "sha256:3dd8dfa54ba4b34a31d0a284385c77992f84ad2d7ef46583ff34683aae4081ac"
     },
     {
       "id": "context.sdk.template-variables",
@@ -185,6 +200,11 @@
       "path": "resources/semantic/compile/index.md",
       "digest": "sha256:4145f6bdc2855e354d00d311448584c3ed4b73849fc1277a2ed72d7be84e9e7c"
     },
+    {
+      "id": "context.source-boundary",
+      "path": "resources/views/source-boundary.yaml",
+      "digest": "sha256:6ff3eeaeb3ea8c3908106c26cfe8b8a6c6b0f636e3daaf7da9511830305feee2"
+    },
     {
       "id": "context.source-current",
       "path": "resources/views/source-current.yaml",
@@ -255,6 +275,11 @@
       "path": "resources/dialogue/package-output.md",
       "digest": "sha256:0ca7a9e56397f9acc62d92777d91e0203e2d6caa7f08268dca8037987e5911a5"
     },
+    {
+      "id": "dialogue.repository-source-recovery",
+      "path": "resources/dialogue/repository-source-recovery.md",
+      "digest": "sha256:ac1c7ba59f91d870f011eb1526afa83003e45205a6c436f635fb0e5b2e3c3055"
+    },
     {
       "id": "dialogue.source-boundary",
       "path": "resources/dialogue/source-boundary.md",
@@ -268,7 +293,7 @@
     {
       "id": "procedure.close-and-build",
       "path": "resources/procedures/close-and-build.md",
-      "digest": "sha256:19c630e9c4c05f5b430df603fb705731427d2ef4bfcaf83a1b653d364164cae2"
+      "digest": "sha256:752f44bbb939cfb2c48bf3900069412b7c8c0eb135bb2b539de6b1e6862e847c"
     },
     {
       "id": "procedure.code-extraction",
@@ -278,7 +303,7 @@
     {
       "id": "procedure.document-capture",
       "path": "resources/procedures/document-capture.md",
-      "digest": "sha256:07f8ccfe3429c28f7dd6b732821911b9636e9a0a9f1b6034986dce669b416248"
+      "digest": "sha256:482fa395dbc5ed167a4c1180463e0b9929d2a9a5a90f4ef0b5122cabf2cce80b"
     },
     {
       "id": "procedure.document-classification",
@@ -293,7 +318,7 @@
     {
       "id": "procedure.knowledge-review",
       "path": "resources/procedures/knowledge-review.md",
-      "digest": "sha256:5ebf2bb9399d291f8a5dbba249169b4fb221e456aa6c05081c4c54b2e6f3cf48"
+      "digest": "sha256:a5d1f85514125eee0da2fda87b9b9af1e922248dffd8e3fc98f626a8325297d2"
     },
     {
       "id": "procedure.package-output",
@@ -315,6 +340,11 @@
       "path": "resources/procedures/prose-compile.md",
       "digest": "sha256:c36ba3dcf9aa11a8759afaab2c9a99859c31acaf5f06456c4e0e6793130b7d6e"
     },
+    {
+      "id": "procedure.repository-source-recovery",
+      "path": "resources/procedures/repository-source-recovery.md",
+      "digest": "sha256:af42c0f67d48518e76f4feac1969476fe16e35f591d2dd4432ae57fb31b6f794"
+    },
     {
       "id": "procedure.source-boundary",
       "path": "resources/procedures/source-boundary.md",
@@ -323,12 +353,12 @@
     {
       "id": "procedure.source-capture-detailed",
       "path": "resources/procedures/source-capture-detailed.md",
-      "digest": "sha256:0cf764a43c33fbcf86b32a3731fec5905ebf0d312b7939059aae99a6ab0532e2"
+      "digest": "sha256:45fd35260c6bcd799ebf4f9069596a604cd23333332e45ef05d2b87f1ad02dfc"
     },
     {
       "id": "procedure.verify-and-repair",
       "path": "resources/procedures/verify-and-repair.md",
-      "digest": "sha256:6becb02923a07eae47de7a9cfca2fc28ee3932a62bbcf4d273ec0f5b430b15e9"
+      "digest": "sha256:177d6c1f1f263f5c502ad197067a7fdcd5165d7ce2ac778672201c9f90888589"
     }
   ],
   "schemas": [
@@ -342,6 +372,11 @@
       "path": "schemas/prose-structure-batch.schema.json",
       "digest": "sha256:fc4ebbb5ee81ae77238cd60350ebac16f55e8a5adf3f5f5db411040474e01842"
     },
+    {
+      "id": "schemas/repository-source-recovery.schema.json",
+      "path": "schemas/repository-source-recovery.schema.json",
+      "digest": "sha256:589aea722965d81c9291232346bfc1d90ea04a94913d8ab7e3461e5a92746c56"
+    },
     {
       "id": "schemas/source-batch-input.schema.json",
       "path": "schemas/source-batch-input.schema.json",
@@ -397,10 +432,6 @@
       "path": "actions/configure-prose-lifecycle.yaml",
       "digest": "sha256:226d20be637455b3ffba4a115dd0437d3330354d8a73b8e5313b3af303d53bcc"
     },
-    {
-      "path": "actions/ensure-repository-sources.yaml",
-      "digest": "sha256:00205debd0e58065f04520b1543c3e5dffc0da63cf42ffff4370757e59557791"
-    },
     {
       "path": "actions/extract-next.yaml",
       "digest": "sha256:3d5e26cbdd912c9be666ce423b19456b31ab67da53c4e01a1a1c7a3dc1e6420a"
@@ -409,6 +440,10 @@
       "path": "actions/inspect-document-classification.yaml",
       "digest": "sha256:973889832e3adfba4fa019b3dfadda35fe22536c44ef97efba2299e6cdd65786"
     },
+    {
+      "path": "actions/inspect-repository-recovery.yaml",
+      "digest": "sha256:6890fc2fb95823753beb7684066ddaac0b02e377c5fe3f568ac75286e00c9e88"
+    },
     {
       "path": "actions/inspect-review.yaml",
       "digest": "sha256:79ab3605a3b17d227f4c3ae4d207634884e1422c4bb07fc275e98c2bb296f140"
@@ -425,6 +460,10 @@
       "path": "actions/materialize-context-view.yaml",
       "digest": "sha256:0ed6b73b6a31324575fd10fb8f2067c8381609ab272a031b326080506105d115"
     },
+    {
+      "path": "actions/reconcile-review-identities.yaml",
+      "digest": "sha256:aac95cc46ab8a872bdd1cc53cf64e3bbde8cf8dc2d6e9ac2da82bb378fcfe09a"
+    },
     {
       "path": "actions/register-source-batch.yaml",
       "digest": "sha256:e2f406ce398f21bfb0a0cb43b88416422581519a8e74168f44a2a4f5f7e673f6"
@@ -435,23 +474,27 @@
     },
     {
       "path": "actions/repair-verification.yaml",
-      "digest": "sha256:ab78ad85d3d001e7897bbb3f952f1489753d58a222b7aaefecb41d189a806375"
+      "digest": "sha256:835789670d5a3ee0b140820c79a26b925b8df374a4a93f598055dfcb06498cc7"
     },
     {
       "path": "actions/repair-workspace-state.yaml",
       "digest": "sha256:67296adf5336a7f746e250dc23676972282f88410fb6a6edc41a929e15d1856b"
     },
+    {
+      "path": "actions/restore-repository-sources.yaml",
+      "digest": "sha256:8e44f0dc15ac9b0eea8af62dcefd315d7c03a52dab1cda373537d275ae7383dc"
+    },
     {
       "path": "codes.yaml",
-      "digest": "sha256:cee059821edb0cf7601189649172418031ec145438e0647a248813c6255f0d55"
+      "digest": "sha256:583f6b7e4d489d42328ea0f7ad73b95c6a28c03cc44bd4b703443f00cdb66a6d"
     },
     {
       "path": "graphs/workspace.yaml",
-      "digest": "sha256:4b344cb9ecc03990f2a2f35aca372949917510f5957c4760fe69a651368eddbc"
+      "digest": "sha256:98b74bb6a59a9024978209e70c2519bd3608ea77b7576326685576184947898f"
     },
     {
       "path": "provider.yaml",
-      "digest": "sha256:0edd1fb11947dbf99179fc715b1a9182a4ed8ffe2007ff1859c09eb2aba609d5"
+      "digest": "sha256:42dbd41c64f6ef7cc2f22a7aeef5be12c8e8619ca31f48050a3de4e449fbf043"
     },
     {
       "path": "resources/diagnostics/projection-stale.md",
@@ -493,6 +536,10 @@
       "path": "resources/dialogue/package-output.md",
       "digest": "sha256:0ca7a9e56397f9acc62d92777d91e0203e2d6caa7f08268dca8037987e5911a5"
     },
+    {
+      "path": "resources/dialogue/repository-source-recovery.md",
+      "digest": "sha256:ac1c7ba59f91d870f011eb1526afa83003e45205a6c436f635fb0e5b2e3c3055"
+    },
     {
       "path": "resources/dialogue/source-boundary.md",
       "digest": "sha256:ae8436045b0de5ace6843b47a552a72ffc0020fa82612e594465cf193255803f"
@@ -501,9 +548,13 @@
       "path": "resources/dialogue/structure-confirmation.md",
       "digest": "sha256:4f9667860bb555c2cf236237c5a21644b7a2b249a452337d83087fa4c389dc2d"
     },
+    {
+      "path": "resources/manuals/guides/lark-resources.md",
+      "digest": "sha256:a179bb8bf7d8185bb6f3033ef692dd15fa5b702c91525e7c272d3025d3bb7c52"
+    },
     {
       "path": "resources/manuals/guides/package-outputs.md",
-      "digest": "sha256:df6236373c23ffde93283b0999450250d90fa1e961185f83b9060a6ba56400fc"
+      "digest": "sha256:32337aae19ba17ec01fc6da04a40cec9aab4ba4ee7561d8073e600d601b560ae"
     },
     {
       "path": "resources/manuals/reference/package-templates.md",
@@ -511,7 +562,7 @@
     },
     {
       "path": "resources/manuals/reference/project-api.md",
-      "digest": "sha256:9ab0be26aeccea79f561c7ecd01636beb97b7088ea1ddb141c3cbc96af758508"
+      "digest": "sha256:3dd8dfa54ba4b34a31d0a284385c77992f84ad2d7ef46583ff34683aae4081ac"
     },
     {
       "path": "resources/manuals/reference/template-variables.md",
@@ -519,7 +570,7 @@
     },
     {
       "path": "resources/procedures/close-and-build.md",
-      "digest": "sha256:19c630e9c4c05f5b430df603fb705731427d2ef4bfcaf83a1b653d364164cae2"
+      "digest": "sha256:752f44bbb939cfb2c48bf3900069412b7c8c0eb135bb2b539de6b1e6862e847c"
     },
     {
       "path": "resources/procedures/code-extraction.md",
@@ -527,7 +578,7 @@
     },
     {
       "path": "resources/procedures/document-capture.md",
-      "digest": "sha256:07f8ccfe3429c28f7dd6b732821911b9636e9a0a9f1b6034986dce669b416248"
+      "digest": "sha256:482fa395dbc5ed167a4c1180463e0b9929d2a9a5a90f4ef0b5122cabf2cce80b"
     },
     {
       "path": "resources/procedures/document-classification.md",
@@ -539,7 +590,7 @@
     },
     {
       "path": "resources/procedures/knowledge-review.md",
-      "digest": "sha256:5ebf2bb9399d291f8a5dbba249169b4fb221e456aa6c05081c4c54b2e6f3cf48"
+      "digest": "sha256:a5d1f85514125eee0da2fda87b9b9af1e922248dffd8e3fc98f626a8325297d2"
     },
     {
       "path": "resources/procedures/package-output.md",
@@ -557,17 +608,21 @@
       "path": "resources/procedures/prose-compile.md",
       "digest": "sha256:c36ba3dcf9aa11a8759afaab2c9a99859c31acaf5f06456c4e0e6793130b7d6e"
     },
+    {
+      "path": "resources/procedures/repository-source-recovery.md",
+      "digest": "sha256:af42c0f67d48518e76f4feac1969476fe16e35f591d2dd4432ae57fb31b6f794"
+    },
     {
       "path": "resources/procedures/source-boundary.md",
       "digest": "sha256:99097947961d7fa5b17f9e6b9c9471aac38cec1943bd7feb414b21d6a1e26a49"
     },
     {
       "path": "resources/procedures/source-capture-detailed.md",
-      "digest": "sha256:0cf764a43c33fbcf86b32a3731fec5905ebf0d312b7939059aae99a6ab0532e2"
+      "digest": "sha256:45fd35260c6bcd799ebf4f9069596a604cd23333332e45ef05d2b87f1ad02dfc"
     },
     {
       "path": "resources/procedures/verify-and-repair.md",
-      "digest": "sha256:6becb02923a07eae47de7a9cfca2fc28ee3932a62bbcf4d273ec0f5b430b15e9"
+      "digest": "sha256:177d6c1f1f263f5c502ad197067a7fdcd5165d7ce2ac778672201c9f90888589"
     },
     {
       "path": "resources/semantic/align/candidate-resolution.md",
@@ -597,6 +652,10 @@
       "path": "resources/views/review-current.yaml",
       "digest": "sha256:264b6f7de5cce9034e5e0a344bf29341421467bfb1ef96c298d4936ee99d13f5"
     },
+    {
+      "path": "resources/views/source-boundary.yaml",
+      "digest": "sha256:6ff3eeaeb3ea8c3908106c26cfe8b8a6c6b0f636e3daaf7da9511830305feee2"
+    },
     {
       "path": "resources/views/source-current.yaml",
       "digest": "sha256:2d9c832f7f6c460d2b1e413048093da1ffb939f7d6ac4dc770433815c8fe3f09"
@@ -621,6 +680,10 @@
       "path": "schemas/prose-structure-batch.schema.json",
       "digest": "sha256:fc4ebbb5ee81ae77238cd60350ebac16f55e8a5adf3f5f5db411040474e01842"
     },
+    {
+      "path": "schemas/repository-source-recovery.schema.json",
+      "digest": "sha256:589aea722965d81c9291232346bfc1d90ea04a94913d8ab7e3461e5a92746c56"
+    },
     {
       "path": "schemas/source-batch-input.schema.json",
       "digest": "sha256:aa5f1a1bf6a6573982e89e50c9d991f6aa72a5cbbda0867d1f483e30315c4409"
@@ -633,5 +696,5 @@
   "graphDependencies": {
     "workspace": []
   },
-  "digest": "sha256:f9d3b6ea8d0b93df323af7557c9729ecb328a260c5389ed8869c21e1290726d3"
+  "digest": "sha256:9a4fdc41e173bd8f98d12428c0ef0f03e00a62a588bedfb58ad52ef6b589317c"
 }

package/providers/context/provider.yaml

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

package/providers/context/resources/dialogue/repository-source-recovery.md

@@ -0,0 +1,23 @@
+---
+id: dialogue.repository-source-recovery
+kind: procedure
+mediaType: text/markdown
+---
+
+# Repository source recovery dialogue
+
+Explain that the Context project is intact: only Git-ignored source checkouts
+or local links are missing. Show one choice per physical repository, not per
+logical module.
+
+For an existing checkout, ask for its path or ask the user to authorize a
+specific parent directory for a bounded scan. Show matching candidates with
+their origin, HEAD, dirty state, and required subpath coverage before the user
+selects one. Do not modify, switch, clean, or pull the selected checkout.
+
+For a clone, show the registered remote, pinned commit, target directory, and
+the logical modules that will share it. The clone restores the recorded source
+version; it does not silently advance to the latest branch.
+
+After recovery, summarize reused and cloned checkouts, actual commits, restored
+module links, and any remaining permission or missing-subpath blockers.

package/providers/context/resources/manuals/guides/lark-resources.md

@@ -0,0 +1,121 @@
+---
+id: context.sdk.lark-resources
+kind: procedure
+mediaType: text/markdown
+---
+
+# Lark Resource Materialization
+
+Lark documents can contain evidence that is not present in the readable text
+body. Context handles these resources mechanically during `captureLark`; the
+Agent does not download, summarize, or reconstruct them itself.
+
+## Resource policy
+
+| Resource | Default capture behavior |
+|---|---|
+| Image and attachment | Download the original file and link it from the Markdown projection. |
+| Sheet | Read the complete selected sheet, render a Markdown table, and retain a CSV snapshot. |
+| Base | Read the selected table/view with pagination, render a Markdown table, and retain a canonical JSON snapshot. |
+| Whiteboard and diagram | Retain a readable preview plus the raw structured export. |
+| Synced block | Resolve the exact source block, project its body, and retain a Markdown evidence snapshot. |
+| Poll | Preserve exported options and metadata as non-interactive Markdown; warn when the export omits them. |
+| Bookmark, citation, sub-document, chat, and generic embed | Preserve a stable navigation reference and provenance. |
+| Video | Preserve a stable reference by default; download only when `resources.videos` is `bundle`. |
+
+Required inline resources fail closed when their stable identity, bytes, or
+complete structured data cannot be obtained. When the remote API explicitly
+confirms that a referenced whiteboard or diagram no longer exists, Context
+preserves an unavailable-resource notice with the reason code
+`document.resource.source-missing`, reports a warning, and continues capture;
+it does not pretend that the deleted content was materialized. When the current
+identity can read the document body but the API explicitly returns
+`authorization/permission_denied` for an embedded resource, Context records
+`document.resource.permission-denied`, keeps the stable resource identity in
+the audit layer, renders the same unavailable-resource notice, and continues
+with a warning. Missing scopes, transient network errors, malformed payloads,
+and unclassified authorization failures still block capture. Reference-only
+resources remain explicit in the capture report. Unknown non-empty XML blocks
+stay auditable in the raw XML and receive a warning; the CLI does not infer
+their meaning.
+
+## Storage lifecycle
+
+Resources have three distinct locations:
+
+```text
+sources/lark/<date>/
+├── <module>.md
+├── manifest.json
+└── assets/<module>/
+    ├── source.xml
+    ├── capture-report.json
+    └── materialized/**
+knowledge/assets/<resource-kind>/<content-sha256>.<ext>
+dist/<package>/others/assets/<resource-kind>/<content-sha256>.<ext>
+```
+
+- `sources/` is the captured source and audit layer. `source.xml` preserves the
+  structured source, one `capture-report.json` closes fidelity and resource
+  handling for the document, and `materialized/` contains downloaded files and
+  structured exports. Resource descriptors are consolidated in the report;
+  capture does not create one metadata file per embedded resource.
+- The date-level `manifest.json` is a compact inventory. It records hashes,
+  asset roles, the report path, and status summaries without duplicating the
+  complete report.
+- `knowledge/assets/` contains only resources referenced by approved pages.
+  Paths are content-addressed, so identical bytes are reused and changed bytes
+  produce a new identity. Review apply rewrites page links mechanically;
+  verification compares the underlying content identity, so this deterministic
+  path projection does not count as a change to a verbatim section.
+  Markdown files below `knowledge/assets/` remain evidence resources and are
+  never interpreted as approved knowledge pages or structure views.
+- `others/assets/` is the portable package projection. Build copies only
+  resources referenced by selected package pages and rewrites their relative
+  links. Audit-only source files are not distributed.
+
+Deleting an approved page allows unreferenced `knowledge/assets` files to be
+cleaned. A missing approved or packaged resource is a verification error rather
+than a silent broken link.
+
+Source assets are part of the reproducible evidence snapshot and should not be
+ignored when the workspace is versioned. Repositories with many binary source
+assets can use Git LFS for `materialized/` while keeping Markdown, XML, JSON, and
+CSV directly reviewable in Git. The workspace must remain private when the
+captured source or screenshots are access-controlled.
+
+## SDK configuration
+
+Defaults are suitable for ordinary documents:
+
+```ts
+captureLark({ source: handbook });
+```
+
+Projects can opt into bundled video and adjust deterministic byte limits:
+
+```ts
+captureLark({
+  source: handbook,
+  resources: {
+    videos: "bundle",
+    maxBytesPerResource: 20 * 1024 * 1024,
+    maxTotalBytes: 200 * 1024 * 1024,
+  },
+});
+```
+
+The limits are capture constraints, not semantic filters. Context does not
+decide which resources are important from their business content.
+
+## Agent behavior
+
+Use the capture command returned by the current Route. Inspect the structured
+resource summary and fidelity diagnostics; do not manually edit `sources/`,
+`knowledge/assets/`, or package links. Required materialization failures other
+than a confirmed source-side deletion or an explicit resource-level permission
+denial must be resolved by recapturing after access or source problems are
+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.

package/providers/context/resources/manuals/guides/package-outputs.md

@@ -67,6 +67,7 @@ wikis/index.md
 guides/...
 rules/...
 feats/...
+others/assets/...
 ```
 
 Do not ask for another distribution namespace. Older workspaces may still
@@ -94,6 +95,13 @@ package needs project-specific terminology, entry points, known limits, or
 task workflows. Authors may explicitly accept the generic default when it is
 intentionally sufficient.
 
+When approved pages reference materialized document resources, Context keeps
+their production copies in content-addressed `knowledge/assets/` paths. Build
+copies only the resources selected by package pages to `others/assets/` and
+rewrites relative Markdown links. Source audit XML and capture reports stay in
+the production workspace; they are not distributed as reader assets. See
+[Lark Resource Materialization](./lark-resources.md).
+
 The same inventory exposes `structure.relationship_coverage`. It records
 whether selected codegraph pages have current source-backed AST relationship
 metadata, how many codegraph views were selected, and how many package-visible