@c4a/context-cli 0.6.3 → 0.6.5

package/docs/context-debug-event-v1.schema.json

@@ -19,6 +19,8 @@
         "agent-graph.evaluated",
         "workflow.action-started",
         "workflow.action-completed",
+        "workflow.scope-opened",
+        "workflow.scope-closed",
         "workflow.stopped"
       ]
     },

package/docs/debug-tracing.md

@@ -55,6 +55,9 @@ The event stream records:
 - Agent Graph evaluation revision, status, selected route, alternatives, and
   whether the observable graph position changed;
 - managed workflow action start and completion with deterministic receipts;
+- execution-scope open and close events, including whether a deterministic
+  action ran in-process or in a child process and whether every short-lived
+  resource was released;
 - the reason and graph position at which a managed loop stopped.
 
 `trace_id` groups the workspace-local debug history, `sequence` defines replay order,
@@ -64,6 +67,11 @@ can animate `agent-graph.evaluated` events whose `data.transition.changed` is
 true, then associate intervening command and action events by sequence and
 invocation identity.
 
+Execution-scope events are runtime evidence, not workflow facts. They make
+resource ownership and cleanup observable without changing a Route or adding
+workspace state. Durable knowledge mutations are still audited through the
+normal action receipt, revision, close, and verify results.
+
 ## Inspect and export
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "type": "module",
   "description": "Local CLI for capturing, compiling, and governing knowledge workspaces",
   "license": "MIT",
@@ -20,11 +20,11 @@
     "node": ">=20"
   },
   "bin": {
-    "context": "dist/cli.js"
+    "context": "cli.js"
   },
   "dependencies": {
-    "@c4a/agent-graph": "0.2.4",
-    "@c4a/context": "0.6.3",
+    "@c4a/agent-graph": "0.2.5",
+    "@c4a/context": "0.6.5",
     "commander": "^11.0.0",
     "fast-xml-parser": "^5.10.1",
     "handlebars": "^4.7.8",

package/plugins/VERSION

@@ -1 +1 @@
-0.6.3
+0.6.5

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

@@ -1,7 +1,7 @@
 {
   "name": "context",
   "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "author": {
     "name": "c4a"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
   "author": {
     "name": "c4a"
@@ -18,7 +18,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.6.3",
+    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.6.5",
     "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/cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "context",
   "displayName": "C4A Context",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
   "author": {
     "name": "Context4AI",

package/providers/context/actions/inspect-code-extraction.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: inspect-code-extraction
+runner: host
+effect: read
+handler: context.extract.inspect-capabilities

package/providers/context/graphs/workspace.yaml

@@ -289,6 +289,7 @@ nodes:
   - id: choose-extraction-scope
     kind: gate
     reasonCode: route.extract.scope-required
+    inspectionAction: actions/inspect-code-extraction.yaml
     gate:
       id: extraction-scope
       prompt: Confirm which registered code modules and symbol boundaries should enter code knowledge.
@@ -318,7 +319,7 @@ nodes:
         - resources/procedures/project-configuration.md
         - resources/procedures/code-extraction.md
         - resources/views/source-current.yaml
-        - resources/manuals/reference/project-api.md
+        - resources/manuals/reference/code-extractors.md
 
   - id: extract-next
     kind: action

package/providers/context/manifest.json

@@ -2,14 +2,14 @@
   "schema": "agent-graph.bundle.v1",
   "provider": {
     "id": "c4a/context",
-    "version": "0.6.3"
+    "version": "0.6.5"
   },
   "providerManifest": "provider.yaml",
   "graphs": [
     {
       "id": "workspace",
       "path": "graphs/workspace.yaml",
-      "digest": "sha256:98b74bb6a59a9024978209e70c2519bd3608ea77b7576326685576184947898f"
+      "digest": "sha256:83c1b8feb410398a34051810cbefffe8fc86dd44211d32e049d3007ecea24d7e"
     }
   ],
   "actions": [
@@ -78,6 +78,11 @@
       "path": "actions/extract-next.yaml",
       "digest": "sha256:3d5e26cbdd912c9be666ce423b19456b31ab67da53c4e01a1a1c7a3dc1e6420a"
     },
+    {
+      "id": "inspect-code-extraction",
+      "path": "actions/inspect-code-extraction.yaml",
+      "digest": "sha256:214cf9b0f9645ec7164a779ab5779ccf5b3e3132b10f8f9f666213d048f582b1"
+    },
     {
       "id": "inspect-document-classification",
       "path": "actions/inspect-document-classification.yaml",
@@ -158,17 +163,17 @@
     {
       "id": "context.sdk.package-outputs",
       "path": "resources/manuals/guides/package-outputs.md",
-      "digest": "sha256:32337aae19ba17ec01fc6da04a40cec9aab4ba4ee7561d8073e600d601b560ae"
+      "digest": "sha256:dd9e8c21ece757a683b9ebf219d3bd6235b9a0ada43b537f143b3f2eacbb8eb9"
     },
     {
       "id": "context.sdk.package-templates",
       "path": "resources/manuals/reference/package-templates.md",
-      "digest": "sha256:32d5fd550304d76fe011aadce4abcb0321f656c710cbeb91d964b463316561d5"
+      "digest": "sha256:c42ea22df144db608ab5dc3718704b2e42c0e7a4fe51ca322dfbe705f0619549"
     },
     {
       "id": "context.sdk.project-api",
       "path": "resources/manuals/reference/project-api.md",
-      "digest": "sha256:3dd8dfa54ba4b34a31d0a284385c77992f84ad2d7ef46583ff34683aae4081ac"
+      "digest": "sha256:0e21f44f9c239abf176da0bcf4094f2b1d0085f31240b97b85a8b44d4633493e"
     },
     {
       "id": "context.sdk.template-variables",
@@ -178,7 +183,7 @@
     {
       "id": "context.semantic.align.align-gates",
       "path": "resources/semantic/align/gates.md",
-      "digest": "sha256:b3982f5104418ba9a9a9b600f362cf83dba6d0becbb4efd128fe1eea89eba727"
+      "digest": "sha256:517be59f675022a5d9e3fa04f9b35f801a80fc32aa42084dac8bce8a45481fea"
     },
     {
       "id": "context.semantic.align.candidate-resolution",
@@ -193,7 +198,7 @@
     {
       "id": "context.semantic.align.structure-planning",
       "path": "resources/semantic/align/structure-planning.md",
-      "digest": "sha256:c6d8902f7f70857596d3486307bb5e58ffaac6efd6021451e487c92ceb86f87d"
+      "digest": "sha256:73d7d1cb49ad27691e7baa29003fa1736fc8a7036c6094f40f733e62fd3c1aad"
     },
     {
       "id": "context.semantic.compile.index",
@@ -243,7 +248,7 @@
     {
       "id": "dialogue.code-extraction",
       "path": "resources/dialogue/code-extraction.md",
-      "digest": "sha256:367c845da3ebab0354d77918170101ee9d5e6aa19700d33db2cbeffffb6b5b70"
+      "digest": "sha256:5aa3b52dcf9cd9bd058baea7dadb123eead162a1ec7640cc63c7c359e71922e3"
     },
     {
       "id": "dialogue.document-capture",
@@ -273,7 +278,7 @@
     {
       "id": "dialogue.package-output",
       "path": "resources/dialogue/package-output.md",
-      "digest": "sha256:0ca7a9e56397f9acc62d92777d91e0203e2d6caa7f08268dca8037987e5911a5"
+      "digest": "sha256:fcf64598b9a505c764ae4984ff4d63a7010143f749ba454e220752f737306612"
     },
     {
       "id": "dialogue.repository-source-recovery",
@@ -290,6 +295,11 @@
       "path": "resources/dialogue/structure-confirmation.md",
       "digest": "sha256:4f9667860bb555c2cf236237c5a21644b7a2b249a452337d83087fa4c389dc2d"
     },
+    {
+      "id": "manual.reference.code-extractors",
+      "path": "resources/manuals/reference/code-extractors.md",
+      "digest": "sha256:6af1a9ea24b59bd5cb2125296e04d19529c92be77910e5e768251e6c4bd7902a"
+    },
     {
       "id": "procedure.close-and-build",
       "path": "resources/procedures/close-and-build.md",
@@ -298,7 +308,7 @@
     {
       "id": "procedure.code-extraction",
       "path": "resources/procedures/code-extraction.md",
-      "digest": "sha256:0563be260b3c37f1c7a1a9c831ba3a0c01a872ec3ddc64fd28d414e3c876f7e2"
+      "digest": "sha256:dce77b35fffbba51cbc8d6bc9d2abe2924229a6248eb9585b90e63ab9e05e37a"
     },
     {
       "id": "procedure.document-capture",
@@ -323,7 +333,7 @@
     {
       "id": "procedure.package-output",
       "path": "resources/procedures/package-output.md",
-      "digest": "sha256:c088c2341fa64caa25a04c3cef75635b2f635a932bfc7326b35cff59fc390b29"
+      "digest": "sha256:5d93de483e668fe77c5eaabb3ae52d4d9c36f73b61e264fd40d53f7f4d008bf8"
     },
     {
       "id": "procedure.project-configuration",
@@ -436,6 +446,10 @@
       "path": "actions/extract-next.yaml",
       "digest": "sha256:3d5e26cbdd912c9be666ce423b19456b31ab67da53c4e01a1a1c7a3dc1e6420a"
     },
+    {
+      "path": "actions/inspect-code-extraction.yaml",
+      "digest": "sha256:214cf9b0f9645ec7164a779ab5779ccf5b3e3132b10f8f9f666213d048f582b1"
+    },
     {
       "path": "actions/inspect-document-classification.yaml",
       "digest": "sha256:973889832e3adfba4fa019b3dfadda35fe22536c44ef97efba2299e6cdd65786"
@@ -490,11 +504,11 @@
     },
     {
       "path": "graphs/workspace.yaml",
-      "digest": "sha256:98b74bb6a59a9024978209e70c2519bd3608ea77b7576326685576184947898f"
+      "digest": "sha256:83c1b8feb410398a34051810cbefffe8fc86dd44211d32e049d3007ecea24d7e"
     },
     {
       "path": "provider.yaml",
-      "digest": "sha256:42dbd41c64f6ef7cc2f22a7aeef5be12c8e8619ca31f48050a3de4e449fbf043"
+      "digest": "sha256:bcf4649a83ca09e4562f83ab8919bdfcaa1134866706506876ce6172a393856c"
     },
     {
       "path": "resources/diagnostics/projection-stale.md",
@@ -510,7 +524,7 @@
     },
     {
       "path": "resources/dialogue/code-extraction.md",
-      "digest": "sha256:367c845da3ebab0354d77918170101ee9d5e6aa19700d33db2cbeffffb6b5b70"
+      "digest": "sha256:5aa3b52dcf9cd9bd058baea7dadb123eead162a1ec7640cc63c7c359e71922e3"
     },
     {
       "path": "resources/dialogue/document-capture.md",
@@ -534,7 +548,7 @@
     },
     {
       "path": "resources/dialogue/package-output.md",
-      "digest": "sha256:0ca7a9e56397f9acc62d92777d91e0203e2d6caa7f08268dca8037987e5911a5"
+      "digest": "sha256:fcf64598b9a505c764ae4984ff4d63a7010143f749ba454e220752f737306612"
     },
     {
       "path": "resources/dialogue/repository-source-recovery.md",
@@ -554,15 +568,19 @@
     },
     {
       "path": "resources/manuals/guides/package-outputs.md",
-      "digest": "sha256:32337aae19ba17ec01fc6da04a40cec9aab4ba4ee7561d8073e600d601b560ae"
+      "digest": "sha256:dd9e8c21ece757a683b9ebf219d3bd6235b9a0ada43b537f143b3f2eacbb8eb9"
+    },
+    {
+      "path": "resources/manuals/reference/code-extractors.md",
+      "digest": "sha256:6af1a9ea24b59bd5cb2125296e04d19529c92be77910e5e768251e6c4bd7902a"
     },
     {
       "path": "resources/manuals/reference/package-templates.md",
-      "digest": "sha256:32d5fd550304d76fe011aadce4abcb0321f656c710cbeb91d964b463316561d5"
+      "digest": "sha256:c42ea22df144db608ab5dc3718704b2e42c0e7a4fe51ca322dfbe705f0619549"
     },
     {
       "path": "resources/manuals/reference/project-api.md",
-      "digest": "sha256:3dd8dfa54ba4b34a31d0a284385c77992f84ad2d7ef46583ff34683aae4081ac"
+      "digest": "sha256:0e21f44f9c239abf176da0bcf4094f2b1d0085f31240b97b85a8b44d4633493e"
     },
     {
       "path": "resources/manuals/reference/template-variables.md",
@@ -574,7 +592,7 @@
     },
     {
       "path": "resources/procedures/code-extraction.md",
-      "digest": "sha256:0563be260b3c37f1c7a1a9c831ba3a0c01a872ec3ddc64fd28d414e3c876f7e2"
+      "digest": "sha256:dce77b35fffbba51cbc8d6bc9d2abe2924229a6248eb9585b90e63ab9e05e37a"
     },
     {
       "path": "resources/procedures/document-capture.md",
@@ -594,7 +612,7 @@
     },
     {
       "path": "resources/procedures/package-output.md",
-      "digest": "sha256:c088c2341fa64caa25a04c3cef75635b2f635a932bfc7326b35cff59fc390b29"
+      "digest": "sha256:5d93de483e668fe77c5eaabb3ae52d4d9c36f73b61e264fd40d53f7f4d008bf8"
     },
     {
       "path": "resources/procedures/project-configuration.md",
@@ -634,11 +652,11 @@
     },
     {
       "path": "resources/semantic/align/gates.md",
-      "digest": "sha256:b3982f5104418ba9a9a9b600f362cf83dba6d0becbb4efd128fe1eea89eba727"
+      "digest": "sha256:517be59f675022a5d9e3fa04f9b35f801a80fc32aa42084dac8bce8a45481fea"
     },
     {
       "path": "resources/semantic/align/structure-planning.md",
-      "digest": "sha256:c6d8902f7f70857596d3486307bb5e58ffaac6efd6021451e487c92ceb86f87d"
+      "digest": "sha256:73d7d1cb49ad27691e7baa29003fa1736fc8a7036c6094f40f733e62fd3c1aad"
     },
     {
       "path": "resources/semantic/compile/index.md",
@@ -696,5 +714,5 @@
   "graphDependencies": {
     "workspace": []
   },
-  "digest": "sha256:9a4fdc41e173bd8f98d12428c0ef0f03e00a62a588bedfb58ad52ef6b589317c"
+  "digest": "sha256:b6e58683cf5ef86192337938b45e2bc4cbafb2512944786e9ab9e76a438dfa94"
 }

package/providers/context/provider.yaml

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

package/providers/context/resources/dialogue/code-extraction.md

@@ -16,11 +16,22 @@ Describe the proposed code scope before SDK fields. State:
 - that the first run or later deltas produce Review candidates rather than
   approved Markdown.
 
+Also state the inspected manifest signals and the chosen extractor in one
+sentence. Say whether the selected capability covers the module directly or
+whether a project-owned adapter supplies the missing mapping. Do not ask the
+user to choose between parser package names unless two genuinely incompatible
+technical choices remain.
+
 If a selected package lacks a standard entry, offer two Context-owned choices:
 configure source-relative API roots, or use scan mode for all declarations in
 the confirmed file scope. Do not ask the user to change source code or package
 metadata to satisfy Context.
 
+For a non-TypeScript source or an aggregated repository protocol, explain that
+the project will use `extractCustom()`. If an optional structural extractor is
+available, use it for syntax facts and keep project-specific classification in
+the project callback; do not imply that installing it adds a new CLI phase.
+
 Run the route-selected dry-run first. Report discovered, AST-analyzed, skipped,
 symbol, relation, and candidate counts separately, plus resolved entries,
 exported/internal counts, symbol-kind counts, and the proposed knowledge tree.

package/providers/context/resources/dialogue/package-output.md

@@ -25,6 +25,15 @@ package namespace. Ask whether Skills need a short optional prefix, then
 maintain their complete final names in the template. Do not expose downstream
 layout terminology or ask for platform-specific identity fields.
 
+Also ask how referenced resources should be delivered. Offer Git raw links,
+bundled files, or explicit omission. Git raw may derive a commit-pinned GitHub
+URL when the workspace is in Git, or use an author-provided HTTPS `urlPrefix`
+for resources published from another repository. A literal branch in that
+prefix is an explicit project choice, not a Context default. If neither local
+Git nor an explicit prefix is available, offer only bundle or omit.
+State that publishing the referenced resources and making private raw hosts
+reachable are the package author's responsibility; Context does not probe them.
+
 Do not offer a hidden `both` shortcut. If the user wants multiple outputs,
 declare and inspect one first, then obtain confirmation for the next. Mention
 `kbPackage` and `llmsPackage` only after the semantic output choice.

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

@@ -96,11 +96,25 @@ 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).
+their production copies in content-addressed `knowledge/assets/` paths. New KB
+setup should offer Git raw delivery first. It rewrites package links to either
+an automatically derived raw prefix or an explicit author-provided prefix.
+Context does not check whether resource files are committed, pushed, or
+remotely readable; that is the package author's responsibility. With no
+explicit prefix, supported remotes use an immutable commit URL. An explicit
+prefix can contain `{commit}` when the Context workspace is in Git, or name a
+mutable branch when that lifecycle is intentional; a literal prefix also works
+when resources are published from a separate repository.
+
+Workspaces without usable Git or an explicit raw prefix can choose bundled
+delivery, which copies only selected resources to `others/assets/`, or explicit
+omission, which does not copy resources and reports that links remain
+unresolved. Bundled output may
+optionally install `sharp` in the workspace and configure
+`assets.optimize`; Context itself has no image dependency. Optimization changes
+only `dist/`, content-addresses smaller WebP output, and leaves `sources/` and
+`knowledge/assets/` unchanged. Source audit XML and capture reports are never
+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

package/providers/context/resources/manuals/reference/code-extractors.md

@@ -0,0 +1,94 @@
+---
+id: manual.reference.code-extractors
+kind: procedure
+mediaType: text/markdown
+---
+
+# Code Extractor Selection
+
+Use this manual only when the current code-extraction Route asks the Agent to
+choose or declare an extractor. The CLI reports repository facts; the Agent
+chooses how those facts become source-backed code knowledge.
+
+## Inspect Before Declaring
+
+Run every read-only inspection command returned by the extraction-scope Gate.
+The result identifies each confirmed module and its recognized `manifests`.
+Treat these as deterministic technology signals, not as product semantics:
+
+| Signal | Technology candidate |
+|---|---|
+| `package.json` | TypeScript, TSX, JavaScript, or JSX |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `pyproject.toml` or `setup.py` | Python |
+| `pom.xml` or `build.gradle` | Java or JVM |
+| multiple manifests | a mixed module that may need more than one extractor |
+
+Do not select `extractTs()` merely because a repository contains some
+TypeScript. Decide against the exact confirmed module and include boundary. A
+mixed module may compose multiple structural passes; parser selection is not an
+exclusive repository-wide switch.
+
+## Selection Order
+
+Use the narrowest reusable capability that covers the confirmed source:
+
+1. Use a Context-owned phase when its contract matches the source.
+2. Otherwise use a reusable structural package inside `extractCustom()`.
+3. If no reusable package covers the syntax or repository protocol, implement a
+   project-owned adapter and keep it in the Context workspace.
+
+Current reusable capabilities are:
+
+| Source fact | Preferred capability | Lifecycle integration |
+|---|---|---|
+| TypeScript/TSX package or file scope | `extractTs()` | Context-owned phase |
+| Go declarations, imports, calls, and common HTTP routes | `@c4a/extract-go` | call from `extractCustom()` |
+| Rush workspace packages, tags, dependencies, entries, and owners | `@c4a/extract-rush` | call from `extractCustom()`; may complement a language extractor |
+| React Router route declarations | `extractReactRouterRoutes()` from `@c4a/extract-ts` | call from `extractCustom()`; complements TypeScript symbols |
+| Rust, Python, Java/JVM, or an unsupported framework/protocol | no assumed built-in parser | project-owned `extractCustom()` adapter |
+
+An optional package does not create a new CLI phase. Add it as an explicit
+workspace dependency, then map its structural facts to candidates in the
+project callback. Do not add a parser package when its documented coverage does
+not match the inspected source.
+
+## Read The Contract Before Extending
+
+Before editing `src/index.ts`, read the relevant installed public manual or
+package README. Do not infer APIs from bundled JavaScript.
+
+- Context lifecycle and `extractCustom()`:
+  `node_modules/@c4a/context/docs/reference/project-api.md`
+- Generic plugin protocol:
+  `node_modules/@c4a/extract/README.md`
+- TypeScript:
+  `node_modules/@c4a/extract-ts/README.md`
+- Go:
+  `node_modules/@c4a/extract-go/README.md`
+- Rush:
+  `node_modules/@c4a/extract-rush/README.md`
+
+If an optional package is not installed, use this capability matrix to decide
+whether it is relevant, add only that dependency, and then read its shipped
+README before implementing the callback.
+
+A project-owned adapter may use an existing parser, compiler API, or command
+whose output is deterministic. It must return source-backed candidates through
+`extractCustom()`; it must not write lifecycle, knowledge, or Review files.
+Framework-specific classification and rendering remain in the project. The CLI
+and structural parser must not infer product meaning.
+
+## Decision To Report
+
+Before the first extraction preview, state briefly:
+
+- the inspected module and manifest signals;
+- the selected Context phase or structural package;
+- whether coverage is complete or which facts remain project-owned; and
+- why another available extractor is not needed.
+
+If no current capability can parse the source reliably, stop at configuration
+and report the missing generic capability. Do not silently emit an empty
+codegraph or reuse an unrelated parser.

package/providers/context/resources/manuals/reference/package-templates.md

@@ -37,6 +37,10 @@ kbPackage({
     foldDirectoryIndexes: true,
     maxInlineEntries: 50,
   },
+  assets: {
+    delivery: "git-raw",
+    urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
+  },
 });
 ```
 
@@ -58,8 +62,67 @@ llmsPackage({
 | `template` | yes | Project-relative template directory or `{ path, vars }`. |
 | `select` | no | Approved knowledge selector. Omit to include all approved knowledge. Supports internal `collections`, OKF `okfRoots`, and `include` / `exclude` path patterns relative to `knowledge/`. |
 | `navigation` | no | KB directory-index policy. Defaults to `{ foldDirectoryIndexes: true, maxInlineEntries: 50 }`. |
+| `assets` | no | Resource delivery: Git raw links, bundled files, or explicit omission. New KB setup should offer Git raw first. Omit for legacy byte-for-byte bundling. |
 | `distribution` | no | Legacy input accepted from older workspaces. It no longer changes package paths and should not be added to new declarations. |
 
+Use Git raw delivery when resources are published from a Git repository.
+Without `urlPrefix`, the Context workspace must be inside Git; GitHub remotes
+are derived automatically and pinned to the current commit. Other hosts accept
+an explicit HTTPS prefix. `{commit}` is replaced only when the workspace is
+inside Git, because Context must resolve the current commit. A workspace outside
+Git must use a literal, already-published prefix without `{commit}`. Context
+appends the project-relative `knowledge/assets/...` path.
+
+The resolved commit and raw URL participate in package freshness, so changing
+Git HEAD or the selected remote makes an existing package stale. Context does
+not check whether resources are committed, pushed, or remotely readable;
+publishing them is the package author's responsibility. A literal branch in the
+prefix is allowed but intentionally follows that mutable branch. The configured
+raw host must be reachable by the eventual package consumers.
+
+```ts
+assets: {
+  delivery: "git-raw",
+  urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
+}
+```
+
+Outside Git, use a literal published prefix or choose bundled delivery or
+explicit omission:
+
+```ts
+assets: {
+  delivery: "git-raw",
+  urlPrefix: "https://code.example.com/team/knowledge/raw/published-assets",
+}
+```
+
+```ts
+assets: { delivery: "bundle" }
+assets: { delivery: "omit" } // keeps unresolved links and reports them
+```
+
+Bundled resources are copied byte-for-byte unless image optimization is
+configured. When optimizable PNG/JPEG resources exceed 20 MiB, build and status
+return `package.assets.optimization-recommended`. To optimize bundled output:
+
+```bash
+bun add -D sharp
+```
+
+```ts
+assets: {
+  delivery: "bundle",
+  optimize: { processor: "sharp", mode: "lossless-webp" },
+}
+```
+
+`optimize.mode: "webp"` additionally accepts `quality` from 1 to 100. Both modes accept
+an optional positive `maxDimension`; images are never enlarged. Context adopts
+a generated image only when it is smaller, uses a digest-derived `.webp` path,
+and rewrites package links. A configured but missing processor blocks before
+the previous `dist/` package is replaced.
+
 `template` is required. Do not call `kbPackage({ name })` or
 `llmsPackage({ name })`.
 

package/providers/context/resources/manuals/reference/project-api.md

@@ -745,6 +745,41 @@ Review summary and source-backed evidence). It must not write `knowledge/`,
 Review snapshots directly. Context owns those files and preserves rejected and
 unchanged-approved decisions across reruns.
 
+#### Optional structural extractors
+
+For the manifest-to-capability decision and unsupported-language extension
+boundary, read [Code Extractor Selection](./code-extractors.md) before declaring
+the phase.
+
+`extractCustom()` may consume optional community packages without making them
+Context CLI dependencies:
+
+```ts
+import { indexGoRepository } from "@c4a/extract-go";
+import { extractCustom } from "@c4a/context";
+
+extractCustom({
+  id: "extract:service:codegraph",
+  sources: [service],
+  collection: "codegraph",
+  extract: async ({ projectRoot }) => {
+    const facts = await indexGoRepository(resolveServiceCheckout(projectRoot));
+    return { candidates: buildServiceCandidates(facts) };
+  },
+});
+```
+
+Available structural libraries include:
+
+- `@c4a/extract-go`: Go declarations, imports, calls, and common HTTP routes;
+- `@c4a/extract-rush`: Rush projects, tags, entries, dependencies, and owners;
+- `@c4a/extract-ts`: TypeScript extraction and `extractReactRouterRoutes()`.
+
+The packages return syntax and repository facts only. They do not classify
+product meaning, choose candidate identities, or write lifecycle state. The
+knowledge project owns that mapping. Context CLI does not auto-install these
+packages and does not expose a built-in Go or Rush phase.
+
 ### `reviewValidity`
 
 Declare the review step for a collection: