\n\n`@illodev/workfile` is a repository-native protocol for coordinating **Work, Docs,\nHistory and durable project Memory** between humans and software agents.\n\nMarkdown files in the repository are canonical. The CLI, HTTP API and local UI use the\nsame core services, collection registry, index and validation rules. No exclusive state\nis kept in the browser or in a database.\n\n> Work, Docs, History and Memory share the common\n> `ProjectRecord` index. The core, CLI, HTTP server and MCP runtime are authored in\n> TypeScript and distributed as compiled ESM with public declarations. The local UI is\n> precompiled and included in the package, and semantic search runs on-device through\n> the optional `@illodev/workfile-search-local` workspace package.\n\n**[Try the live demo](https://workfiledemo.illodev.com)** — it replays this\nrepository's own workspace: the real cards, releases, incidents and learnings of\nWorkfile's development. Mutations work per browser session and reset on reload.\n\nhttps://github.com/user-attachments/assets/c9cd3035-6729-4cda-9172-984829ab5dbc\n\n## Used by\n\n
\n
\n
\n \n In production\n
\n
\n \n Workfile — dogfooding: every release is planned and recorded in this repo's own .project/\n
\n
\n
\n\n## Boundaries\n\nWorkfile records work. It does not configure agents.\n\nThe two get confused because both live next to the same repository. Ecosystem\nconfigurators — [gentle-ai](https://github.com/Gentleman-Programming/gentle-ai) is a\ngood example — install a persona, curated skills, model routing, MCP servers and\nreview gates into the agents you already use, across many agents at once. Their\nquestion is *how your agent works*. Workfile's question is *what was done, who holds\nit and on what evidence*, and its answer is Markdown files that outlive the agent,\nthe session and this package.\n\nThey compose. A well-configured agent still needs somewhere durable to write down\nwhat it did.\n\nWhat is here, and is not a configurator's job:\n\n- **The repository is canonical.** A card is a file in the pull request: reviewed in\n the diff, reported by `workfile doctor` when malformed. No exclusive state in a\n browser, a database or `~/.config`. Remove the package and the records stay\n readable.\n- **Claims are enforced, not agreed.** Ownership is checked at the mutation, so a\n card another actor holds refuses your transition with `CARD_CLAIM_OWNER_MISMATCH`\n instead of quietly accepting it — a guarantee no sentence in a prompt can make.\n- **`review` is not `done`.** `done` requires evidence from somewhere the code\n actually ran. A merge is not evidence.\n- **Humans read the same records.** The UI, the rendered changelog and the releases\n are derived from exactly what the agent writes; there is no machine view and human\n view to keep in sync.\n\nWhat is deliberately absent: Workfile does not install or update agents, ship a\npersona, route models or curate a skill catalogue. It syncs its own protocol into\nthe instruction files an agent already reads (`workfile agents sync`) and exposes\nevery operation over MCP — vendor neutral, but a server, not an ecosystem.\n\n## Requirements\n\n- Node.js 22 or newer.\n- npm, pnpm, yarn or Bun may invoke the package.\n\n## Install\n\nEvery `workfile …` command in this README requires the package to be installed —\n`pnpm dlx` / `npx` one-offs run a command and discard the binary afterwards:\n\n```bash\npnpm add -D @illodev/workfile # per repository (recommended)\npnpm workfile doctor # dependency bins run through pnpm / npx\n\npnpm add -g @illodev/workfile # or globally: `workfile` lands on your PATH\nworkfile doctor\nwf doctor # `wf` is the same binary, for typing by hand\n```\n\n`wf` is an alias, not a rename: both names reach the same entry point, and the\nhelp and error hints answer in whichever one you typed. Keep the long form in\nanything generated or shared. `wf` only resolves once the package is installed,\nand an unrelated `wf` exists on the registry — so `npx wf` would fetch someone\nelse's tool where `npx workfile` fails outright.\n\n`pnpm dlx @illodev/workfile init` is fine for one-shot initialization, but keep the\npackage as a devDependency afterwards: that is what makes the `project*` scripts that\n`init` adds to package.json resolve. That prefix is an npm script namespace — `pnpm\nproject` opens the UI, `pnpm project:doctor` runs the checks — and has nothing to do\nwith the old binary name.\n\n## TypeScript API\n\nThe published surface exposes JavaScript and declarations through conditional package\nexports. TypeScript consumers receive typed configuration, workspace, record, search and\nintegration contracts from the root package and every documented subpath:\n\n```ts\nimport {\n defineProject,\n type CardStatus,\n type ProjectConfig,\n type ProjectRecord\n} from \"@illodev/workfile\";\nimport { createSemanticSearchProvider } from \"@illodev/workfile/search\";\n\nconst config: ProjectConfig = defineProject({\n schemaVersion: 2,\n name: \"Billing\",\n cards: {\n areas: [\"api\", \"web\"]\n }\n});\n\nconst status: CardStatus = \"doing\";\n```\n\nThe CLI and UI do not require TypeScript in consuming projects. React, Primer, Vite and the\nUI type packages are build-only dependencies; the installed package serves bundled browser\nassets from `dist/ui`.\n\n## Workspace\n\nA project is discovered through `project.config.mjs` and normally stores protocol-owned\nfiles under `.project/`:\n\n```text\nproject.config.mjs\n.project/\n├── VERSION\n├── cards/\n│ └── archive/\n├── assets/\n├── docs/\n├── changelog/\n│ ├── unreleased/\n│ └── releases/\n├── memory/\n│ ├── learnings/\n│ ├── decisions/\n│ ├── incidents/\n│ ├── conventions/\n│ └── context/\n├── agents/\n└── .cache/\n```\n\nMinimal configuration — a plain object, not `defineProject(...)`. The loader\napplies `defineProject` itself, and an import here is a bare specifier the file\ncan only resolve with `node_modules` present, which breaks the two consumers\nthat run without one: a `pnpm dlx`-initialized workspace before the package is\ninstalled, and the generated CI job's `npx` run on a clean clone. The JSDoc\nannotation keeps editor typing without a runtime import:\n\n```js\n/** @type {import(\"@illodev/workfile\").ProjectConfigInput} */\nexport default {\n schemaVersion: 2,\n name: \"My project\",\n cards: {\n areas: [\"api\", \"web\", \"infra\", \"docs\"]\n },\n docs: {\n sources: [\n \"README.md\",\n \"docs/**/*.md\",\n \"apps/*/README.md\",\n \".project/specs/**/*.md\"\n ]\n },\n changelog: {\n releaseStrategy: \"semver\",\n defaultVisibility: \"public\"\n },\n memory: {\n collections: [\n \"learnings\",\n \"decisions\",\n \"incidents\",\n \"conventions\",\n \"context\"\n ]\n },\n agents: {\n targets: [\"agents-md\", \"cursor\"]\n },\n ci: {\n targets: [\"github\"]\n },\n mcp: {\n allowMutations: true\n },\n search: {\n semanticWeight: 0.35,\n maxProviderRecords: 500\n }\n};\n```\n\nProject-specific areas, paths and vocabularies are resolved at runtime and exposed through\nthe effective schema. The eight Work statuses and the schema-v2 memory collection\nsemantics remain protocol contracts.\n\n## Work\n\nCards are managed Markdown records under `.project/cards/`. The Work module provides\nhierarchy, dependencies, claims, scope, status transitions, archives, assets and\nconflict-aware writes.\n\n```bash\nworkfile card list --json\nworkfile card show T-0042 --json\nworkfile card create --title \"Implement runtime schema\" --area infra\nworkfile card create --json-input card.json # body, parent, source and tags in one call\nworkfile card claim T-0042 --scope apps/api,packages/sdk # actor resolves itself\nworkfile card transition T-0042 review\nworkfile card patch T-0042 --json-input changes.json --expected-revision sha256:...\nworkfile card archive T-0042\nworkfile card reopen T-0042 --status backlog\n```\n\n## Docs\n\nDocs combines two sources without copying existing documentation:\n\n- **Indexed documents** discovered from configured globs. They receive deterministic\n `PATH-*` IDs and remain read-only through the protocol.\n- **Managed documents** stored in `.project/docs/` with stable `DOC-NNNN` IDs, typed\n frontmatter and revision-aware mutations.\n\nManaged documents are read recursively, so they can be grouped in folders — including\nfolders you create by hand. IDs stay global and sequential: a folder is organization,\nnot identity. New documents follow `docs.layout` (`kind`, the default, groups them by\ndocument kind; `flat` writes them to the managed root) and `--folder` overrides it.\n\n```bash\nworkfile doc list --query billing\nworkfile doc show DOC-0012 --json\nworkfile doc create --title \"Deployment runbook\" --kind runbook --status current\nworkfile doc create --title \"Rate limiting\" --folder architecture/billing\nworkfile doc move DOC-0012 --folder architecture\nworkfile doc patch DOC-0012 --json-input changes.json --expected-revision sha256:...\n```\n\nThe doctor detects broken local links, unresolved related or superseded records, missing\nscope paths and stale review/source relationships.\n\n## History\n\nHistory uses atomic change fragments rather than asking multiple branches or agents to\nedit one shared `CHANGELOG.md`.\n\nUnreleased fragment:\n\n```yaml\n---\nid: CHG-0042\ntitle: Add portable history workspace\ntype: added\narea: infra\nvisibility: public\ncards: [T-0042]\ncreated: 2026-07-28\nupdated: 2026-07-28\n---\n```\n\nA release consumes selected fragments, moves them beneath the release directory and\ncreates a canonical `REL-NNNN` record. Public or internal changelogs are derived output.\n\n```bash\nworkfile changelog list --unreleased\nworkfile changelog add --title \"Add portable history\" --type added --area infra\nworkfile changelog preview\nworkfile changelog release 0.4.0 --title \"History and Memory\"\nworkfile changelog render --visibility public\nworkfile changelog render --visibility public --write\nworkfile changelog verify\n```\n\nRelease versions can use `semver`, `calendar` or `freeform` validation according to\nconfiguration. Fragments and releases participate in the same workfile search and backlink\ngraph as cards, docs and memory.\n\n## Memory\n\nMemory is a set of typed, atomic and lifecycle-aware records rather than a single growing\nconversation transcript:\n\n| Collection | Prefix | Purpose |\n| --- | --- | --- |\n| Learnings | `LRN` | Reusable observations with confidence and occurrence signals |\n| Decisions | `ADR` | Proposed, accepted, rejected or superseded decisions |\n| Incidents | `INC` | Operational events, severity, timing and corrective actions |\n| Conventions | `CONV` | Durable rules followed by humans and agents |\n| Context | `CTX` | Useful but potentially expiring project state |\n\n```bash\nworkfile memory list --collection learnings --status active\nworkfile memory add learning --title \"Atomic fragments avoid merge conflicts\" \\\n --confidence high\nworkfile memory add decision --title \"Keep Markdown canonical\" --status accepted\nworkfile memory add incident --title \"Release pipeline stalled\" --severity high\nworkfile memory graduate LRN-0004 --to CONV-0002,DOC-0012\nworkfile memory supersede ADR-0003 --by ADR-0009\nworkfile memory patch CTX-0002 --json-input changes.json --expected-revision sha256:...\nworkfile memory verify\n```\n\nThe doctor checks invalid lifecycle states, missing graduation/supersession targets,\nexpired context and incomplete incident resolution metadata.\n\n## Unified index\n\nEvery module normalizes its files as `ProjectRecord` entries through a common collection\nregistry. The derived process-local index provides:\n\n- weighted full-project text search;\n- lookup by stable record ID;\n- outgoing references and incoming backlinks across all four domains;\n- card `source:` links and local Markdown links;\n- module-specific health, lifecycle and freshness signals;\n- module and collection counts.\n\nCanonical state always remains on disk. The server cache is short-lived, invalidatable and\nfully rebuildable.\n\n```bash\nworkfile search \"billing architecture\"\nworkfile search release --kind change,release,memory --limit 25 --json\n```\n\n## Initialization\n\nThe initializer can run interactively or deterministically in automation. It detects the\npackage manager, monorepo folders, likely card areas, documentation sources, existing agent\nenvironments and CI providers. A dry run exposes the exact filesystem plan.\n\n```bash\npnpm dlx @illodev/workfile init\npnpm dlx @illodev/workfile init --yes \\\n --agents agents-md,claude,cursor,copilot --ci github\nworkfile init --dry-run --json\n```\n\nThe generated `project.config.mjs` exports a plain object, so a workspace initialized via\n`pnpm dlx` remains loadable before the package is installed locally. Existing files are not\noverwritten unless `--force` is explicit. `.project/.cache/` is added to `.gitignore`; all\ncanonical protocol files remain tracked.\n\n## Hosted demo\n\nThe UI ships with a demo mode for static hosting (Vercel, GitHub Pages, any file server).\n`npm run build:demo` builds the UI with an in-memory API that replays a snapshot of a seeded\nworkspace: every view works and mutations behave normally for the session, then reset on\nreload. The repository includes a `vercel.json`, so importing it into Vercel deploys the\ndemo with zero configuration.\n\n```bash\npnpm run demo:data # reseed and resnapshot packages/workfile/ui/src/demo-data.json\npnpm run build:demo # static demo build into packages/workfile/dist/demo\n```\n\nRegular builds tree-shake the demo layer and snapshot out of the bundle.\n\n## Releasing\n\nReleases publish from CI via npm [trusted publishing](https://docs.npmjs.com/trusted-publishers)\n(OIDC) — no npm token is stored in the repository. The circuit:\n\n1. Cut the changelog: `workfile changelog release ` and `workfile changelog render --write`.\n2. Bump and tag: `npm version ` then `git push && git push --tags`.\n The version hook carries every `packages/*` package inside the same bump —\n workspace packages always ship the core's version.\n3. The `Release` workflow verifies the tag matches `package.json` (and that no\n workspace version drifted), runs `check:release` (build, typechecks, tests,\n audit and a packaged-tarball smoke) with pnpm, and publishes the core and\n every workspace package with the npm CLI under `latest`.\n\nThere is no prerelease channel: every published version is one `npm install`\naway, and a `v*-rc.*` tag fails the release rather than publishing. That is a\nconsequence of trusted publishing rather than a preference — OIDC authorizes\n`npm publish` and no other registry write, so CI cannot move a dist-tag off a\nrelease candidate once it has been set.\n\n## Agent Protocol\n\nCanonical instructions and workflows live under `.project/agents/`. Compact managed blocks\nare synchronized into supported environments without replacing unrelated user content:\n\n```text\nAGENTS.md\nCLAUDE.md\n.cursor/rules/workfile.mdc\n.github/copilot-instructions.md\n```\n\n```bash\nworkfile agents sync\nworkfile agents sync --targets agents-md,claude,cursor,copilot\nworkfile agents check\nworkfile agents context --card T-0042\n```\n\nManaged blocks carry the package version and a SHA-256 digest. `agents check` and\n`workfile doctor` report missing, unmanaged or stale generated instructions. Agent context is\nbounded and prioritizes the selected card, direct relationships, active conventions,\nunresolved incidents and non-expired context instead of loading all workfile memory.\n\n## Model Context Protocol\n\nWorkfile includes a local, dependency-free MCP server using UTF-8,\nnewline-delimited JSON-RPC over stdio. It delegates every operation to the same core\nservices used by the CLI and HTTP API, speaks both the modern (`2026-07-28`) and legacy\n(`2025-11-25`) protocol revisions, and exposes 30 tools, four resources and three\nprompts. Mutation tools disappear entirely in `--read-only` mode.\n\nPoint a client at it without installing anything. This is the invocation the\n[official registry](https://registry.modelcontextprotocol.io) publishes for\n`io.github.illodev/workfile`, and what most clients will build for you from\nthat listing:\n\n```json\n{\n \"mcpServers\": {\n \"workfile\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@illodev/workfile\", \"mcp\"]\n }\n }\n}\n```\n\n`mcp` there is a subcommand, not a binary: `npx` resolves the bin whose name\nmatches the package and hands it everything that follows. Append `--root PATH`\nwhen the client starts somewhere other than the workspace — it searches\nupwards for `.project/` otherwise — and `--read-only` to serve the read tools\nalone, with every mutation refused.\n\nWith the package installed, the same server is a subcommand away:\n\n```bash\nworkfile mcp\nworkfile mcp inspect --json\nworkfile mcp config --read-only --json\n```\n\nFor Claude Code the same surface ships as a plugin — the MCP server plus\n`/claim`, `/context`, `/next` and `/done` commands, a skill, and hooks that\nturn card claims into an executable guard rail — with no generated files\ncommitted to the repository:\n\n```\n/plugin marketplace add illodev/workfile\n/plugin install workfile@illodev\n```\n\nThe full contract — tool inventory, resources, prompts, process hygiene and the\nplugin's surface — is documented in [`docs/mcp.md`](packages/workfile/docs/mcp.md).\n\nThe server is listed on [Glama](https://glama.ai/mcp/servers/illodev/workfile),\nwhich builds it in a container and inspects the capabilities it reports:\n\n[](https://glama.ai/mcp/servers/illodev/workfile)\n\n## Search integrations\n\nLexical search remains deterministic and local. Hosts may inject an optional semantic\nprovider programmatically; Workfile never selects a vendor or sends repository\ncontent over the network by itself.\n\n### First-party: local embeddings\n\n`@illodev/workfile-search-local` runs embeddings on-device (onnxruntime-web,\nONNX on CPU, `Xenova/multilingual-e5-small` quantized) — repository content\nnever leaves the machine. Declare it in `project.config.mjs` with a **guarded\nimport**, because the config must also load where the package cannot resolve\n(the generated CI job runs `npx` on a clean clone):\n\n```js\nexport const integrations = await (async () => {\n try {\n const { localSearchIntegration } = await import(\n \"@illodev/workfile-search-local\"\n );\n return [localSearchIntegration()];\n } catch {\n return []; // package absent: search stays lexical\n }\n})();\n\nexport default {\n // …\n search: { provider: \"local-embeddings\" }\n};\n```\n\nKnow the cost model before wiring it: the **first** hybrid search embeds every\nuncached candidate record — minutes of sustained CPU on a few-thousand-record\nworkspace, triggered by whichever surface searches first (CLI, board UI, or\nthe MCP server an agent loads). The provider caps ONNX at half the cores by\ndefault, persists per batch so an interrupted pass resumes instead of\nrestarting, and reports progress on stderr; sizing `search.maxProviderRecords`\nto your corpus makes every record eligible. Details and options in\n[`packages/search-local/README.md`](packages/search-local/README.md).\n\n### Bring your own\n\n```js\nimport {\n createSemanticSearchProvider,\n searchProjectRecordsHybrid\n} from \"@illodev/workfile/search\";\n\nconst provider = createSemanticSearchProvider({\n id: \"company-embeddings\",\n async search({ query, records }) {\n // Return [{ id, score }] with scores between 0 and 1.\n return rankWithYourApprovedProvider(query, records);\n }\n});\n\nconst result = await searchProjectRecordsHybrid(index.records, query, {\n provider,\n semanticWeight: 0.35\n});\n```\n\nThe adapter boundary makes external data disclosure an explicit host decision and keeps the\ncanonical Markdown/index implementation provider-independent.\n\n### Experimental integration registry\n\nProgrammatic hosts can group approved semantic search and health adapters in a small,\nvendor-neutral registry:\n\n```js\nimport {\n createIntegrationRegistry,\n defineProjectIntegration\n} from \"@illodev/workfile/integrations\";\n\nconst integrations = createIntegrationRegistry([\n defineProjectIntegration({\n id: \"company.platform\",\n semanticSearchProvider: provider,\n async healthCheck({ workspace, index }) {\n return [];\n }\n })\n]);\n```\n\nThe registry is accepted by the MCP server and doctor APIs. It is intentionally limited in\nthe current RC: vendor-specific issue trackers, deployment systems and credentials are not part of\nthe canonical package. The boundary can mature from real integrations without committing\nthe schema to GitHub, GitLab, Jira or a deployment provider.\n\n## CI templates\n\nCI files use the same managed-file contract and can be generated for GitHub Actions,\nGitLab CI or a generic shell runner:\n\n```bash\nworkfile ci sync --targets github,gitlab,generic\nworkfile ci check\n```\n\nTemplates run both the workfile doctor and agent synchronization check against the pinned\nWorkfile version.\n\n## Legacy migration\n\nThe v1 `.planning` system can be planned and applied with deterministic collision checks:\n\n```bash\nworkfile migrate plan --source .planning\nworkfile migrate apply --source .planning --mode copy\nworkfile migrate apply --source .planning --mode move\n```\n\nValid legacy cards and assets become canonical v2 Work records. Old proposals, changelogs,\nlearnings and malformed records are preserved under `.project/sources/legacy-planning/`\nrather than being silently reinterpreted with an incompatible schema. Every applied\nmigration writes `.project/migrations/legacy-planning.json` with source, destination, digest\nand result metadata.\n\n## General CLI\n\n```bash\nworkfile init\nworkfile schema --json\nworkfile doctor --json\nworkfile ui\nworkfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com\n```\n\nCommands return stable machine-readable errors with `--json`. A stale revision exits with\ncode `3`; configuration errors exit with code `2`; validation and not-found errors exit\nwith code `1`. The complete command surface is documented in\n[`docs/cli.md`](packages/workfile/docs/cli.md).\n\n## HTTP API\n\n`workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com` serves the same\nboard as a thing people read: every mutating route answers `409 WORKSPACE_READ_ONLY` and\nthe UI drops its editing affordances. There is still no authentication of its own, so put\na reverse proxy that authenticates in front of anything published this way — see\n[`docs/security.md`](packages/workfile/docs/security.md).\n\n`workfile ui` starts the local server, normally at `http://127.0.0.1:4747`. The versioned\n`/api/v2/*` surface covers the workspace, unified search, and every collection — cards,\ndocs, changelog (including release preview/assembly/render), memory lifecycle, agents and\nCI sync. Managed record reads expose an `ETag`, writes accept `If-Match`, and errors use\nstable codes. The endpoint reference lives in [`docs/http-api.md`](packages/workfile/docs/http-api.md).\n\n## Local UI\n\nNavigation is a collapsible sidebar grouped by domain:\n\n- **Work:** Explorer, Triage, Flow, Epics and a Gantt Timeline (status-colored bars,\n month scale, today marker).\n- **Knowledge:** Docs (search, Markdown, metadata, freshness, scope, backlinks) and\n Memory (typed collections, lifecycle warnings, graduation and supersession).\n- **Project:** Workflow (the provenance graph — every record a node, typed relations as\n edges), History (fragments, releases, release preparation, rendered changelog\n preview) and Health.\n\nHealth issues can navigate to records in any domain. Runtime configuration drives card\nareas, change vocabularies and memory collection statuses; these values are not compiled\ninto the views. File links open the local editor, or the repository web UI when the\nserver provides a `repoUrl` (as the hosted demo does).\n\n\n\nThe Overview answers \"how are we doing\" in a sentence chosen worst-first — doctor\nerrors, hanging claims, colliding scopes, blocked cards, work in flight — above the\ntrail of every move the agents wrote while you were away.\n\n| Explorer with the inspector open | Gantt timeline |\n| --- | --- |\n|  |  |\n\n| History with releases | Memory (dark theme) |\n| --- | --- |\n|  |  |\n\n\n\nWorkflow reads the collections into one graph instead of four lists: the first row of\ntoggles selects them, the second selects relation types. A relation declared in\nfrontmatter draws a solid edge and an ID written into a sentence a dashed one, because a\nlink in prose is a weaker claim than a field and should not look equally solid. Prose\nscanning is off by default — it is 294 of this workspace's 742 edges.\n\n## Development\n\nThe repository is a pnpm workspace: the root is a private shell that holds the\nversion and delegator scripts, while everything published lives under\n`packages/` — the core in [`packages/workfile`](packages/workfile), providers\nlike [`packages/search-local`](packages/search-local) beside it, all shipping\nin version lockstep. pnpm is pinned via the `packageManager` field\n(`corepack enable` picks it up automatically):\n\n```bash\npnpm install\npnpm run check\npnpm run smoke:package\nnode ./packages/workfile/dist/bin/workfile.js mcp inspect --root ./packages/workfile/test/fixtures/workspace --json\nnode ./packages/workfile/dist/bin/workfile.js schema --root ./packages/workfile/test/fixtures/workspace --json\nnode ./packages/workfile/dist/bin/workfile.js doctor --root ./packages/workfile/test/fixtures/workspace --json\nnode ./packages/workfile/dist/bin/workfile.js ui --root ./packages/workfile/test/fixtures/workspace\n```\n\n`pnpm run check` compiles the TypeScript runtime and declarations, checks the strict public\nconsumer contract, typechecks and bundles the React UI, and runs the complete test suite.\n`pnpm run smoke:package` packs and installs the actual tarball in a temporary project before\nexercising initialization, all four domains, MCP and the packaged UI — the smoke installs\nwith npm on purpose, exercising the npm consumer path.\n\n`prepack` rebuilds the runtime declarations and UI so a future published package contains\nonly compiled runtime artifacts under `dist/`, never development TypeScript or a copied UI\nsource tree.\n\n## Current guarantees\n\n- restricted frontmatter codec with byte-stable scalar/list round trips;\n- preservation of unknown frontmatter fields and body bytes;\n- atomic file replacement, per-record locks and collision-safe ID reservations;\n- SHA-256 revision tokens and stale-write rejection;\n- atomic Work claims, transitions, archive and reopen operations;\n- managed Docs, History fragments and typed Memory mutations;\n- release assembly with canonical fragment consumption and derived rendering;\n- configurable repository-safe paths and runtime vocabularies;\n- common normalization, search, references and backlinks across all domains;\n- health diagnostics for Work, Docs, History and Memory;\n- compiled ESM and `.d.ts` declarations for the public package and subpath exports;\n- executable packaged CLI/MCP binaries verified from a clean tarball installation;\n- versioned API plus a compatibility adapter for the original board.\n\n## Documents\n\n- [`docs/getting-started.md`](packages/workfile/docs/getting-started.md) — install, initialize and the\n daily loop.\n- [`docs/cli.md`](packages/workfile/docs/cli.md) — complete CLI reference for every module.\n- [`docs/http-api.md`](packages/workfile/docs/http-api.md) — endpoint reference, conventions and errors.\n- [`docs/mcp.md`](packages/workfile/docs/mcp.md) — MCP server contract: tools, resources, prompts.\n- [`docs/security.md`](packages/workfile/docs/security.md) — threat model of the local server,\n request guard, asset handling and what is deliberately out of scope.\n- [`docs/ui.md`](packages/workfile/docs/ui.md) — the interface: its build, the zero-dependency\n guarantee and how the shadcn migration coexists with the design system.\n- [`docs/SPEC.md`](packages/workfile/docs/SPEC.md) — the normative protocol specification: data model,\n record contracts, revision semantics and the MCP integration contract.\n",
"bytes": 30104,
"sha": "6b06e2207a2bf11ad897eda313e45e7a9a45abe75d57a397240f5577760fb62e",
"repo_slug": "illodev/workfile",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_illodev_workfile_49792fd5/readme"
}
![\"Workfile\"](\"https://raw.githubusercontent.com/illodev/workfile/main/.github/media/brand/lockup.png\")
\n![\"Workfile](\"https://glama.ai/mcp/servers/illodev/workfile/badges/score.svg\")
\n![\"Fube\"](\"https://raw.githubusercontent.com/illodev/workfile/main/.github/media/logos/fube.svg\")
![\"Workfile\"](\"https://raw.githubusercontent.com/illodev/workfile/main/.github/media/brand/logo.svg\"){kind=logo}