# Source Batches



<a id="section-goal"></a>

When a task involves many sources — a dozen services, a folder of handbooks, a Wiki section — register them as one batch rather than one command at a time. A batch is one serial registry write under one date, so sources do not race each other, and with checkpoints a long registration survives interruption.

Registering many sources is not the same as producing a large knowledge base. For work spanning more than 30 documents or substantive investigation of two or more repositories, the Agent first plans the project in stages; see [Large Projects](</context/llms/pages/11ac316d1688fc8030d159834406bcb4.txt>).


<a id="section-payload"></a>

## The payload

```yaml
sources:
  - type: repo
    module: billing-service
    local: ../billing-service
  - type: file
    local: ../docs/user-guide.md
  - type: lark
    url: https://example.larkoffice.com/wiki/example-token
```

```bash
context source add batch 20261012 --input .tmp/sources.yaml --configure --format json
```

- `repo.module` is required; `file` and `lark` modules are derived from the path or URL when omitted, and duplicates in the batch are rejected.
- `repo.local` is resolved from the Context project root. A valid checkout supplies its remote and commit, so `remote`/`ref` are needed only when they cannot be read.
- `--configure` also declares the sources and default capture phases in a simple `src/index.ts`. Without it, the batch only registers.


<a id="section-checkpoint"></a>

## Long batches: checkpoints and resume

```mermaid
flowchart LR
  start["add batch<br/>--checkpoint --progress"] --> run["Register in chunks"]
  run -->|interrupted| status["batch-status job-id"]
  status --> resume["add batch --resume job-id"]
  resume -->|revalidate every item| run
  run --> receipt["Final receipt<br/>registered / total"]
```

```bash
context source add batch 20261012 --input .tmp/sources.yaml --checkpoint --progress --format json
context source batch-status <job-id> --format json
context source add batch --resume <job-id> --progress --format json
```

The saved input stays under `.tmp/context-runtime/source-batches/`, so resuming does not need the original file. Resume replays and revalidates every item against the current registry; the saved cursor is only a hint. Do not combine `--resume` with a date or a new input. Progress goes to stderr as bounded JSON; stdout keeps the final receipt.


<a id="section-failure"></a>

## Partial failure and locks

A batch keeps what succeeded: entries before a failed item stay registered, and the error names the completed entries and the failed position. Lark entries are validated in memory and committed in bounded atomic chunks.

Only one writer runs in a Context knowledge workspace at a time. Wait for an active command rather than starting another or deleting its lock. If a forced stop leaves a stale lock, run `context task recover --format json` before resuming.

---

## Sources

- [context/packages/context-cli/context-workflow/resources/procedures/source-boundary.md L67–L70 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/context-workflow/resources/procedures/source-boundary.md#L67-L70>)
- [context/plugins/context/skills/context-plan/SKILL.md L1–L4 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/plugins/context/skills/context-plan/SKILL.md#L1-L4>)
- [context/packages/context-cli/src/project/sourceCommands.ts L292–L320 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/sourceCommands.ts#L292-L320>)
- [context/packages/context/docs/guides/source-batches.md L7–L29 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/source-batches.md#L7-L29>)
- [context/packages/context/docs/guides/source-batches.md L31–L34 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/source-batches.md#L31-L34>)
- [context/packages/context/docs/guides/source-batches.md L42–L47 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/source-batches.md#L42-L47>)