Document Directories

Use a file source when the material is local Markdown: one file, several files, or a documentation folder. Unlike a code repository, a document source is captured: Context takes a reproducible snapshot under sources/file/, and pages cite that snapshot rather than the live folder.

flowchart LR
  reg["Register<br/>date/module + include"] --> decl["Declare captureFile<br/>in src/index.ts"]
  decl --> cap["Capture<br/>snapshot under sources/"]
  cap --> write["Plan and write<br/>cite the snapshot"]

Ask the Agent

Say which documents to ingest, not just which folder you happen to be in:

Ingest ../docs/user-guide as product documentation. Only the getting-started
and billing chapters.

Run instructions, handbooks, plans or batch lists you hand the Agent are treated as task guidance, not as sources, unless you explicitly ask to ingest them. If the documents to capture are unclear, the Agent asks once instead of capturing the instructions themselves.

Register and declare capture

context source add file 20261012 --module user-guide --local ../docs/user-guide \
  --include "getting-started/**" --include "billing/**" --configure

Option	Meaning
--local	Required. A local Markdown directory or file, used as the refresh location.
--module	Document module name; derived from --local when omitted.
--include	Markdown include glob relative to --local; repeat it for several patterns.
--include-list	A file of include globs, one per line; blank lines and # comments are ignored.
--configure	Also declares the source and a default capture phase in a simple src/index.ts. It does not capture.

Registration reads no content. With --configure, the project gains a declaration like:

const docs = source("20261012/user-guide", { type: "file" });

export default defineProject({
  sources: [docs],
  phases: [captureFile({ source: docs })],
});

If src/index.ts already has custom entries, the configuration result is manual and the Agent makes a focused edit instead of retrying.

Capture

Capture is an external read, so it needs your permission in the current conversation. Asking to capture, ingest or read the named documents grants it; merely mentioning them or asking to register does not. The Agent then runs the capture command returned by the workflow, reports the outcome and continues until every document in the batch is done.

Capture creates the snapshot; it does not classify, summarize or approve anything. The CLI owns normalization, hashes and manifests, and the Agent never edits a captured snapshot by hand.

Documentation sites (MDX)

Default capture handles .md. If the folder turns out to be a documentation site — .mdx pages, _meta.json, sidebars or a docs config — the Agent stops and confirms before changing the configuration. For MDX sites that use _meta.json, the capture phase gains the MDX processor:

captureFile({ source: docs, processor: mdxJsonDocs() });

The processor keeps route metadata and static component text as evidence. If a page is only a shell that mounts runtime-rendered content, the Agent tells you and asks for the rendered site or its data source instead of inventing the body.

When the documents change

Pages keep citing the snapshot they were written from. When the folder changes, ask for an update: the Agent captures the new version and asks which pages need changes. See Updating Knowledge.

文档目录

当材料是本地 Markdown 时，使用文件来源：一个文件、多个文件或一个文档文件夹都可以。与代码仓库不同，文档来源需要采集：Context 会在 sources/file/ 下生成可复现的快照，页面引用的是该快照，而不是实时变化的文件夹。

flowchart LR
  reg["登记<br/>date/module + include"] --> decl["在 src/index.ts 中<br/>声明 captureFile"]
  decl --> cap["采集<br/>在 sources/ 下生成快照"]
  cap --> write["规划与写作<br/>引用快照"]

告诉 Agent

说明要导入哪些文档，而不只是你当前所在的文件夹：

Ingest ../docs/user-guide as product documentation. Only the getting-started
and billing chapters.

你交给 Agent 的运行说明、手册、计划或批次清单都会被视为任务指引，而不是来源，除非你明确要求导入它们。如果要采集哪些文档并不明确，Agent 会询问一次，而不是把这些指引本身采集进去。

登记并声明采集

context source add file 20261012 --module user-guide --local ../docs/user-guide \
  --include "getting-started/**" --include "billing/**" --configure

选项	含义
--local	必填。本地 Markdown 目录或文件，用作刷新位置。
--module	文档模块名；省略时根据 --local 推导。
--include	相对于 --local 的 Markdown include glob；可重复使用以指定多个模式。
--include-list	一个包含 include glob 的文件，每行一个；空行和 # 注释会被忽略。
--configure	同时在简单的 src/index.ts 中声明该来源和默认的采集阶段。它不会执行采集。

登记不读取任何内容。使用 --configure 后，项目中会新增类似如下的声明：

const docs = source("20261012/user-guide", { type: "file" });

export default defineProject({
  sources: [docs],
  phases: [captureFile({ source: docs })],
});

如果 src/index.ts 中已有自定义条目，配置结果为 manual，Agent 会做针对性修改，而不是反复重试。

采集

采集属于外部读取，因此需要你在当前对话中授权。要求采集、导入或读取指定文档即视为授权；仅仅提到这些文档或要求登记则不算。之后 Agent 会运行工作流返回的采集命令，报告结果，并持续执行直到该批次的所有文档都完成。

采集只生成快照，不做分类、摘要或批准。规范化、哈希和清单由 CLI 负责，Agent 绝不手动编辑已采集的快照。

文档站点（MDX）

默认采集处理 .md。如果该文件夹实际上是一个文档站点——包含 .mdx 页面、_meta.json、侧边栏或文档配置——Agent 会先停下来与你确认，再修改配置。对于使用 _meta.json 的 MDX 站点，采集阶段会加入 MDX 处理器：

captureFile({ source: docs, processor: mdxJsonDocs() });

该处理器会保留路由元数据和静态组件文本作为证据。如果某个页面只是挂载运行时渲染内容的外壳，Agent 会告诉你，并请你提供渲染后的站点或其数据源，而不是凭空编造正文。

文档发生变化时

页面会继续引用其写作时依据的快照。文件夹内容变化后，请发起更新：Agent 会采集新版本，并询问哪些页面需要修改。参见更新知识。