> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Adaptive workspace contract

> Fleet Pi's canonical workspace contract — the manifest, section families, kinds, durable file boundary, and non-canonical projection layer for indexes.

This page records the accepted adaptive-workspace contract for Fleet Pi. It defines the canonical durable state, the manifest and section boundaries, and the non-canonical projection layer that may accelerate queries but never replaces files.

The contract is implemented in [`apps/web/src/lib/workspace/workspace-contract.ts`](https://github.com/Qredence/fleet-pi/blob/main/apps/web/src/lib/workspace/workspace-contract.ts) and is currently at `WORKSPACE_CONTRACT_VERSION = 1`.

## Canonical boundary

`agent-workspace/` is the canonical durable adaptive state.

* Durable memory, skills, plans, evals, and artifacts remain **path-backed files**.
* Workspace-installed Pi resources and policy material follow the same rule: reviewable files win over caches, rows, or hidden runtime state.
* `scratch/` is non-canonical temporary space. It can hold disposable working files, but it is not durable adaptive memory.
* `agent-workspace/indexes/` stores non-canonical projection data. Projection rows may accelerate search, health, provenance, or query flows, but canonical files still decide what Fleet Pi knows.

## Accepted workspace shape

```text theme={null}
agent-workspace/
├── manifest.json
├── instructions/
├── system/
├── memory/
│   ├── daily/
│   ├── project/
│   └── research/
├── plans/
│   ├── active/
│   ├── completed/
│   └── abandoned/
├── skills/
├── evals/
├── artifacts/
│   ├── reports/
│   ├── datasets/
│   ├── traces/
│   └── diagrams/
├── scratch/
│   └── tmp/
├── pi/
│   ├── skills/
│   ├── prompts/
│   ├── extensions/
│   │   ├── enabled/
│   │   └── staged/
│   └── packages/
└── indexes/
```

`agent-workspace/manifest.json` describes the workspace shape and the versioned policy of the adaptive layer. Bootstrap may seed missing artifacts later, but the names and semantics of the sections above are fixed.

## Section families and kinds

Every top-level section has a **kind** that the workspace server enforces:

| Section         | Kind       | Purpose                                                                             |
| --------------- | ---------- | ----------------------------------------------------------------------------------- |
| `instructions/` | canonical  | Durable orientation and operational guidance that survives sessions.                |
| `system/`       | canonical  | Workspace policy and system-level instructions (e.g., `workspace-policy.md`).       |
| `memory/`       | canonical  | Durable project knowledge, daily notes, and research.                               |
| `plans/`        | canonical  | Explicit execution plans and backlog state (`active/`, `completed/`, `abandoned/`). |
| `skills/`       | canonical  | Repo-local agent skills and supporting examples/evals.                              |
| `evals/`        | canonical  | Checklists, scorecards, and regression-oriented evaluation material.                |
| `artifacts/`    | canonical  | Durable reports, datasets, traces, and reusable outputs.                            |
| `pi/`           | canonical  | Workspace-installed Pi skills, prompts, extensions, and packages.                   |
| `scratch/`      | temporary  | Disposable working files only — never durable memory.                               |
| `indexes/`      | projection | Projection / query state only — never canonical.                                    |

The canonical kinds are exported as `WORKSPACE_SECTION_KINDS = ["canonical", "temporary", "projection"]`.

## Workspace-installed Pi resources

The canonical home for chat-installed Pi resources is inside `agent-workspace/pi/`:

* `agent-workspace/pi/skills`
* `agent-workspace/pi/prompts`
* `agent-workspace/pi/extensions` (with `enabled/` and `staged/` subdirectories)
* `agent-workspace/pi/packages`

These directories stay canonical because the installed resource itself is a reviewable file or directory in the repository.

## Workspace policy files

The contract seeds a small set of policy files when missing. The current default is `system/workspace-policy.md`, which states:

> `agent-workspace/` is Fleet Pi's canonical durable adaptive state. Bootstrap should preserve user-authored files.

Bootstrap **never overwrites** user-authored content. It only fills in absent canonical paths and the manifest.

## `.pi/settings.json` compatibility bridge

`.pi/settings.json` remains the compatibility bridge between the Pi runtime and workspace-native resources. It may point Pi at `agent-workspace/pi/*`, but it does not replace the workspace as the durable store.

That means:

* Committed `.pi/` configuration can keep loading project-local built-ins.
* Workspace-installed resources still live under `agent-workspace/pi/`.
* Changing the bridge must not imply changing where the canonical resource content lives.

## Non-regression rules

* Never promote `indexes/` rows above canonical files.
* Never treat session state as durable memory.
* Never write durable memory outside of the section families above.
* Bootstrap, health, indexing, and query surfaces must remain projections — they read canonical files, they do not replace them.
* Existing canonical files under `agent-workspace/` remain authoritative until bootstrap and indexing milestones land.

## Related

<CardGroup cols={2}>
  <Card title="Agent workspace" icon="folder-tree" href="/fleet-pi/agent-workspace">
    Human-facing tour of what lives in `agent-workspace/`.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/fleet-pi/architecture">
    How the workspace, web app, and Pi runtime fit together.
  </Card>

  <Card title="Runtime SDK seams" icon="code-branch" href="/fleet-pi/runtime-sdk-integration">
    Safe extension points for workspace bootstrap, indexing, and provenance.
  </Card>

  <Card title="Chat modes" icon="sliders-vertical" href="/fleet-pi/chat-modes">
    `workspace_write` and `resource_install` in Harness mode.
  </Card>
</CardGroup>