kalup 0.1.1 → 0.2.0

package/docs/errors/E_BLUEPRINT_INTEGRITY.md

@@ -4,7 +4,7 @@ A blueprint version now has other bytes than the ones Kalup recorded. Exit 1. No
 
 ## 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.
+`sources` in `hubspot/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
 

package/docs/errors/E_BLUEPRINT_LOCK.md

@@ -1,6 +1,6 @@
 # E_BLUEPRINT_LOCK
 
-`kalup/blueprints.lock.json` is not a valid lock. Exit 3.
+`hubspot/blueprints.lock.json` is not a valid lock. Exit 3.
 
 ## When
 
@@ -8,10 +8,10 @@ The loader reads the lock to add provenance to the resources each blueprint prov
 
 ## 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.
+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 -- hubspot/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)
+hubspot/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 hubspot/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

@@ -4,14 +4,14 @@ The stored original of a blueprint is missing, was changed, or is another bluepr
 
 ## 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.
+`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 `hubspot/.blueprints/` and checks them against the hash in `hubspot/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.
+Restore the file from git, for example `git checkout -- hubspot/.blueprints/acme--renewals@1.0.0.json`, then run the upgrade again. Another blueprint version needs the Kalup that wrote it, or newer. Keep `hubspot/.blueprints/` out of formatters and commit it with the lock. `kalup add` writes `hubspot/.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)
+E_BLUEPRINT_ORIGINAL: the stored original of acme/renewals 1.0.0, hubspot/.blueprints/acme--renewals@1.0.0.json, does not match the hash in hubspot/blueprints.lock.json; upgrade merges against it. Nothing was written. (fix: restore it from git, for example git checkout -- hubspot/.blueprints/acme--renewals@1.0.0.json, then run kalup blueprint upgrade again) (docs: errors/E_BLUEPRINT_ORIGINAL.md)
 ```

package/docs/errors/E_BLUEPRINT_SOURCE.md

@@ -8,7 +8,7 @@ A source is a path to a JSON file, relative to the current directory, or an `htt
 
 ## 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.
+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 `hubspot/blueprints.lock.json` for an upgrade.
 
 ## Example
 

package/docs/errors/E_BLUEPRINT_UNKNOWN.md

@@ -4,7 +4,7 @@
 
 ## 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.
+Upgrade merges against the stored original of a blueprint the project added. The name must be one `hubspot/blueprints.lock.json` lists; the message names them.
 
 ## Fix
 
@@ -13,5 +13,5 @@ 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)
+E_BLUEPRINT_UNKNOWN: acme/billing is not in hubspot/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_DEFINITION_FIELD.md

@@ -0,0 +1,29 @@
+# E_DEFINITION_FIELD
+
+A property definition states a field HubSpot would refuse or misread for this property. Exit 3.
+
+## When
+
+`validate` and every command that validates first check the fields that depend on the builder or on each other, as HubSpot does:
+
+- `numberDisplayHint`, `showCurrencySymbol` and `currencyPropertyName` belong to `p.number`, and `textDisplayHint` to `p.string`, `p.stringArray`, `p.json` and `p.phoneNumber`. HubSpot stores them on any property but shows them only on those.
+- `calculationFormula` needs `fieldType: 'calculation_equation'`. Sent with another field type, HubSpot turns the property into a calculation.
+- `currencyPropertyName` needs `showCurrencySymbol: true`. HubSpot refuses it otherwise (`ONLY_CURRENCY_PROPERTIES_CAN_SPECIFY_CURRENCY`).
+- `displayOrder` is an integer from -1 up.
+- `p.owner` takes no `options`: HubSpot fills them with the account's users and refuses a create that sends any.
+
+A target's definition override that breaks one of these rules is `E_OVERRIDE_DEFINITION`.
+
+## Fix
+
+Change or remove the field the message names, or change the builder.
+
+## Example
+
+```ts
+share: p.string('pick_share', { label: 'Pick share', group: 'orchard', fieldType: 'text', numberDisplayHint: 'percentage' }),
+```
+
+```
+hubspot/objects/companies.ts:14: E_DEFINITION_FIELD: numberDisplayHint is for p.number, not p.string (fix: remove numberDisplayHint) (docs: errors/E_DEFINITION_FIELD.md)
+```

package/docs/errors/E_DIR_AMBIGUOUS.md

@@ -0,0 +1,17 @@
+# E_DIR_AMBIGUOUS
+
+Both `hubspot/` and the 0.1 folder `kalup/` hold .ts files, and `kalup.config.ts` does not say which one holds the object files. Exit 3. Nothing was read or written.
+
+## When
+
+Without `dir` in `kalup.config.ts`, Kalup reads `hubspot/`, or a 0.1 project's `kalup/` while `hubspot/` holds no .ts file (`W_LEGACY_DIR`). When both hold .ts files, such as a half-done move or a HubSpot developer project in `hubspot/`, Kalup does not guess: reading the wrong folder would make everything in the other look removed from config.
+
+## Fix
+
+Add `dir: 'kalup'` to `kalup.config.ts` to keep the 0.1 folder, or `dir: 'hubspot'` when the object files are there. Then move or remove the other folder's copy of the object files.
+
+## Example
+
+```
+kalup.config.ts: E_DIR_AMBIGUOUS: both hubspot/ and kalup/ hold .ts files, and kalup.config.ts does not say which one holds the object files (fix: add dir: 'kalup' to kalup.config.ts to keep the 0.1 folder, or dir: 'hubspot' when the object files are there) (docs: errors/E_DIR_AMBIGUOUS.md)
+```

package/docs/errors/E_DIR_IN_USE.md

@@ -0,0 +1,17 @@
+# E_DIR_IN_USE
+
+`init` refused to run because the folder of object files holds a .ts file that is not Kalup's, or is a file. Exit 1. Nothing was written.
+
+## When
+
+The folder `--dir` names (`hubspot/` without it) belongs to Kalup alone: every command reads each .ts file in it as an object file, `pull` rewrites its `index.ts`, and `init` takes the folder out of the formatter's checks. A folder such as `lib/config` that already holds the app's own modules cannot be it. Object files, `removed.ts` and the `index.ts` barrel from an earlier `init` or `pull` are Kalup's, so `init` runs again after `kalup.config.ts` is removed.
+
+## Fix
+
+Pass `--dir` with a folder of its own, such as `lib/config/hubspot`, or move the file out of the folder.
+
+## Example
+
+```
+lib/config/index.ts: E_DIR_IN_USE: lib/config/index.ts is not a kalup file, and lib/config/ must hold kalup's files only. Nothing was written. (fix: pass --dir with a folder of its own, such as lib/config/hubspot) (docs: errors/E_DIR_IN_USE.md)
+```

package/docs/errors/E_DUPLICATE_ADDRESS.md

@@ -13,5 +13,5 @@ Keep one definition and remove the other, or give one of them another internal n
 ## 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)
+hubspot/objects/companies.ts:15: E_DUPLICATE_ADDRESS: group:companies/orchard is defined twice: hubspot/objects/companies.ts:5 and hubspot/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

@@ -20,5 +20,5 @@ options: [
 ```
 
 ```
-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)
+hubspot/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

@@ -20,5 +20,5 @@ properties: {
 ```
 
 ```
-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)
+hubspot/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

@@ -21,5 +21,5 @@ options: [
 ```
 
 ```
-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)
+hubspot/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_HS_PREFIX.md

@@ -17,5 +17,5 @@ plotCount: p.number('hs_plot_count', { label: 'Plot count', group: 'orchard', fi
 ```
 
 ```
-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)
+hubspot/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_KEY_COLLISION.md

@@ -18,5 +18,5 @@ export const CompanyExtra = defineObject('companies', { properties: { owner: p.s
 ```
 
 ```
-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)
+hubspot/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_LIFECYCLE.md

@@ -4,7 +4,7 @@ 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`.
+`removedOptions` names a value that is still in `options`, or `ignoreChanges` names something other than a definition field: `label`, `group`, `fieldType`, `description`, `options`, `hasUniqueValue`, `formField`, `hidden`, `displayOrder`, `numberDisplayHint`, `showCurrencySymbol`, `currencyPropertyName`, `textDisplayHint`, `calculationFormula` or `dataSensitivity`.
 
 ## Fix
 
@@ -18,6 +18,6 @@ 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)
+hubspot/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)
+hubspot/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

@@ -4,7 +4,7 @@ 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.
+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` whenever it 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
 

package/docs/errors/E_MISSING_EXPORT.md

@@ -1,17 +1,17 @@
 # E_MISSING_EXPORT
 
-A file under `kalup/` has no `defineObject` or `defineCustomObject` export. Exit 3.
+A file under `hubspot/` 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.
+Kalup reads every `.ts` file in the folder of object files (`hubspot/`, or the folder `dir` in `kalup.config.ts` names) except `index.ts` and `removed.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/`.
+Add the export, or move the file out of `hubspot/`.
 
 ## 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)
+hubspot/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

@@ -4,7 +4,7 @@ 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.
+The variable is `credentials.read.env` of the target, or `HUBSPOT_SERVICE_KEY` when the target has no `credentials`. `init` writes no `credentials`, so a new project 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
 

package/docs/errors/E_NOT_DATA.md

@@ -17,5 +17,5 @@ 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)
+hubspot/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_OVERRIDE_DEFINITION.md

@@ -6,9 +6,9 @@ A target's definition override states something that cannot differ per target. E
 
 `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`.
+- a field other than `label`, `description`, `group`, `fieldType`, `formField`, `options`, `hidden`, `displayOrder`, the display fields and `calculationFormula` on a property, or `label` on a group. `hasUniqueValue` and `dataSensitivity` are 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.
+- 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, or a rule of `E_DEFINITION_FIELD`.
 - an option with `as`. Aliases belong to the app and stay in the shared file.
 
 ## Fix

package/docs/errors/E_PENDING_TARGET.md

@@ -0,0 +1,17 @@
+# E_PENDING_TARGET
+
+The command needs the portal of a target that has no `portalId` yet. Exit 3. Nothing was sent.
+
+## When
+
+`kalup init` without `--portal` writes a pending target: a name and no `portalId`, since init never asks HubSpot. `validate`, `ir`, `fmt`, `rm`, `add` and `docs` work with it. A command that reads or writes the portal (`pull`, `plan`, `apply`, `compare`, `snapshot`, `state rebuild`, `target rebind`) refuses it before any request, because the portal guard has nothing to check the key against. `status` lists it as pending.
+
+## Fix
+
+Set `targets.<name>.portalId` in `kalup.config.ts` to the Hub ID from the HubSpot account menu, then run the command again.
+
+## Example
+
+```
+kalup.config.ts: E_PENDING_TARGET: target production has no portalId yet, so pull cannot check the key against its portal. Nothing was sent. (fix: set targets.production.portalId in kalup.config.ts to the Hub ID from the HubSpot account menu) (docs: errors/E_PENDING_TARGET.md)
+```

package/docs/errors/E_PLAN_DELETE.md

@@ -4,7 +4,7 @@ A saved plan deletes something config does not ask to delete. Exit 1. Nothing wa
 
 ## 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.
+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 `hubspot/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
 

package/docs/errors/E_PORTAL_ID.md

@@ -1,10 +1,10 @@
 # E_PORTAL_ID
 
-A target has no `portalId`, or it is not a positive integer. Exit 3.
+A target's `portalId` is not a positive integer. Exit 3.
 
 ## When
 
-`portalId` pins the target to one portal. Every networked command checks the key against it.
+`portalId` pins the target to one portal. Every networked command checks the key against it. A target with no `portalId` at all is pending (`W_PENDING_TARGET`), not this error.
 
 ## Fix
 

package/docs/errors/E_PREVENT_DESTROY.md

@@ -13,5 +13,5 @@ To delete it after all, remove `preventDestroy` from its lifecycle first, then r
 ## 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)
+hubspot/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

@@ -13,5 +13,5 @@ Check that the project directory is writable and the disk has room, then run the
 ## 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)
+E_PROJECT_WRITE: could not write hubspot/index.ts, hubspot/objects/companies.ts, hubspot/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

@@ -1,17 +1,17 @@
 # E_PROTECTED_SAVED_PLAN
 
-`kalup apply` without a plan file does not run on a protected target. Exit 1. Nothing was written.
+`kalup apply` without a plan file on a protected target needs a person at a terminal. Exit 4, `humanRequired: true`. 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.
+Without a file, `kalup apply` plans the target and applies that plan in one run. On a protected target (`protected: true`, and unless config says otherwise every account but a `DEVELOPER_TEST`, `SANDBOX` or `APP_DEVELOPER` one) a person at a terminal reviews that plan there and confirms it by typing the target name, and the number of destructive steps when there are any. Here nobody can: stdin or stderr is not a terminal, `--json` is set, or `CI` is. Apply stops after the portal guard, before it plans.
 
 ## 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.
+Stop. Hand the command in the fix to the user, who runs it in a terminal and confirms it there. In CI, save the plan with `kalup plan --target <name> --out` for review, and let the reviewed job apply that file. Agents never approve on the user's behalf.
 
 ## 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)
+E_PROTECTED_SAVED_PLAN: target production is protected: applying it without a plan file needs a person at a terminal to confirm the plan, and there is none here (no terminal, --json, or CI set). Nothing was written. (fix: ask the user to run kalup apply --target production in a terminal, where they confirm it; in CI, apply a plan saved with kalup plan --target production --out after review) (docs: errors/E_PROTECTED_SAVED_PLAN.md)
 ```

package/docs/errors/E_PULL_INVALID.md

@@ -16,5 +16,5 @@ Change the portal or the file so the two agree, then pull again. To pull everyth
 
 ```
 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)
+hubspot/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_REFERENCE_DEFINITION.md

@@ -17,5 +17,5 @@ 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)
+hubspot/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

@@ -13,5 +13,5 @@ Move those properties to another group, or remove them first (with `kalup rm` fo
 ## 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)
+hubspot/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_SETTING_VALUE.md

@@ -6,11 +6,13 @@ A setting in kalup.config.ts has a value it does not allow. Exit 3.
 
 `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.
 
+`dir` takes a folder inside the project, relative to `kalup.config.ts`: not an absolute path, not one that leaves the project through `..`, and not the project directory itself.
+
 `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`.
+Write the value the fix suggests, or another allowed one. Remove a name from one of `include` and `exclude`. Write `dir` as a relative path such as `'lib/config/hubspot'`, or remove it to use `hubspot/`.
 
 ## Example
 

package/docs/errors/E_STANDARD_OBJECT.md

@@ -17,5 +17,5 @@ export const Company = defineCustomObject('companies', { labels: { singular: 'Co
 ```
 
 ```
-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)
+hubspot/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)
 ```

package/docs/errors/E_STRICT_WITHOUT_OPTIONS.md

@@ -17,5 +17,5 @@ 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)
+hubspot/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_TARGET_PORTAL_MISMATCH.md

@@ -4,7 +4,7 @@ The key belongs to another portal than the one pinned. Exit 4, `humanRequired: t
 
 ## 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.
+Every command that reads a target first checks account-info with its key; `target rebind` checks 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
 

package/docs/errors/E_TOMBSTONE_ADDRESS.md

@@ -1,10 +1,10 @@
 # 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.
+A key in `hubspot/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.
+Each key in `hubspot/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
 
@@ -19,5 +19,5 @@ export default defineRemoved({
 ```
 
 ```
-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)
+hubspot/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

@@ -1,10 +1,10 @@
 # E_TOMBSTONE_CONFLICT
 
-An address is in `kalup/removed.ts` and still defined in config. Exit 3.
+An address is in `hubspot/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.
+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 `hubspot/removed.ts` by hand and the property or group was left in its object file.
 
 ## Fix
 
@@ -13,5 +13,5 @@ Remove the property or group from its object file. `kalup rm <address>` does bot
 ## 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)
+hubspot/removed.ts:4: E_TOMBSTONE_CONFLICT: property:companies/legacy_score is in hubspot/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

@@ -4,7 +4,7 @@ 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.
+Each builder allows some `fieldType` values. `p.enum` takes `select`, `radio`, `booleancheckbox` or `calculation_equation`, and `p.multiEnum` only `checkbox`. [config.md](../config.md#builders) has the full list.
 
 ## Fix
 
@@ -17,5 +17,5 @@ soil: p.enum('soil_type', { label: 'Soil type', group: 'orchard', fieldType: 'ch
 ```
 
 ```
-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)
+hubspot/objects/companies.ts:14: E_TYPE_FIELDTYPE: fieldType 'checkbox' is not allowed for p.enum (type enumeration) (fix: use one of 'select', 'radio', 'booleancheckbox', 'calculation_equation') (docs: errors/E_TYPE_FIELDTYPE.md)
 ```

package/docs/errors/E_UNKNOWN_BUILDER.md

@@ -4,7 +4,7 @@
 
 ## 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.
+The builders are `p.string`, `p.number`, `p.boolean`, `p.date`, `p.datetime`, `p.enum`, `p.multiEnum`, `p.stringArray`, `p.json`, `p.phoneNumber` and `p.owner`. HubSpot field types such as `text` are not builders.
 
 ## Fix
 
@@ -17,5 +17,5 @@ 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)
+hubspot/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, p.phoneNumber, p.owner) (docs: errors/E_UNKNOWN_BUILDER.md)
 ```

package/docs/errors/E_UNKNOWN_GROUP.md

@@ -17,5 +17,5 @@ plotCount: p.number('plot_count', { label: 'Plot count', group: 'orchard', field
 ```
 
 ```
-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)
+hubspot/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

@@ -1,11 +1,13 @@
 # E_UNKNOWN_INCLUDE
 
-`objects.<key>.include` names properties the portal does not have. Exit 3. Nothing is written.
+`objects.<key>.include` names properties that neither the portal nor the object files 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.
 
+A name the object files define is never unknown: pull reports it as missing in the portal and plan creates it. The files need no `include` for their own properties.
+
 ## Fix
 
 Remove the names, or correct them to the internal names shown in HubSpot's property settings.

package/docs/errors/E_UNSUPPORTED_FILE.md

@@ -1,17 +1,17 @@
 # E_UNSUPPORTED_FILE
 
-A file under `kalup/` that this version does not read. Exit 3.
+A file under `hubspot/` 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.
+Anything under `hubspot/pipelines/`, a `defineConfig` file under `hubspot/`, and a `defineRemoved` file anywhere under `hubspot/` except `hubspot/removed.ts`. With `dir` set in `kalup.config.ts`, the same paths under that folder. 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`.
+Move the file out of `hubspot/` until a release reads it. A `defineConfig` file belongs at the project root as `kalup.config.ts`, and tombstones belong in `hubspot/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)
+hubspot/pipelines/deals.ts:1: E_UNSUPPORTED_FILE: this version does not read pipelines yet (fix: move hubspot/pipelines/deals.ts out of hubspot/ until a release reads it) (docs: errors/E_UNSUPPORTED_FILE.md)
 ```

package/docs/errors/E_USAGE.md

@@ -4,7 +4,7 @@ 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.
+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` with an invalid `--portal` or `--dir`, or with `--target config`, or an `--out` path that is a symbolic link or lies inside `.kalup/` (other than `.kalup/snapshots/` and `.kalup/plans/`), 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
 

package/docs/errors/E_WRITE_IN_READ_MODE.md

@@ -4,7 +4,7 @@ Kalup refused to send a request to a write path through a read client. Exit 1. N
 
 ## 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`).
+Every command that only reads (`pull`, `plan`, `status`, `compare`, `snapshot`) 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