# Project API



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

A Context knowledge workspace has two durable declarations with separate jobs:

| File | Declares |
| --- | --- |
| `src/index.ts` | Source references, document capture, custom non-knowledge orchestration, and package outputs — through the `@c4a/context` SDK |
| `src/indexers.yaml` | Long-term reader requirements, authorized target and supporting sources, and confirmed exclusions |

Never describe the same knowledge transformation in both. The Agent edits these declarations when the current Route asks for a configuration change; you do not need to write code yourself.


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

## `defineProject`

```ts
import { defineProject } from "@c4a/context";

export default defineProject({
  sources: [],
  phases: [],
  packages: [],
});
```

The definition is declarative: loading it must not change knowledge or runtime state.


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

## Sources

```ts
const repo = source("20260901", "component-lib");
const docs = source("20260901/product-docs", { type: "file" });
const handbook = source("20260901/handbook", { type: "lark" });
const note = source("20260908/decision-context.md", { type: "note" });
const session = source("20260908/design-discussion.md", { type: "sessions" });
const everyRepo = allSources("repo"); // spread inside sources: [...everyRepo]
```

| Type | Resolves against | Registered with |
| --- | --- | --- |
| `repo` (default), `file`, `lark` | `sources/<type>/index.yaml`; the name includes the registration date and module | `context source add …` |
| `note`, `sessions` | Saved Markdown under `sources/note/YYYYMMDD/` or `sources/sessions/YYYYMMDD/`; no separate registry or capture phase | `context source import` |

Saving a source does not select it — include its reference in `sources`. The source list enables acquisition and initial selection; the requirements and each Indexer's target and read scopes decide what it owns and may read.


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

## Capture phases

```ts
captureFile({ source: docs });
captureFile({ source: docs, processor: mdxJsonDocs() });
captureLark({ source: handbook });
```

Capture only creates a deterministic, readable snapshot; classification and writing follow the selected Indexer. Adding `--configure` to `context source add repo|file|lark|batch` generates the source references and default capture phases in `src/index.ts` for you. It keeps existing settings, is idempotent, and leaves custom or dynamic entries untouched with a `configuration.status: manual` hint.

For many documents with the same settings, map the registry instead of repeating declarations:

```ts
const registry = await loadSourcesRegistry({ rootDir: workspaceRoot });
const documents = registry.larks.map(entry => source(entry.name, { type: "lark" }));

export default defineProject({
  sources: documents,
  phases: documents.map(document => captureLark({ source: document })),
  packages: [],
});
```

File documents use `registry.files` with `captureFile`. Filter entries for a subset. `allSources("lark")` selects a whole collection and cannot be mapped into per-document phases. Capture boundaries do not dictate article boundaries.


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

## `customPhase`

```ts
customPhase("project:refresh-catalog", async (ctx) => {
  await ctx.ensureSources();
});
```

For project orchestration that neither publishes knowledge nor bypasses the Indexer lifecycle. Declare stable reads and writes when the phase has them.


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

## Packages

```ts
kbPackage({
  name: "component-kb",
  template: "src/package-templates/kb",
  select: { collections: ["codeindex", "architecture"] },
  site: { title: "Component knowledge", base: "/" },
});

llmsPackage({
  name: "component-context",
  template: "src/package-templates/llms",
  select: { collections: ["codeindex"] },
});
```

| Field | Required | Meaning |
| --- | --- | --- |
| `name` | Yes | Lowercase, path-safe; output goes to `dist/<name>/` |
| `template` | Yes | Template directory, or `{ path, vars }` |
| `select` | No | `collections`, `okfRoots`, `include`, `exclude`; omit for all approved knowledge |
| `navigation` | No | Directory-index policy; default `{ foldDirectoryIndexes: true, maxInlineEntries: 50 }` |
| `assets` | No | `{ delivery: "bundle" }` (default), `"git-raw"` with `urlPrefix`, or `"omit"`; optional `optimize` |
| `site` | No (`kbPackage` only) | Adds a documentation site at `dist/<base>-site/`, where `<base>` is the name without one trailing `-kb` |

Packages read approved `knowledge/` only; `dist/` is generated. Details are in [Package Templates](</context/llms/pages/a1be2204beca186b97317c9a9af6b07d.txt>).


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

## Site options

| Option | Meaning |
| --- | --- |
| `title`, `description` | Site title and description |
| `lang` | Primary language, default `en-US` |
| `base` | Deployment path such as `/` or `/docs/` |
| `titleLink` | Target of the top-bar title; defaults to the site home |
| `home` | `title`, `slogan`, `description`, hero `actions` (`text`, `link`, `theme`), and `resources` (each needs `href`, `command` or both) |
| `locales` | Additional reader languages keyed by BCP 47 tag, each with optional `label`, `title`, `description`, `home`; must differ from `lang` |
| `nav` | Top links after the knowledge sections: `text`, `link`, optional per-locale `locales` text |
| `more` | Items placed in the More menu before the built-in LLM Docs and Changelog entries: `text` with exactly one of `link` or `target.artifact_ref` (an approved article shown only there) |
| `socialLinks` | `icon` (`github`, `discord`, `x`, `youtube`, `slack`, `linkedin`, `mastodon`, `npm`), an https `link`, optional `ariaLabel` |
| `localePreferenceKey` | Shared storage key so sites on one origin keep the same reader language |
| `theme` | `light` and `dark` colors: `brand`, `accent`, `background`, `surface`, `text`, `mutedText`, `border` as hex values |
| `extensions` | Trusted presentation code: `root` (default `src/site`), `slots` (`brand`, `banner`, `knowledge`, `resources`, `footer`, `floating`; `false` hides one) and custom Markdown `pages` |

Links accept https or `mailto:` URLs, root-relative paths or page anchors. Custom pages are placed in the knowledge map with `target.artifact_ref: "site:<page-key>"`. See [Documentation Sites](</context/llms/pages/089c3c9e0212ca13bb27c8e8d2fe6080.txt>) and [Page and Theme Customization](</context/llms/pages/a14f7cbf6856dbd2ae309934ea6186c8.txt>).



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

## Requirements and Indexer Skills

When `src/indexers.yaml` is missing, the configuration Route supplies its schema. Write `requirements` only — no `protocol`, `indexers`, Provider selections or profiles. Which installed Indexer Skills to use, and their optional configuration, belongs to `indexer_usage` in the temporary production plan, not to this durable file. The Agent writes drafts and references under the returned temporary directory; the CLI accepts them and owns candidates, review and formal output.


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

## Durable and runtime state

Source registries and snapshots, saved notes and summaries, project declarations, package templates and approved knowledge are durable inputs, versioned in Git when Git operations are authorized. `.tmp/context-runtime/` holds unfinished execution state and stays out of Git. `knowledge/structure.yaml` keeps shared page and source metadata and compact `processed_scopes`; a partial update or failed build does not advance a whole range's processed version. Use the CLI to adjust or roll back work rather than editing these baselines.

The workspace `package.json` also accepts `context.convertVisuals` (default `true`): a capable Agent may convert source diagrams and tables into faithful text structures, keeping the original image when it cannot preserve the meaning.

---

## Sources

- [context/packages/context/docs/reference/project-api.md L1–L10 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L1-L10>)
- [context/packages/context/docs/guides/package-outputs.md L400–L402 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L400-L402>)
- [context/packages/context/docs/reference/project-api.md L12–L23 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L12-L23>)
- [context/packages/context/docs/reference/project-api.md L25–L56 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L25-L56>)
- [context/packages/context/docs/reference/project-api.md L58–L83 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L58-L83>)
- [context/packages/context/docs/reference/project-api.md L85–L135 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L85-L135>)
- [context/packages/context/docs/reference/project-api.md L137–L146 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L137-L146>)
- [context/packages/context/docs/reference/project-api.md L148–L196 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L148-L196>)
- [context/packages/context/docs/reference/package-templates.md L48–L57 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/package-templates.md#L48-L57>)
- [context/packages/context/docs/reference/package-templates.md L109–L116 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/package-templates.md#L109-L116>)
- [context/packages/context/src/packageSite.ts L1–L106 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/src/packageSite.ts#L1-L106>)
- [context/packages/context-cli/src/project/packageSiteTheme.ts L310–L318 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/packageSiteTheme.ts#L310-L318>)
- [context/packages/context/docs/reference/project-api.md L183–L202 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L183-L202>)
- [context/packages/context/docs/reference/project-api.md L204–L215 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L204-L215>)
- [context/packages/context/docs/reference/project-api.md L217–L229 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L217-L229>)
- [context/packages/context/docs/reference/project-api.md L231–L235 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/reference/project-api.md#L231-L235>)