workfile

<p align="center">
  <a href="https://workfiledemo.illodev.com"><img src="https://raw.githubusercontent.com/illodev/workfile/main/.github/media/brand/lockup.png" alt="Workfile" width="460"></a>
</p>
<p align="center"><em>The repository is the database.</em></p>

`@illodev/workfile` is a repository-native protocol for coordinating **Work, Docs,
History and durable project Memory** between humans and software agents.

Markdown files in the repository are canonical. The CLI, HTTP API and local UI use the
same core services, collection registry, index and validation rules. No exclusive state
is kept in the browser or in a database.

> Work, Docs, History and Memory share the common
> `ProjectRecord` index. The core, CLI, HTTP server and MCP runtime are authored in
> TypeScript and distributed as compiled ESM with public declarations. The local UI is
> precompiled and included in the package, and semantic search runs on-device through
> the optional `@illodev/workfile-search-local` workspace package.

**[Try the live demo](https://workfiledemo.illodev.com)** — it replays this
repository's own workspace: the real cards, releases, incidents and learnings of
Workfile's development. Mutations work per browser session and reset on reload.

https://github.com/user-attachments/assets/d45a817d-4279-4cde-8f10-29495c0daf2d

## Used by

<table>
  <tr>
    <td align="center" width="260">
      <img src="https://raw.githubusercontent.com/illodev/workfile/main/.github/media/logos/fube.svg" alt="Fube" height="42"><br>
      <sub>In production</sub>
    </td>
    <td align="center" width="260">
      <img src="https://raw.githubusercontent.com/illodev/workfile/main/.github/media/brand/logo.svg" alt="Workfile" height="42"><br>
      <sub><b>Workfile</b> — dogfooding: every release is planned and recorded in this repo's own <a href="https://workfiledemo.illodev.com"><code>.project/</code></a></sub>
    </td>
  </tr>
</table>

## Boundaries

Workfile records work. It does not configure agents.

The two get confused because both live next to the same repository. Ecosystem
configurators — [gentle-ai](https://github.com/Gentleman-Programming/gentle-ai) is a
good example — install a persona, curated skills, model routing, MCP servers and
review gates into the agents you already use, across many agents at once. Their
question is *how your agent works*. Workfile's question is *what was done, who holds
it and on what evidence*, and its answer is Markdown files that outlive the agent,
the session and this package.

They compose. A well-configured agent still needs somewhere durable to write down
what it did.

What is here, and is not a configurator's job:

- **The repository is canonical.** A card is a file in the pull request: reviewed in
  the diff, reported by `workfile doctor` when malformed. No exclusive state in a
  browser, a database or `~/.config`. Remove the package and the records stay
  readable.
- **Claims are enforced, not agreed.** Ownership is checked at the mutation, so a
  card another actor holds refuses your transition with `CARD_CLAIM_OWNER_MISMATCH`
  instead of quietly accepting it — a guarantee no sentence in a prompt can make.
- **`review` is not `done`.** `done` requires evidence from somewhere the code
  actually ran. A merge is not evidence.
- **Humans read the same records.** The UI, the rendered changelog and the releases
  are derived from exactly what the agent writes; there is no machine view and human
  view to keep in sync.

What is deliberately absent: Workfile does not install or update agents, ship a
persona, route models or curate a skill catalogue. It syncs its own protocol into
the instruction files an agent already reads (`workfile agents sync`) and exposes
every operation over MCP — vendor neutral, but a server, not an ecosystem.

## Requirements

- Node.js 22 or newer.
- npm, pnpm, yarn or Bun may invoke the package.

## Install

Every `workfile …` command in this README requires the package to be installed —
`pnpm dlx` / `npx` one-offs run a command and discard the binary afterwards:

```bash
pnpm add -D @illodev/workfile     # per repository (recommended)
pnpm workfile doctor              # dependency bins run through pnpm / npx

pnpm add -g @illodev/workfile     # or globally: `workfile` lands on your PATH
workfile doctor
wf doctor                         # `wf` is the same binary, for typing by hand
```

`wf` is an alias, not a rename: both names reach the same entry point, and the
help and error hints answer in whichever one you typed. Keep the long form in
anything generated or shared. `wf` only resolves once the package is installed,
and an unrelated `wf` exists on the registry — so `npx wf` would fetch someone
else's tool where `npx workfile` fails outright.

`pnpm dlx @illodev/workfile init` is fine for one-shot initialization, but keep the
package as a devDependency afterwards: that is what makes the `project*` scripts that
`init` adds to package.json resolve. That prefix is an npm script namespace — `pnpm
project` opens the UI, `pnpm project:doctor` runs the checks — and has nothing to do
with the old binary name.

## TypeScript API

The published surface exposes JavaScript and declarations through conditional package
exports. TypeScript consumers receive typed configuration, workspace, record, search and
integration contracts from the root package and every documented subpath:

```ts
import {
    defineProject,
    type CardStatus,
    type ProjectConfig,
    type ProjectRecord
} from "@illodev/workfile";
import { createSemanticSearchProvider } from "@illodev/workfile/search";

const config: ProjectConfig = defineProject({
    schemaVersion: 2,
    name: "Billing",
    cards: {
        areas: ["api", "web"]
    }
});

const status: CardStatus = "doing";
```

The CLI and UI do not require TypeScript in consuming projects. React, Primer, Vite and the
UI type packages are build-only dependencies; the installed package serves bundled browser
assets from `dist/ui`.

## Workspace

A project is discovered through `project.config.mjs` and normally stores protocol-owned
files under `.project/`:

```text
project.config.mjs
.project/
├── VERSION
├── cards/
│   └── archive/
├── assets/
├── docs/
├── changelog/
│   ├── unreleased/
│   └── releases/
├── memory/
│   ├── learnings/
│   ├── decisions/
│   ├── incidents/
│   ├── conventions/
│   └── context/
├── agents/
└── .cache/
```

Minimal configuration — a plain object, not `defineProject(...)`. The loader
applies `defineProject` itself, and an import here is a bare specifier the file
can only resolve with `node_modules` present, which breaks the two consumers
that run without one: a `pnpm dlx`-initialized workspace before the package is
installed, and the generated CI job's `npx` run on a clean clone. The JSDoc
annotation keeps editor typing without a runtime import:

```js
/** @type {import("@illodev/workfile").ProjectConfigInput} */
export default {
    schemaVersion: 2,
    name: "My project",
    language: "es",
    cards: {
        areas: ["api", "web", "infra", "docs"]
    },
    docs: {
        sources: [
            "README.md",
            "docs/**/*.md",
            "apps/*/README.md",
            ".project/specs/**/*.md"
        ]
    },
    changelog: {
        releaseStrategy: "semver",
        defaultVisibility: "public"
    },
    memory: {
        collections: [
            "learnings",
            "decisions",
            "incidents",
            "conventions",
            "context"
        ]
    },
    agents: {
        targets: ["agents-md", "cursor"]
    },
    ci: {
        targets: ["github"]
    },
    mcp: {
        allowMutations: true
    },
    search: {
        semanticWeight: 0.35,
        maxProviderRecords: 500
    }
};
```

Project-specific areas, paths and vocabularies are resolved at runtime and exposed through
the effective schema. The eight Work statuses and the schema-v2 memory collection
semantics remain protocol contracts.

## Work

Cards are managed Markdown records under `.project/cards/`. The Work module provides
hierarchy, dependencies, claims, scope, status transitions, archives, assets and
conflict-aware writes.

```bash
workfile card list --json
workfile card show T-0042 --json
workfile card create --title "Implement runtime schema" --area infra
workfile card create --json-input card.json   # body, parent, source and tags in one call
workfile card claim T-0042 --scope apps/api,packages/sdk   # actor resolves itself
workfile card transition T-0042 review
workfile card patch T-0042 --json-input changes.json --expected-revision sha256:...
workfile card archive T-0042
workfile card reopen T-0042 --status backlog
```

## Docs

Docs combines two sources without copying existing documentation:

- **Indexed documents** discovered from configured globs. They receive deterministic
  `PATH-*` IDs and remain read-only through the protocol.
- **Managed documents** stored in `.project/docs/` with stable `DOC-NNNN` IDs, typed
  frontmatter and revision-aware mutations.

Managed documents are read recursively, so they can be grouped in folders — including
folders you create by hand. IDs stay global and sequential: a folder is organization,
not identity. New documents follow `docs.layout` (`kind`, the default, groups them by
document kind; `flat` writes them to the managed root) and `--folder` overrides it.

```bash
workfile doc list --query billing
workfile doc show DOC-0012 --json
workfile doc create --title "Deployment runbook" --kind runbook --status current
workfile doc create --title "Rate limiting" --folder architecture/billing
workfile doc move DOC-0012 --folder architecture
workfile doc patch DOC-0012 --json-input changes.json --expected-revision sha256:...
```

The doctor detects broken local links, unresolved related or superseded records, missing
scope paths and stale review/source relationships.

## History

History uses atomic change fragments rather than asking multiple branches or agents to
edit one sh