Ownership zones

A generated site is a starting point. You keep building on it, by hand or with Claude Code. For that to be safe, every tool that writes files must know which files are yours. Each file in a site is in one of three zones, and a manifest, provenance.json, records the files the tools wrote.

The rule behind it is that no skill or script may overwrite your work. A tool that is not allowed to write a file prints what it would have changed and stops, so you can decide.

The three zones

A few files are mixed. They are yours, but the tools edit them in declared places: package.json, package-lock.json, .gitignore, .env.example, CLAUDE.md, src/env.d.ts, src/styles/global.css, tsconfig.json and, in a site with a Node backend, api/package.json (the kit keeps its two kit-package entries current). A tool adds a dependency, an ignore line, the theme block of src/styles/global.css or the ruleset section of CLAUDE.md. It does not rewrite the rest.

For lake.config.ts only the defineLake({ ... }) call counts. The siteTypeSlots export next to it is edited by hand, and a change there is not drift.

Why kit files are locked

The kit is code that the tools keep consistent with each other: the version of the packages, the lock, the ruleset record. A hand edit would be lost in the next upgrade or, worse, would break the build in a way that nobody can trace. To change what the kit does, override a component in site.config.ts. See Custom components.

The plugin’s edit hook enforces this inside Claude Code. It blocks Edit and Write on kit files and on any file marked locked. The message points to the override in site.config.ts and to npx mdlake adopt.

provenance.json

provenance.json is the ownership manifest. The scripts write it and you never edit it by hand. It is committed.

{
  "version": 2,
  "files": {
    "lake.config.ts": {
      "zone": "generated",
      "hash": "71f8dd4a1df33b04bc19c8fd859d10492d91f10258c946315117aadc289455f2",
      "writer": "plan-to-config"
    },
    "src/pages.config.ts": {
      "zone": "site",
      "hash": "1598b4c2a843006a071a35594b6d29151451e13c87bd1a1942ab6cf51d7b15de",
      "adoptedFrom": "generated",
      "adoptedAt": "2026-10-20T08:12:44.000Z"
    }
  }
}

A file with no entry has the zone that its location gives it: kit and generated files as listed above, and site for anything else. Keys are sorted, so a Git diff shows only what changed. Older sites have a bare map, { "<path>": { "locked": true } }. It is still read, and its locked flags are kept.

See the zones: npx mdlake ownership

npx mdlake ownership

It lists the kit and generated files with their state, then the site files.

kit       12 files  (written by tools: never edit by hand)
  ok         builder.json
  ok         lake.lock
generated 4 files  (written by skills from plan.md and the lake: adopt to edit by hand)
  ok         lake.config.ts
  EDITED     src/pages.config.ts  adopt it: npx mdlake adopt src/pages.config.ts
site      9 files under src/, 1 adopted from the generated zone  (yours: the kit never writes there)
  adopted    src/content/generated/home-hero.md  (changed since it was adopted)
  (npx mdlake ownership --all lists them)

A kit or generated file whose manifest entry has no hash is unrecorded, so it is never silently skipped. npx mdlake ownership lists it and check-ownership warns that it “is not recorded as written by the kit”. Adopt it, regenerate it or run npx mdlake migrate --trust-generated.

When provenance.json has no zones yet, the command says so and tells you to run npx mdlake migrate, which records them without overwriting anything.

Adopt a file: npx mdlake adopt

Adopting turns a generated file into a site file. After that, the kit never writes it again. Use it when you want to edit a generated file by hand and keep the edit.

npx mdlake adopt src/pages.config.ts
npx mdlake adopt lake.config.ts src/content/generated/home-hero.md
npx mdlake adopt --edited

What happens:

• The manifest entry becomes zone site, with adoptedFrom: generated, a time and a hash of the file as it is now.
• Each file prints adopted <file>: it is site-owned now. regenerate, refresh-content and upgrade-ruleset will not write it; they print what they would have changed instead.
• A kit file is refused: “is kit-owned and cannot be adopted. To change what the kit renders, register your own component in site.config.ts.”
• A file that is a site file already is refused: “there is nothing to adopt.”
• A file that does not exist is refused. The command exits with 1 when any file is refused.

Adopt does not move the file, and there is no command to undo it.

Typical cases:

What the checks say

npm run check includes check:ownership (mdlake check-ownership).

The last line is a summary such as Ownership: 14 files as the kit wrote them, 1 adopted, 0 errors, 1 warnings. It exits 1 when there is an error. The warnings do not fail the check, but do not leave them. A warning on a generated file is a decision waiting for you.

What the tools refuse

Every kit writer writes through one guarded function: scaffold-ruleset, vendor-packages, plan-to-config, write-generated, write-lake-lock, apply-design, commit-site, migrate, snapshot, hosting init and the others. It refuses to write a file when:

A refusal prints the file, the reason and a summary of what would have changed, with the first lines of the difference. Scripts then exit with code 3. The migration prints the same as a refused note.

NOT WRITTEN src/pages.config.ts (edited): src/pages.config.ts was edited by hand after the kit wrote it. Adopt it to keep your version (npx mdlake adopt src/pages.config.ts), or overwrite it to regenerate.
  would change src/pages.config.ts: 3 lines added, 1 removed (first change at line 14)
    - { label: 'Cases', href: '/cases/' },
    + { label: 'Customers', href: '/customers/' },

When a skill sees exit code 3 it shows you that summary and stops. It does not decide for you. You can keep the file as it is, adopt it, or regenerate it.

To regenerate a file that was edited but not adopted, run the script again with --overwrite (plan-to-config.mjs, write-generated.mjs). --overwrite never overrides an adopted file. Your edits in the old file are lost, so look at the summary first.

A legacy provenance.json (from before 0.16, a plain map) is left alone by every plugin script that writes a file, such as vendor-packages.mjs and write-lake-lock.mjs. The script writes its file and leaves provenance.json byte for byte as it was. Only npx mdlake migrate converts it. Until then check-ownership warns “no ownership zones yet: run npx mdlake migrate”, the locked flags of the old file are still honoured, and npx mdlake adopt refuses to run on a legacy manifest.

What can go wrong

What’s next

• Find what to change goes from what you see on a page to the file or setting behind it.
• Custom pages and Custom components show the files you own.
• Upgrade and migrate explains how the migration records zones.