kalup 0.1.0

package/docs/errors/E_MISSING_EXPORT.md

@@ -0,0 +1,17 @@
+# E_MISSING_EXPORT
+
+A file under `kalup/` has no `defineObject` or `defineCustomObject` export. Exit 3.
+
+## When
+
+Kalup reads every `.ts` file under `kalup/` except `kalup/index.ts` as an object file. A file with only imports, or an empty file, has nothing to read.
+
+## Fix
+
+Add the export, or move the file out of `kalup/`.
+
+## Example
+
+```
+kalup/objects/empty.ts:1: E_MISSING_EXPORT: no defineObject or defineCustomObject export in this file (fix: add `export const <Name> = defineObject('<object>', {...})`) (docs: errors/E_MISSING_EXPORT.md)
+```

package/docs/errors/E_MISSING_KEY.md

@@ -0,0 +1,17 @@
+# E_MISSING_KEY
+
+The variable that should hold the read key is not set. Exit 1.
+
+## When
+
+The variable is `credentials.read.env` of the target, or `HUBSPOT_SERVICE_KEY` when the target has no `credentials`. In this version `init` has no `--env` flag and always reads `HUBSPOT_SERVICE_KEY`. Kalup looks in the process environment, then in `.env` in the project directory. `status` reports it per target and checks the others.
+
+## Fix
+
+A person sets the variable in the shell or adds `NAME=value` to `.env`. Never paste the key into a chat, a log or a commit. `.env` belongs in `.gitignore`, and `init` adds it there.
+
+## Example
+
+```
+E_MISSING_KEY: HUBSPOT_SANDBOX_KEY is not set. (fix: Set HUBSPOT_SANDBOX_KEY in the environment or in .env in the project directory.) (docs: errors/E_MISSING_KEY.md)
+```

package/docs/errors/E_NOT_DATA.md

@@ -0,0 +1,21 @@
+# E_NOT_DATA
+
+A config file holds something outside the grammar Kalup reads. Exit 3.
+
+## When
+
+Kalup parses config as data and never runs it. Identifiers, spreads, template strings, calls other than the builders, a comment that is not on its own line above an entry, an unknown field, a value of the wrong type, a `credentials` `env` that is not an environment variable name (the value is never quoted back, in case it is the key itself), and a missing required field (a custom object's `labels` or `primaryDisplayProperty`, a group's `label`, an option's `value` or `label`, `credentials.read`) are all this code. The message and the fix say which. [config.md](../config.md#the-grammar) lists the grammar.
+
+## Fix
+
+Follow the fix. To keep a note, put a `//` comment on its own line above the property, group or export.
+
+## Example
+
+```ts
+plotCount: p.number('plot_count'), // counted by hand
+```
+
+```
+kalup/objects/companies.ts:5: E_NOT_DATA: this comment is not attached to an entry (fix: move this comment above the entry it describes) (docs: errors/E_NOT_DATA.md)
+```

package/docs/errors/E_NO_CONFIG.md

@@ -0,0 +1,17 @@
+# E_NO_CONFIG
+
+No `kalup.config.ts` in the working directory or any directory above it. Exit 1.
+
+## When
+
+Every command except `init` starts by looking for `kalup.config.ts`, from the working directory upwards.
+
+## Fix
+
+Run the command inside the project. For a new project, run `npx --no-install kalup init --portal <id>`.
+
+## Example
+
+```
+E_NO_CONFIG: no kalup.config.ts in /work/notes or any directory above it (fix: run npx kalup init --portal <id> in the project directory) (docs: errors/E_NO_CONFIG.md)
+```

package/docs/errors/E_NO_TARGETS.md

@@ -0,0 +1,17 @@
+# E_NO_TARGETS
+
+`kalup.config.ts` declares no targets, so a command that reads a portal has none to read. Exit 3.
+
+## When
+
+`pull`, `plan` and `snapshot`, after the config validates and before any request. `validate`, `ir`, `fmt` and `docs` need no target.
+
+## Fix
+
+Declare one under `targets` with the portal's Hub ID, for example `targets: { prod: { portalId: 1111111 } }`. The name is yours to choose. `kalup init --portal <id>` writes one for a new project.
+
+## Example
+
+```
+E_NO_TARGETS: kalup.config.ts declares no targets (fix: declare one under targets, for example targets: { prod: { portalId: <Hub ID> } }) (docs: errors/E_NO_TARGETS.md)
+```

package/docs/errors/E_OVERRIDE_AMBIGUOUS.md

@@ -0,0 +1,21 @@
+# E_OVERRIDE_AMBIGUOUS
+
+A name override is ambiguous: the portal holds both names. Exit 1.
+
+## When
+
+`overrides: { '<address>': { name: '<portal name>' } }` says the resource has another name in this portal. When the portal also holds a resource under the address's own name, and no other name override claims that name, Kalup cannot tell which one the address means. A swap is fine, since each override claims the other's name, as is an override to the address's own name. In a chain, the first address's own name must be missing from the portal or claimed by another override. Property and group overrides are checked against the object's lists (an archived group does not count), `object:` overrides against the custom object schemas.
+
+## Fix
+
+Remove the override if the address's own name is the right one, or rename one of the two in HubSpot.
+
+## Example
+
+```ts
+overrides: { 'property:harvest/picked_on': { name: 'pickedon' } },
+```
+
+```
+E_OVERRIDE_AMBIGUOUS: the portal holds both 'pickedon' and 'picked_on' on harvest, so the name override for property:harvest/picked_on is ambiguous (fix: remove the override, or rename one of the two in HubSpot) (docs: errors/E_OVERRIDE_AMBIGUOUS.md)
+```

package/docs/errors/E_OVERRIDE_DEFINITION.md

@@ -0,0 +1,26 @@
+# E_OVERRIDE_DEFINITION
+
+A target's definition override states something that cannot differ per target. Exit 3.
+
+## When
+
+`overrides: { '<address>': { definition: {...} } }` replaces fields of the shared definition on one target. `validate` and every command that validates first report, at the override's line:
+
+- a field other than `label`, `description`, `group`, `fieldType`, `formField` and `options` on a property, or `label` on a group. `hasUniqueValue` is fixed when HubSpot creates a property, and `type` comes from the builder. In `lifecycle`, only `options`, `removedOptions` and `ignoreChanges`.
+- an override on a reference, a `.managed(false)` property or a custom object schema.
+- a result that breaks a shared rule: a `fieldType` the builder does not take, a `group` the object does not declare, an option value twice, `removedOptions` naming a kept option, `ignoreChanges` naming no definition field.
+- an option with `as`. Aliases belong to the app and stay in the shared file.
+
+## Fix
+
+Change or remove what the message names.
+
+## Example
+
+```ts
+overrides: { 'property:deals/term_days': { definition: { hasUniqueValue: true } } },
+```
+
+```
+kalup.config.ts:8: E_OVERRIDE_DEFINITION: property:deals/term_days on target sandbox: hasUniqueValue is fixed when HubSpot creates the property, so it cannot differ per target (fix: remove hasUniqueValue from the override) (docs: errors/E_OVERRIDE_DEFINITION.md)
+```

package/docs/errors/E_OVERRIDE_NAME.md

@@ -0,0 +1,23 @@
+# E_OVERRIDE_NAME
+
+Two addresses in config would read one portal resource through a name override. Exit 3.
+
+## When
+
+`overrides: { '<address>': { name: '<portal name>' } }` makes the address read the portal resource of that name on the target. When another address of the same type, on the same object, already has that name and no name override of its own on the target, both addresses would read the same portal resource. So would two name overrides with the same value, an override to the address's own name included. `validate` and every command that validates first report it.
+
+Swapping two names is fine: give each address its own name override.
+
+## Fix
+
+Give the other address its own name override on the target, give each of two overrides its own portal name, or rename one of the two in config.
+
+## Example
+
+```ts
+overrides: { 'property:deals/term_days': { name: 'amount' } },
+```
+
+```
+kalup.config.ts:8: E_OVERRIDE_NAME: the name override for property:deals/term_days on target sandbox is 'amount', the name of property:deals/amount, which has no name override there (fix: give property:deals/amount its own name override on sandbox, or rename one of the two in config) (docs: errors/E_OVERRIDE_NAME.md)
+```

package/docs/errors/E_PLAN_DELETE.md

@@ -0,0 +1,17 @@
+# E_PLAN_DELETE
+
+A saved plan deletes something config does not ask to delete. Exit 1. Nothing was written.
+
+## When
+
+A delete needs a `destroy` tombstone that `kalup rm` wrote, or takeover to ask for it (the mode of the object on the target is takeover, the address is in the pull scope, neither `exclude`, a `skip` override nor a tombstone names it, and the step carries the `takeover` label), and an address gone from config. Before approval, `kalup apply` reads `kalup/removed.ts` and the object files as data, never running them, and refuses a delete step whose address has neither, is still in config, or sets `lifecycle.preventDestroy`; the message says why takeover does not archive it. It also refuses a delete of a portal resource that another address in config names through a name override on the target. The tombstone was removed after planning, the resource came back into config or into `exclude`, or the plan file was edited.
+
+## Fix
+
+To delete a resource, run `kalup rm <address>`, then plan again and review the plan. A resource that sets `preventDestroy` is never deleted through Kalup.
+
+## Example
+
+```
+E_PLAN_DELETE: plan pl_7f3a1c07b2e4 deletes what config does not ask to delete: property:companies/soil_ph is in config and sets lifecycle.preventDestroy. Nothing was written. (fix: to delete a resource, run kalup rm <address>, then kalup plan --target sandbox --out <file> and review it; a plan file is never edited by hand) (docs: errors/E_PLAN_DELETE.md)
+```

package/docs/errors/E_PLAN_DESTINATION.md

@@ -0,0 +1,17 @@
+# E_PLAN_DESTINATION
+
+The plan's target is not where `kalup.config.ts` points now. Exit 1. Nothing was sent.
+
+## When
+
+A saved plan names its destination: a target name and a portal ID. `kalup apply` reads `kalup.config.ts` and refuses when that target is no longer declared, or when it now pins another portal. A renamed target keeps its state, but a plan saved under the old name is refused.
+
+## Fix
+
+Plan again against a declared target with `kalup plan --target <name> --out <file>`, review it, and apply that file. If the portal ID in config is wrong, a person corrects it first.
+
+## Example
+
+```
+E_PLAN_DESTINATION: plan pl_7f3a1c07b2e4 is for target production on portal 2222222, and kalup.config.ts pins that target to portal 3333333. Nothing was sent. (fix: run kalup plan against a declared target with --out, review it and apply that file) (docs: errors/E_PLAN_DESTINATION.md)
+```

package/docs/errors/E_PLAN_DIGEST.md

@@ -0,0 +1,17 @@
+# E_PLAN_DIGEST
+
+The plan file changed after `kalup plan` saved it. Exit 1. Nothing was sent.
+
+## When
+
+`kalup apply` recomputes `writesHash` and `planId` from what the file says it writes: the destination, the policy, the state lineage and serial, the normalizer versions, the bindings and every step with an effect. When they differ from the values in the file, someone or something edited the plan. Titles, stated risk and counts are not part of the digest, so editing them does not trigger this.
+
+## Fix
+
+Run `kalup plan --target <name> --out <file>` again, review the new plan, and apply that file.
+
+## Example
+
+```
+E_PLAN_DIGEST: plan.json: writesHash and planId do not match what the plan says it writes, so it was changed after kalup plan saved it. Nothing was sent. (fix: run kalup plan --target sandbox --out plan.json again and review it) (docs: errors/E_PLAN_DIGEST.md)
+```

package/docs/errors/E_PLAN_INVALID.md

@@ -0,0 +1,17 @@
+# E_PLAN_INVALID
+
+`kalup apply` could not use the plan file. Exit 1. Nothing was sent.
+
+## When
+
+The file named on the command line is missing, is not JSON, or does not match the `plan/1` schema. The message names the first place that fails. Apply also refuses a file whose steps contradict themselves: a change that writes a value the step's `desired` values do not hold. `kalup plan` never writes such a file.
+
+## Fix
+
+Save the plan again with `kalup plan --target <name> --out <file>`, review it, and apply that file. Never edit a plan file by hand.
+
+## Example
+
+```
+E_PLAN_INVALID: plan.json is not JSON. Nothing was sent. (fix: save the plan again with kalup plan --target <name> --out <file>, and apply that file) (docs: errors/E_PLAN_INVALID.md)
+```

package/docs/errors/E_PLAN_RISK.md

@@ -0,0 +1,17 @@
+# E_PLAN_RISK
+
+A step in the plan does not match what Kalup derives from state and the portal. Exit 1. Nothing was written.
+
+## When
+
+Under the portal lock, `kalup apply` reads state and the portal again and derives each step's risk, labels and blocked status as `plan` does. It refuses when a step states a lower risk than derived, leaves out a derived label (`reverts-ui-edit`, `overwrites-portal`, `takeover`), or would be blocked: an update of what state does not own, a delete of what state does not own that takeover does not archive, an adopt of what it does, a delete or takeover option removal the target does not allow, a takeover archive of what HubSpot defines, of a property in a group a `skip` override covers or one a custom object schema names, of a group that held no property, or whose `expect` leaves out a field the base holds (so an edit made in HubSpot after the review would not stop it), a custom object schema change, or a group delete while properties still name the group. A plan `kalup plan` saved matches, unless config changed since, such as a `skip` override added; otherwise the file was edited.
+
+## Fix
+
+Run `kalup plan --target <name> --out <file>` again and review it. Never edit a plan file by hand.
+
+## Example
+
+```
+E_PLAN_RISK: plan pl_7f3a1c07b2e4 does not match what kalup derives from state and the portal: s1 states risk safe, and it is risky. Nothing was written. (fix: run kalup plan --target sandbox --out <file> again and review it; a plan file is never edited by hand) (docs: errors/E_PLAN_RISK.md)
+```

package/docs/errors/E_PLAN_SCHEMA.md

@@ -0,0 +1,17 @@
+# E_PLAN_SCHEMA
+
+A plan does not match the `plan/1` JSON Schema. Exit 1.
+
+## When
+
+`kalup plan` checks the plan it built against `plan-1.schema.json` before it prints or writes it, and stops when the plan does not match. `configPath` is a path in the plan, such as `steps[2].risk`, not a place in a file. A tool that reads a plan file can check it against `plan-1.schema.json`, which the `kalup` package ships as `kalup/schemas/plan-1.schema.json`.
+
+## Fix
+
+A plan Kalup built always matches, so from `kalup plan` this is a bug in Kalup: report it with the command you ran and the issue text. For a plan file that was edited by hand, run `kalup plan` again instead.
+
+## Example
+
+```
+E_PLAN_SCHEMA: expected "blocked" (docs: errors/E_PLAN_SCHEMA.md)
+```

package/docs/errors/E_PLAN_STALE.md

@@ -0,0 +1,17 @@
+# E_PLAN_STALE
+
+The portal changed after the plan was made. Exit 1 when nothing was written, 5 when earlier steps of the run wrote.
+
+## When
+
+Each step records what it expects to find: whether the resource exists, and the live value of every field it writes. `kalup apply` checks every step against a fresh read before the first write, and each step again right before its own write. A change made in HubSpot since the plan, such as a label edited in the UI or a property created by someone else, stops the run there. The message lists what moved.
+
+## Fix
+
+Run `kalup plan --target <name> --out <file>` again. The new plan compares with what the portal holds now, so an edit made in HubSpot is held instead of overwritten. Review it and apply that file.
+
+## Example
+
+```
+E_PLAN_STALE: the portal changed since plan pl_7f3a1c07b2e4 was made: property:companies/soil_ph label. Nothing was written. (fix: run kalup plan --target sandbox --out <file> again and review it) (docs: errors/E_PLAN_STALE.md)
+```

package/docs/errors/E_PLAN_VERSION.md

@@ -0,0 +1,18 @@
+# E_PLAN_VERSION
+
+The plan was made for another version of Kalup. Exit 1. Nothing was written.
+
+## When
+
+A saved plan applies only as `plan/1` and under the release line of Kalup that made it (`generator.version`): one major version from 1.0.0, one minor version before it (in 0.x any minor release may change what a field means), one exact pre-release. `kalup apply` checks this first, before the schema and any request, since a newer version's plan need not match this version's schema. After the portal guard it also refuses a step whose API row is not the one this version sends or whose pin has expired, and a plan compared under other normalizer versions. The comparison the plan was reviewed on would no longer hold.
+
+## Fix
+
+Plan again with the version you apply with: `kalup plan --target <name> --out <file>`, review it, and apply that file. An expired pin needs a newer release of Kalup.
+
+## Example
+
+```
+E_PLAN_VERSION: plan.json was made by kalup 2.0.0, and this is kalup 1.4.0: a saved plan applies only under the release line that made it. Nothing was sent. (fix: plan again with this version: run kalup plan --target <name> --out <file>, review it and apply that file) (docs: errors/E_PLAN_VERSION.md)
+E_PLAN_VERSION: plan pl_7f3a1c07b2e4 was made for another version of kalup: s2 uses crm.properties 2026-03, and this version sends crm.properties 2026-09. Nothing was written. (fix: run kalup plan --target sandbox --out <file> with this version and review it; an expired pin needs a newer release) (docs: errors/E_PLAN_VERSION.md)
+```

package/docs/errors/E_POLICY_CHANGED.md

@@ -0,0 +1,17 @@
+# E_POLICY_CHANGED
+
+The target's policy changed after the plan was made. Exit 1. Nothing was written.
+
+## When
+
+A plan records the target's effective policy: `protected`, `drift`, `adopt`, `allowDestroy`, `yesLimit` and the objects whose mode is takeover, with their defaults filled in (unless config says otherwise, every account but a `DEVELOPER_TEST`, `SANDBOX` or `APP_DEVELOPER` one is protected, an unknown type included). An approval covers the plan under that policy. `kalup apply` works the policy out again from `kalup.config.ts` and the account type, and refuses when any field differs. The message names each field, before and now.
+
+## Fix
+
+Run `kalup plan --target <name> --out <file>` again under the policy config holds now, review it, and apply that file.
+
+## Example
+
+```
+E_POLICY_CHANGED: the policy of target sandbox changed since plan pl_7f3a1c07b2e4: protected was false, now true. Nothing was written. (fix: run kalup plan --target sandbox --out <file> again and review it under the policy in kalup.config.ts) (docs: errors/E_POLICY_CHANGED.md)
+```

package/docs/errors/E_PORTAL_ID.md

@@ -0,0 +1,17 @@
+# E_PORTAL_ID
+
+A target has no `portalId`, or it is not a positive integer. Exit 3.
+
+## When
+
+`portalId` pins the target to one portal. Every networked command checks the key against it.
+
+## Fix
+
+Set `portalId` to the Hub ID from the HubSpot account menu. Do not change a pin to make a mismatch go away; see E_TARGET_PORTAL_MISMATCH.md.
+
+## Example
+
+```
+kalup.config.ts:10: E_PORTAL_ID: portalId 0 is not a positive integer (fix: set portalId to the portal ID shown in HubSpot, a positive integer) (docs: errors/E_PORTAL_ID.md)
+```

package/docs/errors/E_PREVENT_DESTROY.md

@@ -0,0 +1,17 @@
+# E_PREVENT_DESTROY
+
+`kalup rm` was asked to write a destroy tombstone for a resource that sets `lifecycle.preventDestroy`. Exit 3. Nothing was written.
+
+## When
+
+`preventDestroy: true` in a property's `lifecycle` says the property must never be deleted through Kalup. `kalup rm <address>` writes a `destroy` tombstone, which a later plan turns into a delete, so rm refuses it before it changes any file.
+
+## Fix
+
+To delete it after all, remove `preventDestroy` from its lifecycle first, then run `kalup rm` again. To stop managing it and leave it in HubSpot, run `kalup rm <address> --release`, which preventDestroy allows.
+
+## Example
+
+```
+kalup/objects/companies.ts:14: E_PREVENT_DESTROY: property:companies/soil_ph sets lifecycle.preventDestroy, so rm does not write a destroy tombstone for it. Nothing was written. (fix: remove preventDestroy from its lifecycle first, or run kalup rm property:companies/soil_ph --release to stop managing it and leave it in HubSpot) (docs: errors/E_PREVENT_DESTROY.md)
+```

package/docs/errors/E_PROJECT_WRITE.md

@@ -0,0 +1,17 @@
+# E_PROJECT_WRITE
+
+A command could not write the project files it changes. Exit 1.
+
+## When
+
+`kalup rm`, `kalup pull`, `kalup target rebind`, `kalup add` and `kalup blueprint upgrade` change several files as one: each file is copied to `.kalup/history`, written to a temporary name beside it, then renamed over the old one. When a history copy, a write, a rename or the removal of an old blueprint original fails, for example on a full disk or a read-only directory, every file already renamed gets its previous text back and the temporary files are removed, so the project is left as it was. The message says so, or names any file that could not be put back; its previous text is under `.kalup/history`.
+
+## Fix
+
+Check that the project directory is writable and the disk has room, then run the command again.
+
+## Example
+
+```
+E_PROJECT_WRITE: could not write kalup/index.ts, kalup/objects/companies.ts, kalup/removed.ts (ENOSPC). Every file was left as it was. (fix: check that the project directory is writable and the disk has room, then run the command again) (docs: errors/E_PROJECT_WRITE.md)
+```

package/docs/errors/E_PROTECTED_SAVED_PLAN.md

@@ -0,0 +1,17 @@
+# E_PROTECTED_SAVED_PLAN
+
+`kalup apply` without a plan file does not run on a protected target. Exit 1. Nothing was written.
+
+## When
+
+Without a file, `kalup apply` plans the target and applies that plan in one run. That is only for an unprotected target, such as a sandbox. A protected target (`protected: true`, and unless config says otherwise every account but a `DEVELOPER_TEST`, `SANDBOX` or `APP_DEVELOPER` one) accepts only a saved plan that a person reviewed.
+
+## Fix
+
+Run `kalup plan --target <name> --out plan.json` and review the plan. Then a person runs `kalup apply plan.json` in a terminal and confirms it.
+
+## Example
+
+```
+E_PROTECTED_SAVED_PLAN: target production is protected, so it accepts only a saved plan that a person reviewed. Nothing was written. (fix: run kalup plan --target production --out plan.json, review it, then ask the user to run kalup apply plan.json in a terminal) (docs: errors/E_PROTECTED_SAVED_PLAN.md)
+```

package/docs/errors/E_PULL_INVALID.md

@@ -0,0 +1,20 @@
+# E_PULL_INVALID
+
+The files `pull` merged would not load or validate, so it wrote nothing. Exit 3, with or without `--check`.
+
+## When
+
+Pull merges the portal into the object files, then loads and validates the whole project as it would write it, before saving anything. The issues after this one are what `validate` would report, with the file and line in the merged text, not the file on disk.
+
+Two examples: a property HubSpot does not define whose name starts with `hs_` (`E_HS_PREFIX`), and a new property whose key is taken twice (`E_DUPLICATE_KEY`).
+
+## Fix
+
+Change the portal or the file so the two agree, then pull again. To pull everything else first, leave the resource out with `--only`.
+
+## Example
+
+```
+E_PULL_INVALID: the pulled project would not validate; nothing was written (fix: the issues that follow point at the files as pull would write them: change the portal or the file so they agree, or leave the resource out with --only) (docs: errors/E_PULL_INVALID.md)
+kalup/objects/companies.ts:20: E_HS_PREFIX: 'hs_orchard_score' starts with hs_, the prefix HubSpot uses for its own properties (fix: rename the property, or drop label, group and fieldType to reference it) (docs: errors/E_HS_PREFIX.md)
+```

package/docs/errors/E_RATE_LIMIT.md

@@ -0,0 +1,17 @@
+# E_RATE_LIMIT
+
+HubSpot kept answering 429 after three retries. Exit 1, or 5 when `kalup apply` had already written.
+
+## When
+
+Kalup honours `Retry-After` up to 60 seconds, else backs off, and retries three times. `kalup apply` waits out a 429, 423 or 477 on a write three times, reading the resource again before each new attempt, then stops the run with that step not run.
+
+## Fix
+
+Wait a minute and run the command again.
+
+## Example
+
+```
+E_RATE_LIMIT: HubSpot rate limit hit and 3 retries did not clear it. (docs: errors/E_RATE_LIMIT.md)
+```

package/docs/errors/E_REBIND_STANDARD.md

@@ -0,0 +1,17 @@
+# E_REBIND_STANDARD
+
+`kalup target rebind` was pointed at an account that is not a test portal or a sandbox. Exit 4, `humanRequired: true`. Nothing was written.
+
+## When
+
+Rebind is for a test portal or sandbox that was recreated under a new Hub ID. It rewrites the pin in `kalup.config.ts` and adopts, by name, every config resource the new portal holds. It accepts only a `DEVELOPER_TEST` or `SANDBOX` account. Any other type, `STANDARD`, `APP_DEVELOPER` or one Kalup does not know, is refused: a `STANDARD` account is usually a production portal, where adopting by name alone is not a safe way to move a target.
+
+## Fix
+
+Stop and ask the user to check the portal ID. To move a target to a production portal on purpose, a person changes `portalId` in `kalup.config.ts`, runs `kalup plan` and reviews every adoption before applying it.
+
+## Example
+
+```
+E_REBIND_STANDARD: portal 2222222 is a STANDARD account; rebind is only for recreated test portals (DEVELOPER_TEST) and sandboxes (SANDBOX). Nothing was written. (fix: ask the user to check the portal ID; to move a target to a production portal, change portalId in kalup.config.ts by hand and review the plan) (docs: errors/E_REBIND_STANDARD.md)
+```

package/docs/errors/E_REFERENCE_DEFINITION.md

@@ -0,0 +1,21 @@
+# E_REFERENCE_DEFINITION
+
+A property is neither managed nor a valid reference. Exit 3.
+
+## When
+
+A property is one of three things: a full definition with `label`, `group` and `fieldType`; `p.enum` or `p.multiEnum` with `options` only; or no definition. A definition missing one of the three fields, options only on another builder, or `.managed(false)` on a property with no full definition is this error.
+
+## Fix
+
+Add the missing fields, or drop the definition to reference the portal's property.
+
+## Example
+
+```ts
+plotTotal: p.number('plot_total', { label: 'Plot total' }),
+```
+
+```
+kalup/objects/companies.ts:23: E_REFERENCE_DEFINITION: a definition needs label, group and fieldType (fix: add the missing fields, or drop the definition) (docs: errors/E_REFERENCE_DEFINITION.md)
+```

package/docs/errors/E_RM_DEPENDENTS.md

@@ -0,0 +1,17 @@
+# E_RM_DEPENDENTS
+
+`kalup rm` was asked to take out a resource that other config still uses. Exit 3. Nothing was written.
+
+## When
+
+A property group cannot leave config while properties in config name it as their `group`. A property cannot leave config while a custom object schema in config names it as its `primaryDisplayProperty` or in `secondaryDisplayProperties`, `requiredProperties` or `searchableProperties`. The message lists what uses it. The check is the same for `--release`.
+
+## Fix
+
+Move those properties to another group, or remove them first (with `kalup rm` for each), or change the schema. Then run `kalup rm` again.
+
+## Example
+
+```
+kalup/objects/companies.ts:6: E_RM_DEPENDENTS: group:companies/orchard cannot leave config while properties in config use it: property:companies/soil_ph. Nothing was written. (fix: remove or change those first, then run rm again) (docs: errors/E_RM_DEPENDENTS.md)
+```

package/docs/errors/E_SCOPE.md

@@ -0,0 +1,17 @@
+# E_SCOPE
+
+HubSpot answered 403: the key lacks a scope.
+
+## When
+
+A 403 on a properties, groups or schemas list is a gap: the objects behind it are not read and the rest continue. `pull` and `compare` then end with `E_INCOMPLETE`, exit 1. `plan` blocks what is on them and `snapshot` marks them unread, both with `W_INCOMPLETE` and exit 0. The archived properties lists `plan` reads for its creates are no gap: a 403 there stops `plan`, exit 1. In `status`, a 403 on a scope check marks the scope missing, exit 0. A 403 on account-info stops the command, exit 1; `status` marks that target failed and checks the others. A refused Limits Tracking reading is no error: `plan` records it as unreadable, and warns with `W_LIMIT_UNREADABLE` when it creates properties.
+
+## Fix
+
+A person adds the scope named in the fix to the key in HubSpot. A key can only hold scopes its creator has, so a Super Admin creates it.
+
+## Example
+
+```
+E_SCOPE: HubSpot refused GET /crm-object-schemas/2026-09/schemas (403). The key likely lacks the scope crm.schemas.custom.read. (fix: Add the scope crm.schemas.custom.read to the key.) (docs: errors/E_SCOPE.md)
+```

package/docs/errors/E_SETTING_LEVEL.md

@@ -0,0 +1,21 @@
+# E_SETTING_LEVEL
+
+A setting in kalup.config.ts is at a level that does not allow it. Exit 3.
+
+## When
+
+Each setting has the levels it may stand at. `mode` goes at the top level, under `objects.<object>`, under `targets.<target>` or under `targets.<target>.objects.<object>`. `include`, `exclude`, `custom` and `as` go under `objects.<object>`, and are never per target. `protected`, `drift`, `adopt`, `allowDestroy` and `yesLimit` go under `targets.<target>` only: a portal opts itself in, so none of them is inherited from the project or an object. No setting goes in an override or a property definition.
+
+## Fix
+
+Move the setting to one of the levels the fix lists, each with a snippet. The most specific statement of `mode` wins: `targets.<target>.objects.<object>`, then `targets.<target>`, then `objects.<object>`, then the top level.
+
+## Example
+
+```ts
+objects: { companies: { allowDestroy: true } },
+```
+
+```
+kalup.config.ts:6: E_SETTING_LEVEL: allowDestroy is not allowed in objects.companies (fix: move it to targets.<target> (targets: { sandbox: { allowDestroy: true } })) (docs: errors/E_SETTING_LEVEL.md)
+```

package/docs/errors/E_SETTING_VALUE.md

@@ -0,0 +1,23 @@
+# E_SETTING_VALUE
+
+A setting in kalup.config.ts has a value it does not allow. Exit 3.
+
+## When
+
+`mode` takes `'addon'` or `'takeover'`; `drift` and `adopt` take `'hold'` or `'overwrite'`; `yesLimit` takes an integer from 0 to 1000. The fix names the nearest allowed value.
+
+`validate` also reports a name that `include` and `exclude` of one object both list, and a `targets.<target>.objects` key that `objects` does not declare.
+
+## Fix
+
+Write the value the fix suggests, or another allowed one. Remove a name from one of `include` and `exclude`.
+
+## Example
+
+```ts
+mode: 'take-over',
+```
+
+```
+kalup.config.ts:5: E_SETTING_VALUE: 'take-over' is not a value of mode (fix: did you mean 'takeover'? write 'addon' or 'takeover') (docs: errors/E_SETTING_VALUE.md)
+```

package/docs/errors/E_SNAPSHOT.md

@@ -0,0 +1,17 @@
+# E_SNAPSHOT
+
+A snapshot file could not be used. Exit 1 when the file is missing, is not JSON or would be overwritten; exit 3 when it is JSON but not a snapshot this version reads.
+
+## When
+
+`compare` and `docs` read snapshot files that `kalup snapshot` wrote: `ir/1` documents from a portal read, with an observation block. A missing file, or one that is not JSON, is exit 1, as is a `compare` side that is neither `config`, a declared target nor a file. Exit 3: another `irVersion` (refused before anything else), the IR `kalup ir` derives, a resource typed unlike its address, or a coverage name no address can hold. A snapshot that breaks the `ir/1` schema gives `E_IR_SCHEMA` issues naming the file instead. `snapshot` never replaces a file: when its file already exists, it stops with exit 1.
+
+## Fix
+
+Pass a file `kalup snapshot` wrote, or `config` for the config files. For another `irVersion`, snapshot again with this version, or read it with the version of Kalup that wrote it. For a file that exists, pass another `--out` or move the old file away.
+
+## Example
+
+```
+E_SNAPSHOT: ir.json is not a snapshot: it is not an ir/1 document from a portal read with an observation block (fix: pass a file the snapshot command wrote, or config for the config files) (docs: errors/E_SNAPSHOT.md)
+```

package/docs/errors/E_STANDARD_OBJECT.md

@@ -0,0 +1,21 @@
+# E_STANDARD_OBJECT
+
+A `defineCustomObject` uses the key of a standard object. Exit 3.
+
+## When
+
+`defineCustomObject` defines a custom object schema. HubSpot has no custom object schema under a standard object's name (`contacts`, `companies`, `deals`, `line_items` and the rest), so no read can find one there. `validate` and every command that validates first report it, before any request.
+
+## Fix
+
+For the standard object, use `defineObject` and drop `labels` and the display properties. For a custom object, give it a name that is not a standard object's.
+
+## Example
+
+```ts
+export const Company = defineCustomObject('companies', { labels: { singular: 'Company', plural: 'Companies' }, ... })
+```
+
+```
+kalup/objects/companies.ts:6: E_STANDARD_OBJECT: 'companies' is a standard object in HubSpot, so defineCustomObject cannot define it (fix: use defineObject('companies', ...) without labels and the display properties, or name the custom object differently) (docs: errors/E_STANDARD_OBJECT.md)
+```