@c4a/context 0.6.2 → 0.6.4

package/README.md

@@ -67,6 +67,21 @@ code extractor. Use `customPhase()` only for orchestration that does not publish
 knowledge candidates; it is not a replacement for source, extraction, Review,
 and package lifecycle rules.
 
+Context CLI intentionally does not bundle every language or repository parser.
+Optional structural libraries can be installed by the knowledge project and
+used inside `extractCustom()`:
+
+| Package | Structural facts |
+|---|---|
+| `@c4a/extract-go` | Go declarations, imports, calls, and common HTTP route registrations |
+| `@c4a/extract-rush` | Rush projects, tags, entry signals, workspace dependencies, and owner boundaries |
+| `@c4a/extract-ts` | TypeScript extraction plus reusable React Router route facts |
+
+These libraries do not create Context phases or candidates by themselves. The
+project maps their deterministic facts to its own candidate identities and
+review summaries; Context continues to own evidence validation, freshness,
+Review, close, and package output.
+
 ## Knowledge Collections
 
 Approved Markdown is organized under `knowledge/<collection>/`:
@@ -126,11 +141,27 @@ it is not repeated inside knowledge paths. Context still accepts
 no longer changes build output and new declarations do not need it. Skill names
 remain author-maintained and independent.
 
+New KB setup should offer `assets: { delivery: "git-raw" }` first. Build
+rewrites resource links to Git raw URLs; committing and publishing the resource
+files remains the package author's responsibility. Non-Git workspaces may use
+an explicit `urlPrefix`; without one they can bundle resources or explicitly
+omit them and retain unresolved references. Bundled delivery may
+install `sharp` in the workspace and configure `assets.optimize`; Context
+itself has no image dependency and never changes source snapshots or approved
+resources.
+
 For advanced routing and retrieval, a template may carry a local script such as
 `query.ts`, with a Skill describing when and how an Agent should call it. The
 Skill can also route the Agent to MCP servers, CLI commands, or other tools to
 form a package-specific Agentic Search workflow.
 
+Long-lived, multi-source production workspaces can copy
+`templates/project-skills/maintain-project-knowledge/SKILL.md` into their
+`.agents/skills/` directory and customize it with project ownership, source
+impact mappings, and readiness criteria. This project adapter is not included
+in knowledge packages; lifecycle authority remains with the installed Context
+Skill and current Route.
+
 ## State Boundary
 
 The SDK stays declarative. It may describe reads, writes, phases, review, and
@@ -147,5 +178,6 @@ state. The CLI owns that runtime state and removes it after a successful close.
 - [Agent Guide](./docs/guides/agent-guide.md)
 - [Project API](./docs/reference/project-api.md)
 - [Package Outputs](./docs/guides/package-outputs.md)
+- [Lark Resource Materialization](./docs/guides/lark-resources.md)
 - [Package Templates](./docs/reference/package-templates.md)
 - [Template Variables](./docs/reference/template-variables.md)

package/README.zh-CN.md

@@ -57,6 +57,18 @@ export default defineProject({
 非 TypeScript 或需要聚合代码事实时使用 `extractCustom()`。`customPhase()`
 只用于不发布知识候选的项目专用编排，不能绕开来源、提取、审核和打包生命周期。
 
+Context CLI 不会把所有语言和仓库解析器都打入自身。知识项目可以按需安装结构
+提取库，并在 `extractCustom()` 中使用：
+
+| 包 | 提供的结构事实 |
+|---|---|
+| `@c4a/extract-go` | Go 声明、导入、调用和常见 HTTP 路由注册 |
+| `@c4a/extract-rush` | Rush 项目、标签、入口信号、工作区依赖和所有者边界 |
+| `@c4a/extract-ts` | TypeScript 提取，以及可复用的 React Router 路由事实 |
+
+这些库本身不会创建 Context 阶段或候选。项目负责把确定性事实映射为自己的候选
+身份和审核摘要；证据校验、新鲜度、审核、close 和打包仍由 Context 管理。
+
 ## 知识分类
 
 审核通过的 Markdown 会存放在 `knowledge/<collection>/`：
@@ -104,8 +116,21 @@ kb/
 `distribution.knowledgeNamespace` 仍可被读取，但不再改变构建结果；新声明无需配置它。
 Skill 名称继续由作者独立维护。
 
+新建 KB 时优先选择 `assets: { delivery: "git-raw" }`：构建器把资源链接改写到
+Git raw 地址；资源的提交和发布由知识包作者负责，Context 不做远端探测。
+非 Git 工作区也可以配置显式 `urlPrefix`，引用另一个仓库已经发布的资源；没有
+可用 Git 或显式前缀时，可选择 `delivery: "bundle"` 随包分发，或显式选择
+`delivery: "omit"` 不输出资源并保留失效引用。随包分发还可以在工作区安装 `sharp` 并通过
+`assets.optimize` 仅优化生成的知识包；Context 本身不依赖图片处理库。
+
 如果需要更强的路由和检索能力，模板可以携带 `query.ts` 一类本地脚本，再由 Skill 约定 Agent 何时、如何调用。Skill 也可以把 Agent 路由到 MCP、CLI 或其他工具，组成适合当前知识包的 Agentic Search 流程。
 
+长期维护、多来源的知识生产工作区可以从
+`templates/project-skills.zh-CN/maintain-project-knowledge/SKILL.md` 复制一份
+项目维护 Skill 到 `.agents/skills/`。它不进入知识包，而是补充项目专属的来源
+归属、仓库变化影响范围和准出标准；Context 生命周期仍由已安装的 Context Skill
+和当前 Route 负责。
+
 ## 状态边界
 
 SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识包选择，但来源物化、内容读取、代码提取、审核应用、正式知识写入、质量验证和构建都由 CLI 负责。不要通过直接编辑 `sources/`、`knowledge/`、`dist/` 或被忽略的 `.tmp/context-runtime/lifecycle/` 运行态来替代 CLI 生命周期操作；成功 close 后 CLI 会清理该运行态。
@@ -117,5 +142,6 @@ SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识
 - [Agent 指南](./docs/guides/agent-guide.md)
 - [项目 API](./docs/reference/project-api.md)
 - [知识包输出](./docs/guides/package-outputs.md)
+- [飞书资源物化](./docs/guides/lark-resources.md)
 - [知识包模板](./docs/reference/package-templates.md)
 - [模板变量](./docs/reference/template-variables.md)

package/docs/README.md

@@ -17,7 +17,9 @@ general reference; do not preload the whole manual set.
 - [Agent Guide](./guides/agent-guide.md) — what an agent should do, and what it should not inspect manually.
 - [Agent Dialogue](./guides/agent-dialogue.md) — stable dialogue principles and how route-selected gate resources are discovered.
 - [Package Outputs](./guides/package-outputs.md) — how to choose between an agent knowledge-base package, LLM text, or no package output.
+- [Lark Resource Materialization](./guides/lark-resources.md) — how embedded resources move from source evidence to approved knowledge and package assets.
 - [Project API](./reference/project-api.md) — `defineProject`, sources, phases, review, and packages.
+- [Code Extractor Selection](./reference/code-extractors.md) — inspect module technology signals and choose a built-in extractor, reusable structural package, or project adapter.
 - [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.
 - [Template Variables](./reference/template-variables.md) — Handlebars variables, loops, comments, and default knowledge inventories.
 
@@ -40,3 +42,15 @@ node_modules/@c4a/context/templates/package-templates/
 
 Copy or mirror these into a workspace under `src/package-templates/` when the
 project needs package outputs.
+
+Long-lived multi-source production workspaces may also start from the optional
+project-maintenance Skill template at:
+
+```text
+node_modules/@c4a/context/templates/project-skills/maintain-project-knowledge/SKILL.md
+```
+
+Copy it into the project's `.agents/skills/`, rename it for the project, and
+replace its project-fact and impact-map sections. It is a project adapter; it is
+not included in a built knowledge package and does not replace the installed
+Context Skill.

package/docs/getting-started.md

@@ -7,7 +7,7 @@ source boundary, then declare the matching phases in `src/index.ts`.
 ## 1. Initialize
 
 ```bash
-context init context --dev
+context init context
 cd context
 bun install
 context status --format json
@@ -18,10 +18,10 @@ generated README, AGENTS contract, and package starter templates should use a
 specific language. Context stores this choice in `package.json`; it does not
 guess from the shell locale or Agent conversation.
 
-Use `--dev` when testing a local link or prepared pack before the matching SDK
-version is published. It writes a `file:` dependency to the SDK resolved beside
-the active CLI. Published users can omit it and install the versioned SDK from
-the registry.
+Use `--dev` only when testing a locally linked CLI or a prepared package before
+the matching SDK version is published. It writes a `file:` dependency to the SDK
+resolved beside the active CLI. Registry installs should use the default command
+above so the workspace receives the matching versioned SDK dependency.
 
 Without `project-dir`, init uses the dedicated `context/` directory. Initializing
 inside a non-empty directory that is not already a Context workspace is blocked
@@ -187,8 +187,19 @@ and suggested `context source add` commands.
 
 Remote Git sources need the same boundary decision. Ask for the remote URL, the
 pinned commit/ref, and whether the user approves cloning. The CLI does not
-clone, checkout, reset, or fetch silently. If source material is missing or at
-the wrong ref, ask the user before running repo operations outside the CLI.
+clone, checkout, reset, or fetch silently. If registered source material is
+missing, the current Route exposes a repository recovery plan. The user chooses
+an existing checkout, a bounded local scan, or an explicit shallow/partial clone
+of the registered pinned commit. Context validates the remote, commit, and
+subpaths, restores local aliases, and materializes module links. Advancing to a
+new upstream commit remains a separate source-update decision.
+
+For a long-lived production workspace with project-specific source ownership or
+impact rules, copy the optional maintenance Skill template from
+`templates/project-skills/maintain-project-knowledge/SKILL.md` into the
+project's `.agents/skills/`, rename it for the project, and edit its project
+facts. Keep Context lifecycle commands in the installed Context Skill and
+current Route rather than duplicating them in the project Skill.
 
 ## 3. Declare The Flow
 

package/docs/guides/agent-guide.md

@@ -72,6 +72,13 @@ node_modules/@c4a/context/docs/reference/project-api.md
 node_modules/@c4a/context/docs/reference/package-templates.md
 ```
 
+When configuring code extraction, use the Route-selected
+`reference/code-extractors.md` manual. Run the Gate's read-only source
+inspection first, use its manifest signals to select a matching extractor, and
+read that package's public README before implementing an `extractCustom()`
+adapter. Do not probe compiled package output or treat TypeScript as the default
+for a non-TypeScript module.
+
 ## Workspace State Rules
 
 - `src/index.ts` declares sources, phases, and packages.
@@ -107,7 +114,7 @@ Present only the current workflow surface:
 | Task | Current route |
 |---|---|
 | Register a knowledge boundary | `context source add file/lark/repo ...`, followed by the matching project phase declaration. Source registration is a user-confirmed boundary decision. |
-| Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory and updates that directory's single `manifest.json`. |
+| Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory, updates that directory's single `manifest.json`, and mechanically materializes supported Lark resources. Do not download or rewrite embedded resources outside the CLI. |
 | Investigate captured material | Use `context status` and the returned `context run align:<type>:<source>:<collection> --view ...` commands. Evidence views drive reading; raw directory grep is not the workflow. |
 | Confirm prose structure | `alignProse` validates and stages CLI-managed lifecycle structure. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
 | Compile source-bound drafts | `compileProse` turns confirmed structure into source-bound draft pages. It does not approve knowledge. |

package/docs/guides/lark-resources.md

@@ -0,0 +1,115 @@
+# 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/docs/guides/package-outputs.md

@@ -61,6 +61,7 @@ wikis/index.md
 guides/...
 rules/...
 feats/...
+others/assets/...
 ```
 
 Do not ask for another distribution namespace. Older workspaces may still
@@ -88,6 +89,27 @@ 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. 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
 metadata, how many codegraph views were selected, and how many package-visible

package/docs/reference/code-extractors.md

@@ -0,0 +1,88 @@
+# 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/docs/reference/package-templates.md

@@ -31,6 +31,10 @@ kbPackage({
     foldDirectoryIndexes: true,
     maxInlineEntries: 50,
   },
+  assets: {
+    delivery: "git-raw",
+    urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
+  },
 });
 ```
 
@@ -52,8 +56,56 @@ 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 and
+workspaces outside Git accept an explicit HTTPS prefix; Context appends the
+project-relative `knowledge/assets/...` path. Context does not check whether
+the resources are committed, pushed, or remotely readable; publishing them is
+the package author's responsibility.
+`{commit}` is replaced when present. 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}",
+}
+```
+
+When the workspace is not in Git and has no explicit raw prefix, choose bundled
+delivery or explicit omission:
+
+```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/docs/reference/project-api.md

@@ -209,6 +209,13 @@ extraction phases, review gates, close/build, and packages explicitly. The CLI
 then routes work through `context status`, `context run <phase-id>`, `context
 review html/apply`, `context close`, `context verify`, and `context build`.
 
+For Agent and automation output, use `context verify --format json --compact`.
+It returns deterministic groups, counts, affected-scope totals, and a few
+representative samples instead of repeating every issue. Read the complete,
+auditable issue set only when needed with `context verify --view diagnostics
+--page-size 25 --format json`; follow its executable pagination command without
+inventing overlapping file ranges.
+
 ### Status declaration coverage
 
 `context status --format json --view full` includes a `declarationGraph` and
@@ -321,6 +328,21 @@ Markdown snapshot:
 captureLark({ source: handbook });
 ```
 
+Embedded resources are materialized with deterministic defaults. Video remains
+reference-only unless a project opts into bundling, and byte limits prevent an
+unexpected document from expanding the workspace without bound:
+
+```ts
+captureLark({
+  source: handbook,
+  resources: {
+    videos: "bundle",
+    maxBytesPerResource: 20 * 1024 * 1024,
+    maxTotalBytes: 200 * 1024 * 1024,
+  },
+});
+```
+
 Phase id:
 
 ```text
@@ -334,19 +356,33 @@ one date batch; when `--module` is omitted, the CLI derives an opaque,
 credential-safe module id. Capture reads the
 remote document through the CLI runner as structured Docx XML. Context keeps a
 redacted XML audit asset, projects supported blocks deterministically into
-readable Markdown, and registers external resources such as document citations,
-images, video, whiteboards, and Base references in the snapshot manifest even
-when their binary content is not downloaded. The projection does not infer or
-summarize document meaning. Its fidelity report closes discovered blocks
+readable Markdown, and materializes required inline resources such as images,
+attachments, Sheets, Bases, whiteboards, diagrams, and synced blocks. Navigation
+resources and default video capture remain explicit references. The projection
+does not infer or summarize document meaning. Its fidelity and resource reports close discovered blocks
 against converted and intentionally skipped blocks and reports evidence
 completeness separately from Markdown projection quality. Unknown non-empty XML
 blocks receive a generic, auditable, non-interactive projection and do not block
-downstream work. Missing source content or unresolved external-resource identity
-remains an evidence error and prevents downstream Review.
+downstream work. A remote whiteboard or diagram explicitly confirmed as deleted
+is preserved as an unavailable-resource notice with
+`document.resource.source-missing` and a warning. An embedded resource whose
+export is explicitly rejected as `authorization/permission_denied` is retained
+the same way with `document.resource.permission-denied`. Missing scopes,
+unresolved external-resource identity, retryable failures, and unclassified
+authorization errors remain evidence errors and prevent downstream Review.
 Snapshot files live under `sources/lark/<date>/` as sibling document files
-tracked by one date-level `manifest.json`. Access credentials and transient
+tracked by one compact date-level `manifest.json`. Each module keeps one raw
+`source.xml`, one consolidated `capture-report.json`, and its actual downloaded
+or structured resources under `assets/<module>/materialized/`; it does not emit
+one descriptor file per embedded resource. Access credentials and transient
 signed media URLs are not written into the workspace.
 
+Approved resource bytes are projected to content-addressed
+`knowledge/assets/<kind>/` paths. KB build copies selected resources to
+`others/assets/<kind>/` inside the package and rewrites page links. See
+[Lark Resource Materialization](../guides/lark-resources.md) for the complete
+resource table and storage lifecycle.
+
 Use a typed document reference in project declarations:
 
 ```ts
@@ -703,6 +739,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:

package/index.d.ts

@@ -22,6 +22,32 @@ export type PackageDistributionDefinition = {
     /** @deprecated Accepted for older workspaces; package output roots are flat. */
     knowledgeNamespace: string;
 };
+export type PackageAssetOptimizationDefinition = {
+    /** Image codec provider resolved from the Context workspace. */
+    processor: "sharp";
+    /** Lossless is the safe default; lossy WebP must be selected explicitly. */
+    mode?: "lossless-webp" | "webp";
+    /** WebP quality for lossy mode. */
+    quality?: number;
+    /** Optional longest-edge limit. Images are never enlarged. */
+    maxDimension?: number;
+};
+export type PackageAssetDefinition = {
+    /** Publish references to immutable Git-hosted resources instead of copying resource bytes. */
+    delivery: "git-raw";
+    /** Git remote used to derive the repository URL. */
+    remote?: string;
+    /** Optional HTTPS raw root. Context appends knowledge/assets/**; {commit} is supported. */
+    urlPrefix?: string;
+} | {
+    /** Copy resources into the package. */
+    delivery: "bundle";
+    /** Optional image optimization, resolved from the Context workspace. */
+    optimize?: PackageAssetOptimizationDefinition;
+} | {
+    /** Do not copy resources. Existing relative references remain unresolved. */
+    delivery: "omit";
+};
 export type BasePackageDefinition = {
     name: string;
     reads: readonly PhaseResourceReference[];
@@ -34,6 +60,7 @@ export type KbPackageDefinition = BasePackageDefinition & {
     kind: "package.kb";
     navigation: PackageNavigationDefinition;
     distribution?: PackageDistributionDefinition;
+    assets?: PackageAssetDefinition;
 };
 export type LlmsPackageDefinition = BasePackageDefinition & {
     kind: "package.llms";
@@ -55,6 +82,7 @@ export declare const kbPackage: (definition: {
     select?: PackageSelectDefinition;
     navigation?: Partial<PackageNavigationDefinition>;
     distribution?: PackageDistributionDefinition;
+    assets?: PackageAssetDefinition;
 }) => KbPackageDefinition;
 export declare const llmsPackage: (definition: {
     name: string;

package/index.js

@@ -7128,6 +7128,14 @@ var captureFile = (definition) => {
 var captureLark = (definition) => {
   const sourceDefinition = bindSourceType(definition.source, "lark", "captureLark source");
   const sourceId = getSourceName(sourceDefinition);
+  const maxBytesPerResource = definition.resources?.maxBytesPerResource ?? 20 * 1024 * 1024;
+  const maxTotalBytes = definition.resources?.maxTotalBytes ?? 200 * 1024 * 1024;
+  if (!Number.isSafeInteger(maxBytesPerResource) || maxBytesPerResource < 1) {
+    throw new TypeError("captureLark resources.maxBytesPerResource must be a positive safe integer");
+  }
+  if (!Number.isSafeInteger(maxTotalBytes) || maxTotalBytes < maxBytesPerResource) {
+    throw new TypeError("captureLark resources.maxTotalBytes must be a safe integer greater than or equal to maxBytesPerResource");
+  }
   return {
     kind: "phase.capture.lark",
     id: `capture:lark:${sourceId}`,
@@ -7136,7 +7144,12 @@ var captureLark = (definition) => {
       source: sourceDefinition
     }],
     writes: [sourceSnapshotResource(sourceDefinition, "lark")],
-    source: sourceDefinition
+    source: sourceDefinition,
+    resources: {
+      videos: definition.resources?.videos ?? "reference-only",
+      maxBytesPerResource,
+      maxTotalBytes
+    }
   };
 };
 var alignProse = (definition) => {
@@ -11901,6 +11914,58 @@ var normalizePackageDistribution = (distribution) => {
   }
   return { knowledgeNamespace };
 };
+var normalizePackageAssetOptimization = (assets) => {
+  if (assets.processor !== "sharp") {
+    throw new TypeError(`Package assets.optimize.processor must be "sharp": ${String(assets.processor)}`);
+  }
+  const mode = assets.mode ?? "lossless-webp";
+  if (mode !== "lossless-webp" && mode !== "webp") {
+    throw new TypeError(`Package assets.optimize.mode must be "lossless-webp" or "webp": ${String(mode)}`);
+  }
+  if (assets.quality !== undefined && (!Number.isSafeInteger(assets.quality) || assets.quality < 1 || assets.quality > 100)) {
+    throw new TypeError(`Package assets.optimize.quality must be a safe integer from 1 to 100: ${assets.quality}`);
+  }
+  if (mode === "lossless-webp" && assets.quality !== undefined) {
+    throw new TypeError('Package assets.optimize.quality is only valid when assets.optimize.mode is "webp".');
+  }
+  if (assets.maxDimension !== undefined && (!Number.isSafeInteger(assets.maxDimension) || assets.maxDimension < 1)) {
+    throw new TypeError(`Package assets.optimize.maxDimension must be a positive safe integer: ${assets.maxDimension}`);
+  }
+  return {
+    processor: "sharp",
+    mode,
+    ...assets.quality === undefined ? {} : { quality: assets.quality },
+    ...assets.maxDimension === undefined ? {} : { maxDimension: assets.maxDimension }
+  };
+};
+var normalizePackageAssets = (assets) => {
+  if (assets === undefined)
+    return;
+  if (assets.delivery === "bundle") {
+    return {
+      delivery: "bundle",
+      ...assets.optimize === undefined ? {} : { optimize: normalizePackageAssetOptimization(assets.optimize) }
+    };
+  }
+  if (assets.delivery === "omit")
+    return { delivery: "omit" };
+  if (assets.delivery !== "git-raw") {
+    throw new TypeError(`Package assets.delivery must be "git-raw", "bundle", or "omit": ${String(assets.delivery)}`);
+  }
+  const remote = assets.remote?.trim();
+  if (remote !== undefined && !/^[A-Za-z0-9._-]+$/u.test(remote)) {
+    throw new TypeError(`Package assets.remote must be a safe Git remote name: ${assets.remote}`);
+  }
+  const urlPrefix = assets.urlPrefix?.trim().replace(/\/+$/u, "");
+  if (urlPrefix !== undefined && !urlPrefix.startsWith("https://")) {
+    throw new TypeError("Package assets.urlPrefix must be an HTTPS URL; it may contain {commit}.");
+  }
+  return {
+    delivery: "git-raw",
+    ...remote === undefined ? {} : { remote },
+    ...urlPrefix === undefined ? {} : { urlPrefix }
+  };
+};
 var assertSelectOkfRoots = (roots) => {
   for (const root of roots) {
     assertOkfRoot(root, "Package select.okfRoots");
@@ -11946,11 +12011,13 @@ var createPackageDefinitionBase = (kind, definition) => {
 var kbPackage = (definition) => {
   const base = createPackageDefinitionBase("kb", definition);
   const distribution = normalizePackageDistribution(definition.distribution);
+  const assets = normalizePackageAssets(definition.assets);
   return {
     kind: "package.kb",
     ...base,
     navigation: normalizePackageNavigation(definition.navigation),
-    ...distribution === undefined ? {} : { distribution }
+    ...distribution === undefined ? {} : { distribution },
+    ...assets === undefined ? {} : { assets }
   };
 };
 var llmsPackage = (definition) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "type": "module",
   "description": "Context SDK — project-local configuration and workspace primitives",
   "license": "MIT",
@@ -15,6 +15,9 @@
     "knowledge",
     "workspace"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "yaml": "^2.5.1",
     "zod": "^3.23.8"

package/phases.d.ts

@@ -143,6 +143,11 @@ export type CaptureLarkPhaseDefinition = {
     reads: readonly PhaseResourceReference[];
     writes: readonly PhaseResourceReference[];
     source: LarkSourceDefinition | LarkSourceReference;
+    resources: {
+        videos: "reference-only" | "bundle";
+        maxBytesPerResource: number;
+        maxTotalBytes: number;
+    };
 };
 export type AlignProsePhaseDefinition = {
     kind: "phase.align.prose";
@@ -200,6 +205,11 @@ export declare const captureFile: (definition: {
 }) => CaptureFilePhaseDefinition;
 export declare const captureLark: (definition: {
     source: LarkSourceDefinition | LarkSourceReference;
+    resources?: {
+        videos?: "reference-only" | "bundle";
+        maxBytesPerResource?: number;
+        maxTotalBytes?: number;
+    };
 }) => CaptureLarkPhaseDefinition;
 export declare const alignProse: (definition: {
     source: DocumentSourceDefinition;

package/templates/package-templates/kb/skills/knowledge-query/SKILL.md

@@ -78,11 +78,12 @@ phrases, or several large indexes, run the bundled
 node <current knowledge-query Skill directory>/scripts/search.mjs --query '<terms>' --limit 8
 ```
 
-The script locates `{{packageName}}` from a raw package or TTKB installation.
-If discovery is ambiguous, add `--root <package directory containing
-context-build-inventory.json>`. It chunks Markdown mechanically by headings and
-bounded line ranges, then returns paths, line ranges, headings, and previews; it
-does not interpret meaning.
+The script locates `{{packageName}}` when it runs inside the package tree. If a
+package manager copied this Skill elsewhere, add `--root <package directory
+containing context-build-inventory.json>`, or use `--base <package collection>`
+to locate this package by its inventory name. It chunks Markdown mechanically
+by headings and bounded line ranges, then returns paths, line ranges, headings,
+and previews; it does not interpret meaning.
 
 Treat every hit as a lead and open its page and section before answering. For
 relationship or impact claims, use typed edges from

package/templates/package-templates/kb/skills/knowledge-query/scripts/search.mjs

@@ -14,8 +14,8 @@ function usage() {
     "Search an approved knowledge package with deterministic BM25 ranking.",
     "",
     "Usage:",
-    "  node search.mjs --query <text> [--root <package-root>] [--limit <n>] [--json]",
-    "  node search.mjs <text> [--root <package-root>] [--limit <n>] [--json]",
+    "  node search.mjs --query <text> [--root <package-root>] [--base <package-collection>] [--limit <n>] [--json]",
+    "  node search.mjs <text> [--root <package-root>] [--base <package-collection>] [--limit <n>] [--json]",
     "",
     "The package root is detected from context-build-inventory.json when possible.",
   ].join("\n");
@@ -23,7 +23,7 @@ function usage() {
 
 function parseArgs(argv) {
   const positional = [];
-  const options = { root: undefined, query: undefined, limit: 8, json: false };
+  const options = { root: undefined, base: undefined, query: undefined, limit: 8, json: false };
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
     if (arg === "--help" || arg === "-h") return { help: true };
@@ -31,10 +31,11 @@ function parseArgs(argv) {
       options.json = true;
       continue;
     }
-    if (arg === "--root" || arg === "--query" || arg === "--limit") {
+    if (arg === "--root" || arg === "--base" || arg === "--query" || arg === "--limit") {
       const value = argv[++index];
       if (value === undefined) throw new Error(`missing value for ${arg}`);
       if (arg === "--root") options.root = value;
+      else if (arg === "--base") options.base = value;
       else if (arg === "--query") options.query = value;
       else options.limit = Number(value);
       continue;
@@ -83,7 +84,7 @@ function inventoryPackageName(inventoryPath) {
   }
 }
 
-function resolvePackageRoot(explicitRoot) {
+function resolvePackageRoot(explicitRoot, packageCollection) {
   if (explicitRoot !== undefined) {
     const root = resolve(explicitRoot);
     if (!isPackageRoot(root)) throw new Error(`package root has no context-build-inventory.json: ${root}`);
@@ -93,7 +94,10 @@ function resolvePackageRoot(explicitRoot) {
   if (scriptRoot !== undefined) return scriptRoot;
   const cwdRoot = ancestorPackageRoot(process.cwd());
   if (cwdRoot !== undefined) return cwdRoot;
-  const inventories = findInventories(join(process.cwd(), ".ttkb", "packages"));
+  if (packageCollection === undefined) {
+    throw new Error("cannot locate the knowledge package; pass --root <package-root> or --base <package-collection>");
+  }
+  const inventories = findInventories(resolve(packageCollection));
   const matching = inventories.filter((path) => inventoryPackageName(path) === PACKAGE_NAME);
   if (matching.length === 1) return dirname(matching[0]);
   if (matching.length > 1) {
@@ -245,7 +249,7 @@ try {
     process.stdout.write(`${usage()}\n`);
     process.exit(0);
   }
-  const root = resolvePackageRoot(options.root);
+  const root = resolvePackageRoot(options.root, options.base);
   const results = search(root, options.query, options.limit);
   if (options.json) {
     process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, root, query: options.query, results }, null, 2)}\n`);

package/templates/package-templates/llms/llms.txt

@@ -6,4 +6,3 @@ Package kind: {{packageKind}}
 Approved knowledge files: {{knowledgeCount}}
 
 {{knowledge}}
-

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/SKILL.md

@@ -60,7 +60,7 @@ description: 查询 {{displayName}} 中经过审核、可追溯来源的知识
 node <当前 knowledge-query Skill 目录>/scripts/search.mjs --query '<关键词>' --limit 8
 ```
 
-脚本会从原始包或 TTKB 安装目录定位 `{{packageName}}`；无法唯一定位时，增加 `--root <包含 context-build-inventory.json 的包目录>`。它按 Markdown 标题和固定行块机械切分，返回路径、行号、标题和短预览，不判断内容语义。
+脚本位于知识包目录内时会自动定位 `{{packageName}}`。如果包管理工具将本 Skill 复制到了其他位置，增加 `--root <包含 context-build-inventory.json 的包目录>`；也可以使用 `--base <多包集合根目录>`，按构建清单中的包名定位。它按 Markdown 标题和固定行块机械切分，返回路径、行号、标题和短预览，不判断内容语义。
 
 搜索命中只是线索。回答前必须打开命中的页面和章节；关系或影响范围仍以 `context-build-inventory.json` 的类型化边为准，不能用 BM25 分数或文本共现替代关系证据。
 

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/scripts/search.mjs

@@ -14,8 +14,8 @@ function usage() {
     "Search an approved knowledge package with deterministic BM25 ranking.",
     "",
     "Usage:",
-    "  node search.mjs --query <text> [--root <package-root>] [--limit <n>] [--json]",
-    "  node search.mjs <text> [--root <package-root>] [--limit <n>] [--json]",
+    "  node search.mjs --query <text> [--root <package-root>] [--base <package-collection>] [--limit <n>] [--json]",
+    "  node search.mjs <text> [--root <package-root>] [--base <package-collection>] [--limit <n>] [--json]",
     "",
     "The package root is detected from context-build-inventory.json when possible.",
   ].join("\n");
@@ -23,7 +23,7 @@ function usage() {
 
 function parseArgs(argv) {
   const positional = [];
-  const options = { root: undefined, query: undefined, limit: 8, json: false };
+  const options = { root: undefined, base: undefined, query: undefined, limit: 8, json: false };
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
     if (arg === "--help" || arg === "-h") return { help: true };
@@ -31,10 +31,11 @@ function parseArgs(argv) {
       options.json = true;
       continue;
     }
-    if (arg === "--root" || arg === "--query" || arg === "--limit") {
+    if (arg === "--root" || arg === "--base" || arg === "--query" || arg === "--limit") {
       const value = argv[++index];
       if (value === undefined) throw new Error(`missing value for ${arg}`);
       if (arg === "--root") options.root = value;
+      else if (arg === "--base") options.base = value;
       else if (arg === "--query") options.query = value;
       else options.limit = Number(value);
       continue;
@@ -83,7 +84,7 @@ function inventoryPackageName(inventoryPath) {
   }
 }
 
-function resolvePackageRoot(explicitRoot) {
+function resolvePackageRoot(explicitRoot, packageCollection) {
   if (explicitRoot !== undefined) {
     const root = resolve(explicitRoot);
     if (!isPackageRoot(root)) throw new Error(`package root has no context-build-inventory.json: ${root}`);
@@ -93,7 +94,10 @@ function resolvePackageRoot(explicitRoot) {
   if (scriptRoot !== undefined) return scriptRoot;
   const cwdRoot = ancestorPackageRoot(process.cwd());
   if (cwdRoot !== undefined) return cwdRoot;
-  const inventories = findInventories(join(process.cwd(), ".ttkb", "packages"));
+  if (packageCollection === undefined) {
+    throw new Error("cannot locate the knowledge package; pass --root <package-root> or --base <package-collection>");
+  }
+  const inventories = findInventories(resolve(packageCollection));
   const matching = inventories.filter((path) => inventoryPackageName(path) === PACKAGE_NAME);
   if (matching.length === 1) return dirname(matching[0]);
   if (matching.length > 1) {
@@ -245,7 +249,7 @@ try {
     process.stdout.write(`${usage()}\n`);
     process.exit(0);
   }
-  const root = resolvePackageRoot(options.root);
+  const root = resolvePackageRoot(options.root, options.base);
   const results = search(root, options.query, options.limit);
   if (options.json) {
     process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, root, query: options.query, results }, null, 2)}\n`);

package/templates/project-skills/maintain-project-knowledge/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: maintain-project-knowledge
+description: Maintain a project-local Context knowledge workspace by checking registered repository and document sources, selecting the affected project scope, and handing lifecycle actions to the installed Context Skill. Customize the name, description, project facts, and impact map before using this template in a real project.
+---
+
+# Maintain project knowledge
+
+Use this file as a project adapter, not as a copy of the Context workflow. Read
+the installed Context Skill first and treat its current Route, resources, and
+commands as authoritative. Keep only stable project facts and source-impact
+mappings here.
+
+## Repository sources
+
+Start with the current Context Route. If registered repository modules are
+missing or their local links are broken, follow the route-selected repository
+recovery procedure. Let the user choose an existing checkout, authorize a scan
+inside one bounded directory, or explicitly clone the registered pinned commit.
+
+When a checkout already exists, inspect its origin, HEAD, dirty state, and
+registered subpaths before asking whether to keep the recorded commit or update
+to another explicit commit. Never pull, switch, clean, or reset an external
+checkout without separate authority.
+
+Repository sources are ready for knowledge work only when every selected module
+resolves to its registered remote and commit, all required subpaths exist,
+unknown local changes are preserved, Context has materialized its module links,
+and the current Route no longer reports a repository-readiness blocker.
+
+Add the project's stable mapping from repository changes to declared extraction
+scope here. Do not infer this mapping from filenames during a maintenance run.
+
+## Remote document sources
+
+Use the current Context Route and the installed document-provider Skills or CLI
+to read registered remote documents. Keep this section short: provider login,
+permissions, capture, sub-page traversal, and fidelity diagnostics belong to
+the provider and Context resources selected for the current step.
+
+A remote document is ready for knowledge work only when its registered identity
+is unchanged unless the user explicitly adds a new source, the current account
+can read the required body and assets, relevant child pages are represented as
+their own sources, capture fidelity has no blocking error, and the current Route
+allows structure or extraction work to begin.
+
+Add project-specific source ownership, expected document families, and update
+boundaries here. Do not copy credentials, source bodies, or volatile command
+lines into this Skill.
+
+## Project facts and completion
+
+Record only durable project paths, declared package outputs, physical-to-logical
+repository grouping, and evidence-backed impact rules. Do not duplicate Context
+phase commands or manually edit lifecycle-owned directories.
+
+Report completion using the current Context Route and build receipt, including
+the checked source range, changed and unchanged knowledge, unresolved permissions
+or fidelity blockers, and whether a package was built or separately published.

package/templates/project-skills.zh-CN/maintain-project-knowledge/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: maintain-project-knowledge
+description: 维护项目内的 Context 知识生产工作区；用于检查已登记仓库和文档来源、判断项目影响范围，并把生命周期动作交回已安装的 Context Skill。用于真实项目前，请修改名称、描述、项目事实和影响映射。
+---
+
+# 维护项目知识
+
+本 Skill 是项目适配层，不复制 Context 工作流。先读取已安装的 Context
+Skill，并以当前 Route、资源和命令为权威；这里只保留稳定的项目事实和来源
+影响映射。
+
+## 仓库来源的获取和更新
+
+先检查当前 Context Route。已登记仓库模块缺失或本地链接断开时，使用 Route
+选择的仓库恢复流程，让用户选择已有 checkout、授权在一个限定目录内扫描，
+或明确允许 clone 已登记的固定 commit。
+
+checkout 已存在时，先检查 origin、HEAD、dirty 状态和已登记 subpath，再询问
+用户保持当前登记版本，还是更新到另一个明确 commit。没有单独授权时，不得对
+外部 checkout 执行 pull、切换、清理或 reset。
+
+只有当每个目标模块都对应已登记 remote 和 commit、全部 subpath 存在、未知
+本地修改得到保护、Context 已物化模块链接，并且当前 Route 不再报告仓库未
+就绪时，仓库来源才可以进入知识更新。
+
+在这里补充本项目稳定的“仓库变化 → 提取范围”映射。维护过程中不得仅根据
+文件名临时猜测影响关系。
+
+## 远程文档来源的获取和更新
+
+通过当前 Context Route 以及宿主安装的文档提供方 Skill 或 CLI 读取已登记
+文档。本节保持简短：登录、权限、采集、子页遍历和保真诊断由当前步骤选择的
+提供方与 Context 资源负责。
+
+只有当来源身份保持稳定（除非用户明确新增来源）、当前账号能够读取所需正文
+和资源、需要正文的子页已作为独立来源处理、采集不存在阻塞性 fidelity error，
+并且当前 Route 允许开始结构或提取工作时，远程文档才可以进入知识更新。
+
+在这里补充本项目的来源归属、预期文档类型和更新边界。不要把凭据、来源正文
+或易漂移的完整命令写进 Skill。
+
+## 项目事实与完成标准
+
+只记录长期稳定的项目路径、包输出、物理仓库与逻辑来源分组，以及有证据的影响
+规则。不得复制 Context 阶段命令，也不得手工修改生命周期托管目录。
+
+以当前 Context Route 和构建回执报告完成情况，说明检查范围、知识新增/更新/
+无变化、尚未解决的权限或保真问题，以及知识包是仅完成构建还是已经另行发布。