> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Layers

> How Overdeck delivers layered rules and guidance to managed harness sessions

# Context Layers

Overdeck distributes context — engineering rules, project guidance, machine
quirks — to the coding-agent harnesses it drives through a layered system.
You author small canonical markdown files; `pan sync` renders Overdeck-owned
artifacts that are delivered only when Overdeck launches a managed session.
Overdeck never writes native `CLAUDE.md`, `AGENTS.md`, or equivalent files.

## Canonical terminology

Use these names when adding or moving context; they are the vocabulary the
agents themselves are taught:

| Term | Source file | Use for |
| - | - | - |
| **Bundled rule** | `sync-sources/rules/<name>.md` (ships inside the overdeck package) | Engineering rules for **every machine** |
| **Global layer** (machine context) | `~/.overdeck/context/global.md` | Genuinely **machine-specific** quirks |
| **Project layer** | `<projectRoot>/.overdeck/context/project.md` | Guidance for **one project**; committed to that repo |
| **Workspace layer** | `<workspace>/.overdeck/context/workspace.md` | Auto-assembled per issue workspace; never hand-edited |

The rendered outputs are **managed-session launch artifacts** under `~/.overdeck/context/` — never edit those directly.
Edit the source layer or rule, then run `pan sync`.

<Info>
  There is no "global context template". A request phrased that way means either
  a **bundled rule** (every machine) or the **global layer** (one machine).
</Info>

### The shorthand: "add a `<scope>` rule"

In practice you (and your agents) only need four phrases — the scope word
alone routes the content:

| You say | Applies to | Destination |
| - | - | - |
| "add a **universal rule**: …" | every machine, every project | `sync-sources/rules/<name>.md`, `scope: universal` |
| "add a **dev rule**: …" | Overdeck development only | `sync-sources/rules/<name>.md`, `scope: dev` |
| "add a **project rule**: …" | one project | `<root>/.overdeck/context/project.md` |
| "add a **machine rule**: …" | one machine | `~/.overdeck/context/global.md` |

After any of them: `pan sync`, and the change reaches new sessions.

## Bundled rules

Overdeck ships engineering rules inside the package under
`sync-sources/rules/`. Each rule carries a `scope:` frontmatter key:

* `scope: universal` — folded into every machine's rendered global context;
* `scope: dev` — folded in only on a overdeck source checkout, for rules
  about developing Overdeck itself.

Rules ship with `pan install` and refresh on every `pan sync`.

### Switching a bundled rule off

Every bundled rule is on by default. To switch one off on a machine, name it
under `context.rules` in `~/.overdeck/config.yaml`, with the rule's file
basename as the key:

```yaml theme={null}
context:
  rules:
    ste-writing: false # omit the Simplified Technical English writing rule
```

`false` omits the rule from every rendered launch artifact and the dashboard
Context-page preview. Any absent
key (or `true`) leaves the rule on. The map is read when a managed launch is
composed, so the new render reaches new sessions only.

## What each harness actually reads

Each harness consumes context through its own native mechanism. `pan sync`
keeps inspectable global artifacts and spawn-time plumbing composes one
harness-correct launch artifact from global, project, and workspace layers:

| Harness | Rendered artifact | How the harness receives it |
| - | - | - |
| **Claude Code** | `~/.overdeck/context/claude-global.md` | Passed with Claude's append-system-prompt launch mechanism |
| **Codex** | `~/.overdeck/context/codex-global.md` | Passed as Codex `developer_instructions` for TUI, exec/resume, and app-server transports |
| **Pi** | `~/.overdeck/context/pi-global.md` | Injected into the session's system-prompt context at spawn. Pi does natively support a global `~/.pi/agent/AGENTS.md`; Overdeck deliberately does not write there — the global layer is delivered per-spawn instead, leaving `~/.pi/agent/` entirely yours |
| **Kimi Code** | `~/.overdeck/context/launch/kimi-code-<workspace-hash>.md` | Sent once per native Kimi session as a clearly delimited first-user-message envelope. The managed context block comes first and the operator's original task follows unchanged in its own block |
| **Prime Agent** | `<agentDir>/prime-agent-context.md` (per agent) | Passed as `--append-system-prompt` values after Overdeck's managed policy, split on paragraph boundaries into values of at most 100,000 bytes. Overdeck writes nothing under `~/.prime/agent` |

The `claude-global.md` / `pi-global.md` / `codex-global.md` files are **Overdeck-owned render
artifacts** — the harnesses do not know about them. They exist so the global
layer has a stable, inspectable rendered form per harness.

The persisted `.overdeck/context/workspace.md` is **harness-neutral** and does
not contain a pre-rendered project layer. At launch, Overdeck renders the
canonical project source for the active harness and combines it exactly once
with global rules and workspace-only content. User-authored native files remain
entirely user-owned and are still available through each harness's normal
discovery behavior.

## Native files are a no-touch boundary

Normal install, sync, startup, workspace, and agent lifecycle paths do not
create, edit, clean, back up, delete, or migrate native instruction Markdown.
Historical managed regions remain until the user explicitly previews and
applies `pan context detach --dry-run` / `pan context detach --apply`.

## Keeping the synced setup current

`pan sync` records a digest for each sync input in `~/.overdeck/.sync-manifest.json`.
When the dashboard compares, it ignores the directory `pan sync` ran from, so a
sync run from any workspace or project counts.

The dashboard runs the light `pan sync` itself. It checks the inputs when it
starts, so after every `pan reload`, and again every 60 seconds, so a merge that
changes the main checkout's `sync-sources/` is synced within about a minute. Each
set of changes gets one attempt; a failed attempt waits until the inputs change
again.

The **Setup changed** banner appears only when auto-sync failed, ran but could not
apply the change, or is turned off. It names what changed, for example
"3 skills and 1 rule changed", and its tooltip lists the changed files. Click
**Sync now** (or **Retry sync** after a failure) to run the sync by hand.

To turn auto-sync off, set this in `~/.overdeck/config.yaml`. The banner then
shows for every needed sync:

```yaml theme={null}
context:
  auto_sync: false   # default: true
```

## Harness-specific blocks

A layer file targets a single harness with Mustache-style blocks; text outside
any block renders for every harness:

```markdown theme={null}
All agents follow the engineering philosophy: fix root causes, no bandaids.

{{#harness:claude}}
Prefer the tasks CLI (`pan task`) for task tracking.
{{/harness:claude}}

{{#harness:pi}}
Write completion markers via `/pan-done` when ready for review.
{{/harness:pi}}
```

Blocks may be stacked to target several harnesses; `{{#harness:codex}}` is
also recognized, and so is `{{#harness:prime-agent}}` for Prime Agent-only
instructions.

## CLI

```bash theme={null}
pan context list                  # show all three layers and their files
pan context edit                  # open global.md in $EDITOR
pan context edit --layer project  # open this project's project.md
pan context sync                  # refresh managed-session launch artifacts
pan context detach --dry-run      # preview legacy managed-region removal
pan context detach --apply        # back up and remove unambiguous legacy regions
pan context diff --harness pi     # preview what one harness would receive
pan context validate              # lint templates for malformed blocks
```

`pan sync` runs the context render as part of its broader sync (skills,
agents, rules). The dashboard's **Context** page edits the same files with
per-harness previews.

## Changes apply to new sessions only

Harnesses receive their managed context at session startup. After editing a layer
and running `pan sync`, running sessions keep their old context — only newly
spawned agents and conversations pick up the change.

## Source attribution

Each injected section identifies its canonical source path. Bundled rules are
separate from machine context even though both appear in the global render.
Claude receives a single composed append-file argument; Codex receives developer
instructions. Native user and repository instructions continue to load normally.
Existing conversations can retain old instructions in their history; use a fresh
session to verify a context cleanup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.