kalup 0.1.0

package/docs/errors/E_STATE_CHANGED.md

@@ -0,0 +1,19 @@
+# E_STATE_CHANGED
+
+State for the portal changed after the plan was made. Exit 1. Nothing was written.
+
+## When
+
+A plan records the state lineage and serial it was made from, and an approval covers the plan with them. After it takes the portal lock, `kalup apply` reads state again and refuses when either differs: another apply, a pull that recorded bases, a state rebuild or a rebind ran in between. The one exception is a plan that is the last one applied, with outcome `done`: apply reports it as already applied and exits 0.
+
+`state rebuild --write` shows its report before it takes the lock. Under the lock it reads state again and refuses when it is not the file the report showed, so it never archives a file the person did not see.
+
+## Fix
+
+Run `kalup plan --target <name> --out <file>` again. It starts from the new state. Review it and apply that file. For a rebuild, run it again and review the new report.
+
+## Example
+
+```
+E_STATE_CHANGED: state for portal 2222222 changed since plan pl_7f3a1c07b2e4 was made (lineage 0a1b2c3d4e5f6071, serial 4; now lineage 0a1b2c3d4e5f6071, serial 6): another apply, pull or repair ran in between. Nothing was written. (fix: run kalup plan --target production --out <file> again and review it) (docs: errors/E_STATE_CHANGED.md)
+```

package/docs/errors/E_STATE_CONFLICT.md

@@ -0,0 +1,17 @@
+# E_STATE_CONFLICT
+
+The state file changed while this command ran, so its save was refused. Exit 1.
+
+## When
+
+Every state save compares serials: the file must still hold the serial the command read before it started. Another Kalup command saved state for the same portal in between, or someone replaced the file. Nothing was saved, and the file keeps what the other writer put there.
+
+## Fix
+
+Run `kalup plan` again. It reads the new state and shows what is left to do. Two commands that write to one portal should not run at once; the portal lock keeps them apart on one machine.
+
+## Example
+
+```
+.kalup/state/portal-2222222.json: E_STATE_CONFLICT: .kalup/state/portal-2222222.json changed while this command ran: its serial is 8, not 7. Nothing was saved. (fix: another kalup command wrote state for portal 2222222; run kalup plan again) (docs: errors/E_STATE_CONFLICT.md)
+```

package/docs/errors/E_STATE_INVALID.md

@@ -0,0 +1,17 @@
+# E_STATE_INVALID
+
+A state file cannot be used. Exit 1. Nothing was written.
+
+## When
+
+State lives in `.kalup/state/portal-<portalId>.json`, one file per portal. Kalup reads it before it plans or writes against that portal, and stops when the file cannot be read, is not JSON, names a format other than `kalup.state/1`, does not match that schema, or describes another portal than the one the key belongs to. The message says what is wrong.
+
+## Fix
+
+When the file cannot be read, fix its permissions. Another format means another version of Kalup wrote it: use that version or a newer one, and keep the file. Otherwise the file was edited, damaged or overwritten; never edit state by hand. The `.bak` beside it holds the state before its last save: rename it into place if it reads, knowing it lacks that save. Else move the file away and run `kalup state rebuild --target <name>`, or restore it from a CI state branch.
+
+## Example
+
+```
+.kalup/state/portal-2222222.json: E_STATE_INVALID: .kalup/state/portal-2222222.json is not JSON. (fix: rename portal-2222222.json.bak, the state before its last save, into its place if it reads; else move the file away and run kalup state rebuild --target production) (docs: errors/E_STATE_INVALID.md)
+```

package/docs/errors/E_STATE_SCHEMA.md

@@ -0,0 +1,17 @@
+# E_STATE_SCHEMA
+
+A state file does not match the `kalup.state/1` JSON Schema. Exit 1.
+
+## When
+
+Kalup checks a state document against `state-1.schema.json` and returns this issue for each mismatch. `configPath` is a path in the state file, such as `resources.property:companies/billing_status.origin`, not a place in a config file. `kalup plan` reads it and reports a mismatch as `E_STATE_INVALID`.
+
+## Fix
+
+Kalup writes state that matches, so a mismatch means the file was edited by hand or damaged. Do not edit state by hand. Restore the file from where you keep it, such as the state branch of your CI setup.
+
+## Example
+
+```
+E_STATE_SCHEMA: missing required field "portalId" (docs: errors/E_STATE_SCHEMA.md)
+```

package/docs/errors/E_STATE_WRITE.md

@@ -0,0 +1,19 @@
+# E_STATE_WRITE
+
+State could not be saved or archived. Exit 1, or 5 when `kalup apply` had already written.
+
+## When
+
+A save writes a temporary file, flushes it, keeps the old file as `.bak` and renames the new one over it. When a step fails (a full disk, no write permission, a read-only file system), the old file stays as it was.
+
+`state rebuild --write` and `target rebind` archive the old file first: when the new one fails to save, no state file is left, and the message names the archive. Until a state file exists again, the next plan proposes adopting every config resource the portal holds.
+
+## Fix
+
+Check that the state directory (`.kalup/state`, or `KALUP_STATE_DIR`) is writable and the disk has room, then run the command again. If `kalup apply` had already changed the portal, its message names the run's journal. Run `kalup plan`: it compares the portal with the state kept and shows what is left; a property the run created shows as an adopt, never a second create. After a rebuild or rebind, run it again, or move the archived file back to keep the previous state.
+
+## Example
+
+```
+.kalup/state/portal-2222222.json: E_STATE_WRITE: .kalup/state/portal-2222222.json: could not save it (ENOSPC). The previous file is intact. (fix: check that the state directory is writable and the disk has room, then run the command again) (docs: errors/E_STATE_WRITE.md)
+```

package/docs/errors/E_STRICT_WITHOUT_OPTIONS.md

@@ -0,0 +1,21 @@
+# E_STRICT_WITHOUT_OPTIONS
+
+`.strict()` is on a `p.enum` or `p.multiEnum` that lists no options. Exit 3.
+
+## When
+
+A strict enum's codec throws on any value its options do not list. With no options, it would throw on every value HubSpot stores. A bare reference such as `p.enum('lifecyclestage').strict()`, or a definition without `options`, is this error.
+
+## Fix
+
+List the options the app handles, as an options-only reference (`p.enum(name, { options: [...] })`) or in the full definition, or drop `.strict()`: without it the codec reads an unlisted value as `Unlisted`.
+
+## Example
+
+```ts
+stage: p.enum('lifecyclestage').strict(),
+```
+
+```
+kalup/objects/companies.ts:9: E_STRICT_WITHOUT_OPTIONS: .strict() on 'lifecyclestage', which lists no options, so its codec would throw on every value (fix: list the options, or drop .strict()) (docs: errors/E_STRICT_WITHOUT_OPTIONS.md)
+```

package/docs/errors/E_TAKE_UNMATCHED.md

@@ -0,0 +1,19 @@
+# E_TAKE_UNMATCHED
+
+A `--take` selector names nothing it can take. Exit 1. Nothing was written.
+
+## When
+
+`kalup plan --take config <address[#unit]>` writes config over held units and recreates a missing property HubSpot does not hold archived. Each selector must match a held unit (`drift`, `conflict` or `diverged`) or a resource listed in `missing`; a unit that already agrees, a config change or a typo matches nothing. The message lists the units held on the addresses the selector names, and names a missing resource a `#unit` selector matched: only the address alone recreates it.
+
+`kalup blueprint upgrade --take remote <address[#unit]>` must match a conflict of the upgrade, or one the lock holds when the version is unchanged.
+
+## Fix
+
+Run the command without `--take`, pick a held unit, missing resource or conflict from its output, and pass that. A selector without `#unit` takes every unit on the address; `*` in the address works as in `--only`.
+
+## Example
+
+```
+E_TAKE_UNMATCHED: --take config property:companies/billing_status#description matches no held unit and no missing resource; held there: property:companies/billing_status#label (fix: take a held unit or a missing resource that kalup plan --target production lists, or leave the selector out) (docs: errors/E_TAKE_UNMATCHED.md)
+```

package/docs/errors/E_TARGET_NAME.md

@@ -0,0 +1,17 @@
+# E_TARGET_NAME
+
+A target is named `config`. Exit 3.
+
+## When
+
+`compare` uses the word `config` for the config side, so no target may take it.
+
+## Fix
+
+Rename the target, for example to `sandbox` or `production`.
+
+## Example
+
+```
+kalup.config.ts:9: E_TARGET_NAME: a target may not be named 'config': compare uses that word for the config side (fix: rename the target) (docs: errors/E_TARGET_NAME.md)
+```

package/docs/errors/E_TARGET_PORTAL_MISMATCH.md

@@ -0,0 +1,19 @@
+# E_TARGET_PORTAL_MISMATCH
+
+The key belongs to another portal than the one pinned. Exit 4, `humanRequired: true`.
+
+## When
+
+Every command that reads a target first checks account-info with its key; `init` and `target rebind` check the portal `--portal` gives. The key's portal differs, so nothing more is sent with that key and nothing is written. `status` still checks the other targets with their own keys.
+
+## Fix
+
+Stop. A person checks which key is in the variable and which portal `portalId` names. Agents: hand this to the user. Do not edit `portalId` or the key yourself, and do not run `target rebind`: it needs a person at a terminal. Changing the pin to match the key is how the wrong portal gets read.
+
+When a test portal or sandbox was recreated under a new Hub ID, the person moves the target to it with `kalup target rebind <target> --portal <id>` at a terminal (see [state.md](../state.md#target-rebind)). Rebind accepts only a test portal or sandbox (`E_REBIND_STANDARD`), checks the key against the new portal and rebuilds state there.
+
+## Example
+
+```
+E_TARGET_PORTAL_MISMATCH: The key in HUBSPOT_PROD_READ_KEY belongs to portal 3333333, not portal 2222222 pinned for target production. (fix: The key in HUBSPOT_PROD_READ_KEY belongs to portal 3333333. Ask the user to check the key and the pinned portalId for target production. For a recreated test portal or sandbox, the user can run kalup target rebind production --portal <id> in a terminal; it refuses STANDARD accounts.) (docs: errors/E_TARGET_PORTAL_MISMATCH.md)
+```

package/docs/errors/E_TARGET_REQUIRED.md

@@ -0,0 +1,17 @@
+# E_TARGET_REQUIRED
+
+A command that runs against one target found several, none selected by `--target` or `defaultTarget`, and no person at a terminal to choose. Exit 1.
+
+## When
+
+`pull`, `plan` and `snapshot`, after the config validates and before any request or file write. With `--json`, without a terminal, or with `CI` set, the command cannot ask, so it lists the names and portal IDs instead. At a terminal it asks on stderr. Kalup never picks the first target for you. See [Choosing a target](../targets.md#choosing-a-target).
+
+## Fix
+
+Pass `--target <name>` with one of the listed names, or set `defaultTarget` in `kalup.config.ts`. An agent should ask the user which portal to use, then pass `--target`.
+
+## Example
+
+```
+E_TARGET_REQUIRED: kalup.config.ts declares 2 targets and none is selected: sandbox (portal 1111111), production (portal 2222222) (fix: pass --target <name>, or set defaultTarget in kalup.config.ts. An agent should ask the user which portal to use.) (docs: errors/E_TARGET_REQUIRED.md)
+```

package/docs/errors/E_TOMBSTONE_ADDRESS.md

@@ -0,0 +1,23 @@
+# E_TOMBSTONE_ADDRESS
+
+A key in `kalup/removed.ts`, or the address given to `kalup rm`, is not the address of a property or group. Exit 3.
+
+## When
+
+Each key in `kalup/removed.ts` is an address, such as `property:companies/legacy_score`: the type, a colon, the object, a slash and the name. A key with no object, such as `property:legacy_score`, names nothing and is refused. This version removes properties and property groups only, so a key of another type, such as `object:parcels`, is refused as well.
+
+## Fix
+
+Write the address as `kalup ir` lists it, or remove the entry.
+
+## Example
+
+```ts
+export default defineRemoved({
+  legacyScore: { action: 'destroy' },
+})
+```
+
+```
+kalup/removed.ts:4: E_TOMBSTONE_ADDRESS: 'legacyScore' is not an address (fix: write the address of a property or group, such as 'property:companies/legacy_score') (docs: errors/E_TOMBSTONE_ADDRESS.md)
+```

package/docs/errors/E_TOMBSTONE_CONFLICT.md

@@ -0,0 +1,17 @@
+# E_TOMBSTONE_CONFLICT
+
+An address is in `kalup/removed.ts` and still defined in config. Exit 3.
+
+## When
+
+A tombstone takes a resource out of config: `destroy` deletes it in the portal, `release` stops managing it and leaves it there. Config may not define the same address at the same time, not even as a reference without `label`, `group` and `fieldType`. This usually means the entry was added to `kalup/removed.ts` by hand and the property or group was left in its object file.
+
+## Fix
+
+Remove the property or group from its object file. `kalup rm <address>` does both steps: it removes it from config and writes the tombstone. To keep managing the resource, remove the tombstone instead.
+
+## Example
+
+```
+kalup/removed.ts:4: E_TOMBSTONE_CONFLICT: property:companies/legacy_score is in kalup/removed.ts and in config (fix: remove it from config, or run kalup rm, which does both) (docs: errors/E_TOMBSTONE_CONFLICT.md)
+```

package/docs/errors/E_TYPE_FIELDTYPE.md

@@ -0,0 +1,21 @@
+# E_TYPE_FIELDTYPE
+
+A `fieldType` the builder does not allow. Exit 3.
+
+## When
+
+Each builder allows some `fieldType` values. `p.enum` takes `select`, `radio` or `booleancheckbox`, and `p.multiEnum` only `checkbox`. [config.md](../config.md#builders) has the full list.
+
+## Fix
+
+Use one of the values in the fix, or change the builder: a `checkbox` enumeration is `p.multiEnum`.
+
+## Example
+
+```ts
+soil: p.enum('soil_type', { label: 'Soil type', group: 'orchard', fieldType: 'checkbox', options: [...] }),
+```
+
+```
+kalup/objects/companies.ts:14: E_TYPE_FIELDTYPE: fieldType 'checkbox' is not allowed for p.enum (type enumeration) (fix: use one of 'select', 'radio', 'booleancheckbox') (docs: errors/E_TYPE_FIELDTYPE.md)
+```

package/docs/errors/E_UNCERTAIN_WRITE.md

@@ -0,0 +1,17 @@
+# E_UNCERTAIN_WRITE
+
+HubSpot may or may not have applied a write. Exit 5. Kalup never sends it again.
+
+## When
+
+The write timed out, the network failed, HubSpot answered 5xx or a body that is not JSON, or it refused a create whose name then read back. HubSpot documents no idempotency keys, so a second attempt could fail on what the first made, or undo an edit made in between. Apply reads the resource back until a deadline of 60 seconds, and settles the step only when the approved values read back. Otherwise the step is `uncertain`, its state entry stays as it was, and steps that depend on it do not run.
+
+## Fix
+
+Run `kalup plan --target <name>`. It reads what HubSpot holds: a property the write made shows as an adopt, and anything not made shows again.
+
+## Example
+
+```
+E_UNCERTAIN_WRITE: s2 Create property "Soil pH" (soil_ph) on companies: HubSpot may or may not have applied it (no read showed the approved values within 60 s). kalup never sends it again. (fix: run kalup plan --target sandbox: it reads what HubSpot holds and shows what is left) (docs: errors/E_UNCERTAIN_WRITE.md)
+```

package/docs/errors/E_UNEXPECTED.md

@@ -0,0 +1,17 @@
+# E_UNEXPECTED
+
+An error Kalup has no code for. Exit 1.
+
+## When
+
+Anything that is not a Kalup or HubSpot error: a file it cannot read, or a request that got no answer in any command but `status`. The message is the first line of the error, stripped of control characters. It never holds a key.
+
+## Fix
+
+Read the message. A network failure clears when the network does. If it looks like a bug, report it with the command you ran and this line.
+
+## Example
+
+```
+E_UNEXPECTED: fetch failed (docs: errors/E_UNEXPECTED.md)
+```

package/docs/errors/E_UNKNOWN_BUILDER.md

@@ -0,0 +1,21 @@
+# E_UNKNOWN_BUILDER
+
+`p.<kind>` is not a builder. Exit 3.
+
+## When
+
+The builders are `p.string`, `p.number`, `p.boolean`, `p.date`, `p.datetime`, `p.enum`, `p.multiEnum`, `p.stringArray` and `p.json`. HubSpot field types such as `text` are not builders.
+
+## Fix
+
+Pick the builder for the HubSpot type and put the field type in `fieldType`.
+
+## Example
+
+```ts
+plotCount: p.text('plot_count'),
+```
+
+```
+kalup/objects/companies.ts:5: E_UNKNOWN_BUILDER: p.text is not a builder (fix: use one of p.string, p.number, p.boolean, p.date, p.datetime, p.enum, p.multiEnum, p.stringArray, p.json) (docs: errors/E_UNKNOWN_BUILDER.md)
+```

package/docs/errors/E_UNKNOWN_GROUP.md

@@ -0,0 +1,21 @@
+# E_UNKNOWN_GROUP
+
+A property's `group` is not declared for its object. Exit 3.
+
+## When
+
+A managed definition names its group by internal name. That group must be declared under `groups` in some export of the same object, in this file or another.
+
+## Fix
+
+Add the group to `groups`, or use a group that is there. `kalup pull` writes every group a pulled property uses.
+
+## Example
+
+```ts
+plotCount: p.number('plot_count', { label: 'Plot count', group: 'orchard', fieldType: 'number' }),
+```
+
+```
+kalup/objects/companies.ts:5: E_UNKNOWN_GROUP: group 'orchard' is not in the groups of companies (fix: add orchard: { label: '...' } to the groups block) (docs: errors/E_UNKNOWN_GROUP.md)
+```

package/docs/errors/E_UNKNOWN_INCLUDE.md

@@ -0,0 +1,17 @@
+# E_UNKNOWN_INCLUDE
+
+`objects.<key>.include` names properties the portal does not have. Exit 3. Nothing is written.
+
+## When
+
+`pull` checks every `include` name against the portal's property list for that object, after reading all objects.
+
+## Fix
+
+Remove the names, or correct them to the internal names shown in HubSpot's property settings.
+
+## Example
+
+```
+kalup.config.ts:6: E_UNKNOWN_INCLUDE: objects.companies.include names properties the portal does not have: plot_colour (fix: remove them, or check the internal names in HubSpot) (docs: errors/E_UNKNOWN_INCLUDE.md)
+```

package/docs/errors/E_UNKNOWN_OBJECT.md

@@ -0,0 +1,17 @@
+# E_UNKNOWN_OBJECT
+
+A key under `objects` is neither a standard object nor a custom object in the portal. Exit 3. Nothing is written.
+
+## When
+
+A key that is not a standard object name (`contacts`, `companies`, `deals`, `line_items` and the rest, plural) is read as a custom object. None of the portal's custom objects has that name. For a key a `defineCustomObject` in config backs, only `pull` stops: `plan` creates the object and `compare` finds it on the config side only.
+
+## Fix
+
+Use one of the names the message lists, or remove the key. Standard objects use HubSpot's plural API name: `companies`, not `company`.
+
+## Example
+
+```
+kalup.config.ts:8: E_UNKNOWN_OBJECT: 'presses' is not a standard object or a custom object in the portal (custom objects: harvest, press_run) (fix: use one of the names listed, or remove the key) (docs: errors/E_UNKNOWN_OBJECT.md)
+```

package/docs/errors/E_UNKNOWN_OVERRIDE.md

@@ -0,0 +1,17 @@
+# E_UNKNOWN_OVERRIDE
+
+An override key is not an address in config. Exit 3.
+
+## When
+
+`targets.<name>.overrides` is keyed by address: `property:<object>/<name>`, `group:<object>/<name>` or `object:<name>`. The address must exist in the config files.
+
+## Fix
+
+Use an address that `kalup ir` lists, or remove the override. Add the property to config first if it is missing.
+
+## Example
+
+```
+kalup.config.ts:13: E_UNKNOWN_OVERRIDE: override 'property:companies/plot_size' is not an address in config (fix: use an address that kalup ir lists, or remove the override) (docs: errors/E_UNKNOWN_OVERRIDE.md)
+```

package/docs/errors/E_UNKNOWN_TARGET.md

@@ -0,0 +1,17 @@
+# E_UNKNOWN_TARGET
+
+`--target` names a target that `kalup.config.ts` does not declare. Exit 3.
+
+## When
+
+Commands check `--target` against the `targets` block before they send anything. An undeclared name never falls back to `defaultTarget` or to the only target. A `defaultTarget` that names no declared target is `E_DEFAULT_TARGET`.
+
+## Fix
+
+Use a declared name (the fix lists them), or add the target with its `portalId` and `credentials`.
+
+## Example
+
+```
+kalup.config.ts:8: E_UNKNOWN_TARGET: target 'staging' is not declared (fix: use one of sandbox, production, or declare targets.staging) (docs: errors/E_UNKNOWN_TARGET.md)
+```

package/docs/errors/E_UNREACHABLE.md

@@ -0,0 +1,17 @@
+# E_UNREACHABLE
+
+HubSpot did not answer a request, even after retries. Exit 1.
+
+## When
+
+A read failed before any response came (no network, DNS, a proxy or a firewall), or got no answer within 30 seconds. Kalup retries it three times with a growing pause, as it does for a 5xx, then stops with this code. The message names the request and the last failure: the network error, or the timeout. `status` marks the target `unreachable` and checks the others.
+
+## Fix
+
+Check the network connection and any proxy, then run the command again.
+
+## Example
+
+```
+E_UNREACHABLE: GET /account-info/2026-09/details got no answer from HubSpot in 4 attempts: fetch failed (fix: Check the network connection and any proxy, then run the command again.) (docs: errors/E_UNREACHABLE.md)
+```

package/docs/errors/E_UNSUPPORTED_FILE.md

@@ -0,0 +1,17 @@
+# E_UNSUPPORTED_FILE
+
+A file under `kalup/` that this version does not read. Exit 3.
+
+## When
+
+Anything under `kalup/pipelines/`, a `defineConfig` file under `kalup/`, and a `defineRemoved` file anywhere under `kalup/` except `kalup/removed.ts`. Kalup reports them instead of skipping them silently.
+
+## Fix
+
+Move the file out of `kalup/` until a release reads it. A `defineConfig` file belongs at the project root as `kalup.config.ts`, and tombstones belong in `kalup/removed.ts`.
+
+## Example
+
+```
+kalup/pipelines/deals.ts:1: E_UNSUPPORTED_FILE: this version does not read pipelines yet (fix: move kalup/pipelines/deals.ts out of kalup/ until a release reads it) (docs: errors/E_UNSUPPORTED_FILE.md)
+```

package/docs/errors/E_USAGE.md

@@ -0,0 +1,17 @@
+# E_USAGE
+
+The command line is wrong. Exit 1.
+
+## When
+
+An unknown command, a flag the command does not take (each command accepts only its own flags), a flag without its value or repeated, an argument the command does not take or a missing one (`compare` needs two), `init` without a valid `--portal` or with `--target config`, or an `--out` path that is a symbolic link or lies inside `.kalup/` (other than `.kalup/snapshots/`), the lock directory or the state and journal directories `KALUP_STATE_DIR` moves, where Kalup keeps state, journals and locks. Without a command only `--json`, `--help`, `-h` and `--version` are accepted, so `kalup --target sandbox` reads `--target needs a command` and `kalup --help --bogus` reads `unknown flag --bogus`. Without `--json` the help for the named command, or the root help, follows the issue. `kalup <command> --help` lists the command's flags.
+
+## Fix
+
+Run `kalup --help` and correct the command.
+
+## Example
+
+```
+E_USAGE: unknown flag --portal (fix: run kalup --help) (docs: errors/E_USAGE.md)
+```

package/docs/errors/E_WRITE_IN_READ_MODE.md

@@ -0,0 +1,17 @@
+# E_WRITE_IN_READ_MODE
+
+Kalup refused to send a request to a write path through a read client. Exit 1. Nothing was sent.
+
+## When
+
+Every command that only reads (`pull`, `plan`, `status`, `compare`, `snapshot`, `init`) goes through a client that allows only paths tagged `read`, so none of them can reach a write path. Only `kalup apply` opens a write client, and it may send only the property and group writes on its own list (see `E_WRITE_NOT_ALLOWED`).
+
+## Fix
+
+This is a bug in Kalup. Report it with the command you ran.
+
+## Example
+
+```
+E_WRITE_IN_READ_MODE: POST /crm/properties/2026-09/{objectType} is a write path and this client only reads. (docs: errors/E_WRITE_IN_READ_MODE.md)
+```

package/docs/errors/E_WRITE_NOT_ALLOWED.md

@@ -0,0 +1,17 @@
+# E_WRITE_NOT_ALLOWED
+
+Kalup refused to send a write that this run may not send. Exit 1. Nothing was sent.
+
+## When
+
+A run that writes gets an explicit list of the writes it may send. This version allows creating, updating and archiving properties and property groups, and nothing else: no custom object schema writes. A request to any other write path, or to a read path through the write channel, is refused before it leaves Kalup.
+
+## Fix
+
+This is a bug in Kalup. Report it with the command you ran.
+
+## Example
+
+```
+E_WRITE_NOT_ALLOWED: POST /crm-object-schemas/2026-09/schemas (object create) is not a write this run may send. Nothing was sent. (docs: errors/E_WRITE_NOT_ALLOWED.md)
+```

package/docs/errors/W_BLUEPRINT_DOWNGRADE.md

@@ -0,0 +1,17 @@
+# W_BLUEPRINT_DOWNGRADE
+
+A warning from `kalup blueprint upgrade`: the new version is lower than the one the lock holds. Exit stays 0.
+
+## When
+
+Versions compare as semantic versions, a pre-release below its release. Moving to a lower version is allowed, for example to back out a release, and merges like any other: config's own changes stay, and resources the lower version lacks are detached, not deleted.
+
+## Fix
+
+Check that the lower version is the one you meant. If not, run the upgrade again with the version you want.
+
+## Example
+
+```
+W_BLUEPRINT_DOWNGRADE: acme/renewals goes from 2.0.0 down to 1.0.0 (fix: check that the lower version is the one you meant; the merge treats it like any other version) (docs: errors/W_BLUEPRINT_DOWNGRADE.md)
+```

package/docs/errors/W_CODEC_MISMATCH.md

@@ -0,0 +1,18 @@
+# W_CODEC_MISMATCH
+
+A warning from `pull`: the file's builder does not match the portal's property type or fieldType. Exit stays 0, except that `--check --exit-code` exits 2 on it.
+
+## When
+
+The file has `p.string` for a `number` in the portal, say, or `p.enum` where the portal fieldType is `checkbox`, which only `p.multiEnum` takes. Pull keeps the property as written and refreshes nothing on it, so the app's types hold and the file still validates. A fieldType no builder takes, such as `calculation_equation`, is not a mismatch.
+
+## Fix
+
+Change the builder to the one the message names, or keep it if the app relies on it.
+
+## Example
+
+```
+W_CODEC_MISMATCH: property:companies/plot_count is p.string in the file but type number in the portal; the file keeps p.string and nothing is refreshed (fix: change the builder to match the portal type, or keep it if the app relies on it) (docs: errors/W_CODEC_MISMATCH.md)
+W_CODEC_MISMATCH: property:companies/yield_tier is p.enum in the file, but its fieldType in the portal is checkbox, which p.enum does not take (p.multiEnum does); the file keeps p.enum and nothing is refreshed (fix: change the builder to p.multiEnum, or keep it if the app relies on it) (docs: errors/W_CODEC_MISMATCH.md)
+```

package/docs/errors/W_INCOMPLETE.md

@@ -0,0 +1,19 @@
+# W_INCOMPLETE
+
+A warning: a read of a target left something unread, so what it holds is unknown. Exit stays 0.
+
+## When
+
+A properties, groups or custom object schemas list answered 403 (`E_SCOPE`), so the object behind it was not read. Or a config property's portal group name holds whitespace (`W_UNADDRESSABLE_NAME`), so the read could not capture it: the snapshot lists it as `unaddressable`, with `complete: false`, and `plan` blocks its step with `W_UNADDRESSABLE_NAME` instead. `snapshot` still writes the file; its coverage marks what was not read. `docs` gives it for such a snapshot, listing it under Coverage. `plan` gives it when it could not read an object, or config has resources on a key not under `objects`, and blocks every resource there with reason `scope`: it never creates one. `compare` stops with `E_INCOMPLETE` instead.
+
+A resource missing from an object that was not read may still exist in the portal.
+
+## Fix
+
+A person adds the scopes the fix names to the target's read key in HubSpot, or renames the group it names to a name without spaces, then takes a new snapshot or plans again. For an object key the fix names, add it to `objects` in `kalup.config.ts`.
+
+## Example
+
+```
+W_INCOMPLETE: the snapshot of target sandbox is incomplete: harvest was not read, so what it holds is unknown (fix: add the scope crm.schemas.custom.read to the read key of target sandbox, then take a new snapshot) (docs: errors/W_INCOMPLETE.md)
+```

package/docs/errors/W_JSON_FIELDTYPE.md

@@ -0,0 +1,17 @@
+# W_JSON_FIELDTYPE
+
+A warning from validate: a `p.json` property whose `fieldType` is not `textarea`. Exit stays 0.
+
+## When
+
+JSON text is often longer than one line, so it belongs in a textarea.
+
+## Fix
+
+Set `fieldType: 'textarea'`.
+
+## Example
+
+```
+kalup/objects/companies.ts:24: W_JSON_FIELDTYPE: p.json 'orch_row_meta' has fieldType 'text'; JSON text belongs in a textarea (fix: set fieldType: 'textarea') (docs: errors/W_JSON_FIELDTYPE.md)
+```

package/docs/errors/W_KEY_COLLISION.md

@@ -0,0 +1,17 @@
+# W_KEY_COLLISION
+
+A warning from `pull`: a new property's default key was taken, so its internal name is the key. Exit stays 0.
+
+## When
+
+Pull keys a new property by camelCase of its internal name. When another property of the object already has that key, the new one gets its internal name as key.
+
+## Fix
+
+Rename either key to what the app should call it. Pull keeps keys as written from then on.
+
+## Example
+
+```
+W_KEY_COLLISION: property:companies/plot_count: the key plotCount is taken, so its internal name is the key (fix: rename one of the two keys) (docs: errors/W_KEY_COLLISION.md)
+```

package/docs/errors/W_LARGE_SCOPE.md

@@ -0,0 +1,23 @@
+# W_LARGE_SCOPE
+
+A warning from `init`: the first pull wrote more than 200 properties for one object. Exit stays 0.
+
+## When
+
+`init` writes `{}` for each object, so every custom property is in the pull scope.
+
+## Fix
+
+If the app needs only some of them, set `custom: false` for that object and list the ones it needs under `include`. Properties already in the file stay; pull never removes a property.
+
+## Example
+
+```ts
+objects: {
+  companies: { custom: false, include: ['plot_count', 'soil_type'] },
+},
+```
+
+```
+W_LARGE_SCOPE: the first pull wrote 312 properties for companies: every custom property is in the pull scope (fix: set objects.companies.custom to false and list the properties the app needs under objects.companies.include) (docs: errors/W_LARGE_SCOPE.md)
+```