---
type: architecture
updated: 2026-07-08
---

# Conflicts and provenance {#conflicts-and-provenance}

ContextCake returns one primary answer per concept and is honest about
dissent. Where layers disagree on a section, the higher layer's value wins as
primary, and the dissenting layers ride along — tagged with their layer name
and last-updated date. The contradiction is **surfaced, not hidden**.

## Per-section conflicts {#per-section-conflicts}

A conflict is attached to the specific section that disagrees, not to the
whole concept. When another contributor defines a section with content that
differs from the winner, the resolved section carries:

```json
"conflicts": [
  { "layer": "company", "updated": "2026-05-01", "content": "..." }
]
```

Sections where every contributing layer agrees, or that only one layer
defines, resolve silently — no `conflicts` array at all. That is the
common, non-contentious path: most sections in most concepts inherit cleanly.
Suppressed sections (see `architecture/section-merge.md`) also carry no
conflicts — the tombstone is the answer, so there is nothing left to
disagree about.

## Provenance at three levels {#provenance-at-three-levels}

A resolved concept carries provenance so an agent can weight facts by trust
level, not just read a flat answer:

- **`contributors`** — every layer that defines this concept at all, each as
  `{ layer, level, updated }`.
- **`frontmatterProvenance`** — for each frontmatter field, which layer
  supplied the winning value.
- **`sections[].sourceLayer` / `sourceUpdated`** — which layer won each
  section, and when that layer last touched it.

`layer` here doubles as a trust signal: a section sourced from `company` and
a section sourced from an unreviewed `personal` draft carry different
implicit weight, even though both are the "primary" answer for their
respective sections.

## Dates are the staleness signal {#dates-are-the-staleness-signal}

`updated` — on the winning section and on every conflict — is the whole
staleness story. There is no separate hash-based drift detector watching for
silent changes; ContextCake trusts authors to bump `updated` when content
changes, and asks the reader to compare dates directly. If a dissenting
layer's version is newer than the section that beat it on precedence, you see
that plainly and judge for yourself:

```
decisions/database-engine

  SingleStore                    <- primary   (team,        updated 2026-05-12)
  Chosen for HTAP / reporting workloads.

  company disagrees:
    Postgres                               (company, updated 2026-06-01)  <- newer
```

This is an accepted trade-off: date discipline is on the author, not enforced
by content hashing. A prior version of ContextCake had a shadow/hash
drift-detection subsystem; it was removed in favor of this simpler, honest
date comparison.

## Next {#next}

- `architecture/section-merge.md` — how the winning section is chosen before
  a conflict is even possible
- `architecture/the-mcp-server.md` — how `read_file` surfaces `contributors`,
  `frontmatterProvenance`, and per-section `conflicts` to an agent
- `architecture/layers-and-precedence.md` — where layer precedence, the thing
  that decides "primary," comes from

---
type: architecture
updated: 2026-07-08
---

# Federated storage and sources {#federated-storage-and-sources}

ContextCake does not centralize your knowledge. Storage stays **federated** —
each layer keeps its knowledge exactly where it already lives, and ContextCake
reads it through a uniform adapter at request time. There is no import step,
no copy, no shared database. Delete ContextCake and every layer's knowledge is
untouched.

## The `source` seam {#the-source-seam}

Every layer in the manifest declares a `source`. That field decides how the
layer's knowledge gets loaded, and it is the one seam that lets ContextCake
stitch together things that were never the same format:

```json
{ "name": "team", "level": 2, "source": "okf-local", "path": "~/kb-team" }
```

Two source kinds exist today:

- **`okf-local`** — a directory (typically a git repo) of OKF markdown files
  on disk. This is the default: a layer that omits `source` entirely is
  treated as `okf-local`.
- **`mcp`** — a foreign knowledge graph reached over a stdio MCP server. Its
  responses are **translated into OKF at read time**, so a graph that was
  never OKF stitches in alongside your native bundles as if it always had
  been.

Both kinds are read through the same adapter interface, so the resolver never
needs to know or care which one it's talking to.

## Why translation happens at read time {#translation-at-read-time}

An `mcp` layer does not get pre-converted or cached into OKF on disk. Every
read spawns (or reuses) the MCP connection, queries the foreign server, and
maps its response shape into OKF frontmatter and sections in memory, for that
one request. This keeps ContextCake honest about owning no source of truth —
the foreign graph stays the foreign graph's problem to store and version; the
translation is a lens, not a migration.

The practical effect: an `okf-local` layer changes are visible as soon as you
edit the file. An `mcp` layer's freshness depends entirely on what the foreign
server currently returns.

## The adapter files {#the-adapter-files}

Three files implement this seam:

| File | Role |
|------|------|
| `sources/okf-local.mjs` | Reads an OKF bundle from disk — the default adapter |
| `sources/mcp.mjs` | Spawns a foreign stdio MCP server, translates its responses into OKF |
| `sources/index.mjs` | Builds the right adapter for each layer from the manifest |

`sources/index.mjs` is the factory: given a manifest, it walks `layers[]`,
looks at each layer's `source` (defaulting to `okf-local`), and constructs the
matching adapter with that layer's `name` and `level` attached. Everything
downstream — the resolver, the MCP server, the CLI — talks to the resulting
adapters through the same shape, never to raw files or raw MCP responses
directly.

## Why this matters {#why-this-matters}

Federation is the point, not an implementation detail. Your company's
knowledge graph almost certainly predates ContextCake and lives behind its own
tool with its own access model. Federated storage means ContextCake can sit on
top of that reality instead of demanding you migrate into it — you write one
`mcp` adapter for a foreign system once, and every layer that uses it stitches
in for free.

See `architecture/layers-and-precedence.md` for how the resolver combines what
each source returns, and `architecture/the-manifest-and-trust-boundary.md` for
why an `mcp` source is also a trust decision, not just a config option.

---
type: architecture
updated: 2026-07-08
---

# Layers and precedence {#layers-and-precedence}

ContextCake stacks your knowledge into a small number of layers, each with a
precedence level, and resolves them into **one effective concept** whenever an
agent asks for something. This file is the anchor for the rest of
`architecture/` — read it first.

## The three layers {#the-three-layers}

The default stack is three layers, ordered by level:

```
Personal  (level 3)  higher — your drafts, notes, overrides
Team      (level 2)
Company   (level 0)  lower  — org-wide canonical knowledge
```

Higher level wins. Personal overrides Team, Team overrides Company. There is
no fourth "Group" layer — earlier drafts of the design considered one, but it
was speculative and was dropped before implementation.

## Levels are configuration, not hidden magic {#levels-are-configuration}

Layer order lives in `layers.json`, the manifest, as a plain integer per
layer:

```json
{ "layers": [
  { "name": "personal", "level": 3, "source": "okf-local", "path": "~/kb-personal" },
  { "name": "team",     "level": 2, "source": "okf-local", "path": "~/kb-team" },
  { "name": "company",  "level": 0, "source": "mcp", "command": "node", "args": ["./company-graph-server.mjs"] }
] }
```

You can see the precedence order by reading the manifest, and you can change
it by editing a number. There is no separate ranking system, no code path that
special-cases a layer by name. `personal`, `team`, and `company` are
convention, not reserved words — any names and any integers work, and the
default levels (3, 2, 0) deliberately leave gaps so more layers can slot in
later without renumbering everything else.

## One effective concept per read {#one-effective-concept}

When an agent (or the CLI) asks for a concept, `resolver.mjs` looks at every
layer that defines that concept ID and merges them into a single answer. It
does this **per section**, not per document — see
`architecture/section-merge.md` for the mechanics. The result is one OKF
concept with:

- a primary value for every section, chosen by the highest layer that speaks
  to it
- provenance recording which layer won each section and each frontmatter
  field
- any dissenting layers attached as `conflicts`, never silently dropped

An agent reading a resolved concept never has to query three layers itself
and reconcile them by hand. It asks once, gets one answer, and gets told
exactly where that answer came from.

## Precedence is purely by level {#precedence-is-purely-by-level}

There is no same-level tiebreak rule in the default stack, because every
layer has a distinct level. If you configure two layers at the same level,
the first one listed in the manifest wins ties for that level — but the
common case is that levels are already distinct and this never comes up.

Precedence is decided by level alone — never by recency, section order, or
which layer happens to be queried first. A newer edit in a lower layer does
not outrank an older one in a higher layer; see
`architecture/conflicts-and-provenance.md` for how staleness is surfaced
instead of used as a tiebreak.

## Where each layer's knowledge lives {#where-knowledge-lives}

Layers are federated storage, not a shared database — see
`architecture/federated-storage-and-sources.md` for the `source` adapter
seam that lets a layer be a local git bundle or a foreign MCP graph. Access
control on `okf-local` layers is free: repo membership is read access to
that layer.

## Next {#next}

- `architecture/section-merge.md` — how a section's winner is chosen and how
  the rest is inherited
- `architecture/conflicts-and-provenance.md` — what happens when layers
  disagree
- `architecture/federated-storage-and-sources.md` — what a layer actually is
  under the `source` field

---
type: architecture
updated: 2026-07-08
---

# OKF format {#okf-format}

ContextCake speaks Open Knowledge Format (OKF) natively — concepts,
frontmatter, anchored sections, and the links between concepts. It is the one
shape every layer resolves into, whether it started as OKF or was translated
from something else entirely. See `architecture/federated-storage-and-sources.md`
for how a foreign `mcp` source gets translated into this shape at read time.

## Markdown plus frontmatter {#markdown-plus-frontmatter}

A concept is a single markdown file: YAML frontmatter, then a body of
anchored sections. The frontmatter block looks like:

```yaml
type: decision
title: Primary database
updated: 2026-06-20
owner: Data
tags: [database, architecture, analytics]
```

Below the frontmatter, the body carries a title line ("Primary database")
followed by anchored sections — a `Rationale` section (anchor `#rationale`)
saying "Postgres for OLTP, yes -- but we added ClickHouse for analytics
after the reporting queries started locking the primary," and an `Analytics
store` section (anchor `#analytics`) saying "ClickHouse, self-hosted on the
data cluster. It is a read replica target, never a source of truth."

The only **required** frontmatter field is `type`. Everything else —
`title`, `updated`, `owner`, `tags` — is optional, but `updated` is worth
setting: it is the staleness signal the resolver surfaces when layers
disagree (`architecture/conflicts-and-provenance.md`).

## Concept IDs are file paths {#concept-ids-are-file-paths}

A concept's ID is its file path within the bundle, relative to the bundle
root, with the `.md` extension removed. A file at:

```
kb-team/decisions/primary-db.md
```

has the concept ID `decisions/primary-db`. That ID is **stable across
layers** — Company, Team, and Personal can each hold their own
`decisions/primary-db.md`, at the same relative path within their own
bundle root, and the resolver stitches all three into one effective concept
also named `decisions/primary-db`. Layers don't need to coordinate on
anything except that shared relative path.

## Anchored sections {#anchored-sections}

Every heading that matters carries an explicit `{#anchor}`. The anchor, not
the heading text, is what the resolver merges on — it lets a higher layer
address exactly the section it wants to speak to, even if it phrases the
heading slightly differently, and it lets the tombstone syntax
(`{#anchor override=none}`) target one section precisely. See
`architecture/section-merge.md` for how anchors drive the merge.

## Links between concepts {#links-between-concepts}

OKF is a graph, not a pile of documents. A section body can link to another
concept with `[[wiki-style]]` references, or ordinary markdown links that
resolve to a concept path. For example, a `Related` section (anchor
`#related`) might contain the line: `See [[incident-response]] for the
on-call path when a database is degraded.`

Outgoing links are preserved in the stitched output and exposed through the
`get_links` MCP tool (`architecture/the-mcp-server.md`).

## Frontmatter and sections both merge {#frontmatter-and-sections-both-merge}

Frontmatter is field-merged the same way section bodies are: for each key,
the highest layer that sets it wins; unset keys are inherited. A concept's
`type` almost always comes from whichever layer first defined the concept,
since lower layers rarely leave `type` unset.

## Next {#next}

- `architecture/section-merge.md` — how anchored sections combine across
  layers
- `architecture/federated-storage-and-sources.md` — how a non-OKF `mcp`
  source gets mapped into this same shape
- `architecture/the-mcp-server.md` — how a resolved OKF concept reaches an
  agent

---
type: architecture
updated: 2026-07-08
---

# Section merge {#section-merge}

The resolver merges concepts **section by section**, not by replacing one
document with another. This is the core behavior that makes the layer cake
useful instead of just a priority list: a higher layer only needs to speak to
what it actually wants to change.

## Section merge, not whole-document replacement {#not-whole-document-replacement}

For each section — identified by its `{#anchor}` — the resolver picks a
winner independently:

- The highest layer that defines a given section wins that section.
- Every section the winner does not restate is **inherited** from whichever
  lower layer defines it.
- Frontmatter is field-merged the same way: for each key, the highest layer
  that sets it wins that field, and unset keys fall through to lower layers.

Nothing is lost just because a higher layer touched a neighboring section.

## Walking through an example {#walkthrough}

Take `decisions/primary-db`, defined by both Company and Team. The Company
layer's file has two sections: an `Engine` section (anchor `#engine`) that
says "Postgres.", and a `Backups` section (anchor `#backups`) that says
"Nightly snapshots to cold storage." The Team layer's file has only one
section — the same `Engine` anchor — that says "SingleStore (chosen for HTAP
workloads)."

Team only speaks to `Engine`. The resolver merges them into one effective
concept: the `Engine` section resolves to Team's value, because Team (higher
level) restated that anchor; the `Backups` section resolves to Company's
value, untouched, because Team never mentioned it.

Team's silence on `Backups` is not an override of anything — it just means
Team never spoke, so Company's version passes through unchanged. If Company
and Team's `Engine` sections had different content, the resolved section would
also carry a `conflicts` entry recording Company's dissenting value — see
`architecture/conflicts-and-provenance.md`.

## Two escape hatches {#escape-hatches}

Default section merge covers the common case. Two pieces of syntax opt out of
it:

| Syntax | Behavior |
|--------|----------|
| *(default)* | Section/field merge — higher layer wins per key |
| `override: full` in frontmatter | Whole-concept replacement; everything below is dropped |
| `{#anchor override=none}` | Tombstone — suppresses the inherited section |

### `override: full` {#override-full}

Setting `override: full` in a layer's frontmatter replaces the entire
concept. Every lower contributor is dropped for that concept — no section
merge, no inherited sections, no conflicts recorded. Use it sparingly; it
opts a concept out of inheritance entirely, which is rarely what you want
for more than one or two sections at a time.

### `{#anchor override=none}` — the tombstone {#the-tombstone}

To suppress a single inherited section without replacing the whole concept, a
higher layer defines that section — say a `Rollback` section, anchor
`#rollback` — with `override=none` added to that anchor and no content
underneath: `{#rollback override=none}`.

The section disappears from the effective body, but it is not silently
dropped from the record — the resolved output keeps it, marked
`suppressed: true`, so the suppression is auditable. A suppressed section
never carries `conflicts`: the tombstone itself is the answer, and there is
nothing left to disagree about.

This is deliberately the *only* rule beyond "higher wins" and "conflicts are
shown with dates" — the mental model stays at two rules plus one escape
hatch.

## Next {#next}

- `architecture/conflicts-and-provenance.md` — what rides along when layers
  disagree on a section
- `architecture/layers-and-precedence.md` — where the per-layer level that
  decides a winner comes from
- `architecture/okf-format.md` — how `{#anchor}` syntax is written in a file

---
type: architecture
updated: 2026-07-08
---

# The manifest and trust boundary {#the-manifest-and-trust-boundary}

`layers.json` — the manifest — is the one file that defines what layers
exist, in what order they take precedence, and where each layer's knowledge
comes from. Every command that resolves knowledge (`resolver.mjs`,
`mcp-server.mjs`, `write.mjs`) is pointed at one with `--manifest`.

## Shape {#shape}

```json
{
  "layers": [
    { "name": "personal", "level": 3, "source": "okf-local", "path": "~/kb-personal" },
    { "name": "team",     "level": 2, "source": "okf-local", "path": "~/kb-team" },
    { "name": "company",  "level": 0, "source": "mcp", "command": "node", "args": ["./company-graph-server.mjs"] }
  ]
}
```

One top-level key, `layers`: an ordered array of layer objects.

| Field | Required | Meaning |
|-------|----------|---------|
| `name` | yes | Layer identifier, used in provenance and as the `layer` argument to `read_file` |
| `level` | yes | Precedence — higher wins per section (any integer; 3/2/0 is convention, not a rule) |
| `source` | no | `okf-local` (default) or `mcp` |
| `path` | for `okf-local` | Directory holding the OKF bundle |
| `command` / `args` | for `mcp` | Executable and arguments to spawn as a stdio MCP server |

`path` and any relative `args` (starting with `./` or `../`) resolve
relative to the manifest file's own directory, not the current working
directory — so a manifest stays portable if you keep it next to the bundles
it points at.

## Why the manifest is a trust boundary {#why-a-trust-boundary}

A layer with `"source": "mcp"` causes ContextCake to spawn `command` with
`args` **as your user**. Nothing sandboxes that process — it runs with full
user permissions, exactly as if you had typed the command yourself. If the
manifest says:

```json
{ "name": "company", "level": 0, "source": "mcp", "command": "sh", "args": ["-c", "..."] }
```

that shell command runs, unreviewed, the moment something resolves against
this manifest. A manifest you did not author can therefore execute arbitrary
commands on your machine.

This is not a hypothetical edge case bolted onto the design — it is the same
model as any MCP client config (Claude Desktop, Claude Code, or any other
tool that spawns MCP servers from a config file). Treat `layers.json` with
the same suspicion you'd treat an unfamiliar MCP config or an unfamiliar
shell script someone handed you.

## `okf-local` layers only read files {#okf-local-only-reads-files}

The risk is specific to `mcp` layers. An `okf-local` layer is a directory of
markdown on disk — ContextCake only reads those files under `path`. It spawns
no process and runs no command. A manifest built entirely from `okf-local`
layers cannot execute anything; the worst it can do is point you at files you
didn't expect to read.

When you audit a manifest before trusting it, the layers to scrutinize are
the ones with `"source": "mcp"` — check `command` and `args` specifically.

## The rule {#the-rule}

**Only point `--manifest` at configs you wrote or trust.** Same model as any
MCP client config: the config that names a server is trusted to name a safe
one. This applies everywhere a manifest is consumed — `resolver.mjs`,
`mcp-server.mjs`, `write.mjs` — not just the MCP server.

## Next {#next}

- `architecture/federated-storage-and-sources.md` — what `okf-local` and
  `mcp` actually do once trusted
- `architecture/the-mcp-server.md` — the server that reads this manifest to
  serve agents
- `architecture/layers-and-precedence.md` — how `level` in this file drives
  resolution

---
type: architecture
updated: 2026-07-08
---

# The MCP server {#the-mcp-server}

`mcp-server.mjs` is the read surface AI agents connect to. It is a stdio MCP
server that exposes the resolved cascade — not raw layer files — as one
effective, read-time OKF graph. Every read goes through the same section and
field merge as the CLI: level precedence, provenance, per-section conflicts,
over every source declared in the manifest.

```bash
node mcp-server.mjs --manifest layers.json
```

## The four tools {#the-four-tools}

| Tool | What it returns |
|------|------------------|
| `search` | Full-text search across all layers; one entry per concept, with the layers that contributed to it |
| `read_file` | The resolved effective concept — section merge, provenance, per-section conflicts |
| `list_concepts` | Every effective concept ID, with contributing layers |
| `get_links` | Outgoing and incoming links, resolved against the effective graph |

### search {#search}

Full-text search across every layer, scored and deduplicated by concept ID.
Arguments: `query` (required), `limit` (default 10). Each result is
`{ id, title, score, layers, snippet }`, with `layers` ordered by level,
highest first — so an agent can tell at a glance whether a hit is backed by
Company policy, a Team runbook, or just a Personal note.

### read_file {#read_file}

The core tool. Reads the resolved concept across the whole cascade, with full
provenance: `contributors`, `frontmatterProvenance`, and per-section
`sourceLayer` / `sourceUpdated` / `conflicts` / `suppressed`. See
`architecture/conflicts-and-provenance.md` for what those fields mean and
`architecture/section-merge.md` for how the merge that produces them works.

Arguments: `concept_id` (required), `layer` (optional). Passing `layer`
skips the merge entirely and returns that one layer's raw, unmerged concept
as stored — useful for auditing what a specific layer actually says, versus
what the cascade resolves to.

### list_concepts {#list_concepts}

Lists every effective concept ID across the cascade, each with its
contributing layers. Optional `type` argument filters by the resolved
effective OKF `type`. This is how an agent (or a UI) discovers what exists
without knowing concept IDs up front.

### get_links {#get_links}

Returns outgoing and incoming links for a concept, resolved against the
effective graph — not any single layer's raw links. Argument: `concept_id`
(required). Outgoing links come from the resolved body; incoming links are
gathered from every concept elsewhere in the cascade that points back at this
one.

## Why `read_file` carries provenance, not just content {#why-provenance}

An agent that only got the merged text back would have no way to weight what
it's reading — a Company policy and an unreviewed Personal draft would look
identical. `read_file` deliberately returns enough structure
(`contributors`, `frontmatterProvenance`, `sourceLayer` per section) that an
agent can decide for itself how much to trust a given section, and can
surface a conflict to a human instead of silently picking one side.

## Cascade mode vs. legacy mode {#cascade-vs-legacy}

`mcp-server.mjs` accepts either a manifest (cascade mode, any number of
layers with any sources) or an explicit two-layer flag pair (legacy mode,
`okf-local` only):

```bash
node mcp-server.mjs --manifest layers.json
node mcp-server.mjs --personal ~/kb-personal --shared ~/kb-shared
```

Legacy mode exists for the simplest case — two local bundles, no `mcp`
sources — without requiring a manifest file at all.

## Next {#next}

- `architecture/conflicts-and-provenance.md` — the fields `read_file`
  attaches when layers disagree
- `architecture/the-manifest-and-trust-boundary.md` — what the server
  actually spawns when a layer's `source` is `mcp`
- `architecture/layers-and-precedence.md` — the precedence rules every tool
  resolves through

---
type: example
updated: 2026-07-08
---

# A real `layers.json`, field by field {#a-real-layers-json}

The manifest is the one file that declares your whole cascade: which
layers exist, their precedence, and how to reach each one. Here is a
realistic three-layer manifest — personal and team as local bundles,
company reached over MCP — with every field explained.

## The manifest {#the-manifest}

```json
{ "layers": [
  { "name": "personal", "level": 3, "source": "okf-local", "path": "~/kb-personal" },
  { "name": "team",     "level": 2, "source": "okf-local", "path": "~/kb-team" },
  { "name": "company",  "level": 0, "source": "mcp", "command": "node", "args": ["./company-graph-server.mjs"] }
] }
```

## Field by field {#field-by-field}

**`name`** — a label used in output (`sourceLayer`, `contributors`,
`conflicts[].layer`) so you can see which layer answered or dissented. Not
used for precedence.

**`level`** — the number that actually decides who wins. Higher wins, per
section, when two layers define the same concept. Here personal (3) beats
team (2) beats company (0). Levels are yours to set — the 3/2/0 spread is a
convention, not a hardcoded rule, and you could run a four-layer stack with
different numbers if your org needs it. There is no same-level tiebreak, so
give each layer a distinct level.

**`source`** — `okf-local` or `mcp`. Defaults to `okf-local` when omitted,
so the personal and team lines above could drop `"source": "okf-local"`
entirely and behave the same; it's written out here for clarity.

**`path`** (`okf-local` only) — the directory holding the bundle. Personal
and team here are two separate git repos on disk, each with its own access
control: repo membership is read access.

**`command` / `args`** (`mcp` only) — exactly what gets spawned to reach
this layer. The company layer above runs `node ./company-graph-server.mjs`
as a child process and talks MCP to it over stdio. No separate transport
config exists — this is the whole story.

## What's not in this file {#whats-not-in-this-file}

No merge rules, no conflict-resolution logic, no auth tokens. Precedence is
just `level`. Merge behavior lives in the resolver and in each concept's own
`{#anchor}` structure, not in the manifest. If a layer needs credentials to
reach a real backend, that belongs in the spawned command's own environment
or config — not in `layers.json`, which is not a secrets file.

## The trust boundary {#the-trust-boundary}

Anyone who can edit this file can make your `mcp` layers run arbitrary
commands as you — `command` and `args` are executed, not sandboxed. Only
point `--manifest` at a file you wrote or explicitly trust, the same way
you'd vet any MCP client config before pointing a tool at it.

## Next {#next}

- `use-cases/foreign-mcp-sources.md` — what actually happens when the
  company layer above gets queried
- `examples/resolved-output-example.md` — a `read_file` call against a
  concept spanning all three of these layers

---
type: example
updated: 2026-07-08
---

# A full OKF concept file {#a-full-okf-concept-file}

This is a realistic `okf-local` concept, as it would sit on disk at
`decisions/primary-db.md` inside a team bundle. It shows the two required
pieces of every OKF file: YAML frontmatter, and markdown sections anchored
with `{#anchor}`.

## The file {#the-file}

```markdown
---
type: decision
title: Primary database
updated: 2026-06-20
owner: Data
tags: [database, architecture, analytics]
---

##Primary database

##Rationale {#rationale}

Postgres for OLTP, yes — but we added ClickHouse for analytics after the
reporting queries started locking the primary. The org "one datastore" line
no longer matches what we actually run.

##Analytics store {#analytics-store}

ClickHouse, self-hosted on the data cluster. It is a read replica target,
never a source of truth. Nightly ETL loads from Postgres on a fixed
schedule.

##Related {#related}

See [[runbooks/analytics-etl-failure]] for what to do when the nightly load
breaks.
```

## Reading it apart {#reading-it-apart}

**Frontmatter.** Only `type` is required by OKF. Everything else here —
`title`, `updated`, `owner`, `tags` — is optional but worth setting:
`updated` in particular is the staleness signal the resolver surfaces when
another layer's version of this concept disagrees.

**The concept ID.** This file's ID is `decisions/primary-db` — its path
inside the bundle, minus `.md`. That ID is stable across layers: a Company
bundle and a Personal bundle can each hold their own
`decisions/primary-db.md`, and the resolver treats all three as one
concept.

**Sections.** Each `{#anchor}` is the unit a higher layer can address
individually. A team layer can override just `Rationale` without touching
`Analytics store`, and a company layer that never mentions either section
still contributes anything else it defines under this same concept ID —
inherited, not overwritten.

**Links.** `[[wikilink]]` syntax inside a section body points at another
concept ID. Outgoing links are preserved in the resolved output and exposed
through the `get_links` MCP tool.

## What's notably absent {#whats-notably-absent}

No `layer` field, no precedence number, no merge instructions anywhere in
this file. A concept file doesn't know or care which layer it lives in or
who wins — that's entirely a property of where the bundle sits in
`layers.json`. The same file format works identically in the personal,
team, or company bundle.

## Next {#next}

- `examples/layers-json-example.md` — where this bundle's `path` gets
  declared
- `examples/resolved-output-example.md` — what this file looks like after
  merging with a company-layer version of the same concept

---
type: example
updated: 2026-08-04
---

# What an agent gets back from `read_file` {#what-an-agent-gets-back}

This is the shape of a resolved concept — what `read_file` returns after
the resolver stitches every contributing layer together. It's the same
`decisions/primary-db` concept from `examples/okf-concept-example.md`,
resolved across a personal/team/company cascade. The response below is
real resolver output (`node resolver.mjs --manifest <manifest> --concept
decisions/primary-db`), trimmed to the two sections that show both shapes:
a contested section and a clean inherited one.

## The response {#the-response}

```json
{
  "id": "decisions/primary-db",
  "contributors": [
    { "layer": "personal", "level": 3, "updated": "2026-06-28" },
    { "layer": "team", "level": 2, "updated": "2026-06-20" },
    { "layer": "company", "level": 0, "updated": "2026-05-01" }
  ],
  "frontmatter": {
    "type": "decision",
    "title": "Primary database",
    "updated": "2026-06-28",
    "owner": "me",
    "tags": ["database", "local-dev"]
  },
  "frontmatterProvenance": {
    "type": "personal",
    "title": "personal",
    "updated": "personal",
    "owner": "personal",
    "tags": "personal"
  },
  "sections": [
    {
      "key": "rationale",
      "heading": "## Rationale {#rationale}",
      "content": "Postgres for OLTP, yes — but we added ClickHouse for analytics after the reporting\nqueries started locking the primary. The org \"one datastore\" line no longer matches\nwhat we actually run.",
      "sourceLayer": "team",
      "sourceUpdated": "2026-06-20",
      "conflicts": [
        {
          "layer": "company",
          "updated": "2026-05-01",
          "content": "One vendor, one backup story, one compliance boundary. Managed RDS is SOC2-covered\nand the security team already audits it."
        }
      ]
    },
    {
      "key": "ownership",
      "heading": "## Ownership {#ownership}",
      "content": "Platform team owns provisioning, upgrades, and the backup policy. File a ticket in\n`platform/infra` for a new instance.",
      "sourceLayer": "company",
      "sourceUpdated": "2026-05-01"
    }
  ]
}
```

## Reading each part {#reading-each-part}

**`id`** is the concept path, stable across every layer that defines it.

**`contributors`** lists every layer that has a version of this concept at
all — as `{layer, level, updated}` objects, ordered by precedence — including
layers that didn't win any section shown, so an agent can see the full set
of voices, their precedence, and how fresh each one is.

**`frontmatter` / `frontmatterProvenance`** — frontmatter is field-merged,
not replaced. Each key in `frontmatterProvenance` names the layer the final
value came from; here personal defined all five fields, so personal wins all
five, even though team and company also define this concept.

**`sections[].key` / `heading`** — `key` is the section's merge identity
across layers (the `{#anchor}` when one is authored); `heading` is the
winning layer's raw heading line. Merging is per section, not per document:
`rationale` was won by team (level 2), while `ownership` was inherited
straight from company (level 0) because no higher layer spoke to it. A
higher layer doesn't have to restate what it agrees with.

**`sections[].sourceLayer` / `sourceUpdated`** — provenance and freshness,
per section. `sourceUpdated` is the winning section's date, falling back to
its document's date.

**`sections[].conflicts`** — where a section has more than one layer's
version, the losing layers ride along here — layer, `updated` date, and
full content — instead of being discarded. The `rationale` section shows
company's dissenting take, dated `2026-05-01`, so the agent can weigh the
older company line against the newer team rationale. A section with no
disagreement, like `ownership`, omits `conflicts` entirely. When a dissent
is *newer* than the effective value (compared at day granularity), the
section also carries `fresherDissent: true` — not the case here, since
company's line predates the team's. Dissent that differs from the winner
only by formatting (trailing whitespace, bullet glyphs, blank-line runs) is
not disagreement and is dropped before any of this.

Over MCP, `read_file` returns this object plus a rendered `markdown` view
of the same content, where each dissent is quoted beneath the winning
section with its layer and date.

## Why this shape, not just plain text {#why-this-shape}

An agent reading only `content` per section gets a fluent, coherent answer.
An agent that also reads `sourceLayer` and `conflicts` can reason about
trust and staleness explicitly — "this is the team's current call, and it
overrides an older, more conservative company default" — instead of
silently inheriting whichever layer happened to answer first.

## Next {#next}

- `use-cases/personal-team-company-context.md` — the three-layer scenario
  this response is drawn from
- `examples/layers-json-example.md` — the manifest that produced this
  cascade

---
type: guide
updated: 2026-07-08
---

# Connect an AI agent {#connect-an-ai-agent}

`mcp-server.mjs` is a dependency-free stdio MCP server. It resolves every read
through the same cascade engine as the CLI — section/field merge, precedence,
provenance, per-section conflicts — and exposes the result as MCP tools.

## Start the server {#start-the-server}

Cascade mode, against a manifest:

```bash
node mcp-server.mjs --manifest layers.json
```

Legacy two-layer mode, no manifest file required:

```bash
node mcp-server.mjs --personal ~/kb-personal --shared ~/kb-shared
```

`--help` prints usage for both forms.

> **Caution:** the manifest is a trust boundary. A layer with `"source": "mcp"`
> spawns its `command` with `args` as your user. Only point `--manifest` at a
> config you trust — same model as any MCP client config.

## Register it as an MCP server {#register-it-as-an-mcp-server}

Use absolute paths — MCP clients spawn the server from their own working
directory, not yours. For Claude Code:

```bash
claude mcp add contextcake -- node /ABS/PATH/mcp-server.mjs --manifest /ABS/PATH/layers.json
```

The server identifies itself over the MCP `initialize` handshake as
`contextcake`. Any MCP-compatible client can spawn it the same way: `command`
is `node`, `args` are the script path and flags.

## What the agent gets {#what-the-agent-gets}

| Tool | What it returns |
|------|------------------|
| `search` | One entry per matching concept ID, with a snippet and the contributing layers. |
| `read_file` | The resolved effective concept: merged sections, frontmatter, provenance, per-section `conflicts`. Pass `layer` to instead read one layer's raw, unmerged concept. |
| `list_concepts` | Every effective concept ID across the cascade with its contributing layers. |
| `get_links` | Outgoing and incoming links for a concept, resolved against the effective graph. |

Every `read_file` response carries `contributors` (each layer with its
last-updated date), `frontmatterProvenance` (which layer set each frontmatter
field), and sections tagged with the `sourceLayer` that won them.

## Why this is safe for an agent to read directly {#why-this-is-safe}

Where layers disagree on a section, the losing layers' content rides along as
that section's `conflicts` array instead of being dropped. The agent can quote
the winning value as authoritative, but it can also see *that* there's a live
disagreement, who holds each position, and when each side was last updated —
so it can flag the disagreement to a human instead of silently picking a side,
or weight a personal-layer note lower than a company-layer policy when they
conflict.

## Try it against the demo {#try-it-against-the-demo}

```bash
node mcp-server.mjs --manifest apps/playground/manifest.json
```

Then call `read_file` with `concept_id: "decisions/primary-db"` from your
agent — the bundled demo layers deliberately disagree on that concept, so
you'll see a populated `conflicts` array on the first try.

## Next {#next}

- `tool-guides/using-with-claude-code.md` — the same setup, Claude Code specific
- `tool-guides/pointing-an-agent-at-the-resolved-graph.md` — tool-agnostic consumption patterns

---
type: guide
updated: 2026-07-08
---

# Installing ContextCake {#installing-contextcake}

ContextCake installs from a **versioned release archive**, not `npm install`. The
engine is dependency-free — no install scripts run, and nothing is fetched after
you unpack the archive.

## Prerequisites {#prerequisites}

- Node.js >= 18
- `gh` for the terminal download path, or a browser for manual download

## Download and unpack {#download-and-unpack}

```bash
gh release download --repo siracusa5/context-cake --archive=tar.gz --output contextcake.tar.gz
mkdir contextcake
tar -xzf contextcake.tar.gz -C contextcake --strip-components=1
cd contextcake
```

You can also grab the archive from the latest GitHub release page and unpack it
by hand. Either way, what you get is plain `.mjs` scripts and a couple of JSON
fixtures — nothing to build, nothing to compile.

## Why an archive, not a package registry {#why-an-archive}

Package registries have repeatedly shipped compromised AI/agent tooling through
hijacked maintainer accounts and `postinstall` payloads. A knowledge engine your
agents read from should have a supply chain you can audit: a tagged archive is
small, inspectable, and runnable as plain Node.js — no transitive dependency tree
to trust.

## Verify the install {#verify-the-install}

Resolve a concept from the bundled three-layer demo, where the layers
deliberately disagree:

```bash
node resolver.mjs --manifest apps/playground/manifest.json --concept decisions/primary-db
```

The JSON output shows `contributors` (each layer and its last-updated date),
per-section `sourceLayer` (which layer won each section), and `conflicts` on
sections where layers disagree.

Run the full test suite (requires `bash`):

```bash
npm test
```

## The CLI entry points {#the-cli-entry-points}

| Tool | Run with |
|------|----------|
| Cascade resolver | `node resolver.mjs --manifest <file> --concept <id>` |
| MCP server for agents | `node mcp-server.mjs --manifest <file>` |
| Interactive playground | `npm run playground` (http://127.0.0.1:8790) |
| Signal ingestion | `node ingest.mjs --events <file> --out <file>` |
| Layer bundle writer | `node write.mjs --signals <file> --manifest <file> --target-layer <name>` |

Every script accepts `--help` and prints its own usage.

## Source checkout (optional) {#source-checkout-optional}

Use a git checkout only if you want to inspect history, contribute, or pin your
own fork — it is not the primary install path:

```bash
git clone https://github.com/siracusa5/context-cake.git
cd context-cake
```

## Next {#next}

- `getting-started/your-first-cascade.md` — build your own two-layer manifest and resolve a concept
- `getting-started/writing-a-layer.md` — author your first OKF concept file

---
type: guide
updated: 2026-07-08
---

# Writing a layer {#writing-a-layer}

A layer is a directory of OKF (Open Knowledge Format) markdown files. This is
the file shape every `okf-local` layer resolves from.

## Concept ID = file path {#concept-id-equals-file-path}

A concept's ID is its file path within the layer's directory, minus `.md`. The
file `decisions/primary-db.md` is the concept `decisions/primary-db`. That ID
must be **stable across layers** — company, team, and personal can each hold a
file at `decisions/primary-db.md`, and the resolver treats all three as
contributions to one effective concept.

## Frontmatter {#frontmatter}

Every concept file starts with YAML frontmatter. The only required field is
`type`:

```markdown
---
type: decision
updated: 2026-06-20
---
```

`updated` is not required by the engine but you should always set it — it is
the entire staleness signal. There is no separate drift-detection subsystem;
when layers disagree on a section, an agent (or you) judges recency by
comparing `updated` dates across the `conflicts` entries. A layer that forgets
to bump `updated` after a real change won't be flagged automatically.

## Sections need anchors {#sections-need-anchors}

Every heading that should resolve as an independently-mergeable unit needs a
`{#anchor}`:

```markdown
## Engine {#engine}

SingleStore (chosen for HTAP workloads).

## Backups {#backups}

Nightly snapshots to cold storage.
```

The anchor, not the heading text, is the merge key. Two layers with `## Engine
{#engine}` are contributing to the *same* section even if they word the
heading slightly differently; keep anchors identical across layers for a
concept you intend to merge.

## How a higher layer overrides a section {#how-a-higher-layer-overrides-a-section}

Default behavior is **section merge, not whole-document replacement**. A
higher-precedence layer only needs to restate the sections it actually
disagrees with or adds to:

```markdown
<!-- team layer, overriding only Engine -->
## Engine {#engine}

SingleStore (chosen for HTAP workloads).
```

If `team` doesn't mention `Backups` at all, the resolved concept still
contains `Backups`, inherited untouched from whichever lower layer defines it.
Nothing needs to be copy-pasted forward.

## Two escape hatches {#two-escape-hatches}

- `override: full` in frontmatter replaces the **entire** concept for that
  layer and below — use sparingly, it forfeits section-level inheritance.
- `{#anchor override=none}` on a heading is a tombstone: it suppresses an
  inherited section without restating content to negate it. The suppression
  is retained as `suppressed: true` for audit, so it's visible, not silent.

## Next {#next}

- `getting-started/your-first-cascade.md` — resolve a two-layer example end to end
- `getting-started/connect-an-ai-agent.md` — expose the resolved graph to an agent over MCP

---
type: guide
updated: 2026-07-08
---

# Your first cascade {#your-first-cascade}

The fastest way to see the merge engine work is to build a two-layer manifest by
hand and resolve a concept that exists in both layers.

## Two ways to do this {#two-ways-to-do-this}

- Build the tiny manifest below (five minutes, teaches you the mechanics), or
- Run `npm run playground` and open the bundled three-layer demo at
  `http://127.0.0.1:8790` to see the same merge rendered visually — precedence
  chain, winning sections, and conflict panels side by side.

Both read the same engine. The manifest path is described here.

## Create two layers {#create-two-layers}

Each layer is a directory of OKF markdown. Create a company layer and a team
layer, both defining the same concept ID:

```bash
mkdir -p ~/kb-company/decisions ~/kb-team/decisions
```

```markdown
<!-- ~/kb-company/decisions/primary-db.md -->
---
type: decision
updated: 2026-05-01
---

## Engine {#engine}

Postgres.

## Backups {#backups}

Nightly snapshots to cold storage.
```

```markdown
<!-- ~/kb-team/decisions/primary-db.md -->
---
type: decision
updated: 2026-06-20
---

## Engine {#engine}

SingleStore (chosen for HTAP workloads).
```

The concept ID is the file path minus `.md` — `decisions/primary-db` — and it is
stable across layers on purpose: both files describe the *same* concept from a
different vantage point.

## Write the manifest {#write-the-manifest}

```json
{ "layers": [
  { "name": "team",    "level": 2, "path": "~/kb-team" },
  { "name": "company", "level": 0, "path": "~/kb-company" }
] }
```

`source` defaults to `okf-local` when omitted, so a plain directory `path` is
enough — you don't need to spell out `"source": "okf-local"` for local layers.

## Resolve it {#resolve-it}

```bash
node resolver.mjs --manifest layers.json --concept decisions/primary-db
```

`team` is level 2, `company` is level 0, so `team` wins `Engine` — and because
`company` disagrees on that same section, its value rides along as a
`conflicts` entry instead of being dropped. `Backups` isn't mentioned in
`team`'s file at all, so it's inherited from `company` untouched, with no
conflict.

That's the whole model: higher layer wins **per section**, unmentioned sections
inherit, and disagreements are surfaced with dates rather than silently
overwritten.

## Or just run the playground {#or-just-run-the-playground}

```bash
npm run playground
```

Open `http://127.0.0.1:8790` and select `decisions/primary-db` in the bundled
demo (`apps/playground/demo-layers/`, three layers: personal/team/company) to see
the same contributors, sourceLayer tags, and conflict panels in the inspector,
without writing any files yourself.

## Next {#next}

- `getting-started/writing-a-layer.md` — the OKF concept file shape in full
- `getting-started/connect-an-ai-agent.md` — expose this same resolved graph over MCP

---
type: nuance
updated: 2026-07-08
---

# Conflicts are surfaced, not hidden {#conflicts-are-surfaced-not-hidden}

When two layers define the same section with different content, ContextCake
does not quietly pick the higher layer and discard the rest. The losing
layer's value rides along as a first-class part of the response.

## The shape: `conflicts[]` on a section {#the-shape}

Every resolved section can carry an optional `conflicts` array, one entry
per dissenting contributor:

```json
{
  "key": "choice",
  "heading": "## Choice {#choice}",
  "content": "Postgres in every shared environment...",
  "sourceLayer": "personal",
  "sourceUpdated": "2026-06-28",
  "conflicts": [
    {
      "layer": "company",
      "updated": "2026-05-01",
      "content": "Postgres (org standard). All services provision managed RDS..."
    }
  ]
}
```

`sourceLayer` and `sourceUpdated` describe the winner. Each entry in
`conflicts` describes a layer that defined the same section differently —
its name, when it was last updated, and its full content, not just a diff.
An agent reading this gets the primary answer plus everything it would need
to disagree with that answer if the dissenting version turns out to matter
more in context.

## Silent resolution is the common case {#silent-resolution-is-common}

Most sections do not conflict. A section resolves silently — no `conflicts`
key at all — when only one layer defines it (pure inheritance, nothing to
disagree about) or when multiple layers define it identically. Conflicts
only appear where layers actually disagree on content, which in practice is
the minority of sections in a healthy knowledge base. Suppressed sections
(`{#anchor override=none}`) also emit no conflicts — the suppression itself
is the answer, not a disagreement to record.

## Layer plus date, not a full diff engine {#layer-plus-date}

The provenance ContextCake attaches is deliberately narrow: which layer said
this, and when that layer last touched it. It is not a change history, not
a diff against the winning value, and not an explanation of *why* the
layers disagree. That judgment call is left to whoever — human or agent —
reads the resolved concept. The `updated` date is enough to answer the one
question that matters most: is the dissenting version newer than the
version that won? See `nuances/precedence-and-recency.md` for why a newer
loser does not become the winner automatically.

## The old shadow/hash drift detector is gone {#shadow-hash-detector-is-gone}

An earlier version of the engine tried to catch staleness a different way:
hashing each layer's content and flagging when a lower layer's underlying
value silently drifted out of sync with what a higher layer had overridden
(`detectShadow`, `--shadow`, `--hash`, `hashConcept`, and the
`overrides_ref`/`overrides_layer` metadata that supported it). That whole
subsystem has been removed. There is no hash comparison running anywhere in
the current engine, and no `--shadow` or `--hash` flags to reach for.

Staleness is now surfaced entirely through `conflicts[]` plus each
contributor's `updated` date — the same mechanism that surfaces
disagreement in general. This is a real, accepted tradeoff: it trusts
authors to bump a concept's `updated` field when they actually change
content. A base-layer edit that forgets to bump the date will not show up
as newer than it should, where the old hash mechanism would have caught
content drift regardless of whether a date changed. The project has chosen
simplicity over that guarantee; if lax date discipline becomes a real
problem in practice, the documented fallback is a stitch-time content
fingerprint computed at read time with no author action required — but that
is explicitly not built today.

## What this means for you {#what-this-means-for-you}

Do not build tooling or agent prompts that assume ContextCake will flag
stale content automatically. It will not scan your layers looking for drift.
What it will do, reliably, is show you every layer's answer and every
layer's date whenever there is disagreement — the judgment step is yours or
your agent's, every time.

## Next {#next}

- `nuances/precedence-and-recency.md` — why the winning layer does not
  change just because a dissenting value is newer
- `overview/mental-model.md` — the layer stack this conflict model sits on

---
type: nuance
updated: 2026-07-08
---

# The engine is dependency-free {#the-engine-is-dependency-free}

The core of ContextCake — the resolver, the source adapters, the CLI tools —
runs on plain Node.js (>= 18) built-ins only. No npm packages. `npm install`
in the repo root has nothing to install; the engine simply requires none.

## What that covers {#what-that-covers}

The dependency-free boundary applies to the engine surface:

- `resolver.mjs` — the cascade engine: OKF parsing, section merge,
  precedence, provenance, conflict surfacing
- `packages/core/src/sources/okf-local.mjs`, `packages/core/src/sources/mcp.mjs`, `packages/core/src/sources/index.mjs` — the
  source-adapter layer
- `mcp-server.mjs` — the stdio MCP server that exposes the resolved graph
- `classify-context.mjs`, `ingest.mjs`, `write.mjs`, `promote.mjs` — the
  write path
- `apps/playground/` — the interactive playground ships its own dependency-free
  HTTP server (`server.mjs`) rather than pulling in a framework

If you are integrating against ContextCake as a library or spawning
`mcp-server.mjs` as a subprocess, you are not inheriting any transitive
dependency tree. That is a deliberate property, not an accident of the
current version — it keeps the trust surface small, especially given that
the manifest can spawn arbitrary MCP server processes (see the security note
in `nuances/what-contextcake-is-not.md`).

## What is exempt: `apps/console/` and `apps/site/` {#what-is-exempt}

Two parts of the repository are explicitly carved out of this rule, and
carved out *cleanly* — they are separate npm packages with their own
`package.json`, their own build step, and their own dependency tree:

- `apps/console/` — a React + Vite + TypeScript web UI (the ContextCake Console),
  deployed to Cloudflare Pages
- `apps/site/` — the public product site and docs, built on Astro + Starlight

Both exist because a real UI and a real docs site are reasonable things to
want npm's ecosystem for, and pretending otherwise would just mean
reinventing a worse version of React or Astro by hand. The boundary that
matters is that **neither imports from the engine as a library** — they
talk to it the same way any other consumer would: `apps/console/` calls the
resolved graph over its API surface, and `apps/site/` just documents the engine,
it does not embed it.

## Why this boundary is enforced, not just documented {#why-enforced}

Adding an npm dependency to the engine is explicitly gated: it requires
asking first, per the project's boundaries (see the design doc's
constitution-style rules). This is not bureaucracy for its own sake — a
dependency-free engine is easier to audit line by line, easier to vendor or
embed in another tool without pulling in a `node_modules` tree, and easier
to trust when it is already spawning subprocesses declared in a manifest
you may or may not have authored yourself.

If you are contributing to ContextCake and find yourself reaching for a
package to solve something in `resolver.mjs` or `packages/core/src/sources/`, that is a
signal to slow down and either solve it with built-ins or raise the
question explicitly — not a signal to `npm install` and move on.

## What this means for you {#what-this-means-for-you}

- Running the engine (`node mcp-server.mjs --manifest layers.json`, `node
  resolver.mjs ...`) never requires an `npm install` step.
- `apps/console/` and `apps/site/` do require `npm install` / `npm ci` — run those
  commands from inside those subdirectories, not the repo root.
- If you are writing your own source adapter or extending the engine, keep
  it to built-ins, or expect to have that conversation before it lands.

## Next {#next}

- `nuances/what-contextcake-is-not.md` — the manifest-as-trust-boundary
  point this dependency discipline supports

---
type: nuance
updated: 2026-07-08
---

# Precedence and recency {#precedence-and-recency}

The rule sounds simple — higher layer wins — but it is worth being precise
about what "higher" means, because it is easy to assume recency plays a
role when it does not.

## Level dominates, full stop {#level-dominates}

Precedence is decided purely by the layer's `level` in the manifest. If
Personal (level 3) and Company (level 0) both define the `Choice` section
of a concept, Personal wins that section — even if the Company section was
edited an hour ago and the Personal section has not been touched in months.
Level is a static, configured fact about the layer, not something that
shifts based on which edit happened most recently.

This is a deliberate simplification. An earlier version of the resolver
considered same-level recency (`updated=` timestamps) as a tiebreak. That
logic is gone: with three distinct default levels (3, 2, 0), there is no
same-level tie to break, and the design explicitly cut the recency-tiebreak
and DAG same-level resolution machinery as unnecessary complexity.

## No same-level ties in the default stack {#no-same-level-ties}

Because Personal, Team, and Company sit at three distinct levels by default,
there is no built-in rule for what happens when two layers share a level —
the situation does not arise unless you configure it that way yourself. If
you add a layer and give it the same level as an existing one, you are
opting into undefined tie behavior; the supported model is one layer per
level.

## Order is a visible setting {#order-is-a-visible-setting}

Nothing about precedence is implicit. The levels live in `layers.json`,
readable and editable:

```json
{ "layers": [
  { "name": "personal", "level": 3, "source": "okf-local", "path": "~/kb-personal" },
  { "name": "team",     "level": 2, "source": "okf-local", "path": "~/kb-team" },
  { "name": "company",  "level": 0, "source": "mcp", "command": "node", "args": ["./company-graph-server.mjs"] }
] }
```

If you want Team to outrank Personal for some reason, that is a one-line
manifest edit, not a code change. The tradeoff is that whoever edits the
manifest controls precedence for everyone reading through that manifest —
treat it with the same care as any config that changes what "the truth"
means for your agents.

## Recency still matters — just not for winning {#recency-still-matters}

Dropping recency from the precedence rule does not mean dates are ignored.
Every resolved section carries `sourceUpdated`, and every conflict carries
its own `updated` date. Recency is the signal you use to judge a resolved
answer, not the rule that produces it. If Company's dissenting value on a
section is dated *after* the Personal value that won, you see that
juxtaposition directly — a newer, lower-precedence value sitting next to an
older, higher-precedence one — and decide for yourself whether the win is
still the right call. See `nuances/conflicts-are-surfaced-not-hidden.md`.

## The flapping tradeoff {#the-flapping-tradeoff}

Precedence-by-level rather than precedence-by-recency is a real tradeoff,
not a free lunch. The alternative — let the most recently updated layer win
regardless of level — sounds appealing until you picture it running: any
layer could reclaim precedence on a section just by touching it, so the
"winner" for a given section could flap back and forth depending on who
edited last, with no floor. A personal scratch note touched five minutes
ago would out-rank a carefully reviewed company policy from last month.

Fixed levels trade that instability for a small amount of staleness risk
(a section can go stale under a layer that outranks it and nothing forces a
re-check) in exchange for an answer that does not change identity just
because someone edited an unrelated layer. Given the resolver runs fresh at
every read anyway (see `overview/mental-model.md`), staleness is visible the
moment you look, which is judged an acceptable price for predictable
winners.

## Next {#next}

- `nuances/conflicts-are-surfaced-not-hidden.md` — how dissent and dates are
  represented on a resolved section
- `overview/mental-model.md` — the layer cake this precedence rule governs

---
type: nuance
updated: 2026-07-08
---

# What ContextCake is not {#what-contextcake-is-not}

The one-sentence description says what ContextCake does. This file is the
mirror image: the things people reasonably assume it is, that it deliberately
is not.

## Not a knowledge store, database, or source of truth {#not-a-knowledge-store}

ContextCake owns nothing. Every layer's knowledge lives exactly where it
lived before ContextCake showed up — a git repo of OKF markdown on disk, or
a foreign graph behind an MCP server. The resolver reads those sources fresh
at request time and hands back a stitched view; it does not copy the data
into a database, does not cache a merged snapshot as a new authoritative
copy, and does not become the place anyone should go to *edit* knowledge.
Edit the layer, not a ContextCake-owned copy — there isn't one. If you
deleted the resolver and the MCP server entirely, every layer's knowledge
would be completely intact and exactly as authoritative as before.

This also means ContextCake never resolves *disputes* about what is true —
it resolves *precedence*, which is a much narrower and more honest claim.
See `nuances/conflicts-are-surfaced-not-hidden.md` for how it represents
disagreement instead of adjudicating it.

## Not a graph database with node-level access control {#not-a-graph-database-with-rbac}

There is no per-node or per-field permission system inside ContextCake, and
none is planned. Access control is inherited entirely from whatever already
gates each layer's underlying source — in the common case, git repo
membership. If you can clone the team repo, you can read everything in the
team layer through ContextCake; if you cannot, that layer simply does not
contribute to your resolved view. There is no finer-grained control than
"which repos can you read," and no ContextCake-specific ACL to configure,
audit, or get out of sync with reality.

This is a feature, not a missing feature: it means access control is exactly
as strong (or weak) as your existing repo permissions, with nothing new to
maintain. But it also means ContextCake cannot do things a real graph
database with RBAC could — like letting one person see a sensitive section
of a concept that a teammate with the same repo access cannot.

## Not a silent auto-merger {#not-a-silent-auto-merger}

ContextCake never resolves a disagreement between layers by quietly picking
one side and dropping the other. Every conflict — same section, different
content, different layers — is preserved and surfaced with its source layer
and date, not merged away into a single blended answer and not silently
overwritten. See `nuances/conflicts-are-surfaced-not-hidden.md` for the
exact shape of that surfacing. The only things that behave like a merge
override are the two explicit, opt-in mechanisms in the override table:
`override: full` (whole-concept replacement, stated in frontmatter) and
`{#anchor override=none}` (a tombstone that blanks one inherited section,
retained as `suppressed: true` for audit). Both require the higher layer to
say so explicitly — nothing is suppressed or merged away by inference.

## The manifest is a trust boundary, not a config file {#the-manifest-is-a-trust-boundary}

This is not a "what it's not" claim so much as a related warning worth
repeating here: an `mcp`-sourced layer in `layers.json` spawns `command`
with `args` taken directly from that file. A manifest is not inert
configuration — pointing `--manifest` at a file you did not author or trust
means letting it run arbitrary commands as your user, exactly like pointing
any MCP client at an untrusted server config. Treat `layers.json` with the
same suspicion you would treat any other executable-adjacent config, not the
same casualness you'd give a `.env` file.

## Next {#next}

- `overview/what-is-contextcake.md` — what it actually is, stated positively
- `nuances/dependency-free-engine.md` — why the engine's trust surface is
  kept deliberately small
- `nuances/conflicts-are-surfaced-not-hidden.md` — how disagreement is
  represented instead of merged away

---
type: overview
updated: 2026-07-08
---

# The mental model {#the-mental-model}

One picture carries most of what you need: three layers, stacked by level,
higher wins.

```
Personal  (level 3)  ← your drafts, notes, overrides
────────────────────
Team      (level 2)  ← runbooks, decisions, system docs
────────────────────
Company   (level 0)  ← org-wide canonical knowledge
```

## Levels, not names, decide precedence {#levels-decide-precedence}

`personal`, `team`, and `company` are the default names, but what actually
governs precedence is the numeric `level` each layer declares in the
manifest — 3, 2, and 0 by default. The gaps (skipping 1) are intentional:
they leave room to slot another layer into the stack later without
renumbering everything above it. Levels are a visible, configurable setting
you read straight out of `layers.json` — not hidden logic baked into the
engine. See `nuances/precedence-and-recency.md` for what happens at the
edges of this rule.

## Higher wins — per section, not per document {#higher-wins-per-section}

This is the detail that makes the model actually useful instead of just
simple. When the same concept exists in two layers, the higher layer does
not replace the whole document — it wins only the sections it actually
speaks to. Everything it stays silent on is inherited from the layer below.

```markdown
<!-- Company layer: decisions/primary-db.md -->
[Engine] {#engine}
Postgres.

[Backups] {#backups}
Nightly snapshots to cold storage.

<!-- Team layer: decisions/primary-db.md -->
[Engine] {#engine}
SingleStore (chosen for HTAP workloads).

<!-- Effective (what agents see): -->
[Engine]        -- Team wins
SingleStore (chosen for HTAP workloads).

[Backups]       -- inherited from Company
Nightly snapshots to cold storage.
```

Team only spoke to `Engine`. It said nothing about `Backups`, so that
section flows through from Company untouched. Nothing is lost just because a
higher layer happened to weigh in on a neighboring section — the guiding
rule is **no knowledge lost**.

## One effective graph at read time {#one-effective-graph-at-read-time}

Nothing is pre-merged or cached into a fourth copy of the data. Each layer's
source stays exactly where it lives — a git bundle on disk, or a foreign
graph behind an MCP server — and the resolver (`resolver.mjs`) walks all of
them fresh every time an agent asks for a concept, stitching the result into
one effective OKF concept on the spot. Ask again after someone edits the
team layer, and the new answer reflects that edit immediately, with no sync
step in between.

This is also why the same concept ID can exist in every layer at once and
still resolve to one answer: a concept's ID is its file path within the
bundle (minus `.md`), and it is stable across layers — `decisions/primary-db.md`
in Company, Team, and Personal are three contributions to the *same*
effective concept `decisions/primary-db`, not three different concepts.

## What a resolved answer carries {#what-a-resolved-answer-carries}

An agent reading a resolved concept through the MCP server's `read_file`
tool does not just get merged text — it gets provenance: which layer won
each section (`sourceLayer`), when that layer last touched it
(`sourceUpdated`), and which layers contributed at all (`contributors`).
Where layers disagree, the dissenting versions ride along too. See
`nuances/conflicts-are-surfaced-not-hidden.md`.

## Next {#next}

- `nuances/precedence-and-recency.md` — ties, staleness, and the flapping
  tradeoff
- `nuances/conflicts-are-surfaced-not-hidden.md` — what happens when layers
  disagree

---
type: overview
updated: 2026-07-08
---

# The problem it solves {#the-problem-it-solves}

## Blank-context agents {#blank-context-agents}

Every new AI session starts from zero. You explain the same architecture
decisions, the same team conventions, the same "no, we don't use that
anymore" corrections, over and over, because the agent has no durable place
to keep what it learned last time. Multiply that across a team and the
re-explaining tax compounds: the same context gets typed out by five
different engineers into five different chat windows, none of which talk to
each other.

The instinct is to write it down somewhere the agent can read it. That
mostly works — until "somewhere" turns out to be three somewheres.

## Separate graphs, separate access, no bridge {#separate-graphs-separate-access}

Knowledge about a codebase or a team accumulates at different scopes, and
those scopes naturally end up in different systems with different access
rules:

- **Personal** — your own notes, half-finished decisions, drafts you are not
  ready to share. Lives in something only you can read.
- **Team** — runbooks, architecture decisions, the stuff your team agreed on
  last sprint. Lives in a repo your team can clone.
- **Company** — org-wide policy, canonical infrastructure choices, the
  things that apply everywhere. Often lives behind a completely different
  tool with its own API.

These graphs do not talk to each other by default, and there is no reason
they ever would — nobody is going to build and maintain a sync job between a
personal notes vault and a company wiki just so an AI agent has one thing to
query. Left alone, an agent working in your repo can see at most one of
these layers at a time, and has no way to know what it's missing.

## Why not one unified graph {#why-not-one-unified-graph}

The tempting fix is to dump everything into a single shared knowledge base.
It fails for the same reason a single shared notes app fails for humans:
personal drafts do not belong in company policy, team-specific decisions do
not belong at company scope, and access control gets flattened — either
everyone sees everything, or you rebuild a bespoke permission system on top
of a system that was not designed for one. You also lose the signal of
*where* a fact came from and *who* is authoritative for it.

## Why not fully siloed graphs {#why-not-fully-siloed-graphs}

The opposite failure is doing nothing: leave personal, team, and company
knowledge in their separate systems and let agents query at most one at a
time. This is where most teams actually are today. It preserves access
control perfectly but reproduces the blank-context problem at a higher
level — the agent still has to be pointed at the right source manually, and
still cannot see the other two layers' relevant context, even when they
would change the answer.

## Federated, with precedence {#federated-with-precedence}

ContextCake's answer is federation instead of unification: leave each layer
where it lives, in the system that already governs its access, and resolve
across them only at read time. Each layer stays a `source` behind a uniform
adapter — a local OKF bundle or a foreign graph reached over MCP — so access
control is inherited for free from whatever already gates that source (repo
membership, in the common case).

On top of federation, precedence gives agents a single coherent answer
instead of three disconnected ones: higher layers win per section, and
where layers disagree, the resolver does not hide it — it shows the primary
answer plus every dissenting layer's version and date. See
`overview/mental-model.md` for how the stack works, and
`nuances/conflicts-are-surfaced-not-hidden.md` for how disagreement is
represented.

This gets you the best of both failed approaches without their costs: one
coherent view for the agent, and access control that was never
ContextCake's to build in the first place.

## Next {#next}

- `overview/mental-model.md` — the layer cake in one picture
- `nuances/dependency-free-engine.md` — how the resolver stays a thin,
  auditable layer instead of a new system to operate

---
type: overview
updated: 2026-07-08
---

# What ContextCake is {#what-is-contextcake}

ContextCake stitches your separate knowledge graphs — personal, team, company —
into one OKF graph your agent can read, returning a primary answer and being
honest about contradictions: which layers disagree, and when each was last
updated.

Unpack that sentence and there are two ideas doing the work:

## Stitch {#stitch}

Your knowledge already exists. It just lives in separate places behind
separate access: a personal notes repo only you can read, a team runbook
repo your team can clone, a company graph reachable only through some other
tool's API. Those graphs do not talk to each other today, and they never
will by default — nobody is going to write a sync job between your personal
notes and the company wiki.

ContextCake is the layer that makes them talk. It does this by treating each
graph as a `source` behind a uniform adapter — either a local OKF bundle (a
git repo of markdown) or a foreign graph reached over MCP and translated
into OKF at read time — and resolving all of them into **one effective OKF
concept** whenever an agent asks for something. See
`overview/mental-model.md` for how the layers stack and win.

## Surface conflicts honestly {#surface-conflicts-honestly}

Stitching sources together raises an obvious question: what happens when
they disagree? ContextCake's answer is to never silently pick a winner and
throw the rest away. It returns one primary answer — decided by layer
precedence — and attaches every dissenting layer's version alongside it,
tagged with that layer's name and its last-updated date. See
`nuances/conflicts-are-surfaced-not-hidden.md` for the mechanics.

That date is the whole staleness story. There is no separate drift-detection
subsystem watching for changes behind your back — you read the primary
answer, see what other layers said and when, and judge for yourself whether
the winner is actually the most current truth.

## It owns no source of truth {#owns-no-source-of-truth}

This matters enough to say plainly: ContextCake is not a knowledge store,
not a database, and not where your knowledge "lives." The company repo is
still the company's source of truth for company decisions; the team repo is
still the team's. ContextCake reads those sources at request time and hands
back a resolved view — it does not copy, own, or become authoritative over
any of them. Delete ContextCake and every layer's knowledge is exactly where
it was before. See `nuances/what-contextcake-is-not.md` for the fuller
boundary.

## Who it's for {#who-its-for}

Two audiences, same artifact:

- **Developers** who are tired of re-explaining team context to an AI agent
  every session, or who want their personal notes, team decisions, and
  company policy to show up as one coherent answer instead of three
  disconnected searches.
- **AI agents** themselves — this pack, and the resolved OKF graph it
  describes, are meant to be read as context. An agent that understands the
  layer cake and the conflict model can reason about which answer to trust
  without a human mediating every lookup.

## Where to go next {#where-to-go-next}

- `overview/the-problem-it-solves.md` — why federated layers beat one big
  graph or fully separate ones
- `overview/mental-model.md` — the layer cake, in one picture
- `nuances/precedence-and-recency.md` — how ties and staleness actually work

---
type: tool-guide
updated: 2026-07-08
---

# Pointing any agent at the resolved graph {#pointing-any-agent-at-the-resolved-graph}

`mcp-server.mjs` speaks plain MCP over stdio. Nothing about it is
Claude-specific — any MCP-capable client (Cursor, a custom agent harness, your
own MCP client library) can spawn it the same way and get the same resolved
cascade. This guide is the tool-agnostic version.

## Spawning the server {#spawning-the-server}

Every MCP client config reduces to a command and arguments:

```json
{ "command": "node", "args": ["/ABS/PATH/mcp-server.mjs", "--manifest", "/ABS/PATH/layers.json"] }
```

Use absolute paths — the client spawns the process from its own working
directory, not the manifest author's. The server identifies itself over the
MCP `initialize` handshake as `contextcake`.

> **Caution:** the manifest named in `--manifest` is a trust boundary: a layer
> with `"source": "mcp"` spawns its own `command` with `args` as your user.
> Only point any client at a manifest you trust.

## The four tools {#the-four-tools}

| Tool | Input | Returns |
|------|-------|---------|
| `search` | `query`, optional `limit` | One entry per matching concept, with a snippet and contributing layers |
| `read_file` | `concept_id`, optional `layer` | The resolved effective concept: merged sections, frontmatter, provenance, per-section `conflicts`. With `layer`, one layer's raw unmerged concept instead. |
| `list_concepts` | optional `type` filter | Every effective concept ID with its contributing layers |
| `get_links` | `concept_id` | Outgoing and incoming links, resolved against the effective graph |

These are the only four surfaces an agent needs — search to find a concept,
`read_file` to read it resolved, `list_concepts` to enumerate what exists,
`get_links` to walk the graph.

## Weight facts by provenance, not just content {#weight-facts-by-provenance}

Every `read_file` response includes fields an agent should reason over before
treating a value as fact:

- **`contributors`** — every layer holding a version of this concept, with
  its `level` and `updated` date. A `personal` note (level 3) outranks
  `company` (level 0) in the merge, but that doesn't make it more *true* —
  it's one person's view, current as of one date.
- **`frontmatterProvenance`** — which layer set each frontmatter field.
- **Per-section `sourceLayer`** — the winning layer for that section
  specifically. Different sections of the same concept can be won by
  different layers.

A well-behaved agent treats layer level as precedence for which answer to
surface first, not as a proxy for confidence. Company policy on a compliance
question should usually outrank a personal note even if that's not how the
manifest ranks levels for other purposes — build that judgment into the
agent's prompt, not into the engine (the engine only knows numeric levels).

## Respect surfaced conflicts {#respect-surfaced-conflicts}

When a section carries a `conflicts` array, the resolver is telling you
something specific: layers disagree, and it picked a primary answer by
precedence, not by adjudicating who's right. The correct agent behavior is
usually one of:

- State the primary answer, then note the disagreement and who holds it
  (name the layer and its `updated` date) — especially for anything
  consequential (compliance, security, financial decisions).
- If the conflict looks like plain staleness (the losing layer is
  conspicuously older with no rationale), say so, but don't silently resolve
  it — resolution is a human action in ContextCake, not something an agent
  should do unprompted by rewriting a source file.
- Never merge or average conflicting values into a new answer that appears
  nowhere in any layer.

## Next {#next}

- `tool-guides/using-with-claude-code.md` — the Claude Code specific registration steps
- `getting-started/connect-an-ai-agent.md` — starting the server and its flags

---
type: tool-guide
updated: 2026-07-08
---

# Using ContextCake with Claude Code {#using-with-claude-code}

Two ways to give Claude Code the resolved cascade: register the live MCP
server (Claude can read and search the graph at runtime), or hand it this
pack as static context (Claude reads the architecture and conventions, no
running process required). Use both — they answer different questions.

## Option 1: register the MCP server {#register-the-mcp-server}

`mcp-server.mjs` is a dependency-free stdio MCP server. Register it with
absolute paths, since Claude Code spawns the process from its own working
directory:

```bash
claude mcp add contextcake -- node /ABS/PATH/mcp-server.mjs --manifest /ABS/PATH/layers.json
```

No manifest yet, or just trying it out — point at the bundled demo instead:

```bash
claude mcp add contextcake -- node /ABS/PATH/mcp-server.mjs --manifest /ABS/PATH/apps/playground/manifest.json
```

Once registered, Claude has four tools: `search`, `read_file`, `list_concepts`,
`get_links`. Ask it something like "what does the team layer say about our
primary database, and does that conflict with company policy?" — Claude calls
`search` or `read_file` and reasons over the returned `sourceLayer` and
`conflicts` fields instead of guessing.

> **Caution:** the manifest is a trust boundary. A layer with `"source": "mcp"`
> spawns its `command` with `args` as your user. Only register a manifest you
> trust — same model as any other MCP client config.

## Option 2: install this pack as static context {#install-this-pack-as-static-context}

This context pack (the directory these files live in) is itself meant to be
read as context, independent of a running server. Two ways to give it to
Claude Code:

- **Drop it in the repo.** Copy the pack directory into your project (for
  example `.claude/context/contextcake/`) so Claude Code picks it up as part
  of the working tree it already reads.
- **Install as a Claude Code plugin.** Package the pack's `PACK.yaml` and
  module directories following Claude Code's plugin skill-content
  conventions, then reference it from your plugin marketplace or local
  plugin config.

Static context answers "how does ContextCake work and how do I use it here" —
the MCP server answers "what does my resolved graph currently say." Most
setups want the MCP server for live queries and this pack (or its
`overview/` and `architecture/` modules at minimum) for the mental model.

## Verifying the connection {#verifying-the-connection}

```bash
claude mcp list
```

Confirms `contextcake` is registered. Then ask Claude to call `list_concepts`
— if you get back concept IDs and contributing layers, the server is live and
resolving.

## Next {#next}

- `tool-guides/pointing-an-agent-at-the-resolved-graph.md` — the same setup, generalized to any MCP client
- `getting-started/connect-an-ai-agent.md` — the underlying server flags and tool schemas