kalup 0.1.0

package/dist/schemas/state-1.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kalup.dev/schemas/state-1.schema.json",
+  "title": "Kalup portal state, version 1",
+  "description": ".kalup/state/portal-<portalId>.json. Describes one verified portal, not the code, and holds no target name. Covered by the compatibility policy (docs/compatibility.md): closed at every level apart from the free-form values in an entry's base and rewrites, so a new field is a new format version. No tokens, record data, unowned fields or unmanaged resources.",
+  "type": "object",
+  "required": ["format", "lineage", "serial", "portalId", "resources"],
+  "properties": {
+    "format": { "const": "kalup.state/1" },
+    "lineage": {
+      "description": "16 lowercase hex characters, new on rebuild and rebind. A plan made against another lineage is refused.",
+      "type": "string",
+      "pattern": "^[0-9a-f]{16}$"
+    },
+    "serial": {
+      "description": "Increases on every save. A plan binds it, and a save compares it.",
+      "type": "integer",
+      "minimum": 0
+    },
+    "portalId": {
+      "description": "The verified portal. Every read checks it against the portal the key belongs to.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "lastApply": {
+      "type": "object",
+      "required": ["planId", "writesHash", "actor", "at", "outcome"],
+      "properties": {
+        "planId": { "type": "string", "pattern": "^pl_[0-9a-f]{12}$" },
+        "writesHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "actor": { "type": "string" },
+        "at": { "type": "string" },
+        "outcome": { "enum": ["running", "done", "partial", "uncertain"] }
+      },
+      "additionalProperties": false
+    },
+    "resources": {
+      "type": "object",
+      "patternProperties": { "^[a-z]+:\\S+$": { "$ref": "#/$defs/resourceState" } },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "resourceState": {
+      "type": "object",
+      "required": ["origin", "id"],
+      "properties": {
+        "origin": {
+          "description": "created and adopted are owned. pulled owns nothing: pull recorded the base of a resource no entry owned, and a plan still adopts it.",
+          "enum": ["created", "adopted", "reference", "pulled"]
+        },
+        "id": {
+          "description": "The portal name the entry owns. It owns the resource only while this equals the name the address resolves to. null for runbook-only types.",
+          "type": ["string", "null"]
+        },
+        "via": { "description": "Transport of the last write.", "type": "string" },
+        "normVersion": { "description": "Normalizer version of the type that wrote base.", "type": "integer" },
+        "base": { "$ref": "#/$defs/base" },
+        "baseHash": { "description": "Replaces base for opaque payloads and runbook types.", "type": "string" },
+        "attested": {
+          "type": "object",
+          "required": ["by", "at"],
+          "properties": { "by": { "type": "string" }, "at": { "type": "string" } },
+          "additionalProperties": false
+        },
+        "rewrites": {
+          "description": "Units whose read-back showed HubSpot storing another value than the one sent, by unit.",
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["sent", "stored"],
+            "properties": { "sent": {}, "stored": {} },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "base": {
+      "description": "Per owned unit, the value config and portal last agreed on; possibly partial. Scalar units by field name. options: a map keyed by option value whose members hold the agreed label, hidden and description; a member with no fields means only its membership is agreed. optionsOrder: the agreed order of the members both sides held.",
+      "type": "object",
+      "properties": {
+        "options": { "type": "object", "additionalProperties": { "$ref": "#/$defs/baseOption" } },
+        "optionsOrder": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "baseOption": {
+      "type": "object",
+      "properties": {
+        "label": { "type": "string" },
+        "hidden": { "type": "boolean" },
+        "description": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/docs/apply.md

@@ -0,0 +1,64 @@
+# Apply
+
+`kalup apply <plan-file> [--yes | --approve <writesHash>]` applies a plan saved by `kalup plan --out` to the target it names. `kalup apply [--target <name>] [--take config <selector>] [--yes]` plans an unprotected target now and applies that plan through the same checks. Apply writes property groups and properties, on custom objects too, and never a custom object schema.
+
+This page is the reference. For the walk-through with examples, see [kalup apply](https://kalup.dev/docs/commands/apply) on the website.
+
+## Approval
+
+A plan with any effect (a write, adoption, release, delete or state-only update) needs one approval:
+
+- **A person at a terminal**: stdin and stderr are terminals, no `--json`, `CI` unset. Apply prints the target, portal, account type, protection, each step in words from its data (never the plan's titles, with a differing portal name) and the counts, then asks for the target name and, for deletes and takeover option removals, the number of destructive steps. A wrong answer or the end of input is `E_CANCELLED`.
+- **`--yes`**: an unprotected target, no step Kalup derives as risky or destructive, at most the target's `yesLimit` (default 25; `0` turns `--yes` off) writes, adoptions and releases. It trusts the file once its digest matches, never past the risk or delete rules.
+- **`--approve <writesHash>`**: a reviewed CI job. The digest must equal the file's recomputed `writesHash` (`E_APPROVE_MISMATCH`), and the target must name its own `credentials.write`, read from the process environment, with no `.env` defining it (`E_APPROVE_CREDENTIAL`). It covers protected targets and risky steps, and shows only that the writes equal a reviewed digest, not that a review happened. A write key exported in a workstation shell satisfies it too, so keep that key only in CI. Agents never pass it.
+
+Every delete, and every option removal takeover asks for, needs the person at a terminal. Otherwise apply stops with `E_APPROVAL_REQUIRED`, exit 4, printing the command. A protected target accepts only a saved plan (`E_PROTECTED_SAVED_PLAN`).
+
+The terminal question stops an over-eager agent, not a hostile one: anything with a shell on the machine can read its keys.
+
+## What apply checks
+
+Before any write, in order:
+
+1. The file is `plan/1` from this release line (`E_PLAN_VERSION`, `E_PLAN_INVALID`), and `writesHash` and `planId` recomputed from it match (`E_PLAN_DIGEST`). A plan with nothing to apply exits 0 with no request.
+2. `kalup.config.ts`: the target is declared and pins the plan's portal (`E_PLAN_DESTINATION`). Later config edits change nothing it writes.
+3. The write key (`credentials.write`, else the read key) passes the portal guard. Every request, reads included, uses it.
+4. The policy equals the plan's: `protected`, `drift`, `adopt`, `allowDestroy`, `yesLimit` and the objects in takeover (`E_POLICY_CHANGED`); each step's API version is current and unexpired, and the normalizer versions match (`E_PLAN_VERSION`).
+5. Every step but a release is on an object `kalup.config.ts` declares, the name bindings match the target's name overrides, and no two steps but releases resolve to one portal resource (`E_BINDING_CHANGED`).
+6. Each delete has a `destroy` tombstone in `kalup/removed.ts` or takeover's leave (takeover mode, in the pull scope, not excluded), is gone from config, and no address in config names its portal resource, read as data (`E_PLAN_DELETE`). The object files also tell takeover's option removals from config's own.
+7. Approval, then the portal lock (`E_LOCKED`).
+8. State: a plan already applied with outcome `done` exits 0 ("Already applied"); otherwise lineage and serial equal the plan's (`E_STATE_CHANGED`).
+9. A fresh read of each object the plan changes, and of the schemas list for a custom object (`E_INCOMPLETE` on a 403, `E_BINDING_CHANGED` for another type ID). Every `expect` must hold (`E_PLAN_STALE`), a delete's covering each field its base holds. Kalup derives each step's risk, labels and blocked status again (`E_PLAN_RISK` when the plan states less); a takeover removal needs `allowDestroy`, and never takes a HubSpot-defined property.
+10. Three calls per write plus the reads use at most half of HubSpot's daily remainder (`E_BUDGET`).
+
+## Running the steps
+
+Apply records `lastApply.outcome: running`, then runs the steps one at a time: groups, properties, releases, then deletes, properties before groups. Each write reads the resource again and compares it with `expect`, builds the request from that read, sends it once, and reads it back for up to 60 seconds, saying so on stderr after a few seconds.
+
+- A property update sends the approved fields with the live `type` and `fieldType`; options go as the full live list with the approved changes, new ones last.
+- A 429, 423 or 477 is waited out three times, reading again before each resend. A daily 429 stops the run.
+- A timeout, network failure or 5xx is `uncertain` and never resent: HubSpot documents no idempotency keys. Only reading back the approved values settles it (`E_UNCERTAIN_WRITE`).
+- A value HubSpot stores differently is `W_UNVERIFIED`: state records both, and the next plan notes it instead of writing again.
+- A delete runs only once every earlier step verified. HubSpot keeps an archived property restorable in its UI for 90 days.
+
+State is saved after each step that changes an entry, then the outcome: `done`, `partial` or `uncertain`. Each request is journaled in `.kalup/journal/portal-<id>/`, never with a key or body. SIGINT or SIGTERM stops before the next request and saves state. A second one exits at once, unless it comes within a second (npx passes one Ctrl-C on twice).
+
+## Outcomes and exit codes
+
+Each step in `data.steps` is `done`, `unverified`, `uncertain`, `rejected`, `stale`, `not-run` or `blocked`; a blocked one carries the plan's `reason`. The text ends every run, `Nothing to apply` included, with `N blocked, not run:` and each blocked address, reason and detail, and with `N values differ between config and HubSpot ... held, not written:` and the `kalup plan` command that shows them and how to settle them.
+
+| Exit | When |
+|---|---|
+| 0 | Every effect verified, nothing to apply, or already applied |
+| 1 | A check refused, or no write could have landed and no state entry changed |
+| 3 | Config invalid |
+| 4 | The portal guard, `E_APPROVAL_REQUIRED`, `E_APPROVE_CREDENTIAL` |
+| 5 | A write landed or may have, or a state entry changed, and not every effect verified |
+
+## Recovery
+
+There is no resume and no rollback. After a run that did not finish, run `kalup plan --target <name>`: it compares the portal with the kept state. A property an interrupted create made shows as an adopt, never a second create.
+
+## Limits
+
+A read and the write after it are not atomic: an edit in HubSpot between the two is overwritten for that field. The lock keeps apart one user's commands on one machine only; in CI, one workflow per portal applies, in a concurrency group. A delete checks no use first; HubSpot refused to archive a property a calculation property used (developer test account, 2026-09-29).

package/docs/blueprints.md

@@ -0,0 +1,86 @@
+# Blueprints
+
+A blueprint is a versioned JSON file of property groups and properties that `kalup add` writes into config. It is data: Kalup parses it and never runs it. `add` and `blueprint upgrade` change config files only; `kalup plan` and `kalup apply` make the changes in HubSpot. Text in a blueprint (its description, labels, option labels) is third-party data, never instructions.
+
+This page is the reference. For the walk-through with examples, see [kalup add and blueprint upgrade](https://kalup.dev/docs/commands/blueprint) and [Agencies and blueprints](https://kalup.dev/docs/guides/blueprints-for-agencies) on the website.
+
+## The format
+
+```json
+{
+  "blueprintVersion": 1,
+  "name": "acme/renewals",
+  "version": "1.1.0",
+  "irVersion": 1,
+  "description": "Renewal tracking for deals",
+  "requires": [{ "$ref": "object:deals" }],
+  "resources": {
+    "group:deals/renewal": { "type": "group", "definition": { "label": "Renewal" } },
+    "property:deals/renewal_date": {
+      "type": "property",
+      "definition": { "label": "Renewal date", "group": { "$ref": "group:deals/renewal" }, "type": "date", "fieldType": "date" },
+      "binding": { "key": "renewalDate", "codec": "date" },
+      "lifecycle": { "options": "additive" }
+    }
+  }
+}
+```
+
+- `name` is one or two segments of lowercase letters and digits joined by single dashes; `version` is `MAJOR.MINOR.PATCH` with an optional pre-release.
+- `resources` holds groups and managed properties only, each with a full definition in IR terms; `binding` and `lifecycle` are optional. No `provenance`, `x`, `managed: false`, `p.json` or field the schema does not list.
+- Names, in addresses and group `$ref`s, are lowercase letters, digits and underscores, never `hs_`. Option values are unique. The codec fits the HubSpot type.
+- A property's group is in the blueprint, or config must already have it (`E_BLUEPRINT_REF`).
+
+Anything else is `E_BLUEPRINT_SCHEMA`. The schema ships in `kalup` as `kalup/schemas/blueprint-1.schema.json`.
+
+## add
+
+`kalup add <source> [--prefix <p>] [--dry-run] [--json]`. The source is a path relative to the current directory, or an `https://` URL: no key is sent, redirects are followed only to https, and the fetch stops after 30 seconds or 1 MB (`E_BLUEPRINT_SOURCE`). A URL with credentials or a query string is refused: the lock records it.
+
+1. The bytes are hashed (`sha256:`), parsed as JSON and checked. The prefix is applied (below).
+2. A new resource is added. One config already has with the same definition and binding is recorded under the blueprint, not rewritten. Any other difference is `E_BLUEPRINT_COLLISION`, listing the differing units; so is a `.managed(false)` entry, or an address another blueprint provides.
+3. Resources go into the export that holds their object, or a new `kalup/objects/<object>.ts` for a standard object. A custom object must already be in config (`E_BLUEPRINT_REQUIRES`). An object missing from `objects` in `kalup.config.ts` is added as `{}`.
+4. The lock entry goes to `kalup/blueprints.lock.json`, and the bytes, unchanged, to `kalup/.blueprints/<name with / as -->@<version>.json`. `.gitattributes` gets `kalup/.blueprints/** -text`, so git never changes their line endings.
+
+The project as add would leave it is validated first: any issue, such as a binding key another property uses, is exit 3. Files are copied to `.kalup/history/`, then written as one change (`E_PROJECT_WRITE` restores them on a failure).
+
+The output lists each resource (added, already in config, colliding), the objects added, each file, and the next step, `kalup plan`. The description is printed only at a terminal, labelled as the blueprint's own text. `--dry-run` writes nothing.
+
+## Prefix
+
+`--prefix acme_`, else `prefix` in `kalup.config.ts`, else none. It goes before every group and property name, in addresses and every `$ref`: `property:deals/renewal_date` becomes `property:deals/acme_renewal_date`. Labels, option values, binding keys and object keys stay, so the app code is the same in every project. HubSpot names are permanent, so a prefix is too. Upgrades reuse the recorded prefix.
+
+## blueprint upgrade
+
+`kalup blueprint upgrade <name> <source> [--take remote <address[#unit]>]... [--dry-run] [--exit-code] [--json]` merges three ways: the stored original is the base, config is local, the new version is remote.
+
+- Units: each definition field, each option (by value, then `label`, `hidden`, `description`), the options order, each lifecycle field, and the binding's `key`, `codec`, `aliases`, `required` and `readonly`.
+- Config unchanged since the base takes upstream's value. Upstream unchanged keeps config's. Both changed alike is fine. Both changed differently is a conflict: config keeps its value, the output shows both and the command that takes upstream's, and the lock records it under `held`. It stays held at later versions until taken or settled in config.
+- A resource new upstream is added; one config already has differently is a conflict per differing unit.
+- An option added upstream is added. One removed upstream that config still has stays, with its `as` alias and a note. An option or resource the client removed stays removed.
+- A resource removed upstream is detached: config keeps it, with no provenance.
+
+The same version and hash prints "Already at" and the conflicts config still holds, dropping settled ones from the lock; add `--take remote <address#unit>` to take upstream's side of one. A lower version warns `W_BLUEPRINT_DOWNGRADE`. The new original replaces the old one.
+
+A field a version owns for the first time, where the portal holds another value, is held by `plan` as `diverged` (plan.md); `plan --take config` writes it.
+
+## Provenance and the lock
+
+These two commands write `kalup/blueprints.lock.json`, never a person (`E_BLUEPRINT_LOCK`, exit 3). Per blueprint it records `version`, `source`, `hash`, `prefix`, `original`, `resources` (local address to blueprint address) and `held`. The loader adds `provenance` to each config resource the lock lists; `kalup ir` shows it. Commit the lock, `kalup/.blueprints/` and `.gitattributes` with the config.
+
+## Integrity
+
+The lock's `sources` keeps the hash of every source and version ever recorded. The same source and version with other bytes is `E_BLUEPRINT_INTEGRITY`: new content needs a new version number. A stored original that is missing or edited is `E_BLUEPRINT_ORIGINAL`; restore it from git.
+
+## What upgrade never does
+
+Write to a portal, delete or tombstone a resource, overwrite a value the client changed without `--take remote`, or touch overrides, state or another blueprint's resources.
+
+## Exit codes
+
+| Exit | When |
+|---|---|
+| 0 | Written, or nothing to do |
+| 1 | `E_USAGE`, `E_TAKE_UNMATCHED`, `E_PROJECT_WRITE` and every `E_BLUEPRINT_` code but `E_BLUEPRINT_LOCK` |
+| 2 | `upgrade --exit-code` when the lock holds conflicts |
+| 3 | Config invalid, before or after the change; `E_BLUEPRINT_LOCK` |

package/docs/compare.md

@@ -0,0 +1,73 @@
+# Compare
+
+`kalup compare <a> <b>` reports what would change in `b` to match `a`. It never writes, to the portal or to disk.
+
+This page is the reference. For the walk-through with examples, see [kalup compare](https://kalup.dev/docs/commands/compare) on the website.
+
+## Sides
+
+Each side is, in this order:
+
+1. `config`: the config files, as `kalup ir` derives them. Compared with a target, that target's `definition` overrides apply.
+2. A target declared in `kalup.config.ts`, read now. Each target has its own key, client and portal guard, and every guard runs before the first read: a key for another portal is exit 4.
+3. Otherwise a snapshot file, relative to the current directory. No such file is `E_SNAPSHOT`, exit 1.
+
+The project must load and validate only when a side is `config` or a target (exit 3 otherwise). Two snapshot files compare anywhere and send no request. A target is read as `pull` reads it: the same scope, three properties lists per object, `skip` and `name` overrides applied.
+
+## Direction
+
+`a` is desired, `b` observed. In `changes[]`, `before` is `b`'s value and `after` is `a`'s.
+
+- `compare config production`: what a plan for production would change, without planning.
+- `compare <snapshot> production`: drift since the snapshot. `before` is the portal now, `after` the snapshot.
+- `compare sandbox production`: two portals.
+
+## What is compared
+
+Every address present on either side, including properties Kalup does not write, and every config address. Each gets a status:
+
+- Equal: every unit converged. Counted, not listed.
+- `differs`: `changes[]` lists options to add or remove; `held[]` lists units that differ, `diverged` since there is no base; `notes[]` lists options only `b` holds, kept because options are additive. When `b` is a portal side, the note names the pull command that brings the option into config. `pull` does not write a resource that names a portal name a `name` override shadows (`shadowed:<name>`), so on such a resource the note says to correct or remove that override instead. Nor does it write a property outside its object's pull scope, so there the note says to add the name to `objects.<object>.include`. A snapshot does not record whether HubSpot defines a property, so on a reference `include` does not name, a snapshot's note says it may be outside the scope and gives the same advice.
+- `only-a` or `only-b`: on one side only.
+- `unmanaged`: only a portal side holds it and the other side is config. Listed and counted, never a difference: absence never deletes.
+- `unknown`: a side could not read its object, never read it, left out a property config names because its group's name holds whitespace (`W_UNADDRESSABLE_NAME`), or a target side has a `lookup` override, since this version manages no lookup resources. `reason` says which side and why.
+- `excluded`: a `skip` override, or outside a side's read scope. Listed, not a difference.
+
+Config owns the fields it states, less `ignoreChanges`; a reference owns nothing, so only its presence compares. A portal side owns every field it captured; a field HubSpot left out takes its default, or `null` when it has none. With config as `b`, only the fields config states are compared. Options are compared when the config side states them, and always between two portal sides. Config managing what the portal holds as HubSpot-defined or calculated differs in the unit `managed`.
+
+## Complete
+
+A comparison is complete when no address is unknown and every object either side names was read on both sides (read, absent from the portal, or skipped). Otherwise the exit is 1 with `E_INCOMPLETE`, naming what was not compared and what to do: add scopes or an object key under `objects`, or rename in HubSpot a portal group whose name holds whitespace, with or without `--exit-code`. `data` is still printed, with `ok: false`. An incomplete comparison is never a clean result.
+
+## Flags
+
+- `--exit-code`: exit 2 when anything `differs` or is `only-a` or `only-b`. An option only `b` holds counts. Unmanaged and excluded addresses do not.
+- `--json`: one `envelope/1`. `data` holds `a` and `b` (kind, name, portal ID, file, `observedAt`), `complete`, `counts` and `differences[]` with `address`, `status`, `changes`, `held`, `notes` and `reason`.
+
+Structured values keep portal strings exact. The text output is sanitized.
+
+## Output
+
+The example project after config added an option and a property, and the portal renamed a label and added an option:
+
+```
+a: config
+b: target sandbox, portal 1111111
+12 equal, 1 differs, 1 only in a, 0 only in b, 1 unmanaged, 0 unknown, 0 skipped
+unmanaged: group:companies/companyinformation
+differs: property:companies/billing_status
+  add options[trial]: null -> {"value":"trial","label":"Trial"}
+  label differs: a "Billing status", b "Billing state"
+  kept options[paused]: {"value":"paused","label":"Paused","hidden":false,"description":""}
+only in a: property:companies/churn_reason
+```
+
+## Exit codes
+
+| Exit | When |
+|---|---|
+| 0 | Complete, differences included without `--exit-code` |
+| 1 | `E_INCOMPLETE`, `E_USAGE`, `E_NO_CONFIG`, `E_SNAPSHOT` (a missing file, not JSON), `E_MISSING_KEY`, `E_OVERRIDE_AMBIGUOUS`, a failed request |
+| 2 | `--exit-code` and a difference, with `ok: true` |
+| 3 | Config invalid, `E_UNKNOWN_OBJECT`, or a file that is not a valid snapshot |
+| 4 | `E_TARGET_PORTAL_MISMATCH` |

package/docs/config.md

@@ -0,0 +1,88 @@
+# Config files
+
+Kalup reads `kalup.config.ts` and every `.ts` file under `kalup/` except `kalup/index.ts` as data. It parses a small grammar and never runs them. The app imports the same files and runs them for types and codecs.
+
+This page is the reference. For the walk-through with examples, see [Config files](https://kalup.dev/docs/config/config-files), [kalup.config.ts](https://kalup.dev/docs/config/kalup-config) and [Property builders](https://kalup.dev/docs/config/property-builders) on the website.
+
+## Files
+
+- `kalup.config.ts`: one `export default defineConfig({...})` and nothing after it. Fields: `name` (default: the directory name), `prefix`, `defaultTarget` (targets.md), `mode` (below), `objects` (the pull scope, pull.md) and `targets` (targets.md). A setting at a level that does not take it is `E_SETTING_LEVEL`, whose fix lists the levels that do; a value it does not take is `E_SETTING_VALUE`, with the nearest allowed one.
+- `kalup/objects/<object>.ts`: one or more `export const <Name> = defineObject('<object>', {...})` or `defineCustomObject('<name>', {...})`. The writer adds an `export type <Name>Data = ...` line after each. A file with no such export is `E_MISSING_EXPORT`.
+- `kalup/index.ts`: the barrel, written by `pull` and `fmt`. It imports each object file as `./objects/<object>.js`, which resolves under TypeScript `NodeNext`, `Node16` and `Bundler` resolution, bundlers such as Vite and Next.js, and plain Node running `tsc` output. Under `NodeNext`, import it as `./kalup/index.js`.
+- `kalup/removed.ts`: tombstones, below.
+- `kalup/pipelines/*`, and a `defineConfig` or `defineRemoved` file elsewhere under `kalup/`, are `E_UNSUPPORTED_FILE`.
+
+## The grammar
+
+Anything else is `E_NOT_DATA`.
+
+- `import` lines. Imports from `@kalup/core` and `kalup` are rewritten; others are kept, for `p.json` validators.
+- Object literals of `key: value` entries, arrays, strings in single or double quotes on one line, numbers, `true` and `false`. No template strings, identifiers as values, spreads, computed keys, shorthand, or calls other than the builders.
+- A `//` comment on its own line above an export, a group entry or a property entry, and a comment block above the imports (the file header). Every other comment is an error, including any in `kalup.config.ts` but the header.
+- `p.<kind>('<internal name>')` or `p.<kind>('<internal name>', {...})`, then any of `.strict()` (`p.enum` and `p.multiEnum` only), `.required()`, `.readonly()` and `.managed(false)`, each once. Any other chain call is `E_BAD_CHAIN`. A kind not listed below is `E_UNKNOWN_BUILDER`.
+- `p.json('<name>', <validator>, {...})`. The validator is opaque text and may not hold a `//` comment.
+- A custom object needs `labels: { singular, plural }` and `primaryDisplayProperty`, and may set `requiredProperties`, `searchableProperties` and `secondaryDisplayProperties`.
+
+`E_DUPLICATE_KEY`: a key twice in one literal, an export name twice in one file, or one internal name under two keys. `E_DUPLICATE_ADDRESS`: one address from two files or two exports.
+
+## Builders
+
+Each builder sets the HubSpot `type`, which config never states, and allows these `fieldType` values. Any other is `E_TYPE_FIELDTYPE`.
+
+- `p.string`, `p.stringArray`, `p.json`: `string`; text, textarea, file, phonenumber.
+- `p.number`: `number`; number.
+- `p.boolean`: `bool`; booleancheckbox.
+- `p.date` (`YYYY-MM-DD`) and `p.datetime` (ISO 8601): `date` and `datetime`; date.
+- `p.enum`: `enumeration`; select, radio, booleancheckbox.
+- `p.multiEnum`: `enumeration`; checkbox.
+
+In the app every value can be `null`, and a blank one reads as `null`. `p.enum` gives one alias, `p.multiEnum` an alias array (`;`-separated on the wire); a stored value the options do not list reads as `Unlisted`, a branded string `set` writes back unchanged. `.strict()` makes both throw on it instead and drops `Unlisted` from the type; it needs options (`E_STRICT_WITHOUT_OPTIONS`). A bare `p.enum` reference is `Unlisted | null`. `p.stringArray` a `string[]` (split on `,` or `;`, written `,`-joined), `p.json` the validator's output. `.required()` drops `null` and makes `get` throw on a missing value. `.readonly()` removes `set` from the type. `pull` never writes `.required()`, `p.stringArray` or `p.json`, and keeps them.
+
+## Managed, reference, options-only
+
+A definition with `label`, `group` and `fieldType` is managed: the fields present are owned, and an omitted `description`, `options`, `hasUniqueValue` or `formField` belongs to the portal. `group` must name a group declared under `groups` for the same object, in any export or file (`E_UNKNOWN_GROUP`). A managed internal name starting with `hs_` is `E_HS_PREFIX`.
+
+No definition makes a reference: never created, changed or removed. `p.enum` or `p.multiEnum` with `options` and nothing else is a reference with typed options, which pull refreshes.
+
+A definition missing one of the three fields, options-only on another builder, or `.managed(false)` on a reference is `E_REFERENCE_DEFINITION`.
+
+`.managed(false)` keeps a full definition for typing while nothing owns it.
+
+## Options and aliases
+
+`options: [{ value, label, as?, hidden?, description? }]`. Array order is display order. `as` is the app-side name: the TypeScript type is the union of `as ?? value`, `get` returns the alias and `set` takes it. `as` never goes to HubSpot. Values and aliases must each be unique (`E_DUPLICATE_OPTION`, `E_DUPLICATE_ALIAS`).
+
+## Keys
+
+The object key is the app's name for the property. Two exports of one object using the same key is `E_KEY_COLLISION`. Rename keys freely; HubSpot only knows the internal name.
+
+## Lifecycle
+
+`lifecycle: { options: 'additive' | 'exact', removedOptions: [...], ignoreChanges: [...], preventDestroy: true }` inside a full definition. `options` defaults to `additive`, and to `exact` under takeover, unless the property or the target's override states it. `removedOptions` may not name a value still in `options`, and `ignoreChanges` may name only definition fields (`E_LIFECYCLE`). `plan` and `compare` apply the others (plan.md); `preventDestroy` blocks a `rm` destroy.
+
+## Per-target definitions
+
+A target's override `definition` (targets.md) replaces each field it states there, whole, and owns it, empty values included: a property's `label`, `description`, `group`, `fieldType`, `formField`, `options` (no `as`) and lifecycle but `preventDestroy`; a group's `label`. Else `E_OVERRIDE_DEFINITION`. `pull` writes these fields into the override.
+
+## Mode: addon and takeover
+
+`mode: 'addon' | 'takeover'` at the top level, under `objects.<object>`, under `targets.<target>`, or under `targets.<target>.objects.<object>`. The most specific wins, in that order from the last, and the default is `addon`: Kalup manages only what config names. A target `mode` that differs from an object's `mode` the target says nothing more about is `W_MODE_SHADOWED`.
+
+Under `takeover`, `plan` archives every custom property and group in the object's pull scope that config lacks and `kalup/removed.ts` does not name (a group only once every property in it goes, and after them), and removes enum options only the portal holds. Never a HubSpot-defined or calculated property, a kind Kalup does not write, anything an object file lists, a name `exclude` covers, or a property a custom object schema names. Every takeover removal is destructive: it needs `allowDestroy: true` on the target and a person at a terminal, and `--yes` and `--approve` never cover it. Without `allowDestroy` it is blocked, reason `policy`; after an incomplete read, reason `scope`.
+
+## Removed resources
+
+`kalup/removed.ts` holds `export default defineRemoved({...})`, keyed by address:
+
+```ts
+export default defineRemoved({
+  'property:companies/legacy_score': { action: 'destroy', reason: 'Replaced by lead_score' },
+  'group:companies/old_billing': { action: 'release' },
+})
+```
+
+`destroy` deletes the resource, only on a target with `allowDestroy: true` (default false). `release` stops managing it, leaving it there. Keys are property or group addresses (`E_TOMBSTONE_ADDRESS`) that config no longer defines (`E_TOMBSTONE_CONFLICT`).
+
+## Canonical form
+
+`kalup fmt` validates, then rewrites `kalup.config.ts`, `kalup/removed.ts`, every object file and the barrel: groups and properties sorted by internal name, tombstones by address, fields in a fixed order, options in display order, quotes as biome writes them, 120 columns. It keeps every value you wrote, `description: ''`, `options: []`, `false` and an empty `lifecycle` included: a present field is owned. `fmt --check` lists the files it would change; `--exit-code` exits 2 then. Old files go to `.kalup/history/<timestamp>/` first; the last 20 runs are kept.

package/docs/dictionary.md

@@ -0,0 +1,43 @@
+# Data dictionary
+
+`kalup docs [<source>]` prints a Markdown data dictionary. The source is `config`, the default, or a snapshot file relative to the current directory. It sends no request.
+
+This page is the reference. For the walk-through with examples, see [kalup docs](https://kalup.dev/docs/commands/docs) on the website.
+
+- `config`: the project must validate (exit 3). The page describes the config files: a field a definition leaves out belongs to the portal and is not listed.
+- A snapshot file needs no project. The page describes the read, with HubSpot's defaults filled in, such as `Hidden: no`.
+
+## Layout
+
+1. `# <project> data dictionary` and a line naming the source: the config files, or the target, portal ID and `observedAt` of the snapshot.
+2. `## Coverage`. For a snapshot: whether the read was complete, the objects not read with the missing scope, objects absent from the portal, what `skip` overrides left out, unsupported properties (Kalup does not write them), schemas without a label, `name` overrides, config properties in a group no address can hold, counts out of scope and shadowed, custom objects config does not name, and the fields Kalup does not capture. Reference properties record only their options.
+3. One `## <object>` section per object key, sorted: a custom object's labels, display property and property lists; a groups table (internal name, label); a properties table (internal name, label, type, field type, group, managed or reference, description); and one options table per enumeration (value, label, hidden, description), in display order. Config adds the key, codec, required and alias columns. Unsupported properties appear only under Coverage.
+4. Config with `definition` overrides: `## Per-target overrides`, one row per address, field and target with its value, sorted.
+
+## Escaping
+
+Every string from a file or a portal is shown as text: newlines become spaces, control and bidirectional formatting characters are removed, every ASCII punctuation character is backslash-escaped, and an invisible word joiner (U+2060) breaks a bare URL, `www.` name or email address, which GFM renderers such as remark-gfm link even when escaped. So no label can form a link, HTML, emphasis, code, a heading or a table cell. Descriptions are cut at 500 characters with an ellipsis.
+
+## Deterministic
+
+The same source gives the same bytes: objects, groups and properties sorted, options in display order, and no timestamp but a snapshot's own `observedAt`. Commit the dictionary and check it in CI:
+
+```sh
+npx --no-install kalup docs --out DATA-DICTIONARY.md
+git diff --exit-code DATA-DICTIONARY.md
+```
+
+## Flags
+
+- `--out <file>`: write the Markdown there, relative to the current directory, replacing an older file, and print `Wrote <file>`.
+- `--json`: one `envelope/1` with `data: { markdown }`, or `data: { file }` with `--out`.
+
+An incomplete snapshot gives `W_INCOMPLETE`: what was not read is unknown, and the Coverage section lists it.
+
+## Exit codes
+
+| Exit | When |
+|---|---|
+| 0 | Written, warnings included |
+| 1 | `E_USAGE`, `E_NO_CONFIG`, `E_SNAPSHOT` (a missing file, not JSON) |
+| 3 | Config invalid, or a file that is not a valid snapshot |

package/docs/errors/E_ACCEPT_UNMATCHED.md

@@ -0,0 +1,17 @@
+# E_ACCEPT_UNMATCHED
+
+A `pull --accept` selector matches nothing pull keeps. Exit 1. Nothing was written.
+
+## When
+
+Where state owns a resource, pull keeps the file's value for a unit config changed, for a conflict, for an option config added, and for an option HubSpot removed that config still holds. `--accept <address[#unit]>` takes the portal's side of those units. A selector that matches none of them (a unit that agrees, one pull takes from the portal anyway, a typo) is refused. The message lists what pull keeps there. The run's warnings follow it, so an unread list (`E_SCOPE`, `E_INCOMPLETE`) that explains an empty match is shown too.
+
+## Fix
+
+Run `kalup pull --target <name> --check`, pick a unit it lists as a config change kept, a conflict or removed in HubSpot, and pass that. A selector without `#unit` takes every such unit on the address, and `*` in the address works as in `--only`.
+
+## Example
+
+```
+E_ACCEPT_UNMATCHED: --accept property:companies/soil_ph#description matches no config change, conflict or option removed in HubSpot; pull keeps: property:companies/soil_ph#label (conflict, config kept). Nothing was written. (fix: accept a unit that kalup pull --target sandbox --check lists as kept, a conflict or removed in HubSpot, or leave the selector out) (docs: errors/E_ACCEPT_UNMATCHED.md)
+```

package/docs/errors/E_APPROVAL_REQUIRED.md

@@ -0,0 +1,17 @@
+# E_APPROVAL_REQUIRED
+
+Nothing approved this plan. Exit 4, `humanRequired: true`. Nothing was written.
+
+## When
+
+A plan with any effect needs one approval. A person at a terminal (stdin and stderr are terminals, no `--json`, `CI` unset) confirms it by typing the target name. `--yes` covers only an unprotected target, with no risky or destructive step, and at most as many writes, adoptions and releases as `yesLimit` on the target allows (25 by default; `yesLimit: 0` turns `--yes` off). Every delete, and every option removal takeover asks for, on every host, needs a person at a terminal who also types the number of destructive steps. Otherwise apply stops here, and the message says which condition failed. `kalup state rebuild --write` and `kalup target rebind` run only for a person at a terminal, and stop here otherwise.
+
+## Fix
+
+Stop. Hand the command in the fix to the user, who runs it in a terminal and confirms it there. Agents never approve on the user's behalf.
+
+## Example
+
+```
+E_APPROVAL_REQUIRED: --yes does not cover this plan: s1 (risky) is not safe. (fix: ask the user to run kalup apply plan.json in a terminal, where they confirm it) (docs: errors/E_APPROVAL_REQUIRED.md)
+```

package/docs/errors/E_APPROVE_CREDENTIAL.md

@@ -0,0 +1,17 @@
+# E_APPROVE_CREDENTIAL
+
+`--approve` was refused because the write key is not held apart. Exit 4, `humanRequired: true`. Nothing was sent.
+
+## When
+
+`--approve <writesHash>` lets a reviewed CI job apply a plan. It rests on custody: only that CI environment holds the write key. So the target must name its own `credentials.write`, and the key is read from the process environment only. Kalup refuses when the target has no `credentials.write`, or one that names the read credential's variable, or when `.env` in the project directory defines that variable at all, whatever its value, because the key is then on this machine. The message never includes a value.
+
+## Fix
+
+Stop. A person decides. Give the target `credentials.write` with a variable only the reviewed CI environment holds. Keep it out of `.env` and every workstation shell: exported there, it satisfies `--approve` too. Or a person applies the plan at a terminal. Agents: hand this to the user.
+
+## Example
+
+```
+E_APPROVE_CREDENTIAL: --approve needs a write key that only the reviewed CI environment holds, and .env in the project directory defines HUBSPOT_PROD_WRITE_KEY. (fix: Remove HUBSPOT_PROD_WRITE_KEY from .env, or have a person apply the plan at a terminal.) (docs: errors/E_APPROVE_CREDENTIAL.md)
+```

package/docs/errors/E_APPROVE_MISMATCH.md

@@ -0,0 +1,17 @@
+# E_APPROVE_MISMATCH
+
+The digest given to `--approve` is not this plan's. Exit 1. Nothing was written.
+
+## When
+
+`--approve <writesHash>` is for a reviewed CI job: the digest of the plan a reviewer saw. `kalup apply` recomputes the digest of the plan file it was given and refuses when the two differ. The plan changed after the review, or the digest belongs to another plan.
+
+## Fix
+
+Review the plan file again, and approve the digest of the plan that will run. A person can also apply it with `kalup apply <plan-file>` in a terminal.
+
+## Example
+
+```
+E_APPROVE_MISMATCH: The digest given to --approve is not the writesHash of this plan: the plan changed after the review, or the digest belongs to another plan. Nothing was written. (fix: review this plan again; a person can apply it with kalup apply plan.json in a terminal) (docs: errors/E_APPROVE_MISMATCH.md)
+```

package/docs/errors/E_AUTH.md

@@ -0,0 +1,17 @@
+# E_AUTH
+
+HubSpot rejected the read key with a 401. Exit 1.
+
+## When
+
+A request from a command that reads a portal came back 401: the key is wrong, revoked or expired. `status` reports it for that target and checks the others.
+
+## Fix
+
+Check the key in the variable the target reads (`credentials.read.env`, or `HUBSPOT_SERVICE_KEY` when there is none). If it was revoked, a person creates a new one in HubSpot. When the request needed a scope, the fix names it.
+
+## 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)
+```

package/docs/errors/E_BAD_CHAIN.md

@@ -0,0 +1,21 @@
+# E_BAD_CHAIN
+
+A builder call is followed by a chain call Kalup does not accept. Exit 3.
+
+## When
+
+After `p.<kind>(...)` only `.strict()`, `.required()`, `.readonly()` and `.managed(false)` are allowed, each once, and `.strict()` only after `p.enum` or `p.multiEnum`. `.optional()`, `.managed(true)`, `.required` without parentheses, `.required()` twice or `.strict()` on `p.string` are errors.
+
+## Fix
+
+Use one of the four calls, once each. A property is nullable unless it has `.required()`, so there is no `.optional()`. Drop `.strict()` from a builder other than `p.enum` and `p.multiEnum`.
+
+## Example
+
+```ts
+plotCount: p.number('plot_count').optional(),
+```
+
+```
+kalup/objects/companies.ts:5: E_BAD_CHAIN: .optional() is not a chain call (fix: use .strict(), .required(), .readonly() or .managed(false)) (docs: errors/E_BAD_CHAIN.md)
+```

package/docs/errors/E_BINDING_CHANGED.md

@@ -0,0 +1,17 @@
+# E_BINDING_CHANGED
+
+A plan binds an address to a portal resource that kalup.config.ts or the portal does not give it now. Exit 1. Nothing was written.
+
+## When
+
+A plan's `bindings` say which portal resource each address stands for: a target's name override, or a custom object's type ID. `kalup apply` never trusts the file. Before approval, every step but a release must be on an object `kalup.config.ts` declares under `objects`, each name binding must be the one the target's overrides give, and no two steps but releases may resolve to one portal resource. Under the lock, each custom object's type ID must be the one the schemas list gives now: a custom object made again has a new one.
+
+## Fix
+
+Run `kalup plan --target <name> --out <file>` again, review it, and apply that file. Never edit a plan file by hand.
+
+## Example
+
+```
+E_BINDING_CHANGED: plan pl_7f3a1c07b2e4 does not name what kalup.config.ts names on target sandbox: the plan binds property:companies/soil_ph to portal name plot_notes, and the name override in kalup.config.ts gives none. 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_BINDING_CHANGED.md)
+```

package/docs/errors/E_BIOME_CONFIG.md

@@ -0,0 +1,17 @@
+# E_BIOME_CONFIG
+
+`init` found a `biome.json` that is not valid JSON. Exit 1. Nothing was written.
+
+## When
+
+`init` adds `!kalup`, `!kalup.config.ts` and `!.kalup` to `files.includes` in `biome.json`, so it reads that file before it writes anything. Biome reads `biome.json` as plain JSON, so a comment in it is also this error. A `biome.jsonc` that does not parse is not an error: `init` leaves it alone and prints a note.
+
+## Fix
+
+Fix the JSON in `biome.json` (a trailing comma or a comment is the usual cause), then run `npx --no-install kalup init --portal <id>` again.
+
+## Example
+
+```
+biome.json: E_BIOME_CONFIG: biome.json is not valid JSON: <parser message> (fix: fix the file, then run npx kalup init again) (docs: errors/E_BIOME_CONFIG.md)
+```