kalup 0.1.0

package/docs/errors/E_BLUEPRINT_ADDED.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_ADDED
+
+`kalup add` was given a blueprint the project already has. Exit 1. Nothing was written.
+
+## When
+
+`kalup/blueprints.lock.json` lists each blueprint once, by name. Adding it again would lose its merge base and the conflicts the lock holds, so `add` refuses and points at `kalup blueprint upgrade`, which merges the new version with what the client changed.
+
+## Fix
+
+Run the command in the fix, `kalup blueprint upgrade <name> <source>`, to move to the version you gave.
+
+## Example
+
+```
+E_BLUEPRINT_ADDED: acme/renewals is already in kalup/blueprints.lock.json, at version 1.0.0. Nothing was written. (fix: to move to this version, run kalup blueprint upgrade acme/renewals blueprints/renewals-2.0.0.json) (docs: errors/E_BLUEPRINT_ADDED.md)
+```

package/docs/errors/E_BLUEPRINT_COLLISION.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_COLLISION
+
+A blueprint resource has the address of a config resource with another definition. Exit 1. Nothing was written.
+
+## When
+
+`kalup add` compares each resource of the blueprint, after the prefix, with config. The same definition and binding is recorded under the blueprint; any differing unit (a label, an option, the key, the codec, a lifecycle field) is a collision, listed with both values. So is a `.managed(false)` entry: a blueprint resource is managed. An address another blueprint provides collides even when alike, for `add` and for a resource new in `kalup blueprint upgrade`.
+
+## Fix
+
+Make config match the blueprint, take the resource out of config, or add the blueprint with `--prefix` so its names do not collide. HubSpot names are permanent, so choose the prefix with care. When another blueprint provides the resource, use `--prefix`, or your own copy of the blueprint without it.
+
+## Example
+
+```
+E_BLUEPRINT_COLLISION: property:deals/renewal_date is in config with another definition: label (config "Contract end", blueprint "Renewal date"). Nothing was written. (fix: make config match the blueprint, remove the resource from config, or add the blueprint with --prefix so its names do not collide) (docs: errors/E_BLUEPRINT_COLLISION.md)
+```

package/docs/errors/E_BLUEPRINT_INTEGRITY.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_INTEGRITY
+
+A blueprint version now has other bytes than the ones Kalup recorded. Exit 1. Nothing was written.
+
+## When
+
+`sources` in `kalup/blueprints.lock.json` remembers the hash of every source and version ever added or upgraded to. When the same source serves the same version with a different hash, someone changed a published version in place, by mistake or on purpose. Kalup refuses to use it, and names both hashes. `kalup blueprint upgrade` refuses the same version with another hash than the lock holds, from any source.
+
+## Fix
+
+The same version must hold the same bytes. Ask the author why it changed, and use a new version number for new content. Do not edit the lock to make the hashes match.
+
+## Example
+
+```
+E_BLUEPRINT_INTEGRITY: blueprints/renewals-1.0.0.json version 1.0.0 was recorded with sha256:3f1c…, and the source now serves sha256:9a0e…. Nothing was written. (fix: the same version must hold the same bytes: ask the author why it changed, and use a new version number for new content) (docs: errors/E_BLUEPRINT_INTEGRITY.md)
+```

package/docs/errors/E_BLUEPRINT_LOCK.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_LOCK
+
+`kalup/blueprints.lock.json` is not a valid lock. Exit 3.
+
+## When
+
+The loader reads the lock to add provenance to the resources each blueprint provides, so every command that loads the project checks it: a `lockVersion` of 1 (another one was written by another version of Kalup), JSON that matches `blueprints-lock-1.schema.json`, each stored original at the path its name and version fix, each source and version listed under `sources` with the same hash, one blueprint per local address, and each held conflict on an address the blueprint lists. `kalup add` and `kalup blueprint upgrade` write the lock; a hand edit or a bad merge breaks it.
+
+## Fix
+
+For another lock version, use the version of Kalup that wrote it, or a newer one. Otherwise restore the file from git, for example `git checkout -- kalup/blueprints.lock.json`. After a merge conflict, take one side whole and run `kalup blueprint upgrade` again rather than editing the JSON.
+
+## Example
+
+```
+kalup/blueprints.lock.json: E_BLUEPRINT_LOCK: sources does not record blueprints/renewals-1.0.0.json@1.0.0 with the hash of acme/renewals (fix: restore kalup/blueprints.lock.json from git: kalup add and kalup blueprint upgrade write it, never a person) (docs: errors/E_BLUEPRINT_LOCK.md)
+```

package/docs/errors/E_BLUEPRINT_ORIGINAL.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_ORIGINAL
+
+The stored original of a blueprint is missing, was changed, or is another blueprint version. Exit 1. Nothing was written.
+
+## When
+
+`kalup blueprint upgrade` merges three ways, with the version the project last added or upgraded to as the base. Kalup keeps that version's bytes under `kalup/.blueprints/` and checks them against the hash in `kalup/blueprints.lock.json`. A deleted file, an edit, a reformat by another tool, a bad merge or git converting line endings (`core.autocrlf`) breaks the base, and a merge against it would misreport what the client changed.
+
+## Fix
+
+Restore the file from git, for example `git checkout -- kalup/.blueprints/acme--renewals@1.0.0.json`, then run the upgrade again. Another blueprint version needs the Kalup that wrote it, or newer. Keep `kalup/.blueprints/` out of formatters and commit it with the lock. `kalup add` writes `kalup/.blueprints/** -text` to `.gitattributes` so git keeps the bytes; if that line is missing, add it back, commit, and check the file out again.
+
+## Example
+
+```
+E_BLUEPRINT_ORIGINAL: the stored original of acme/renewals 1.0.0, kalup/.blueprints/acme--renewals@1.0.0.json, does not match the hash in kalup/blueprints.lock.json; upgrade merges against it. Nothing was written. (fix: restore it from git, for example git checkout -- kalup/.blueprints/acme--renewals@1.0.0.json, then run kalup blueprint upgrade again) (docs: errors/E_BLUEPRINT_ORIGINAL.md)
+```

package/docs/errors/E_BLUEPRINT_REF.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_REF
+
+A blueprint property is in a group that neither the blueprint nor config holds. Exit 1. Nothing was written.
+
+## When
+
+A blueprint may put its properties in a group the project provides instead of one of its own. `kalup add` and `kalup blueprint upgrade` check that each such group is a group of the same object in config, so the written property does not name a missing group.
+
+## Fix
+
+Add the group to the object in config, for example `contract: { label: 'Contract' }` under `groups`, or pull it from a portal that has it, then run the command again.
+
+## Example
+
+```
+E_BLUEPRINT_REF: property:deals/renewal_date is in group group:deals/contract, which is neither in the blueprint nor in config. Nothing was written. (fix: add contract: { label: '...' } to the groups of deals in config, then run the command again) (docs: errors/E_BLUEPRINT_REF.md)
+```

package/docs/errors/E_BLUEPRINT_REQUIRES.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_REQUIRES
+
+A blueprint needs a custom object config does not define. Exit 1. Nothing was written.
+
+## When
+
+A blueprint's resources and its `requires` list name objects. A standard object (contacts, companies, deals, tickets and the rest) is always there, and `kalup add` adds it to `objects` in `kalup.config.ts` when missing. A custom object has to exist in the portal and in config first: Kalup does not create custom object schemas, so the blueprint's properties would have nowhere to go.
+
+## Fix
+
+Create the custom object in HubSpot, add its key under `objects` in `kalup.config.ts`, run `kalup pull` to write its object file, then run the command again.
+
+## Example
+
+```
+E_BLUEPRINT_REQUIRES: the blueprint needs the custom object vineyard, which config does not define. Nothing was written. (fix: add vineyard: {} under objects in kalup.config.ts and run kalup pull to write its object file, or create the object in HubSpot first) (docs: errors/E_BLUEPRINT_REQUIRES.md)
+```

package/docs/errors/E_BLUEPRINT_SCHEMA.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_SCHEMA
+
+A blueprint is not a valid `blueprint/1` document. Exit 1. Nothing was written.
+
+## When
+
+`kalup add` and `kalup blueprint upgrade` parse the source as JSON, never as code. Another `blueprintVersion` is refused first. Then they check `blueprint-1.schema.json` and the rules the schema cannot state: addresses of the form `group:<object>/<name>` or `property:<object>/<name>` that match their type, plain names that never start with `hs_` (a group `$ref` names a plain group too), unique option values, aliases that name an option, and a codec that fits the HubSpot type and field type. Text that is not JSON or UTF-8 is refused, and so are names a prefix makes invalid. Each issue names its path; quoted text is sanitized.
+
+## Fix
+
+A blueprint is third-party data: ask its author for a version that passes, `blueprint/1` for another version. If you maintain the blueprint, fix the field the issue names. For a prefix problem, pass another `--prefix`.
+
+## Example
+
+```
+E_BLUEPRINT_SCHEMA: property name 'hs_renewal_flag' starts with hs_, the prefix HubSpot uses for its own names (fix: a blueprint is third-party data: ask its author for a version that passes, or fix your own copy of the file) (docs: errors/E_BLUEPRINT_SCHEMA.md)
+```

package/docs/errors/E_BLUEPRINT_SOURCE.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_SOURCE
+
+A blueprint source could not be read. Exit 1. Nothing was written.
+
+## When
+
+A source is a path to a JSON file, relative to the current directory, or an `https://` URL. Kalup refuses anything else (an `http://` URL, a registry name), a missing file, a URL that answers with an error status or does not answer within 30 seconds, a redirect to a location that is not https, and a file or body over 1 MB. It also refuses a URL with credentials or a query string: the lock records the source. `kalup blueprint upgrade` also refuses a source that holds another blueprint than the name it was given. A URL fetch sends no key and no header but `accept`.
+
+## Fix
+
+Pass a path to the blueprint file, or an https URL that serves it. For a private URL, download the file and pass its path. Check the name against `kalup/blueprints.lock.json` for an upgrade.
+
+## Example
+
+```
+E_BLUEPRINT_SOURCE: http://blueprints.example.com/renewals.json is not an https URL; Kalup fetches blueprints over https only (fix: pass a path to a blueprint JSON file, or an https:// URL that serves one) (docs: errors/E_BLUEPRINT_SOURCE.md)
+```

package/docs/errors/E_BLUEPRINT_UNKNOWN.md

@@ -0,0 +1,17 @@
+# E_BLUEPRINT_UNKNOWN
+
+`kalup blueprint upgrade` was given a name the lock does not hold. Exit 1. Nothing was written.
+
+## When
+
+Upgrade merges against the stored original of a blueprint the project added. The name must be one `kalup/blueprints.lock.json` lists; the message names them.
+
+## Fix
+
+Use a name the lock lists, or add the blueprint first with `kalup add <source>`.
+
+## Example
+
+```
+E_BLUEPRINT_UNKNOWN: acme/billing is not in kalup/blueprints.lock.json, which lists acme/renewals (fix: add it first with kalup add <source>, or name a blueprint the lock lists) (docs: errors/E_BLUEPRINT_UNKNOWN.md)
+```

package/docs/errors/E_BUDGET.md

@@ -0,0 +1,17 @@
+# E_BUDGET
+
+The apply would use more than half of the API calls HubSpot reports left today. Exit 1. Nothing was written.
+
+## When
+
+After it reads the portal, `kalup apply` estimates its calls: the reads it made, plus three per step that writes (a read before it, the write, a read-back). When HubSpot reports a daily figure and the estimate is more than half of it, apply stops, so that other apps on the portal keep room. With no daily figure it warns `W_RATE_HEADERS` and goes on.
+
+## Fix
+
+Apply after the daily limit resets at midnight in the portal's time zone, or split the change into smaller plans.
+
+## Example
+
+```
+E_BUDGET: plan pl_7f3a1c07b2e4 needs about 640 API calls, more than half of the 1100 HubSpot reports left today. Nothing was written. (fix: apply after the daily limit resets, or split the change into smaller plans) (docs: errors/E_BUDGET.md)
+```

package/docs/errors/E_CANCELLED.md

@@ -0,0 +1,21 @@
+# E_CANCELLED
+
+The person at the terminal cancelled, or a signal stopped `kalup apply`. Exit 1, or 5 when apply had already written.
+
+## When
+
+`pull`, `plan`, `snapshot` or `apply` asked which target to use, and got the end of input (Ctrl-D), Ctrl-C, or three answers that were neither a listed number nor a target name. Nothing was read or written.
+
+`kalup apply` asked the person to type the target name, and the number of destructive steps when there are any, and the answer did not match or the input ended. Nothing was written.
+
+SIGINT or SIGTERM during `kalup apply`: it let the request in flight settle, sent nothing more, saved state and released the lock. A second signal stops at once.
+
+## Fix
+
+Run the command again and answer, or pass `--target <name>`. Set `defaultTarget` in `kalup.config.ts` to stop the question. After a stopped apply, run `kalup plan` to see what is left.
+
+## Example
+
+```
+E_CANCELLED: Not applied: the answer was not the target name. Nothing was written. (docs: errors/E_CANCELLED.md)
+```

package/docs/errors/E_CONFIG_EXISTS.md

@@ -0,0 +1,17 @@
+# E_CONFIG_EXISTS
+
+`init` refused to run because `kalup.config.ts` already exists in the working directory. Exit 1. Nothing was written.
+
+## When
+
+`init` runs once per project. It never overwrites a config.
+
+## Fix
+
+To refresh the files from the portal, run `npx --no-install kalup pull --target <name>`. To start over, remove `kalup.config.ts` first.
+
+## Example
+
+```
+kalup.config.ts: E_CONFIG_EXISTS: kalup.config.ts already exists in /work/orchard-crm (fix: this is a kalup project already: run npx kalup pull --target <name>, or remove the file to start over) (docs: errors/E_CONFIG_EXISTS.md)
+```

package/docs/errors/E_DAILY_LIMIT.md

@@ -0,0 +1,17 @@
+# E_DAILY_LIMIT
+
+The portal has used its daily HubSpot API limit. Exit 1.
+
+## When
+
+HubSpot answered 429 with the `DAILY` policy. Kalup does not retry it. Other apps on the portal share the same daily limit. On a Limits Tracking reading, `plan` records it as that reading's issue in `preflight.limits` and carries on. `kalup apply` stops before the write HubSpot refused, so that step and the rest do not run; exit 5 when earlier steps wrote.
+
+## Fix
+
+Run the command again after the time in the fix. Kalup takes it as the next midnight in the portal's time zone.
+
+## Example
+
+```
+E_DAILY_LIMIT: The portal has used its daily API limit. (fix: Try again after 2026-09-23T22:00:00.000Z.) (docs: errors/E_DAILY_LIMIT.md)
+```

package/docs/errors/E_DEFAULT_TARGET.md

@@ -0,0 +1,17 @@
+# E_DEFAULT_TARGET
+
+`defaultTarget` in `kalup.config.ts` names a target that `targets` does not declare. Exit 3.
+
+## When
+
+`validate` reports it, and so does every command that loads the config, with or without `--target`, before anything is read. The name must match a key under `targets` exactly.
+
+## Fix
+
+Set `defaultTarget` to a declared name (the fix lists them), declare the target, or remove `defaultTarget`. A project with one target needs no default.
+
+## Example
+
+```
+kalup.config.ts:5: E_DEFAULT_TARGET: defaultTarget 'staging' is not a declared target (fix: use one of sandbox, production, or remove defaultTarget) (docs: errors/E_DEFAULT_TARGET.md)
+```

package/docs/errors/E_DUPLICATE_ADDRESS.md

@@ -0,0 +1,17 @@
+# E_DUPLICATE_ADDRESS
+
+One address is defined twice, in two files or in two exports. Exit 3.
+
+## When
+
+Every group, property and custom object has one address, such as `group:companies/orchard`. Two exports of the same object that both declare the group `orchard`, or the same property in two files, give that address twice. The issue names both places.
+
+## Fix
+
+Keep one definition and remove the other, or give one of them another internal name.
+
+## Example
+
+```
+kalup/objects/companies.ts:15: E_DUPLICATE_ADDRESS: group:companies/orchard is defined twice: kalup/objects/companies.ts:5 and kalup/objects/companies.ts:15 (fix: remove or rename one of the two definitions) (docs: errors/E_DUPLICATE_ADDRESS.md)
+```

package/docs/errors/E_DUPLICATE_ALIAS.md

@@ -0,0 +1,24 @@
+# E_DUPLICATE_ALIAS
+
+Two options of one enum read as the same alias in the app. Exit 3.
+
+## When
+
+Every option has an alias: its `as`, or its `value` when it has no `as`. Two options with the same alias would make `get` return one name for two stored values, and `set` could only write one of them. An `as` equal to another option's value counts, when that option has no `as` of its own. The app throws the same error when the builder runs.
+
+## Fix
+
+Give one of the two options a different `as`. Swapping names is fine: `a` read as `b` and `b` read as `a` is still one alias per value.
+
+## Example
+
+```ts
+options: [
+  { value: 'CLAY', label: 'Clay', as: 'clay' },
+  { value: 'clay', label: 'Clay (old)' },
+],
+```
+
+```
+kalup/objects/companies.ts:14: E_DUPLICATE_ALIAS: options 'CLAY' and 'clay' share the alias 'clay' (fix: give one of them another as; an option without as uses its value as the alias) (docs: errors/E_DUPLICATE_ALIAS.md)
+```

package/docs/errors/E_DUPLICATE_KEY.md

@@ -0,0 +1,24 @@
+# E_DUPLICATE_KEY
+
+A name is used twice where it must be unique. Exit 3.
+
+## When
+
+The same key twice in one object literal, the same export name twice in one file, or one internal name under two keys of one export.
+
+## Fix
+
+Remove one of the two entries, or rename it.
+
+## Example
+
+```ts
+properties: {
+  plotCount: p.number('plot_count'),
+  plotTotal: p.number('plot_count'),
+},
+```
+
+```
+kalup/objects/companies.ts:9: E_DUPLICATE_KEY: internal name 'plot_count' is used by two keys of Company: 'plotCount' and 'plotTotal' (fix: remove or rename one of the two entries) (docs: errors/E_DUPLICATE_KEY.md)
+```

package/docs/errors/E_DUPLICATE_OPTION.md

@@ -0,0 +1,25 @@
+# E_DUPLICATE_OPTION
+
+An enum lists the same option value twice. Exit 3.
+
+## When
+
+Two entries in `options` of a `p.enum` or `p.multiEnum` have the same `value`, in a full definition or in an options-only reference. HubSpot stores one value per option, and the app could not tell the two apart. The app throws the same error when the builder runs.
+
+## Fix
+
+Remove one of the two options. To show one stored value under another name in the app, give it an `as`.
+
+## Example
+
+```ts
+options: [
+  { value: 'clay', label: 'Clay' },
+  { value: 'loam', label: 'Loam' },
+  { value: 'clay', label: 'Heavy clay' },
+],
+```
+
+```
+kalup/objects/companies.ts:14: E_DUPLICATE_OPTION: option value 'clay' is listed twice (fix: remove one of the two options) (docs: errors/E_DUPLICATE_OPTION.md)
+```

package/docs/errors/E_DUPLICATE_PORTAL.md

@@ -0,0 +1,24 @@
+# E_DUPLICATE_PORTAL
+
+Two targets pin the same portal. Exit 3.
+
+## When
+
+`validate` and every command that validates first check that no two targets in `kalup.config.ts` have the same `portalId`. Two names for one portal could carry different policies, and the less protected name would get around the stricter one. The issue points at the later target's `portalId` and names the earlier target.
+
+## Fix
+
+Keep one target per portal: remove one of the two, and move any settings you need to the one you keep.
+
+## Example
+
+```ts
+targets: {
+  sandbox: { portalId: 1111111 },
+  qa: { portalId: 1111111 },
+},
+```
+
+```
+kalup.config.ts:6: E_DUPLICATE_PORTAL: target 'qa' pins portal 1111111, which target 'sandbox' pins too (fix: each portal has one target; remove or rename one of sandbox, qa) (docs: errors/E_DUPLICATE_PORTAL.md)
+```

package/docs/errors/E_FIRST_PULL.md

@@ -0,0 +1,18 @@
+# E_FIRST_PULL
+
+`init` wrote the project files, but the first pull failed. The exit code is the pull's.
+
+## When
+
+`init` checks the portal, writes `kalup.config.ts`, `.gitignore`, `AGENTS.md`, `CLAUDE.md` and, when it finds a formatter, its ignore entries, then runs a pull. The issue before this one says why the pull failed.
+
+## Fix
+
+Fix that issue, then run the pull yourself. Do not run `init` again: the config exists now, so it would stop with `E_CONFIG_EXISTS`.
+
+## Example
+
+```
+E_AUTH: HubSpot rejected the key (401). (fix: Check that the key is valid and not expired. It needs the scope crm.schemas.companies.read.) (docs: errors/E_AUTH.md)
+E_FIRST_PULL: The project files are written, but the first pull failed. (fix: fix the issue above, then run npx kalup pull --target sandbox) (docs: errors/E_FIRST_PULL.md)
+```

package/docs/errors/E_HS_PREFIX.md

@@ -0,0 +1,21 @@
+# E_HS_PREFIX
+
+A managed property's internal name starts with `hs_`. Exit 3.
+
+## When
+
+HubSpot uses `hs_` for its own properties. Kalup never claims that prefix for a property it would own. Whether HubSpot refuses such a create is not confirmed. A reference (no definition) may carry the prefix.
+
+## Fix
+
+Give the property another internal name, or drop `label`, `group` and `fieldType` so it refers to HubSpot's property.
+
+## Example
+
+```ts
+plotCount: p.number('hs_plot_count', { label: 'Plot count', group: 'orchard', fieldType: 'number' }),
+```
+
+```
+kalup/objects/companies.ts:9: E_HS_PREFIX: 'hs_plot_count' 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_HTTP.md

@@ -0,0 +1,17 @@
+# E_HTTP
+
+HubSpot returned an error Kalup has no other code for. Exit 1.
+
+## When
+
+A 400, a 404, a 5xx that three retries did not clear, or a success whose body is not JSON (often a proxy's HTML page). The issue holds the status, the method, the path and HubSpot's message when it sent one. In `apply`, a refusal whose reason HubSpot names and Kalup knows says it in plain words: a property in use, a group that still holds properties, or a property name that exists.
+
+## Fix
+
+A 5xx is usually temporary: run the command again later. A 404 on a properties list means the object does not exist in that portal. A body that is not JSON points at a proxy between you and HubSpot.
+
+## Example
+
+```
+E_HTTP: HubSpot returned 503 for GET /crm/properties/2026-09/companies. (docs: errors/E_HTTP.md)
+```

package/docs/errors/E_INCOMPLETE.md

@@ -0,0 +1,23 @@
+# E_INCOMPLETE
+
+A command could not read all it needed. Exit 1, whatever the flags: with or without `--check`, `--exit-code` or `--discover`.
+
+## When
+
+In `pull`, a properties, groups or custom object schemas list answered 403 (`E_SCOPE`). The object behind it was skipped: nothing on it was compared, reported missing or written. A refused schemas list skips every custom object. The objects read in full are still merged and, without `--check`, written.
+
+In `compare`, a side did not read an object either side names (a 403, a snapshot taken before config named it, or a key `objects` lacks), or an address is unknown (a `lookup` override, or whitespace in its group name, `W_UNADDRESSABLE_NAME`). `data` still holds the comparison, with `complete: false` and `ok: false`.
+
+In `apply`, the write key could not read a list (403) of an object the plan changes. Apply never writes on a partial read. In `state rebuild --write` and `target rebind`, the read missed something config names: a new state file would drop every entry there, created origins and agreed values included, so nothing was written and no prompt was shown. The read-only `state rebuild` still reports.
+
+It comes last and names what was not read. It is never clean, so a CI job running `--exit-code` fails on it.
+
+## Fix
+
+Add the scopes the fix names to the key in HubSpot, its object key to `objects` in `kalup.config.ts`, or rename the portal group to a name without spaces, then read the portal again (a new snapshot, when a snapshot side missed it). To leave an object out on purpose, remove its key from `objects` and its object file.
+
+## Example
+
+```
+E_INCOMPLETE: pull did not read everything in scope: the properties list of harvest. Nothing there was compared or written. (fix: add the scope crm.schemas.custom.read to the key, then run npx kalup pull --target sandbox) (docs: errors/E_INCOMPLETE.md)
+```

package/docs/errors/E_IR_SCHEMA.md

@@ -0,0 +1,18 @@
+# E_IR_SCHEMA
+
+The IR that `kalup ir` derived does not match the `ir/1` JSON Schema. Exit 3.
+
+## When
+
+`kalup ir` and `kalup ir --check` check the IR against the schema. `configPath` is a path in the IR, such as `targets.sandbox.portalId`, not a place in a file. From config files it comes with a validate issue that explains it. `compare` and `docs` check a snapshot file the same way; the issue then names the file, and a fix to that file, or a new snapshot, clears it.
+
+## Fix
+
+Fix the other issues first; this one goes with them. If it is the only issue left, it is a bug in Kalup: report it with the issue text.
+
+## Example
+
+```
+kalup.config.ts:9: 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)
+E_IR_SCHEMA: expected at least 1 (docs: errors/E_IR_SCHEMA.md)
+```

package/docs/errors/E_JOURNAL_WRITE.md

@@ -0,0 +1,17 @@
+# E_JOURNAL_WRITE
+
+`kalup apply` could not write a line of its journal. Exit 1, or 5 when a write had already been sent.
+
+## When
+
+Apply records every request in `.kalup/journal/portal-<id>/` and flushes the line to disk before the next request goes. When a line cannot be written (a full disk, a directory without write permission), apply sends no further request. It still saves state for what it verified and records the outcome.
+
+## Fix
+
+Make the journal directory writable and check the disk has room. Then run `kalup plan`: it compares the portal with the state that was kept and shows what is left.
+
+## Example
+
+```
+E_JOURNAL_WRITE: the journal .kalup/journal/portal-2222222/pl_7f3a1c07b2e4-20260924T100000000Z.jsonl could not be written (ENOSPC: no space left on device, write), so the run stopped before its next request (fix: make the journal directory writable, then run kalup plan to see what the portal holds and what is left) (docs: errors/E_JOURNAL_WRITE.md)
+```

package/docs/errors/E_KEY_COLLISION.md

@@ -0,0 +1,22 @@
+# E_KEY_COLLISION
+
+Two properties of one object have the same key. Exit 3.
+
+## When
+
+The app reads every property of an object through one type, so keys must differ. Within one export a repeated key is `E_DUPLICATE_KEY`; this code is for two exports of the same object.
+
+## Fix
+
+Rename one of the keys. The internal name stays, so nothing changes in HubSpot.
+
+## Example
+
+```ts
+export const Company = defineObject('companies', { properties: { owner: p.string('orch_owner') } })
+export const CompanyExtra = defineObject('companies', { properties: { owner: p.string('orch_owner_name') } })
+```
+
+```
+kalup/objects/companies.ts:39: E_KEY_COLLISION: key 'owner' is used by two properties of companies: property:companies/orch_owner and property:companies/orch_owner_name (fix: rename one of the two keys) (docs: errors/E_KEY_COLLISION.md)
+```

package/docs/errors/E_KEY_INVALID.md

@@ -0,0 +1,19 @@
+# E_KEY_INVALID
+
+The variable that holds a key has a value no request header can carry. Exit 1. Nothing was sent.
+
+## When
+
+Kalup sends the key in the `Authorization` header. A value with a line break, a carriage return, a NUL or another control character, or a character outside Latin-1, cannot go into a header, and the HTTP client would quote the whole value in its error. Kalup checks the value first, for the read key and the write key, from the process environment or from `.env`. The message names the variable and never the value.
+
+This usually means the key was pasted across two lines, or with a stray character from a chat or a document.
+
+## Fix
+
+A person sets the variable again, with the key alone on one line, copied from HubSpot. Never paste the key into a chat, a log or a commit.
+
+## Example
+
+```
+E_KEY_INVALID: The value of HUBSPOT_SANDBOX_KEY holds a line break or another character a request header cannot carry, so it was not sent. (fix: Set HUBSPOT_SANDBOX_KEY again with the key alone on one line, as HubSpot shows it.) (docs: errors/E_KEY_INVALID.md)
+```

package/docs/errors/E_LIFECYCLE.md

@@ -0,0 +1,23 @@
+# E_LIFECYCLE
+
+A `lifecycle` block contradicts itself. Exit 3.
+
+## When
+
+`removedOptions` names a value that is still in `options`, or `ignoreChanges` names something other than `label`, `group`, `fieldType`, `description`, `options`, `hasUniqueValue` or `formField`.
+
+## Fix
+
+Take the value out of `options` or out of `removedOptions`. Spell `ignoreChanges` entries as definition field names.
+
+## Example
+
+```ts
+options: [{ value: 'clay', label: 'Clay' }, { value: 'loam', label: 'Loam' }],
+lifecycle: { removedOptions: ['clay'], ignoreChanges: ['colour'] },
+```
+
+```
+kalup/objects/companies.ts:14: E_LIFECYCLE: removedOptions names 'clay', which is still in options (fix: remove it from options or from removedOptions) (docs: errors/E_LIFECYCLE.md)
+kalup/objects/companies.ts:14: E_LIFECYCLE: ignoreChanges names 'colour', which is not a definition field (fix: use one of label, group, fieldType, description, options, hasUniqueValue, formField) (docs: errors/E_LIFECYCLE.md)
+```

package/docs/errors/E_LOCKED.md

@@ -0,0 +1,17 @@
+# E_LOCKED
+
+Another Kalup command holds the lock of this portal. Exit 1. Kalup does not wait.
+
+## When
+
+Commands that write to a portal or its state take a lock named by the portal ID before they read state, and hold it until state is saved: `apply`, `state rebuild --write`, `target rebind`, and `pull` and `init` whenever they may record bases (not with `--check` or `--discover`). The lock is a file in `~/.kalup/locks` (or `KALUP_LOCK_DIR`) that names the holder's command, plan, host, process ID and start time. It keeps apart the writers of one user on one machine, across clones, worktrees and target names. Kalup never takes a lock over, even when its holder has ended: a command that crashed or was killed leaves its lock behind until a person deletes it.
+
+## Fix
+
+Wait for the other command to finish, then run yours again. If no Kalup command is running on the host the message names, the lock was left behind: delete the file the fix names, then run yours again. Never delete it while that command runs.
+
+## Example
+
+```
+E_LOCKED: portal 2222222 is locked by kalup apply for plan pl_7f3a1c07b2e4 on build-agent-7, pid 4242, since 2026-09-24T10:00:00.000Z. (fix: wait for it to finish; delete /home/dana/.kalup/locks/portal-2222222.lock only when no kalup command is running on build-agent-7) (docs: errors/E_LOCKED.md)
+```

package/docs/errors/E_LOCK_DIR.md

@@ -0,0 +1,17 @@
+# E_LOCK_DIR
+
+The lock directory cannot be written. Exit 1. No write was sent.
+
+## When
+
+Commands that write to a portal lock it with a file in a per-user directory: `~/.kalup/locks`, or `KALUP_LOCK_DIR` when it is set. Kalup could not create that directory or a file in it (no permission, a read-only file system, or a path under a file). It never falls back to a directory in the project, because then two clones of one project would not see each other's locks.
+
+## Fix
+
+Set `KALUP_LOCK_DIR` to a directory this user can write, outside the project, or fix the permissions of `~/.kalup/locks`. Every Kalup command that writes to the same portal on this machine must use the same directory.
+
+## Example
+
+```
+E_LOCK_DIR: the lock directory /home/dana/.kalup/locks cannot be written (EACCES). (fix: set KALUP_LOCK_DIR to a directory this user can write, outside the project) (docs: errors/E_LOCK_DIR.md)
+```