# The Context Knowledge Workspace



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

A **Context knowledge workspace** is the directory where Context keeps one body of knowledge: its declarations, its registered sources, the approved pages and the outputs built from them. `context init` creates it, and its `package.json` marks it as a Context project. It is usually a Git repository of its own, or a directory inside a project repository.

Everything about the knowledge lives here, not in the conversation. Run Context commands from this directory: Route paths and `.tmp/` belong to this knowledge workspace, not to the surrounding repository or a parent directory.

```mermaid
flowchart LR
  subgraph you["You and the Agent declare"]
    src["src/<br/>project, requirements, map, templates"]
  end
  subgraph cli["Context CLI maintains"]
    sources["sources/<br/>registered evidence"] --> knowledge["knowledge/<br/>approved pages"]
    knowledge --> tr["translations/"]
  end
  src --> sources
  knowledge --> dist["dist/<br/>packages and sites"]
  tr --> dist
```


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

## The layout

Right after `context init`, and after the first deliveries, a knowledge workspace looks like this:

```text
my-knowledge/
├── package.json            # version and context.project marker
├── AGENTS.md               # rules for Agents working here
├── README.md
├── .gitignore
├── src/
│   ├── index.ts            # sources, capture phases and packages
│   ├── indexers.yaml       # reader purpose and authorized sources
│   ├── knowledge-map.yaml  # navigation for sites and LLM Docs
│   ├── package-templates/  # templates for each package kind
│   └── site/               # optional website customization
├── sources/
│   ├── repo/index.yaml     # repository sources: remote, commit, modules
│   ├── file/               # local document sources and snapshots
│   ├── lark/               # Lark document sources and snapshots
│   ├── note/YYYYMMDD/      # saved notes
│   └── sessions/YYYYMMDD/  # saved conversation summaries
├── knowledge/
│   ├── <collection>/…      # approved Markdown pages
│   └── structure.yaml      # page identities, sections and source references
├── translations/<locale>/  # translated pages and navigation titles
├── changelog.yaml          # knowledge version history
├── CHANGELOG.md            # generated from changelog.yaml
├── dist/                   # built packages and sites
└── .tmp/                   # runtime state, reports, Agent scratch
```

Some files appear only when you use the feature they belong to: `imports.yaml`, `repo-content.yaml` with its `repo-content/` view, `context-evidence.sourcegraph.wasm`, and a `PLAN-*.md` during a planned project. They are described below.


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

## Who writes what, and what Git keeps

| Path | Written by | In Git |
| --- | --- | --- |
| `package.json`, `AGENTS.md`, `README.md` | Created by `context init`; the version is updated by the CLI | Yes |
| `src/index.ts`, `src/indexers.yaml`, `src/package-templates/`, `src/site/` | You or the Agent, only when the current Route asks for a configuration change | Yes |
| `src/knowledge-map.yaml` | The CLI, through navigation adjustments the Agent submits | Yes |
| `sources/` registries, snapshots, notes and summaries | The CLI | Yes — except repository checkouts under `sources/repo/`, which are recovered from `index.yaml` |
| `knowledge/` | The CLI, when you approve a Review | Yes |
| `translations/`, `changelog.yaml`, `CHANGELOG.md` | The CLI, from Agent-written translations and change notes | Yes |
| `dist/` | `context build` | No — reproducible |
| `.tmp/` | The CLI and the Agent | No — runtime only |

`sources/` and `knowledge/` are the durable state of the knowledge; `dist/` can always be rebuilt from them. Commit the knowledge workspace only when Git operations are authorized for your task.


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

## Files that appear as the knowledge grows

- **`src/knowledge-map.yaml`** is the persistent knowledge map. It organizes website navigation and LLM Docs without changing page identities, and stays after each delivery. See [Reorganizing at Scale](</context/llms/pages/9b7018d3ff025bc9a5ed714bf0a7762c.txt>).
- **`translations/<locale>/`** holds one translated file per approved page plus a `knowledge-map.yaml` of translated navigation titles. Translations are formal content: they count toward versions and are packaged with the site.
- **`changelog.yaml` and `CHANGELOG.md`** are updated together with `package.json.version` each time a delivery records a version. See [Versions and Changelog](</context/llms/pages/4b322e03dfda3960ee4e5753b1f66a0f.txt>).


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

## Files for linked content

- **`imports.yaml`** at the root declares external entrances — content elsewhere that pages may link to — without downloading or capturing it. See [External Entrances](</context/llms/pages/3c35b84bd6846bd03f010004a29bf565.txt>).
- **`repo-content.yaml`** registers documentation and authored Skills that live in the same repository; **`repo-content/`** is a symlink view of them, and the originals stay where they are. See [Same-Repository Docs](</context/llms/pages/3f921b4529b91c86c7acd8db0f76f291.txt>).
- **`context-evidence.sourcegraph.wasm`** is an optional plugin for reading code evidence remotely. `context evidence install` maintains it; queries never install it on their own. See [Reading Code Evidence Remotely](</context/llms/pages/4c3472783cd20f6e615aab817f44126d.txt>).


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

## Runtime and scratch space

| Path | Holds |
| --- | --- |
| `.tmp/context-runtime/` | Unfinished workflow state: production stages, candidates, review reports, routes |
| `.tmp/agent-payloads/` | Command inputs the Agent prepares, such as translations |
| `.tmp/install/` | Temporary files used while installing dependencies |
| `.tmp/context-plans/<date-slug>/` | Research for a planned project: `repos/`, `documents/`, `research/`, `stage-inputs/` |

`.tmp/context-runtime/` is not the only record of progress. After a successful delivery the CLI removes completed task state, and approved knowledge with `structure.yaml` keeps what later updates need. Its absence never means accepted work may be replayed. A planned project also keeps `PLAN-YYYYMMDD-slug.md` at the Git root, committed so work can resume; see [Planning a Large Project](</context/llms/pages/50c06cb5af03a7d6f924874b49d02d50.txt>).


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

## Rules that keep it healthy

- **Do not edit CLI-owned state by hand.** `sources/`, `knowledge/`, `dist/` and `.tmp/context-runtime/` change only through Context commands. To change a page, ask for a [revision](</context/llms/pages/b75357332a63899630e3d8b2fa0346b1.txt>).
- **One knowledge workspace per directory.** Do not create a hidden second workspace, and do not mix revisions, tasks or `.tmp/` files with a parent directory that is also a knowledge workspace.
- **Repair through the Route.** When something looks broken, follow the recovery action the current Route returns instead of deleting runtime files.

Next: [Commands and Skills](</context/llms/pages/2e3119bc24e49da0e10fbf2c002d5472.txt>) lists what you can invoke in this knowledge workspace, and [Core Concepts](</context/llms/pages/e7afa377a464a3453f2ed4ed2a90f3f7.txt>) explains how its parts relate.

---

## Sources

- [context/packages/context-cli/src/project/workspaceGuidanceTemplates.ts L104–L108 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspaceGuidanceTemplates.ts#L104-L108>)
- [context/packages/context/docs/getting-started.md L38–L45 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/getting-started.md#L38-L45>)
- [context/packages/context-cli/src/project/workspace.ts L22–L25 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspace.ts#L22-L25>)
- [context/packages/context-cli/src/project/workspace.ts L467–L537 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspace.ts#L467-L537>)
- [context/packages/context-cli/src/project/workspaceGuidanceTemplates.ts L119–L131 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspaceGuidanceTemplates.ts#L119-L131>)
- [context/packages/context/src/managedSources.ts L18–L21 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/src/managedSources.ts#L18-L21>)
- [context/packages/context-cli/src/project/workspace.ts L454–L465 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspace.ts#L454-L465>)
- [context/packages/context/docs/reference/project-api.md L217–L222 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L217-L222>)
- [context/packages/context-cli/README.md L159–L178 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/README.md#L159-L178>)
- [context/packages/context/docs/guides/package-outputs.md L500–L505 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L500-L505>)
- [context/packages/context/docs/guides/site-translation.md L8–L16 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/site-translation.md#L8-L16>)
- [context/packages/context/docs/guides/knowledge-updates.md L169–L169 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/knowledge-updates.md#L169-L169>)
- [context/packages/context/docs/guides/imports.md L1–L7 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/imports.md#L1-L7>)
- [context/packages/context/docs/guides/repo-content.md L1–L20 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/repo-content.md#L1-L20>)
- [context/packages/context-cli/src/project/workspaceGuidanceTemplates.ts L125–L126 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspaceGuidanceTemplates.ts#L125-L126>)
- [context/packages/context-cli/src/project/workspaceGuidanceTemplates.ts L128–L130 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspaceGuidanceTemplates.ts#L128-L130>)
- [context/packages/context/docs/getting-started.md L150–L153 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/getting-started.md#L150-L153>)
- [context/plugins/context/skills/context-plan/references/project-planning.md L10–L28 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/plugins/context/skills/context-plan/references/project-planning.md#L10-L28>)
- [context/packages/context-cli/src/project/workspaceGuidanceTemplates.ts L132–L132 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspaceGuidanceTemplates.ts#L132-L132>)
- [context/packages/context-cli/src/project/workspaceGuidanceTemplates.ts L154–L158 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/workspaceGuidanceTemplates.ts#L154-L158>)
- [context/packages/context-cli/README.md L173–L178 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/README.md#L173-L178>)